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.

Organisation

• types.jl: Abstract and concrete initial guess types (CTModels.Init.InitialGuess, CTModels.Init.PreInitialGuess)
• utils.jl: Time grid and data formatting helpers (CTModels.Init._format_time_grid, CTModels.Init._format_init_data_for_grid)
• state.jl: State initialisation functions (CTModels.Init.initial_state)
• control.jl: Control initialisation functions (CTModels.Init.initial_control)
• variable.jl: Variable initialisation functions (CTModels.Init.initial_variable)
• builders.jl: Component-level and time-grid builders (CTModels.Init._build_block_with_components, CTModels.Init._build_time_dependent_init)
• validation.jl: Validation and construction from various formats (CTModels.Init._validate_initial_guess, CTModels.Init._initial_guess_from_solution)
• api.jl: Public API for initial guess construction (CTModels.Init.initial_guess, CTModels.Init.build_initial_guess, CTModels.Init.validate_initial_guess)

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
• build_initial_guess: Build and validate an initial guess from various formats
• validate_initial_guess: Validate an initial guess against a problem
• initial_state: State initialisation helper
• initial_control: Control initialisation helper
• initial_variable: Variable initialisation helper

Types

• CTModels.Init.InitialGuess: Validated initial guess with callable trajectories
• CTModels.Init.PreInitialGuess: Pre-initialization container for raw data
• CTModels.Init.AbstractInitialGuess: Abstract base type for initial guesses
• CTModels.Init.AbstractPreInitialGuess: Abstract base type for pre-initialization data

Dependencies

External: CTBase.Core, CTBase.Interpolation, CTBase.Exceptions.

See also: CTModels.Components, CTModels.Models, CTModels.Solutions, CTModels.Building.

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: CTModels.Init.InitialGuess, CTModels.Init.PreInitialGuess.

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 CTModels.Init.InitialGuess.

See also: CTModels.Init.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)

See also: CTModels.Init.AbstractInitialGuess, CTModels.Init.PreInitialGuess.

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])

See also: CTModels.Init.AbstractPreInitialGuess, CTModels.Init.InitialGuess.

build_initial_guess(
    ocp::CTModels.Models.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.
• Solutions.AbstractSolution: Warm-starts from a previous solution.
• NamedTuple: Parses named fields for state, control, and variable.

Arguments

• ocp::Models.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]))

See also: CTModels.Init.initial_guess, CTModels.Init.validate_initial_guess.

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

Return the control function directly when provided as a function.

Arguments

• ocp::Models.AbstractModel: The optimal control problem (unused).
• control::Function: The control function t -> u(t).

Returns

• Function: The control function unchanged.

See also: CTModels.Init.initial_control for other input types.

initial_control(
    ocp::CTModels.Models.AbstractModel,
    control::Real
) -> CTModels.Components.ConstantInTime{V} where V<:Real

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• control::Real: The scalar control value.

Returns

• Function: A constant function t -> control.

Throws

• Exceptions.IncorrectArgument: If the control dimension is not 1 or is 0.

initial_control(
    ocp::CTModels.Models.AbstractModel,
    control::Vector{<:Real}
) -> CTModels.Components.ConstantInTime{V} where V<:(Vector{<:Real})

Convert a control vector to a constant function.

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• control::Vector{<:Real}: The control vector.

Returns

• Function: A constant function t -> control.

Throws

• Exceptions.IncorrectArgument: If the vector length does not match the control dimension.

initial_control(
    ocp::CTModels.Models.AbstractModel,
    _::Nothing
) -> Union{CTModels.Components.ConstantInTime{Float64}, CTModels.Components.ConstantInTime{Vector{Float64}}}

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• ::Nothing: Indicates no control provided.

Returns

• Function: 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.Models.AbstractModel,
    control::Tuple
) -> Union{Nothing, Function}

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• control::Tuple: A 2-tuple (time, data) for time-grid interpolation.

Returns

• Function: An interpolated function t -> u(t).

Throws

• Exceptions.IncorrectArgument: If the tuple is not a 2-tuple.

See also: CTModels.Init._build_time_dependent_init.

initial_guess(
    ocp::CTModels.Models.AbstractModel;
    state,
    control,
    variable
) -> CTModels.Init.InitialGuess{X, U, V} where {X<:Union{CTModels.Components.ConstantInTime{Float64}, CTModels.Components.ConstantInTime{Vector{Float64}}}, U<:Union{CTModels.Components.ConstantInTime{Float64}, CTModels.Components.ConstantInTime{Vector{Float64}}}, 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::Models.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])

See also: CTModels.Init.build_initial_guess, CTModels.Init.validate_initial_guess.

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

Return the state function directly when provided as a function.

Arguments

• ocp::Models.AbstractModel: The optimal control problem (unused).
• state::Function: The state function t -> x(t).

Returns

• Function: The state function unchanged.

See also: CTModels.Init.initial_state for other input types.

initial_state(
    ocp::CTModels.Models.AbstractModel,
    state::Real
) -> CTModels.Components.ConstantInTime{V} where V<:Real

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• state::Real: The scalar state value.

Returns

• Function: A constant function t -> state.

Throws

• Exceptions.IncorrectArgument: If the state dimension is not 1.

initial_state(
    ocp::CTModels.Models.AbstractModel,
    state::Vector{<:Real}
) -> CTModels.Components.ConstantInTime{V} where V<:(Vector{<:Real})

Convert a state vector to a constant function.

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• state::Vector{<:Real}: The state vector.

Returns

• Function: A constant function t -> state.

Throws

• Exceptions.IncorrectArgument: If the vector length does not match the state dimension.

initial_state(
    ocp::CTModels.Models.AbstractModel,
    _::Nothing
) -> Union{CTModels.Components.ConstantInTime{Float64}, CTModels.Components.ConstantInTime{Vector{Float64}}}

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• ::Nothing: Indicates no state provided.

Returns

• Function: A constant function yielding 0.1 (scalar) or fill(0.1, dim) (vector).

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

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• state::Tuple: A 2-tuple (time, data) for time-grid interpolation.

Returns

• Function: An interpolated function t -> x(t).

Throws

• Exceptions.IncorrectArgument: If the tuple is not a 2-tuple.

See also: CTModels.Init._build_time_dependent_init.

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

Return a scalar variable value for 1D variable problems.

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• variable::Real: The scalar variable value.

Returns

• Real: The variable value.

Throws

• Exceptions.IncorrectArgument: If the variable dimension is not 1 or is 0.

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

Return a variable vector.

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• variable::Vector{<:Real}: The variable vector.

Returns

• Vector{<:Real}: The variable vector unchanged.

Throws

• Exceptions.IncorrectArgument: If the vector length does not match the variable dimension.

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

Return a default variable initialisation when no variable is provided.

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• ::Nothing: Indicates no variable provided.

Returns

• Union{Vector{<:Real}, Real}: An empty vector if dim == 0, 0.1 if dim == 1, or fill(0.1, dim) otherwise.

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

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

Arguments

• ocp::Models.AbstractModel: The optimal control problem.
• variable::Tuple: A 2-tuple (time, data) for time-grid interpolation.

Returns

• Function: An interpolated function t -> v(t).

Throws

• Exceptions.IncorrectArgument: If the tuple is not a 2-tuple.

See also: CTModels.Init._build_time_dependent_init.

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])

See also: CTModels.Init.initial_guess, CTModels.Init.build_initial_guess.

validate_initial_guess(
    ocp::CTModels.Models.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::Models.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.

See also: CTModels.Init.build_initial_guess, CTModels.Init.initial_guess.