Program API#

A predicate the file states of its data, under the name it wrote in assumptions:.

predicate is true at every coordinate of its frame — the product of every dim the two masks name — that where admits, a missing row reading as false as it does in any mask. Nothing here is decidable at load: both sides are the data's, which is why the consumer attaching it checks.

A value defined by region — exactly one region applies at each coordinate.

The regions are disjoint and total, so a consumer adds them rather than ranking them. Not a shape operator: every region spans the dims the expression does.

A scalar constant.

lhs sense rhs for each coord combination of dims.

Either side may carry variables and constants alike; which side a consumer gathers them onto is its own arrangement and not stated here. where masks out coord combinations (row absence, like variables).

How many coordinates predicate admits along over, against a literal — count(points, over=bp) >= 2.

The count is one number per coordinate of dims, which is every dim predicate reads minus over, so a claim about each curve is written without saying "each curve". A predicate a leaf reads arrives as a Mask, where a connective's operand is a bare Predicate: a walk recurses through the second and stops at the first.

Compare a dimension's own coordinates against a literal.

A dimension, as the file declares it.

Compare where a row sits along a dimension against a position — position(snapshot) == 0.

Both sides are integers, negative counting from the end. With a partition the position is counted within each group the relation makes (Partition), whose joined columns' dimensions the frame carries.

One relation as one call reads it — which columns are consumed, which produced, which joined on.

The declaration fixes no direction; the call does, and this is the one it named. name is the relation's, as Program.relations keys it. consumed, produced and joined are roles — column names of relation, which maps every role to its dimension and names the key. joined is the key roles the call did not name (every role, for a bare relation): the join keys on them, and a value role left unnamed is not read.

489
490
491

def dim(self, role: str) -> str:
    """The dimension *role* ranges over."""
    return self.relation.dim(role)

Quotient numerator / divisor, the divisor variable-free wherever the math reads it (mathspec.degree).

A constraint's dual — its shadow price, read after the solve.

Stands only under an ExpressionDeclaration the math never reads: the loader refuses dual() anywhere a solver ingests. One value per coordinate of the named constraint's own dims frame: the leaf reshapes nothing, like a parameter.

Compare two variable-free expressions, coordinate by coordinate — p_min <= 0.5 * p_max.

dims is every dim either side carries. A side whose value is absent at a coordinate — a parameter row missing, a translation that vacated it — makes the comparison false there, as a null does in every other comparison; under a summing operator the absent term is one fewer.

A named quantity — one the math reads, or one only read back after a solve.

in_math where the objective or a constraint reads it, directly or through another entry or a macro; its body then stands inside Program.roots and is held to the degree rules where it is read. Otherwise nothing a solver sees contains it: it is a reported quantity, its body held to no degree, the one place a Dual may stand. A bound and a where name no entry, so neither decides this.

Which of the language's constructs one program uses.

A subset, never the whole: an empty field says this program does not use the construct.

Sum operand through a relation: the dims direction consumes go, the dims it produces arrive, the dims it joins on stay.

The join keys on the consumed columns and every joined column, and the operand carries every dim consumed or joined on.

One link of a piecewise: block: an expression tied to the breakpoints a values parameter holds.

sign is '==' where the link is pinned to the curve, and one side of it where the link is bounded by the curve instead.

A resolved where and the questions the language answers about it.

root is the predicate a consumer dispatches on with isinstance; every question below is derived from it. Construction folds, so a boolean literal stands at the root or nowhere in it, and refuses an unresolved tree.

Product of two operands.

Affine where at least one factor is variable-free; degree 2 where neither is, which mathspec.degree admits in a QuadraticPosition alone.

A use of an expressions: entry, standing where its name was written, with the entry's body under it.

Its value is its body's: a consumer building rows steps through it, as children does. It is kept as a node rather than written in so the typesetter can print the symbol where the name stood and define it once. Every use of one entry holds the one node resolution built for it, whose body is the ExpressionDeclaration.expression of that entry.

Objective — scalar, every reduction in it one the file wrote.

A parameter reference — contributes to the constant part.

Compare a parameter against a literal, element-wise.

Shape declaration; data is attached at execution time by name.

dtype is what the declaration claims the values are, and a consumer attaching data refuses a column that is not it — so the declaration is what is read, rather than whatever the column happens to hold.

True wherever the named parameter is non-null and finite.

dims is the parameter's own, copied off the declaration during resolution; every leaf below that names a declaration carries its dims (or over) the same way.

One relation as a partition steps along it — the key column stepped along, the group columns, and the key columns joined on.

name is the relation's, as Program.relations keys it. along, group and joined are roles — column names of relation, which maps every role to its dimension and names the key. along is the one key column over the dimension stepped along, and the frame keeps it. group is the value columns within= named, read at the row's key. joined is the other key columns, whose dimensions the frame carries. Nothing is consumed and nothing is produced: the frame does not change.

526
527
528

def dim(self, role: str) -> str:
    """The dimension *role* ranges over."""
    return self.relation.dim(role)

A piecewise: block as the curve it states, which expand writes out as rows.

A program of a spec that still declares one carries it here, typed; a program of the expanded spec carries the rows instead, under Program.variables and Program.constraints, and what the method assumes of the breakpoints under Program.assumptions. A consumer building rows takes the expanded spec.

base ** exponent, both variable-free wherever the math reads it.

The language refuses a variable anywhere under it (mathspec.degree), so in the program a solver sees it is degree 0 and folds to one number per coordinate like any other parameter arithmetic.

A complete declarative description of a mathematical program, with no data in it.

Every group of declarations is keyed by the name the file wrote, in the order it wrote them, and is read-only: the mappings are wrapped at construction, so a consumer cannot rewrite what another consumer reads. A whole program is not hashable — the declarations and expression nodes inside it are, which is what dedup and memoisation ask for.

915
916
917

def relations_of(self, dimension: str) -> Mapping[str, RelationDeclaration]:
    """The relations with a column over *dimension*, by name."""
    return Sealed({n: lk for n, lk in self.relations.items() if dimension in lk.dims})

Read operand through a relation — the adjoint of GroupSum.

The dims direction consumes go and the dims it produces arrive, one value per coordinate because the read takes value columns at a key the result fixes, which the loader checks. The join fans out, many produced tuples sharing one consumed tuple — at each coordinate of the joined columns, which the operand carries and the result keeps.

operand read through a relation — at(has_curve, by=converter_of, over=converter, into=flow).

True at a coordinate where the relation has a row and operand holds at the coordinate that row reads. False where the relation has no row, which is what a missing row already means in a mask. The dims direction consumes go and the dims it produces arrive, as Pullback's do.

One read along an axis whose distance only data can say.

One region of a Cases: where it applies, and the value there.

when is stated on every region; the one the file wrote as otherwise: carries the negation of the others.

Compare one value column of a keyed relation against a literal — period_of == 2030.

column is the role read, and dims the dimensions of the key columns: the leaf is read at them, one value per coordinate.

One declared relation: a table over its columns, single-valued per key.

columns maps each role to its dimension in the order the table carries them, the key's roles first; key is the roles a row is identified by, and values the rest — every role is a key role for a bare relation, which is one with no value columns. Every value is checked when the data is attached to be a label of its column's dimension, and the table to have one row per key tuple — which keeps a mistyped label from silently dropping its terms in the join that places them, and is what lets at read one value.

466
467

def dim(self, role: str) -> str:
    return self._dim_of[role]

True where the relation has a row at the frame's coordinates.

dims is what the frame supplies: the key's dimensions, whose row is then the one the key finds — every column's for a bare relation, where a row is the whole tuple.

Compare a value column of one keyed relation with one of another — from_bus != to_bus — row by row on the key.

Both keys are over the same dims, and the two columns are over one dimension, so a match is possible at all.

What building one dimension a window at a time asks of a driver, and what it would break.

A rolling-horizon or myopic driver cuts an axis into windows and builds each on its own, and a decomposition cuts the same axis and solves each piece on its own. What the program can say is whether every row it builds is then complete inside one window: how far a row reads ahead along the axis, which declarations tie the axis together so that no window holds them, and — the same fact read as a set — which rows and columns are left over as the border every window shares. It cannot say whether the windowed answer is the one a whole-horizon solve would give — a store carried over one row windows cleanly, and a rolling solve of it is still a different answer — which is the driver's design and not the spec's.

What a row reads behind is not reported. A window starts where the driver puts it, and what its first rows meet there is the edge policy: the opening state a rolling horizon seeds, and the driver's to carry.

837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862

def resolved(self, least: Mapping[str, int]) -> Separability:
    """The same verdict with each named offset folded into [`ahead`][].

    A driver holding the data reads the least value of each parameter an
    [`undecided`][] reach names and hands it here, so the rule that
    turns a value into a reach — a negative offset reads ahead by that
    much, a positive one reads behind and asks nothing — has one home.

    Args:
        least: Parameter name to the least of its values. A reach through
            a relation — a partition, a coordinate — cannot be folded this
            way and stays undecided, as does a parameter left out.

    Raises:
        KeyError: A name no undecided reach along this axis waits on.
    """
    waiting = {reach.name for reach in self.undecided if reach.kind == 'offset'}
    for name in least:
        if name not in waiting:
            raise KeyError(
                f"'{name}' is not a parameter an undecided reach along '{self.dimension}' waits on. "
                + did_you_mean(name, sorted(waiting))
            )
    folded = {reach for reach in self.undecided if reach.kind == 'offset' and reach.name in least}
    ahead = max([self.ahead, *(-least[reach.name] for reach in folded)])
    return replace(self, ahead=ahead, undecided=tuple(r for r in self.undecided if r not in folded))

One special-ordered set per coordinate of the variable's dims minus along.

The only declaration that adds neither a column nor a row: it names columns a consumer already has and says what may be nonzero among them. Which dims those are is the variable's own dims and is read from it: a copy here would be a second home for a fact (Program.variables).

Sum operand over the named dims, removing them from the result.

Re-index along one dimension: the result at t is operand at t - offset.

wrap is edge='wrap' in the file: periodic, and stated on every node. fill is what an acyclic shift leaves behind: None leaves the vacated positions absent, so the row drops; a number makes them present and contribute it. Always None under wrap.

offset is an integer, or the name of an integer parameter that does not depend on along and carries its sign in the values.

partition is a relation with a key column over along (Partition), and the translation then happens inside each group its within= columns make: the neighbour is the one before in the same group, the edge is the group's, and a wrap closes each group onto itself. A coordinate the relation sends nowhere reaches nothing.

operand read at a neighbouring coordinate — shift(points, along=bp, offset=1).

False where the translation vacates, and there is no edge= to state. The arithmetic translation needs one because no number is neutral and inventing one changes the answer; false is what a missing row already means in a mask, so the predicate form has the value the language already gives it.

A variable reference — one term per existing variable row.

True at the coordinates where the named variable exists.

Sum operand over a trailing window along one dimension.

The result at t is the sum of the operand at every position from t - width + 1 through t, so a width of 1 is the operand itself. The dimension survives: this replicates terms onto the positions that can see them rather than reducing anything away.

width is a whole number, or the name of an integer parameter when the window differs per entity — a minimum up time, a rolling budget, a delivery horizon. A named width may not depend on the dimension being summed over.

wrap says whether the window reaches around the start of the axis instead of stopping short at it, and is stated on every node.

partition names a relation over that dimension, and the window then stops at each group's edge. Positions are counted inside the group, so a coordinate the relation places nowhere reaches nothing — not even itself.