diff --git a/docs/src/comparison.md b/docs/src/comparison.md index fcf0c70afb..37763ef20c 100644 --- a/docs/src/comparison.md +++ b/docs/src/comparison.md @@ -1,4 +1,4 @@ -# Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages +# [Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages](@id comparison) ## Comparison Against Modelica diff --git a/docs/src/examples/higher_order.md b/docs/src/examples/higher_order.md index 7dafe758dc..608a7490fa 100644 --- a/docs/src/examples/higher_order.md +++ b/docs/src/examples/higher_order.md @@ -1,4 +1,4 @@ -# Automatic Transformation of Nth Order ODEs to 1st Order ODEs +# [Automatic Transformation of Nth Order ODEs to 1st Order ODEs](@id higher_order) ModelingToolkit has a system for transformations of mathematical systems. These transformations allow for symbolically changing diff --git a/docs/src/examples/modelingtoolkitize_index_reduction.md b/docs/src/examples/modelingtoolkitize_index_reduction.md index 415d5b85ff..dae0025c2b 100644 --- a/docs/src/examples/modelingtoolkitize_index_reduction.md +++ b/docs/src/examples/modelingtoolkitize_index_reduction.md @@ -1,4 +1,4 @@ -# Automated Index Reduction of DAEs +# [Automated Index Reduction of DAEs](@id higher_index) In many cases one may accidentally write down a DAE that is not easily solvable by numerical methods. In this tutorial, we will walk through an example of a diff --git a/docs/src/examples/remake.md b/docs/src/examples/remake.md index f4396ef7a7..e692e53d2a 100644 --- a/docs/src/examples/remake.md +++ b/docs/src/examples/remake.md @@ -1,4 +1,4 @@ -# Optimizing through an ODE solve and re-creating MTK Problems +# [Optimizing through an ODE solve and re-creating MTK Problems](@id remake) Solving an ODE as part of an `OptimizationProblem`'s loss function is a common scenario. In this example, we will go through an efficient way to model such scenarios using diff --git a/docs/src/examples/sparse_jacobians.md b/docs/src/examples/sparse_jacobians.md index 1ed3b1733c..942938fff8 100644 --- a/docs/src/examples/sparse_jacobians.md +++ b/docs/src/examples/sparse_jacobians.md @@ -1,4 +1,4 @@ -# Automated Sparse Analytical Jacobians +# [Automated Sparse Analytical Jacobians](@id modelingtoolkitize_sparse) In many cases where you have large stiff differential equations, getting a sparse Jacobian can be essential for performance. In this tutorial, we will show diff --git a/docs/src/examples/tearing_parallelism.md b/docs/src/examples/tearing_parallelism.md index 9540e610bd..fb850204dd 100644 --- a/docs/src/examples/tearing_parallelism.md +++ b/docs/src/examples/tearing_parallelism.md @@ -1,4 +1,4 @@ -# Exposing More Parallelism By Tearing Algebraic Equations in ODESystems +# [Exposing More Parallelism By Tearing Algebraic Equations in ODESystems](@id tearing) Sometimes it can be very non-trivial to parallelize a system. In this tutorial, we will demonstrate how to make use of `structural_simplify` to expose more diff --git a/docs/src/internals.md b/docs/src/internals.md index 00b29f1a64..8669867e0c 100644 --- a/docs/src/internals.md +++ b/docs/src/internals.md @@ -1,4 +1,4 @@ -# Internal Details +# [Internal Details](@id internals) This is a page for detailing some of the inner workings to help future contributors to the library. diff --git a/docs/src/tutorials/SampledData.md b/docs/src/tutorials/SampledData.md index a72fd1698b..9ad73e62ff 100644 --- a/docs/src/tutorials/SampledData.md +++ b/docs/src/tutorials/SampledData.md @@ -1,4 +1,4 @@ -# Clocks and Sampled-Data Systems +# [Clocks and Sampled-Data Systems](@id hybrid) A sampled-data system contains both continuous-time and discrete-time components, such as a continuous-time plant model and a discrete-time control system. ModelingToolkit supports the modeling and simulation of sampled-data systems by means of *clocks*. diff --git a/docs/src/tutorials/discrete_system.md b/docs/src/tutorials/discrete_system.md index 8f6828fde7..0630c51a6c 100644 --- a/docs/src/tutorials/discrete_system.md +++ b/docs/src/tutorials/discrete_system.md @@ -1,4 +1,4 @@ -# (Experimental) Modeling Discrete Systems +# [(Experimental) Modeling Discrete Systems](@id discrete) In this example, we will use the new [`DiscreteSystem`](@ref) API to create an SIR model. diff --git a/docs/src/tutorials/initialization.md b/docs/src/tutorials/initialization.md index f40c28991f..5655eaef56 100644 --- a/docs/src/tutorials/initialization.md +++ b/docs/src/tutorials/initialization.md @@ -1,4 +1,4 @@ -# Initialization of ODESystems +# [Initialization of ODESystems](@id initialization) While for simple numerical ODEs choosing an initial condition can be an easy affair, with ModelingToolkit's more general differential-algebraic equation diff --git a/docs/src/tutorials/modelingtoolkitize.md b/docs/src/tutorials/modelingtoolkitize.md index e272a2237c..aeae823290 100644 --- a/docs/src/tutorials/modelingtoolkitize.md +++ b/docs/src/tutorials/modelingtoolkitize.md @@ -1,4 +1,4 @@ -# Modelingtoolkitize: Automatically Translating Numerical to Symbolic Code +# [Modelingtoolkitize: Automatically Translating Numerical to Symbolic Code](@id modelingtoolkitize) ## What is `modelingtoolkitize`? diff --git a/docs/src/tutorials/nonlinear.md b/docs/src/tutorials/nonlinear.md index 057e856229..b7b21a4d38 100644 --- a/docs/src/tutorials/nonlinear.md +++ b/docs/src/tutorials/nonlinear.md @@ -1,4 +1,4 @@ -# Modeling Nonlinear Systems +# [Modeling Nonlinear Systems](@id nonlinear) ModelingToolkit.jl is not only useful for generating initial value problems (`ODEProblem`). The package can also build nonlinear systems. diff --git a/docs/src/tutorials/ode_modeling.md b/docs/src/tutorials/ode_modeling.md index 755e70ef46..62e38c4f7d 100644 --- a/docs/src/tutorials/ode_modeling.md +++ b/docs/src/tutorials/ode_modeling.md @@ -366,24 +366,55 @@ exploiting the structural information. For more information, see the ## Notes and pointers how to go on -Here are some notes that may be helpful during your initial steps with MTK: +Now you know how to do basic ODE modeling with MTK, what's next is up to you. - - The `@mtkmodel` macro is for high-level usage of MTK. However, in many cases you - may need to programmatically generate `ODESystem`s. If that's the case, check out - the [Programmatically Generating and Scripting ODESystems Tutorial](@ref programmatically). - - Vector-valued parameters and variables are possible. A cleaner, more - consistent treatment of these is still a work in progress, however. Once finished, - this introductory tutorial will also cover this feature. +If ODEs are not your speed, MTK can represent many other systems: -Where to go next? + - [Rootfinding for nonlinear systems of equations](@ref nonlinear) + - [Solving optimization problems](@ref optimization) + - [Stochastic Differential Equations](@ref SDE) + - Jump Systems + - [Discrete time systems](@ref discrete) + - [hybrid systems](@ref hybrid). + +Numerical differential equation solvers require you to write your model in a very specific form. +However, these forms are often not the most human-readable. +MTK has symbolic transforms to translate your model into something your computer can simulate: + + - [Automatically transform higher order ODEs to first order ones](@ref higher_order) + - [Automatically transform higher index DAEs to index one](@ref higher_index) + +If you want some extra modeling goodies: + + - [Validate your equations with units](@ref units) + - [Add discrete time controls to your continuous plant](@ref hybrid) + - [Add general discrete/continuous time events to your system](@ref events) + +If the getting started tutorial is too high-level for you, do a deeper dive: + + - [Learn everything there is to know about `@mtkmodel` blocks](@ref mtk_language) + - [Learn how to write your own components to use in `@mtkmodel`](@ref acausal) + - [Learn how to script the creation of `ODESystems` without the `@mtkmodel`](@ref programmatically) + - [Learn how to conserve certain quantities when connecting components using a domain](@ref domains) + - [Learn how MTK ensures that the initial state of your model is correct](@ref initialization) + - [Learn how MTK reduces the size of your model](@ref tearing) + +If you liked the idea of the speedup symbolic Jacobians give you, but don't want to commit to writing your entire model in MTK: + + - [modelingtoolkitize your `ODEProblem`](@ref modelingtoolkitize) + - [use modelingtoolkitize to calculate sparsity patterns](@ref modelingtoolkitize_sparse) + +If you want to further investigate the properties of your ODE model: + + - [Check if the parameters of your model are identifiable](@ref identifiability) + - [Check if your system exhibits any bifurcation](@ref bifurcation_diagrams) + - [Perform a perturbation analysis to see your system change as parameter values change](@ref perturb_diff) + - [Linearize your system](@ref linearization) and [turn it into an input-output system](@ref inputoutput) (useful for feedback control) + - [Use your MTK ODE model in an `OptimizationProblem`](@ref remake) + +Still want to know more about MTK? - Not sure how MTK relates to similar tools and packages? Read - [Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages](@ref). - - For a more detailed explanation of `@mtkmodel` checkout - [Defining components with `@mtkmodel` and connectors with `@connectors`](@ref mtk_language) - - Depending on what you want to do with MTK, have a look at some of the other - **Symbolic Modeling Tutorials**. - - If you want to automatically convert an existing function to a symbolic - representation, you might go through the **ModelingToolkitize Tutorials**. - - To learn more about the inner workings of MTK, consider the sections under - **Basics** and **System Types**. + [Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages](@ref comparison) + - Want to become a MTK dev? Read + [Internal Details](@ref internals) diff --git a/docs/src/tutorials/optimization.md b/docs/src/tutorials/optimization.md index 20f1079dcd..fbf161d53b 100644 --- a/docs/src/tutorials/optimization.md +++ b/docs/src/tutorials/optimization.md @@ -1,4 +1,4 @@ -# Modeling Optimization Problems +# [Modeling Optimization Problems](@id optimization) ModelingToolkit.jl is not only useful for generating initial value problems (`ODEProblem`). The package can also build optimization systems. diff --git a/docs/src/tutorials/parameter_identifiability.md b/docs/src/tutorials/parameter_identifiability.md index 0875a7698c..945525fb87 100644 --- a/docs/src/tutorials/parameter_identifiability.md +++ b/docs/src/tutorials/parameter_identifiability.md @@ -1,4 +1,4 @@ -# Parameter Identifiability in ODE Models +# [Parameter Identifiability in ODE Models](@id identifiability) Ordinary differential equations are commonly used for modeling real-world processes. The problem of parameter identifiability is one of the key design challenges for mathematical models. A parameter is said to be _identifiable_ if one can recover its value from experimental data. _Structural_ identifiability is a theoretical property of a model that answers this question. In this tutorial, we will show how to use `StructuralIdentifiability.jl` with `ModelingToolkit.jl` to assess identifiability of parameters in ODE models. The theory behind `StructuralIdentifiability.jl` is presented in paper [^4]. diff --git a/docs/src/tutorials/stochastic_diffeq.md b/docs/src/tutorials/stochastic_diffeq.md index fd03d51810..feff585a43 100644 --- a/docs/src/tutorials/stochastic_diffeq.md +++ b/docs/src/tutorials/stochastic_diffeq.md @@ -1,4 +1,4 @@ -# Modeling with Stochasticity +# [Modeling with Stochasticity](@id SDE) All models with `ODESystem` are deterministic. `SDESystem` adds another element to the model: randomness. This is a