Integrators

integrator(ds::DynamicalSystem [, u0]; diffeq) -> integ

Return an integrator object that can be used to evolve a system interactively using step!(integ [, Δt]). Optionally specify an initial state u0.

The state of this integrator is a vector.

• diffeq is a NamedTuple (or Dict) of keyword arguments propagated into init of DifferentialEquations.jl. See trajectory for examples. Only valid for continuous systems.

parallel_integrator(ds::DynamicalSystem, states; kwargs...)

Return an integrator object that can be used to evolve many states of a system in parallel at the exact same times, using step!(integ [, Δt]).

states are expected as vectors of vectors.

Keyword Arguments

• diffeq is a NamedTuple (or Dict) of keyword arguments propagated into init of DifferentialEquations.jl. See trajectory for examples. Only valid for continuous systems.

It is heavily advised to use the functions get_state and set_state! to manipulate the integrator. Provide i as a second argument to change the i-th state.

tangent_integrator(ds::DynamicalSystem, Q0 | k::Int; kwargs...)

Return an integrator object that evolves in parallel both the system as well as deviation vectors living on the tangent space, also called linearized space.

Q0 is a matrix whose columns are initial values for deviation vectors. If instead of a matrix Q0 an integer k is given, then k random orthonormal vectors are choosen as initial conditions.

It is heavily advised to use the functions get_state, get_deviations, set_state!, set_deviations! to manipulate the integrator.

Keyword Arguments

• u0 : Optional different initial state.
• diffeq is a NamedTuple (or Dict) of keyword arguments propagated into init of DifferentialEquations.jl. See trajectory for examples. Only valid for continuous systems.

Description

If $J$ is the jacobian of the system then the tangent dynamics are the equations that evolve in parallel the system as well as a deviation vector (or matrix) $w$:

\[\begin{aligned} \dot{u} &= f(u, p, t) \\ \dot{w} &= J(u, p, t) \times w \end{aligned}\]

with $f$ being the equations of motion and $u$ the system state. Similar equations hold for the discrete case.

projected_integrator(ds::DynamicalSystem, projection, complete_state; kwargs...) → integ

Return an integrator that produces iterations of the dynamical system ds on a projected state space. See Integrator API for handling integrators.

The projection defines the projected space. If projection isa AbstractVector{Int}, then the projected space is simply the variable indices that projection contains. Otherwise, projection can be an arbitrary function that given the state of the original system, returns the state in the projected space. In this case the projected space can be equal, or even higher-dimensional than the original.

complete_state produces the state for the original system from the projected state. complete_state can always be a function that given the projected state returns the full state. However, if projection isa AbstractVector{Int}, then complete_state can also be a vector that contains the values of the remaining variables of the system, i.e., those not contained in the projected space. Obviously in this case the projected space needs to be lower-dimensional than the original.

Notice that projected_integrator does not require an invertible projection, complete_state is only used during reinit!. Of course the internal integrator operates in the full state space, where the dynamic rule has been defined. The projection always happens as a last step, e.g., during get_state.

Keyword Arguments

• u0: initial state
• diffeq is a NamedTuple (or Dict) of keyword arguments propagated into init of DifferentialEquations.jl.

Examples

Case 1: project 5-dimensional system to its last two dimensions.

ds = Systems.lorenz96(5)
projection = [4, 5]
complete_state = [0.0, 0.0, 0.0] # completed state just in the plane of last two dimensions
pinteg = projected_integrator(ds, projection, complete_state)
reinit!(pinteg, [0.2, 0.4])
step!(pinteg)
get_state(pinteg)

Case 2: custom projection to general functions of state. julia ds = Systems.lorenz96(5) projection(u) = [sum(u), sqrt(u[1]^2 + u[2]^2)] complete_state(y) = repeat(y[1]/5, 5) pinteg = # same as in above example...`

stroboscopicmap(ds::ContinuousDynamicalSystem, T; kwargs...)  → smap

Return a map (integrator) that produces iterations over a period T of the ds, known as a stroboscopic map. See Integrator API for handling integrators.

See also poincaremap.

Keyword Arguments

• u0: initial state
• diffeq is a NamedTuple (or Dict) of keyword arguments propagated into init of DifferentialEquations.jl.

Example

f = 0.27; ω = 0.1
ds = Systems.duffing(zeros(2); ω, f, d = 0.15, β = -1)
smap = stroboscopicmap(ds, 2π/ω; diffeq = (;reltol = 1e-8))
reinit!(smap, [1.0, 1.0])
u = step!(smap)
u = step!(smap, 4) # step 4 iterations forward

poincaremap(ds::ContinuousDynamicalSystem, plane, Tmax=1e3; kwargs...) → pmap

Return a map (integrator) that produces iterations over the Poincaré map of ds. This map is defined as the sequence of points on the Poincaré surface of section. See poincaresos for details on plane and all other kwargs. Keyword idxs does not apply to poincaremap, as it doesn't save any states.

Notice that while in theory the Poincaré map has one less dimension than ds, in code the map operates on the full D-dimensional state of ds because that is the only way to accommodate planes with generic orientation.

The output pmap follows the Integrator API, i.e., step! and reinit!. current_time(pmap) returns the time of the last crossing. For the special case of plane being a Tuple{Int, <:Real}, a special reinit! method is allowed with input state with length D-1 instead of D, i.e., a reduced state already on the hyperplane that is then converted into the D dimensional state.

Notice: The argument Tmax exists so that the integrator can terminate instead of being evolved for infinite time, to avoid cases where iteration would continue forever for ill-defined hyperplanes or for convergence to fixed points. If during one step! the system has been evolved for more than Tmax, then step!(pmap) will terminate and return nothing.

Example

ds = Systems.rikitake([0.,0.,0.], μ = 0.47, α = 1.0)
pmap = poincaremap(ds, (3, 0.0))
next_state_on_psos = step!(pmap)
# Change initial condition
reinit!(pmap, [1.0, 0]) # 3rd variable gets value 0 from the plane
next_state_on_psos = step!(pmap)

GeneralizedDynamicalSystem

An umbrella term that includes any instance of DynamicalSystem but also stroboscopicmap, poincaremap and projeted_integrator.

It is used as type declaration in functions that work for any conceivable system type, such as trajectory or AttractorMapper.

step!(discrete_integ [, dt::Int])

Progress the discrete-time integrator for 1 or dt steps.

step!(continuous_integ, [, dt [, stop_at_tdt]])

Progress the continuous-time integrator for one step.

Alternative, if a dt is given, then step! the integrator until there is a temporal difference ≥ dt (so, step at least for dt time).

When true is passed to the optional third argument, the integrator advances for exactly dt time.

get_state(ds::DynamicalSystem)

Return the state of ds.

get_state(integ [, i::Int = 1])

Return the state of the integrator, in the sense of the state of the dynamical system. This function works for any integrator of the library.

If the integrator is a parallel_integrator, passing i will return the i-th state. The function also correctly returns the true state of the system for tangent integrators.

reinit!(integ [, state])

Re-initialize the integrator to the new given state. The state type should match the integrator type. Specifically:

• integrator, stroboscopicmap, poincaremap: it needs to be a vector of size the same as the dimension of the dynamical system that produced the integrator.
• projected_integrator: it needs to be a vector of same size as the projected space.
• parallel_integrator: it needs to be a vector of vectors of size the same as the dimension of the dynamical system that produced the integrator.
• tangent_integrator: there the special signature reinit!(integ, state, Q0::AbstractMatrix) should be used, with Q0 containing the deviation vectors. Alternatively, use set_deviations! if you only want to change the deviation vectors.

current_time(integ) → t

Return the current time of the integrator.

get_deviations(tang_integ)

Return the deviation vectors of the tangent_integrator in a form of a matrix with columns the vectors.

set_deviations!(tang_integ, Q)

Set the deviation vectors of the tangent_integrator to Q, which must be a matrix with each column being a deviation vector.

Automatically does u_modified!(tang_integ, true).