Public API

This page lists exported symbols of CTModels.Serialization.

---

From CTModels.Serialization

CTModels.Serialization [Module]

CTModels.Serialization Module

Serialization

Serialization module for CTModels.

This module provides functions for importing and exporting optimal control solutions to various formats (JLD2, JSON).

Organisation

• types.jl: Abstract and concrete types for format tags (CTModels.Serialization.AbstractTag, CTModels.Serialization.JLD2Tag, CTModels.Serialization.JSONTag)

• export_import.jl: Public API for export/import (CTModels.Serialization.export_ocp_solution, CTModels.Serialization.import_ocp_solution)

• reconstruction_helpers.jl: Internal helpers for solution reconstruction (CTModels.Serialization._reconstruct_solution_from_data, CTModels.Serialization._extract_time_vector)

Public API

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

• export_ocp_solution: Export a solution to file

• import_ocp_solution: Import a solution from file

Supported Formats

• JLD2: Binary format (requires JLD2.jl package)

• JSON: Text format (requires JSON.jl package)

Private API

The following are internal utilities (accessible via Serialization.function_name):

• __format: Get default format

• __filename_export_import: Get default filename

See also: CTModels.Serialization.export_ocp_solution, CTModels.Serialization.import_ocp_solution.

AbstractTag [Abstract Type]

CTModels.Serialization.AbstractTag Type

abstract type AbstractTag

Abstract type for export/import functions, used to choose between JSON or JLD extensions.

See also: CTModels.Serialization.JLD2Tag, CTModels.Serialization.JSONTag.

JLD2Tag [Struct]

CTModels.Serialization.JLD2Tag Type

struct JLD2Tag <: CTModels.Serialization.AbstractTag

JLD tag for export/import functions.

Fields

No fields (empty struct used as a type tag).

See also: CTModels.Serialization.AbstractTag, CTModels.Serialization.JSONTag.

JSONTag [Struct]

CTModels.Serialization.JSONTag Type

struct JSONTag <: CTModels.Serialization.AbstractTag

JSON tag for export/import functions.

Fields

No fields (empty struct used as a type tag).

See also: CTModels.Serialization.AbstractTag, CTModels.Serialization.JLD2Tag.

export_ocp_solution [Function]

CTModels.Serialization.export_ocp_solution Function

export_ocp_solution(
    sol::CTModels.Solutions.AbstractSolution;
    format,
    filename
)

Export an optimal control solution to a file.

Arguments

• sol::AbstractSolution: The solution to export.

Keyword Arguments

• format::Symbol=:JLD: Export format, either :JLD or :JSON.

• filename::String="solution": Base filename; the extension is appended automatically, unless filename already ends with it (case-insensitively).

Returns

• Nothing: This function writes to a file and returns nothing.

Notes

Requires loading the appropriate package (JLD2 or JSON) before use.

See also: CTModels.Serialization.import_ocp_solution.

export_ocp_solution(
    ::CTModels.Serialization.JSONTag,
    sol::CTModels.Solutions.Solution;
    filename
)

Export an optimal control solution to a .json file using the JSON format.

This function serializes a CTModels.Solution into a structured JSON dictionary, including all primal and dual information, which can be read by external tools.

Arguments

• ::CTModels.JSONTag: A tag used to dispatch the export method for JSON.

• sol::CTModels.Solution: The solution to be saved.

Keyword Arguments

• filename::String = "solution": Base filename. The .json extension is appended automatically, unless filename already ends with it (case-insensitively).

Notes

The exported JSON includes the time grid, state, control, costate, objective, solver info, all constraint duals (if available), and the switching structure (switching times, phase labels, left/right limits) when the solution holds one.

Example

julia> using JSON, CTModels

julia> CTModels.export_ocp_solution(CTModels.JSONTag(), sol; filename="mysolution")
# → creates "mysolution.json"

export_ocp_solution(
    ::CTModels.Serialization.JLD2Tag,
    sol::CTModels.Solutions.Solution;
    filename
)

Export an optimal control solution to a .jld2 file using the JLD2 format.

This function serializes and saves a CTModels.Solution object to disk, allowing it to be reloaded later. The solution is discretized to avoid serialization warnings for function objects.

Arguments

• ::CTModels.JLD2Tag: A tag used to dispatch the export method for JLD2.

• sol::CTModels.Solution: The optimal control solution to be saved.

Keyword Arguments

• filename::String = "solution": Base name of the file. The .jld2 extension is appended automatically, unless filename already ends with it (case-insensitively).

Example

julia> using JLD2, CTModels

julia> CTModels.export_ocp_solution(CTModels.JLD2Tag(), sol; filename="mysolution")
# → creates "mysolution.jld2"

Notes

• A signature of the model (dimensions, names, constraint labels, times, criterion) is stored with the data, to check the file against the model at import time

• Functions are discretized on the time grid to avoid JLD2 serialization warnings

• The solution can be perfectly reconstructed via import_ocp_solution

• Uses the same discretization logic as JSON export for consistency

import_ocp_solution [Function]

CTModels.Serialization.import_ocp_solution Function

import_ocp_solution(
    ocp::CTModels.Models.AbstractModel;
    format,
    filename
) -> CTModels.Solutions.Solution{TimeGridModelType, TimesModelType, StateModelType, ControlModelType, VariableModelType, ModelType, CostateModelType, Float64, DualModelType, CTModels.Solutions.SolverInfos{Any, Dict{Symbol, Any}}, SwitchingModelType} where {TimeGridModelType<:Union{CTModels.Solutions.MultipleTimeGridModel, CTModels.Solutions.UnifiedTimeGridModel{Vector{Float64}}}, TimesModelType<:CTModels.Components.TimesModel, StateModelType<:(CTModels.Components.StateModelSolution{TS} where TS<:CTModels.Components.CoercedTrajectory), ControlModelType<:(CTModels.Components.ControlModelSolution{TS} where TS<:CTModels.Components.CoercedTrajectory), VariableModelType<:Union{CTModels.Components.VariableModelSolution{Vector{Float64}}, CTModels.Components.VariableModelSolution{Float64}}, ModelType<:(CTModels.Models.Model{<:CTBase.Traits.TimeDependence, T} where T<:CTModels.Components.TimesModel), CostateModelType<:CTModels.Components.CoercedTrajectory, DualModelType<:Union{CTModels.Solutions.EmptyDualModel, CTModels.Solutions.DualModel{PC_Dual, BC_Dual, SC_LB_Dual, SC_UB_Dual, CC_LB_Dual, CC_UB_Dual, VC_LB_Dual, VC_UB_Dual} where {PC_Dual<:Union{Nothing, CTModels.Components.CoercedTrajectory}, BC_Dual<:Union{Nothing, Vector{Float64}}, SC_LB_Dual<:Union{Nothing, CTModels.Components.CoercedTrajectory}, SC_UB_Dual<:Union{Nothing, CTModels.Components.CoercedTrajectory}, CC_LB_Dual<:Union{Nothing, CTModels.Components.CoercedTrajectory}, CC_UB_Dual<:Union{Nothing, CTModels.Components.CoercedTrajectory}, VC_LB_Dual<:Union{Nothing, Float64, Vector{Float64}}, VC_UB_Dual<:Union{Nothing, Float64, Vector{Float64}}}}, SwitchingModelType<:Union{CTModels.Solutions.EmptySwitchingModel, CTModels.Solutions.SwitchingModel}}

Import an optimal control solution from a file.

Arguments

• ocp::AbstractModel: The model associated with the solution.

Keyword Arguments

• format::Symbol=:JLD: Import format, either :JLD or :JSON.

• filename::String="solution": Base filename; the extension is appended automatically, unless filename already ends with it (case-insensitively).

Returns

• Solution: The imported solution.

Throws

• CTBase.Exceptions.IncorrectArgument: if the file cannot belong to a solution of ocp (dimensions of the state, control or variable, number or labels of the constraints, fixed versus free initial or final time). All differences are reported together; pass the model the solution was computed from.

Notes

Requires loading the appropriate package (JLD2 or JSON) before use.

Files store a signature of the model they were exported from. Differences that cannot make the solution unusable (names of the components, criterion, type of cost, values of fixed times) only produce a warning. Files exported by older versions of CTModels have no signature: only the dimensions and the time grids are then checked, and an informational message is logged.

See also: CTModels.Serialization.export_ocp_solution.

import_ocp_solution(
    ::CTModels.Serialization.JSONTag,
    ocp::CTModels.Models.Model;
    filename
)

Import an optimal control solution from a .json file exported with export_ocp_solution.

This function reads the JSON contents and reconstructs a CTModels.Solution object, including the discretized primal and dual trajectories.

Arguments

• ::CTModels.JSONTag: A tag used to dispatch the import method for JSON.

• ocp::CTModels.Model: The model associated with the optimal control problem. Used to rebuild the full solution.

Keyword Arguments

• filename::String = "solution": Base filename. The .json extension is appended automatically, unless filename already ends with it (case-insensitively).

Returns

• CTModels.Solution: A reconstructed solution instance.

Throws

• CTBase.Exceptions.IncorrectArgument: if the file does not match ocp (dimensions, number or labels of constraints, fixed versus free times). Pass the model the solution was computed from.

• CTBase.Exceptions.ParsingError: if an optional solver field has a value of the wrong type.

Notes

An unset optional solver field (iterations, constraints_violation, message, status) is written as null and read back as Core.NotProvided; the string "NotProvided", written by older versions, is read the same way.

Handles both vector and matrix encodings of signals. If dual fields are missing or null, the corresponding attributes are set to nothing.

The file is checked against ocp before the solution is rebuilt; see CTModels.Serialization.import_ocp_solution.

Example

julia> using JSON, CTModels

julia> sol = CTModels.import_ocp_solution(CTModels.JSONTag(), model; filename="mysolution")

import_ocp_solution(
    ::CTModels.Serialization.JLD2Tag,
    ocp::CTModels.Models.Model;
    filename
)

Import an optimal control solution from a .jld2 file.

This function loads a previously saved CTModels.Solution from disk and reconstructs it using build_solution from the discretized data.

Arguments

• ::CTModels.JLD2Tag: A tag used to dispatch the import method for JLD2.

• ocp::CTModels.Model: The associated optimal control problem model.

Keyword Arguments

• filename::String = "solution": Base name of the file. The .jld2 extension is appended automatically, unless filename already ends with it (case-insensitively).

Returns

• CTModels.Solution: The reconstructed solution object.

Example

julia> using JLD2, CTModels

julia> sol = CTModels.import_ocp_solution(CTModels.JLD2Tag(), model; filename="mysolution")

Throws

• CTBase.Exceptions.ParsingError: if an optional solver field has a value of the wrong type.

Notes

• An unset optional solver field (iterations, constraints_violation, message, status) is stored as nothing and read back as Core.NotProvided (Core.NotProvided stored by older versions is read the same way)

• The solution is reconstructed from discretized data via build_solution

• This ensures perfect round-trip consistency with the export

• The file does not contain the model: ocp must be the model the solution was computed from. Incompatible dimensions, constraints or times raise an IncorrectArgument; other differences (names, criterion, ...) raise a warning