Merge pull request #1729 from isaacsas/event_tutorial

Event basics

Author: ChrisRackauckas

docs/make.jl

@@ -14,9 +14,10 @@ makedocs(sitename = "ModelingToolkit.jl",
              # Other available options are
              # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
          ],
-         format = Documenter.HTML(analytics = "UA-90474609-3",
+         format = Documenter.HTML(; analytics = "UA-90474609-3",
                                   assets = ["assets/favicon.ico"],
-                                  canonical = "https://mtk.sciml.ai/stable/"),
+                                  canonical = "https://mtk.sciml.ai/stable/",
+                                  prettyurls = (get(ENV, "CI", nothing) == "true")),
          pages = pages)
 
 deploydocs(repo = "github.com/SciML/ModelingToolkit.jl.git";

docs/pages.jl

@@ -16,6 +16,7 @@ pages = [
                     "basics/ContextualVariables.md",
                     "basics/Variable_metadata.md",
                     "basics/Composition.md",
+                    "basics/Events.md",
                     "basics/Validation.md",
                     "basics/DependencyGraphs.md",
                     "basics/FAQ.md"],

docs/src/basics/Composition.md

@@ -248,173 +248,11 @@ solving. In summary: these problems are structurally modified, but could be
 more efficient and more stable.
 
 ## Components with discontinuous dynamics
-When modeling, e.g., impacts, saturations or Coulomb friction, the dynamic equations are discontinuous in either the state or one of its derivatives. This causes the solver to take very small steps around the discontinuity, and sometimes leads to early stopping due to `dt <= dt_min`. The correct way to handle such dynamics is to tell the solver about the discontinuity by means of a root-finding equation. [`ODEsystem`](@ref)s accept a keyword argument `continuous_events`
-```
-ODESystem(eqs, ...; continuous_events::Vector{Equation})
-ODESystem(eqs, ...; continuous_events::Pair{Vector{Equation}, Vector{Equation}})
-```
-where equations can be added that evaluate to 0 at discontinuities.
-
-To model events that have an effect on the state, provide `events::Pair{Vector{Equation}, Vector{Equation}}` where the first entry in the pair is a vector of equations describing event conditions, and the second vector of equations describe the effect on the state. The effect equations must be of the form
-```
-single_state_variable ~ expression_involving_any_variables
-```
-
-### Example: Friction
-The system below illustrates how this can be used to model Coulomb friction
-```@example events
-using ModelingToolkit, OrdinaryDiffEq, Plots
-function UnitMassWithFriction(k; name)
-  @variables t x(t)=0 v(t)=0
-  D = Differential(t)
-  eqs = [
-    D(x) ~ v
-    D(v) ~ sin(t) - k*sign(v) # f = ma, sinusoidal force acting on the mass, and Coulomb friction opposing the movement
-  ]
-  ODESystem(eqs, t; continuous_events=[v ~ 0], name) # when v = 0 there is a discontinuity
-end
-@named m = UnitMassWithFriction(0.7)
-prob = ODEProblem(m, Pair[], (0, 10pi))
-sol = solve(prob, Tsit5())
-plot(sol)
-```
-
-### Example: Bouncing ball
-In the documentation for DifferentialEquations, we have an example where a bouncing ball is simulated using callbacks which has 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)
-
-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
-    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())
-@assert 0 <= minimum(sol[x]) <= 1e-10 # the ball never went through the floor but got very close
-plot(sol)
-```
-
-### Test bouncing ball in 2D with walls
-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)
-
-continuous_events = [ # This time we have a vector of pairs
-    [x ~ 0] => [vx ~ -vx]
-    [y ~ -1.5, y ~ 1.5] => [vy ~ -vy]
-]
-
-@named 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)
-
-sol = solve(prob,Tsit5())
-@assert 0 <= minimum(sol[x]) <= 1e-10 # the ball never went through the floor but got very close
-@assert minimum(sol[y]) > -1.5 # check wall conditions
-@assert maximum(sol[y]) < 1.5  # check wall conditions
-
-tv = sort([LinRange(0, 10, 200); sol.t])
-plot(sol(tv)[y], sol(tv)[x], line_z=tv)
-vline!([-1.5, 1.5], l=(:black, 5), primary=false)
-hline!([0], l=(:black, 5), primary=false)
-```
-
-### Generalized affect support
-In some instances, a more flexible response to events is needed, which cannot be encapsulated by
-an equation. For example, a component may implement complex behavior that it is inconvenient or
-impossible to capture in equations.
-
-ModelingToolkit therefore supports Julia functions as affects: instead of an equation, an affect is
-defined as a `tuple`:
-```
-[x ~ 0] => (affect!, [v, x], [p, q], ctx)
-```
-
-where, `affect!` is a Julia function with the signature: `affect!(integ, u, p, ctx)`; `[u,v]` and `[p,q]` 
-are the states (variables) and parameters that are accessed by `affect!`, respectively; and `ctx` is a 
-context that is passed to `affect!` as the `ctx` argument.
-
-`affect!` receives the `DiffEqs` integrator as its first argument, which can then be used to access states
-and parameters that are provided in the `u` and `p` arguments (implemented as `NamedTuple`s):
-
-```
-function affect!(integ, u, v, ctx)
-    # integ.t is the current time
-    # integ.u[u.v] is the value of the state `v` above
-    # integ.p[p.q] is the value of the parameter `q` above
-end
-```
-
-When accessing variables of a sub-system, it could be useful to rename them (alternatively, an affect function
-may be reused in different contexts):
-```
-[x ~ 0] => (affect!, [resistor₊v => :v, x], [p, q => :p2], ctx)
-```
-
-Here, `resistor₊v` is passed as `v` while `q` has been renamed `p2`.
-
-As an example, here is the bouncing ball example from `DiffEqs` using ModelingToolkit:
-
-```@example events
-sts = @variables y(t), v(t)
-par = @parameters g = 9.8
-bb_eqs = [D(y) ~ v
-          D(v) ~ -g]
-
-function bb_affect!(integ, u, p, ctx)
-    integ.u[u.v] = -integ.u[u.v]
-end
-
-@named bb_model = ODESystem(bb_eqs, t, sts, par,
-                            continuous_events = [[y ~ 0] => (bb_affect!, [v], [], nothing)])
-
-bb_sys = structural_simplify(bb_model)
-u0 = [v => 0.0, y => 50.0]
-
-bb_prob = ODEProblem(bb_sys, u0, (0, 15.0))
-bb_sol = solve(bb_prob, Tsit5())
-
-plot(bb_sol)
-```
-
-### Discrete events support
-In addition to continuous events, discrete events are also supported.
-
-TBD
-
-Two important sub-classes of discrete events are periodic and set-time events. A periodic event is triggered at
-fixed intervals (e.g. every Δt seconds). To specify a periodic interval, pass the interval as the condition for
-the event:
-
-```
-discrete_events=[1.0 => [v ~ -v]]
-```
-
-will change the sign of `v` at t=1.0, 2.0, ...
-
-Alternatively, the event may be triggered at specific set times:
-```
-discrete_events=[[1.0, 4.0] => [v ~ -v]]
-```
-
-will change the sign of `v` *only* at t=1.0, 4.0.
-
+When modeling, e.g., impacts, saturations or Coulomb friction, the dynamic
+equations are discontinuous in either the state or one of its derivatives. This
+causes the solver to take very small steps around the discontinuity, and
+sometimes leads to early stopping due to `dt <= dt_min`. The correct way to
+handle such dynamics is to tell the solver about the discontinuity by means of a
+root-finding equation, which can be modeling using [`ODESystem`](@ref)'s event
+support. Please see the tutorial on [Callbacks and Events](@ref events) for
+details and examples.