feat(language): a parameter and a relation each say whether their data must be complete, so a row lost in preparation is not read as a mask

[FBumann]

Prompt: Rebase all other PRs [...] 245 [...] Port the change

Note

The following content was generated by AI.

Replaces #245, whose branch shares no history with main. Closes #296. parameters: and relations: take coverage: total | masked, default total. The expansion now declares a curve's tables masked where the curve has points:.

What was ported, what is new, gates

Ported from #245

• Coverage = Literal['total', 'masked'], now on math_spec.program with the other vocabularies. ParameterDeclaration.coverage is Coverage | None, and RelationDeclaration.coverage is Coverage.
• ParameterBlock and RelationBlock share _CoveredBlock: the field is Coverage | None = None, and coverage_or_default gives the reading. The schema is regenerated: coverage is anyOf [enum, null] on both.
• The refusal of coverage: on a parameter a piecewise: block consumes (either spelling) is one more rule in validation.reference_errors. PiecewiseBlock.consumes is the one list the refusal and lowering read.
• Lowering reports None for a parameter a block consumes, and the file's reading for every other parameter and relation.
• The pypsa examples mark the parameters feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245 marked. pypsa_losses.yaml's Line_cycle_weight, which has the same description ("a line in no cycle has no row"), is marked too.
• Docs: absence.md and declarations.md as in feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245. The relation rows feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245 wrote on dimensions.md are now on relations.md, where main documents relations; its "A partial map is the rows it has" becomes the masked reading, beside the total rule. The reading page tells a binder what each coverage asks of it.

Changed from #245

• Relations use main's spelling. A relation is key:/values:, and total is a row for every key coordinate.
• No emitted parameter. feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245 exempted the <block>_points mask it emitted. main emits no parameter, so the exempt set is exactly what the block consumes.
• The expansion carries the curve's reading. At feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245's time every program held the expanded rows and knew which block owned which table. On main, a consumer building rows reads the program of spec.expand(...), where no block is left. Left alone, that program would report total for a curve's tables, and a binder would refuse the ragged curve the block admits. That is the failure feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245's third review fixed, reached through the expansion instead. So expand_piecewise declares coverage: masked on a parameter consumed only by curves with points:. Their weights carry where: <points>, the lp rows sit on masks built from it, and the <block>_complete assumption states where a row is required. A parameter read by a curve over every breakpoint stays total. The two tests/expand/*-points/after.yaml files carry the new line. test_an_expansion_declares_exactly_the_parameters_the_file_declared now compares names, dims and dtype, which is what "the same data binds both" needs.

Guards, each deleted in turn on this head

guard deleted	suite
the curve-parameter refusal	2 failed
lowering's None for a curve parameter	1 failed
lowering dropping a parameter's coverage	3 failed
the namespace dropping a relation's coverage	1 failed
the expansion writing no coverage	3 failed
the unwritten default flipping to masked	11 failed

Every new test was run on unported main first and failed there.

Gates

The gates ran from a uv venv on Python 3.12, with the docs toolchain from pixi.toml's docs feature.

gate	result
pytest -n 4	1654 passed, 5 skipped
ruff check, ruff format --check	clean
pyrefly check	0 errors
tools.schema --check, golden regeneration, every generated page	current
mkdocs build --strict	clean. The sandbox blocks the fetch of docs.python.org/3/objects.inv, so the build ran from a scratch copy of mkdocs.yml without that one inventory line.
prettier --check docs	clean

Both new YAML fences load, and read back masked where they write it.

Docs sentences, after (before): absence.md n 34, avg 13.5, median 12, over 25 words 2 (32, 13.2, 12, 2); declarations.md n 43, avg 13.9, median 12, over 25 words 5 (30, 10.7, 10, 1); relations.md n 42, avg 16.4, median 15, over 25 words 7 (39, 15.9, 15, 5); piecewise.md n 72, avg 17.5, median 16, over 25 words 12 (71, 17.5, 15, 12); reading.md n 84, avg 16.3, median 15, over 25 words 13 (80, 16.2, 15, 13). Four of declarations.md's five are the script joining a bold lead-in to the sentence after it.

Not run: compile-tex. No typeset output changed, because coverage is not printed, as #245 decided.

Not done

• feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245 is left open for you to close. Its discussion, including the lpspec to-do list, stays there.
• feat(language): a piecewise block states its dims and names its links, and its where reaches links that walk a relation #630 renames points: to where:. Whichever of the two lands second moves the refusal's wording, consumes and the expander's points test to the new key.
• feat(language): a parameter and a lookup each say whether their data must be complete, so a row lost in preparation is not read as a mask #245's labels and milestone ("area: relations", "area: data contract", "Data contract declarations") are not set here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GpnFcQDuvt2bExGngb6MYk

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34754223 | 📁 Comparing f4d7316 against latest (af55a75)

  🔍 Preview build  

57 files changed · + 4 added · ± 29 modified · - 24 deleted

+ Added

• first-model/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/program/index.html

± Modified

• index.html
• CHANGELOG/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/pypsa/index.html
• howto/check/index.html
• howto/curve-by-hand/index.html
• and 19 more...

- Deleted

• about/file-and-program/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/boundedness/index.html
• reference/math_spec/degree/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/exclusivity/index.html
• reference/math_spec/expansion/index.html
• reference/math_spec/lowering/index.html
• reference/math_spec/model/index.html
• and 14 more...

[FBumann]

Prompt: "Did you close all the other superseeded prs, if there were any realted to absence, coverage, etc?"

Note

The following content was generated by AI.

Superseded by #810. coverage: total | masked became missing: error | neutral there, with absent and a value beside them, on parameters and relations. Closing.

What #810 took from this PR

• total is the default, now spelled error, for parameters and for relations with values:. A bare relation takes no missing:.
• masked is neutral on a parameter and absent on a relation, because a partial map's reading on main is absence.
• A parameter a piecewise: block reads takes no missing:, the program reports None for it, and the expansion declares it neutral where the curve has points:. The tests are ported.
• The PyPSA examples are marked by their descriptions, starting from this PR's list.

---

Generated by Claude Code