Skip to content

canonize docs #1940

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 12, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@
- `connect` should not be overloaded by users anymore. `[connect = Flow]`
informs ModelingToolkit that particular variable in a connector ought to sum
to zero, and by default, variables are equal in a connection. Please check out
[acausal components tutorial](https://mtk.sciml.ai/dev/tutorials/acausal_components/)
[acausal components tutorial](https://docs.sciml.ai/ModelingToolkit/stable/tutorials/acausal_components/)
for examples.
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,14 @@ computations. Automatic transformations, such as index reduction, can be applied
to the model to make it easier for numerical solvers to handle.

For information on using the package,
[see the stable documentation](https://mtk.sciml.ai/stable/). Use the
[in-development documentation](https://mtk.sciml.ai/dev/) for the version of
[see the stable documentation](https://docs.sciml.ai/ModelingToolkit/stable/). Use the
[in-development documentation](https://docs.sciml.ai/ModelingToolkit/dev/) for the version of
the documentation which contains the unreleased features.

## Standard Library

For a standard library of ModelingToolkit components and blocks, check out the
[ModelingToolkitStandardLibrary](https://github.com/SciML/ModelingToolkitStandardLibrary.jl)
[ModelingToolkitStandardLibrary](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/)

## High-Level Examples

Expand Down
2 changes: 1 addition & 1 deletion docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ makedocs(sitename = "ModelingToolkit.jl",
format = Documenter.HTML(; analytics = "UA-90474609-3",
assets = ["assets/favicon.ico"],
mathengine,
canonical = "https://mtk.sciml.ai/stable/",
canonical = "https://docs.sciml.ai/ModelingToolkit/stable/",
prettyurls = (get(ENV, "CI", nothing) == "true")),
pages = pages)

Expand Down
2 changes: 1 addition & 1 deletion docs/src/basics/ContextualVariables.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ ModelingToolkit.jl has a system of contextual variable types which allows for
helping the system transformation machinery do complex manipulations and
automatic detection. The standard variable definition in ModelingToolkit.jl is
the `@variable` which is defined by
[Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl). For example:
[Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/). For example:

```julia
@variables x y(x)
Expand Down
12 changes: 6 additions & 6 deletions docs/src/basics/Events.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ ModelingToolkit provides several ways to represent system events, which enable
system state or parameters to be changed when certain conditions are satisfied,
or can be used to detect discontinuities. These events are ultimately converted
into DifferentialEquations.jl [`ContinuousCallback`s or
`DiscreteCallback`s](https://docs.sciml.ai/stable/modules/DiffEqDocs/features/callback_functions/),
`DiscreteCallback`s](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/),
or into more specialized callback types from the
[DiffEqCallbacks.jl](https://docs.sciml.ai/stable/modules/DiffEqDocs/features/callback_library/)
[DiffEqCallbacks.jl](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_library/)
library.

[`ODESystem`](@ref)s and [`SDESystem`](@ref)s accept keyword arguments
Expand All @@ -15,7 +15,7 @@ discrete callbacks. [`JumpSystem`](@ref)s currently support only
zero, with root finding used to determine the time at which a zero crossing
occurred. Discrete events are applied when a condition tested after each
timestep evaluates to true. See the [DifferentialEquations
docs](https://docs.sciml.ai/stable/modules/DiffEqDocs/features/callback_functions/)
docs](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/)
for more detail.

Events involve both a *condition* function (for the zero crossing or truth
Expand Down Expand Up @@ -73,7 +73,7 @@ plot(sol)

### Example: Bouncing ball
In the documentation for
[DifferentialEquations](https://docs.sciml.ai/stable/modules/DiffEqDocs/features/callback_functions/#Example-1:-Bouncing-Ball),
[DifferentialEquations](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#Example-1:-Bouncing-Ball),
we have an example where a bouncing ball is simulated using callbacks which have
an `affect!` on the state. We can model the same system using ModelingToolkit
like this
Expand Down Expand Up @@ -149,12 +149,12 @@ that are accessed by `affect!`, respectively; and `ctx` is any context that is
passed to `affect!` as the `ctx` argument.

`affect!` receives a [DifferentialEquations.jl
integrator](https://docs.sciml.ai/stable/modules/DiffEqDocs/basics/integrator/)
integrator](https://docs.sciml.ai/DiffEqDocs/stable/basics/integrator/)
as its first argument, which can then be used to access states and parameters
that are provided in the `u` and `p` arguments (implemented as `NamedTuple`s).
The integrator can also be manipulated more generally to control solution
behavior, see the [integrator
interface](https://docs.sciml.ai/stable/modules/DiffEqDocs/basics/integrator/)
interface](https://docs.sciml.ai/DiffEqDocs/stable/basics/integrator/)
documentation. In affect functions we have that
```julia
function affect!(integ, u, p, ctx)
Expand Down
2 changes: 1 addition & 1 deletion docs/src/basics/Linearization.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ If the modeled system is actually proper (but MTK failed to find a proper realiz


## Tools for linear analysis
[ModelingToolkitStandardLibrary](http://mtkstdlib.sciml.ai/dev/API/linear_analysis/) contains a set of [tools for more advanced linear analysis](http://mtkstdlib.sciml.ai/dev/API/linear_analysis/). These can be used to make it easier to work with and analyze causal models, such as control and signal-processing systems.
[ModelingToolkitStandardLibrary](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/) contains a set of [tools for more advanced linear analysis](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/API/linear_analysis/). These can be used to make it easier to work with and analyze causal models, such as control and signal-processing systems.

```@index
Pages = ["Linearization.md"]
Expand Down
14 changes: 7 additions & 7 deletions docs/src/comparison.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,9 @@
Julia as an order of magnitude or more faster in many cases due to its JIT
compilation.
- Simulink uses the MATLAB differential equation solvers while ModelingToolkit.jl
uses [DifferentialEquations.jl](https://diffeq.sciml.ai/dev/). For a systematic
uses [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/). For a systematic
comparison between the solvers, consult
[open benchmarks](https://benchmarks.sciml.ai/html/MultiLanguage/wrapper_packages.html)
[open benchmarks](https://docs.sciml.ai/SciMLBenchmarksOutput/stable/)
which demonstrate two orders of magnitude performance advantage for the native
Julia solvers across many benchmark problems.
- Simulink comes with a Graphical User Interface (GUI), ModelingToolkit.jl
Expand All @@ -64,9 +64,9 @@
interactively in the REPL.
- CASADI includes limited support for Computer Algebra System (CAS) functionality,
while ModelingToolkit.jl is built on the full
[Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) CAS.
[Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/) CAS.
- CASADI supports DAE and ODE problems via SUNDIALS IDAS and CVODES. ModelingToolkit.jl
supports DAE and ODE problems via [DifferentialEquations.jl](https://diffeq.sciml.ai/dev/),
supports DAE and ODE problems via [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/),
of which Sundials.jl is <1% of the total available solvers and is outperformed
by the native Julia solvers on the vast majority of the benchmark equations.
In addition, the DifferentialEquations.jl interface is confederated, meaning
Expand All @@ -83,7 +83,7 @@
## Comparison Against Modia.jl

- Modia.jl uses Julia's expression objects for representing its equations.
ModelingToolkit.jl uses [Symbolics.jl](https://symbolics.juliasymbolics.org/dev/),
ModelingToolkit.jl uses [Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/),
and thus the Julia expressions follow Julia semantics and can be manipulated
using a computer algebra system (CAS).
- Modia's compilation pipeline is similar to the
Expand All @@ -93,7 +93,7 @@
`structural_simplify` is an adaptation of the Modia.jl-improved alias elimination
and tearing algorithms.
- Both Modia and ModelingToolkit generate `DAEProblem` and `ODEProblem` forms for
solving with [DifferentialEquations.jl](https://diffeq.sciml.ai/dev/).
solving with [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/).
- ModelingToolkit.jl integrates with its host language Julia, so Julia code
can be automatically converted into ModelingToolkit expressions. Users of
Modia must explicitly create Modia expressions.
Expand All @@ -106,7 +106,7 @@
- Causal.jl is a causal modeling environment, whereas ModelingToolkit.jl is an
acausal modeling environment. For an overview of the differences, consult
academic reviews such as [this one](https://arxiv.org/abs/1909.00484).
- Both ModelingToolkit.jl and Causal.jl use [DifferentialEquations.jl](https://diffeq.sciml.ai/stable/)
- Both ModelingToolkit.jl and Causal.jl use [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/)
as the backend solver library.
- Causal.jl lets one add arbitrary equation systems to a given node, and allow
the output to effect the next node. This means an SDE may drive an ODE. These
Expand Down
30 changes: 15 additions & 15 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ before generating code.

For information on how to use the Symbolics.jl CAS system that ModelingToolkit.jl
is built on, consult the
[Symbolics.jl documentation](https://github.com/JuliaSymbolics/Symbolics.jl)
[Symbolics.jl documentation](https://docs.sciml.ai/Symbolics/stable/)

### Equation Types

Expand All @@ -72,28 +72,28 @@ is built on, consult the
- Nonlinear systems
- Optimization problems
- Continuous-Time Markov Chains
- Chemical Reactions (via [Catalyst.jl](https://github.com/SciML/Catalyst.jl))
- Chemical Reactions (via [Catalyst.jl](https://docs.sciml.ai/Catalyst/stable/))
- Nonlinear Optimal Control

## Standard Library

For quick development, ModelingToolkit.jl includes
[ModelingToolkitStandardLibrary.jl](https://github.com/SciML/ModelingToolkitStandardLibrary.jl),
[ModelingToolkitStandardLibrary.jl](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/),
a standard library of prebuilt components for the ModelingToolkit ecosystem.

## Model Import Formats

- [CellMLToolkit.jl](https://github.com/SciML/CellMLToolkit.jl): Import [CellML](https://www.cellml.org/) models into ModelingToolkit
- [CellMLToolkit.jl](https://docs.sciml.ai/CellMLToolkit/stable/): Import [CellML](https://www.cellml.org/) models into ModelingToolkit
- Repository of more than a thousand pre-made models
- Focus on biomedical models in areas such as: Calcium Dynamics,
Cardiovascular Circulation, Cell Cycle, Cell Migration, Circadian Rhythms,
Electrophysiology, Endocrine, Excitation-Contraction Coupling, Gene Regulation,
Hepatology, Immunology, Ion Transport, Mechanical Constitutive Laws,
Metabolism, Myofilament Mechanics, Neurobiology, pH Regulation, PKPD,
Protein Modules, Signal Transduction, and Synthetic Biology.
- [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl): Import [SBML](http://sbml.org/) models into ModelingToolkit
- [SBMLToolkit.jl](https://docs.sciml.ai/SBMLToolkit/stable/): Import [SBML](http://sbml.org/) models into ModelingToolkit
- Uses the robust libsbml library for parsing and transforming the SBML
- [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl): Import various models into ModelingToolkit
- [ReactionNetworkImporters.jl](https://docs.sciml.ai/ReactionNetworkImporters/stable/): Import various models into ModelingToolkit
- Supports the BioNetGen `.net` file
- Supports importing networks specified by stoichiometric matrices

Expand All @@ -103,20 +103,20 @@ Because ModelingToolkit.jl is the core foundation of a equation-based modeling
ecosystem, there is a large set of libraries adding features to this system.
Below is an incomplete list of extension libraries one may want to be aware of:

- [Catalyst.jl](https://github.com/SciML/Catalyst.jl): Symbolic representations
- [Catalyst.jl](https://docs.sciml.ai/Catalyst/stable/): Symbolic representations
of chemical reactions
- Symbolically build and represent large systems of chemical reactions
- Generate code for ODEs, SDEs, continuous-time Markov Chains, and more
- Simulate the models using the SciML ecosystem with O(1) Gillespie methods
- [DataDrivenDiffEq.jl](https://github.com/SciML/DataDrivenDiffEq.jl): Automatic
- [DataDrivenDiffEq.jl](https://docs.sciml.ai/DataDrivenDiffEq/stable/): Automatic
identification of equations from data
- Automated construction of ODEs and DAEs from data
- Representations of Koopman operators and Dynamic Mode Decomposition (DMD)
- [MomentClosure.jl](https://github.com/augustinas1/MomentClosure.jl): Automatic
- [MomentClosure.jl](https://docs.sciml.ai/MomentClosure/dev/): Automatic
transformation of ReactionSystems into deterministic systems
- Generates ODESystems for the moment closures
- Allows for geometrically-distributed random reaction rates
- [ReactionMechanismSimulator.jl](https://github.com/ReactionMechanismGenerator/ReactionMechanismSimulator.jl):
- [ReactionMechanismSimulator.jl](https://docs.sciml.ai/ReactionMechanismSimulator/stable):
Simulating and analyzing large chemical reaction mechanisms
- Ideal gas and dilute liquid phases.
- Constant T and P and constant V adiabatic ideal gas reactors.
Expand All @@ -140,16 +140,16 @@ an `ODEProblem` to then be solved by a numerical ODE solver. Below is a list of
the solver libraries which are the numerical targets of the ModelingToolkit
system:

- [DifferentialEquations.jl](https://diffeq.sciml.ai/stable/)
- [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/)
- Multi-package interface of high performance numerical solvers for `ODESystem`,
`SDESystem`, and `JumpSystem`
- [NonlinearSolve.jl](https://github.com/JuliaComputing/NonlinearSolve.jl)
- [NonlinearSolve.jl](https://docs.sciml.ai/NonlinearSolve/stable/)
- High performance numerical solving of `NonlinearSystem`
- [Optimization.jl](https://github.com/SciML/Optimization.jl)
- [Optimization.jl](https://docs.sciml.ai/Optimization/stable/)
- Multi-package interface for numerical solving `OptimizationSystem`
- [NeuralPDE.jl](https://github.com/SciML/NeuralPDE.jl)
- [NeuralPDE.jl](https://docs.sciml.ai/NeuralPDE/stable/)
- Physics-Informed Neural Network (PINN) training on `PDESystem`
- [MethodOfLines.jl](https://github.com/SciML/MethodOfLines.jl)
- [MethodOfLines.jl](https://docs.sciml.ai/MethodOfLines/stable/)
- Automated finite difference method (FDM) discretization of `PDESystem`

## Contributing
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ In this tutorial we will look at the pendulum system:
```

As a good DifferentialEquations.jl user, one would follow
[the mass matrix DAE tutorial](https://diffeq.sciml.ai/stable/tutorials/dae_example/#Mass-Matrix-Differential-Algebraic-Equations-(DAEs))
[the mass matrix DAE tutorial](https://docs.sciml.ai/DiffEqDocs/stable/tutorials/dae_example/#Mass-Matrix-Differential-Algebraic-Equations-(DAEs))
to arrive at code for simulating the model:

```@example indexred
Expand Down
6 changes: 3 additions & 3 deletions docs/src/systems/PDESystem.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,12 +72,12 @@ The only functions which act on a PDESystem are the following:

### NeuralPDE.jl: PhysicsInformedNN

[NeuralPDE.jl](https://github.com/SciML/NeuralPDE.jl) defines the `PhysicsInformedNN`
discretizer which uses a [DiffEqFlux.jl](https://github.com/SciML/DiffEqFlux.jl)
[NeuralPDE.jl](https://docs.sciml.ai/NeuralPDE/stable/) defines the `PhysicsInformedNN`
discretizer which uses a [DiffEqFlux.jl](https://docs.sciml.ai/DiffEqFlux/stable/)
neural network to solve the differential equation.

### MethodOfLines.jl: MOLFiniteDifference

[MethodOfLines.jl](https://github.com/SciML/MethodOfLines.jl) defines the
[MethodOfLines.jl](https://docs.sciml.ai/MethodOfLines/stable/) defines the
`MOLFiniteDifference` discretizer which performs a finite difference discretization.
Includes support for higher approximation order stencils and nonuniform grids.
8 changes: 4 additions & 4 deletions docs/src/tutorials/acausal_components.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ equalities before solving. Let's see this in action.

This tutorial teaches how to build the entire RC circuit from scratch.
However, to simulate electrical components with more ease, check out the
[ModelingToolkitStandardLibrary.jl](https://github.com/SciML/ModelingToolkitStandardLibrary.jl)
[ModelingToolkitStandardLibrary.jl](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/)
which includes a
[tutorial for simulating RC circuits with pre-built components](http://mtkstdlib.sciml.ai/dev/tutorials/rc_circuit/)
[tutorial for simulating RC circuits with pre-built components](https://docs.sciml.ai/ModelingToolkitStandardLibrary/stable/tutorials/rc_circuit/)

## Copy-Paste Example

Expand Down Expand Up @@ -303,7 +303,7 @@ parameters(rc_model)
## Simplifying and Solving this System

This system could be solved directly as a DAE using [one of the DAE solvers
from DifferentialEquations.jl](https://diffeq.sciml.ai/stable/solvers/dae_solve/).
from DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/dae_solve/).
However, let's take a second to symbolically simplify the system before doing the
solve. Although we can use ODE solvers that handles mass matrices to solve the
above system directly, we want to run the `structural_simplify` function first,
Expand All @@ -324,7 +324,7 @@ with two state variables. One of the equations is a differential equation
while the other is an algebraic equation. We can then give the values for the
initial conditions of our states and solve the system by converting it to
an ODEProblem in mass matrix form and solving it with an [ODEProblem mass matrix
DAE solver](https://diffeq.sciml.ai/stable/solvers/dae_solve/#OrdinaryDiffEq.jl-(Mass-Matrix)).
DAE solver](https://docs.sciml.ai/DiffEqDocs/stable/solvers/dae_solve/#OrdinaryDiffEq.jl-(Mass-Matrix)).
This is done as follows:

```@example acausal
Expand Down
2 changes: 1 addition & 1 deletion docs/src/tutorials/ode_modeling.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Note that equations in MTK use the tilde character (`~`) as equality sign.
Also note that the `@named` macro simply ensures that the symbolic name
matches the name in the REPL. If omitted, you can directly set the `name` keyword.

After construction of the ODE, you can solve it using [DifferentialEquations.jl](https://diffeq.sciml.ai/):
After construction of the ODE, you can solve it using [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/):

```julia
using DifferentialEquations
Expand Down
2 changes: 1 addition & 1 deletion docs/src/tutorials/spring_mass.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ parameters(model)

### Simplifying and solving this system

This system can be solved directly as a DAE using [one of the DAE solvers from DifferentialEquations.jl](https://diffeq.sciml.ai/stable/solvers/dae_solve/). However, we can symbolically simplify the system first beforehand. Running `structural_simplify` eliminates unnecessary variables from the model to give the leanest numerical representation of the system.
This system can be solved directly as a DAE using [one of the DAE solvers from DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/dae_solve/). However, we can symbolically simplify the system first beforehand. Running `structural_simplify` eliminates unnecessary variables from the model to give the leanest numerical representation of the system.

```@example component
sys = structural_simplify(model)
Expand Down