API

PEtabTraining implements three training strategies that can be applied directly to a PEtabODEProblem:

julia

PEtabClProblem(prob_original::PEtabODEProblem, split_alg::Union{SplitTime, SplitData})

Construct a curriculum of PEtab problems by splitting the measurement data of prob_original into curriculum stages using split_alg.

Stage problems are stored in petab_problems, where petab_problems[i] is the PEtabODEProblem for curriculum stage i. The original problem is stored in original.

See also SplitTime, SplitData.

source

PEtabTraining.PEtabMsProblem Type

julia

PEtabMsProblem(prob_original::PEtabODEProblem, split_alg::SplitTime; kwargs...)

Construct a multiple-shooting PEtab problem by splitting the time domain of prob_original into windows defined by split_alg.

In the constructed prob_ms, the multiple-shooting PEtabODEProblem is stored in prob_ms.petab_ms_problem, and the original problem is stored in prob_ms.original.

Keyword arguments

window_u0_scale::Symbol = :lin: Scale for estimating the window initial-value parameters on (:lin, :log, :log10). For problems where ODE states span orders of magnitude, :log10 often improves performance. Any option other than :lin should only be used if states are strictly positive, since it requires (and thus enforces) positive values.
window_u0_penalty_scale::Symbol = :lin: Scale used for the ODE states ( $u$ and $\tilde{u}$ below) in the window-continuity penalty formula (:lin, :log, :log10). Log scales can help when state values span orders of magnitude and it is difficult to choose a single penalty weight suitable for all states, but requires strictly positive ODE states.

Mathematical description

Multiple shooting introduces additional window initial-value parameters that are estimated together with the original parameters. Window continuity is enforced by adding a quadratic penalty at each window boundary. For consecutive windows with end time $t_{i}$ and next-window initial-value parameter ${\tilde{u}}_{i + 1}$ , the penalty used is

λ {‖ u_{i} (t_{i}) - {\tilde{u}}_{i + 1} ‖}_{2}^{2},

where $u_{i} (t_{i})$ is the state at the end of window $i$ , and $λ$ is the window-penalty weight (can be set with set_ms_window_penalty!). If window_u0_penalty_scale != :lin, the penalty is applied on the transformed scale, i.e. $s (u_{i} (t_{i})) - s ({\tilde{u}}_{i + 1})$ (elementwise), with $s$ being either $l o g$ or $l o g 10$ .

Initial values for the window parameters ${\tilde{u}}_{i + 1}$ can be set with set_u0_ms_windows! (default 0.01).

source

PEtabTraining.PEtabClMsProblem Type

julia

PEtabClMsProblem(prob_original::PEtabODEProblem, split_alg::SplitTime; kwargs...)

Construct a curriculum of multiple-shooting PEtab problems from prob_original by progressively merging time windows defined by split_alg.

In the constructed prob_cl_ms, stage problems are stored in prob_cl_ms.petab_problems, where prob_cl_ms.petab_problems[i] is the PEtabODEProblem for curriculum stage i. The original problem is stored in prob_cl_ms.original.

Keyword Arguments

Keyword arguments are the same as for PEtabMsProblem (window_u0_scale, window_u0_penalty_scale).

Description

A PEtabClMsProblem is a curriculum of problems, where each intermediate stage is a multiple-shooting problem with a different window partition (with increasing window length and overlap). The final stage equals the original problem. Because the number of shooting windows changes between stages, the parameter vector dimension changes as well. Use map_x_stage to map a parameter vector between stages.

As in PEtabMsProblem, each multiple-shooting stage includes a quadratic window penalty applied at the first time point shared by two consecutive windows; the penalty weight can be set with set_ms_window_penalty!.

source

All above training strategies require splitting the original simulation in windows/stages:

PEtabTraining.SplitTime Type

julia

SplitTime(n::Integer)

Split the measurements in the measurement table into n chunks based on unique time points.

The resulting chunking is applied to each simulation condition. If the number of unique time points is not divisible by n, the last chunk contains the remaining time points.

source

julia

SplitTime(split_points::Vector{<:Real})

Splits the measurements in the measurement table into length(split_points) + 1 chunks using the time values in split_points as split points.

Chunks are defined as [tmin, s₁), [s₁, s₂), …, [sₙ, tmax], where tmin/tmax are the minimum/maximum measurement time points and sᵢ are the entries in split_points. split_points must be sorted and lie within the range of the measurement time points. Split points do not need to coincide with measurement time points.

source

PEtabTraining.SplitData Type

julia

SplitData(n::Integer)

Splits the time-sorted measurements into n chunks (uniform by number of data points).

The resulting chunking is applied to each simulation condition. If the number of data points is not divisible by n, the last chunk contains the remaining data points.

If all measurements have a unique time point, this is equivalent to SplitTime(n).

source

julia

SplitData(chunk_sizes::Vector{<:Integer})

Splits the measurements in the time-sorted measurement table into length(chunk_sizes) chunks, where chunk_sizes[i] gives the number of data points in chunk i.

chunk_sizes must be sorted, and the final entry must equal the number of measurements.

source

Utility functions are provided for setting window initial values and the continuity window penalty for multiple-shooting-based methods.

PEtabTraining.set_ms_window_penalty! Function

julia

set_ms_window_penalty!(prob_ms::PEtabMsProblem, val::Real)

Set the multiple-shooting window-penalty weight to val for prob_ms.

See PEtabMsProblem for the definition of the window penalty.

source

julia

set_ms_window_penalty!(prob_cl_ms::PEtabClMsProblem, val::Real)

Set the multiple-shooting window-penalty weight to val for each multiple-shooting stage problem in prob_cl_ms.

See PEtabMsProblem for the definition of the window penalty.

source

PEtabTraining.set_u0_ms_windows! Function

julia

set_u0_ms_windows!(x, prob_ms::PEtabMsProblem; init = MsInitConstant(0.01))
set_u0_ms_windows!(x, prob_ms::PEtabMsProblem, p; init = MsInitFirst())
set_u0_ms_windows!(x, prob_ms::PEtabMsProblem, p; init = MsInitSimulate())

Set multiple-shooting window initial values in the multiple-shooting parameter vector x.

x must be a parameter vector in the format expected by prob_ms (e.g. returned by get_x(prob_ms)). When provided, p must be a parameter vector compatible with either the original PEtab problem or the multiple-shooting PEtab problem.

Initialization is controlled by init:

MsInitConstant(value): Set all window initial values to value.
MsInitFirst(): Copy initial values from the first window to all windows.
MsInitSimulate(): Forward simulate the model and set each window initial value from the simulated state at the window start time.

source

julia

set_u0_ms_windows!(x, prob::PEtabClMSProblem, stage::Integer; init = MsInitConstant(0.01))
set_u0_ms_windows!(x, prob::PEtabClMSProblem, stage::Integer, p; init = MsInitFirst())
set_u0_ms_windows!(x, prob::PEtabClMSProblem, stage::Integer, p; init = MsInitSimulate())

Set multiple-shooting window initial values in the multiple-shooting parameter vector x for stage of a combined curriculum-learning and multiple-shooting problem prob.

x must be in the format expected by the multiple-shooting stage problem (e.g. returned by get_x(prob; stage = stage)). All other arguments have the same meaning as for set_u0_ms_windows!(x, prob::PEtabMsProblem, ...).

source

PEtabTraining.MsInitConstant Type

julia

MsInitConstant(value::Real = 0.01)

Initialization strategy for multiple-shooting window initial values, where each window initial value is set to value.

API ​

API