Skip to content

Reading a loaded model#

Every other page here says what a file may declare. This one says what a program gets when it loads one: the contract between the language and anything that reads the AST — a solver backend, a renderer, a second front end.

None of it is needed to write a model: these are the names a consumer reads a model through, and they are the whole of the seam:

to_spec  →  Spec  →  to_program  →  Program

Two states, and the difference between them#

A Spec is what the file says. A Program is what it means — macros expanded, curves become the declarations they stand for, names typed, operators resolved to nodes, and every dim and degree rule already checked. A consumer that builds reads the second; one that asks what the file wrote reads the first.

A file may declare a construct whose variables and constraints do not exist yet. piecewise: is the one that does — a curve expands into weights, a convexity row and one link row per tuple, and those declarations are the model as much as the ones that were typed.

curve.yaml
dimensions:
  generator: { dtype: str }
  bp: { dtype: int }
parameters:
  bp_x: { dims: [generator, bp] }
  bp_y: { dims: [generator, bp] }
variables:
  p:
    foreach: [generator]
    bounds: { lower: 0 }
  cost:
    foreach: [generator]
    bounds: { lower: 0 }
piecewise:
  curve:
    over: bp
    links:
      - [p, bp_x]
      - [cost, bp_y, ">="]
    method: convex
constraints:
  target:
    foreach: []
    expression: sum(p, over=generator) >= 100
objective:
  sense: minimize
  expression: sum(cost)

from math_spec import to_spec, to_program

spec = to_spec('curve.yaml')
sorted(spec.constraints)  # ['target']

program = to_program(spec)
sorted(program.constraints)  # ['curve_convexity', 'curve_link0', 'curve_link1', 'target']
sorted(program.variables)  # ['cost', 'curve_lam', 'p']

to_program takes whatever you have — a path, the YAML, a mapping, a Spec, or a Program already — and is idempotent, so a consumer that does not know which it holds can call it and be sure.

Which one to take#

you are take because
building rows — a solver backend, a second front end Program every declaration is there, resolved
reading the file — macros:, description:, a link as it was written Spec a program keeps a curve's facts, not its text

Take a Program to build. A consumer that reads constraints: off a Spec still carrying a curve builds a model missing declarations — and a model missing declarations is a model, so it solves, and the answer is wrong with nothing to see. Program is a different type from Spec, so that mistake is one the signature refuses rather than one the numbers report.

A program cannot answer what the file wrote. It has no macros:, no description:, and no link expression — those are the Spec's, and rendering has to be handed what to_spec returned. The projection runs one way on purpose. What it keeps of a piecewise: block is program.piecewise: which parameters carry the curve, and what the block assumes of the numbers as a checks tuple — each check carrying the names it is about, so the consumer holding the numbers runs it, with check_message for the sentence to raise. What the expansion emitted is answered where it is asked instead: a ParameterDeclaration.derivation says how that parameter is filled, and None means the caller binds it.

Nothing here is built by hand. The program's nodes are exported to be dispatched on with isinstance and read, which is why what ships beside them is the walk (children()) and not builders. A mask is Mask: the language's own resolved where as its .root — the node an engine still dispatches on with isinstance — and every question derived from it, the way a dimension carries .maps. .conjuncts flattens the AND spine and stops at an OR or a NOT; .names_read gives the declarations the mask names; .atoms its leaves, connectives removed; and .dims the dimensions it is read at — read off the leaves, which resolution stamped with their declarations' dims the way a lookup leaf carries the dimension it maps out of. So a predicate a consumer builds from resolved pieces answers exactly as a declaration's own does: wrap it in Mask, or build it there with ~, & and |. Construction folds — a double negation cancels, a literal flips or is absorbed rather than buried — so a boolean literal stands at a mask's root or nowhere, derived or carried alike, and a tree with unresolved leaves is refused at the door. A consumer asks the mask rather than re-deriving any of these from .root, so two cannot come to disagree about what a conjunct, a name or a comparison is. A Region's when arrives in the same carrier, and the node classes a .root is built of live in math_spec.program beside every other node a consumer dispatches on.

Asking what a program uses#

program.footprint is which of the language's constructs one program actually reaches for — a subset, never the whole. It is walked once and held, which is safe because a program cannot change after it is built.

footprint = program.footprint

sorted(footprint.quadratic)  # []
sorted(footprint.variable_types)  # ['continuous']
sorted(footprint.sos_types)  # []
sorted(kind.__name__ for kind in footprint.shapes)  # ['Constant', 'Multiply', 'Parameter', 'Sum', 'Variable']

Every field is a set, so if footprint.sos_types asks whether sets appear at all and 2 in footprint.sos_types asks about one kind. An empty field says this program does not use that construct — never that the construct does not exist. A construct admitted later widens a set rather than needing a field no consumer yet reads.

It answers what the program uses, never what you can do about it. What a sink can ingest is a separate axis — capability is not the ceiling — where a capability is neither a flat set nor one verdict per construct: SOS is solver-bounded, and quadratic is bounded twice over on a single sink, by convexity and again by what it stands beside. So there is deliberately no verdict here to read instead of giving one, and convexity is absent because it depends on coefficient data rather than on anything a program states.

The footprint stops at the kind. A sink that takes a window but not a wrapped one reads Window in footprint.shapes and then walks: wrap, partition and a named width are refinements without end, and each is one line once the set has said where to look.