refactor(program): a program names its nodes by the naming rule and its groups as the file does

[FBumann]

Prompt: review the Program architecture of lpspec. Are the naming of methods and classes clear? Are there better alternatives? Can we improve the architecture?

Follow-up: Yes, turn all of this into a PR

Note

The following content was generated by AI.

What this changes

Every public name in math_spec.program now follows the naming rule in docs/contributing.md, and a relation and a named expression are read from the program the way the file declares them. Nothing the language accepts, refuses or prints changes. Regenerated on top of #437 and #477.

This is a break, described here because the alpha stream refuses the marker. Every rename, one row per old name:

Where nodes

Was	Is
AndNode	And
OrNode	Or
NotNode	Not
BooleanLiteralNode	BooleanLiteral
ParameterDefinedNode	ParameterDefined
VariableDefinedNode	VariableDefined
ParameterComparisonNode	ParameterComparison
DimensionComparisonNode	DimensionComparison
DimensionPositionNode	DimensionPosition
RelationComparisonNode	RelationComparison
RelationPairComparisonNode	RelationPairComparison
RelationDefinedNode	RelationDefined

Unions

Was	Is
ExpressionNode	Expression
WhereNode	Predicate
TypedPredicateNode	TypedPredicate
ConnectiveWhereNode	Connective

Expression nodes and their fields

Was	Is
At	Pullback
Window	WindowSum
Translate.dimension	Translate.along, the keyword shift takes since #477
Window.dimension	WindowSum.along, the keyword sum_back takes since #477

Program and declarations

Was	Is
Program.named_expressions	Program.expressions, the file's own expressions: section
Program.expressions (the objective and both sides of every constraint)	Program.roots
Program.relations, a property built from the per-dimension nesting	Program.relations, a field: a Mapping[str, RelationDeclaration] keyed by name like every other group
DimensionDeclaration.relations	gone; DimensionDeclaration carries dtype alone
RelationDeclaration(name, columns, key), a NamedTuple	RelationDeclaration(columns, key), a frozen dataclass; the name is its key in Program.relations
Walk(relation, consumed, produced, joined), a NamedTuple whose name read off the relation	Walk(name, relation, consumed, produced, joined), a frozen dataclass
Footprint.shapes	Footprint.nodes

Deleted

Was	Now
Expression base class, with __add__ and __mul__	the nodes share no base; Expression is the union. Build Add(a, b) and Multiply(a, b)
Program.dimension(name)	program.dimensions[name]
Program.parameter(name)	program.parameters[name]
Program.variable(name)	program.variables[name]

Kept, deliberately: Sum.over, and over, into and coordinate on GroupSum and Pullback. #477 settled the call keywords on over= and into=, and the program follows the file. Also kept: the public walk helpers with no caller in this tree (fan_in, is_quadratic, parameters_of, quotients, divisor_parameters, check_message, Mask.conjuncts, Mask.names_read), since whether lpspec reads them is not visible from here.

Why

The naming table says Node marks the core AST and the program uses bare names, yet the program's where vocabulary carried the suffix. At was the file's spelling where the rule asks for the coordinate map, and Window did not say it sums. A translation and a window called their axis dimension where every other node and the file itself name it. The file's expressions: arrived under a different name while Program.expressions meant something else. Relations were nested under each dimension they touch, one relation under several, and a property undid the nesting; with the group keyed by name, the declaration's own name field was a second home for one fact. The singular accessors covered three of five groups, and one had no caller. The operator sugar contradicted the reading page's "you never build a node yourself".

Verification

pixi is not installable in this session (the installer host is blocked), so the gates ran from a uv venv on Python 3.12 with the same pinned ruff==0.16.1 and pyrefly==1.2.0.

Ran on the current head:

• ruff check and ruff format --check on src, tests, tools: clean.
• pyrefly check --python-interpreter-path <venv>: 0 errors, 9 suppressed, same as main.
• pytest -q -n auto: 1265 passed, 6 skipped. The 6 skips are the typst compile tests, which skip without the typst binding.
• python -m tools.schema, python -m tests.typesetting.golden and the four page generators: no diff.
• mkdocs build --strict: builds, with the docs.python.org inventory line removed locally because that host is blocked here. The config is unchanged in the commit.
• prettier --check on every Markdown file: clean.

Not run: reuse lint, typos, taplo, zizmor, compile-tex, and pixi run ci as one command.

Coverage moved:

• test_an_unknown_dimension_is_a_near_miss_rather_than_an_empty_declaration is deleted with the accessor it tested.
• test_a_relation_names_the_dimension_its_values_label is replaced by test_a_relation_is_declared_as_the_file_declares_it, which lowers a file rather than hand-building a program.
• test_expressions_are_the_ones_a_row_is_built_from is test_roots_are_the_trees_a_row_is_built_from.
• test_a_program_seals_its_declaration_groups now covers relations too.
• Two tests that built nodes with * and + now call Multiply and Add. The review claimed the sugar had no caller in tests; it had these two.
• The golden test's carrier set gains Walk and RelationDeclaration, which its dataclass walk now reaches.

Departed defaults: the branch name is the one this session was given rather than <type>/<topic> in a worktree; the renames and the relation restructure ship in one PR at the follow-up's ask rather than stacked; and main was merged in rather than the branch rebased, because the project forbids a force-push.

🤖 Generated with Claude Code

https://claude.ai/code/session_019fhGZgaBspo7mh9Hjd3KtT

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34578888 | 📁 Comparing d54968f against latest (5656b11)

  🔍 Preview build  

37 files changed · ± 37 modified

± Modified

• index.html
• CHANGELOG/index.html
• contributing/index.html
• about/limits/index.html
• examples/commitment/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa_losses/index.html
• and 27 more...

[FBumann]

@FabianHofmann This is a cleanup of the code that is breaking for lpspec and linopy-mathspec.

I like the naming much more! Please accept.

EDIT: I would defer this until we merged #437

[FBumann]

Note

The following content was generated by AI.

Follow-up once #437 lands. #437 rewrites lookups as relations and redefines what over= means on the surface: it survives only on shift, sum_back and position, as "the axis walked and kept", while a sum's dims become consume=. Three of this PR's renames already agree with that (Program.lookups keyed by name, over on Translate and WindowSum, Pullback as the read). Four more only make sense on top of #437's semantics, so they wait for it rather than land here:

• Sum.over becomes consumed. Under feat(language): a relation between dimensions, walked in the direction each call names #437, over in the program should mean an axis that stays, as it does on the surface.
• GroupSum and Pullback expose consumed and produced rather than over and into. feat(language): a relation between dimensions, walked in the direction each call names #437's body lists this as open.
• Walk becomes a frozen dataclass rather than a NamedTuple, as every other program record is.
• LookupDeclaration drops its name field once the group is keyed by name, and Walk carries the name instead.

Not planned: renaming lookups to relations in the program. The file still says lookups:, and the program follows the file's group names.

Merge order. #437 first, then this PR re-applied on top. This diff is a scripted rename over 23 files and is cheap to regenerate; rebasing #437's 84 files over these renames is manual conflict resolution in resolution.py, exclusivity.py, the where parser and the typesetter.

---

Generated by Claude Code

[FBumann]

Superseeded by #585