Private API

Define an optimal control problem. One pass parsing of the definition. Can be used writing either ocp = @def begin ... end or @def ocp begin ... end. In the second case, setting log to true will display the parsing steps.

Example

ocp = @def begin
    tf ∈ R, variable
    t ∈ [ 0, tf ], time
    x ∈ R², state
    u ∈ R, control
    tf ≥ 0
    -1 ≤ u(t) ≤ 1
    q = x₁
    v = x₂
    q(0) == 1
    v(0) == 2
    q(tf) == 0
    v(tf) == 0
    0 ≤ q(t) ≤ 5,       (1)
    -2 ≤ v(t) ≤ 3,      (2)
    ẋ(t) == [ v(t), u(t) ]
    tf → min
end

@def ocp begin
    tf ∈ R, variable
    t ∈ [ 0, tf ], time
    x ∈ R², state
    u ∈ R, control
    tf ≥ 0
    -1 ≤ u(t) ≤ 1
    q = x₁
    v = x₂
    q(0) == 1
    v(0) == 2
    q(tf) == 0
    v(tf) == 0
    0 ≤ q(t) ≤ 5,       (1)
    -2 ≤ v(t) ≤ 3,      (2)
    ẋ(t) == [ v(t), u(t) ]
    tf → min
end true # final boolean to show parsing log

Prefix reference for the error-handling backend used in generated code.

This Ref stores the symbol of the module that defines the ParsingError type used by __throw and __wrap.

Prefix reference for the ExaModels backend used in generated code.

This Ref stores the symbol of the module that implements the ExaModels backend targeted by @def when backend = :exa.

Prefix reference for the functional backend used in generated code.

This Ref stores the symbol of the module that implements the functional backend targeted by @def when backend = :fun.

mutable struct ParsingInfo

Fields

__init_aliases(
;
    max_dim
) -> OrderedCollections.OrderedDict{Symbol, Union{Expr, Real, Symbol}}

Initialise the dictionary of textual aliases for the parser.

This includes mappings such as R₁, R₂, … for powers of R, and ASCII fallbacks like <= → ≤, >= → ≥, => → →, etc.

__symgen(s...) -> Any

Generate a fresh symbol by concatenating the given components and a gensym() suffix.

This is used throughout the parser to create unique internal names that do not collide with user-defined identifiers.

__throw(mess, n, line) -> Expr

Helper to build a static ParsingError expression.

This is used for syntactic and semantic errors detected at macro expansion time. It formats the message with line information and wraps it in a throw(ParsingError(...)) expression using the current e_prefix.

__wrap(e, n, line) -> Expr

Wrap a block of generated code with line-aware error reporting.

The returned expression executes e inside a try/catch block and, in case of an exception, prints the originating line number and source text before rethrowing.

activate_backend(backend)

Activate parsing backend. Possible choices: :exa.

as_range(x) -> Any

Return x itself if it is a range, or a one-element array [x].

This is a normalisation helper used when interpreting constraint indices.

deactivate_backend(backend)

Deactivate parsing backend. Possible choices: :exa.

def_exa(e; log) -> Expr

Core computation used to discretise, parsing an expression towards an ExaModels.ExaModel.

def_fun(e; log) -> Expr

Core computation of @def macro, parsing an expression towards a CTModels.Model.

e_prefix() -> Symbol

Return the current error-handling backend prefix.

e_prefix!(p)

Set the error-handling backend prefix used in generated code.

is_active_backend(backend) -> Bool

Check whether backend is active or not.

is_range(x) -> Union{Missing, Bool}

Return true if x represents a range.

This predicate is specialised for AbstractRange values and for expressions of the form i:j or i:p:j.

parse!(p, p_ocp, e; log, backend) -> Any

Parse the expression e and update the ParsingInfo structure p.

Example

parse!(p, :p_ocp, :(v ∈ R, variable))

parsing(s, backend) -> Function

Call the primitive associated with symbol s (:alias, etc.) for the associated backend.

prefix_exa() -> Symbol

Return the current ExaModels backend prefix.

prefix_exa!(p)

Set the ExaModels backend prefix used for generated code.

prefix_fun() -> Symbol

Return the current functional backend prefix.

This is the symbol of the module that will be used for the functional backend when expanding @def with backend = :fun.

prefix_fun!(p)

Set the functional backend prefix.

This updates PREFIX_FUN, thereby changing which module is used as the functional backend for code generated by @def.