[FBumann]

Prompt: I think making it sorty by name, stable and predictable, is better. We can add mroe complex rules later maybe...

Note

The following content was generated by AI.

What this changes

The dims that the loader derives for an entry are sorted by name. The order of dimensions: no longer reaches any value of the program. Entries that declare dims: keep the order the file writes.

The four derived orders, and what a reader sees

Derived dims	Before	Now
a named condition (NamedCondition.dims)	in the order dimensions: declares	sorted by name
a named expression that declares no dims:	in the order dimensions: declares	sorted by name
a piecewise curve's frame (Piecewise.frame), and so the dims of the variables and constraints its expansion writes	in the order dimensions: declares, in the order the links are met	sorted by name, then the breakpoint dimension
a comparison of two expressions in a condition (ExpressionComparison.dims)	in the order dimensions: declares	sorted by name

What a reader sees:

• The printed indices of those entries follow, for example $\mathit{marginal\price}{b,t}$ instead of $\mathit{marginal\price}{t,b}$, and cost_curve_lam over [generator, snapshot, bp] instead of [snapshot, generator, bp].
• One line can print two orders. A composed sum whose reader declares dims: [snapshot, bus] prints as injection_(t,b) = generator_injection_(b,t) + …, because its terms declare no dims:.
• specsolve lays out a named condition and the expansion's variables in the new order.
• The golden typesetter output, the generated pages, and the pypsa fragments (given: conditions: restates the condition's dims) are regenerated with their tools, not edited.
• docs/several-files.md shows printed output and is not generated, so it is edited by hand.

Why

On main (ed6af52), the same file loaded to a different program in 23 of the 53 examples when only dimensions: was reversed. The canonical form sorts dimensions:, so it changed the program too. A consumer needs one fixed order, not the author's order. A sort by name is that order, with nothing to keep in step across files. This is also what lets merge stay as it is.

Verification

The test. test_the_order_of_dimensions_reaches_no_value_of_the_program reverses dimensions: in every example and asserts that the program is equal, before and after expand(). On ed6af52 it fails for 23 of the 53 examples. It passes with this change.

test_the_form_declares_the_same_spec now compares the dims of each constraint and variable in their order, not as a set. Its docstring said that sorting variables: could reorder the dims of a constraint the expansion writes. That is no longer true. reading.md said the same, and is corrected.

Gates on ae0e4ec:

• pixi run lint passes.
• pixi run test passes: 2976 passed, 1 skipped.
• pixi run docs-build passes.
• compile-tex was not run, because the container cannot download the TeX bundle. CI runs it.

Mutation table. Each change was made by hand and the full suite was run. The file was restored with git checkout --, __pycache__ was dropped before and after each run, and the tree came back clean each time.

Change	Caught by
a named condition's dims in declaration order	33 failures: 16 cases of the new test, 15 generated pages, test_the_fragments_are_what_the_splitter_writes, test_a_named_condition_stands_where_its_name_is_written_with_its_condition_under_it
a named expression without dims: in declaration order	24 failures: 9 cases of the new test, 10 generated pages, the golden output, test_the_composed_sum_prints_its_terms_by_name, test_every_python_step_prints_what_the_page_shows
a curve frame in declaration order	18 failures: 5 cases of the new test, 5 of test_the_form_declares_the_same_spec, the golden output, test_a_curve_prints_over_the_frame_its_expansion_builds_one_per_coordinate_of
a comparison of two expressions in declaration order	7 cases of the new test

Coverage moved. test_the_emitted_foreach_follows_file_order is now test_the_emitted_frame_is_sorted_by_name_whatever_order_the_file_declares, with the same two orders of dimensions: and one expected frame.

Not done

• Expression nodes have no dims on main. feat(program): each expression node states the dimensions it is read over #899 adds them. Once this PR merges, feat(program): each expression node states the dimensions it is read over #899 takes main and sorts its node dims by name too. Its named-expression frame then needs no special case.
• Leaf conditions (ParameterDefined and the others) keep the order of the entry they read, which is an order the file writes.
• The breakpoint dimension stays last in the dims an expansion writes. It is not a derived set, and a curve's breakpoints stay contiguous.
• specsolve's scope.in_declaration_order stays as it is until a release. It is a separate PR there.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D2S9sN1jLGGMCCwqwVyGD6

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35273420 | 📁 Comparing d61753d against latest (ed6af52)

  🔍 Preview build  

24 files changed · ± 24 modified

± Modified

• several-files/index.html
• examples/pypsa_linearized_uc/index.html
• reference/changelog/index.html
• reference/notation/index.html
• reference/program/index.html
• reference/reading/index.html
• examples/pypsa/generator/index.html
• examples/pypsa/generator_commitment/index.html
• examples/pypsa/generator_maintenance/index.html
• examples/pypsa/generator_ramping/index.html
• and 14 more...

[brynpickering]

My general preference is to follow the order defined in dimensions as the user might have good reason to order it like that. However, this will mean that diffs become harder. If the user changes the order of dimensions in one version compared to the last then the diff will be riddled with changes that are immaterial (dims list reordering).

So, agreed that this is the safest approach. It will match the dimension order on dump anyway since those keys get ordered by name (right?).

[FBumann]

My general preference is to follow the order defined in dimensions as the user might have good reason to order it like that. However, this will mean that diffs become harder. If the user changes the order of dimensions in one version compared to the last then the diff will be riddled with changes that are immaterial (dims list reordering).

So, agreed that this is the safest approach. It will match the dimension order on dump anyway since those keys get ordered by name (right?).

Yes. I also think that having a custom order would be appreciated, but making this work early with composition will be quite hard...

We might revisit this in the future.