Private API

@init ocp begin
    ...
end

Build an initial guess object for an optimal control problem from a small initialisation DSL.

The block following @init is interpreted as a collection of assignment rules for the state, control and variable components of an optimal control problem, using a compact syntax of the form

q(t) := sin(t)     # time-dependent function
x(T) := X          # time grid and associated samples
u := 0.1           # constant value
a = 1.0           # ordinary Julia alias (not part of the initial guess)
v(t) := a         # time-dependent function using the alias above

The macro itself only rewrites this DSL into a NamedTuple-based representation. All dimensional checks, interpretation of aliases and construction of the concrete initial guess object are delegated to the backend selected by init_prefix (by défaut :CTModels), via build_initial_guess and validate_initial_guess.

An optional keyword-like trailing argument controls logging:

ig = @init ocp begin
    u(t) := t
end log = true

When log = true, the macro additionally prints a human-readable NamedTuple-like representation of the specification.

Arguments

• ocp: symbolic optimal control problem built with @def.
• begin ... end: block containing the initialisation DSL.
• log: optional Boolean keyword (default false) enabling textual logging of the parsed specification.

Returns

• AbstractInitialGuess: backend-specific initial guess object produced by the current backend (par défaut CTModels).

Example

julia> using CTParser

julia> ocp = @def begin
           t ∈ [0, 1], time
           x ∈ R, state
           u ∈ R, control
           ẋ(t) == u(t)
           x(0) == 0
           x(1) == 0
           ∫(0.5u(t)^2) → min
       end

julia> ig = @init ocp begin
           u(t) := t
       end

julia> ig isa CTModels.AbstractInitialGuess
true

Current backend prefix used by @init.

This reference stores the symbol of the backend module that provides build_initial_guess and validate_initial_guess. It is initialised by __default_init_prefix and can be updated at runtime via init_prefix!.

__default_init_prefix() -> Symbol

Return the default backend prefix used by @init.

The returned symbol identifies the module that implements build_initial_guess and validate_initial_guess. In the current implementation this is :CTModels.

Returns

• Symbol: name of the default backend module.

Example

julia> using CTParser

julia> CTParser.__default_init_prefix()
:CTModels

__gen_spec_value(pref, ocp, spec) -> Tuple{Symbol, Expr}

Generate runtime code for a single initialisation specification.

This function dispatches based on the specification kind (:constant or :temporal) and delegates to the appropriate code generator.

Arguments

• pref::Symbol: backend module prefix.
• ocp: symbolic OCP variable.
• spec::Tuple: specification tuple, either (:constant, rhs) or (:temporal, arg, rhs, arg_in_rhs).

Returns

• val_sym::Symbol: generated symbol to store the value.
• code::Expr: expression to insert in the generated code.

__gen_temporal_value(
    pref,
    ocp,
    arg,
    rhs,
    arg_in_rhs
) -> Tuple{Symbol, Expr}

Generate runtime code for a temporal specification lhs(arg) := rhs.

This function produces the Julia expression that will be evaluated at runtime to determine whether the specification represents a time-dependent function or a time grid, based on whether arg matches time_name(ocp).

Arguments

• pref::Symbol: backend module prefix (e.g. :CTModels).
• ocp: symbolic OCP variable passed from the macro.
• arg: argument used in the specification (e.g. :t, :s, or a literal array after alias expansion).
• rhs: right-hand side expression.
• arg_in_rhs::Bool: whether arg appears in rhs (computed at parse-time via has).

Returns

• val_sym::Symbol: generated symbol to store the computed value.
• code::Expr: expression block to insert in the generated code.

Notes

When arg is not a Symbol (e.g., a literal array after alias expansion like [0.0, 0.5, 1.0]), it is always treated as a time grid specification.

When arg is a Symbol and arg_in_rhs is true, the specification is definitely a time-dependent function, so we validate that arg == Symbol(time_name(ocp)) and throw an error if not. When arg_in_rhs is false, we generate a runtime conditional that checks whether arg matches the time name to decide between a constant function or a time grid.

__log_spec(key, spec) -> String

Format a single initialisation specification for logging.

This function produces a human-readable string representation of a specification, used when log = true is passed to @init.

Arguments

• key::Symbol: component name (e.g. :u, :x).
• spec::Tuple: specification tuple.

Returns

• String: formatted string like "u = t -> sin(t)" or "x = 1.0".

_collect_init_specs(
    ex,
    lnum::Int64,
    line_str::String
) -> Tuple{Vector{Symbol}, Vector{Tuple}}

Internal helper that parses the body of an @init block.

The function walks through the expression ex and splits it into

• alias statements of the form lhs = rhs, which are stored in a dictionary and substituted into subsequent statements at parse-time using subs;
• initialisation specifications of the form lhs := rhs or lhs(arg) := rhs, which are converted into structured specification tuples after alias expansion.

For expressions of the form lhs(arg) := rhs, this function uses has(rhs, arg) to determine whether arg appears in the right-hand side. This information is stored in the specification tuple and used later to generate appropriate runtime code that distinguishes time-dependent functions from time grids.

Alias substitution happens before each statement is matched, enabling time-dependent aliases like phi = 2π * t and accumulated aliases like a = t; s = a.

Arguments

• ex::Any: expression or block coming from the body of @init.
• lnum::Int: line number for error reporting.
• line_str::String: line string for error reporting.

Returns

• keys::Vector{Symbol}: names of the components being initialised (e.g. :q, :v, :u, :tf).
• specs::Vector{Tuple}: specification tuples, either (:constant, rhs) for constant values or (:temporal, arg, rhs, arg_in_rhs) for temporal specifications where arg_in_rhs indicates whether arg appears in rhs.

init_fun(
    ocp,
    e,
    lnum::Int64,
    line_str::String
) -> Tuple{String, Expr}

Lowering function used by @init to build the expanded code.

Given an optimal control problem ocp and the body e of an @init block, this function collects the initialisation specifications, builds an appropriate NamedTuple expression and constructs the call to build_initial_guess / validate_initial_guess on the current backend (prefix returned by init_prefix).

It also produces a compact string representation of the specification, used for optional logging when log = true is requested at the macro level.

Arguments

• ocp: symbolic optimal control problem built with @def.
• e: expression corresponding to the body of the @init block.
• lnum::Int: line number for error reporting.
• line_str::String: line string for error reporting.

Returns

• log_str::String: human-readable NamedTuple-like description of the specification.
• code_expr::Expr: block of Julia code that builds and validates the initial guess when executed.

init_prefix() -> Symbol

Return the current backend prefix used by @init.

This is the symbol of the module that will be used to interpret the NamedTuple produced by the initialisation DSL, typically :CTModels.

Returns

• Symbol: name of the backend module currently used by @init.

Example

julia> using CTParser

julia> CTParser.init_prefix()
:CTModels

init_prefix!(p)

Set the backend prefix used by @init.

This function updates the global INIT_PREFIX, thereby changing which module is used to build and validate initial guesses.

Arguments

• p::Symbol: name of the backend module to use (e.g. :CTModels).

Returns

• Nothing.

Example

julia> using CTParser

julia> old = CTParser.init_prefix();

julia> CTParser.init_prefix!(:MyBackend)

julia> CTParser.init_prefix()
:MyBackend

julia> CTParser.init_prefix!(old);  # restore