Private API
This page lists non-exported (internal) symbols of CTParser.
From CTParser
@def [Macro]
CTParser.@def — Macro
@def eDefine 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 logEXA_SCHEMES [Constant]
CTParser.EXA_SCHEMES — Constant
Numerical schemes accepted by the :exa backend. Their aliases, EXA_SCHEME_ALIASES, are accepted too but not advertised. Keep in sync with the scheme branches of p_dynamics_exa!, p_dynamics_coord_exa! and p_lagrange_exa!.
EXA_SCHEME_ALIASES [Constant]
CTParser.EXA_SCHEME_ALIASES — Constant
Aliases of the :exa schemes, resolved to their canonical name (EXA_SCHEMES) at the top of the generated model builder, so the scheme branches only know canonical names. :euler_explicit and :euler_forward (aliases of :euler) and :euler_backward (alias of :euler_implicit) are the names the :adnlp modeler of CTDirect accepts; :euler_b and :trapezoidal are deprecated.
ParsingInfo [Struct]
CTParser.ParsingInfo — Type
mutable struct ParsingInfoFields
__constraint_parts [Function]
CTParser.__constraint_parts — Function
__constraint_parts(
e
) -> Union{Nothing, Tuple{Any, Any, Any}}Return the operands (e1, e2, e3) of a constraint statement e as they are passed to p_constraint!: the lower bound e1, the constrained expression e2 and the upper bound e3, where a missing bound is nothing and an equality a == b has the bound b on both sides. Return nothing if e is not a constraint.
It mirrors the constraint patterns of parse! and is used on the statement as the user wrote it, to show the operands in an error message.
__fill [Function]
CTParser.__fill — Function
__fill(r, e) -> ExprBuild the code that writes the value of e into the output array r of a generated function (dynamics, boundary or path constraint).
When e is a vector literal without splat, [e₁, e₂, …], the generated code evaluates the n entries into local variables, checks that r has n entries, then assigns them one by one: the temporary vector that @views r[:] .= [e₁, e₂, …] allocates at every call is avoided. The entries are evaluated before any assignment, so the result is the same when r shares memory with an input. Any other expression is broadcast, as before.
__find_call [Function]
CTParser.__find_call — Function
__find_call(
e,
sym
) -> Union{Nothing, Base.AnnotatedString{String}, String}Return the arguments, as a string, of the first call of sym (sym(args) or sym[i](args)) found in e, or nothing if sym appears in e only without being called with an argument.
__init_aliases [Function]
CTParser.__init_aliases — Function
__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.
__is_alias_redefinition [Function]
CTParser.__is_alias_redefinition — Function
__is_alias_redefinition(p, e)Tell whether the statement e is name = body where name is an alias already defined.
It is tested before the aliases are substituted: afterwards c = 7 has become 5 = 7, and the name of the alias is lost.
__is_equation_with_assign [Function]
CTParser.__is_equation_with_assign — Function
__is_equation_with_assign(e) -> Union{Missing, Bool}Tell whether the statement e has the shape f(args) = body.
Julia reads it as a short function definition. In the DSL it is a mistake: an alias has a name and no arguments, and an equation, for instance the dynamics ẋ(t) = u(t), is written with ==. It is tested before the aliases are substituted, so that the error shows what the user wrote (ẋ(t), not the internal ∂(x)(t)).
__is_malformed_declaration [Function]
CTParser.__is_malformed_declaration — Function
__is_malformed_declaration(e1) -> Union{Missing, Bool}Tell whether the right-hand side e1 of a = e1 has the shape of a declaration with named components, (names) ∈ dom, kind with kind one of state, control or variable.
It is called on the right-hand sides that none of the valid declaration patterns of parse! matched (the domain is not R^n). Without this test such a line would silently become an alias, and nothing would be declared.
__is_named_scalar [Function]
CTParser.__is_named_scalar — Function
__is_named_scalar(components_names, q)Tell whether a declaration names the components (components_names) of an element of dimension q = 1, for example u = (z,) ∈ R^1, control.
A one-dimensional variable, state or control is a scalar whose only component has the name of the element: naming it separately would give two names to one scalar, and the declaration u = (z,) ∈ R, control is already refused. The two spellings of dimension one, R and R^1, are treated alike.
__stray_error [Function]
CTParser.__stray_error — Function
__stray_error(p, e) -> Union{Nothing, Expr}Look in the expression e of a statement for the state or the control used without being evaluated at a time of the problem, and return the ParsingError expression for the first one found, or nothing.
The state and the control are functions of time. In e, x(t) and u(t) (and the same at the initial and the final time, x(t0), x(tf)) are the legitimate uses; once they are replaced, any x or u left over is a mistake: a bare x₁ or u, or a call with another time, as in x₁(0.5). Without this test the mistake goes through the parser, and fails late or not at all, if a variable of the same name exists where the model is evaluated.
__throw [Function]
CTParser.__throw — Function
__throw(mess, n, line; suggestion) -> ExprHelper 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 qualified on ERR (CTBase).
The optional suggestion keyword says how to fix the error; it is stored in the suggestion field of the ParsingError.
__throw_alias_redefinition [Function]
CTParser.__throw_alias_redefinition — Function
__throw_alias_redefinition(p, e) -> ExprBuild the ParsingError expression for the redefinition of an alias, see __is_alias_redefinition.
__throw_dependent_bound [Function]
CTParser.__throw_dependent_bound — Function
__throw_dependent_bound(
p,
e1,
e2,
e3,
side,
b,
what
) -> ExprBuild the ParsingError expression for a constraint e1 ≤ e2 ≤ e3 whose bound b (side is "lower" or "upper") depends on what, which a bound cannot do: bounds are evaluated once, when the model is built.
The suggestion is built from the constraint itself:
- an equality
e2 == b:e2 - b == 0; - the constrained expression
e2does not depend on anything, the bound does (the two sides are in the wrong order, as in1 ≤ x₂(t)): the same constraint with the sides swapped,x₂(t) ≥ 1; - otherwise: the term moved to the constrained side,
e2 - b ≤ 0(b - e2 ≤ 0for a lower bound).
__throw_equation_with_assign [Function]
CTParser.__throw_equation_with_assign — Function
__throw_equation_with_assign(p, e) -> ExprBuild the ParsingError expression for a statement f(args) = body, see __is_equation_with_assign. The suggestion repeats the statement with ==.
__throw_malformed_declaration [Function]
CTParser.__throw_malformed_declaration — Function
__throw_malformed_declaration(p, a, e1) -> ExprBuild the ParsingError expression for a declaration a = (names) ∈ dom, kind whose domain is not R^n, for example u = (z,) ∈ R, control.
Named components need an explicit dimension; a one-dimensional element is declared without names, a ∈ R, kind, and its only component is named a.
__throw_named_scalar [Function]
CTParser.__throw_named_scalar — Function
__throw_named_scalar(p, kind, a) -> ExprBuild the ParsingError expression for a declaration that names the components of a one-dimensional kind ("variable", "state" or "control") a, see __is_named_scalar.
__wrap [Function]
CTParser.__wrap — Function
__wrap(e, n, line) -> ExprWrap a block of generated code with selective line-aware error reporting.
The returned expression executes e inside a try/catch block. Structured CTBase.CTException values are rethrown unchanged because they already carry their own diagnostic information; other exceptions are preceded by the originating line number and source text before being rethrown.
_bound_length_check [Function]
CTParser._bound_length_check — Function
_bound_length_check(e1, e3, rg, n, line) -> ExprBuild the run-time check that the bounds e1 and e3 of a constraint have matching lengths, and, unless rg is nothing, that they also match the length of the constrained range rg.
The check is emitted into generated code because the bounds are only known at build time. It throws a PreconditionError whose context names the originating @def line (n: line): __wrap does not print that line for structured exceptions, so the exception must carry it.
_check_parsing_backend [Function]
CTParser._check_parsing_backend — Function
_check_parsing_backend(backend)Throw an IncorrectArgument unless backend is one of the known PARSING_BACKENDS.
_check_toggleable_backend [Function]
CTParser._check_toggleable_backend — Function
_check_toggleable_backend(backend)Throw unless backend is a known parsing backend that can be (de)activated: an unknown name is an IncorrectArgument, and :fun, which is always active, a PreconditionError.
_or_list [Function]
CTParser._or_list — Function
_or_list(syms)Render a tuple of symbols as the human-readable list ":a, :b or :c" used in the expected field of generated errors.
_unknown_scheme_error [Function]
CTParser._unknown_scheme_error — Function
_unknown_scheme_error() -> ExprBuild the run-time error raised by generated :exa code when the scheme keyword is not one of EXA_SCHEMES.
No source line is attached: the scheme is chosen when the model is built, not on a line of the @def block.
activate_backend [Function]
CTParser.activate_backend — Function
activate_backend(backend)Activate parsing backend. Possible choices: :exa.
deactivate_backend [Function]
CTParser.deactivate_backend — Function
deactivate_backend(backend)Deactivate parsing backend. Possible choices: :exa.
def_exa_code [Function]
CTParser.def_exa_code — Function
def_exa_code(e; log) -> ExprCore computation used to discretise, parsing an expression towards an ExaModels.ExaModel.
It is the counterpart of def_fun, and is called by the @def_exa macro and by def_fun when the :exa backend is active. It does not share its name with the macro, so that the function can be found and renamed on its own.
def_fun [Function]
CTParser.def_fun — Function
def_fun(e; log) -> ExprCore computation of @def macro, parsing an expression towards a CTModels.Model.
is_active_backend [Function]
CTParser.is_active_backend — Function
is_active_backend(backend) -> BoolCheck whether backend is active or not.
parse! [Function]
CTParser.parse! — Function
parse!(p, p_ocp, e; log, backend)Parse the expression e and update the ParsingInfo structure p.
The aliases are substituted in a single pass, in the order in which they were defined (p.aliases is ordered). This is enough because the right-hand side of an alias is itself parsed, hence expanded with the aliases known at that point: an alias value never contains an alias defined before it, and a name used before it is defined is substituted by the later alias since the later keys come after in the pass. See the tests "aliases defined from other aliases".
Example
parse!(p, :p_ocp, :(v ∈ R, variable))parsing [Function]
CTParser.parsing — Function
parsing(s, backend) -> FunctionCall the primitive associated with symbol s (:alias, etc.) for the associated backend.