Skip to content

The language#

You write a spec as one YAML file. The file declares the dimensions the spec runs over, the data it expects, the decisions the solver makes, and the rules those decisions obey.

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

dimensions:
  snapshot: { dtype: int }
  generator: { dtype: str }

parameters:
  load: { dims: [snapshot] }
  cost: { dims: [generator] }
  capacity: { dims: [generator] }

variables:
  dispatch:
    dims: [snapshot, generator]
    where: "capacity > 0"
    bounds: { lower: 0, upper: capacity }

constraints:
  power_balance:
    dims: [snapshot]
    expression: sum(dispatch, over=generator) == load

objective:
  sense: minimize
  expression: sum(dispatch * cost) # an objective is one number, so the sum is written

That file is a complete spec. The pages below give the exact rules, and the glossary defines each word they use in a fixed sense.

The eleven rules#

to_spec refuses a file that breaks one of these rules, with a message that names the fix.

# Rule
1 A file has thirteen section keys, plus version and description. An unknown key is refused, with the nearest valid key named. File shape
2 to_spec checks everything it can check without data when the file loads. Errors
3 Every name is declared once. A parameter and a dimension both called snapshot is refused. Names
4 The kind of a name decides where it may stand. A dimension follows over= or along=, and is never multiplied. Names
5 a + b carries the dimensions of a and of b together. A constraint's expression carries exactly its dims, and the objective carries none. How dimensions combine
6 A variable's where: deletes the variable at the masked coordinates. A constraint's where: deletes the row. Absence
7 A deleted variable takes its row with it. Inside a sum it is one term fewer, and the row stays. Absence
8 A row missing from a table is refused, unless the missing: of the entry says it is absent, neutral, or a value. Absence
9 Two variables may be multiplied in the objective and in a constraint, and nowhere else. x / y and a ** b need their divisor, base and exponent free of variables. Expressions
10 The operators are sum, sum_back, at and shift, plus dual in a reported expression. A file cannot add one. Operators
11 A construct that steps or counts along a dimension needs the dimension declared ordered: true. These are shift, sum_back, position, piecewise and an sos of type: 2. Order