Merge pull request #2460 from AayushSabharwal/as/doc-mtkbuild

docs: use `@mtkbuild` instead of manually calling `complete`

Author: ChrisRackauckas

docs/src/basics/Events.md

@@ -72,8 +72,8 @@ function UnitMassWithFriction(k; name)
         D(v) ~ sin(t) - k * sign(v)]
     ODESystem(eqs, t; continuous_events = [v ~ 0], name) # when v = 0 there is a discontinuity
 end
-@named m = UnitMassWithFriction(0.7)
-prob = ODEProblem(complete(m), Pair[], (0, 10pi))
+@mtkbuild m = UnitMassWithFriction(0.7)
+prob = ODEProblem(m, Pair[], (0, 10pi))
 sol = solve(prob, Tsit5())
 plot(sol)
 ```
@@ -93,11 +93,9 @@ D = Differential(t)
 root_eqs = [x ~ 0]  # the event happens at the ground x(t) = 0
 affect = [v ~ -v] # the effect is that the velocity changes sign
 
-@named ball = ODESystem([D(x) ~ v
+@mtkbuild ball = ODESystem([D(x) ~ v
         D(v) ~ -9.8], t; continuous_events = root_eqs => affect) # equation => affect
 
-ball = structural_simplify(ball)
-
 tspan = (0.0, 5.0)
 prob = ODEProblem(ball, Pair[], tspan)
 sol = solve(prob, Tsit5())
@@ -116,15 +114,13 @@ D = Differential(t)
 continuous_events = [[x ~ 0] => [vx ~ -vx]
     [y ~ -1.5, y ~ 1.5] => [vy ~ -vy]]
 
-@named ball = ODESystem([
+@mtkbuild ball = ODESystem([
         D(x) ~ vx,
         D(y) ~ vy,
         D(vx) ~ -9.8 - 0.1vx, # gravity + some small air resistance
         D(vy) ~ -0.1vy,
     ], t; continuous_events)
 
-ball = structural_simplify(ball)
-
 tspan = (0.0, 10.0)
 prob = ODEProblem(ball, Pair[], tspan)
 
@@ -197,10 +193,9 @@ end
 
 reflect = [x ~ 0] => (bb_affect!, [v], [], nothing)
 
-@named bb_model = ODESystem(bb_eqs, t, sts, par,
+@mtkbuild bb_sys = ODESystem(bb_eqs, t, sts, par,
     continuous_events = reflect)
 
-bb_sys = structural_simplify(bb_model)
 u0 = [v => 0.0, x => 1.0]
 
 bb_prob = ODEProblem(bb_sys, u0, (0, 5.0))
@@ -243,8 +238,8 @@ injection = (t == tinject) => [N ~ N + M]
 u0 = [N => 0.0]
 tspan = (0.0, 20.0)
 p = [α => 100.0, tinject => 10.0, M => 50]
-@named osys = ODESystem(eqs, t, [N], [α, M, tinject]; discrete_events = injection)
-oprob = ODEProblem(complete(osys), u0, tspan, p)
+@mtkbuild osys = ODESystem(eqs, t, [N], [α, M, tinject]; discrete_events = injection)
+oprob = ODEProblem(osys, u0, tspan, p)
 sol = solve(oprob, Tsit5(); tstops = 10.0)
 plot(sol)
 ```
@@ -262,7 +257,7 @@ to
 ```@example events
 injection = ((t == tinject) & (N < 50)) => [N ~ N + M]
 
-@named osys = ODESystem(eqs, t, [N], [M, tinject, α]; discrete_events = injection)
+@mtkbuild osys = ODESystem(eqs, t, [N], [M, tinject, α]; discrete_events = injection)
 oprob = ODEProblem(osys, u0, tspan, p)
 sol = solve(oprob, Tsit5(); tstops = 10.0)
 plot(sol)
@@ -287,7 +282,7 @@ killing = (t == tkill) => [α ~ 0.0]
 
 tspan = (0.0, 30.0)
 p = [α => 100.0, tinject => 10.0, M => 50, tkill => 20.0]
-@named osys = ODESystem(eqs, t, [N], [α, M, tinject, tkill];
+@mtkbuild osys = ODESystem(eqs, t, [N], [α, M, tinject, tkill];
     discrete_events = [injection, killing])
 oprob = ODEProblem(osys, u0, tspan, p)
 sol = solve(oprob, Tsit5(); tstops = [10.0, 20.0])
@@ -315,7 +310,7 @@ injection = [10.0] => [N ~ N + M]
 killing = [20.0] => [α ~ 0.0]
 
 p = [α => 100.0, M => 50]
-@named osys = ODESystem(eqs, t, [N], [α, M];
+@mtkbuild osys = ODESystem(eqs, t, [N], [α, M];
     discrete_events = [injection, killing])
 oprob = ODEProblem(osys, u0, tspan, p)
 sol = solve(oprob, Tsit5())

docs/src/basics/FAQ.md

@@ -141,7 +141,6 @@ using ModelingToolkit, StaticArrays
 sts = @variables x1(t)=0.0
 D = Differential(t)
 eqs = [D(x1) ~ 1.1 * x1]
-@named sys = ODESystem(eqs, t)
-sys = structural_simplify(sys)
+@mtkbuild sys = ODESystem(eqs, t)
 prob = ODEProblem{false}(sys, [], (0,1); u0_constructor = x->SVector(x...))
 ```

docs/src/examples/parsing.md

@@ -25,8 +25,8 @@ nonlinear solve:
 ```@example parsing
 using ModelingToolkit, NonlinearSolve
 vars = union(ModelingToolkit.vars.(eqs)...)
-@named ns = NonlinearSystem(eqs, vars, [])
+@mtkbuild ns = NonlinearSystem(eqs, vars, [])
 
-prob = NonlinearProblem(complete(ns), [1.0, 1.0, 1.0])
+prob = NonlinearProblem(ns, [1.0, 1.0, 1.0])
 sol = solve(prob, NewtonRaphson())
 ```

docs/src/examples/perturbation.md

@@ -92,8 +92,7 @@ We are nearly there! From this point on, the rest is standard ODE solving proced
 ```julia
 using ModelingToolkit, DifferentialEquations
 
-@named sys = ODESystem(eqs, t)
-sys = structural_simplify(sys)
+@mtkbuild sys = ODESystem(eqs, t)
 unknowns(sys)
 ```
 
@@ -158,8 +157,7 @@ eqs = [substitute(first(v), subs) ~ substitute(last(v), subs) for v in vals]
 We continue with converting 'eqs' to an `ODEProblem`, solving it, and finally plot the results against the exact solution to the original problem, which is $x(t, \epsilon) = (1 - \epsilon)^{-1/2} e^{-\epsilon t} \sin((1- \epsilon^2)^{1/2}t)$,
 
 ```julia
-@named sys = ODESystem(eqs, t)
-sys = structural_simplify(sys)
+@mtkbuild sys = ODESystem(eqs, t)
 ```
 
 ```julia

docs/src/examples/sparse_jacobians.md

@@ -54,8 +54,7 @@ prob = ODEProblem(brusselator_2d_loop, u0, (0.0, 11.5), p)
 Now let's use `modelingtoolkitize` to generate the symbolic version:
 
 ```@example sparsejac
-sys = modelingtoolkitize(prob);
-sys = complete(sys);
+@mtkbuild sys = modelingtoolkitize(prob);
 nothing # hide
 ```
 

docs/src/tutorials/bifurcation_diagram_computation.md

@@ -12,8 +12,7 @@ using ModelingToolkit
 @parameters μ α
 eqs = [0 ~ μ * x - x^3 + α * y,
     0 ~ -y]
-@named nsys = NonlinearSystem(eqs, [x, y], [μ, α])
-nsys = complete(nsys)
+@mtkbuild nsys = NonlinearSystem(eqs, [x, y], [μ, α])
 ```
 
 we wish to compute a bifurcation diagram for this system as we vary the parameter `μ`. For this, we need to provide the following information:
@@ -94,8 +93,7 @@ using BifurcationKit, ModelingToolkit, Plots
 D = Differential(t)
 eqs = [D(x) ~ μ * x - y - x * (x^2 + y^2),
     D(y) ~ x + μ * y - y * (x^2 + y^2)]
-@named osys = ODESystem(eqs, t)
-osys = complete(osys)
+@mtkbuild osys = ODESystem(eqs, t)
 
 bif_par = μ
 plot_var = x

docs/src/tutorials/domain_connections.md

@@ -135,7 +135,7 @@ To see how the domain works, we can examine the set parameter values for each of
 
 ```@repl domain
 sys = structural_simplify(odesys)
-ModelingToolkit.defaults(sys)[complete(odesys).vol.port.ρ]
+ModelingToolkit.defaults(sys)[odesys.vol.port.ρ]
 ```
 
 ## Multiple Domain Networks
@@ -280,8 +280,7 @@ Adding the `Restrictor` to the original system example will cause a break in the
     ODESystem(eqs, t, [], []; systems, name)
 end
 
-@named ressys = RestrictorSystem()
-sys = structural_simplify(ressys)
+@mtkbuild ressys = RestrictorSystem()
 nothing #hide
 ```
 
@@ -296,9 +295,9 @@ nothing #hide
 When `structural_simplify()` is applied to this system it can be seen that the defaults are missing for `res.port_b` and `vol.port`.
 
 ```@repl domain
-ModelingToolkit.defaults(sys)[complete(ressys).res.port_a.ρ]
-ModelingToolkit.defaults(sys)[complete(ressys).res.port_b.ρ]
-ModelingToolkit.defaults(sys)[complete(ressys).vol.port.ρ]
+ModelingToolkit.defaults(ressys)[ressys.res.port_a.ρ]
+ModelingToolkit.defaults(ressys)[ressys.res.port_b.ρ]
+ModelingToolkit.defaults(ressys)[ressys.vol.port.ρ]
 ```
 
 To ensure that the `Restrictor` component does not disrupt the domain network, the [`domain_connect()`](@ref) function can be used, which explicitly only connects the domain network and not the unknown variables.
@@ -322,15 +321,14 @@ To ensure that the `Restrictor` component does not disrupt the domain network, t
     ODESystem(eqs, t, [], pars; systems, name)
 end
 
-@named ressys = RestrictorSystem()
-sys = structural_simplify(ressys)
+@mtkbuild ressys = RestrictorSystem()
 nothing #hide
 ```
 
 Now that the `Restrictor` component is properly defined using `domain_connect()`, the defaults for `res.port_b` and `vol.port` are properly defined.
 
 ```@repl domain
-ModelingToolkit.defaults(sys)[complete(ressys).res.port_a.ρ]
-ModelingToolkit.defaults(sys)[complete(ressys).res.port_b.ρ]
-ModelingToolkit.defaults(sys)[complete(ressys).vol.port.ρ]
+ModelingToolkit.defaults(ressys)[ressys.res.port_a.ρ]
+ModelingToolkit.defaults(ressys)[ressys.res.port_b.ρ]
+ModelingToolkit.defaults(ressys)[ressys.vol.port.ρ]
 ```

docs/src/tutorials/modelingtoolkitize.md

@@ -52,11 +52,11 @@ If we want to get a symbolic representation, we can simply call `modelingtoolkit
 on the `prob`, which will return an `ODESystem`:
 
 ```@example mtkize
-sys = modelingtoolkitize(prob)
+@mtkbuild sys = modelingtoolkitize(prob)
 ```
 
 Using this, we can symbolically build the Jacobian and then rebuild the ODEProblem:
 
 ```@example mtkize
-prob_jac = ODEProblem(complete(sys), [], (0.0, 1e5), jac = true)
+prob_jac = ODEProblem(sys, [], (0.0, 1e5), jac = true)
 ```

docs/src/tutorials/nonlinear.md

@@ -16,8 +16,7 @@ using ModelingToolkit, NonlinearSolve
 eqs = [0 ~ σ * (y - x),
     0 ~ x * (ρ - z) - y,
     0 ~ x * y - β * z]
-@named ns = NonlinearSystem(eqs, [x, y, z], [σ, ρ, β])
-ns = complete(ns)
+@mtkbuild ns = NonlinearSystem(eqs, [x, y, z], [σ, ρ, β])
 
 guess = [x => 1.0,
     y => 0.0,

docs/src/tutorials/optimization.md

@@ -19,7 +19,7 @@ Now we can define our optimization problem.
 end
 @parameters a=1 b=1
 loss = (a - x)^2 + b * (y - x^2)^2
-@named sys = OptimizationSystem(loss, [x, y], [a, b])
+@mtkbuild sys = OptimizationSystem(loss, [x, y], [a, b])
 ```
 
 A visualization of the objective function is depicted below.
@@ -50,7 +50,7 @@ u0 = [x => 1.0
 p = [a => 1.0
     b => 100.0]
 
-prob = OptimizationProblem(complete(sys), u0, p, grad = true, hess = true)
+prob = OptimizationProblem(sys, u0, p, grad = true, hess = true)
 solve(prob, GradientDescent())
 ```
 
@@ -68,10 +68,10 @@ loss = (a - x)^2 + b * (y - x^2)^2
 cons = [
     x^2 + y^2 ≲ 1,
 ]
-@named sys = OptimizationSystem(loss, [x, y], [a, b], constraints = cons)
+@mtkbuild sys = OptimizationSystem(loss, [x, y], [a, b], constraints = cons)
 u0 = [x => 0.14
     y => 0.14]
-prob = OptimizationProblem(complete(sys),
+prob = OptimizationProblem(sys,
     u0,
     grad = true,
     hess = true,