[FabianHofmann]

Note

The following content was generated by AI.

Supersedes #905: the same rename, on current main, without the PyPSA YAML work.

What this changes

mathspec.rename(source, names) returns a spec with other names, so one fragment states several components in one merge. names is a map or a function.

# before: one hand-written file per component
ms.merge(['network.yaml', 'gas.yaml', 'wind.yaml'])

# after: one fragment, renamed by a rule (or by a map)
def named(prefix, dim):
    def new_name(name):
        if name == 'unit':
            return dim
        return prefix + name.removeprefix('Unit') if name.startswith('Unit_') else None
    return new_name

ms.merge(['network.yaml', ms.rename('unit.yaml', named('Gas', 'gas')), ms.rename('unit.yaml', named('Wind', 'wind'))])
ms.rename('generator.yaml', {'Generator_p_nom': 'Generator_capacity'})

Why

• PyPSA maps names by rule (Unit_p_nom → Generator_p_nom); a function saves listing every name first
• the PyPSA spec moves to feat: build the optimisation model from pypsa.yaml via linopy PyPSA/PyPSA#2128, so the PyPSA YAML work of feat(composition): rename gives a spec other names, so one fragment can serve several classes in one merge #905 is dropped; its last head is ad386d8

Method, gate output, alternatives

• gate: pixi run lint (with pyrefly), test (4197 passed, 1 skipped), docs-build exit 0 on 4b9ea22; compile-tex passed on 3cd3e97, no file under examples/ changed since
• not run: specsolve parity harness
• renamed: entry keys, dims:, relation sides, a relation column named after its dimension, adds_to:, given: entries, name tokens in expression, where:, bound, case, assumption and macro template text
• kept: description, one_of: labels, case and link names, macro arguments, fixed choices, call keywords, quoted labels, numbers
• a map value of None or of the same name keeps the name, as in the function form
• refused before any rename: a key the spec lacks; a new name already in use; two names on one; a new name that is a macro argument where the template uses the old name; a name to or from a relation column not named after its dimension; names neither a map nor a function (TypeError)
• fresh review by a separate agent found the last three; each reproduced, then fixed with a test; each guard removed in turn fails its test
• ported from feat(composition): rename gives a spec other names, so one fragment can serve several classes in one merge #905 to main: conditions: for masks:, frozen sorted sections; one_of: labels and link names stay as written
• sweep, not in the suite: 58 files under examples/ rename to a prefix and back to the same canonical form
• docs: how-to section with the steps; composition.md has a rename section with what it changes and keeps, and each refusal quoted whole; page examples and messages run and match
• no figure for rename: it changes names, not rows
• prose checked against the prose-writing and docs-writing skills; compose.md: 51 sentences, average 10.6 words; composition.md: 113, average 13.9; none over 25
• not done: renaming inside description:; merge still names a renamed spec by its place, such as '#2'; a quoted label that ends in \ inside an expression is not handled like the parser does (not reproduced)

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #35851057 | 📁 Comparing 4b9ea22 against latest (5029b4e)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• about/versions/index.html
• howto/check/index.html
• howto/compose/index.html
• howto/installation/index.html
• reference/api/index.html
• reference/changelog/index.html
• reference/composition/index.html
• reference/language/file/index.html

[FabianHofmann]

I would deliberately merge this as this is super useful for the pypsa pr. Hope that works out