API Reference

struct Trajectory{S, U, P, T, SH}

The solution to an optimal control problem.

Fields

• sys: The symbolic system used for SymbolicIndexingInterface

• u: The state trajectory

• p: The parameter values

• t: The timepoints

• shooting: The shooting values

• shooting_indices: The shooting indices

Note

If present, shooting_points contains a list of Tuples (timeseries_index, last_shooting_point).

struct ControlParameter{T, C, B}

Implements a piecewise constant control discretization.

Fields

• name: The name of the control

• t: The timepoints at which discretized variables are introduced

• controls: The initial values for the controls. Either a vector or a function (rng,t,bounds) -> u

• bounds: The bounds as a tuple

struct SingleShootingLayer{P, A, C, B, PB, SI, PI} <: LuxCore.AbstractLuxLayer

Defines a callable layer that integrates the AbstractDEProblem problem using the specified algorithm. Controls are assumed to impact differential equation via its parameters problem.p at the positions indicated via control_indices and are itself specified via controls. Moreover, initial conditions problem.u0 that are degrees of freedom to be optimized can be specified by their indices via tunable_ic along with their upper and lower bounds via bounds_ic.

Fields

• problem: The underlying differential equation problem

• algorithm: The algorithm with which problem is integrated.

• control_indices: Indices in parameters of prob corresponding to controls

• controls: The controls

• tunable_ic: Indices of prob.u0 which are degrees of freedom

• bounds_ic: Bounds on the tunable initial conditions of the problem

• state_initialization: Initialization of u

• tunable_p: Indices of prob.p which are degrees of freedom. This is derived from control_indices!

• bounds_p: Bounds on the tunable parameters of the problem

• parameter_initialization: Initialization of p

• quadrature_indices: Indices of differential states that are quadratures, i.e. they do not enter into the right hand side of problem

Note: The orders of both controls and control_indices, and bounds_ic and tunable_ic are assumed to be identical!

struct MultipleShootingLayer{L, I, E, Z} <: LuxCore.AbstractLuxWrapperLayer{:layer}

Defines a callable layer that integrates a differential equation using multiple shooting, i.e., the problem is lifted and integration is decoupled on disjunct time intervals given in shooting_intervals. Initial conditions on the shooting_intervals are degrees of freedom (except perhaps for the first layer), for which the initialization scheme initialization provides initial values. Parallelization is integration is possible, for which a suitable EnsembleAlgorithm can be specified with ensemble_alg.

Fields

• layer: The original layer

• shooting_intervals: The shooting intervals

• ensemble_alg: The ensemble algorithm

• initialization: The initialization scheme

default_initialization

Initializes all shooting nodes with their default value, i.e., their initial value in the underlying problem.

random_initialization(rng, shooting; ps, kwargs...)

Initializes all shooting nodes with random values.

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer

Keyworded Arguments

• ps the default parameters of the shooting layer.

forward_initialization(
    rng,
    shooting;
    ps,
    fixed_indices,
    kwargs...
)

Initializes the problem using a forward solve of the problem. This results in a continuous trajectory.

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer

Keyworded Arguments

• ps the default parameters of the shooting layer.

linear_initialization(
    rng,
    shooting;
    ps,
    u_infinity,
    kwargs...
)

Linearly interpolates u0 and u_inf for t with tspan[1] < t < tspan[2].

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer

Keyworded Arguments

• ps the default parameters of the shooting layer.
• u_infinity::AbstractArray the value at the last timepoint for all states.

custom_initialization(rng, shooting; ps, u0s, kwargs...)

Initializes all shooting nodes with user-provided values. Initial values are given as an iterable collection of AbstractArrays, Dicts, or a vector of Pairs. The variable indices are interpreted depending on the passed value

• AbstractArray just sets the initial condition with the provided value. This assumes equal dimensionality.
• Dict assumes the keys represent indices of the initial condition.
• A Vector or Tuple of Pairs assumes the first value represents an index of the initial condition.

Other options simply skip the corresponding interval.

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer

Keyworded Arguments

• ps the default parameters of the shooting layer.
• u0s the collection of initial conditions.

Example

# Assumes a shooting layer with 3 intervals
# Skips the first interval
# Sets the first index of the second interval to 3.0
# Sets the second index of the third interval to 5.0 and the 5th index to -1.0
custom_initialization(rng, shooting, u0s = [nothing, Dict(1 => 3.0), (2 => 5.0, 5 => -1.0)])

constant_initialization(rng, shooting; ps, u0, kwargs...)

Initializes all shooting nodes with user-provided value. The variable indices are interpreted depending on the passed value

• AbstractArray just sets the initial condition with the provided value. This assumes equal dimensionality.
• Dict assumes the keys represent indices of the initial condition.
• A Vector or Tuple of Pairs assumes the first value represents an index of the initial condition.

Other options simply skip the corresponding interval.

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer

Keyworded Arguments

• ps the default parameters of the shooting layer.
• u0 the initial condition.

Example

# Assumes a shooting layer with 3 intervals
# Sets the first index of all intervals to 3.0
constant_initialization(rng, shooting, u0 = Dict(1 => 3.0))
constant_initialization(rng, shooting, u0 = (1 => 3.0,))
# Set the initial condition to the given vector
constant_initialization(rng, shooting, u0 = [1., 2., 4.])

hybrid_initialization(rng, shooting, f; ps, kwargs...)

Initializes the shooting nodes in a hybrid method by applying the provided methods and indices f sequentially. Here we assume the structure interval => method for the initialization.

Arguments

• rng::Random.AbstractRNG a random number generator
• shooting::MultipleShootingLayer a shooting layer
• f::Pairs of the interval index and applied method

Keyworded Arguments

• ps the default parameters of the shooting layer.

All other keyworded arguments are passed on to the functions below.

struct CorleoneDynamicOptProblem{L, G, O, C, CB}

A struct for capturing the internal definition of a dynamic optimization problem.

Fields

• layer: The resulting layer for the problem

• getters: The getters which return the values of the trajectory

• objective: The objective function

• constraints: The constraint function

• lcons: Lower bounds for the constraints

• ucons: Upper bounds for the constraints

get_block_structure(layer; kwargs...)

Return cumulative parameter boundaries for a Corleone layer. The first entry is zero and the final entry is the number of optimization parameters. Layer wrappers should extend this method when their parameter blocks have additional structure.

get_block_structure(layer)
get_block_structure(layer, tspan, kwargs)

Compute the block structure of the hessian of the Lagrangian of an optimal control problem. As this is a SingleShootingLayer, this hessian is dense. See also $MultipleShootingLayer$.

get_block_structure(mslayer)

Compute the block structure of the hessian of the Lagrangian of an optimal control problem as specified via the shooting_intervals of the MultipleShootingLayer. Note: Constraints other than the matching conditions of the multiple shooting approach are not considered here and might alter the block structure.

get_block_structure(layer)

Computes the block structure as defined by the MultiExperimentLayer, which may come from two levels: 1) the different experiments, and 2) multiple shooting discretizations on the experiment level.

get_bounds(layer; kwargs...)

Return lower and upper bounds for the optimization variables of layer as a tuple (lower, upper). A layer extension must preserve the same structure in both values.

get_bounds(parameters; tspan, kwargs...)

Returns bounds of discretized controls restricted to given tspan.

get_bounds(mslayer)

Extracts lower and upper bounds of all optimization variables in the MultipleShootingLayer.

get_controls(, parameters; raw, tspan, kwargs...)

Returns discretized controls of ControlParameter params restricted to given tspan.

get_controls(layer::SingleShootingLayer)

Return (controls, control_indices), where controls are the control parameter objects and control_indices identify their positions in the problem parameter vector.

get_number_of_shooting_constraints(layer)

Return the number of matching constraints generated by layer. Single shooting has no matching constraints; multiple shooting counts state, parameter, and control continuity constraints in that order.

get_problem(layer::SingleShootingLayer)

Return the differential-equation problem integrated by layer.

get_timegrid(parameters::ControlParameter, tspan = (-Inf, Inf))

Return the control time points inside tspan. The returned points retain the order of the control parameter grid and exclude the right endpoint of a finite interval.

get_tspan(layer::SingleShootingLayer)

Return the time span of the underlying differential-equation problem.

get_tunable(layer::SingleShootingLayer)

Return the indices of tunable initial-condition entries.

shooting_constraints(traj)

Returns the shooting violations sorted by states - parameters - controls and per-kind sorted by shooting-stage.

shooting_constraints!(res, traj)

In-place version of shooting_constraints.

struct OEDLayer{DISCRETE, SAMPLED, FIXED, L, O} <: LuxCore.AbstractLuxWrapperLayer{:layer}

Wraps a Corleone shooting layer with the augmented dynamics needed for optimal experimental design. The DISCRETE type parameter selects discrete or continuous information accumulation, and optional measurement controls can restrict where observations are collected.

Fields

• layer: The underlying layer

• observed: The observed functions

• sampling_indices: The sampling indices

fisher_information(oed, x, ps, st; add_initial)

Computes the Fisher information matrix for an OEDLayer at parameters ps and state st.

Arguments

• oed: Optimal experimental design layer.
• x: External input passed through the Lux layer interface.
• ps: Layer parameters, typically from LuxCore.initialparameters or LuxCore.setup.
• st: Layer state, typically from LuxCore.initialstates or LuxCore.setup.

Keywords

• add_initial: Include previously accumulated information stored in st.

Returns

A tuple (F, st) containing the Fisher information matrix and updated layer state.

observed_equations(oed, traj)

Evaluates the observation equations associated with an OEDLayer.

Returns

For trajectory inputs, observed values are returned directly. For layer inputs, the return value is (observed, st) with the updated layer state.

sensitivities(oed, traj)

Returns the parameter sensitivities of the observed outputs for an OED trajectory.

Returns

For trajectory inputs, the sensitivity arrays are returned directly. For layer inputs, the return value is (sensitivities, st) with the updated layer state.

local_information_gain(oed, x, ps, st)

Computes local information gain contributions from each observed quantity along the OED trajectory.

Returns

A tuple (gains, st) containing per-observation information matrices and the updated layer state.

global_information_gain(oed, x, ps, st)

Computes global information gain contributions scaled by the inverse final Fisher information matrix.

Returns

A tuple (gains, st) containing per-observation information matrices and the updated layer state.

struct MultiExperimentLayer{DISCRETE, FIXED, SPLIT, SHOOTING, L, P} <: LuxCore.AbstractLuxLayer

Generalization of OEDLayer to multiple experiments that can be jointly optimized.

Fields

• layers: Layers defining multiexperiments

• n_exp: Number of experiments

• params: Parameters considered in the different experiments

abstract type AbstractCriterion

Interface for an optimal-design criterion.

Concrete criteria must implement (::MyCriterion)(F::Symmetric) and return a scalar objective from a Fisher information matrix. The generic layer method calls fisher_information(layer, x, ps, st) and returns (value, st) while preserving the updated layer state. Criteria are pure with respect to the matrix input and must not mutate the layer state.

Example

struct TraceCriterion <: AbstractCriterion end
(::TraceCriterion)(F::Symmetric) = tr(F)

struct ACriterion <: CorleoneOED.AbstractCriterion

Minimizes $\operatorname{tr}(F^{-1})$. This is an A-optimality criterion and is defined for a nonsingular symmetric Fisher information matrix.

struct DCriterion <: CorleoneOED.AbstractCriterion

Minimizes $\det(F^{-1})$ for a nonsingular symmetric Fisher information matrix.

struct ECriterion <: CorleoneOED.AbstractCriterion

Minimizes the largest eigenvalue of $F^{-1}$ for a symmetric Fisher information matrix.

struct FisherACriterion <: CorleoneOED.AbstractCriterion

Maximizes $\operatorname{tr}(F)$ by minimizing its negative.

struct FisherECriterion <: CorleoneOED.AbstractCriterion

Maximizes the smallest eigenvalue of F by minimizing its negative.

struct FisherDCriterion <: CorleoneOED.AbstractCriterion

Maximizes $\det(F)$ by minimizing its negative.

load_benchmarks()

Loads all benchmark problem constructors from the problems directory.

Returns

A vector of benchmark constructor functions. Each function accepts a benchmark grid configuration and returns the corresponding optimal control problem data.

run_all(benchmarks, optimizer, grids)

Runs each benchmark problem with the Corleone benchmark solver.

Arguments

• benchmarks: Iterable of benchmark constructor functions, such as the result of load_benchmarks().
• optimizer: Optimization solver passed to solve_with_corleone.
• grids: Grid configuration passed to each benchmark constructor.

Returns

A vector of named tuples containing each benchmark name and measured runtime placeholder.

struct OptimalControlBenchmark

Description of one benchmark problem registered by load_benchmarks.

Fields

• name: Stable identifier used in benchmark output.

• description: Human-readable description of the problem.

• make_problem: Callable accepting BenchmarkGrids and returning benchmark problem data.

This is a developer type. Benchmark packages should provide a constructor with the same callable contract as make_problem rather than depending on implementation details of the benchmark registry.

struct BenchmarkGrids

The grids used by an optimal-control benchmark constructor.

Fields

• control_grid: Control discretization points.

• shooting_grid: Multiple-shooting points.

• constraint_grid: Points at which path or terminal constraints are evaluated.

Usage contract

Each grid contains the time points used for the corresponding discretization. A benchmark constructor accepts a BenchmarkGrids value and returns the problem data consumed by run_all.