Update docs

Author: YingboMa

docs/src/basics/Composition.md

@@ -32,10 +32,10 @@ end
 
 @parameters t
 D = Differential(t)
-@named connected = ODESystem([
+@named connected = compose(ODESystem([
                         decay2.f ~ decay1.x
                         D(decay1.f) ~ 0
-                      ], t, systems=[decay1, decay2])
+                      ], t), decay1, decay2)
 
 equations(connected)
 
@@ -81,7 +81,7 @@ subsystems. A model is the composition of itself and its subsystems.
 For example, if we have:
 
 ```julia
-@named sys = ODESystem(eqs,indepvar,states,ps,system=[subsys])
+@named sys = compose(ODESystem(eqs,indepvar,states,ps),subsys)
 ```
 
 the `equations` of `sys` is the concatenation of `get_eqs(sys)` and
@@ -191,7 +191,7 @@ N = S + I + R
 @named ieqn = ODESystem([D(I) ~ β*S*I/N-γ*I])
 @named reqn = ODESystem([D(R) ~ γ*I])
 
-@named sir = ODESystem([   
+@named sir = compose(ODESystem([
                     S ~ ieqn.S,
                     I ~ seqn.I,
                     R ~ ieqn.R,
@@ -200,13 +200,12 @@ N = S + I + R
                     seqn.R ~ reqn.R,
                     ieqn.R ~ reqn.R,
                     reqn.I ~ ieqn.I], t, [S,I,R], [β,γ],
-                    systems=[seqn,ieqn,reqn],
-                    default_p = [
+                    defaults = [
                         seqn.β => β
                         ieqn.β => β
                         ieqn.γ => γ
                         reqn.γ => γ
-                    ])
+                    ]), seqn, ieqn, reqn)
 ```
 
 Note that the states are forwarded by an equality relationship, while
@@ -241,14 +240,6 @@ sol = solve(prob,Tsit5())
 sol[reqn.R]
 ```
 
-However, one can similarly simplify this process of inheritance by
-using `combine` which concatenates all of the vectors within the
-systems. For example, we could equivalently have done:
-
-```julia
-@named sir = combine([seqn,ieqn,reqn])
-```
-
 ## Tearing Problem Construction
 
 Some system types, specifically `ODESystem` and `NonlinearSystem`, can be further
@@ -259,12 +250,3 @@ strongly connected components calculated during the process of simplification
 as the basis for building pre-simplified nonlinear systems in the implicit
 solving. In summary: these problems are structurally modified, but could be
 more efficient and more stable.
-
-## Automatic Model Promotion (TODO)
-
-In many cases one might want to compose models of different types. For example,
-one may want to include a `NonlinearSystem` as a set of algebraic equations
-within an `ODESystem`, or one may want to use an `ODESystem` as a subsystem of
-an `SDESystem`. In these cases, the compostion works automatically by promoting
-the model via `promote_system`. System promotions exist in the cases where a
-mathematically-trivial definition of the promotion exists.

docs/src/tutorials/acausal_components.md

@@ -35,7 +35,7 @@ end
 function Ground(;name)
     @named g = Pin()
     eqs = [g.v ~ 0]
-    ODESystem(eqs, t, [], [], systems=[g]; name=name)
+    compose(ODESystem(eqs, t, [], []; name=name), g)
 end
 
 function OnePort(;name)
@@ -47,7 +47,7 @@ function OnePort(;name)
            0 ~ p.i + n.i
            i ~ p.i
           ]
-    ODESystem(eqs, t, sts, [], systems=[p, n]; name=name)
+    compose(ODESystem(eqs, t, sts, []; name=name), p, n)
 end
 
 function Resistor(;name, R = 1.0)
@@ -57,7 +57,7 @@ function Resistor(;name, R = 1.0)
     eqs = [
            v ~ i * R
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name), oneport)
 end
 
 function Capacitor(;name, C = 1.0)
@@ -68,7 +68,7 @@ function Capacitor(;name, C = 1.0)
     eqs = [
            D(v) ~ i / C
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name), oneport)
 end
 
 function ConstantVoltage(;name, V = 1.0)
@@ -78,7 +78,7 @@ function ConstantVoltage(;name, V = 1.0)
     eqs = [
            V ~ v
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name), oneport)
 end
 
 R = 1.0
@@ -153,7 +153,7 @@ that the voltage in such a `Pin` is equal to zero. This gives:
 function Ground(;name)
     @named g = Pin()
     eqs = [g.v ~ 0]
-    ODESystem(eqs, t, [], [], systems=[g]; name=name)
+    compose(ODESystem(eqs, t, [], []; name=name), g)
 end
 ```
 
@@ -173,7 +173,7 @@ function OnePort(;name)
            0 ~ p.i + n.i
            i ~ p.i
           ]
-    ODESystem(eqs, t, sts, [], systems=[p, n]; name=name)
+    compose(ODESystem(eqs, t, sts, []; name=name), p, n)
 end
 ```
 
@@ -192,7 +192,7 @@ function Resistor(;name, R = 1.0)
     eqs = [
            v ~ i * R
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name, oneport)
 end
 ```
 
@@ -216,7 +216,7 @@ function Capacitor(;name, C = 1.0)
     eqs = [
            D(v) ~ i / C
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name), oneport)
 end
 ```
 
@@ -233,7 +233,7 @@ function ConstantVoltage(;name, V = 1.0)
     eqs = [
            V ~ v
           ]
-    extend(oneport, ODESystem(eqs, t, [], ps; name=name); name=name)
+    extend(ODESystem(eqs, t, [], ps; name=name), oneport)
 end
 ```
 

docs/src/tutorials/ode_modeling.md

@@ -71,11 +71,11 @@ matches the name in the REPL. If omitted, you can directly set the `name` keywor
 After construction of the ODE, you can solve it using [DifferentialEquations.jl](https://diffeq.sciml.ai/):
 
 ```julia
-using DifferentialEquations: solve
-using Plots: plot
+using DifferentialEquations
+using Plots
 
 prob = ODEProblem(fol_model, [x => 0.0], (0.0,10.0), [τ => 3.0])
-solve(prob) |> plot
+plot(solve(prob))
 ```
 
 ![Simulation result of first-order lag element](https://user-images.githubusercontent.com/13935112/111958369-703f2200-8aed-11eb-8bb4-0abe9652e850.png)
@@ -211,7 +211,7 @@ again are just algebraic relations:
 connections = [ fol_1.f ~ 1.5,
                 fol_2.f ~ fol_1.x ]
 
-@named connected = ODESystem(connections; systems=[fol_1,fol_2])
+@named connected = compose(ODESystem(connections), fol_1, fol_2)
       # Model connected with 5 equations
       # States (5):
       #   fol_1₊f(t)
@@ -267,7 +267,7 @@ p = [ fol_1.τ => 2.0,
       fol_2.τ => 4.0 ]
 
 prob = ODEProblem(connected_simp, u0, (0.0,10.0), p)
-solve(prob) |> plot
+plot(solve(prob))
 ```
 
 ![Simulation of connected system (two first-order lag elements in series)](https://user-images.githubusercontent.com/13935112/111958439-877e0f80-8aed-11eb-9074-9d35458459a4.png)
@@ -308,9 +308,8 @@ still is the problem using the `connected_simp` system above):
 
 ```julia
 using BenchmarkTools
-using DifferentialEquations: Rodas4
 
-@btime solve(prob, Rodas4());
+@btime solve($prob, Rodas4());
       # 251.300 μs (873 allocations: 31.18 KiB)
 ```
 
@@ -320,7 +319,7 @@ be specified during the construction of the `ODEProblem`:
 ```julia
 prob_an = ODEProblem(connected_simp, u0, (0.0,10.0), p; jac=true, sparse=true)
 
-@btime solve(prob_an, Rodas4());
+@btime solve($prob_an, Rodas4());
       # 142.899 μs (1297 allocations: 83.96 KiB)
 ```
 

docs/src/tutorials/tearing_parallelism.md

@@ -39,88 +39,79 @@ end
 @parameters t
 const D = Differential(t)
 function Pin(;name)
-    @variables v(t) i(t)
-    ODESystem(Equation[], t, [v, i], [], name=name, defaults=Dict([v=>1.0, i=>1.0]))
+    @variables v(t)=1.0 i(t)=1.0
+    ODESystem(Equation[], t, [v, i], [], name=name)
 end
 
 function Ground(;name)
     @named g = Pin()
     eqs = [g.v ~ 0]
-    ODESystem(eqs, t, [], [], systems=[g], name=name)
+    compose(ODESystem(eqs, t, [], [], name=name), g)
 end
 
 function ConstantVoltage(;name, V = 1.0)
     val = V
     @named p = Pin()
     @named n = Pin()
-    @parameters V
+    @parameters V=V
     eqs = [
            V ~ p.v - n.v
            0 ~ p.i + n.i
           ]
-    ODESystem(eqs, t, [], [V], systems=[p, n], defaults=Dict(V => val), name=name)
+    compose(ODESystem(eqs, t, [], [V], name=name), p, n)
 end
 
 function HeatPort(;name)
-    @variables T(t) Q_flow(t)
-    return ODESystem(Equation[], t, [T, Q_flow], [], defaults=Dict(T=>293.15, Q_flow=>0.0), name=name)
+    @variables T(t)=293.15 Q_flow(t)=0.0
+    ODESystem(Equation[], t, [T, Q_flow], [], name=name)
 end
 
 function HeatingResistor(;name, R=1.0, TAmbient=293.15, alpha=1.0)
-    R_val, TAmbient_val, alpha_val = R, TAmbient, alpha
     @named p = Pin()
     @named n = Pin()
     @named h = HeatPort()
     @variables v(t) RTherm(t)
-    @parameters R TAmbient alpha
+    @parameters R=R TAmbient=TAmbient alpha=alpha
     eqs = [
            RTherm ~ R*(1 + alpha*(h.T - TAmbient))
            v ~ p.i * RTherm
            h.Q_flow ~ -v * p.i # -LossPower
            v ~ p.v - n.v
            0 ~ p.i + n.i
           ]
-    ODESystem(
-        eqs, t, [v, RTherm], [R, TAmbient, alpha], systems=[p, n, h],
-        defaults=Dict(
-            R=>R_val, TAmbient=>TAmbient_val, alpha=>alpha_val,
-            v=>0.0, RTherm=>R_val
-        ),
+    compose(ODESystem(
+        eqs, t, [v, RTherm], [R, TAmbient, alpha],
         name=name,
-    )
+    ), p, n, h)
 end
 
 function HeatCapacitor(;name, rho=8050, V=1, cp=460, TAmbient=293.15)
-    rho_val, V_val, cp_val = rho, V, cp
-    @parameters rho V cp
+    @parameters rho=rho V=V cp=cp
     C = rho*V*cp
     @named h = HeatPort()
     eqs = [
            D(h.T) ~ h.Q_flow / C
           ]
-    ODESystem(
-        eqs, t, [], [rho, V, cp], systems=[h],
-        defaults=Dict(rho=>rho_val, V=>V_val, cp=>cp_val),
+    compose(ODESystem(
+        eqs, t, [], [rho, V, cp],
         name=name,
-    )
+    ), h)
 end
 
 function Capacitor(;name, C = 1.0)
-    val = C
     @named p = Pin()
     @named n = Pin()
-    @variables v(t)
-    @parameters C
+    @variables v(t)=0.0
+    @parameters C=C
     eqs = [
            v ~ p.v - n.v
            0 ~ p.i + n.i
            D(v) ~ p.i / C
           ]
-    ODESystem(
-        eqs, t, [v], [C], systems=[p, n],
-        defaults=Dict(v => 0.0, C => val),
+    compose(ODESystem(
+        eqs, t, [v], [C],
         name=name
-    )
+    ), p, n)
 end
 
 function rc_model(i; name, source, ground, R, C)
@@ -154,12 +145,12 @@ Rs = 10 .^range(0, stop=-4, length=N)
 Cs = 10 .^range(-3, stop=0, length=N)
 rc_systems = map(1:N) do i
     rc_model(i; name=:rc, source=source, ground=ground, R=Rs[i], C=Cs[i])
-end
-@variables E(t)
+end;
+@variables E(t)=0.0
 eqs = [
        D(E) ~ sum(((i, sys),)->getproperty(sys, Symbol(:resistor, i)).h.Q_flow, enumerate(rc_systems))
       ]
-big_rc = ODESystem(eqs, t, [E], [], systems=rc_systems, defaults=Dict(E=>0.0))
+big_rc = compose([ODESystem(eqs, t, [E], []); rc_systems])
 ```
 
 Now let's say we want to expose a bit more parallelism via running tearing.

examples/electrical_components.jl

@@ -22,7 +22,7 @@ end
 function Ground(;name)
     @named g = Pin()
     eqs = [g.v ~ 0]
-    ODESystem(eqs, t, [], [], systems=[g]; name=name)
+    compose(ODESystem(eqs, t, [], []; name=name), g)
 end
 
 function OnePort(;name)
@@ -34,7 +34,7 @@ function OnePort(;name)
            0 ~ p.i + n.i
            i ~ p.i
           ]
-    ODESystem(eqs, t, sts, [], systems=[p, n]; name=name)
+    compose(ODESystem(eqs, t, sts, []; name=name), p, n)
 end
 
 function Resistor(;name, R = 1.0)

examples/rc_model.jl

@@ -14,4 +14,4 @@ rc_eqs = [
           connect(capacitor.n, source.n, ground.g)
          ]
 
-@named rc_model = ODESystem(rc_eqs, t, systems=[resistor, capacitor, source, ground])
+@named rc_model = compose(ODESystem(rc_eqs, t), resistor, capacitor, source, ground)

examples/serial_inductor.jl

@@ -13,4 +13,4 @@ eqs = [
        connect(source.n, inductor2.n, ground.g)
       ]
 
-@named ll_model = ODESystem(eqs, t, systems=[source, resistor, inductor1, inductor2, ground])
+@named ll_model = compose(ODESystem(eqs, t), source, resistor, inductor1, inductor2, ground)

src/ModelingToolkit.jl

@@ -190,6 +190,6 @@ export simplify, substitute
 export build_function
 export modelingtoolkitize
 export @variables, @parameters
-export @named, @nonamespace, @namespace, extend
+export @named, @nonamespace, @namespace, extend, compose
 
 end # module