Spec API#

Bases: _StrictSpec

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

Written in YAML as a bare 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: _StrictSpec

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: _StrictSpec

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

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::

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

Its bare name in another condition stands for it, inside count, shift and at too. Its frame is the dims its condition reads, so it declares none. It is true or false, so it is never a value in an expression.

Bases: _StrictSpec

A declared constraint: one rule, over one frame.

Bases: _StrictSpec

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. Which coordinates there are is data, and arrives when the data is attached; a one_of only names the labels a coordinate may have. The maps its members carry — a generator's bus, a snapshot's period — are top-level relations: (RelationSpec), keyed by their own name.

Bases: _StrictSpec

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 entry'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: _StrictSpec

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: gives the dimensions over which the quantity is indexed. A plain entry may leave it out, and its expression then decides them. A declared dims: gives exactly the dimensions over which the expression is indexed: an expression indexed over a dimension dims: does not give is refused, and so is a dims: that gives one over which the expression is not indexed. 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: _GivenEntrySpec

A named condition this file reads and another file defines.

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

Bases: _GivenEntrySpec

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: _GivenEntrySpec

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: _GivenEntrySpec

Data this file reads and another file declares.

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

Bases: _StrictSpec

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

Bases: _GivenEntrySpec

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: _StrictSpec

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: _StrictSpec

A declared objective function.

Bases: _StrictSpec

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

Bases: _StrictSpec

One link of a piecewise entry: an expression tied to the curve through a values parameter.

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.

A link that names by: relation[column] reads the curve's weights through the relation, as at reads an array, and is written as a mapping. Its row is the entry's dims: with the dims the lookup reads replaced by the key columns it arrives at, so one link emits a row per fine coordinate and each reads the curve of the coarse coordinate it maps to.

Bases: _StrictSpec

Expressions tied to one breakpoint-indexed piecewise curve per coordinate of dims:.

Mirrors linopy.Spec.add_piecewise_formulation. links: maps a name to [expression, values_parameter] or [expression, values_parameter, sign]: expression is any affine expression string over dims:, values_parameter names a parameter carrying along and no dim the link's row lacks, and sign bounds the link by the curve instead of pinning it. The name is the link's row in the expansion, <entry>_<link>.

dims: alone decides how many curves the entry builds: one set of weights per coordinate of it. where: says which of those coordinates have a curve, and how far each runs along along where it reads that dim too; activity: whether a curve that exists is switched on. A link that walks a relation builds a row per fine coordinate, each reading the one curve its coarse coordinate has, so how many expressions a curve ties is data.

Bases: _StrictSpec

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 entry fixes no direction. 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: _StrictSpec

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: _StrictSpec

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. Nothing changes one after it loads either: a section is a read-only mapping, a list is a tuple, and a field cannot be set, so to_yaml writes the file program was lowered from. override is the edit, and loads what it makes as a new spec.

The API is the thirteen 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.

1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330

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 entry's
    own, and drops the entry. 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 sections 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

1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239

@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

1268
1269
1270

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

1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294

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

    The fields the file wrote, and no others: a default it writes out is
    written back, and one it leaves out is not. ``version`` is always
    written. Sections and the keys of an entry come in the schema's order.

    Args:
        canonical: Write the normal form instead: entries sorted by
            name, no field at its default, 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.
    """
    if canonical:
        from mathspec._canonical import canonical_yaml

        return canonical_yaml(self)
    from mathspec._yaml import dump_yaml

    return dump_yaml(self.to_dict())

Bases: _StrictSpec

A declared decision variable.