Public API

InitialGuess

Initial guess module for CTModels.

This module provides types and functions for constructing and managing initial guesses for optimal control problems. Initial guesses help warm-start numerical solvers by providing starting trajectories for state, control, and variables.

Public API

The following functions are exported and accessible as CTModels.function_name():

• initial_guess: Construct a validated initial guess
• pre_initial_guess: Create a pre-initialization object

Types

• InitialGuess: Validated initial guess with callable trajectories
• PreInitialGuess: Pre-initialization container for raw data

See also: CTModels

abstract type AbstractInitialGuess

Abstract base type for initial guesses used in optimal control problem solvers.

Subtypes provide initial trajectories for state, control, and optimisation variables to warm-start numerical solvers.

See also: InitialGuess.

abstract type AbstractPreInitialGuess

Abstract base type for pre-initialisation data used before constructing a full initial guess.

Subtypes store raw or partial information that will be processed into an InitialGuess.

See also: PreInitialGuess.

struct InitialGuess{X<:Function, U<:Function, V} <: CTModels.Init.AbstractInitialGuess

Concrete initial guess for an optimal control problem, storing callable trajectories for state and control, and a value for the optimisation variable.

Fields

• state::X: A function t -> x(t) returning the state guess at time t.
• control::U: A function t -> u(t) returning the control guess at time t.
• variable::V: The initial guess for the optimisation variable (scalar or vector).

Example

julia> using CTModels

julia> x_guess = t -> [cos(t), sin(t)]
julia> u_guess = t -> [0.5]
julia> v_guess = [1.0, 2.0]
julia> ig = CTModels.InitialGuess(x_guess, u_guess, v_guess)

struct PreInitialGuess{SX, SU, SV} <: CTModels.Init.AbstractPreInitialGuess

Pre-initialisation container for initial guess data before validation and interpolation.

Fields

• state::SX: Raw state data (e.g., matrix, vector of vectors, or function).
• control::SU: Raw control data (e.g., matrix, vector of vectors, or function).
• variable::SV: Raw optimisation variable data (scalar, vector, or nothing).

Example

julia> using CTModels

julia> pre = CTModels.PreInitialGuess([1.0 2.0; 3.0 4.0], [0.5, 0.6], [1.0])

build_initial_guess(
    ocp::CTModels.OCP.AbstractModel,
    init_data
) -> CTModels.Init.AbstractInitialGuess

Build and validate an initial guess from various input formats.

Accepts multiple input types, converts them to an InitialGuess, and validates dimensions against the problem definition. This is the single entry point that guarantees a validated initial guess.

Supported input types:

• nothing or (): Returns default initial guess.
• AbstractInitialGuess: Validates and returns.
• AbstractPreInitialGuess: Converts from pre-initialisation.
• AbstractSolution: Warm-starts from a previous solution.
• NamedTuple: Parses named fields for state, control, and variable.

Arguments

• ocp::AbstractModel: The optimal control problem.
• init_data: The initial guess data in one of the supported formats.

Returns

• InitialGuess: A validated initial guess.

Throws

• Exceptions.IncorrectArgument: If init_data has an unsupported type or if dimensions do not match the problem definition.

Example

julia> using CTModels

julia> init = CTModels.build_initial_guess(ocp, (state=t -> [0.0], control=t -> [1.0]))

initial_control(
    _::CTModels.OCP.AbstractModel,
    control::Function
) -> Function

Return the control function directly when provided as a function.

initial_control(
    ocp::CTModels.OCP.AbstractModel,
    control::Real
) -> CTModels.Init.var"#initial_control##0#initial_control##1"{<:Real}

Convert a scalar control value to a constant function for 1D control problems.

Throws Exceptions.IncorrectArgument if the control dimension is not 1.

initial_control(
    ocp::CTModels.OCP.AbstractModel,
    control::Vector{<:Real}
) -> CTModels.Init.var"#initial_control##2#initial_control##3"{Vector{var"#s203"}} where var"#s203"<:Real

Convert a control vector to a constant function.

Throws Exceptions.IncorrectArgument if the vector length does not match the control dimension.

initial_control(
    ocp::CTModels.OCP.AbstractModel,
    _::Nothing
) -> Union{CTModels.Init.var"#initial_control##4#initial_control##5", CTModels.Init.var"#initial_control##6#initial_control##7", CTModels.Init.var"#initial_control##8#initial_control##9"{Int64}}

Return a default control initialisation function when no control is provided.

Returns a constant function yielding Float64[] (empty) if dim == 0, 0.1 (scalar) if dim == 1, or fill(0.1, dim) (vector) otherwise.

initial_control(
    ocp::CTModels.OCP.AbstractModel,
    control::Tuple
) -> Union{Nothing, Function}

Handle time-grid control initialization with (time, data) tuple.

Interpolates the provided data over the time grid to create a callable function.

initial_guess(
    ocp::CTModels.OCP.AbstractModel;
    state,
    control,
    variable
) -> CTModels.Init.InitialGuess{X, U, V} where {X<:Union{CTModels.Init.var"#initial_state##4#initial_state##5", CTModels.Init.var"#initial_state##6#initial_state##7"{Int64}}, U<:Union{CTModels.Init.var"#initial_control##4#initial_control##5", CTModels.Init.var"#initial_control##6#initial_control##7", CTModels.Init.var"#initial_control##8#initial_control##9"{Int64}}, V<:Union{Float64, Vector{Float64}}}

Construct an initial guess for an optimal control problem.

Builds an InitialGuess from the provided state, control, and variable data. The returned initial guess is not validated against the problem dimensions; use build_initial_guess or validate_initial_guess for dimension checking.

Arguments

• ocp::AbstractModel: The optimal control problem.
• state: State initialisation (function t -> x(t), constant, vector, or nothing).
• control: Control initialisation (function t -> u(t), constant, vector, or nothing).
• variable: Variable initialisation (scalar, vector, or nothing).

Returns

• InitialGuess: An initial guess (not yet validated).

Example

julia> using CTModels

julia> init = CTModels.initial_guess(ocp; state=t -> [0.0, 0.0], control=t -> [1.0])

initial_state(
    _::CTModels.OCP.AbstractModel,
    state::Function
) -> Function

Return the state function directly when provided as a function.

initial_state(
    ocp::CTModels.OCP.AbstractModel,
    state::Real
) -> CTModels.Init.var"#initial_state##0#initial_state##1"{<:Real}

Convert a scalar state value to a constant function for 1D state problems.

Throws Exceptions.IncorrectArgument if the state dimension is not 1.

initial_state(
    ocp::CTModels.OCP.AbstractModel,
    state::Vector{<:Real}
) -> CTModels.Init.var"#initial_state##2#initial_state##3"{Vector{var"#s203"}} where var"#s203"<:Real

Convert a state vector to a constant function.

Throws Exceptions.IncorrectArgument if the vector length does not match the state dimension.

initial_state(
    ocp::CTModels.OCP.AbstractModel,
    _::Nothing
) -> Union{CTModels.Init.var"#initial_state##4#initial_state##5", CTModels.Init.var"#initial_state##6#initial_state##7"{Int64}}

Return a default state initialisation function when no state is provided.

Returns a constant function yielding 0.1 (scalar) or fill(0.1, dim) (vector).

initial_state(
    ocp::CTModels.OCP.AbstractModel,
    state::Tuple
) -> Union{Nothing, Function}

Handle time-grid state initialization with (time, data) tuple.

Interpolates the provided data over the time grid to create a callable function.

initial_variable(
    ocp::CTModels.OCP.AbstractModel,
    variable::Real
) -> Real

Return a scalar variable value for 1D variable problems.

Throws Exceptions.IncorrectArgument if the variable dimension is not 1.

initial_variable(
    ocp::CTModels.OCP.AbstractModel,
    variable::Vector{<:Real}
) -> Vector{<:Real}

Return a variable vector.

Throws Exceptions.IncorrectArgument if the vector length does not match the variable dimension.

initial_variable(
    ocp::CTModels.OCP.AbstractModel,
    _::Nothing
) -> Union{Float64, Vector{Float64}}

Return a default variable initialisation when no variable is provided.

Returns an empty vector if dim == 0, 0.1 if dim == 1, or fill(0.1, dim) otherwise.

initial_variable(
    ocp::CTModels.OCP.AbstractModel,
    variable::Tuple
) -> Union{Nothing, Function}

Handle time-grid variable initialization with (time, data) tuple.

Interpolates the provided data over the time grid to create a callable function.

pre_initial_guess(
;
    state,
    control,
    variable
) -> CTModels.Init.PreInitialGuess{Nothing, Nothing, Nothing}

Create a pre-initialisation object for an initial guess.

This function creates an PreInitialGuess that can later be processed into a full InitialGuess.

Arguments

• state: Raw state initialisation data (function, vector, matrix, or nothing).
• control: Raw control initialisation data (function, vector, matrix, or nothing).
• variable: Raw variable initialisation data (scalar, vector, or nothing).

Returns

• PreInitialGuess: A pre-initialisation container.

Example

julia> using CTModels

julia> pre = CTModels.pre_initial_guess(state=t -> [0.0, 0.0], control=t -> [1.0])

validate_initial_guess(
    ocp::CTModels.OCP.AbstractModel,
    init::CTModels.Init.AbstractInitialGuess
) -> CTModels.Init.AbstractInitialGuess

Validate an initial guess against an optimal control problem.

Checks that the state, control, and variable dimensions of the initial guess are consistent with the problem definition. This function can be called explicitly on a manually constructed InitialGuess.

Arguments

• ocp::AbstractModel: The optimal control problem.
• init::AbstractInitialGuess: The initial guess to validate.

Returns

• AbstractInitialGuess: The validated initial guess (same object).

Throws

• Exceptions.IncorrectArgument: If dimensions do not match the problem definition.