Skip to content

File shape

A model file is a YAML mapping with ten declaration keys, plus version and description:

Key
dimensions the axes (dimensions)
lookups named maps out of a dimension (lookups)
parameters the data the model expects (declarations)
variables what the solver decides
constraints the rules those decisions obey
objective what is minimised or maximised
expressions named quantities, reusable and readable back after a solve (expressions)
macros parameterised templates (macros)
piecewise piecewise-linear curves (piecewise)
sos special-ordered sets (sos)

Any subset is accepted, objective included: a file with none is a feasibility problem, and the answer is whether the constraints can be met at all. It solves, its variables read back, and result.objective is the zero the solver was handed.

description

What the file as a whole is: the same plain prose a declaration's description: takes, and the first thing a typeset document prints. Optional, never parsed, default null.

description: Least-cost dispatch of a generator fleet against an hourly load.
dimensions: ...

A # comment above the file says this too, and the parser throws it away. A description: is the version a reader who never opens the YAML still gets.

version

Which language surface the file is written against. Optional; absent means 0:

version: 0
dimensions: ...

0 means unstable, and that is the promise being made. The surface may change in any release, and saying so in the file is more honest than silence. 0 does not become 1 without a changelog entry naming what moved.

A version this release does not know is a load error, and nothing else — the field gates no behaviour and never selects an alternative surface:

model declares version 1, and lpspec 0.0.1a75 understands [0].
Upgrade lpspec, or write the version this file actually targets.

It is a language version, not a package one: it moves when the accepted YAML surface moves, which most releases do not.

The schema is closed

An unrecognised key — top level or inside any declaration — is a load error naming the near miss:

unknown key 'boundz' … Did you mean 'bounds'?

Ignoring it would let a typo change the model: a dropped bounds: leaves a variable unbounded, a dropped where: leaves it unmasked.

How the YAML is read

  • Booleans are YAML 1.2 (true / false only); everything else is read as 1.1. Under 1.1 on / off / yes / no / y / n become booleans and silently destroy dimension labels that are country codes, so values: [no, se, on] is three labels here.
  • Implicit timestamps (2024-01-01) and sexagesimal integers (12:30 → 750) survive, and the dtype of a dimension catches them wherever they were not meant (dimensions).
  • A duplicate key is a load error naming both lines.
  • <<: merge keys are honoured, and a key the mapping declares itself overrides the merged value.
  • The document must be a mapping.