feat(spec): a decided variable becomes a supplied number in one call, so a subproblem is not a second file

[FBumann]

Prompt: "Lets tackle the remaining issues in https://github.com/energy-models/mathspec/milestone/12"

Then, for #303: "Port #748 onto main (Recommended)"

Then: "Review 824. Any simplifications or refactorings? Is the wording good? Is it placed in a how to?", and "Yes" to applying the findings.

Then: "Should we rebase 824 onto this PR?" (#810), "I think so!!", and "i removed the stack. Retarget both and rebase them."

Note

The following content was generated by AI.

What this changes

spec.fix(*names) turns each named variable into a parameter with the same name, and every expression goes on reading it. A Benders subproblem, a myopic step or a rolling window is then a call on the whole model, not a second file. The parameter takes the variable's missing:, so no row changes. Closes #303.

Stacked on #810, rebased onto its branch. GitHub moves the base to main when #810 merges. #826 is stacked on this PR.

Rules, the stack, what moved, guards, gates, what was not done

The rewrite

• The variable becomes a parameter over the same dims. binary and integer become int, and continuous becomes float. The description is kept.
• The parameter takes the variable's missing:. A masked variable that is absent outside its mask gives a parameter that is missing: absent: a row that reads it there is still not built, and a sum has one summand fewer. A neutral variable gives a neutral parameter, which still reads 0. A variable with no where: existed everywhere, so its parameter keeps the default, error.
• Its bounds, and a binary's 0 and 1, become the assumption <name>_within_bounds, under the variable's where:. Each side is written once.
• A constraint that named only fixed variables becomes an assumption under its own name, with its where: and description.
• A set or a curve that names the variable refuses the fix. spec.expand().fix(...) works.
• All names are checked before the first one is rewritten. The result is validated once. fix('a').fix('b') equals fix('a', 'b').
• A variable that a fragment reads under given: variables: is refused, and the message tells you to fix it on the merged spec.

What the stack removed

Before #810, a parameter read 0 where the variable had been absent, so fix had to prove every read outside a sum was guarded, add the variable's mask to a row's where:, or refuse. With missing: absent every read keeps its meaning, so these are gone:

• _unguarded_reads, _spreading_reads and _guards, and the mask added to a row's where:;
• the refusal of a read in a case, and step 4 of the how-to;
• fixing.py is 147 lines, down from 250.

A read through a shift is still refused, now by the language's rule on a shift over an expression with no variable (it needs edge=), when the fixed spec reloads. Whether that rule should let an absent parameter through is a question for limits.md, not this PR.

Where the tests' coverage moved

Test before the stack	Now
test_an_unguarded_read_takes_the_mask_into_the_row, test_the_mask_joins_a_where_the_row_already_has, test_a_guarded_read_leaves_the_row_as_written, test_a_case_under_the_mask_is_guarded, test_a_read_the_mask_cannot_reach_is_refused[in-a-case…]	test_every_read_keeps_its_meaning_and_no_row_changes, over five readers: pointwise, under another mask, under its own mask, inside a sum, in a case
test_a_read_the_mask_cannot_reach_is_refused[through-a-shift]	test_a_read_through_a_shift_is_refused_by_the_language
test_two_masks_added_to_one_row_are_both_kept	test_fixing_two_masked_variables_together_is_fixing_them_one_at_a_time
—	test_the_parameter_reads_a_missing_row_as_the_variable_read_its_mask: error, absent, neutral
test_the_pypsa_capacities_are_guarded_where_they_are_read	test_the_pypsa_capacities_are_fixed_without_changing_a_row

Guards

Guard deleted	tests/test_fixing.py
the parameter takes the variable's missing:	8 failed

The guards for the rules that stayed (dtype, bounds written once, settled rows, set, curve, a name given twice, a given variable, a taken assumption name) were measured before the stack, and not re-measured.

Gates

On 87af38e, whose tree is the one tested before the rebase:

• pixi run lint: pass.
• pixi run test: 2692 passed.
• docs-build: the only warning is pathlib.Path, which needs docs.python.org/3/objects.inv; the proxy here refuses it.
• compile-tex: not run. tectonic cannot download its bundle here. The diff changes no typeset output.

The rebase replays the four commits onto #810, so the first three still read the old variable.absence, and only the last one passes. Pushed with --force-with-lease, at your instruction, against the AGENTS.md rule.

Not done

• A reported expression that reads a masked variable keeps the parameter's reading: absent where the variable was absent.
• dual(c) of a constraint that becomes an assumption stops resolving. The reload names it.
• A masked, unbounded variable gets no assumption that the data carries a row inside its mask; under absent a missing row there is read as absence.
• feat: a decided variable becomes a supplied number, so a subproblem is a call on the whole model #748 is still open. Close it in favour of this PR.

Why

#303: a fix that a driver writes by hand is wrong in two ways, and nothing reports either. A masked variable reads 0 where it did not exist, and a binary becomes a float. Two drivers would also each decide these rules differently.

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34895615 | 📁 Comparing 7defa6f against latest (34c68fd)

  🔍 Preview build  

39 files changed · ± 39 modified

± Modified

• changelog/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• howto/pin-a-variable/index.html
• reference/api/index.html
• reference/glossary/index.html
• reference/language/index.html
• reference/notation/index.html
• reference/program/index.html
• reference/reading/index.html
• and 29 more...