Filtration.jl private functions

show(io::IO, z::Control)

Print a Control

show(io::IO, z::Costate)

Print a Costate

show(io::IO, z::Extremal)

Print an Extremal

show(io::IO, model::Model)

Print a Model (used by e.g. print/error messages). This is a lightweight fallback that requires no extra dependency.

Once the caller's own environment does using ModelingToolkit, the FiltrationModelingToolkitExt package extension additionally provides a richer Base.show(io, ::MIME"text/plain", model) method — the REPL/notebook/Documenter "rich display" for a top-level result — printing the associated symbolic ODE system instead (see [weakdeps]/[extensions] in Project.toml).

show(io::IO, z::MultiModel)

Print a MultiModel

show(io::IO, z::MultiSynthesis)

Print a MultiSynthesis

show(io::IO, odelike::ODELike)

Print an ODELike

show(io::IO, z::Pareto)

Print a Pareto

show(io::IO, z::Solution)

Print a Solution

show(io::IO, z::State)

Print a State

show(io::IO, z::Synthesis)

Print a Synthesis

__AichoucheModel(p::Vector{<:Real}; initial_guess) -> Model

Create the Aichouche model.

Arguments

• p : Parameter vector for the Aichouche model.

Keyword Arguments (optional)

• initial_guess : initial guess forwarded to the constructed Model.

Return

• model : the constructed Model.

__BenyahiaModel(p::Vector{<:Real}; initial_guess) -> Model

Create the Benyahia model.

Arguments

• p : Parameter vector for the Benyahia model.

Keyword Arguments (optional)

• initial_guess : initial guess forwarded to the constructed Model.

Return

• model : the constructed Model.

__CoganModel(p::Vector{<:Real}; initial_guess) -> Model

Create the Cogan model.

Arguments

• p : Parameter vector for the Cogan model.

Keyword Arguments (optional)

• initial_guess : initial guess forwarded to the constructed Model.

Return

• model : the constructed Model.

__bound_value(bound::Real, t::Real) -> Real

Evaluate a bound (a constant, a ODESolution cut, or another ODELike) at a given $t$.

__compute_phi(
    t::Real,
    extremal::Extremal,
    model::Model;
    p
) -> Real

Compute the value of the function $t \mapsto \phi(x(t), p(t))$ on a given time $t$ of an Extremal computed on a Model.

Arguments

• t : a real time $t$
• extremal : the Extremal
• model : the Model

Keyword arguments (optional)

• p : a vector of parameter for the model (default is the parametes of the model).

Return

• phi : the value of $\phi(t)$.

__get_m(
    synthesis1::Synthesis,
    synthesis2::Synthesis
) -> Real

Get the end of the DL2 curve of synthesis1, ie. the value of $x_1$ at which it meets synthesis2's cut₊ curve.

Arguments

• synthesis1 : the below Synthesis
• synthesis2 : the above Synthesis

Return

• m : the value of $x_1$ at the junction

dispersal_locus_2_continuation_method(
    model::Model,
    xlim::Tuple{Real, Real},
    ylim::Tuple{Real, Real},
    DL::Union{ODELike, SciMLBase.ODESolution}
) -> SciMLBase.ODESolution

Compute the second dispersal locus by continuation method.

Arguments

• model : a Model
• xlim : the limits of state $x_2$
• ylim : the limits of state $x_1$
• DL : the first dispersal locus curve

Returns

• DL2 : the second dispersal locus curve

dispersal_locus_2_direct(
    model::Model,
    xlim::Tuple{Real, Real},
    ylim::Tuple{Real, Real},
    DL::Union{ODELike, SciMLBase.ODESolution},
    cutSL::SciMLBase.ODESolution;
    n
) -> ODELike

Compute the second dispersal locus by direct method.

Arguments

• model : a Model
• xlim : the limits of state $x_2$
• ylim : the limits of state $x_1$
• DL : the first dispersal locus curve
• cutSL : the cutSL curve

Returns

• DL2 : the second dispersal locus curve

dispersal_locus_continuation_method(
    model::Model,
    xlim::Tuple{Real, Real},
    ylim::Tuple{Real, Real},
    SL::SciMLBase.ODESolution,
    cut₋::SciMLBase.ODESolution
) -> SciMLBase.ODESolution

Compute the first dispersal locus by continuation method.

Arguments

• model : a Model
• xlim : the limits of state $x_2$
• ylim : the limits of state $x_1$
• SL : the switching locus curve
• cut₋ : the cut₋ curve

Returns

• DL : the dispersal locus curve

Compute the dispersal locus with a direct method.

Arguments

• model : the Model
• xlim : the limits of state $x_2$
• ylim : the limits of state $x_1$
• SL : the switching locus curve
• cut₋ : the cut₋ curve

Returns

• DL : the dispersal locus curve, as an ODELike solution

fit_free(
    model::Model,
    control::Control,
    time::Vector{<:Real},
    data_x0::AbstractVecOrMat{<:Real},
    initial_p::Vector{<:Real},
    x0::Vector{<:Real};
    obs_indices,
    lb,
    ub,
    max_iter,
    verbose
) -> NamedTuple{(:p, :x0), <:Tuple{Any, Any}}

Fit the model parameters and the full initial state x0 jointly, by minimizing the least square error between the simulated and observed data — unlike fit_unknown, no get_m function, no steady-state pre-arc, no slope estimation: every component of x0 is just a free variable in the same optimization as p, with x0 (the caller's guess) only used to seed the search.

Arguments

• model : a Model
• control : a Control
• time : vector of time points where data are observed
• datax0 : observed data — a vector (one state index) or an `ntime × length(obsindices)matrix (several indices, columns matchingobsindices`'s order)
• initial_p : initial guess for the model parameters
• x0 : initial guess for the full initial state (all three components free)

Keyword Arguments

• obsindices : which state indices `datax0holds data for (default :[1]`)
• lb : lower bounds for the model parameters (default : zeros)
• ub : upper bounds for the model parameters (default : Inf)
• max_iter : cap on Ipopt's iteration count (default : nothing, i.e. Ipopt's own default — unbounded search time). Whether or not the search is cut short by this cap, the best (lowest mean-squared-error) (p, x0) seen across every objective evaluation attempted is returned — not necessarily wherever Ipopt's own final iterate happens to land, which isn't guaranteed to be the best one visited when the search is truncated.
• verbose : whether to print optimization details (default : false)

x0 itself is always constrained to be component-wise non-negative (no upper bound) — without some bound, Ipopt can wander into a region where the ODE becomes unstable/NaN (the same failure mode fit_known/fit_unknown's own tests guard p against via ub), and unlike p, x0's components are physical state values with no natural upper bound to offer as a default, but negativity is never physically meaningful for them either.

Return

• (p, x0) — the fitted parameters and full initial state

fit_known(
    model::Model,
    control::Control,
    time::Vector{<:Real},
    data_x0::AbstractVecOrMat{<:Real},
    initial_p::Vector{<:Real},
    x0::Vector{<:Real};
    obs_indices,
    lb,
    ub,
    max_iter,
    verbose
) -> Any

Fit the model parameters to the given data by minimizing the least square error between the simulated and observed data. The initial state is supposed to be known.

Arguments

• model : a Model
• control : a Control
• time : vector of time points where data are observed
• datax0 : observed data — a vector (one state index) or an `ntime × length(obsindices)matrix (several indices, columns matchingobsindices`'s order)
• initial_p : initial guess for the model parameters
• x0 : initial state

Keyword Arguments

• obsindices : which state indices `datax0holds data for (default :[1], i.e. statex_0` alone — the original single-index behavior)
• lb : lower bounds for the model parameters (default : zeros)
• ub : upper bounds for the model parameters (default : Inf)
• max_iter : cap on Ipopt's iteration count (default : nothing, i.e. Ipopt's own default — unbounded search time). Whether or not the search is cut short by this cap, the best (lowest mean-squared-error) p seen across every objective evaluation attempted is returned — not necessarily wherever Ipopt's own final iterate happens to land, which isn't guaranteed to be the best one visited when the search is truncated.
• verbose : whether to print optimization details (default : false)

fit_unknown(
    model::Model,
    control::Control,
    time::Vector{<:Real},
    data_x0::Vector{<:Real},
    initial_p::Vector{<:Real},
    x0::Vector{<:Real},
    get_m::Function,
    u::Real,
    slope::Real;
    lb,
    ub,
    verbose
) -> Any

Fit the model parameters to the given data by minimizing the least square error between the simulated and observed data. The initial state is supposed to be partially unknown, with one unknown state variable being fitted via a constraint on its derivative at initial time. See here for more information.

Arguments

• model : a Model
• control : a Control
• time : vector of time points where data are observed
• datax0 : vector of observed data for state ``x0``
• initial_p : initial guess for the model parameters
• x0 : initial state and initial guess for the unknown state variables
• get_m : function to compute the unknown initial state variable from control and parameters
• u : singular control applied before initial time
• slope : slope of state $x_0$ before initial time

Keyword Arguments

• lb : lower bounds for the model parameters (default : zeros)
• ub : upper bounds for the model parameters (default : Inf)
• verbose : whether to print optimization details (default : false)

Get the y-coordinate of the ode at a given x-coordinate.

Arguments

• x : the x-coordinate
• ode : the ode solution

Returns

• y : the y-coordinate

real_solve_control(
    model::Model,
    init_x₂::Real,
    end_x₂::Real,
    init_x₁::Real,
    N::Int64
) -> Solution

Provide the real solution, where the control is only composed by -1 and 1 values. In this method, the control is approximated by -1 and 1 with respect to the value of uₛ.

Arguments

• model : a Model
• init_x₂ : the initial state $x_2(t_0)$
• end_x₂ : the final state $x_2(t_f)$
• init_x₁ : the initial state $x_1(t_0)$
• N : the number of subdivision of the singular arc

Return

• real_sol : the Solution

real_solve_optimal(
    model::Model,
    init_x₂::Real,
    end_x₂::Real,
    init_x₁::Real,
    N::Int64;
    verbose
) -> Solution

Provide the optimal real solution, where the control is only composed by -1 and 1 values. In this method, the global constraints non linear optimization problem is constructed and solved.

Arguments

• model : a Model
• init_x₂ : the initial state $x_2(t_0)$
• end_x₂ : the final state $x_2(t_f)$
• init_x₁ : the initial state $x_1(t_0)$
• N : the number of subdivision of the singular arc

Keyword arguments (optional)

• verbose : if true, print the optimization process (default is false)

Return

• real_sol : the Solution

real_solve_singular(
    model::Model,
    init_x₂::Real,
    end_x₂::Real,
    init_x₁::Real,
    N::Int64;
    verbose
) -> Solution

Provide a real solution, where the control is only composed by -1 and 1 values. In this method, the singular arc is subdivided into N intervals. On each subintervals, we ensure that the solution minimize the cost and satisfy that the begining and the end of the state $x\_1$ on each subintervals corresponds to the value of the singular arc $x\_s$.

Arguments

• model : a Model
• init_x₂ : the initial state $x_2(t_0)$
• end_x₂ : the final state $x_2(t_f)$
• init_x₁ : the initial state $x_1(t_0)$
• N : the number of subdivision of the singular arc

Keyword arguments (optional)

• verbose : if true, print the optimization process (default is false)

Return

• real_sol : the Solution