feat: upright is what the model is given, italic is what the solver chooses

[FBumann]

Targets main, so #31 and the stack rebase onto it. A pass over the page as a whole — which is what notation.md exists to make possible — turned up one distinction the notation was not drawing at all, six places where it said something other than what it meant, and one about to start saying something a reader could not trace.

The distinction that was missing

$$\sum_{g\,:\,\mathrm{gen\_bus}(g)=b} p_{t,g} + \mathit{spill}_{t} - \mathit{slack}_{t} = \mathrm{load}_{t,b}$$

Three of those four are chosen by the solver and one is data. Before this, all four printed identically: ParameterNode and VariableNode reached the page through one call on one symbol dict, with nothing between them.

Upright is what the model is given — a parameter, a coordinate map, a label. Italic is what the solver chooses. The nomenclature table stays and is a real convention in this field, but it is a lookup rather than a reading: quote one equation on a slide and the legend does not travel with it.

It also completes a system the page was already three-quarters through — script for index sets, upright for the maps and qualifiers a model is handed, italic for quantities. The cut this adds is inside italic.

	before	after
parameter	$\mathit{load}_{t,b}$	$\mathrm{load}_{t,b}$
variable	$\mathit{spill}_{t}$	unchanged
parameter, single letter	$p^{\mathrm{max}}$	$\mathrm{p}^{\mathrm{max}}$
parameter, Greek name	—	$\mathrm{eta}_{g}$
variable, Greek name	—	$\theta_{b}$

The rule admits no exception. Not for single letters: $\mathrm{p}^{\mathrm{max}}$ beside a variable $p$ is exactly the pair a reader has to be able to tell apart. And not for Greek, which was the interesting one:

upgreek is what LaTeX needs for an upright lower-case Greek letter, and taking it costs two things this repository holds on purpose. A two-package preamble — the CI render gate exists partly to assert it stays installable from a small TeX. And markdown that renders the same in both places: docs/static/mathjax.js says it outright, "a block pasted out of to_markdown should render the same here as it does on GitHub", and GitHub's MathJax takes no configuration, so an extension the docs site can load is one GitHub cannot — \uptheta would render there as an error.

So the letter yields to the rule rather than the rule to the letter. A Greek name prints as the letter where it is chosen and upright as the word where it is given; an italic $\eta$ that might be either is worse than an upright $\mathrm{eta}$ that is one. The escape hatch costs nothing and already exists: a table entry is printed verbatim, so an author whose own preamble loads upgreek writes eta: "\upeta". The fixture now shows both cases in one legend, $\mathrm{eta}$ beside $\theta$.

The legend states the convention once, in the model's own symbols, gated on the model having both — a note explaining a contrast the page does not draw is the dead end the translation notes already avoid. The index-collision guard shrank to exactly the collisions that are still collisions: a dimension may now take p beside a parameter p, because $\mathrm{p}$ and $p$ are not the same symbol.

The six fixes

	before	after
a name that is a Greek letter	$\mathit{theta}_b$	$\theta_b$
an axis as a qualifier head	$\mathit{zone}^{\mathrm{cap}}$	$\mathrm{zone_cap}$
negation under a +	$-\mathit{reserve} + -\mathit{headroom}$	$-\mathrm{reserve} - \mathrm{headroom}$
a bracketed negation	$\left(-\left(\sum p\right)\right)\cdot 3$	$-\left(\sum p\right)\cdot 3$
the fill and the group	$\boxminus_{0,\mathrm{season_of}(t)}$	$\boxminus_{0}^{\mathrm{season_of}(t)}$
a mask that is only True	$\forall t \in \mathcal{T} : \top$	$\forall t \in \mathcal{T}$

• Greek is the same curated-map move as _INDEX_ALIASES, lower case only, and it composes with the qualifier rule so theta_max is a head a qualifier hangs off.
• The qualifier head must name a quantity. zone_cap is a capacity indexed by zone, not a zone qualified by cap — and reading the axis as the head made a parameter's symbol depend on whether some unrelated dimension shared its prefix, which is why the fixture showed zone_cap splitting and tech_cap not.
• a + -b is a spelling nobody uses; folding also hands the right operand subtraction's bracket rule, which is the one it needs.
• The fill and the group shared one subscript because two subscripts is a Double subscript error that stopped the page compiling (#1165) — but comma-joined there, 0,season_of(t) said nothing about which was the value at the boundary and which was the group. Fill below, group above, with a legend note.
• True is the same as no where per expressions.md, so the condition read as one and was not. Nested it still prints; ⊥ stays either way, because "this constraint has no rows" is worth seeing.

One inconsistency left deliberately: a group rides the superscript on a translation and the subscript on pos (#31). Each is unambiguous alone, but they are not the same slot. Making them agree means moving pos, which is a decision in flight on that PR rather than one to take from here.

The seventh: a table, not a rename

economies_of_scale_lam printed six times in one row is unreadable, and the piecewise-linear literature calls it λ. Renaming it inside the typesetter would have produced a symbol nobody could trace back to the file, so the rename is a declaration — the --symbols sidecar any reader may write, under the filename convention tools/render_tex.py already uses — and the notation page prints the table beside the math it renamed:

Rendered with the sidecar symbol table examples/symbols/transport_pwl.yaml, which is what the weights print as:

notation: latex
names:
  economies_of_scale_lam: "\lambda"
  economies_of_scale_seg: "\delta"
  bp_x: "\mathrm{x}"
  bp_y: "\mathrm{y}"

$\mathit{economies_of_scale_lam}{p,m,b} \le \mathit{economies_of_scale_seg}{p,m,b} + \ldots$ becomes $\lambda_{p,m,b} \le \delta_{p,m,b} + \delta_{p,m,b \boxminus_{0} 1}$, and none of it is the typesetter's opinion. The tables follow the convention they now live under: the weights are variables, so they stay Greek; bp_x/bp_y are data, so they print upright.

The fixture

Four cases it owed: a nested True beside the mask that is only one, a unary + — whose walk arm the line-coverage guard had never reached, because it sat inside a ternary until this change split it — and a Greek name on each side of the convention.

Checks

pixi.sh is unreachable from this environment, so the gates ran on a 3.13 venv at the versions pixi.toml pins, plus prettier@3.9.3 and typos fetched directly: 375 passed (including the Typst compiles and the walk's line-coverage guard), ruff check and format clean, pyrefly 0 errors, prettier clean over the files this touches, typos clean, reuse lint compliant. Goldens, notation.md and docs/examples/ all regenerated by their own tools; render_tex renders all nineteen models, the four new tables included. pixi.lock and schema/math-spec.schema.json fail a repo-wide prettier --check here exactly as they do on main — both generator-owned and outside the hook's *.{md,yml,yaml} glob.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34192965 | 📁 Comparing 1e6bcd1 against latest (e0e1fe8)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• examples/dispatch/index.html
• examples/operators/index.html
• reference/notation/index.html
• reference/language/operators/index.html
• reference/math_spec/typeset/format/index.html
• reference/math_spec/typeset/latex/index.html
• reference/math_spec/typeset/markdown/index.html
• reference/math_spec/typeset/symbols/index.html
• reference/math_spec/typeset/typst/index.html
• reference/math_spec/typeset/walk/index.html