Glossary#

We use several words in these docs with one fixed sense. Unlike constructs like parameter or macro (defined in their respective language pages), no single reference page defines these words.

The file and its readers#

Spec : Short for specification. A spec is the optimisation problem that a file states: its dimensions, the data it expects, its decisions and its rules, but no data. In Python it is a Spec, the file as written and checked, which to_spec returns (reading a spec and its program).

Model : A spec with data attached, which an engine builds and a solver takes. mathspec alone cannot hold a model.

Program : What the file means once it has been parsed by mathspec: every name typed, every macro expanded, every operator a node. In Python it is a Program, accessed at spec.program.

Consumer : A tool that reads a spec: an engine that attaches data and builds the model, a renderer such as the typesetter, or a checker.

Load : What the to_spec method does. "Refused at load" means to_spec raises, before any data exists.

Attach : What a consumer does when it combines data with a program. A consumer can only check a rule involving data after it has attached; mathspec checks no such rule itself. The docs will never say "bind" when they refer to this, so that bound means one thing: a lower or upper limit on a variable (variables).

Provide : What a host model does for a name under given:, when layering several files. The host model will hold a column or a row family of that name, on the same frame. A consumer is responsible for checking that the host provides each given name (what a program does not build).

Section : One of the thirteen top-level keys of a file, such as parameters: or given:, and the entries under it (file shape).

Entry : One named item under one section: one dimension, one parameter, one constraint (file shape). In Python, an entry is a *Spec in mathspec.spec, such as VariableSpec, and a class with the bare name in mathspec.program, such as Variable.

Coordinates#

Label : One member of a dimension, wind say. The labels arrive with the data, in the order that shift, sum_back and position() count along.

Coordinate : One point of an entry's dimensions: one generator in one snapshot. A variable has one column at each coordinate it is built at, and a constraint has one row.

Frame : The dimensions over which an entry ranges. The data of an expression, a mask and a bound parameter must fit inside their defined frame (how dimensions combine).

Group : The labels of a relation value column, used for grouping the relation's keys. within=<column> can be used to apply shift, sum_back or position() separately per group.

Masks and absence#

Mask · predicate : A predicate is a true-or-false expression in the where grammar. A mask is a predicate on an entry, and the coordinates it admits.

Absence : No value at a coordinate. A masked-out variable has no column there, and a row that reads it is not built (absence).

Missing row : A coordinate that a parameter's or a relation's table has no row for. Its missing: says what it is: refused when the data is attached (refused, the default), absence (absent), 0 in arithmetic and false in a where (neutral), or a value (a missing row).

Kinds of construct#

Primitive : A construct built into the language, which every engine implements and the typesetter prints. This covers the operators and the where comparisons.

Formulation : An entry that states ordinary variables and constraints rather than being one: piecewise: and sos: (piecewise curves and SOS).

New constructs (primitives, formulations, macros) are not allowed (how a new construct enters).

Words with two senses#

The meaning of some words changes depending on the context in which they appear in the docs.