[FabianHofmann]

Note

The following content was generated by AI.

relations: states which rows exist; a new maps: section gives each row of a subject one label. Implements the design in #1000 (closes the split part; its open questions stay open).

# before
relations:
  gen_bus: { key: generator, values: bus }
  line_ends: { key: line, values: { bus0: bus, bus1: bus }, missing: absent }
  connection: { key: [generator, bus], missing: absent }
  zone_of: { key: [generator, period], values: zone }
constraints:
  balance: { expression: "sum(p, over=generator, by=gen_bus[bus]) == load" }
variables:
  flow: { dims: [line], where: line_ends }
  dispatch: { dims: [generator, bus], where: connection }

# after
relations:
  connection: { dims: [generator, bus], missing: absent }
  zone_of: { dims: [generator, period] }
maps:
  generator: { bus: bus }
  line:
    bus0: bus
    bus1: { refers_to: bus, missing: absent }   # missing is per map now
  zone_of: { zone: zone }
constraints:
  balance: { expression: "sum(p, over=generator, by=generator[bus]) == load" }
variables:
  flow: { dims: [line], where: "line[bus1]" }   # true where the map gives a label
  dispatch: { dims: [generator, bus], in: [connection] }   # `where: connection` is refused

• Typeset legend: connection ⊆ B × G, bus: G → B; a map test prints bus1(l) is defined.
• Breaks every file with key:/values:; no alias, per AGENTS.md (pre-1.0).

Method, gate output, alternatives

• Relations, maps and in:: the agreed design, the decisions made and the questions still open #1000, rule by rule:

  • relation lists the combinations of its dims:; not a dimension: in dims:, over=, along= refused with its dimensions as the rewrite ✓
  • map gives each row of a dimension or a relation one label; refers_to: must be a dimension, so a number stays a parameter ✓
  • missing: per relation and per map ✓
  • in:, then where:, then missing:: from feat(language): relation rows may index an entry #980, unchanged ✓
  • merge joins the maps of a subject; each fragment declares the maps it reads ✓
  • the example in Relations, maps and in:: the agreed design, the decisions made and the questions still open #1000 loads as written ✓

• departure: Relations, maps and in:: the agreed design, the decisions made and the questions still open #1000 says "a label of another dimension"; a map may refer to its own subject's dimension (snapshot[rep], used by the examples).

• from FBumann on Relations, maps and in:: the agreed design, the decisions made and the questions still open #1000:

  • a relation's bare name in the where: of a parameter or a variable is refused, rewrite in: [relation]; under OR/NOT, a bool parameter. The index-set advice is gone, its cases moved to test_validation.py.
  • refers: → refers_to: (FBumann offered references: or refers_to:; refers_to: keeps coroa's word).

• still allowed: a bare relation in a constraint's where:, a case when:, an assumption, since in: is not on those (Relations, maps and in:: the agreed design, the decisions made and the questions still open #1000 question 2, untouched).

• relations: takes dims: (≥ 2 columns), missing:, description. One-column relation refused, pointing at maps:.

• maps: keyed by subject (dimension or relation); each map has refers_to:, missing: (refused/absent, per map), description. Short form bus: bus. Composes as a shared section in merge/override.

• Read as subject[map] in every operator, condition and missing: by:. subject[map] alone in a condition is a presence test (RelationDefined.column).

• Program: one Relation table per subject, keyed by its name; Relation.partial lists the maps with missing: absent; Reach.name names subject[map].

• Overlap prover (_exclusivity): a map has a null cell; a comparison of two maps is false where either has no label (was unsound: two not complements proved apart); a dimension subject always has a row; witness says "has no label".

• Bugs found while porting, each with a test that fails without the fix:

  • a walked piecewise link wrote the bare subject into its where: and did not load (51 tests in test_piecewise.py);
  • a map of an int dimension read the subject's dtype, and a label hit an internal assertion (test_a_map_of_a_numbered_dimension_compares_a_label);
  • the pair comparison above (4 tests in test_exclusivity.py).

• All examples, fixtures, goldens, schema and generated pages regenerated; docs/reference/language/relations.md rewritten as "Relations and maps"; every other page, the operator labels and 14 figures swept to the new words.

• gate: ruff check, ruff format --check, pyrefly check, pytest (4285 passed, 8 skipped), typos, prettier, zensical build --strict. Not run: compile-tex (no tectonic here); pixi unavailable, ran in a uv venv.

• Stack: on feat(language): a missing row reads per relation label #984 → feat(language): assumptions may require a row to exist #982 → feat(language): relation rows may index an entry #980, all three updated with main (docs(pypsa): the file states the rows PyPSA builds #998); docs(pypsa): the file states the rows PyPSA builds #998's new PyPSA rows converted to snapshot[period].

• Breaks open PRs that use key:/values:: docs(calliope): all of calliope's math is a set of fragments that merge, with its modes laid over them as patches #770, docs(pypsa): the linearized unit commitment names the units it tightens as a mask #887, docs(pypsa): the pypsa spec names its fix, ext, commitment, maintenance and ramp row sets as masks #888, docs(pypsa): the PyPSA spec is written as fragments, with each committable class, the relaxed commitment and the risk preference as layers that a model takes or leaves out #902, feat(composition): rename gives a spec other names, so one fragment can serve several classes in one merge #905, docs(pypsa): the file states four more piecewise curves #989.

https://claude.ai/code/session_01F4nx8GcpB6VRUi38KTVQiw

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35835868 | 📁 Comparing dc808f4 against latest (5029b4e)

  🔍 Preview build  

65 files changed · ± 65 modified

± Modified

• contributing/index.html
• examples/index.html
• howto/index.html
• reference/index.html
• about/limits/index.html
• about/overview/index.html
• about/relations-as-linear-maps/index.html
• about/sql-and-dataframes/index.html
• about/versions/index.html
• about/what-counts-as-language/index.html
• and 55 more...