Skip to content

Commit 2fe7cd9

Browse files
committed
Merge remote-tracking branch 'origin/master' into add_odes_to_jumpsys
2 parents e4ed136 + f20fb5f commit 2fe7cd9

File tree

8 files changed

+556
-203
lines changed

8 files changed

+556
-203
lines changed

Project.toml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "ModelingToolkit"
22
uuid = "961ee093-0014-501f-94e3-6117800e7a78"
33
authors = ["Yingbo Ma <[email protected]>", "Chris Rackauckas <[email protected]> and contributors"]
4-
version = "9.49.0"
4+
version = "9.50.0"
55

66
[deps]
77
AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -131,7 +131,7 @@ SpecialFunctions = "0.7, 0.8, 0.9, 0.10, 1.0, 2"
131131
StaticArrays = "0.10, 0.11, 0.12, 1.0"
132132
SymbolicIndexingInterface = "0.3.31"
133133
SymbolicUtils = "3.7"
134-
Symbolics = "6.15.2"
134+
Symbolics = "6.15.4"
135135
URIs = "1"
136136
UnPack = "0.1, 1.0"
137137
Unitful = "1.1"

docs/src/examples/perturbation.md

Lines changed: 53 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,183 +1,104 @@
11
# [Symbolic-Numeric Perturbation Theory for ODEs](@id perturb_diff)
22

3-
## Prelims
3+
In the [Mixed Symbolic-Numeric Perturbation Theory tutorial](https://symbolics.juliasymbolics.org/stable/tutorials/perturbation/), we discussed how to solve algebraic equations using **Symbolics.jl**. Here we extend the method to differential equations. The procedure is similar, but the Taylor series coefficients now become functions of an independent variable (usually time).
44

5-
In the previous tutorial, [Mixed Symbolic-Numeric Perturbation Theory](https://symbolics.juliasymbolics.org/stable/examples/perturbation/), we discussed how to solve algebraic equations using **Symbolics.jl**. Here, our goal is to extend the method to differential equations. First, we import the following helper functions that were introduced in [Mixed Symbolic/Numerical Methods for Perturbation Theory - Algebraic Equations](https://symbolics.juliasymbolics.org/stable/examples/perturbation/):
5+
## Free fall in a varying gravitational field
66

7-
```@example perturbation
8-
using Symbolics
9-
10-
def_taylor(x, ps) = sum([a * x^(i - 1) for (i, a) in enumerate(ps)])
11-
12-
function collect_powers(eq, x, ns; max_power = 100)
13-
eq = substitute(expand(eq), Dict(x^j => 0 for j in (last(ns) + 1):max_power))
14-
15-
eqs = []
16-
for i in ns
17-
powers = Dict(x^j => (i == j ? 1 : 0) for j in 1:last(ns))
18-
e = substitute(eq, powers)
19-
20-
# manually remove zeroth order from higher orders
21-
if 0 in ns && i != 0
22-
e = e - eqs[1]
23-
end
24-
25-
push!(eqs, e)
26-
end
27-
eqs
28-
end
29-
30-
function solve_coef(eqs, ps)
31-
vals = Dict()
32-
33-
for i in 1:length(ps)
34-
eq = substitute(eqs[i], vals)
35-
vals[ps[i]] = Symbolics.symbolic_linear_solve(eq ~ 0, ps[i])
36-
end
37-
vals
38-
end
39-
```
40-
41-
## The Trajectory of a Ball!
42-
43-
In the first two examples, we applied the perturbation method to algebraic problems. However, the main power of the perturbation method is to solve differential equations (usually ODEs, but also occasionally PDEs). Surprisingly, the main procedure developed to solve algebraic problems works well for differential equations. In fact, we will use the same two helper functions, `collect_powers` and `solve_coef`. The main difference is in the way we expand the dependent variables. For algebraic problems, the coefficients of $\epsilon$ are constants; whereas, for differential equations, they are functions of the dependent variable (usually time).
44-
45-
As the first ODE example, we have chosen a simple and well-behaved problem, which is a variation of a standard first-year physics problem: what is the trajectory of an object (say, a ball, or a rocket) thrown vertically at velocity $v$ from the surface of a planet? Assuming a constant acceleration of gravity, $g$, every burgeoning physicist knows the answer: $x(t) = x(0) + vt - \frac{1}{2}gt^2$. However, what happens if $g$ is not constant? Specifically, $g$ is inversely proportional to the distant from the center of the planet. If $v$ is large and the projectile travels a large fraction of the radius of the planet, the assumption of constant gravity does not hold anymore. However, unless $v$ is large compared to the escape velocity, the correction is usually small. After simplifications and change of variables to dimensionless, the problem becomes
7+
Our first ODE example is a well-known physics problem: what is the altitude $x(t)$ of an object (say, a ball or a rocket) thrown vertically with initial velocity $ẋ(0)$ from the surface of a planet with mass $M$ and radius $R$? According to Newton's second law and law of gravity, it is the solution of the ODE
468

479
```math
48-
\ddot{x}(t) = -\frac{1}{(1 + \epsilon x(t))^2}
49-
```
50-
51-
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
52-
53-
```@example perturbation
54-
using ModelingToolkit: t_nounits as t, D_nounits as D
55-
order = 2
56-
n = order + 1
57-
@variables ϵ (y(t))[1:n] (∂∂y(t))[1:n]
10+
ẍ = -\frac{GM}{(R+x)^2} = -\frac{GM}{R^2} \frac{1}{\left(1+ϵ\frac{x}{R}\right)^2}.
5811
```
5912

60-
Next, we define $x$.
61-
62-
```@example perturbation
63-
x = def_taylor(ϵ, y)
64-
```
13+
In the last equality, we introduced a perturbative expansion parameter $ϵ$. When $ϵ=1$, we recover the original problem. When $ϵ=0$, the problem reduces to the trivial problem $ẍ = -g$ with constant gravitational acceleration $g = GM/R^2$ and solution $x(t) = x(0) + ẋ(0) t - \frac{1}{2} g t^2$. This is a good setup for perturbation theory.
6514

66-
We need the second derivative of `x`. It may seem that we can do this using `Differential(t)`; however, this operation needs to wait for a few steps because we need to manipulate the differentials as separate variables. Instead, we define dummy variables `∂∂y` as the placeholder for the second derivatives and define
15+
To make the problem dimensionless, we redefine $x \leftarrow x / R$ and $t \leftarrow t / \sqrt{R^3/GM}$. Then the ODE becomes
6716

6817
```@example perturbation
69-
∂∂x = def_taylor(ϵ, ∂∂y)
70-
```
71-
72-
as the second derivative of `x`. After rearrangement, our governing equation is $\ddot{x}(t)(1 + \epsilon x(t))^{-2} + 1 = 0$, or
73-
74-
```@example perturbation
75-
eq = ∂∂x * (1 + ϵ * x)^2 + 1
76-
```
77-
78-
The next two steps are the same as the ones for algebraic equations (note that we pass `1:n` to `collect_powers` because the zeroth order term is needed here)
79-
80-
```@example perturbation
81-
eqs = collect_powers(eq, ϵ, 0:order)
18+
using ModelingToolkit
19+
using ModelingToolkit: t_nounits as t, D_nounits as D
20+
@variables ϵ x(t)
21+
eq = D(D(x)) ~ -(1 + ϵ * x)^(-2)
8222
```
8323

84-
and,
24+
Next, expand $x(t)$ in a series up to second order in $ϵ$:
8525

8626
```@example perturbation
87-
vals = solve_coef(eqs, ∂∂y)
27+
using Symbolics
28+
@variables y(t)[0:2] # coefficients
29+
x_series = series(y, ϵ)
8830
```
8931

90-
Our system of ODEs is forming. Now is the time to convert `∂∂`s to the correct **Symbolics.jl** form by substitution:
32+
Insert this into the equation and collect perturbed equations to each order:
9133

9234
```@example perturbation
93-
subs = Dict(∂∂y[i] => D(D(y[i])) for i in eachindex(y))
94-
eqs = [substitute(first(v), subs) ~ substitute(last(v), subs) for v in vals]
35+
eq_pert = substitute(eq, x => x_series)
36+
eqs_pert = taylor_coeff(eq_pert, ϵ, 0:2)
9537
```
9638

97-
We are nearly there! From this point on, the rest is standard ODE solving procedures. Potentially, we can use a symbolic ODE solver to find a closed form solution to this problem. However, **Symbolics.jl** currently does not support this functionality. Instead, we solve the problem numerically. We form an `ODESystem`, lower the order (convert second derivatives to first), generate an `ODEProblem` (after passing the correct initial conditions), and, finally, solve it.
98-
99-
```@example perturbation
100-
using ModelingToolkit, DifferentialEquations
101-
102-
@mtkbuild sys = ODESystem(eqs, t)
103-
unknowns(sys)
104-
```
39+
!!! note
40+
41+
The 0-th order equation can be solved analytically, but ModelingToolkit does currently not feature automatic analytical solution of ODEs, so we proceed with solving it numerically.
42+
These are the ODEs we want to solve. Now construct an `ODESystem`, which automatically inserts dummy derivatives for the velocities:
10543

10644
```@example perturbation
107-
# the initial conditions
108-
# everything is zero except the initial velocity
109-
u0 = Dict([unknowns(sys) .=> 0; D(y[1]) => 1])
110-
111-
prob = ODEProblem(sys, u0, (0, 3.0))
112-
sol = solve(prob; dtmax = 0.01);
45+
@mtkbuild sys = ODESystem(eqs_pert, t)
11346
```
11447

115-
Finally, we calculate the solution to the problem as a function of `ϵ` by substituting the solution to the ODE system back into the defining equation for `x`. Note that `𝜀` is a number, compared to `ϵ`, which is a symbolic variable.
48+
To solve the `ODESystem`, we generate an `ODEProblem` with initial conditions $x(0) = 0$, and $ẋ(0) = 1$, and solve it:
11649

11750
```@example perturbation
118-
X = 𝜀 -> sum([𝜀^(i - 1) * sol[yi] for (i, yi) in enumerate(y)])
51+
using DifferentialEquations
52+
u0 = Dict([unknowns(sys) .=> 0.0; D(y[0]) => 1.0]) # nonzero initial velocity
53+
prob = ODEProblem(sys, u0, (0.0, 3.0))
54+
sol = solve(prob)
11955
```
12056

121-
Using `X`, we can plot the trajectory for a range of $𝜀$s.
57+
This is the solution for the coefficients in the series for $x(t)$ and their derivatives. Finally, we calculate the solution to the original problem by summing the series for different $ϵ$:
12258

12359
```@example perturbation
12460
using Plots
125-
126-
plot(sol.t, hcat([X(𝜀) for 𝜀 in 0.0:0.1:0.5]...))
61+
p = plot()
62+
for ϵᵢ in 0.0:0.1:1.0
63+
plot!(p, sol, idxs = substitute(x_series, ϵ => ϵᵢ), label = "ϵ = $ϵᵢ")
64+
end
65+
p
12766
```
12867

129-
As expected, as `𝜀` becomes larger (meaning the gravity is less with altitude), the object goes higher and stays up for a longer duration. Of course, we could have solved the problem directly using as ODE solver. One of the benefits of the perturbation method is that we need to run the ODE solver only once and then can just calculate the answer for different values of `𝜀`; whereas, if we had used the direct method, we would need to run the solver once for each value of `𝜀`.
68+
This makes sense: for larger $ϵ$, gravity weakens with altitude, and the trajectory goes higher for a fixed initial velocity.
13069

131-
## A Weakly Nonlinear Oscillator
70+
An advantage of the perturbative method is that we run the ODE solver only once and calculate trajectories for several $ϵ$ for free. Had we solved the full unperturbed ODE directly, we would need to do repeat it for every $ϵ$.
13271

133-
For the next example, we have chosen a simple example from a very important class of problems, the nonlinear oscillators. As we will see, perturbation theory has difficulty providing a good solution to this problem, but the process is instructive. This example closely follows the chapter 7.6 of *Nonlinear Dynamics and Chaos* by Steven Strogatz.
72+
## Weakly nonlinear oscillator
13473

135-
The goal is to solve $\ddot{x} + 2\epsilon\dot{x} + x = 0$, where the dot signifies time-derivatives and the initial conditions are $x(0) = 0$ and $\dot{x}(0) = 1$. If $\epsilon = 0$, the problem reduces to the simple linear harmonic oscillator with the exact solution $x(t) = \sin(t)$. We follow the same steps as the previous example.
136-
137-
```@example perturbation
138-
order = 2
139-
n = order + 1
140-
@variables ϵ (y(t))[1:n] (∂y)[1:n] (∂∂y)[1:n]
141-
x = def_taylor(ϵ, y)
142-
∂x = def_taylor(ϵ, ∂y)
143-
∂∂x = def_taylor(ϵ, ∂∂y)
144-
```
74+
Our second example applies perturbation theory to nonlinear oscillators -- a very important class of problems. As we will see, perturbation theory has difficulty providing a good solution to this problem, but the process is nevertheless instructive. This example closely follows chapter 7.6 of *Nonlinear Dynamics and Chaos* by Steven Strogatz.
14575

146-
This time we also need the first derivative terms. Continuing,
76+
The goal is to solve the ODE
14777

14878
```@example perturbation
149-
eq = ∂∂x + 2 * ϵ * ∂x + x
150-
eqs = collect_powers(eq, ϵ, 0:n)
151-
vals = solve_coef(eqs, ∂∂y)
79+
eq = D(D(x)) + 2 * ϵ * D(x) + x ~ 0
15280
```
15381

154-
Next, we need to replace ``s and `∂∂`s with their **Symbolics.jl** counterparts:
82+
with initial conditions $x(0) = 0$ and $ẋ(0) = 1$. With $ϵ = 0$, the problem reduces to the simple linear harmonic oscillator with the exact solution $x(t) = \sin(t)$.
15583

156-
```@example perturbation
157-
subs1 = Dict(∂y[i] => D(y[i]) for i in eachindex(y))
158-
subs2 = Dict(∂∂y[i] => D(D(y[i])) for i in eachindex(y))
159-
subs = subs1 ∪ subs2
160-
eqs = [substitute(first(v), subs) ~ substitute(last(v), subs) for v in vals]
161-
```
162-
163-
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)$,
84+
We follow the same steps as in the previous example to construct the `ODESystem`:
16485

16586
```@example perturbation
166-
@mtkbuild sys = ODESystem(eqs, t)
87+
eq_pert = substitute(eq, x => x_series)
88+
eqs_pert = taylor_coeff(eq_pert, ϵ, 0:2)
89+
@mtkbuild sys = ODESystem(eqs_pert, t)
16790
```
16891

169-
```@example perturbation
170-
# the initial conditions
171-
u0 = Dict([unknowns(sys) .=> 0; D(y[1]) => 1])
172-
173-
prob = ODEProblem(sys, u0, (0, 50.0))
174-
sol = solve(prob; dtmax = 0.01)
92+
We solve and plot it as in the previous example, and compare the solution with $ϵ=0.1$ to the exact solution $x(t, ϵ) = e^{-ϵ t} \sin(\sqrt{(1-ϵ^2)}\,t) / \sqrt{1-ϵ^2}$ of the unperturbed equation:
17593

176-
X = 𝜀 -> sum([𝜀^(i - 1) * sol[yi] for (i, yi) in enumerate(y)])
177-
T = sol.t
178-
Y = 𝜀 -> exp.(-𝜀 * T) .* sin.(sqrt(1 - 𝜀^2) * T) / sqrt(1 - 𝜀^2) # exact solution
94+
```@example perturbation
95+
u0 = Dict([unknowns(sys) .=> 0.0; D(y[0]) => 1.0]) # nonzero initial velocity
96+
prob = ODEProblem(sys, u0, (0.0, 50.0))
97+
sol = solve(prob)
98+
plot(sol, idxs = substitute(x_series, ϵ => 0.1); label = "Perturbative (ϵ=0.1)")
17999
180-
plot(sol.t, [Y(0.1), X(0.1)])
100+
x_exact(t, ϵ) = exp(-ϵ * t) * sin(√(1 - ϵ^2) * t) / √(1 - ϵ^2)
101+
plot!(sol.t, x_exact.(sol.t, 0.1); label = "Exact (ϵ=0.1)")
181102
```
182103

183-
The figure is similar to Figure 7.6.2 in *Nonlinear Dynamics and Chaos*. The two curves fit well for the first couple of cycles, but then the perturbation method curve diverges from the true solution. The main reason is that the problem has two or more time-scales that introduce secular terms in the solution. One solution is to explicitly account for the two time scales and use an analytic method called *two-timing*.
104+
This is similar to Figure 7.6.2 in *Nonlinear Dynamics and Chaos*. The two curves fit well for the first couple of cycles, but then the perturbative solution diverges from the exact solution. The main reason is that the problem has two or more time-scales that introduce secular terms in the solution. One solution is to explicitly account for the two time scales and use an analytic method called *two-timing*, but this is outside the scope of this example.

src/systems/abstractsystem.jl

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -984,6 +984,8 @@ function complete(sys::AbstractSystem; split = true, flatten = true)
984984
end
985985
@set! sys.ps = ordered_ps
986986
end
987+
elseif has_index_cache(sys)
988+
@set! sys.index_cache = nothing
987989
end
988990
if isdefined(sys, :initializesystem) && get_initializesystem(sys) !== nothing
989991
@set! sys.initializesystem = complete(get_initializesystem(sys); split)
@@ -1907,15 +1909,16 @@ function Base.show(
19071909

19081910
# Print name and description
19091911
desc = description(sys)
1910-
printstyled(io, "Model ", nameof(sys), ":"; bold)
1912+
name = nameof(sys)
1913+
printstyled(io, "Model ", name, ":"; bold)
19111914
!isempty(desc) && print(io, " ", desc)
19121915

19131916
# Print subsystems
19141917
subs = get_systems(sys)
19151918
nsubs = length(subs)
19161919
nrows = min(nsubs, limit ? rows : nsubs)
19171920
nrows > 0 && printstyled(io, "\nSubsystems ($(nsubs)):"; bold)
1918-
nrows > 0 && hint && print(io, " see hierarchy(sys)")
1921+
nrows > 0 && hint && print(io, " see hierarchy($name)")
19191922
for i in 1:nrows
19201923
sub = subs[i]
19211924
name = String(nameof(sub))
@@ -1939,9 +1942,9 @@ function Base.show(
19391942
next = n_expanded_connection_equations(sys)
19401943
ntot = neqs + next
19411944
ntot > 0 && printstyled(io, "\nEquations ($ntot):"; bold)
1942-
neqs > 0 && print(io, "\n $neqs standard", hint ? ": see equations(sys)" : "")
1945+
neqs > 0 && print(io, "\n $neqs standard", hint ? ": see equations($name)" : "")
19431946
next > 0 && print(io, "\n $next connecting",
1944-
hint ? ": see equations(expand_connections(sys))" : "")
1947+
hint ? ": see equations(expand_connections($name))" : "")
19451948
#Base.print_matrix(io, eqs) # usually too long and not useful to print all equations
19461949
end
19471950

@@ -1952,7 +1955,7 @@ function Base.show(
19521955
nvars == 0 && continue # skip
19531956
header = titlecase(String(nameof(varfunc))) # e.g. "Unknowns"
19541957
printstyled(io, "\n$header ($nvars):"; bold)
1955-
hint && print(io, " see $(nameof(varfunc))(sys)")
1958+
hint && print(io, " see $(nameof(varfunc))($name)")
19561959
nrows = min(nvars, limit ? rows : nvars)
19571960
defs = has_defaults(sys) ? defaults(sys) : nothing
19581961
for i in 1:nrows
@@ -1981,7 +1984,7 @@ function Base.show(
19811984
# Print observed
19821985
nobs = has_observed(sys) ? length(observed(sys)) : 0
19831986
nobs > 0 && printstyled(io, "\nObserved ($nobs):"; bold)
1984-
nobs > 0 && hint && print(io, " see observed(sys)")
1987+
nobs > 0 && hint && print(io, " see observed($name)")
19851988

19861989
return nothing
19871990
end
@@ -2994,12 +2997,13 @@ end
29942997
"""
29952998
$(TYPEDSIGNATURES)
29962999
2997-
Extend the `basesys` with `sys`, the resulting system would inherit `sys`'s name
2998-
by default.
3000+
Extend `basesys` with `sys`.
3001+
By default, the resulting system inherits `sys`'s name and description.
29993002
30003003
See also [`compose`](@ref).
30013004
"""
3002-
function extend(sys::AbstractSystem, basesys::AbstractSystem; name::Symbol = nameof(sys),
3005+
function extend(sys::AbstractSystem, basesys::AbstractSystem;
3006+
name::Symbol = nameof(sys), description = description(sys),
30033007
gui_metadata = get_gui_metadata(sys))
30043008
T = SciMLBase.parameterless_type(basesys)
30053009
ivs = independent_variables(basesys)
@@ -3022,13 +3026,12 @@ function extend(sys::AbstractSystem, basesys::AbstractSystem; name::Symbol = nam
30223026
cevs = union(get_continuous_events(basesys), get_continuous_events(sys))
30233027
devs = union(get_discrete_events(basesys), get_discrete_events(sys))
30243028
defs = merge(get_defaults(basesys), get_defaults(sys)) # prefer `sys`
3025-
desc = join(filter(desc -> !isempty(desc), description.([sys, basesys])), " ") # concatenate non-empty descriptions with space
30263029
meta = union_nothing(get_metadata(basesys), get_metadata(sys))
30273030
syss = union(get_systems(basesys), get_systems(sys))
30283031
args = length(ivs) == 0 ? (eqs, sts, ps) : (eqs, ivs[1], sts, ps)
30293032
kwargs = (parameter_dependencies = dep_ps, observed = obs, continuous_events = cevs,
30303033
discrete_events = devs, defaults = defs, systems = syss, metadata = meta,
3031-
name = name, description = desc, gui_metadata = gui_metadata)
3034+
name = name, description = description, gui_metadata = gui_metadata)
30323035

30333036
# collect fields specific to some system types
30343037
if basesys isa ODESystem
@@ -3040,8 +3043,8 @@ function extend(sys::AbstractSystem, basesys::AbstractSystem; name::Symbol = nam
30403043
return T(args...; kwargs...)
30413044
end
30423045

3043-
function Base.:(&)(sys::AbstractSystem, basesys::AbstractSystem; name::Symbol = nameof(sys))
3044-
extend(sys, basesys; name = name)
3046+
function Base.:(&)(sys::AbstractSystem, basesys::AbstractSystem; kwargs...)
3047+
extend(sys, basesys; kwargs...)
30453048
end
30463049

30473050
"""

0 commit comments

Comments
 (0)