refactor(language): a relation is read in a direction rather than walked

docs/examples/commitment.md

@@ -123,7 +123,7 @@ Upright is what the model is given — a parameter such as $`\mathrm{committable
 
 $`t \boxminus_{v} k`$ denotes translation with $`v`$ standing where index $`t-k`$ leaves the dimension (`shift(edge=v)`), so the row at that boundary is built and carries $`v`$ rather than being dropped.
 
-$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` walks, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
+$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` steps along, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
 
 #### Objective
 

docs/examples/operators.md

@@ -76,7 +76,7 @@ $`\sum_{g \in \mathcal{G}} p_{t,g} \le \mathrm{limit}_{t} \qquad \forall\, t \in
 ```yaml
 description: >-
   The membership reduction — `sum(array, by=relation, over=a, into=b)` lands the result on the
-  column the relation is walked to, which is what makes topology data rather than
+  column the relation is read to, which is what makes topology data rather than
   structure.
 
 dimensions:
@@ -111,7 +111,7 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{gen\_bus}(g) = b} p_{t,g} \le \mathrm{li
 
 ```yaml
 description: >-
-  A walk that names its ends — `sum(array, by=relation, over=a, into=b)`
+  A call that names its ends — `sum(array, by=relation, over=a, into=b)`
   consumes column `a` and lands on column `b`, and the other key column is
   joined on, so each zone's total is taken per period.
 
@@ -147,7 +147,7 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone\_of}(g,\ e) = z} p_{g,e} \ge \mathr
 
 ```yaml
 description: >-
-  A walk with several columns at each end — `sum(array, by=relation, over=[a, …], into=[b, …])`
+  A call with several columns at each end — `sum(array, by=relation, over=[a, …], into=[b, …])`
   consumes both key columns at once and lands on the product of both value
   columns in one join.
 

docs/examples/pypsa.md

@@ -1385,7 +1385,7 @@ $`t \ominus k`$ denotes cyclic translation: index $`t-k`$ taken modulo the size
 
 $`t \boxminus_{v} k`$ denotes translation with $`v`$ standing where index $`t-k`$ leaves the dimension (`shift(edge=v)`), so the row at that boundary is built and carries $`v`$ rather than being dropped.
 
-$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` walks, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
+$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` steps along, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
 
 ### Objective
 

docs/examples/pypsa_linearized_uc.md

@@ -150,7 +150,7 @@ The relaxed class of a plain `n.optimize()`: `linearized_unit_commitment`, state
 | $`\overleftarrow{u}`$ | `Generator_previous_status` over $`\mathcal{T} \times \mathcal{G}`$ — the commitment state a generator carries into a snapshot — the state it brought into the horizon at the first, the previous snapshot's after that |
 | $`\overleftarrow{p}`$ | `Generator_previous_p` over $`\mathcal{T} \times \mathcal{G}`$ — the output a generator carries into a snapshot — nothing at the start of the horizon, which is why a unit that came in running carries no ramp row there |
 
-$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` walks, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
+$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` steps along, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
 
 ### Objective
 

docs/howto/declare-a-column.md

@@ -14,8 +14,8 @@ what the math does with the column.
 | The column…                                                                                                                           | is declared as                          | because                                                                                                                   |
 | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | is an axis: something is indexed by it, or an aggregation lands terms on it                                                           | a `dimension`                           | its members are the coordinate set every table over it is reindexed onto                                                  |
-| has one value per member of a dimension, or per tuple of several — a generator's bus, a line's two ends, a generator's zone by period | a `relation` with that `key`            | it is a map every operator walks, and its values are checked against the dimensions they name                             |
-| relates members of two dimensions many-to-many, with nothing to weigh — which buses a generator may connect to                        | a bare `relation`, with no `values:`    | `sum` walks it with both ends named, and a bare `where` tests it. Nothing reads it, because there is no one value to read |
+| has one value per member of a dimension, or per tuple of several — a generator's bus, a line's two ends, a generator's zone by period | a `relation` with that `key`            | it is a map every operator reads, and its values are checked against the dimensions they name                             |
+| relates members of two dimensions many-to-many, with nothing to weigh — which buses a generator may connect to                        | a bare `relation`, with no `values:`    | `sum` reads it with both ends named, and a bare `where` tests it. Nothing reads it, because there is no one value to read |
 | relates members of two dimensions many-to-many, with a weight per pair — a link's efficiency to each bus, a cycle's lines             | a `parameter` over both                 | the weight is the data, its row set is the relation, and the aggregation is `sum(w * x, over=a)`                          |
 | is a label set the model only selects on or counts within — a period, a season, a zone                                                | a `dimension`, and a `relation` onto it | its labels are checked, at the cost of one line and one table                                                             |
 | scales terms — a coefficient, a bound, an offset                                                                                      | a `parameter` (`float` or `int`)        | arithmetic is over numbers ([dtype](../reference/language/declarations.md#parameters))                                    |

docs/reference/language/expressions.md

@@ -82,18 +82,18 @@ after a variable. The objective has no name at all.
 
 The dimension set of every expression is known before any data binds:
 
-| Node                             | Dim set                           | Error                                                                                    |
-| -------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
-| number                           | `{}`                              |                                                                                          |
-| parameter / variable             | its `dims`                        |                                                                                          |
-| `-x`, `+x`                       | `dims(x)`                         |                                                                                          |
-| `a + b`, `a * b`, `a / b`        | `dims(a) ∪ dims(b)`               |                                                                                          |
-| `sum(x)`                         | `{}`                              | error if `dims(x)` is already empty                                                      |
-| `sum(x, over=d)`                 | `dims(x) − {d}`                   | error if `d ∉ dims(x)`                                                                   |
-| `sum(x, by=l, over=a, into=b)`   | `(dims(x) − consumed) ∪ produced` | the walk's refusals, under [how a relation is used](relations.md#how-a-relation-is-used) |
-| `at(x, by=l, over=a, into=b)`    | `(dims(x) − consumed) ∪ produced` | the same                                                                                 |
-| `shift(x, along=d, offset=n)`    | `dims(x)`                         | error if `d ∉ dims(x)`                                                                   |
-| `sum_back(x, along=d, window=n)` | `dims(x)`                         | error if `d ∉ dims(x)`                                                                   |
+| Node                             | Dim set                           | Error                                                                            |
+| -------------------------------- | --------------------------------- | -------------------------------------------------------------------------------- |
+| number                           | `{}`                              |                                                                                  |
+| parameter / variable             | its `dims`                        |                                                                                  |
+| `-x`, `+x`                       | `dims(x)`                         |                                                                                  |
+| `a + b`, `a * b`, `a / b`        | `dims(a) ∪ dims(b)`               |                                                                                  |
+| `sum(x)`                         | `{}`                              | error if `dims(x)` is already empty                                              |
+| `sum(x, over=d)`                 | `dims(x) − {d}`                   | error if `d ∉ dims(x)`                                                           |
+| `sum(x, by=l, over=a, into=b)`   | `(dims(x) − consumed) ∪ produced` | the refusals under [how a relation is used](relations.md#how-a-relation-is-used) |
+| `at(x, by=l, over=a, into=b)`    | `(dims(x) − consumed) ∪ produced` | the same                                                                         |
+| `shift(x, along=d, offset=n)`    | `dims(x)`                         | error if `d ∉ dims(x)`                                                           |
+| `sum_back(x, along=d, window=n)` | `dims(x)`                         | error if `d ∉ dims(x)`                                                           |
 
 A binary operator takes the **union** of the two dimension sets, so an outer
 product is allowed. The declaration's own dimensions are its **frame**, and a
@@ -167,7 +167,7 @@ a boolean parameter instead.
 ### `position()`
 
 `position(dim)` is where the row sits along the dimension's own order, which is
-the order `shift` walks. A boundary written with it survives a relabelling of
+the order `shift` steps along. A boundary written with it survives a relabelling of
 the index:
 
 ```yaml

docs/reference/language/operators.md

@@ -21,7 +21,7 @@ in a reported expression, are all of them. A composition of them goes in
 | `shift(array, along=dim, offset=n, edge='wrap')`    | The value `n` positions earlier, counted cyclically, so nothing is vacated                                                                                        |
 | `shift(array, along=dim, offset=n, edge=v)`         | The value `n` positions earlier, with the number `v` standing where the edge was vacated                                                                          |
 | `shift(array, along=dim, offset=p, edge=…)`         | `p` is an integer parameter, so each entity is reached by its own offset                                                                                          |
-| `shift(array, along=dim, offset=n, by=relation, within=c)` | The translation walks inside each group that the relation's column `c` makes. Neighbours, edges and a wrap all belong to that group                        |
+| `shift(array, along=dim, offset=n, by=relation, within=c)` | The translation steps inside each group that the relation's column `c` makes. Neighbours, edges and a wrap all belong to that group                        |
 | `sum_back(array, along=dim, window=n)`              | The sum of the last `n` positions along `dim`, ending at the position being written                                                                               |
 | `sum_back(array, along=dim, window=p)`              | `p` is an integer parameter, so each entity gets its own window length                                                                                            |
 | `sum_back(array, along=dim, window=p, edge='wrap')` | The window reaches around the axis, instead of stopping short at its start                                                                                        |
@@ -78,7 +78,7 @@ is null belongs to no group.
 
 ## `at`
 
-`at(x, by=l, over=a, into=b)` walks the relation the other way. It consumes a
+`at(x, by=l, over=a, into=b)` reads the relation the other way. It consumes a
 value column and produces the key, so it reads one coarse value once for each
 fine label that points at it ([reads](relations.md#aggregates-and-reads)).
 
@@ -172,7 +172,7 @@ previous snapshot's duration.
 
 ### Translation within groups
 
-`by=` partitions the axis the operator walks, so the neighbour of a coordinate
+`by=` partitions the axis the operator steps along, so the neighbour of a coordinate
 is the coordinate before it in its own group. A group can be a season, an
 investment period or a representative day:
 
@@ -197,8 +197,8 @@ Every `edge=` setting then applies one group at a time. Bare, the first
 coordinate of each group is vacated and its row drops. `edge='wrap'` closes each
 group onto its own last coordinate. `edge=v` puts `v` at the edge of each group.
 
-`by=` takes a relation with a key column over the dimension being walked, and
-`within=` names the value columns the group is made of
+`by=` takes a relation with a key column over the dimension being stepped
+along, and `within=` names the value columns the group is made of
 ([partitions](relations.md#partitions)). A coordinate the relation sends
 nowhere is in no group, so its row drops under every `edge=`.
 

docs/reference/notation.md

@@ -51,10 +51,10 @@ relations:
   zone_of: { key: bus, values: zone }
   area_of: { key: bus, values: zone } # a second map into the same set, to compare against
   season_of: { key: snapshot, values: season }
-  gen_zone: { key: [generator, snapshot], values: zone } # a map keyed by two dimensions: a call walks one and joins on the other
+  gen_zone: { key: [generator, snapshot], values: zone } # a map keyed by two dimensions: a call consumes one and joins on the other
   rep_of: { key: snapshot, values: { rep: snapshot } } # a map into its own dimension: the representative snapshot
-  connection: { key: [generator, bus] } # a bare relation, with no value columns: many-to-many, walked only by sum with both ends named
-  gen_bt: { key: generator, values: [bus, technology] } # one table with two value columns, walked to both at once
+  connection: { key: [generator, bus] } # a bare relation, with no value columns: many-to-many, read only by sum with both ends named
+  gen_bt: { key: generator, values: [bus, technology] } # one table with two value columns, read to both at once
 
 parameters:
   p_max: { dims: [generator] }
@@ -131,7 +131,7 @@ $`t \boxminus_{v} k`$ denotes translation with $`v`$ standing where index $`t-k`
 
 $`t \ominus^{\mathrm{relation}(t)} k`$ denotes a translation counted inside the group a relation puts $`t`$ in (`shift(by=relation)`), so a term never crosses out of its own group. The two modifiers take different slots — the group above, the fill below — so $`t \boxminus_{v}^{\mathrm{relation}(t)} k`$ is both at once.
 
-$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` walks, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
+$`\mathrm{pos}(t)`$ denotes where index $`t`$ sits along its dimension's own order — the order `shift` steps along, not the order labels sort in — counted from $`0`$. The index itself stays the coordinate, so $`t`$ compares against labels and $`\mathrm{pos}(t)`$ against positions.
 
 $`\mathrm{pos}_{\mathrm{relation}(t)}(t)`$ counts within the group a relation puts $`t`$ in: the subscript names the map, $`\mathcal{T}_{\mathrm{relation}(t)}`$ is the group it lands in, and that group has a first position of its own.
 
@@ -382,7 +382,7 @@ pullback:
 
 #### `grouped_once`
 
-one table walked to two value columns: the domain carries a condition per column
+one table read to two value columns: the domain carries a condition per column
 
 ```yaml
 grouped_once:
@@ -454,7 +454,7 @@ p_{t,g} \le \mathrm{load}_{t,b} \qquad \forall\, t \in \mathcal{T},\ g \in \math
 
 #### `representative`
 
-a map into its own dimension, walked both ways: the frame is unchanged and the index is primed
+a map into its own dimension, read both ways: the frame is unchanged and the index is primed
 
 ```yaml
 representative:
@@ -468,7 +468,7 @@ representative:
 
 #### `zonal`
 
-a grouping through a two-key map, walked along one key: the condition reads the other, and the row keeps it
+a grouping through a two-key map, consuming one key: the condition reads the other, and the row keeps it
 
 ```yaml
 zonal:
@@ -482,7 +482,7 @@ zonal:
 
 #### `zonal_history`
 
-the same table walked along its other key
+the same table consuming its other key
 
 ```yaml
 zonal_history:
@@ -496,7 +496,7 @@ zonal_history:
 
 #### `zonal_membership`
 
-the same table walked between its two key columns: no value column is read, so the domain asks only that the row is there
+the same table read between its two key columns: no value column is read, so the domain asks only that the row is there
 
 ```yaml
 zonal_membership:

examples/operators/sum_by.yaml

@@ -4,7 +4,7 @@
 
 description: >-
   The membership reduction — `sum(array, by=relation, over=a, into=b)` lands the result on the
-  column the relation is walked to, which is what makes topology data rather than
+  column the relation is read to, which is what makes topology data rather than
   structure.
 
 dimensions:

examples/operators/sum_by_column_lists.yaml

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 description: >-
-  A walk with several columns at each end — `sum(array, by=relation, over=[a, …], into=[b, …])`
+  A call with several columns at each end — `sum(array, by=relation, over=[a, …], into=[b, …])`
   consumes both key columns at once and lands on the product of both value
   columns in one join.
 

examples/operators/sum_by_columns.yaml

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 description: >-
-  A walk that names its ends — `sum(array, by=relation, over=a, into=b)`
+  A call that names its ends — `sum(array, by=relation, over=a, into=b)`
   consumes column `a` and lands on column `b`, and the other key column is
   joined on, so each zone's total is taken per period.