Merge pull request #3987 from TorkelE/update_README

Update README

Author: ChrisRackauckas

README.md

@@ -11,7 +11,7 @@
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 ModelingToolkit.jl is a modeling framework for high-performance symbolic-numeric computation
-in scientific computing  and scientific machine learning.
+in scientific computing and scientific machine learning.
 It allows for users to give a high-level description of a model for
 symbolic preprocessing to analyze and enhance the model. ModelingToolkit can
 automatically generate fast functions for model components like Jacobians
@@ -36,88 +36,95 @@ lower it to a first order system, symbolically generate the Jacobian function
 for the numerical integrator, and solve it.
 
 ```julia
-using OrdinaryDiffEqDefault, ModelingToolkit
+using ModelingToolkit
 using ModelingToolkit: t_nounits as t, D_nounits as D
 
+# Defines a ModelingToolkit `System` model.
 @parameters σ ρ β
 @variables x(t) y(t) z(t)
-
-eqs = [D(D(x)) ~ σ * (y - x),
+eqs = [
+    D(D(x)) ~ σ * (y - x),
     D(y) ~ x * (ρ - z) - y,
-    D(z) ~ x * y - β * z]
-
+    D(z) ~ x * y - β * z
+]
 @mtkcompile sys = System(eqs, t)
 
-u0 = [D(x) => 2.0,
+# Simulate the model for a specific condition (initial condition and parameter values).
+using OrdinaryDiffEqDefault
+sim_cond = [
+    D(x) => 2.0,
     x => 1.0,
     y => 0.0,
-    z => 0.0]
-
-p = [σ => 28.0,
+    z => 0.0,
+    σ => 28.0,
     ρ => 10.0,
-    β => 8 / 3]
-
-tspan = (0.0, 100.0)
-prob = ODEProblem(sys, u0, tspan, p, jac = true)
+    β => 8 / 3
+]
+tend = 100.0
+prob = ODEProblem(sys, sim_cond, tend; jac = true)
 sol = solve(prob)
+
+# Plot the solution in phase-space.
 using Plots
 plot(sol, idxs = (x, y))
 ```
 
-![Lorenz2](https://user-images.githubusercontent.com/1814174/79118645-744eb580-7d5c-11ea-9c37-13c4efd585ca.png)
+![Lorenz2](https://github.com/user-attachments/assets/e82fb2ce-97b7-4f56-b272-85653c88bdb3)
 
-This automatically will have generated fast Jacobian functions, making
+This will have automatically generated fast Jacobian functions, making
 it more optimized than directly building a function. In addition, we can then
 use ModelingToolkit to compose multiple ODE subsystems. Now, let's define two
 interacting Lorenz equations and simulate the resulting Differential-Algebraic
 Equation (DAE):
 
 ```julia
-using DifferentialEquations, ModelingToolkit
+using ModelingToolkit
 using ModelingToolkit: t_nounits as t, D_nounits as D
 
-@parameters σ ρ β
-@variables x(t) y(t) z(t)
-
-eqs = [D(x) ~ σ * (y - x),
+# Defines two lorenz system models.
+eqs = [
+    D(x) ~ σ * (y - x),
     D(y) ~ x * (ρ - z) - y,
-    D(z) ~ x * y - β * z]
-
+    D(z) ~ x * y - β * z
+]
 @named lorenz1 = System(eqs, t)
 @named lorenz2 = System(eqs, t)
 
+# Connect the two models, creating a single model.
 @variables a(t)
 @parameters γ
 connections = [0 ~ lorenz1.x + lorenz2.y + a * γ]
-@mtkcompile connected = System(connections, t, systems = [lorenz1, lorenz2])
+@mtkcompile connected_lorenz = System(connections, t; systems = [lorenz1, lorenz2])
 
-u0 = [lorenz1.x => 1.0,
+# Simulate the model for a specific condition (initial condition and parameter values).
+using OrdinaryDiffEqDefault
+sim_cond = [
+    lorenz1.x => 1.0,
     lorenz1.y => 0.0,
     lorenz1.z => 0.0,
     lorenz2.x => 0.0,
-    lorenz2.y => 1.0,
     lorenz2.z => 0.0,
-    a => 2.0]
-
-p = [lorenz1.σ => 10.0,
+    a => 2.0,
+    lorenz1.σ => 10.0,
     lorenz1.ρ => 28.0,
     lorenz1.β => 8 / 3,
     lorenz2.σ => 10.0,
     lorenz2.ρ => 28.0,
     lorenz2.β => 8 / 3,
-    γ => 2.0]
-
-tspan = (0.0, 100.0)
-prob = ODEProblem(connected, u0, tspan, p)
+    γ => 2.0
+]
+tend = 100.0
+prob = ODEProblem(connected_lorenz, sim_cond, tend)
 sol = solve(prob)
 
+# Plot the solution in phase-space.
 using Plots
 plot(sol, idxs = (a, lorenz1.x, lorenz2.z))
 ```
 
-![](https://user-images.githubusercontent.com/17304743/187790221-528046c3-dbdb-4853-b977-799596c147f3.png)
+![LorenzConnected](https://github.com/user-attachments/assets/ef65d812-c10e-42c6-945d-e61515e3b6a1)
 
-# Citation
+## Citation
 
 If you use ModelingToolkit.jl in your research, please cite [this paper](https://arxiv.org/abs/2103.05244):