Merge pull request #2478 from SciML/ChrisRackauckas-patch-5

Fix and update documentation for v9

Author: ChrisRackauckas

docs/src/basics/Composition.md

@@ -16,22 +16,20 @@ of `decay2` is the value of the unknown variable `x`.
 
 ```@example composition
 using ModelingToolkit
+using ModelingToolkit: t_nounits as t, D_nounits as D
 
 function decay(; name)
-    @parameters t a
+    @parameters a
     @variables x(t) f(t)
-    D = Differential(t)
     ODESystem([
             D(x) ~ -a * x + f
-        ];
+        ], t;
         name = name)
 end
 
 @named decay1 = decay()
 @named decay2 = decay()
 
-@parameters t
-D = Differential(t)
 connected = compose(
     ODESystem([decay2.f ~ decay1.x
                D(decay1.f) ~ 0], t; name = :connected), decay1, decay2)
@@ -137,7 +135,7 @@ sys.y = u * 1.1
 In a hierarchical system, variables of the subsystem get namespaced by the name of the system they are in. This prevents naming clashes, but also enforces that every unknown and parameter is local to the subsystem it is used in. In some cases it might be desirable to have variables and parameters that are shared between subsystems, or even global. This can be accomplished as follows.
 
 ```julia
-@parameters t a b c d e f
+@parameters a b c d e f
 
 # a is a local variable
 b = ParentScope(b) # b is a variable that belongs to one level up in the hierarchy
@@ -197,19 +195,16 @@ higher level system:
 
 ```@example compose
 using ModelingToolkit, OrdinaryDiffEq, Plots
+using ModelingToolkit: t_nounits as t, D_nounits as D
 
 ## Library code
-
-@parameters t
-D = Differential(t)
-
 @variables S(t), I(t), R(t)
 N = S + I + R
 @parameters β, γ
 
-@named seqn = ODESystem([D(S) ~ -β * S * I / N])
-@named ieqn = ODESystem([D(I) ~ β * S * I / N - γ * I])
-@named reqn = ODESystem([D(R) ~ γ * I])
+@named seqn = ODESystem([D(S) ~ -β * S * I / N], t)
+@named ieqn = ODESystem([D(I) ~ β * S * I / N - γ * I], t)
+@named reqn = ODESystem([D(R) ~ γ * I],t )
 
 sir = compose(
     ODESystem(

docs/src/basics/Events.md

@@ -65,9 +65,10 @@ friction
 
 ```@example events
 using ModelingToolkit, OrdinaryDiffEq, Plots
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
 function UnitMassWithFriction(k; name)
-    @variables t x(t)=0 v(t)=0
-    D = Differential(t)
+    @variables x(t)=0 v(t)=0
     eqs = [D(x) ~ v
            D(v) ~ sin(t) - k * sign(v)]
     ODESystem(eqs, t; continuous_events = [v ~ 0], name) # when v = 0 there is a discontinuity
@@ -87,8 +88,7 @@ an `affect!` on the state. We can model the same system using ModelingToolkit
 like this
 
 ```@example events
-@variables t x(t)=1 v(t)=0
-D = Differential(t)
+@variables x(t)=1 v(t)=0
 
 root_eqs = [x ~ 0]  # the event happens at the ground x(t) = 0
 affect = [v ~ -v] # the effect is that the velocity changes sign
@@ -108,8 +108,7 @@ plot(sol)
 Multiple events? No problem! This example models a bouncing ball in 2D that is enclosed by two walls at $y = \pm 1.5$.
 
 ```@example events
-@variables t x(t)=1 y(t)=0 vx(t)=0 vy(t)=2
-D = Differential(t)
+@variables x(t)=1 y(t)=0 vx(t)=0 vy(t)=2
 
 continuous_events = [[x ~ 0] => [vx ~ -vx]
                      [y ~ -1.5, y ~ 1.5] => [vy ~ -vy]]
@@ -229,7 +228,7 @@ Suppose we have a population of `N(t)` cells that can grow and die, and at time
 
 ```@example events
 @parameters M tinject α
-@variables t N(t)
+@variables N(t)
 Dₜ = Differential(t)
 eqs = [Dₜ(N) ~ α - N]
 

docs/src/basics/FAQ.md

@@ -102,9 +102,10 @@ end
 This error can come up after running `structural_simplify` on a system that generates dummy derivatives (i.e. variables with `ˍt`).  For example, here even though all the variables are defined with initial values, the `ODEProblem` generation will throw an error that defaults are missing from the variable map.
 
 ```
-@variables t
+using ModelingToolkit
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
 sts = @variables x1(t)=0.0 x2(t)=0.0 x3(t)=0.0 x4(t)=0.0
-D = Differential(t)
 eqs = [x1 + x2 + 1 ~ 0
        x1 + x2 + x3 + 2 ~ 0
        x1 + D(x3) + x4 + 3 ~ 0
@@ -137,9 +138,9 @@ container type. For example:
 
 ```
 using ModelingToolkit, StaticArrays
-@variables t
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
 sts = @variables x1(t)=0.0
-D = Differential(t)
 eqs = [D(x1) ~ 1.1 * x1]
 @mtkbuild sys = ODESystem(eqs, t)
 prob = ODEProblem{false}(sys, [], (0,1); u0_constructor = x->SVector(x...))

docs/src/basics/Linearization.md

@@ -21,9 +21,9 @@ The `linearize` function expects the user to specify the inputs ``u`` and the ou
 
 ```@example LINEARIZE
 using ModelingToolkit
-@variables t x(t)=0 y(t)=0 u(t)=0 r(t)=0
+using ModelingToolkit: t_nounits as t, D_nounits as D
+@variables x(t)=0 y(t)=0 u(t)=0 r(t)=0
 @parameters kp = 1
-D = Differential(t)
 
 eqs = [u ~ kp * (r - y) # P controller
        D(x) ~ -x + u    # First-order plant

docs/src/basics/Validation.md

@@ -83,7 +83,7 @@ second argument.
 ```@example validation2
 using ModelingToolkit, Unitful
 # Composite type parameter in registered function
-@parameters t
+@variables t
 D = Differential(t)
 struct NewType
     f::Any

docs/src/basics/Variable_metadata.md

@@ -10,14 +10,14 @@ Descriptive strings can be attached to variables using the `[description = "desc
 
 ```@example metadata
 using ModelingToolkit
+using ModelingToolkit: t_nounits as t, D_nounits as D
 @variables u [description = "This is my input"]
 getdescription(u)
 ```
 
 When variables with descriptions are present in systems, they will be printed when the system is shown in the terminal:
 
 ```@example metadata
-@parameters t
 @variables u(t) [description = "A short description of u"]
 @parameters p [description = "A description of p"]
 @named sys = ODESystem([u ~ p], t)
@@ -50,8 +50,9 @@ current in a resistor. These variables sum up to zero in connections.
 
 ```@example connect
 using ModelingToolkit
+using ModelingToolkit: t_nounits as t, D_nounits as D
 
-@variables t, i(t) [connect = Flow]
+@variables i(t) [connect = Flow]
 @variables k(t) [connect = Stream]
 ```
 
@@ -61,6 +62,8 @@ Designate a variable as either an input or an output using the following
 
 ```@example metadata
 using ModelingToolkit
+using ModelingToolkit: t_nounits as t, D_nounits as D
+
 @variables u [input = true]
 isinput(u)
 ```
@@ -136,8 +139,6 @@ For systems that contain parameters with metadata like described above, have som
 In the example below, we define a system with tunable parameters and extract bounds vectors
 
 ```@example metadata
-@parameters t
-Dₜ = Differential(t)
 @variables x(t)=0 u(t)=0 [input = true] y(t)=0 [output = true]
 @parameters T [tunable = true, bounds = (0, Inf)]
 @parameters k [tunable = true, bounds = (0, Inf)]

docs/src/examples/higher_order.md

@@ -13,16 +13,16 @@ We utilize the derivative operator twice here to define the second order:
 
 ```@example orderlowering
 using ModelingToolkit, OrdinaryDiffEq
+using ModelingToolkit: t_nounits as t, D_nounits as D
 
 @parameters σ ρ β
-@variables t x(t) y(t) z(t)
-D = Differential(t)
+@variables x(t) y(t) z(t)
 
 eqs = [D(D(x)) ~ σ * (y - x),
     D(y) ~ x * (ρ - z) - y,
     D(z) ~ x * y - β * z]
 
-@named sys = ODESystem(eqs)
+@named sys = ODESystem(eqs,t)
 ```
 
 Note that we could've used an alternative syntax for 2nd order, i.e.

docs/src/examples/modelingtoolkitize_index_reduction.md

@@ -31,7 +31,7 @@ pendulum_prob = ODEProblem(pendulum_fun!, u0, tspan, p)
 traced_sys = modelingtoolkitize(pendulum_prob)
 pendulum_sys = structural_simplify(dae_index_lowering(traced_sys))
 prob = ODEProblem(pendulum_sys, [], tspan)
-sol = solve(prob, Tsit5(), abstol = 1e-8, reltol = 1e-8)
+sol = solve(prob, Rodas5P(), abstol = 1e-8, reltol = 1e-8)
 plot(sol, idxs = unknowns(traced_sys))
 ```
 
@@ -71,7 +71,7 @@ u0 = [1.0, 0, 0, 0, 0];
 p = [9.8, 1];
 tspan = (0, 10.0);
 pendulum_prob = ODEProblem(pendulum_fun!, u0, tspan, p)
-solve(pendulum_prob, Rodas4())
+solve(pendulum_prob, Rodas5P())
 ```
 
 However, one will quickly be greeted with the unfortunate message:
@@ -151,7 +151,7 @@ numerical solver. Let's try that out:
 traced_sys = modelingtoolkitize(pendulum_prob)
 pendulum_sys = structural_simplify(dae_index_lowering(traced_sys))
 prob = ODEProblem(pendulum_sys, Pair[], tspan)
-sol = solve(prob, Rodas4())
+sol = solve(prob, Rodas5P())
 
 using Plots
 plot(sol, idxs = unknowns(traced_sys))

docs/src/examples/perturbation.md

@@ -45,8 +45,9 @@ As the first ODE example, we have chosen a simple and well-behaved problem, whic
 with the initial conditions $x(0) = 0$, and $\dot{x}(0) = 1$. Note that for $\epsilon = 0$, this equation transforms back to the standard one. Let's start with defining the variables
 
 ```julia
+using ModelingToolkit: t_nounits as t, D_nounits as D
 n = 3
-@variables ϵ t y[1:n](t) ∂∂y[1:n](t)
+@variables ϵ y[1:n](t) ∂∂y[1:n](t)
 ```
 
 Next, we define $x$.
@@ -82,7 +83,6 @@ vals = solve_coef(eqs, ∂∂y)
 Our system of ODEs is forming. Now is the time to convert `∂∂`s to the correct **Symbolics.jl** form by substitution:
 
 ```julia
-D = Differential(t)
 subs = Dict(∂∂y[i] => D(D(y[i])) for i in eachindex(y))
 eqs = [substitute(first(v), subs) ~ substitute(last(v), subs) for v in vals]
 ```
@@ -147,7 +147,6 @@ vals = solve_coef(eqs, ∂∂y)
 Next, we need to replace `∂`s and `∂∂`s with their **Symbolics.jl** counterparts:
 
 ```julia
-D = Differential(t)
 subs1 = Dict(∂y[i] => D(y[i]) for i in eachindex(y))
 subs2 = Dict(∂∂y[i] => D(D(y[i])) for i in eachindex(y))
 subs = subs1 ∪ subs2

docs/src/examples/spring_mass.md

@@ -6,11 +6,9 @@ In this tutorial, we will build a simple component-based model of a spring-mass
 
 ```@example component
 using ModelingToolkit, Plots, DifferentialEquations, LinearAlgebra
+using ModelingToolkit: t_nounits as t, D_nounits as D
 using Symbolics: scalarize
 
-@variables t
-D = Differential(t)
-
 function Mass(; name, m = 1.0, xy = [0.0, 0.0], u = [0.0, 0.0])
     ps = @parameters m = m
     sts = @variables pos(t)[1:2]=xy v(t)[1:2]=u