feat(language): a fragment reads a parameter or a named expression another file declares, under given:

[FBumann]

Prompt: "I think we can be sure that we need to add parameters and expressions to given... Lets just do it as a stacked PR onto 690. Then retry. Iterate until the split is clean, reasonable and its easy to add new features via a fragment."

Note

The following content was generated by AI.

given: takes parameters: and expressions: beside variables: and constraints:. merge folds both into their introducer. A given expression's dims bound what it reads, and the composed model decides the rest.

Stacked on #690. Measured need in #722: without these two kinds, 491 of 652 declarations of examples/pypsa.yaml must share one file. The whole design is presented in #723.

What this changes

• given: parameters: takes dims, dtype and description, what a parameter declaration takes. A given parameter reads wherever a parameter does: an expression, a where, a bound. program.given.parameters carries it with its dtype.
• given: expressions: takes dims and description. The file reads the name as it reads a given variable: a quantity over the frame, of degree one, lowered to a Variable node. program.given.expressions carries the frame. A where does not read it.
• merge folds both kinds. A given parameter says the same as the declaration or less, as a given variable does. A given expression's dims are an upper bound: a definition whose body carries a dimension the reader does not state is refused. A body over fewer dimensions is folded, and the composed model's load decides: it refuses a row that would repeat across the missing dimension, and accepts one where another term carries it. A name read as one kind that a sibling introduces as another is refused, both fragments named.
• override lays both kinds over like the other two: GIVEN_KINDS drives both verbs.
• Typesetting: the legend lists both under Given, "data another file declares" and "an expression another file defines". typeset_declaration refuses both names as it refuses the other two kinds.
• advice notes every given name, the two new kinds included. The note now says "declared elsewhere" rather than "built elsewhere", which a parameter is not.
• Docs: the given section of the language reference, the composition table of compose.md, reading.md, errors.md, limits.md.

Why

A fragment that reads a sibling's parameter or expression had to declare it, and merge then refused the second declaration. A shared weight such as scenario_weight or a total such as scenario_opex tied every component file of the PyPSA model into one.

Guards, gates, design choices, what was not done

Triage (limits.md). This extends a declaration section, given:, rather than adding a primitive. Loading decides everything about it, and the typesetter prints it in all three formats.

Guards, each deleted in turn, the suite run, the tree restored:

Guard	Failures
a body over a dimension the reader does not state	1: test_a_definition_over_a_dimension_the_reader_does_not_state_is_refused
kind check of a given declaration	1: test_a_given_expression_a_sibling_introduces_as_a_variable_is_refused
given parameter in the flat namespace	1: test_a_parameter_both_declared_and_given_in_one_file_is_refused
given expression in the flat namespace	1: test_an_expression_both_defined_and_given_in_one_file_is_refused
given parameter frame declared	1: test_a_given_parameter_is_refused_where_it_oversteps[a-frame-over-an-undeclared-dimension]
bound may name a given parameter	1: test_a_given_parameter_is_read_in_a_bound_as_any_parameter_is

test_given.py goes from 40 cases to 67. The first 26 (25 new, 1 rewritten) were written first and all failed on the tree before the first commit. The two frame cases of the second commit (test_a_definition_over_fewer_dimensions_merges_where_the_row_carries_the_rest, test_the_composed_load_refuses_a_row_a_narrower_definition_repeats) failed under the earlier set-equality rule. test_composition.py gains 2 cases for override.

Gates. Pixi cannot be installed in this container. In a Python 3.12 uv virtualenv with the pins of pixi.toml, on d41d3ee:

pytest tests -n 8                          1787 passed, 7 skipped
ruff check . / ruff format --check .       clean
pyrefly check                              0 errors (9 suppressed)
typos .                                    clean
prettier --check (the changed docs pages)  clean

Not run: compile-tex (the tectonic bundle download is blocked), mkdocs build --strict (the proxy refuses the docs.python.org inventory; no other warning on the first commit), zizmor, taplo.

Choices.

• A given expression lowers to a Variable node, not to a new node kind. The expression node set is closed, and a new kind would need a branch in every walk. The fragment knows only the frame, so the degree-one reading is what it can check; the composed model checks the body where the fragment reads it (test_the_composed_model_holds_a_definition_to_the_rules_of_where_it_is_read).
• The frame is an upper bound rather than an equality. A reader's row may carry a dimension through another term, as injection == demand carries snapshot through a demand that varies by snapshot. Equality would refuse that sound model; the composed load already refuses a row that would repeat.
• A given parameter or variable is still compared as an ordered list (open since feat(language): merge and override load every model they compose and return one #690). Only the expression rule changed here.
• A given expression prints italic, as a column does. The composed model prints the definition upright where its body reads no variable. A symbol table overrides either.
• A piecewise breakpoint or mask still names a declared parameter only. Nothing reads one under given: yet.

Not done.

• No CHANGELOG.md line: this base predates the ## Upcoming version rule. The line lands when the stack merges main.
• The stack does not carry main's rename to mathspec. chore: examples/pypsa/ cuts pypsa.yaml into 24 topic fragments that merge back to its rows #723 merges both and resolves it.

Follow-up in this stack. #729 (stacked on this PR) lets a reader mark a given expression as a sum other files add terms to.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sr4SCw5A7GUF5ARhdCaKR1

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34761005 | 📁 Comparing d41d3ee against latest (188262a)

  🔍 Preview build  

50 files changed · + 8 added · ± 39 modified · - 3 deleted

+ Added

• CHANGELOG/index.html
• first-model/index.html
• examples/library/index.html
• howto/compose/index.html
• examples/library/composed/index.html
• examples/library/generator/index.html
• examples/library/load/index.html
• examples/library/surface/index.html

± Modified

• index.html
• contributing/index.html
• examples/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• about/what-counts-as-public-api/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• and 29 more...

- Deleted

• changelog/index.html
• first-spec/index.html
• about/versions/index.html

[FBumann]

Prompt: "I think we should close all superseeded ones that are from me (FBumann), and name what superseeded them "Superseeded by #xyz""

Note

The following content was generated by AI.

Superseded by #732.

---

Generated by Claude Code