SciML / DataDrivenDiffEq.jl

Data driven modeling and automated discovery of dynamical systems for the SciML Scientific Machine Learning organization
https://docs.sciml.ai/DataDrivenDiffEq/stable/
MIT License
405 stars 57 forks source link

Docs Reorganization #280

Closed Gregliest closed 3 years ago

Gregliest commented 3 years ago

This PR reorganizes the docs as suggested in #247. I've taken a lot of liberties in reorganizing, with the rough outline as follows:

To me, this outline made the most sense because the general workflow is:

  1. Define a problem
  2. Choose a basis (optional)
  3. Solve

However, let me know if you'd like something different.

This PR still has some outstanding issues and questions:

  1. The "Basic Usage" example in "Getting Started" does not work. I think I need some help understanding why. I'd like the minimal example here for clarity. [Needs a code change]
  2. I was confused by the basis generators. I'd expect something named monomial_basis to return a basis, not a vector of equations. I'll call that out in the docs, but it might be clearer to name them something like monomial_basis_eqs or something like that. [Addressed below]
  3. It looks like the OccamNet stuff is in an "optional" function in the module builder, and isn't getting called when I build docs. I assume that gets built properly in CI? [Addressed]
  4. Along the same line, none of the examples run locally due to an environment issue, which means that none of the png's are getting generated. [Addressed]
AlCap23 commented 3 years ago

Hey Greg!

Very nice work so far! Thank you!

I added some minor discussion points / proposals for changes and reminder for myself :sweat_smile: .

For your list above:

  1. As stated above, this is my fault. Right now, Sparse Regression is only tuned to continuous dynamical systems, but not for discrete or direct. Should be fixable.
  2. Good point. Maybe we should point this out in the docs. The reason for this is due to the general common term basis for e.g. a Fourier basis vs. Our Basis, which is the more carved out representation for use withinin our algorithms. Hence the confusion. I tend to generalize a little to much, hence I wanted to return a Vector of Equations rather than a basis to be able to add my own stuff on top.
  3. Yes. I normally activate the docs environment and use LiveServer.jl for the preview.
  4. As above.

I am fully back and just adjusting to be fully back right now, so feel free to DM on Slack or keep this conversation going.

AlCap23 commented 3 years ago

Ah, and I compiled an initial list of references here.

Once you feel that this PR is mature enough, I can jump in and add it and DocumenterCitations.jl .

Gregliest commented 3 years ago

Ok, I think this PR is in a decent place. I'd still like to check it using your LiveServer.jl workflow, so I can make sure the png's and optional module elements are working properly. But, I think most things are in and working, and stuff is reasonably proofread at this point.