math_spec.model

The YAML surface's types — every block a file may contain, rooted at :class:Spec.

Nothing here has seen data.

CURVATURES = frozenset(get_args(Curvature)) module-attribute

Curvature = Literal['convex', 'concave', 'either'] module-attribute

DIMENSION_DTYPES = frozenset(get_args(DimensionDtype)) module-attribute

DeclaredDtype = ParameterDtype | DimensionDtype module-attribute

DimensionDtype = Literal['float', 'int', 'str', 'datetime'] module-attribute

Expression = Annotated[str, BeforeValidator(_number_is_an_expression, json_schema_input_type=str | float)] module-attribute

LinkSign = ComparisonOperator module-attribute

NUMERIC_DTYPES = frozenset({'float', 'int'}) module-attribute

ObjectiveSense = Literal['minimize', 'maximize'] module-attribute

PARAMETER_DTYPES = frozenset(get_args(ParameterDtype)) module-attribute

PIECEWISE_METHODS = {'adjacency': 'a binary per segment, and a row making the two nonzero weights neighbours', 'sos2': 'the same weights, restricted by a set the solver branches on (the sos rules)', 'convex': 'nothing — the weights range over the hull, which is a pure LP', 'lp': 'no weights at all — one row per segment line, plus the two rows holding the domain'} module-attribute

ParameterDtype = Literal['float', 'int', 'bool', 'str'] module-attribute

PiecewiseMethod = Literal['adjacency', 'sos2', 'convex', 'lp'] module-attribute

SOS_TYPES = frozenset(get_args(SosType)) module-attribute

SUPPORTED_VERSIONS = (0,) module-attribute

SosType = Literal[1, 2] module-attribute

VARIABLE_ABSENCE = frozenset(get_args(VariableAbsence)) module-attribute

VARIABLE_DOMAINS = frozenset(get_args(VariableDomain)) module-attribute

VariableAbsence = Literal['undefined', 'zero'] module-attribute

VariableDomain = Literal['continuous', 'integer', 'binary'] module-attribute

BoundsBlock

Bases: _StrictBlock

Variable bounds — each side is a number or parameter name.

An omitted bound leaves the variable unbounded on that side, not implicitly non-negative.

lower = float('-inf') class-attribute instance-attribute

upper = float('inf') class-attribute instance-attribute

ConstraintBlock

Bases: _StrictBlock

A declared constraint: one rule, over one frame.

description = None class-attribute instance-attribute

dims instance-attribute

expression instance-attribute

where = None class-attribute instance-attribute

DimensionBlock

Bases: _StrictBlock

A declared dimension, and the dtype its coordinates must be.

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 at bind time. The maps its members carry — a generator's bus, a snapshot's period — are top-level relations: (:class:RelationBlock), keyed by their own name.

description = None class-attribute instance-attribute

dtype = 'str' class-attribute instance-attribute

ExpandedPiecewise

Bases: _StrictBlock

A piecewise: block after expansion: the block, and the parameters it emitted.

points is the mask the weights carry — the file's own parameter, or the one derived from a values parameter; starts and ends are the edge flags an lp block under a mask sits its domain rows on.

block instance-attribute

ends = None class-attribute instance-attribute

points = None class-attribute instance-attribute

starts = None class-attribute instance-attribute

ExpressionBlock

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

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.

cases = {} class-attribute instance-attribute

description = None class-attribute instance-attribute

dims = None class-attribute instance-attribute

expression = None class-attribute instance-attribute

otherwise = None class-attribute instance-attribute

ExpressionCase

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

expression instance-attribute

when instance-attribute

MacroBlock

Bases: _StrictBlock

A parameterised expression template, defined in the YAML itself.

Language, not code: formals (args positional, kwargs keyword) shadow model names inside the template, and every call site expands into core AST before either backend sees the expression.

args = [] class-attribute instance-attribute

description = None class-attribute instance-attribute

kwargs = [] class-attribute instance-attribute

template instance-attribute

ObjectiveBlock

Bases: _StrictBlock

A declared objective function.

description = None class-attribute instance-attribute

expression instance-attribute

sense = 'minimize' class-attribute instance-attribute

ParameterBlock

Bases: _StrictBlock

A declared parameter with dims and dtype.

description = None class-attribute instance-attribute

dims instance-attribute

dtype = 'float' class-attribute instance-attribute

PiecewiseBlock

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 along dim, and sign bounds the link by the curve instead of pinning it (at most one non-"==", and only with exactly two links).

The block builds one curve per coordinate of the frame. dims: declares it; where the file writes none it is inferred as the union of the link expressions' dims. Three keys say something different about those coordinates: where: which of them have a curve, points: how far each curve runs along along, and activity: whether a curve that exists is switched on.

A link naming by: sits on a refinement of the frame, so the number of expressions one curve ties is data. Such a block declares its dims:, because the frame can no longer be told from the links.

activity = None class-attribute instance-attribute

along instance-attribute

curve property

The two links as (x, y), the bounded one last.

Two-link blocks only.

description = None class-attribute instance-attribute

dims = None class-attribute instance-attribute

links instance-attribute

method = 'adjacency' class-attribute instance-attribute

points = None class-attribute instance-attribute

where = None class-attribute instance-attribute

PiecewiseLink

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 :meth:Spec.to_yaml reproduces the file.

A link that names into: sits on a refinement of the curve's frame rather than on the frame itself, and is written as a mapping. Its row is (frame - over) | into, the frame law a relation walk already follows, so one link emits a row per fine coordinate and the weights it reads stay on the curve's own frame. That is what lets one curve tie as many expressions as the data says.

Two forms, one law. into: alone names a dimension the row gains and the weights broadcast across, so every coordinate of it is a tie to the one operating point. by:, over: and into: together are the :func:at walk, which loses a frame dimension and gains what the relation maps it to.

by = None class-attribute instance-attribute

expression instance-attribute

into = None class-attribute instance-attribute

over = None class-attribute instance-attribute

refined property

Whether the link's row is a refinement of the curve's frame rather than the frame itself.

sign = '==' class-attribute instance-attribute

values instance-attribute

walks property

Whether the refinement is reached through a relation, rather than a dimension the row simply gains.

RelationBlock

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 at bind: 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]}

An operator reads the table in the direction the call names (over=, into=), joining on the other key columns; the declaration fixes no direction. The map itself is data, and arrives at bind time under the relation's name, one column per role.

description = None class-attribute instance-attribute

dims property

key instance-attribute

key_roles property

The key roles, however key: was written.

pairs property

(role, dimension) per column, the key's columns first.

The program calls the same thing :attr:~math_spec.program.RelationDeclaration.columns; here the table has no field of its own, being what the two sides make.

roles property

value_roles property

The roles the key determines; empty for a bare relation.

values = None class-attribute instance-attribute

SosBlock

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, and big_m is the optional cap a consumer that reformulates the set puts on its linking rows.

type: 1 admits at most one nonzero member, type: 2 at most two, and those two consecutive. Unlike every other block this one declares no math to read off A: it is a set, carried to a consumer that has the concept and reformulated for one that does not.

along instance-attribute

big_m = None class-attribute instance-attribute

description = None class-attribute instance-attribute

type instance-attribute

variable instance-attribute

Spec

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, :meth:model_validate, the constructor — runs every load-time check, expansion and expression pass included, and raises :class:~math_spec.errors.LanguageError on a model the language refuses. Holding one is the proof, so nothing downstream checks it again.

The API is the ten declaration sections plus version and description, and two ways back out: :meth:to_dict for the model as data, :meth:to_yaml for the file a reviewer reads. Everything else on this class is pydantic's, not a contract this package keeps.

constraints = {} class-attribute instance-attribute

description = None class-attribute instance-attribute

dimensions = {} class-attribute instance-attribute

expressions = {} class-attribute instance-attribute

macros = {} class-attribute instance-attribute

objective = None class-attribute instance-attribute

parameters = {} class-attribute instance-attribute

piecewise = {} class-attribute instance-attribute

relations = {} class-attribute instance-attribute

sos = {} class-attribute instance-attribute

variables = {} class-attribute instance-attribute

version = 0 class-attribute instance-attribute

model_validate(obj, *, strict=None, extra=None, from_attributes=None, context=None, by_alias=None, by_name=None) classmethod

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.

Source code in src/math_spec/model.py

@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

relations_of(dimension)

The relations with a column over dimension, by name.

Source code in src/math_spec/model.py

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

to_dict()

The model as plain data. to_spec(m.to_dict()) reproduces it.

Source code in src/math_spec/model.py

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

to_yaml()

The file a reviewer reads — including for a model that never had one.

Source code in src/math_spec/model.py

def to_yaml(self) -> str:
    """The file a reviewer reads — including for a model that never had one."""
    import yaml

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

VariableBlock

Bases: _StrictBlock

A declared decision variable.

absence = 'undefined' class-attribute instance-attribute

bounds = BoundsBlock() class-attribute instance-attribute

description = None class-attribute instance-attribute

dims instance-attribute

domain = 'continuous' class-attribute instance-attribute

where = None class-attribute instance-attribute

undeclared_dimension(kind, name, dimension)

The one wording for a declaration naming a dimension the file does not declare.

Source code in src/math_spec/model.py

def undeclared_dimension(kind: str, name: str, dimension: str) -> str:
    """The one wording for a declaration naming a dimension the file does not declare."""
    return f"{kind} '{name}' references undeclared dimension '{dimension}'. Declare it under 'dimensions:'."