Global documentation for the Julia SciML Scientific Machine Learning Organization
Home Page: https://docs.sciml.ai
License: MIT License
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
The logo on the top left at https://docs.sciml.ai/Overview/dev/ goes to https://docs.sciml.ai/https:/sciml.ai, which is a broken link.
Forking off this discussion from #108, I wrote up some thoughts on implementing the top navbar into Documenter: JuliaDocs/Documenter.jl#2177
What I would love, though, is to more precisely understand how we would like to use it for SciML. Do we have a rough sketch of what the navigation would look like for the SciML manual in the ideal world? E.g. what would we see if we would be on, say, these pages?
Now that we have SciMLDocs, some of the pages of DiffEqDocs are no longer relevant.
Replace the above with a single overview page mentioning them all?
Analysis Tools
When stepping through the example code for GPU-Accelerated Physics-Informed Neural Network (PINN) PDE Solvers
at step 5, the line:
prob = discretize(pde_system, discretization)
threw an error
ERROR: MethodError: no method matching CuArray{Float64, 1, CUDA.Mem.DeviceBuffer}(::Matrix{Float64})
We have
https://github.com/SciML/SciMLDocs/blob/main/docs/src/index.md
and
https://github.com/SciML/SciMLDocs/blob/main/docs/src/overview.md
The link https://docs.sciml.ai/Overview/dev/
currently goes to index.md?
Will SciMLTutorials get integrated in this repo ?
@pfitzseb is there any explanation for this one? Seems like a an odd thing that is happening on its own.
https://docs.sciml.ai/DiffEqDevDocs/stable/
linked from the header under “developer documentation”
Since JumpProblem and such is not in SciMLBase or documented there.
As we update the documentation links across SciML packages, most packages only have old links in the README and make.jl files. However, some older packages have a lot of links to the old documentation link format in their source files. This issue notes the relevant packages so that we can resolve them later.
When opening in a private browser window on firefox, PolyChaos has white theme, while most others have dark theme.
No idea why, maybe related to https://github.com/SciML/PolyChaos.jl/blob/master/docs/src/assets/myfont.css
The following require it for either size or GPU requirements:
Most don't exist with buildkite scripts yet, but those that do are having deployment issues.
Also, the buildkite scripts are not deploying on tags, so things like https://docs.sciml.ai/SciMLSensitivity/dev/ are missing a lot of tags.
I think all off the preview urls redirect to docs.sciml.ai?
But those are only updated once a day and thus might not have the preview.
We should probably also enable previews everywhere and a CI script to remove old previews to save on space/time?
In the tutorial "Solve your first optimization problem" at https://docs.sciml.ai/Overview/stable/getting_started/first_optimization/ we use a gradient-based method but do not supply the gradient. Thus instead of a solution [NaN, NaN] is returned, see https://docs.sciml.ai/Overview/stable/getting_started/first_optimization/#Step-3:-Solve-the-Optimization-Problem. The correct solution is of course [1, 1].
We can either switch to a gradient-free method or we can use Optimization.AutoForwardDiff() as suggested in the example at https://docs.sciml.ai/Optimization/stable/getting_started/#Controlling-Gradient-Calculations-(Automatic-Differentiation)
The following are the major steps to complete the SciML documentation overhaul:
We have a ton of information in our doc builds. It's where all of our tutorials are! So the biggest stress test is actually the documentation builds. The system of downstream testing by @giordano has been a massive success for our testing, so we would like to get something similarly setup for downstream testing of the documentation. One way I had in mind for doing this was:
runtests.jl for GROUP=="DownstreamDocs"include("make.jl)if GROUP!="DownstreamDocs" around the deploymentDownstreamDocs to the Downstream.yml files that need the respective doc tests.That seems innocent enough, and would work for a lot of cases. Though there are a few cases, like SciMLSensitivity.jl, SciMLDocs.jl, and DiffEqGPU.jl, which require GPUs as part of the documentation build and thus are run on the Buildkite instead of Github Actions. Some of them are just really long builds too (SciMLSensitivity We would like to put the high level SciMLDocs (with its new showcase!) onto many packages (since those are the first tutorials everyone will see), so if that requires GPU, then the system really needs to be able to use GPUs, at least for some of the tests.
For that, I might need the help of @thazhemadam @staticfloat to maybe get some thing I can paste into some Buildkite scripts?
(Note: since it won't need deployment it won't need the help with the cryptographic signatures stuff, thank god)
Now that this is starting to deploy, we need to update everything to be pointing here. For every package, we need:
@ArnoStrouwen can you help with this?
https://github.com/lorenzoh/Pollen.jl
@lorenzoh had an early version that looked pretty interesting.
Currently it has a warning on it. That's the last piece of the showcase so going ahead with a deployment @AlCap23
This button should redirect to the readme.
For e.g. MuladdMacro this does seem to work.
I noticed, that some documentation of third arty tools like
https://docs.sciml.ai/ManifoldDiffEq/stable/ (thanks for seeing these already btw)
or
https://docs.sciml.ai/FFTW/stable/
are rendered (again) in this repo while they have their own docs ( https://juliamanifolds.github.io/ManifoldDiffEq.jl/stable/ or https://juliamath.github.io/FFTW.jl/stable/) while other menu entries for third party tools like Flux link to external docs.
Is there a rule when docs are “re-rendered” here and when they are linked? I feel linking should be the default if the standalone docs outside SciML exist?
is this known?
At https://docs.sciml.ai/Overview/stable/getting_started/fit_simulation/#Step-4:-Solve-the-Optimization-Problem the tutorial says: "This step will look very similar to the first optimization tutorial, except now we have a new cost function. Just like in that tutorial, we want to define a callback to monitor the solution process." However there is no discussion of callback functions in the first optimization tutorial. Presumably such a discussion was planned to be included but then wasn't because the example chosen in that first tutorial was too simple to make a callback function useful.
hello - this might seem like a trivial request, but it'd make navigating a lot easier:
when I click on a section in the scrollable Table of Contents, when the section comes up, the Table of Contents jumps back to the top and I have to scroll down to click on another section - it'd be great if the Table of Contents maintained its place even after the new section comes up
hope that makes sense - thank you!
Here's a big page where we can voice high level desires over the direction and design of the overall SciML documentation and the "template" we are using for each of the solver packages.
Starting by copying the ModelingToolkit summary of some docs discussions:
This comes after some hefty discussions with users, customers, etc. along with surveys, analytics, and all of that. We'll be rolling out a slightly perturbed style throughout all of the packages, starting with the biggies, being ModelingToolkit and DifferentialEquations.
This comes from some discussions with folks who found the documentation of the following styles to be quite good:
One noticeable aspect is the separation of tutorials from examples. While these all do something slightly different of course, the general mantra is that tutorials are more beginner explanations of core functionality while examples are just "cool shit" you want to show, which maybe has less text. The latter is mostly useful for showing people what you can do, or giving people starter code. The former is more about a human-level explanation. We had been traditionally mixing the two, but it's good to split them so they can serve their respective functions better.
Additionally, for each package we are designating one tutorial to be on top as the "Getting Started" tutorial. The SciML docs as a whole have a "Getting Started" section which we use as a landing page that orients people to the whole ecosystem (https://docs.sciml.ai/Overview/stable/). It's in-depth, multipage, etc. and similar in style to the Pandas or SciPy ones. This then leaves room for the "Getting Started" section of a package to simply be about the package itself. It should have a section at the end that contextualizes, like is seen right now in DifferentialEquations.jl (https://docs.sciml.ai/DiffEqDocs/v7.6/tutorials/ode_example/#Additional-Features-and-Analysis-Tools), but its real focus is "99% of people who use this package should know at least these things". Our Google Analytics shows that >90% of all users read the first tutorial (and about 20% only read the first tutorial in DifferentialEquations, but seem to keep coming back to it!). Thus we basically want a page that will serve as something we "know" or can assume every reader has read. This is why it's then elevated from being the first tutorial to being a separate highlighted "Getting Started" page (which should then also include installation instructions and links to other tutorials / videos).
For ModelingToolkit and DifferentialEquations, and many of our other packages, the first tutorial has already been written as a "Getting Started" type of tutorial, while the other tutorials then dig into specific features. So this PR, like the ones that will happen to other package, elevates the first tutorial to this "Getting Started" status.
That is not to say everything is completed. The matplotlib and MATLAB documentation examples show that associating a plot with each example and putting them in a tiled view is really nice and accessible. We cannot do that with Documenter.jl, so for now we will at least get the examples curated while we beg for some new way to distinguish them from the rest of the documentation. Additionally, I have taken the following notes for documentation improvements, which I'll put here but not actually do yet in this restructuring PR:
This is the start of the SciML showcase which was mentioned in #73 (comment) . Thus this PR supersedes #73
What is the SciML Showcase? It's a place for cool demonstrations. Tutorials have to be simple and teaching focused, so it's hard for them to really dive into the fun stuff. But the "why SciML?" is the fun stuff, so that needs to be there front and center somehow. Enter the showcase.
By being separated from the "getting started" section, it's very clear (and has a note) that this is not for getting started. It's saying, hey, you might not understand this code at first glance, but this is to show you all of the cool stuff you'll learn around here! And that's it's main purpose: to show off some cool stuff.
Thus to kick off the showcase, I wanted to revive some of the core examples from the UDE paper and the Bayesian UDE paper, given how those examples seem to be some of the biggest awe drivers to the ecosystem.
That said, the showcase also serves another purpose of making sure that our best examples stay reproducible! Thus the showcase is made for the examples to be run with @example in strict mode, meaning that errors cause failures in the documentation build. I intend for this to be added as a downstream test to all of the major SciML packages that are showcased in the showcase, as this will ensure that any breakage to our top examples are remedied ASAP. This will make our "core" examples much more robust, making it easier for people to share them.
Related:
Can not get the drop-down menu on e.g.
https://docs.sciml.ai/Lux/stable/
Hi everyone. I am trying to implement the Deep Bayesian Model Discovery on the Lotka-Volterra model discussed in the Automated Discovery of Missing Physics example. The problem I am facing is that I am not able to figure out a way to pass the parameters of the neural network embedded in the ODE of the Lotka-Volterra model to the Hamiltonian as done here. The main issue here is that the hamiltonian is fed a vector of parameters and they are updated naturally as the optimization is carried out. I am having trouble achieving the same with the missing physics example.
Any pointers as to how this can be achieved will be very helpful. Thanks.
The LaTeX and the code don't seem to match up.
https://docs.sciml.ai/Overview/dev/showcase/symbolic_analysis/#Input-System-2
https://github.com/JuliaComputing/MultiDocumenter.jl
A lot of what's already here should be helpful to make this work out?
We should probably explain with each package installation what version of Julia is recommended/required.
More thoughts: https://discourse.julialang.org/t/universal-differential-equations/89093/7
It looks like it would be a good one to add: https://discourse.julialang.org/t/ann-finitevolumemethod-jl/91395. We'd need to vet it to our standards first.
Change "Plots and Visualization" to "Third-Party Plots and Visualization"?
We can optimize our S3 upload a bit by adding the following extra flags:
--size-only: Only upload a version if the size of the object has changed. Without this, since our timestamps are always newer (because we just copied all the files over) we're copying everything up every time. Since the sizes of things should be changing when uploading, I think this is fairly safe to set.--delete: We want to remove files that no longer exist locally, so that when we delete a file, it gets deleted on S3 as well.Also, we can split the Aggregate.yml file into two pieces, on that does the build, one that does the upload, so that only the upload part is signed. This will allow Aggregate.yml to be an unsigned pipeline, and editable without needing @thazhemadam to re-sign the pipelines. :)
This includes:
@example docs, like SciML/SciMLSensitivity.jl#649Anything missed?
In https://docs.sciml.ai/Overview/stable/getting_started/getting_started/#Coming-from... ,
the link for Introduction to Julia's SciML for the Python User is broken. It should point to https://docs.sciml.ai/Overview/stable/comparisons/python/.
A bunch of the Catalyst docs have dynamic output using @example blocks, but these seem like they aren't being executed here. See https://docs.sciml.ai/dev/modules/Catalyst/tutorials/symbolic_stoich/ and compare to https://catalyst.sciml.ai/dev/tutorials/symbolic_stoich/
When I run the exemplary code for "Solve your first optimization problem"
using Optimization, OptimizationNLopt
# Define the problem to optimize
L(u, p) = (p[1] - u[1])^2 + p[2] * (u[2] - u[1]^2)^2
# Define the Optimization Problem
u0 = zeros(2)
p = [1.0, 100.0]
prob = OptimizationProblem(L, u0, p, lb = -1 * ones(2), ub = ones(2))
# Solve the optimization problem
sol = solve(prob, NLopt.LD_LBFGS())
it gave a warning:
Warning: NLopt failed to converge: FORCED_STOP
└ @ OptimizationNLopt ~/.julia/packages/OptimizationNLopt/eAzgn/src/OptimizationNLopt.jl:231
and:
u: 2-element Vector{Float64}:
NaN
NaN
I guess the optimization was not successful?
By the way, I am using Julia version 1.9.
https://diffeq.sciml.ai/stable/analysis/dev_and_test/ The link in this page redirects to an http link instead of the https one, which leads to the not secure badge in chrome
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.