Program API#

One thing the language advises about a file it accepts.

Never an error: each is what a half-written spec looks like too. A consumer prints it, or filters on kind and subject; the text is the language's, so no consumer writes its own.

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

holds 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 position in a frame: the dimension whose labels it runs over, and the relation column it stands for.

A declared dimension is the axis Axis(dimension). A Join opens Axis(dimension, column) for each column it drops, so a column dropped and a column added over one dimension are two axes of one frame. Two axes are equal where both fields are, so a frame holds a dimension's own axis at most once however many join axes run over the same labels.

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.

One column of a relation: the relation's name, and the column's name in its entry.

A use of a conditions: entry, standing where its name was written, with the entry's condition under it.

Its truth is its body's: a consumer steps through it, as condition_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, as ExpressionReference does for an expression.

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).

True at the coordinates where the named constraint has a row. Only an assumption reads one.

A row exists where the constraint's where holds and every term outside a sum is present, which the data alone decides, before any solve.

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

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

A dimension, as the file declares it.

Compare a dimension's own coordinates against a literal.

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.

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

A constraint's dual — the rate the optimal objective rises with the constraint's right side, read after the solve.

Of lhs <= rhs it is the rate in d of lhs <= rhs + d, for every comparator and under either sense. Stands only under an NamedExpression 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 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 NamedExpression.expression of that entry.

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.

The variable that switches a piecewise: entry's curves on, as each curve reads it.

variable is the variable the file named: a binary, or an integer under method: incremental, which turns the curve off at 0 and, from 1 up, moves it by its point at the first breakpoint once per unit above 1. read is the gate at one curve: the variable on the entry's own frame, or the variable read through a relation, as at(..., by=) reads it. exists is where a curve reads the gate, and the curve is ungated elsewhere, its weights summing to 1; it is None where every curve reads it. A masked variable exists only on its mask, and a relation declared missing: absent may have no row for a curve, so both leave curves ungated; missing: 0 reads the variable as 0 off its mask instead, which pins those curves off. Under the relation's missing: refused every curve has a row.

A column or a row family this program reads and does not build.

The frame is the whole entry. A consumer looks the name up in the model this one is layered onto, checks the frame against what it finds, and refuses a name the host does not provide.

Data this program reads and another file declares: the frame the dim rules read, and the dtype a where compares against.

What a missing row means is the declaring file's missing:, so it is not here.

What a program reads and does not build, by kind.

Every group is empty in a program built from one whole spec. Every group is frozen at construction, like every group of Program.

Join operand to a relation on the columns columns joins on, one row per matching row of the relation.

The operand carries every dim joined on. The result has the operand's dims, less the dims joined on, plus the dims grouped by, plus one axis per column joined on and not grouped by (JoinColumns.axes), which stands for the relation's column and runs over its dimension. So a column dropped and a column added over one dimension stay two axes. A Sum over those axes is the group-by that follows the join, which is how sum(x, over=a, by=subject[b]) lowers. Where the grouped columns hold the relation's whole key, they determine every other column, the join opens no axis, and the bare Join is at(x, by=subject[a]): one value per row of the result, fanned out where several key tuples share the values joined on.

An axis is never a dim: a join that opens axes states the dims of the sum that closes them, and that sum removes only the dims its plain axes name.

One relation as one call joins it: the columns joined on, and the columns grouped by.

The entry fixes no direction; the call does, and this is the one it named. name is the relation's, as Program.relations keys it. joined and grouped are roles, which are column names of relation. relation maps every role to its dimension and names the key. joined is every column the join matches the operand on: the columns that leave the frame, and every key column the call does not name. grouped is every column of the relation the result keeps: the columns that arrive, and the same unnamed key columns. Both are in the order of the relation's columns: the key's first, each side sorted by role. A column in neither is not read, so a relation may gain a value column without changing what a call means.

A column both joined on and grouped by stays in the frame. One joined on and not grouped by is dropped, and one grouped by and not joined on is added, so the frame after the call is the operand's dims, less the dims joined on, plus the dims grouped by.

605
606
607

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

operand read through a relation, written at(has_curve, by=converter_of[converter]): a lookup Join of a condition.

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 columns joins on go and the dims it groups by arrive, as a lookup Join's do.

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

name is the link's key in the entry, and <entry>_<name> is the row the expansion writes for it. 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 link that walks a map reads the curve's weights through it, as at(..., by=) reads an array: by is the subject[map] the file wrote, and walk the join it resolves to. dims is the row the link builds: the entry's frame, or, for a walked link, that frame with the dims the join drops replaced by the ones it adds. reads says whether that row reads the entry's where through the relation, which it does when the mask carries every dim the join drops or keeps.

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

root is the condition 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.

1871
1872
1873
1874
1875
1876

def within(self, relations: Iterable[str]) -> Mask:
    """The mask read inside the rows of *relations*, where each of them, read at the mask's own coordinates, is true.

    A relation read anywhere else, as through ``shift`` or ``at``, is left as it is.
    """
    return Mask(_within(self.root, frozenset(relations)))

A missing: that reads a missing row by the label a map gives its coordinate.

At a coordinate with no row, the parameter reads as the fill of the label that the map column of the subject by gives that coordinate, and as otherwise where fill names no such label.

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 named condition — a conditions: entry, read wherever a where, a when or a holds names it.

It builds nothing of its own: every use stands as a ConditionReference with this condition under it, so a consumer reading a condition never looks the name up here.

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

in_math where the objective, a constraint or a term of a given expression reads it, directly or through another entry or a macro, and where it is such a term itself; 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.

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

The shape of a column; data is attached at execution time by name.

dtype is what the entry claims the values are, and a consumer attaching data refuses a column that is not it — so the entry is what is read, rather than whatever the column happens to hold. It refuses a null or NaN value too: a coordinate with no value has no row, and inf is a value.

Compare a parameter against a literal, element-wise.

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

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

A parameter reference — contributes to the constant part.

One relation as a partition steps along it: the key column it steps along, the columns it partitions by, and the key columns it joins on.

name is the relation's, as Program.relations keys it. along, grouped and joined are roles, which are column names of relation. relation 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. grouped is the value columns within= named, read at the row's key: the partition's group. joined is the other key columns, whose dimensions the frame carries. No column is dropped and none is added: the frame does not change.

680
681
682

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

A piecewise: entry 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 entries is keyed by the name the file wrote, sorted by name, and is read-only: the mappings are wrapped at construction, so a consumer cannot rewrite what another consumer reads. Every dims and frame in it is sorted by name, whatever order the file writes them in. A whole program is not hashable — the entries and expression nodes inside it are, which is what dedup and memoisation ask for.

1229
1230
1231

def relations_of(self, dimension: str) -> Mapping[str, Relation]:
    """The tables with a column over *dimension*, by name: a relation over it, or a subject with a map into it."""
    return Frozen({n: lk for n, lk in self.relations.items() if dimension in lk.dims})

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.

One table the data supplies: a relation's rows, or a dimension's labels, with a column per map of the subject.

columns maps each role to its dimension, the key's roles first and each side sorted by role; key is the roles a row is identified by: a relation's own columns, or the dimension for a dimension's table. Its values are the subject's maps, each named after the map, and none for a relation with no maps. 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. Program.relations keys a table by its subject's name, so a dimension's table shares the dimension's name.

564
565

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

571
572
573
574

def in_order(self, roles: Iterable[str]) -> tuple[str, ...]:
    """*roles* as [`columns`][] orders them: the key's first, each side sorted by role."""
    given = tuple(roles)
    return (*sorted(r for r in given if r in self.key), *sorted(r for r in given if r not in self.key))

567
568
569

def missing_at(self, roles: Iterable[str]) -> RelationMissing:
    """``absent`` where a read of *roles* may find nothing there: the table may lack the row, or a map its label."""
    return 'absent' if self.missing == 'absent' or set(roles) & set(self.partial) else 'refused'

Compare one map of a subject against a literal — snapshot[period] == 2030.

column is the map read, and dims the dimensions of the subject's own columns: the leaf is read at them, one label per coordinate.

True where the table has a row at the frame's coordinates, and with column set, a label in that map.

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. A bare relation name in a condition sets no column; subject[map] alone sets it, as outage[line] does.

Compare a map of one subject with a map of another, or of the same — line[bus0] != line[bus1] — row by row.

Both subjects are over the same dims, and the two maps refer to 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 entries 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.

1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167

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 that 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 entry 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 axes in over, removing them from the result.

An axis in over is a dimension's own, or one a Join under it opens (JoinColumns.axes): sum(x, over=a, by=subject[b]) lowers to a Sum over a Join, over the axis of each column the join does not group by. This node is the group-by that follows the join.

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 offset coordinates back along one dimension — shift(points, along=bp, offset=1).

A negative offset reads forward. Where the shift reads past the edge, the condition is false, as a missing row is false in any condition, so the file states no edge=.

True at the coordinates where the named variable exists.

A variable reference — one term per existing variable row.

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.