Documents in the series

Maintainers

This document is maintained by the Plurimath project at https://github.com/plurimath/plurimath. Corrections and implementations are tracked as issues in that repository.

Stability of this document

This document is a draft standard. The model it describes is implemented and released; the document pins behaviour to model versions so that readers can tell which statements describe released software and which anticipate the next edition. Corrections that change observable behaviour arrive with a model-version change and are recorded here; corrections that only clarify arrive at any time.

1.1  General

This document specifies the math model of the Plurimath system:

This document does not specify:

1.2  Relationship to the series

1.3  Audience

Implementers of Plurimath itself, implementers of independent readers or writers that must interoperate with it, and authors of the neighbouring documents in this series.

4.1  Tree notation

Trees are written as indented lines, one node per line:

Formula
└─ Power
   ├─ Symbol("x")
   └─ Number("2")

The class name appears first; a quoted string after the name is the node’s value (Symbol, Number, Text). This is the shape the math zone printer emits.

4.2  Examples

Examples appear in blocks titled Example and end with an Expected outcome paragraph. The expected outcome states what a conforming implementation does; an implementation that does something else does not conform to the clause the example illustrates.

4.3  Identifiers

Class names are written as they appear in the implementation: Plurimath::Math::Function::Frac is written Frac when the module is clear from context. The registry entries for symbols are written with the displayed glyph followed by the class name in parentheses when the glyph alone is ambiguous.

4.4  Version references

Behaviour is pinned to model versions. “0.11.x” names any version whose version string begins 0.11.; a clause that names a specific version, such as 0.11.12, applies to that version and is revisited at the next edition of this document.

4.5  Reading the LML blocks

The LML blocks of this document are the model. Attribute lines read as attribute name, Type with the cardinality following in braces where it is not one: attribute parameters, Node { cardinality 1..n } reads “every Formula carries one or more parameters, each a Node”. A cardinality left implicit is exactly one ([1]). Enumerations list their values; a node’s attribute of enumeration type carries one of them.

The LML blocks are checked: the model compiles with the LutaML toolchain, and a block that fails to compile fails the build of this document. The prose and the LML state the same model; where they appear to differ, the LML is corrected or the prose is — the two are never allowed to settle into disagreement.

4.6  Names

Conceptual class names are written without their implementation namespace: Formula stands for the implementation’s Plurimath::Math::Formula. Implementation namespaces appear once, here, and in the conformance vectors where byte output is frozen. A reader of this document needs no Ruby knowledge; an implementer maps each conceptual class to the implementation class of the same name.

4.7  The example format

Examples carry an Expected outcome paragraph. The outcome is stated as the observable behaviour of a conforming implementation: rendered bytes where the example is about rendering, tree shape where it is about the model, and refusal behaviour where it is about a prohibition. An example whose outcome cannot be observed is a defect in this document.

5.1  General

The formula tree is specified as an LutaML model. The model is normative: classes, attributes, types and cardinalities are defined in the LML blocks of this clause, and the prose states the rules the diagrams cannot.

5.2  The model

lml "1.0"

models Plurimath {

  package Structure {

    class Node {
      attribute kind, String[1]
    }

    class Formula {
      attribute parameters, Node { cardinality 1..n }
      attribute display_style, Boolean
      attribute options, RenderingOptions
    }

    class Symbol {
      attribute entry, SymbolEntry[1]
    }

    class Number {
      attribute text, String[1]
    }

    class Text {
      attribute content, String[1]
    }
  }

  package Functions {

    class Function {
      attribute operands, Node { cardinality 0..n }
    }

    class UnaryFunction {
      attribute operand, Node[1]
    }

    class BinaryFunction {
      attribute first, Node[1]
      attribute second, Node[1]
    }

    class TernaryFunction {
      attribute first, Node[1]
      attribute second, Node[1]
      attribute third, Node[1]
    }

    class NaryFunction {
      attribute operand, Node[1]
      attribute lower_limit, Node
      attribute upper_limit, Node
      attribute nary_value, String[1]
    }
  }

  package Layout {

    class Table {
      attribute rows, Tr { cardinality 1..n }
    }

    class Tr {
      attribute cells, Td { cardinality 1..n }
    }

    class Td {
      attribute content, Node { cardinality 0..n }
    }

    class FontStyle {
      attribute variant, FontVariant[1]
      attribute operand, Node[1]
    }

    class Fenced {
      attribute content, Node { cardinality 1..n }
      attribute open, Symbol[1]
      attribute close, Symbol[1]
    }

    class Linebreak
    class None

    class Phantom {
      attribute operand, Node[1]
    }
  }

  package Measurement {

    class Unitsml {
      attribute expression, String[1]
      attribute unicode_form, String[1]
      attribute latex_form, String[1]
      attribute mathml_form, String[1]
      attribute xml_form, String[1]
    }

    class Uncertainty {
      attribute value, Node[1]
      attribute category, UncertaintyCategory[1]
      attribute magnitude, Node
      attribute coverage_factor, Node
      attribute coverage_probability, Node
      attribute lower, Node
      attribute upper, Node
      attribute interval_kind, IntervalKind
      attribute notation, Notation
      attribute unit, Unitsml
    }

    enum UncertaintyCategory {
      value standard
      value expanded
      value coverage-interval
    }

    enum Notation {
      value absolute
      value concise
    }

    enum IntervalKind {
      value shortest
      value probabilistically-symmetric
    }
  }

  enum FontVariant {
    value "bold"
    value "italic"
    value "bold-italic"
    value "sans-serif"
    value "sans-serif-italic"
    value "sans-serif-bold-italic"
    value "bold-sans-serif"
    value "monospace"
    value "fraktur"
    value "bold-fraktur"
    value "script"
    value "bold-script"
    value "double-struck"
    value "normal"
  }
}

5.3  The composition

diagram PlurimathComposition {
  association HasParameters {
    owner Formula
    owner_type composition
    member_type Structure::Node
    member_multiplicity "1..n"
  }

  association HasOperands {
    owner Functions::Function
    owner_type composition
    member_type Structure::Node
    member_multiplicity "0..n"
  }

  association HasRows {
    owner Layout::Table
    owner_type composition
    member_type Layout::Tr
    member_multiplicity "1..n"
  }

  association HasCells {
    owner Layout::Tr
    owner_type composition
    member_type Layout::Td
    member_multiplicity "1..n"
  }
}

Every concrete function class of Annex A is a Function with a fixed operand count and order; the abstract shapes above (unary, binary, ternary, nary) are the families the concrete classes specialise.

5.4  Root and ownership

A formula tree has exactly one root, a Formula. The root holds the ordered top-level nodes and the presentation options; descendant nodes carry none. Display style, font defaults and line width are decided once, at the root, and applied during rendering.

5.5  Content nodes

A Symbol holds one registry reference: a glyph, an operator name or a named constant from the symbol space of the registry (1 438 entries at this edition). The class carries the per-format renderings; the tree carries only the reference.

A Number holds the numeral as written. The tree does not parse numbers into machine values — evaluation is a separate step (document 1004). Negative signs are not part of a Number; a minus is a Symbol sibling.

A Text holds literal text to be typeset upright, copied verbatim by every surface, escaping only what the target format requires.

5.6  Function nodes

A function node is an instance of one of the concrete classes of Annex A. Operand order is normative and stable across editions: Frac renders its first operand as the numerator and its second as the denominator in every surface; Root renders its first operand as the radicand and its second as the degree. A reader may not reverse operand order to accommodate a quirk of its input; the surface writers absorb those quirks.

The nary family carries a nary_value (∑, ∏, ∫, ∮) that the MathML and OMML surfaces emit on nary constructs.

5.7  Tables, fonts and fences

A Table holds Tr rows of Td cells; the concrete table class determines the delimiters and alignment semantics of the output, the row and cell structure is shared. Mlabeledtr is a row carrying a label. Cases renders a left brace with a null right delimiter on every surface.

A FontStyle holds one operand and one FontVariant; MathML emits it as mathvariant, OMML as run properties, LaTeX as the corresponding command, UnicodeMath as the corresponding mathematical alphanumeric character where one exists.

A Fenced holds its content and its open and close symbols; Left and Right declare the halves separately in the linear surfaces.

5.8  Units and uncertainty

A Unitsml embeds a unit expression written in the asciiunits content language (CalConnect 36817) together with the four renderings the UnitsML system supplies (CalConnect 36816). The tree performs no unit arithmetic: every surface emits the UnitsML-provided form for its format, and the XML form stays available machine-readably.

An Uncertainty attaches an uncertainty to a value expression. Its fields are specified in document 1002 and stated here in summary: the value, the category (standard, expanded, coverage interval), the magnitude or endpoints, the coverage factor and probability where present, the interval kind, the notation and the unit; the model-level contract stated here is that an uncertainty is carried as a node, rendering never recomputes it, and a surface without a faithful form for its category renders the category’s declared fallback from document 1002 and nothing else.

5.9  Presentation constructs

Intent and Semantics carry the MathML 4 intent and semantics constructs. Phantom renders its operand as space of the operand’s measure. Menclose, Merror, Mglyph, Mpadded, Ms, Msgroup, Msline, Multiscript, Mlabeledtr, Linebreak, None, Longdiv, Cancel, Scarry, Scarries, Obrace, Ubrace, Rule and Color model their host-format constructs under the names of those constructs.

5.10  Invariants

These properties hold for every tree a conforming implementation produces and consumes.

5.11  Quantity assertions

A tree may carry a quantity assertion: a statement that a subtree denotes a named quantity kind. The assertion is data — an intent annotation — and the tree performs no arithmetic gating with it. The semantics of assertions and their use in evaluation are specified in document 1004.

5.12  Normalisation

The tree form is canonical within a model version. Constructions that differ only in incidental ways — a lone parameter held directly versus wrapped in a single-child container, equivalent fence pairings, a unary function written with or without explicit grouping — produce the same canonical tree after normalisation, and normalisation is applied at construction time, not at render time. Writers therefore never normalise: they render what the tree holds.

Structural equality ([formula-tree]) compares normalised trees. Two trees that are equal up to normalisation are equal.

6.1  General

The registry is the versioned catalogue of everything the model can name: the symbol entries (6.3, Paragraph 1) and the function entries (Clause 12). It exists so that the vocabulary of the system is data, not code spread across readers and writers.

6.2  Entry shape

A registry entry names one thing the model can represent and carries its renderings. The entry is an LML model:

models Registry {

  class SymbolEntry {
    attribute name, String[1]
    attribute glyph, String
    attribute mathml, String[1]
    attribute latex, String[1]
    attribute omml, String[1]
    attribute unicodemath, String[1]
    attribute categories, Category { cardinality 1..n }
    attribute status, EntryStatus[1]
  }

  class FunctionEntry {
    attribute name, String[1]
    attribute operands, String[1]
    attribute fallbacks, String { cardinality 0..n }
    attribute status, EntryStatus[1]
  }

  enum Category {
    value greek
    value operator
    value arrow
    value relation
    value logic
    value trigonometric
    value nary
    value accent
  }

  enum EntryStatus {
    value active
    value deprecated
  }
}

Prose restatement of the fields:

Entries are immutable once published. A correction to an entry is a new registry edition, never a mutation.

6.3  The symbol space

The symbol registry at this edition contains 1 438 entries, one implementation class each, generated from the registry data. The space covers the Greek alphabet (upper and lower), Latin letters in their mathematical roles, binary and relation operators, arrows, set and logic symbols, integrals and nary operators, accents and decoration forms, and the named constants of the input notations.

The complete listing is generated from the registry; this document does not print it. Annex B shows representative entries per category and the lifecycle of an entry.

6.4  Generation

The symbol classes and the parser vocabulary of each input notation are generated from the registry data. Generation is deterministic: the same registry edition produces byte-identical generated sources. A build that regenerates and finds a diff fails.

The generated artifacts are committed, and the build compares them against the registry as a drift check; a hand-edit to a generated file that survives regeneration is a defect.

6.5  Collision discipline

A new entry whose name or glyph collides with an existing entry, or with a name reserved by the model (Formula, Symbol, Number, Text, Function, the class names of Clause 12), fails the build. The registry does not permit two entries to share a class name, and the model does not permit an entry to shadow a model class.

6.6  Versioning

The registry is editioned with this document series. An entry’s renderings are stable within an edition: a writer using edition 1 entries produces the same bytes for the same tree across all model versions that declare edition 1. New entries join at the next edition; renderings of existing entries do not change within an edition.

6.7  Unit terminals

The unit expressions that may appear inside a Unitsml node are not registry entries of this document. They come from the UnitsDB dataset through the asciiunits artifact of the UnitsML series (CalConnect 36814, 1006), and the model consumes them as opaque validated content. Nothing in this registry duplicates a unit name, a prefix, or a quantity — the registry’s single source of truth for units is the UnitsDB dataset.

7.1  The surfaces

The model renders to six surfaces:

Each surface has one entry point on the root and one rendering rule per node class. The math zone printer (to_asciimath_math_zone and its per-format siblings) is the diagnostic surface: it prints the tree as the indented notation of [conventions]-style examples.

7.2  Stability

Writers are deterministic. The same tree rendered by the same model version produces the same bytes, and a conforming implementation reproduces those bytes. Renderer output is covered by replay corpora: for each surface there is a frozen set of trees with frozen expected byte sequences, and a writer change that changes any of those bytes is a model-version change, not a patch.

7.3  Fallbacks

Some constructs have no faithful form in some surfaces. Each such pair has one declared fallback, recorded with the class in Clause 12, and the writer emits the fallback and nothing else: no marker, no warning channel in the output. Typical fallbacks: colour is dropped in LaTeX output when no colour package context is present, intent annotations are dropped in surfaces without annotation mechanisms, Mglyph degrades to its alt text in OMML.

7.4  Lossless and lossy directions

A surface is lossless when reading its output back yields a tree equal to the rendered tree. AsciiMath, MathML, OMML, LaTeX and UnicodeMath are the lossless directions of the readers defined in document 1003, each with the exceptions that document enumerates. HTML is a display surface: reading it back is not part of the contract, and its renderings optimise presentation.

7.5  Construct mapping

The same tree renders through every surface. The mapping below is the normative correspondence between node families and the constructs each surface emits; the per-class notes of Clause 12 refine it.

Where a family has no faithful construct in a surface, the declared fallback applies ([fallbacks]); the mapping above lists only the faithful forms.

7.6  OMML specifics

The OMML surface emits run properties (fonts, styles) from font style nodes, nary constructs from the nary classes, matrices from the table classes, and preserves linebreak semantics from Linebreak nodes and from the root’s linebreak option. Display style: the root’s display flag selects m:oMathPara wrapping; inline rendering omits it.

7.7  MathML specifics

The MathML surface emits MathML 4. Intent annotations carried by Intent nodes become intent attributes; Semantics nodes become semantics elements with their annotations as annotation children. Font style nodes become mathvariant. Tables become mtable/mtr/mtd, with labelled rows as mlabeledtr. Numbers become mn, symbols become mi or mo per their registry entry, and text becomes mtext.

7.8  Display and inline

The root’s display style selects between the display and inline forms of each surface: MathML toggles display="block"; OMML toggles the m:oMathPara wrapper; LaTeX and UnicodeMath choose display-only constructs (display fractions, centred nary limits) over their inline forms; HTML applies the display style class. The tree content is identical in both forms; only the surface presentation changes.

8.1  General

9.1  Adding a node class

A new construct enters the model as a new class with: its operands, its registry entry (if it names a symbol), its per-surface rendering rules, and — where a surface has no faithful form — its declared fallbacks. No existing class changes. The collision build of Clause 6 applies.

9.2  Adding a registry entry

A new symbol or constant joins the registry per the entry lifecycle of Annex B. Generated sources regenerate; existing byte sequences are unchanged.

9.3  Adding a surface

A new output format is a new set of per-class rendering rules behind one root entry point. The node classes are untouched: the per-format field printers on the base are extended with the new surface’s printer, and each class supplies its rule. A surface that ships without a rule for a class fails the build — render totality (Clause 7) is enforced at build time, not discovered at run time.

9.4  Adding an input format

Readers are outside this document (document 1003). This document constrains them in one way: a reader ends at the tree. A reader that requires a change to a node class to accommodate its input is a model change and follows [adding-a-node-class].

9.5  Deprecation

A node class or registry entry is deprecated by marking it in the registry and this document, keeping its behaviour byte-stable, and removing it at a stated edition. Nothing is removed silently and no published output changes between the deprecation and the removal.

9.6  Worked extension

10.1  General

11.1  What conformance covers

An implementation of this document is an implementation of the math model: the tree, the node classes of Clause 12, the registry behaviour, and the writers of the six surfaces. Readers and the uncertainty and evaluation semantics are covered by documents 1003, 1002 and 1004; conformance to those documents is claimed separately.

11.2  Conformance classes

A conformance claim names the classes it makes. A claim of render-<format> carries model with it: no surface can be claimed without the tree it renders.

11.3  The render corpus

The render corpus is a frozen set of trees and, per surface, their expected bytes. A corpus entry states its provenance (the tree’s construction, the model version that froze the bytes) and is replayed without modification. Corpus bytes change only at an edition: a new corpus entry joins frozen; a frozen entry never changes.

11.4  Drift

An implementation whose output for any frozen entry differs from the corpus bytes does not conform at the model version the corpus was frozen against, whatever its own version string says. Divergence is resolved by a model-version change and a new corpus entry, or by fixing the implementation.

12.1  General

This annex enumerates every function class of the model at this edition: 103 function classes, 14 font styles and 10 table classes. The list is normative. A class’s operands column uses 1, 2, 3, or “rows” for the table containers.

12.2  The inventory as a model

lml "1.0"

models FunctionInventory {

  package Elementary {
    class Abs
    class Arg
    class Ceil
    class Deg
    class Det
    class Dim
    class Exp
    class Floor
    class Gcd
    class Glb
    class Hom
    class Inf
    class Ker
    class Lcm
    class Lub
    class Max
    class Min
    class Mod
    class Norm
  }

  package Trigonometric {
    class Sin
    class Cos
    class Tan
    class Cot
    class Sec
    class Csc
    class Sinh
    class Cosh
    class Tanh
    class Coth
    class Sech
    class Csch
    class Arcsin
    class Arccos
    class Arctan
  }

  package Logarithmic {
    class Ln
    class Lg
    class Log
  }

  package ScriptPlacement {
    class Power
    class PowerBase
    class Base
    class Sup
    class Ul
    class Underover
    class Over
    class Overleftrightarrow
    class Overset
    class Underset
    class Stackrel
    class Substack
    class Limits
    class Lim
    class Liminf
    class Limsup
    class Multiscript
  }

  package Fractions {
    class Frac
    class Root
    class Sqrt
    class Longdiv
    class Cancel
    class Scarry
    class Scarries
  }

  package Fences {
    class Fenced
    class Left
    class Right
    class Obrace
    class Ubrace
  }

  package Accents {
    class Bar
    class Vec
    class Hat
    class Tilde
    class Dot
    class Ddot
  }

  package Calculus {
    class Sum
    class Prod
    class Int
    class Oint
    class Nary
  }

  package Tables {
    class Table
    class Td
    class Tr
    class Mlabeledtr
    class Matrix
    class Bmatrix
    class Pmatrix
    class Vmatrix
    class Cases
    class Array
    class Align
    class Eqarray
    class Split
    class Multline
  }

  package TextAndAnnotation {
    class Text
    class Mbox
    class Intent
    class Semantics
  }

  package Presentation {
    class Phantom
    class Menclose
    class Merror
    class Mglyph
    class Mpadded
    class Ms
    class Msgroup
    class Msline
    class None
    class Linebreak
    class Rule
    class Color
  }

  package Measurement {
    class Unitsml
    class Uncertainty
  }

  package Bases {
    class UnaryFunction
    class BinaryFunction
    class TernaryFunction
  }
}

The operand shape of each class is the family it belongs to in [formula-tree]: the Elementary and Trigonometric classes are unary with an optional limit where their input notation carries one; Log and Lg are unary with an optional base operand; the ScriptPlacement classes are binary (Power, Over, Underset, and the rest) or ternary (PowerBase, Underover); the Calculus classes are nary; the Tables containers hold rows. The tables below give the semantics and surface notes per class.

12.3  Elementary functions and operators

Elementary function classes:

12.4  Trigonometric and hyperbolic

Trigonometric and hyperbolic classes:

12.5  Logarithmic and exponential

Logarithmic and exponential classes:

12.6  Script placement and limits

Script placement and limit classes:

12.7  Fractions, roots and cancellation

Fraction, root and cancellation classes:

12.8  Fences and delimiters

Fence and delimiter classes:

12.9  Accents and decorations

Accent and decoration classes:

12.10  Calculus and nary operators

Calculus and nary operator classes:

12.11  Tables

Table classes:

12.12  Text and annotation

Text and annotation classes:

12.13  Presentation constructs

Presentation construct classes:

12.14  Units and uncertainty

Unit and uncertainty classes:

12.15  Generic bases

These are the abstract bases the concrete classes specialise. They appear in trees only when a reader needs a function with no concrete class, which is a defect to be fixed at the model level.

12.16  Font styles

The 14 font style classes apply a mathematical font variant to their operand. Each carries one operand; the surfaces carry the variant per the mapping.

Where an alphanumeric range does not exist for a character, the UnicodeMath surface renders the plain character with the variant dropped, per the fallback rule.

13.1  General

14.1  Defining an entry

An entry is a row of the registry data: name, glyph, the four format renderings, categories. Two examples:

The generated symbol class is derived from the name: Plurimath::Math::Symbols::Alpha, Plurimath::Math::Symbols::Plusminus. The class holds the entry; the tree and the readers refer to the class.

14.2  Adding an entry

The steps of a new entry, in order:

No step reorders: a glyph that fails collision never ships; a corpus entry is never retrofitted after publication.

14.3  Function entries

Function classes are not registry rows in the same sense — their semantics live in this document (Clause 12) and their renderings in their class definitions — but they obey the same discipline: a new function class ships with its operand definition, its per-surface rules, its fallbacks, and a frozen corpus entry per surface.

14.4  Deprecation path

A deprecated entry keeps its class, its glyph and its renderings byte-stable. The registry marks it deprecated with the edition of removal. Readers that encounter the entry keep parsing it; writers keep writing it. At the removal edition, the class is deleted, the corpus entries that used it are superseded, and the registry count decreases.

14.5  Counting

The symbol-space count is asserted by the build against the registry data, so this document’s count and the registry cannot disagree silently. Edition 1: 1 438 symbol entries, 103 function classes, 14 font styles, 10 table classes.

14.6  Representative symbol entries

The entries below are drawn from the registry at this edition; each row is one symbol entry with its input tokens and its LaTeX rendering as published.

An entry carries more than the table shows: each row’s registry record also holds the MathML and OMML renderings and the additional input tokens (an entry may have several accepted tokens per notation; Alpha accepts alpha and the numeric character reference, for instance). The tables show the primary tokens.

15.1  General

Vectors illustrative of the conformance classes of [conformance-classes]. Each vector states the construction, the property under test, and the expected outcome. The replay corpora carry the frozen versions of these vectors.

15.2  Structural equality (class model)

15.3  Math zone (class model)

15.4  Render replay (class render-<format>)

15.5  Fallback verification (classes render-*)

15.6  Byte stability (all render classes)

15.7  Model identity (class model)

15.8  Units embedding (classes render-*)

15.9  Fallback discipline (classes render-*)

15.10  Registry stability (class model)

15.11  Normalisation (class model)