Spec API#

Bases: _StrictBlock

What the spec assumes of its data: a predicate every coordinate it is checked at has to satisfy.

Written in YAML as a bare where string, or as a mapping once it carries a where: or a description:, and serialised back to whichever form it was written in::

assumptions:
  efficiency_is_a_fraction: "efficiency > 0 AND efficiency <= 1"
  bounds_do_not_cross:
    holds: "p_min <= p_max"
    where: "p_min"
    description: a unit with no minimum is unconstrained below

The language decides nothing about the numbers, so the consumer attaching the data checks it, and refuses the data where it does not hold.

Bases: _StrictBlock

Variable bounds — each side is a finite number, a parameter name, or None where it is open.

An omitted bound leaves the variable unbounded on that side, not implicitly non-negative. An infinity is refused: an open side is null, and the other infinity leaves no value at all.

Bases: _StrictBlock

A declared constraint: one rule, over one frame.

Bases: _StrictBlock

A declared dimension, the dtype its coordinates must be, and whether their order means anything.

A dimension is an axis and nothing else: it declares that the axis exists and what its coordinates are typed as, never which coordinates there are — those are data, and arrive when the data is attached. The maps its members carry — a generator's bus, a snapshot's period — are top-level relations: (RelationBlock), keyed by their own name.

Bases: _StrictBlock

A named quantity: one arithmetic expression, referenced by the math or read back after a solve.

Written in YAML as a bare string, or as a mapping once it carries a description: — and serialised back to whichever form it was written in, so a round trip through Spec.to_yaml reproduces the file::

expressions:
  total_generation: sum(p, over=generator)
  emissions:
    expression: sum(p * rate, over=generator)
    description: CO2 released, the quantity the cap bounds

dims: declares the frame the quantity is read over. A plain entry may leave it out, and its body then decides the frame; a body that carries a dimension the frame does not name is refused, and one that carries fewer is constant along the rest. A quantity whose value varies by region is written as cases: over a declared dims:, with an otherwise: for the rest — see the language reference.

adds_to: adds this entry as a term to the sum it names, a given: expressions: entry of this file: a write, where the given entry is the read. merge adds every term to that name by name, after the body a file defines where one does. The term is read over at most the frame the given entry states, and does not read the name it adds to.

Bases: _StrictBlock

One region of a named expression: the value, and when it is the value.

Every case says where it applies. The value wherever none of them does is the block's otherwise:, which is written outside cases: because it is not a region like these — it is what is left::

cases:
  opening: { when: "position(snapshot) == 0", expression: p_max }
otherwise: 0

Bases: _StrictBlock

What this file reads and does not build, by kind. Closed at the five kinds.

Bases: _StrictBlock

A row family this file reads the dual of and another model builds.

The frame says how many duals there are and what indexes them, which is what dual() needs. There is no expression:, because nothing here builds a row.

Bases: _StrictBlock

A named expression this file reads and another file defines.

The frame is all this file states. This file reads the name as a quantity over that frame, affine in the columns, as it reads a given variable: the body is the definer's, and the composed spec holds the body to the rules of every place this file reads it.

A named expression of this file may add to the name with adds_to:. merge then writes every term the files add after the body a file defines, or as the whole body where no file defines it. The file itself reads the name as the whole sum, alone and composed.

Bases: _StrictBlock

A mask this file reads and another file defines.

The frame is all this file states, and it names the dims the definer's predicate reads. A where reads the name as data over that frame, true or false at each coordinate, since a mask reads nothing a solve decides: the predicate is the definer's.

Bases: _StrictBlock

Data this file reads and another file declares.

It says the frame and the dtype of a ParameterBlock, which are what this file reads: a where compares against the dtype, and the dim rules read the frame. What a missing row means is the declaring file's missing:.

Bases: _StrictBlock

A column this file reads and another file introduces.

The frame and the domain are all this file states. The file that introduces the column owns its bounds and its mask.

Bases: _StrictBlock

A parameterised expression template, defined in the YAML itself.

Language, not code: formals (args positional, kwargs keyword) shadow the spec's names inside the template, and every call site expands in the syntax tree before resolution reads the expression.

Bases: _StrictBlock

A named predicate: one where string, read wherever a where:, a when: or a holds: names it.

Written in YAML as a bare where string, or as a mapping once it carries a description:, and serialised back to whichever form it was written in::

masks:
  committable: "Generator_committable AND Generator_active"
  stands:
    where: build_year <= period_year AND period_year < build_year + lifetime
    description: the generator stands in this period

A bare mask name in a where string stands for its predicate, inside count, shift and at too. The mask's frame is the dims its predicate reads, so it declares none. A mask is a predicate, so it is never a value in an expression.

Bases: _StrictBlock

A declared objective function.

Bases: _StrictBlock

A declared parameter with dims and dtype, and what a missing row of its data means.

Bases: _StrictBlock

N expressions jointly pinned to a breakpoint-indexed piecewise curve.

Mirrors linopy.Spec.add_piecewise_formulation. Each link is [expression, values_parameter] or [expression, values_parameter, sign]: expression is any affine expression string, values_parameter names a parameter carrying the over dim, and sign bounds the link by the curve instead of pinning it (at most one non-"==", and only with exactly two links).

Bases: _StrictBlock

One link of a piecewise block: an expression pinned to a values curve.

Written in YAML as [expression, values] or [expression, values, sign] and serialised back to exactly that form, so a round trip through Spec.to_yaml reproduces the file.

Bases: _StrictBlock

A named relation between dimensions: the columns a row is keyed by, and the columns that key determines.

Each side is a dimension, a list of them, or a mapping of column name to dimension where two columns share one. key: is the claim the language checks when the data is attached: one row per key tuple, so every values: column is a function of it. A relation with no values: is bare — every column is in its key, a row is its own identity, and nothing reads it::

relations:
  gen_bus: {key: generator, values: bus}
  gen_bt: {key: [generator], values: [bus, technology]}
  zone_of: {key: [generator, period], values: zone}
  ends: {key: line, values: {bus0: bus, bus1: bus}}
  connection: {key: [generator, bus]}

A sum joins the table on the columns over= names and every other key column, and groups by the columns by=relation[...] names; a lookup joins on the columns it names. The declaration fixes no direction, and a column is named after its own dimension or after none, so a name in a call reads the same as a column and as a dimension. The map itself is data, and arrives with the rest of it, under the relation's name, one column per role.

Bases: _StrictBlock

A special-ordered set over one dimension of one variable.

One set per coordinate of the variable's dims minus along; the members are the variable's existing coordinates along along, in that dimension's declared order.

type: 1 admits at most one nonzero member, type: 2 at most two, and those two consecutive. A consumer with the concept takes the set as one; Spec.expand states it as binaries instead, and the rows it writes multiply by the member's own bounds, which is why a member needs both.

Bases: _StrictBlock

The declared math — one YAML file, or one dict, validated. Nothing here has seen data.

A Spec that exists has passed the whole language: constructing one by any route — to_spec, model_validate, the constructor — runs every load-time check, expression pass included, and raises LanguageError on a spec the language refuses. Holding one is the proof, so nothing downstream checks it again.

The API is the thirteen declaration sections plus version and description, three ways back out — to_dict for the spec as data, to_yaml for the file a reviewer reads, expand for the spec with its formulations written out as plain rows — and program, the spec typed, which every reader after load walks. Everything else on this class is pydantic's, not a contract this package keeps.

1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227

def expand(self, *kinds: Formulation) -> Spec:
    """This spec with its formulations written out as plain variables and constraints.

    A formulation states rows rather than being one — ``piecewise:`` states
    a curve, ``sos:`` states which members of a family may be nonzero.
    Expanding one writes those rows under names prefixed with the block's
    own, and drops the block. The result is a different spec: it declares
    more variables and constraints, so it does not compare equal to this
    one. It declares the same dimensions and parameters, so the same data
    attaches to both. Nothing is cached, so a second call builds the
    expansion again.

    Args:
        kinds: Which formulations to write out — ``'piecewise'``,
            ``'sos'``, or none of them for every one. They go in that
            order whatever order they are asked in, because a
            ``method: sos2`` curve emits a set and no set emits a curve.

    Returns:
        The spec with those blocks written out, or this same object where
        it declares none of them, so an expansion asked for the same kinds
        again returns itself. It is a spec like any other: [`to_yaml`][]
        writes it, and [`program`][] holds its rows.

    Raises:
        ValueError: *kinds* names something that is not a formulation.
    """
    wanted = _formulations(kinds)
    from mathspec.piecewise import expand_piecewise
    from mathspec.sos import expand_sets

    expanded = expand_piecewise(self) if 'piecewise' in wanted else self
    if 'sos' in wanted and expanded.sos:
        expanded = expand_sets(expanded)
    return expanded

1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142

@classmethod
@override
def model_validate(
    cls,
    obj: object,
    *,
    strict: bool | None = None,
    extra: ExtraValues | None = None,
    from_attributes: bool | None = None,
    context: object = None,
    by_alias: bool | None = None,
    by_name: bool | None = None,
) -> Self:
    """Validate a mapping, raising this package's exception tree rather than pydantic's.

    ``__init__`` is not wrapped the same way, because defining one makes
    pydantic run every after-validator twice.
    """
    try:
        return super().model_validate(
            obj,
            strict=strict,
            extra=extra,
            from_attributes=from_attributes,
            context=context,
            by_alias=by_alias,
            by_name=by_name,
        )
    except ValidationError as exc:
        raise schema_error(exc) from None

1169
1170
1171

def to_dict(self) -> dict[str, object]:
    """The spec as plain data. ``to_spec(m.to_dict())`` reproduces it."""
    return self.model_dump()

1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191

def to_yaml(self, *, canonical: bool = False) -> str:
    """The file a reviewer reads — including for a spec that never had one.

    Args:
        canonical: Write the normal form instead: declarations sorted by
            name, every expression printed from its parsed tree, one term
            of a sum per line. Two files that state the same spec write
            the same text, so what a diff shows is a difference in the
            spec. The normal form loads to the same spec and not to an
            equal [`Spec`][mathspec.spec.Spec], a reprinted expression
            being a different string.
    """
    import yaml

    if canonical:
        from mathspec.canonical import canonical_yaml

        return canonical_yaml(self)
    return yaml.safe_dump(self.to_dict(), sort_keys=False, allow_unicode=True)

Bases: _StrictBlock

A declared decision variable.