Evaluating expressions¶
A PALS lattice may write numeric values as mathematical expressions —
0.3 * r_electron, a_const^2, mass_of("proton"). As part of expansion,
parse_and_expand_PALS evaluates every such expression to a plain number, so
both expanded trees are fully numeric. The original and combined views
always keep the expression text exactly as written.
The expression language itself — the grammar and its precedence, the built-in
constants, the functions, the syntax for defining constants and variables, for
Controller elements and for set commands — belongs to the PALS standard and
is documented with it at
pals-project.readthedocs.io. This page
covers what this library does with it: when evaluation happens, what it
declines to evaluate, and what it reports rather than guesses.
Constant values come from AtomicAndPhysicalConstantsCLib (APC — a C++ mirror of AtomicAndPhysicalConstants.jl, CODATA 2022), fetched automatically by CMake, so PALSParserCpp shares one set of numbers with the rest of the toolchain.
Where the standard leaves a choice¶
The standard fixes the operator precedence (^ right-associative, a unary
sign looser than ^, so -2^2 is -4 and 2^-1 is 0.5). One point it does
not settle, which this library therefore has to fix:
Species names must be quoted.
mass_of("proton")is read; an unquoted name is an error. A mass number carries a leading#—"#3He", not"3He"— matching AtomicAndPhysicalConstants.jl, and quoting is also what lets that#be written without tripping YAML’s comment rule. The argument may instead be a constant or variable whose value is a species name, passed unquoted; such a definition may also be used directly wherever a species name is expected, and a bare identifier used as a parameter value is replaced by the species string it stands for.
What gets evaluated¶
Only scalars that are genuine expressions are touched. Names that happen to sit
where a value could go — element and line references in a line:, kind:
names, booleans, a MetaP description — are not expressions and are left
alone. Immediate expressions (length: 0.3 * r_electron) and delayed ones
(Kn1: expr(3.74 * a_var)) both become numbers, but at different times:
An immediate expression is evaluated once, when its definition is reached in the
facilitylist. Asetfurther down the list does not change it, even when it writes a parameter the expression uses. What it cannot evaluate yet — a parameter only expansion computes — is evaluated after expansion.A delayed expression is evaluated after expansion and again after the
post_expansionlist, so it follows apost_expansionset on a parameter it uses. Asetwhose value is delayed stores the expression rather than its value. Control expressions are delayed by definition.
The expr(...) wrapper must enclose the whole expression; 2 * expr(a) is
reported. A constant may not be delayed, and a controller variable’s initial
value may not be either.
Inheritance follows the same order. An inherit (of an element, a group, or
another element’s group, q1>ApertureP) copies the values the source has when
the inheriting definition is reached, whether that definition stands under
facility or in place in a line (- q2: {inherit: q1}). A later set on the
source does not touch it. A line item that only uses an element (- q1, or
- q1: {length: 0.3} with values of its own) gets the element’s parameters at
branch expansion, so it does follow such a set, except where it sets a value
itself.
A value that fails to evaluate is left as text rather than aborting the
expansion, and it is reported as a problem only if it looks like one — an
operator, a parenthesis, a > reference, or an explicit expr(...). That is
what keeps a plain name or a label from being mistaken for broken arithmetic.
Some keys are excluded from evaluation outright, because their values are names
or free-form prose that could otherwise collide with a constant or parse as
arithmetic — kind, use and inherit, the fork targets, and the authors,
notes and reminders prose among them.
Constants and variables are resolved in dependency order, so a value may
reference one written later in the file as readily as one written earlier. A
reference that cannot be resolved, or a genuine cycle, leaves the value as text
and is reported. Nothing in facility may use a constant, variable or
controller defined in post_expansion.
Randomness is deferred, never invented¶
An expression that calls random() or random_gauss() is left as text, so that
expanding the same lattice twice gives byte-identical output:
Kn2: 0.01 + 0.003*random_gauss() # kept verbatim
The same rule reaches everywhere such an expression can appear: a control
expression containing one is deferred and so drives nothing, and a set whose
value calls one leaves its parameter untouched.
absolute_error and relative_error follow from the same principle. The
standard gives the error magnitude — absolute_error + relative_error * |value| — but not its distribution, so this library reads them, writes the
deterministic value, and reports a problem rather than picking a distribution
on the author’s behalf.
How sets are applied¶
A parameter of a known element that has not been written reads as zero, so
PARAMETER + 0.02 works on an element that carries no such group yet — the
group is created. The exception is a parameter that is still to be derived: if
any member of its linked family has been written (the four interchangeable forms
BnN/BnNL/KnN/KnNL of a magnetic multipole component, the two forms of an
electric one, or the tied BendP geometry), its value is the bookkeeper’s to
compute and reading it beforehand is an error:
- Q1:
kind: Quadrupole
MagneticMultipoleP:
Ks1: 0.34
- set:
parameter: Q2>MagneticMultipoleP.Bs1
value: Q1>MagneticMultipoleP.Bs1 # error: Bs1 needs the reference momentum
PARAMETER reads an unwritten parameter as its default value. For most
parameters this is zero. Where the default is null (for example
ApertureP.x_min, BendP.e1 or RFP.frequency), there is no value to read,
and using PARAMETER is an error. The same holds for a parameter written as
null.
This matters for a BeamLine line item that only uses an element, such as
- q1. Before branch expansion such an item has only the values written on
the item itself, so a facility set on main>>q1>MagneticMultipoleP.Kn1L
sees the default (zero), not the value in the q1 definition. The value the
set writes on the item then overrides the definition’s at expansion. To change
the values that line items get from the definition, put the set under
post_expansion.
Interdependent parameters¶
The members of such a family state one physical quantity in different units, so only one of them can be the statement of it. Writing one nullifies the previous settings of all the others: they are removed, and the bookkeeper derives them again from the value just written.
- s1:
kind: Sextupole
length: 0.27
MagneticMultipoleP:
Ks2: 0.34
- set:
parameter: s1>MagneticMultipoleP.Ks2L
value: 0.5
Here s1 states its skew sextupole component as Ks2 and the set restates it
as Ks2L; the Ks2 goes, and Ks2 comes back as 0.5 / 0.27. Without this
the two would be left contradicting each other and reported as inconsistent.
The rule holds for every writer that reaches a parameter from outside the
element definition — sets in facility and in post_expansion, and ABSOLUTE
controllers, which are ordered among themselves by the order they are evaluated
in. Two members written inside one element definition are a different matter:
neither is “previous”, so that stays an inconsistency for the bookkeeper to
report.
facility, post_expansion and where a set acts¶
Which list a set sits in decides what it writes:
A set in
facilityacts on the element definitions, and only on those defined earlier in the list — an element defined after it is untouched. An unqualified name reaches the construct that defines the element, whether it stands underfacilityor is defined in place in a beamline’sline(it has akindor aninheritof its own). It does not reach a line item that only uses an element defined elsewhere; that answers to a name qualified by its beamline (myline>>q1). One definition is written once, so every use of it gets the same value.A set in
post_expansionacts on the already-expanded lattice, so each copy is a separate element and is written separately. The bookkeeper has already run at this point, so a value may use computed parameters such asSELF>s_position.
The order of the passes¶
facility list, in order: inherits, immediate expressions, sets
→ branch and fork expansion
→ expression evaluation (the rest, delayed ones included)
→ ABSOLUTE controllers
→ element bookkeeper
→ post_expansion sets
→ delayed expressions evaluated again
→ ABSOLUTE controllers again
→ element bookkeeper again
Applying the controllers last is what keeps a controller authoritative over a
parameter a later set also writes. The second bookkeeper pass recomputes what
those writes invalidated: the reference, floor and position values, and the
family members a post_expansion set or a controller nullified.
The snapshot that separates expanded from full_expanded is taken between the
first expression evaluation and the first bookkeeper pass — see
The five trees.
Evaluating a single expression¶
evaluate_pals_expression evaluates one expression string on its own and
returns a double, setting an optional ok flag:
bool ok = false;
double v = evaluate_pals_expression("3.75e7 / c_light^2", &ok);
// ok == true, v == 4.172…e-10
This evaluates a standalone string, so user-defined constants and variables
are not in scope — use parse_and_expand_PALS for whole-lattice evaluation,
whose expanded trees already have every expression resolved. ok is set to
false on a parse error, an unknown identifier or species, an unquoted species
name, a random()/random_gauss() expression (intentionally deferred), or a
non-finite result.