eFMI® Standard

M-1.1 (syntactic term / Meta-rules, terminology): Parts of semantic rules typeset in italic refer to non-terminals; they are called syntactic term. Let N be a non-terminal referred to in a semantic rule S; let G be the syntactic rule defining N (cf. M-1.2 for uniqueness of syntactic rules). The semantic of N in S is: a code fragment F of a whole GALEC program P, where F is derived according to G throughout the derivation of P and satisfies all semantic rules amended to G.

M-1.2 (uniqueness of syntactic rules / Meta-rules): For every non-terminal N exists a single syntactic rule whose EBNF syntax-rule has N as meta-identifier (cf. ISO/IEC 14977).

M-1.3 (syntactic relations / Meta-rules, terminology): Let N₁ and N₂ be syntactic terms.

N₁ is contained in N₂, if, and only if, N₁ is derived throughout the derivation of N₂; in this case N₂ is called a container of N₁ and we say N₂ contains N₁ and N₁ is part of N₂. If, and only if, N₂ contains N₁ and both refer to the same non-terminal N, N₁ is called a nested N. N₂ is the closest container of N₁, if, and only if, N₂ contains N₁ and for all N₃ containing N₁ and that refer to the same non-terminal as N₂ it holds that N₃ contains N₂.

N₁ is preceding N₂, if, and only if, neither is contained in the other and the left-most derivation of the closest container of N₁ and N₂ derives N₁ before N₂; in this case N₂ follows N₁. Instead of preceding also the term before is used; and instead of follows also the term after. If, and only if, either, N₁ follows N₂ or N₂ follows N₁, both are siblings. N₁ and N₂ are different, if, and only if, they are siblings or the one contains the other.

N₁ is lexically-equivalent to a sequence of characters α, written N₁ =_lexical α, if, and only if, N₁ derives to α. N₁ is lexically-equivalent to N₂, written N₁ =_lexical N₂, if, and only if, N₁ and N₂ derive to the same sequence of characters.

If, and only if, N₂ contains N₁ and throughout all possible derivations of the non-terminal N₂ refers to the non-terminal N₁ refers to can be derived at most once, we speak of the N₁ of N₂; obviously, N₂ is the closest container of N₁ in that case.

Let d = β₁, …​, β_n be a single definition according to ISO/IEC 14977; β_i with 1 ≤ i ≤ n is called the i’th factor of d. A δ_z is called the γ₂-…​-γ_z'th factor of δ₁, if, and only if, ∀i,j∈ℕ+; i = j - 1; 2 ≤ j ≤ z: δ_j is the γ_j'th factor of δ_i. Let G be the syntactic rule of N₂. We call N₁ the i₁-…​-i_k'th child of N₂, if, and only if, N₁ has been derived for the i₁-…​-i_k'th factor of G when deriving N₂; in this case N₂ is called the parent of N₁. If, and only if, the i₁-…​-i_k'th factor of G has been derived when deriving N₂, we say N₂ has a i₁-…​-i_k'th child; otherwise it is without i₁-…​-i_k'th child.

A syntactic term F is without a code fragment according to some non-terminal N, if, and only if, N is not derived throughout the derivation of F; in this case, we say F does not contain a N, it is N-free. Note, that F is a syntactic term — i.e., a code fragment derived according to the syntactic rule for the non-terminal F — whereas N is just a non-terminal referring to some syntactic rule; nevertheless, N will be highlighted italic in semantic rules as if it is a syntactic term, denoting that it is a non-existing code fragment.

S-TODO (guarded multi-dimension access / Dimensionality-analysis): For each dimensional-context of the function-declaration a reference R is part of (cf. S-TODO), the dimensional-bounds of the computed-dimensions of R must be within the dimensional-bounds of the declaration R refers to (cf. S-TODO).

S-TODO (uniqueness of early loop exits / Termination-analysis): Let B₁ and B₂ be two different early-loop-exits. Their respective closest for-loop containers must be different; and their loop-iterator-references must refer to different for-loops.

L-1 (design-space of Production Code generation and system integration): Production Code generators and system integration are free to realize a GALEC block by any means they see fit as long as its operational semantic is satisfied. They can achieve a mutual agreement that block-interface functionality is not supported, like recalibration by means of Recalibrate() or reading block inputs from the runtime environment, given that the use-case and system integration scenario does not require such. In general however, Production Code generators must support the full block-interface and life-cycle to be eFMI specification conformant.

Examples of integration scenario specific design-space agreements are:

Particularly (3) is a common integration scenario, since recalibration typically is only performed during the development phase of an embedded system and no longer supported in production systems.

R-1 (block-variable initialization and Algorithm Code Container manifest start values): The start values of the variables in the manifest of an Algorithm Code Container are conceptually determined by calling Startup() on the target system and its runtime environment. A Production Code generator can for example (1) use these start values directly in the C-Code for static initialization (i.e., as precomputed values), hereby casting from the concrete manifest-variable type in which the start-values are stored to the best fitting concrete type of the target system, or (2) provide an implementation of Startup() to be called by the runtime environment during startup, or (3) use any other means to ensure block-variables have initial values according to Startup() (cf. §2:R-1).

R-1 (block life-cycle implications for system integration): The following discussion refers to the block life-cycle state machine. Italic refers to states or transitions of it; monospace refers to state actions, i.e., block-interface methods according to §2.

The block life-cycle does not enforce the runtime environment to set inputs and tunable parameters (input written and tuneable parameter written transitions) separately in sequence or at most once before each sampling. It does not prohibit the runtime environment to read block inputs or tunable parameters or execute Recalibrate() several times before a single sampling. This allows complex system integration scenarios where the runtime environment has to setup the next sampling depending on the state of a block instance.

The block life-cycle enforces however, that whenever a tunable parameter is changed via tunable parameter written, all dependent parameters must be recomputed via Recalibrate() before the next sampling (recalibration required conditional). Otherwise, a protocol error is given and the block behavior is undefined (idle (protocol error) state). Several tunable parameter changes can be bundled though; it is not required to switch to recalibrating after each individual new tunable parameter is set, but sufficient to do so once before the next sampling.

Likewise, the block life-cycle enforces that DoStep() is executed exactly once for each sampling (sampling clock ticks transition).

The block life-cycle also enforces that the new block inputs, to be used for the next sampling, must be ready before the execution of DoStep() starts (all inputs set condition of sampling clock ticks transition). It is however not enforced that every input must be assigned a new value each sampling. Since Startup() assigns all block-variables a well-defined value, including block inputs, following samplings will be well-defined even if an input is not set anew (assuming recalibration is done as described in the last but one paragraph). If a block-input is not updated before a sampling, it has the last value set. It is however very uncommon not to set all inputs each sampling; one reasonable scenario not to do so is if the block is super-sampled compared to some of its inputs (e.g., a sensor provides a new input value every 2ms, but the block is sampled every 1ms because of other faster changing inputs).

G-1.1 — G-1.7 (white space characters):

G-1.8 — G-1.17 (constants):

G-1.19 — G-1.26 (names):

S-1.1 (longest match / Meta-rules, lexical-structure): Given the following EBNF grammar: G_lexemes = { ? all meta-identifiers of G-1.1 — G-1.26 concatenated by | ? }. Let αβγδ be an arbitrary GALEC program P, with α being an arbitrarily long sequence of characters matched throughout a left-most derivation of P according to G_lexemes, β and γ being arbitrary long but not empty sequences of characters, and δ being an arbitrary long sequence of characters. Let G₁ and G₂ be any two different rules of G-1.1 — G-1.26 that can be applied next throughout the left-most derivation of P according to G_lexemes. Assume G₁ would match β and G₂ would match βγ; in that case G₁ is not applicable.

For every left-most derivation of any GALEC program P it must hold that the sequence of G-1.1 — G-1.26 applications is the same as the sequence of G-1.1 — G-1.26 applications for the left-most derivation of P by G_lexemes.

S-1.2 (universality of white space / Meta-rules, lexical-structure): Except for rules G-1.1 — G-1.26, { white-space } is implicitly preceding and following each syntactic-factor of a syntax-rule (cf. ISO/IEC 14977).

S-1.3 (primitive names / Name-analysis, terminology): Names, identifiers and quoted-identifiers are primitive names. Let α be lexically-equivalent to a primitive name N; α is the name of N. Syntactic terms with a name are called named. Let α be the name of a named syntactic term N; we say N has name α and N is named α.

R-1.1 (scalarization and quoted identifiers / Traceability): Quoted-identifiers are provided to denote scalarized entities — typically multi-dimensional nested components of the original physics-model whose elements are flattened to individual scalar entities for further numeric optimisations throughout the generation of an algorithmic solution. By reusing the original multi-dimensional query for an element that is now an independent scalar as the scalar’s name, traceability can be achieved.

The previous(α) and derivative(α) notations are intended to be used for support-variables holding the value a variable α had at the end of the last control-cycle or its derivative respectively. Many physics-modeling languages, like Modelica, provide such values implicitly by means of operators applicable to any variable. Since algorithmic solutions are discrete however, no continuous derivatives exist. And the meaning of previous, in terms of the last value before the current, depends on the applied discretization scheme. For backward discretization it indeed is the last control-cycle’s value; for forward discretization however, it is the current value. For mixed schemes the meaning is unclear. Due to these issues, no specific operators are provided. Instead, algorithmic solutions have to explicitly introduce variables to hold values or compute derivates. The previous(α) and derivative(α) notations can be used to give the explicit variables introduced for the variables α that have been subject of such implicit operations convenient names, ultimately increasing traceability.

R-1.2 (reserved keywords): G-1.19 (keyword) reserves certain character sequences for future language extensions; the respective sequences are not used elsewhere in the grammar. The sequences while, do and until are reserved for a potential future introduction of non-bounded or more complicated loops, return and break for potential early function and loop exit statements and enumeration for a potential extension with enumeration types. Such reservations do not imply by any means that the language indeed will be extended accordingly; they rather serve to preserve up-wards compatibility of code when respective language extensions are added. The "__", identifier alternative reserves names that might collide with internal compiler macros of further tooling; it is in the spirit of 6.11.9 of ISO/IEC 9899:TC3.

G-2.1 — G-2.3 (blocks, state compartments and functions):

G-2.4 — G-2.12 (state entity, parameter and local variable declarations):

R-2.1 (unique start symbol): According to ISO/IEC 14977 and S-1.2, block is the only start symbol.

S-2.1 (consistent naming / Name-analysis): The 2nd and 12th child of blocks must be lexically-equivalent. The 2nd and 5th child of a state-compartment-declaration must be lexically-equivalent. The 2nd and 9th child of a function-declaration must be lexically-equivalent.

S-2.2 (state compartments, components and variables and control-inputs and -outputs; input and output parameters; local variables / Type-analysis, terminology): A state-entity-declaration without primitive-type is called state component, otherwise it is called state variable. State components and variables are called state entities.

State-compartment-declarations are called state compartment; the state entities contained in a state compartment are called its local entities (thus, state compartments have local components and variables).

State entities whose data-flow-direction is lexically-equivalent to input are called control-input; state entities whose data-flow-direction is lexically-equivalent to output are called control-output. Control-inputs and -outputs must be state variables and not be part of state compartments (i.e., state components cannot be control-inputs or -outputs nor can such be local entities of any state compartment).

A parameter-declaration whose data-flow-direction is lexically-equivalent to input is called an input parameter; otherwise it is called an output parameter. Input and output parameters are called parameters.

Local-variable-declarations are called local variable.

S-2.3 (stateless and stateful functions / Side-effect-analysis, terminology): Function-declarations are just called functions. Functions whose first child is lexically-equivalent to method are called stateful function; otherwise, they are called stateless function.

S-2.4 (names of state compartments and entities, functions, parameters and local variables / Name-analysis): State compartments, state entities, functions, parameters and local variables are named.

The name of a state compartment is the name of its 2nd child.

The name of a function is the name of its 2nd child.

The name of a state entity, parameter and local variable is the name of its variable-declaration where the name of a variable-declaration is the name of its 2nd child.

S-2.5 (unique declarations (Part I) / Name-analysis): Blocks must not contain two different functions or state compartments with equivalent names. Functions and state compartments must have different names. Parameters and local variables must not be named like functions or state compartments. Functions must not contain two different parameters or local variables with equivalent names. Parameters and local variables contained in the same function must have different names. Different local entities of a state compartment must have different names.

S-TODO incorporates and adds further unique declaration restrictions for iterators.

S-2.6 (state compartment lookup / Name-analysis): Let R be a state-compartment-reference. There must exist a state compartment D named like the name of R; according to S-2.5, D must be unique. We say R refers to D.

S-2.7 (types of state entities, parameters and local variables / Type-analysis): The first child of a variable-declaration D defines its type. If, and only if, D contains a primitive-type T, the type of D is lexically-equivalent to T. In this case D has a variable type; otherwise, the type of D is the state compartment its state-compartment-reference refers to and D has a component type.

The type of a state entity, parameter and local variable is the type of its variable-declaration.

The type of parameters and local variables must not be a component type.

S-2.8 (state compartment composition graph, control-state and control-state extent / Termination-analysis): We define the following directed graph G. For every state compartment C, G contains a node labeled with the name of C. For every state component with type T and local to C, we add a directed edge from C to T. G is called the state compartment composition graph.

The state compartment composition graph must be cycle-free and it must contain a node N labeled efmu from which all other nodes are reachable (and which therefore is its only root, i.e., the only node without incoming edges).

The state compartment named efmu is called the control-state.

Control-inputs and outputs must be local state entities of the control-state.

S-2.10 (locally and transitively called functions, static function call graph and recursion-freeness / Termination-analysis): Let C_f be the set of names of the function-calls contained in a function f; C_f is called the local function call set of f and we say for each function f_c whose name is in C_f that it is locally called by f and that f locally calls f_c.

We define the following directed graph G. For every function f (including builtin functions), G contains a node labeled with the name of f. For every function f_c locally called by a function f, we add a directed edge from f to f_c. G is called the static function call graph.

Let n be a node of the static function call graph and n_r be a node reachable from n; let f be the function named like the label of n and f_r the function named like n_r. We say f_r is transitively called by f and f transitively calls f_r.

The static function call graph must be cycle-free.

S-2.11 (initialization and control-cycle functions / Name-analysis): Every block must contain a function named Startup; respective functions are called initialization function. Initialization functions must be stateful and parameter-declaration-free. Initialization functions must not locally call user-defined functions (i.e., initialization functions can only call builtin functions).

Every block must contain a function named DoStep; respective functions are called control-cycle function. Control-cycle functions must be stateful and parameter-declaration-free.

All user-defined functions, except the control-cycle and initialization functions, must be transitively called from the control-cycle function (thus, let N_user-defined be the set of nodes of the static function call graph labeled with the name of a user-defined function, excluding the control-cycle and initialization functions, and let n_{control-cycle} be the node labeled with the name of the control-cycle function: ∀n_user-defined∈N_user-defined: n_user-defined is reachable from n_{control-cycle}).

S-2.12 (scalars, multi-dimensions, vectors and matrices / Dimensionality-analysis, terminology): State entities, parameters and local variables without constant-dimensions are called scalar; otherwise multi-dimension. Let d = [ α₁, …​, α_n ] be the constant-dimensions of a state entity, parameter or local variable v; in that case v is n-dimensional/multi-dimensional, n is the number of its dimensions and each α_i with 1 ≤ i ≤ n is its i'th dimension. Scalars are zero-dimensional. If, and only if, v is one-dimensional it is called vector; if, and only if, it is two-dimensional, matrix. The first dimension of a matrix are its rows, the second its columns.

S-2.13 (dimensional-sizes of state entities / Dimensionality-analysis): State entities must not contain dimension-queries or derived-dimensions.

TODO: More relaxed alternative: Contained dimension-queries must refer to state entities; the resulting dependency graph must be cycle-free. More restrict alternative: The constant-scalar-integer-expressions of their constant-dimensions must derive to positive-integers.

TODO: Static computation of actual dimensions.

S-2.14 (dimensional-sizes of parameters and local variables / Dimensionality-analysis): Output parameters and local variables must not contain derived-dimensions (i.e., only input parameters can contain derived-dimensions).

TODO: Static computation of actual dimensions.

S-2.15 (signature of functions; procedures / Type-analysis, terminology): The parameters a function contains define its signature, i.e., its input-arity, output-arity and order of inputs and outputs.

Let S_input be the set of all input parameters contained in a function f; let S_output be the set of all output parameters contained in f. The inputs of f are the tuple T_input = (p₁,…​,p_n) with n = |T_input| = |S_input| and ∀p_i,p_j∈T_input ; i,j∈ℕ+ ; i < j ≤ n: p_i∈S_input ∧ p_j∈S_input ∧ p_i is preceding p_j; likewise, the outputs of f are the tuple T_output = (q₁,…​,q_m) with m = |T_output| = |S_output| and ∀q_i,q_j∈T_output ; i,j∈ℕ+ ; i < j ≤ m: q_i∈S_output ∧ q_j∈S_output ∧ q_i is preceding q_j. The input-arity of f is n; its output-arity is m.

An input parameter is called the i'th input of a function f, if, and only if, it is the i'th element of the inputs of f; likewise, an output parameter is called the i'th output, if, and only if, it is the i'th element of the outputs. Trivially, an input parameter part of a function f is an input of f and an output parameter an output.

Functions of output-arity 0 are called procedure.

G-3.1 — G-3.4 (statically- and dynamically-evaluated expressions):

G-3.5 — G-3.10 (operations):

G-3.11 — G-3.14 (multi-dimension constructors, function calls and conditional expressions):

S-3.1 (statically- and dynamically-evaluated expressions / Syntactical-structure, terminology): Expressions and all children of such, as well as constant-scalar-integer-expressions, are called expression. Expressions part of, or that are, a constant-scalar-integer-expression are called statically-evaluated; all other expressions are called dynamically-evaluated.

References contained in statically-evaluated expressions must either, be the third child of a dimension-query or refer to a loop-iterator-declaration. Function-calls contained in statically-evaluated expressions must refer to builtin functions.

S-3.2 (operations, operators and arguments of operations / Type-analysis, terminology): Binary-operations and unary-operations are also just called operation. The 2’nd child of a binary-operation and the 1’st child of an unary-operation are called its operator. The 1’st and 3’rd child of a binary-operation O are called its first and second argument respectively; they are the arguments of O. The 2’nd child of an unary-operation is called its argument.

Let ⊕ be lexically-equivalent to the operator O_⊕ of an operation O; we call O an ⊕-operation and O_⊕ the ⊕-operator. If, and only if, O is a binary-operation it and its operator are called binary; otherwise unary.

S-3.3 (operator precedence and associativity / Meta-rules, syntactical-structure): The following table defines a unique disambiguation for the syntactic ambiguities of binary-operations by means of an operator precedence and associativity for sequences of operators with equivalent precedence:

Binary-operations must satisfy the defined operator precedence and associativity.

A binary-operation O satisfies operator precedence, if, and only if, it does not contain binary-operations whose operator has a lower operator precedence than the operator of O and which themselves are not contained within a precedence-overriding non-terminal part of O. The precedence-overriding non-terminals are: reference, dimension-query, function-call, parenthesized-expression, if-expression and multi-dimension-constructor.

Operator associativity is satisfied if, and only if, binary-operations are derived left-most if their operator’s associativity is left-to-right and right-most otherwise.

S-3.4 (type of operations / Type-analysis): Except for ^-operations, the arguments of an operation must be equally typed. The arguments of arithmetic-operators and relational-operators, except == and <>-operators, must be of type Integer or Real. The arguments of /-operations must be of type Real. The arguments of logical-operators must be of type Boolean. The argument of unary --operations must be of type Real or Integer; the argument of unary not-operations must be of type Boolean.

Except for ^-operations and operations with an operator that is a relational-operator, the type of an operation is the type of its arguments. The type of ^-operations is Real; the type of operations with an operator that is a relational-operator is Boolean.

S-3.TODO (type and dimensionality of constant-scalar-integer-expressions / Type-analysis, dimensionality-analysis): The type and dimensionality of constant-scalar-integer-expressions are the type and dimensionality of their first child; they must be Integer and scalar respectively.

S-3.TODO (well-defined stateful function calls / Side-effect-analysis): Expressions containing a function-call C referring to a stateful function must not contain function-calls or state-references that are siblings of C. If-expressions must not contain function-calls referring to a stateful function.

S-3.TODO (function lookup / Name-analysis): Let f_c be a function-call. There must exist a function f_d named like the first child of f_c; according to S-2.5, f_d must be unique. We say f_c refers to f_d.

S-3.TODO (type of function calls used in expressions / Type-analysis): Function-calls part of expressions must refer to functions of output-arity 1; their type is the type of the first output of the function they refer to.

G-TODO.TODO — G-TODO.TODO (TODO)

S-TODO.TODO (type of references / Type-analysis): The type of a reference is the type of the entity it refers to.

References referring to a state component must be the third child of a dimension-query or part of a limit-statement.

S-TODO.TODO (left- and right-hand of assignments / Side-effect-analysis, terminology): Single-assignments and multi-assignments are called assignment. The first child of an assignment is called its left-hand; the third child its right-hand.

S-TODO.TODO (non-writeable control-inputs, input parameters and loop iterators; side-effect-freeness of stateless functions / Side-effect-analysis): State-references contained in the left-hand of an assignment must not refer to control-inputs. Local-references contained in the left-hand of an assignment must not refer to input parameters or loop-iterator-declarations.

Stateless functions must not contain an assignment whose left-hand contains a state-reference; and they must not transitively call stateful functions.

S-2.9 (builtin functions / Syntactical-structure, terminology): Let C_builtin = C_builtin¹ ∘ C_builtin² ∘ C_builtin³ ∘ C_builtin⁴ where each C_builtinⁿ with n∈{1,2,…​,4} is a sequence of characters defined in the following and ∘ is the left-to-right concatenation of sequences of characters. C_builtin is implicitly appended to each program; its functions are called builtin. Functions that are not builtin are called user-defined.