feat: sum_forward, the window sum_back already was pointed the other way

[FBumann]

What this changes

sum_forward(<expr>, over=<dim>, within=<n|parameter>[, edge='wrap'][, by=<lookup>]) — sums the next n positions along an axis, where sum_back sums the last n.

• operators.py, dimensions.py, degree.py — the operator, its dim rule, its place among the reductions.
• typesetting/walk.py — one branch renders both windows; _WINDOWS decides only which side of the lag operator the written index falls on.
• Four examples (sum_forward, _by_parameter, _wrap, _partitioned), three golden constraints, generator rows; docs regenerated.

Also carries the sum_forward half of #59: by= partitions a leading window exactly as it does a trailing one.

Why

sum_back and sum_forward are one operator with a direction. Spelling that direction in the name rather than in the sign of a width keeps the width a count — which is what every rule about it already assumes — and lets the typesetter render both from one place:

seasonal_window   ∑_{t' ∈ 𝒯 : 0 ≤ t  -^season_of(t) t' < 3} on_{t',g} ≤ units_g
seasonal_outlook  ∑_{t' ∈ 𝒯 : 0 ≤ t' -^season_of(t) t  < 3} on_{t',g} ≤ units_g

Same operator, operands swapped.

The sum_back half of #59 was split out into #65, since it fixed a rule main already documented in the BUILTINS comment and already checked in _dims_call — only the builtin declaration was missing, so the rule was unreachable. #59 is now closed as superseded.

Landing order

Merge #65 first. This branch is built on it — the partitioned-window typesetting (_group) comes from there — but GitHub refuses to retarget this PR's base ("the pull request is part of a stack", left over from the closed #59), so it still points at main and its diff shows #65's commit as well. Once #65 lands, rebasing this branch onto main drops that commit and the diff is sum_forward alone.

#61 → #63 also branch off #65, in parallel with this. Both this PR and #61 touch dimensions.py around the named-amount rules; whichever lands second needs the sum_forward keys added back to _AMOUNTS / _VARIES (and _NEGATED, from #63). That is a few lines rather than a conflict in the operator itself — but it argues for landing #61/#63 first, so those dicts get written once with both windows in them.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34254281 | 📁 Comparing 2759dd7 against latest (f1c207f)

  🔍 Preview build  

46 files changed · + 6 added · ± 40 modified

+ Added

• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• examples/pypsa_losses/index.html
• examples/pypsa_multi_period/index.html
• examples/pypsa_quadratic/index.html
• examples/pypsa_stochastic/index.html

± Modified

• 404.html
• index.html
• CHANGELOG/index.html
• contributing/index.html
• examples/index.html
• installation/index.html
• about/ceiling/index.html
• about/what-counts-as-language/index.html
• examples/dispatch/index.html
• examples/operators/index.html
• and 30 more...

[FBumann]

Rebased onto current main (alpha.24). The three wording tables the PR carried are main's one _AMOUNT_WORDING with a sum_forward row; the window branch reads the reduction the way main's walk does. Gate: pytest, strict docs, compile-tex.

[FBumann]

Note

The following content was generated by AI.

Closed at the author's request, in a sweep of the open PRs. Closed rather than rebased, because the operator surface this branch adds is written in a spelling main no longer uses.

The facts behind that:

• The branch is one commit from 24 August and was never rebased. fix: let sum_back stop at each group's edge, as its checks already assumed #65, which it says to merge first, merged on 25 August.
• feat(language): relations replace lookups, walked with over= and into= rather than consume= and produce= #477 renamed the ordered axis that shift and sum_back walk from over= to along=. This branch declares sum_forward(<expr>, over=<dim>, within=<n|parameter>[, edge='wrap'][, by=<lookup>]), so both the axis keyword and the word lookup are now wrong.
• feat(language): a relation between dimensions, walked in the direction each call names #437 replaced lookups: with relations:, which by= reads.
• The branch is conflicted against main.

Rebasing it would mean rewriting the operator declaration, the dim rule, the typesetting branch, four examples and three golden constraints against the new names. That is the work of writing it again, without the benefit of starting from what the language looks like today.

The feature is still wanted. sum_back and sum_forward are one operator with a direction, and the argument in this PR's description holds. It needs a fresh branch against current main, with along= as the axis keyword.

---

Generated by Claude Code