feat(program): the axis a join opens names the relation column it stands for

[FBumann]

Prompt: Let's do this as 2 stacked PRs. One introducing the new syntax, but keeping the dot notation internally, and then the one adding the axis class […] Can we simplify it with a stacked PR?

Note

The following content was generated by AI.

Axis(dimension, column) replaces the dotted axis names in Sum.over and JoinColumns.axes. A join's axis names its Column(relation, name). A dimension's own axis has no column. Frames stay sets of dimension names. This PR includes #799.

What this changes

• Column(relation, name) and Axis(dimension, column=None) are public in mathspec.program. str() gives the user spelling: generator, or zone_of[generator] for a join's axis.
• Sum.over is tuple[Axis, ...]. sum(p, over=g) stores (Axis('g'),). sum(p, over=g, by=R[c]) stores the join's axes. A dim that no column of the relation is over gets its own Sum of dimension axes around that.
• JoinColumns.axes is tuple[Axis, ...]. Each axis runs over the dimension of the column the join drops, and stands for that column. A map into its own dimension gives the join axis Axis('snapshot', Column('rep_of', 'snapshot')), which is not equal to Axis('snapshot'). The type keeps them apart. Before, a naming trick did it.
• Separability reads axis.column to tell a grouping from a plain sum. The dictionary that mapped an axis string back to its dimension is removed.
• The dimension check is unchanged for callers. dims_of still returns a set of dimension names. It reads a sum over a join as one rule, so a join's axes never reach a frame (chore(program): a frame stays a set of dimension names, and only the sum over a join reads the axes it opens #799).

Why

Agreed in the discussion on #662. With the dotted name, a join axis was kept apart from a dimension by a character, and every consumer had to know that. With Axis, the type does it: pyrefly checks it, and a consumer reads axis.dimension or axis.column. It does not branch on the kind of axis and does not parse strings.

The axes are needed only between a join and the sum that closes it. The resolver is the only code that builds a sum over a join, and it always sums over exactly join.axes. So frames do not carry axes (#799). That removed about 40% of this PR's diff, and one class of silent error: a string tested for membership in a set of axes.

Method, guards, coverage moved, gates, not done

How this PR was made

The first version changed frames to frozenset[Axis] as well. #799, stacked on this PR, changed them back to dimension names and was squash-merged into this branch as 8aed330. 3dfafa6 changes the changelog line to this title. The branch is not rebased and not force-pushed.

src/ and tests/, against #664's head	files	lines
before #799	13	+183 / −107
now	9	+106 / −61

Guards and the tests that fail without them

Each guard was undone in turn, the suite was run, and the tree was restored. The first two were taken before #799, and #799 did not change their lines.

guard	caught by
a join's axis is not the dimension's own axis	5 tests, e.g. test_dim_inference[a-map-into-its-own-dimension-keeps-the-frame]
separability reads a join axis as a grouping	test_a_grouping_that_sums_the_axis_away_couples_it

#799 added two asserts in dimensions.py:

• A sum over a join closes exactly join.columns.axes.
• A join that opens axes is read only by the sum that closes them.

The resolver makes both true, so no test fails when either one is deleted. No probe builds such a node by hand. The three Axis(d) in frame guards of the first version are removed together with the lines they guarded.

Coverage that moved

• tests/test_dimensions.py compares frames to string sets, as on feat(language)!: a call names the columns of a relation as relation[column], and a sum through a relation is a sum over the axes its join opens #664. The self-map test asserts node.over == (Axis('snapshot', Column('rep_of', 'snapshot')),) and the frame of the sum. It does not check the frame of the bare join, because that frame no longer exists.
• tests/test_lowering.py and tests/test_expansion.py build Sum with Axis values.
• tests/typesetting/test_golden.py lists Axis and Column in CARRIERS, because they are values that a node carries, not nodes.

Gates, on 3dfafa6

Pixi is not reachable here. The gates ran from a uv venv on Python 3.12, with the pinned ruff and pyrefly.

gate	result
pytest -q -n auto	2557 passed, 53 skipped
ruff check, ruff format --check .	clean
pyrefly check on src/	4 errors, all about missing yaml stubs in the venv
generators, docs-build, compile-tex, the git hooks	not run here. #799 changes no generated file, no docs and no printed output. CI runs docs-build and compile-tex.

Not done

• Relation columns are still called roles internally. JoinColumns.dropped and the other fields hold column names, and Column.name is that name. The role to column rename is separate.
• JoinColumns.joined_dims and the other *_dims properties stay strings. They name dimensions.
• The feat(language)!: a call names the columns of a relation as relation[column], and a sum through a relation is a sum over the axes its join opens #664 cleanups a review found are not included, for example JoinColumns.kept_dims, which has no reader. That is separate work.
• fluxopt/lpspec is not updated. It reads Sum.over, and it must read axis.dimension, and axis.column for a grouping.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CPwrjirBZhVS4CcndN6f4H

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34754288 | 📁 Comparing 2d367bb against latest (b56e28e)

  🔍 Preview build  

62 files changed · + 5 added · ± 35 modified · - 22 deleted

+ Added

• first-model/index.html
• about/relations-as-linear-maps/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/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• and 25 more...

- Deleted

• 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
• reference/math_spec/operators/index.html
• and 12 more...

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34855897 | 📁 Comparing 3dfafa6 against latest (ae4a44c)

  🔍 Preview build  

42 files changed · + 1 added · ± 41 modified

+ Added

• about/relations-as-linear-maps/index.html

± Modified

• changelog/index.html
• contributing/index.html
• several-files/index.html
• about/limits/index.html
• about/what-counts-as-language/index.html
• examples/operators/index.html
• examples/pypsa_linearized_uc/index.html
• howto/compose/index.html
• howto/curve-by-hand/index.html
• howto/declare-a-column/index.html
• and 31 more...