feat(language): a variable, a constraint and a cased expression declare their shape as dims, as a parameter does

[FBumann]

Prompt: do dims everywhere!

Prompt: "Please rebase #245 and #429" — rebased onto main at eac1930, where #422 landed.

Note

The following content was generated by AI.

Closes #425, the other way round from its title: foreach: is gone and every declaration's shape is dims:, the word a parameter, the program's three declarations and the rest of the code already used. No alias: the closed schema's own error names the valid keys.

What this changes

dims: on variables, constraints and cased expressions, in the model, the schema, every example, the golden model, the reference and the error messages that name the key. The program is untouched: ParameterDeclaration, VariableDeclaration and ConstraintDeclaration already said dims. Typeset output is unchanged, so the golden .out files did not move.

Why

One fact had two spellings on the file surface, and foreach was doing two jobs, naming a shape and reading as the ∀ the typesetter prints anyway (#425).

What the rebase onto eac1930 resolved

Four conflicts, all where #422 removed the label-space kind of lookup out from under a passage this branch had only renamed a key in:

• dimensions.md — the dtype: label-space section this branch edited is gone from main; the one surviving foreach in the rewritten "Dimension or lookup?" paragraph took the rename.
• tests/fixtures.py — SMALL_MODEL's tag is a parameter on main, not a label-space lookup; only the three variables entries take the rename.
• tests/test_lowering.py — test_a_label_space_keeps_its_dtype_and_has_no_target is deleted on main, so there is nothing to rename.
• tests/test_validation.py — one docstring line.

Gates, what was regenerated, and what was left

pixi is not installed in the session that rebased this, so the gates were run tool by tool in a plain venv at the pinned ruff==0.16.1 and pyrefly==1.2.0, on 8c809c6, clean worktree, base eac1930:

Gate	Result
ruff check / ruff format --check	pass, 127 files
pyrefly check	0 errors (9 suppressed)
reuse lint	compliant, 203 / 203
pytest -q	1155 passed, 6 skipped — the same count origin/main gives in that venv
mkdocs build --strict	pass
prettier --check on every changed page	pass

docs-build had not been run on the pre-rebase branch; it passes here with the one intersphinx inventory (https://docs.python.org/3/objects.inv) removed from mkdocs.yml for the run and restored after — the proxy answers it 403, and it is the only thing that failed the gate.

• Regenerated with their own tools and the diff read: schema/math-spec.schema.json (the key and its title), tests/typesetting/golden/*.out (no change), the gallery pages, notation.md, operators.md, docs/index.md and README.md (YAML key lines only). All were already byte-identical to what the branch carried.
• tests/test_dimensions.py pins the reworded constraint message, which now says "not in its dims:" and "add it to dims:".
• Left: over: on a lookup and a set names one dimension, not a shape, and stays. CHANGELOG.md keeps its history. The docs' noun for the shape is still "the frame" where it was.

Not run: compile-tex — tectonic and typst are absent here, and the LaTeX output is byte-identical. The 6 skips are those two. pixi run ci itself was not run.

Noticed, not changed: tests/test_piecewise.py still names a test test_the_emitted_foreach_follows_declaration_order, the one foreach left in the tree outside CHANGELOG.md. It is this branch's to rename, not the rebase's.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34491906 | 📁 Comparing bc77542 against latest (140ec94)

  🔍 Preview build  

44 files changed · + 6 added · ± 35 modified · - 3 deleted

+ Added

• about/limits/index.html
• about/what-counts-as-public-api/index.html
• howto/check/index.html
• howto/installation/index.html
• howto/print/index.html
• howto/regimes/index.html

± Modified

• index.html
• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• about/what-counts-as-language/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• and 25 more...

- Deleted

• installation/index.html
• about/ceiling/index.html
• about/what-counts-as-a-verb/index.html

[FBumann]

@brynpickering @FabianHofmann Opinions?

[FabianHofmann]

I like that very much, I think dims is the natural way to go, as 1) they are dimensions defining the shape of the objects 2) we define dimensions explicitly and we pick up that wording. So I would give that a go. But I am not master of design (@brynpickering)

Note I did not take a look at the code yet and would wait until the the merge conflicts are resolved

[brynpickering]

@FBumann @FabianHofmann the reason for foreach was to try and be more explicit for non-linopy/xarray users, since dims is an xarray concept more than anything else. pandas doesn't have the concept of dims, but rather index. Not sure what polars/narwhals uses.

foreach is very much trying to be defining a sentence that modellers can readily understand without needing the wider programming context in mind (define A foreach [B, C], where XYZ). But it maybe isn't the right name. Can we define something else that isn't foreach and isn't dims that is the most understandable for a non-programmer audience?

[FBumann]

@brynpickering Do you agree that we should remove the problem of having dims and foreach interchangeably?

So we merge this pr and have dims everywhere.

Then we can decide about a final name in a follow up?

About that final word:

We have the top level concept in the yaml right now

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

And INDEX in pandas isn't the same as dims in xarray. It's index.name = dim, index = dim.values pretty much

I think dimension/dims is the best word for it. That xarray happens to use it is not a problem I think.
But we could land on not abbreviating dims --> use dimensions everywhere...?

variables:
  p:
    dimensions: [snapshot, generator]

[brynpickering]

@FBumann yes I agree we should use the same term everywhere. I'm fine with using dimensions everywhere for now (via this PR) and then we might want to update it later.

One caveat I'd make is that there could be a benefit to having parameters define a different name to the others since it has a different meaning. It is the maximum dimensions over which it can be defined, while for all others, it is the exact dimensions over which it will be defined. Not sure how we clarify that except through documentation or through explicit naming (max_dimensions). Can be a different issue to resolve later.