Skip to content

docs(notation): the notation page shows a named expression whose declared frame is wider than its body #756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FBumann merged 2 commits into from
Sep 28, 2026
Merged

docs(notation): the notation page shows a named expression whose declared frame is wider than its body #756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
21c3563
docs(notation): the golden model and the notation page show a named e…
claude Sep 28, 2026
9c924c0
Add the changelog line for #756
claude Sep 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp

## Upcoming version

- docs(notation): the notation page shows a named expression whose declared frame is wider than its body ([#756](https://github.com/energy-models/mathspec/pull/756))
- feat(language): a named expression may declare the frame it is read over ([#741](https://github.com/energy-models/mathspec/pull/741))
- docs: code examples on the site are readable in light and dark mode, and a diagram shows what mathspec leaves to engines and other tools ([#730](https://github.com/energy-models/mathspec/pull/730))
- docs: the site follows the reader's light or dark setting, and a page shows where it sits in the navigation ([#727](https://github.com/energy-models/mathspec/pull/727))
Expand Down
31 changes: 31 additions & 0 deletions docs/reference/notation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ parameters:
|---|---|
| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{G}`$ |
| $`\mathit{spend}`$ | `spend` over $`\mathcal{T}`$ β€” what a snapshot's dispatch costs |
| $`\mathrm{rating}`$ | `rating` over $`\mathcal{G} \times \mathcal{T}`$ |
| $`\mathit{lcoe}`$ | `lcoe` (scalar) |
| $`\mathit{marginal\_price}`$ | `marginal_price` over $`\mathcal{T} \times \mathcal{B}`$ |
| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{T} \times \mathcal{G}`$ β€” what starting a unit in this snapshot costs, which the horizon's edge changes |
Expand Down Expand Up @@ -645,6 +646,21 @@ constraints:
p_{t,g} \le \mathrm{startup\_cost}_{t,g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
```

#### Expression with a declared frame in a constraint

names the expression with a declared frame: the row reads it at every snapshot, though its body has no snapshot

```yaml
constraints:
under_rating:
dims: [snapshot, generator]
expression: p <= rating
```

```math
p_{t,g} \le \mathrm{rating}_{g,t} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
```

#### Plain named expression

a plain named expression: its symbol prints where it is used, its body once as a definition
Expand All @@ -659,6 +675,21 @@ expressions:
\mathit{spend}_{t} = \sum_{g \in \mathcal{G}} p_{t,g} \cdot \mathrm{cost}_{g} \qquad \forall\, t \in \mathcal{T}
```

#### Named expression with a declared frame

a frame wider than the body, in an order of its own: the value is the same at every snapshot

```yaml
expressions:
rating:
dims: [generator, snapshot]
expression: eta * p_max
```

```math
\mathrm{rating}_{g,t} = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T}
```

#### Expression defined by cases

a quantity defined by region: no two cases overlap, and `otherwise` is the rest
Expand Down
3 changes: 3 additions & 0 deletions tests/typesetting/golden/latex.out
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
\begin{description}
\item[{$\mathrm{spend}^{\mathrm{cap}}$}] \texttt{spend\_cap} over $\mathcal{G}$
\item[{$\mathit{spend}$}] \texttt{spend} over $\mathcal{T}$ --- what a snapshot's dispatch costs
\item[{$\mathrm{rating}$}] \texttt{rating} over $\mathcal{G} \times \mathcal{T}$
\item[{$\mathit{lcoe}$}] \texttt{lcoe} (scalar)
\item[{$\mathit{marginal\_price}$}] \texttt{marginal\_price} over $\mathcal{T} \times \mathcal{B}$
\item[{$\mathrm{startup\_cost}$}] \texttt{startup\_cost} over $\mathcal{T} \times \mathcal{G}$ --- what starting a unit in this snapshot costs, which the horizon's edge changes
Expand Down Expand Up @@ -88,6 +89,7 @@
\begin{align}
\text{budgeted} && \mathit{spend}_{t} & \le \mathrm{budget} && \forall\, t \in \mathcal{T} \\
\text{starts} && p_{t,g} & \le \mathrm{startup\_cost}_{t,g} && \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \\
\text{under\_rating} && p_{t,g} & \le \mathrm{rating}_{g,t} && \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \\
\text{balance} && \sum_{g \in \mathcal{G} \,:\, \mathrm{gen\_bus}(g) = b} p_{t,g} + \mathit{spill}_{t} - \mathit{slack}_{t} & = \mathrm{load}_{t,b} && \forall\, t \in \mathcal{T},\ b \in \mathcal{B} \\
\text{ramp} && p_{t,g} - p_{t \ominus 1,g} & \le p_{t - 1,g} + \mathrm{p}^{\mathrm{max}}_{g} && \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \\
\text{edges} && p_{t \boxminus_{0} 1,g} & \le p_{t \boxplus_{0} 1,g} + \mathrm{p}^{\mathrm{max}}_{g} && \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \\
Expand Down Expand Up @@ -143,6 +145,7 @@
\begin{align}
\text{spend\_cap} && \mathrm{spend}^{\mathrm{cap}}_{g} & = \mathrm{cost}_{g} \cdot 2 && \forall\, g \in \mathcal{G} \\
\text{spend} && \mathit{spend}_{t} & = \sum_{g \in \mathcal{G}} p_{t,g} \cdot \mathrm{cost}_{g} && \forall\, t \in \mathcal{T} \\
\text{rating} && \mathrm{rating}_{g,t} & = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\
\text{lcoe} && \mathit{lcoe} & = \frac{\sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g} \cdot \mathrm{cost}_{g}}{\sum_{t \in \mathcal{T},\ g \in \mathcal{G}} p_{t,g}} \\
\text{marginal\_price} && \mathit{marginal\_price}_{t,b} & = \lambda_{\mathrm{balance},t,b} && \forall\, t \in \mathcal{T},\ b \in \mathcal{B} \\
\text{startup\_cost} && \mathrm{startup\_cost}_{t,g} & = \begin{cases} \mathrm{cost}_{g} & \text{if } \mathrm{pos}(t) = 0 \\ \mathrm{cost}_{g} \cdot 2 & \text{if } \mathrm{pos}(t) > 0 \wedge \mathrm{season\_of}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} && \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
Expand Down
13 changes: 13 additions & 0 deletions tests/typesetting/golden/markdown.out
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5
|---|---|
| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{G}`$ |
| $`\mathit{spend}`$ | `spend` over $`\mathcal{T}`$ β€” what a snapshot's dispatch costs |
| $`\mathrm{rating}`$ | `rating` over $`\mathcal{G} \times \mathcal{T}`$ |
| $`\mathit{lcoe}`$ | `lcoe` (scalar) |
| $`\mathit{marginal\_price}`$ | `marginal_price` over $`\mathcal{T} \times \mathcal{B}`$ |
| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{T} \times \mathcal{G}`$ β€” what starting a unit in this snapshot costs, which the horizon's edge changes |
Expand Down Expand Up @@ -98,6 +99,12 @@ $`\lvert \mathcal{T} \rvert`$ denotes the size of the set being counted along, a
p_{t,g} \le \mathrm{startup\_cost}_{t,g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
```

**`under_rating`**

```math
p_{t,g} \le \mathrm{rating}_{g,t} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G}
```

**`balance`**

```math
Expand Down Expand Up @@ -406,6 +413,12 @@ p_{t,g} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, t \in \mathcal{T},\ g
\mathit{spend}_{t} = \sum_{g \in \mathcal{G}} p_{t,g} \cdot \mathrm{cost}_{g} \qquad \forall\, t \in \mathcal{T}
```

**`rating`**

```math
\mathrm{rating}_{g,t} = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T}
```

**`lcoe`**

```math
Expand Down
6 changes: 6 additions & 0 deletions tests/typesetting/golden/model.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,9 @@ expressions:
spend: # a plain named expression: its symbol prints where it is used, its body once as a definition
description: what a snapshot's dispatch costs
expression: sum(p * cost, over=generator)
rating: # a frame wider than the body, in an order of its own: the value is the same at every snapshot
dims: [generator, snapshot]
expression: eta * p_max
lcoe: sum(p * cost) / sum(p) # nothing in the math reads it, so its divisor may carry a variable
marginal_price: dual(balance) # the row dual of a constraint, the one builtin only an entry the math never reads may call
startup_cost: # a quantity defined by region: no two cases overlap, and `otherwise` is the rest
Expand All @@ -160,6 +163,9 @@ constraints:
starts: # names the cased expression: its symbol prints here, its block once below
dims: [snapshot, generator]
expression: p <= startup_cost
under_rating: # names the expression with a declared frame: the row reads it at every snapshot, though its body has no snapshot
dims: [snapshot, generator]
expression: p <= rating
balance: # sum over a relation
dims: [snapshot, bus]
expression: sum(p, by=gen_bus, over=generator, into=bus) + spill - slack == load
Expand Down
3 changes: 3 additions & 0 deletions tests/typesetting/golden/typst.out
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5
== Definitions
/ $upright("spend")^(upright("cap"))$: `spend_cap` over $cal(G)$
/ $italic("spend")$: `spend` over $cal(T)$ --- what a snapshot's dispatch costs
/ $upright("rating")$: `rating` over $cal(G) times cal(T)$
/ $italic("lcoe")$: `lcoe` (scalar)
/ $italic("marginal_price")$: `marginal_price` over $cal(T) times cal(B)$
/ $upright("startup_cost")$: `startup_cost` over $cal(T) times cal(G)$ --- what starting a unit in this snapshot costs, which the horizon's edge changes
Expand All @@ -75,6 +76,7 @@ $ & max & sum_(t in cal(T), g in cal(G)) p_(t,g) dot upright("cost")_(g) + sum_
#set math.equation(numbering: "(1)")
$ upright("budgeted") & italic("spend")_(t) & <= upright("budget") & forall t in cal(T) \
upright("starts") & p_(t,g) & <= upright("startup_cost")_(t,g) & forall t in cal(T), g in cal(G) \
upright("under_rating") & p_(t,g) & <= upright("rating")_(g,t) & forall t in cal(T), g in cal(G) \
upright("balance") & sum_(g in cal(G) colon upright("gen_bus")(g) = b) p_(t,g) + italic("spill")_(t) - italic("slack")_(t) & = upright("load")_(t,b) & forall t in cal(T), b in cal(B) \
upright("ramp") & p_(t,g) - p_(t minus.o 1,g) & <= p_(t - 1,g) + upright("p")^(upright("max"))_(g) & forall t in cal(T), g in cal(G) \
upright("edges") & p_(t minus.square_(0) 1,g) & <= p_(t plus.square_(0) 1,g) + upright("p")^(upright("max"))_(g) & forall t in cal(T), g in cal(G) \
Expand Down Expand Up @@ -129,6 +131,7 @@ $ upright("budgeted") & italic("spend")_(t) & <= upright("budget") & forall t in
#set math.equation(numbering: "(1)")
$ upright("spend_cap") & upright("spend")^(upright("cap"))_(g) & = upright("cost")_(g) dot 2 & forall g in cal(G) \
upright("spend") & italic("spend")_(t) & = sum_(g in cal(G)) p_(t,g) dot upright("cost")_(g) & forall t in cal(T) \
upright("rating") & upright("rating")_(g,t) & = upright("eta")_(g) dot upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \
upright("lcoe") & italic("lcoe") & = frac(sum_(t in cal(T), g in cal(G)) p_(t,g) dot upright("cost")_(g), sum_(t in cal(T), g in cal(G)) p_(t,g)) \
upright("marginal_price") & italic("marginal_price")_(t,b) & = lambda_(upright("balance"),t,b) & forall t in cal(T), b in cal(B) \
upright("startup_cost") & upright("startup_cost")_(t,g) & = cases(upright("cost")_(g) & upright("if ") upright("pos")(t) = 0, upright("cost")_(g) dot 2 & upright("if ") upright("pos")(t) > 0 and upright("season_of")(t) = upright("'winter'"), 0 & upright("otherwise")) & forall t in cal(T), g in cal(G) $
Expand Down
2 changes: 2 additions & 0 deletions tools/notation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,9 @@
'Named expressions': {
'budgeted': 'Plain expression in a constraint',
'starts': 'Cased expression in a constraint',
'under_rating': 'Expression with a declared frame in a constraint',
'spend': 'Plain named expression',
'rating': 'Named expression with a declared frame',
'startup_cost': 'Expression defined by cases',
'spend_cap': 'Data-only expression',
'capped': 'Named expression in a condition',
Expand Down
Loading