flesh out next steps

ArnoStrouwen · ArnoStrouwen · commit 1daa32fdf8de · 2024-10-03T11:23:48.000+02:00
diff --git 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
@@ -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_ODE)
 
 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
@@ -1,4 +1,4 @@
-# Automated Index Reduction of DAEs
+# [Automated Index Reduction of DAEs](@ref 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -366,24 +366,48 @@ 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:
-
-  - 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.
-
-Where to go next?
-
+Now you know how to do basic ODE modeling with MTK, what's next is up to you.
+
+If ODEs are not your speed, MTK can represent many other systems:
+  - [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`](@id 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 internal)
diff --git 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
@@ -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
@@ -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

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages`
	`1`	`+# [Comparison of ModelingToolkit vs Equation-Based and Block Modeling Languages](@id comparison)`
`2`	`2`
`3`	`3`	`## Comparison Against Modelica`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Automatic Transformation of Nth Order ODEs to 1st Order ODEs`
	`1`	`+# [Automatic Transformation of Nth Order ODEs to 1st Order ODEs](@id higher_order_ODE)`
`2`	`2`
`3`	`3`	`ModelingToolkit has a system for transformations of mathematical`
`4`	`4`	`systems. These transformations allow for symbolically changing`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Automated Index Reduction of DAEs`
	`1`	`+# [Automated Index Reduction of DAEs](@ref higher_index)`
`2`	`2`
`3`	`3`	`In many cases one may accidentally write down a DAE that is not easily solvable`
`4`	`4`	`by numerical methods. In this tutorial, we will walk through an example of a`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Optimizing through an ODE solve and re-creating MTK Problems`
	`1`	`+# [Optimizing through an ODE solve and re-creating MTK Problems](@id remake)`
`2`	`2`
`3`	`3`	Solving an ODE as part of an `OptimizationProblem`'s loss function is a common scenario.
`4`	`4`	`In this example, we will go through an efficient way to model such scenarios using`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Automated Sparse Analytical Jacobians`
	`1`	`+# [Automated Sparse Analytical Jacobians](@id modelingtoolkitize_sparse)`
`2`	`2`
`3`	`3`	`In many cases where you have large stiff differential equations, getting a`
`4`	`4`	`sparse Jacobian can be essential for performance. In this tutorial, we will show`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Exposing More Parallelism By Tearing Algebraic Equations in ODESystems`
	`1`	`+# [Exposing More Parallelism By Tearing Algebraic Equations in ODESystems](@id tearing)`
`2`	`2`
`3`	`3`	`Sometimes it can be very non-trivial to parallelize a system. In this tutorial,`
`4`	`4`	we will demonstrate how to make use of `structural_simplify` to expose more
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Internal Details`
	`1`	`+# [Internal Details](@id internals)`
`2`	`2`
`3`	`3`	`This is a page for detailing some of the inner workings to help future`
`4`	`4`	`contributors to the library.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Clocks and Sampled-Data Systems`
	`1`	`+# [Clocks and Sampled-Data Systems](@id hybrid)`
`2`	`2`
`3`	`3`	`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.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# (Experimental) Modeling Discrete Systems`
	`1`	`+# (Experimental) [Modeling Discrete Systems](@id discrete)`
`2`	`2`
`3`	`3`	In this example, we will use the new [`DiscreteSystem`](@ref) API
`4`	`4`	`to create an SIR model.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Initialization of ODESystems`
	`1`	`+# [Initialization of ODESystems](@id initialization)`
`2`	`2`
`3`	`3`	`While for simple numerical ODEs choosing an initial condition can be an easy`
`4`	`4`	`affair, with ModelingToolkit's more general differential-algebraic equation`