General

This document is the fourth document of the Plurimath specifications series. It specifies evaluation: the computation of a numeric value for a formula tree against variable bindings, under a strict error contract.

The evaluator described here is implemented in the plurimath gem of the 0.11 series (Plurimath::Math::Evaluation). It evaluates arithmetic over the tree exactly as written: it never rewrites the tree, never rounds behind the caller’s back, and never returns a value that is not a real, finite number — the alternative is one of the typed errors. Uncertainty propagation is not part of this edition: the model of PM 1002 carries uncertainty nodes, this document’s evaluator does not compute with them, and the propagation rules will arrive in this document when they arrive in the implementation.

Documents in the series

Maintainers

This document is maintained by the Plurimath project at https://github.com/plurimath/plurimath.

1.1  General

This document specifies evaluation of Plurimath formula trees:

This document does not specify:

1.2  Relationship to the series

1.3  Audience

Implementers of Plurimath, applications embedding evaluation, and authors of the propagation rules to come.

4.1  General

Evaluations are written as: tree, bindings, result. Errors are written as their class names of clause 11 with the identifying data the message carries.

4.2  Examples

Examples carry an Expected outcome paragraph stating the number yielded or the error raised. Numbers in examples are exact where they are exact: a rational binding such as one third behaves as its exact value in every example that uses it.

4.3  Names

Names in examples (x, n, i) are the plain identifiers the trees carry. The mapping from a tree’s symbols to names is pinned by the corpus; this document treats names as the keys of the binding set.

5.1  The model

lml "1.0"

models Evaluation {

  class Evaluator {
    attribute tree, Formula[1]
    attribute bindings, Binding { cardinality 0..n }
  }

  class Binding {
    attribute name, Name[1]
    attribute value, RealNumber[1]
  }

  class Result {
    attribute value, RealNumber[1]
  }

  enum EvaluationError {
    value "division-by-zero"
    value "invalid-binding"
    value "invalid-binding-key"
    value "math-domain"
    value "missing-variable"
    value "non-finite-result"
    value "unsupported-expression"
  }
}

An evaluation is one Evaluator over one tree with zero or more bindings. Its success is one Result; its failure is one EvaluationError, raised as the corresponding class of clause 11.

5.2  The contract

The strict error contract, stated once and honoured everywhere below: an evaluation returns a real, finite number, or raises one of the typed errors. There is no NaN result, no infinite result, no silently skipped subtree, no partial evaluation.

5.3  Determinism

The same tree and the same bindings produce the same result or the same error, in the same order of internal operations. Evaluation has no randomness, no parallelism and no environment sensitivity; the corpus replays it identically.

5.4  The tree is not modified

Evaluation reads the tree. Nothing in the tree changes — no annotation of computed values, no caching inside nodes, no rewrite. A tree evaluates twice identically, and an evaluated tree writes exactly as an unevaluated one.

5.5  Foreign exceptions become typed errors

The underlying arithmetic platform’s own signals — domain errors from the math library, float-domain failures, platform division failures — are caught at the evaluation boundary and re-raised as the corresponding typed errors: MathDomainError, NonFiniteResultError, DivisionByZeroError. A caller never sees a foreign exception from evaluation; the message text of the platform error, where one exists, travels inside the typed error.

5.6  The walk, in order

An evaluation proceeds:

The order is observable through the errors: an expression with both a missing name and a division by zero reports whichever the walk reaches first. The corpus includes order-sensitive vectors so the ordering is tested, not implied.

5.7  Zero bindings

An evaluation with no bindings evaluates the closed part of the tree: a tree without names evaluates completely (2 + 3 * 4 yields 14 with no bindings); a tree with any name refuses at that name. Both are ordinary evaluations under the one contract.

5.8  The evaluator is reentrant

An Evaluator instance holds its tree and bindings and nothing mutable; evaluating twice, or evaluating from two callers, shares no state. Iteration’s temporary bindings are scoped to their body and restored on every exit path, including the error paths — an aborted iteration leaves the binding set as it found it.

6.1  General

A tree denotes operations in writing order, not in a flat list: 2 + 3 * 4 multiplies before it adds. The expression parser turns the evaluator’s node walk into that precedence-correct sequence of folds. It is a precedence-climbing parser over the tree’s linear reading, with one level per binding strength.

6.2  The precedence chain

The parser descends one chain, strictest last:

Each level parses the next as its operand and folds left-associatively within itself — powers excepted, which fold right-associatively: 2³2 is 2⁽³2), the mathematical convention.

6.3  What the parser accepts

The parser accepts the arithmetic core the evaluator evaluates: numbers, bound names, the operations above, groups, and the function and iteration calls of clauses 8 and 10. A node outside this core — a Text node, a matrix, an uncertainty node — makes the whole evaluation raise UnsupportedExpressionError: the evaluator does not evaluate what it does not define, and never guesses.

6.4  Groups

A group saves the parser’s pending state, evaluates its content to one value, and presents that value as an operand. Groups are the author’s precedence: 2 * (3 + 4) yields 14, not 10.

6.5  Relations

The relation level evaluates comparisons to truth values in the platform’s terms. A tree whose top level is a relation yields that relation’s result; relations compose left-associatively where the tree carries chains. The corpus pins the truth-value results alongside the numeric ones — both are results of the one contract.

6.6  Token normalisation

Before parsing, the tree’s linear tokens normalise: implicit products are marked (2x becomes 2 * x, a(x + 1) becomes multiplication, x sin y stays two operands), explicit multiplication symbols map to the same fold, and spacing is irrelevant. Normalisation is deterministic and pinned by the corpus; it changes no node, only the fold sequence.

6.7  Function calls in the chain

A function call parses as a prefix at the operand level: the function name, then its argument or arguments as the grammar of the construct gives them — parenthesised, braced, or by adjacency for the notation’s single-argument forms. The argument expressions parse at the full chain, so log_2 x^3 binds the power inside the argument where the notation’s grouping says so; the corpus carries the ambiguous-looking cases explicitly.

7.1  The operations

The evaluator’s operations, their names, and their domains:

Every operation consumes real, finite values and produces one; the contract of clause 5 applies at each fold.

7.2  Division

Division by zero raises DivisionByZeroError — including division by an expression that evaluated to zero, however far away the zero came from. There is no limiting behaviour, no infinity: the contract has no place to put one.

7.3  Modulo

Modulo follows the platform’s modulo semantics for real operands; a zero divisor raises DivisionByZeroError. The sign behaviour is the platform’s and the corpus pins it.

7.4  Powers

The power operation evaluates a^b for the domains the real numbers define: a positive base with any real exponent, a zero base with a positive exponent, a negative base only where the exponent is an integer or a rational with an odd denominator in lowest terms. Outside those domains the platform’s domain error becomes MathDomainError. An exponent that would produce a non-finite magnitude raises NonFiniteResultError at the boundary.

7.5  Negation and sign

Negation flips the sign of its operand; a unary plus is the identity. Neither has side effects, and chains (−−x) negate once per sign as written.

7.6  Results

Every fold’s result passes the real-and-finite check before it feeds the next. A non-finite intermediate — an overflow inside the platform’s numbers — aborts the whole evaluation with NonFiniteResultError rather than propagating a poisoned value.

7.7  Implicit products

Adjacency means multiplication where the notation puts values side by side: a number before a name, a name before a group, a group before a group. It does not mean multiplication between two numbers (2 3 is not a valid product — the corpus refuses it as a token fault) nor between a name and the keyword introducing an iteration. The normalisation of clause 6 makes every implicit product explicit before folding.

7.8  Accuracy classes

Every value an evaluation carries belongs to an accuracy class. Integers and rationals are exact: their add, subtract, multiply and rational division are exact operations, and an exact operand list yields an exact result. Floats are limited with undeclared accuracy (the platform’s bits); guard-digit decimals are limited to their declared precision. Limited operands contaminate exact ones: the accuracy of an operation’s result is the accuracy of its least precise operand. A five-digit value times a six-digit value is defined to five digits — the class algebra states this, the corpus vectors pin it.

7.9  Boundaries

A boundary is an operation that would replace exact values with platform approximations: a transcendental function, an irrational root, a non-exact power on exact operands. The evaluator processes until a boundary and never violates one silently — every crossing is reported.

7.10  Modes

The caller chooses the mode at the entry point; the default is approximate.

Exact vectors — whole expressions evaluated without a crossed boundary — are byte-identical across runtimes: their results are integers and rationals, not platform values. The exact-decimal discipline of the data layer (CalConnect 36813) is the same discipline strict mode evaluates under.

7.11  Results

Evaluation returns a result object, not a bare number: the value, the ordered boundary records (operation, operands, operand accuracy, action — approximated, guarded or deferred — and the produced value), and the unevaluated expressions when strict mode deferred. A result whose boundaries contain no approximation is exact; a deferred result carries the residual expression.

7.12  Order of folds

Left-associative levels fold left: a − b − c is (a − b) − c, and a / b / c is (a / b) / c. Right-associativity belongs to powers alone. The distinction is observable in floating point even when exact arithmetic would agree; the corpus pins the fold order with vectors whose inputs differ by association.

7.13  A precedence walk, concretely

The tree of −3 + 4 * 2^2 / (1 + 1):

Expected outcome. 5 — each level once, in the chain’s order, with the group overriding the written order.

8.1  The function classes

The evaluator evaluates the function classes the model defines where a numeric semantics exists: the trigonometric and hyperbolic functions and their inverses, the logarithms (ln, lg, log with a base), the exponential, the absolute value, floor and ceiling, min and max, and the named constants of the registry where the platform defines their values.

8.2  Arguments

A function’s arguments are its operands, evaluated left to right as ordinary sub-evaluations. The argument count is the class-defined arity of PM 1001; a tree that carries a different count is an UnsupportedExpressionError — the evaluator does not improvise signatures.

8.3  The logarithm base

log with a base evaluates to the logarithm in that base: log_2 8 yields 3 under exact arithmetic in the corpus. The one-argument form is the natural logarithm’s decadic sibling per the registry’s reading; the corpus pins which.

8.4  Constants

Registry constants with platform values (π, the exponential constant) evaluate to the platform’s value of that constant. Constants without one are names: they bind from the bindings or refuse with MissingVariableError, like any name.

8.5  Nary calls and argument evaluation

The nary functions the evaluator defines (sum, prod with bounds) route to iteration (clause 10); the nary classes without bounds refuse as unsupported in this edition — a bare ∑ over a list has no evaluation semantics here. Argument sub-evaluations run through the same chain and contract; an error inside an argument aborts the whole call, and there is no argument-level recovery.

8.6  The log argument rule

The logarithm’s argument is the full expression the notation groups: log x + 1 is log(x) + 1 under the adjacency binding, and log(x + 1) is the logarithm of the sum. Where the writer’s shape and the reader’s grouping disagree, the tree is authority: the evaluator evaluates the tree it is given, and the corpus carries the disambiguated pairs.

8.7  Constants and names, precisely

A registry constant with a platform value evaluates without bindings; a name without one binds or refuses. The registry decides which is which, per PM 1001 — evaluation adds no constants of its own and treats an unknown constant exactly like any other name.

9.1  The binding set

Bindings are the evaluation’s variables: a set of names, each with a real numeric value. Keys arrive as strings or symbols and normalise to strings; values must be real numbers.

9.2  Validation at entry

The binding set is validated before the tree is touched:

An evaluation with an invalid binding refuses before any evaluation happens: the tree is not walked with a bad environment.

9.3  Missing names

A name the tree mentions and the bindings lack raises MissingVariableError, carrying the name. The refusal happens at first use — evaluation does not pre-scan the tree for names, so an evaluation that dies early reports the first missing name it needed, not all of them.

9.4  Shadowing

The iteration index temporarily shadows an outer binding of the same name for the body’s evaluation and restores the outer binding afterwards (clause 10). Shadowing is scoped to the body: outside the iteration, the outer binding is untouched.

9.5  The numeric types accepted

A binding value may be any real numeric type the platform offers — integers, rationals, floating-point numbers. The evaluator normalises nothing: an integer binding stays an integer in the arithmetic where the platform keeps it one, a rational stays exact while its operations do, and the corpus pins the type-observable outcomes (sum_(i=1)^3 i with an integer index folds in integers). Values that are complex, non-real or not numbers at all refuse per clause 9.

9.6  Name shape

A name is the identifier text a tree’s symbols carry for evaluation. Names are case-sensitive and exact: X and x are different bindings, and a binding for one does not serve the other. There are no reserved names — the iteration indexes are ordinary names that shadow per clause 10.

9.7  Binding once, evaluating many

An evaluation binds its names once, at entry. There is no rebinding during evaluation, no environment mutation from inside the tree, and no callback through which the tree could observe or alter its own bindings.

10.1  The construct

The nary sum and product with explicit bounds — sum_(i=1)^n body, prod_(i=1)^n body — evaluate as bounded iteration: the index runs the integer range and the body’s values fold under the operation, starting from the operation’s identity.

10.2  The bounds

The lower bound parses as index = start and the upper as the end expression. Both evaluate to integers: a bound that evaluates to a non-integer or an infinite value raises the typed error of its cause (MathDomainError for a non-integer bound where the platform names it so, NonFiniteResultError for an infinite one). An empty range — a start above the end — yields the identity: the empty sum is 0, the empty product is 1.

10.3  The step limit

A range wider than the implementation’s step limit refuses with UnsupportedExpressionError: iteration is bounded by construction, and an unbounded or enormous range is a caller error, not a long computation.

10.4  The fold

The body evaluates once per index value, left to right, with the index bound; the values fold under the operation — addition for the sum, multiplication for the product — from the identity. The index binding shadows per clause 9 and restores after.

10.5  The index definition, precisely

The lower bound parses as the two-part form name = start. The name becomes the index; anything else in the lower-bound position is an UnsupportedExpressionError. The start evaluates once, to an integer; a non-integer start refuses with the typed error the platform names for it.

10.6  Bounds validation

After the start, the upper bound evaluates once, to an integer. Validation is order-fixed: start first, end second, both integers, then the step limit. The error each check raises names its stage, so a caller with a malformed bound learns which one it was.

10.7  The step limit’s value

The implementation carries a fixed maximum range width; the corpus pins it as behaviour (a range one past it refuses, one within it runs). The limit exists so that sum_(i=1)¹⁰9 — an infinite work order in the caller’s clothing — is a refusal the caller handles, not a hang they kill.

10.8  Nested iteration

A body may itself carry an iteration: the inner index shadows the outer for the inner body, and the ranges compose. The corpus carries nested vectors to fixed depth; the step limits apply per range.

11.1  The eight errors

Catching the base class catches them all; catching a subclass catches the specific refusal. The errors are the contract’s vocabulary: everything a caller can do about a refusal starts from one of these names.

11.2  Refusal points

Where each error can arise:

11.3  What the contract forbids

No default values for missing names, no complex-number escape hatch, no unsigned infinity, no NaN, no evaluation of part of a tree, no second chance. Each of those would turn a refusal the caller can handle into a value the caller must guess about — the contract prefers the refusal.

11.4  Messages

Message shapes are stable within an edition. The identifying data travels in the message: the missing name, the offending binding, the node class refused. The corpus pins the shapes with one vector per error.

11.5  Causes, not substitutes

Where a typed error wraps a platform exception, the platform’s error is the cause — preserved for diagnostics, never raised in its place. Callers match on the typed name; the cause answers “what exactly did the platform say”.

11.6  Catching guidance

Handle the specific errors you can act on: retry with corrected bindings for MissingVariableError, report the input for UnsupportedExpressionError, treat DivisionByZeroError and MathDomainError as mathematical facts about the input. Catching the base class is for the boundary of a long pipeline; everywhere else, the specific name is the better match, and the corpus holds a vector for each name.

11.7  Errors are results too

A refusal is a well-defined outcome, deterministic as any number: the same tree and bindings produce the same error with the same message. The evaluation corpus treats errors exactly like results — frozen, replayed, drift-checked — because a caller’s error handling is only as reliable as the errors are repeatable.

12.1  Uncertainty propagation

The model carries uncertainty nodes (PM 1002); this edition’s evaluator does not compute with them. An evaluation whose tree contains an uncertainty node refuses with UnsupportedExpressionError — the honest answer, rather than an arithmetic that quietly drops the uncertainty. The propagation rules — sensitivities, the propagation law, second-order terms, coverage — enter this document in the edition whose implementation carries them.

12.2  Simplification

The evaluator never rewrites the tree: no folding of constants into nodes, no canonicalisation of equivalent forms, no algebra. Evaluation is a reading of the tree, and two equal trees evaluate identically while two different trees evaluate as written even when their values coincide.

12.3  Units and quantities

Evaluation works on numbers. Unit conversions, quantity arithmetic and the absolute/difference typing of the UnitsML series are that series’ contracts; an evaluator applied to unit-bearing trees evaluates the numeric content as the bindings supply it and the units ride with the tree, unconverted.

12.4  Solving

No root-finding, no inversion, no symbolic manipulation. The evaluator answers one tree with one number, given complete bindings; everything else is a different tool.

12.5  Why the limits are stated

Each non-goal is a contract someone will eventually ask for. Stating them keeps the boundary honest: an evaluator that quietly simplified would surprise every caller who diffed two trees; one that silently propagated uncertainty would make reported results and computed results behave differently in the same expression; one that converted units would need the whole UnitsML typing inside arithmetic. The limits are the design; the clauses above are the contract they protect.

12.6  The road in

When propagation arrives, it arrives in this document: its operations, its error extensions if any, its corpus, its conformance class — the same structure this edition uses for arithmetic. The uncertainty nodes of PM 1002 were built to carry everything propagation will need: category, fields, exact decimals. Nothing in the model blocks the road; the evaluator simply has not walked it yet.

13.1  General

Conformance to this document is the implementation of the evaluator per clauses 5 to 11. One class covers it, with the corpus as its evidence; a partial implementation claims nothing.

13.2  Conformance classes

The claim carries the model claim of PM 1001: an evaluator over trees is an implementation of trees first.

13.3  The evaluation corpus

The corpus freezes, per entry: the tree (in a canonical reading), the bindings, and the outcome — the exact result or the typed error with its message shape. Entries come from this document’s examples first and from defect fixes and community reports as they arrive; a generation is immutable once published.

13.4  Drift

An implementation whose result or error differs from the corpus for the same tree and bindings does not conform. Floating-point-order differences that change results are drift: the corpus, not the platform, defines the expected values, and an implementation adjusts or the document moves an edition.

14.1  The precedence chain in full

14.2  The operations in full

14.3  Function domains, normative summary

Every refusal raises MathDomainError with the platform’s message; every overflow raises NonFiniteResultError.

15.1  Refusal vectors in the corpus

The message shapes of this annex carry one corpus vector each, plus: a missing name deep inside an iteration body (the name reported is the body’s first use), an unsupported node inside a group (the group does not shield it), and a non-finite intermediate inside an argument (refused at the argument, before the call). The corpus, not this annex, is the checkable form; this annex is its key.

16.1  Results

16.2  Refusals

16.3  Determinism

16.4  Precedence vectors

16.5  Binding vectors

16.6  Iteration vectors

17.1  The quadratic discriminant

The tree of b^2 − 4ac, bindings b → −3, a → 1, c → 2.

Expected outcome. 1. The discriminant is positive; nothing in this document says what that means — the caller reads their own mathematics into the number.

17.2  A series sum with shadowing

The tree of x_0 + sum_(n=1)^5 (n * x_0 / n) — a deliberately redundant form to exercise the machinery — bindings x_0 → 2.

Expected outcome. 12. The outer x_0 binding is untouched by the iteration; a second evaluation of the same tree with the same bindings yields 12 again, byte for byte.

17.3  What the walk-through shows