Problem Types

myMCProblem

Abstract type for all problem types defined in this library. Note that the DifferentialEquations.jl problem types are not supertypes of this types.

MCBBProblem <: myMCProblem

Abstract type of DEMCBBProblem (using DifferentialEquations.jl as a backend) and CustomMCBBProblem (using customized solve and problem functions).

DEMCBBProblem

Differential Equations Monte Carlo Basin Bifurcation Problem: Main type for the sample based bifurcation/stablity analysis based on EnsembleProblem from DifferentialEquations. This struct holds information about the underlying differential equation and the parameters and initial conditions its supposed to be solved for. Many points from the initial conditions - parameter space are sampled. When solved the solutions is evaluated seperatly for each dimension and certain statistical measures like mean or standard deviation are saved.

The struct has several different constructors following below.

Note that its supertypes are MCBBProblem and myMCProblem, but not any of the DifferentialEquations abstract problem types.

The struct has the following fields:

• p: EnsembleProblem to be solved, part of DifferentialEquations
• N_mc: Number of (Monte Carlo) runs to be solved
• rel_transient_time: Only after this time (relative to the total integration time) the solutions are evaluated
• ic: ($N_{mc} \times (N_{dim_{ic}} + N_{par})$)-Matrix containing initial conditions for each run.
• par: (``N{mc} \times N{par})-Matrix containitng parameter values for each run
• par_var: ParameterVar, information about how the parameters are varied, see ParameterVar

Constructors

The type has three different main constructors and several others that do automatic type conversions of appropiate tuples to ParamterVar types or of functions and arrays to arrays of functions/arrays if needed.

Randomized Initial conditions

DEMCBBProblem(p::DiffEqBase.DEProblem, ic_gens::Array{<:Function,1}, N_ic::Int, pars::DEParameters, par_range_tuple::ParameterVar, eval_ode_func::Function, tail_frac::Number)

Setup a DEMCBBProblem with randomized initial conditions (and parameters).

• p: A Problem from DifferentialEquations, currently supported are DiscreteProblem, ODEProblem, SDEProblem,DDEProblem the base problem one is interested in.
• ic_gens: A function or an array of functions that generate the initial conditions for each trial. Function signature is ()->new_value::Number or (i_run)->new_value::Number or ()->new_value::AbstractArray or (i_run)->new_value::AbstractArray. If only one function is provided its used for all IC dims, if $M<N_{dim}$ functions with $N_{dim}=k\cdot M$ are provided these functions are repeated $k$ times (usefull e.g. for coupled chaotic oscillators).
• N_ic: Number of trials to be computed, if parameter variation is varied by an array/range, N_ic is the number of initial conditions for each parameter value. Each parameter step then has the same N_ic idential initial conditions.
• pars: parameter struct of the underlying system
• par_range_tuple: ParameterVar, information about how the parameters are varied, see ParameterVar. Its also possible to hand over an appropiate tuple that will be automaticly converted to a ParameterVar type. A tuple of (First: name of the parameter as a symbol, Second: AbstractArray or Function that contains all parameters for the experiment or a function that generates parameter values. The function has to be format (oldvalue) -> (newvalue), Third: OPTIONAL: a function that maps (oldparameterinstance; (parrange[1],newparametervalue)) -> newparameterinstance. Default is 'reconstruct' from @withkw/Parameters.jl is used) For examples see Basic Usage.
• eval_ode_func: Evaluation function for the EnsembleProblem with the signature (sol,i)->(results, repeat). There are many premade functions for this purpose in this library, most of them called eval_ode_run, see also eval_ode_run
• tail_frac: Only after this time (relative to the total integration time) the solutions are evaluated

Non-randomized initial conditions

DEMCBBProblem(p::DiffEqBase.DEProblem, ic_ranges::Array{<:AbstractArray,1}, pars::DEParameters, par_range_tuple::ParameterVar, eval_ode_func::Function, tail_frac::Number)

Setup a DEMCBBProblem with initial conditions (and parameters) from predefined arrays or ranges. All arguments are identical to the other constructor except for:

• ic_ranges: A range/array or array of ranges/arrays with initial conditions for each trial. If only one range/array is provided its used for all IC dims.
• Note that there is no N_ic argument in constrast to the other constructor

Hidden / Background Parameter Problem

In case we are varying hidden/background parameters at each trial and , we can use the regular calls above, just with the parameter variation given by a HiddenParameterVar.

Hidden / Background Parameter Problem with Identical ICs

It is also possible to use the same IC for all trials with background parameters with

DEMCBBProblem(p::DiffEqBase.DEProblem, ics::Array{Number,1}, pars::DEParameters, par_range_tuple::HiddenParameterVar, eval_ode_func::Function, tail_frac::Number)

but replace the ic_ranges argument, with an array ics that contains the constant ICs and the parameter variation has to be given as a HiddenParameterVar.

Direct constructor

It is also possible to initialize the type directly with its fields with

DEMCBBProblem(p::EnsembleProblem, N_mc::Int64, rel_transient_time::Float64, ic::AbstractArray, par::AbstractArray, par_range_tuple::ParameterVar)

parameter(p::DEMCBBProblem, i::Int=1; complex_returns_abs=true)

Utility function that returns the parameters of each trial of of a problem. In case multiple parameters are varied simultaneously it returns the i-th parameter. In case the initial conditions or parameters are complex valued the function returns the absolute value of the parameters if complex_returns_abs==true and the original complex number if complex_returns_abs==false.

MCBBSol <: myMCSol

Abstract type of DEMCBBSol (using DifferentialEquations.jl as a backend) and CustomMCBBSolution (using customized solve and problem functions).

DEMCBBSol

Type that stores the solutions of a DEMCBBProblem. Is returned by the corresponding solve routine.

Its fields are:

• sol: EnsembleSolution (see DifferentialEquations)
• N_mc: number of solutions saved / Monte Carlo trials runs
• N_t: number of time steps for each solutions
• N_dim: dimension measured with per dimension measures. if no state_filter was applied this is equal to the sytem dimension
• N_meas: number of measures used, ``N{meas} = N{meas{dim}} + N{meas_{global}}
• N_meas_dim: number of measures that are evalauted for every dimension seperatly
• N_meas_global: number of measures that are evalauted globally
• solve_command: A function that solves one individual run/trial with the same settings as where used to

Note, in case N_dim==1 => N_meas_global == 0 and N_meas_dim == N_meas

sort(sol::DEMCBBSol, prob::DEMCBBProblem, i::Int=1)

Returns a copy of the sol and prob sorted by the values of the i-th parameter.

(In case the parameter is complex valued, it sorts by the absolute value of the parameter)

sort(sol::DEMCBBSol, prob::DEMCBBProblem, i::Int=1)

Sorts sol and prob inplace by the values of the i-th parameter.

(In case the parameter is complex valued, it sorts by the absolute value of the parameter)

sort(prob::DEMCBBProblem, i::Int=1)

Returns a copy of prob sorted by the values of the i-th paramater.

(In case the parameter is complex valued, it sorts by the absolute value of the parameter)

sort(prob::DEMCBBProblem, i::Int=1)

Sorts prob inplace by the values of thei-th paramater.

(In case the parameter is complex valued, it sorts by the absolute value of the parameter)

show_results(sol::DEMCBBSol, prob::DEMCBBProblem, min_par::Number, max_par::Number, i::Int=1, sorted::Bool=false)

Returns the solutions for which the i-th parameter exhibits values between min_par and max_par. If sorted==true it assumes that sol and prob are already sorted by this parameter.

get_measure(sol::MCBBSol, k::Int; state_filter::Union{AbstractArray, Nothing}=nothing)

Return the results for the k-th measure as an array. State_filter filters the system dimensions, e.g. if state_filter==1:10 only the first measurements from the first 10 system dimensions are returned. Default: all. This works only for the per dimenension measures of course. Attention: if the evalation function already used a state_filter this will be refering only to the system dimension that were measured.

get_measure(sol::myMCSol, i::Int, clusters::ClusteringResult, i_cluster::Int, prob::Union{MCBBProblem,Nothing}=nothing, min_par::Number=-Inf, max_par::Number=+Inf, i_par::Int=1)

Get measure i for the i_cluster-th cluster with parameter values between min_par and max_par. If no prob is given, it ignores the parameter values. In case a multidimensional setup is used, uses the i_par-th Parameter.

normalize(sol::DEMCBBSol, k::AbstractArray)

Returns a copy of sol with the solutions normalized to be in range [0,1]. It is possible to only select that some of the measures are normalized by providing an array with the indices of the measures that should be normalized, e.g. [1,2] for measure 1 and measure 2 to be normalized.

normalize(sol::DEMCBBSol)

If no extra array is provided, all measures are normalized.

solve(prob::DEMCBBProblem, alg=nothing, N_t=400::Int, parallel_type=:parfor; flag_check_inf_nan=true, custom_solve::Union{Function,Nothing}=nothing, kwargs...)

Custom solve for the DEMCBBProblem. Solves the EnsembleProblem, but saves and evaluates only after transient at a constant step size, the results are sorted by parameter value.

• prob: EnsembleProblem of type defined in this library
• alg: Algorithm to use, same as for solve() from DifferentialEquations.jl
• N_t: Number of timesteps to be saved
• parallel_type: Which form of parallelism should be used? Same as for EnsembleProblem from DifferentialEquations.jl
• flag_check_inf_nan: Does a check if any of the results are NaN or inf
• custom_solve:: Function/Nothing, custom solve function

save(p::DEMCBBProblem, file_name::String)

Saves p. It uses JLD2, but it does not fully save every single function contained in p. This makes it a bit less errorprone to some loading/saving problems that JLD2 seems to have. The file has to be loaded with load_prob.

load_prob(file_name::String, base_problem::DiffEqBase.DEProblem, eval_func::Function, par_var)

Loads a DEMCBBProblem, that was saved via save. The routine needs some additional information to fully recover all functions.

load_sol(file_name::String)

Loads a DEMCBBSol, that was saved via save.

setup_ic_par_mc_problem

Methods that are usually called automaticly while constructing a DEMCBBProblem. These methods setup the initial conditions - parameter matrix and the problem function for the EnsembleProblem.

Initial Condtions set with Arrays or Ranges

setup_ic_par_mc_problem(prob::DiffEqBase.DEProblem, ic_ranges::Array{T,1}, parameters::DEParameters, var_par::ParameterVar) where T <: AbstractArray

• prob: A Problem from DifferentialEquations, currently supported are DiscreteProblem, ODEProblem, SDEProblem, the base problem one is interested in.
• ic_ranges: A range/array or array of ranges/arrays with initial conditions for each trial. If only one range/array is provided its used for all IC dims.
• parameters: parameter struct of the underlying system
• var_par: ParameterVar, information about how the parameters are varied, see ParameterVar. Its also possible to hand over an appropiate tuple that will be automaticly converted to a ParameterVar type. For examples see Basic Usage.

Initial Condtions generated by Functions

setup_ic_par_mc_problem(prob::DiffEqBase.DEProblem, ic_gens::Array{<:Function,1}, N_ic::Int, parameters::DEParameters, var_par::ParameterVar)

• prob: A Problem from DifferentialEquations, currently supported are DiscreteProblem, ODEProblem, SDEProblem, the base problem one is interested in.
• ic_gens: A function or an array of functions that generate the initial conditions for each trial. Function signature is ()->new_value::Number or (i_run)->new_value::Number. If only one function is provided its used for all IC dims, if $M<N_{dim}$ functions with $N_{dim}=k\cdot M$ are provided these functions are repeated $k$ times (useful e.g. for coupled chaotic oscillators).
• parameters: parameter struct of the underlying system
• var_par: ParameterVar, information about how the parameters are varied, see ParameterVar.

define_new_problem(prob, ic::Abstract, par::AbstractArray, parameters::DEParameters, N_dim_ic::Int, ic_gens::AbstractArray, var_par::ParameterVar)

Returns the functions that returns new DifferentialEquations problems needed for EnsembleProblem.

• prob: A Problem from DifferentialEquations, currently supported are DiscreteProblem, ODEProblem, SDEProblem, DDEProblem the base problem one is interested in.
• ic: ($N_{mc} \times N_{dim_{ic}}$)-Matrix containing initial conditions for each run.
• par: ($N_{mc} \times N_{par}$)-Matrix containing parameter values for each run.
• N_dim_ic: system dimension
• ic_gens: Array of functions or arrays/ranges that contain/generate the ICs.
• var_par: ParameterVar, information about how the parameters are varied, see ParameterVar.

 define_new_problem(prob::CustomProblem, ic_par::AbstractArray, parameters::DEParameters, N_dim_ic::Int, ic_gens::AbstractArray, var_par::ParameterVar)

Helper functions that refurns a function returning new functions needed for CustomMonteCarloProblem.

 tsave_array(prob, N_t::Int, rel_transient_time::Float64=0.7)

Given a tspan to be used in a DEProblem, returns the array/iterator of time points to be saved (saveat argument of solve())

• prob: DifferentialEquations problem
• N_t : number of time points to be saved
• rel_transient_time: Only after this time (relative to the total integration time) the solutions are evaluated