File shape#

A model file is a YAML mapping with eleven declaration keys, plus version and description. Any subset of the eleven is accepted.

Key
`dimensions`	the axes (dimensions)
`relations`	named relations between dimensions (relations)
`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 in the math and readable after a solve (named expressions)
`macros`	templates that take arguments (macros)
`piecewise`	piecewise-linear curves (piecewise)
`sos`	special-ordered sets (sos)
`assumptions`	what the model expects of its data (assumptions)

A file with no objective is a feasibility problem: it asks whether the constraints can all be met.

`description`#

Free text that says what the model is. It is optional, and a typeset document prints it first.

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

The language version the file is written against. It is optional, and it defaults to 0, the one version this release knows.

version: 0

A version this release does not know is a load error:

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

An unknown key is a load error that names the near miss, at the top level and inside every declaration:

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

The document is a mapping.
Only true and false are booleans, so no: {dtype: str} is a dimension called no.
A duplicate key is a load error, and the message names both lines.
<<: merge keys are honoured. A key the mapping declares itself overrides the merged value.