From 04e9b852539f992ea8a910cbcbad7c44b3ddf856 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 16:32:01 +0000 Subject: [PATCH 01/11] feat(language): a dimension lists its members Ports #1014 alone onto #1015's maps, without #1012 or #1013. A dimension takes `over:` and `missing:`; each member is an implied map of the dimension, read as `connection[unit]`, beside the maps the file declares under `maps: connection:`. A declared map named after a member is refused. A bound over a member suggests a constraint through `at`, since a bound does not read through a map here. Co-Authored-By: Fabian Hofmann Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- CHANGELOG.md | 1 + docs/about/limits.md | 2 + docs/howto/declare-a-column.md | 15 +- docs/howto/see-an-expansion.md | 6 +- docs/reference/glossary.md | 16 +- docs/reference/language/dimensions.md | 185 +++++- docs/reference/language/expressions.md | 24 +- docs/reference/language/index.md | 2 +- docs/reference/language/piecewise.md | 22 +- docs/reference/language/relations.md | 8 +- docs/reference/notation.md | 23 + docs/reference/reading.md | 7 + schema/mathspec.schema.json | 30 + src/mathspec/_advising.py | 17 +- src/mathspec/_condition_resolver.py | 26 +- src/mathspec/_dimensions.py | 193 ++++-- src/mathspec/_expression_resolver.py | 61 +- src/mathspec/_lowering.py | 13 +- src/mathspec/_piecewise.py | 4 +- src/mathspec/_renaming.py | 35 +- src/mathspec/_resolution.py | 43 +- src/mathspec/_sos.py | 20 +- src/mathspec/_typesetting/legend.py | 15 +- src/mathspec/_validation.py | 57 +- src/mathspec/errors.py | 14 +- src/mathspec/program.py | 17 +- src/mathspec/spec.py | 72 ++- tests/expand/curve-activity/after.yaml | 2 +- .../expand/curve-adjacency-points/after.yaml | 2 +- tests/expand/curve-adjacency/after.yaml | 2 +- tests/expand/curve-sos2/after.yaml | 2 +- tests/expand/set-lower-bound/after.yaml | 2 +- tests/expand/set-type1/after.yaml | 2 +- tests/expand/set-type2/after.yaml | 2 +- tests/test_dimensions.py | 2 +- tests/test_tuple_dimensions.py | 574 ++++++++++++++++++ tests/typesetting/golden/latex.out | 5 + tests/typesetting/golden/markdown.out | 10 + tests/typesetting/golden/model.yaml | 7 + tests/typesetting/golden/typst.out | 5 + tools/notation.py | 1 + 41 files changed, 1370 insertions(+), 176 deletions(-) create mode 100644 tests/test_tuple_dimensions.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 477e8f4da..7fb91e95b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## Upcoming version +- feat(language): a dimension lists its members ([#0000](https://github.com/energy-models/mathspec/pull/0000)) - feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) - Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a map under `maps:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[map]`, such as `generator[bus]`. - Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[map]`. diff --git a/docs/about/limits.md b/docs/about/limits.md index c066f1012..f40eae114 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -116,6 +116,8 @@ same thing. | A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. | | Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | | A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | +| Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a map](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that map: `at(capacity, by=connection[unit])`. | +| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` a bare relation that lists the tuples. The construct then steps along an ordered member. | | A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | ### Data preparation diff --git a/docs/howto/declare-a-column.md b/docs/howto/declare-a-column.md index ec1241c75..3385d61f0 100644 --- a/docs/howto/declare-a-column.md +++ b/docs/howto/declare-a-column.md @@ -16,13 +16,14 @@ file and the columns of the data you plan to attach to the spec. Use the first row that fits what you do with the column in the spec: -| In the spec you… | For example | So declare it as | -| --------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| index parameters, variables or constraints over the rows the column lists | `generator`, `snapshot` | a [`dimension`](../reference/language/dimensions.md) | -| look up a label of another dimension, one per row | the bus of each generator | a [`map`](../reference/language/relations.md#maps) of `generator` into `bus`, a dimension | -| list which pairs of two dimensions exist, with no value | `connection`, the buses a generator may connect to | a [`relation`](../reference/language/relations.md#relations) with [`missing: absent`](../reference/language/relations.md#missing) | -| use its numbers in an expression or a bound | `cost` per generator, `availability` per generator and snapshot | a [`parameter`](../reference/language/parameters-variables-constraints.md#parameters) over the dimensions that index it | -| test its values in a [condition](../reference/language/expressions.md#conditions) | `fuel`, `is_committable` | a `str` or `bool` parameter | +| In the spec you… | For example | So declare it as | +| -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| index parameters, variables or constraints over the rows the column lists | `generator`, `snapshot` | a [`dimension`](../reference/language/dimensions.md) | +| index parameters, variables or constraints over the pairs of two dimensions that exist | `connection`, the ports of each unit | a `dimension` with [`over:`](../reference/language/dimensions.md#over) | +| look up a label of another dimension, one per row | the bus of each generator | a [`map`](../reference/language/relations.md#maps) of `generator` into `bus`, a dimension | +| list which pairs of two dimensions exist, with no value | `connection`, the buses a generator may connect to | a [`relation`](../reference/language/relations.md#relations) with [`missing: absent`](../reference/language/relations.md#missing) | +| use its numbers in an expression or a bound | `cost` per generator, `availability` per generator and snapshot | a [`parameter`](../reference/language/parameters-variables-constraints.md#parameters) over the dimensions that index it | +| test its values in a [condition](../reference/language/expressions.md#conditions) | `fuel`, `is_committable` | a `str` or `bool` parameter | ## Declare each kind of column diff --git a/docs/howto/see-an-expansion.md b/docs/howto/see-an-expansion.md index e8428c59d..a76ab1db0 100644 --- a/docs/howto/see-an-expansion.md +++ b/docs/howto/see-an-expansion.md @@ -214,7 +214,7 @@ every `sos:` entry. Then write out both with `spec.expand()`: curve_seg: dims: [bp] domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: curve_convexity: @@ -347,7 +347,7 @@ math without the symbol tables. Save the spec in the "Before" tab below as `sos.yaml`, and write it out with `ms.to_spec('sos.yaml').expand()`. In this spec, the `sos:` entry `pick` -requires at most one member of `p` to be non-zero: +requires at most one element of `p` to be non-zero: @@ -405,7 +405,7 @@ requires at most one member of `p` to be non-zero: pick_seg: dims: [g] domain: binary - description: a binary per member, 1 where that member may be nonzero + description: a binary per element, 1 where that element may be nonzero constraints: pick_pick: diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 9d35fc338..5c224d815 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -149,9 +149,10 @@ of a year ([partitions](language/relations.md#partitions)). ## Label -A label is one member of a dimension, such as `wind` in `generator`. The +A label is one element of a dimension, such as `wind` in `generator`. The labels arrive with the data, in the order that `shift`, `sum_back` and -`position()` count along. +`position()` count along. A label of a dimension with +[members](#member) is one tuple of their labels. ## Load @@ -174,6 +175,13 @@ A map gives each row of a dimension or a relation (its generator. A condition or an operator reads it as `subject[map]`, as in `generator[bus]` ([maps](language/relations.md#maps)). +## Member + +A member is a dimension that another dimension lists under `over:`. A label +of the listing dimension combines one label of each member, and a call reads +a member as a map of the dimension, as in `connection[unit]` +([`over`](language/dimensions.md#over)). + ## Missing row A missing row is a coordinate for which the table of a parameter or a relation @@ -268,8 +276,8 @@ costs exists. ## Special ordered set (SOS) A special ordered set (SOS) is an `sos:` entry over one dimension of one -variable. With `type: 1`, at most one member is non-zero. With `type: 2`, at -most two consecutive members are non-zero ([sos](language/piecewise.md#sos)). +variable. With `type: 1`, at most one element is non-zero. With `type: 2`, at +most two consecutive elements are non-zero ([sos](language/piecewise.md#sos)). ## Subject diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index 924af95f4..ebd150545 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -8,7 +8,8 @@ SPDX-License-Identifier: CC-BY-4.0 A **dimension** is a set of labels that entries are indexed over, such as the hours in `snapshot` or the units in `generator`. This page lists the keys a dimension accepts, the closed label lists of -`one_of`, and the rule for the order of a dimension. +`one_of`, the rule for the order of a dimension, and the members that a +dimension lists under `over`. ## `dimensions` @@ -38,12 +39,14 @@ change nothing. mathspec sorts both by name at load, and an entry is indexed over its dimensions in that order. So `dispatch` above prints as $`\mathit{dispatch}_{g,t}`$, and the legend lists `generator` first. -| Key | What it sets | Default | -| ------------- | --------------------------------------------------------------------------- | ------- | -| `dtype` | the type of a label: `float`, `int`, `str` or `datetime` | `str` | -| `one_of` | [the labels a `str` dimension allows](#one_of) | `null` | -| `ordered` | whether the order of the labels is part of the spec ([`ordered`](#ordered)) | `false` | -| `description` | free text, which the typeset legend lists | `null` | +| Key | What it sets | Default | +| ------------- | --------------------------------------------------------------------------- | -------- | +| `dtype` | the type of a label: `float`, `int`, `str` or `datetime` | `str` | +| `one_of` | [the labels a `str` dimension allows](#one_of) | `null` | +| `ordered` | whether the order of the labels is part of the spec ([`ordered`](#ordered)) | `false` | +| `over` | [the dimensions whose labels a label combines](#over) | `null` | +| `missing` | [whether every combination of the members needs a label](#missing) | `absent` | +| `description` | free text, which the typeset legend lists | `null` | The file does not list the labels themselves. They arrive with the data, in the order that the data table lists them. With data attached, a piece of @@ -153,11 +156,179 @@ An `int` dimension is not ordered unless it declares `ordered: true`. An `sos` entry of `type: 1` uses no order, so it needs no `ordered: true`. +A dimension with [`over:`](#over) has no order, so mathspec refuses +`ordered: true` on it. + [`edge='wrap'`](operators.md#shift) makes one `shift` cyclic, so that the first label steps back to the last. `edge='wrap'` does not change the dimension, and the dimension still needs `ordered: true`. +## `over` + +`over` lists the dimensions (the **members**) whose labels a label of the +dimension combines. A label is then one tuple of member labels, such as the +unit `u1` with the port `out`. + +```yaml +dimensions: + unit: { dtype: str } + port: { dtype: str } + bus: { dtype: str } + snapshot: { dtype: int, ordered: true } + connection: { over: [unit, port] } +maps: + connection: + bus: { dim: bus } +parameters: + capacity: { dims: [unit] } + load: { dims: [bus, snapshot] } +variables: + flow: { dims: [connection, snapshot], bounds: { lower: 0 } } +constraints: + limit: + dims: [connection, snapshot] + expression: flow <= at(capacity, by=connection[unit]) + balance: + dims: [bus, snapshot] + expression: sum(flow, over=connection, by=connection[bus]) == load +``` + +`flow` has one column per listed connection and snapshot, and none for a unit +and a port that the data does not list together. `limit` reads the capacity of +the unit of each connection, and `balance` adds each flow to the bus of its +connection. The legend prints the dimension as +$`\mathcal{C} \subseteq \mathcal{P} \times \mathcal{U}`$, and `limit` prints as: + +```math +\mathit{flow}_{c,t} \le \mathrm{capacity}_{\mathrm{unit}(c)} \qquad \forall\, c \in \mathcal{C},\ t \in \mathcal{T} +``` + +`over` takes a list of dimensions, or a mapping of name to dimension where two +members are over one dimension: + +```yaml +dimensions: + region: { dtype: str } + trade: { over: { source: region, target: region } } +``` + +A member in the list form has the name of its dimension. The order of the +members changes nothing, because mathspec sorts them by name at load. + +### The maps of the dimension + +Each member is also a [map](relations.md#maps) of the dimension, named after +the member, with `dim:` the dimension of the member and `missing: refused`. So +`connection` above has the maps `unit` and `port` beside the map `bus` that +the file declares, and a call reads a member as it reads any map: + +| Written | Result | +| ------------------------------------------------- | ----------------------------------------------------------- | +| `at(capacity, by=connection[unit])` | the capacity of the unit of each connection | +| `at(rating, by=connection[unit, port])` | `rating`, a parameter over `unit` and `port`, at each tuple | +| `sum(flow, over=connection, by=connection[port])` | the flows of each port, added over its connections | +| `where: "connection[unit] == 'u1'"` | the connections of the unit `u1` | +| `where: "at(active, by=connection[unit])"` | the connections whose unit is in the condition `active` | + +A fact about a tuple that is not a member, such as the bus of a connection, +is a map that the file declares under `maps: connection:`, as `bus` is above. +mathspec refuses a declared map with the name of a member. With +`maps: { connection: { unit: { dim: unit } } }`, mathspec prints: + +```text +maps: 'connection': map 'unit' has the name of a member of 'connection', which already gives each tuple its label of 'unit'. Read the member as connection[unit], or rename the map. +``` + +### One dimension in every operator + +A dimension with members is one dimension wherever a `dims:` list or an +operator names it. mathspec does not align an entry over a member with an +entry over the dimension. With `flow <= capacity` in `limit` above, mathspec +prints: + +```text +Constraint 'limit': an operand over ['unit'] meets one over 'connection'. 'unit' is a member of 'connection', which is one dimension here. Read the operand at each tuple: at(capacity, by=connection[unit]), or sum flow to the member: sum(flow, over=connection, by=connection[unit]). +``` + +mathspec suggests the lookup through the map of the member, or the sum +of `flow` to the member. The same refusal applies wherever the two operands +meet: in a product, in a sum, and in the objective, as in +`sum(flow * capacity)`. An entry over both, such as a variable over +`[connection, unit]`, loads. + +mathspec refuses the meeting unless the `dims:` of the entry lists both the +dimension and the member. Then the two operands meet as their cross product, +at every pair of a connection and a unit. With +`dims: [connection, unit, snapshot]`, `flow <= capacity` loads, with one row +for each connection, unit and snapshot. Inside a `sum`, a dimension that the +`sum` adds up is not in the `dims:` of the entry, so +`sum(flow * capacity, over=unit)` is refused in that entry too. The objective +and an [assumption](assumptions.md) have no `dims:`, so mathspec refuses +the meeting in each of them. It also refuses the meeting in the `where:` of a +`piecewise:` entry, because mathspec repeats that condition in assumptions. + +A sum over a member is refused the same way. With `sum(flow, over=unit)`, +mathspec prints: + +```text +Constraint 'balance': sum(over=unit) but the expression has only the dims ['connection', 'snapshot']. 'unit' is a member of 'connection', which is one dimension here. Write sum(..., over=connection, by=connection[port]). +``` + +mathspec suggests the sum over the dimension, grouped by the other member. + +A `dims:` list is the domain of an entry, so a tool refuses a data row at a +tuple that the dimension does not list. A +[`where:`](absence.md#where) condition then removes rows of that domain. + +At load, mathspec also refuses each of these, and prints the rewrite: + +| Refused | What you write instead | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| a member that has members of its own | the members themselves, in one list | +| a dimension twice in the list form, as in `over: [region, region]` | the mapping form, with a name for each member | +| a member named after a dimension that it is not over | another name for the member | +| `ordered: true`, `dtype:` or `one_of:` beside `over:` | the key on a member | +| `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` along the dimension | an entry over the members, with `where:` a relation that lists the tuples | +| a comparison of the dimension with a label, as in `connection == 'a'` | a comparison of a member, as in `connection[unit] == 'u1'` | +| a call through a member on an operand over both the dimension and that member | the member summed out of the operand first | + +A set of tuples with an ordered member, such as the periods in which each unit +is active, therefore stays a [bare relation](relations.md) over `unit` and +`period`. An entry over `unit` and `period` uses it as `where: active`, and an +entry over `connection` and `period` reads it as +`where: "at(active, by=connection[unit])"`. + +### `missing` + +`missing:` on a dimension with members sets whether every combination of +member labels needs a label. + +| `missing:` | Result | +| -------------------- | ------------------------------------------------------------------------------------------------------ | +| `absent`, by default | the data lists the tuples that exist, and a combination that it leaves out is not in the dimension | +| `refused` | a tool refuses data that leaves a combination out, so the dimension is the full product of its members | + +With `missing: refused`, the legend prints the dimension with $`=`$ in place of +$`\subseteq`$. mathspec refuses `missing:` on a dimension without `over:`. + +### The data contract + +With data attached, the labels of `connection` are one column whose values +have one field per member, named after the member: `{unit: u1, port: out}`. +The [maps of the members](#the-maps-of-the-dimension) take their labels from +these fields, so a tool reads no column of the table of the dimension for +them. A tool requires three things of the column: + +- Each tuple appears once. +- Every field is a label of its dimension. +- Under `missing: refused`, every combination of member labels appears. + +mathspec declares no type for the tuple, so a tool may store the label in any +form that keeps the fields. + !!! info "See also" + - [Relations and maps](relations.md#maps), for the calls that read a member. + - [choose between a dimension, a relation, a map and a parameter](../../howto/declare-a-column.md) for a column of data. diff --git a/docs/reference/language/expressions.md b/docs/reference/language/expressions.md index eda314a6c..c03a244aa 100644 --- a/docs/reference/language/expressions.md +++ b/docs/reference/language/expressions.md @@ -251,18 +251,18 @@ and never to a constraint of the same name. Before any data is attached, [`to_spec`](../api.md#mathspec.to_spec) works out the dimensions of every expression. Each part of an expression (a node) has a set of dimensions: -| Node | Dimensions of the result | Refused when | -| -------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | -| number | `{}` | | -| parameter / variable | its `dims` | | -| `-x`, `+x` | `dims(x)` | | -| `a + b`, `a * b`, `a / b` | `dims(a) ∪ dims(b)` | | -| `sum(x)` | `{}` | `dims(x)` is already empty | -| `sum(x, over=d)` | `dims(x) − {d}` | `d ∉ dims(x)` | -| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how relations and maps are used](relations.md#how-relations-and-maps-are-used) applies | -| `at(x, by=s[m])` | `(dims(x) − joined) ∪ grouped` | the same refusals apply | -| `shift(x, along=d, offset=n)` | `dims(x)` | `d ∉ dims(x)` | -| `sum_back(x, along=d, window=n)` | `dims(x)` | `d ∉ dims(x)` | +| Node | Dimensions of the result | Refused when | +| -------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| number | `{}` | | +| parameter / variable | its `dims` | | +| `-x`, `+x` | `dims(x)` | | +| `a + b`, `a * b`, `a / b` | `dims(a) ∪ dims(b)` | one side carries a [member](dimensions.md#over) of a dimension the other carries without it, and the `dims:` of the entry does not list both | +| `sum(x)` | `{}` | `dims(x)` is already empty | +| `sum(x, over=d)` | `dims(x) − {d}` | `d ∉ dims(x)` | +| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how relations and maps are used](relations.md#how-relations-and-maps-are-used) applies | +| `at(x, by=s[m])` | `(dims(x) − joined) ∪ grouped` | the same refusals apply | +| `shift(x, along=d, offset=n)` | `dims(x)` | `d ∉ dims(x)` | +| `sum_back(x, along=d, window=n)` | `dims(x)` | `d ∉ dims(x)` | mathspec refuses `sum(p, over=t)` with `p` over `g` alone, and prints: diff --git a/docs/reference/language/index.md b/docs/reference/language/index.md index 12e9c2c51..00c34ec68 100644 --- a/docs/reference/language/index.md +++ b/docs/reference/language/index.md @@ -17,7 +17,7 @@ _entry_, _coordinate_ and _absent_, in one fixed sense. - **[File shape](file.md)** lists the top-level keys of a spec file, and how mathspec reads the YAML. - **[Given, parameters, variables, objective and constraints](parameters-variables-constraints.md)** lists the keys of the data, the decisions, the goal and the rules, and of the `given:` section. -- **[Dimensions](dimensions.md)** lists the keys of a dimension, the set of labels that entries are indexed over. +- **[Dimensions](dimensions.md)** lists the keys of a dimension, the set of labels that entries are indexed over, and how a dimension lists tuples of other dimensions. - **[Relations and maps](relations.md)** lists the keys of a relation, a set of combinations of labels, and of a map, which gives each row one label, and how each operator uses them. - **[Expressions](expressions.md)** defines the grammar of arithmetic and of conditions, and how dimensions combine. - **[Named expressions, conditions and macros](named.md)** lists the keys of the three kinds of named piece of an expression. diff --git a/docs/reference/language/piecewise.md b/docs/reference/language/piecewise.md index af9350a00..ef97deba5 100644 --- a/docs/reference/language/piecewise.md +++ b/docs/reference/language/piecewise.md @@ -9,7 +9,7 @@ This page describes the two kinds of entry that expand into ordinary entries ([**formulations**](../glossary.md#formulation)). They expand before the tool that builds the model (an [engine](../glossary.md#tool)) reads the spec. An `sos:` entry lets only one -member of a variable, or only two neighbouring members, be non-zero. A +element of a variable, or only two neighbouring elements, be non-zero. A `piecewise:` entry ties two or more quantities to one piecewise-linear curve. [`Spec.expand()`](../spec.md#mathspec.spec.Spec.expand) replaces each @@ -28,8 +28,8 @@ an `adjacency` curve adds. The expansion has three properties: ## `sos` -An `sos` entry states a set with few non-zero members (a -**special ordered set**, or SOS). It limits how many members of a variable +An `sos` entry states a set with few non-zero elements (a +**special ordered set**, or SOS). It limits how many elements of a variable along one dimension are non-zero at once. In the spec below, each site builds at most one size: @@ -68,7 +68,7 @@ The entry states one set per site, and each set runs along `size`. | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `variable` | Sets the variable that the set is over. | | `along` | Sets the dimension the set runs along. The entry states one set per [coordinate](../glossary.md#coordinate) of the other dimensions. | -| `type` | `1`: at most one member is non-zero. `2`: at most two members are non-zero, and they are consecutive. | +| `type` | `1`: at most one element is non-zero. `2`: at most two elements are non-zero, and they are consecutive. | A set is over **one** variable, and a variable has **one** set. At load, mathspec refuses a second entry that lists the same variable: @@ -80,16 +80,16 @@ Sos 'again': variable 'build' already carries the set declared by 'pick_one_size mathspec suggests two rewrites: a second variable, or the other restriction written as a constraint. -A member that the `where:` of the variable leaves out -([absent](absence.md#where)) is not in the set. The members follow the order of the `along` dimension. For `type: 2`, that +An element that the `where:` of the variable leaves out +([absent](absence.md#where)) is not in the set. The elements follow the order of the `along` dimension. For `type: 2`, that dimension must be declared [ordered](dimensions.md#ordered), because "consecutive" depends on its order. ### What a set is written out as -`spec.expand('sos')` states the set as one binary variable per member. Under -`type: 1`, the binary of a member admits that member. Under `type: 2`, it -admits that member and the next, so it picks the segment between them. A member +`spec.expand('sos')` states the set as one binary variable per element. Under +`type: 1`, the binary of an element admits that element. Under `type: 2`, it +admits that element and the next, so it picks the segment between them. An element that the binaries do not admit is held at zero, from above and from below. For a set `s` over the variable `x` along `d`, let `admitted` be `s_seg` for `type: 1`, and `s_seg + shift(s_seg, along=d, offset=1, edge=0)` for `type: 2`: @@ -130,11 +130,11 @@ The output of each command contains these two rows: The lower bound of `build` is `0`, so the expansion writes no `pick_one_size_nonzero_below` row. -`upper` and `lower` are the `bounds:` of the member, each a number or a parameter, and for a binary member they are `1` and `0`. mathspec refuses a member +`upper` and `lower` are the `bounds:` of the variable, each a number or a parameter, and for a binary variable they are `1` and `0`. mathspec refuses a variable with no `bounds.lower`, or with no `bounds.upper` and no `domain: binary`, and with `bounds: { upper: max_build }` on `build` it prints: ```text -Sos 'pick_one_size': variable 'build' has no lower bound, and the set expands to rows that hold an unpicked member at zero from below as well as above. Declare bounds.lower, as a number or a parameter. +Sos 'pick_one_size': variable 'build' has no lower bound, and the set expands to rows that hold an unpicked element at zero from below as well as above. Declare bounds.lower, as a number or a parameter. ``` The `_below` row of the expansion needs a lower bound, so that an unpicked diff --git a/docs/reference/language/relations.md b/docs/reference/language/relations.md index 771c3833d..17efc3605 100644 --- a/docs/reference/language/relations.md +++ b/docs/reference/language/relations.md @@ -87,6 +87,11 @@ maps: A map always writes `dim:`, and has no shorter form. A condition or an operator reads a map as `subject[map]`, so `generator[bus]` is the bus of a generator. +A dimension that lists its members under [`over:`](dimensions.md#over) already +has a map per member, named after the member and under `missing: refused`. So +`connection[unit]` is the unit of a connection, and every call on this page +reads a member as it reads a map under `maps:`. + | Key | What it sets | Default | | ------------- | --------------------------------------------------------------------------------- | --------- | | `dim` | required. The dimension whose labels the map gives | | @@ -96,12 +101,13 @@ reads a map as `subject[map]`, so `generator[bus]` is the bus of a generator. A map is named after the dimension it refers to, or after no dimension. The typesetter prints a map as a function from its subject into that dimension, so `generator[bus]` prints as $`\mathrm{bus}: \mathcal{G} \to \mathcal{B}`$. -mathspec refuses a map at load in four cases: +mathspec refuses a map at load in five cases: - The subject is neither a dimension nor a relation. - `dim:` names a relation, or names no dimension. - The map is named after a dimension that it does not refer to. - The map has the name of a column of its subject. +- The map has the name of a member of its subject. With `generator: { period: { dim: zone } }`, mathspec prints: diff --git a/docs/reference/notation.md b/docs/reference/notation.md index ab078981c..bb801d53c 100644 --- a/docs/reference/notation.md +++ b/docs/reference/notation.md @@ -34,6 +34,8 @@ dimensions: season: { dtype: str } technology: { dtype: str } bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through + site: { over: [generator, bus] } # a dimension that lists its members: the legend prints it as a subset of their product + corridor: { over: { from_bus: bus, to_bus: bus }, missing: refused } # members by role, and every combination required: the product itself relations: gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other @@ -56,6 +58,7 @@ parameters: load: { dims: [snapshot, bus] } is_flexible: { dims: [generator], dtype: bool, missing: false } zone_cap: { dims: [zone] } + corridor_cap: { dims: [corridor] } # over a dimension whose two members are over one dimension tech_cap: { dims: [bus, technology], missing: absent } link_eff: { dims: [generator, bus], where: connection, missing: 1 } area_weight: { dims: [bus], where: "bus[area]" } # a map's label as a condition: the buses that have an area @@ -76,8 +79,10 @@ parameters: |---|---| | $`\mathcal{B}`$ | index $`b`$ — `bp` | | $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}`$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{C}`$ | index $`c`$ — `corridor`, $`\mathcal{C} = \mathcal{U} \times \mathcal{U}`$ | | $`\mathcal{G}`$ | index $`g`$ — `generator` with $`\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}`$, `connection` is `absent` where the data has no row | | $`\mathcal{S}`$ | index $`s`$ — `season` with $`\mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | +| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}`$ | | $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | | $`\mathcal{E}`$ | index $`e`$ — `technology` with $`\mathrm{technology}: \mathcal{G} \to \mathcal{E}`$ | | $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | @@ -92,6 +97,7 @@ parameters: | $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{budget}`$ | `budget` (scalar) | +| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{C}`$ | | $`\mathrm{cost}`$ | `cost` over $`\mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{eta}`$ | `eta` over $`\mathcal{G}`$ | | $`\mathrm{growth}`$ | `growth` (scalar) | @@ -123,6 +129,7 @@ parameters: | $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{G} \times \mathcal{T}`$ | | $`p`$ | `p` over $`\mathcal{G} \times \mathcal{T}`$ | | $`\mathit{reserve}`$ | `reserve` (scalar) | +| $`\mathit{site\_out}`$ | `site_out` over $`\mathcal{I} \times \mathcal{T}`$ | | $`\mathit{slack}`$ | `slack` over $`\mathcal{T}`$ | | $`\mathit{spare}`$ | `spare` over $`\mathcal{G}`$ | | $`\mathit{spill}`$ | `spill` over $`\mathcal{T}`$ | @@ -198,6 +205,22 @@ variables: \mathit{slack}_{t} \le 100 \qquad \forall\, t \in \mathcal{T} ``` +#### Variable over a dimension with members + +over a dimension with members, where a parameter of one member holds + +```yaml +variables: + site_out: + dims: [snapshot, site] + where: "at(is_flexible, by=site[generator])" + bounds: { lower: 0 } +``` + +```math +\mathit{site\_out}_{i,t} \ge 0 \qquad \forall\, i \in \mathcal{I},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{\mathrm{generator}(i)} +``` + #### Unbounded variable ```yaml diff --git a/docs/reference/reading.md b/docs/reference/reading.md index 62edcc9ab..e62cb92ea 100644 --- a/docs/reference/reading.md +++ b/docs/reference/reading.md @@ -170,6 +170,13 @@ is one of its `values`. `program.relations[name].missing` is `'refused'` or `'absent'`, and `partial` lists the maps under `missing: absent`. The program of `spec.expand(...)` has the same `missing` values. +The table of a dimension with [members](language/dimensions.md#over) is in +`program.relations` under the name of the dimension, whether or not the file +declares maps of it. It has a map per member, and +`program.relations[name].members` names them. A tool takes the labels of a +member from the fields of each label of the dimension, and reads no column of +the table for them. + A [given](language/parameters-variables-constraints.md#given) parameter is a `GivenParameter` under `program.given.parameters`, and not under `program.parameters`. It has its `dims`, `dtype` and `description`, and no diff --git a/schema/mathspec.schema.json b/schema/mathspec.schema.json index 31392b32f..055b2ba39 100644 --- a/schema/mathspec.schema.json +++ b/schema/mathspec.schema.json @@ -192,6 +192,15 @@ "title": "Dtype", "type": "string" }, + "missing": { + "default": "absent", + "enum": [ + "refused", + "absent" + ], + "title": "Missing", + "type": "string" + }, "one_of": { "anyOf": [ { @@ -213,6 +222,27 @@ "default": false, "title": "Ordered", "type": "boolean" + }, + "over": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Over" } }, "title": "DimensionSpec", diff --git a/src/mathspec/_advising.py b/src/mathspec/_advising.py index 036e683b9..e699ac21d 100644 --- a/src/mathspec/_advising.py +++ b/src/mathspec/_advising.py @@ -91,11 +91,12 @@ def _term_note(name: str) -> str: def _never_an_axis(program: Program) -> list[Advice]: """One piece of advice per dimension nothing reaches. - A dimension a relation has a column over is reached: its members are the - labels that column is checked against, and a ``where`` selects on them, - so it is in use even where nothing is indexed by it. A dimension only a - given entry indexes is reached too: the column exists, in another - file. + A dimension a relation has a column over is reached: its labels are what + that column is checked against, and a ``where`` selects on them, so it is + in use even where nothing is indexed by it. A dimension only a given entry + indexes is reached too: the column exists, in another file. A member of a + dimension is a map the file does not declare, so it is no use of its own; + a reached dimension reaches its members. """ reached: set[str] = set() for entry in ( @@ -109,7 +110,11 @@ def _never_an_axis(program: Program) -> list[Advice]: ): reached.update(entry.dims) reached |= _grouped_axes(program) - reached |= {dim for lk in program.relations.values() for dim in lk.dims} + for lk in program.relations.values(): + declared = [role for role in lk.values if role not in lk.members] + if declared or not lk.members: + reached.update(lk.dim(role) for role in (*lk.key, *declared)) + reached |= {dim for name in reached for _, dim in program.dimensions[name].over} return [ Advice( diff --git a/src/mathspec/_condition_resolver.py b/src/mathspec/_condition_resolver.py index a133446fe..a0987f23a 100644 --- a/src/mathspec/_condition_resolver.py +++ b/src/mathspec/_condition_resolver.py @@ -37,7 +37,7 @@ nodes, ) from mathspec._expression_resolver import ExpressionResolver, condition_compared -from mathspec.errors import DimensionError, LanguageError, SchemaError, did_you_mean, prefixed, unordered +from mathspec.errors import DimensionError, LanguageError, SchemaError, did_you_mean, prefixed from mathspec.program import ( Add, And, @@ -93,17 +93,18 @@ class ConditionResolver: faults reports both. ``self_variable`` is the variable whose own ``where`` is being read, which may not ask whether it exists. A side that is an expression is built by an [`ExpressionResolver`][] over - the same namespace. + the same namespace and ``frame``, the ``dims:`` of the entry. """ ns: Namespace context: str errors: list[str] self_variable: str | None = None + frame: frozenset[str] = frozenset() @property def _expressions(self) -> ExpressionResolver: - return ExpressionResolver(self.ns, self.context, self.errors) + return ExpressionResolver(self.ns, self.context, self.errors, frame=self.frame) def build(self, node: Condition | UnresolvedConditionNode) -> Condition | UnresolvedConditionNode: """One condition node typed, or returned unresolved with its refusal appended.""" @@ -171,10 +172,12 @@ def _bare_name(self, node: NameNode) -> Condition | UnresolvedConditionNode: return node return ParameterDefined(node.name, ns.leaf_dims[node.name]) case 'dimension': + members = ns.spec.dimensions[node.name].members + compared = f"{node.name}[{members[0][0]}] == '...'" if members else f'{node.name} > 0' self.errors.append( f"{context}: '{node.name}' is a dimension, and a bare dimension " f'name is true at every coordinate. ' - f'Remove it, or compare it: where: "{node.name} > 0".' + f'Remove it, or compare it: where: "{compared}".' ) case 'relation': shape = ns.relations[node.name] @@ -248,7 +251,9 @@ def _condition_call(self, node: UnresolvedConditionCallNode) -> Condition | Unre ) return node if self.ns.unordered(along.name): - self.errors.append(unordered(context, f'shift(, along={along.name})', along.name)) + self.errors.append( + self.ns.unordered_refusal(context, f'shift(, along={along.name})', along.name) + ) return node return TranslatedCondition(mask, along.name, int(offset.value), mask.dims) @@ -419,6 +424,8 @@ def _expression_comparison(self, node: UnresolvedComparisonNode) -> ExpressionCo if len(self.errors) > found: return node left, right = sides + if self._expressions.met(left, right): + return node if all(_is_number(side) for side in sides): self.errors.append( f"{context}: '{node.left} {node.op} {node.right}' compares two numbers. Name the parameter one " @@ -456,7 +463,7 @@ def _position( ) return node if ns.unordered(dimension): - self.errors.append(unordered(context, f'position({dimension})', dimension)) + self.errors.append(ns.unordered_refusal(context, f'position({dimension})', dimension)) return node if within is None: return DimensionPosition(dimension, node.op, position) @@ -507,6 +514,13 @@ def _plain_comparison(self, node: UnresolvedComparisonNode, plain: _Plain) -> Co elif kind in ('parameter', 'dimension'): dtype = ns.dtypes[left_name] labelled = left_name if kind == 'dimension' else None + if labelled is not None and (members := ns.spec.dimensions[labelled].members): + self.errors.append( + f"{context}: '{plain.name}' compares a label of '{labelled}', and '{labelled}' lists its members, " + f"so it has no label to compare. In an entry over '{labelled}', compare a member: " + f'{labelled}[{members[0][0]}] {plain.op} {plain.value!r}.' + ) + return node if dtype is not None: typed = self._typed_literal(plain, dtype) if typed is None: diff --git a/src/mathspec/_dimensions.py b/src/mathspec/_dimensions.py index 84eb13c20..f47f96620 100644 --- a/src/mathspec/_dimensions.py +++ b/src/mathspec/_dimensions.py @@ -24,12 +24,14 @@ DimensionPosition, Expression, ExpressionComparison, + ExpressionReference, Join, JoinColumns, JoinedCondition, Mask, ParameterComparison, ParameterDefined, + ParameterReference, Partition, RelationComparison, RelationDefined, @@ -38,7 +40,9 @@ Translate, TranslatedCondition, VariableDefined, + VariableReference, WindowSum, + walk, ) if TYPE_CHECKING: @@ -59,7 +63,7 @@ def check_node(node: Sum | Join | Translate | WindowSum, spec: Spec, context: st """ inner = frozenset(node.operand.dims) if isinstance(node, Sum): - _check_sum(node, inner, context) + _check_sum(node, inner, spec, context) elif isinstance(node, Join): join_dims(node.columns, inner, context, 'the expression') else: @@ -71,7 +75,7 @@ def _not_carried(context: str, call: str, inner: frozenset[str], rewrite: str) - return f'{context}: {call} but the expression has only the dims {sorted(inner)}. {rewrite}.' -def _check_sum(node: Sum, inner: frozenset[str], context: str) -> None: +def _check_sum(node: Sum, inner: frozenset[str], spec: Spec, context: str) -> None: """``sum`` reduces each dim in ``over`` away, so the operand carries every one. The axes a join opens never reach a frame: the sum over the join closes @@ -82,11 +86,34 @@ def _check_sum(node: Sum, inner: frozenset[str], context: str) -> None: return for summed in node.over: if summed.dimension not in inner: + rewrite = _sum_through(summed.dimension, {s.dimension for s in node.over}, inner, spec) raise DimensionError( - _not_carried(context, f'sum(over={summed})', inner, 'Remove the sum, or correct the dimension') + _not_carried( + context, f'sum(over={summed})', inner, rewrite or 'Remove the sum, or correct the dimension' + ) ) +def _sum_through(summed: str, over: set[str], inner: frozenset[str], spec: Spec) -> str | None: + """The rewrite for a sum over *summed*, a member of a dimension the operand carries, or ``None``. + + A dimension with members is one dimension in a sum, so the sum is over it + and groups by the members the call does not sum away. + """ + for name in sorted(inner): + members = spec.dimensions[name].members + dims = [dim for _, dim in members] + if summed not in dims: + continue + kept = [role for role, dim in members if dim not in over] + if len(set(dims)) < len(dims): + by = f', by={name}[]' + else: + by = f', by={name}[{", ".join(kept)}]' if kept else '' + return f"'{summed}' is a member of '{name}', which is one dimension here. Write sum(..., over={name}{by})" + return None + + def join_dims(columns: JoinColumns, inner: frozenset[str], context: str, operand: str) -> frozenset[str]: """The dims *inner* has once *columns* joins it, an expression's or a condition's alike. @@ -101,6 +128,12 @@ def join_dims(columns: JoinColumns, inner: frozenset[str], context: str, operand lookup = columns.one_row_per_group named = columns.dropped if lookup else columns.added call = f'{"at" if lookup else "sum"}(by={columns.name}[{", ".join(named)}])' + if columns.name in inner and (both := sorted(inner & {columns.dim(r) for r in columns.relation.members})): + raise DimensionError( + f"{context}: {call} reads through '{columns.name}', and {operand} carries both '{columns.name}' and " + f'its member {both} (dims {sorted(inner)}). Sum {both} out of the operand first, or declare the ' + f"operand over '{columns.name}' without {both}." + ) if missing := sorted(set(columns.dropped_dims) - inner): if lookup: raise DimensionError( @@ -204,6 +237,100 @@ def _check_named_amount( # --------------------------------------------------------------------------- +def _at_member( + stray: Iterable[str], + frame: frozenset[str], + spec: Spec, + operands: Iterable[Expression] = (), + read: str | None = None, +) -> str | None: + """The rewrite for dims in *stray* that are members of a dimension in *frame*, or ``None`` where one is not. + + An operand over a member does not align with the dimension that lists the + member, so the file reads it at each tuple with ``at``. The rewrite names + *read*, or else the operand in *operands* that is over the members. + """ + wanted = sorted(stray) + for name in sorted(frame): + if (columns := _member_columns(name, wanted, spec)) is None: + continue + read = read or operand_over(operands, wanted, name) + return f'{_one_dimension(wanted, name)}. Read the operand at each tuple: at({read}, by={name}[{columns}])' + return None + + +def _one_dimension(wanted: list[str], name: str) -> str: + """That the dims *wanted* are members of *name*, which an operator reads as one dimension.""" + noun = 'is a member' if len(wanted) == 1 else 'are members' + return f"{', '.join(map(repr, wanted))} {noun} of '{name}', which is one dimension here" + + +def _bound_member( + variable: str, side: str, bound: str, outside: frozenset[str], frame: frozenset[str], spec: Spec +) -> str | None: + """The rewrite for a bound over members of a dimension in *frame*, or ``None`` where one is not. + + A bound is a number or a parameter over the variable's dims, so a + parameter over a member is read at each tuple by a constraint instead. + """ + wanted = sorted(outside) + for name in sorted(frame): + if (columns := _member_columns(name, wanted, spec)) is not None: + sense = '<=' if side == 'upper' else '>=' + return ( + f'{_one_dimension(wanted, name)}. Bound the variable in a constraint over its dims, which reads the ' + f'parameter at each tuple: {variable} {sense} at({bound}, by={name}[{columns}])' + ) + return None + + +def _member_columns(name: str, wanted: list[str], spec: Spec) -> str | None: + """The maps of *name* that its members over the dims *wanted* are, as a call writes them, or ``None`` where one is no member.""" + members = spec.dimensions[name].members + if not set(wanted) <= {dim for _, dim in members}: + return None + return ', '.join(' or '.join(role for role, dim in members if dim == d) for d in wanted) + + +def operand_over(operands: Iterable[Expression], over: Iterable[str], without: str) -> str: + """The outermost name in *operands* over every dim in *over* and not over *without*, or ``...`` where none is. + + A named expression is a name the file wrote, so the walk takes it before + the body it stands for. + """ + wanted, named = set(over), ParameterReference | VariableReference | ExpressionReference + found = (n for n in walk(*operands) if isinstance(n, named) and wanted <= set(n.dims) and without not in n.dims) + return next((n.name for n in found), '...') + + +def check_meeting(left: Expression, right: Expression, spec: Spec, context: str, frame: frozenset[str]) -> None: + """Two operands meet a member against the dimension that lists it only where *frame* declares both. + + A dimension with members is one plain dimension, so an operand over a + member does not align with one over the dimension: the two meet as their + cross product. An entry whose ``dims:`` declares both asks for that + product; anywhere else, a sum or the objective would add it up without a + frame that names it. *frame* is the entry's ``dims:`` less what an + enclosing sum takes away, and empty in the objective. + + Raises: + DimensionError: One operand carries a dimension with members, the + other carries a member of it but not the dimension, and *frame* + lacks one of the two. + """ + for one, other in ((left, right), (right, left)): + for name in sorted(set(one.dims) - set(other.dims)): + members = {dim for _, dim in spec.dimensions[name].members} + stray = sorted((members & set(other.dims)) - set(one.dims)) + if stray and not {name, *stray} <= frame: + summed = operand_over((one,), (name,), stray[0]) + raise DimensionError( + f"{context}: an operand over {stray} meets one over '{name}'. " + f'{_at_member(stray, frozenset({name}), spec, (other,))}, or sum {summed} to the member: ' + f'sum({summed}, over={name}, by={name}[{_member_columns(name, stray, spec)}]).' + ) + + def check_spec(spec: Spec, program: Program) -> None: """Check every entry's dim rules, on the trees *program* holds for *spec*. @@ -211,21 +338,23 @@ def check_spec(spec: Spec, program: Program) -> None: DimensionError: On the first entry that breaks one. """ for pname, parameter in program.parameters.items(): - _check_condition_dims(parameter.where, frozenset(parameter.dims), f"Parameter '{pname}'") + _check_condition_dims(parameter.where, frozenset(parameter.dims), f"Parameter '{pname}'", spec) for vname, vdef in spec.variables.items(): frame = frozenset(vdef.dims) context = f"Variable '{vname}'" - _check_condition_dims(program.variables[vname].where, frame, context) + _check_condition_dims(program.variables[vname].where, frame, context, spec) for side in ('lower', 'upper'): bound = getattr(vdef.bounds, side) if isinstance(bound, str): bdims = frozenset({**spec.parameters, **spec.given.parameters}[bound].dims) - if not bdims <= frame: + if outside := bdims - frame: + rewrite = _bound_member(vname, side, bound, outside, frame, spec) or ( + f"Declare '{bound}' over the variable's dims" + ) raise DimensionError( - f"{context}: bounds.{side} parameter '{bound}' has dims " - f"{sorted(bdims - frame)} outside the variable's dims " - f"{sorted(frame)}. Declare '{bound}' over the variable's dims." + f"{context}: bounds.{side} parameter '{bound}' has dims {sorted(outside)} outside the " + f"variable's dims {sorted(frame)}. {rewrite}." ) for ename, entry in program.expressions.items(): @@ -234,15 +363,15 @@ def check_spec(spec: Spec, program: Program) -> None: continue frame = frozenset(declared.dims) if not isinstance(entry.expression, Cases): - indexed = _check_body_dims(entry.expression, frame, f"Named expression '{ename}'") + indexed = _check_value_dims(entry.expression, frame, f"Named expression '{ename}'", spec, 'body') _check_dims_are_indexed(ename, frame, indexed, 'the expression is not') continue indexed = frozenset[str]() for region, label in zip(entry.expression.regions, [*declared.cases, None], strict=True): context = case_context(ename, label) if label is not None: - _check_condition_dims(region.when, frame, context) - indexed |= _check_value_dims(region.value, frame, context) | frozenset(region.when.dims) + _check_condition_dims(region.when, frame, context, spec) + indexed |= _check_value_dims(region.value, frame, context, spec, 'value') | frozenset(region.when.dims) _check_dims_are_indexed(ename, frame, indexed, 'no case value and no `when:` is') for ename, entry in program.expressions.items(): @@ -258,12 +387,14 @@ def check_spec(spec: Spec, program: Program) -> None: for cname, constraint in program.constraints.items(): frame = frozenset(constraint.dims) context = f"Constraint '{cname}'" - _check_condition_dims(constraint.where, frame, context) + _check_condition_dims(constraint.where, frame, context, spec) got = frozenset((*constraint.lhs.dims, *constraint.rhs.dims)) if got != frame: stray, missing = sorted(got - frame), sorted(frame - got) + operands = (constraint.lhs, constraint.rhs) detail = ( - f'carries dims {stray} that are not in its dims: {sorted(frame)}. Add them to dims:, or sum them out' + f'carries dims {stray} that are not in its dims: {sorted(frame)}. ' + f'{_at_member(stray, frame, spec, operands) or "Add them to dims:, or sum them out"}' if stray else f'does not carry {missing}, which its dims: declares. Remove them from dims:, or use them ' f'in the expression' @@ -281,28 +412,17 @@ def check_spec(spec: Spec, program: Program) -> None: ) -def _check_value_dims(node: Expression, frame: frozenset[str], context: str) -> frozenset[str]: - """A region's value may only carry dims the frame does — the ``otherwise:`` included. +def _check_value_dims(node: Expression, frame: frozenset[str], context: str, spec: Spec, noun: str) -> frozenset[str]: + """A named expression's body, or a region's value, carries only dims its ``dims:`` gives; those it carries come back. A wider one would give the quantity dims its entry does not, which is the second answer a ``dims:`` exists to avoid. """ got = frozenset(node.dims) - if not got <= frame: - raise DimensionError( - f'{context}: the value carries dims {sorted(got - frame)} outside the dims: ' - f'{sorted(frame)}. Add them to dims:, or take them out of the value.' - ) - return got - - -def _check_body_dims(node: Expression, frame: frozenset[str], context: str) -> frozenset[str]: - """A plain entry's expression is indexed only over dims its ``dims:`` gives; the dims it is indexed over come back.""" - got = frozenset(node.dims) - if not got <= frame: + if stray := sorted(got - frame): + rewrite = _at_member(stray, frame, spec, (node,)) or f'Add them to dims:, or take them out of the {noun}' raise DimensionError( - f'{context}: the body carries dims {sorted(got - frame)} outside the dims: {sorted(frame)}. ' - f'Add them to dims:, or take them out of the body.' + f'{context}: the {noun} carries dims {stray} outside the dims: {sorted(frame)}. {rewrite}.' ) return got @@ -323,11 +443,7 @@ def _check_dims_are_indexed(name: str, declared: frozenset[str], indexed: frozen ) -def _check_condition_dims( - mask: Mask | None, - frame: frozenset[str], - context: str, -) -> None: +def _check_condition_dims(mask: Mask | None, frame: frozenset[str], context: str, spec: Spec) -> None: """A condition may only test dims the frame carries; reducing an outside dim to fit would fail open. The refusal names the leaf that left the frame, reading its dims as @@ -360,7 +476,10 @@ def _check_condition_dims( leaf = f"a condition read through '{atom.columns.name}'" case _: assert_never(atom) + read = atom.name if isinstance(atom, ParameterDefined | ParameterComparison | VariableDefined) else None + rewrite = ( + _at_member(outside, frame, spec, read=read) or 'Add them to dims:, or test a name over the declared dims' + ) raise DimensionError( - f'{context}: {leaf} reads dims {outside} outside the declared dims {sorted(frame)}. ' - f'Add them to dims:, or test a name over the declared dims.' + f'{context}: {leaf} reads dims {outside} outside the declared dims {sorted(frame)}. {rewrite}.' ) diff --git a/src/mathspec/_expression_resolver.py b/src/mathspec/_expression_resolver.py index cd4e9a8e6..27232ed16 100644 --- a/src/mathspec/_expression_resolver.py +++ b/src/mathspec/_expression_resolver.py @@ -12,10 +12,10 @@ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, replace from typing import TYPE_CHECKING, assert_never, cast -from mathspec._dimensions import check_node, joined, sorted_dims +from mathspec._dimensions import check_meeting, check_node, joined, operand_over, sorted_dims from mathspec._expression_parser import ( MAX_DEPTH, ArithmeticNode, @@ -40,7 +40,7 @@ edge_error, unknown_operator_message, ) -from mathspec.errors import DimensionError, SchemaError, did_you_mean, unordered +from mathspec.errors import DimensionError, SchemaError, did_you_mean from mathspec.program import ( Add, Axis, @@ -84,13 +84,16 @@ class ExpressionResolver: appended to ``errors``; every sibling is still read, so an entry with two faults reports both. ``formals`` are a macro template's formals: a formal has no kind until a call site binds it, so a node one stands - under is ``None`` with nothing appended. + under is ``None`` with nothing appended. ``frame`` is the ``dims:`` of + the entry, less the dims an enclosing sum adds up, which is where a + member may meet the dimension that lists it. """ ns: Namespace context: str errors: list[str] formals: frozenset[str] = frozenset() + frame: frozenset[str] = frozenset() def _formal(self, value: ArithmeticNode) -> bool: """Whether *value* is a formal, left for the call site to bind.""" @@ -155,7 +158,7 @@ def arith(self, node: ArithmeticNode) -> Expression | None: def _binary(self, node: BinaryOperatorNode) -> Expression | None: """A subtraction is an addition of the negation, so a program has one additive node.""" left, right = self.arith(node.left), self.arith(node.right) - if left is None or right is None: + if left is None or right is None or self.met(left, right): return None dims = sorted_dims(left.dims, right.dims) match node.op: @@ -172,6 +175,15 @@ def _binary(self, node: BinaryOperatorNode) -> Expression | None: case _: assert_never(node.op) + def met(self, left: Expression, right: Expression) -> bool: + """Whether *left* and *right* meet a member against the dimension that lists it, the refusal appended.""" + try: + check_meeting(left, right, self.ns.spec, self.context, self.frame) + except DimensionError as e: + self.errors.append(self.ns.refused_dims(e)) + return True + return False + def _name(self, node: NameNode) -> Expression | None: """A bare name as the variable, parameter or named expression it declares; a dimension or relation is not a value. @@ -233,7 +245,7 @@ def _call(self, node: FunctionCallNode) -> Expression | None: self.errors.append(f'{self.context}: {shape_error}') if node.name == 'dual': return None if shape_error is not None else self._dual(node) - args = [self.arith(a) for a in node.args] + args = [self._inside(node).arith(a) for a in node.args] along: str | None = None over: tuple[str, ...] | None = None amounts: dict[str, int | str | None] = {} @@ -274,6 +286,13 @@ def _call(self, node: FunctionCallNode) -> Expression | None: return None return self._translation(node.name, operand, along, amounts, edge, partition) + def _inside(self, node: FunctionCallNode) -> ExpressionResolver: + """The resolver for the operands of *node*: inside a sum, a dim it sums away is no longer the entry's own.""" + if node.name != 'sum': + return self + over = node.kwargs.get('over') + return replace(self, frame=frozenset() if over is None else self.frame - set(names_in(over))) + def _sum(self, operand: Expression, over: tuple[str, ...] | None, columns: ColumnsNode | None) -> Expression | None: """A plain sum over the dims *over* names, or a sum through a relation, grouped by *columns*. @@ -286,7 +305,7 @@ def _sum(self, operand: Expression, over: tuple[str, ...] | None, columns: Colum return self._bare_sum(operand) return self._summed(operand, tuple(Axis(d) for d in over)) assert over is not None, 'the call shape requires over= beside by=' - grouping = self._grouping(columns, over) + grouping = self._grouping(columns, over, operand) if grouping is None: return None join, plain = grouping @@ -329,7 +348,7 @@ def _translation( ) -> Expression | None: """``shift`` or ``sum_back`` from its read arguments, or ``None`` with the refusal appended.""" if self.ns.unordered(along): - self.errors.append(unordered(self.context, f'{operator}(along={along})', along)) + self.errors.append(self.ns.unordered_refusal(self.context, f'{operator}(along={along})', along)) return None wrap, fill = edge if edge is not None else (False, None) if operator == 'shift': @@ -576,7 +595,9 @@ def _not_columns(self, value: ArithmeticNode, operator: str, key: str) -> str: f'{context}: {operator}({key}=...) takes columns of one subject. Write subject[map] or subject[map, ...].' ) - def _grouping(self, columns: ColumnsNode, over: tuple[str, ...]) -> tuple[JoinColumns, tuple[str, ...]] | None: + def _grouping( + self, columns: ColumnsNode, over: tuple[str, ...], operand: Expression + ) -> tuple[JoinColumns, tuple[str, ...]] | None: """How ``sum(x, over=..., by=subject[...])`` joins the relation, and the dims it sums away with no column. A name in *over* is a column of the relation where it has one, and a @@ -598,10 +619,27 @@ def _grouping(self, columns: ColumnsNode, over: tuple[str, ...]) -> tuple[JoinCo ) return None if not from_roles: + listing = [ + f"{n!r} is a member of '{r}', which is one dimension here, so write over={r}" + for n in plain + for r in shape.roles + if n in {dim for _, dim in ns.spec.dimensions[shape.dim(r)].members} + ] self.errors.append( f"{self.context}: {call}: over={shown(over)} names no column of '{name}', so the sum reads nothing " f"through '{name}'. Name in over= the column that the operand is joined on: " - f'{_columns_over(shape, plain)}.' + f'{listing[0] if listing else _columns_over(shape, plain)}.' + ) + return None + if set(from_roles) & set(shape.members) and name not in (*from_roles, *into_roles): + if name in operand.dims: + rewrite = f'sum(..., over={name}, by={columns})' + else: + read = operand_over((operand,), (shape.dim(r) for r in from_roles), name) + rewrite = f'sum(at({read}, by={name}[{", ".join(from_roles)}]), over={name}, by={columns})' + self.errors.append( + f"{self.context}: {call}: over={shown(from_roles)} names a member of '{name}', which is one " + f'dimension here. Write {rewrite}.' ) return None join = self._checked_join(name, call, from_roles, into_roles) @@ -675,6 +713,9 @@ def partition(self, columns: ColumnsNode, operator: str, along_dim: str) -> Part name, within_roles = columns.relation, columns.columns shape = self.ns.relations[name] call = f'{operator}(within={columns})' + if shape.members: + self.errors.append(self.ns.unordered_refusal(context, call, name)) + return None if not shape.values: self.errors.append( f"{context}: {call}: '{name}' has no map, so it makes no groups. Declare the group as a map of " diff --git a/src/mathspec/_lowering.py b/src/mathspec/_lowering.py index 3bb1cd912..521a98608 100644 --- a/src/mathspec/_lowering.py +++ b/src/mathspec/_lowering.py @@ -149,7 +149,9 @@ def lower(spec: Spec) -> Program: variables = {} for vname, vdef in spec.variables.items(): - where = resolve_condition_text(vdef.where, ns, f"Variable '{vname}'", errors, self_variable=vname) + where = resolve_condition_text( + vdef.where, ns, f"Variable '{vname}'", errors, self_variable=vname, frame=vdef.dims + ) if where is not None and (refusal := self_existence(where, vname, f"Variable '{vname}'")) is not None: errors.append(refusal) if vdef.domain == 'binary': @@ -169,8 +171,8 @@ def lower(spec: Spec) -> Program: constraints: dict[str, Constraint] = {} for cname, cdef in spec.constraints.items(): context = f"Constraint '{cname}'" - where = resolve_condition_text(cdef.where, ns, context, errors) - if (sides := resolve_constraint_text(cdef.expression, ns, context, errors)) is not None: + where = resolve_condition_text(cdef.where, ns, context, errors, frame=cdef.dims) + if (sides := resolve_constraint_text(cdef.expression, ns, context, errors, frame=cdef.dims)) is not None: lhs, sense, rhs = sides constraints[cname] = Constraint(cdef.dims, lhs, sense, rhs, mask_of(where), description=cdef.description) @@ -230,7 +232,7 @@ def lower(spec: Spec) -> Program: constraints=constraints, objective=objective, dimensions={ - name: Dimension(dtype=ddef.dtype, one_of=ddef.one_of, ordered=ddef.ordered, description=ddef.description) + name: Dimension(ddef.dtype, ddef.one_of, ddef.ordered, ddef.description, ddef.members, ddef.missing) for name, ddef in spec.dimensions.items() }, relations=ns.relations, @@ -395,7 +397,8 @@ def _parameter_masks(spec: Spec, ns: Namespace, errors: list[str]) -> dict[str, masks: dict[str, Mask | None] = {} for pname in sorted(masked): context = f"Parameter '{pname}'" - mask = masks[pname] = mask_of(resolve_condition_text(spec.parameters[pname].where, ns, context, errors)) + pdef = spec.parameters[pname] + mask = masks[pname] = mask_of(resolve_condition_text(pdef.where, ns, context, errors, frame=pdef.dims)) if mask is None: continue errors.extend( diff --git a/src/mathspec/_piecewise.py b/src/mathspec/_piecewise.py index 5b3ac8602..160de201f 100644 --- a/src/mathspec/_piecewise.py +++ b/src/mathspec/_piecewise.py @@ -498,7 +498,9 @@ def resolve_links(name: str, pw: PiecewiseSpec, ns: Namespace, errors: list[str] A link is read affinely, so it is held to degree 1 where it is read. """ links = [ - resolve_expression_text(link.expression, ns, f"piecewise '{name}' link '{key}'", errors, ceiling=1) + resolve_expression_text( + link.expression, ns, f"piecewise '{name}' link '{key}'", errors, ceiling=1, frame=pw.dims + ) for key, link in pw.links.items() ] if any(link is None for link in links): diff --git a/src/mathspec/_renaming.py b/src/mathspec/_renaming.py index df2136d9b..c3ceb3a18 100644 --- a/src/mathspec/_renaming.py +++ b/src/mathspec/_renaming.py @@ -108,8 +108,8 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: A token in text is renamed wherever it has the spelling, so a new name that is the argument of a macro whose template uses the old name, or a name that - is a map or a relation column named after something else, would change an - expression without a refusal. + is a map, a relation column or a member named after something else, would + change an expression without a refusal. """ for old in names: if old not in declared: @@ -119,17 +119,26 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: ) raise LanguageError(msg) changed = {old: new for old, new in names.items() if new is not None and new != old} - columns = { - column: f"a column of the relation '{relation}'" - for relation, entry in spec.relations.items() - for column, dimension in entry.pairs - if column != dimension - } | { - name: f"a map of '{subject}'" - for subject, maps in spec.maps.items() - for name, entry in maps.items() - if name != entry.dim - } + columns = ( + { + column: f"a column of the relation '{relation}'" + for relation, entry in spec.relations.items() + for column, dimension in entry.pairs + if column != dimension + } + | { + name: f"a map of '{subject}'" + for subject, maps in spec.maps.items() + for name, entry in maps.items() + if name != entry.dim + } + | { + role: f"a member of the dimension '{name}'" + for name, entry in spec.dimensions.items() + for role, dimension in entry.members + if role != dimension + } + ) for old, new in changed.items(): for macro, entry in spec.macros.items(): if new in (*entry.args, *entry.kwargs) and old in _names_in(entry.template): diff --git a/src/mathspec/_resolution.py b/src/mathspec/_resolution.py index 490d0c423..75183048c 100644 --- a/src/mathspec/_resolution.py +++ b/src/mathspec/_resolution.py @@ -35,7 +35,7 @@ nodes, ) from mathspec._expression_resolver import ExpressionResolver -from mathspec.errors import DimensionError, LanguageError, SchemaError, case_context, prefixed +from mathspec.errors import DimensionError, LanguageError, SchemaError, case_context, prefixed, unordered from mathspec.program import ( BooleanLiteral, Cases, @@ -254,6 +254,10 @@ def unordered(self, name: str) -> bool: """Whether the declared dimension *name* is one whose order the file does not declare part of the model.""" return not self.spec.dimensions[name].ordered + def unordered_refusal(self, context: str, construct: str, name: str) -> str: + """The refusal for *construct* reading the order of the dimension *name*, with the rewrite its entry allows.""" + return unordered(context, construct, name, self.spec.dimensions[name].members) + def kind(self, name: str) -> NameKind | None: """What *name* was declared as, or ``None`` where the file declares it nowhere.""" if name in self.variables: @@ -340,9 +344,14 @@ def resolve_expression( errors: list[str], *, formals: frozenset[str] = frozenset(), + frame: Iterable[str] = (), ) -> Expression | None: """Build the program tree *node* stands for, checking every name and operator call shape on the way. + *frame* is the ``dims:`` of the entry *node* belongs to: where it declares + a dimension with members and a member, an operand over the member meets + one over the dimension as their cross product. + Returns: The tree, or ``None`` once anything failed — appending to *errors* rather than raising, so a caller collecting problems across a whole @@ -353,7 +362,7 @@ def resolve_expression( """ before = len(errors) - resolved = ExpressionResolver(ns, context, errors, formals=formals).build(node) + resolved = ExpressionResolver(ns, context, errors, formals=formals, frame=frozenset(frame)).build(node) return None if len(errors) > before else resolved @@ -363,8 +372,10 @@ def resolve_condition( context: str, errors: list[str], self_variable: str | None = None, + *, + frame: Iterable[str] = (), ) -> Condition | None: - """Rewrite a parsed where AST into typed conditions, folded as [`Mask`][] folds. + """Rewrite a parsed where AST into typed conditions, folded as [`Mask`][] folds, *frame* read as [`resolve_expression`][] reads it. Returns: The typed tree — a mask admitting every row or none comes back as the @@ -372,7 +383,7 @@ def resolve_condition( problems appended to *errors*. """ before = len(errors) - resolved = ConditionResolver(ns, context, errors, self_variable).build(node) + resolved = ConditionResolver(ns, context, errors, self_variable, frozenset(frame)).build(node) return None if len(errors) > before else Mask(cast('Condition', resolved)).root @@ -382,6 +393,8 @@ def resolve_condition_text( context: str, errors: list[str], self_variable: str | None = None, + *, + frame: Iterable[str] = (), ) -> Condition | None: """Parse and resolve one condition as [`resolve_condition`][] does, a parse failure appended to *errors*. @@ -395,11 +408,11 @@ def resolve_condition_text( except ValueError as e: errors.append(f'{context}: {e}') return None - return resolve_condition(node, ns, context, errors, self_variable) + return resolve_condition(node, ns, context, errors, self_variable, frame=frame) def resolve_expression_text( - text: str, ns: Namespace, context: str, errors: list[str], *, ceiling: int | None + text: str, ns: Namespace, context: str, errors: list[str], *, ceiling: int | None, frame: Iterable[str] = () ) -> Expression | None: """Parse, expand, resolve and degree-check one expression string that stands for a value. @@ -420,14 +433,14 @@ def resolve_expression_text( if isinstance(ast, ComparisonNode): errors.append(f'{context}: the expression holds a comparison operator.\nGot: {text!r}\nRemove the comparison.') return None - resolved = resolve_expression(ast, ns, context, errors) + resolved = resolve_expression(ast, ns, context, errors, frame=frame) if resolved is None or ceiling is None: return resolved return None if _over_the_ceiling(resolved, context, errors, ceiling=ceiling) else resolved def resolve_constraint_text( - text: str, ns: Namespace, context: str, errors: list[str] + text: str, ns: Namespace, context: str, errors: list[str], *, frame: Iterable[str] = () ) -> tuple[Expression, Sense, Expression] | None: """Parse, expand, resolve and degree-check one constraint string: exactly one comparison, a variable on a side (#1171). @@ -444,9 +457,9 @@ def resolve_constraint_text( ) return None found = len(errors) - resolver = ExpressionResolver(ns, context, errors) + resolver = ExpressionResolver(ns, context, errors, frame=frozenset(frame)) left, right = resolver.build(ast.left), resolver.build(ast.right) - if len(errors) > found or left is None or right is None: + if len(errors) > found or left is None or right is None or resolver.met(left, right): return None if any(_over_the_ceiling(side, context, errors, ceiling=2) for side in (left, right)): return None @@ -488,10 +501,10 @@ def _named(name: str, entry: ExpressionSpec, ns: Namespace, errors: list[str]) - regions rather than working out which one is left; the language proved the rest apart, so the regions are disjoint and total. """ - context = f"Named expression '{name}'" + context, frame = f"Named expression '{name}'", entry.dims or () if not entry.cases: assert entry.expression is not None - body = resolve_expression_text(entry.expression, ns, context, errors, ceiling=None) + body = resolve_expression_text(entry.expression, ns, context, errors, ceiling=None, frame=frame) return None if body is None else ExpressionReference(name, body, dims=body.dims) found = len(errors) @@ -499,16 +512,16 @@ def _named(name: str, entry: ExpressionSpec, ns: Namespace, errors: list[str]) - masks: dict[str, Condition] = {} for case_name, case in entry.cases.items(): arm_context = case_context(name, case_name) - when = resolve_condition_text(case.when, ns, arm_context, errors) + when = resolve_condition_text(case.when, ns, arm_context, errors, frame=frame) if isinstance(when, BooleanLiteral): errors.append(_constant_arm(arm_context, value=when.value)) elif when is not None: masks[case_name] = when - value = resolve_expression_text(case.expression, ns, arm_context, errors, ceiling=None) + value = resolve_expression_text(case.expression, ns, arm_context, errors, ceiling=None, frame=frame) if when is not None and value is not None: regions.append(Region(Mask(when), value)) assert entry.otherwise is not None - fallback = resolve_expression_text(entry.otherwise, ns, case_context(name, None), errors, ceiling=None) + fallback = resolve_expression_text(entry.otherwise, ns, case_context(name, None), errors, ceiling=None, frame=frame) if len(errors) > found or fallback is None: return None errors.extend(f'{context}: {problem}' for problem in overlapping(masks, ns.dtypes, ns.defaults)) diff --git a/src/mathspec/_sos.py b/src/mathspec/_sos.py index bef1cfa97..f425509de 100644 --- a/src/mathspec/_sos.py +++ b/src/mathspec/_sos.py @@ -6,9 +6,9 @@ A set becomes ordinary entries under names prefixed with the entry's own, the way a ``piecewise:`` entry becomes weights and rows; what it emits is -tabled in ``docs/reference/language/piecewise.md``. An unpicked member is held +tabled in ``docs/reference/language/piecewise.md``. An unpicked element is held at zero from both sides, so the rewrite states the same feasible set whatever -sign the member takes — what it needs is a coefficient on each side, which a +sign the element takes — what it needs is a coefficient on each side, which a spec declaring a set without is refused at load for ([`mathspec.spec.Spec`][] validates it) rather than here. """ @@ -27,13 +27,13 @@ def coefficients(domain: str, lower: float | str | None, upper: float | str | None) -> Coefficients: - """What a member's two linking rows multiply its binary by, ``None`` on a side the spec leaves open. + """What an element's two linking rows multiply its binary by, ``None`` on a side the spec leaves open. The 0 and 1 a binary's domain fixes, which no ``bounds:`` carries; - otherwise the member's own declared bounds, each a number or the name of a + otherwise the element's own declared bounds, each a number or the name of a parameter. A parameter is a coefficient like any other: it is what the row multiplies by, and no rewrite needs to know its value. Nothing else is a - coefficient: a number below the bound would cap a picked member the set + coefficient: a number below the bound would cap a picked element the set does not cap, and one above it is a looser row than the bound already states. """ @@ -47,9 +47,9 @@ class Emitted: """Every name one set's expansion writes, spelled once for the emitter and the collision check. The linking row is named after what it says, which the two orders do not - share: order 2 admits a member in either half of one segment, and order 1 + share: order 2 admits an element in either half of one segment, and order 1 admits it alone. ``below`` is the same row from underneath, written only - where the member may be nonzero below zero. + where the element may be nonzero below zero. """ seg: str @@ -74,8 +74,8 @@ def by_kind(self) -> tuple[tuple[str, tuple[str, ...]], ...]: _SEGMENTS = { - 1: 'a binary per member, 1 where that member may be nonzero', - 2: 'a binary per segment, 1 where the two members it spans may be nonzero', + 1: 'a binary per element, 1 where that element may be nonzero', + 2: 'a binary per segment, 1 where the two elements it spans may be nonzero', } @@ -127,7 +127,7 @@ def emit(raw: dict[str, object], name: str) -> None: def _scaled(factor: float | str, picked: str) -> str: - """The binaries a member is admitted by, times *factor*. + """The binaries an element is admitted by, times *factor*. A coefficient of 1 is left out. It is the common one — a weight and a binary are both bounded by 1 — and ``x <= 1 * (seg)`` is a factor every reader of diff --git a/src/mathspec/_typesetting/legend.py b/src/mathspec/_typesetting/legend.py index e99c0f5a6..b12868deb 100644 --- a/src/mathspec/_typesetting/legend.py +++ b/src/mathspec/_typesetting/legend.py @@ -264,7 +264,8 @@ def _signatures(self, name: str, lk: Relation, dim: str) -> list[str]: A relation prints as ``connection ⊆ P x U`` under each of its dimensions. A map prints as ``carrier: U → C`` under its subject's dimensions and the one it refers to, its subject a set symbol for a - dimension and the relation's name for a relation. + dimension and the relation's name for a relation. A member is no + declared map, and prints as the product its dimension is a subset of. """ own = {lk.dim(r) for r in lk.key} dimension = name in self.program.dimensions and lk.key == (name,) @@ -276,25 +277,29 @@ def _signatures(self, name: str, lk: Relation, dim: str) -> list[str]: signatures.extend( f'{self.format.upright(role)}: {subject} {self._op("maps_to")} {self.symbols.set[lk.dim(role)]}' for role in lk.values - if dim in own or lk.dim(role) == dim + if role not in lk.members and (dim in own or lk.dim(role) == dim) ) return signatures def _coords(self, dim: str, noticed: Noticed) -> str: - """The dimension's carried structure: the labels its ``one_of`` allows, each relation over it and map from or into it, and each that may leave a row out. + """The dimension's carried structure: the labels its ``one_of`` allows, the product of its members, each relation over it and map from or into it, and each that may leave a row out. The dtype is named only where an equation compared the index against a number, the one place "position 3" and "the coordinate 3" are both readings of a line. """ + dimensions = self.program.dimensions carried = self.program.relations_of(dim) clauses = [] if dim in noticed.numeric_coordinates: clauses.append(f' ({self.format.mono(self.program.dimensions[dim].dtype)} coordinates)') if (labels := self.program.dimensions[dim].one_of) is not None: clauses.append(f' (labels {", ".join(self.format.mono(m) for m in labels)})') - if carried: - signatures = [part for c, lk in carried.items() for part in self._signatures(c, lk, dim)] + if members := dimensions[dim].over: + product = self.format.joined([self.symbols.set[d] for _, d in members], self._op('times')) + holds = self._op('subset_of' if dimensions[dim].missing == 'absent' else 'equal') + clauses.append(f', {self.format.math(f"{self.symbols.set[dim]} {holds} {product}")}') + if signatures := [part for c, lk in carried.items() for part in self._signatures(c, lk, dim)]: clauses.append(f' with {self.format.math(self.format.joined(signatures, ""))}') own = {c: {lk.dim(r) for r in lk.key} for c, lk in carried.items()} clauses.extend( diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index d23cdd4f2..3a2fa8304 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -109,6 +109,7 @@ def reference_errors(spec: Spec) -> list[str]: return [ *_name_collisions(spec), *_frame_dimensions(spec), + *_members(spec), *_relation_targets(spec), *_map_targets(spec), *_bound_names(spec), @@ -198,6 +199,40 @@ def _frame_dimensions(spec: Spec) -> Iterator[str]: ) +def _members(spec: Spec) -> Iterator[str]: + """A dimension lists plain, declared dimensions as its members, each once or under a role of its own. + + Each member is a map of the dimension named after its role, so a role is + held to the rule of a map: it is named after its own dimension or after + none. + """ + for name, entry in spec.dimensions.items(): + dims = [dim for _, dim in entry.members] + yield from ( + undeclared_dimension('Dimension', name, d, spec) for d in dict.fromkeys(dims) if d not in spec.dimensions + ) + for d in dict.fromkeys(dims): + if d in spec.dimensions and (inner := spec.dimensions[d].members): + flat = sorted({*dims, *(dim for _, dim in inner)} - {d, name}) + yield ( + f"Dimension '{name}' lists '{d}' under 'over:', and '{d}' has members of its own. A member is " + f'a dimension without `over:`. List the members themselves: over: {flat}.' + ) + if not isinstance(entry.over, Mapping): + yield from ( + f"Dimension '{name}' lists '{d}' twice under 'over:'. Give the two members roles: " + f'over: {{{d}0: {d}, {d}1: {d}}}.' + for d, count in Counter(dims).items() + if count > 1 + ) + yield from ( + f"Dimension '{name}' names member '{role}' after dimension '{role}', but the member is over " + f"'{dim}'. Rename the member after what it holds." + for role, dim in entry.members + if role in spec.dimensions and role != dim + ) + + def _relation_targets(spec: Spec) -> Iterator[str]: """A relation has at least two columns, over declared dimensions, each named once.""" for lname, lk in spec.relations.items(): @@ -236,6 +271,7 @@ def _map_targets(spec: Spec) -> Iterator[str]: """ for subject, maps in spec.maps.items(): head = f"maps: '{subject}'" + members = dict(spec.dimensions[subject].members if subject in spec.dimensions else ()) if subject in spec.relations: pairs = spec.relations[subject].pairs if twice := [d for d, count in Counter(d for _, d in pairs).items() if count > 1]: @@ -258,7 +294,12 @@ def _map_targets(spec: Spec) -> Iterator[str]: f'{head}: {role!r} is not a name. Start it with a letter or an underscore, then use only ' f'letters, digits or underscores.' ) - if role in dict(pairs): + if role in members: + yield ( + f"{head}: map '{role}' has the name of a member of '{subject}', which already gives each tuple " + f"its label of '{members[role]}'. Read the member as {subject}[{role}], or rename the map." + ) + elif role in dict(pairs): yield ( f"{head}: map '{role}' has the name of a column of '{subject}', which holds the row, not a " f'label of it. Rename the map after what it holds.' @@ -324,7 +365,7 @@ def _sos_shapes(spec: Spec) -> Iterator[str]: f'to one of these dims.' ) elif entry.type == 2 and not spec.dimensions[entry.along].ordered: - yield unordered(context, f'type: 2 along {entry.along}', entry.along) + yield unordered(context, f'type: 2 along {entry.along}', entry.along, spec.dimensions[entry.along].members) elif entry.variable in claimed: yield ( f"{context}: variable '{entry.variable}' already carries the set declared by " @@ -336,10 +377,10 @@ def _sos_shapes(spec: Spec) -> Iterator[str]: def _sos_bounds(spec: Spec) -> Iterator[str]: - """A set states what the binaries it expands to state: each side of a member carries a coefficient. + """A set states what the binaries it expands to state: each side of an element carries a coefficient. - The rewrite holds an unpicked member at zero from both sides, so a side - the spec leaves open leaves the member free of it. Either coefficient + The rewrite holds an unpicked element at zero from both sides, so a side + the spec leaves open leaves the element free of it. Either coefficient may be a parameter, because a row multiplies by it rather than reading it. Decided here rather than where the rewrite runs, so a set the language cannot state twice is refused before any data exists. @@ -352,13 +393,13 @@ def _sos_bounds(spec: Spec) -> Iterator[str]: if below is None: yield ( f"{context}: variable '{entry.variable}' has no lower bound, and the set expands to rows " - f'that hold an unpicked member at zero from below as well as above. Declare bounds.lower, ' + f'that hold an unpicked element at zero from below as well as above. Declare bounds.lower, ' f'as a number or a parameter.' ) if above is None: yield ( f"{context}: variable '{entry.variable}' has no upper bound, and the set expands to rows " - f'that hold an unpicked member at zero from above as well as below. Declare bounds.upper, ' + f'that hold an unpicked element at zero from above as well as below. Declare bounds.upper, ' f'as a number or a parameter.' ) @@ -378,7 +419,7 @@ def _piecewise_references(spec: Spec) -> Iterator[str]: yield undeclared_dimension('piecewise', name, pw.along, spec, along=True) continue if not spec.dimensions[pw.along].ordered: - yield unordered(context, f'along: {pw.along}', pw.along) + yield unordered(context, f'along: {pw.along}', pw.along, spec.dimensions[pw.along].members) for d in pw.dims: if d not in spec.dimensions: yield undeclared_dimension('piecewise', name, d, spec) diff --git a/src/mathspec/errors.py b/src/mathspec/errors.py index a0fce4a8f..ed5a4f5b7 100644 --- a/src/mathspec/errors.py +++ b/src/mathspec/errors.py @@ -43,8 +43,18 @@ def did_you_mean(name: str, known: Iterable[str], *, label: str = 'Declared', li return f'{label}: {", ".join(candidates) or "nothing"}.' if listing else '' -def unordered(context: str, construct: str, dimension: str) -> str: - """The refusal for *construct* reading the order of *dimension*, which is not declared ordered.""" +def unordered(context: str, construct: str, dimension: str, members: Iterable[tuple[str, str]] = ()) -> str: + """The refusal for *construct* reading the order of *dimension*, which is not declared ordered. + + A dimension with *members*, each a ``(role, dimension)``, cannot be + declared ordered, so its rewrite is the entry over the members. + """ + if over := sorted({dim for _, dim in members}): + return ( + f"{context}: {construct} reads the order of '{dimension}', which lists its members and so has no " + f'order. Declare the entry over {over}, with `where:` a relation that lists the tuples, and step ' + f'along a member that is declared ordered.' + ) return ( f"{context}: {construct} reads the order of '{dimension}', which is not declared ordered, so the " f'order would come from the row order of the data. Declare ' diff --git a/src/mathspec/program.py b/src/mathspec/program.py index 7f5c93718..00178f7d8 100644 --- a/src/mathspec/program.py +++ b/src/mathspec/program.py @@ -511,6 +511,10 @@ class Relation: description: str | None = None partial: tuple[str, ...] = () """The value roles a row may leave empty: the maps under ``missing: absent``, sorted by role.""" + members: tuple[str, ...] = () + """The value roles a dimension's members are, sorted by role. A tool reads each off the fields of a label of the + dimension, and the file declares no map of that name. + """ @property def roles(self) -> tuple[str, ...]: @@ -677,6 +681,15 @@ class Dimension: them. """ description: str | None = None + over: tuple[tuple[str, str], ...] = () + """The members of the dimension as ``(role, dimension)``, sorted by role, or empty when the file lists none. A label + is then one tuple of member labels, which ``dtype`` does not describe. The table of the dimension in + [`Program.relations`][mathspec.program.Program.relations] has a map per member. + """ + missing: RelationMissing = 'absent' + """Whether every combination of member labels needs a tuple: ``absent`` or ``refused``. It has no meaning for a + dimension without members. + """ @dataclass(frozen=True) @@ -1143,7 +1156,9 @@ class Program: dimensions: Mapping[str, Dimension] = Frozen({}) relations: Mapping[str, Relation] = Frozen({}) """Each table the data supplies, by its subject's name: every relation the file declares, and every dimension it - declares maps of, each with its maps as value columns. + declares maps of or lists members of, each with its maps as value columns. A member is a map of its dimension, listed + in [`Relation.members`][mathspec.program.Relation.members]: a tool reads it off the labels of the dimension, one field + per member, and not off a table. """ sos: Mapping[str, Sos] = Frozen({}) piecewise: Mapping[str, Piecewise] = Frozen({}) diff --git a/src/mathspec/spec.py b/src/mathspec/spec.py index 626a26fb8..6f4a737a1 100644 --- a/src/mathspec/spec.py +++ b/src/mathspec/spec.py @@ -368,8 +368,66 @@ class DimensionSpec(_StrictSpec): """Whether the order in which the data gives the labels is part of the spec. An operator may step or count only along an ordered dimension. On any other dimension, the order of the rows has no meaning. """ + over: Dims | ByName[str] | None = None + """The members of the dimension: a list of dimensions, or a mapping of role to dimension where two members are over + one dimension. A label of the dimension is then one tuple of member labels, and each member is a map of the dimension, + read as ``dimension[member]``. The order of the members has no meaning. + """ + missing: RelationMissing = 'absent' + """Whether every combination of member labels needs a tuple. Under ``absent``, the data lists the tuples that exist. + Under ``refused``, a tool refuses data that leaves a combination out. + """ description: str | None = None + @property + def members(self) -> tuple[tuple[str, str], ...]: + """``(role, dimension)`` per member, sorted by role; empty for a dimension without ``over:``.""" + return () if self.over is None else tuple(sorted(relation_columns(self.over))) + + @field_validator('over', mode='after') + @classmethod + def _lists_a_member(cls, v: object) -> object: + if v is not None and not v: + raise ValueError('lists no member. List at least one dimension, or leave `over:` out.') + return v + + @field_validator('missing', mode='before') + @classmethod + def _absent_or_refused(cls, v: object) -> object: + """A tuple is a label, so no value fills a combination the data leaves out.""" + if v not in get_args(RelationMissing): + msg = ( + f'missing: {_as_yaml(v)} on a dimension, which takes absent or refused. A combination of member ' + f'labels with no tuple is not in the dimension, or is refused.' + ) + raise ValueError(msg) + return v + + @model_validator(mode='after') + def _members_or_labels(self) -> Self: + """A label of a dimension with members is a tuple, so the keys that describe one plain label do not apply.""" + if self.over is None: + if 'missing' in self.model_fields_set: + raise ValueError( + '`missing:` is on a dimension without `over:`, and it states whether every combination of the ' + 'members needs a tuple. Delete `missing:`, or list the members under `over:`.' + ) + return self + members = sorted({dim for _, dim in self.members}) + if self.ordered: + raise ValueError( + f'`ordered: true` is on a dimension with `over:`, and a tuple of member labels has no order. ' + f'Declare the entry that steps over {members}, with `where:` a relation that lists the tuples, and ' + f'declare the member it steps along `ordered: true`.' + ) + for key in ('dtype', 'one_of'): + if key in self.model_fields_set and getattr(self, key) is not None: + raise ValueError( + f'`{key}:` is on a dimension with `over:`, where the label is the tuple of its members. Delete ' + f'`{key}:` here, and write the {key}: of a member on that member.' + ) + return self + @field_validator('one_of', mode='before') @classmethod def _strings_listed_once(cls, v: object, info: ValidationInfo[object]) -> object: @@ -1395,10 +1453,14 @@ def subject_tables(spec: Spec) -> dict[str, Relation]: own columns. A dimension's table has one row per label, keyed by the dimension. Each map is a column of its subject's table, and a map under ``missing: absent`` is listed as [`partial`][mathspec.program.Relation.partial]. + A dimension with members has a table whether or not the file declares maps + of it: each member is a map that every label has, listed as + [`members`][mathspec.program.Relation.members]. A subject the file does not declare is left out, which the load refuses. """ tables: dict[str, Relation] = {} - for name in sorted({*spec.relations, *spec.maps}): + tuples = {d: dd.members for d, dd in spec.dimensions.items() if dd.over} + for name in sorted({*spec.relations, *spec.maps, *tuples}): maps = spec.maps.get(name, Frozen({})) if (relation := spec.relations.get(name)) is not None: key, missing, description = relation.pairs, relation.missing, relation.description @@ -1406,9 +1468,13 @@ def subject_tables(spec: Spec) -> dict[str, Relation]: key, missing, description = ((name, name),), cast('RelationMissing', 'refused'), None else: continue - values = tuple((role, m.dim) for role, m in maps.items()) + members = tuples.get(name, ()) if relation is None else () + values = tuple(sorted((*members, *((role, m.dim) for role, m in maps.items())))) partial = tuple(role for role, m in maps.items() if m.missing == 'absent') - tables[name] = Relation((*key, *values), tuple(r for r, _ in key), missing, description, partial) + key_roles = tuple(r for r, _ in key) + tables[name] = Relation( + (*key, *values), key_roles, missing, description, partial, tuple(role for role, _ in members) + ) return tables diff --git a/tests/expand/curve-activity/after.yaml b/tests/expand/curve-activity/after.yaml index f9176885e..9d60ec365 100644 --- a/tests/expand/curve-activity/after.yaml +++ b/tests/expand/curve-activity/after.yaml @@ -16,7 +16,7 @@ variables: curve_seg: dims: [bp] domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: curve_convexity: diff --git a/tests/expand/curve-adjacency-points/after.yaml b/tests/expand/curve-adjacency-points/after.yaml index 0649307b8..6210173ec 100644 --- a/tests/expand/curve-adjacency-points/after.yaml +++ b/tests/expand/curve-adjacency-points/after.yaml @@ -17,7 +17,7 @@ variables: dims: [bp] where: x_bp domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: curve_convexity: diff --git a/tests/expand/curve-adjacency/after.yaml b/tests/expand/curve-adjacency/after.yaml index b5071dcbf..34ccca2f1 100644 --- a/tests/expand/curve-adjacency/after.yaml +++ b/tests/expand/curve-adjacency/after.yaml @@ -15,7 +15,7 @@ variables: curve_seg: dims: [bp] domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: curve_convexity: diff --git a/tests/expand/curve-sos2/after.yaml b/tests/expand/curve-sos2/after.yaml index b5071dcbf..34ccca2f1 100644 --- a/tests/expand/curve-sos2/after.yaml +++ b/tests/expand/curve-sos2/after.yaml @@ -15,7 +15,7 @@ variables: curve_seg: dims: [bp] domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: curve_convexity: diff --git a/tests/expand/set-lower-bound/after.yaml b/tests/expand/set-lower-bound/after.yaml index dd1a64e9c..bec681bcd 100644 --- a/tests/expand/set-lower-bound/after.yaml +++ b/tests/expand/set-lower-bound/after.yaml @@ -8,7 +8,7 @@ variables: pick_seg: dims: [g] domain: binary - description: a binary per member, 1 where that member may be nonzero + description: a binary per element, 1 where that element may be nonzero constraints: pick_pick: diff --git a/tests/expand/set-type1/after.yaml b/tests/expand/set-type1/after.yaml index 7f6eccd36..e3a977854 100644 --- a/tests/expand/set-type1/after.yaml +++ b/tests/expand/set-type1/after.yaml @@ -8,7 +8,7 @@ variables: pick_seg: dims: [g] domain: binary - description: a binary per member, 1 where that member may be nonzero + description: a binary per element, 1 where that element may be nonzero constraints: pick_pick: diff --git a/tests/expand/set-type2/after.yaml b/tests/expand/set-type2/after.yaml index 583f060ed..feb714665 100644 --- a/tests/expand/set-type2/after.yaml +++ b/tests/expand/set-type2/after.yaml @@ -8,7 +8,7 @@ variables: pick_seg: dims: [g] domain: binary - description: a binary per segment, 1 where the two members it spans may be nonzero + description: a binary per segment, 1 where the two elements it spans may be nonzero constraints: pick_pick: diff --git a/tests/test_dimensions.py b/tests/test_dimensions.py index d09cc1ce7..2337fff82 100644 --- a/tests/test_dimensions.py +++ b/tests/test_dimensions.py @@ -656,7 +656,7 @@ def test_the_frame_check_and_the_reading_walk_the_same_leaves(namespace): assert where.dims == ('generator',), 'read at the generator axis' with pytest.raises(DimensionError, match=r"where-parameter 'p_max' reads dims \['generator'\]"): - _check_condition_dims(where, frozenset({'snapshot'}), 'test') + _check_condition_dims(where, frozenset({'snapshot'}), 'test', namespace.spec) @pytest.mark.parametrize( diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py new file mode 100644 index 000000000..e3de1aad4 --- /dev/null +++ b/tests/test_tuple_dimensions.py @@ -0,0 +1,574 @@ +# SPDX-FileCopyrightText: mathspec Contributors +# +# SPDX-License-Identifier: MIT + +"""A dimension that lists its members under `over:`: what loads, what it implies, and what is refused. + +Its label is the tuple of its members, and it is one plain dimension in every +operator. Each member is a map of the dimension, read as `dimension[member]`. +""" + +from __future__ import annotations + +from typing import Any + +import pytest + +from mathspec import merge, override, rename, to_spec +from mathspec._advising import advice +from mathspec._typesetting import FORMATS, typeset +from mathspec.errors import LanguageError +from mathspec.program import JoinedCondition, Relation, RelationComparison +from tests.fixtures import varied + +#: The example of #1011: `connection` lists (unit, port) pairs and maps each to a +#: bus, `trade` lists two regions by role, and `active` is a sparse set with an +#: ordered member. +MODEL: dict[str, Any] = { + 'dimensions': { + 'unit': {}, + 'port': {}, + 'bus': {}, + 'region': {}, + 'snapshot': {'dtype': 'int', 'ordered': True}, + 'period': {'dtype': 'int', 'ordered': True}, + 'connection': {'over': ['unit', 'port']}, + 'trade': {'over': {'src': 'region', 'dst': 'region'}}, + }, + 'relations': {'active': {'dims': ['unit', 'period'], 'missing': 'absent'}}, + 'maps': {'connection': {'bus': {'dim': 'bus'}}}, + 'parameters': { + 'capacity': {'dims': ['unit']}, + 'rating': {'dims': ['unit', 'port']}, + 'tariff': {'dims': ['region']}, + 'load': {'dims': ['bus', 'snapshot']}, + }, + 'variables': { + 'flow': {'dims': ['connection', 'snapshot'], 'bounds': {'lower': 0}}, + 'shipped': {'dims': ['trade'], 'bounds': {'lower': 0}}, + 'both': {'dims': ['connection', 'unit']}, + }, + 'constraints': { + 'limit': {'dims': ['connection', 'snapshot'], 'expression': 'flow <= at(capacity, by=connection[unit])'}, + 'balance': { + 'dims': ['bus', 'snapshot'], + 'expression': 'sum(flow, over=connection, by=connection[bus]) == load', + }, + }, +} + + +FRAGMENT: dict[str, Any] = { + 'dimensions': {'unit': {}, 'port': {}, 'connection': {'over': ['unit', 'port']}}, + 'variables': {'flow': {'dims': ['connection']}}, +} + + +def _refusal(**patch: Any) -> str: + """The message `to_spec` refuses the model patched with, and it has to refuse.""" + with pytest.raises(LanguageError) as caught: + to_spec(varied(MODEL, **patch)) + return str(caught.value) + + +def _constraint(expression: str, dims: list[str]) -> dict[str, Any]: + return {'constraints.probe': {'dims': dims, 'expression': expression}} + + +def test_each_member_is_a_map_of_the_dimension(): + program = to_spec(MODEL).program + connection = program.dimensions['connection'] + assert connection.over == (('port', 'port'), ('unit', 'unit')), 'members are (role, dimension), sorted by role' + assert connection.missing == 'absent', 'a tuple dimension is a sparse subset unless the file says refused' + assert program.relations['connection'] == Relation( + (('connection', 'connection'), ('bus', 'bus'), ('port', 'port'), ('unit', 'unit')), + ('connection',), + 'refused', + members=('port', 'unit'), + ), 'the table of the dimension has a map per member beside the maps the file declares' + assert program.relations['trade'].members == ('dst', 'src'), 'a dimension with no declared map has its members' + assert program.dimensions['trade'].over == (('dst', 'region'), ('src', 'region')), 'a role names each member' + assert program.dimensions['unit'].over == (), 'a plain dimension has no members' + + +def test_the_order_of_the_members_changes_nothing(): + swapped = varied(MODEL, **{'dimensions.connection': {'over': ['port', 'unit']}}) + assert to_spec(swapped) == to_spec(MODEL) + + +@pytest.mark.parametrize('missing', ['absent', 'refused']) +def test_missing_says_whether_the_full_product_is_required(missing): + spec = to_spec(varied(MODEL, **{'dimensions.connection.missing': missing})) + assert spec.program.dimensions['connection'].missing == missing + assert spec.program.relations['connection'].missing == 'refused', 'every tuple has its members, either way' + assert spec.program.relations['connection'].partial == (), 'no member may leave a tuple without a label' + + +@pytest.mark.parametrize( + ('expression', 'dims'), + [ + pytest.param('flow <= at(capacity, by=connection[unit])', ['connection', 'snapshot'], id='one-member'), + pytest.param('flow <= at(rating, by=connection[unit, port])', ['connection', 'snapshot'], id='every-member'), + pytest.param('shipped <= at(tariff, by=trade[src])', ['trade'], id='a-member-by-role'), + pytest.param( + 'sum(flow, over=connection, by=connection[port]) >= 0', ['port', 'snapshot'], id='sum-to-a-member' + ), + pytest.param('sum(flow, over=connection) >= 0', ['snapshot'], id='sum-the-tuples-away'), + pytest.param('both <= capacity', ['connection', 'unit'], id='an-entry-over-the-dimension-and-a-member'), + ], +) +def test_a_member_is_read_as_a_map_of_the_dimension(expression, dims): + constraint = to_spec(varied(MODEL, **_constraint(expression, dims))).program.constraints['probe'] + assert sorted({*constraint.lhs.dims, *constraint.rhs.dims}) == sorted(dims) + + +@pytest.mark.parametrize( + 'patch', + [ + pytest.param(_constraint('flow <= capacity', ['connection', 'unit', 'snapshot']), id='a-constraint'), + pytest.param( + {'expressions.e': {'dims': ['connection', 'unit', 'snapshot'], 'expression': 'flow * capacity'}}, + id='a-named-expression', + ), + pytest.param( + _constraint('sum(flow * capacity, over=snapshot) <= both', ['connection', 'unit']), + id='under-a-sum-that-keeps-both', + ), + pytest.param({'variables.both.where': 'at(rating, by=connection[unit, port]) > capacity'}, id='a-condition'), + pytest.param( + { + 'constraints.probe': { + 'dims': ['connection', 'unit'], + 'expression': 'both <= 1', + 'where': 'at(rating, by=connection[unit, port]) > capacity', + } + }, + id='a-constraint-where', + ), + pytest.param( + { + 'parameters.p': { + 'dims': ['connection', 'unit'], + 'where': 'at(rating, by=connection[unit, port]) > capacity', + } + }, + id='a-parameter-where', + ), + pytest.param( + { + 'expressions.e': { + 'dims': ['connection', 'unit', 'snapshot'], + 'cases': { + 'a': { + 'when': 'at(rating, by=connection[unit, port]) > capacity', + 'expression': 'flow * capacity', + } + }, + 'otherwise': 'flow * capacity', + } + }, + id='a-case', + ), + pytest.param( + { + 'parameters.xs': {'dims': ['period']}, + 'parameters.ys': {'dims': ['period']}, + 'variables.w': {'dims': ['connection']}, + 'variables.v': {'dims': ['unit']}, + 'variables.y': {'dims': ['connection', 'unit']}, + 'piecewise.curve': { + 'dims': ['connection', 'unit'], + 'along': 'period', + 'links': {'x': ['w + v', 'xs'], 'y': ['y', 'ys']}, + }, + }, + id='a-piecewise-link', + ), + ], +) +def test_a_frame_over_the_dimension_and_its_member_takes_the_cross_product(patch): + """Rule 11 of #1011: where `dims:` declares both, a member operand meets the dimension, and the entry loads.""" + to_spec(varied(MODEL, **patch)) + + +def test_a_condition_compares_a_member_label(): + spec = to_spec(varied(MODEL, **{'variables.flow.where': "connection[unit] == 'gas'"})) + (atom,) = spec.program.variables['flow'].where.atoms + assert atom == RelationComparison('connection', 'unit', '==', 'gas', ('connection',)) + + +def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): + """Rule 9 of #1011: `active` stays a bare relation over (unit, period), and an entry over `connection` reads it with `at`.""" + built = {'dims': ['connection', 'period'], 'where': 'at(active, by=connection[unit])'} + spec = to_spec(varied(MODEL, **{'variables.built': built})) + (atom,) = spec.program.variables['built'].where.atoms + assert isinstance(atom, JoinedCondition) + assert spec.program.variables['built'].where.dims == ('connection', 'period') + + +@pytest.mark.parametrize( + ('patch', 'fragments'), + [ + pytest.param( + {'dimensions.pair': {'over': ['connection', 'bus']}}, + ( + "Dimension 'pair' lists 'connection' under 'over:', and 'connection' has members of its own", + "over: ['bus', 'port', 'unit']", + ), + id='a-tuple-dimension-as-a-member', + ), + pytest.param( + {'dimensions.pair': {'over': ['unit', 'nope']}}, + ("Dimension 'pair' references undeclared dimension 'nope'",), + id='an-undeclared-member', + ), + pytest.param( + {'dimensions.connection.ordered': True}, + ('dimensions.connection', '`ordered: true`', 'no order', "over ['port', 'unit']", 'where:'), + id='ordered', + ), + pytest.param( + {'dimensions.connection.one_of': ['a']}, + ('dimensions.connection', '`one_of:`', 'the label is the tuple of its members', 'one_of: of a member'), + id='one-of', + ), + pytest.param( + {'dimensions.connection.dtype': 'str'}, + ('dimensions.connection', '`dtype:`', 'the label is the tuple of its members', 'dtype: of a member'), + id='dtype', + ), + pytest.param( + {'dimensions.bus.missing': 'refused'}, + ('dimensions.bus', '`missing:`', 'without `over:`', 'Delete `missing:`'), + id='missing-without-members', + ), + pytest.param( + {'dimensions.connection.missing': 0}, + ('missing: 0 on a dimension', 'takes absent or refused'), + id='missing-is-a-number', + ), + pytest.param( + {'dimensions.connection.over': []}, + ('dimensions.connection.over', 'lists no member', 'leave `over:` out'), + id='no-member', + ), + pytest.param( + {'dimensions.pair': {'over': {'port': 'unit', 'bus': 'bus'}}}, + ("Dimension 'pair' names member 'port' after dimension 'port', but the member is over 'unit'", 'Rename'), + id='a-role-named-after-another-dimension', + ), + pytest.param( + {'dimensions.pair': {'over': ['region', 'region']}}, + ("Dimension 'pair' lists 'region' twice under 'over:'", 'over: {region0: region, region1: region}'), + id='a-dimension-twice-in-the-list-form', + ), + pytest.param( + {'relations.connection': {'dims': ['unit', 'port']}}, + ("Relation 'connection' collides with the dimension of the same name",), + id='a-declared-relation-of-the-same-name', + ), + pytest.param( + {'maps.connection.unit': {'dim': 'unit'}}, + ("maps: 'connection': map 'unit' has the name of a member of 'connection'", 'connection[unit]'), + id='a-declared-map-named-after-a-member', + ), + pytest.param( + _constraint("shift(flow, along=connection, offset=1, edge='wrap') >= 0", ['connection', 'snapshot']), + ("shift(along=connection) reads the order of 'connection'", 'no order', "over ['port', 'unit']"), + id='shift', + ), + pytest.param( + _constraint('sum_back(flow, along=connection, window=2) >= 0', ['connection', 'snapshot']), + ("sum_back(along=connection) reads the order of 'connection'", 'no order'), + id='sum-back', + ), + pytest.param( + {'variables.flow.where': 'position(connection) == 0'}, + ("position(connection) reads the order of 'connection'", 'no order'), + id='position', + ), + pytest.param( + { + 'parameters.xs': {'dims': ['connection']}, + 'parameters.ys': {'dims': ['connection']}, + 'variables.x': {'dims': []}, + 'variables.y': {'dims': []}, + 'piecewise.curve': {'dims': [], 'along': 'connection', 'links': {'x': ['x', 'xs'], 'y': ['y', 'ys']}}, + }, + ("piecewise 'curve': along: connection reads the order of 'connection'", 'no order'), + id='piecewise', + ), + pytest.param( + { + 'variables.flow.bounds.upper': 1, + 'sos.pick': {'variable': 'flow', 'along': 'connection', 'type': 2}, + }, + ("Sos 'pick': type: 2 along connection reads the order of 'connection'", "over ['port', 'unit']"), + id='sos-of-type-2', + ), + pytest.param( + _constraint('at(both, by=connection[unit]) >= 0', ['connection']), + ( + "at(by=connection[unit]) reads through 'connection'", + "carries both 'connection' and its member ['unit']", + "Sum ['unit'] out of the operand first", + ), + id='an-operand-with-the-tuple-and-a-member', + ), + pytest.param( + _constraint('sum(flow, over=unit) >= 0', ['connection', 'snapshot']), + ( + "'unit' is a member of 'connection'", + 'sum(..., over=connection, by=connection[port])', + ), + id='over-names-a-member', + ), + pytest.param( + _constraint('sum(flow, over=unit, by=connection[port]) >= 0', ['port', 'snapshot']), + ("over=unit names a member of 'connection'", 'sum(..., over=connection, by=connection[port])'), + id='over-names-a-member-beside-by', + ), + pytest.param( + _constraint('sum(flow, over=unit, by=connection[bus]) >= 0', ['bus', 'snapshot']), + ("over=unit names a member of 'connection'", 'sum(..., over=connection, by=connection[bus])'), + id='over-names-a-member-beside-a-declared-map', + ), + pytest.param( + _constraint('sum(flow, over=[unit, port]) >= 0', ['snapshot']), + ("'unit' is a member of 'connection'", 'Write sum(..., over=connection).'), + id='over-names-every-member', + ), + pytest.param( + _constraint('sum(shipped, over=region) >= 0', ['trade']), + ("'region' is a member of 'trade'", 'by=trade[]'), + id='over-names-a-dimension-two-roles-are-over', + ), + pytest.param( + _constraint('flow <= capacity', ['connection', 'snapshot']), + ( + "an operand over ['unit'] meets one over 'connection'", + 'at(capacity, by=connection[unit])', + 'sum(flow, over=connection, by=connection[unit])', + ), + id='a-member-operand-meets-the-tuple', + ), + pytest.param( + _constraint('flow <= capacity', ['unit', 'snapshot']), + ("meets one over 'connection'", 'sum(flow, over=connection, by=connection[unit])'), + id='a-member-operand-meets-the-tuple-in-a-frame-over-the-member', + ), + pytest.param( + {'objective': {'sense': 'minimize', 'expression': 'sum(flow * capacity)'}}, + ( + "The objective: an operand over ['unit'] meets one over 'connection'", + 'at(capacity, by=connection[unit])', + ), + id='a-member-operand-meets-the-tuple-in-a-product', + ), + pytest.param( + _constraint('sum(flow * capacity, over=unit) <= 1', ['connection', 'snapshot']), + ("meets one over 'connection'", 'at(capacity, by=connection[unit])'), + id='a-member-operand-meets-the-tuple-under-a-sum', + ), + pytest.param( + _constraint('sum(flow * capacity, over=unit) <= both', ['connection', 'unit', 'snapshot']), + ("meets one over 'connection'", 'at(capacity, by=connection[unit])'), + id='a-member-operand-meets-the-tuple-under-a-sum-over-the-member-the-frame-declares', + ), + pytest.param( + _constraint('sum(flow * capacity) <= both', ['connection', 'unit']), + ("meets one over 'connection'", 'at(capacity, by=connection[unit])'), + id='a-member-operand-meets-the-tuple-under-a-sum-over-everything', + ), + pytest.param( + {'assumptions.a': 'at(rating, by=connection[unit, port]) > capacity'}, + ("Assumption 'a': an operand over ['unit'] meets one over 'connection'",), + id='a-member-operand-meets-the-tuple-in-an-assumption', + ), + pytest.param( + { + 'parameters.xs': {'dims': ['period']}, + 'parameters.ys': {'dims': ['period']}, + 'variables.y': {'dims': ['connection', 'unit']}, + 'piecewise.curve': { + 'dims': ['connection', 'unit'], + 'along': 'period', + 'links': {'x': ['y', 'xs'], 'y': ['y', 'ys']}, + 'where': 'at(rating, by=connection[unit, port]) > capacity', + }, + }, + ("piecewise 'curve' where: an operand over ['unit'] meets one over 'connection'",), + id='a-member-operand-meets-the-tuple-in-a-piecewise-where-its-assumptions-repeat', + ), + pytest.param( + {'variables.flow.where': 'at(rating, by=connection[unit, port]) > capacity'}, + ("Variable 'flow': an operand over ['unit'] meets one over 'connection'",), + id='a-member-operand-meets-the-tuple-in-a-condition', + ), + pytest.param( + {'expressions.e': {'dims': ['unit'], 'expression': '2 * capacity'}} + | _constraint('flow <= e', ['connection', 'snapshot']), + ('at(e, by=connection[unit])',), + id='a-named-expression-over-a-member-meets-the-tuple', + ), + pytest.param( + {'expressions.e': {'dims': ['connection', 'snapshot'], 'expression': 'capacity'}}, + ("the body carries dims ['unit']", 'at(capacity, by=connection[unit])'), + id='a-named-expression-body-over-a-member', + ), + pytest.param( + { + 'expressions.e': { + 'dims': ['connection', 'snapshot'], + 'cases': {'a': {'when': "connection[unit] == 'u'", 'expression': 'capacity'}}, + 'otherwise': 'flow', + } + }, + ("the value carries dims ['unit']", 'at(capacity, by=connection[unit])'), + id='a-case-value-over-a-member', + ), + pytest.param( + {'variables.u': {'dims': ['unit']}} | _constraint('sum(u, over=unit, by=connection[port]) >= 0', ['port']), + ('sum(at(u, by=connection[unit]), over=connection, by=connection[port])',), + id='over-names-a-member-of-an-operand-without-the-dimension', + ), + pytest.param( + {'variables.u': {'dims': ['unit']}} | _constraint('u <= 1', ['connection']), + ("carries dims ['unit'] that are not in its dims", 'at(u, by=connection[unit])'), + id='a-constraint-over-a-member-its-dims-lack', + ), + pytest.param( + {'variables.flow.bounds.upper': 'capacity'}, + ( + "parameter 'capacity' has dims ['unit'] outside", + 'Bound the variable in a constraint', + 'flow <= at(capacity, by=connection[unit])', + ), + id='a-bound-over-a-member', + ), + pytest.param( + {'variables.flow.where': 'capacity > 0'}, + ("reads dims ['unit'] outside the declared dims", 'at(capacity, by=connection[unit])'), + id='a-where-over-a-member', + ), + pytest.param( + {'variables.flow.where': "connection == 'a'"}, + ("'connection' lists its members", 'no label to compare', "connection[port] == 'a'"), + id='a-label-comparison', + ), + pytest.param( + {'variables.flow.where': 'connection'}, + ('a bare dimension name is true at every coordinate', 'where: "connection[port] == \'...\'"'), + id='a-bare-dimension-with-members', + ), + pytest.param( + {'dimensions.ring': {'over': ['loop', 'unit']}, 'dimensions.loop': {'over': ['ring', 'port']}}, + ("Dimension 'ring' lists 'loop'", "over: ['port', 'unit']"), + id='two-dimensions-as-members-of-each-other', + ), + ], +) +def test_what_a_tuple_dimension_does_not_take_is_refused_with_the_rewrite(patch, fragments): + message = _refusal(**patch) + for fragment in fragments: + assert fragment in message + + +def test_no_advice_about_a_tuple_dimension_where_none_is_in_play(): + """A stray dimension that is no member keeps the advice it had.""" + message = _refusal(**_constraint('flow <= load', ['connection', 'snapshot'])) + assert 'Add them to dims:, or sum them out' in message + assert 'at(' not in message, 'bus is no member of connection' + + +@pytest.mark.parametrize('fmt', FORMATS) +@pytest.mark.parametrize( + ('missing', 'relation'), + [pytest.param('absent', 'subset_of', id='a-subset'), pytest.param('refused', 'equal', id='the-full-product')], +) +def test_the_legend_prints_the_members(fmt, missing, relation): + spec = to_spec(varied(FRAGMENT, **{'dimensions.connection.missing': missing})) + ops = FORMATS[fmt].operators + c, p, u = ((r'cal(%s)' if fmt == 'typst' else r'\mathcal{%s}') % letter for letter in 'CPU') + assert f'{c} {ops[relation]} {p} {ops["times"]} {u}' in typeset(spec, fmt), f'{fmt} prints the product' + member = r'upright("unit")' if fmt == 'typst' else r'\mathrm{unit}' + assert member not in typeset(spec, fmt), 'a member prints as the product, not as a map of its own' + + +def test_a_set_of_type_1_runs_along_a_dimension_with_members(): + """A type-1 set uses no order, so a dimension without one carries it.""" + sos = {'variables.flow.bounds.upper': 1, 'sos.pick': {'variable': 'flow', 'along': 'connection', 'type': 1}} + assert to_spec(varied(MODEL, **sos)).sos['pick'].along == 'connection' + + +@pytest.mark.parametrize( + ('variables', 'unused'), + [ + pytest.param({'x': {'dims': ['snapshot']}}, ['connection', 'port', 'unit'], id='nothing-is-over-the-dimension'), + pytest.param({'x': {'dims': ['connection']}}, ['snapshot'], id='an-entry-is-over-the-dimension'), + ], +) +def test_a_member_does_not_count_as_a_use(variables, unused): + """The table of the dimension has a column over the dimension and each member, so it counted as reaching them.""" + spec = { + 'dimensions': {'unit': {}, 'port': {}, 'snapshot': {}, 'connection': {'over': ['unit', 'port']}}, + 'variables': variables, + } + notes = sorted(note.subject for note in advice(spec) if note.kind == 'never-an-axis') + assert notes == unused, 'an entry over the dimension reaches its members, and a member reaches nothing' + + +def test_fragments_that_agree_on_the_members_merge(): + other = { + 'dimensions': {'port': {}, 'unit': {}, 'connection': {'over': ['port', 'unit']}}, + 'variables': {'loss': {'dims': ['connection']}}, + } + assert merge([FRAGMENT, other]).program.dimensions['connection'].over == (('port', 'port'), ('unit', 'unit')) + + +@pytest.mark.parametrize( + 'connection', + [ + pytest.param({'over': ['unit']}, id='other-members'), + pytest.param({'over': {'unit': 'unit', 'side': 'port'}}, id='other-roles'), + pytest.param({'over': ['unit', 'port'], 'missing': 'refused'}, id='other-missing'), + pytest.param({}, id='no-members'), + ], +) +def test_fragments_that_disagree_on_the_members_are_refused(connection): + other = { + 'dimensions': {'port': {}, 'unit': {}, 'connection': connection}, + 'variables': {'loss': {'dims': ['connection']}}, + } + with pytest.raises(LanguageError, match=r"say different things about the dimension 'connection'") as raised: + merge([FRAGMENT, other]) + assert 'Make the two identical' in str(raised.value) + + +def test_a_patch_cannot_change_the_members(): + with pytest.raises(LanguageError, match=r"declares the dimension 'connection'"): + override(FRAGMENT, [{'dimensions': {'connection': {'over': ['unit']}}}]) + + +def test_rename_reaches_the_members_and_their_reads(): + renamed = rename(MODEL, {'unit': 'plant', 'connection': 'link', 'region': 'zone'}) + assert renamed.dimensions['link'].over == ('plant', 'port') + assert dict(renamed.dimensions['trade'].over) == {'src': 'zone', 'dst': 'zone'}, 'a role keeps its name' + assert renamed.constraints['limit'].expression == 'flow <= at(capacity, by=link[plant])' + assert rename(renamed, {'plant': 'unit', 'link': 'connection', 'zone': 'region'}) == to_spec(MODEL) + + +@pytest.mark.parametrize( + 'names', [pytest.param({'src': 'origin'}, id='from-a-role'), pytest.param({'bus': 'src'}, id='to-a-role')] +) +def test_rename_refuses_a_name_that_is_a_role(names): + """A token is renamed wherever it is spelt, so a role named after no dimension would change with an entry of its name.""" + model = varied(MODEL, **{'parameters.src': {'dims': []}}) if 'src' in names else MODEL + with pytest.raises(LanguageError, match=r"'src' is also a member of the dimension 'trade'"): + rename(model, names) + + +@pytest.mark.parametrize('canonical', [False, True]) +def test_a_spec_with_members_is_written_and_read_back(canonical): + spec = to_spec(MODEL) + assert to_spec(spec.to_yaml(canonical=canonical)).program == spec.program diff --git a/tests/typesetting/golden/latex.out b/tests/typesetting/golden/latex.out index 6c1023216..431e76f1e 100644 --- a/tests/typesetting/golden/latex.out +++ b/tests/typesetting/golden/latex.out @@ -11,8 +11,10 @@ \begin{description} \item[{$\mathcal{B}$}] index $b$ --- \texttt{bp} \item[{$\mathcal{U}$}] index $u$ --- \texttt{bus} with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}$, \texttt{connection} is \texttt{absent} where the data has no row, \texttt{bus[area]} is \texttt{absent} where the data gives no label +\item[{$\mathcal{C}$}] index $c$ --- \texttt{corridor}, $\mathcal{C} = \mathcal{U} \times \mathcal{U}$ \item[{$\mathcal{G}$}] index $g$ --- \texttt{generator} with $\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}$, \texttt{connection} is \texttt{absent} where the data has no row \item[{$\mathcal{S}$}] index $s$ --- \texttt{season} with $\mathrm{season}: \mathcal{T} \to \mathcal{S}$ +\item[{$\mathcal{I}$}] index $i$ --- \texttt{site}, $\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}$ \item[{$\mathcal{T}$}] index $t$ --- \texttt{snapshot} (\texttt{int} coordinates) with $\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}$ \item[{$\mathcal{E}$}] index $e$ --- \texttt{technology} with $\mathrm{technology}: \mathcal{G} \to \mathcal{E}$ \item[{$\mathcal{Z}$}] index $z$ --- \texttt{zone} (labels \texttt{north}, \texttt{south}) with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}$, \texttt{bus[area]} is \texttt{absent} where the data gives no label @@ -26,6 +28,7 @@ \item[{$\mathrm{bp\_x}$}] \texttt{bp\_x} over $\mathcal{B} \times \mathcal{G}$, $0$ where the data has no row \item[{$\mathrm{bp\_y}$}] \texttt{bp\_y} over $\mathcal{B} \times \mathcal{G}$, $0$ where the data has no row \item[{$\mathrm{budget}$}] \texttt{budget} (scalar) +\item[{$\mathrm{corridor\_cap}$}] \texttt{corridor\_cap} over $\mathcal{C}$ \item[{$\mathrm{cost}$}] \texttt{cost} over $\mathcal{G}$, $0$ where the data has no row \item[{$\mathrm{eta}$}] \texttt{eta} over $\mathcal{G}$ \item[{$\mathrm{growth}$}] \texttt{growth} (scalar) @@ -55,6 +58,7 @@ \item[{$\mathit{op\_cost}$}] \texttt{op\_cost} over $\mathcal{G} \times \mathcal{T}$ \item[{$p$}] \texttt{p} over $\mathcal{G} \times \mathcal{T}$ \item[{$\mathit{reserve}$}] \texttt{reserve} (scalar) +\item[{$\mathit{site\_out}$}] \texttt{site\_out} over $\mathcal{I} \times \mathcal{T}$ \item[{$\mathit{slack}$}] \texttt{slack} over $\mathcal{T}$ \item[{$\mathit{spare}$}] \texttt{spare} over $\mathcal{G}$ \item[{$\mathit{spill}$}] \texttt{spill} over $\mathcal{T}$ @@ -100,6 +104,7 @@ \text{op\_cost} && \mathit{op\_cost}_{g,t} & \ge 0 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ \text{p} && \mathrm{p}^{\mathrm{min}}_{g} \le p_{g,t} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \vee \mathrm{p}^{\mathrm{min}}_{g} > 0 \\ \text{reserve} && \mathit{reserve} & \ge 0 \\ +\text{site\_out} && \mathit{site\_out}_{i,t} & \ge 0 && \forall\, i \in \mathcal{I},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{\mathrm{generator}(i)} \\ \text{slack} && \mathit{slack}_{t} & \le 100 && \forall\, t \in \mathcal{T} \\ \text{spare} && \mathit{spare}_{g} & \in \mathbb{Z} && \forall\, g \in \mathcal{G} \\ \text{spill} && \mathit{spill}_{t} & \ge 0 && \forall\, t \in \mathcal{T} \\ diff --git a/tests/typesetting/golden/markdown.out b/tests/typesetting/golden/markdown.out index 4451ad904..35541b311 100644 --- a/tests/typesetting/golden/markdown.out +++ b/tests/typesetting/golden/markdown.out @@ -8,8 +8,10 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 |---|---| | $`\mathcal{B}`$ | index $`b`$ — `bp` | | $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}`$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{C}`$ | index $`c`$ — `corridor`, $`\mathcal{C} = \mathcal{U} \times \mathcal{U}`$ | | $`\mathcal{G}`$ | index $`g`$ — `generator` with $`\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}`$, `connection` is `absent` where the data has no row | | $`\mathcal{S}`$ | index $`s`$ — `season` with $`\mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | +| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}`$ | | $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | | $`\mathcal{E}`$ | index $`e`$ — `technology` with $`\mathrm{technology}: \mathcal{G} \to \mathcal{E}`$ | | $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | @@ -24,6 +26,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 | $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{budget}`$ | `budget` (scalar) | +| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{C}`$ | | $`\mathrm{cost}`$ | `cost` over $`\mathcal{G}`$, $`0`$ where the data has no row | | $`\mathrm{eta}`$ | `eta` over $`\mathcal{G}`$ | | $`\mathrm{growth}`$ | `growth` (scalar) | @@ -55,6 +58,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 | $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{G} \times \mathcal{T}`$ | | $`p`$ | `p` over $`\mathcal{G} \times \mathcal{T}`$ | | $`\mathit{reserve}`$ | `reserve` (scalar) | +| $`\mathit{site\_out}`$ | `site_out` over $`\mathcal{I} \times \mathcal{T}`$ | | $`\mathit{slack}`$ | `slack` over $`\mathcal{T}`$ | | $`\mathit{spare}`$ | `spare` over $`\mathcal{G}`$ | | $`\mathit{spill}`$ | `spill` over $`\mathcal{T}`$ | @@ -144,6 +148,12 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 \mathit{reserve} \ge 0 ``` +**`site_out`** + +```math +\mathit{site\_out}_{i,t} \ge 0 \qquad \forall\, i \in \mathcal{I},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{\mathrm{generator}(i)} +``` + **`slack`** ```math diff --git a/tests/typesetting/golden/model.yaml b/tests/typesetting/golden/model.yaml index a98643e17..b6780d706 100644 --- a/tests/typesetting/golden/model.yaml +++ b/tests/typesetting/golden/model.yaml @@ -20,6 +20,8 @@ dimensions: season: { dtype: str } technology: { dtype: str } bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through + site: { over: [generator, bus] } # a dimension that lists its members: the legend prints it as a subset of their product + corridor: { over: { from_bus: bus, to_bus: bus }, missing: refused } # members by role, and every combination required: the product itself relations: gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other @@ -42,6 +44,7 @@ parameters: load: { dims: [snapshot, bus] } is_flexible: { dims: [generator], dtype: bool, missing: false } zone_cap: { dims: [zone] } + corridor_cap: { dims: [corridor] } # over a dimension whose two members are over one dimension tech_cap: { dims: [bus, technology], missing: absent } link_eff: { dims: [generator, bus], where: connection, missing: 1 } area_weight: { dims: [bus], where: "bus[area]" } # a map's label as a condition: the buses that have an area @@ -68,6 +71,10 @@ variables: bounds: { upper: 100 } theta: # unbounded dims: [bus] + site_out: # over a dimension with members, where a parameter of one member holds + dims: [snapshot, site] + where: "at(is_flexible, by=site[generator])" + bounds: { lower: 0 } on: # a binary domain, which is a set rather than a pair of bounds dims: [snapshot, generator] domain: binary diff --git a/tests/typesetting/golden/typst.out b/tests/typesetting/golden/typst.out index 0722349a2..349d705de 100644 --- a/tests/typesetting/golden/typst.out +++ b/tests/typesetting/golden/typst.out @@ -6,8 +6,10 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 == Sets / $cal(B)$: index $b$ --- `bp` / $cal(U)$: index $u$ --- `bus` with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("connection") subset.eq cal(U) times cal(G), upright("bus"): cal(G) arrow.r cal(U)$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label +/ $cal(C)$: index $c$ --- `corridor`, $cal(C) = cal(U) times cal(U)$ / $cal(G)$: index $g$ --- `generator` with $upright("connection") subset.eq cal(U) times cal(G), upright("gen_zone") subset.eq cal(G) times cal(T), upright("zone"): upright("gen_zone") arrow.r cal(Z), upright("bus"): cal(G) arrow.r cal(U), upright("technology"): cal(G) arrow.r cal(E)$, `connection` is `absent` where the data has no row / $cal(S)$: index $s$ --- `season` with $upright("season"): cal(T) arrow.r cal(S)$ +/ $cal(I)$: index $i$ --- `site`, $cal(I) subset.eq cal(U) times cal(G)$ / $cal(T)$: index $t$ --- `snapshot` (`int` coordinates) with $upright("gen_zone") subset.eq cal(G) times cal(T), upright("zone"): upright("gen_zone") arrow.r cal(Z), upright("rep"): cal(T) arrow.r cal(T), upright("season"): cal(T) arrow.r cal(S)$ / $cal(E)$: index $e$ --- `technology` with $upright("technology"): cal(G) arrow.r cal(E)$ / $cal(Z)$: index $z$ --- `zone` (labels `north`, `south`) with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("zone"): upright("gen_zone") arrow.r cal(Z)$, `bus[area]` is `absent` where the data gives no label @@ -19,6 +21,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 / $upright("bp_x")$: `bp_x` over $cal(B) times cal(G)$, $0$ where the data has no row / $upright("bp_y")$: `bp_y` over $cal(B) times cal(G)$, $0$ where the data has no row / $upright("budget")$: `budget` (scalar) +/ $upright("corridor_cap")$: `corridor_cap` over $cal(C)$ / $upright("cost")$: `cost` over $cal(G)$, $0$ where the data has no row / $upright("eta")$: `eta` over $cal(G)$ / $upright("growth")$: `growth` (scalar) @@ -44,6 +47,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 / $italic("op_cost")$: `op_cost` over $cal(G) times cal(T)$ / $p$: `p` over $cal(G) times cal(T)$ / $italic("reserve")$: `reserve` (scalar) +/ $italic("site_out")$: `site_out` over $cal(I) times cal(T)$ / $italic("slack")$: `slack` over $cal(T)$ / $italic("spare")$: `spare` over $cal(G)$ / $italic("spill")$: `spill` over $cal(T)$ @@ -83,6 +87,7 @@ $ upright("fuel") & italic("fuel")_(g,t) & >= 0 & forall g in cal(G), t in cal(T upright("op_cost") & italic("op_cost")_(g,t) & >= 0 & forall g in cal(G), t in cal(T) \ upright("p") & upright("p")^(upright("min"))_(g) <= p_(g,t) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) colon upright("p")^(upright("max"))_(g) > 0 and not upright("is_flexible")_(g) or upright("p")^(upright("min"))_(g) > 0 \ upright("reserve") & italic("reserve") & >= 0 \ + upright("site_out") & italic("site_out")_(i,t) & >= 0 & forall i in cal(I), t in cal(T) colon upright("is_flexible")_(upright("generator")(i)) \ upright("slack") & italic("slack")_(t) & <= 100 & forall t in cal(T) \ upright("spare") & italic("spare")_(g) & in ZZ & forall g in cal(G) \ upright("spill") & italic("spill")_(t) & >= 0 & forall t in cal(T) \ diff --git a/tools/notation.py b/tools/notation.py index c47c76ceb..e46864210 100644 --- a/tools/notation.py +++ b/tools/notation.py @@ -65,6 +65,7 @@ 'p': 'Lower and upper bounds', 'spill': 'Lower bound only', 'slack': 'Upper bound only', + 'site_out': 'Variable over a dimension with members', 'theta': 'Unbounded variable', 'on': 'Binary domain', 'units': 'Bounded integer domain', From 3be1b193da95ceba7e2032242e32385ee0cf2962 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 16:32:46 +0000 Subject: [PATCH 02/11] docs(changelog): the tuple-dimension line links #1017 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fb91e95b..dd07fef7d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## Upcoming version -- feat(language): a dimension lists its members ([#0000](https://github.com/energy-models/mathspec/pull/0000)) +- feat(language): a dimension lists its members ([#1017](https://github.com/energy-models/mathspec/pull/1017)) - feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) - Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a map under `maps:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[map]`, such as `generator[bus]`. - Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[map]`. From ce4c86e00b4486d7a50972eaf104068db5923b6f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 17:51:27 +0000 Subject: [PATCH 03/11] Merge feat/dimension-alias into feat/maps-tuple-dimensions The TIMES trade example in this PR's spelling: top_ire is a dimension over the two aliases and the two plain dimensions, and ire_flo, trade_cost and export are over it. capacity.yaml keeps its relations: rtp_vintyr has an ordered member, which a tuple dimension cannot step along. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- docs/examples/times/trade.md | 50 +++++++++++++++++------------------- examples/symbols/trade.yaml | 1 + examples/times/trade.yaml | 20 +++++---------- 3 files changed, 31 insertions(+), 40 deletions(-) diff --git a/docs/examples/times/trade.md b/docs/examples/times/trade.md index 637308a85..a61e37d5d 100644 --- a/docs/examples/times/trade.md +++ b/docs/examples/times/trade.md @@ -13,13 +13,14 @@ which TIMES writes with a second name for each set, `ALIAS(REG,R)` in The spec does the same with an [alias](../../reference/language/dimensions.md#alias): `from_region` has the labels of `region`, and `from_commodity` those of -`commodity`. The relation `top_ire` lists the links that exist, and -`ire_flo`, `trade_cost` and `export` exist only at its rows. The data of +`commodity`. The dimension `top_ire` lists the links that exist, each a tuple of its four +members, and `ire_flo`, `trade_cost` and `export` are over it, so a data row at +a link that does not exist is refused. The data of `ire_flo` has the four columns that the TIMES data already has, and no label is invented. -`balance` adds the imports of each region and commodity over the far end of -each link. It reads the exports at the near end: it sums them to each +`balance` adds the imports of each region and commodity through the members +`region` and `commodity` of each link. It sums the exports to each `from_region` and `from_commodity`, and reads those back onto `region` and `commodity` through the map of each alias. @@ -37,31 +38,25 @@ dimensions: commodity: { description: an energy carrier or a material } from_region: { alias: region, description: the region an export leaves } from_commodity: { alias: commodity, description: the commodity an export leaves as } - -relations: top_ire: description: the links that exist, from a region and commodity to another (TOP_IRE) - dims: [from_region, from_commodity, region, commodity] - missing: absent + over: [from_region, from_commodity, region, commodity] parameters: ire_flo: description: the share of an export that arrives as an import (IRE_FLO) - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] demand: { dims: [commodity, region], description: what a region needs of a commodity } supply_cost: { dims: [commodity, region], description: the cost of a unit produced in a region } trade_cost: description: the cost of a unit exported along a link - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] variables: supply: { dims: [commodity, region], bounds: { lower: 0 }, description: what a region produces of a commodity } export: description: what leaves along a link (VAR_IRE) - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] bounds: { lower: 0 } constraints: @@ -70,9 +65,9 @@ constraints: dims: [commodity, region] expression: >- supply - + sum(ire_flo * export, over=[from_region, from_commodity]) - - sum(sum(sum(export, over=[region, commodity]), over=from_region, by=from_region[region]), - over=from_commodity, by=from_commodity[commodity]) + + sum(ire_flo * export, over=top_ire, by=top_ire[commodity, region]) + - sum(sum(sum(export, over=top_ire, by=top_ire[from_commodity, from_region]), + over=from_region, by=from_region[region]), over=from_commodity, by=from_commodity[commodity]) >= demand objective: @@ -86,25 +81,26 @@ Trade between regions from TIMES: IRE\_FLO, the efficiency of a flow from one re | Symbol | Meaning | |---|---| -| $`\mathcal{C}`$ | index $`c`$ — `commodity` with $`\mathrm{top\_ire} \subseteq \mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, `top_ire` is `absent` where the data has no row — an energy carrier or a material | -| $`\mathcal{C}`$ | index $`c'`$ — `from_commodity`, an alias of `commodity` with $`\mathrm{top\_ire} \subseteq \mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, `top_ire` is `absent` where the data has no row — the commodity an export leaves as | -| $`\mathcal{R}`$ | index $`r'`$ — `from_region`, an alias of `region` with $`\mathrm{top\_ire} \subseteq \mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, `top_ire` is `absent` where the data has no row — the region an export leaves | -| $`\mathcal{R}`$ | index $`r`$ — `region` with $`\mathrm{top\_ire} \subseteq \mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, `top_ire` is `absent` where the data has no row — a region of the model | +| $`\mathcal{C}`$ | index $`c`$ — `commodity` — an energy carrier or a material | +| $`\mathcal{C}`$ | index $`c'`$ — `from_commodity`, an alias of `commodity` — the commodity an export leaves as | +| $`\mathcal{R}`$ | index $`r'`$ — `from_region`, an alias of `region` — the region an export leaves | +| $`\mathcal{R}`$ | index $`r`$ — `region` — a region of the model | +| $`\mathcal{L}`$ | index $`l`$ — `top_ire`, $`\mathcal{L} \subseteq \mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$ — the links that exist, from a region and commodity to another (TOP\_IRE) | #### Parameters | Symbol | Meaning | |---|---| | $`\mathrm{demand}`$ | `demand` over $`\mathcal{C} \times \mathcal{R}`$ — what a region needs of a commodity | -| $`\mathrm{ire\_flo}`$ | `ire_flo` over $`\mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, only where $`\left( c,\ c',\ r',\ r \right) \in \mathrm{top\_ire}`$ — the share of an export that arrives as an import (IRE\_FLO) | +| $`\mathrm{ire\_flo}`$ | `ire_flo` over $`\mathcal{L}`$ — the share of an export that arrives as an import (IRE\_FLO) | | $`\mathrm{supply}^{\mathrm{cost}}`$ | `supply_cost` over $`\mathcal{C} \times \mathcal{R}`$ — the cost of a unit produced in a region | -| $`\mathrm{trade\_cost}`$ | `trade_cost` over $`\mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$, only where $`\left( c,\ c',\ r',\ r \right) \in \mathrm{top\_ire}`$ — the cost of a unit exported along a link | +| $`\mathrm{trade\_cost}`$ | `trade_cost` over $`\mathcal{L}`$ — the cost of a unit exported along a link | #### Variables | Symbol | Meaning | |---|---| -| $`\mathit{export}`$ | `export` over $`\mathcal{C} \times \mathcal{C} \times \mathcal{R} \times \mathcal{R}`$ — what leaves along a link (VAR\_IRE) | +| $`\mathit{export}`$ | `export` over $`\mathcal{L}`$ — what leaves along a link (VAR\_IRE) | | $`\mathit{supply}`$ | `supply` over $`\mathcal{C} \times \mathcal{R}`$ — what a region produces of a commodity | #### Variable domains @@ -112,7 +108,7 @@ Trade between regions from TIMES: IRE\_FLO, the efficiency of a flow from one re **`export`** ```math -\mathit{export}_{c,c',r',r} \ge 0 \qquad \forall\, c \in \mathcal{C},\ c' \in \mathcal{C},\ r' \in \mathcal{R},\ r \in \mathcal{R} \,:\, \left( c,\ c',\ r',\ r \right) \in \mathrm{top\_ire} +\mathit{export}_{l} \ge 0 \qquad \forall\, l \in \mathcal{L} ``` **`supply`** @@ -124,7 +120,7 @@ Trade between regions from TIMES: IRE\_FLO, the efficiency of a flow from one re #### Objective ```math -\min \sum_{c \in \mathcal{C},\ r \in \mathcal{R}} \mathrm{supply}^{\mathrm{cost}}_{c,r} \cdot \mathit{supply}_{c,r} + \sum_{c \in \mathcal{C},\ c' \in \mathcal{C},\ r' \in \mathcal{R},\ r \in \mathcal{R}} \mathrm{trade\_cost}_{c,c',r',r} \cdot \mathit{export}_{c,c',r',r} +\min \sum_{c \in \mathcal{C},\ r \in \mathcal{R}} \mathrm{supply}^{\mathrm{cost}}_{c,r} \cdot \mathit{supply}_{c,r} + \sum_{l \in \mathcal{L}} \mathrm{trade\_cost}_{l} \cdot \mathit{export}_{l} ``` #### Subject to @@ -132,6 +128,6 @@ Trade between regions from TIMES: IRE\_FLO, the efficiency of a flow from one re **`balance`** ```math -\mathit{supply}_{c,r} + \sum_{c' \in \mathcal{C},\ r' \in \mathcal{R}} \mathrm{ire\_flo}_{c,c',r',r} \cdot \mathit{export}_{c,c',r',r} - \left( \sum_{c' \in \mathcal{C} \,:\, c' = c} \sum_{r' \in \mathcal{R} \,:\, r' = r} \sum_{c'' \in \mathcal{C},\ r'' \in \mathcal{R}} \mathit{export}_{c'',c',r',r''} \right) \ge \mathrm{demand}_{c,r} \qquad \forall\, c \in \mathcal{C},\ r \in \mathcal{R} +\mathit{supply}_{c,r} + \sum_{l \in \mathcal{L} \,:\, \mathrm{commodity}(l) = c \wedge \mathrm{region}(l) = r} \mathrm{ire\_flo}_{l} \cdot \mathit{export}_{l} - \left( \sum_{c' \in \mathcal{C} \,:\, c' = c} \sum_{r' \in \mathcal{R} \,:\, r' = r} \sum_{l \in \mathcal{L} \,:\, \mathrm{from\_commodity}(l) = c' \wedge \mathrm{from\_region}(l) = r'} \mathit{export}_{l} \right) \ge \mathrm{demand}_{c,r} \qquad \forall\, c \in \mathcal{C},\ r \in \mathcal{R} ``` diff --git a/examples/symbols/trade.yaml b/examples/symbols/trade.yaml index 87702bf96..be2c73ef9 100644 --- a/examples/symbols/trade.yaml +++ b/examples/symbols/trade.yaml @@ -7,3 +7,4 @@ notation: latex dimensions: region: { index: r, set: '\mathcal{R}' } commodity: { index: c, set: '\mathcal{C}' } + top_ire: { index: l, set: '\mathcal{L}' } diff --git a/examples/times/trade.yaml b/examples/times/trade.yaml index fdbfeee88..046e0481d 100644 --- a/examples/times/trade.yaml +++ b/examples/times/trade.yaml @@ -11,31 +11,25 @@ dimensions: commodity: { description: an energy carrier or a material } from_region: { alias: region, description: the region an export leaves } from_commodity: { alias: commodity, description: the commodity an export leaves as } - -relations: top_ire: description: the links that exist, from a region and commodity to another (TOP_IRE) - dims: [from_region, from_commodity, region, commodity] - missing: absent + over: [from_region, from_commodity, region, commodity] parameters: ire_flo: description: the share of an export that arrives as an import (IRE_FLO) - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] demand: { dims: [commodity, region], description: what a region needs of a commodity } supply_cost: { dims: [commodity, region], description: the cost of a unit produced in a region } trade_cost: description: the cost of a unit exported along a link - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] variables: supply: { dims: [commodity, region], bounds: { lower: 0 }, description: what a region produces of a commodity } export: description: what leaves along a link (VAR_IRE) - dims: [from_region, from_commodity, region, commodity] - where: top_ire + dims: [top_ire] bounds: { lower: 0 } constraints: @@ -44,9 +38,9 @@ constraints: dims: [commodity, region] expression: >- supply - + sum(ire_flo * export, over=[from_region, from_commodity]) - - sum(sum(sum(export, over=[region, commodity]), over=from_region, by=from_region[region]), - over=from_commodity, by=from_commodity[commodity]) + + sum(ire_flo * export, over=top_ire, by=top_ire[commodity, region]) + - sum(sum(sum(export, over=top_ire, by=top_ire[from_commodity, from_region]), + over=from_region, by=from_region[region]), over=from_commodity, by=from_commodity[commodity]) >= demand objective: From 16f558c7c7863f9b0bea3219d234a3ce74681e00 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 19:52:09 +0000 Subject: [PATCH 04/11] Merge feat/dimension-alias into feat/maps-tuple-dimensions sparse.yaml in this PR's spelling: connection is a dimension over unit and port, capacity is read through at(), the sum per unit groups by the member, and active stays a relation because ramp_up steps along its ordered member. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- docs/examples/sparse.md | 44 ++++++++++++++++++++--------------------- examples/sparse.yaml | 17 +++++++--------- 2 files changed, 29 insertions(+), 32 deletions(-) diff --git a/docs/examples/sparse.md b/docs/examples/sparse.md index 0581da6cd..7dafc8c7e 100644 --- a/docs/examples/sparse.md +++ b/docs/examples/sparse.md @@ -17,9 +17,11 @@ the sets in one way: - `balance` sums over every row of `connection`, grouped by the bus each port feeds. -`efficiency` and `flow` exist only where `connection` lists a port, so -`missing: 1` fills only those ports, and a data row for a port that -`connection` does not list is dropped. +`connection` is a dimension whose labels are the pairs of a unit and a port. +`efficiency` and `flow` are over it, so `missing: 1` fills only the ports it +lists, and a data row for a port it does not list is refused. `active` has the +ordered member `period`, along which `ramp_up` steps, so it stays a relation +that `output` reads in its `where:`. [#1019](https://github.com/energy-models/mathspec/issues/1019) compares how three designs for sparse sets write this spec. @@ -34,12 +36,9 @@ dimensions: port: { description: an output of a unit } bus: { description: a node of the network } period: { dtype: int, ordered: true, description: a step of the horizon } + connection: { over: [unit, port], description: the ports a unit has } relations: - connection: - description: the ports a unit has - dims: [unit, port] - missing: absent active: description: the periods a unit runs in dims: [unit, period] @@ -50,24 +49,24 @@ maps: bus: { dim: bus, description: the bus a port feeds } parameters: - efficiency: { dims: [unit, port, period], where: connection, missing: 1, description: share of the output a port delivers } + efficiency: { dims: [connection, period], missing: 1, description: share of the output a port delivers } capacity: { dims: [unit], description: the most a unit produces in a period } ramp: { dims: [unit], description: the most a unit's output rises from one period to the next } load: { dims: [bus, period], description: demand to be met } variables: output: { dims: [unit, period], where: active, bounds: { lower: 0 }, description: what a unit produces } - flow: { dims: [unit, port, period], where: connection, bounds: { lower: 0 }, description: what a port takes of it } + flow: { dims: [connection, period], bounds: { lower: 0 }, description: what a port takes of it } constraints: port_limit: description: a port takes no more than the unit's capacity - dims: [unit, port, period] - expression: flow <= capacity + dims: [connection, period] + expression: flow <= at(capacity, by=connection[unit]) split: description: the ports of a unit take what it produces dims: [unit, period] - expression: sum(flow, over=port) == output + expression: sum(flow, over=connection, by=connection[unit]) == output ramp_up: description: output rises by at most the ramp from one active period to the next dims: [unit, period] @@ -75,7 +74,7 @@ constraints: balance: description: what the ports deliver to a bus meets its load dims: [bus, period] - expression: sum(efficiency * flow, over=[unit, port], by=connection[bus]) >= load + expression: sum(efficiency * flow, over=connection, by=connection[bus]) >= load objective: sense: minimize @@ -88,17 +87,18 @@ Units that feed buses through the ports they have, and run only in the periods t | Symbol | Meaning | |---|---| -| $`\mathcal{B}`$ | index $`b`$ — `bus` with $`\mathrm{bus}: \mathrm{connection} \to \mathcal{B}`$ — a node of the network | +| $`\mathcal{B}`$ | index $`b`$ — `bus` with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B}`$ — a node of the network | +| $`\mathcal{C}`$ | index $`c`$ — `connection`, $`\mathcal{C} \subseteq \mathcal{O} \times \mathcal{U}`$ with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B}`$ — the ports a unit has | | $`\mathcal{T}`$ | index $`t`$ — `period` with $`\mathrm{active} \subseteq \mathcal{T} \times \mathcal{U}`$, `active` is `absent` where the data has no row — a step of the horizon | -| $`\mathcal{O}`$ | index $`o`$ — `port` with $`\mathrm{connection} \subseteq \mathcal{O} \times \mathcal{U},\ \mathrm{bus}: \mathrm{connection} \to \mathcal{B}`$, `connection` is `absent` where the data has no row — an output of a unit | -| $`\mathcal{U}`$ | index $`u`$ — `unit` with $`\mathrm{active} \subseteq \mathcal{T} \times \mathcal{U},\ \mathrm{connection} \subseteq \mathcal{O} \times \mathcal{U},\ \mathrm{bus}: \mathrm{connection} \to \mathcal{B}`$, `active` is `absent` where the data has no row, `connection` is `absent` where the data has no row — a converter | +| $`\mathcal{O}`$ | index $`o`$ — `port` — an output of a unit | +| $`\mathcal{U}`$ | index $`u`$ — `unit` with $`\mathrm{active} \subseteq \mathcal{T} \times \mathcal{U}`$, `active` is `absent` where the data has no row — a converter | #### Parameters | Symbol | Meaning | |---|---| | $`\mathrm{capacity}`$ | `capacity` over $`\mathcal{U}`$ — the most a unit produces in a period | -| $`\mathrm{efficiency}`$ | `efficiency` over $`\mathcal{T} \times \mathcal{O} \times \mathcal{U}`$, only where $`\left( o,\ u \right) \in \mathrm{connection}`$, $`1`$ where the data has no row — share of the output a port delivers | +| $`\mathrm{efficiency}`$ | `efficiency` over $`\mathcal{C} \times \mathcal{T}`$, $`1`$ where the data has no row — share of the output a port delivers | | $`\mathrm{load}`$ | `load` over $`\mathcal{B} \times \mathcal{T}`$ — demand to be met | | $`\mathrm{ramp}`$ | `ramp` over $`\mathcal{U}`$ — the most a unit's output rises from one period to the next | @@ -106,7 +106,7 @@ Units that feed buses through the ports they have, and run only in the periods t | Symbol | Meaning | |---|---| -| $`\mathit{flow}`$ | `flow` over $`\mathcal{T} \times \mathcal{O} \times \mathcal{U}`$ — what a port takes of it | +| $`\mathit{flow}`$ | `flow` over $`\mathcal{C} \times \mathcal{T}`$ — what a port takes of it | | $`\mathit{output}`$ | `output` over $`\mathcal{T} \times \mathcal{U}`$ — what a unit produces | #### Variable domains @@ -114,7 +114,7 @@ Units that feed buses through the ports they have, and run only in the periods t **`flow`** ```math -\mathit{flow}_{t,o,u} \ge 0 \qquad \forall\, t \in \mathcal{T},\ o \in \mathcal{O},\ u \in \mathcal{U} \,:\, \left( o,\ u \right) \in \mathrm{connection} +\mathit{flow}_{c,t} \ge 0 \qquad \forall\, c \in \mathcal{C},\ t \in \mathcal{T} ``` **`output`** @@ -134,13 +134,13 @@ Units that feed buses through the ports they have, and run only in the periods t **`balance`** ```math -\sum_{o \in \mathcal{O},\ u \in \mathcal{U} \,:\, \mathrm{bus}(o,\ u) = b} \mathrm{efficiency}_{t,o,u} \cdot \mathit{flow}_{t,o,u} \ge \mathrm{load}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T} +\sum_{c \in \mathcal{C} \,:\, \mathrm{bus}(c) = b} \mathrm{efficiency}_{c,t} \cdot \mathit{flow}_{c,t} \ge \mathrm{load}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T} ``` **`port_limit`** ```math -\mathit{flow}_{t,o,u} \le \mathrm{capacity}_{u} \qquad \forall\, t \in \mathcal{T},\ o \in \mathcal{O},\ u \in \mathcal{U} +\mathit{flow}_{c,t} \le \mathrm{capacity}_{\mathrm{unit}(c)} \qquad \forall\, c \in \mathcal{C},\ t \in \mathcal{T} ``` **`ramp_up`** @@ -152,6 +152,6 @@ Units that feed buses through the ports they have, and run only in the periods t **`split`** ```math -\sum_{o \in \mathcal{O}} \mathit{flow}_{t,o,u} = \mathit{output}_{t,u} \qquad \forall\, t \in \mathcal{T},\ u \in \mathcal{U} +\sum_{c \in \mathcal{C} \,:\, \mathrm{unit}(c) = u} \mathit{flow}_{c,t} = \mathit{output}_{t,u} \qquad \forall\, t \in \mathcal{T},\ u \in \mathcal{U} ``` diff --git a/examples/sparse.yaml b/examples/sparse.yaml index 3bdd33b1d..0dc4722cc 100644 --- a/examples/sparse.yaml +++ b/examples/sparse.yaml @@ -11,12 +11,9 @@ dimensions: port: { description: an output of a unit } bus: { description: a node of the network } period: { dtype: int, ordered: true, description: a step of the horizon } + connection: { over: [unit, port], description: the ports a unit has } relations: - connection: - description: the ports a unit has - dims: [unit, port] - missing: absent active: description: the periods a unit runs in dims: [unit, period] @@ -27,24 +24,24 @@ maps: bus: { dim: bus, description: the bus a port feeds } parameters: - efficiency: { dims: [unit, port, period], where: connection, missing: 1, description: share of the output a port delivers } + efficiency: { dims: [connection, period], missing: 1, description: share of the output a port delivers } capacity: { dims: [unit], description: the most a unit produces in a period } ramp: { dims: [unit], description: the most a unit's output rises from one period to the next } load: { dims: [bus, period], description: demand to be met } variables: output: { dims: [unit, period], where: active, bounds: { lower: 0 }, description: what a unit produces } - flow: { dims: [unit, port, period], where: connection, bounds: { lower: 0 }, description: what a port takes of it } + flow: { dims: [connection, period], bounds: { lower: 0 }, description: what a port takes of it } constraints: port_limit: description: a port takes no more than the unit's capacity - dims: [unit, port, period] - expression: flow <= capacity + dims: [connection, period] + expression: flow <= at(capacity, by=connection[unit]) split: description: the ports of a unit take what it produces dims: [unit, period] - expression: sum(flow, over=port) == output + expression: sum(flow, over=connection, by=connection[unit]) == output ramp_up: description: output rises by at most the ramp from one active period to the next dims: [unit, period] @@ -52,7 +49,7 @@ constraints: balance: description: what the ports deliver to a bus meets its load dims: [bus, period] - expression: sum(efficiency * flow, over=[unit, port], by=connection[bus]) >= load + expression: sum(efficiency * flow, over=connection, by=connection[bus]) >= load objective: sense: minimize From 0cbb7fabd94237103bad7f6bba014433b7e083c1 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 19:48:52 +0000 Subject: [PATCH 05/11] feat(language): a member shared by two dimensions of one frame is refused A dims: list reaches each member once. Two dimensions that share a member, or a dimension beside one of its own members, are refused at load, in place of the cross product they meant. The message names the shared member and the rewrite: one of the two with a where: through a relation, or an alias. The same holds for a piecewise entry's dims:. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- docs/about/limits.md | 1 + docs/reference/language/dimensions.md | 40 ++++++++++------ src/mathspec/_validation.py | 31 +++++++++++++ tests/test_tuple_dimensions.py | 40 +++++++++------- tests/test_validation.py | 66 +++++++++++++++++++++++++++ 5 files changed, 147 insertions(+), 31 deletions(-) diff --git a/docs/about/limits.md b/docs/about/limits.md index f40eae114..965d5ec19 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -117,6 +117,7 @@ same thing. | Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | | A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | | Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a map](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that map: `at(capacity, by=connection[unit])`. | +| Two dimensions in one `dims:` that share a member, or a dimension beside its own member, read as their cross product | A tool may store each dimension as the columns of its members, so the shared member would index the entry twice. | One of the two in `dims:`, and a `where:` that reads a relation through the shared member, or an alias of the member: `site: { over: [from_unit, bus] }`. | | An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` a bare relation that lists the tuples. The construct then steps along an ordered member. | | A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index 1653f82da..0feb91e2d 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -256,19 +256,31 @@ Constraint 'limit': an operand over ['unit'] meets one over 'connection'. 'unit' mathspec suggests the lookup through the map of the member, or the sum of `flow` to the member. The same refusal applies wherever the two operands meet: in a product, in a sum, and in the objective, as in -`sum(flow * capacity)`. An entry over both, such as a variable over -`[connection, unit]`, loads. - -mathspec refuses the meeting unless the `dims:` of the entry lists both the -dimension and the member. Then the two operands meet as their cross product, -at every pair of a connection and a unit. With -`dims: [connection, unit, snapshot]`, `flow <= capacity` loads, with one row -for each connection, unit and snapshot. Inside a `sum`, a dimension that the -`sum` adds up is not in the `dims:` of the entry, so -`sum(flow * capacity, over=unit)` is refused in that entry too. The objective -and an [assumption](assumptions.md) have no `dims:`, so mathspec refuses -the meeting in each of them. It also refuses the meeting in the `where:` of a -`piecewise:` entry, because mathspec repeats that condition in assumptions. +`sum(flow * capacity)`, in an [assumption](assumptions.md), and in the +`where:` of a `piecewise:` entry. + +### Each member once in `dims:` + +A tool may store a dimension with members as the columns of its members. So a +`dims:` list reaches each member once. mathspec refuses two dimensions in one +`dims:` that share a member, and a dimension beside one of its own members. +With `site: { over: [unit, bus] }` and `dims: [connection, site, snapshot]`, +mathspec prints: + +```text +Variable 'flow': 'connection' and 'site' in dims: share the member 'unit', so the entry would be indexed by 'unit' twice. Keep 'connection' in dims:, list ['bus'] beside it, and confine the entry with where: "at(, by=connection[unit])", where is a relation over ['bus', 'unit'] that lists the tuples of 'site'. Or declare an alias of 'unit', such as from_unit: {alias: unit}, and list it in 'site' in place of 'unit', so the members differ. +``` + +With `dims: [connection, unit, snapshot]`, mathspec prints: + +```text +Variable 'flow': 'connection' and 'unit' in dims: share the member 'unit', so the entry would be indexed by 'unit' twice. Delete 'unit' from dims: and read it as connection[unit], or declare an alias of 'unit', such as from_unit: {alias: unit}, and list it in place of 'unit'. +``` + +The refusal applies to every `dims:` list: a parameter, a variable, a +constraint, a named expression, a given entry and a `piecewise:` entry. A +different unit at each connection is an alias of `unit`, which is a member of +its own. A sum over a member is refused the same way. With `sum(flow, over=unit)`, mathspec prints: @@ -292,7 +304,7 @@ At load, mathspec also refuses each of these, and prints the rewrite: | `ordered: true`, `dtype:` or `one_of:` beside `over:` | the key on a member | | `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` along the dimension | an entry over the members, with `where:` a relation that lists the tuples | | a comparison of the dimension with a label, as in `connection == 'a'` | a comparison of a member, as in `connection[unit] == 'u1'` | -| a call through a member on an operand over both the dimension and that member | the member summed out of the operand first | +| two dimensions in one `dims:` that share a member, or a dimension beside its own member | [one of the two, and a `where:`, or an alias](#each-member-once-in-dims) | A set of tuples with an ordered member, such as the periods in which each unit is active, therefore stays a [bare relation](relations.md) over `unit` and diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index f8685dabc..122c19ec1 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -198,6 +198,36 @@ def _frame_dimensions(spec: Spec) -> Iterator[str]: for d, count in Counter(dims).items() if count > 1 ) + yield from _shared_members(kind, name, dims, spec) + + +def _shared_members(kind: str, name: str, dims: Iterable[str], spec: Spec) -> Iterator[str]: + """A frame reaches each member once, so a later reading of a tuple dimension by its members means the same. + + A plain dimension counts as its own member. + """ + carriers: dict[str, list[str]] = {} + for d in dict.fromkeys(dims): + if d in spec.dimensions: + for member in [dim for _, dim in spec.dimensions[d].members] or [d]: + carriers.setdefault(member, []).append(d) + for member, (one, other, *_) in ((m, c) for m, c in carriers.items() if len(c) > 1): + head = f"{kind} '{name}': '{one}' and '{other}' in dims: share the member '{member}'" + alias = f'declare an alias of {member!r}, such as from_{member}: {{alias: {member}}}' + if member in (one, other): + tup = other if member == one else one + yield ( + f"{head}, so the entry would be indexed by '{member}' twice. Delete '{member}' from dims: and " + f'read it as {tup}[{member}], or {alias}, and list it in place of {member!r}.' + ) + continue + rest = sorted({dim for _, dim in spec.dimensions[other].members} - {member}) + yield ( + f"{head}, so the entry would be indexed by '{member}' twice. Keep '{one}' in dims:, list {rest} " + f'beside it, and confine the entry with where: "at(, by={one}[{member}])", where ' + f" is a relation over {sorted({member, *rest})} that lists the tuples of '{other}'. Or " + f"{alias}, and list it in '{other}' in place of {member!r}, so the members differ." + ) def _members(spec: Spec) -> Iterator[str]: @@ -438,6 +468,7 @@ def _piecewise_references(spec: Spec) -> Iterator[str]: ) if len(set(pw.dims)) != len(pw.dims): yield f'{context}: dims repeats a dimension: {list(pw.dims)}. Write each dimension once.' + yield from _shared_members('piecewise', name, pw.dims, spec) for key, link in pw.links.items(): yield from _piecewise_link_shape(spec, name, pw, key, link) if pw.activity is None: diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py index 033ef97ed..bdbb75782 100644 --- a/tests/test_tuple_dimensions.py +++ b/tests/test_tuple_dimensions.py @@ -47,7 +47,6 @@ 'variables': { 'flow': {'dims': ['connection', 'snapshot'], 'bounds': {'lower': 0}}, 'shipped': {'dims': ['trade'], 'bounds': {'lower': 0}}, - 'both': {'dims': ['connection', 'unit']}, }, 'constraints': { 'limit': {'dims': ['connection', 'snapshot'], 'expression': 'flow <= at(capacity, by=connection[unit])'}, @@ -119,7 +118,6 @@ def test_missing_says_whether_the_full_product_is_required(missing): 'sum(flow, over=connection, by=connection[port]) >= 0', ['port', 'snapshot'], id='sum-to-a-member' ), pytest.param('sum(flow, over=connection) >= 0', ['snapshot'], id='sum-the-tuples-away'), - pytest.param('both <= capacity', ['connection', 'unit'], id='an-entry-over-the-dimension-and-a-member'), ], ) def test_a_member_is_read_as_a_map_of_the_dimension(expression, dims): @@ -136,15 +134,23 @@ def test_a_member_is_read_as_a_map_of_the_dimension(expression, dims): id='a-named-expression', ), pytest.param( - _constraint('sum(flow * capacity, over=snapshot) <= both', ['connection', 'unit']), + _constraint('sum(flow * capacity, over=snapshot) <= 1', ['connection', 'unit']), id='under-a-sum-that-keeps-both', ), - pytest.param({'variables.both.where': 'at(rating, by=connection[unit, port]) > capacity'}, id='a-condition'), + pytest.param( + { + 'variables.both': { + 'dims': ['connection', 'unit'], + 'where': 'at(rating, by=connection[unit, port]) > capacity', + } + }, + id='a-condition', + ), pytest.param( { 'constraints.probe': { 'dims': ['connection', 'unit'], - 'expression': 'both <= 1', + 'expression': 'at(rating, by=connection[unit, port]) <= capacity', 'where': 'at(rating, by=connection[unit, port]) > capacity', } }, @@ -191,9 +197,9 @@ def test_a_member_is_read_as_a_map_of_the_dimension(expression, dims): ), ], ) -def test_a_frame_over_the_dimension_and_its_member_takes_the_cross_product(patch): - """Rule 11 of #1011: where `dims:` declares both, a member operand meets the dimension, and the entry loads.""" - to_spec(varied(MODEL, **patch)) +def test_a_frame_over_the_dimension_and_its_member_is_refused(patch): + """Rule 11 of #1011 read these as the cross product; a later reading by member name would read them as a join.""" + assert "'connection' and 'unit' in dims: share the member 'unit'" in _refusal(**patch) def test_a_condition_compares_a_member_label(): @@ -307,11 +313,11 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): id='sos-of-type-2', ), pytest.param( - _constraint('at(both, by=connection[unit]) >= 0', ['connection']), + {'variables.both': {'dims': ['connection', 'unit']}} + | _constraint('at(both, by=connection[unit]) >= 0', ['connection']), ( - "at(by=connection[unit]) reads through 'connection'", - "carries both 'connection' and its member ['unit']", - "Sum ['unit'] out of the operand first", + "Variable 'both': 'connection' and 'unit' in dims: share the member 'unit'", + 'read it as connection[unit]', ), id='an-operand-with-the-tuple-and-a-member', ), @@ -371,12 +377,12 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): id='a-member-operand-meets-the-tuple-under-a-sum', ), pytest.param( - _constraint('sum(flow * capacity, over=unit) <= both', ['connection', 'unit', 'snapshot']), - ("meets one over 'connection'", 'at(capacity, by=connection[unit])'), + _constraint('sum(flow * capacity, over=unit) <= 1', ['connection', 'unit', 'snapshot']), + ("Constraint 'probe': 'connection' and 'unit' in dims: share the member 'unit'",), id='a-member-operand-meets-the-tuple-under-a-sum-over-the-member-the-frame-declares', ), pytest.param( - _constraint('sum(flow * capacity) <= both', ['connection', 'unit']), + _constraint('sum(flow * capacity) <= 1', ['connection', 'snapshot']), ("meets one over 'connection'", 'at(capacity, by=connection[unit])'), id='a-member-operand-meets-the-tuple-under-a-sum-over-everything', ), @@ -389,9 +395,9 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): { 'parameters.xs': {'dims': ['period']}, 'parameters.ys': {'dims': ['period']}, - 'variables.y': {'dims': ['connection', 'unit']}, + 'variables.y': {'dims': ['connection']}, 'piecewise.curve': { - 'dims': ['connection', 'unit'], + 'dims': ['connection'], 'along': 'period', 'links': {'x': ['y', 'xs'], 'y': ['y', 'ys']}, 'where': 'at(rating, by=connection[unit, port]) > capacity', diff --git a/tests/test_validation.py b/tests/test_validation.py index 327193671..aa2fe1d22 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -3545,3 +3545,69 @@ def test_a_divisor_a_shift_fills_with_zero_is_refused(divisor, patch): def test_a_divisor_a_shift_fills_with_another_value_loads(divisor): spec = to_spec(varied(SMALL_MODEL, **{'constraints.cap': {'dims': ['g'], 'expression': f'p / ({divisor}) <= 1'}})) assert 'cap' in spec.program.constraints + + +_SHARED_MEMBER: dict[str, Any] = { + 'dimensions': { + 'unit': {}, + 'port': {}, + 'bus': {}, + 'connection': {'over': ['unit', 'port']}, + 'site': {'over': ['unit', 'bus']}, + }, + 'variables': {'flow': {'dims': ['connection']}}, +} + + +@pytest.mark.parametrize( + ('patch', 'fragments'), + [ + pytest.param( + {'variables.pair': {'dims': ['connection', 'site']}}, + ( + "Variable 'pair': 'connection' and 'site' in dims: share the member 'unit'", + 'where: "at(, by=connection[unit])"', + "declare an alias of 'unit'", + ), + id='two-tuple-dimensions-in-a-variable', + ), + pytest.param( + {'constraints.pair': {'dims': ['connection', 'site'], 'expression': 'flow >= 0'}}, + ("Constraint 'pair': 'connection' and 'site' in dims: share the member 'unit'",), + id='two-tuple-dimensions-in-a-constraint', + ), + pytest.param( + {'parameters.rating': {'dims': ['connection', 'unit']}}, + ( + "Parameter 'rating': 'connection' and 'unit' in dims: share the member 'unit'", + 'read it as connection[unit]', + ), + id='a-tuple-dimension-beside-its-own-member', + ), + pytest.param( + { + 'dimensions.period': {'dtype': 'int', 'ordered': True}, + 'parameters.xs': {'dims': ['period']}, + 'parameters.ys': {'dims': ['period']}, + 'variables.w': {'dims': ['connection']}, + 'variables.v': {'dims': ['site']}, + 'piecewise.curve': { + 'dims': ['connection', 'site'], + 'along': 'period', + 'links': {'x': ['w', 'xs'], 'y': ['v', 'ys']}, + }, + }, + ("piecewise 'curve': 'connection' and 'site' in dims: share the member 'unit'",), + id='two-tuple-dimensions-in-a-piecewise-entry', + ), + ], +) +def test_a_member_shared_by_two_dimensions_of_one_frame_is_refused(patch, fragments): + """A tuple dimension is flat over its members, so two that share one would index an entry by it twice. + + The merged tree loaded both as their cross product, which a later reading by + name would turn into a join. + """ + message = _refusal(_SHARED_MEMBER, **patch) + for fragment in fragments: + assert fragment in message From a207fa5de5a99226d77adc94ab3fa28082fcc3c2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 19:50:27 +0000 Subject: [PATCH 06/11] docs(changelog): the strict tuple-dimension line links #9 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a67d9e65..0797b9f00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## Upcoming version +- feat(language): a dimension lists its members, strictly ([#9](https://github.com/fluxopt/mathspec/pull/9)) - feat(language): a dimension lists its members ([#1017](https://github.com/energy-models/mathspec/pull/1017)) - feat(language): a dimension may alias another's labels ([#1020](https://github.com/energy-models/mathspec/pull/1020)) - feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) From 9a32ef116732107be8ecd855798c47772599bb84 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 20:13:39 +0000 Subject: [PATCH 07/11] feat(language): a tuple dimension's bare name tests membership On an entry over every member, as plain dimensions, the bare name of a dimension with members keeps the coordinates whose member tuple it lists. It aligns nothing by name. An entry missing a member is refused with the frame rewrite. It prints as the tuple of the member indices. The shared-member and order refusals name the bare name as their rewrite. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- docs/about/limits.md | 2 +- docs/reference/language/dimensions.md | 56 ++++++++++++++----- docs/reference/language/expressions.md | 2 +- docs/reference/language/operators.md | 4 +- src/mathspec/_condition_resolver.py | 6 +- src/mathspec/_typesetting/walk.py | 10 ++++ src/mathspec/_validation.py | 5 +- src/mathspec/errors.py | 7 ++- src/mathspec/spec.py | 2 +- tests/test_canonical.py | 6 +- tests/test_tuple_dimensions.py | 77 +++++++++++++++++++++++++- tests/test_validation.py | 9 ++- 12 files changed, 151 insertions(+), 35 deletions(-) diff --git a/docs/about/limits.md b/docs/about/limits.md index 965d5ec19..a6d761331 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -118,7 +118,7 @@ same thing. | A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | | Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a map](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that map: `at(capacity, by=connection[unit])`. | | Two dimensions in one `dims:` that share a member, or a dimension beside its own member, read as their cross product | A tool may store each dimension as the columns of its members, so the shared member would index the entry twice. | One of the two in `dims:`, and a `where:` that reads a relation through the shared member, or an alias of the member: `site: { over: [from_unit, bus] }`. | -| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` a bare relation that lists the tuples. The construct then steps along an ordered member. | +| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` the bare name of the dimension. The construct then steps along an ordered member. | | A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | ### Data preparation diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index 0feb91e2d..b64338d19 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -268,7 +268,7 @@ With `site: { over: [unit, bus] }` and `dims: [connection, site, snapshot]`, mathspec prints: ```text -Variable 'flow': 'connection' and 'site' in dims: share the member 'unit', so the entry would be indexed by 'unit' twice. Keep 'connection' in dims:, list ['bus'] beside it, and confine the entry with where: "at(, by=connection[unit])", where is a relation over ['bus', 'unit'] that lists the tuples of 'site'. Or declare an alias of 'unit', such as from_unit: {alias: unit}, and list it in 'site' in place of 'unit', so the members differ. +Variable 'flow': 'connection' and 'site' in dims: share the member 'unit', so the entry would be indexed by 'unit' twice. Keep 'connection' in dims:, list ['bus'] beside it, and confine the entry with where: "at(site, by=connection[unit])". Or declare an alias of 'unit', such as from_unit: {alias: unit}, and list it in 'site' in place of 'unit', so the members differ. ``` With `dims: [connection, unit, snapshot]`, mathspec prints: @@ -297,20 +297,46 @@ tuple that the dimension does not list. A At load, mathspec also refuses each of these, and prints the rewrite: -| Refused | What you write instead | -| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| a member that has members of its own | the members themselves, in one list | -| a dimension twice, as in `over: [region, region]` | an [alias](#alias) of the dimension as one of the members | -| `ordered: true`, `dtype:` or `one_of:` beside `over:` | the key on a member | -| `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` along the dimension | an entry over the members, with `where:` a relation that lists the tuples | -| a comparison of the dimension with a label, as in `connection == 'a'` | a comparison of a member, as in `connection[unit] == 'u1'` | -| two dimensions in one `dims:` that share a member, or a dimension beside its own member | [one of the two, and a `where:`, or an alias](#each-member-once-in-dims) | - -A set of tuples with an ordered member, such as the periods in which each unit -is active, therefore stays a [bare relation](relations.md) over `unit` and -`period`. An entry over `unit` and `period` uses it as `where: active`, and an -entry over `connection` and `period` reads it as -`where: "at(active, by=connection[unit])"`. +| Refused | What you write instead | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| a member that has members of its own | the members themselves, in one list | +| a dimension twice, as in `over: [region, region]` | an [alias](#alias) of the dimension as one of the members | +| `ordered: true`, `dtype:` or `one_of:` beside `over:` | the key on a member | +| `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` along the dimension | an entry over the members, with `where:` the bare name of the dimension | +| a comparison of the dimension with a label, as in `connection == 'a'` | a comparison of a member, as in `connection[unit] == 'u1'` | +| two dimensions in one `dims:` that share a member, or a dimension beside its own member | [one of the two, and a `where:`, or an alias](#each-member-once-in-dims) | + +### The bare name in a condition + +The bare name of a dimension with members is true where the frame's member +labels form a tuple that the dimension lists. The entry must be over every +member, each as a plain dimension. A set of tuples with an ordered member, +such as the periods in which each unit is active, is a dimension that an entry +over its members tests: + +```yaml +dimensions: + active: { over: [unit, period] } +variables: + output: { dims: [unit, period], where: active } +constraints: + ramp_up: + dims: [unit, period] + where: active + expression: output - shift(output, along=period, offset=1) <= ramp +``` + +`output` has a column at each unit and period that `active` lists, and +`ramp_up` steps along the ordered member `period`. The typeset condition is +$`(p, u) \in \mathrm{active}`$, the tuple of the member indices. An entry over `connection` and +`period` reads the set through a member: `where: "at(active, by=connection[unit])"`. + +The test aligns nothing by name. An entry over `[unit]`, or over `[active]`, +does not have every member, so mathspec refuses `where: active` there: + +```text +Variable 'built': where-relation 'active' reads dims ['period'] outside the declared dims ['unit']. Add them to dims:, or test a name over the declared dims. +``` ### `missing` diff --git a/docs/reference/language/expressions.md b/docs/reference/language/expressions.md index c03a244aa..9f5df20d9 100644 --- a/docs/reference/language/expressions.md +++ b/docs/reference/language/expressions.md @@ -328,7 +328,7 @@ its entry. | `name` (bare) | variable | It is true where the variable exists | | `name` (bare) | relation | It is true where the relation has a row. A `missing: absent` relation has no row for some combinations ([`missing`](relations.md#missing)), and the bare name selects the combinations it lists | | `subject[map]` (bare) | map | It is true where the map gives the row of its subject a label. A `missing: absent` map gives some rows no label ([`missing`](relations.md#missing)) | -| `name` (bare) | dimension | mathspec refuses it at load | +| `name` (bare) | dimension | For a dimension with [members](dimensions.md#the-bare-name-in-a-condition), it is true where the tuple of the frame's member labels is listed. The entry must be over every member. mathspec refuses it on any other dimension | | `name` (bare) | named condition | It tests the [named condition](named.md#conditions). A given condition is true or false at each coordinate, as a `bool` parameter is | | `name OP value` | parameter | It compares element by element. A missing row with no `missing:` value compares false | | `name OP value` | dimension | It filters the frame's own coordinate column | diff --git a/docs/reference/language/operators.md b/docs/reference/language/operators.md index e0a87860e..46a731ea0 100644 --- a/docs/reference/language/operators.md +++ b/docs/reference/language/operators.md @@ -408,8 +408,8 @@ The typesetter prints each form from the smallest spec that uses it. | `sum(array, over=dim)` | $`\sum_{g \in \mathcal{G}} p_{g,t} \le \mathrm{limit}_{t} \qquad \forall\, t \in \mathcal{T}`$ | | `sum(array, over=[a, …])` | $`\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{c,g,t} \le \mathrm{limit}_{c} \qquad \forall\, c \in \mathcal{C}`$ | | `sum(array, over=dim, by=subject[m])` | $`\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = b} p_{g,t} \le \mathrm{limit}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ | -| `sum(array, over=dim, by=subject[m]), joining on the rest of the key` | $`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ e) = z} p_{g,e} \ge \mathrm{demand}_{e,z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z}`$ | -| `sum(array, over=[dim, …], by=subject[m, …])` | $`\sum_{g \in \mathcal{G},\ e \in \mathcal{E} \,:\, \mathrm{bus}(g,\ e) = b \wedge \mathrm{technology}(g,\ e) = t} p_{g,e} \le \mathrm{cap}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ | +| `sum(array, over=dim, by=subject[m]), joining on the rest of the key` | $`\sum_{o \in \mathcal{O} \,:\, \mathrm{period}(o) = e \wedge \mathrm{zone}(o) = z} p_{\mathrm{generator}(o),\mathrm{period}(o)} \ge \mathrm{demand}_{e,z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z}`$ | +| `sum(array, over=[dim, …], by=subject[m, …])` | $`\sum_{s \in \mathcal{S} \,:\, \mathrm{bus}(s) = b \wedge \mathrm{technology}(s) = t} p_{\mathrm{generator}(s),\mathrm{period}(s)} \le \mathrm{cap}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ | | `at(array, by=subject[m])` | $`p_{t} \le \mathrm{cap}_{\mathrm{period}(t)} \qquad \forall\, t \in \mathcal{T}`$ | | `at(array, by=subject[m]), two maps into one dimension` | $`f_{l} \le \mathrm{cap}_{\mathrm{bus0}(l)} \qquad \forall\, l \in \mathcal{L}`$ | | `shift(array, along=dim, offset=n)` | $`p_{t} \le p_{t - 1} \qquad \forall\, t \in \mathcal{T}`$ | diff --git a/src/mathspec/_condition_resolver.py b/src/mathspec/_condition_resolver.py index a0987f23a..c6595dcde 100644 --- a/src/mathspec/_condition_resolver.py +++ b/src/mathspec/_condition_resolver.py @@ -172,12 +172,12 @@ def _bare_name(self, node: NameNode) -> Condition | UnresolvedConditionNode: return node return ParameterDefined(node.name, ns.leaf_dims[node.name]) case 'dimension': - members = ns.spec.dimensions[node.name].members - compared = f"{node.name}[{members[0][0]}] == '...'" if members else f'{node.name} > 0' + if members := ns.spec.dimensions[node.name].members: + return RelationDefined(node.name, tuple(sorted(dim for _, dim in members))) self.errors.append( f"{context}: '{node.name}' is a dimension, and a bare dimension " f'name is true at every coordinate. ' - f'Remove it, or compare it: where: "{compared}".' + f'Remove it, or compare it: where: "{node.name} > 0".' ) case 'relation': shape = ns.relations[node.name] diff --git a/src/mathspec/_typesetting/walk.py b/src/mathspec/_typesetting/walk.py index 5b7f63dc1..ea19f1ce1 100644 --- a/src/mathspec/_typesetting/walk.py +++ b/src/mathspec/_typesetting/walk.py @@ -287,6 +287,14 @@ def _relation_row(self, name: str, at: Mapping[str, str], column: str | None = N return f'{self.format.apply(self.format.upright(column), key)} {self.format.prose(" is defined")}' return f'{self.format.parenthesise(key)} {self._op("in")} {self.format.upright(name)}' + def _tuple_listed(self, name: str, members: Iterable[str], ctx: _Context) -> str: + """That dimension *name* lists the tuple of the frame's indices of its *members*: ``(t, u) ∈ active``. + + The frame holds the members, not the dimension, so its key has no index here. + """ + key = self.format.joined([ctx.subscript(d) for d in members], '') + return f'{self.format.parenthesise(key)} {self._op("in")} {self.format.upright(name)}' + def _frame_key(self, name: str, ctx: _Context) -> dict[str, str]: """Table *name*'s key roles at the frame's own indices of their dimensions.""" lk = self.program.relations[name] @@ -564,6 +572,8 @@ def _boolean(self, node: Condition, ctx: _Context) -> tuple[str, int]: return self._boolean(node.operand.root, self._looked_up(node.columns, ctx)) if isinstance(node, RelationDefined): + if node.column is None and node.name in self.program.dimensions and self.program.dimensions[node.name].over: + return self._tuple_listed(node.name, node.dims, ctx), comparison return self._relation_row(node.name, self._frame_key(node.name, ctx), node.column), comparison if isinstance(node, Not): diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index 122c19ec1..4465886ad 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -224,9 +224,8 @@ def _shared_members(kind: str, name: str, dims: Iterable[str], spec: Spec) -> It rest = sorted({dim for _, dim in spec.dimensions[other].members} - {member}) yield ( f"{head}, so the entry would be indexed by '{member}' twice. Keep '{one}' in dims:, list {rest} " - f'beside it, and confine the entry with where: "at(, by={one}[{member}])", where ' - f" is a relation over {sorted({member, *rest})} that lists the tuples of '{other}'. Or " - f"{alias}, and list it in '{other}' in place of {member!r}, so the members differ." + f'beside it, and confine the entry with where: "at({other}, by={one}[{member}])". Or {alias}, and ' + f"list it in '{other}' in place of {member!r}, so the members differ." ) diff --git a/src/mathspec/errors.py b/src/mathspec/errors.py index ed5a4f5b7..10d677234 100644 --- a/src/mathspec/errors.py +++ b/src/mathspec/errors.py @@ -47,13 +47,14 @@ def unordered(context: str, construct: str, dimension: str, members: Iterable[tu """The refusal for *construct* reading the order of *dimension*, which is not declared ordered. A dimension with *members*, each a ``(role, dimension)``, cannot be - declared ordered, so its rewrite is the entry over the members. + declared ordered, so its rewrite is the entry over the members, confined + to the tuples by the bare name of the dimension. """ if over := sorted({dim for _, dim in members}): return ( f"{context}: {construct} reads the order of '{dimension}', which lists its members and so has no " - f'order. Declare the entry over {over}, with `where:` a relation that lists the tuples, and step ' - f'along a member that is declared ordered.' + f'order. Declare the entry over {over}, with `where: {dimension}`, and step along a member that is ' + f'declared ordered.' ) return ( f"{context}: {construct} reads the order of '{dimension}', which is not declared ordered, so the " diff --git a/src/mathspec/spec.py b/src/mathspec/spec.py index d70dee0a3..3b904dc45 100644 --- a/src/mathspec/spec.py +++ b/src/mathspec/spec.py @@ -421,7 +421,7 @@ def _members_or_labels(self) -> Self: if self.ordered: raise ValueError( f'`ordered: true` is on a dimension with `over:`, and a tuple of member labels has no order. ' - f'Declare the entry that steps over {members}, with `where:` a relation that lists the tuples, and ' + f'Declare the entry that steps over {members}, with `where:` the bare name of this dimension, and ' f'declare the member it steps along `ordered: true`.' ) for key in ('dtype', 'one_of'): diff --git a/tests/test_canonical.py b/tests/test_canonical.py index 76fb4fc14..8befb8a37 100644 --- a/tests/test_canonical.py +++ b/tests/test_canonical.py @@ -252,9 +252,9 @@ def test_the_order_a_macro_lists_its_keywords_in_is_no_difference(): pytest.param( raw_of(EXAMPLES / 'operators' / 'sum_by_column_lists.yaml'), 'constraints.slot_cap.expression', - 'sum(p, over=[generator, period], by=slot_of[bus, technology]) <= cap', - 'sum(p, over=[generator, period], by=slot_of[technology, bus]) <= cap', - id='the-columns-of-a-relation', + 'sum(at(p, by=slot_of[generator, period]), over=slot_of, by=slot_of[bus, technology]) <= cap', + 'sum(at(p, by=slot_of[period, generator]), over=slot_of, by=slot_of[technology, bus]) <= cap', + id='the-maps-of-a-tuple-dimension', ), pytest.param( DISPATCH_MODEL, diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py index bdbb75782..9f593a309 100644 --- a/tests/test_tuple_dimensions.py +++ b/tests/test_tuple_dimensions.py @@ -18,7 +18,7 @@ from mathspec._advising import advice from mathspec._typesetting import FORMATS, typeset from mathspec.errors import LanguageError -from mathspec.program import JoinedCondition, Relation, RelationComparison +from mathspec.program import JoinedCondition, Relation, RelationComparison, RelationDefined from tests.fixtures import varied #: The example of #1011: `connection` lists (unit, port) pairs and maps each to a @@ -202,6 +202,79 @@ def test_a_frame_over_the_dimension_and_its_member_is_refused(patch): assert "'connection' and 'unit' in dims: share the member 'unit'" in _refusal(**patch) +_SPAN = {'dimensions.span': {'over': ['unit', 'period']}} + + +@pytest.mark.parametrize( + ('patch', 'read'), + [ + pytest.param( + {'variables.built': {'dims': ['unit', 'period'], 'where': 'span'}}, + lambda spec: spec.program.variables['built'].where, + id='a-variable-where', + ), + pytest.param( + {'parameters.cost': {'dims': ['period', 'unit'], 'where': 'span'}}, + lambda spec: spec.program.parameters['cost'].where, + id='a-parameter-where', + ), + pytest.param( + { + 'variables.built': {'dims': ['unit', 'period']}, + 'constraints.probe': {'dims': ['unit', 'period'], 'expression': 'built >= 0', 'where': 'span'}, + }, + lambda spec: spec.program.constraints['probe'].where, + id='a-constraint-where', + ), + pytest.param( + {'conditions.on': 'span', 'variables.built': {'dims': ['unit', 'period'], 'where': 'on'}}, + lambda spec: spec.program.variables['built'].where, + id='a-named-condition', + ), + ], +) +def test_a_tuple_dimension_tests_membership_on_an_entry_over_every_member(patch, read): + """The bare name keeps the rows whose member labels the dimension lists; it aligns nothing by name.""" + spec = to_spec(varied(MODEL, **_SPAN, **patch)) + assert read(spec).atoms == (RelationDefined('span', ('period', 'unit')),), 'a test of the member tuple' + + +@pytest.mark.parametrize('fmt', FORMATS) +def test_a_membership_test_prints_the_member_indices(fmt): + """It prints as the bare relation over the same members does, not at an index of the dimension.""" + patch = { + 'variables.built': {'dims': ['unit', 'period'], 'where': 'span'}, + 'variables.kept': {'dims': ['unit', 'period'], 'where': 'active'}, + } + text = typeset(to_spec(varied(MODEL, **_SPAN, **patch)), fmt) + name = r'upright("%s")' if fmt == 'typst' else r'\mathrm{%s}' + line = next(line for line in text.splitlines() if 'built' in line and name % 'span' in line) + condition = line[line.index('forall') :] + assert condition.replace(name % 'span', name % 'active') in text, condition + + +def test_a_tuple_dimension_tests_membership_in_a_case(): + case = {'when': 'span', 'expression': 'capacity'} + named = {'dims': ['unit', 'period'], 'cases': {'on': case}, 'otherwise': '0'} + spec = to_spec(varied(MODEL, **_SPAN, **{'expressions.e': named})) + expression = repr(spec.program.expressions['e'].expression) + assert repr(RelationDefined('span', ('period', 'unit'))) in expression, 'the case tests the member tuple' + + +@pytest.mark.parametrize( + 'patch', + [ + pytest.param({'variables.built': {'dims': ['unit'], 'where': 'span'}}, id='a-member-missing'), + pytest.param({'variables.built': {'dims': ['span'], 'where': 'span'}}, id='over-the-dimension-itself'), + pytest.param({'variables.built': {'dims': ['unit', 'snapshot'], 'where': 'span'}}, id='a-member-replaced'), + ], +) +def test_a_tuple_dimension_tests_membership_only_where_the_entry_has_every_member(patch): + message = _refusal(**_SPAN, **patch) + assert "where-relation 'span' reads dims" in message, message + assert 'outside the declared dims' in message + + def test_a_condition_compares_a_member_label(): spec = to_spec(varied(MODEL, **{'variables.flow.where': "connection[unit] == 'gas'"})) (atom,) = spec.program.variables['flow'].where.atoms @@ -464,7 +537,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): ), pytest.param( {'variables.flow.where': 'connection'}, - ('a bare dimension name is true at every coordinate', 'where: "connection[port] == \'...\'"'), + ("where-relation 'connection' reads dims ['port', 'unit'] outside the declared dims",), id='a-bare-dimension-with-members', ), pytest.param( diff --git a/tests/test_validation.py b/tests/test_validation.py index aa2fe1d22..dce69a3d7 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -3566,7 +3566,7 @@ def test_a_divisor_a_shift_fills_with_another_value_loads(divisor): {'variables.pair': {'dims': ['connection', 'site']}}, ( "Variable 'pair': 'connection' and 'site' in dims: share the member 'unit'", - 'where: "at(, by=connection[unit])"', + 'where: "at(site, by=connection[unit])"', "declare an alias of 'unit'", ), id='two-tuple-dimensions-in-a-variable', @@ -3611,3 +3611,10 @@ def test_a_member_shared_by_two_dimensions_of_one_frame_is_refused(patch, fragme message = _refusal(_SHARED_MEMBER, **patch) for fragment in fragments: assert fragment in message + + +def test_the_rewrite_of_a_shared_member_loads(): + """The entry keeps one dimension and reads the other as a condition through the shared member.""" + rewrite = {'dims': ['connection', 'bus'], 'where': 'at(site, by=connection[unit])'} + spec = to_spec(varied(_SHARED_MEMBER, **{'variables.pair': rewrite})) + assert spec.program.variables['pair'].where.dims == ('bus', 'connection'), 'the where stays on the frame' From 91c05358fec790f22fc78f4b798ddf1c4a119dff Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 20:13:39 +0000 Subject: [PATCH 08/11] docs(examples): every example declares its sets as dimensions No example has relations: any more. Each relation becomes a dimension over its members, with an alias where it held one dimension twice (ts_map, the PyPSA maintenance covers). Sums and lookups read through the members with at(); act is confined with where: "prc_ts AND rtp_vintyr". Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- docs/examples/connection.md | 50 ++++++++--------- docs/examples/operators.md | 27 ++++----- docs/examples/pypsa_linearized_uc.md | 30 +++++----- docs/examples/sparse.md | 19 +++---- docs/examples/times/capacity.md | 47 +++++++++------- examples/connection.yaml | 15 ++--- examples/operators/sum_by_column_lists.yaml | 10 ++-- examples/operators/sum_by_columns.yaml | 13 ++--- examples/pypsa.yaml | 62 +++++++++++---------- examples/pypsa/generator_maintenance.yaml | 14 +++-- examples/pypsa/link_maintenance.yaml | 14 +++-- examples/pypsa/process_maintenance.yaml | 14 +++-- examples/sparse.yaml | 7 +-- examples/symbols/capacity.yaml | 3 + examples/times/capacity.yaml | 17 +++--- 15 files changed, 167 insertions(+), 175 deletions(-) diff --git a/docs/examples/connection.md b/docs/examples/connection.md index 8d22fb1f6..dc152aee1 100644 --- a/docs/examples/connection.md +++ b/docs/examples/connection.md @@ -9,17 +9,17 @@ Units with ports is a specification of an optimisation model ([a spec](../reference/glossary.md#spec)) in which each unit attaches to buses through numbered ports. Each port number matches one of the `bus0`, `bus1`, … columns of an open-source power system modelling framework -([PyPSA](https://pypsa.org)). The [relation](../reference/language/relations.md) -`connection` lists the bus and the role of each port. Its key is the unit and -the port, not the bus, so two ports of one unit may attach to the same bus. +([PyPSA](https://pypsa.org)). The dimension `connection` lists the pairs of a +unit and a port, its [members](../reference/language/dimensions.md#over), and +its maps give the bus and the role of each pair. Its label is the pair, not +the bus, so two ports of one unit may attach to the same bus. -`efficiency` is declared over every unit, port and snapshot. Its +`efficiency` is declared over every connection and snapshot. Its [`where:`](../reference/language/parameters-variables-constraints.md#where) -keeps only the output ports, and `missing: 1` applies only there. Where -`connection` has no row, `injection` takes its `otherwise:` and `efficiency` -is [absent](../reference/language/absence.md), so `injection` is absent too. -The sum in `balance` therefore has a term only for the ports that attach to -each bus. +keeps only the output ports, and `missing: 1` applies only there. At an input +port, `injection` takes its case, and elsewhere `efficiency` times the flow of +the unit, read with `at`. The sum in `balance` adds each connection to the bus +it attaches to. ```yaml @@ -31,12 +31,9 @@ dimensions: unit: { description: "converters, such as an electrolyser or a heat pump" } port: { dtype: int, description: "an attachment of a unit, numbered as PyPSA's bus0, bus1, ..." } role: { description: input or output } - -relations: connection: description: the bus each port of a unit attaches to, and whether the port draws or delivers - dims: [unit, port] - missing: absent + over: [unit, port] maps: connection: { bus: { dim: bus }, role: { dim: role } } @@ -45,7 +42,7 @@ parameters: capacity: { dims: [unit], description: the most a unit can draw at its input } efficiency: description: share of the drawn power that an output port delivers - dims: [unit, port, snapshot] + dims: [connection, snapshot] where: "connection[role] == 'output'" missing: 1 load: { dims: [bus, snapshot], description: demand to be met } @@ -64,15 +61,15 @@ variables: expressions: injection: description: what a port puts into its bus - dims: [unit, port, snapshot] + dims: [connection, snapshot] cases: - draws: { when: "connection[role] == 'input'", expression: -flow } - otherwise: efficiency * flow + draws: { when: "connection[role] == 'input'", expression: "-at(flow, by=connection[unit])" } + otherwise: efficiency * at(flow, by=connection[unit]) constraints: balance: dims: [bus, snapshot] - expression: supply + sum(injection, over=[unit, port], by=connection[bus]) == load + expression: supply + sum(injection, over=connection, by=connection[bus]) == load objective: sense: minimize @@ -85,11 +82,12 @@ Units that draw power from one bus and deliver it to others, through numbered po | Symbol | Meaning | |---|---| -| $`\mathcal{B}`$ | index $`b`$ — `bus` with $`\mathrm{bus}: \mathrm{connection} \to \mathcal{B}`$ — nodes of the network | -| $`\mathcal{P}`$ | index $`p`$ — `port` with $`\mathrm{connection} \subseteq \mathcal{P} \times \mathcal{U},\ \mathrm{bus}: \mathrm{connection} \to \mathcal{B},\ \mathrm{role}: \mathrm{connection} \to \mathcal{R}`$, `connection` is `absent` where the data has no row — an attachment of a unit, numbered as PyPSA's bus0, bus1, ... | -| $`\mathcal{R}`$ | index $`r`$ — `role` with $`\mathrm{role}: \mathrm{connection} \to \mathcal{R}`$ — input or output | +| $`\mathcal{B}`$ | index $`b`$ — `bus` with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B}`$ — nodes of the network | +| $`\mathcal{C}`$ | index $`c`$ — `connection`, $`\mathcal{C} \subseteq \mathcal{P} \times \mathcal{U}`$ with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B},\ \mathrm{role}: \mathcal{C} \to \mathcal{R}`$ — the bus each port of a unit attaches to, and whether the port draws or delivers | +| $`\mathcal{P}`$ | index $`p`$ — `port` — an attachment of a unit, numbered as PyPSA's bus0, bus1, ... | +| $`\mathcal{R}`$ | index $`r`$ — `role` with $`\mathrm{role}: \mathcal{C} \to \mathcal{R}`$ — input or output | | $`\mathcal{T}`$ | index $`t`$ — `snapshot` — dispatch periods | -| $`\mathcal{U}`$ | index $`u`$ — `unit` with $`\mathrm{connection} \subseteq \mathcal{P} \times \mathcal{U},\ \mathrm{bus}: \mathrm{connection} \to \mathcal{B},\ \mathrm{role}: \mathrm{connection} \to \mathcal{R}`$, `connection` is `absent` where the data has no row — converters, such as an electrolyser or a heat pump | +| $`\mathcal{U}`$ | index $`u`$ — `unit` — converters, such as an electrolyser or a heat pump | #### Parameters @@ -97,7 +95,7 @@ Units that draw power from one bus and deliver it to others, through numbered po |---|---| | $`\mathrm{capacity}`$ | `capacity` over $`\mathcal{U}`$ — the most a unit can draw at its input | | $`\mathrm{cost}`$ | `cost` over $`\mathcal{B}`$ — price of power bought at a bus | -| $`\mathrm{efficiency}`$ | `efficiency` over $`\mathcal{P} \times \mathcal{T} \times \mathcal{U}`$, only where $`\mathrm{role}(p,\ u) = \text{'}\mathrm{output}\text{'}`$, $`1`$ where the data has no row — share of the drawn power that an output port delivers | +| $`\mathrm{efficiency}`$ | `efficiency` over $`\mathcal{C} \times \mathcal{T}`$, only where $`\mathrm{role}(c) = \text{'}\mathrm{output}\text{'}`$, $`1`$ where the data has no row — share of the drawn power that an output port delivers | | $`\mathrm{load}`$ | `load` over $`\mathcal{B} \times \mathcal{T}`$ — demand to be met | #### Variables @@ -111,7 +109,7 @@ Units that draw power from one bus and deliver it to others, through numbered po | Symbol | Meaning | |---|---| -| $`\mathit{injection}`$ | `injection` over $`\mathcal{P} \times \mathcal{T} \times \mathcal{U}`$ — what a port puts into its bus | +| $`\mathit{injection}`$ | `injection` over $`\mathcal{C} \times \mathcal{T}`$ — what a port puts into its bus | #### Variable domains @@ -132,7 +130,7 @@ Units that draw power from one bus and deliver it to others, through numbered po **`injection`** ```math -\mathit{injection}_{p,t,u} = \begin{cases} -\mathit{flow}_{t,u} & \text{if } \mathrm{role}(p,\ u) = \text{'}\mathrm{input}\text{'} \\ \mathrm{efficiency}_{p,t,u} \cdot \mathit{flow}_{t,u} & \text{otherwise} \end{cases} \qquad \forall\, p \in \mathcal{P},\ t \in \mathcal{T},\ u \in \mathcal{U} +\mathit{injection}_{c,t} = \begin{cases} -\mathit{flow}_{t,\mathrm{unit}(c)} & \text{if } \mathrm{role}(c) = \text{'}\mathrm{input}\text{'} \\ \mathrm{efficiency}_{c,t} \cdot \mathit{flow}_{t,\mathrm{unit}(c)} & \text{otherwise} \end{cases} \qquad \forall\, c \in \mathcal{C},\ t \in \mathcal{T} ``` #### Objective @@ -146,6 +144,6 @@ Units that draw power from one bus and deliver it to others, through numbered po **`balance`** ```math -\mathit{supply}_{b,t} + \sum_{p \in \mathcal{P},\ u \in \mathcal{U} \,:\, \mathrm{bus}(p,\ u) = b} \mathit{injection}_{p,t,u} = \mathrm{load}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T} +\mathit{supply}_{b,t} + \sum_{c \in \mathcal{C} \,:\, \mathrm{bus}(c) = b} \mathit{injection}_{c,t} = \mathrm{load}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T} ``` diff --git a/docs/examples/operators.md b/docs/examples/operators.md index 0f1c49448..9e871d21d 100644 --- a/docs/examples/operators.md +++ b/docs/examples/operators.md @@ -149,18 +149,15 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = b} p_{g,t} \le \mathrm{limit}_ ```yaml description: >- - A sum that keeps a key column: `sum(array, over=dim, by=subject[m])` joins - on the column over `dim` and groups by map `m`. The sum also joins on the - key column that the call does not list. It keeps that column, so each zone - gets one total per period. + A sum that keeps a member: `zone_of` lists (generator, period) tuples. The + sum reads `p` at each tuple with `at`, then groups by the member `period` + and the map `zone`, so each zone gets one total per period. dimensions: generator: { dtype: str } period: { dtype: int } zone: { dtype: str } - -relations: - zone_of: { dims: [generator, period] } + zone_of: { over: [generator, period], missing: refused } maps: zone_of: { zone: { dim: zone } } @@ -176,12 +173,12 @@ variables: constraints: zone_balance: dims: [zone, period] - expression: sum(p, over=generator, by=zone_of[zone]) >= demand + expression: sum(at(p, by=zone_of[generator, period]), over=zone_of, by=zone_of[period, zone]) >= demand objective: { sense: minimize, expression: sum(p) } ``` -$`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ e) = z} p_{g,e} \ge \mathrm{demand}_{e,z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z}`$ +$`\sum_{o \in \mathcal{O} \,:\, \mathrm{period}(o) = e \wedge \mathrm{zone}(o) = z} p_{\mathrm{generator}(o),\mathrm{period}(o)} \ge \mathrm{demand}_{e,z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z}`$ ### `sum(array, over=[dim, …], by=subject[m, …])` @@ -189,17 +186,15 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ e) = z} p_{g,e} \ge \mathrm{de ```yaml description: >- - Several columns and maps: `sum(array, over=[dim, …], by=subject[m, …])` - joins on both columns of the relation and groups by both of its maps. + Several maps: `slot_of` lists (generator, period) tuples. The sum reads `p` + at each tuple with `at`, then groups by both maps of `slot_of`. dimensions: generator: { dtype: str } period: { dtype: int } bus: { dtype: str } technology: { dtype: str } - -relations: - slot_of: { dims: [generator, period] } + slot_of: { over: [generator, period], missing: refused } maps: slot_of: { bus: { dim: bus }, technology: { dim: technology } } @@ -215,12 +210,12 @@ variables: constraints: slot_cap: dims: [bus, technology] - expression: sum(p, over=[generator, period], by=slot_of[bus, technology]) <= cap + expression: sum(at(p, by=slot_of[generator, period]), over=slot_of, by=slot_of[bus, technology]) <= cap objective: { sense: minimize, expression: sum(p) } ``` -$`\sum_{g \in \mathcal{G},\ e \in \mathcal{E} \,:\, \mathrm{bus}(g,\ e) = b \wedge \mathrm{technology}(g,\ e) = t} p_{g,e} \le \mathrm{cap}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ +$`\sum_{s \in \mathcal{S} \,:\, \mathrm{bus}(s) = b \wedge \mathrm{technology}(s) = t} p_{\mathrm{generator}(s),\mathrm{period}(s)} \le \mathrm{cap}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ ### `at(array, by=subject[m])` diff --git a/docs/examples/pypsa_linearized_uc.md b/docs/examples/pypsa_linearized_uc.md index b75f8d240..f720e2805 100644 --- a/docs/examples/pypsa_linearized_uc.md +++ b/docs/examples/pypsa_linearized_uc.md @@ -213,7 +213,7 @@ Generator_com_p_before: ``` ```math -\overleftarrow{p}_{g,\xi,t} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} - \left( \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \left( u_{g,\xi,t} - \mathit{up}_{g,\xi,t} \right) \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t'} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) +\overleftarrow{p}_{g,\xi,t} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} - \left( \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \left( u_{g,\xi,t} - \mathit{up}_{g,\xi,t} \right) \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t''} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) ``` ### `Generator-com-p-current` @@ -233,7 +233,7 @@ Generator_com_p_current: ``` ```math -p_{g,\xi,t} - \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot u_{g,\xi,t} + \left( \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{ru}}^{\mathrm{up}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t'} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} +p_{g,\xi,t} - \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot u_{g,\xi,t} + \left( \overline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{ru}}^{\mathrm{up}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t''} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} ``` ### `Generator-com-partly-start-up` @@ -257,7 +257,7 @@ Generator_com_partly_start_up: ``` ```math -p_{g,\xi,t} - \overleftarrow{p}_{g,\xi,t} - \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{ru}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot u_{g,\xi,t} + \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} + \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{ru}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{ru}}^{\mathrm{up}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t'} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) +p_{g,\xi,t} - \overleftarrow{p}_{g,\xi,t} - \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{ru}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot u_{g,\xi,t} + \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} + \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{ru}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{ru}}^{\mathrm{up}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t''} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) ``` ### `Generator-com-partly-shut-down` @@ -280,7 +280,7 @@ Generator_com_partly_shut_down: ``` ```math -\overleftarrow{p}_{g,\xi,t} - p_{g,\xi,t} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} + \left( \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot u_{g,\xi,t} - \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{rd}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t'} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) +\overleftarrow{p}_{g,\xi,t} - p_{g,\xi,t} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \cdot \overleftarrow{u}_{g,\xi,t} + \left( \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot u_{g,\xi,t} - \left( \underline{\mathrm{p}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} + \widetilde{\mathrm{rd}}_{g,\xi,t} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} - \widetilde{\mathrm{rd}}^{\mathrm{dn}}_{g,\xi} \cdot \mathrm{p}^{\mathrm{nom}}_{g,\xi} \right) \cdot \mathit{up}_{g,\xi,t} \le 0 \qquad \forall\, g \in \mathcal{G},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}_{g} \wedge \neg \mathrm{ext}_{g} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{\mathrm{up}}_{g,\xi',t''} \neq \mathrm{c}^{\mathrm{dn}}_{g,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}_{g,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{0}_{g,\xi} = 0 \vee \mathrm{p}^{0}_{g,\xi} \text{ is defined} \right) ``` ### `Link-com-p-before` @@ -306,7 +306,7 @@ Link_com_p_before: ``` ```math -\overleftarrow{f}_{l,\xi,t} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} - \left( \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \left( u^{f}_{l,\xi,t} - \mathit{up}^{f}_{l,\xi,t} \right) \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t'} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) +\overleftarrow{f}_{l,\xi,t} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} - \left( \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \left( u^{f}_{l,\xi,t} - \mathit{up}^{f}_{l,\xi,t} \right) \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t''} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) ``` ### `Link-com-p-current` @@ -326,7 +326,7 @@ Link_com_p_current: ``` ```math -f_{l,\xi,t} - \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot u^{f}_{l,\xi,t} + \left( \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{ru}}^{f,\mathrm{up}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t'} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} +f_{l,\xi,t} - \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot u^{f}_{l,\xi,t} + \left( \overline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{ru}}^{f,\mathrm{up}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t''} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} ``` ### `Link-com-partly-start-up` @@ -350,7 +350,7 @@ Link_com_partly_start_up: ``` ```math -f_{l,\xi,t} - \overleftarrow{f}_{l,\xi,t} - \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{ru}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot u^{f}_{l,\xi,t} + \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} + \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{ru}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{ru}}^{f,\mathrm{up}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t'} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) +f_{l,\xi,t} - \overleftarrow{f}_{l,\xi,t} - \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{ru}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot u^{f}_{l,\xi,t} + \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} + \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{ru}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{ru}}^{f,\mathrm{up}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t''} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) ``` ### `Link-com-partly-shut-down` @@ -373,7 +373,7 @@ Link_com_partly_shut_down: ``` ```math -\overleftarrow{f}_{l,\xi,t} - f_{l,\xi,t} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} + \left( \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot u^{f}_{l,\xi,t} - \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{rd}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t'} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) +\overleftarrow{f}_{l,\xi,t} - f_{l,\xi,t} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \cdot \overleftarrow{u}^{f}_{l,\xi,t} + \left( \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot u^{f}_{l,\xi,t} - \left( \underline{\mathrm{f}}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} + \widetilde{\mathrm{rd}}^{f}_{l,\xi,t} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} - \widetilde{\mathrm{rd}}^{f,\mathrm{dn}}_{l,\xi} \cdot \mathrm{f}^{\mathrm{nom}}_{l,\xi} \right) \cdot \mathit{up}^{f}_{l,\xi,t} \le 0 \qquad \forall\, l \in \mathcal{L},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{f}_{l} \wedge \neg \mathrm{ext}^{f}_{l} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{f,\mathrm{up}}_{l,\xi',t''} \neq \mathrm{c}^{f,\mathrm{dn}}_{l,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{f}_{l,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{f,0}_{l,\xi} = 0 \vee \mathrm{f}^{0}_{l,\xi} \text{ is defined} \right) ``` ### `Process-com-p-before` @@ -399,7 +399,7 @@ Process_com_p_before: ``` ```math -\overleftarrow{z}_{j,\xi,t} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} - \left( \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \left( u^{z}_{j,\xi,t} - \mathit{up}^{z}_{j,\xi,t} \right) \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t'} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) +\overleftarrow{z}_{j,\xi,t} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} - \left( \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \left( u^{z}_{j,\xi,t} - \mathit{up}^{z}_{j,\xi,t} \right) \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t''} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) ``` ### `Process-com-p-current` @@ -419,7 +419,7 @@ Process_com_p_current: ``` ```math -z_{j,\xi,t} - \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot u^{z}_{j,\xi,t} + \left( \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{ru}}^{z,\mathrm{up}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t'} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} +z_{j,\xi,t} - \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot u^{z}_{j,\xi,t} + \left( \overline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{ru}}^{z,\mathrm{up}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t''} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} ``` ### `Process-com-partly-start-up` @@ -443,7 +443,7 @@ Process_com_partly_start_up: ``` ```math -z_{j,\xi,t} - \overleftarrow{z}_{j,\xi,t} - \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{ru}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot u^{z}_{j,\xi,t} + \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} + \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{ru}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{ru}}^{z,\mathrm{up}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t'} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) +z_{j,\xi,t} - \overleftarrow{z}_{j,\xi,t} - \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{ru}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot u^{z}_{j,\xi,t} + \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} + \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{ru}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{ru}}^{z,\mathrm{up}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t''} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) ``` ### `Process-com-partly-shut-down` @@ -466,7 +466,7 @@ Process_com_partly_shut_down: ``` ```math -\overleftarrow{z}_{j,\xi,t} - z_{j,\xi,t} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} + \left( \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot u^{z}_{j,\xi,t} - \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{rd}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t'} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t'} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) +\overleftarrow{z}_{j,\xi,t} - z_{j,\xi,t} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \cdot \overleftarrow{u}^{z}_{j,\xi,t} + \left( \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot u^{z}_{j,\xi,t} - \left( \underline{\mathrm{z}}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} + \widetilde{\mathrm{rd}}^{z}_{j,\xi,t} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} - \widetilde{\mathrm{rd}}^{z,\mathrm{dn}}_{j,\xi} \cdot \mathrm{z}^{\mathrm{nom}}_{j,\xi} \right) \cdot \mathit{up}^{z}_{j,\xi,t} \le 0 \qquad \forall\, j \in \mathcal{J},\ \xi \in \Xi,\ t \in \mathcal{T} \,:\, \mathrm{com}^{z}_{j} \wedge \neg \mathrm{ext}^{z}_{j} \wedge \lvert \{ \xi' \in \Xi \,:\, \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{c}^{z,\mathrm{up}}_{j,\xi',t''} \neq \mathrm{c}^{z,\mathrm{dn}}_{j,\xi',t''} \} \rvert > 0 \} \rvert = 0 \wedge \mathrm{on}^{z}_{j,t} \wedge \left( \mathrm{pos}(t) > 0 \vee \mathrm{u}^{z,0}_{j,\xi} = 0 \vee \mathrm{z}^{0}_{j,\xi} \text{ is defined} \right) ``` ### `Generator_marginal_cost_incremental` @@ -521,7 +521,7 @@ Generator_committable_is_not_modular: ``` ```math -\neg \left( \mathrm{p}^{\mathrm{mod}}_{g} > 0 \right) \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{com}_{g} \wedge \lvert \{ t \in \mathcal{T} \,:\, \mathrm{on}_{g,t} \} \rvert > 0 +\neg \left( \mathrm{p}^{\mathrm{mod}}_{g} > 0 \right) \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{com}_{g} \wedge \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{on}_{g,t''} \} \rvert > 0 ``` ### `Link_committable_is_not_modular` @@ -539,7 +539,7 @@ Link_committable_is_not_modular: ``` ```math -\neg \left( \mathrm{f}^{\mathrm{mod}}_{l} > 0 \right) \qquad \forall\, l \in \mathcal{L} \,:\, \mathrm{com}^{f}_{l} \wedge \lvert \{ t \in \mathcal{T} \,:\, \mathrm{on}^{f}_{l,t} \} \rvert > 0 +\neg \left( \mathrm{f}^{\mathrm{mod}}_{l} > 0 \right) \qquad \forall\, l \in \mathcal{L} \,:\, \mathrm{com}^{f}_{l} \wedge \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{on}^{f}_{l,t''} \} \rvert > 0 ``` ### `Process_committable_is_not_modular` @@ -557,7 +557,7 @@ Process_committable_is_not_modular: ``` ```math -\neg \left( \mathrm{z}^{\mathrm{mod}}_{j} > 0 \right) \qquad \forall\, j \in \mathcal{J} \,:\, \mathrm{com}^{z}_{j} \wedge \lvert \{ t \in \mathcal{T} \,:\, \mathrm{on}^{z}_{j,t} \} \rvert > 0 +\neg \left( \mathrm{z}^{\mathrm{mod}}_{j} > 0 \right) \qquad \forall\, j \in \mathcal{J} \,:\, \mathrm{com}^{z}_{j} \wedge \lvert \{ t'' \in \mathcal{T} \,:\, \mathrm{on}^{z}_{j,t''} \} \rvert > 0 ``` diff --git a/docs/examples/sparse.md b/docs/examples/sparse.md index 7dafc8c7e..37b93af1a 100644 --- a/docs/examples/sparse.md +++ b/docs/examples/sparse.md @@ -19,9 +19,10 @@ the sets in one way: `connection` is a dimension whose labels are the pairs of a unit and a port. `efficiency` and `flow` are over it, so `missing: 1` fills only the ports it -lists, and a data row for a port it does not list is refused. `active` has the -ordered member `period`, along which `ramp_up` steps, so it stays a relation -that `output` reads in its `where:`. +lists, and a data row for a port it does not list is refused. `active` is a +dimension over `unit` and `period`. `output` is over both members, and +`where: active` keeps the pairs that `active` lists, so `ramp_up` can step +along the ordered member `period`. [#1019](https://github.com/energy-models/mathspec/issues/1019) compares how three designs for sparse sets write this spec. @@ -37,12 +38,7 @@ dimensions: bus: { description: a node of the network } period: { dtype: int, ordered: true, description: a step of the horizon } connection: { over: [unit, port], description: the ports a unit has } - -relations: - active: - description: the periods a unit runs in - dims: [unit, period] - missing: absent + active: { over: [unit, period], description: the periods a unit runs in } maps: connection: @@ -87,11 +83,12 @@ Units that feed buses through the ports they have, and run only in the periods t | Symbol | Meaning | |---|---| +| $`\mathcal{A}`$ | index $`a`$ — `active`, $`\mathcal{A} \subseteq \mathcal{T} \times \mathcal{U}`$ — the periods a unit runs in | | $`\mathcal{B}`$ | index $`b`$ — `bus` with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B}`$ — a node of the network | | $`\mathcal{C}`$ | index $`c`$ — `connection`, $`\mathcal{C} \subseteq \mathcal{O} \times \mathcal{U}`$ with $`\mathrm{bus}: \mathcal{C} \to \mathcal{B}`$ — the ports a unit has | -| $`\mathcal{T}`$ | index $`t`$ — `period` with $`\mathrm{active} \subseteq \mathcal{T} \times \mathcal{U}`$, `active` is `absent` where the data has no row — a step of the horizon | +| $`\mathcal{T}`$ | index $`t`$ — `period` — a step of the horizon | | $`\mathcal{O}`$ | index $`o`$ — `port` — an output of a unit | -| $`\mathcal{U}`$ | index $`u`$ — `unit` with $`\mathrm{active} \subseteq \mathcal{T} \times \mathcal{U}`$, `active` is `absent` where the data has no row — a converter | +| $`\mathcal{U}`$ | index $`u`$ — `unit` — a converter | #### Parameters diff --git a/docs/examples/times/capacity.md b/docs/examples/times/capacity.md index c8824589d..1c84d2ef3 100644 --- a/docs/examples/times/capacity.md +++ b/docs/examples/times/capacity.md @@ -17,10 +17,14 @@ without storage, with the upper bound only. The GAMS conditions map to the spec as follows: -- `RTP_VINTYR` and `PRC_TS` are [relations](../../reference/language/relations.md), - and `act` exists only at the coordinates that both list. -- `TS_MAP(R,S,TS)` is the relation `ts_map`, which names `timeslice` twice - under two column names. +- `RTP_VINTYR` and `PRC_TS` are dimensions with + [members](../../reference/language/dimensions.md#over). `act` is over every + member of both, and `where: "prc_ts AND rtp_vintyr"` keeps the coordinates + that both list. +- `TS_MAP(R,S,TS)` is the dimension `ts_map`. Its upper timeslice is the + alias `upper_timeslice`, so the two timeslices are two members. + `eq_capact_up` reads the activity at each tuple of `ts_map`, sums it to each + upper timeslice, and reads that back onto `timeslice`. - `COEF_AF(…,'UP')` is the `where:` of `eq_capact_up`. - `NCAP_PASTI$PASTYEAR(V)` reads `0` where the data has no row. @@ -40,20 +44,16 @@ dimensions: vintage: { dtype: int, description: the period a capacity was built in } process: { description: a technology } timeslice: { description: "a slice of the year, at any level of the timeslice tree" } - -relations: + upper_timeslice: { alias: timeslice, description: a timeslice that another is at or below } rtp_vintyr: description: the vintages of a process that exist in a period (RTP_VINTYR) - dims: [region, vintage, period, process] - missing: absent + over: [region, vintage, period, process] prc_ts: description: the timeslices a process operates at (PRC_TS) - dims: [region, process, timeslice] - missing: absent + over: [region, process, timeslice] ts_map: description: each timeslice and the timeslices at or below it (TS_MAP) - dims: { region: region, s: timeslice, ts: timeslice } - missing: absent + over: [region, upper_timeslice, timeslice] parameters: coef_cpt: { dims: [region, vintage, period, process], description: the share of a vintage that still exists in a period } @@ -70,7 +70,7 @@ variables: act: description: activity of a vintage of a process in a timeslice (VAR_ACT) dims: [region, vintage, period, process, timeslice] - where: rtp_vintyr AND prc_ts + where: "prc_ts AND rtp_vintyr" bounds: { lower: 0 } constraints: @@ -83,7 +83,8 @@ constraints: dims: [region, period, process, timeslice] where: coef_af_up expression: >- - sum(sum(act, over=vintage), over=ts, by=ts_map[s]) + sum(sum(at(sum(act, over=vintage), by=ts_map[region, timeslice]), over=ts_map, by=ts_map[region, upper_timeslice]), + over=upper_timeslice, by=upper_timeslice[timeslice]) <= coef_af_up * prc_capact * g_yrfr * cap objective: @@ -99,11 +100,15 @@ Capacity transfer and capacity–activity from TIMES: EQ\_CPT and the upper form | Symbol | Meaning | |---|---| -| $`\mathcal{T}`$ | index $`t`$ — `period` with $`\mathrm{rtp\_vintyr} \subseteq \mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{V}`$, `rtp_vintyr` is `absent` where the data has no row — a milestone year | -| $`\mathcal{P}`$ | index $`p`$ — `process` with $`\mathrm{prc\_ts} \subseteq \mathcal{P} \times \mathcal{R} \times \mathcal{S},\ \mathrm{rtp\_vintyr} \subseteq \mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{V}`$, `prc_ts` is `absent` where the data has no row, `rtp_vintyr` is `absent` where the data has no row — a technology | -| $`\mathcal{R}`$ | index $`r`$ — `region` with $`\mathrm{prc\_ts} \subseteq \mathcal{P} \times \mathcal{R} \times \mathcal{S},\ \mathrm{rtp\_vintyr} \subseteq \mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{V},\ \mathrm{ts\_map} \subseteq \mathcal{R} \times \mathcal{S} \times \mathcal{S}`$, `prc_ts` is `absent` where the data has no row, `rtp_vintyr` is `absent` where the data has no row, `ts_map` is `absent` where the data has no row — a region of the model | -| $`\mathcal{S}`$ | index $`s`$ — `timeslice` with $`\mathrm{prc\_ts} \subseteq \mathcal{P} \times \mathcal{R} \times \mathcal{S},\ \mathrm{ts\_map} \subseteq \mathcal{R} \times \mathcal{S} \times \mathcal{S}`$, `prc_ts` is `absent` where the data has no row, `ts_map` is `absent` where the data has no row — a slice of the year, at any level of the timeslice tree | -| $`\mathcal{V}`$ | index $`v`$ — `vintage` with $`\mathrm{rtp\_vintyr} \subseteq \mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{V}`$, `rtp_vintyr` is `absent` where the data has no row — the period a capacity was built in | +| $`\mathcal{T}`$ | index $`t`$ — `period` — a milestone year | +| $`\mathcal{Q}`$ | index $`q`$ — `prc_ts`, $`\mathcal{Q} \subseteq \mathcal{P} \times \mathcal{R} \times \mathcal{S}`$ — the timeslices a process operates at (PRC\_TS) | +| $`\mathcal{P}`$ | index $`p`$ — `process` — a technology | +| $`\mathcal{R}`$ | index $`r`$ — `region` — a region of the model | +| $`\mathcal{K}`$ | index $`k`$ — `rtp_vintyr`, $`\mathcal{K} \subseteq \mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{V}`$ — the vintages of a process that exist in a period (RTP\_VINTYR) | +| $`\mathcal{S}`$ | index $`s`$ — `timeslice` — a slice of the year, at any level of the timeslice tree | +| $`\mathcal{M}`$ | index $`m`$ — `ts_map`, $`\mathcal{M} \subseteq \mathcal{R} \times \mathcal{S} \times \mathcal{S}`$ — each timeslice and the timeslices at or below it (TS\_MAP) | +| $`\mathcal{S}`$ | index $`s'`$ — `upper_timeslice`, an alias of `timeslice` — a timeslice that another is at or below | +| $`\mathcal{V}`$ | index $`v`$ — `vintage` — the period a capacity was built in | #### Parameters @@ -130,7 +135,7 @@ Capacity transfer and capacity–activity from TIMES: EQ\_CPT and the upper form **`act`** ```math -\mathit{act}_{t,p,r,s,v} \ge 0 \qquad \forall\, t \in \mathcal{T},\ p \in \mathcal{P},\ r \in \mathcal{R},\ s \in \mathcal{S},\ v \in \mathcal{V} \,:\, \left( t,\ p,\ r,\ v \right) \in \mathrm{rtp\_vintyr} \wedge \left( p,\ r,\ s \right) \in \mathrm{prc\_ts} +\mathit{act}_{t,p,r,s,v} \ge 0 \qquad \forall\, t \in \mathcal{T},\ p \in \mathcal{P},\ r \in \mathcal{R},\ s \in \mathcal{S},\ v \in \mathcal{V} \,:\, \left( p,\ r,\ s \right) \in \mathrm{prc\_ts} \wedge \left( t,\ p,\ r,\ v \right) \in \mathrm{rtp\_vintyr} ``` **`cap`** @@ -156,7 +161,7 @@ Capacity transfer and capacity–activity from TIMES: EQ\_CPT and the upper form **`eq_capact_up`** ```math -\sum_{s' \in \mathcal{S} \,:\, \left( r,\ s,\ s' \right) \in \mathrm{ts\_map}} \sum_{v \in \mathcal{V}} \mathit{act}_{t,p,r,s',v} \le \mathrm{coef\_af\_up}_{t,p,r,s} \cdot \mathrm{prc\_capact}_{p,r} \cdot \mathrm{g}^{\mathrm{yrfr}}_{r,s} \cdot \mathit{cap}_{t,p,r} \qquad \forall\, t \in \mathcal{T},\ p \in \mathcal{P},\ r \in \mathcal{R},\ s \in \mathcal{S} \,:\, \mathrm{coef\_af\_up}_{t,p,r,s} \text{ is defined} +\sum_{s' \in \mathcal{S} \,:\, s' = s} \sum_{m \in \mathcal{M} \,:\, \mathrm{region}(m) = r \wedge \mathrm{upper\_timeslice}(m) = s'} \sum_{v \in \mathcal{V}} \mathit{act}_{t,p,\mathrm{region}(m),\mathrm{timeslice}(m),v} \le \mathrm{coef\_af\_up}_{t,p,r,s} \cdot \mathrm{prc\_capact}_{p,r} \cdot \mathrm{g}^{\mathrm{yrfr}}_{r,s} \cdot \mathit{cap}_{t,p,r} \qquad \forall\, t \in \mathcal{T},\ p \in \mathcal{P},\ r \in \mathcal{R},\ s \in \mathcal{S} \,:\, \mathrm{coef\_af\_up}_{t,p,r,s} \text{ is defined} ``` **`eq_cpt`** diff --git a/examples/connection.yaml b/examples/connection.yaml index 37ef20837..6f127d88c 100644 --- a/examples/connection.yaml +++ b/examples/connection.yaml @@ -10,12 +10,9 @@ dimensions: unit: { description: "converters, such as an electrolyser or a heat pump" } port: { dtype: int, description: "an attachment of a unit, numbered as PyPSA's bus0, bus1, ..." } role: { description: input or output } - -relations: connection: description: the bus each port of a unit attaches to, and whether the port draws or delivers - dims: [unit, port] - missing: absent + over: [unit, port] maps: connection: { bus: { dim: bus }, role: { dim: role } } @@ -24,7 +21,7 @@ parameters: capacity: { dims: [unit], description: the most a unit can draw at its input } efficiency: description: share of the drawn power that an output port delivers - dims: [unit, port, snapshot] + dims: [connection, snapshot] where: "connection[role] == 'output'" missing: 1 load: { dims: [bus, snapshot], description: demand to be met } @@ -43,15 +40,15 @@ variables: expressions: injection: description: what a port puts into its bus - dims: [unit, port, snapshot] + dims: [connection, snapshot] cases: - draws: { when: "connection[role] == 'input'", expression: -flow } - otherwise: efficiency * flow + draws: { when: "connection[role] == 'input'", expression: "-at(flow, by=connection[unit])" } + otherwise: efficiency * at(flow, by=connection[unit]) constraints: balance: dims: [bus, snapshot] - expression: supply + sum(injection, over=[unit, port], by=connection[bus]) == load + expression: supply + sum(injection, over=connection, by=connection[bus]) == load objective: sense: minimize diff --git a/examples/operators/sum_by_column_lists.yaml b/examples/operators/sum_by_column_lists.yaml index ca61c040d..ef07fe8a5 100644 --- a/examples/operators/sum_by_column_lists.yaml +++ b/examples/operators/sum_by_column_lists.yaml @@ -3,17 +3,15 @@ # SPDX-License-Identifier: MIT description: >- - Several columns and maps: `sum(array, over=[dim, …], by=subject[m, …])` - joins on both columns of the relation and groups by both of its maps. + Several maps: `slot_of` lists (generator, period) tuples. The sum reads `p` + at each tuple with `at`, then groups by both maps of `slot_of`. dimensions: generator: { dtype: str } period: { dtype: int } bus: { dtype: str } technology: { dtype: str } - -relations: - slot_of: { dims: [generator, period] } + slot_of: { over: [generator, period], missing: refused } maps: slot_of: { bus: { dim: bus }, technology: { dim: technology } } @@ -29,6 +27,6 @@ variables: constraints: slot_cap: dims: [bus, technology] - expression: sum(p, over=[generator, period], by=slot_of[bus, technology]) <= cap + expression: sum(at(p, by=slot_of[generator, period]), over=slot_of, by=slot_of[bus, technology]) <= cap objective: { sense: minimize, expression: sum(p) } diff --git a/examples/operators/sum_by_columns.yaml b/examples/operators/sum_by_columns.yaml index e417f783c..262937865 100644 --- a/examples/operators/sum_by_columns.yaml +++ b/examples/operators/sum_by_columns.yaml @@ -3,18 +3,15 @@ # SPDX-License-Identifier: MIT description: >- - A sum that keeps a key column: `sum(array, over=dim, by=subject[m])` joins - on the column over `dim` and groups by map `m`. The sum also joins on the - key column that the call does not list. It keeps that column, so each zone - gets one total per period. + A sum that keeps a member: `zone_of` lists (generator, period) tuples. The + sum reads `p` at each tuple with `at`, then groups by the member `period` + and the map `zone`, so each zone gets one total per period. dimensions: generator: { dtype: str } period: { dtype: int } zone: { dtype: str } - -relations: - zone_of: { dims: [generator, period] } + zone_of: { over: [generator, period], missing: refused } maps: zone_of: { zone: { dim: zone } } @@ -30,6 +27,6 @@ variables: constraints: zone_balance: dims: [zone, period] - expression: sum(p, over=generator, by=zone_of[zone]) >= demand + expression: sum(at(p, by=zone_of[generator, period]), over=zone_of, by=zone_of[period, zone]) >= demand objective: { sense: minimize, expression: sum(p) } diff --git a/examples/pypsa.yaml b/examples/pypsa.yaml index bf6655374..c047cb90e 100644 --- a/examples/pypsa.yaml +++ b/examples/pypsa.yaml @@ -24,6 +24,9 @@ dimensions: description: dispatch periods dtype: datetime ordered: true + covered_snapshot: + alias: snapshot + description: a snapshot that a maintenance event covers bus: description: network nodes generator: @@ -88,6 +91,27 @@ dimensions: breakpoints its data has rows for, so curves may differ in length dtype: int ordered: true + Generator_maintenance_cover: + description: >- + each snapshot a maintenance event starts in, with a snapshot it covers, + data prep. In a scenario, they are the start and the snapshots after it, + until their generator weightings reach that scenario's + `maintenance_duration`. A generator that is not maintainable has no rows + over: [scenario, generator, snapshot, covered_snapshot] + Link_maintenance_cover: + description: >- + each snapshot a maintenance event starts in, with a snapshot it covers, + data prep. In a scenario, they are the start and the snapshots after it, + until their generator weightings reach that scenario's + `maintenance_duration`. A link that is not maintainable has no rows + over: [scenario, link, snapshot, covered_snapshot] + Process_maintenance_cover: + description: >- + each snapshot a maintenance event starts in, with a snapshot it covers, + data prep. In a scenario, they are the start and the snapshots after it, + until their generator weightings reach that scenario's + `maintenance_duration`. A process that is not maintainable has no rows + over: [scenario, process, snapshot, covered_snapshot] parameters: Bus_attached: @@ -1581,32 +1605,6 @@ parameters: dims: [global_constraint, process] missing: absent -relations: - Generator_maintenance_cover: - description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, - data prep. In a scenario, they are the start and the snapshots after it, - until their generator weightings reach that scenario's - `maintenance_duration`. A generator that is not maintainable has no rows - dims: { scenario: scenario, generator: generator, start: snapshot, covered: snapshot } - missing: absent - Link_maintenance_cover: - description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, - data prep. In a scenario, they are the start and the snapshots after it, - until their generator weightings reach that scenario's - `maintenance_duration`. A link that is not maintainable has no rows - dims: { scenario: scenario, link: link, start: snapshot, covered: snapshot } - missing: absent - Process_maintenance_cover: - description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, - data prep. In a scenario, they are the start and the snapshots after it, - until their generator weightings reach that scenario's - `maintenance_duration`. A process that is not maintainable has no rows - dims: { scenario: scenario, process: process, start: snapshot, covered: snapshot } - missing: absent - maps: snapshot: period: @@ -3630,7 +3628,9 @@ constraints: since the maintenance status is at most one dims: [scenario, snapshot, generator] where: Generator_maintainable AND Generator_active - expression: Generator_maintenance == sum(Generator_maintenance_start, over=start, by=Generator_maintenance_cover[covered]) + expression: Generator_maintenance == sum(sum(at(Generator_maintenance_start, by=Generator_maintenance_cover[generator, scenario, snapshot]), + over=Generator_maintenance_cover, by=Generator_maintenance_cover[generator, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Generator_maint_start_horizon: description: "`Generator-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, generator] @@ -3876,7 +3876,9 @@ constraints: maintenance status is at most one dims: [scenario, snapshot, link] where: Link_maintainable AND Link_active - expression: Link_maintenance == sum(Link_maintenance_start, over=start, by=Link_maintenance_cover[covered]) + expression: Link_maintenance == sum(sum(at(Link_maintenance_start, by=Link_maintenance_cover[link, scenario, snapshot]), + over=Link_maintenance_cover, by=Link_maintenance_cover[link, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Link_maint_start_horizon: description: "`Link-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, link] @@ -4131,7 +4133,9 @@ constraints: the maintenance status is at most one dims: [scenario, snapshot, process] where: Process_maintainable AND Process_active - expression: Process_maintenance == sum(Process_maintenance_start, over=start, by=Process_maintenance_cover[covered]) + expression: Process_maintenance == sum(sum(at(Process_maintenance_start, by=Process_maintenance_cover[process, scenario, snapshot]), + over=Process_maintenance_cover, by=Process_maintenance_cover[process, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Process_maint_start_horizon: description: "`Process-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, process] diff --git a/examples/pypsa/generator_maintenance.yaml b/examples/pypsa/generator_maintenance.yaml index 6bc608280..e856e24e7 100644 --- a/examples/pypsa/generator_maintenance.yaml +++ b/examples/pypsa/generator_maintenance.yaml @@ -25,18 +25,18 @@ dimensions: description: dispatch periods dtype: datetime ordered: true + covered_snapshot: + alias: snapshot + description: a snapshot that a maintenance event covers generator: description: generating units, each on one bus - -relations: Generator_maintenance_cover: description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, + each snapshot a maintenance event starts in, with a snapshot it covers, data prep. In a scenario, they are the start and the snapshots after it, until their generator weightings reach that scenario's `maintenance_duration`. A generator that is not maintainable has no rows - dims: { scenario: scenario, generator: generator, start: snapshot, covered: snapshot } - missing: absent + over: [scenario, generator, snapshot, covered_snapshot] parameters: Generator_maintainable: @@ -147,7 +147,9 @@ constraints: since the maintenance status is at most one dims: [scenario, snapshot, generator] where: Generator_maintainable AND Generator_active - expression: Generator_maintenance == sum(Generator_maintenance_start, over=start, by=Generator_maintenance_cover[covered]) + expression: Generator_maintenance == sum(sum(at(Generator_maintenance_start, by=Generator_maintenance_cover[generator, scenario, snapshot]), + over=Generator_maintenance_cover, by=Generator_maintenance_cover[generator, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Generator_maint_start_horizon: description: "`Generator-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, generator] diff --git a/examples/pypsa/link_maintenance.yaml b/examples/pypsa/link_maintenance.yaml index 98c5ed585..7e45f1de2 100644 --- a/examples/pypsa/link_maintenance.yaml +++ b/examples/pypsa/link_maintenance.yaml @@ -25,18 +25,18 @@ dimensions: description: dispatch periods dtype: datetime ordered: true + covered_snapshot: + alias: snapshot + description: a snapshot that a maintenance event covers link: description: controllable connections, each from one bus to the buses it delivers to - -relations: Link_maintenance_cover: description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, + each snapshot a maintenance event starts in, with a snapshot it covers, data prep. In a scenario, they are the start and the snapshots after it, until their generator weightings reach that scenario's `maintenance_duration`. A link that is not maintainable has no rows - dims: { scenario: scenario, link: link, start: snapshot, covered: snapshot } - missing: absent + over: [scenario, link, snapshot, covered_snapshot] parameters: Link_maintainable: @@ -144,7 +144,9 @@ constraints: maintenance status is at most one dims: [scenario, snapshot, link] where: Link_maintainable AND Link_active - expression: Link_maintenance == sum(Link_maintenance_start, over=start, by=Link_maintenance_cover[covered]) + expression: Link_maintenance == sum(sum(at(Link_maintenance_start, by=Link_maintenance_cover[link, scenario, snapshot]), + over=Link_maintenance_cover, by=Link_maintenance_cover[link, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Link_maint_start_horizon: description: "`Link-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, link] diff --git a/examples/pypsa/process_maintenance.yaml b/examples/pypsa/process_maintenance.yaml index 15533b742..936c27c75 100644 --- a/examples/pypsa/process_maintenance.yaml +++ b/examples/pypsa/process_maintenance.yaml @@ -25,18 +25,18 @@ dimensions: description: dispatch periods dtype: datetime ordered: true + covered_snapshot: + alias: snapshot + description: a snapshot that a maintenance event covers process: description: generalised multi-port converters, each with an internal power that every port draws or delivers at its own rate - -relations: Process_maintenance_cover: description: >- - the snapshots a maintenance event covers, by the snapshot it starts in, + each snapshot a maintenance event starts in, with a snapshot it covers, data prep. In a scenario, they are the start and the snapshots after it, until their generator weightings reach that scenario's `maintenance_duration`. A process that is not maintainable has no rows - dims: { scenario: scenario, process: process, start: snapshot, covered: snapshot } - missing: absent + over: [scenario, process, snapshot, covered_snapshot] parameters: Process_maintainable: @@ -147,7 +147,9 @@ constraints: the maintenance status is at most one dims: [scenario, snapshot, process] where: Process_maintainable AND Process_active - expression: Process_maintenance == sum(Process_maintenance_start, over=start, by=Process_maintenance_cover[covered]) + expression: Process_maintenance == sum(sum(at(Process_maintenance_start, by=Process_maintenance_cover[process, scenario, snapshot]), + over=Process_maintenance_cover, by=Process_maintenance_cover[process, covered_snapshot, scenario]), + over=covered_snapshot, by=covered_snapshot[snapshot]) Process_maint_start_horizon: description: "`Process-maint-start-horizon` — no event starts where it could not run its whole duration" dims: [scenario, snapshot, process] diff --git a/examples/sparse.yaml b/examples/sparse.yaml index 0dc4722cc..4df712f49 100644 --- a/examples/sparse.yaml +++ b/examples/sparse.yaml @@ -12,12 +12,7 @@ dimensions: bus: { description: a node of the network } period: { dtype: int, ordered: true, description: a step of the horizon } connection: { over: [unit, port], description: the ports a unit has } - -relations: - active: - description: the periods a unit runs in - dims: [unit, period] - missing: absent + active: { over: [unit, period], description: the periods a unit runs in } maps: connection: diff --git a/examples/symbols/capacity.yaml b/examples/symbols/capacity.yaml index e23b76f20..d7dd6aa58 100644 --- a/examples/symbols/capacity.yaml +++ b/examples/symbols/capacity.yaml @@ -10,3 +10,6 @@ dimensions: vintage: { index: v, set: '\mathcal{V}' } process: { index: p, set: '\mathcal{P}' } timeslice: { index: s, set: '\mathcal{S}' } + rtp_vintyr: { index: k, set: '\mathcal{K}' } + prc_ts: { index: q, set: '\mathcal{Q}' } + ts_map: { index: m, set: '\mathcal{M}' } diff --git a/examples/times/capacity.yaml b/examples/times/capacity.yaml index f8b544947..f98e69414 100644 --- a/examples/times/capacity.yaml +++ b/examples/times/capacity.yaml @@ -12,20 +12,16 @@ dimensions: vintage: { dtype: int, description: the period a capacity was built in } process: { description: a technology } timeslice: { description: "a slice of the year, at any level of the timeslice tree" } - -relations: + upper_timeslice: { alias: timeslice, description: a timeslice that another is at or below } rtp_vintyr: description: the vintages of a process that exist in a period (RTP_VINTYR) - dims: [region, vintage, period, process] - missing: absent + over: [region, vintage, period, process] prc_ts: description: the timeslices a process operates at (PRC_TS) - dims: [region, process, timeslice] - missing: absent + over: [region, process, timeslice] ts_map: description: each timeslice and the timeslices at or below it (TS_MAP) - dims: { region: region, s: timeslice, ts: timeslice } - missing: absent + over: [region, upper_timeslice, timeslice] parameters: coef_cpt: { dims: [region, vintage, period, process], description: the share of a vintage that still exists in a period } @@ -42,7 +38,7 @@ variables: act: description: activity of a vintage of a process in a timeslice (VAR_ACT) dims: [region, vintage, period, process, timeslice] - where: rtp_vintyr AND prc_ts + where: "prc_ts AND rtp_vintyr" bounds: { lower: 0 } constraints: @@ -55,7 +51,8 @@ constraints: dims: [region, period, process, timeslice] where: coef_af_up expression: >- - sum(sum(act, over=vintage), over=ts, by=ts_map[s]) + sum(sum(at(sum(act, over=vintage), by=ts_map[region, timeslice]), over=ts_map, by=ts_map[region, upper_timeslice]), + over=upper_timeslice, by=upper_timeslice[timeslice]) <= coef_af_up * prc_capact * g_yrfr * cap objective: From 9b83fa562f3b00eedfcbbef0c107797e2c44683d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 20:16:45 +0000 Subject: [PATCH 09/11] feat(language): a step along a member names the flat entry shift, sum_back and position along a member of an entry over the tuple were refused without a rewrite, or with an at() that does not apply. The message now names the entry over the members, confined with where: . The data contract leaves the storage of a tuple to the tool. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- docs/reference/language/dimensions.md | 14 ++++++------- src/mathspec/_dimensions.py | 29 ++++++++++++++++++--------- tests/test_tuple_dimensions.py | 21 +++++++++++++++++++ 3 files changed, 47 insertions(+), 17 deletions(-) diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index b64338d19..dbc419e75 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -353,19 +353,17 @@ $`\subseteq`$. mathspec refuses `missing:` on a dimension without `over:`. ### The data contract -With data attached, the labels of `connection` are one column whose values -have one field per member, named after the member: `{unit: u1, port: out}`. -The [maps of the members](#the-maps-of-the-dimension) take their labels from -these fields, so a tool reads no column of the table of the dimension for -them. A tool requires three things of the column: +With data attached, a label of `connection` is one tuple with one field per +member, named after the member: `{unit: u1, port: out}`. A tool or a data store +chooses how it stores the tuples: one column of records, or one column per +member. Either form gives the same labels, so the choice changes no spec. The +[maps of the members](#the-maps-of-the-dimension) take their labels from the +fields. A tool requires three things of the tuples: - Each tuple appears once. - Every field is a label of its dimension. - Under `missing: refused`, every combination of member labels appears. -mathspec declares no type for the tuple, so a tool may store the label in any -form that keeps the fields. - ## `alias` An entry is over each dimension once. An alias is the same labels under a diff --git a/src/mathspec/_dimensions.py b/src/mathspec/_dimensions.py index a1b61e457..57656cdee 100644 --- a/src/mathspec/_dimensions.py +++ b/src/mathspec/_dimensions.py @@ -169,14 +169,8 @@ def _check_translation(node: Translate | WindowSum, inner: frozenset[str], spec: """``shift`` and ``sum_back`` keep every dim, and a named amount and a partition are checked here.""" verb = _VERBS[type(node)] if node.along not in inner: - raise DimensionError( - _not_carried( - context, - f'{verb}(along={node.along})', - inner, - f'Name a dimension the operand carries, or remove the {verb}', - ) - ) + rewrite = _step_member(node.along, inner, spec) or f'Name a dimension the operand carries, or remove the {verb}' + raise DimensionError(_not_carried(context, f'{verb}(along={node.along})', inner, rewrite)) _check_named_amount(node, verb, inner, spec, context) if node.partition is not None: within = f'{node.partition.name}[{", ".join(node.partition.grouped)}]' @@ -256,6 +250,20 @@ def _at_member( return None +def _step_member(along: str, frame: Iterable[str], spec: Spec) -> str | None: + """The rewrite for a step along *along*, a member of a dimension in *frame*, or ``None`` where it is no member. + + A tuple has no order, so the step runs in an entry over the members, + confined to the tuples by the bare name of the dimension. + """ + for name in sorted(frame): + members = sorted({dim for _, dim in spec.dimensions[name].members}) + if along in members: + flat = sorted({*members, *frame} - {name}) + return f'{_one_dimension([along], name)}. Declare the entry over dims: {flat}, with where: {name}' + return None + + def _one_dimension(wanted: list[str], name: str) -> str: """That the dims *wanted* are members of *name*, which an operator reads as one dimension.""" noun = 'is a member' if len(wanted) == 1 else 'are members' @@ -473,8 +481,11 @@ def _check_condition_dims(mask: Mask | None, frame: frozenset[str], context: str case _: assert_never(atom) read = atom.name if isinstance(atom, ParameterDefined | ParameterComparison | VariableDefined) else None + stepped = _step_member(atom.name, frame, spec) if isinstance(atom, DimensionPosition) else None rewrite = ( - _at_member(outside, frame, spec, read=read) or 'Add them to dims:, or test a name over the declared dims' + stepped + or _at_member(outside, frame, spec, read=read) + or 'Add them to dims:, or test a name over the declared dims' ) raise DimensionError( f'{context}: {leaf} reads dims {outside} outside the declared dims {sorted(frame)}. {rewrite}.' diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py index 9f593a309..e4fd24ace 100644 --- a/tests/test_tuple_dimensions.py +++ b/tests/test_tuple_dimensions.py @@ -275,6 +275,27 @@ def test_a_tuple_dimension_tests_membership_only_where_the_entry_has_every_membe assert 'outside the declared dims' in message +_STEPPED = {'dimensions.span': {'over': ['unit', 'period']}, 'variables.out': {'dims': ['span']}} + + +@pytest.mark.parametrize( + 'patch', + [ + pytest.param(_constraint('out - shift(out, along=period, offset=1) <= 1', ['span']), id='shift'), + pytest.param(_constraint('sum_back(out, along=period, window=2) <= 1', ['span']), id='sum-back'), + pytest.param( + {'constraints.probe': {'dims': ['span'], 'where': 'position(period) > 0', 'expression': 'out <= 1'}}, + id='position', + ), + ], +) +def test_a_step_along_a_member_of_an_entry_over_the_tuple_names_the_flat_entry(patch): + """The entry is over the tuple, which has no order, so the rewrite is the entry over the members, confined by the tuple.""" + message = _refusal(**_STEPPED, **patch) + assert "'period' is a member of 'span'" in message, message + assert "dims: ['period', 'unit'], with where: span" in message, message + + def test_a_condition_compares_a_member_label(): spec = to_spec(varied(MODEL, **{'variables.flow.where': "connection[unit] == 'gas'"})) (atom,) = spec.program.variables['flow'].where.atoms From ba4ef2b6618606bb12d1a3bc933a061692ffeec7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 20:25:05 +0000 Subject: [PATCH 10/11] feat(language)!: the section of lookups is called mappings `maps:` is renamed to `mappings:`, `MapSpec` to `MappingSpec` and `Spec.maps` to `Spec.mappings`. Messages, docstrings, the reference, the examples and the figures say "mapping", and a read is written `subject[mapping]`. The math symbol of a group stays `map(t)`. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA4HppT8Z4pzepcHkj9 --- CHANGELOG.md | 6 +- docs/about/limits.md | 14 +- docs/about/overview.md | 2 +- docs/about/relations-as-linear-maps.md | 36 +-- docs/about/sql-and-dataframes.md | 6 +- docs/contributing.md | 2 +- docs/examples/connection.md | 2 +- docs/examples/index.md | 2 +- docs/examples/library/composed.md | 2 +- docs/examples/library/generator.md | 2 +- docs/examples/library/load.md | 2 +- docs/examples/library/surface.md | 2 +- docs/examples/operators.md | 30 +- docs/examples/pypsa/generator_commitment.md | 2 +- docs/examples/sparse.md | 2 +- docs/examples/times/trade.md | 4 +- docs/howto/compose.md | 12 +- docs/howto/declare-a-column.md | 8 +- docs/howto/index.md | 2 +- docs/reference/composition.md | 100 +++---- docs/reference/glossary.md | 14 +- docs/reference/index.md | 4 +- docs/reference/language/absence.md | 40 +-- docs/reference/language/assumptions.md | 16 +- docs/reference/language/dimensions.md | 12 +- docs/reference/language/errors.md | 4 +- docs/reference/language/expressions.md | 58 ++-- docs/reference/language/file.md | 2 +- docs/reference/language/index.md | 2 +- docs/reference/language/named.md | 4 +- docs/reference/language/operators.md | 36 +-- .../parameters-variables-constraints.md | 8 +- docs/reference/language/piecewise.md | 62 ++-- docs/reference/language/relations.md | 152 +++++----- docs/reference/notation.md | 70 ++--- docs/reference/reading.md | 26 +- docs/static/absence-relation-missing.svg | 8 +- docs/static/expressions-at-condition.svg | 6 +- docs/static/expressions-position.svg | 4 +- docs/static/linear-maps-at.svg | 8 +- docs/static/linear-maps-empty.svg | 6 +- docs/static/linear-maps-join.svg | 8 +- docs/static/operators-at.svg | 4 +- docs/static/operators-shift-within.svg | 4 +- docs/static/operators-sum.svg | 6 +- docs/static/parameters-where.svg | 4 +- docs/static/relations-at.svg | 6 +- docs/static/relations-missing.svg | 6 +- docs/static/relations-partition.svg | 6 +- docs/static/relations-sum-by.svg | 8 +- docs/tutorials/first-spec.md | 4 +- docs/tutorials/several-files.md | 4 +- docs/tutorials/storage.md | 4 +- examples/connection.yaml | 2 +- examples/library/generator.yaml | 2 +- examples/library/load.yaml | 2 +- examples/library/surface.yaml | 2 +- examples/operators/at.yaml | 4 +- examples/operators/at_columns.yaml | 6 +- examples/operators/shift_partitioned.yaml | 2 +- examples/operators/sum_back_partitioned.yaml | 2 +- examples/operators/sum_by.yaml | 4 +- examples/operators/sum_by_column_lists.yaml | 6 +- examples/operators/sum_by_columns.yaml | 4 +- examples/piecewise_coupling.yaml | 2 +- examples/pypsa.yaml | 2 +- examples/pypsa/flow_based.yaml | 2 +- examples/pypsa/generator.yaml | 2 +- examples/pypsa/generator_commitment.yaml | 2 +- examples/pypsa/generator_ramping.yaml | 2 +- examples/pypsa/line.yaml | 2 +- examples/pypsa/link.yaml | 2 +- examples/pypsa/link_commitment.yaml | 2 +- examples/pypsa/link_ramping.yaml | 2 +- examples/pypsa/load.yaml | 2 +- examples/pypsa/power_flow.yaml | 2 +- examples/pypsa/process.yaml | 2 +- examples/pypsa/process_commitment.yaml | 2 +- examples/pypsa/process_ramping.yaml | 2 +- examples/pypsa/security.yaml | 2 +- examples/pypsa/settings.yaml | 2 +- examples/pypsa/storage_unit.yaml | 2 +- examples/pypsa/store.yaml | 2 +- examples/pypsa/transformer.yaml | 2 +- examples/sparse.yaml | 2 +- examples/times/trade.yaml | 2 +- mkdocs.yml | 4 +- schema/mathspec.schema.json | 20 +- src/mathspec/_advising.py | 2 +- src/mathspec/_composition.py | 48 +-- src/mathspec/_condition_parser.py | 6 +- src/mathspec/_condition_resolver.py | 64 ++-- src/mathspec/_dimensions.py | 6 +- src/mathspec/_exclusivity.py | 16 +- src/mathspec/_expression_resolver.py | 50 ++-- src/mathspec/_lowering.py | 2 +- src/mathspec/_operators.py | 8 +- src/mathspec/_piecewise.py | 36 +-- src/mathspec/_renaming.py | 26 +- src/mathspec/_separability.py | 6 +- src/mathspec/_typesetting/README.md | 2 +- src/mathspec/_typesetting/legend.py | 12 +- src/mathspec/_typesetting/symbols.py | 2 +- src/mathspec/_typesetting/walk.py | 12 +- src/mathspec/_validation.py | 38 +-- src/mathspec/program.py | 38 +-- src/mathspec/spec.py | 56 ++-- tests/fixtures.py | 12 +- tests/fixtures/every_program_node.yaml | 2 +- tests/fixtures/pypsa_standard_shape.yaml | 2 +- tests/test_advice.py | 10 +- tests/test_boundedness.py | 2 +- tests/test_canonical.py | 16 +- tests/test_composition.py | 98 +++--- tests/test_dimensions.py | 34 +-- tests/test_exclusivity.py | 36 +-- tests/test_expansion.py | 14 +- tests/test_given.py | 8 +- tests/test_lowering.py | 60 ++-- tests/test_parser.py | 2 +- tests/test_piecewise.py | 68 ++--- tests/test_pypsa_collapses.py | 2 +- tests/test_renaming.py | 24 +- tests/test_separability.py | 22 +- tests/test_terms.py | 4 +- tests/test_validation.py | 280 +++++++++--------- tests/typesetting/golden/latex.out | 4 +- tests/typesetting/golden/markdown.out | 4 +- tests/typesetting/golden/model.yaml | 42 +-- tests/typesetting/golden/typst.out | 4 +- tests/typesetting/test_golden.py | 2 +- tests/typesetting/test_symbols.py | 6 +- tests/typesetting/test_walk.py | 34 +-- tools/notation.py | 34 +-- tools/pypsa_split.py | 20 +- tools/spec_math.py | 2 +- 136 files changed, 1122 insertions(+), 1104 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 85cffa596..78e52e7f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,9 +12,9 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## Upcoming version -- feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) - - Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a map under `maps:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[map]`, such as `generator[bus]`. - - Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[map]`. +- feat!: mappings give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) + - Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a mapping under `mappings:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[mapping]`, such as `generator[bus]`. + - Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[mapping]`. - docs(examples): TIMES examples and a sparse-set example ([#1021](https://github.com/energy-models/mathspec/pull/1021)) - docs(pypsa): the example page shows one fragment ([#1010](https://github.com/energy-models/mathspec/pull/1010)) - feat(composition): rename gives a spec other names ([#1002](https://github.com/energy-models/mathspec/pull/1002)) diff --git a/docs/about/limits.md b/docs/about/limits.md index c066f1012..f18d8ae28 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -110,13 +110,13 @@ limit does not depend on what solvers take. mathspec refuses a request when a construct that exists already states the same thing. -| Request | Why refused | What you write instead | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| A `where` comparing the label that each row has ([a map](../reference/language/relations.md#maps)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The map already gives each row its label. | A sum or a lookup through the map. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the map gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). | -| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. | -| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | -| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | -| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | +| Request | Why refused | What you write instead | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A `where` comparing the label that each row has ([a mapping](../reference/language/relations.md#mappings)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The mapping already gives each row its label. | A sum or a lookup through the mapping. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the mapping gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). | +| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. | +| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | +| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | +| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | ### Data preparation diff --git a/docs/about/overview.md b/docs/about/overview.md index a91b76880..2bf2de79c 100644 --- a/docs/about/overview.md +++ b/docs/about/overview.md @@ -94,7 +94,7 @@ and the engine that attaches the data checks the condition. - [`missing:`](../reference/language/absence.md#missing) on a parameter, a table that pairs labels ([a relation](../reference/language/relations.md)) or a - [map](../reference/language/relations.md#maps) sets what a missing row or + [mapping](../reference/language/relations.md#mappings) sets what a missing row or label means. When the engine attaches the data, it refuses a missing row by default. - An [`assumptions:`](../reference/language/assumptions.md) entry is a condition that the data must meet. diff --git a/docs/about/relations-as-linear-maps.md b/docs/about/relations-as-linear-maps.md index 30aca65a5..749159c05 100644 --- a/docs/about/relations-as-linear-maps.md +++ b/docs/about/relations-as-linear-maps.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: CC-BY-4.0 A [`sum`](../reference/language/operators.md#sum) or an [`at`](../reference/language/operators.md#at) through a table that gives each -row a label ([a map](../reference/language/relations.md#maps)) is the product +row a label ([a mapping](../reference/language/relations.md#mappings)) is the product of a matrix and a vector. The relations page describes the same sum in database words, "joined on" and "grouped by". The matrix form is the sum in the form a paper uses. @@ -21,7 +21,7 @@ dimensions: zone: { dtype: str } relations: zone_of: { dims: [generator, snapshot], missing: absent } -maps: +mappings: zone_of: { zone: { dim: zone } } parameters: zone_cap: { dims: [snapshot, zone] } @@ -40,17 +40,17 @@ objective: expression: sum(p) ``` -`zonal` contains a sum of `p` through the map `zone_of[zone]`, and -`looked_up` a lookup of `zone_cap` through the same map. The spec loads. +`zonal` contains a sum of `p` through the mapping `zone_of[zone]`, and +`looked_up` a lookup of `zone_cap` through the same mapping. The spec loads. ## The indicator of a relation A relation with columns over the dimensions $`D_1, \dots, D_n`$ is a set of rows, so it is a subset $`R \subseteq D_1 \times \dots \times D_n`$. Its **indicator** $`\mathbf{1}_R`$ is $`1`$ at a row of the table and $`0`$ -everywhere else. A [map](../reference/language/relations.md#maps) gives each +everywhere else. A [mapping](../reference/language/relations.md#mappings) gives each row of its subject one label, and a row is one combination of key labels (a -key tuple). So a map from the key $`K`$ of its subject into the dimension +key tuple). So a mapping from the key $`K`$ of its subject into the dimension $`V`$ is a function $`f: K \to V`$. The set of pairs $`(k, f(k))`$ is a relation $`R`$ (the graph of $`f`$), and its indicator is @@ -70,14 +70,14 @@ generators, snapshots and zones, `zone_of[zone]` in the spec above is a partial $`f: \mathcal{G} \times \mathcal{T} \to \mathcal{Z}`$, because the relation `zone_of` declares `missing: absent`. -A [relation](../reference/language/relations.md#relations) with no map is a +A [relation](../reference/language/relations.md#relations) with no mapping is a subset with no function behind it. So one generator may sit in several rows, each with its own bus. By default a relation also lists every key tuple, so one that does not must declare `missing: absent`. -Every column of a relation is in its key, so a relation with no map has no +Every column of a relation is in its key, so a relation with no mapping has no label for `at` to read. At load, mathspec refuses `at` through a relation with -no map. +no mapping. ## A join and group-by as a contraction @@ -107,7 +107,7 @@ index can take in the formula: | joined on, the column in `over=` | $`g`$ is on both factors and summed. It is not in the result. | | grouped by, the column in `by=` | $`z`$ is on the indicator alone and not summed. It is in the result. | | joined on and grouped by, a key column the call does not name | $`t`$ is on both factors and not summed. It is in the result. | -| neither, a map the call does not name | The map is not in the formula, and the sum does not use it. | +| neither, a mapping the call does not name | The mapping is not in the formula, and the sum does not use it. | The result has the **free indices**, which are the indices that are not summed. They are the indices of the operand and of the indicator together, @@ -129,9 +129,9 @@ formula needs each of them: At each $`t`$, the matrix $`M_t[z, g] = \mathbf{1}_R(g, t, z)`$ has one row per zone and one column per generator, with entries of zero and one, and $`y_t = M_t\, p_t`$. Over all snapshots, the key column that the call does not name makes the -matrix zero outside one block per snapshot (**block-diagonal**). A map of a subject with one key column has one block. +matrix zero outside one block per snapshot (**block-diagonal**). A mapping of a subject with one key column has one block. -## A lookup through a map +## A lookup through a mapping `at(zone_cap, by=zone_of[zone])` joins the same table, and sums over the other index: @@ -236,12 +236,12 @@ With the data in the figure, no generator maps to `south`, so both rows of ## Partitions and tests -The other two uses of a map, a +The other two uses of a mapping, a [partition](../reference/language/relations.md#partitions) and a [test](../reference/language/relations.md#tests), are not matrix products. An operator with `within=`, such as `shift`, works separately on each set of members that $`f`$ sends to one value (a fibre). The dimensions of the result -do not change. With the map `snapshot: { season: { dim: season } }`, +do not change. With the mapping `snapshot: { season: { dim: season } }`, `shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[season])` steps back within each season: @@ -253,16 +253,16 @@ Each season is one fibre of `snapshot[season]`, so no value crosses from winter summer. A test is an indicator. In a `where`, the name of a relation is -$`\mathbf{1}_R`$ at the coordinate of the entry, and a map alone, such as +$`\mathbf{1}_R`$ at the coordinate of the entry, and a mapping alone, such as `zone_of[zone]`, is the indicator of the domain of $`f`$. -You can now judge the dimensions of a sum or an `at` through a map, and +You can now judge the dimensions of a sum or an `at` through a mapping, and why the language has no `join` operator. !!! info "See also" - - [relations and maps](../reference/language/relations.md), for every key a - relation and a map accept + - [relations and mappings](../reference/language/relations.md), for every key a + relation and a mapping accept - [how dimensions combine](../reference/language/expressions.md#how-dimensions-combine), for the rule that sets the free indices of every expression - [how absence travels](../reference/language/absence.md#how-absence-travels), diff --git a/docs/about/sql-and-dataframes.md b/docs/about/sql-and-dataframes.md index ca0905eb7..43a617410 100644 --- a/docs/about/sql-and-dataframes.md +++ b/docs/about/sql-and-dataframes.md @@ -19,7 +19,7 @@ dimensions: snapshot: { dtype: int, ordered: true } generator: { dtype: str } bus: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } parameters: load: { dims: [snapshot, bus] } @@ -72,8 +72,8 @@ coordinate of `(snapshot, bus)`. A [relation](../reference/language/relations.md#relations) is a table whose columns are all in its primary key, so it lists which combinations of labels -exist. A [map](../reference/language/relations.md#maps) is a column of the -table of its subject. `generator: { bus: { dim: bus } }` under `maps:` is a table +exist. A [mapping](../reference/language/relations.md#mappings) is a column of the +table of its subject. `generator: { bus: { dim: bus } }` under `mappings:` is a table `generator` with the columns `generator` and `bus`, and one row per generator. Under the default `missing: refused`, every generator needs a bus. Under [`missing: absent`](../reference/language/relations.md#missing), the bus of a diff --git a/docs/contributing.md b/docs/contributing.md index 0f7c8ac9e..d4f3431ef 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -183,7 +183,7 @@ only when it meets these conditions: argument, such as `over=snapshot`. - It reads a bounded number of rows for each row of its result. It may filter rows on a column they already have, or join each row against a parameter, a - relation or a map. It may also read neighbouring rows at a fixed offset, or only + relation or a mapping. It may also read neighbouring rows at a fixed offset, or only the coordinate labels. - If it reads every row, it reads them in one pass over the data. That pass ends before a tool that builds the model diff --git a/docs/examples/connection.md b/docs/examples/connection.md index 8d22fb1f6..61d2fc36d 100644 --- a/docs/examples/connection.md +++ b/docs/examples/connection.md @@ -38,7 +38,7 @@ relations: dims: [unit, port] missing: absent -maps: +mappings: connection: { bus: { dim: bus }, role: { dim: role } } parameters: diff --git a/docs/examples/index.md b/docs/examples/index.md index 6f08b0868..5ab3a13c5 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -23,7 +23,7 @@ like yours, and what each line of the file means. inequality covers a running unit and a starting unit. [Open →](commitment.md) - **Units with ports** - One relation lists the ports of each unit, maps give each port a bus and + One relation lists the ports of each unit, mappings give each port a bus and a role, and a parameter with `where:` keeps only the output ports. [Open →](connection.md) - **A sparse set, read four ways** diff --git a/docs/examples/library/composed.md b/docs/examples/library/composed.md index ecdca69e9..da0d3a84b 100644 --- a/docs/examples/library/composed.md +++ b/docs/examples/library/composed.md @@ -52,7 +52,7 @@ dimensions: load: {dtype: str, description: 'demands, each on one port'} port: {dtype: str, description: 'the connections components make, one label per connection'} snapshot: {dtype: datetime, description: dispatch periods} -maps: +mappings: generator: port: {dim: port} load: diff --git a/docs/examples/library/generator.md b/docs/examples/library/generator.md index f85e64db7..040c37ceb 100644 --- a/docs/examples/library/generator.md +++ b/docs/examples/library/generator.md @@ -32,7 +32,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } port: { dtype: str, description: "the connections components make, one label per connection" } generator: { dtype: str, description: "generating units, each on one port" } -maps: +mappings: generator: { port: { dim: port } } parameters: Generator_p_nom: { dims: [generator], description: nominal power } diff --git a/docs/examples/library/load.md b/docs/examples/library/load.md index cbe13e09e..87027c50b 100644 --- a/docs/examples/library/load.md +++ b/docs/examples/library/load.md @@ -23,7 +23,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } port: { dtype: str, description: "the connections components make, one label per connection" } load: { dtype: str, description: "demands, each on one port" } -maps: +mappings: load: { port: { dim: port } } parameters: Load_p_set: { dims: [snapshot, load], description: "`Load-p_set` — what a load takes in a snapshot" } diff --git a/docs/examples/library/surface.md b/docs/examples/library/surface.md index 3b2158ac3..7342bd337 100644 --- a/docs/examples/library/surface.md +++ b/docs/examples/library/surface.md @@ -30,7 +30,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } bus: { dtype: str, description: network nodes } port: { dtype: str, description: "the connections components make, one label per connection" } -maps: +mappings: port: { bus: { dim: bus } } variables: Port_p: diff --git a/docs/examples/operators.md b/docs/examples/operators.md index 0f1c49448..fc9d91156 100644 --- a/docs/examples/operators.md +++ b/docs/examples/operators.md @@ -114,7 +114,7 @@ $`\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{c,g,t} \le \mathrm{limit}_{c} ```yaml description: >- A sum by group: `sum(array, over=dim, by=subject[m])` groups the result by - the label that map `m` gives each row. The data of the map, not the file, + the label that mapping `m` gives each row. The data of the mapping, not the file, sets which generator sits at which bus. dimensions: @@ -122,7 +122,7 @@ dimensions: generator: { dtype: str } bus: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } parameters: @@ -150,7 +150,7 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = b} p_{g,t} \le \mathrm{limit}_ ```yaml description: >- A sum that keeps a key column: `sum(array, over=dim, by=subject[m])` joins - on the column over `dim` and groups by map `m`. The sum also joins on the + on the column over `dim` and groups by mapping `m`. The sum also joins on the key column that the call does not list. It keeps that column, so each zone gets one total per period. @@ -162,7 +162,7 @@ dimensions: relations: zone_of: { dims: [generator, period] } -maps: +mappings: zone_of: { zone: { dim: zone } } parameters: @@ -189,8 +189,8 @@ $`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ e) = z} p_{g,e} \ge \mathrm{de ```yaml description: >- - Several columns and maps: `sum(array, over=[dim, …], by=subject[m, …])` - joins on both columns of the relation and groups by both of its maps. + Several columns and mappings: `sum(array, over=[dim, …], by=subject[m, …])` + joins on both columns of the relation and groups by both of its mappings. dimensions: generator: { dtype: str } @@ -201,7 +201,7 @@ dimensions: relations: slot_of: { dims: [generator, period] } -maps: +mappings: slot_of: { bus: { dim: bus }, technology: { dim: technology } } parameters: @@ -229,13 +229,13 @@ $`\sum_{g \in \mathcal{G},\ e \in \mathcal{E} \,:\, \mathrm{bus}(g,\ e) = b \wed ```yaml description: >- The join without a grouping: `at(array, by=subject[m])` takes, for each - `snapshot`, the value at the `period` that the map gives that snapshot. + `snapshot`, the value at the `period` that the mapping gives that snapshot. dimensions: snapshot: { dtype: int } period: { dtype: int } -maps: +mappings: snapshot: { period: { dim: period } } parameters: @@ -256,21 +256,21 @@ objective: { sense: minimize, expression: sum(p) } $`p_{t} \le \mathrm{cap}_{\mathrm{period}(t)} \qquad \forall\, t \in \mathcal{T}`$ -### `at(array, by=subject[m]), two maps into one dimension` +### `at(array, by=subject[m]), two mappings into one dimension` `examples/operators/at_columns.yaml` ```yaml description: >- - One of two maps: where a subject has two maps into one dimension, - `at(array, by=subject[m])` takes the value at the label of map `m`. Here `m` + One of two mappings: where a subject has two mappings into one dimension, + `at(array, by=subject[m])` takes the value at the label of mapping `m`. Here `m` is `bus0`, the sending end of a line. dimensions: line: { dtype: str } bus: { dtype: str } -maps: +mappings: line: { bus0: { dim: bus }, bus1: { dim: bus } } parameters: @@ -419,7 +419,7 @@ dimensions: snapshot: { dtype: int, ordered: true } season: { dtype: str } -maps: +mappings: snapshot: { season: { dim: season } } variables: @@ -552,7 +552,7 @@ dimensions: hour: { dtype: int, ordered: true } day: { dtype: str } -maps: +mappings: hour: { day: { dim: day } } variables: diff --git a/docs/examples/pypsa/generator_commitment.md b/docs/examples/pypsa/generator_commitment.md index d0d12784d..6982252b6 100644 --- a/docs/examples/pypsa/generator_commitment.md +++ b/docs/examples/pypsa/generator_commitment.md @@ -70,7 +70,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/docs/examples/sparse.md b/docs/examples/sparse.md index 0581da6cd..1c13fec41 100644 --- a/docs/examples/sparse.md +++ b/docs/examples/sparse.md @@ -45,7 +45,7 @@ relations: dims: [unit, period] missing: absent -maps: +mappings: connection: bus: { dim: bus, description: the bus a port feeds } diff --git a/docs/examples/times/trade.md b/docs/examples/times/trade.md index 392253454..4d0bdbe30 100644 --- a/docs/examples/times/trade.md +++ b/docs/examples/times/trade.md @@ -15,7 +15,7 @@ which TIMES writes with a second name for each set, `ALIAS(REG,R)` in mathspec refuses an entry over one dimension twice. This spec declares a dimension `trade_link`, whose labels the data invents, one per link, and - the maps of `trade_link` give each link its two regions and two + the mappings of `trade_link` give each link its two regions and two commodities. Nothing refuses two labels for the same link, and a row of `ire_flo` for a process that does not carry the link is dropped, not refused. Issue [#969](https://github.com/energy-models/mathspec/issues/969) @@ -39,7 +39,7 @@ dimensions: process: { description: a technology that carries trade } trade_link: { description: "one link from a region and commodity to another, a label the data invents" } -maps: +mappings: trade_link: # the region and commodity at each end of a link from_commodity: { dim: commodity } from_region: { dim: region } diff --git a/docs/howto/compose.md b/docs/howto/compose.md index 6b42d74db..1ffcfdfc5 100644 --- a/docs/howto/compose.md +++ b/docs/howto/compose.md @@ -61,7 +61,7 @@ names, so that one file states several components. You need mathspec snapshot: { dtype: int } bus: { dtype: str } generator: { dtype: str } - maps: + mappings: generator: { bus: { dim: bus } } parameters: Generator_p_nom: { dims: [generator] } @@ -85,7 +85,7 @@ names, so that one file states several components. You need mathspec snapshot: { dtype: int } bus: { dtype: str } load: { dtype: str } - maps: + mappings: load: { bus: { dim: bus } } parameters: Load_p_set: { dims: [snapshot, load] } @@ -158,7 +158,7 @@ Add a new file with a term of its own, and leave `network.yaml` as it is. snapshot: { dtype: int, ordered: true } bus: { dtype: str } store: { dtype: str } - maps: + mappings: store: { bus: { dim: bus } } parameters: Store_e_nom: { dims: [store] } @@ -214,7 +214,7 @@ it other names with [`rename`](../reference/api.md#mathspec.rename). snapshot: { dtype: int } bus: { dtype: str } unit: { dtype: str } - maps: + mappings: unit: { bus: { dim: bus } } parameters: Unit_p_nom: { dims: [unit] } @@ -270,7 +270,7 @@ it other names with [`rename`](../reference/api.md#mathspec.rename). Each renamed fragment adds its own terms to the two sums. -To change only a few names, pass a map from each old name to its new name: +To change only a few names, pass a mapping from each old name to its new name: ```python spec = ms.rename('generator.yaml', {'Generator_p_nom': 'Generator_capacity'}) @@ -453,7 +453,7 @@ in the spec as a named expression that no sum includes. - [refusals](../reference/composition.md#refusals), for each message that `merge` and `override` give - [`rename`](../reference/composition.md#rename), for what a rename changes - and keeps, and each map that it refuses + and keeps, and each mapping that it refuses - [a spec in several files](../tutorials/several-files.md), for a lesson in which you build a library step by step - [a component library](../examples/library/index.md), for a larger library diff --git a/docs/howto/declare-a-column.md b/docs/howto/declare-a-column.md index ec1241c75..747ab03d0 100644 --- a/docs/howto/declare-a-column.md +++ b/docs/howto/declare-a-column.md @@ -3,7 +3,7 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> -# Choose between a dimension, a relation, a map and a parameter +# Choose between a dimension, a relation, a mapping and a parameter This guide shows how to choose the declaration for a [column](../reference/glossary.md#column) of your data, in @@ -19,7 +19,7 @@ Use the first row that fits what you do with the column in the spec: | In the spec you… | For example | So declare it as | | --------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | index parameters, variables or constraints over the rows the column lists | `generator`, `snapshot` | a [`dimension`](../reference/language/dimensions.md) | -| look up a label of another dimension, one per row | the bus of each generator | a [`map`](../reference/language/relations.md#maps) of `generator` into `bus`, a dimension | +| look up a label of another dimension, one per row | the bus of each generator | a [`mapping`](../reference/language/relations.md#mappings) of `generator` into `bus`, a dimension | | list which pairs of two dimensions exist, with no value | `connection`, the buses a generator may connect to | a [`relation`](../reference/language/relations.md#relations) with [`missing: absent`](../reference/language/relations.md#missing) | | use its numbers in an expression or a bound | `cost` per generator, `availability` per generator and snapshot | a [`parameter`](../reference/language/parameters-variables-constraints.md#parameters) over the dimensions that index it | | test its values in a [condition](../reference/language/expressions.md#conditions) | `fuel`, `is_committable` | a `str` or `bool` parameter | @@ -37,7 +37,7 @@ dimensions: relations: connection: { dims: [generator, bus], missing: absent } -maps: +mappings: generator: { bus: { dim: bus } } parameters: @@ -106,6 +106,6 @@ spec and has no remark that is not a refusal - [Check a spec without data](check.md), for how to read a refusal or advice. - [Dimensions](../reference/language/dimensions.md), - [relations and maps](../reference/language/relations.md) and + [relations and mappings](../reference/language/relations.md) and [parameters](../reference/language/parameters-variables-constraints.md#parameters), for every key of each declaration. diff --git a/docs/howto/index.md b/docs/howto/index.md index 5560aa699..8bb00c93a 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -28,7 +28,7 @@ To learn the language from the start, follow the
-- **[Choose between a dimension, a relation, a map and a parameter](declare-a-column.md)** +- **[Choose between a dimension, a relation, a mapping and a parameter](declare-a-column.md)** for a column of your data. - **[State a rule that differs by case](cases.md)**, such as committable and non-committable generators, in one spec. diff --git a/docs/reference/composition.md b/docs/reference/composition.md index a14bc4936..e49799689 100644 --- a/docs/reference/composition.md +++ b/docs/reference/composition.md @@ -83,7 +83,7 @@ dimensions: snapshot: { dtype: int } bus: { dtype: str } generator: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } parameters: Generator_p_nom: { dims: [generator] } @@ -107,7 +107,7 @@ dimensions: snapshot: { dtype: int } bus: { dtype: str } load: { dtype: str } -maps: +mappings: load: { bus: { dim: bus } } parameters: Load_p_set: { dims: [snapshot, load] } @@ -134,7 +134,7 @@ dimensions: generator: {dtype: str} load: {dtype: str} snapshot: {dtype: int} -maps: +mappings: generator: {bus: { dim: bus }} load: {bus: { dim: bus }} parameters: @@ -176,21 +176,21 @@ The objective is the one that `network.yaml` sets. ### Each kind of entry Two fragments may share a [dimension](language/dimensions.md), a -[relation](language/relations.md#relations), a [map](language/relations.md#maps), a given entry or a +[relation](language/relations.md#relations), a [mapping](language/relations.md#mappings), a given entry or a sum. -| The entry | What `merge` does | -| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| a dimension, a relation or a map | accepts it from every fragment that declares it, where every fragment declares it the same way | -| a `description` on a shared dimension, relation or map | keeps the first wording in the list | -| `ordered: true` on a shared dimension | makes the dimension ordered if one fragment sets it | -| `missing:` on a shared relation or map | requires the same value from every fragment that declares it, where `missing: refused` and no `missing:` are one value | -| an entry under `given:` | checks it against the fragment that declares the name, then folds it in ([given entries](#given-entries)) | -| an expression with `adds_to:` | adds it as a term to the sum in its `adds_to:` ([terms and sums](#terms-and-sums)) | -| `objective` | takes it from the one fragment that sets it, and refuses a second | -| `version` | requires the same value from every fragment | -| `description` at the top of a fragment | drops it | -| any other entry | takes it from the one fragment that declares it, and refuses a second | +| The entry | What `merge` does | +| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| a dimension, a relation or a mapping | accepts it from every fragment that declares it, where every fragment declares it the same way | +| a `description` on a shared dimension, relation or mapping | keeps the first wording in the list | +| `ordered: true` on a shared dimension | makes the dimension ordered if one fragment sets it | +| `missing:` on a shared relation or mapping | requires the same value from every fragment that declares it, where `missing: refused` and no `missing:` are one value | +| an entry under `given:` | checks it against the fragment that declares the name, then folds it in ([given entries](#given-entries)) | +| an expression with `adds_to:` | adds it as a term to the sum in its `adds_to:` ([terms and sums](#terms-and-sums)) | +| `objective` | takes it from the one fragment that sets it, and refuses a second | +| `version` | requires the same value from every fragment | +| `description` at the top of a fragment | drops it | +| any other entry | takes it from the one fragment that declares it, and refuses a second | ### Terms and sums @@ -432,10 +432,10 @@ patched `dispatch` has no row at `old`. | a whole entry under a new name | adds it | | a named expression as a [bare string](language/named.md#expressions) | replaces only its body, `expression:` or `cases:`, and keeps its `dims:`, description and `adds_to:`, so the new body may have no dimension outside those `dims:` | | `null` on an entry, a field or a section | applies the rule in [`null` in a patch](#null-in-a-patch) | -| a dimension, a relation or a map | adds it, or accepts it restated as the base declares it, field by field, where a field left out equals its default | -| `description:` on a dimension, a relation or a map of the base | replaces the description of the base, alone or with other fields, and `null` removes it | +| a dimension, a relation or a mapping | adds it, or accepts it restated as the base declares it, field by field, where a field left out equals its default | +| `description:` on a dimension, a relation or a mapping of the base | replaces the description of the base, alone or with other fields, and `null` removes it | | `ordered:` on a restated dimension | makes the dimension ordered for `true`, and refuses `false` over an ordered dimension | -| `missing:` on a relation or a map, alone or with other fields | changes whether every combination needs a row, or every row a label, as on a parameter | +| `missing:` on a relation or a mapping, alone or with other fields | changes whether every combination needs a row, or every row a label, as on a parameter | | an entry under one kind of `given:` | edits, adds or removes it like any entry, and keeps the other kinds | | `version`, `description` | replaces the value of the base | | a field that an earlier patch writes | replaces that value | @@ -504,8 +504,8 @@ description of `Generator_p_nom` still has the old name `Unit_p`. ### The `names` argument -- In a map, each key is a name and its value is the new name. `rename` replaces all - names at the same time, so two names can swap. An empty map returns +- In a mapping, each key is a name and its value is the new name. `rename` replaces all + names at the same time, so two names can swap. An empty mapping returns `source` loaded. - A function sets the new names by a rule. `rename` calls it once with each name that `source` declares or lists under @@ -518,19 +518,19 @@ A second call with the inverse map returns a spec with the ### What a rename changes -| The spec has | What `rename` does | -| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| a name as the key of an entry, in `dims:`, under `maps:`, in `adds_to:` or in `given:` | replaces the name | -| a name in an expression, `where:`, bound, case or assumption | replaces the name, and keeps the spaces and line breaks around it | -| a map or a relation column named after its dimension, such as `bus` in `unit[bus]` | replaces it with the dimension | -| a map or a relation column named after something else, such as `bus0` in `{bus0: bus}` | keeps it, and refuses a map that changes a name to or from it | -| a longer name that contains a renamed name, such as `Unit_p_nom` for `Unit_p` | keeps the longer name | -| a keyword of an operator, such as `over=` | keeps the keyword | -| a quoted label, a label under `one_of:`, or a number such as `1e6` | keeps the label or the number | -| the name of a case or of a piecewise link | keeps the name, because it is a label of rows | -| an argument of a macro, and the template text that uses it | keeps the argument | -| a fixed value of a field, such as `domain: integer` | keeps the value | -| a `description` | keeps the text as written | +| The spec has | What `rename` does | +| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | +| a name as the key of an entry, in `dims:`, under `mappings:`, in `adds_to:` or in `given:` | replaces the name | +| a name in an expression, `where:`, bound, case or assumption | replaces the name, and keeps the spaces and line breaks around it | +| a mapping or a relation column named after its dimension, such as `bus` in `unit[bus]` | replaces it with the dimension | +| a mapping or a relation column named after something else, such as `bus0` in `{bus0: bus}` | keeps it, and refuses a mapping that changes a name to or from it | +| a longer name that contains a renamed name, such as `Unit_p_nom` for `Unit_p` | keeps the longer name | +| a keyword of an operator, such as `over=` | keeps the keyword | +| a quoted label, a label under `one_of:`, or a number such as `1e6` | keeps the label or the number | +| the name of a case or of a piecewise link | keeps the name, because it is a label of rows | +| an argument of a macro, and the template text that uses it | keeps the argument | +| a fixed value of a field, such as `domain: integer` | keeps the value | +| a `description` | keeps the text as written | ## Refusals @@ -601,9 +601,9 @@ patch 'project.yaml' edits the constraint 'power_balnce', which its base does no ### A dimension restated differently -Over a dimension, a relation or a map that its base declares, a patch may +Over a dimension, a relation or a mapping that its base declares, a patch may change only `description`, a dimension's `ordered`, and the `missing` of a -relation or a map. A patch +relation or a mapping. A patch that writes any other field restates the entry. Every other field must then be as the base declares it, and a field the patch leaves out equals its default. @@ -658,8 +658,8 @@ Named expression 'Store_injection': it adds to 'Bus_injection', which this file ### A rename of a name the spec lacks -`rename` refuses a key of the map that `source` neither declares nor lists -under `given:`. Here the map has `Unit_pnom` in place of `Unit_p_nom`: +`rename` refuses a key of the mapping that `source` neither declares nor lists +under `given:`. Here the mapping has `Unit_pnom` in place of `Unit_p_nom`: ```text rename cannot change 'Unit_pnom', which the spec neither declares nor lists under 'given:'. Did you mean 'Unit_p_nom'? @@ -667,8 +667,8 @@ rename cannot change 'Unit_pnom', which the spec neither declares nor lists unde ### A new name that an entry already has -`rename` refuses a new name that an entry outside the map already has, because -the spec would then declare that name twice. Here the map is `{'Unit_p': 'Unit_p_nom'}`: +`rename` refuses a new name that an entry outside the mapping already has, because +the spec would then declare that name twice. Here the mapping is `{'Unit_p': 'Unit_p_nom'}`: ```text rename gives the variable 'Unit_p' the name 'Unit_p_nom', which the parameter 'Unit_p_nom' already has. Rename that one too, or choose another name. @@ -676,7 +676,7 @@ rename gives the variable 'Unit_p' the name 'Unit_p_nom', which the parameter 'U ### One new name for two names -`rename` refuses a map that gives two names the same new name. Here the map +`rename` refuses a mapping that gives two names the same new name. Here the mapping gives `Unit_p` and `Unit_p_nom` the new name `Generator_p`: ```text @@ -688,28 +688,28 @@ rename gives 'Unit_p' and 'Unit_p_nom' the one name 'Generator_p'. Give each a n `rename` refuses a new name that is an argument of a macro whose template uses the old name. The template would otherwise use the argument in place of the entry. Here the macro `scaled` has the argument `x` and the template -`x * Unit_marginal_cost`, and the map is `{'Unit_marginal_cost': 'x'}`: +`x * Unit_marginal_cost`, and the mapping is `{'Unit_marginal_cost': 'x'}`: ```text rename gives the parameter 'Unit_marginal_cost' the name 'x', which is an argument of the macro 'scaled', whose template uses 'Unit_marginal_cost'. Choose another name. ``` -### A name that is also a map +### A name that is also a mapping -`rename` refuses a map that changes a name to or from the name of a -[map](language/relations.md#maps) or a relation column that is not named after -its dimension. An expression such as `line[bus0]` reads the map by its name, -so the rename would change the map too. Here `line` has the maps -`{bus0: bus, bus1: bus}`, and the map is `{'bus0': 'price'}`: +`rename` refuses a mapping that changes a name to or from the name of a +[mapping](language/relations.md#mappings) or a relation column that is not named after +its dimension. An expression such as `line[bus0]` reads the mapping by its name, +so the rename would change the mapping too. Here `line` has the mappings +`{bus0: bus, bus1: bus}`, and the mapping is `{'bus0': 'price'}`: ```text -rename changes 'bus0' to 'price', and 'bus0' is also a map of 'line'. Give it another name in the file, or choose another name. +rename changes 'bus0' to 'price', and 'bus0' is also a mapping of 'line'. Give it another name in the file, or choose another name. ``` ### A renamed spec that does not load `rename` loads the renamed spec with `to_spec`, so a new name that is a built-in -operator gets the refusal of `to_spec`. Here the map is +operator gets the refusal of `to_spec`. Here the mapping is `{'Unit_p': 'sum'}`: ```text diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 9d35fc338..e1133e556 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -143,7 +143,7 @@ does not build](reading.md#what-a-program-does-not-build)). ## Group A group is the set of rows of a dimension or a relation to which one -[map](#map) gives one label. `within=[]` makes `shift`, +[mapping](#mapping) gives one label. `within=[]` makes `shift`, `sum_back` or `position()` work separately in each group, such as each season of a year ([partitions](language/relations.md#partitions)). @@ -167,12 +167,12 @@ expression before any tool reads it. A file declares its own macros under `macros:`, so a macro is the one construct a file can add ([macros](language/named.md#macros)). -## Map +## Mapping -A map gives each row of a dimension or a relation (its +A mapping gives each row of a dimension or a relation (its [subject](#subject)) one label of a dimension, such as the bus of each -generator. A condition or an operator reads it as `subject[map]`, as in -`generator[bus]` ([maps](language/relations.md#maps)). +generator. A condition or an operator reads it as `subject[mapping]`, as in +`generator[bus]` ([mappings](language/relations.md#mappings)). ## Missing row @@ -273,8 +273,8 @@ most two consecutive members are non-zero ([sos](language/piecewise.md#sos)). ## Subject -The subject of a map is a dimension or a relation, such as `generator` in -`generator[bus]` ([maps](language/relations.md#maps)). +The subject of a mapping is a dimension or a relation, such as `generator` in +`generator[bus]` ([mappings](language/relations.md#mappings)). ## Surface diff --git a/docs/reference/index.md b/docs/reference/index.md index 11a935b6b..12c330cd8 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -24,8 +24,8 @@ optimisation model ([a spec](glossary.md#spec)). `given:` section. - **[Dimensions](language/dimensions.md)** lists the keys of a named set of labels (a dimension). -- **[Relations and maps](language/relations.md)** lists the keys of a set of - combinations of labels (a relation) and of the label each row has (a map), +- **[Relations and mappings](language/relations.md)** lists the keys of a set of + combinations of labels (a relation) and of the label each row has (a mapping), and how an expression uses them. - **[Expressions](language/expressions.md)** defines the grammar of arithmetic and of conditions, and how dimensions combine. diff --git a/docs/reference/language/absence.md b/docs/reference/language/absence.md index 731c34885..a77e6fab6 100644 --- a/docs/reference/language/absence.md +++ b/docs/reference/language/absence.md @@ -53,17 +53,17 @@ contain. Eight constructs make a coordinate absent: -| Construct | What is absent | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `where:` on a variable | the variable, at the coordinates the condition excludes ([`where`](#where)) | -| `where:` on a parameter | the parameter, at the coordinates the condition excludes ([`where` on a parameter](parameters-variables-constraints.md#where)) | -| `where:` on a constraint | the row ([`where`](#where)) | -| `shift(x, along=d, offset=n)` without `edge=` | the expression, at the edge coordinate ([shift](operators.md#shift)) | -| a key with no row in a `missing: absent` relation | the relation, at that key ([relations](relations.md#missing)) | -| a row with no label in a `missing: absent` map | the map, at that row ([maps](relations.md#missing)) | -| a missing row of a `missing: absent` parameter | the parameter, at that coordinate ([`missing`](#missing)) | -| `within=` at a coordinate in no group | the expression, at that coordinate ([`within=`](operators.md#within)) | -| a quotient whose divisor is zero | the quotient, at that coordinate ([reported values](#reported-values)) | +| Construct | What is absent | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `where:` on a variable | the variable, at the coordinates the condition excludes ([`where`](#where)) | +| `where:` on a parameter | the parameter, at the coordinates the condition excludes ([`where` on a parameter](parameters-variables-constraints.md#where)) | +| `where:` on a constraint | the row ([`where`](#where)) | +| `shift(x, along=d, offset=n)` without `edge=` | the expression, at the edge coordinate ([shift](operators.md#shift)) | +| a key with no row in a `missing: absent` relation | the relation, at that key ([relations](relations.md#missing)) | +| a row with no label in a `missing: absent` mapping | the mapping, at that row ([mappings](relations.md#missing)) | +| a missing row of a `missing: absent` parameter | the parameter, at that coordinate ([`missing`](#missing)) | +| `within=` at a coordinate in no group | the expression, at that coordinate ([`within=`](operators.md#within)) | +| a quotient whose divisor is zero | the quotient, at that coordinate ([reported values](#reported-values)) | No value shifts in at the edge, so a `shift` without `edge=` has no row there: @@ -73,14 +73,14 @@ No value shifts in at the edge, so a `shift` without `edge=` has no row there: `shift(x, along=snapshot, offset=1)` has no row at snapshot 1, so the expression is absent there. -A map with `missing: absent` is absent at a row of its subject that the data +A mapping with `missing: absent` is absent at a row of its subject that the data gives no label:
--8<-- "docs/static/absence-relation-missing.svg"
-The data gives `l3` no label in `line[bus1]`, so the map is absent at `l3`. +The data gives `l3` no label in `line[bus1]`, so the mapping is absent at `l3`. ## `missing` @@ -342,13 +342,13 @@ either. An operator has one of two results for an absent input: -| Operator | Inputs to one output | At an absent input | -| -------------------------------- | ----------------------------- | ------------------------------------------------ | -| `sum(x, over=d)` | every position along `d` | the sum leaves it out, and the row stays | -| `sum(x, over=d, by=s[c])` | every member of the group | the sum leaves it out, and the row stays | -| `sum_back(x, along=d, window=w)` | the positions in the window | the sum leaves it out, and the row stays | -| `shift(x, along=d, offset=n)` | one position, `n` back | that input is the only one, so the row is absent | -| `at(x, by=s[m])` | one position, through the map | that input is the only one, so the row is absent | +| Operator | Inputs to one output | At an absent input | +| -------------------------------- | --------------------------------- | ------------------------------------------------ | +| `sum(x, over=d)` | every position along `d` | the sum leaves it out, and the row stays | +| `sum(x, over=d, by=s[c])` | every member of the group | the sum leaves it out, and the row stays | +| `sum_back(x, along=d, window=w)` | the positions in the window | the sum leaves it out, and the row stays | +| `shift(x, along=d, offset=n)` | one position, `n` back | that input is the only one, so the row is absent | +| `at(x, by=s[m])` | one position, through the mapping | that input is the only one, so the row is absent | With data attached, a missing row that takes the value `0` can leave a constraint row with no variable in it. In a constraint diff --git a/docs/reference/language/assumptions.md b/docs/reference/language/assumptions.md index 4a938f310..baf481a1a 100644 --- a/docs/reference/language/assumptions.md +++ b/docs/reference/language/assumptions.md @@ -180,14 +180,14 @@ _Assumptions_ heading as the assumptions you write, and [`spec.expand()`](../spec.md#mathspec.spec.Spec.expand) writes them out as `assumptions:` entries with these names: -| Entry | Added for | What it requires | -| ----------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `curve_complete` | an entry with a link that does not walk a map | every values parameter of such a link has a row at every breakpoint the curve runs through | -| `curve__complete` | a [link that walks a map](piecewise.md#a-link-that-walks-a-map) | the values parameter of the link has a row at every breakpoint, at every row of the link | -| `curve_increasing` | `convex`, `lp` | the breakpoints of the pinned link, or of the first link where both are pinned, strictly increase along `along` | -| `curve_curvature` | `convex`, `lp` | with a `>=` link the curve is convex, with a `<=` link concave, and with both links pinned it bends one way only | -| `curve_breakpoints` | `lp` | each curve has at least two breakpoints | -| `curve_contiguous` | a [`where:` over `along`](piecewise.md#curves-of-unequal-length) | the marked breakpoints form one consecutive run of at least one | +| Entry | Added for | What it requires | +| ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `curve_complete` | an entry with a link that does not walk a mapping | every values parameter of such a link has a row at every breakpoint the curve runs through | +| `curve__complete` | a [link that walks a mapping](piecewise.md#a-link-that-walks-a-mapping) | the values parameter of the link has a row at every breakpoint, at every row of the link | +| `curve_increasing` | `convex`, `lp` | the breakpoints of the pinned link, or of the first link where both are pinned, strictly increase along `along` | +| `curve_curvature` | `convex`, `lp` | with a `>=` link the curve is convex, with a `<=` link concave, and with both links pinned it bends one way only | +| `curve_breakpoints` | `lp` | each curve has at least two breakpoints | +| `curve_contiguous` | a [`where:` over `along`](piecewise.md#curves-of-unequal-length) | the marked breakpoints form one consecutive run of at least one | For an [`lp`](piecewise.md#method) entry named `cost_curve`, with its second link signed `>=`, the typesetter prints the first three added assumptions as: diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index 924af95f4..6035cc672 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -55,7 +55,7 @@ mathspec loads a dimension that no entry uses, and for that dimension ([advice](../glossary.md#advice)). The label of another dimension that each label has, such as the carrier of -each generator, is a [map](relations.md#maps), not a dimension. +each generator, is a [mapping](relations.md#mappings), not a dimension. ## `one_of` @@ -67,13 +67,13 @@ compares against. dimensions: carrier: { dtype: str, one_of: [ccgt, ocgt, wind] } generator: { dtype: str } -maps: +mappings: generator: { carrier: { dim: carrier } } variables: p: { dims: [generator], where: "generator[carrier] == 'wind'" } ``` -`p` exists only at the generators whose carrier is `wind`. The map +`p` exists only at the generators whose carrier is `wind`. The mapping `generator[carrier]` gives each generator one carrier, and `one_of` makes `wind` one of three allowed labels. @@ -91,7 +91,7 @@ The order of the list changes nothing. mathspec sorts it by name at load, so `one_of: [wind, ccgt, ocgt]` declares the same dimension. At load, mathspec refuses a [condition](expressions.md#conditions) that -compares the dimension, or a map into it, against a label that is not in the +compares the dimension, or a mapping into it, against a label that is not in the list. With `generator[carrier] == 'gnrtr'` in place of `generator[carrier] == 'wind'` above, mathspec prints: ```text @@ -102,7 +102,7 @@ mathspec lists the allowed labels and suggests two rewrites. With data attached, a tool refuses a label outside the list: in the table of the dimension, in every column of a relation -over it, and in the column of every map into it. +over it, and in the column of every mapping into it. Only a dimension takes `one_of`, and a `one_of` key on a parameter is refused as an unknown key. @@ -159,5 +159,5 @@ the dimension still needs `ordered: true`. !!! info "See also" - - [choose between a dimension, a relation, a map and a parameter](../../howto/declare-a-column.md) + - [choose between a dimension, a relation, a mapping and a parameter](../../howto/declare-a-column.md) for a column of data. diff --git a/docs/reference/language/errors.md b/docs/reference/language/errors.md index a075238b4..df0eca859 100644 --- a/docs/reference/language/errors.md +++ b/docs/reference/language/errors.md @@ -142,7 +142,7 @@ advice, so the file still loads and `check` exits `0`. | `kind` | The file has… | The advice is… | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| `never-an-axis` | a dimension that indexes nothing, that nothing sums into, and that no relation or map has a column over | remove it, or keep it if the entries that use it are still to be written | +| `never-an-axis` | a dimension that indexes nothing, that nothing sums into, and that no relation or mapping has a column over | remove it, or keep it if the entries that use it are still to be written | | `given` | a parameter, column, named expression or set of constraint rows (a row family) that it uses and does not declare ([given](parameters-variables-constraints.md#given)) | the file this one is layered onto provides it | | `unbounded` | a variable that no constraint, set or curve uses, whose objective term pushes it towards a bound it does not have | give it a finite bound, or the constraint that was meant to define it | @@ -185,7 +185,7 @@ objective: Both commands print the same two messages of advice: ```text -dimension 'region' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'region' is never used: nothing is indexed by it, nothing sums into it, and no relation or mapping is over it. Remove it, or keep it if the entries that use it are still to be written. Variable 'slack' makes this spec unbounded: no constraint names it, and bounds.lower is open, and the +slack term in the minimize objective improves toward it. Give it a finite bounds.lower, or the constraint that was meant to define it. ``` diff --git a/docs/reference/language/expressions.md b/docs/reference/language/expressions.md index eda314a6c..963dcfb73 100644 --- a/docs/reference/language/expressions.md +++ b/docs/reference/language/expressions.md @@ -225,8 +225,8 @@ The place of a name in a string sets which kinds of name it may be: | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | expression (`p * cost`) | a variable, or a parameter whose values are numbers ([dtype](parameters-variables-constraints.md#parameters)) | | dimension argument (`over=`, `along=`) | a dimension, a list of them for `over=`, or with `by=` a column of the table in `by=` where one has that name | -| column argument (`by=`, `within=`) | maps or columns of one subject, written `subject[column]` or `subject[column, …]` | -| condition | a parameter, variable, dimension, relation, map or named condition ([conditions](#conditions)) | +| column argument (`by=`, `within=`) | mappings or columns of one subject, written `subject[column]` or `subject[column, …]` | +| condition | a parameter, variable, dimension, relation, mapping or named condition ([conditions](#conditions)) | | `bounds.lower` / `bounds.upper` | a parameter name, or a number | | the `edge` key of `shift` | `'wrap'` in quotes, or a bare number | | `dual` argument (`dual(c)`) | a constraint, resolved against the constraints alone ([named expressions](named.md#dual)) | @@ -251,18 +251,18 @@ and never to a constraint of the same name. Before any data is attached, [`to_spec`](../api.md#mathspec.to_spec) works out the dimensions of every expression. Each part of an expression (a node) has a set of dimensions: -| Node | Dimensions of the result | Refused when | -| -------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | -| number | `{}` | | -| parameter / variable | its `dims` | | -| `-x`, `+x` | `dims(x)` | | -| `a + b`, `a * b`, `a / b` | `dims(a) ∪ dims(b)` | | -| `sum(x)` | `{}` | `dims(x)` is already empty | -| `sum(x, over=d)` | `dims(x) − {d}` | `d ∉ dims(x)` | -| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how relations and maps are used](relations.md#how-relations-and-maps-are-used) applies | -| `at(x, by=s[m])` | `(dims(x) − joined) ∪ grouped` | the same refusals apply | -| `shift(x, along=d, offset=n)` | `dims(x)` | `d ∉ dims(x)` | -| `sum_back(x, along=d, window=n)` | `dims(x)` | `d ∉ dims(x)` | +| Node | Dimensions of the result | Refused when | +| -------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| number | `{}` | | +| parameter / variable | its `dims` | | +| `-x`, `+x` | `dims(x)` | | +| `a + b`, `a * b`, `a / b` | `dims(a) ∪ dims(b)` | | +| `sum(x)` | `{}` | `dims(x)` is already empty | +| `sum(x, over=d)` | `dims(x) − {d}` | `d ∉ dims(x)` | +| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how relations and mappings are used](relations.md#how-relations-and-mappings-are-used) applies | +| `at(x, by=s[m])` | `(dims(x) − joined) ∪ grouped` | the same refusals apply | +| `shift(x, along=d, offset=n)` | `dims(x)` | `d ∉ dims(x)` | +| `sum_back(x, along=d, window=n)` | `dims(x)` | `d ∉ dims(x)` | mathspec refuses `sum(p, over=t)` with `p` over `g` alone, and prints: @@ -327,19 +327,19 @@ its entry. | `name` (bare) | parameter | For a number, it is true where the data has a row, whatever the `missing:`. For a `bool`, it is its value, and the `missing:` sets the value at a missing row ([`missing`](parameters-variables-constraints.md#missing)). `0.0` is a row, and `inflow != 0` tests for non-zero | | `name` (bare) | variable | It is true where the variable exists | | `name` (bare) | relation | It is true where the relation has a row. A `missing: absent` relation has no row for some combinations ([`missing`](relations.md#missing)), and the bare name selects the combinations it lists | -| `subject[map]` (bare) | map | It is true where the map gives the row of its subject a label. A `missing: absent` map gives some rows no label ([`missing`](relations.md#missing)) | +| `subject[mapping]` (bare) | mapping | It is true where the mapping gives the row of its subject a label. A `missing: absent` mapping gives some rows no label ([`missing`](relations.md#missing)) | | `name` (bare) | dimension | mathspec refuses it at load | | `name` (bare) | named condition | It tests the [named condition](named.md#conditions). A given condition is true or false at each coordinate, as a `bool` parameter is | | `name OP value` | parameter | It compares element by element. A missing row with no `missing:` value compares false | | `name OP value` | dimension | It filters the frame's own coordinate column | -| `subject[map] OP value` | map | It compares the label that the map gives each row of its subject. A comparison reads one map. Where the map gives no label, the comparison is false for every operator, `!=` included, so `NOT` of it is true there | -| `s[a] OP t[b]` | two maps | mathspec accepts it where both subjects are over the same dimensions and both maps refer to one dimension. `line[bus0] != line[bus1]` excludes a self-loop. Where either map gives no label, the comparison is false | +| `subject[mapping] OP value` | mapping | It compares the label that the mapping gives each row of its subject. A comparison reads one mapping. Where the mapping gives no label, the comparison is false for every operator, `!=` included, so `NOT` of it is true there | +| `s[a] OP t[b]` | two mappings | mathspec accepts it where both subjects are over the same dimensions and both mappings refer to one dimension. `line[bus0] != line[bus1]` excludes a self-loop. Where either mapping gives no label, the comparison is false | | `expression OP expression` | arithmetic over parameters | It compares coordinate by coordinate, over every dimension either side is over ([arithmetic in a comparison](#arithmetic-in-a-comparison)). A side with no value at a coordinate compares false | | `position(name) OP i` | dimension | It tests where the row sits along the dimension's own order. `0` is first, and a negative number counts from the end | -| `position(name, within=s[m])` | dimension | It tests the same, counted within each group the map makes | +| `position(name, within=s[m])` | dimension | It tests the same, counted within each group the mapping makes | | `count(condition, over=name) OP i` | condition | It compares how many coordinates along the dimension the condition admits ([`count`](#count)) | | `shift(condition, along=name, offset=i)` | condition | It is the condition `i` coordinates back, and false at the first `i` coordinates | -| `at(condition, by=s[m])` | condition | It is the condition through the map ([`at` in a condition](#at-in-a-condition)), and false where the map gives no label | +| `at(condition, by=s[m])` | condition | It is the condition through the mapping ([`at` in a condition](#at-in-a-condition)), and false where the mapping gives no label | | `AND` `OR` `NOT` | | They are case-insensitive. `NOT` applies before `AND`, and `AND` before `OR` | | `True` / `False` | | `True` is the same as no `where`. `False` leaves an entry with no rows | @@ -482,9 +482,9 @@ arithmetic `shift` takes. ### `at` in a condition -`at(, by=[])` reads a condition at the label that a -map gives each row of its subject, as `at` reads an expression. It is true -where the condition is true at that label, and **false** where the map gives +`at(, by=[])` reads a condition at the label that a +mapping gives each row of its subject, as `at` reads an expression. It is true +where the condition is true at that label, and **false** where the mapping gives the row no label. In the spec below, `rate` exists only for a flow whose converter has a curve: @@ -492,7 +492,7 @@ the spec below, `rate` exists only for a flow whose converter has a curve: dimensions: converter: { dtype: str } flow: { dtype: str } -maps: +mappings: flow: { converter: { dim: converter } } parameters: has_curve: { dims: [converter], dtype: bool } @@ -517,11 +517,11 @@ objective: The converter of `f3` has no curve, so `rate` has no row for `f3`. -`at` removes `converter`, the dimension that the map in `by=` refers to, and +`at` removes `converter`, the dimension that the mapping in `by=` refers to, and adds the subject, `flow`. So the condition is over `flow` alone, which is the frame of `rate`. -`by=` lists one map, or several as `subject[a, …]`, and every other +`by=` lists one mapping, or several as `subject[a, …]`, and every other rule of [`at` in an expression](relations.md#lookups) applies. !!! info "See also" @@ -567,8 +567,8 @@ Variable 'p': 'snapshot' is a datetime dimension, so comparing it to 5.0 compare mathspec suggests the rewrite: a quoted date. Only a number or a `datetime` compares with `<`, `<=`, `>` and `>=`. A `str` -or a `bool` compares only with `==` and `!=`. A map has the -dtype of the dimension it refers to, so the rule also applies to a map. For the +or a `bool` compares only with `==` and `!=`. A mapping has the +dtype of the dimension it refers to, so the rule also applies to a mapping. For the condition `generator < 'b9'` on a `str` dimension, mathspec prints: ```text @@ -597,7 +597,7 @@ data preparation. Either side of a comparison may be an expression over parameters, such as `p_min <= 0.5 * p_max` or `p_max <= at(bus_cap, by=generator[bus])`. With macros and named expressions included, mathspec reads such a side as it reads an -[expression](#the-arithmetic-grammar). A map and a quoted label +[expression](#the-arithmetic-grammar). A mapping and a quoted label are compared on their own, and never take part in arithmetic. A variable and a `dual()` are refused in a comparison, because a condition @@ -694,7 +694,7 @@ one starting row: dimensions: snapshot: { dtype: int, ordered: true } period: { dtype: int } -maps: +mappings: snapshot: { period: { dim: period } } parameters: soc_initial: { dims: [period] } diff --git a/docs/reference/language/file.md b/docs/reference/language/file.md index 8ed84a423..0b81b78c1 100644 --- a/docs/reference/language/file.md +++ b/docs/reference/language/file.md @@ -19,7 +19,7 @@ declares only `dimensions:` loads. | `given` | what this file uses and another file declares ([given](parameters-variables-constraints.md#given)) | | `dimensions` | the sets of labels that entries are indexed over ([dimensions](dimensions.md)) | | `relations` | named sets of combinations of labels of two or more dimensions ([relations](relations.md#relations)) | -| `maps` | the label of a dimension that each row of a dimension or a relation has ([maps](relations.md#maps)) | +| `mappings` | the label of a dimension that each row of a dimension or a relation has ([mappings](relations.md#mappings)) | | `parameters` | the data the spec expects ([parameters](parameters-variables-constraints.md#parameters)) | | `conditions` | named conditions, used by name in a `where:`, a `when:` or a `holds:` ([conditions](named.md#conditions)) | | `variables` | what the solver decides ([variables](parameters-variables-constraints.md#variables)) | diff --git a/docs/reference/language/index.md b/docs/reference/language/index.md index 12e9c2c51..5fc36ef04 100644 --- a/docs/reference/language/index.md +++ b/docs/reference/language/index.md @@ -18,7 +18,7 @@ _entry_, _coordinate_ and _absent_, in one fixed sense. - **[File shape](file.md)** lists the top-level keys of a spec file, and how mathspec reads the YAML. - **[Given, parameters, variables, objective and constraints](parameters-variables-constraints.md)** lists the keys of the data, the decisions, the goal and the rules, and of the `given:` section. - **[Dimensions](dimensions.md)** lists the keys of a dimension, the set of labels that entries are indexed over. -- **[Relations and maps](relations.md)** lists the keys of a relation, a set of combinations of labels, and of a map, which gives each row one label, and how each operator uses them. +- **[Relations and mappings](relations.md)** lists the keys of a relation, a set of combinations of labels, and of a mapping, which gives each row one label, and how each operator uses them. - **[Expressions](expressions.md)** defines the grammar of arithmetic and of conditions, and how dimensions combine. - **[Named expressions, conditions and macros](named.md)** lists the keys of the three kinds of named piece of an expression. - **[Operators](operators.md)** lists every operator, such as `sum` and `shift`, and the math each one prints. diff --git a/docs/reference/language/named.md b/docs/reference/language/named.md index 7be6c9547..e3eede0e8 100644 --- a/docs/reference/language/named.md +++ b/docs/reference/language/named.md @@ -172,7 +172,7 @@ The constraint `emission_cap` uses `emissions` by name, and the objective uses | `expression` | without `cases:` | | the quantity, in the [expression grammar](expressions.md), which `cases:` replaces | | `dims` | with `cases:` | `null` | the dimensions over which the quantity is indexed, sorted by name at load ([`dims`](#dims)) | | `description` | no | `null` | free text | -| `cases` | no | `null` | a map of named cases, each with a `when:` condition and an `expression:` ([`cases`](#cases)) | +| `cases` | no | `null` | a mapping of named cases, each with a `when:` condition and an `expression:` ([`cases`](#cases)) | | `otherwise` | with `cases:` | `null` | the value at every combination of labels (a [coordinate](../glossary.md#coordinate)) that no case claims | | `adds_to` | no | `null` | the name of a sum that this entry adds a term to ([`adds_to`](#adds_to)) | @@ -377,7 +377,7 @@ dimensions: snapshot: { dtype: int } bus: { dtype: str } generator: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } variables: gen_p: { dims: [snapshot, generator], bounds: { lower: 0 } } diff --git a/docs/reference/language/operators.md b/docs/reference/language/operators.md index e0a87860e..1c2af0e1e 100644 --- a/docs/reference/language/operators.md +++ b/docs/reference/language/operators.md @@ -26,18 +26,18 @@ A file cannot add an operator, and only | `sum(array)` | `sum` removes every [dimension](dimensions.md) of `array`. The result is a scalar | | `sum(array, over=dim)` | `sum` removes `dim` | | `sum(array, over=[a, …])` | `sum` removes each dimension in the list | -| `sum(array, over=dim, by=subject[c])` | `sum` removes `dim`, and groups the result by the column `c` of the table of `subject`, a [map](relations.md#maps) or a column of a [relation](relations.md#relations). The call joins on the other key columns, so `array` and the result are indexed over them | +| `sum(array, over=dim, by=subject[c])` | `sum` removes `dim`, and groups the result by the column `c` of the table of `subject`, a [mapping](relations.md#mappings) or a column of a [relation](relations.md#relations). The call joins on the other key columns, so `array` and the result are indexed over them | | `sum(array, over=[dim, …], by=subject[c, …])` | The call does the same with several dimensions and several columns of one table, joins on them together, and groups by their product | -| `at(array, by=subject[m])` | The result is `array` read at the label that the map `m` gives each row of `subject`, once per row. The result gains the key of `subject` | +| `at(array, by=subject[m])` | The result is `array` read at the label that the mapping `m` gives each row of `subject`, once per row. The result gains the key of `subject` | | `shift(array, along=dim, offset=n)` | The result is the value `n` positions earlier along `dim`, and the vacated edge is [absent](absence.md) | | `shift(array, along=dim, offset=n, edge='wrap')` | The result is the value `n` positions earlier, counted cyclically, so nothing is vacated | | `shift(array, along=dim, offset=n, edge=v)` | The result is the value `n` positions earlier, with the number `v` at the vacated edge | | `shift(array, along=dim, offset=p, edge=…)` | The result is the value `p` positions earlier, with `p` an integer parameter read per entity | -| `shift(array, along=dim, offset=n, within=subject[m])` | The result is the value `n` positions earlier inside each group that the map `m` makes. Neighbours, edges and a wrap all belong to that group | +| `shift(array, along=dim, offset=n, within=subject[m])` | The result is the value `n` positions earlier inside each group that the mapping `m` makes. Neighbours, edges and a wrap all belong to that group | | `sum_back(array, along=dim, window=n)` | The result is the sum of the last `n` positions along `dim`, ending at the position being written | | `sum_back(array, along=dim, window=p)` | The result is the sum of the last `p` positions, with `p` an integer parameter read per entity | | `sum_back(array, along=dim, window=p, edge='wrap')` | Instead of stopping short at its start, the window reaches around the dimension | -| `sum_back(array, along=dim, window=n, within=subject[m])` | The window stays inside each group that the map `m` makes | +| `sum_back(array, along=dim, window=n, within=subject[m])` | The window stays inside each group that the mapping `m` makes | `array` is any expression with the right dimensions, such as a parameter or a variable. [Every operator as math](#every-operator-as-math) lists the typeset @@ -53,7 +53,7 @@ each dimension once. `sum(x, over=[a, b])` is the same as `sum(sum(x, over=a), over=b)`, and the [typesetter](../typeset.md) prints it as one sum over both sets. -With `by=`, the sum adds up each group that a [map](relations.md#maps) or a +With `by=`, the sum adds up each group that a [mapping](relations.md#mappings) or a column of a [relation](relations.md#relations) makes, and the result is indexed over that column. The balance at each bus (a nodal balance) is one `sum(by=)` per kind of component: @@ -63,7 +63,7 @@ dimensions: bus: { dtype: str } generator: { dtype: str } line: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } line: { bus0: { dim: bus }, bus1: { dim: bus } } parameters: @@ -110,14 +110,14 @@ sum. !!! info "See also" - - [How relations and maps are used](relations.md#how-relations-and-maps-are-used), - for the dimensions that a call through a relation or a map joins on, and + - [How relations and mappings are used](relations.md#how-relations-and-mappings-are-used), + for the dimensions that a call through a relation or a mapping joins on, and those its result has. ## `at` -`at` takes, for each row of the subject of a [map](relations.md#maps), the -value of an expression at the label that the map gives the row. `at` adds +`at` takes, for each row of the subject of a [mapping](relations.md#mappings), the +value of an expression at the label that the mapping gives the row. `at` adds nothing up (a [lookup](relations.md#lookups)), and takes one row for each row of the subject. Here `at` takes, @@ -127,7 +127,7 @@ for every line, the build decision of its bus: dimensions: bus: { dtype: str } line: { dtype: str } -maps: +mappings: line: { bus: { dim: bus } } parameters: cap: { dims: [line] } @@ -149,7 +149,7 @@ f_{l} \le \mathrm{cap}_{l} \cdot \mathit{build}_{\mathrm{bus}(l)} \qquad \forall --8<-- "docs/static/operators-at.svg" -`at` removes `bus`, the dimension that the map in `by=` refers to, and adds +`at` removes `bus`, the dimension that the mapping in `by=` refers to, and adds the key, `line`, so `build` is read once per line. ## `shift` @@ -236,7 +236,7 @@ group: dimensions: snapshot: { dtype: int, ordered: true } season: { dtype: str } -maps: +mappings: snapshot: { season: { dim: season } } parameters: inflow: { dims: [snapshot] } @@ -315,14 +315,14 @@ Constraint 'arrives_after_its_lead': shift(offset=lead) steps along 'month', and `lead` then varies along `month`, the dimension that the shift moves along. mathspec reads the offset over the dimensions of the shifted expression, and -over the dimension that a [`within=`](#within) map groups into. At load, mathspec refuses an offset over any other dimension. With a dimension `period`, a map +over the dimension that a [`within=`](#within) mapping groups into. At load, mathspec refuses an offset over any other dimension. With a dimension `period`, a mapping `month: { period: { dim: period } }`, and `lead` declared over `[period]`, the spec loads under `within=month[period]`, with one offset per period. Without the `within=` on the shift, mathspec refuses the file and prints: ```text -Constraint 'arrives_after_its_lead': shift(offset=lead): 'lead' varies over ['period'], which the expression does not carry (dims ['month', 'technology']). Declare 'lead' over dims the expression carries, or group by a map into one of ['period']. +Constraint 'arrives_after_its_lead': shift(offset=lead): 'lead' varies over ['period'], which the expression does not carry (dims ['month', 'technology']). Declare 'lead' over dims the expression carries, or group by a mapping into one of ['period']. ``` `period` is neither a dimension of `order` nor a group of a `within=`. @@ -411,7 +411,7 @@ The typesetter prints each form from the smallest spec that uses it. | `sum(array, over=dim, by=subject[m]), joining on the rest of the key` | $`\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ e) = z} p_{g,e} \ge \mathrm{demand}_{e,z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z}`$ | | `sum(array, over=[dim, …], by=subject[m, …])` | $`\sum_{g \in \mathcal{G},\ e \in \mathcal{E} \,:\, \mathrm{bus}(g,\ e) = b \wedge \mathrm{technology}(g,\ e) = t} p_{g,e} \le \mathrm{cap}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T}`$ | | `at(array, by=subject[m])` | $`p_{t} \le \mathrm{cap}_{\mathrm{period}(t)} \qquad \forall\, t \in \mathcal{T}`$ | -| `at(array, by=subject[m]), two maps into one dimension` | $`f_{l} \le \mathrm{cap}_{\mathrm{bus0}(l)} \qquad \forall\, l \in \mathcal{L}`$ | +| `at(array, by=subject[m]), two mappings into one dimension` | $`f_{l} \le \mathrm{cap}_{\mathrm{bus0}(l)} \qquad \forall\, l \in \mathcal{L}`$ | | `shift(array, along=dim, offset=n)` | $`p_{t} \le p_{t - 1} \qquad \forall\, t \in \mathcal{T}`$ | | `shift(array, along=dim, offset=n, edge='wrap')` | $`p_{t} \le p_{t \ominus 1} \qquad \forall\, t \in \mathcal{T}`$ | | `shift(array, along=dim, offset=n, edge=v)` | $`p_{t} \le p_{t \boxminus_{0} 1} \qquad \forall\, t \in \mathcal{T}`$ | @@ -428,8 +428,8 @@ The typesetter prints each form from the smallest spec that uses it. - [Absence and where](absence.md) for what each operator does with an absent input. - - [Relations and maps](relations.md#how-relations-and-maps-are-used) for the - relation or the map that `by=` and `within=` take. + - [Relations and mappings](relations.md#how-relations-and-mappings-are-used) for the + relation or the mapping that `by=` and `within=` take. - [Macros](named.md#macros) for a composition of operators under one name. - [One construct per spec](../../examples/operators.md) for the smallest spec that uses each form. diff --git a/docs/reference/language/parameters-variables-constraints.md b/docs/reference/language/parameters-variables-constraints.md index 2240d688b..0aeb5f5ee 100644 --- a/docs/reference/language/parameters-variables-constraints.md +++ b/docs/reference/language/parameters-variables-constraints.md @@ -142,7 +142,7 @@ dimensions: snapshot: { dtype: int } port: { dtype: str } generator: { dtype: str } -maps: +mappings: generator: { port: { dim: port } } variables: gen_p: { dims: [snapshot, generator], bounds: { lower: 0 } } @@ -406,7 +406,7 @@ dimensions: snapshot: { dtype: int } relations: connection: { dims: [entity, bus], missing: absent } -maps: +mappings: connection: { role: { dim: role } } parameters: efficiency: @@ -466,10 +466,10 @@ For a `where:` on `efficiency` that contains the variable `p`, the message is: ```text -Parameter 'efficiency': its `where:` contains variable 'p', and a tool evaluates the `where:` of a parameter from the data alone, before any variable has a value. Test a parameter or a map instead. +Parameter 'efficiency': its `where:` contains variable 'p', and a tool evaluates the `where:` of a parameter from the data alone, before any variable has a value. Test a parameter or a mapping instead. ``` -mathspec suggests a parameter or a map as the rewrite. +mathspec suggests a parameter or a mapping as the rewrite. The typeset legend lists the condition beside the dimensions, after `only where`. For `efficiency`, the legend entry ends in diff --git a/docs/reference/language/piecewise.md b/docs/reference/language/piecewise.md index af9350a00..55f8e8764 100644 --- a/docs/reference/language/piecewise.md +++ b/docs/reference/language/piecewise.md @@ -212,18 +212,18 @@ expansion writes the link `power` of `chp` as the row `chp_power`. | _values_ | A parameter over the `along` dimension. Its other dimensions are dimensions of the row of the link. | | _sign_ | `<=`, `>=` or `==`. Without a sign, the link is `==` ([signs](#signs)). | -A link that [walks a map](#a-link-that-walks-a-map) is a mapping +A link that [walks a mapping](#a-link-that-walks-a-mapping) is a mapping instead, with the keys `expression`, `values`, `by` and, where it has one, `sign`. -| Key | Required | Default | What it does | -| ---------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `along` | yes | | Sets the breakpoint dimension. | -| `dims` | yes | | Sets the dimensions of the curves. The entry states one curve per coordinate ([`dims`](#dims)). | -| `links` | yes | | Lists the links by name: two or more, or one link that walks a map. | -| `where` | no | `null` | Sets which curves exist, and how far each one runs ([`where`](#where)). | -| `method` | no | `adjacency` | Sets the rows that the expansion writes for each curve ([`method`](#method)). | -| `activity` | no | `null` | Sets the variable that switches the curve on and off: a binary, or an integer under `incremental`. Written as its name or as `at(, by=[])` ([`activity`](#activity)). | +| Key | Required | Default | What it does | +| ---------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `along` | yes | | Sets the breakpoint dimension. | +| `dims` | yes | | Sets the dimensions of the curves. The entry states one curve per coordinate ([`dims`](#dims)). | +| `links` | yes | | Lists the links by name: two or more, or one link that walks a mapping. | +| `where` | no | `null` | Sets which curves exist, and how far each one runs ([`where`](#where)). | +| `method` | no | `adjacency` | Sets the rows that the expansion writes for each curve ([`method`](#method)). | +| `activity` | no | `null` | Sets the variable that switches the curve on and off: a binary, or an integer under `incremental`. Written as its name or as `at(, by=[])` ([`activity`](#activity)). | The breakpoints follow the order of the `along` dimension, so that dimension must be declared [ordered](dimensions.md#ordered). Without `ordered: true`, @@ -261,17 +261,17 @@ The entry states one curve, with its own weights, at each coordinate of dimension. The row of a link is over `dims:`, or over the dimensions of its -[walk](#a-link-that-walks-a-map). The expression of a link must be over +[walk](#a-link-that-walks-a-mapping). The expression of a link must be over exactly the dimensions of its row. With `power` and `fuel` over `[snapshot, generator]` and an entry with `dims: [generator]`, mathspec prints: ```text -piecewise 'fuel_use': link 'power' expression is over ['snapshot'], and its row ['generator'] is not, so every coordinate of ['snapshot'] would share one curve. Add ['snapshot'] to dims:, sum it out, or look the curve up through a map with by: []. +piecewise 'fuel_use': link 'power' expression is over ['snapshot'], and its row ['generator'] is not, so every coordinate of ['snapshot'] would share one curve. Add ['snapshot'] to dims:, sum it out, or look the curve up through a mapping with by: []. ``` mathspec suggests three rewrites: `snapshot` in `dims:`, a sum over -`snapshot`, or a walk through a map. mathspec also refuses an expression +`snapshot`, or a walk through a mapping. mathspec also refuses an expression that is not over a dimension of its row. One value of the expression would then lie on several curves at once. @@ -391,14 +391,14 @@ pinned `power` on the curve, `fuel` may lie any amount above the curve, and `convex` and `lp` take exactly two links ([`method`](#method)). At load, mathspec refuses a sign other than `<=`, `>=` and `==`. -### A link that walks a map +### A link that walks a mapping -On a link with `by: subject[map]`, mathspec looks the weights of the curve -up through a [map](relations.md#lookups), as -[`at(x, by=subject[map])`](operators.md#at) looks up the value of `x`. The -row of the link is over `dims:`, with the dimension that `map` refers to +On a link with `by: subject[mapping]`, mathspec looks the weights of the curve +up through a [mapping](relations.md#lookups), as +[`at(x, by=subject[mapping])`](operators.md#at) looks up the value of `x`. The +row of the link is over `dims:`, with the dimension that `mapping` refers to replaced by the key columns of the subject. Each row lies on the curve of the -label that the map gives it, so the number of rows is known only when the +label that the mapping gives it, so the number of rows is known only when the data is attached: ```yaml @@ -407,7 +407,7 @@ dimensions: converter: { dtype: str } flow: { dtype: str } bp: { dtype: int, ordered: true } -maps: +mappings: flow: { converter: { dim: converter } } parameters: bp_rate: { dims: [flow, bp] } @@ -446,14 +446,14 @@ These rules apply to a walked link: flow of a converter, and those rows share the weights. - The values parameter is over the row of the link, so `bp_rate` is per flow, not per converter. -- `map` refers to a dimension of `dims:`. The walk adds the key columns of the +- `mapping` refers to a dimension of `dims:`. The walk adds the key columns of the subject that are over dimensions outside `dims:`, and joins on those over dimensions of `dims:`. mathspec refuses a key column over `along`, because a row could then take each breakpoint from a different curve. - mathspec holds a walk to every rule of [`at`](relations.md#lookups), and quotes the link in the refusal. -- If the map or its subject declares - [`missing: absent`](relations.md#missing), the expansion adds the map test +- If the mapping or its subject declares + [`missing: absent`](relations.md#missing), the expansion adds the mapping test `flow[converter]` to the `where:` of the row, so a flow with no converter has no row. - `method: convex` and `method: lp` take no walked link, and the other methods @@ -513,8 +513,8 @@ mathspec refuses a `where:` over a dimension that is neither in `dims:` nor `along`, because a condition cannot add coordinates. On the row of a walked link, the expansion looks the `where:` up through the -map of the link. In the -[walk example](#a-link-that-walks-a-map), with a boolean parameter +mapping of the link. In the +[walk example](#a-link-that-walks-a-mapping), with a boolean parameter `has_curve` over `[converter]` and `where: has_curve`, the expansion writes the row `operating_point_rate` with `where: at(has_curve, by=flow[converter])`: @@ -531,7 +531,7 @@ exists per coordinate of `dims:`. With a boolean parameter `active` over `[flow]` as the `where:`, mathspec prints: ```text -piecewise 'operating_point': where 'active' tests ['flow'], which link 'rate' adds through the map it walks. A where: sets which curves exist, one per coordinate of dims: ['converter', 'snapshot'], and only the rows of the link are over ['flow']. Test ['converter', 'snapshot'] in the where:, or declare a where: over ['flow'] on the variable of the link, so that its rows are absent. +piecewise 'operating_point': where 'active' tests ['flow'], which link 'rate' adds through the mapping it walks. A where: sets which curves exist, one per coordinate of dims: ['converter', 'snapshot'], and only the rows of the link are over ['flow']. Test ['converter', 'snapshot'] in the where:, or declare a where: over ['flow'] on the variable of the link, so that its rows are absent. ``` mathspec suggests two rewrites: a condition over `dims:`, or a `where:` on @@ -778,15 +778,15 @@ Where the gate is [absent](absence.md), the curve is ungated, as under curve scaled by `running` alone. The gate must have no dimension that `dims:` does not include, unless it walks -a map. A gate over fewer dimensions switches every curve +a mapping. A gate over fewer dimensions switches every curve that it covers, so a gate over `[generator]` switches the curve of a generator at every snapshot. -#### A gate that walks a map +#### A gate that walks a mapping On a gate written as -[`at(, by=[])`](operators.md#at), mathspec looks -the variable up through a [map](relations.md#lookups), as `at` looks up +[`at(, by=[])`](operators.md#at), mathspec looks +the variable up through a [mapping](relations.md#lookups), as `at` looks up any value. Here `running` is per unit, and the status of its unit switches the curve of each generator: @@ -796,7 +796,7 @@ dimensions: unit: { dtype: str } generator: { dtype: str } bp: { dtype: int, ordered: true } -maps: +mappings: generator: unit: { dim: unit, missing: absent } parameters: @@ -838,7 +838,7 @@ After the lookup, the gate must be over dimensions of `dims:` only. With `running` over `[snapshot, unit, period]`, mathspec refuses the file at load: ```text -piecewise 'fuel_use': activity 'running' is over ['period'] after the lookup, which is not in dims: ['generator', 'snapshot']. The gate switches the curve of one coordinate of dims:. Look it up through a map that leaves it over dims:, or add ['period'] to dims:. +piecewise 'fuel_use': activity 'running' is over ['period'] after the lookup, which is not in dims: ['generator', 'snapshot']. The gate switches the curve of one coordinate of dims:. Look it up through a mapping that leaves it over dims:, or add ['period'] to dims:. ``` #### An integer gate diff --git a/docs/reference/language/relations.md b/docs/reference/language/relations.md index 771c3833d..4fbae06af 100644 --- a/docs/reference/language/relations.md +++ b/docs/reference/language/relations.md @@ -3,13 +3,13 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> -# Relations and maps +# Relations and mappings A **relation** is a set of combinations of labels of [dimensions](dimensions.md), such as the buses that each generator may connect -to. A **map** gives each row of a dimension or a relation one label of a +to. A **mapping** gives each row of a dimension or a relation one label of a dimension, such as the bus of each generator. The file declares both, and the -rows come with the data. This page lists the keys of `relations:` and `maps:`, +rows come with the data. This page lists the keys of `relations:` and `mappings:`, the data they expect, and how each operator uses them. ## `relations` @@ -47,11 +47,11 @@ Relation 'zp' names column 'period' after dimension 'period', but the column is ``` A relation with one column is refused, because one column holds labels of one -dimension, and a map or a condition states that. With +dimension, and a mapping or a condition states that. With `r: { dims: [generator] }`, mathspec prints: ```text -Relation 'r' has one column under 'dims:', and a relation needs at least two. To give each generator a label, declare a map under maps: generator:. To mark some of them, declare a bool parameter or a condition. +Relation 'r' has one column under 'dims:', and a relation needs at least two. To give each generator a label, declare a mapping under mappings: generator:. To mark some of them, declare a bool parameter or a condition. ``` A relation is not a dimension, so its name does not go in `dims:`, `over=` or @@ -65,10 +65,10 @@ The order of the columns under `dims:` changes nothing. The typesetter sorts the columns by name, so `connection` above prints as $`\mathrm{connection} \subseteq \mathcal{B} \times \mathcal{G}`$. -## `maps` +## `mappings` -Each key under `maps:` names a **subject**, which is a dimension or a relation. -Each key under the subject declares one map, which gives every row of the +Each key under `mappings:` names a **subject**, which is a dimension or a relation. +Each key under the subject declares one mapping, which gives every row of the subject one label of the dimension that `dim:` names. ```yaml @@ -76,7 +76,7 @@ dimensions: bus: { dtype: str } generator: { dtype: str } line: { dtype: str } -maps: +mappings: generator: bus: { dim: bus } # each generator is on one bus line: @@ -84,54 +84,54 @@ maps: bus1: { dim: bus, missing: absent } # a line may have an open end ``` -A map always writes `dim:`, and has no shorter form. A condition or an operator -reads a map as `subject[map]`, so `generator[bus]` is the bus of a generator. +A mapping always writes `dim:`, and has no shorter form. A condition or an operator +reads a mapping as `subject[mapping]`, so `generator[bus]` is the bus of a generator. | Key | What it sets | Default | | ------------- | --------------------------------------------------------------------------------- | --------- | -| `dim` | required. The dimension whose labels the map gives | | +| `dim` | required. The dimension whose labels the mapping gives | | | `missing` | [`refused` or `absent`](#missing): whether every row of the subject needs a label | `refused` | | `description` | free text | `null` | -A map is named after the dimension it refers to, or after no dimension. The -typesetter prints a map as a function from its subject into that dimension, so +A mapping is named after the dimension it refers to, or after no dimension. The +typesetter prints a mapping as a function from its subject into that dimension, so `generator[bus]` prints as $`\mathrm{bus}: \mathcal{G} \to \mathcal{B}`$. -mathspec refuses a map at load in four cases: +mathspec refuses a mapping at load in four cases: - The subject is neither a dimension nor a relation. - `dim:` names a relation, or names no dimension. -- The map is named after a dimension that it does not refer to. -- The map has the name of a column of its subject. +- The mapping is named after a dimension that it does not refer to. +- The mapping has the name of a column of its subject. With `generator: { period: { dim: zone } }`, mathspec prints: ```text -maps: 'generator': map 'period' is named after dimension 'period', but refers to 'zone'. Rename the map after what it holds. +mappings: 'generator': mapping 'period' is named after dimension 'period', but refers to 'zone'. Rename the mapping after what it holds. ``` -A relation with two columns over one dimension takes no maps, because a map +A relation with two columns over one dimension takes no mappings, because a mapping gives one label per combination of the dimensions of its subject. ### Cardinalities How many labels a row may have (the cardinality) decides whether a fact is a -map or a relation: - -| What the file states | Written | Cardinality | -| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------- | -| each generator has one bus | `maps: { generator: { bus: { dim: bus } } }` | many-to-one | -| a generator may connect to several buses | `relations: { connection: { dims: [generator, bus], missing: absent } }` | many-to-many | -| a generator has one zone in each period | `relations: { zone_of: { dims: [generator, period] } }` and `maps: { zone_of: { zone: { dim: zone } } }` | many-to-one, from a pair | -| a snapshot has a month, a week and a weekday | `maps: { snapshot: { month: { dim: month }, week: { dim: week }, weekday: { dim: weekday } } }` | three maps of one subject | -| a line has two ends, both buses | `maps: { line: { bus0: { dim: bus }, bus1: { dim: bus } } }` | two maps into one dimension | -| a snapshot has a representative snapshot | `maps: { snapshot: { rep: { dim: snapshot } } }` | many-to-one, onto itself | -| a snapshot has neighbours | `relations: { neighbour: { dims: { from: snapshot, to: snapshot }, missing: absent } }` | many-to-many, onto itself | +mapping or a relation: + +| What the file states | Written | Cardinality | +| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | +| each generator has one bus | `mappings: { generator: { bus: { dim: bus } } }` | many-to-one | +| a generator may connect to several buses | `relations: { connection: { dims: [generator, bus], missing: absent } }` | many-to-many | +| a generator has one zone in each period | `relations: { zone_of: { dims: [generator, period] } }` and `mappings: { zone_of: { zone: { dim: zone } } }` | many-to-one, from a pair | +| a snapshot has a month, a week and a weekday | `mappings: { snapshot: { month: { dim: month }, week: { dim: week }, weekday: { dim: weekday } } }` | three mappings of one subject | +| a line has two ends, both buses | `mappings: { line: { bus0: { dim: bus }, bus1: { dim: bus } } }` | two mappings into one dimension | +| a snapshot has a representative snapshot | `mappings: { snapshot: { rep: { dim: snapshot } } }` | many-to-one, onto itself | +| a snapshot has neighbours | `relations: { neighbour: { dims: { from: snapshot, to: snapshot }, missing: absent } }` | many-to-many, onto itself | ## `missing` `missing:` sets whether the data may leave something out. On a relation, it sets whether every combination of the dimensions under `dims:` needs a row. On -a map, it sets whether every row of the subject needs a label. +a mapping, it sets whether every row of the subject needs a label. ```yaml dimensions: @@ -140,7 +140,7 @@ dimensions: line: { dtype: str } relations: connection: { dims: [generator, bus], missing: absent } # most pairs are not wired -maps: +mappings: generator: bus: { dim: bus } # refused: every generator is on a bus line: @@ -163,7 +163,7 @@ No number can replace a missing label, so at load mathspec refuses a value such as `missing: 0`: ```text -maps.generator.bus.missing: missing: 0 on a map, which takes refused or absent. A row with nothing there is refused, or is not in the data. +mappings.generator.bus.missing: missing: 0 on a mapping, which takes refused or absent. A row with nothing there is refused, or is not in the data. ``` Under the default `refused`, a relation needs a row for every combination, so @@ -176,64 +176,64 @@ dimension they are over, and nothing for `refused`. ## The data contract -With data attached, each relation and each subject with maps has one table, +With data attached, each relation and each subject with mappings has one table, named after it. The table of a relation has one column per column under -`dims:`. The table of a subject also has one column per map, named after the -map. So the data for the maps of `line` is a table `line` with the columns +`dims:`. The table of a subject also has one column per mapping, named after the +mapping. So the data for the mappings of `line` is a table `line` with the columns `line`, `bus0` and `bus1`. A piece of software that reads a spec ([a tool](../glossary.md#tool)) requires five things of a table: - The table has one row per combination of the columns of its subject, so a generator with two rows, on two buses, is refused. -- Every label in the column of a map is a label of the dimension it refers to, +- Every label in the column of a mapping is a label of the dimension it refers to, and a label that matches none is refused. - The table has a row for every combination of its dimensions, unless the relation declares `missing: absent`. The table of a dimension has a row for every label of the dimension. -- A null is refused, except in the column of a map that declares +- A null is refused, except in the column of a mapping that declares `missing: absent`. - The order of the rows has no meaning, because the order comes from the [dimension](dimensions.md#ordered). -A relation and a map have no `where:`, so their rows and labels come from the +A relation and a mapping have no `where:`, so their rows and labels come from the data alone. A tool therefore knows them before it evaluates any condition, such as the [`where:` of a parameter](parameters-variables-constraints.md#where). An [assumption](assumptions.md) can require rows of a relation or labels of a -map. For `line[bus1]` [above](#missing), `{holds: "line[bus1]", where: "closed"}` +mapping. For `line[bus1]` [above](#missing), `{holds: "line[bus1]", where: "closed"}` requires an end for every closed line, where `closed` is a `bool` parameter over `line`. -## How relations and maps are used +## How relations and mappings are used -A relation fixes no direction, so the same table can map generators to buses +A relation fixes no direction, so the same table can mapping generators to buses or buses to generators. A call **joins** the expression it acts on (its operand) to the table on their shared columns, and then **groups** the rows it has joined. In a call, `s[c]` names the subject `s` and its column `c`, and -`s[c, …]` names several columns of one table. A column is a map of `s`, or one +`s[c, …]` names several columns of one table. A column is a mapping of `s`, or one of the columns of a relation under `dims:`. The subject appears once, so one call uses one table. -| Kind | What it does | Written as | -| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | -| join and group by | rows of the operand match rows of the table, and each group is added up | `sum(x, over=d, by=s[c])` | -| join | each row of the operand matches one row of the table, and takes its label | `at(x, by=s[m])` | -| partition | the dimensions stay, and the rows are grouped | `shift`, `sum_back`, `position` with `within=s[m]` | -| test | a coordinate stays where the relation has a row, or where the map has a label | `r` or `s[m]` in a condition | +| Kind | What it does | Written as | +| ----------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- | +| join and group by | rows of the operand match rows of the table, and each group is added up | `sum(x, over=d, by=s[c])` | +| join | each row of the operand matches one row of the table, and takes its label | `at(x, by=s[m])` | +| partition | the dimensions stay, and the rows are grouped | `shift`, `sum_back`, `position` with `within=s[m]` | +| test | a coordinate stays where the relation has a row, or where the mapping has a label | `r` or `s[m]` in a condition | Four rules apply to every call: 1. A call lists every column it uses. -2. A map that the call does not list is not used. +2. A mapping that the call does not list is not used. 3. The key of a subject cannot change in a call. 4. A dimension that no column of the table is over passes through to the result. Under the first rule, mathspec refuses `at(x, by=generator)`, and the message -lists the maps of the subject: +lists the mappings of the subject: ```text -Constraint 'c': at(by=generator) names the subject and none of its maps. Write by=generator[], with a map of 'generator': ['bus']. +Constraint 'c': at(by=generator) names the subject and none of its mappings. Write by=generator[], with a mapping of 'generator': ['bus']. ``` ### Sums @@ -258,9 +258,9 @@ Each column of the table is either **joined on** or not, and either | a column in `over=` | yes | no | removed | | a column in `by=` | no | yes | added | | a key column the call does not list | yes | yes | kept | -| a map the call does not list | no | no | not used | +| a mapping the call does not list | no | no | not used | -With the relation `zone_of` over `[generator, period]` and its map `zone`, the +With the relation `zone_of` over `[generator, period]` and its mapping `zone`, the relation `connection` over `[generator, bus]`, and a variable `p` over `[generator, period]`, three sums have three results: @@ -275,7 +275,7 @@ Five more rules apply to a sum through a table: - The operand is over every column that the call joins on, and over none that it groups by. A column that the operand is over is joined on. - A name in `over=` is a column of the table, or else a dimension. With the - map `rep` of `snapshot`, `sum(x, over=snapshot, by=snapshot[rep])` joins on + mapping `rep` of `snapshot`, `sum(x, over=snapshot, by=snapshot[rep])` joins on the key column `snapshot` and groups by `rep`. Where two columns are over one dimension, the name selects which one, so `sum(x, over=from, by=neighbour[to])` joins on `from` and groups by `to`. @@ -293,7 +293,7 @@ Under the first rule, with `load` over `[bus]`, mathspec refuses ```text Constraint 'c': sum(by=generator[bus]) groups by ['bus'], which the expression already carries. -Move the factor carrying ['bus'] outside the operator, or group by a map into another dimension. +Move the factor carrying ['bus'] outside the operator, or group by a mapping into another dimension. ``` `load * sum(p, over=generator, by=generator[bus])` is accepted, because the @@ -303,13 +303,13 @@ Under the last rule, with `p` over `[generator, period, zone]`, mathspec refuses `sum(p, over=zone, by=zone_of[generator, period])` and prints: ```text -Constraint 'cap': sum(by=zone_of[generator, period]): the columns this sum groups by, ['generator', 'period'], hold the whole key ['generator', 'period'], so every group is one row and the sum adds nothing. Write at(..., by=zone_of[zone]), or group by a map. +Constraint 'cap': sum(by=zone_of[generator, period]): the columns this sum groups by, ['generator', 'period'], hold the whole key ['generator', 'period'], so every group is one row and the sum adds nothing. Write at(..., by=zone_of[zone]), or group by a mapping. ``` ### Lookups -`at(x, by=s[m])` takes the value of `x` at the label that map `m` gives each -row of `s`. It joins `x` on the maps in `by=` and groups by the key, so every +`at(x, by=s[m])` takes the value of `x` at the label that mapping `m` gives each +row of `s`. It joins `x` on the mappings in `by=` and groups by the key, so every group is one row. A lookup adds up nothing, and each row of the result is the value of `x` at one coordinate. With a variable `build` over `[bus]`, `at(build, by=line[bus0])` has one row per line: @@ -323,31 +323,31 @@ it at `south`. Three rules apply to a lookup: -- A lookup reads only maps. A key column in `by=` is refused, and so is a - relation with no map, where one combination can have several rows. +- A lookup reads only mappings. A key column in `by=` is refused, and so is a + relation with no mapping, where one combination can have several rows. - The result gains every key column that the operand is not already over. A key column over a dimension that the operand is over is joined on too, - unless a map in `by=` already refers to that dimension. With `price` over + unless a mapping in `by=` already refers to that dimension. With `price` over `[zone, period]`, `at(price, by=zone_of[zone])` joins on `zone` and `period`, and its result is `[generator, period]`. `at(x, by=snapshot[rep])` joins on `rep` alone, so the result gains the key column `snapshot`. -- No two maps in `by=` refer to one dimension, because the operand has one +- No two mappings in `by=` refer to one dimension, because the operand has one coordinate along each of its dimensions. With `at(build, by=line[line])`, mathspec prints: ```text -Constraint 'c': at(by=line[line]) names ['line'], a column of 'line' itself. A lookup reads maps at the row. Name one of its maps, ['bus0', 'bus1']. +Constraint 'c': at(by=line[line]) names ['line'], a column of 'line' itself. A lookup reads mappings at the row. Name one of its mappings, ['bus0', 'bus1']. ``` ### Partitions `shift(x, along=d, within=s[m])`, `sum_back(x, along=d, within=s[m])` and `position(d, within=s[m])` step along the key column over `d`. They join on -the other key columns, and split the rows into groups by the maps in +the other key columns, and split the rows into groups by the mappings in `within=`. The dimensions of the result do not change. The result is absent -at a coordinate that the map gives [no group](operators.md#within). With the -map `season` of `snapshot`, +at a coordinate that the mapping gives [no group](operators.md#within). With the +mapping `season` of `snapshot`, `shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[season])` steps back within each season: @@ -358,29 +358,29 @@ steps back within each season: The first snapshot of each season takes the value of the last snapshot of the same season, and no value crosses from winter to summer. -`within=` may list two maps into one dimension, but not a key column. A -relation with no map makes no groups, so mathspec refuses it in `within=`: +`within=` may list two mappings into one dimension, but not a key column. A +relation with no mapping makes no groups, so mathspec refuses it in `within=`: ```text -Constraint 'd': shift(within=sp[period]): 'sp' has no map, so it makes no groups. Declare the group as a map of the dimension shift steps along, under maps: snapshot:. +Constraint 'd': shift(within=sp[period]): 'sp' has no mapping, so it makes no groups. Declare the group as a mapping of the dimension shift steps along, under mappings: snapshot:. ``` ### Tests -A condition tests a relation or a map at the coordinates of its own entry. It -compares a map, written `s[m]`, against a label, compares two maps, or tests +A condition tests a relation or a mapping at the coordinates of its own entry. It +compares a mapping, written `s[m]`, against a label, compares two mappings, or tests that a row or a label exists. [Conditions](expressions.md#conditions) lists -when two maps may be compared. A comparison reads one map, so +when two mappings may be compared. A comparison reads one mapping, so `snapshot[month, weekday] == 'x'` is refused, and mathspec suggests the rewrite on the second line of the message: ```text Variable 'x': Cannot parse the condition "snapshot[month, weekday] == 'x'". -a comparison reads one map of 'snapshot'. Compare each map on its own: snapshot[month] == … AND snapshot[weekday] == …. +a comparison reads one mapping of 'snapshot'. Compare each mapping on its own: snapshot[month] == … AND snapshot[weekday] == …. Expected end of text, found '[' (at char 8), (line:1, col:9) ``` -A map alone in a condition, such as `line[bus1]`, is true where the map gives +A mapping alone in a condition, such as `line[bus1]`, is true where the mapping gives the row a label. A relation name alone is true where the relation has a row. On a variable, the condition leaves the variable absent at every pair that the relation does not list: @@ -424,7 +424,7 @@ constraint: ``` The domain of `flow` is the pairs `(b, g)` in `connection`, at every snapshot. -The columns are sorted to `(bus, generator)`. A map test prints as +The columns are sorted to `(bus, generator)`. A mapping test prints as $`\mathrm{bus1}(l) \text{ is defined}`$. !!! info "See also" diff --git a/docs/reference/notation.md b/docs/reference/notation.md index ab078981c..e3fd75078 100644 --- a/docs/reference/notation.md +++ b/docs/reference/notation.md @@ -23,7 +23,7 @@ typesetter changes nothing else. ### Legend -A dimension, a relation, a map and a parameter declare no equation; what they print is the legend every spec opens with. +A dimension, a relation, a mapping and a parameter declare no equation; what they print is the legend every spec opens with. ```yaml dimensions: @@ -36,17 +36,17 @@ dimensions: bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through relations: - gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other - connection: { dims: [generator, bus], missing: absent } # a relation with no map: many-to-many, read only by sum with both ends named + gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a mapping: a call sums one away and joins on the other + connection: { dims: [generator, bus], missing: absent } # a relation with no mapping: many-to-many, read only by sum with both ends named -maps: - generator: { bus: { dim: bus }, technology: { dim: technology } } # two maps of one subject, read to both at once +mappings: + generator: { bus: { dim: bus }, technology: { dim: technology } } # two mappings of one subject, read to both at once bus: zone: { dim: zone } - area: { dim: zone, missing: absent } # a second map into the same set, to compare against; a bus may be in no area + area: { dim: zone, missing: absent } # a second mapping into the same set, to compare against; a bus may be in no area snapshot: season: { dim: season } - rep: { dim: snapshot } # a map into its own dimension: the representative snapshot + rep: { dim: snapshot } # a mapping into its own dimension: the representative snapshot gen_zone: { zone: { dim: zone } } parameters: @@ -58,7 +58,7 @@ parameters: zone_cap: { dims: [zone] } tech_cap: { dims: [bus, technology], missing: absent } link_eff: { dims: [generator, bus], where: connection, missing: 1 } - area_weight: { dims: [bus], where: "bus[area]" } # a map's label as a condition: the buses that have an area + area_weight: { dims: [bus], where: "bus[area]" } # a mapping's label as a condition: the buses that have an area min_up: { dims: [generator], dtype: int } eta: { dims: [generator] } # a Greek name that is *given*, so the rule wins and it prints as the word lead: { dims: [generator], dtype: int } @@ -149,9 +149,9 @@ parameters: |---|---| | $`t \ominus k`$ | `edge='wrap'` — $`t-k`$, cyclic | | $`t \boxminus_{v} k`$ | `edge=v` — $`t-k`$, and $`v`$ past the edge | -| $`t \ominus^{\mathrm{map}(t)} k`$ | `within=subject[map]` — $`t-k`$ inside the group of $`t`$ | +| $`t \ominus^{\mathrm{map}(t)} k`$ | `within=subject[mapping]` — $`t-k`$ inside the group of $`t`$ | | $`\mathrm{pos}(t)`$ | `position()` — the position of $`t`$, counted from $`0`$; $`t`$ is the label | -| $`\mathrm{pos}_{\mathrm{map}(t)}(t)`$ | `position(within=subject[map])` — the position of $`t`$ inside its group | +| $`\mathrm{pos}_{\mathrm{map}(t)}(t)`$ | `position(within=subject[mapping])` — the position of $`t`$ inside its group | | $`\lvert \mathcal{T} \rvert`$ | the size of $`\mathcal{T}`$; $`\lvert \mathcal{T} \rvert - 1`$ is the last position | ### Variable domains @@ -380,9 +380,9 @@ objective: \max \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} \cdot \mathrm{growth}^{\mathrm{lead}_{g}} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{g}} \right)^{2} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{p}^{\mathrm{max}}_{g} - \mathit{reserve} - \mathit{headroom} ``` -### Relations and maps +### Relations and mappings -#### Sum through a map +#### Sum through a mapping ```yaml constraints: @@ -410,9 +410,9 @@ constraints: \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \le \mathrm{budget} ``` -#### `at` through a map +#### `at` through a mapping -at(), which re-indexes through a map instead of an offset +at(), which re-indexes through a mapping instead of an offset ```yaml constraints: @@ -425,7 +425,7 @@ constraints: \mathit{spill}_{t} \le \mathrm{zone\_cap}_{\mathrm{zone}(u)} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` -#### Sum into two maps +#### Sum into two mappings one table read to two value columns: the domain carries a condition per column @@ -440,7 +440,7 @@ constraints: \sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u \wedge \mathrm{technology}(g) = e} p_{g,t} \le \mathrm{tech\_cap}_{u,e} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ e \in \mathcal{E} ``` -#### `at` through two maps +#### `at` through two mappings the same table joined the other way, reading one slot through two columns @@ -455,7 +455,7 @@ constraints: \mathit{units}_{g} \le \mathrm{tech\_cap}_{\mathrm{bus}(g),\mathrm{technology}(g)} \qquad \forall\, g \in \mathcal{G} ``` -#### Shift within one map +#### Shift within one mapping a partition grouped by one named value column of a two-value table, and a position within both @@ -473,7 +473,7 @@ constraints: #### Sum through a relation -a sum through a relation with no map: the domain is a row of the relation rather than a label +a sum through a relation with no mapping: the domain is a row of the relation rather than a label ```yaml constraints: @@ -502,9 +502,9 @@ constraints: p_{g,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \left( u,\ g \right) \in \mathrm{connection} ``` -#### Map into its own dimension +#### Mapping into its own dimension -a map into its own dimension, read both ways: the frame is unchanged and the index is primed +a mapping into its own dimension, read both ways: the frame is unchanged and the index is primed ```yaml constraints: @@ -517,9 +517,9 @@ constraints: \sum_{t' \in \mathcal{T} \,:\, \mathrm{rep}(t') = t} \mathit{spill}_{t'} \le \mathit{spill}_{\mathrm{rep}(t)} \qquad \forall\, t \in \mathcal{T} ``` -#### Sum through a map of a relation +#### Sum through a mapping of a relation -a grouping through a two-key map, summing one key away: the condition reads the other, and the row keeps it +a grouping through a two-key mapping, summing one key away: the condition reads the other, and the row keeps it ```yaml constraints: @@ -549,7 +549,7 @@ constraints: #### Sum between the two columns of a relation -the same relation read between its own two columns: no map is read, so the domain asks only that the row is there +the same relation read between its own two columns: no mapping is read, so the domain asks only that the row is there ```yaml constraints: @@ -562,7 +562,7 @@ constraints: \sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}} \mathit{units}_{g} \le \mathrm{budget} \qquad \forall\, t \in \mathcal{T} ``` -#### `at` through a map of a relation +#### `at` through a mapping of a relation the same table joined the other way, reading the slot the row's own snapshot puts the generator in @@ -961,7 +961,7 @@ p_{g,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \fo #### Cyclic shift within a group -a translation partitioned by a map: the group rides on the operator +a translation partitioned by a mapping: the group rides on the operator ```yaml constraints: @@ -1023,7 +1023,7 @@ constraints: #### Window within a group -a window partitioned by a map: the group rides on the operator +a window partitioned by a mapping: the group rides on the operator ```yaml constraints: @@ -1425,9 +1425,9 @@ assumptions: \mathrm{lead}_{g} \le 3 \qquad \forall\, g \in \mathcal{G} ``` -#### Two maps compared +#### Two mappings compared -two maps into one set, compared row by row +two mappings into one set, compared row by row ```yaml assumptions: @@ -1481,9 +1481,9 @@ assumptions: \mathrm{p}^{\mathrm{min}}_{g} < \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{is\_flexible}_{g} ``` -#### Assumption with a map condition +#### Assumption with a mapping condition -a map comparison as the where, over a frame two dims wide +a mapping comparison as the where, over a frame two dims wide ```yaml assumptions: @@ -1562,9 +1562,9 @@ constraints: \mathit{on}_{g,t} = 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 ``` -#### Map compared to a label +#### Mapping compared to a label -a map compared to a label, to another map, and tested for a label +a mapping compared to a label, to another mapping, and tested for a label ```yaml constraints: @@ -1644,7 +1644,7 @@ p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t #### Shift and lookup in a condition -a translation under a comparison names its edge, a lookup reads through a map, and the position keeps the vacated row out +a translation under a comparison names its edge, a lookup reads through a mapping, and the position keeps the vacated row out ```yaml constraints: @@ -1722,9 +1722,9 @@ constraints: \mathit{slack}_{t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} \wedge \neg \left( \mathrm{load}_{u,t - 1} \text{ is defined} \right) ``` -#### Condition through a map +#### Condition through a mapping -a condition read through a map: a bus is held only where its zone has a cap at all +a condition read through a mapping: a bus is held only where its zone has a cap at all ```yaml constraints: diff --git a/docs/reference/reading.md b/docs/reference/reading.md index 62edcc9ab..41908025a 100644 --- a/docs/reference/reading.md +++ b/docs/reference/reading.md @@ -42,7 +42,7 @@ the file changes nothing: - the entries of each section, and of each kind under `given:` - each `dims:` list -- the columns of each relation, and the maps of each subject +- the columns of each relation, and the mappings of each subject - the cases under `cases:` - the `kwargs:` of a macro - the labels under `one_of:` @@ -165,9 +165,9 @@ the colon is the description that the file sets. [`missing:`](language/absence.md#missing) for a missing row of that parameter. It is `'refused'`, `'absent'`, or the value that a tool uses for the row. `program.relations` has one table per relation and per subject with -[maps](language/relations.md#the-data-contract), named after it, and each map +[mappings](language/relations.md#the-data-contract), named after it, and each mapping is one of its `values`. `program.relations[name].missing` is `'refused'` or -`'absent'`, and `partial` lists the maps under `missing: absent`. The program of +`'absent'`, and `partial` lists the mappings under `missing: absent`. The program of `spec.expand(...)` has the same `missing` values. A [given](language/parameters-variables-constraints.md#given) parameter is a @@ -262,17 +262,17 @@ A name compared against a literal is a different node. `p_max > 5` is a `ParameterComparison` and `1 * p_max > 5` is an `ExpressionComparison`, though both are true at the same coordinates. -A comparison of a map against a label is a `RelationComparison`, and a -comparison of two maps is a `RelationPairComparison`. The page on [conditions](language/expressions.md#conditions) defines both, -and both are false for every operator where the map gives no label. A -relation name alone is a `RelationDefined`, and a map alone, `subject[map]`, is a -`RelationDefined` with `column` set to the map. +A comparison of a mapping against a label is a `RelationComparison`, and a +comparison of two mappings is a `RelationPairComparison`. The page on [conditions](language/expressions.md#conditions) defines both, +and both are false for every operator where the mapping gives no label. A +relation name alone is a `RelationDefined`, and a mapping alone, `subject[mapping]`, is a +`RelationDefined` with `column` set to the mapping. Three conditions contain another condition rather than an entry. A `CountComparison` contains the condition that it counts and the dimension that it counts away. A `TranslatedCondition` contains the condition that it evaluates at a neighbouring coordinate. A `JoinedCondition` contains the -condition that it evaluates through a map, and the `JoinColumns` that it +condition that it evaluates through a mapping, and the `JoinColumns` that it joins on and groups by. Each of the three contains its inner condition as a `Mask`, whereas a @@ -383,12 +383,12 @@ report has these attributes: - `undecided` lists each `shift` or join whose reach, the number of coordinates that it looks across, is known only when the data is attached. Each is a `Reach`, with the entry, the name of what the entry uses, and the - kind of use. The name is a parameter, or `subject[map]` where a map decides + kind of use. The name is a parameter, or `subject[mapping]` where a mapping decides the reach, such as `snapshot[season]`. - `resolved()` is a method that takes a mapping from a parameter under `undecided` to the least of its values. It returns the report with each `shift` offset in the mapping folded into `ahead`. A reach through a - map stays undecided, and a name that no undecided reach uses raises + mapping stays undecided, and a name that no undecided reach uses raises `KeyError`. - `restarts` lists each entry that counts a `position()` along the dimension. - `linking_rows` lists each constraint that no single window contains. @@ -445,7 +445,7 @@ Writing the canonical form out again gives the same text. The canonical form has these rules: - The sections come in one fixed order: `version`, `description`, `given`, - `dimensions`, `relations`, `maps`, `parameters`, `conditions`, `variables`, + `dimensions`, `relations`, `mappings`, `parameters`, `conditions`, `variables`, `expressions`, `objective`, `constraints`, `sos`, `piecewise`, `assumptions`, `macros`. The keys of an entry also come in one order. - Entries are sorted by name within each section, and so is every other list @@ -456,7 +456,7 @@ has these rules: brackets are the printer's rather than the author's. - The terms of a sum are sorted with their signs, so `y - x` is written as `-x + y`. The factors of a product, the keyword arguments of a call, and a - list of names or the maps of a subject in a call, such as + list of names or the mappings of a subject in a call, such as `over=[generator, snapshot]`, are sorted too. - A sum of two or more terms is broken one term to a line, each under its own sign. diff --git a/docs/static/absence-relation-missing.svg b/docs/static/absence-relation-missing.svg index dcef14b0c..bd3a84d33 100644 --- a/docs/static/absence-relation-missing.svg +++ b/docs/static/absence-relation-missing.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A map with missing absent is absent at a row with no label - The dimension line has three labels: l1, l2 and l3. The map line[bus1], declared with missing absent, gives each line a bus. Its data gives l1 the bus north and l2 the bus south, and gives l3 no label. At l3 the map line[bus1] is absent. + A mapping with missing absent is absent at a row with no label + The dimension line has three labels: l1, l2 and l3. The mapping line[bus1], declared with missing absent, gives each line a bus. Its data gives l1 the bus north and l2 the bus south, and gives l3 no label. At l3 the mapping line[bus1] is absent. @@ -21,7 +21,7 @@ SPDX-License-Identifier: CC-BY-4.0 - maps: + mappings: line: { bus1: { dim: bus, missing: absent } } line @@ -48,7 +48,7 @@ SPDX-License-Identifier: CC-BY-4.0 line[bus1] - a map + a mapping line bus1 diff --git a/docs/static/expressions-at-condition.svg b/docs/static/expressions-at-condition.svg index a1cc2e750..fcb79851d 100644 --- a/docs/static/expressions-at-condition.svg +++ b/docs/static/expressions-at-condition.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - at in a condition reads a condition through a map - The map flow[converter] gives flows f1 and f2 the converter c1 and flow f3 the converter c2. The parameter has_curve is true at c1 and false at c2. The variable rate, declared with where at of has_curve by flow[converter], is a table with two rows, f1 and f2. The converter of f3 has no curve, so rate has no row for f3 and is absent there. + at in a condition reads a condition through a mapping + The mapping flow[converter] gives flows f1 and f2 the converter c1 and flow f3 the converter c2. The parameter has_curve is true at c1 and false at c2. The variable rate, declared with where at of has_curve by flow[converter], is a table with two rows, f1 and f2. The converter of f3 has no curve, so rate has no row for f3 and is absent there. @@ -20,7 +20,7 @@ SPDX-License-Identifier: CC-BY-4.0 flow[converter] - a map, with has_curve + a mapping, with has_curve flowconverterhas_curve f1c1true diff --git a/docs/static/expressions-position.svg b/docs/static/expressions-position.svg index cd582874c..fb4875faa 100644 --- a/docs/static/expressions-position.svg +++ b/docs/static/expressions-position.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> position within a partition keeps the first snapshot of each period - The map snapshot[period] gives snapshots 1 and 2 the period 2030 and snapshots 3 and 4 the period 2040. position of snapshot within snapshot[period] is 0 at snapshots 1 and 3 and 1 at snapshots 2 and 4. The condition position equal to 0 is true at snapshots 1 and 3, so the constraint soc_start has one row per period, at snapshots 1 and 3, and no row at snapshots 2 and 4. + The mapping snapshot[period] gives snapshots 1 and 2 the period 2030 and snapshots 3 and 4 the period 2040. position of snapshot within snapshot[period] is 0 at snapshots 1 and 3 and 1 at snapshots 2 and 4. The condition position equal to 0 is true at snapshots 1 and 3, so the constraint soc_start has one row per period, at snapshots 1 and 3, and no row at snapshots 2 and 4. @@ -40,7 +40,7 @@ SPDX-License-Identifier: CC-BY-4.0 snapshot[period] - a map + a mapping snapshot period 1 diff --git a/docs/static/linear-maps-at.svg b/docs/static/linear-maps-at.svg index 9f8ce2968..34343b99d 100644 --- a/docs/static/linear-maps-at.svg +++ b/docs/static/linear-maps-at.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A lookup through a map is a join with one row per key - The parameter zone_cap has a value at each snapshot, 0 and 1, and each zone, north and south: 5 and 2 at snapshot 0, 6 and 3 at snapshot 1. The map zone_of[zone], of the relation zone_of over generator and snapshot, puts wind in zone north at both snapshots, and gas in zone north at snapshot 0 and in zone south at snapshot 1. The lookup joins each row of zone_of with the row of zone_cap that has the same snapshot and zone. The result has one row per row of zone_of: at snapshot 0, wind and gas both take 5, the value at north. At snapshot 1, wind takes 6, the value at north, and gas takes 3, the value at south. No row of the result takes the value 2 at snapshot 0 and zone south. + A lookup through a mapping is a join with one row per key + The parameter zone_cap has a value at each snapshot, 0 and 1, and each zone, north and south: 5 and 2 at snapshot 0, 6 and 3 at snapshot 1. The mapping zone_of[zone], of the relation zone_of over generator and snapshot, puts wind in zone north at both snapshots, and gas in zone north at snapshot 0 and in zone south at snapshot 1. The lookup joins each row of zone_of with the row of zone_cap that has the same snapshot and zone. The result has one row per row of zone_of: at snapshot 0, wind and gas both take 5, the value at north. At snapshot 1, wind takes 6, the value at north, and gas takes 3, the value at south. No row of the result takes the value 2 at snapshot 0 and zone south. @@ -21,7 +21,7 @@ SPDX-License-Identifier: CC-BY-4.0 relations: { zone_of: { dims: [generator, snapshot], missing: absent } } - maps: { zone_of: { zone: { dim: zone } } } + mappings: { zone_of: { zone: { dim: zone } } } parameters: zone_cap: { dims: [snapshot, zone] } at(zone_cap, by=zone_of[zone]) @@ -29,7 +29,7 @@ SPDX-License-Identifier: CC-BY-4.0 zone_cap a parameter zone_of[zone] - a map + a mapping the result an expression diff --git a/docs/static/linear-maps-empty.svg b/docs/static/linear-maps-empty.svg index fccb85683..b1e6770c4 100644 --- a/docs/static/linear-maps-empty.svg +++ b/docs/static/linear-maps-empty.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> An empty group is a row with no variable, and a key tuple outside the domain has no row - The map zone_of[zone], of the relation zone_of over generator and snapshot with missing: absent, puts wind in zone north at snapshots 0 and 1, and gas in zone north at snapshot 0. It has no row for gas at snapshot 1, so f has no value there. The constraint zonal sums p by zone and has one row per snapshot and zone. At snapshot 0, north is p of wind plus p of gas, at most 5. At snapshot 1, north is p of wind, at most 6. South has no generator at either snapshot, so its rows are 0 at most 2 and 0 at most 3: empty groups with no variable. The lookup at of zone_cap by zone_of[zone] has one row per row of zone_of: wind at 0 takes 5, gas at 0 takes 5, wind at 1 takes 6. It has no row for gas at snapshot 1, where at is absent. + The mapping zone_of[zone], of the relation zone_of over generator and snapshot with missing: absent, puts wind in zone north at snapshots 0 and 1, and gas in zone north at snapshot 0. It has no row for gas at snapshot 1, so f has no value there. The constraint zonal sums p by zone and has one row per snapshot and zone. At snapshot 0, north is p of wind plus p of gas, at most 5. At snapshot 1, north is p of wind, at most 6. South has no generator at either snapshot, so its rows are 0 at most 2 and 0 at most 3: empty groups with no variable. The lookup at of zone_cap by zone_of[zone] has one row per row of zone_of: wind at 0 takes 5, gas at 0 takes 5, wind at 1 takes 6. It has no row for gas at snapshot 1, where at is absent. @@ -21,12 +21,12 @@ SPDX-License-Identifier: CC-BY-4.0 relations: { zone_of: { dims: [generator, snapshot], missing: absent } } - maps: { zone_of: { zone: { dim: zone } } } + mappings: { zone_of: { zone: { dim: zone } } } sum(p, over=generator, by=zone_of[zone]) <= zone_cap at(zone_cap, by=zone_of[zone]) zone_of[zone] - a map + a mapping zonal a constraint at(zone_cap, by=zone_of[zone]) diff --git a/docs/static/linear-maps-join.svg b/docs/static/linear-maps-join.svg index b8c7fd45a..ec36cd6aa 100644 --- a/docs/static/linear-maps-join.svg +++ b/docs/static/linear-maps-join.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A sum through a map is a join, then a group-by with a sum - The variable p has a row at each generator, gas and wind, and each snapshot, 0 and 1. The map zone_of[zone], of the relation zone_of over generator and snapshot, puts gas in zone north at snapshot 0 and in zone south at snapshot 1, and wind in zone north at both snapshots. The join pairs each row of p with the row of zone_of that has the same generator and snapshot, and each pair takes the zone of that row. The group-by adds the pairs that have the same snapshot and zone. The result y has three rows: at snapshot 0 and zone north, p of gas and 0 plus p of wind and 0. At snapshot 1 and zone north, p of wind and 1. At snapshot 1 and zone south, p of gas and 1. + A sum through a mapping is a join, then a group-by with a sum + The variable p has a row at each generator, gas and wind, and each snapshot, 0 and 1. The mapping zone_of[zone], of the relation zone_of over generator and snapshot, puts gas in zone north at snapshot 0 and in zone south at snapshot 1, and wind in zone north at both snapshots. The join pairs each row of p with the row of zone_of that has the same generator and snapshot, and each pair takes the zone of that row. The group-by adds the pairs that have the same snapshot and zone. The result y has three rows: at snapshot 0 and zone north, p of gas and 0 plus p of wind and 0. At snapshot 1 and zone north, p of wind and 1. At snapshot 1 and zone south, p of gas and 1. @@ -26,7 +26,7 @@ SPDX-License-Identifier: CC-BY-4.0 relations: { zone_of: { dims: [generator, snapshot], missing: absent } } - maps: { zone_of: { zone: { dim: zone } } } + mappings: { zone_of: { zone: { dim: zone } } } variables: p: { dims: [snapshot, generator] } sum(p, over=generator, by=zone_of[zone]) @@ -34,7 +34,7 @@ SPDX-License-Identifier: CC-BY-4.0 p a variable zone_of[zone] - a map + a mapping the join one pair per matching row the result diff --git a/docs/static/operators-at.svg b/docs/static/operators-at.svg index 4e45ef296..8c4454ccb 100644 --- a/docs/static/operators-at.svg +++ b/docs/static/operators-at.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> at reads one bus value once for each line at that bus - The variable build has one row per bus, north and south. The map line[bus] puts lines l1 and l2 on bus north and line l3 on bus south. at of build by line[bus] has one row per line: l1 and l2 both read build at north, and l3 reads build at south. + The variable build has one row per bus, north and south. The mapping line[bus] puts lines l1 and l2 on bus north and line l3 on bus south. at of build by line[bus] has one row per line: l1 and l2 both read build at north, and l3 reads build at south. @@ -30,7 +30,7 @@ SPDX-License-Identifier: CC-BY-4.0 line[bus] - a map + a mapping line bus diff --git a/docs/static/operators-shift-within.svg b/docs/static/operators-shift-within.svg index 202b515a1..31400eedb 100644 --- a/docs/static/operators-shift-within.svg +++ b/docs/static/operators-shift-within.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> shift with within= wraps inside each season - The variable soc has four rows, snapshots 1 to 4. The map snapshot[season] puts snapshots 1 and 2 in winter and snapshots 3 and 4 in summer. shift of soc along snapshot, offset 1, edge wrap, within snapshot[season], has one row per snapshot. Snapshot 2 reads soc at 1 and snapshot 4 reads soc at 3. Snapshot 1, the first of winter, wraps to soc at 2, the last of winter, and snapshot 3, the first of summer, wraps to soc at 4. + The variable soc has four rows, snapshots 1 to 4. The mapping snapshot[season] puts snapshots 1 and 2 in winter and snapshots 3 and 4 in summer. shift of soc along snapshot, offset 1, edge wrap, within snapshot[season], has one row per snapshot. Snapshot 2 reads soc at 1 and snapshot 4 reads soc at 3. Snapshot 1, the first of winter, wraps to soc at 2, the last of winter, and snapshot 3, the first of summer, wraps to soc at 4. @@ -36,7 +36,7 @@ SPDX-License-Identifier: CC-BY-4.0 snapshot[season] - a map + a mapping snapshot season diff --git a/docs/static/operators-sum.svg b/docs/static/operators-sum.svg index c96439637..be38be4b1 100644 --- a/docs/static/operators-sum.svg +++ b/docs/static/operators-sum.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A nodal balance sums each kind of component by bus - The map generator[bus] puts the generators wind and gas on bus north, and solar on bus south. The maps line[bus0] and line[bus1] give the line l1 from north to south. The constraint nodal_balance has one row per bus. At north it adds p of wind and p of gas, and subtracts f of l1. At south it adds p of solar and f of l1. + The mapping generator[bus] puts the generators wind and gas on bus north, and solar on bus south. The mappings line[bus0] and line[bus1] give the line l1 from north to south. The constraint nodal_balance has one row per bus. At north it adds p of wind and p of gas, and subtracts f of l1. At south it adds p of solar and f of l1. @@ -19,7 +19,7 @@ SPDX-License-Identifier: CC-BY-4.0 generator[bus] - a map + a mapping generator bus @@ -38,7 +38,7 @@ SPDX-License-Identifier: CC-BY-4.0 line[bus0], line[bus1] - two maps + two mappings line bus0 diff --git a/docs/static/parameters-where.svg b/docs/static/parameters-where.svg index fa949fd80..d803232b2 100644 --- a/docs/static/parameters-where.svg +++ b/docs/static/parameters-where.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A where condition on a parameter drops rows of its data - At one snapshot, the relation connection has three rows: chp to el, chp to heat and boiler to heat, and its map role gives each of them the label output. The data of efficiency has three rows: chp el 0.4, boiler heat 0.9 and boiler el 0.5. With where connection[role] == output and missing 1, the parameter efficiency has three rows: chp el 0.4, chp heat 1 and boiler heat 0.9. The data row for boiler el, which connection does not list, has no role, so it is dropped, so efficiency is absent there. The row for chp heat, which the data does not have, takes the value 1. + At one snapshot, the relation connection has three rows: chp to el, chp to heat and boiler to heat, and its mapping role gives each of them the label output. The data of efficiency has three rows: chp el 0.4, boiler heat 0.9 and boiler el 0.5. With where connection[role] == output and missing 1, the parameter efficiency has three rows: chp el 0.4, chp heat 1 and boiler heat 0.9. The data row for boiler el, which connection does not list, has no role, so it is dropped, so efficiency is absent there. The row for chp heat, which the data does not have, takes the value 1. @@ -23,7 +23,7 @@ SPDX-License-Identifier: CC-BY-4.0 connection - a relation with the map role + a relation with the mapping role efficiency the data, at one snapshot efficiency diff --git a/docs/static/relations-at.svg b/docs/static/relations-at.svg index 587ca5c47..5cd097d24 100644 --- a/docs/static/relations-at.svg +++ b/docs/static/relations-at.svg @@ -4,14 +4,14 @@ SPDX-License-Identifier: CC-BY-4.0 --> at reads one bus value once for each line at that bus - The variable build has one row per bus, north and south. The map line[bus0] puts lines l1 and l2 on bus north and line l3 on bus south. at of build by line[bus0] has one row per line: l1 and l2 both read build at north, and l3 reads build at south. + The variable build has one row per bus, north and south. The mapping line[bus0] puts lines l1 and l2 on bus north and line l3 on bus south. at of build by line[bus0] has one row per line: l1 and l2 both read build at north, and l3 reads build at south. - maps: + mappings: line: { bus0: bus } @@ -35,7 +35,7 @@ SPDX-License-Identifier: CC-BY-4.0 line[bus0] - a map + a mapping line bus0 diff --git a/docs/static/relations-missing.svg b/docs/static/relations-missing.svg index 7625c58ac..e747139cb 100644 --- a/docs/static/relations-missing.svg +++ b/docs/static/relations-missing.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A map with missing absent is absent at a row with no label - The dimension line has three labels: l1, l2 and l3. The map line[bus1], declared with missing absent, gives each line a bus. Its data gives l1 the bus north and l2 the bus south, and gives l3 no label. At l3 the map line[bus1] is absent. + A mapping with missing absent is absent at a row with no label + The dimension line has three labels: l1, l2 and l3. The mapping line[bus1], declared with missing absent, gives each line a bus. Its data gives l1 the bus north and l2 the bus south, and gives l3 no label. At l3 the mapping line[bus1] is absent. @@ -45,7 +45,7 @@ SPDX-License-Identifier: CC-BY-4.0 line[bus1] - a map + a mapping line bus1 diff --git a/docs/static/relations-partition.svg b/docs/static/relations-partition.svg index 856bedfa3..26fbc6138 100644 --- a/docs/static/relations-partition.svg +++ b/docs/static/relations-partition.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A partition by snapshot[season]: shift wraps inside each season - The variable soc has four rows, snapshots 1 to 4. The map snapshot[season] puts snapshots 1 and 2 in winter and snapshots 3 and 4 in summer. shift of soc along snapshot, offset 1, edge wrap, within snapshot[season], has one row per snapshot. Snapshot 2 reads soc at 1 and snapshot 4 reads soc at 3. Snapshot 1, the first of winter, wraps to soc at 2, the last of winter, and snapshot 3, the first of summer, wraps to soc at 4. + The variable soc has four rows, snapshots 1 to 4. The mapping snapshot[season] puts snapshots 1 and 2 in winter and snapshots 3 and 4 in summer. shift of soc along snapshot, offset 1, edge wrap, within snapshot[season], has one row per snapshot. Snapshot 2 reads soc at 1 and snapshot 4 reads soc at 3. Snapshot 1, the first of winter, wraps to soc at 2, the last of winter, and snapshot 3, the first of summer, wraps to soc at 4. @@ -22,7 +22,7 @@ SPDX-License-Identifier: CC-BY-4.0 - maps: { snapshot: { season: { dim: season } } } + mappings: { snapshot: { season: { dim: season } } } shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[season]) soc @@ -39,7 +39,7 @@ SPDX-License-Identifier: CC-BY-4.0 snapshot[season] - a map + a mapping snapshot season diff --git a/docs/static/relations-sum-by.svg b/docs/static/relations-sum-by.svg index 6152d17b3..ec57658cd 100644 --- a/docs/static/relations-sum-by.svg +++ b/docs/static/relations-sum-by.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A sum through a map joins, then groups - The variable p is a table with three rows: wind, gas and solar. The map generator[bus] has three rows: wind on north, gas on north and solar on south. The sum of p over generator by generator[bus] first joins p to the table of generator on generator, which gives each row of p its bus. It then adds up the rows of each bus. The result is a table with one row per bus: north holds p of wind plus p of gas, and south holds p of solar. + A sum through a mapping joins, then groups + The variable p is a table with three rows: wind, gas and solar. The mapping generator[bus] has three rows: wind on north, gas on north and solar on south. The sum of p over generator by generator[bus] first joins p to the table of generator on generator, which gives each row of p its bus. It then adds up the rows of each bus. The result is a table with one row per bus: north holds p of wind plus p of gas, and south holds p of solar. @@ -24,7 +24,7 @@ SPDX-License-Identifier: CC-BY-4.0 - maps: + mappings: generator: { bus: { dim: bus } } variables: p: { dims: [generator] } @@ -39,7 +39,7 @@ SPDX-License-Identifier: CC-BY-4.0 solar generator[bus] - a map + a mapping generator bus diff --git a/docs/tutorials/first-spec.md b/docs/tutorials/first-spec.md index bb3ad7c45..d1fcd0407 100644 --- a/docs/tutorials/first-spec.md +++ b/docs/tutorials/first-spec.md @@ -46,8 +46,8 @@ Check the file: ``` ```text -dimension 'generator' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. -dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'generator' is never used: nothing is indexed by it, nothing sums into it, and no relation or mapping is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or mapping is over it. Remove it, or keep it if the entries that use it are still to be written. ``` mathspec accepts the file. `check` prints one remark that is not a refusal (a line of diff --git a/docs/tutorials/several-files.md b/docs/tutorials/several-files.md index 59ceb055a..30cedd23a 100644 --- a/docs/tutorials/several-files.md +++ b/docs/tutorials/several-files.md @@ -81,7 +81,7 @@ Make a file `generators.yaml`. The file declares the [shared dimensions](../refe [`adds_to:`](../reference/language/named.md#adds_to) keys of the file make `generation` a term of the injection and `generation_cost` a term of the total cost. `generator[bus]` gives each generator its bus -(a [map](../reference/language/relations.md#maps)). `generation` uses `generator[bus]` to sum the dispatch by bus. +(a [mapping](../reference/language/relations.md#mappings)). `generation` uses `generator[bus]` to sum the dispatch by bus. ```yaml title="generators.yaml" description: A generator fleet, each unit on one bus. @@ -96,7 +96,7 @@ dimensions: bus: { dtype: str } generator: { description: generating units } -maps: +mappings: generator: bus: { dim: bus, description: the bus a generator sits on } diff --git a/docs/tutorials/storage.md b/docs/tutorials/storage.md index 4df67b0b1..3e1872f30 100644 --- a/docs/tutorials/storage.md +++ b/docs/tutorials/storage.md @@ -44,8 +44,8 @@ Check the file: ``` ```text -dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. -dimension 'store' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or mapping is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'store' is never used: nothing is indexed by it, nothing sums into it, and no relation or mapping is over it. Remove it, or keep it if the entries that use it are still to be written. ``` mathspec accepts the file. `check` prints one remark that is not a refusal (a line of diff --git a/examples/connection.yaml b/examples/connection.yaml index 37ef20837..a393ac50f 100644 --- a/examples/connection.yaml +++ b/examples/connection.yaml @@ -17,7 +17,7 @@ relations: dims: [unit, port] missing: absent -maps: +mappings: connection: { bus: { dim: bus }, role: { dim: role } } parameters: diff --git a/examples/library/generator.yaml b/examples/library/generator.yaml index fdfa3fe64..7f66d7aeb 100644 --- a/examples/library/generator.yaml +++ b/examples/library/generator.yaml @@ -17,7 +17,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } port: { dtype: str, description: "the connections components make, one label per connection" } generator: { dtype: str, description: "generating units, each on one port" } -maps: +mappings: generator: { port: { dim: port } } parameters: Generator_p_nom: { dims: [generator], description: nominal power } diff --git a/examples/library/load.yaml b/examples/library/load.yaml index 26cb5c575..fa74fc412 100644 --- a/examples/library/load.yaml +++ b/examples/library/load.yaml @@ -12,7 +12,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } port: { dtype: str, description: "the connections components make, one label per connection" } load: { dtype: str, description: "demands, each on one port" } -maps: +mappings: load: { port: { dim: port } } parameters: Load_p_set: { dims: [snapshot, load], description: "`Load-p_set` — what a load takes in a snapshot" } diff --git a/examples/library/surface.yaml b/examples/library/surface.yaml index f82566506..81b9b2ab6 100644 --- a/examples/library/surface.yaml +++ b/examples/library/surface.yaml @@ -15,7 +15,7 @@ dimensions: snapshot: { dtype: datetime, description: dispatch periods } bus: { dtype: str, description: network nodes } port: { dtype: str, description: "the connections components make, one label per connection" } -maps: +mappings: port: { bus: { dim: bus } } variables: Port_p: diff --git a/examples/operators/at.yaml b/examples/operators/at.yaml index cd7a43bfb..eb3de4946 100644 --- a/examples/operators/at.yaml +++ b/examples/operators/at.yaml @@ -4,13 +4,13 @@ description: >- The join without a grouping: `at(array, by=subject[m])` takes, for each - `snapshot`, the value at the `period` that the map gives that snapshot. + `snapshot`, the value at the `period` that the mapping gives that snapshot. dimensions: snapshot: { dtype: int } period: { dtype: int } -maps: +mappings: snapshot: { period: { dim: period } } parameters: diff --git a/examples/operators/at_columns.yaml b/examples/operators/at_columns.yaml index 46a94500c..5791f5e3e 100644 --- a/examples/operators/at_columns.yaml +++ b/examples/operators/at_columns.yaml @@ -3,15 +3,15 @@ # SPDX-License-Identifier: MIT description: >- - One of two maps: where a subject has two maps into one dimension, - `at(array, by=subject[m])` takes the value at the label of map `m`. Here `m` + One of two mappings: where a subject has two mappings into one dimension, + `at(array, by=subject[m])` takes the value at the label of mapping `m`. Here `m` is `bus0`, the sending end of a line. dimensions: line: { dtype: str } bus: { dtype: str } -maps: +mappings: line: { bus0: { dim: bus }, bus1: { dim: bus } } parameters: diff --git a/examples/operators/shift_partitioned.yaml b/examples/operators/shift_partitioned.yaml index 84de92fa9..daca58eac 100644 --- a/examples/operators/shift_partitioned.yaml +++ b/examples/operators/shift_partitioned.yaml @@ -11,7 +11,7 @@ dimensions: snapshot: { dtype: int, ordered: true } season: { dtype: str } -maps: +mappings: snapshot: { season: { dim: season } } variables: diff --git a/examples/operators/sum_back_partitioned.yaml b/examples/operators/sum_back_partitioned.yaml index 52dcbd544..2f9d383b8 100644 --- a/examples/operators/sum_back_partitioned.yaml +++ b/examples/operators/sum_back_partitioned.yaml @@ -10,7 +10,7 @@ dimensions: hour: { dtype: int, ordered: true } day: { dtype: str } -maps: +mappings: hour: { day: { dim: day } } variables: diff --git a/examples/operators/sum_by.yaml b/examples/operators/sum_by.yaml index 8b2599742..c3ed27091 100644 --- a/examples/operators/sum_by.yaml +++ b/examples/operators/sum_by.yaml @@ -4,7 +4,7 @@ description: >- A sum by group: `sum(array, over=dim, by=subject[m])` groups the result by - the label that map `m` gives each row. The data of the map, not the file, + the label that mapping `m` gives each row. The data of the mapping, not the file, sets which generator sits at which bus. dimensions: @@ -12,7 +12,7 @@ dimensions: generator: { dtype: str } bus: { dtype: str } -maps: +mappings: generator: { bus: { dim: bus } } parameters: diff --git a/examples/operators/sum_by_column_lists.yaml b/examples/operators/sum_by_column_lists.yaml index ca61c040d..12f62dfcf 100644 --- a/examples/operators/sum_by_column_lists.yaml +++ b/examples/operators/sum_by_column_lists.yaml @@ -3,8 +3,8 @@ # SPDX-License-Identifier: MIT description: >- - Several columns and maps: `sum(array, over=[dim, …], by=subject[m, …])` - joins on both columns of the relation and groups by both of its maps. + Several columns and mappings: `sum(array, over=[dim, …], by=subject[m, …])` + joins on both columns of the relation and groups by both of its mappings. dimensions: generator: { dtype: str } @@ -15,7 +15,7 @@ dimensions: relations: slot_of: { dims: [generator, period] } -maps: +mappings: slot_of: { bus: { dim: bus }, technology: { dim: technology } } parameters: diff --git a/examples/operators/sum_by_columns.yaml b/examples/operators/sum_by_columns.yaml index e417f783c..3acd01af0 100644 --- a/examples/operators/sum_by_columns.yaml +++ b/examples/operators/sum_by_columns.yaml @@ -4,7 +4,7 @@ description: >- A sum that keeps a key column: `sum(array, over=dim, by=subject[m])` joins - on the column over `dim` and groups by map `m`. The sum also joins on the + on the column over `dim` and groups by mapping `m`. The sum also joins on the key column that the call does not list. It keeps that column, so each zone gets one total per period. @@ -16,7 +16,7 @@ dimensions: relations: zone_of: { dims: [generator, period] } -maps: +mappings: zone_of: { zone: { dim: zone } } parameters: diff --git a/examples/piecewise_coupling.yaml b/examples/piecewise_coupling.yaml index d512f4364..036948c40 100644 --- a/examples/piecewise_coupling.yaml +++ b/examples/piecewise_coupling.yaml @@ -28,7 +28,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: flow: converter: description: which converter each flow belongs to diff --git a/examples/pypsa.yaml b/examples/pypsa.yaml index bf6655374..049e85d0f 100644 --- a/examples/pypsa.yaml +++ b/examples/pypsa.yaml @@ -1607,7 +1607,7 @@ relations: dims: { scenario: scenario, process: process, start: snapshot, covered: snapshot } missing: absent -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/flow_based.yaml b/examples/pypsa/flow_based.yaml index 82efe945a..6b1a2a75b 100644 --- a/examples/pypsa/flow_based.yaml +++ b/examples/pypsa/flow_based.yaml @@ -31,7 +31,7 @@ dimensions: positions (PyPSA's `domain` of a `flow_based` row), data prep. A run whose flow-based rows name no domain has one. A run without them has none -maps: +mappings: bus: flow_based_domain: description: >- diff --git a/examples/pypsa/generator.yaml b/examples/pypsa/generator.yaml index 486895611..0460ee904 100644 --- a/examples/pypsa/generator.yaml +++ b/examples/pypsa/generator.yaml @@ -52,7 +52,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/generator_commitment.yaml b/examples/pypsa/generator_commitment.yaml index f69a3f5c2..f0a0e5072 100644 --- a/examples/pypsa/generator_commitment.yaml +++ b/examples/pypsa/generator_commitment.yaml @@ -50,7 +50,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/generator_ramping.yaml b/examples/pypsa/generator_ramping.yaml index 11d870143..499b3f726 100644 --- a/examples/pypsa/generator_ramping.yaml +++ b/examples/pypsa/generator_ramping.yaml @@ -38,7 +38,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/line.yaml b/examples/pypsa/line.yaml index c8a2779ee..8dc01b3f1 100644 --- a/examples/pypsa/line.yaml +++ b/examples/pypsa/line.yaml @@ -47,7 +47,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/link.yaml b/examples/pypsa/link.yaml index bd014646e..5f046f027 100644 --- a/examples/pypsa/link.yaml +++ b/examples/pypsa/link.yaml @@ -49,7 +49,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/link_commitment.yaml b/examples/pypsa/link_commitment.yaml index 280187f8c..229c79706 100644 --- a/examples/pypsa/link_commitment.yaml +++ b/examples/pypsa/link_commitment.yaml @@ -41,7 +41,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/link_ramping.yaml b/examples/pypsa/link_ramping.yaml index 2909f3a8b..704f8b6dd 100644 --- a/examples/pypsa/link_ramping.yaml +++ b/examples/pypsa/link_ramping.yaml @@ -38,7 +38,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/load.yaml b/examples/pypsa/load.yaml index 0a285ed29..4e2bb199e 100644 --- a/examples/pypsa/load.yaml +++ b/examples/pypsa/load.yaml @@ -18,7 +18,7 @@ dimensions: load: description: demands, each on one bus -maps: +mappings: load: bus: description: the bus a load sits on diff --git a/examples/pypsa/power_flow.yaml b/examples/pypsa/power_flow.yaml index cc777bf63..25d761d29 100644 --- a/examples/pypsa/power_flow.yaml +++ b/examples/pypsa/power_flow.yaml @@ -28,7 +28,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/process.yaml b/examples/pypsa/process.yaml index c017e1430..aec5dab8b 100644 --- a/examples/pypsa/process.yaml +++ b/examples/pypsa/process.yaml @@ -47,7 +47,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/process_commitment.yaml b/examples/pypsa/process_commitment.yaml index b3b49c3f4..0ba392108 100644 --- a/examples/pypsa/process_commitment.yaml +++ b/examples/pypsa/process_commitment.yaml @@ -41,7 +41,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/process_ramping.yaml b/examples/pypsa/process_ramping.yaml index 9c8eb02d9..b120a132b 100644 --- a/examples/pypsa/process_ramping.yaml +++ b/examples/pypsa/process_ramping.yaml @@ -38,7 +38,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/security.yaml b/examples/pypsa/security.yaml index ef45a9cb2..3fdab0dce 100644 --- a/examples/pypsa/security.yaml +++ b/examples/pypsa/security.yaml @@ -40,7 +40,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/settings.yaml b/examples/pypsa/settings.yaml index 175266bd5..d7f176b17 100644 --- a/examples/pypsa/settings.yaml +++ b/examples/pypsa/settings.yaml @@ -70,7 +70,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/storage_unit.yaml b/examples/pypsa/storage_unit.yaml index 0560ecce4..1bbbf2a20 100644 --- a/examples/pypsa/storage_unit.yaml +++ b/examples/pypsa/storage_unit.yaml @@ -40,7 +40,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/store.yaml b/examples/pypsa/store.yaml index 2b8d5ecfd..be5a10b95 100644 --- a/examples/pypsa/store.yaml +++ b/examples/pypsa/store.yaml @@ -41,7 +41,7 @@ dimensions: carrier: description: energy carriers, what a growth limit is set per -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/pypsa/transformer.yaml b/examples/pypsa/transformer.yaml index cb41cac55..1bd3c823a 100644 --- a/examples/pypsa/transformer.yaml +++ b/examples/pypsa/transformer.yaml @@ -39,7 +39,7 @@ dimensions: dtype: int ordered: true -maps: +mappings: snapshot: period: description: the investment period a snapshot falls in diff --git a/examples/sparse.yaml b/examples/sparse.yaml index 3bdd33b1d..cc2425236 100644 --- a/examples/sparse.yaml +++ b/examples/sparse.yaml @@ -22,7 +22,7 @@ relations: dims: [unit, period] missing: absent -maps: +mappings: connection: bus: { dim: bus, description: the bus a port feeds } diff --git a/examples/times/trade.yaml b/examples/times/trade.yaml index 677d21ca1..6a9e57051 100644 --- a/examples/times/trade.yaml +++ b/examples/times/trade.yaml @@ -13,7 +13,7 @@ dimensions: process: { description: a technology that carries trade } trade_link: { description: "one link from a region and commodity to another, a label the data invents" } -maps: +mappings: trade_link: # the region and commodity at each end of a link from_commodity: { dim: commodity } from_region: { dim: region } diff --git a/mkdocs.yml b/mkdocs.yml index dd6f992f3..2667a8e27 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,7 +40,7 @@ nav: - howto/index.md - Install mathspec: howto/installation.md - Check a spec without data: howto/check.md - - Choose between a dimension, a relation, a map and a parameter: howto/declare-a-column.md + - Choose between a dimension, a relation, a mapping and a parameter: howto/declare-a-column.md - State a rule that differs by case: howto/cases.md - Fix a quantity that is data in one model and a decision in another: howto/pin-a-variable.md - Print a spec as math: howto/print.md @@ -54,7 +54,7 @@ nav: - File shape: reference/language/file.md - Given, parameters, variables, objective and constraints: reference/language/parameters-variables-constraints.md - Dimensions: reference/language/dimensions.md - - Relations and maps: reference/language/relations.md + - Relations and mappings: reference/language/relations.md - Expressions: reference/language/expressions.md - Named expressions, conditions and macros: reference/language/named.md - Operators: reference/language/operators.md diff --git a/schema/mathspec.schema.json b/schema/mathspec.schema.json index 31392b32f..e7b68397c 100644 --- a/schema/mathspec.schema.json +++ b/schema/mathspec.schema.json @@ -167,7 +167,7 @@ }, "DimensionSpec": { "additionalProperties": false, - "description": "A declared dimension, the dtype its coordinates must be, and whether their order means anything.\n\nA dimension is an axis and nothing else: it declares that the axis exists\nand what its coordinates are typed as. Which coordinates there are is data,\nand arrives when the data is attached; a ``one_of`` only names the labels a\ncoordinate may have. The labels its members carry \u2014 a\ngenerator's bus, a snapshot's period \u2014 are its ``maps:``\n([`MapSpec`][]).", + "description": "A declared dimension, the dtype its coordinates must be, and whether their order means anything.\n\nA dimension is an axis and nothing else: it declares that the axis exists\nand what its coordinates are typed as. Which coordinates there are is data,\nand arrives when the data is attached; a ``one_of`` only names the labels a\ncoordinate may have. The labels its members carry \u2014 a\ngenerator's bus, a snapshot's period \u2014 are its ``mappings:``\n([`MappingSpec`][]).", "properties": { "description": { "anyOf": [ @@ -600,9 +600,9 @@ "title": "MacroSpec", "type": "object" }, - "MapSpec": { + "MappingSpec": { "additionalProperties": false, - "description": "A map: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names.\n\nWritten in YAML under its subject, with ``dim:`` always written::\n\n maps:\n unit:\n carrier: {dim: carrier, missing: absent}\n connection:\n bus: {dim: bus}\n line:\n bus0: {dim: bus}\n bus1: {dim: bus}\n\nThe map's name is a column of its subject's table, beside the subject's\nown columns. A call reads it as ``subject[map]``: ``sum(by=)`` totals\nalong it, ``at(by=)`` reads through it, ``within=`` works in each group\nof rows it sends to one label, and a condition compares it or tests that\na row has a label.", + "description": "A mapping: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names.\n\nWritten in YAML under its subject, with ``dim:`` always written::\n\n mappings:\n unit:\n carrier: {dim: carrier, missing: absent}\n connection:\n bus: {dim: bus}\n line:\n bus0: {dim: bus}\n bus1: {dim: bus}\n\nThe mapping's name is a column of its subject's table, beside the subject's\nown columns. A call reads it as ``subject[mapping]``: ``sum(by=)`` totals\nalong it, ``at(by=)`` reads through it, ``within=`` works in each group\nof rows it sends to one label, and a condition compares it or tests that\na row has a label.", "properties": { "description": { "anyOf": [ @@ -633,7 +633,7 @@ "required": [ "dim" ], - "title": "MapSpec", + "title": "MappingSpec", "type": "object" }, "ObjectiveSpec": { @@ -753,7 +753,7 @@ "anyOf": [ { "additionalProperties": false, - "description": "One link of a piecewise entry: an expression tied to the curve through a values parameter.\n\nWritten in YAML as ``[expression, values]`` or ``[expression, values,\nsign]``, and serialised back to exactly that form, so a round trip through\n[`Spec.to_yaml`][] reproduces the file.\n\nA link that names ``by: subject[map]`` reads the curve's weights\nthrough the relation, as ``at`` reads an array, and is written as a\nmapping. Its row is the entry's ``dims:`` with the dims the lookup reads\nreplaced by the key columns it arrives at, so one link emits a row per fine\ncoordinate and each reads the curve of the coarse coordinate it maps to.", + "description": "One link of a piecewise entry: an expression tied to the curve through a values parameter.\n\nWritten in YAML as ``[expression, values]`` or ``[expression, values,\nsign]``, and serialised back to exactly that form, so a round trip through\n[`Spec.to_yaml`][] reproduces the file.\n\nA link that names ``by: subject[mapping]`` reads the curve's weights\nthrough the relation, as ``at`` reads an array, and is written as a\nmapping. Its row is the entry's ``dims:`` with the dims the lookup reads\nreplaced by the key columns it arrives at, so one link emits a row per fine\ncoordinate and each reads the curve of the coarse coordinate it maps to.", "properties": { "by": { "anyOf": [ @@ -805,7 +805,7 @@ }, "PiecewiseSpec": { "additionalProperties": false, - "description": "Expressions tied to one breakpoint-indexed piecewise curve per coordinate of ``dims:``.\n\nMirrors ``linopy.Spec.add_piecewise_formulation``. ``links:`` maps a name\nto ``[expression, values_parameter]`` or ``[expression, values_parameter,\nsign]``: *expression* is any affine expression string over ``dims:``,\n*values_parameter* names a parameter carrying ``along`` and no dim the\nlink's row lacks, and *sign* bounds the link by the curve instead of\npinning it. The name is the link's row in the expansion, ``_``.\n\n``dims:`` alone decides how many curves the entry builds: one set of\nweights per coordinate of it. ``where:`` says which of those coordinates\nhave a curve, and how far each runs along ``along`` where it reads that\ndim too; ``activity:`` whether a curve that exists is switched on. A link\nthat walks a map builds a row per fine coordinate, each reading the\none curve its coarse coordinate has, so how many expressions a curve ties\nis data.", + "description": "Expressions tied to one breakpoint-indexed piecewise curve per coordinate of ``dims:``.\n\nMirrors ``linopy.Spec.add_piecewise_formulation``. ``links:`` maps a name\nto ``[expression, values_parameter]`` or ``[expression, values_parameter,\nsign]``: *expression* is any affine expression string over ``dims:``,\n*values_parameter* names a parameter carrying ``along`` and no dim the\nlink's row lacks, and *sign* bounds the link by the curve instead of\npinning it. The name is the link's row in the expansion, ``_``.\n\n``dims:`` alone decides how many curves the entry builds: one set of\nweights per coordinate of it. ``where:`` says which of those coordinates\nhave a curve, and how far each runs along ``along`` where it reads that\ndim too; ``activity:`` whether a curve that exists is switched on. A link\nthat walks a mapping builds a row per fine coordinate, each reading the\none curve its coarse coordinate has, so how many expressions a curve ties\nis data.", "properties": { "activity": { "anyOf": [ @@ -884,7 +884,7 @@ }, "RelationSpec": { "additionalProperties": false, - "description": "A named relation: the combinations of its dimensions that exist, one row each.\n\n``dims:`` is a list of dimensions, or a mapping of column name to\ndimension where two columns share one. A row is its own identity, so the\nrelation is a subset of the product of its dimensions::\n\n relations:\n connection: {dims: [unit, port], missing: absent}\n corridor: {dims: {from: bus, to: bus}}\n\nA relation is not a dimension. Its name stands in a condition, where it\nis true at the rows it lists, and before a\nbracket, where it reads one of its maps (``maps:``, [`MapSpec`][]). The\nrows are data, and arrive under the relation's name, one column per\ncolumn name, with a column per map beside them.", + "description": "A named relation: the combinations of its dimensions that exist, one row each.\n\n``dims:`` is a list of dimensions, or a mapping of column name to\ndimension where two columns share one. A row is its own identity, so the\nrelation is a subset of the product of its dimensions::\n\n relations:\n connection: {dims: [unit, port], missing: absent}\n corridor: {dims: {from: bus, to: bus}}\n\nA relation is not a dimension. Its name stands in a condition, where it\nis true at the rows it lists, and before a\nbracket, where it reads one of its mappings (``mappings:``, [`MappingSpec`][]). The\nrows are data, and arrive under the relation's name, one column per\ncolumn name, with a column per mapping beside them.", "properties": { "description": { "anyOf": [ @@ -1114,15 +1114,15 @@ "title": "Macros", "type": "object" }, - "maps": { + "mappings": { "additionalProperties": { "additionalProperties": { - "$ref": "#/$defs/MapSpec" + "$ref": "#/$defs/MappingSpec" }, "type": "object" }, "default": {}, - "title": "Maps", + "title": "Mappings", "type": "object" }, "objective": { diff --git a/src/mathspec/_advising.py b/src/mathspec/_advising.py index 036e683b9..546c42bfb 100644 --- a/src/mathspec/_advising.py +++ b/src/mathspec/_advising.py @@ -116,7 +116,7 @@ def _never_an_axis(program: Program) -> list[Advice]: 'never-an-axis', name, f"dimension '{name}' is never used: nothing is indexed by it, nothing " - f'sums into it, and no relation or map is over it. Remove it, or keep it ' + f'sums into it, and no relation or mapping is over it. Remove it, or keep it ' f'if the entries that use it are still to be written.', ) for name in program.dimensions diff --git a/src/mathspec/_composition.py b/src/mathspec/_composition.py index 6bf124783..2943dc828 100644 --- a/src/mathspec/_composition.py +++ b/src/mathspec/_composition.py @@ -108,7 +108,7 @@ from mathspec._yaml import read_spec from mathspec.errors import LanguageError, SchemaError, did_you_mean, schema_error from mathspec.program import variables_of -from mathspec.spec import GivenSpec, MapSpec, Spec +from mathspec.spec import GivenSpec, MappingSpec, Spec if TYPE_CHECKING: from collections.abc import Iterable @@ -116,22 +116,22 @@ from mathspec.program import Program from mathspec.spec import DimensionSpec -SHARED_SECTIONS = ('dimensions', 'relations', 'maps') +SHARED_SECTIONS = ('dimensions', 'relations', 'mappings') SETTINGS: dict[str, frozenset[str]] = { 'dimensions': frozenset({'ordered'}), 'relations': frozenset({'missing'}), - 'maps': frozenset({'missing'}), + 'mappings': frozenset({'missing'}), } -"""The fields of a dimension, a relation or a map, other than ``description``, that a patch may change. A patch may +"""The fields of a dimension, a relation or a mapping, other than ``description``, that a patch may change. A patch may change no other field of one that its base declares. """ -class _Maps(BaseModel): - """The ``maps:`` section one level flatter, each map under ``subject[map]``, so it folds as a section of entries.""" +class _Mappings(BaseModel): + """The ``mappings:`` section one level flatter, each mapping under ``subject[mapping]``, so it folds as a section of entries.""" - maps: Frozen[str, MapSpec] + mappings: Frozen[str, MappingSpec] OWNED_SECTIONS = tuple( @@ -174,7 +174,7 @@ def merge(fragments: Sequence[Source], description: str | None = None) -> Spec: Raises: LanguageError: A fragment does not load on its own; two fragments declare one name; two fragments say different things about one - dimension, relation, map or given entry; a fragment reads a name as + dimension, relation, mapping or given entry; a fragment reads a name as something other than what its sibling introduces, as another kind of thing, or over fewer dimensions than its body carries; a fragment adds a term to a variable, a parameter, a constraint or a @@ -195,10 +195,10 @@ def merge(fragments: Sequence[Source], description: str | None = None) -> Spec: if agreed := _agreed(read, section, _singular(section), 'give one of them a name of its own'): merged[section] = agreed flat: dict[str, dict[str, object]] = { - name: {'maps': _flat_maps(sections.get('maps'))} for name, sections in read.items() + name: {'mappings': _flat_mappings(sections.get('mappings'))} for name, sections in read.items() } - if agreed := _agreed(flat, 'maps', 'map', 'give one of them a name of its own', owner=_Maps): - merged['maps'] = _nested_maps(agreed) + if agreed := _agreed(flat, 'mappings', 'mapping', 'give one of them a name of its own', owner=_Mappings): + merged['mappings'] = _nested_mappings(agreed) asked = {name: spec.given.model_dump(exclude_unset=True) for name, spec in loaded.items()} readings = { kind: _agreed(asked, kind, label, 'read it over the same dims', owner=GivenSpec) @@ -742,17 +742,17 @@ def _entries(source: Source) -> dict[str, object]: return read_spec(source) -def _flat_maps(section: object) -> dict[str, object]: - """A ``maps:`` section keyed by ``subject[map]``, as [`_Maps`][] reads it.""" +def _flat_mappings(section: object) -> dict[str, object]: + """A ``mappings:`` section keyed by ``subject[mapping]``, as [`_Mappings`][] reads it.""" return { f'{subject}[{role}]': entry - for subject, maps in _mapping(section).items() - for role, entry in _mapping(maps).items() + for subject, mappings in _mapping(section).items() + for role, entry in _mapping(mappings).items() } -def _nested_maps(flat: Mapping[str, object]) -> dict[str, dict[str, object]]: - """*flat* as the ``maps:`` section a file writes, under each subject.""" +def _nested_mappings(flat: Mapping[str, object]) -> dict[str, dict[str, object]]: + """*flat* as the ``mappings:`` section a file writes, under each subject.""" nested: dict[str, dict[str, object]] = {} for key, entry in flat.items(): subject, _, role = key.partition('[') @@ -826,15 +826,15 @@ def _lay_over(base: dict[str, object], patch: dict[str, object], name: str) -> d for key, value in patch.items(): if key == 'given': laid[key] = _given(_mapping(laid.get(key)), _section(value, key, name), name) - elif key == 'maps': + elif key == 'mappings': section = _section(value, key, name) - if dropped := [subject for subject, maps in section.items() if maps is None]: + if dropped := [subject for subject, mappings in section.items() if mappings is None]: raise LanguageError( - f"patch '{name}' removes the maps of '{dropped[0]}', which a patch cannot change. Leave the " - f'subject out of the patch, and remove the entries written over its maps one at a time.' + f"patch '{name}' removes the mappings of '{dropped[0]}', which a patch cannot change. Leave the " + f'subject out of the patch, and remove the entries written over its mappings one at a time.' ) - shared = _shared(_flat_maps(laid.get(key)), _flat_maps(section), key, name, owner=_Maps) - laid[key] = _nested_maps(shared) + shared = _shared(_flat_mappings(laid.get(key)), _flat_mappings(section), key, name, owner=_Mappings) + laid[key] = _nested_mappings(shared) elif key in SHARED_SECTIONS: laid[key] = _shared(_mapping(laid.get(key)), _section(value, key, name), key, name) elif key in OWNED_SECTIONS: @@ -904,7 +904,7 @@ def _shared( *, owner: type[BaseModel] = Spec, ) -> dict[str, object]: - """One ``dimensions``, ``relations`` or ``maps`` section: a patch adds one or restates one, never changes or drops it. + """One ``dimensions``, ``relations`` or ``mappings`` section: a patch adds one or restates one, never changes or drops it. A patch may change the description and the [`SETTINGS`][] of one its base declares, and ``null`` puts back the default. A dimension may gain diff --git a/src/mathspec/_condition_parser.py b/src/mathspec/_condition_parser.py index 66d30e6dd..76f2c530c 100644 --- a/src/mathspec/_condition_parser.py +++ b/src/mathspec/_condition_parser.py @@ -54,7 +54,7 @@ @dataclass(frozen=True) class ColumnNode: - """``subject[map]``: the label at the frame's coordinates on a side of a comparison, and alone, that there is one.""" + """``subject[mapping]``: the label at the frame's coordinates on a side of a comparison, and alone, that there is one.""" relation: str column: str @@ -230,7 +230,7 @@ def _named_rewrite(text: str, loc: int) -> str | None: ``!=``, ``<`` and ``>`` are legal here, so only the tokens no condition admits are diagnosed. The grammar gives up at the bracket of - ``subject[a, b]``, since a comparison reads one map. + ``subject[a, b]``, since a comparison reads one mapping. """ rest = text[loc:].lstrip() if rest.startswith('&'): @@ -246,7 +246,7 @@ def _named_rewrite(text: str, loc: int) -> str | None: ): relation, columns = before.group(1), [c.strip() for c in listed.group(1).split(',')] each = ' AND '.join(f'{relation}[{column}] == …' for column in columns) - return f"a comparison reads one map of '{relation}'. Compare each map on its own: {each}." + return f"a comparison reads one mapping of '{relation}'. Compare each mapping on its own: {each}." return None diff --git a/src/mathspec/_condition_resolver.py b/src/mathspec/_condition_resolver.py index a133446fe..d5e25342b 100644 --- a/src/mathspec/_condition_resolver.py +++ b/src/mathspec/_condition_resolver.py @@ -112,7 +112,7 @@ def build(self, node: Condition | UnresolvedConditionNode) -> Condition | Unreso if isinstance(node, NameNode): return self._bare_name(node) if isinstance(node, ColumnNode): - return self._map_defined(node) + return self._mapping_defined(node) if isinstance(node, UnresolvedComparisonNode): return self._comparison(node) if isinstance(node, UnresolvedConditionCallNode): @@ -197,7 +197,7 @@ def _bare_name(self, node: NameNode) -> Condition | UnresolvedConditionNode: return node def _condition_call(self, node: UnresolvedConditionCallNode) -> Condition | UnresolvedConditionNode: - """``shift(, along=, offset=)`` or ``at(, by=subject[map])`` — the two operators that read a condition and answer one. + """``shift(, along=, offset=)`` or ``at(, by=subject[mapping])`` — the two operators that read a condition and answer one. ``count`` answers a number, so it stands on a comparison's side and [`_count`][] reads it there. Anything else naming a condition is @@ -253,7 +253,7 @@ def _condition_call(self, node: UnresolvedConditionCallNode) -> Condition | Unre return TranslatedCondition(mask, along.name, int(offset.value), mask.dims) def _joined(self, node: UnresolvedConditionCallNode, mask: Mask) -> Condition | UnresolvedConditionNode: - """``at(, by=subject[map])`` — the condition read through a relation, as ``at`` reads an array. + """``at(, by=subject[mapping])`` — the condition read through a relation, as ``at`` reads an array. The columns are read by the rules an expression's ``at`` is, so the one refusal a file meets for a bad read is the same in a ``where:`` and in @@ -430,13 +430,13 @@ def _expression_comparison(self, node: UnresolvedComparisonNode) -> ExpressionCo def _position( self, call: FunctionCallNode, node: UnresolvedComparisonNode ) -> DimensionPosition | UnresolvedComparisonNode: - """``position(dim[, within=subject[map]]) i``: the name a dimension, the relation keyed over it.""" + """``position(dim[, within=subject[mapping]]) i``: the name a dimension, the relation keyed over it.""" ns, context = self.ns, self.context shape = _position_shape(call) if shape is None: self.errors.append( f'{context}: this position() call is not of the form ' - f'position([, within=[]]). Write it in that form.' + f'position([, within=[]]). Write it in that form.' ) return node dimension, within = shape @@ -493,7 +493,7 @@ def _plain_comparison(self, node: UnresolvedComparisonNode, plain: _Plain) -> Co self.errors.append(ns.unknown(left_name, context, allow_dims=True)) return node if left_column and kind != 'relation': - self.errors.append(_no_maps(context, plain.name, left_name, ns)) + self.errors.append(_no_mappings(context, plain.name, left_name, ns)) return node column = None dtype: DeclaredDtype | None = None @@ -543,47 +543,47 @@ def _plain_comparison(self, node: UnresolvedComparisonNode, plain: _Plain) -> Co return node def _relation_column(self, name: str, column: str | None, spelling: str, op: ComparisonOperator) -> str | None: - """The map a where-comparison through subject *name* reads, or the refusal. + """The mapping a where-comparison through subject *name* reads, or the refusal. - A comparison reads one label per coordinate, so it names one map of the + A comparison reads one label per coordinate, so it names one mapping of the subject in brackets, whatever the subject has. """ ns, context = self.ns, self.context shape = ns.relations[name] if not shape.values: self.errors.append( - f"{context}: '{spelling}' compares the relation '{name}', which has no map, so its rows hold no " - f"label. Test the bare name '{name}' for whether a row exists, or declare a map under maps: {name}:." + f"{context}: '{spelling}' compares the relation '{name}', which has no mapping, so its rows hold no " + f"label. Test the bare name '{name}' for whether a row exists, or declare a mapping under mappings: {name}:." ) return None if column is None: self.errors.append( f"{context}: '{spelling}' compares the relation '{name}' itself, and a comparison reads a label. " - f'Name one of its maps: {name}[{shape.values[0]}].' + f'Name one of its mappings: {name}[{shape.values[0]}].' ) return None if column in shape.key: self.errors.append( f"{context}: '{spelling}': '{column}' is a column of '{name}' itself. Compare the coordinate, " - f'{shape.dim(column)} {op} ..., or a map.' + f'{shape.dim(column)} {op} ..., or a mapping.' ) return None if column not in shape.values: self.errors.append( - f"{context}: '{spelling}': '{column}' is no map of '{name}'. " - f'{did_you_mean(column, shape.values, label="Maps")}' + f"{context}: '{spelling}': '{column}' is no mapping of '{name}'. " + f'{did_you_mean(column, shape.values, label="Mappings")}' ) return None return column - def _map_defined(self, node: ColumnNode) -> Condition | UnresolvedConditionNode: - """``subject[map]`` alone: true where the subject's row at the frame's coordinates has a label in the map.""" + def _mapping_defined(self, node: ColumnNode) -> Condition | UnresolvedConditionNode: + """``subject[mapping]`` alone: true where the subject's row at the frame's coordinates has a label in the mapping.""" ns, context = self.ns, self.context if _kind(ns, node.relation, node.column) != 'relation': if ns.kind(node.relation) is None: self.errors.append(ns.unknown(node.relation, context, allow_dims=True)) else: - self.errors.append(_no_maps(context, node.shown, node.relation, ns)) + self.errors.append(_no_mappings(context, node.shown, node.relation, ns)) return node shape = ns.relations[node.relation] if node.column in shape.key: @@ -594,8 +594,8 @@ def _map_defined(self, node: ColumnNode) -> Condition | UnresolvedConditionNode: return node if node.column not in shape.values: self.errors.append( - f"{context}: '{node.shown}': '{node.column}' is no map of '{node.relation}'. " - f'{did_you_mean(node.column, shape.values, label="Maps")}' + f"{context}: '{node.shown}': '{node.column}' is no mapping of '{node.relation}'. " + f'{did_you_mean(node.column, shape.values, label="Mappings")}' ) return node return RelationDefined(node.relation, tuple(sorted(shape.dim(k) for k in shape.key)), node.column) @@ -681,19 +681,19 @@ def _declared_as(ns: Namespace, name: str) -> str: def _kind(ns: Namespace, name: str, column: str) -> str | None: - """What *name* is declared as, read as a subject with maps where *column* is written in brackets after it. + """What *name* is declared as, read as a subject with mappings where *column* is written in brackets after it. - A dimension with maps shares its name with its table, so the brackets are + A dimension with mappings shares its name with its table, so the brackets are what make it a subject. """ return 'relation' if column and name in ns.relations else ns.kind(name) -def _no_maps(context: str, spelling: str, name: str, ns: Namespace) -> str: - """The refusal for ``name[map]`` where *name* has no maps.""" +def _no_mappings(context: str, spelling: str, name: str, ns: Namespace) -> str: + """The refusal for ``name[mapping]`` where *name* has no mappings.""" return ( - f"{context}: '{spelling}' reads a map of '{name}', which is {_declared_as(ns, name)} with no maps. " - f'Declare it under maps: {name}:, or read a subject that has it.' + f"{context}: '{spelling}' reads a mapping of '{name}', which is {_declared_as(ns, name)} with no mappings. " + f'Declare it under mappings: {name}:, or read a subject that has it.' ) @@ -716,7 +716,7 @@ def _side_name_or_none(side: ArithmeticNode | ColumnNode | KeywordNode) -> str | def _side_name(side: ArithmeticNode | ColumnNode) -> str | None: - """The name a side of a where-comparison spells — bare or ``subject[map]`` — or ``None`` where it is arithmetic.""" + """The name a side of a where-comparison spells — bare or ``subject[mapping]`` — or ``None`` where it is arithmetic.""" if isinstance(side, NameNode): return side.name if isinstance(side, ColumnNode): @@ -725,7 +725,7 @@ def _side_name(side: ArithmeticNode | ColumnNode) -> str | None: def _split_column(name: str) -> tuple[str, str]: - """``subject[map]`` as its two names, and a bare name with an empty column: the one reader of a side's spelling.""" + """``subject[mapping]`` as its two names, and a bare name with an empty column: the one reader of a side's spelling.""" relation, _, column = name.partition('[') return relation, column.removesuffix(']') @@ -788,8 +788,8 @@ def _not_arithmetic(context: str, side: ColumnNode | KeywordNode) -> str: """Why a relation column or a quoted label may not stand on a side of a comparison of expressions.""" if isinstance(side, ColumnNode): return ( - f"{context}: '{side.shown}' is a map in arithmetic. Compare it alone against a literal or another " - f'map, or carry the value in a parameter.' + f"{context}: '{side.shown}' is a mapping in arithmetic. Compare it alone against a literal or another " + f'mapping, or carry the value in a parameter.' ) return ( f"{context}: '{side.value}' is a quoted label, which is compared against one name. Put the name alone on " @@ -813,7 +813,7 @@ def _declared_rhs_error(context: str, node: _Plain, value: str, kind: str, *, gi if kind == 'relation': return ( f'{context}: {comparison} compares {node.name!r} against {value!r}, which is no label. Compare ' - f'against a literal, or compare two maps of subjects over the same dimensions: subject[map].' + f'against a literal, or compare two mappings of subjects over the same dimensions: subject[mapping].' ) return ( f'{context}: {comparison} compares against dimension {value!r}, and two dimensions cannot be ' @@ -837,8 +837,8 @@ def _relation_pair_error(context: str, node: _Plain, other: str, ns: Namespace, left_keys, right_keys = {ls.dim(k) for k in ls.key}, {rs.dim(k) for k in rs.key} if left_keys != right_keys: return ( - f'{context}: {comparison} compares maps of subjects over different dimensions ' - f"('{left_name}' over {sorted(left_keys)}, '{right_name}' over {sorted(right_keys)}). Compare maps " + f'{context}: {comparison} compares mappings of subjects over different dimensions ' + f"('{left_name}' over {sorted(left_keys)}, '{right_name}' over {sorted(right_keys)}). Compare mappings " f'of subjects over the same dimensions.' ) if ls.dim(left) != rs.dim(right): diff --git a/src/mathspec/_dimensions.py b/src/mathspec/_dimensions.py index 84eb13c20..379de57b5 100644 --- a/src/mathspec/_dimensions.py +++ b/src/mathspec/_dimensions.py @@ -116,7 +116,7 @@ def join_dims(columns: JoinColumns, inner: frozenset[str], context: str, operand if clash := sorted((added & inner) - dropped): raise DimensionError( f'{context}: {call} groups by {clash}, which the expression already carries.\n' - f'Move the factor carrying {clash} outside the operator, or group by a map into another dimension.' + f'Move the factor carrying {clash} outside the operator, or group by a mapping into another dimension.' ) _check_joined(call, columns, inner, context) return joined(columns, inner) @@ -195,7 +195,7 @@ def _check_named_amount( raise DimensionError( f"{context}: {verb}({kwarg}={amount}): '{amount}' varies over {stray}, which the expression does " f"not carry (dims {sorted(inner)}). Declare '{amount}' over dims the expression carries, or group " - f'by a map into one of {stray}.' + f'by a mapping into one of {stray}.' ) @@ -349,7 +349,7 @@ def _check_condition_dims( case RelationDefined(column=None): leaf = f"where-relation '{atom.name}'" case RelationComparison() | RelationPairComparison() | RelationDefined(): - leaf = f"where-map '{atom.name}[{atom.column}]'" + leaf = f"where-mapping '{atom.name}[{atom.column}]'" case ExpressionComparison(): leaf = 'a comparison of expressions' case CountComparison(): diff --git a/src/mathspec/_exclusivity.py b/src/mathspec/_exclusivity.py index 8dc194e70..5fb248ced 100644 --- a/src/mathspec/_exclusivity.py +++ b/src/mathspec/_exclusivity.py @@ -205,8 +205,8 @@ def cells(self) -> Iterator[dict[Subject, Cell]]: def witness(self, cell: dict[Subject, Cell]) -> str: """*cell* in words. A column names a value only where its row and its labels exist, and a value says the row exists. - A comparison of two maps that is shown says both have a label, so a - map no literal names is not listed beside it. + A comparison of two mappings that is shown says both have a label, so a + mapping no literal names is not listed beside it. """ shown = [ subject @@ -224,7 +224,7 @@ def witness(self, cell: dict[Subject, Cell]) -> str: ) def _unnamed(self, subject: Subject) -> bool: - """Whether *subject* is a map no literal names, so its cells are only "a label" and "none".""" + """Whether *subject* is a mapping no literal names, so its cells are only "a label" and "none".""" return self.domains[subject] == [Special.OTHER, Special.NULL] @@ -302,7 +302,7 @@ def _observe(node: TypedCondition, subject: Subject, values: set[_Literal]) -> N if node.op not in ('==', '!='): msg = ( f'{subject} uses {node.op!r}, and this analysis does not decide an inequality between two ' - 'maps. Compare them with == or !=, or precompute the comparison as a boolean ' + 'mappings. Compare them with == or !=, or precompute the comparison as a boolean ' 'parameter and test that' ) raise Undecidable(msg) @@ -322,14 +322,14 @@ def _rows_read(node: TypedCondition) -> tuple[str, ...]: def _labels_read(node: TypedCondition) -> tuple[Subject, ...]: - """The maps whose label *node* compares, and so is false without, beyond the label of its own subject.""" + """The mappings whose label *node* compares, and so is false without, beyond the label of its own subject.""" if isinstance(node, RelationPairComparison): return (Subject('relation', node.name, node.column), Subject('relation', node.other, node.other_column)) return () def _pair_labels(subject: Subject) -> tuple[Subject, ...]: - """The two labels a comparison of two maps compares, so a cell without either gives it no value.""" + """The two labels a comparison of two mappings compares, so a cell without either gives it no value.""" if subject.kind != 'relation_pair' or subject.qualifier is None: return () (column, other_column), other = subject.group, subject.qualifier @@ -413,7 +413,7 @@ def _cells_for(subject: Subject, values: set[_Literal], dtypes: Mapping[str, Dec def _absence_cells(subject: Subject, *, numeric: bool) -> list[Cell]: """The regions where *subject* has no ordinary value. - A dimension's coordinates have no null. A map may give a row no label, so + A dimension's coordinates have no null. A mapping may give a row no label, so it has one, beside the row itself, which is a subject of its own. ``defined`` excludes an infinity, so a magnitude needs a region where every comparison still reads normally and the bare name is false. @@ -526,7 +526,7 @@ def _rank_cells(subject: Subject, positions_seen: set[int]) -> list[Cell]: def _clause(subject: Subject, value: Cell, *, named: bool = True) -> str: """*subject* in one cell, in words. A null cell says the data has no row or label, never a ``missing:`` reading's name. - A map compared against no literal has only the cells "a label" and "none", + A mapping compared against no literal has only the cells "a label" and "none", so where *named* is false its label is not "anything else" but simply there. """ label = subject.kind == 'relation' and subject.qualifier is not None diff --git a/src/mathspec/_expression_resolver.py b/src/mathspec/_expression_resolver.py index cd4e9a8e6..5ba84f8eb 100644 --- a/src/mathspec/_expression_resolver.py +++ b/src/mathspec/_expression_resolver.py @@ -146,8 +146,8 @@ def arith(self, node: ArithmeticNode) -> Expression | None: return None if isinstance(node, ColumnsNode): self.errors.append( - f'{self.context}: {node} names a map of a subject, which is allowed only as an operator ' - f'argument, such as at(x, by={node}). A map is not a value.' + f'{self.context}: {node} names a mapping of a subject, which is allowed only as an operator ' + f'argument, such as at(x, by={node}). A mapping is not a value.' ) return None assert_never(node) @@ -314,7 +314,7 @@ def _checked[N: Sum | Join | Translate | WindowSum](self, node: N) -> N | None: return node def _at(self, operand: Expression, columns: ColumnsNode) -> Expression | None: - """``at(x, by=subject[map])``: *operand* read at the value of *columns* each row of the relation holds.""" + """``at(x, by=subject[mapping])``: *operand* read at the value of *columns* each row of the relation holds.""" join = self.lookup(columns, frozenset(operand.dims)) return None if join is None else self._joined(operand, join) @@ -497,7 +497,7 @@ def _over(self, value: ArithmeticNode, operator: str, *, relation: bool) -> tupl return None if isinstance(value, ColumnsNode): self.errors.append( - f'{self.context}: {operator}(over={value}) names maps of a subject, and over= takes bare names. Write ' + f'{self.context}: {operator}(over={value}) names mappings of a subject, and over= takes bare names. Write ' f'over={shown(value.columns)}. Beside by={value.relation}[...], a name in over= is a column of ' f"'{value.relation}', or a dimension." ) @@ -540,7 +540,7 @@ def columns_ref(self, value: ArithmeticNode, operator: str, key: str) -> Columns return None shape = self.ns.relations[value.relation] if unknown := [c for c in value.columns if c not in shape.roles and c not in self.formals]: - word, named = ('map', shape.values) if value.relation in self.ns.dimensions else ('column', shape.roles) + word, named = ('mapping', shape.values) if value.relation in self.ns.dimensions else ('column', shape.roles) self.errors.append( f'{self.context}: {operator}({key}={value}) names {unknown}, which is no {word} of ' f"'{value.relation}'. Name one of its {word}s, {list(named)}." @@ -558,7 +558,7 @@ def _not_columns(self, value: ArithmeticNode, operator: str, key: str) -> str: ns, context = self.ns, self.context if isinstance(value, NameNode) and value.name in ns.relations: shape = ns.relations[value.name] - word, named = ('map', shape.values) if value.name in ns.dimensions else ('column', shape.roles) + word, named = ('mapping', shape.values) if value.name in ns.dimensions else ('column', shape.roles) return ( f'{context}: {operator}({key}={value.name}) names the subject and none of its {word}s. Write ' f"{key}={value.name}[<{word}>], with a {word} of '{value.name}': {list(named)}." @@ -567,14 +567,12 @@ def _not_columns(self, value: ArithmeticNode, operator: str, key: str) -> str: over_here = [ f'{n}[{r}]' for n, shape in ns.relations.items() for r, dim in shape.columns if dim == value.name ] - hint = f'Columns over {value.name!r}: {over_here}' if over_here else f'No map refers to {value.name!r}.' + hint = f'Columns over {value.name!r}: {over_here}' if over_here else f'No mapping refers to {value.name!r}.' return ( - f"{context}: {operator}({key}={value.name}): '{value.name}' is a dimension with no maps, and {key}= " - f'takes columns of a subject, written subject[map]. {hint}' + f"{context}: {operator}({key}={value.name}): '{value.name}' is a dimension with no mappings, and {key}= " + f'takes columns of a subject, written subject[mapping]. {hint}' ) - return ( - f'{context}: {operator}({key}=...) takes columns of one subject. Write subject[map] or subject[map, ...].' - ) + return f'{context}: {operator}({key}=...) takes columns of one subject. Write subject[mapping] or subject[mapping, ...].' def _grouping(self, columns: ColumnsNode, over: tuple[str, ...]) -> tuple[JoinColumns, tuple[str, ...]] | None: """How ``sum(x, over=..., by=subject[...])`` joins the relation, and the dims it sums away with no column. @@ -611,7 +609,7 @@ def _grouping(self, columns: ColumnsNode, over: tuple[str, ...]) -> tuple[JoinCo self.errors.append( f'{self.context}: {call}: the columns this sum groups by, {list(join.grouped)}, hold the whole key ' f'{list(shape.key)}, so every group is one row and the sum adds nothing. Write ' - f'{_lookup_rewrite(name, from_roles, plain)}, or group by a map.' + f'{_lookup_rewrite(name, from_roles, plain)}, or group by a mapping.' ) return None return join, plain @@ -621,22 +619,22 @@ def lookup(self, columns: ColumnsNode, inner: frozenset[str]) -> JoinColumns | N The operand is joined on the named columns, and on each other key column over a dim it carries that the named columns do not already - match. The rest of the key arrives. So a map into its own dimension + match. The rest of the key arrives. So a mapping into its own dimension joins on the value column alone, and the key column arrives. """ name, call = columns.relation, f'at(by={columns})' shape = self.ns.relations[name] if not shape.values: self.errors.append( - f"{self.context}: {call}: '{name}' has no map for at() to read. Sum through it instead, or declare " - f'a map under maps: {name}:.' + f"{self.context}: {call}: '{name}' has no mapping for at() to read. Sum through it instead, or declare " + f'a mapping under mappings: {name}:.' ) return None if keyed := [r for r in columns.columns if r in shape.key]: through = '' if name in self.ns.dimensions else ', or sum through the column' self.errors.append( - f"{self.context}: {call} names {keyed}, a column of '{name}' itself. A lookup reads maps at the " - f'row. Name one of its maps, {list(shape.values)}{through}.' + f"{self.context}: {call} names {keyed}, a column of '{name}' itself. A lookup reads mappings at the " + f'row. Name one of its mappings, {list(shape.values)}{through}.' ) return None matched = inner - {shape.dim(r) for r in columns.columns} @@ -677,8 +675,8 @@ def partition(self, columns: ColumnsNode, operator: str, along_dim: str) -> Part call = f'{operator}(within={columns})' if not shape.values: self.errors.append( - f"{context}: {call}: '{name}' has no map, so it makes no groups. Declare the group as a map of " - f'the dimension {operator} steps along, under maps: {along_dim}:.' + f"{context}: {call}: '{name}' has no mapping, so it makes no groups. Declare the group as a mapping of " + f'the dimension {operator} steps along, under mappings: {along_dim}:.' ) return None over_keys = [r for r in shape.key if shape.dim(r) == along_dim] @@ -690,7 +688,7 @@ def partition(self, columns: ColumnsNode, operator: str, along_dim: str) -> Part return None if keyed := [r for r in within_roles if r in shape.key]: self.errors.append( - f"{context}: {call}: within= names {keyed}, a column of '{name}' itself. Name one of its maps, " + f"{context}: {call}: within= names {keyed}, a column of '{name}' itself. Name one of its mappings, " f'{list(shape.values)}.' ) return None @@ -705,18 +703,18 @@ def not_a_relation(self, name: str, operator: str, key: str) -> str | None: return None if name in ns.dimensions: return ( - f"{context}: {operator}({key}={name}[...]): '{name}' is a dimension with no maps. Declare the map " - f'under maps: {name}:, or read a subject that has it: {key}=[].' + f"{context}: {operator}({key}={name}[...]): '{name}' is a dimension with no mappings. Declare the mapping " + f'under mappings: {name}:, or read a subject that has it: {key}=[].' ) kinds = ( - 'a relation, a dimension with maps or a formal argument of this macro' + 'a relation, a dimension with mappings or a formal argument of this macro' if self.formals - else 'a relation or a dimension with maps' + else 'a relation or a dimension with mappings' ) return ( f'{context}: {operator}({key}={name}[...]): {name!r} is not {kinds}. ' f'{did_you_mean(name, ns.relations, label="Subjects")}\n' - f'Write {key}=[], and declare a missing map under maps:.' + f'Write {key}=[], and declare a missing mapping under mappings:.' ) diff --git a/src/mathspec/_lowering.py b/src/mathspec/_lowering.py index 3bb1cd912..2a787a2d5 100644 --- a/src/mathspec/_lowering.py +++ b/src/mathspec/_lowering.py @@ -400,7 +400,7 @@ def _parameter_masks(spec: Spec, ns: Namespace, errors: list[str]) -> dict[str, continue errors.extend( f"{context}: its `where:` contains variable '{v}', and a tool evaluates the `where:` of a parameter " - f'from the data alone, before any variable has a value. Test a parameter or a map instead.' + f'from the data alone, before any variable has a value. Test a parameter or a mapping instead.' for v in sorted(mask.names_read & {*spec.variables, *spec.given.variables}) ) errors.extend( diff --git a/src/mathspec/_operators.py b/src/mathspec/_operators.py index 8a410c913..8b3f2c5a1 100644 --- a/src/mathspec/_operators.py +++ b/src/mathspec/_operators.py @@ -68,18 +68,18 @@ def kind_of(self, kwarg: str) -> Literal['dimension', 'columns', 'edge', 'value' BUILTINS: dict[str, Builtin] = { 'sum': Builtin( - 'sum(), sum(, over=) or sum(, over=, by=[])', + 'sum(), sum(, over=) or sum(, over=, by=[])', dimension_kwargs=('over',), column_kwargs=('by',), optional_kwargs=('over', 'by'), with_columns=('over',), ), 'at': Builtin( - 'at(, by=[])', + 'at(, by=[])', column_kwargs=('by',), ), 'sum_back': Builtin( - "sum_back(, along=, window=[, edge='wrap'][, within=[]])", + "sum_back(, along=, window=[, edge='wrap'][, within=[]])", dimension_kwargs=('along',), column_kwargs=('within',), required_value_kwargs=('window',), @@ -87,7 +87,7 @@ def kind_of(self, kwarg: str) -> Literal['dimension', 'columns', 'edge', 'value' optional_kwargs=('within',), ), 'shift': Builtin( - "shift(, along=, offset=[, edge='wrap'|][, within=[]])", + "shift(, along=, offset=[, edge='wrap'|][, within=[]])", dimension_kwargs=('along',), column_kwargs=('within',), required_value_kwargs=('offset',), diff --git a/src/mathspec/_piecewise.py b/src/mathspec/_piecewise.py index 5b3ac8602..6be1a2148 100644 --- a/src/mathspec/_piecewise.py +++ b/src/mathspec/_piecewise.py @@ -249,12 +249,12 @@ def _walked(text: str, dims: Iterable[str], link: Link | None) -> str: def _on_walk(text: str | None, link: Link) -> str | None: - """*text* as *link*'s row reads it, admitted only at the rows whose map gives the walk a label. + """*text* as *link*'s row reads it, admitted only at the rows whose mapping gives the walk a label. - A map or a relation declared ``missing: absent`` may give a row no label, + A mapping or a relation declared ``missing: absent`` may give a row no label, and there the walked read of the curve is absent, so the row would pin the link's expression to an empty sum, or to the first breakpoint under - ``incremental``. A where read through the map is already false there, and + ``incremental``. A where read through the mapping is already false there, and under ``missing: refused`` every row has a label. """ if link.walk is None or link.reads or link.walk.relation.missing_at(link.walk.dropped) == 'refused': @@ -263,7 +263,7 @@ def _on_walk(text: str | None, link: Link) -> str | None: def labelled(walk: JoinColumns) -> str: - """The condition that the walk finds a label, ``subject[map]`` for each map it reads.""" + """The condition that the walk finds a label, ``subject[mapping]`` for each mapping it reads.""" return ' AND '.join(f'{walk.name}[{role}]' for role in walk.dropped) @@ -444,7 +444,7 @@ def leaves_ungated(gate: VariableSpec | Variable, walk: JoinColumns | None = Non A masked gate is absent off its mask, and there the curve sums to 1; ``missing: 0`` reads the gate as 0 there instead, which one row states. - A map or a relation declared ``missing: absent`` may give a curve no + A mapping or a relation declared ``missing: absent`` may give a curve no label, and there the read is absent whatever the gate's ``missing:``. Under ``missing: refused`` every curve has one. """ @@ -478,8 +478,8 @@ def gate_text(text: str, gate: VariableSpec | Variable, read: Expression) -> tup *text* is the ``activity:`` the file wrote, and *read* the expression it resolved to. Where [`leaves_ungated`][] says a curve can run ungated, the where is the read itself, which exists where the gate and the row of - its map both do. Under ``missing: 0`` a walked gate reads 0 off its - mask, so the map alone decides, and its label is the where. + its mapping both do. Under ``missing: 0`` a walked gate reads 0 off its + mask, so the mapping alone decides, and its label is the where. """ walk = read.columns if isinstance(read, Join) else None if not leaves_ungated(gate, walk): @@ -509,7 +509,7 @@ def resolve_links(name: str, pw: PiecewiseSpec, ns: Namespace, errors: list[str] def resolve_walks(name: str, pw: PiecewiseSpec, ns: Namespace, errors: list[str]) -> dict[str, JoinColumns] | None: """Entry *name*'s walks by link key, each read as ``at(..., by=)`` reads its relation, or ``None`` once one failed. - The expansion writes a walked row as ``at(_lam, by=[])``, + The expansion writes a walked row as ``at(_lam, by=[])``, so a walk is held to every rule that call is held to, and refused here on the link the file wrote. Each refusal is appended to *errors*. """ @@ -537,8 +537,8 @@ def walked_columns(by: str, resolver: ExpressionResolver) -> ColumnsNode | None: """ if (columns := _columns_of(by)) is None: resolver.errors.append( - f'{resolver.context}: by: {by!r} is not a subject with its maps in brackets. Write ' - f'by: [], as in at(..., by=).' + f'{resolver.context}: by: {by!r} is not a subject with its mappings in brackets. Write ' + f'by: [], as in at(..., by=).' ) return None return resolver.columns_ref(columns, 'at', 'by') @@ -676,13 +676,13 @@ def _walk_fits(ctx: str, entry: PiecewiseSpec, walk: JoinColumns) -> None: ) if framed := sorted(added & {*entry.dims, entry.along}): raise DimensionError( - f'{ctx}: by: {walk.name} adds {framed}, which the curve is already over. Walk through a map ' + f'{ctx}: by: {walk.name} adds {framed}, which the curve is already over. Walk through a mapping ' f'whose subject is over a dimension outside dims: and along:.' ) if entry.along in walk.joined_dims: raise DimensionError( f"{ctx}: by: {walk.name} is keyed on '{entry.along}', the breakpoint dimension, so a row of the " - f'link could take each breakpoint from a different curve. Walk through a map whose subject leaves ' + f'link could take each breakpoint from a different curve. Walk through a mapping whose subject leaves ' f"out '{entry.along}'." ) @@ -735,14 +735,14 @@ def _link_fits(ctx: str, key: str, entry: PiecewiseSpec, found: frozenset[str], raise DimensionError( f"{ctx}: link '{key}' expression is over {stray}, and its row {list(own)} is not, so every " f'coordinate of {stray} would share one curve. Add {stray} to dims:, sum it out, or look the curve ' - f'up through a map with by: [].' + f'up through a mapping with by: [].' ) if added := sorted(set(own) - found - set(entry.dims)): by = entry.links[key].by raise DimensionError( f"{ctx}: link '{key}' expression is not over {added}, which by: {by} adds to its row {list(own)}, " f'so one value of the expression would lie on every curve along {added} at once. Write an ' - f'expression over {added}, or walk through a map whose subject leaves out {added}.' + f'expression over {added}, or walk through a mapping whose subject leaves out {added}.' ) if missing := sorted(set(own) - found): raise DimensionError( @@ -787,7 +787,7 @@ def _where_fits(ctx: str, entry: PiecewiseSpec, where: Mask | None, walks: dict[ for key, walk in walks.items(): if into := [d for d in stray if d in walk.added_dims]: raise DimensionError( - f"{ctx}: where {entry.where!r} tests {into}, which link '{key}' adds through the map it walks. A " + f"{ctx}: where {entry.where!r} tests {into}, which link '{key}' adds through the mapping it walks. A " f'where: sets which curves exist, one per coordinate of dims: {list(entry.dims)}, and only the rows of ' f'the link are over {into}. Test {list(entry.dims)} in the where:, or declare a where: over {into} on ' f'the variable of the link, so that its rows are absent.' @@ -811,14 +811,14 @@ def _gate_fits(ctx: str, entry: PiecewiseSpec, gate: Gate, walks: dict[str, Join listable = not unlistable & set(stray) if entry.activity != gate.variable: found = f'over {stray} after the lookup' - rewrite = 'Look it up through a map that leaves it over dims:' + ( + rewrite = 'Look it up through a mapping that leaves it over dims:' + ( f', or add {stray} to dims:.' if listable else '.' ) else: found = f'over {stray}' rewrite = (f'Add {stray} to dims:, or gate' if listable else 'Gate') + ( - f' with a variable over dims:, or read the gate through a map with ' - f'activity: at({gate.variable}, by=[]).' + f' with a variable over dims:, or read the gate through a mapping with ' + f'activity: at({gate.variable}, by=[]).' ) raise DimensionError( f"{ctx}: activity '{gate.variable}' is {found}, which is not in dims: {list(entry.dims)}. The gate switches " diff --git a/src/mathspec/_renaming.py b/src/mathspec/_renaming.py index df2136d9b..5b610d0d0 100644 --- a/src/mathspec/_renaming.py +++ b/src/mathspec/_renaming.py @@ -38,12 +38,12 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str """*source* with each name that *names* changes replaced by its new name. A name is replaced everywhere it occurs in the spec: as the key of its - entry, in ``dims:``, under ``maps:``, in ``adds_to:``, under ``given:``, + entry, in ``dims:``, under ``mappings:``, in ``adds_to:``, under ``given:``, and in the text of every expression, ``where:``, bound, case and assumption. Only whole names are replaced, and the text around each name - is unchanged. A map or a relation column named after its dimension is - renamed with the dimension, because an expression reads a map as - ``subject[map]``. + is unchanged. A mapping or a relation column named after its dimension is + renamed with the dimension, because an expression reads a mapping as + ``subject[mapping]``. Prose and labels stay as written: a description, the labels of ``one_of:``, the name of a case or of a piecewise link, and the arguments @@ -74,7 +74,7 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str name of an entry that is not renamed, or an argument of a macro whose template uses the old name. Also when two names get the same new name, or when an old or a new - name is a map or a relation column that is not named after its + name is a mapping or a relation column that is not named after its dimension. FileNotFoundError: A ``str`` with no newline that names no file. TypeError: *names* is neither a mapping nor a function. @@ -95,10 +95,10 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str def _declared(spec: Spec) -> dict[str, str]: """Every name that *spec* declares or lists under ``given:``, with the kind of its entry for a refusal. - ``maps:`` declares no name of its own: its keys are dimensions and relations. + ``mappings:`` declares no name of its own: its keys are dimensions and relations. """ declared = {name: GIVEN_KINDS[kind] for kind in GIVEN_KINDS for name in getattr(spec.given, kind)} - for section in (s for s in (*SHARED_SECTIONS, *OWNED_SECTIONS) if s != 'maps'): + for section in (s for s in (*SHARED_SECTIONS, *OWNED_SECTIONS) if s != 'mappings'): declared |= dict.fromkeys(getattr(spec, section), _singular(section)) return declared @@ -108,7 +108,7 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: A token in text is renamed wherever it has the spelling, so a new name that is the argument of a macro whose template uses the old name, or a name that - is a map or a relation column named after something else, would change an + is a mapping or a relation column named after something else, would change an expression without a refusal. """ for old in names: @@ -125,9 +125,9 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: for column, dimension in entry.pairs if column != dimension } | { - name: f"a map of '{subject}'" - for subject, maps in spec.maps.items() - for name, entry in maps.items() + name: f"a mapping of '{subject}'" + for subject, mappings in spec.mappings.items() + for name, entry in mappings.items() if name != entry.dim } for old, new in changed.items(): @@ -169,8 +169,8 @@ def _renamed(cls: type[BaseModel], entry: object, names: Mapping[str, str]) -> o with prose or labels needs a place in ``_KEPT`` or ``_LABELLED``. A description, the labels of ``one_of:`` and a fixed choice (a ``Literal``, such as a dtype) are kept. A field of entries has its keys renamed, except ``cases:`` and - ``links:``, whose keys are labels of rows, and ``maps:`` holds entries by - subject and then by map. Every other string is text that + ``links:``, whose keys are labels of rows, and ``mappings:`` holds entries by + subject and then by mapping. Every other string is text that may contain names. An entry that is not a mapping is a short form of one: an expression on one line, or a piecewise link written as a list. """ diff --git a/src/mathspec/_separability.py b/src/mathspec/_separability.py index 06786f5a4..f0bc66e66 100644 --- a/src/mathspec/_separability.py +++ b/src/mathspec/_separability.py @@ -188,6 +188,6 @@ def linking_rows(dimension: str) -> tuple[str, ...]: def _read_through(columns: JoinColumns) -> str: - """The subject *columns* reads, with the maps whose labels decide the reach, as the file writes them.""" - maps = [role for role in (*columns.joined, *columns.grouped) if role in columns.relation.values] - return f'{columns.name}[{", ".join(maps)}]' if maps else columns.name + """The subject *columns* reads, with the mappings whose labels decide the reach, as the file writes them.""" + mappings = [role for role in (*columns.joined, *columns.grouped) if role in columns.relation.values] + return f'{columns.name}[{", ".join(mappings)}]' if mappings else columns.name diff --git a/src/mathspec/_typesetting/README.md b/src/mathspec/_typesetting/README.md index 73cab78fd..d90dc31c1 100644 --- a/src/mathspec/_typesetting/README.md +++ b/src/mathspec/_typesetting/README.md @@ -59,7 +59,7 @@ mathspec.to_latex('dispatch.yaml', symbols=mathspec.SymbolTable.load(table)) # ``` The dict has the same sections as the file, which are `notation`, `dimensions` -and `names`. It is what the YAML parses to, and not a flat `{name: symbol}` map. +and `names`. It is what the YAML parses to, and not a flat `{name: symbol}` mapping. Whichever form you use, the table is checked against the spec. A key that names nothing is an error, and the message gives the near miss. Without that check, a diff --git a/src/mathspec/_typesetting/legend.py b/src/mathspec/_typesetting/legend.py index e99c0f5a6..c977463d1 100644 --- a/src/mathspec/_typesetting/legend.py +++ b/src/mathspec/_typesetting/legend.py @@ -54,7 +54,7 @@ class Noticed: Attributes: policies: Each translation policy some ``shift`` or ``sum_back`` prints. - grouped: Whether some translation is counted inside the group of a map. + grouped: Whether some translation is counted inside the group of a mapping. positions: Each form a ``position()`` prints in. numeric_coordinates: Each dimension whose index is compared against a number, where "position 3" and "the coordinate 3" are both @@ -259,10 +259,10 @@ def _missing(self, value: ParameterMissing, default: str = 'refused', where: str return f', {shown} {where}' def _signatures(self, name: str, lk: Relation, dim: str) -> list[str]: - """The parts of table *name* that touch *dim*: the relation inside its product, and each map from its subject. + """The parts of table *name* that touch *dim*: the relation inside its product, and each mapping from its subject. A relation prints as ``connection ⊆ P x U`` under each of its - dimensions. A map prints as ``carrier: U → C`` under its subject's + dimensions. A mapping prints as ``carrier: U → C`` under its subject's dimensions and the one it refers to, its subject a set symbol for a dimension and the relation's name for a relation. """ @@ -281,7 +281,7 @@ def _signatures(self, name: str, lk: Relation, dim: str) -> list[str]: return signatures def _coords(self, dim: str, noticed: Noticed) -> str: - """The dimension's carried structure: the labels its ``one_of`` allows, each relation over it and map from or into it, and each that may leave a row out. + """The dimension's carried structure: the labels its ``one_of`` allows, each relation over it and mapping from or into it, and each that may leave a row out. The dtype is named only where an equation compared the index against a number, the one place "position 3" and "the coordinate 3" are both @@ -334,7 +334,7 @@ def _notation(self, noticed: Noticed) -> list[LegendItem]: items.append( LegendItem( f't {fmt.superscript(self._op("cyclic_minus"), relation)} k', - f'{fmt.mono("within=subject[map]")} {dash} {shifted} inside the group of {t}', + f'{fmt.mono("within=subject[mapping]")} {dash} {shifted} inside the group of {t}', ) ) if noticed.positions: @@ -348,7 +348,7 @@ def _notation(self, noticed: Noticed) -> list[LegendItem]: items.append( LegendItem( fmt.apply(fmt.subscript(self._op('position'), [relation]), 't'), - f'{fmt.mono("position(within=subject[map])")} {dash} the position of {t} inside its group', + f'{fmt.mono("position(within=subject[mapping])")} {dash} the position of {t} inside its group', ) ) if 'from_end' in noticed.positions: diff --git a/src/mathspec/_typesetting/symbols.py b/src/mathspec/_typesetting/symbols.py index 86e120594..6ab3fc401 100644 --- a/src/mathspec/_typesetting/symbols.py +++ b/src/mathspec/_typesetting/symbols.py @@ -102,7 +102,7 @@ class Symbols: constraint: Each constraint's symbol, the subscript ``dual(c)`` prints λ against. Off the flat namespace, like the constraints themselves — a spec may name a constraint after a variable, so this is its - own map rather than an entry in [`name`][]. Given structure, so + own mapping rather than an entry in [`name`][]. Given structure, so upright unless a table overrides it. index: Each dimension's index letter. set: Each dimension's set symbol. diff --git a/src/mathspec/_typesetting/walk.py b/src/mathspec/_typesetting/walk.py index f0c0df9ad..370b73d39 100644 --- a/src/mathspec/_typesetting/walk.py +++ b/src/mathspec/_typesetting/walk.py @@ -251,19 +251,19 @@ def _translation(self, step: _Step) -> str: return self.format.superscript(operator, step.within) def _relation_read(self, name: str, at: Mapping[str, str], read: str) -> str: - """Subject *name*'s map *read* as a function at the columns *at* fixes: ``bus(g)`` or ``bus(p, u)``. + """Subject *name*'s mapping *read* as a function at the columns *at* fixes: ``bus(g)`` or ``bus(p, u)``. *at* maps each key role to the index it is read at. The function is - named after the map alone, as the legend lists it. + named after the mapping alone, as the legend lists it. """ lk = self.program.relations[name] return self.format.apply(self.format.upright(read), self.format.joined([at[k] for k in lk.key], '')) def _relation_row(self, name: str, at: Mapping[str, str], column: str | None = None) -> str: - """That relation *name* has a row at the key *at* fixes, or with *column*, that the map gives the row a label. + """That relation *name* has a row at the key *at* fixes, or with *column*, that the mapping gives the row a label. A relation is a set of rows, so the row is written out: - ``(p, u) ∈ connection``. A map is a function, so the claim is that it + ``(p, u) ∈ connection``. A mapping is a function, so the claim is that it is defined there: ``line(o) is defined``. """ lk = self.program.relations[name] @@ -278,7 +278,7 @@ def _frame_key(self, name: str, ctx: _Context) -> dict[str, str]: return {k: ctx.subscript(lk.dim(k)) for k in lk.key} def _value_read(self, name: str, column: str, ctx: _Context) -> str: - """Subject *name*'s map *column* read at the frame's own indices of its key: ``period(t)``.""" + """Subject *name*'s mapping *column* read at the frame's own indices of its key: ``period(t)``.""" return self._relation_read(name, self._frame_key(name, ctx), column) def _tuple(self, reads: list[str]) -> str: @@ -904,7 +904,7 @@ def _piecewise(self, name: str) -> Line: return Line(label=name, left=left, right=right, condition=self._quantifier(frame, condition)) def _link(self, link: Link, ctx: _Context) -> tuple[str, str]: - """One link's point coordinate and its breakpoints, each a family where the link walks a map. + """One link's point coordinate and its breakpoints, each a family where the link walks a mapping. A walked link is one coordinate per fine index that maps to the curve's own, so it prints as the family over those, which is what ties them to diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index d23cdd4f2..85ff19ed4 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -110,7 +110,7 @@ def reference_errors(spec: Spec) -> list[str]: *_name_collisions(spec), *_frame_dimensions(spec), *_relation_targets(spec), - *_map_targets(spec), + *_mapping_targets(spec), *_bound_names(spec), *_sos_shapes(spec), *_sos_bounds(spec), @@ -205,7 +205,7 @@ def _relation_targets(spec: Spec) -> Iterator[str]: dim = lk.pairs[0][1] if lk.pairs else '' yield ( f"Relation '{lname}' has {'one column' if lk.pairs else 'no column'} under 'dims:', and a relation " - f'needs at least two. To give each {dim} a label, declare a map under maps: {dim}:. To mark some ' + f'needs at least two. To give each {dim} a label, declare a mapping under mappings: {dim}:. To mark some ' f'of them, declare a bool parameter or a condition.' ) if not isinstance(lk.dims, Mapping): @@ -228,31 +228,31 @@ def _relation_targets(spec: Spec) -> Iterator[str]: ) -def _map_targets(spec: Spec) -> Iterator[str]: - """A map's subject is a dimension or a relation, its name is no column of the subject, and it refers to a dimension. +def _mapping_targets(spec: Spec) -> Iterator[str]: + """A mapping's subject is a dimension or a relation, its name is no column of the subject, and it refers to a dimension. - A relation with two columns over one dimension takes no map, since a call + A relation with two columns over one dimension takes no mapping, since a call through it would not know which of the two the frame's dimension meets. """ - for subject, maps in spec.maps.items(): - head = f"maps: '{subject}'" + for subject, mappings in spec.mappings.items(): + head = f"mappings: '{subject}'" if subject in spec.relations: pairs = spec.relations[subject].pairs if twice := [d for d, count in Counter(d for _, d in pairs).items() if count > 1]: yield ( - f"{head} is a relation with two columns over '{twice[0]}', and a map reads one row per " - f'combination of its dimensions. Declare the maps on a relation over each dimension once.' + f"{head} is a relation with two columns over '{twice[0]}', and a mapping reads one row per " + f'combination of its dimensions. Declare the mappings on a relation over each dimension once.' ) elif subject in spec.dimensions: pairs = ((subject, subject),) else: subjects = [*spec.dimensions, *spec.relations] yield ( - f'{head} is neither a dimension nor a relation, and a map gives each row of one a label. ' + f'{head} is neither a dimension nor a relation, and a mapping gives each row of one a label. ' f'{did_you_mean(subject, subjects, label="Subjects")}' ) continue - for role, m in maps.items(): + for role, m in mappings.items(): if not re.fullmatch(NAME, role): yield ( f'{head}: {role!r} is not a name. Start it with a letter or an underscore, then use only ' @@ -260,22 +260,22 @@ def _map_targets(spec: Spec) -> Iterator[str]: ) if role in dict(pairs): yield ( - f"{head}: map '{role}' has the name of a column of '{subject}', which holds the row, not a " - f'label of it. Rename the map after what it holds.' + f"{head}: mapping '{role}' has the name of a column of '{subject}', which holds the row, not a " + f'label of it. Rename the mapping after what it holds.' ) if m.dim in spec.relations: yield ( - f"{head}: map '{role}' refers to the relation '{m.dim}', and a map gives a label of one " + f"{head}: mapping '{role}' refers to the relation '{m.dim}', and a mapping gives a label of one " f"dimension. Refer to one of its dimensions, or declare '{role}' on the relation instead." ) elif m.dim not in spec.dimensions: yield ( - f"{head}: map '{role}' refers to undeclared dimension '{m.dim}'. Declare it under 'dimensions:'." + f"{head}: mapping '{role}' refers to undeclared dimension '{m.dim}'. Declare it under 'dimensions:'." ) elif role in spec.dimensions and role != m.dim: yield ( - f"{head}: map '{role}' is named after dimension '{role}', but refers to '{m.dim}'. Rename the " - f'map after what it holds.' + f"{head}: mapping '{role}' is named after dimension '{role}', but refers to '{m.dim}'. Rename the " + f'mapping after what it holds.' ) @@ -395,8 +395,8 @@ def _piecewise_references(spec: Spec) -> Iterator[str]: continue if (activity := gate_of(pw.activity)) is None: yield ( - f'{context}: activity: {pw.activity!r} is neither a variable nor a variable read through a map. ' - f'Write activity: , or activity: at(, by=[]).' + f'{context}: activity: {pw.activity!r} is neither a variable nor a variable read through a mapping. ' + f'Write activity: , or activity: at(, by=[]).' ) continue if activity not in spec.variables: diff --git a/src/mathspec/program.py b/src/mathspec/program.py index 7f5c93718..24e7a3bda 100644 --- a/src/mathspec/program.py +++ b/src/mathspec/program.py @@ -275,7 +275,7 @@ class Column: name: str def __str__(self) -> str: - """The column as a file writes it, ``subject[map]``.""" + """The column as a file writes it, ``subject[mapping]``.""" return f'{self.relation}[{self.name}]' @@ -294,7 +294,7 @@ class Axis: column: Column | None = None def __str__(self) -> str: - """The dimension's name, or the column's ``subject[map]`` for a join's axis.""" + """The dimension's name, or the column's ``subject[mapping]`` for a join's axis.""" return self.dimension if self.column is None else str(self.column) @@ -490,13 +490,13 @@ def children(expression: Expression) -> tuple[Expression, ...]: @dataclass(frozen=True) class Relation: - """One table the data supplies: a relation's rows, or a dimension's labels, with a column per map of the subject. + """One table the data supplies: a relation's rows, or a dimension's labels, with a column per mapping of the subject. ``columns`` maps each role to its dimension, the key's roles first and each side sorted by role; ``key`` is the roles a row is identified by: a relation's own columns, or the dimension for a dimension's table. Its - [`values`][] are the subject's maps, each named after the map, and none - for a relation with no maps. Every value is + [`values`][] are the subject's mappings, each named after the mapping, and none + for a relation with no mappings. Every value is checked when the data is attached to be a label of its column's dimension, and the table to have one row per key tuple — which keeps a mistyped label from silently dropping its terms in the join that places them, and is what lets ``at`` @@ -510,7 +510,7 @@ class Relation: """Whether every combination of the key needs a row: ``refused`` or ``absent``.""" description: str | None = None partial: tuple[str, ...] = () - """The value roles a row may leave empty: the maps under ``missing: absent``, sorted by role.""" + """The value roles a row may leave empty: the mappings under ``missing: absent``, sorted by role.""" @property def roles(self) -> tuple[str, ...]: @@ -535,7 +535,7 @@ def dim(self, role: str) -> str: return self._dim_of[role] def missing_at(self, roles: Iterable[str]) -> RelationMissing: - """``absent`` where a read of *roles* may find nothing there: the table may lack the row, or a map its label.""" + """``absent`` where a read of *roles* may find nothing there: the table may lack the row, or a mapping its label.""" return 'absent' if self.missing == 'absent' or set(roles) & set(self.partial) else 'refused' def in_order(self, roles: Iterable[str]) -> tuple[str, ...]: @@ -895,8 +895,8 @@ class Link: ``name`` is the link's key in the entry, and ``_`` is the row the expansion writes for it. ``sign`` is ``'=='`` where the link is pinned to the curve, and one side of it where the link is bounded by the curve - instead. A link that walks a map reads the curve's weights through - it, as ``at(..., by=)`` reads an array: ``by`` is the ``subject[map]`` + instead. A link that walks a mapping reads the curve's weights through + it, as ``at(..., by=)`` reads an array: ``by`` is the ``subject[mapping]`` the file wrote, and ``walk`` the join it resolves to. ``dims`` is the row the link builds: the entry's frame, or, for a walked link, that frame with the dims the join drops replaced by the ones it adds. ``reads`` says @@ -1014,7 +1014,7 @@ class Reach: Attributes: label: The entry reading, as the lowering's messages label it. - name: The parameter, the relation, or the ``subject[map]`` whose data says how far. + name: The parameter, the relation, or the ``subject[mapping]`` whose data says how far. kind: An ``offset`` is a parameter's values, which [`Separability.resolved`][] folds in; a ``partition`` and a ``coordinate`` are a relation's groups, which it does not. @@ -1143,7 +1143,7 @@ class Program: dimensions: Mapping[str, Dimension] = Frozen({}) relations: Mapping[str, Relation] = Frozen({}) """Each table the data supplies, by its subject's name: every relation the file declares, and every dimension it - declares maps of, each with its maps as value columns. + declares mappings of, each with its mappings as value columns. """ sos: Mapping[str, Sos] = Frozen({}) piecewise: Mapping[str, Piecewise] = Frozen({}) @@ -1182,7 +1182,7 @@ def _by_position(self) -> Iterator[tuple[QuadraticPosition, tuple[Expression, .. yield 'constraint', tuple(side for c in self.constraints.values() for side in (c.lhs, c.rhs)) def relations_of(self, dimension: str) -> Mapping[str, Relation]: - """The tables with a column over *dimension*, by name: a relation over it, or a subject with a map into it.""" + """The tables with a column over *dimension*, by name: a relation over it, or a subject with a mapping into it.""" return Frozen({n: lk for n, lk in self.relations.items() if dimension in lk.dims}) @property @@ -1416,9 +1416,9 @@ class DimensionPosition: @dataclass(frozen=True) class RelationComparison: - """Compare one map of a subject against a literal — ``snapshot[period] == 2030``. + """Compare one mapping of a subject against a literal — ``snapshot[period] == 2030``. - ``column`` is the map read, and ``dims`` the dimensions of the subject's + ``column`` is the mapping read, and ``dims`` the dimensions of the subject's own columns: the leaf is read at them, one label per coordinate. """ @@ -1431,9 +1431,9 @@ class RelationComparison: @dataclass(frozen=True) class RelationPairComparison: - """Compare a map of one subject with a map of another, or of the same — ``line[bus0] != line[bus1]`` — row by row. + """Compare a mapping of one subject with a mapping of another, or of the same — ``line[bus0] != line[bus1]`` — row by row. - Both subjects are over the same ``dims``, and the two maps refer to one + Both subjects are over the same ``dims``, and the two mappings refer to one dimension, so a match is possible at all. """ @@ -1447,12 +1447,12 @@ class RelationPairComparison: @dataclass(frozen=True) class RelationDefined: - """True where the table has a row at the frame's coordinates, and with ``column`` set, a label in that map. + """True where the table has a row at the frame's coordinates, and with ``column`` set, a label in that mapping. ``dims`` is what the frame supplies: the key's dimensions, whose row is then the one the key finds — every column's for a bare relation, where a row is the whole tuple. A bare relation name in a condition sets no - ``column``; ``subject[map]`` alone sets it, as ``outage[line]`` does. + ``column``; ``subject[mapping]`` alone sets it, as ``outage[line]`` does. """ name: str @@ -1639,7 +1639,7 @@ def _atom_names(atom: TypedCondition) -> frozenset[str]: """One leaf's entries, its dimension apart — the rule [`Mask.names_read`][] is the union of. A comparison on a dimension names no entry — a coordinate is not - data to feed — a relation pair names both maps it compares, and a + data to feed — a relation pair names both mappings it compares, and a comparison of expressions names every parameter and relation its sides read, answered on the program's form of it since only a program mask is asked. ``assert_never``-closed for the reason [`_atom_dims`][] is: a condition diff --git a/src/mathspec/spec.py b/src/mathspec/spec.py index 626a26fb8..5bc240ccf 100644 --- a/src/mathspec/spec.py +++ b/src/mathspec/spec.py @@ -74,7 +74,7 @@ 'GivenSpec', 'GivenVariableSpec', 'MacroSpec', - 'MapSpec', + 'MappingSpec', 'ObjectiveSpec', 'ParameterSpec', 'PiecewiseLinkSpec', @@ -256,9 +256,9 @@ class RelationSpec(_StrictSpec): A relation is not a dimension. Its name stands in a condition, where it is true at the rows it lists, and before a - bracket, where it reads one of its maps (``maps:``, [`MapSpec`][]). The + bracket, where it reads one of its mappings (``mappings:``, [`MappingSpec`][]). The rows are data, and arrive under the relation's name, one column per - column name, with a column per map beside them. + column name, with a column per mapping beside them. """ _label: ClassVar[str] = 'a relation entry' @@ -292,12 +292,12 @@ def roles(self) -> tuple[str, ...]: return tuple(role for role, _ in self.pairs) -class MapSpec(_StrictSpec): - """A map: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names. +class MappingSpec(_StrictSpec): + """A mapping: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names. Written in YAML under its subject, with ``dim:`` always written:: - maps: + mappings: unit: carrier: {dim: carrier, missing: absent} connection: @@ -306,17 +306,17 @@ class MapSpec(_StrictSpec): bus0: {dim: bus} bus1: {dim: bus} - The map's name is a column of its subject's table, beside the subject's - own columns. A call reads it as ``subject[map]``: ``sum(by=)`` totals + The mapping's name is a column of its subject's table, beside the subject's + own columns. A call reads it as ``subject[mapping]``: ``sum(by=)`` totals along it, ``at(by=)`` reads through it, ``within=`` works in each group of rows it sends to one label, and a condition compares it or tests that a row has a label. """ - _label: ClassVar[str] = 'a map entry' + _label: ClassVar[str] = 'a mapping entry' dim: str - """The dimension whose label the map gives each row of its subject.""" + """The dimension whose label the mapping gives each row of its subject.""" missing: RelationMissing = 'refused' """Whether every row of the subject has a label. Under ``refused``, a tool refuses data that leaves one out. Under ``absent``, that row has none. @@ -326,12 +326,12 @@ class MapSpec(_StrictSpec): @field_validator('missing', mode='before') @classmethod def _refused_or_absent(cls, v: object) -> object: - """A label is data, so no value fills a gap in a map.""" - return _refused_or_absent(v, 'a map', 'Write absent where a row may have no label, or leave it out.') + """A label is data, so no value fills a gap in a mapping.""" + return _refused_or_absent(v, 'a mapping', 'Write absent where a row may have no label, or leave it out.') def _refused_or_absent(v: object, kind: str, rewrite: str) -> object: - """*v* where it is ``refused`` or ``absent``, the two words a ``missing:`` of a relation or a map takes.""" + """*v* where it is ``refused`` or ``absent``, the two words a ``missing:`` of a relation or a mapping takes.""" if v is None: raise _missing_null(kind, rewrite) if v not in get_args(RelationMissing): @@ -350,8 +350,8 @@ class DimensionSpec(_StrictSpec): and what its coordinates are typed as. Which coordinates there are is data, and arrives when the data is attached; a ``one_of`` only names the labels a coordinate may have. The labels its members carry — a - generator's bus, a snapshot's period — are its ``maps:`` - ([`MapSpec`][]). + generator's bus, a snapshot's period — are its ``mappings:`` + ([`MappingSpec`][]). """ _label: ClassVar[str] = 'a dimension entry' @@ -362,7 +362,7 @@ class DimensionSpec(_StrictSpec): | None ) = None """The labels a ``str`` dimension allows, at least one and each once, sorted by name. At load, mathspec refuses a - condition that compares the dimension, or a map into it, with any other label. + condition that compares the dimension, or a mapping into it, with any other label. """ ordered: bool = False """Whether the order in which the data gives the labels is part of the spec. An operator may step or count only along @@ -929,7 +929,7 @@ class PiecewiseLinkSpec(_StrictSpec): sign]``, and serialised back to exactly that form, so a round trip through [`Spec.to_yaml`][] reproduces the file. - A link that names ``by: subject[map]`` reads the curve's weights + A link that names ``by: subject[mapping]`` reads the curve's weights through the relation, as ``at`` reads an array, and is written as a mapping. Its row is the entry's ``dims:`` with the dims the lookup reads replaced by the key columns it arrives at, so one link emits a row per fine @@ -1015,7 +1015,7 @@ class PiecewiseSpec(_StrictSpec): weights per coordinate of it. ``where:`` says which of those coordinates have a curve, and how far each runs along ``along`` where it reads that dim too; ``activity:`` whether a curve that exists is switched on. A link - that walks a map builds a row per fine coordinate, each reading the + that walks a mapping builds a row per fine coordinate, each reading the one curve its coarse coordinate has, so how many expressions a curve ties is data. """ @@ -1038,7 +1038,7 @@ class PiecewiseSpec(_StrictSpec): activity: str | None = None """The variable that switches each curve off where it is 0, or no switch when the key is left out. A binary variable, or an integer one under ``method: incremental``, which from 1 up moves the curve by its point at the first breakpoint - once per unit above 1. Written as the name of the variable, or as ``at(, by=[])``. + once per unit above 1. Written as the name of the variable, or as ``at(, by=[])``. """ description: str | None = None @@ -1078,7 +1078,7 @@ def _check_method_shape(self) -> PiecewiseSpec: walked = [key for key, link in self.links.items() if link.walks] if walked and self.method in ('convex', 'lp'): msg = ( - f"method: {self.method} does not take a link that walks a map (link '{walked[0]}'). " + f"method: {self.method} does not take a link that walks a mapping (link '{walked[0]}'). " f'{_NO_WALK[self.method]} Use method: adjacency, sos2 or incremental.' ) raise ValueError(msg) @@ -1201,8 +1201,8 @@ class is pydantic's, not a contract this package keeps. """What this file uses and does not build ([`GivenSpec`][]). It is empty when the file has no ``given:``.""" dimensions: ByName[DimensionSpec] = Frozen({}) relations: ByName[RelationSpec] = Frozen({}) - maps: ByName[ByName[MapSpec]] = Frozen({}) - """Each subject's maps, by subject, a dimension or a relation, and then by map ([`MapSpec`][]).""" + mappings: ByName[ByName[MappingSpec]] = Frozen({}) + """Each subject's mappings, by subject, a dimension or a relation, and then by mapping ([`MappingSpec`][]).""" parameters: ByName[ParameterSpec] = Frozen({}) conditions: ByName[ConditionSpec] = Frozen({}) variables: ByName[VariableSpec] = Frozen({}) @@ -1389,25 +1389,25 @@ def _lower(self) -> Spec: def subject_tables(spec: Spec) -> dict[str, Relation]: - """Each table the data supplies, by name: a relation with its maps as columns beside its own, and a dimension with maps. + """Each table the data supplies, by name: a relation with its mappings as columns beside its own, and a dimension with mappings. A relation's table has one row per row of the relation, keyed by all of its own columns. A dimension's table has one row per label, keyed by the - dimension. Each map is a column of its subject's table, and a map under + dimension. Each mapping is a column of its subject's table, and a mapping under ``missing: absent`` is listed as [`partial`][mathspec.program.Relation.partial]. A subject the file does not declare is left out, which the load refuses. """ tables: dict[str, Relation] = {} - for name in sorted({*spec.relations, *spec.maps}): - maps = spec.maps.get(name, Frozen({})) + for name in sorted({*spec.relations, *spec.mappings}): + mappings = spec.mappings.get(name, Frozen({})) if (relation := spec.relations.get(name)) is not None: key, missing, description = relation.pairs, relation.missing, relation.description elif name in spec.dimensions: key, missing, description = ((name, name),), cast('RelationMissing', 'refused'), None else: continue - values = tuple((role, m.dim) for role, m in maps.items()) - partial = tuple(role for role, m in maps.items() if m.missing == 'absent') + values = tuple((role, m.dim) for role, m in mappings.items()) + partial = tuple(role for role, m in mappings.items() if m.missing == 'absent') tables[name] = Relation((*key, *values), tuple(r for r, _ in key), missing, description, partial) return tables diff --git a/tests/fixtures.py b/tests/fixtures.py index 49201ef19..54d9c362c 100644 --- a/tests/fixtures.py +++ b/tests/fixtures.py @@ -47,13 +47,13 @@ 'objective': {'sense': 'minimize', 'expression': 'sum(p * cost)'}, } -#: Two dimensions, a map from one into the other, a numeric, a scalar, a boolean and a +#: Two dimensions, a mapping from one into the other, a numeric, a scalar, a boolean and a #: label parameter, a variable on each frame — one entry of every kind #: a rule can name, and no objective, so a test adds what it judges. `p` and `r` #: share no dimension, which is what a rule about *different* dims needs. SMALL_MODEL: dict[str, Any] = { 'dimensions': {'g': {'dtype': 'str', 'ordered': True}, 'h': {'dtype': 'str', 'ordered': True}}, - 'maps': {'g': {'h': {'dim': 'h'}}}, + 'mappings': {'g': {'h': {'dim': 'h'}}}, 'parameters': { 'c': {'dims': ['g']}, 'k': {'dims': []}, @@ -94,7 +94,7 @@ def sets_reversed(data: Any) -> Any: """*data* with every list or mapping that names a set reversed, at any depth. Each ``dims:``, ``one_of:`` and ``kwargs:`` list, a relation's - ``dims:`` mapping among them, and the maps of each subject. + ``dims:`` mapping among them, and the mappings of each subject. """ if isinstance(data, list): return [sets_reversed(item) for item in data] @@ -104,11 +104,11 @@ def sets_reversed(data: Any) -> Any: def _reversed_under(key: str, value: Any) -> Any: - """*value* reversed where *key* names a set, each subject's maps reversed under ``maps``, else searched on.""" + """*value* reversed where *key* names a set, each subject's mappings reversed under ``mappings``, else searched on.""" if key in ('dims', 'one_of', 'kwargs'): return _reversed(value) - if key == 'maps' and isinstance(value, dict): - return {subject: _reversed(maps) for subject, maps in value.items()} + if key == 'mappings' and isinstance(value, dict): + return {subject: _reversed(mappings) for subject, mappings in value.items()} return sets_reversed(value) diff --git a/tests/fixtures/every_program_node.yaml b/tests/fixtures/every_program_node.yaml index 094947e29..5c570c4ce 100644 --- a/tests/fixtures/every_program_node.yaml +++ b/tests/fixtures/every_program_node.yaml @@ -7,7 +7,7 @@ dimensions: t: { dtype: int, ordered: true } g: { dtype: str } zone: { dtype: str } -maps: +mappings: g: { zone: { dim: zone } } parameters: cost: { dims: [g] } diff --git a/tests/fixtures/pypsa_standard_shape.yaml b/tests/fixtures/pypsa_standard_shape.yaml index 867f27bda..2a52f1394 100644 --- a/tests/fixtures/pypsa_standard_shape.yaml +++ b/tests/fixtures/pypsa_standard_shape.yaml @@ -931,7 +931,7 @@ parameters: snapshot_weightings_stores: - snapshot transmission_losses: [] -maps: +mappings: - generator[bus] - line[bus0] - line[bus1] diff --git a/tests/test_advice.py b/tests/test_advice.py index c1d6d7c2b..18ea6e7a2 100644 --- a/tests/test_advice.py +++ b/tests/test_advice.py @@ -23,15 +23,15 @@ EXAMPLES = Path(__file__).resolve().parents[1] / 'examples' -#: ``h`` is what the map ``g[h]`` refers to, and nothing else reaches it; ``g`` is an axis. +#: ``h`` is what the mapping ``g[h]`` refers to, and nothing else reaches it; ``g`` is an axis. TARGET_ONLY = varied( SMALL_MODEL, variables={'p': {'dims': ['g']}}, objective={'sense': 'minimize', 'expression': 'sum(p * c)'}, ) -#: The same with the map gone, so nothing reaches ``h`` at all. -UNREACHED = varied(TARGET_ONLY, maps={}) +#: The same with the mapping gone, so nothing reaches ``h`` at all. +UNREACHED = varied(TARGET_ONLY, mappings={}) #: A curve on ``p``, so the program of the file as written carries a piecewise entry and #: the program of its expansion carries the rows. The objective drives ``p`` @@ -55,7 +55,7 @@ def test_a_dimension_nothing_reaches_is_named(): @pytest.mark.parametrize( 'patch', [ - pytest.param({}, id='referred-to-by-a-map'), + pytest.param({}, id='referred-to-by-a-mapping'), pytest.param( {'constraints': {'cap': {'dims': ['h'], 'expression': 'sum(p, over=g, by=g[h]) <= k'}}}, id='grouping-into-it', @@ -65,7 +65,7 @@ def test_a_dimension_nothing_reaches_is_named(): ) def test_a_dimension_something_reaches_is_in_use(patch): assert not advice(varied(TARGET_ONLY, **patch)), ( - 'a dimension a map refers to, an entry indexes or a grouping groups by is in use' + 'a dimension a mapping refers to, an entry indexes or a grouping groups by is in use' ) diff --git a/tests/test_boundedness.py b/tests/test_boundedness.py index c961ae79e..1bff4dfa7 100644 --- a/tests/test_boundedness.py +++ b/tests/test_boundedness.py @@ -138,7 +138,7 @@ def test_nothing_is_claimed_where_the_file_does_not_decide_it(patch): 'sum': {'objective.expression': 'sum(v, over=g)'}, 'shift': {'objective.expression': 'sum(shift(v, along=g, offset=1), over=g)'}, 'sum_back': {'objective.expression': 'sum(sum_back(v, along=g, window=2), over=g)'}, - # `at` reads onto the map's subject, so the variable it drives is on `h` + # `at` reads onto the mapping's subject, so the variable it drives is on `h` 'at': {'variables.u': {'dims': ['h']}, 'objective.expression': 'sum(at(u, by=g[h]), over=g)'}, } diff --git a/tests/test_canonical.py b/tests/test_canonical.py index 76fb4fc14..53ffe0063 100644 --- a/tests/test_canonical.py +++ b/tests/test_canonical.py @@ -140,9 +140,11 @@ def test_the_entries_of_a_section_are_sorted_by_name(): pytest.param({'dim': 'h', 'missing': 'absent'}, id='with-missing'), ], ) -def test_a_map_is_written_back_as_the_mapping_it_was_declared_as(declared): - dumped = yaml.safe_load(ms.to_spec(varied(SMALL_MODEL, **{'maps.g.h': declared})).to_yaml(canonical=True)) - assert dumped['maps'] == {'g': {'h': declared}}, 'a map is written with `dim:`, never as the bare dimension name' +def test_a_mapping_is_written_back_as_the_mapping_it_was_declared_as(declared): + dumped = yaml.safe_load(ms.to_spec(varied(SMALL_MODEL, **{'mappings.g.h': declared})).to_yaml(canonical=True)) + assert dumped['mappings'] == {'g': {'h': declared}}, ( + 'a mapping is written with `dim:`, never as the bare dimension name' + ) #: The order the form writes the sections in, whatever order the file wrote @@ -154,7 +156,7 @@ def test_a_map_is_written_back_as_the_mapping_it_was_declared_as(declared): 'given', 'dimensions', 'relations', - 'maps', + 'mappings', 'parameters', 'conditions', 'variables', @@ -204,8 +206,8 @@ def test_every_section_is_sorted_by_name(path): for section, entries in data.items(): if isinstance(entries, dict) and section != 'objective': assert list(entries) == sorted(entries), f'{path.name}: `{section}` reads in name order' - for subject, maps in data.get('maps', {}).items(): - assert list(maps) == sorted(maps), f'{path.name}: the maps of `{subject}` read in name order' + for subject, mappings in data.get('mappings', {}).items(): + assert list(mappings) == sorted(mappings), f'{path.name}: the mappings of `{subject}` read in name order' def _commitment_with_its_cases_reversed() -> dict[str, object]: @@ -344,7 +346,7 @@ def test_two_spellings_of_one_spec_write_one_canonical_text(source, key, written pytest.param('not (not a)', 'NOT (NOT a)', id='and-another-not'), pytest.param('true or a', 'True OR a', id='a-literal'), pytest.param("tag == 'it\\'s'", "tag == 'it\\'s'", id='a-quoted-label-keeps-its-escape'), - pytest.param('g[h] == h', 'g[h] == h', id='a-label-a-map-gives'), + pytest.param('g[h] == h', 'g[h] == h', id='a-label-a-mapping-gives'), pytest.param('count(b or a, over=t) >= 2', 'count(a OR b, over=t) >= 2', id='a-count'), pytest.param('count(a, over=t, by=g) >= 1', 'count(a, by=g, over=t) >= 1', id='a-calls-kwargs-are-sorted'), ], diff --git a/tests/test_composition.py b/tests/test_composition.py index 47996afe7..8e4fcc861 100644 --- a/tests/test_composition.py +++ b/tests/test_composition.py @@ -37,14 +37,14 @@ #: each is a spec on its own as well as a piece of the composition. SURFACE = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, - 'maps': {'port': {'bus': {'dim': 'bus'}}}, + 'mappings': {'port': {'bus': {'dim': 'bus'}}}, 'variables': {'flow': {'dims': ['snapshot', 'port']}}, 'constraints': {'balance': {'dims': ['snapshot', 'bus'], 'expression': 'sum(flow, over=port, by=port[bus]) == 0'}}, } SUPPLY = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'generator': {'dtype': 'str'}}, - 'maps': {'generator': {'port': {'dim': 'port'}}}, + 'mappings': {'generator': {'port': {'dim': 'port'}}}, 'given': {'variables': {'flow': {'dims': ['snapshot', 'port']}}}, 'parameters': {'gen_cost': {'dims': ['generator']}, 'gen_p_max': {'dims': ['generator']}}, 'variables': {'gen_p': {'dims': ['snapshot', 'generator'], 'bounds': {'lower': 0, 'upper': 'gen_p_max'}}}, @@ -59,7 +59,7 @@ DEMAND = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'demand': {'dtype': 'str'}}, - 'maps': {'demand': {'port': {'dim': 'port'}}}, + 'mappings': {'demand': {'port': {'dim': 'port'}}}, 'given': {'variables': {'flow': {'dims': ['snapshot', 'port']}}}, 'parameters': {'dem_load': {'dims': ['snapshot', 'demand']}}, 'constraints': { @@ -118,7 +118,7 @@ def test_the_balance_does_not_grow_when_a_component_type_is_added(): three = merge(LIBRARY).constraints['balance'].expression storage = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'store': {'dtype': 'str'}}, - 'maps': {'store': {'port': {'dim': 'port'}}}, + 'mappings': {'store': {'port': {'dim': 'port'}}}, 'given': {'variables': {'flow': {'dims': ['snapshot', 'port']}}}, 'parameters': {'st_capacity': {'dims': ['store']}}, 'variables': {'st_p': {'dims': ['snapshot', 'store'], 'bounds': {'lower': 0, 'upper': 'st_capacity'}}}, @@ -224,21 +224,21 @@ def test_a_dimension_one_fragment_declares_ordered_is_ordered_in_the_composition def _mapped(missing: str | None = None, dim: str = 'bus') -> dict[str, object]: - """A fragment that declares only the map `port[bus]` into *dim*, with *missing* written where it is not ``None``.""" + """A fragment that declares only the mapping `port[bus]` into *dim*, with *missing* written where it is not ``None``.""" entry = {'dim': dim} | ({} if missing is None else {'missing': missing}) - return {'dimensions': {'port': {'dtype': 'str'}, dim: {'dtype': 'str'}}, 'maps': {'port': {'bus': entry}}} + return {'dimensions': {'port': {'dtype': 'str'}, dim: {'dtype': 'str'}}, 'mappings': {'port': {'bus': entry}}} def _wired(missing: str | None = None) -> dict[str, object]: - """A fragment that declares only the relation `wired` over `port` and `bus`, as `_mapped` does a map.""" + """A fragment that declares only the relation `wired` over `port` and `bus`, as `_mapped` does a mapping.""" entry = {'dims': ['port', 'bus']} | ({} if missing is None else {'missing': missing}) return {'dimensions': {'port': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, 'relations': {'wired': entry}} -#: A fragment that gives `port` a map of its own beside the one `SURFACE` gives it. +#: A fragment that gives `port` a mapping of its own beside the one `SURFACE` gives it. CARRIER = { 'dimensions': {'port': {'dtype': 'str'}, 'carrier': {'dtype': 'str'}}, - 'maps': {'port': {'carrier': {'dim': 'carrier'}}}, + 'mappings': {'port': {'carrier': {'dim': 'carrier'}}}, } @@ -249,9 +249,11 @@ def _wired(missing: str | None = None) -> dict[str, object]: pytest.param([CARRIER, SURFACE], id='the-carrier-first'), ], ) -def test_two_fragments_join_the_maps_they_give_one_subject(fragments): - """`maps:` is shared as `dimensions:` is, so a subject's maps fold by map rather than by subject.""" - assert sorted(merge(fragments).maps['port']) == ['bus', 'carrier'], "each fragment's map of `port` is in the spec" +def test_two_fragments_join_the_mappings_they_give_one_subject(fragments): + """`mappings:` is shared as `dimensions:` is, so a subject's mappings fold by mapping rather than by subject.""" + assert sorted(merge(fragments).mappings['port']) == ['bus', 'carrier'], ( + "each fragment's mapping of `port` is in the spec" + ) @pytest.mark.parametrize( @@ -259,7 +261,7 @@ def test_two_fragments_join_the_maps_they_give_one_subject(fragments): [ pytest.param([SURFACE, _mapped('refused')], 'refused', id='the-default-written-out'), pytest.param( - [varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'missing': 'absent'}}), _mapped('absent')], + [varied(SURFACE, **{'mappings.port.bus': {'dim': 'bus', 'missing': 'absent'}}), _mapped('absent')], 'absent', id='both-absent', ), @@ -267,15 +269,15 @@ def test_two_fragments_join_the_maps_they_give_one_subject(fragments): ) def test_two_fragments_that_say_one_missing_agree(fragments, missing): """A written `missing: refused` was refused against an omitted one, as two fragments saying different things.""" - assert merge(fragments).maps['port']['bus'].missing == missing + assert merge(fragments).mappings['port']['bus'].missing == missing @pytest.mark.parametrize( ('fragments', 'entry'), [ - pytest.param([SURFACE, _mapped('absent')], "map 'port[bus]'", id='refused-against-absent'), - pytest.param([_mapped('absent'), SURFACE], "map 'port[bus]'", id='absent-against-refused'), - pytest.param([SURFACE, _mapped(dim='node')], "map 'port[bus]'", id='two-dimensions-referred-to'), + pytest.param([SURFACE, _mapped('absent')], "mapping 'port[bus]'", id='refused-against-absent'), + pytest.param([_mapped('absent'), SURFACE], "mapping 'port[bus]'", id='absent-against-refused'), + pytest.param([SURFACE, _mapped(dim='node')], "mapping 'port[bus]'", id='two-dimensions-referred-to'), pytest.param([_wired(), _wired('absent')], "relation 'wired'", id='a-relation-refused-against-absent'), ], ) @@ -566,10 +568,10 @@ def test_a_later_patch_is_laid_on_what_the_earlier_ones_make(patches, field, val assert field(override(DISPATCH_MODEL, patches)) == value -def test_a_patch_adds_a_map_to_a_subject_its_base_maps(): - laid = override(SURFACE, [varied(CARRIER, **{'maps.port.bus': {'dim': 'bus'}})]) - assert sorted(laid.maps['port']) == ['bus', 'carrier'], ( - 'the map the patch adds joins the one the base gives `port`, and the restated one is not doubled' +def test_a_patch_adds_a_mapping_to_a_subject_its_base_mappings(): + laid = override(SURFACE, [varied(CARRIER, **{'mappings.port.bus': {'dim': 'bus'}})]) + assert sorted(laid.mappings['port']) == ['bus', 'carrier'], ( + 'the mapping the patch adds joins the one the base gives `port`, and the restated one is not doubled' ) @@ -598,7 +600,7 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated assert laid.dimensions[dimension].ordered is ordered -#: `SURFACE` with a relation, `wired`, over the two dimensions `port[bus]` maps between. +#: `SURFACE` with a relation, `wired`, over the two dimensions `port[bus]` mappings between. WIRED = varied(SURFACE, **{'relations.wired': {'dims': ['port', 'bus']}}) @@ -620,11 +622,11 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated id='a-relation', ), pytest.param( - varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), - {'maps': {'port': {'bus': {'dim': 'bus', 'description': 'a port and its bus'}}}}, - lambda spec: spec.maps['port']['bus'].description, + varied(SURFACE, **{'mappings.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), + {'mappings': {'port': {'bus': {'dim': 'bus', 'description': 'a port and its bus'}}}}, + lambda spec: spec.mappings['port']['bus'].description, 'a port and its bus', - id='a-map', + id='a-mapping', ), pytest.param( DISPATCH_MODEL, @@ -648,11 +650,11 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated id='null-removes-a-relation-description', ), pytest.param( - varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), - {'maps': {'port': {'bus': {'description': None}}}}, - lambda spec: spec.maps['port']['bus'].description, + varied(SURFACE, **{'mappings.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), + {'mappings': {'port': {'bus': {'description': None}}}}, + lambda spec: spec.mappings['port']['bus'].description, None, - id='null-removes-a-map-description', + id='null-removes-a-mapping-description', ), ], ) @@ -729,7 +731,7 @@ def test_a_patch_that_rewrites_a_dimension_is_refused(patch, says): pytest.param( {'relations': {'wired': {'dims': ['port']}}}, 'relation', 'wired', id='a-relation-over-one-dimension' ), - pytest.param({'maps': {'port': {'bus': {}}}}, 'map', 'port[bus]', id='a-map-with-no-field'), + pytest.param({'mappings': {'port': {'bus': {}}}}, 'mapping', 'port[bus]', id='a-mapping-with-no-field'), ], ) def test_a_patch_that_restates_an_entry_in_part_is_refused_with_the_rewrite(patch, kind, name): @@ -752,9 +754,9 @@ def test_a_patch_that_restates_an_entry_in_part_is_refused_with_the_rewrite(patc id='a-relation', ), pytest.param( - {'maps': {'port': {'bus': {'dmi': 'bus'}}}}, - "unknown key 'dmi' in a map entry. Did you mean 'dim'?", - id='a-map', + {'mappings': {'port': {'bus': {'dmi': 'bus'}}}}, + "unknown key 'dmi' in a mapping entry. Did you mean 'dim'?", + id='a-mapping', ), ], ) @@ -768,27 +770,27 @@ def test_a_misspelled_key_in_a_restated_entry_names_the_key_it_meant(patch, says ('patch', 'says'), [ pytest.param( - {'maps': {'port': {'bus': {'dim': 'port'}}}}, - 'Restate the map as its base declares it', + {'mappings': {'port': {'bus': {'dim': 'port'}}}}, + 'Restate the mapping as its base declares it', id='referred-to-another-dimension', ), - pytest.param({'maps': {'port': {'bus': None}}}, "removes the map 'port[bus]'", id='a-map-removed'), - pytest.param({'maps': {'port': None}}, "removes the maps of 'port'", id='a-subject-s-maps-removed'), + pytest.param({'mappings': {'port': {'bus': None}}}, "removes the mapping 'port[bus]'", id='a-mapping-removed'), + pytest.param({'mappings': {'port': None}}, "removes the mappings of 'port'", id='a-subject-s-mappings-removed'), ], ) -def test_a_patch_that_rewrites_or_drops_a_map_is_refused(patch, says): - """A map changed or dropped under the expressions that read it is a different spec, as a dimension is.""" +def test_a_patch_that_rewrites_or_drops_a_mapping_is_refused(patch, says): + """A mapping changed or dropped under the expressions that read it is a different spec, as a dimension is.""" with pytest.raises(LanguageError) as raised: override(SURFACE, [patch]) - assert says in str(raised.value), 'the refusal names the map and the rewrite' + assert says in str(raised.value), 'the refusal names the mapping and the rewrite' #: `SURFACE` with `port[bus]` declared `missing: absent`. -ABSENT_SURFACE = varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'missing': 'absent'}}) +ABSENT_SURFACE = varied(SURFACE, **{'mappings.port.bus': {'dim': 'bus', 'missing': 'absent'}}) @pytest.mark.parametrize( - ('base', 'map_', 'missing'), + ('base', 'mapping', 'missing'), [ pytest.param(SURFACE, {'missing': 'absent'}, 'absent', id='the-reading-alone'), pytest.param(SURFACE, {'dim': 'bus', 'missing': 'absent'}, 'absent', id='restated-absent'), @@ -798,9 +800,9 @@ def test_a_patch_that_rewrites_or_drops_a_map_is_refused(patch, says): pytest.param(ABSENT_SURFACE, {'dim': 'bus'}, 'absent', id='restated-without-one'), ], ) -def test_a_patch_changes_what_a_row_the_map_gives_no_label_means(base, map_, missing): - """`missing:` says what a row with no label means, and a patch that wrote it was refused as a change of the map.""" - assert override(base, [{'maps': {'port': {'bus': map_}}}]).maps['port']['bus'].missing == missing +def test_a_patch_changes_what_a_row_the_mapping_gives_no_label_means(base, mapping, missing): + """`missing:` says what a row with no label means, and a patch that wrote it was refused as a change of the mapping.""" + assert override(base, [{'mappings': {'port': {'bus': mapping}}}]).mappings['port']['bus'].missing == missing def test_a_patch_changes_what_a_combination_the_relation_leaves_out_means(): @@ -828,7 +830,7 @@ def test_a_patch_changes_what_a_missing_row_of_a_parameter_means(base, written, [ pytest.param('parameters', 'c', {'dims': ['g']}, id='a-parameter'), pytest.param('relations', 'gh', {'dims': ['g', 'h']}, id='a-relation'), - pytest.param('maps', 'g.h', {'dim': 'h'}, id='a-map'), + pytest.param('mappings', 'g.h', {'dim': 'h'}, id='a-mapping'), ], ) def test_the_default_missing_written_out_is_the_spec_that_leaves_it_out(section, name, declared): @@ -844,7 +846,7 @@ def test_the_default_missing_written_out_is_the_spec_that_leaves_it_out(section, [ pytest.param({'constraints': None}, id='an-owned-section'), pytest.param({'dimensions': None}, id='a-shared-section'), - pytest.param({'maps': None}, id='the-maps'), + pytest.param({'mappings': None}, id='the-mappings'), pytest.param({'given': {'variables': None}}, id='one-kind-of-given'), ], ) diff --git a/tests/test_dimensions.py b/tests/test_dimensions.py index d09cc1ce7..60e432cca 100644 --- a/tests/test_dimensions.py +++ b/tests/test_dimensions.py @@ -68,7 +68,7 @@ 'zone': {'dtype': 'str'}, }, 'relations': {'gen_zone': {'dims': ['generator', 'snapshot']}}, - 'maps': { + 'mappings': { 'generator': {'bus': {'dim': 'bus'}, 'zone': {'dim': 'zone'}, 'b0': {'dim': 'bus'}, 'b1': {'dim': 'bus'}}, 'snapshot': {'bus': {'dim': 'bus'}, 'rep': {'dim': 'snapshot'}}, 'gen_zone': {'zone': {'dim': 'zone'}}, @@ -211,7 +211,7 @@ def namespace() -> Namespace: pytest.param( 'sum(p, over=snapshot, by=snapshot[rep])', {'snapshot', 'generator'}, - id='a-map-into-its-own-dimension-keeps-the-frame', + id='a-mapping-into-its-own-dimension-keeps-the-frame', ), pytest.param('at(p, by=snapshot[rep])', {'snapshot', 'generator'}, id='and-so-does-its-lookup'), pytest.param('sum(p, over=[generator, snapshot])', set(), id='a-plain-sum-over-a-list'), @@ -257,14 +257,14 @@ def test_a_bare_relation_is_summed_between_its_key_columns(expr, expected): def test_a_value_column_added_to_a_relation_changes_no_call(): - """A name in `over=` is a column of the table, so `snapshot` gaining a map `alt` leaves every call as it was. + """A name in `over=` is a column of the table, so `snapshot` gaining a mapping `alt` leaves every call as it was. `over=snapshot` read as a dimension would match two columns once `alt` arrives, and the call that loaded would stop loading. Read as a column, it is the key column either way, and the new column is named where it is meant. """ - wider = {'maps.snapshot.alt': {'dim': 'snapshot'}} + wider = {'mappings.snapshot.alt': {'dim': 'snapshot'}} before = _dims('sum(p, over=snapshot, by=snapshot[rep])') assert _dims_with('sum(p, over=snapshot, by=snapshot[rep])', **wider) == before == {'snapshot', 'generator'} assert _dims_with('sum(p, over=snapshot, by=snapshot[alt])', **wider) == before, ( @@ -283,7 +283,7 @@ def test_a_lookup_carries_the_whole_key_and_what_the_operand_brings_beside_it(): def test_a_join_opens_an_axis_for_the_column_it_drops_and_the_sum_over_it_closes_it(): - """A map into its own dimension drops and adds one dimension, so the axis the join opens stands for the column. + """A mapping into its own dimension drops and adds one dimension, so the axis the join opens stands for the column. The dropped column's axis runs over `snapshot` and stands for the key column of the `snapshot` table, so it is not the dimension's own axis. The sum over @@ -445,7 +445,7 @@ def test_two_joined_columns_do_not_share_a_dimension(expr, diag): @pytest.mark.parametrize( - ('expr', 'maps', 'expected'), + ('expr', 'mappings', 'expected'), [ pytest.param( 'at(zone_cap, by=gen_zone[zone])', @@ -461,7 +461,7 @@ def test_two_joined_columns_do_not_share_a_dimension(expr, diag): ), ], ) -def test_a_lookup_joins_on_the_key_columns_the_operand_carries_and_the_read_does_not_match(expr, maps, expected): +def test_a_lookup_joins_on_the_key_columns_the_operand_carries_and_the_read_does_not_match(expr, mappings, expected): """`at` joins on each key column over a dim the operand carries, unless the column it reads already matches that dim. `at(load, by=diag, over=rep, into=generator)` once joined on the key's @@ -469,7 +469,7 @@ def test_a_lookup_joins_on_the_key_columns_the_operand_carries_and_the_read_does call names only the column it reads now, so the key's `snapshot` arrives and the result is `load` read at `rep(t, g)` for every `(t, g)`. """ - assert _dims_with(expr, **{'maps.gen_zone': maps}) == frozenset(expected), ( + assert _dims_with(expr, **{'mappings.gen_zone': mappings}) == frozenset(expected), ( 'the frame is the operand less the dim read, plus the key' ) @@ -608,10 +608,10 @@ def test_a_zero_step_vacates_nothing_and_needs_no_edge(self): pytest.param('p_max > 0', {'generator'}, id='a-parameter-through-its-own-dims'), pytest.param('snapshot == 0', {'snapshot'}, id='a-dimension-through-itself'), pytest.param('position(snapshot) == 0', {'snapshot'}, id='a-position-through-the-axis-it-counts'), - pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-map-through-the-dim-it-maps-out-of'), + pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-mapping-through-the-dim-it-mappings-out-of'), pytest.param('gen_zone[zone] == "z1"', {'generator', 'snapshot'}, id='a-two-key-relation-through-both-keys'), pytest.param('gen_zone', {'generator', 'snapshot'}, id='a-bare-two-key-relation-the-same'), - pytest.param('snapshot[rep] == 3', {'snapshot'}, id='a-map-into-its-own-dimension-through-its-key'), + pytest.param('snapshot[rep] == 3', {'snapshot'}, id='a-mapping-into-its-own-dimension-through-its-key'), pytest.param( 'position(snapshot, within=snapshot[rep]) == 0', {'snapshot'}, id='a-position-within-a-representative' ), @@ -665,8 +665,8 @@ def test_the_frame_check_and_the_reading_walk_the_same_leaves(namespace): pytest.param('p_max > 0', {'p_max'}, id='a-parameter-comparison-names-the-parameter'), pytest.param('cost', {'cost'}, id='a-parameter-bare-names-the-parameter'), pytest.param('p', {'p'}, id='a-variable-bare-names-the-variable'), - pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-map-comparison-names-its-subject'), - pytest.param('generator[bus]', {'generator'}, id='a-map-test-names-its-subject'), + pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-mapping-comparison-names-its-subject'), + pytest.param('generator[bus]', {'generator'}, id='a-mapping-test-names-its-subject'), pytest.param('gen_zone', {'gen_zone'}, id='a-relation-bare-names-the-relation'), pytest.param('snapshot == 0', set(), id='a-dimension-names-nothing-it-is-a-coordinate'), pytest.param('position(snapshot) == 0', set(), id='a-position-names-nothing'), @@ -693,9 +693,9 @@ def test_a_condition_names_the_entries_its_leaves_test(namespace, condition, exp pytest.param('generator[b0] != generator[b1]', {'generator'}, id='one-subject-is-named-once'), ], ) -def test_names_read_takes_both_sides_of_a_map_pair(condition, expected): - """The one leaf that can name two entries — two maps compared row by row on the key their subjects share.""" - home_of = {'relations.home_of': {'dims': ['generator', 'snapshot']}, 'maps.home_of': {'zone': {'dim': 'zone'}}} +def test_names_read_takes_both_sides_of_a_mapping_pair(condition, expected): + """The one leaf that can name two entries — two mappings compared row by row on the key their subjects share.""" + home_of = {'relations.home_of': {'dims': ['generator', 'snapshot']}, 'mappings.home_of': {'zone': {'dim': 'zone'}}} where = where_of(condition, Namespace(_spec(**home_of)), 'test') assert where is not None, 'a condition the connectives cannot settle survives the fold' @@ -981,8 +981,8 @@ def test_a_condition_on_a_relation_states_its_key_dims_sorted_by_name(entry): **{ 'relations.zone_of': keyed_backwards, 'relations.home_of': keyed_backwards, - 'maps.zone_of': {'zone': {'dim': 'zone'}}, - 'maps.home_of': {'zone': {'dim': 'zone'}}, + 'mappings.zone_of': {'zone': {'dim': 'zone'}}, + 'mappings.home_of': {'zone': {'dim': 'zone'}}, } ) patch = {f'variables.p.{key}': value for key, value in entry.items()} diff --git a/tests/test_exclusivity.py b/tests/test_exclusivity.py index 2f9947f5f..74db227fb 100644 --- a/tests/test_exclusivity.py +++ b/tests/test_exclusivity.py @@ -36,7 +36,7 @@ 'storage': {'ordered': True}, 'period': {'dtype': 'int'}, }, - 'maps': {'snapshot': {'period': {'dim': 'period'}}}, + 'mappings': {'snapshot': {'period': {'dim': 'period'}}}, 'parameters': { 'cyclic': {'dims': ['storage'], 'dtype': 'bool'}, 'committable': {'dims': ['storage'], 'dtype': 'bool'}, @@ -50,16 +50,16 @@ } -#: A line has one label in each map, or none, and each comparison on `line[...]` reads that one row. +#: A line has one label in each mapping, or none, and each comparison on `line[...]` reads that one row. NETWORK: dict[str, Any] = { 'dimensions': {'line': {}, 'bus': {}}, - 'maps': {'line': {'bus0': {'dim': 'bus'}, 'bus1': {'dim': 'bus'}}}, + 'mappings': {'line': {'bus0': {'dim': 'bus'}, 'bus1': {'dim': 'bus'}}}, 'variables': {'flow': {'dims': ['line']}}, 'constraints': {'c': {'dims': ['line'], 'expression': 'flow >= 0'}}, } #: The same network with a third end, so two pairs of columns can share one. -THREE_ENDS: dict[str, Any] = varied(NETWORK, **{'maps.line.bus2': {'dim': 'bus'}}) +THREE_ENDS: dict[str, Any] = varied(NETWORK, **{'mappings.line.bus2': {'dim': 'bus'}}) @pytest.fixture(scope='module') @@ -418,15 +418,15 @@ def test_under_a_reading_a_missing_row_compares_false(self, reading: str): class TestAMapWithNoLabel: - """A comparison on a map is false where the map gives the row no label, whatever its operator.""" + """A comparison on a mapping is false where the mapping gives the row no label, whatever its operator.""" - def test_a_map_of_a_numbered_dimension_compares_a_label(self): - """A map read the dtype of its subject, so a label of `snapshot[season]` reached the cells of an int. + def test_a_mapping_of_a_numbered_dimension_compares_a_label(self): + """A mapping read the dtype of its subject, so a label of `snapshot[season]` reached the cells of an int. The prover then asserted that a label or a date reached a magnitude, and the file did not load. """ - spec = to_spec(varied(STORAGE, **{'dimensions.season': {}, 'maps.snapshot.season': {'dim': 'season'}})) + spec = to_spec(varied(STORAGE, **{'dimensions.season': {}, 'mappings.snapshot.season': {'dim': 'season'}})) cases = {'winter': "snapshot[season] == 'winter'", 'rest': "snapshot[season] != 'winter'"} assert refusals(spec, cases) == [], 'a label is equal to winter or not, whatever dtype the subject has' @@ -436,12 +436,12 @@ def test_a_map_of_a_numbered_dimension_compares_a_label(self): pytest.param( {'same': 'not line[bus0] == line[bus1]', 'different': 'not line[bus0] != line[bus1]'}, 'line[bus0] has a label, line[bus1] has no label', - id='two-maps', + id='two-mappings', ), pytest.param( {'north': "not line[bus0] == 'north'", 'elsewhere': "not line[bus0] != 'north'"}, 'line[bus0] has no label', - id='a-map-and-a-label', + id='a-mapping-and-a-label', ), ], ) @@ -459,18 +459,20 @@ def test_the_negations_of_two_complements_both_claim_a_missing_label(self, cases ('cases', 'model'), [ pytest.param({'kept': "line[bus0] != 'north'", 'left_out': 'not line[bus0]'}, NETWORK, id='a-label'), - pytest.param({'kept': 'line[bus0] != line[bus1]', 'left_out': 'not line[bus0]'}, NETWORK, id='two-maps'), + pytest.param( + {'kept': 'line[bus0] != line[bus1]', 'left_out': 'not line[bus0]'}, NETWORK, id='two-mappings' + ), pytest.param( {'later': 'snapshot[period] != 2030', 'left_out': 'not snapshot[period]'}, STORAGE, id='a-number' ), ], ) def test_a_comparison_and_the_missing_label_are_apart(self, cases: dict[str, str], model: dict[str, Any]): - """A comparison is true only where the map gives a label, so `not subject[map]` excludes it. + """A comparison is true only where the mapping gives a label, so `not subject[mapping]` excludes it. - The prover read the label a comparison needs and the label the map + The prover read the label a comparison needs and the label the mapping test asks for as two facts, and refused the pair with a witness where - the map gives no label and still holds a value. + the mapping gives no label and still holds a value. """ assert refusals(to_spec(model), cases) == [], 'no row both has a label and has none' @@ -480,12 +482,12 @@ def test_a_comparison_and_the_missing_label_are_apart(self, cases: dict[str, str pytest.param( {'loop': 'line[bus0] == line[bus1]', 'north': "line[bus0] == 'north'"}, "where line[bus0] vs line[bus1] is equal, line[bus0] is 'north'.", - id='a-map-value-says-the-label-exists', + id='a-mapping-value-says-the-label-exists', ), pytest.param( {'listed': 'line[bus0]', 'again': 'line[bus0]'}, 'where line[bus0] has a label.', - id='the-map-test-says-it', + id='the-mapping-test-says-it', ), ], ) @@ -498,7 +500,7 @@ def test_a_label_both_cases_read_is_still_found(self, cases: dict[str, str], wit class TestTwoPairsOfColumns: """Each pair of columns is its own fact: a line can have `bus0 == bus1` and `bus0 != bus2` at once.""" - def test_two_pairs_that_share_a_map_both_claim_a_line(self): + def test_two_pairs_that_share_a_mapping_both_claim_a_line(self): """Both cases claim a line whose `bus0` is its `bus1` but not its `bus2`. The prover keyed a comparison of two columns by the two subject names diff --git a/tests/test_expansion.py b/tests/test_expansion.py index e5d3d33a9..b4c954dc0 100644 --- a/tests/test_expansion.py +++ b/tests/test_expansion.py @@ -295,12 +295,12 @@ def test_macro_collisions_rejected(patch, match): ), pytest.param( {'grouped': {'args': ['x'], 'template': 'sum(x, over=g, by=[nope, also])'}}, - r"Macro 'grouped'.*sum\(by=\.\.\.\) takes columns of one subject. Write subject\[map\]", + r"Macro 'grouped'.*sum\(by=\.\.\.\) takes columns of one subject. Write subject\[mapping\]", id='a-list-of-names-for-columns', ), pytest.param( {'grouped': {'args': ['x', 'a', 'b'], 'template': 'sum(x, over=a, by=nope[b])'}}, - r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a relation, a dimension with maps or a formal argument of this macro", + r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a relation, a dimension with mappings or a formal argument of this macro", id='a-typo-in-a-relation-beside-formal-columns', ), pytest.param( @@ -341,7 +341,7 @@ def test_an_entry_nothing_reads_is_held_to_the_rules_a_use_is(): [ pytest.param('x * tag', "Macro 'm': 'tag' is declared dtype: str", id='a-label-parameter-as-a-value'), pytest.param( - 'sum(x, over=g, by=g[nope])', r"names \['nope'\], which is no map of 'g'", id='a-typo-in-a-column' + 'sum(x, over=g, by=g[nope])', r"names \['nope'\], which is no mapping of 'g'", id='a-typo-in-a-column' ), ], ) @@ -371,7 +371,7 @@ def test_an_unknown_operator_names_no_construct_the_language_lacks(): pytest.param(['x', 'e'], 'shift(x, along=g, offset=1, edge=e)', id='an-edge'), pytest.param(['row'], 'dual(row)', id='a-constraint'), pytest.param(['x', 'rel', 'a', 'b'], 'sum(x, over=a, by=rel[b])', id='a-relation-and-its-columns'), - pytest.param(['x', 'a', 'b'], 'sum(x, over=a, by=g[b])', id='the-maps-of-a-declared-subject'), + pytest.param(['x', 'a', 'b'], 'sum(x, over=a, by=g[b])', id='the-mappings-of-a-declared-subject'), pytest.param( ['x', 'd'], 'shift(x, along=d, offset=1, within=g[h])', id='the-dimension-a-partition-steps-along' ), @@ -411,7 +411,7 @@ def test_a_call_binding_the_dimension_a_partition_steps_along_builds_it(): ns = Namespace(spec_of(SMALL_MODEL, macros={'m': {'args': ['x', 'd'], 'template': template}})) node = expression_of('m(p, g)', ns, 'expression') assert isinstance(node, Translate) and node.along == 'g' - assert node.partition is not None and node.partition.name == 'g', 'the map is read once along= is bound' + assert node.partition is not None and node.partition.name == 'g', 'the mapping is read once along= is bound' def test_a_named_expression_is_resolved_once_however_many_uses(monkeypatch): @@ -443,7 +443,7 @@ def test_a_use_of_a_refused_named_expression_names_it_rather_than_repeating_its_ GROUPED_MODEL = { 'dimensions': {'generator': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, - 'maps': {'generator': {'bus': {'dim': 'bus'}}}, + 'mappings': {'generator': {'bus': {'dim': 'bus'}}}, 'parameters': {'cap': {'dims': ['bus']}}, 'variables': {'p': {'dims': ['generator']}}, 'objective': {'sense': 'minimize', 'expression': 'sum(p)'}, @@ -479,7 +479,7 @@ def test_a_selection_bound_into_arithmetic_is_refused(): 'constraints': {'k': {'dims': ['generator'], 'expression': 'plus(p, cols=generator[bus]) <= 1'}}, } with pytest.raises( - LanguageError, match=r'generator\[bus\] names a map of a subject, which is allowed only as an operator' + LanguageError, match=r'generator\[bus\] names a mapping of a subject, which is allowed only as an operator' ): to_spec(model) diff --git a/tests/test_given.py b/tests/test_given.py index 0424e2ad4..6a85521c4 100644 --- a/tests/test_given.py +++ b/tests/test_given.py @@ -26,7 +26,7 @@ SUPPLY = { 'description': 'A fleet of generators, each on one port.', 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'generator': {'dtype': 'str'}}, - 'maps': {'generator': {'port': {'dim': 'port'}}}, + 'mappings': {'generator': {'port': {'dim': 'port'}}}, 'given': {'variables': {'flow': {'dims': ['snapshot', 'port'], 'description': 'what a port puts into its bus'}}}, 'parameters': {'gen_cost': {'dims': ['generator']}, 'gen_p_max': {'dims': ['generator']}}, 'variables': {'gen_p': {'dims': ['snapshot', 'generator'], 'bounds': {'lower': 0, 'upper': 'gen_p_max'}}}, @@ -42,7 +42,7 @@ #: The fragment that introduces `flow`, with the bounds and the balance that go with it. SURFACE = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'port': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, - 'maps': {'port': {'bus': {'dim': 'bus'}}}, + 'mappings': {'port': {'bus': {'dim': 'bus'}}}, 'variables': {'flow': {'dims': ['snapshot', 'port'], 'bounds': {'lower': -1000, 'upper': 1000}}}, 'constraints': {'balance': {'dims': ['snapshot', 'bus'], 'expression': 'sum(flow, over=port, by=port[bus]) == 0'}}, } @@ -480,7 +480,7 @@ def test_the_advice_names_a_given_parameter_as_data_a_consumer_binds(): #: A component file that defines the injection. INJECTOR = { 'dimensions': {'snapshot': {'dtype': 'int'}, 'bus': {'dtype': 'str'}, 'generator': {'dtype': 'str'}}, - 'maps': {'generator': {'bus': {'dim': 'bus'}}}, + 'mappings': {'generator': {'bus': {'dim': 'bus'}}}, 'parameters': {'load': {'dims': ['snapshot', 'bus']}}, 'variables': {'gen_p': {'dims': ['snapshot', 'generator'], 'bounds': {'lower': 0}}}, 'expressions': {'injection': {'expression': 'sum(gen_p, over=generator, by=generator[bus]) - load'}}, @@ -545,7 +545,7 @@ def test_a_definition_over_a_dimension_the_reader_does_not_state_is_refused(): #: An injector whose output does not vary by snapshot: its injection is over `bus` alone. FLAT_INJECTOR = { 'dimensions': {'bus': {'dtype': 'str'}, 'generator': {'dtype': 'str'}}, - 'maps': {'generator': {'bus': {'dim': 'bus'}}}, + 'mappings': {'generator': {'bus': {'dim': 'bus'}}}, 'variables': {'gen_p': {'dims': ['generator'], 'bounds': {'lower': 0}}}, 'expressions': {'injection': {'expression': 'sum(gen_p, over=generator, by=generator[bus])'}}, 'objective': {'sense': 'minimize', 'expression': 'sum(gen_p)'}, diff --git a/tests/test_lowering.py b/tests/test_lowering.py index fd0067258..eb04785a8 100644 --- a/tests/test_lowering.py +++ b/tests/test_lowering.py @@ -83,20 +83,20 @@ 'constraints': {'c': {'dims': [], 'expression': 'sum(p, over=g) >= 1'}}, } -#: The table of `g` in `SHAPES_MODEL`: a row per `g`, with a column per map. +#: The table of `g` in `SHAPES_MODEL`: a row per `g`, with a column per mapping. G = Relation((('g', 'g'), ('h', 'h'), ('z', 'z')), ('g',)) -#: `g[h]` as `sum` joins it: joined on `g`, grouped by the map, no column of `g` left unnamed. +#: `g[h]` as `sum` joins it: joined on `g`, grouped by the mapping, no column of `g` left unnamed. G_JOIN = JoinColumns('g', G, ('g',), ('h',)) -#: `fixtures.SMALL_MODEL` plus a second map and an integer +#: `fixtures.SMALL_MODEL` plus a second mapping and an integer #: offset. Which node a construct becomes is mostly a claim about the dim it #: joins on and the dim it groups by, and stating that needs a third dimension -#: and two maps of one subject. +#: and two mappings of one subject. SHAPES_MODEL = varied( SMALL_MODEL, **{ 'dimensions.z': {'dtype': 'str'}, - 'maps.g.z': {'dim': 'z'}, + 'mappings.g.z': {'dim': 'z'}, 'parameters.lead': {'dims': [], 'dtype': 'int'}, }, ) @@ -285,7 +285,7 @@ def test_a_lowered_where_is_a_mask_that_answers_from_its_root(dispatch_program): {'g', 'h'}, 2, 2, - id='a-map-is-read-at-its-subject-and-a-position-at-its-own', + id='a-mapping-is-read-at-its-subject-and-a-position-at-its-own', ), pytest.param('p', 'k > 0', set(), 1, 1, id='a-scalar-parameter-is-read-at-no-coordinate'), pytest.param( @@ -431,7 +431,7 @@ def test_a_comparison_of_expressions_lowers_to_program_expressions_on_both_sides assert mask is not None and isinstance(mask.root, ExpressionComparison) assert isinstance(mask.root.right, Add) and isinstance(mask.root.right.left, Join) assert mask.names_read == frozenset({'c', 'zc', 'g'}), ( - 'the map a lookup and a partition read through is data the consumer attaches too' + 'the mapping a lookup and a partition read through is data the consumer attaches too' ) @@ -474,8 +474,8 @@ def test_a_translated_condition_keeps_what_it_reads_in_reach(): assert sorted(mask.dims) == ['g'] -def test_a_condition_read_through_a_map_is_lowered_and_keeps_the_map_in_reach(): - """The comparison under the read is rebuilt, and the map is data the consumer attaches as well as the operand.""" +def test_a_condition_read_through_a_mapping_is_lowered_and_keeps_the_mapping_in_reach(): + """The comparison under the read is rebuilt, and the mapping is data the consumer attaches as well as the operand.""" program = to_spec( varied( SHAPES_MODEL, @@ -560,7 +560,7 @@ def test_an_assumption_refuses_in_the_words_the_file_wrote(): def test_a_cased_side_reads_the_data_its_regions_are_decided_by(): - """`names_read` promised every parameter and map the sides read, and dropped the + """`names_read` promised every parameter and mapping the sides read, and dropped the `when:` of a cased entry: the walk descends a `Cases` by its values alone.""" program = to_spec( varied( @@ -578,7 +578,7 @@ def test_a_cased_side_reads_the_data_its_regions_are_decided_by(): where = program.variables['p'].where assert where is not None assert where.names_read == frozenset({'c', 'k', 'flag', 'g'}), ( - 'the flag and the map decide which region applies, so the consumer attaches them too' + 'the flag and the mapping decide which region applies, so the consumer attaches them too' ) @@ -649,7 +649,7 @@ def test_a_power_resolves_to_a_node_of_its_own(dispatch_spec): partition=Partition('g', G, 'g', ('h',), ()), dims=('g',), ), - id='a-translation-stops-at-the-edges-of-the-map-it-names', + id='a-translation-stops-at-the-edges-of-the-mapping-it-names', ), pytest.param( 'sum_back(p, along=g, window=3)', @@ -671,7 +671,7 @@ def test_a_power_resolves_to_a_node_of_its_own(dispatch_spec): partition=Partition('g', G, 'g', ('h',), ()), dims=('g',), ), - id='a-window-stops-at-the-edges-of-the-map-it-names', + id='a-window-stops-at-the-edges-of-the-mapping-it-names', ), ], ) @@ -680,19 +680,19 @@ def test_a_construct_resolves_to_its_node(shapes_spec, expression, expected): assert resolved(expression, shapes_spec) == expected, 'the whole frozen node, so no field is asserted by omission' -def test_a_partition_keeps_its_group_when_the_subject_gains_a_map(): - """`within=` is what the call groups by, so a calendar that gains a `week` map regroups no `shift` through it (#538). +def test_a_partition_keeps_its_group_when_the_subject_gains_a_mapping(): + """`within=` is what the call groups by, so a calendar that gains a `week` mapping regroups no `shift` through it (#538). - With `within=` optional, an omitted one meant every map, and the + With `within=` optional, an omitted one meant every mapping, and the same call grouped by `('day',)` on one calendar and `('day', 'week')` on the next. """ grouping = {} - for maps in ({'day': {'dim': 'day'}}, {'day': {'dim': 'day'}, 'week': {'dim': 'week'}}): + for mappings in ({'day': {'dim': 'day'}}, {'day': {'dim': 'day'}, 'week': {'dim': 'week'}}): program = to_spec( { 'dimensions': {'hour': {'dtype': 'int', 'ordered': True}, 'day': {}, 'week': {}}, - 'maps': {'hour': maps}, + 'mappings': {'hour': mappings}, 'variables': {'p': {'dims': ['hour']}}, 'constraints': { 'k': { @@ -702,9 +702,9 @@ def test_a_partition_keeps_its_group_when_the_subject_gains_a_map(): }, } ).program - grouping[tuple(maps)] = _partition_of(program.constraints['k']).grouped + grouping[tuple(mappings)] = _partition_of(program.constraints['k']).grouped assert grouping == {('day',): ('day',), ('day', 'week'): ('day',)}, ( - 'the group is the maps the call named, on both calendars' + 'the group is the mappings the call named, on both calendars' ) @@ -721,7 +721,7 @@ def test_a_relation_lowers_with_the_join_each_call_names(): { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'generator': {'ordered': True}, 'zone': {}}, 'relations': {'zone_of': {'dims': ['generator', 'snapshot'], 'missing': 'absent'}}, - 'maps': {'zone_of': {'zone': {'dim': 'zone'}}}, + 'mappings': {'zone_of': {'zone': {'dim': 'zone'}}}, 'parameters': {'price': {'dims': ['snapshot', 'zone']}}, 'variables': { 'p': {'dims': ['snapshot', 'generator'], 'where': "zone_of AND zone_of[zone] == 'A'"}, @@ -806,14 +806,14 @@ def test_a_relation_lowers_with_the_join_each_call_names(): ('variable', 'entry', 'atom'), [ pytest.param('q', {'where': 'link'}, RelationDefined('link', ('g', 'h')), id='a-bare-relation-tests-a-row'), - pytest.param('p', {'where': 'g[h]'}, RelationDefined('g', ('g',), 'h'), id='a-map-alone-tests-a-label'), + pytest.param('p', {'where': 'g[h]'}, RelationDefined('g', ('g',), 'h'), id='a-mapping-alone-tests-a-label'), ], ) def test_a_condition_tests_a_row_or_a_label_by_how_it_is_written(variable, entry, atom): - """A relation's bare name asks for a row, and `subject[map]` alone asks whether the map gives the row a label.""" + """A relation's bare name asks for a row, and `subject[mapping]` alone asks whether the mapping gives the row a label.""" patch = { 'relations.link': {'dims': ['g', 'h'], 'missing': 'absent'}, - 'maps.g.h': {'dim': 'h', 'missing': 'absent'}, + 'mappings.g.h': {'dim': 'h', 'missing': 'absent'}, **{f'variables.{variable}.{key}': value for key, value in entry.items()}, } assert to_spec(varied(SMALL_MODEL, **patch)).program.variables[variable].where == Mask(atom) @@ -892,23 +892,23 @@ def test_walk_is_the_node_column_of_walk_regions(): def test_a_relation_is_declared_as_the_file_declares_it(): - """One table per subject, keyed by its name: a relation's rows, and a dimension's labels once it has maps.""" + """One table per subject, keyed by its name: a relation's rows, and a dimension's labels once it has mappings.""" program = to_spec( varied( TINY, dimensions={'g': {}, 'bus': {}, 'season': {}}, relations={'link': {'dims': ['g', 'bus'], 'missing': 'absent'}}, - maps={'g': {'season': {'dim': 'season'}, 'bus': {'dim': 'bus', 'missing': 'absent'}}}, + mappings={'g': {'season': {'dim': 'season'}, 'bus': {'dim': 'bus', 'missing': 'absent'}}}, ) ).program assert program.relations == { 'g': Relation((('g', 'g'), ('bus', 'bus'), ('season', 'season')), ('g',), partial=('bus',)), 'link': Relation((('bus', 'bus'), ('g', 'g')), ('bus', 'g'), missing='absent'), - }, 'a table per subject, its own columns first, then one column per map' - assert program.relations['g'].values == ('bus', 'season'), 'the maps are what a row of the subject determines' - assert program.relations['link'].values == (), 'a relation with no maps determines nothing' - assert program.dimensions['g'] == Dimension(dtype='str'), 'a dimension carries its dtype and no map' + }, 'a table per subject, its own columns first, then one column per mapping' + assert program.relations['g'].values == ('bus', 'season'), 'the mappings are what a row of the subject determines' + assert program.relations['link'].values == (), 'a relation with no mappings determines nothing' + assert program.dimensions['g'] == Dimension(dtype='str'), 'a dimension carries its dtype and no mapping' @pytest.mark.parametrize('ordered', [pytest.param(True, id='ordered'), pytest.param(False, id='unordered')]) diff --git a/tests/test_parser.py b/tests/test_parser.py index a095f528b..5f2c9ead0 100644 --- a/tests/test_parser.py +++ b/tests/test_parser.py @@ -326,7 +326,7 @@ def test_a_relation_column_is_named_in_brackets(): ) with pytest.raises(SchemaError, match='Cannot parse the condition'): parse_condition('ends[bus0] + 1 > 0') - with pytest.raises(SchemaError, match=r'Compare each map on its own: ends\[bus0\] == … AND ends\[bus1\] == …'): + with pytest.raises(SchemaError, match=r'Compare each mapping on its own: ends\[bus0\] == … AND ends\[bus1\] == …'): parse_condition("ends[bus0, bus1] == 'x'") diff --git a/tests/test_piecewise.py b/tests/test_piecewise.py index cafd5c33d..e0f37cf30 100644 --- a/tests/test_piecewise.py +++ b/tests/test_piecewise.py @@ -838,7 +838,7 @@ def test_a_where_the_block_cannot_read_is_refused(patch, match): def test_a_where_over_a_dim_a_link_walks_into_is_not_sent_to_dims(): """The refusal said to add `flow` to `dims:`, and the walk into `flow` was then refused for that very edit.""" - with pytest.raises(LanguageError, match=r"which link 'power' adds through the map it walks") as refused: + with pytest.raises(LanguageError, match=r"which link 'power' adds through the mapping it walks") as refused: spec_of( WALKED, **{'parameters.on_flow': {'dims': ['flow'], 'dtype': 'bool'}, 'piecewise.coupling.where': 'on_flow'}, @@ -884,7 +884,7 @@ def test_a_model_written_out_and_read_back_asks_its_conditions_only_where_a_curv #: fluxopt's converter: one curve per generator, tying however many flows the -#: map gives it. The link that carries `flow` walks the map `flow[generator]` +#: mapping gives it. The link that carries `flow` walks the mapping `flow[generator]` #: from the curve's `generator` to its own `flow`. WALKED = { 'dimensions': { @@ -893,7 +893,7 @@ def test_a_model_written_out_and_read_back_asks_its_conditions_only_where_a_curv 'flow': {'dtype': 'str'}, 'bp': {'dtype': 'int', 'ordered': True}, }, - 'maps': {'flow': {'generator': {'dim': 'generator'}}}, + 'mappings': {'flow': {'generator': {'dim': 'generator'}}}, 'parameters': { 'load': {'dims': ['snapshot']}, 'bp_power': {'dims': ['flow', 'bp']}, @@ -918,7 +918,7 @@ def test_a_model_written_out_and_read_back_asks_its_conditions_only_where_a_curv } #: The values tables of the walked curve under a ragged ``where:``, which stop where the curve stops. WALKED_RAGGED = {'parameters.bp_power.missing': 0, 'parameters.bp_fuel.missing': 0} -#: The walked link alone, which the map gives its arity. +#: The walked link alone, which the mapping gives its arity. POWER_ONLY = { 'piecewise.coupling.links': {'power': {'expression': 'power', 'values': 'bp_power', 'by': 'flow[generator]'}}, 'objective.expression': 'sum(power)', @@ -975,7 +975,7 @@ def _walk(**written: object) -> dict[str, object]: def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: """The `power` link walked through `generator_of`, a relation over *dims* that maps each row to a generator.""" - return {'relations.generator_of': {'dims': dims}, 'maps.generator_of.generator': {'dim': 'generator'}} | _walk( + return {'relations.generator_of': {'dims': dims}, 'mappings.generator_of.generator': {'dim': 'generator'}} | _walk( by='generator_of[generator]' ) @@ -984,21 +984,21 @@ def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: ('patch', 'match'), [ pytest.param({'piecewise.coupling.dims': None}, 'with one curve per coordinate', id='a-block-without-dims'), - pytest.param(_walk(by='flow'), 'is not a subject with its maps in brackets', id='a-walk-naming-no-column'), - pytest.param(_walk(by='flow[]'), 'is not a subject with its maps in brackets', id='an-empty-column-list'), + pytest.param(_walk(by='flow'), 'is not a subject with its mappings in brackets', id='a-walk-naming-no-column'), + pytest.param(_walk(by='flow[]'), 'is not a subject with its mappings in brackets', id='an-empty-column-list'), pytest.param( _walk(by='flow[generator]) * (2'), - 'is not a subject with its maps in brackets', + 'is not a subject with its mappings in brackets', id='a-walk-closing-the-call-early', ), pytest.param( _walk(by='flow[generator]) + (power'), - 'is not a subject with its maps in brackets', + 'is not a subject with its mappings in brackets', id='a-walk-adding-a-term', ), pytest.param( _walk(by='flow[snapshot]'), - r"at\(by=flow\[snapshot\]\) names \['snapshot'\], which is no map of 'flow'", + r"at\(by=flow\[snapshot\]\) names \['snapshot'\], which is no mapping of 'flow'", id='a-walk-naming-a-column-the-relation-lacks', ), pytest.param( @@ -1023,7 +1023,7 @@ def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: id='a-walk-into-a-dim-the-block-has', ), pytest.param( - {'maps.bp.generator': {'dim': 'generator'}} | _walk(by='bp[generator]'), + {'mappings.bp.generator': {'dim': 'generator'}} | _walk(by='bp[generator]'), r"link 'power': by: bp adds no dimension", id='a-walk-into-the-breakpoint-dim', ), @@ -1061,8 +1061,8 @@ def test_a_walked_block_the_language_cannot_read_is_refused(patch, match): spec_of(WALKED, **patch) -#: A map into the breakpoint dim that a walk can name. -SLOT_OF = {'maps.flow.slot': {'dim': 'bp'}} +#: A mapping into the breakpoint dim that a walk can name. +SLOT_OF = {'mappings.flow.slot': {'dim': 'bp'}} @pytest.mark.parametrize( @@ -1136,7 +1136,7 @@ def test_a_link_that_only_gains_a_dimension_is_refused_and_names_the_walk(): 'piecewise.coupling.links.rate': ['rate', 'bp_rate'], }, ) - with pytest.raises(LanguageError, match=r'look the curve up through a map with by: \[\]'): + with pytest.raises(LanguageError, match=r'look the curve up through a mapping with by: \[\]'): spec_of(model) @@ -1252,7 +1252,7 @@ def test_a_gate_over_fewer_dims_than_the_block_switches_each_curve_it_covers(): 'snapshot': {'dtype': 'int'}, 'bp': {'dtype': 'int', 'ordered': True}, }, - 'maps': {'converter': {'status_entity': {'dim': 'status_entity', 'missing': 'absent'}}}, + 'mappings': {'converter': {'status_entity': {'dim': 'status_entity', 'missing': 'absent'}}}, 'parameters': {'bp_p': {'dims': ['converter', 'bp']}, 'bp_fuel': {'dims': ['converter', 'bp']}}, 'variables': { 'running': {'dims': ['status_entity', 'snapshot'], 'domain': 'binary'}, @@ -1277,8 +1277,8 @@ def test_a_gate_over_fewer_dims_than_the_block_switches_each_curve_it_covers(): } #: The status only committable entities have, read as 0 elsewhere. COMMITTABLE = STATUS_MASKED | {'variables.running.missing': 0} -#: A map that gives every converter a status entity. -REFUSED = {'maps.converter.status_entity.missing': 'refused'} +#: A mapping that gives every converter a status entity. +REFUSED = {'mappings.converter.status_entity.missing': 'refused'} def test_a_gate_read_through_a_relation_switches_the_curves_it_maps_to(): @@ -1306,7 +1306,7 @@ def test_a_gate_read_through_a_relation_is_written_as_the_at_call_it_reads(): status_entity: {{dtype: str}} snapshot: {{dtype: int}} bp: {{dtype: int, ordered: true}} -maps: +mappings: converter: {{status_entity: {{ dim: status_entity }}}} parameters: bp_p: {{dims: [converter, bp]}} @@ -1378,11 +1378,11 @@ def test_a_gate_read_through_a_relation_is_ungated_only_where_its_read_may_be_ab def test_a_gate_read_through_a_relation_prints_as_the_read(): printed = typeset_line(spec_of(COMMITTED), 'curve', 'latex') assert r'\mathit{running}_{t,\mathrm{status\_entity}(c)}' in printed, 'the gate is read at each converter' - assert r'\text{otherwise}' in printed, 'and a converter the map gives no status entity is ungated' + assert r'\text{otherwise}' in printed, 'and a converter the mapping gives no status entity is ungated' #: What every malformed gate is refused with: the two shapes it may take. -SHAPES = r'Write activity: , or activity: at\(, by=\[\]\)\.' +SHAPES = r'Write activity: , or activity: at\(, by=\[\]\)\.' @pytest.mark.parametrize( @@ -1395,7 +1395,7 @@ def test_a_gate_read_through_a_relation_prints_as_the_read(): ), pytest.param( {'piecewise.curve.activity': 'at(running, by=converter)'}, - r"piecewise 'curve' activity: at\(by=converter\) names the subject and none of its maps", + r"piecewise 'curve' activity: at\(by=converter\) names the subject and none of its mappings", id='a-walk-naming-no-column', ), pytest.param( @@ -1405,7 +1405,7 @@ def test_a_gate_read_through_a_relation_prints_as_the_read(): ), pytest.param( {'piecewise.curve.activity': 'at(running, by=converter[snapshot])'}, - r"at\(by=converter\[snapshot\]\) names \['snapshot'\], which is no map of 'converter'", + r"at\(by=converter\[snapshot\]\) names \['snapshot'\], which is no mapping of 'converter'", id='a-walk-naming-a-column-the-relation-lacks', ), pytest.param( @@ -1415,7 +1415,7 @@ def test_a_gate_read_through_a_relation_prints_as_the_read(): ), pytest.param( {'piecewise.curve.activity': f'{RUNNING} * 2'}, - rf"activity: '{re.escape(RUNNING)} \* 2' is neither a variable nor a variable read through a map\. " + rf"activity: '{re.escape(RUNNING)} \* 2' is neither a variable nor a variable read through a mapping\. " + SHAPES, id='a-product', ), @@ -1440,7 +1440,7 @@ def test_a_gate_read_through_a_relation_is_held_to_the_rules_of_at(patch, match) [ pytest.param( 'at(running, by=converter)', - r"piecewise 'curve' activity: at\(by=converter\) names the subject and none of its maps", + r"piecewise 'curve' activity: at\(by=converter\) names the subject and none of its mappings", id='a-walk-naming-no-column', ), pytest.param(f'{RUNNING} * (2)', SHAPES, id='a-walk-closing-the-call-early'), @@ -1482,8 +1482,8 @@ def test_a_block_mask_reaches_a_walked_link_through_its_relation(): ) -#: The map of the walk, which may give a flow no generator. -PARTIAL = {'maps.flow.generator': {'dim': 'generator', 'missing': 'absent'}} +#: The mapping of the walk, which may give a flow no generator. +PARTIAL = {'mappings.flow.generator': {'dim': 'generator', 'missing': 'absent'}} @pytest.mark.parametrize( @@ -1519,7 +1519,7 @@ def test_a_walked_row_exists_only_where_its_relation_has_a_row(patch, where): 'dimensions': {name: {'dtype': 'str'} for name in ('cost_curve', 'effect', 'flow')} | {'bp': {'dtype': 'int', 'ordered': True}}, 'relations': {'cost_of': {'dims': ['flow', 'effect']}}, - 'maps': {'cost_of': {'cost_curve': {'dim': 'cost_curve'}}}, + 'mappings': {'cost_of': {'cost_curve': {'dim': 'cost_curve'}}}, 'parameters': { 'has_cost_curve': {'dims': ['cost_curve'], 'dtype': 'bool'}, 'size_bp': {'dims': ['cost_curve', 'bp']}, @@ -1637,7 +1637,7 @@ def test_a_mask_over_part_of_what_a_walk_joins_on_reaches_the_walked_row_through @pytest.mark.parametrize( ('model', 'read'), [ - pytest.param(WALKED, {'flow'}, id='no-mask-asks-only-where-the-map-reaches'), + pytest.param(WALKED, {'flow'}, id='no-mask-asks-only-where-the-mapping-reaches'), pytest.param(CURVED, {'curved', 'flow'}, id='a-mask-read-through'), ], ) @@ -1647,7 +1647,7 @@ def test_a_walked_links_breakpoints_are_asked_only_at_the_rows_it_reads_the_curv walked = assumptions['coupling_power_complete'] assert walked.holds.names_read == frozenset({'bp_power'}), 'the walked link asks for its own values alone' assert walked.where is not None and walked.where.dims == ('flow',), 'asked per flow the walk reaches' - assert walked.where.names_read == frozenset(read), 'the where reads the mask, if any, and the map' + assert walked.where.names_read == frozenset(read), 'the where reads the mask, if any, and the mapping' assert assumptions['coupling_complete'].holds.names_read == frozenset({'bp_fuel'}), ( 'the link on dims: keeps the block condition to itself' ) @@ -1956,7 +1956,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod 'snapshot': {'dtype': 'int'}, 'bp': {'dtype': 'int', 'ordered': True}, }, - 'maps': {'link_output': {'link': {'dim': 'link'}}}, + 'mappings': {'link_output': {'link': {'dim': 'link'}}}, 'parameters': { 'bp_in': {'dims': ['link_output', 'bp']}, 'bp_out': {'dims': ['link_output', 'bp']}, @@ -1983,7 +1983,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod #: A status per unit, which each generator reads through the unit it belongs to. UNITS = { 'dimensions.unit': {'dtype': 'str'}, - 'maps.generator.unit': {'dim': 'unit'}, + 'mappings.generator.unit': {'dim': 'unit'}, 'variables.status': {'dims': ['unit', 'snapshot'], 'domain': 'binary'}, 'piecewise.coupling.activity': 'at(status, by=generator[unit])', } @@ -2008,7 +2008,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod ), pytest.param( INCREMENTAL, - UNITS | {'maps.generator.unit': {'dim': 'unit', 'missing': 'absent'}}, + UNITS | {'mappings.generator.unit': {'dim': 'unit', 'missing': 'absent'}}, 'coupling_power', f'({FIRST}) AND ({UNIT_STATUS})', f'bp_power * ({UNIT_STATUS})', @@ -2016,7 +2016,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod ), pytest.param( INCREMENTAL, - UNITS | {'maps.flow.generator': {'dim': 'generator', 'missing': 'absent'}}, + UNITS | {'mappings.flow.generator': {'dim': 'generator', 'missing': 'absent'}}, 'coupling_power', f'(flow[generator]) AND ({FIRST})', f'bp_power * ({UNIT_STATUS})', @@ -2036,7 +2036,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod **COMMITTABLE, 'piecewise.curve.method': 'incremental', 'dimensions.hour': {'dtype': 'int'}, - 'maps.hour.snapshot': {'dim': 'snapshot'}, + 'mappings.hour.snapshot': {'dim': 'snapshot'}, 'variables.heat': {'dims': ['converter', 'hour']}, 'parameters.bp_heat': {'dims': ['converter', 'bp']}, 'piecewise.curve.links.heat': {'expression': 'heat', 'values': 'bp_heat', 'by': 'hour[snapshot]'}, diff --git a/tests/test_pypsa_collapses.py b/tests/test_pypsa_collapses.py index aa90a5471..8255a33d4 100644 --- a/tests/test_pypsa_collapses.py +++ b/tests/test_pypsa_collapses.py @@ -47,7 +47,7 @@ def _dims(entry: Any) -> list[str]: def test_every_standard_name_survives(): sections = { 'parameters': ALL.parameters, - 'maps': [f'{subject}[{name}]' for subject, maps in ALL.maps.items() for name in maps], + 'mappings': [f'{subject}[{name}]' for subject, mappings in ALL.mappings.items() for name in mappings], 'variables': ALL.variables, 'expressions': ALL.expressions, 'constraints': ALL.constraints, diff --git a/tests/test_renaming.py b/tests/test_renaming.py index a6c741a4e..6cfb0dcd2 100644 --- a/tests/test_renaming.py +++ b/tests/test_renaming.py @@ -26,7 +26,7 @@ UNIT = { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'unit': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, 'relations': {'unit_link': {'dims': ['bus', 'unit'], 'missing': 'absent'}}, - 'maps': {'unit': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, + 'mappings': {'unit': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, 'given': {'expressions': {'total_cost': {'dims': []}}}, 'parameters': { 'unit_p_max': {'dims': ['unit'], 'description': 'the most a unit_p reaches'}, @@ -97,7 +97,9 @@ def _as(prefix: str, dim: str) -> dict[str, str]: {'dims': ['bus', 'generator'], 'missing': 'absent'}, id='relation', ), - pytest.param(lambda s: s['maps'], {'generator': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, id='map'), + pytest.param( + lambda s: s['mappings'], {'generator': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, id='mapping' + ), pytest.param(lambda s: s['parameters']['Generator_cost']['dims'], ['generator', 'snapshot'], id='dims'), pytest.param(lambda s: s['variables']['Generator_p']['where'], 'Generator_on', id='where'), pytest.param(lambda s: s['variables']['Generator_p']['bounds']['upper'], 'Generator_p_max', id='bound'), @@ -116,7 +118,7 @@ def _as(prefix: str, dim: str) -> dict[str, str]: pytest.param( lambda s: s['expressions']['Generator_at_end'], 'sum(Generator_p, over=generator, by=generator[bus0])', - id='map-not-renamed', + id='mapping-not-renamed', ), pytest.param( lambda s: s['constraints']['Generator_ramp']['expression'], @@ -167,7 +169,7 @@ def test_a_quoted_label_spelt_like_a_renamed_name_stays(): """A label is data: `'gas'` names a coordinate, not the dimension `gas`.""" spec = { 'dimensions': {'gas': {'dtype': 'str'}, 'tech': {'dtype': 'str'}}, - 'maps': {'tech': {'gas': {'dim': 'gas'}}}, + 'mappings': {'tech': {'gas': {'dim': 'gas'}}}, 'conditions': {'fossil': {'condition': "tech[gas] == 'gas'"}}, } renamed = rename(spec, {'gas': 'fuel'}) @@ -302,7 +304,7 @@ def test_a_function_is_asked_once_for_each_name_the_spec_has(): pytest.param( {'unit': 'bus'}, r"rename gives the dimension 'unit' the name 'bus', which the dimension 'bus' already has\.", - id='a-dimension-with-maps-is-named-as-a-dimension', + id='a-dimension-with-mappings-is-named-as-a-dimension', ), pytest.param( {'unit_cost': 'Generator_cost', 'unit_p_max': 'Generator_cost'}, @@ -318,9 +320,9 @@ def test_a_function_is_asked_once_for_each_name_the_spec_has(): ), pytest.param( {'unit_cost': 'bus0'}, - r"rename changes 'unit_cost' to 'bus0', and 'bus0' is also a map of 'unit'\. " + r"rename changes 'unit_cost' to 'bus0', and 'bus0' is also a mapping of 'unit'\. " r'Give it another name in the file, or choose another name\.', - id='a-new-name-that-is-a-map', + id='a-new-name-that-is-a-mapping', ), pytest.param( {'unit_cost': 'unit_p_max'}.get, @@ -347,16 +349,16 @@ def test_a_map_the_spec_cannot_take_is_refused(names, message): @pytest.mark.parametrize( ('old', 'message'), [ - pytest.param('bus0', "'bus0' is also a map of 'line'", id='a-map'), + pytest.param('bus0', "'bus0' is also a mapping of 'line'", id='a-mapping'), pytest.param('from_bus', "'from_bus' is also a column of the relation 'corridor'", id='a-relation-column'), ], ) -def test_a_name_that_is_also_a_map_or_a_relation_column_is_refused(old, message): - """`line[bus0]` reads a map, and a rename of the parameter `bus0` would change it too.""" +def test_a_name_that_is_also_a_mapping_or_a_relation_column_is_refused(old, message): + """`line[bus0]` reads a mapping, and a rename of the parameter `bus0` would change it too.""" spec = { 'dimensions': {'line': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, 'relations': {'corridor': {'dims': {'from_bus': 'bus', 'to_bus': 'bus'}}}, - 'maps': {'line': {'bus0': {'dim': 'bus'}, 'bus1': {'dim': 'bus'}}}, + 'mappings': {'line': {'bus0': {'dim': 'bus'}, 'bus1': {'dim': 'bus'}}}, 'parameters': {'bus0': {'dims': ['bus']}, 'from_bus': {'dims': ['bus']}}, 'variables': {'flow': {'dims': ['line']}}, 'expressions': {'sent': 'sum(flow, over=line, by=line[bus0])'}, diff --git a/tests/test_separability.py b/tests/test_separability.py index 33ee6f7be..0ff91bdd4 100644 --- a/tests/test_separability.py +++ b/tests/test_separability.py @@ -30,7 +30,7 @@ 'zone': {'dtype': 'str'}, 'day': {'dtype': 'int'}, }, - 'maps': {'u': {'zone': {'dim': 'zone'}}, 'h': {'day': {'dim': 'day'}}}, + 'mappings': {'u': {'zone': {'dim': 'zone'}}, 'h': {'day': {'dim': 'day'}}}, 'parameters': { 'cost': {'dims': ['u']}, 'budget': {'dims': []}, @@ -99,7 +99,7 @@ def test_a_model_the_axis_ties_together_names_what_ties_it(patch, fragment): ], ) def test_a_reach_only_data_can_say_names_what_says_it(patch, reach): - """The verdict names the parameter or the subject of a map and what it stands as, rather + """The verdict names the parameter or the subject of a mapping and what it stands as, rather than refusing the model, so a driver holding the data knows what to read and `resolved` knows how to fold it.""" verdict = _verdict(**patch) @@ -131,7 +131,7 @@ def test_a_named_reach_resolves_to_the_lookahead_its_values_need(patch, least, a assert verdict.ahead == ahead, 'the value decides the lookahead, by its sign' -def test_resolving_keeps_the_static_reach_and_what_a_map_decides(): +def test_resolving_keeps_the_static_reach_and_what_a_mapping_decides(): verdict = _verdict( constraints={ 'fixed': {'dims': ['h', 'u'], 'expression': 'p >= shift(p, along=h, offset=-2, edge=0)'}, @@ -144,7 +144,7 @@ def test_resolving_keeps_the_static_reach_and_what_a_map_decides(): ).resolved({'width': -1}) assert verdict.ahead == 2, 'a folded value never narrows what the model reads on its own' assert verdict.undecided == (Reach("constraint 'grouped'", 'h[day]', 'partition'),), ( - 'a reach a map decides is not a value and stays undecided' + 'a reach a mapping decides is not a value and stays undecided' ) assert not verdict.windowable, 'so the axis is still not windowable' @@ -154,13 +154,13 @@ def test_resolving_a_name_nothing_waits_on_is_refused(): _verdict(**_rows('p >= shift(p, along=h, offset=width, edge=0)')).resolved({'depth': 0}) -def test_a_read_through_a_map_is_undecided_on_the_axis_it_reads(): - """`at(cap, by=u[zone])` reads `zone` at whatever coordinate the map - chooses, so how far that reaches along `zone` is the map's data to say.""" +def test_a_read_through_a_mapping_is_undecided_on_the_axis_it_reads(): + """`at(cap, by=u[zone])` reads `zone` at whatever coordinate the mapping + chooses, so how far that reaches along `zone` is the mapping's data to say.""" verdict = _verdict('zone', **_rows('p - at(cap, by=u[zone]) <= 0')) - assert not verdict.windowable and not verdict.coupled, 'undecided until the map is attached' + assert not verdict.windowable and not verdict.coupled, 'undecided until the mapping is attached' assert verdict.undecided == (Reach("constraint 'k'", 'u[zone]', 'coordinate'),), ( - 'the report names the subject whose map a driver has to read' + 'the report names the subject whose mapping a driver has to read' ) @@ -178,7 +178,7 @@ def test_a_sum_over_a_lookup_is_a_sum_and_a_lookup_not_a_grouping(): 'sums over u (use sum_back(window=n) for a rolling sum)' ], 'the sum over u is a plain sum, reported as one' assert program.separability['zone'].undecided == (Reach("constraint 'k'", 'u[zone]', 'coordinate'),), ( - 'the lookup under it still reads zone at a coordinate the map chooses' + 'the lookup under it still reads zone at a coordinate the mapping chooses' ) @@ -247,7 +247,7 @@ def test_a_grouping_that_sums_the_axis_away_couples_it(): assert verdict.coupled == { "constraint 'z'": 'groups u into zone (window that dimension instead, or cut only at the group edges)' }, 'the sum over the join is the grouping, reported once' - assert not verdict.undecided, 'the join under the sum is not also a lookup waiting on the map' + assert not verdict.undecided, 'the join under the sum is not also a lookup waiting on the mapping' def test_every_declared_axis_has_a_verdict_and_nothing_else_does(): diff --git a/tests/test_terms.py b/tests/test_terms.py index 18b6f4ef7..b546b4ba7 100644 --- a/tests/test_terms.py +++ b/tests/test_terms.py @@ -25,7 +25,7 @@ #: A generator fleet: what it puts in is its term. FLEET = { 'dimensions': {**BUS_DIMS, 'generator': {'dtype': 'str'}}, - 'maps': {'generator': {'bus': {'dim': 'bus'}}}, + 'mappings': {'generator': {'bus': {'dim': 'bus'}}}, 'variables': {'gen_p': {'dims': ['snapshot', 'generator'], 'bounds': {'lower': 0}}}, 'given': {'expressions': {'injection': {'dims': BUS_FRAME}}}, 'expressions': { @@ -49,7 +49,7 @@ #: A store, added in a second merge. STORAGE = { 'dimensions': {**BUS_DIMS, 'store': {'dtype': 'str'}}, - 'maps': {'store': {'bus': {'dim': 'bus'}}}, + 'mappings': {'store': {'bus': {'dim': 'bus'}}}, 'variables': {'store_p': {'dims': ['snapshot', 'store']}}, 'given': {'expressions': {'injection': {'dims': BUS_FRAME}}}, 'expressions': { diff --git a/tests/test_validation.py b/tests/test_validation.py index 327193671..5281abf8b 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -210,7 +210,7 @@ def test_an_unreferenced_nonlinear_entry_loads_and_is_reported(self): def _kwarg_model(expression: str, dims: list[str] | None = None) -> dict[str, Any]: - """A model over (snapshot, generator), with `generator[zone]` a map into `bus`. + """A model over (snapshot, generator), with `generator[zone]` a mapping into `bus`. `zone` deliberately targets a dim `p` does *not* carry: grouping into one it already has needs that dim twice, which is its own error. @@ -223,7 +223,7 @@ def _kwarg_model(expression: str, dims: list[str] | None = None) -> dict[str, An 'bus': {'dtype': 'str'}, 'generator': {'dtype': 'str'}, }, - 'maps': {'generator': {'zone': {'dim': 'bus'}}}, + 'mappings': {'generator': {'zone': {'dim': 'bus'}}}, 'parameters': {'load': {'dims': ['snapshot']}}, 'variables': {'p': {'dims': ['snapshot', 'generator']}}, 'constraints': {'c': {'dims': ['snapshot'] if dims is None else dims, 'expression': expression}}, @@ -322,14 +322,14 @@ class TestDimensionKwargs: pytest.param( 'sum(p, over=generator, by=bus) == load', ( - "'bus' is a dimension with no maps, and by= takes columns of a subject", + "'bus' is a dimension with no mappings, and by= takes columns of a subject", "Columns over 'bus': ['generator[zone]']", ), id='by-names-a-dimension', ), pytest.param( 'sum(p, over=generator, by=generatr[zone]) == load', - ("'generatr' is not a relation or a dimension with maps", "Did you mean 'generator'?"), + ("'generatr' is not a relation or a dimension with mappings", "Did you mean 'generator'?"), id='by-relation-typo', ), pytest.param( @@ -437,7 +437,7 @@ def test_a_where_comparison_must_match_the_declared_dtype(self, dtype, where, ma pytest.param( {'variables.p.where': "g[h] > 'b'"}, ["'g[h]' has dtype 'str', on which > is not defined", _NO_INEQUALITY_REWRITE], - id='map', + id='mapping', ), pytest.param( {'conditions.late': "g <= 'b'", 'variables.p.where': 'late'}, @@ -445,12 +445,12 @@ def test_a_where_comparison_must_match_the_declared_dtype(self, dtype, where, ma id='named-condition', ), pytest.param( - {'maps.g.h2': {'dim': 'h'}, 'variables.p.where': 'g[h] < g[h2]'}, + {'mappings.g.h2': {'dim': 'h'}, 'variables.p.where': 'g[h] < g[h2]'}, [ "compares two columns over 'h', of dtype 'str', on which < is not defined", 'Compare them with == or !=, or precompute the comparison as a boolean parameter.', ], - id='two-maps', + id='two-mappings', ), pytest.param( {'variables.p.where': 'flag > 0'}, @@ -485,8 +485,8 @@ class TestADimensionWithOneOf: pytest.param({'variables.r.where': "h == 'west'"}, id='a-dimension-equal-to-a-label'), pytest.param({'variables.r.where': "h != 'west'"}, id='a-dimension-not-equal-to-a-label'), pytest.param({'variables.r.where': 'h == west'}, id='an-unquoted-label'), - pytest.param({'variables.p.where': "g[h] == 'west'"}, id='a-map-equal-to-a-label'), - pytest.param({'variables.p.where': "g[h] != 'west'"}, id='a-map-not-equal-to-a-label'), + pytest.param({'variables.p.where': "g[h] == 'west'"}, id='a-mapping-equal-to-a-label'), + pytest.param({'variables.p.where': "g[h] != 'west'"}, id='a-mapping-not-equal-to-a-label'), pytest.param({'conditions.west': "h == 'west'"}, id='a-named-condition'), pytest.param({'assumptions.west': {'holds': "g[h] != 'west'"}}, id='an-assumption'), ], @@ -500,7 +500,7 @@ def test_a_label_not_in_one_of_is_refused(self, patch): 'patch', [ pytest.param({'variables.r.where': "h == 'north'"}, id='a-dimension'), - pytest.param({'variables.p.where': 'g[h] != south'}, id='a-map'), + pytest.param({'variables.p.where': 'g[h] != south'}, id='a-mapping'), ], ) def test_a_label_in_one_of_is_admitted(self, patch): @@ -592,7 +592,7 @@ class TestAnUndeclaredKeywordIsRefusedOnce: SIGNATURE = ( 'The objective: shift() expects ' - "shift(, along=, offset=[, edge='wrap'|][, within=[]])" + "shift(, along=, offset=[, edge='wrap'|][, within=[]])" ) @pytest.mark.parametrize( @@ -620,7 +620,7 @@ def test_a_typo_of_a_real_keyword_is_the_signature_not_advice_about_its_value(se TEMPLATE_SIGNATURE = ( "Macro 'm': shift() expects " - "shift(, along=, offset=[, edge='wrap'|][, within=[]])" + "shift(, along=, offset=[, edge='wrap'|][, within=[]])" ) @pytest.mark.parametrize( @@ -739,7 +739,7 @@ def test_the_version_gates_no_behaviour(self): POSITION_SPEC = to_spec( { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'period': {'dtype': 'int'}}, - 'maps': {'snapshot': {'period': {'dim': 'period'}}, 'period': {'start': {'dim': 'snapshot'}}}, + 'mappings': {'snapshot': {'period': {'dim': 'period'}}, 'period': {'start': {'dim': 'snapshot'}}}, 'parameters': {'load': {'dims': ['snapshot']}}, 'variables': {'p': {'dims': ['snapshot']}}, } @@ -779,8 +779,8 @@ def test_it_resolves(self, mask: str, position: int, by: str | None): ( 'position(snapshot, within=load[snapshot]) == 0', [ - "position(within=load[...]): 'load' is not a relation or a dimension with maps", - 'Write within=[]', + "position(within=load[...]): 'load' is not a relation or a dimension with mappings", + 'Write within=[]', ], ), ( @@ -819,17 +819,17 @@ class TestAWhereSideIsReadInResolution: ), pytest.param( 'position(g, h) == 0', - ('this position() call is not of the form position([, within=[]])',), + ('this position() call is not of the form position([, within=[]])',), id='a-position-with-two-dimensions', ), pytest.param( 'position(g, edge=1) == 0', - ('this position() call is not of the form position([, within=[]])',), + ('this position() call is not of the form position([, within=[]])',), id='a-position-with-a-kwarg-it-lacks', ), pytest.param( 'position(g, by=[g, h]) == 0', - ('this position() call is not of the form position([, within=[]])',), + ('this position() call is not of the form position([, within=[]])',), id='a-position-by-a-list', ), ], @@ -858,7 +858,7 @@ def test_a_signed_literal_and_inf_are_numbers_on_a_side(self): pytest.param( {'parameters.d': {'dims': ['h']}}, 'c <= at(d, by=g[h])', - id='a-lookup-through-a-map', + id='a-lookup-through-a-mapping', ), pytest.param( {}, 'c - shift(c, along=g, offset=1, edge=0) <= k AND position(g) > 0', id='a-translation-with-its-edge' @@ -915,8 +915,8 @@ def test_a_reduction_on_a_side_leaves_the_frame_it_reduced(self): ), pytest.param( {'variables.p.where': 'g[h] > 2 * k'}, - ("'g[h]' is a map in arithmetic", 'Compare it alone against a literal or another map'), - id='a-map-inside-arithmetic', + ("'g[h]' is a mapping in arithmetic", 'Compare it alone against a literal or another mapping'), + id='a-mapping-inside-arithmetic', ), pytest.param( {'variables.p.where': "2 * k == 'x'"}, @@ -1017,7 +1017,7 @@ class TestAConditionIsAnOperand: pytest.param('shift(flag, along=g, offset=1)', id='a-translated-mask'), pytest.param('shift(flag, along=g, offset=-1)', id='a-translation-forwards'), pytest.param('count(shift(flag, along=g, offset=1), over=g) >= 1', id='a-translation-under-a-count'), - pytest.param('at(r, by=g[h])', id='a-mask-read-through-a-map'), + pytest.param('at(r, by=g[h])', id='a-mask-read-through-a-mapping'), pytest.param("flag AND NOT at(h == 'north', by=g[h])", id='a-read-under-connectives'), pytest.param('count(at(r, by=g[h]), over=g) >= 1', id='a-read-under-a-count'), ], @@ -1041,7 +1041,7 @@ def test_a_shape_the_language_admits(self, where): ['curve'], {'has_cost', 'curve'}, {'has_cost', 'flow', 'effect'}, - id='the-read-names-several-maps', + id='the-read-names-several-mappings', ), ], ) @@ -1055,7 +1055,7 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r { 'dimensions': {name: {'dtype': 'str'} for name in ('curve', 'effect', 'flow')}, 'relations': {'cost_of': {'dims': ['flow', 'effect']}}, - 'maps': { + 'mappings': { 'cost_of': {'curve': {'dim': 'curve'}}, 'curve': {'flow': {'dim': 'flow'}, 'effect': {'dim': 'effect'}}, }, @@ -1075,7 +1075,7 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r assert to_spec(spec.to_yaml()).program == spec.program, 'the where string reads back to the same mask' for fmt in ('markdown', 'latex', 'typst'): assert all(name in typeset_line(spec, 'k', fmt).replace('\\_', '_') for name in printed), ( - f'{fmt} prints the operand and each map it is read through' + f'{fmt} prints the operand and each mapping it is read through' ) @pytest.mark.parametrize( @@ -1178,7 +1178,7 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r ), pytest.param( 'at(r, by=g)', - ('at(by=g) names the subject and none of its maps. Write by=g[]',), + ('at(by=g) names the subject and none of its mappings. Write by=g[]',), id='a-read-naming-no-columns', ), pytest.param( @@ -1193,12 +1193,12 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r ), pytest.param( 'at(flag, by=g[g])', - ("at(by=g[g]) names ['g'], a column of 'g' itself. A lookup reads maps at the row",), + ("at(by=g[g]) names ['g'], a column of 'g' itself. A lookup reads mappings at the row",), id='a-read-of-the-subject-column', ), pytest.param( 'at(r, by=nope[h])', - ("at(by=nope[...]): 'nope' is not a relation or a dimension with maps",), + ("at(by=nope[...]): 'nope' is not a relation or a dimension with mappings",), id='a-read-through-no-relation', ), pytest.param( @@ -1249,13 +1249,13 @@ def test_a_count_is_undecidable_in_a_case_when(self): ) assert 'it counts the coordinates a condition admits, which only the data decides' in message - def test_an_inequality_between_two_maps_is_undecidable_in_a_case_when(self): - """The analysis does not decide an inequality between two maps, whatever their dtype. + def test_an_inequality_between_two_mappings_is_undecidable_in_a_case_when(self): + """The analysis does not decide an inequality between two mappings, whatever their dtype. Before, the refusal said that two relations have no order, which is false for two int columns. """ message = _refusal( - **{'dimensions.h': {'dtype': 'int'}, 'maps.g.h2': {'dim': 'h'}}, + **{'dimensions.h': {'dtype': 'int'}, 'mappings.g.h2': {'dim': 'h'}}, expressions={ 'pick': { 'dims': ['g'], @@ -1268,7 +1268,7 @@ def test_an_inequality_between_two_maps_is_undecidable_in_a_case_when(self): }, constraints={'cap': {'dims': ['g'], 'expression': 'p <= pick'}}, ) - assert 'this analysis does not decide an inequality between two maps' in message, message + assert 'this analysis does not decide an inequality between two mappings' in message, message assert 'no order' not in message, message @pytest.mark.parametrize( @@ -1278,13 +1278,13 @@ def test_an_inequality_between_two_maps_is_undecidable_in_a_case_when(self): pytest.param('g[a] == 3', 'g[b] == 4', 'g[a] is 3.0, g[b] is 4.0', id='equalities'), ], ) - def test_two_maps_of_one_subject_are_not_proved_apart_in_a_case_when(self, first, second, witness): - """One row holds a label in each map, so a test on one map does not exclude a test on the other. + def test_two_mappings_of_one_subject_are_not_proved_apart_in_a_case_when(self, first, second, witness): + """One row holds a label in each mapping, so a test on one mapping does not exclude a test on the other. - Before, both maps were read as one value, and two cases that a row can satisfy together loaded. + Before, both mappings were read as one value, and two cases that a row can satisfy together loaded. """ message = _refusal( - **{'dimensions.n': {'dtype': 'int'}, 'maps.g': {'a': {'dim': 'n'}, 'b': {'dim': 'n'}}}, + **{'dimensions.n': {'dtype': 'int'}, 'mappings.g': {'a': {'dim': 'n'}, 'b': {'dim': 'n'}}}, expressions={ 'pick': { 'dims': ['g'], @@ -1296,8 +1296,8 @@ def test_two_maps_of_one_subject_are_not_proved_apart_in_a_case_when(self, first ) assert f'both claim the value where {witness}' in message, message - def test_a_read_through_a_map_is_undecidable_in_a_case_when(self): - """Which label a map gives a coordinate is the data's to say, so two cases split by one are not proved apart.""" + def test_a_read_through_a_mapping_is_undecidable_in_a_case_when(self): + """Which label a mapping gives a coordinate is the data's to say, so two cases split by one are not proved apart.""" message = _refusal( expressions={ 'pick': { @@ -1324,12 +1324,12 @@ def test_a_read_given_an_edge_is_not_told_about_translations(self): where_of('at(r, by=g[h], edge=0)', Namespace(_spec()), 'probe') assert 'translation' not in str(caught.value) - def test_a_read_lands_on_the_dims_it_produces_and_reads_the_map(self): - """The mask is over the subject of the map, and a consumer attaches the map as well as the operand.""" + def test_a_read_lands_on_the_dims_it_produces_and_reads_the_mapping(self): + """The mask is over the subject of the mapping, and a consumer attaches the mapping as well as the operand.""" mask = where_of("at(h == 'north', by=g[h])", Namespace(_spec()), 'probe') assert mask is not None assert sorted(mask.dims) == ['g'], "'h' is read at g[h], so g is all the mask is over" - assert mask.names_read == frozenset({'g'}), 'the map is data a consumer attaches, the label is not' + assert mask.names_read == frozenset({'g'}), 'the mapping is data a consumer attaches, the label is not' def test_a_count_reduces_the_dim_it_counts_along_away(self): """The count is one number per remaining coordinate, so a claim about each group needs no word for the group.""" @@ -1443,7 +1443,7 @@ class TestRulesDecidedWithoutData: {'relations.link': {'dims': ['g']}}, ( "Relation 'link' has one column under 'dims:', and a relation needs at least two", - 'To give each g a label, declare a map under maps: g:.', + 'To give each g a label, declare a mapping under mappings: g:.', ), id='relation-with-one-column', ), @@ -1468,49 +1468,57 @@ class TestRulesDecidedWithoutData: id='relation-with-no-columns', ), pytest.param( - {'maps.nope': {'h': {'dim': 'h'}}}, - ("maps: 'nope' is neither a dimension nor a relation", 'Subjects: g, h.'), - id='map-of-no-subject', + {'mappings.nope': {'h': {'dim': 'h'}}}, + ("mappings: 'nope' is neither a dimension nor a relation", 'Subjects: g, h.'), + id='mapping-of-no-subject', ), pytest.param( - {'maps.g': {'two words': {'dim': 'h'}}}, - ("maps: 'g': 'two words' is not a name",), - id='map-whose-name-is-not-a-name', + {'mappings.g': {'two words': {'dim': 'h'}}}, + ("mappings: 'g': 'two words' is not a name",), + id='mapping-whose-name-is-not-a-name', ), pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.link': {'g': {'dim': 'g'}}}, - ("maps: 'link': map 'g' has the name of a column of 'link'", 'Rename the map after what it holds'), - id='map-named-after-a-column-of-its-subject', + {'relations.link': {'dims': ['g', 'h']}, 'mappings.link': {'g': {'dim': 'g'}}}, + ( + "mappings: 'link': mapping 'g' has the name of a column of 'link'", + 'Rename the mapping after what it holds', + ), + id='mapping-named-after-a-column-of-its-subject', ), pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.g': {'x': {'dim': 'link'}}}, - ("maps: 'g': map 'x' refers to the relation 'link', and a map gives a label of one dimension",), - id='map-referring-to-a-relation', + {'relations.link': {'dims': ['g', 'h']}, 'mappings.g': {'x': {'dim': 'link'}}}, + ( + "mappings: 'g': mapping 'x' refers to the relation 'link', and a mapping gives a label of one dimension", + ), + id='mapping-referring-to-a-relation', ), pytest.param( - {'maps.g': {'x': {'dim': 'z'}}}, - ("maps: 'g': map 'x' refers to undeclared dimension 'z'",), - id='map-referring-to-an-undeclared-dimension', + {'mappings.g': {'x': {'dim': 'z'}}}, + ("mappings: 'g': mapping 'x' refers to undeclared dimension 'z'",), + id='mapping-referring-to-an-undeclared-dimension', ), pytest.param( - {'maps.g': {'h': {'dim': 'g'}}}, - ("maps: 'g': map 'h' is named after dimension 'h', but refers to 'g'",), - id='map-named-after-another-dimension', + {'mappings.g': {'h': {'dim': 'g'}}}, + ("mappings: 'g': mapping 'h' is named after dimension 'h', but refers to 'g'",), + id='mapping-named-after-another-dimension', ), pytest.param( - {'relations.pair': {'dims': {'g0': 'g', 'g1': 'g'}}, 'maps.pair': {'x': {'dim': 'h'}}}, - ("maps: 'pair' is a relation with two columns over 'g'", 'Declare the maps on a relation over each'), - id='map-on-a-relation-with-two-columns-over-one-dimension', + {'relations.pair': {'dims': {'g0': 'g', 'g1': 'g'}}, 'mappings.pair': {'x': {'dim': 'h'}}}, + ( + "mappings: 'pair' is a relation with two columns over 'g'", + 'Declare the mappings on a relation over each', + ), + id='mapping-on-a-relation-with-two-columns-over-one-dimension', ), pytest.param( - {'maps.g.h': 'h'}, - ('maps.g.h: Input should be a valid dictionary',), - id='map-written-as-a-bare-dimension-name', + {'mappings.g.h': 'h'}, + ('mappings.g.h: Input should be a valid dictionary',), + id='mapping-written-as-a-bare-dimension-name', ), pytest.param( - {'maps.g.h': {'dim': 'h', 'value': 'x'}}, - ("unknown key 'value' in a map entry. Valid keys: description, dim, missing.",), - id='map-with-an-unknown-key', + {'mappings.g.h': {'dim': 'h', 'value': 'x'}}, + ("unknown key 'value' in a mapping entry. Valid keys: description, dim, missing.",), + id='mapping-with-an-unknown-key', ), pytest.param( {'objective': {'expression': 'sum(sum(q, over=g, by=g[h]))'}}, @@ -1519,8 +1527,8 @@ class TestRulesDecidedWithoutData: ), pytest.param( {'objective': {'expression': 'sum(sum(p, over=g, by=g[z]))'}}, - ("sum(by=g[z]) names ['z'], which is no map of 'g'. Name one of its maps, ['h'].",), - id='a-map-the-subject-lacks', + ("sum(by=g[z]) names ['z'], which is no mapping of 'g'. Name one of its mappings, ['h'].",), + id='a-mapping-the-subject-lacks', ), pytest.param( { @@ -1546,10 +1554,10 @@ class TestRulesDecidedWithoutData: pytest.param( { 'dimensions.z': {}, - 'maps.g.z': {'dim': 'z'}, + 'mappings.g.z': {'dim': 'z'}, 'objective': {'expression': 'sum(sum(p, over=g[z], by=g[h]))'}, }, - ('sum(over=g[z]) names maps of a subject, and over= takes bare names. Write over=z',), + ('sum(over=g[z]) names mappings of a subject, and over= takes bare names. Write over=z',), id='a-selection-in-over-beside-by', ), pytest.param( @@ -1565,7 +1573,7 @@ class TestRulesDecidedWithoutData: pytest.param( { 'dimensions.z': {}, - 'maps.g.z': {'dim': 'z'}, + 'mappings.g.z': {'dim': 'z'}, 'objective': {'expression': 'sum(sum(p, over=g, by=g[h, h]))'}, }, ('sum(by=g[h, h]) names a column twice',), @@ -1573,7 +1581,7 @@ class TestRulesDecidedWithoutData: ), pytest.param( { - 'maps.g': {'h0': {'dim': 'h'}, 'h1': {'dim': 'h'}}, + 'mappings.g': {'h0': {'dim': 'h'}, 'h1': {'dim': 'h'}}, 'objective': {'expression': 'sum(sum(p, over=[h0, h1], by=g[g]))'}, }, ("['h0', 'h1'] are columns over one dimension, ['h'], and the operand carries each dimension once",), @@ -1583,27 +1591,27 @@ class TestRulesDecidedWithoutData: {'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=g[h], over=g))'}}, ( "shift() expects shift(, along=, offset=[, edge='wrap'|]" - '[, within=[]])', + '[, within=[]])', ), id='a-partition-takes-no-from', ), pytest.param( { 'dimensions.z': {}, - 'maps.g.z': {'dim': 'z'}, + 'mappings.g.z': {'dim': 'z'}, 'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=g[g]))'}, }, - ("within= names ['g'], a column of 'g' itself. Name one of its maps, ['h', 'z']",), + ("within= names ['g'], a column of 'g' itself. Name one of its mappings, ['h', 'z']",), id='a-partition-grouped-within-the-subject-column', ), pytest.param( {'variables.q.where': 'position(g, within=g[z]) == 0'}, - ("position(within=g[z]) names ['z'], which is no map of 'g'. Name one of its maps, ['h'].",), - id='position-within-a-map-the-subject-lacks', + ("position(within=g[z]) names ['z'], which is no mapping of 'g'. Name one of its mappings, ['h'].",), + id='position-within-a-mapping-the-subject-lacks', ), pytest.param( {'objective': {'expression': 'sum(sum(p, over=g[h]))'}}, - ('sum(over=g[h]) names maps of a subject, and over= takes bare names. Write over=h',), + ('sum(over=g[h]) names mappings of a subject, and over= takes bare names. Write over=h',), id='a-selection-in-over-without-by', ), pytest.param( @@ -1613,20 +1621,20 @@ class TestRulesDecidedWithoutData: ), pytest.param( {'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=g))'}}, - ('shift(within=g) names the subject and none of its maps. Write within=g[]',), + ('shift(within=g) names the subject and none of its mappings. Write within=g[]',), id='a-partition-names-the-columns-it-groups-by', ), pytest.param( {'objective': {'expression': 'sum(sum_back(p, along=g, window=2, within=g))'}}, - ('sum_back(within=g) names the subject and none of its maps',), + ('sum_back(within=g) names the subject and none of its mappings',), id='a-window-names-the-columns-it-groups-by', ), pytest.param( {'variables.q.where': 'position(g, within=g) == 0'}, ( - 'position(within=g) names the subject and none of its maps', - 'within=g[]', - "with a map of 'g': ['h']", + 'position(within=g) names the subject and none of its mappings', + 'within=g[]', + "with a mapping of 'g': ['h']", ), id='a-position-names-the-columns-it-counts-within', ), @@ -1635,8 +1643,10 @@ class TestRulesDecidedWithoutData: 'relations.rel': {'dims': ['g', 'h']}, 'objective': {'expression': 'sum(at(r, by=rel[h]))'}, }, - ("'rel' has no map for at() to read. Sum through it instead, or declare a map under maps: rel:.",), - id='at-through-a-relation-with-no-map', + ( + "'rel' has no mapping for at() to read. Sum through it instead, or declare a mapping under mappings: rel:.", + ), + id='at-through-a-relation-with-no-mapping', ), pytest.param( {'objective': {'expression': 'sum(sum(q, over=h, by=g[g]))'}}, @@ -1652,20 +1662,20 @@ class TestRulesDecidedWithoutData: 'relations.rel': {'dims': ['g', 'h']}, 'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=rel[h]))'}, }, - ("'rel' has no map, so it makes no groups", 'under maps: g:'), - id='a-partition-through-a-relation-with-no-map', + ("'rel' has no mapping, so it makes no groups", 'under mappings: g:'), + id='a-partition-through-a-relation-with-no-mapping', ), pytest.param( {'relations.rel': {'dims': ['g', 'h']}, 'variables.q.where': "rel[h] == 'x'"}, ( - "compares the relation 'rel', which has no map, so its rows hold no label", - "Test the bare name 'rel' for whether a row exists, or declare a map under maps: rel:.", + "compares the relation 'rel', which has no mapping, so its rows hold no label", + "Test the bare name 'rel' for whether a row exists, or declare a mapping under mappings: rel:.", ), - id='where-compares-a-relation-with-no-map', + id='where-compares-a-relation-with-no-mapping', ), pytest.param( {'variables.q.where': "g[g] == 'x'"}, - ("'g' is a column of 'g' itself. Compare the coordinate, g == ..., or a map.",), + ("'g' is a column of 'g' itself. Compare the coordinate, g == ..., or a mapping.",), id='where-compares-the-subject-column', ), pytest.param( @@ -1801,11 +1811,11 @@ class TestRulesDecidedWithoutData: ), pytest.param( { - 'maps.h': {'z': {'dim': 'z'}}, + 'mappings.h': {'z': {'dim': 'z'}}, 'dimensions.z': {}, 'objective': {'expression': 'sum(sum(p, over=g, by=[g, h]))'}, }, - ('sum(by=...) takes columns of one subject. Write subject[map]',), + ('sum(by=...) takes columns of one subject. Write subject[mapping]',), id='several-subjects-in-one-by', ), pytest.param( @@ -1826,10 +1836,10 @@ class TestRulesDecidedWithoutData: { 'dimensions.z': {}, 'relations.gz': {'dims': ['g', 'z']}, - 'maps.gz': {'h': {'dim': 'h'}}, + 'mappings.gz': {'h': {'dim': 'h'}}, 'variables.q.where': 'g[h] != gz[h]', }, - ("compares maps of subjects over different dimensions ('g' over ['g'], 'gz' over ['g', 'z'])",), + ("compares mappings of subjects over different dimensions ('g' over ['g'], 'gz' over ['g', 'z'])",), id='where-two-subjects-over-different-dimensions', ), pytest.param( @@ -1911,7 +1921,7 @@ class TestRulesDecidedWithoutData: ), pytest.param( {'variables.p.where': "c[h] == 'x'"}, - ("'c[h]' reads a map of 'c', which is a parameter with no maps",), + ("'c[h]' reads a mapping of 'c', which is a parameter with no mappings",), id='where-a-column-of-a-parameter', ), pytest.param( @@ -1922,7 +1932,7 @@ class TestRulesDecidedWithoutData: pytest.param( { 'relations.link': {'dims': ['g', 'h']}, - 'maps.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}, + 'mappings.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}, 'variables.q.where': "link == 'x'", }, ("'link' compares the relation 'link' itself, and a comparison reads a label", 'link[y]'), @@ -1930,16 +1940,16 @@ class TestRulesDecidedWithoutData: ), pytest.param( {'variables.p.where': "g[zz] == 'x'"}, - ("'g[zz]': 'zz' is no map of 'g'. Maps: h.",), - id='where-a-map-the-subject-lacks', + ("'g[zz]': 'zz' is no mapping of 'g'. Mappings: h.",), + id='where-a-mapping-the-subject-lacks', ), pytest.param( - {'dimensions.z': {}, 'maps.g.z': {'dim': 'z'}, 'variables.p.where': 'g[h] == g[z]'}, + {'dimensions.z': {}, 'mappings.g.z': {'dim': 'z'}, 'variables.p.where': 'g[h] == g[z]'}, ( "compares 'g[h]' (a column over 'h') with 'g[z]' (a column over 'z')", 'Compare two columns over the same dimension', ), - id='where-two-maps-over-different-dimensions', + id='where-two-mappings-over-different-dimensions', ), ], ) @@ -1986,21 +1996,21 @@ def test_the_rewrite_a_sum_grouped_by_the_whole_key_names_is_one_the_language_ta ('patch', 'where'), [ pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}}, + {'relations.link': {'dims': ['g', 'h']}, 'mappings.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}}, "link == 'x'", - id='a-relation-with-two-maps-read-bare', + id='a-relation-with-two-mappings-read-bare', ), ], ) - def test_the_map_a_bare_comparison_is_told_to_read_is_one_the_language_takes(self, patch, where): - """A refusal that names a map is holding out a rewrite, so the rewrite has to load. + def test_the_mapping_a_bare_comparison_is_told_to_read_is_one_the_language_takes(self, patch, where): + """A refusal that names a mapping is holding out a rewrite, so the rewrite has to load. Was: the message named the column as `lk.h`, which the where grammar - no longer parses. A map is written `subject[map]`. + no longer parses. A mapping is written `subject[mapping]`. """ message = _refusal(**{'variables.q.where': where}, **patch) - named = re.search(r'Name one of its maps: (\S+)\.$', message) - assert named is not None, f'the refusal holds out no map to read instead: {message}' + named = re.search(r'Name one of its mappings: (\S+)\.$', message) + assert named is not None, f'the refusal holds out no mapping to read instead: {message}' _spec(**{'variables.q.where': where.replace('link', named.group(1), 1)}, **patch) @@ -2057,12 +2067,12 @@ def test_a_relation_named_where_a_dimension_belongs_is_refused(patch: dict[str, pytest.param({'variables.p.where': 'pair AND NOT link'}, id='the-rows-of-two-relations'), pytest.param({'variables.p.where': 'flag'}, id='a-test-of-a-value'), pytest.param( - {'maps.g.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'g[zone]'}, - id='a-label-of-a-map-of-a-dimension', + {'mappings.g.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'g[zone]'}, + id='a-label-of-a-mapping-of-a-dimension', ), pytest.param( - {'maps.pair.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'pair[zone]'}, - id='a-label-of-a-map-of-the-relation', + {'mappings.pair.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'pair[zone]'}, + id='a-label-of-a-mapping-of-the-relation', ), pytest.param( { @@ -2073,7 +2083,7 @@ def test_a_relation_named_where_a_dimension_belongs_is_refused(patch: dict[str, ), ], ) -def test_a_where_that_reads_a_relation_or_a_map_loads(patch: dict[str, Any]): +def test_a_where_that_reads_a_relation_or_a_mapping_loads(patch: dict[str, Any]): to_spec(varied(ON_A_RELATION, **patch)) @@ -2144,7 +2154,7 @@ def test_an_entry_the_language_refuses(self, entry, fragments): pytest.param('c <= k', id='two-parameters'), pytest.param('c <= 0.5 * k', id='arithmetic-on-a-side'), pytest.param('sum(c, over=g) >= k', id='a-reduction-on-a-side'), - pytest.param("g[h] == 'north' AND c > 0", id='a-map-and-a-connective'), + pytest.param("g[h] == 'north' AND c > 0", id='a-mapping-and-a-connective'), pytest.param({'holds': 'c > 0', 'where': 'flag'}, id='a-where-of-its-own'), pytest.param({'holds': 'c > 0', 'description': 'costs are positive'}, id='a-description'), ], @@ -2282,11 +2292,11 @@ def _cased(cases: dict[str, Any] | None = None, **entry: Any) -> dict[str, Any]: #: Every kind of thing a spec holds: an entry, a field two levels down, a list, #: a section, the given sections, the cases of an expression, a relation's -#: columns written as a mapping, and the maps of a subject. +#: columns written as a mapping, and the mappings of a subject. _PROBED = { **DISPATCH_MODEL, 'relations': {'pair': {'dims': {'from_gen': 'generator', 'to_gen': 'generator'}}}, - 'maps': {'generator': {'peer': {'dim': 'generator'}}}, + 'mappings': {'generator': {'peer': {'dim': 'generator'}}}, 'expressions': { 'price': { 'dims': ['generator'], @@ -2309,7 +2319,7 @@ def _cased(cases: dict[str, Any] | None = None, **entry: Any) -> dict[str, Any]: pytest.param(lambda s: s.given.parameters.__setitem__('extra', None), id='a-given-entry-added'), pytest.param(lambda s: s.expressions['price'].cases.pop('cheap'), id='a-case-removed'), pytest.param(lambda s: s.relations['pair'].dims.pop('to_gen'), id='a-relation-column-removed'), - pytest.param(lambda s: s.maps['generator'].pop('peer'), id='a-map-removed'), + pytest.param(lambda s: s.mappings['generator'].pop('peer'), id='a-mapping-removed'), ], ) def test_a_loaded_spec_cannot_be_written_to(write): @@ -2882,7 +2892,7 @@ def test_a_bare_parameter_whose_answer_needs_the_data_loads(patch): #: A parameter over the pairs of `g` and `h` that a relation lists, with a fill. _MASKED = { 'relations.pair': {'dims': ['g', 'h'], 'missing': 'absent'}, - 'maps.pair.kind': {'dim': 'h', 'missing': 'absent'}, + 'mappings.pair.kind': {'dim': 'h', 'missing': 'absent'}, 'parameters.w': {'dims': ['g', 'h'], 'where': 'pair[kind]', 'missing': 1}, } @@ -2967,7 +2977,7 @@ def test_the_legend_says_where_a_parameter_has_coordinates(fmt: FormatName): """The mask decides which rows of the data count, so a reader of the legend sees it beside the dims.""" spec = _spec(**_MASKED, **{'variables.q.bounds': {'upper': 'w'}}) row = next(line for line in typeset(spec, fmt).splitlines() if 'only where' in line) - assert 'kind' in row, 'the legend row names the map the mask reads' + assert 'kind' in row, 'the legend row names the mapping the mask reads' assert row.index('only where') < row.index('where the data has no row'), 'the mask comes before the fill' @@ -2999,11 +3009,11 @@ def test_a_relation_says_whether_every_combination_needs_a_row(declared, read): pytest.param({'dim': 'h', 'missing': 'absent'}, ('h',), id='absent'), ], ) -def test_a_map_says_whether_every_row_needs_a_label(declared, partial): - """A map takes `missing:` as a relation does, and the table of its subject lists the maps under `absent`.""" - spec = to_spec(varied(SMALL_MODEL, **{'maps.g.h': declared})) +def test_a_mapping_says_whether_every_row_needs_a_label(declared, partial): + """A mapping takes `missing:` as a relation does, and the table of its subject lists the mappings under `absent`.""" + spec = to_spec(varied(SMALL_MODEL, **{'mappings.g.h': declared})) assert spec.program.relations['g'].partial == partial - assert to_spec(spec.to_yaml()) == spec, 'the map writes back the file it read' + assert to_spec(spec.to_yaml()) == spec, 'the mapping writes back the file it read' @pytest.mark.parametrize( @@ -3030,19 +3040,21 @@ def test_a_map_says_whether_every_row_needs_a_label(declared, partial): id='null-on-a-relation', ), pytest.param( - {'maps.g.h': {'dim': 'h', 'missing': 0}}, - 'maps.g.h.missing: missing: 0 on a map, which takes refused or absent', - id='a-number-on-a-map', + {'mappings.g.h': {'dim': 'h', 'missing': 0}}, + 'mappings.g.h.missing: missing: 0 on a mapping, which takes refused or absent', + id='a-number-on-a-mapping', + ), + pytest.param( + {'mappings.g.h': {'dim': 'h', 'missing': 'h1'}}, 'missing: h1 on a mapping', id='a-label-on-a-mapping' ), - pytest.param({'maps.g.h': {'dim': 'h', 'missing': 'h1'}}, 'missing: h1 on a map', id='a-label-on-a-map'), pytest.param( - {'maps.g.h': {'dim': 'h', 'missing': None}}, - 'missing: null on a map says nothing', - id='null-on-a-map', + {'mappings.g.h': {'dim': 'h', 'missing': None}}, + 'missing: null on a mapping says nothing', + id='null-on-a-mapping', ), ], ) -def test_a_relation_or_map_missing_that_reads_nothing_is_refused(patch, fragment): +def test_a_relation_or_mapping_missing_that_reads_nothing_is_refused(patch, fragment): assert fragment in _refusal(**patch) diff --git a/tests/typesetting/golden/latex.out b/tests/typesetting/golden/latex.out index 6c1023216..1439e861b 100644 --- a/tests/typesetting/golden/latex.out +++ b/tests/typesetting/golden/latex.out @@ -79,9 +79,9 @@ \begin{description} \item[{$t \ominus k$}] \texttt{edge='wrap'} --- $t-k$, cyclic \item[{$t \boxminus_{v} k$}] \texttt{edge=v} --- $t-k$, and $v$ past the edge -\item[{$t \ominus^{\mathrm{map}(t)} k$}] \texttt{within=subject[map]} --- $t-k$ inside the group of $t$ +\item[{$t \ominus^{\mathrm{map}(t)} k$}] \texttt{within=subject[mapping]} --- $t-k$ inside the group of $t$ \item[{$\mathrm{pos}(t)$}] \texttt{position()} --- the position of $t$, counted from $0$; $t$ is the label -\item[{$\mathrm{pos}_{\mathrm{map}(t)}(t)$}] \texttt{position(within=subject[map])} --- the position of $t$ inside its group +\item[{$\mathrm{pos}_{\mathrm{map}(t)}(t)$}] \texttt{position(within=subject[mapping])} --- the position of $t$ inside its group \item[{$\lvert \mathcal{T} \rvert$}] the size of $\mathcal{T}$; $\lvert \mathcal{T} \rvert - 1$ is the last position \end{description} diff --git a/tests/typesetting/golden/markdown.out b/tests/typesetting/golden/markdown.out index 4451ad904..cbea4a3aa 100644 --- a/tests/typesetting/golden/markdown.out +++ b/tests/typesetting/golden/markdown.out @@ -81,9 +81,9 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 |---|---| | $`t \ominus k`$ | `edge='wrap'` — $`t-k`$, cyclic | | $`t \boxminus_{v} k`$ | `edge=v` — $`t-k`$, and $`v`$ past the edge | -| $`t \ominus^{\mathrm{map}(t)} k`$ | `within=subject[map]` — $`t-k`$ inside the group of $`t`$ | +| $`t \ominus^{\mathrm{map}(t)} k`$ | `within=subject[mapping]` — $`t-k`$ inside the group of $`t`$ | | $`\mathrm{pos}(t)`$ | `position()` — the position of $`t`$, counted from $`0`$; $`t`$ is the label | -| $`\mathrm{pos}_{\mathrm{map}(t)}(t)`$ | `position(within=subject[map])` — the position of $`t`$ inside its group | +| $`\mathrm{pos}_{\mathrm{map}(t)}(t)`$ | `position(within=subject[mapping])` — the position of $`t`$ inside its group | | $`\lvert \mathcal{T} \rvert`$ | the size of $`\mathcal{T}`$; $`\lvert \mathcal{T} \rvert - 1`$ is the last position | #### Conditions diff --git a/tests/typesetting/golden/model.yaml b/tests/typesetting/golden/model.yaml index a98643e17..34820b3d7 100644 --- a/tests/typesetting/golden/model.yaml +++ b/tests/typesetting/golden/model.yaml @@ -22,17 +22,17 @@ dimensions: bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through relations: - gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other - connection: { dims: [generator, bus], missing: absent } # a relation with no map: many-to-many, read only by sum with both ends named + gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a mapping: a call sums one away and joins on the other + connection: { dims: [generator, bus], missing: absent } # a relation with no mapping: many-to-many, read only by sum with both ends named -maps: - generator: { bus: { dim: bus }, technology: { dim: technology } } # two maps of one subject, read to both at once +mappings: + generator: { bus: { dim: bus }, technology: { dim: technology } } # two mappings of one subject, read to both at once bus: zone: { dim: zone } - area: { dim: zone, missing: absent } # a second map into the same set, to compare against; a bus may be in no area + area: { dim: zone, missing: absent } # a second mapping into the same set, to compare against; a bus may be in no area snapshot: season: { dim: season } - rep: { dim: snapshot } # a map into its own dimension: the representative snapshot + rep: { dim: snapshot } # a mapping into its own dimension: the representative snapshot gen_zone: { zone: { dim: zone } } parameters: @@ -44,7 +44,7 @@ parameters: zone_cap: { dims: [zone] } tech_cap: { dims: [bus, technology], missing: absent } link_eff: { dims: [generator, bus], where: connection, missing: 1 } - area_weight: { dims: [bus], where: "bus[area]" } # a map's label as a condition: the buses that have an area + area_weight: { dims: [bus], where: "bus[area]" } # a mapping's label as a condition: the buses that have an area min_up: { dims: [generator], dtype: int } eta: { dims: [generator] } # a Greek name that is *given*, so the rule wins and it prints as the word lead: { dims: [generator], dtype: int } @@ -165,7 +165,7 @@ piecewise: links: p: [p, bp_x] fuel: [fuel, bp_y, ">="] - bus_curve: # one curve per bus, read by each generator on it: a link that walks a map prints as the family it ties, and the mask is read through the map too + bus_curve: # one curve per bus, read by each generator on it: a link that walks a mapping prints as the family it ties, and the mask is read through the mapping too along: bp dims: [snapshot, bus] where: load @@ -209,7 +209,7 @@ constraints: under_rating: # names the expression with declared dims, read in the row's own order dims: [snapshot, generator] expression: p <= rating - balance: # sum through a map + balance: # sum through a mapping dims: [snapshot, bus] expression: sum(p, over=generator, by=generator[bus]) + spill - slack == load netted: # names the signed sum on the right of a plus: inlined, its minus prints as a subtraction @@ -238,7 +238,7 @@ constraints: lead_time: # an offset the data carries, so it prints as a symbol rather than a number dims: [snapshot, generator] expression: shift(p, along=snapshot, offset=lead, edge=0) <= p_max - in_season: # a translation partitioned by a map: the group rides on the operator + in_season: # a translation partitioned by a mapping: the group rides on the operator dims: [snapshot, generator] expression: p <= shift(p, along=snapshot, offset=1, edge='wrap', within=snapshot[season]) held_in_season: # the same group, with a fill: each season's opening row is kept and given a zero @@ -250,10 +250,10 @@ constraints: history: # the same window, its width in the data and its edge wrapped dims: [snapshot, generator] expression: sum_back(on, along=snapshot, window=min_up, edge='wrap') <= units - seasonal_window: # a window partitioned by a map: the group rides on the operator + seasonal_window: # a window partitioned by a mapping: the group rides on the operator dims: [snapshot, generator] expression: sum_back(on, along=snapshot, window=3, within=snapshot[season]) <= units - lookup: # at(), which re-indexes through a map instead of an offset + lookup: # at(), which re-indexes through a mapping instead of an offset dims: [snapshot, bus] expression: spill <= at(zone_cap, by=bus[zone]) grouped_once: # one table read to two value columns: the domain carries a condition per column @@ -266,23 +266,23 @@ constraints: dims: [generator] where: "position(generator, within=generator[bus, technology]) == 0" expression: units <= shift(units, along=generator, offset=1, edge=0, within=generator[bus]) - relational: # a sum through a relation with no map: the domain is a row of the relation rather than a label + relational: # a sum through a relation with no mapping: the domain is a row of the relation rather than a label dims: [snapshot, bus] expression: sum(p, over=generator, by=connection[bus]) <= load connected: # a relation as a where: the row of the frame has to be a member of the relation dims: [snapshot, generator, bus] where: "connection" expression: p <= load - representative: # a map into its own dimension, read both ways: the frame is unchanged and the index is primed + representative: # a mapping into its own dimension, read both ways: the frame is unchanged and the index is primed dims: [snapshot] expression: sum(spill, over=snapshot, by=snapshot[rep]) <= at(spill, by=snapshot[rep]) - zonal: # a grouping through a two-key map, summing one key away: the condition reads the other, and the row keeps it + zonal: # a grouping through a two-key mapping, summing one key away: the condition reads the other, and the row keeps it dims: [snapshot, zone] expression: sum(p, over=generator, by=gen_zone[zone]) <= zone_cap zonal_history: # the same table summing its other key away dims: [generator, zone] expression: sum(p, over=snapshot, by=gen_zone[zone]) <= zone_cap - zonal_membership: # the same relation read between its own two columns: no map is read, so the domain asks only that the row is there + zonal_membership: # the same relation read between its own two columns: no mapping is read, so the domain asks only that the row is there dims: [snapshot] expression: sum(units, over=generator, by=gen_zone[snapshot]) <= budget zonal_lookup: # the same table joined the other way, reading the slot the row's own snapshot puts the generator in @@ -313,7 +313,7 @@ constraints: dims: [snapshot, generator] where: "position(snapshot) == -1 OR position(snapshot, within=snapshot[season]) == -1" expression: on == 0 - northern: # a map compared to a label, to another map, and tested for a label + northern: # a mapping compared to a label, to another mapping, and tested for a label dims: [snapshot, bus] where: "bus[zone] == 'north' AND bus[zone] != bus[area] AND bus[area]" expression: slack <= load @@ -339,7 +339,7 @@ constraints: dims: [snapshot, generator] where: "p_max - p_min > cost / 2" expression: p <= p_max - ramped: # a translation under a comparison names its edge, a lookup reads through a map, and the position keeps the vacated row out + ramped: # a translation under a comparison names its edge, a lookup reads through a mapping, and the position keeps the vacated row out dims: [snapshot, bus] where: "load - shift(load, along=snapshot, offset=1, edge=0) <= at(zone_cap, by=bus[zone]) AND position(snapshot) > 0" expression: slack <= load @@ -359,7 +359,7 @@ constraints: dims: [snapshot, bus] where: "load AND NOT shift(load, along=snapshot, offset=1)" expression: slack <= load - zoned: # a condition read through a map: a bus is held only where its zone has a cap at all + zoned: # a condition read through a mapping: a bus is held only where its zone has a cap at all dims: [bus] where: "at(zone_cap, by=bus[zone])" expression: theta <= budget @@ -376,7 +376,7 @@ assumptions: # what the data has to satisfy for the answer to mean anything bounds_do_not_cross: "p_min <= p_max" # two parameters, which is arithmetic like any other efficiency_is_a_fraction: "eta > 0 AND eta <= 1" # a connective, so the line has no relation to align on lead_times_are_short: "lead <= 3" # one parameter against a literal - zones_agree: "bus[zone] == bus[area]" # two maps into one set, compared row by row + zones_agree: "bus[zone] == bus[area]" # two mappings into one set, compared row by row budget_covers_the_peak: "sum(p_max, over=generator) >= budget" # a reduction on a side, leaving nothing to quantify ramps_are_gentle: # a translation inside arithmetic, and a position keeping the vacated row out holds: "load - shift(load, along=snapshot, offset=1, edge=0) <= budget" @@ -385,7 +385,7 @@ assumptions: # what the data has to satisfy for the answer to mean anything holds: "p_min < p_max" where: "is_flexible" description: a unit that cannot be turned down needs somewhere to go - northern_demand_is_real: # a map comparison as the where, over a frame two dims wide + northern_demand_is_real: # a mapping comparison as the where, over a frame two dims wide holds: "load >= 0" where: "bus[zone] == 'north'" diff --git a/tests/typesetting/golden/typst.out b/tests/typesetting/golden/typst.out index 0722349a2..ff102083d 100644 --- a/tests/typesetting/golden/typst.out +++ b/tests/typesetting/golden/typst.out @@ -64,9 +64,9 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 == Notation / $t minus.o k$: `edge='wrap'` --- $t-k$, cyclic / $t minus.square_(v) k$: `edge=v` --- $t-k$, and $v$ past the edge -/ $t minus.o^(upright("map")(t)) k$: `within=subject[map]` --- $t-k$ inside the group of $t$ +/ $t minus.o^(upright("map")(t)) k$: `within=subject[mapping]` --- $t-k$ inside the group of $t$ / $upright("pos")(t)$: `position()` --- the position of $t$, counted from $0$; $t$ is the label -/ $upright("pos")_(upright("map")(t))(t)$: `position(within=subject[map])` --- the position of $t$ inside its group +/ $upright("pos")_(upright("map")(t))(t)$: `position(within=subject[mapping])` --- the position of $t$ inside its group / $abs(cal(T))$: the size of $cal(T)$; $abs(cal(T)) - 1$ is the last position == Conditions diff --git a/tests/typesetting/test_golden.py b/tests/typesetting/test_golden.py index 3c4ffe82d..a8b8818c7 100644 --- a/tests/typesetting/test_golden.py +++ b/tests/typesetting/test_golden.py @@ -161,7 +161,7 @@ def test_the_golden_model_carries_every_node_kind_the_walk_renders(): """A construct added to the language is a case this fixture owes output for. Two constructs can share every symbol and still render differently — - ``at`` and ``sum(by=)`` both print a coordinate map — so this counts node + ``at`` and ``sum(by=)`` both print a coordinate mapping — so this counts node kinds rather than symbols. Like the operator census it runs without `coverage` installed, and its failure names the construct rather than a line. """ diff --git a/tests/typesetting/test_symbols.py b/tests/typesetting/test_symbols.py index 177754ce1..6cb83a166 100644 --- a/tests/typesetting/test_symbols.py +++ b/tests/typesetting/test_symbols.py @@ -101,7 +101,7 @@ def test_a_named_expression_has_a_legend_row_exactly_while_its_symbol_prints(nam DISPATCH_MODEL, **{ 'dimensions.bus': {'dtype': 'str'}, - 'maps.generator': {'bus': {'dim': 'bus', 'missing': 'absent'}}, + 'mappings.generator': {'bus': {'dim': 'bus', 'missing': 'absent'}}, 'parameters.p_max.missing': 'inf', 'parameters.cost.missing': 1, 'parameters.load.missing': 0, @@ -115,7 +115,7 @@ def test_a_named_expression_has_a_legend_row_exactly_while_its_symbol_prints(nam @EVERY_FORMAT def test_the_legend_prints_what_a_missing_row_means(name: FormatName, fmt: Format): - """The legend printed a value and left out a reading, so `absent`, `0` and a partial map looked complete.""" + """The legend printed a value and left out a reading, so `absent`, `0` and a partial mapping looked complete.""" out = typeset(DEFAULTED, name) for shown in ( fmt.math(number(math.inf, fmt)), @@ -127,7 +127,7 @@ def test_the_legend_prints_what_a_missing_row_means(name: FormatName, fmt: Forma ): assert f'{shown} where the data has no row' in out assert out.count(f'{fmt.mono("generator[bus]")} is {fmt.mono("absent")} where the data gives no label') == 2, ( - 'the map says what a missing label means in each of its two sets' + 'the mapping says what a missing label means in each of its two sets' ) assert out.count('where the data has no row') == 6, ( 'six parameters say what a missing row means; `ramp` keeps the default, refused, and says nothing' diff --git a/tests/typesetting/test_walk.py b/tests/typesetting/test_walk.py index 0c9b3fcc8..d77fbe23a 100644 --- a/tests/typesetting/test_walk.py +++ b/tests/typesetting/test_walk.py @@ -155,7 +155,7 @@ def test_a_fill_and_a_group_take_the_operators_two_slots(name: FormatName, fmt: """ model = { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'season': {'dtype': 'str'}}, - 'maps': {'snapshot': {'season': {'dim': 'season'}}}, + 'mappings': {'snapshot': {'season': {'dim': 'season'}}}, 'variables': {'p': {'dims': ['snapshot'], 'bounds': {'lower': 0}}}, 'constraints': { 'held': { @@ -180,7 +180,7 @@ def test_a_translation_by_nothing_takes_no_legend_row(name: FormatName): translation as printed and explained a grouped operator the page never shows.""" model = { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'season': {'dtype': 'str'}}, - 'maps': {'snapshot': {'season': {'dim': 'season'}}}, + 'mappings': {'snapshot': {'season': {'dim': 'season'}}}, 'variables': {'p': {'dims': ['snapshot'], 'bounds': {'lower': 0}}}, 'constraints': { 'held': { @@ -209,7 +209,7 @@ def test_a_translation_under_a_lookup_survives_it(name: FormatName, fmt: Format) 'snapshot': {'dtype': 'int', 'ordered': True}, 'period': {'dtype': 'int', 'ordered': True}, }, - 'maps': {'snapshot': {'period': {'dim': 'period'}}}, + 'mappings': {'snapshot': {'period': {'dim': 'period'}}}, 'parameters': {'cap': {'dims': ['period']}}, 'variables': {'p': {'dims': ['snapshot'], 'bounds': {'lower': 0}}}, 'constraints': { @@ -318,7 +318,7 @@ def _selected(mask: str) -> dict[str, Any]: """One constraint carrying *mask*, over a dimension a relation groups.""" return { 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'season': {'dtype': 'str'}}, - 'maps': {'snapshot': {'season': {'dim': 'season'}}}, + 'mappings': {'snapshot': {'season': {'dim': 'season'}}}, 'variables': {'soc': {'dims': ['snapshot'], 'bounds': {'lower': 0}}}, 'constraints': {'seed': {'dims': ['snapshot'], 'where': mask, 'expression': 'soc == 0'}}, } @@ -464,7 +464,7 @@ def test_inlining_keeps_the_definition_of_an_entry_the_math_never_reads(name: Fo @EVERY_FORMAT def test_a_dual_prints_the_constraint_symbol_not_a_same_named_variable(name: FormatName, fmt: Format): - """`dual(c)` subscripts λ from a map of its own, so a variable sharing the + """`dual(c)` subscripts λ from a mapping of its own, so a variable sharing the constraint's name — a legal collision, constraints sit outside the flat namespace (#74) — cannot lend the dual its italic letter.""" model = varied( @@ -658,9 +658,9 @@ def test_every_operator_probe_renders(path, name: FormatName, fmt: Format): # --------------------------------------------------------------------------- -#: Two tables a call can leave a map unread. A sum between `gen_zone`'s own -#: two columns reads no map at all, and a sum that consumes one of -#: `generator`'s two maps leaves the other one. +#: Two tables a call can leave a mapping unread. A sum between `gen_zone`'s own +#: two columns reads no mapping at all, and a sum that consumes one of +#: `generator`'s two mappings leaves the other one. UNREAD = { 'dimensions': { 'snapshot': {'dtype': 'int', 'ordered': True}, @@ -670,7 +670,7 @@ def test_every_operator_probe_renders(path, name: FormatName, fmt: Format): 'technology': {'dtype': 'str'}, }, 'relations': {'gen_zone': {'dims': ['generator', 'snapshot']}}, - 'maps': { + 'mappings': { 'gen_zone': {'zone': {'dim': 'zone'}}, 'generator': {'bus': {'dim': 'bus'}, 'technology': {'dim': 'technology'}}, }, @@ -690,33 +690,33 @@ def _grouped(dims: list[str], expression: str) -> str: return next(line for line in to_latex(model, legend=False).splitlines() if line.startswith(r'\text{c}')) -def test_a_sum_that_reads_no_map_asks_only_that_the_relation_has_the_row(): +def test_a_sum_that_reads_no_mapping_asks_only_that_the_relation_has_the_row(): """`sum(u, over=generator, by=gen_zone[snapshot])` died with `KeyError: 'zone'`. The domain was written as a whole row of the table, which needs an index for every column, and this sum goes between the relation's own two - columns: it reads no map, so there is no index to write in `zone`'s place. + columns: it reads no mapping, so there is no index to write in `zone`'s place. What the sum asks of the relation is that it has the row at all. """ row = _grouped(['snapshot'], 'sum(u, over=generator, by=gen_zone[snapshot]) <= cap') assert r'\sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}}' in row, ( - 'the condition is that the row is in the relation, and the unread map is written nowhere' + 'the condition is that the row is in the relation, and the unread mapping is written nowhere' ) -def test_a_map_the_call_consumes_is_a_condition_like_a_produced_one(): +def test_a_mapping_the_call_consumes_is_a_condition_like_a_produced_one(): """`sum(f, over=[generator, bus], by=generator[technology])` bound `b` and then said nothing about it, so the sum ran over every bus rather than over the one the table puts each generator on. - The conditions were written per *produced* column. A call fixes a map by - consuming it too, and either way the map is one lookup at the row. + The conditions were written per *produced* column. A call fixes a mapping by + consuming it too, and either way the mapping is one lookup at the row. """ row = _grouped(['technology'], 'sum(f, over=[generator, bus], by=generator[technology]) <= cap') assert ( r'\sum_{g \in \mathcal{G},\ b \in \mathcal{B} \,:\, ' r'\mathrm{bus}(g) = b \wedge \mathrm{technology}(g) = e}' - ) in row, 'both maps the call touches are read' + ) in row, 'both mappings the call touches are read' # --------------------------------------------------------------------------- @@ -732,7 +732,7 @@ def test_a_map_the_call_consumes_is_a_condition_like_a_produced_one(): 'generator': {'dtype': 'str', 'ordered': True}, 'bus': {'dtype': 'str'}, }, - 'maps': {'generator': {'bus': {'dim': 'bus'}}}, + 'mappings': {'generator': {'bus': {'dim': 'bus'}}}, 'parameters': {'load': {'dims': ['snapshot']}, 'k': {'dims': []}, 'flag': {'dims': ['snapshot'], 'dtype': 'bool'}}, 'variables': {'p': {'dims': ['snapshot', 'generator']}, 'q': {'dims': ['snapshot', 'generator']}}, } diff --git a/tools/notation.py b/tools/notation.py index c47c76ceb..7b95a5466 100644 --- a/tools/notation.py +++ b/tools/notation.py @@ -48,7 +48,7 @@ BEGIN, END = '', '' #: The sections of the fixture that declare math. ``dimensions``, ``relations``, -#: ``maps`` and ``parameters`` are absent on purpose: they declare no equation, and what +#: ``mappings`` and ``parameters`` are absent on purpose: they declare no equation, and what #: they print is the legend, which the page shows once rather than a row at a #: time. SECTIONS = ('objective', 'constraints', 'expressions', 'conditions', 'variables', 'piecewise', 'sos', 'assumptions') @@ -80,20 +80,20 @@ 'Objective': { 'objective': 'Products and powers in the objective', }, - 'Relations and maps': { - 'balance': 'Sum through a map', + 'Relations and mappings': { + 'balance': 'Sum through a mapping', 'total': 'Sum over every dimension', - 'lookup': '`at` through a map', - 'grouped_once': 'Sum into two maps', - 'looked_up_once': '`at` through two maps', - 'within_bus': 'Shift within one map', + 'lookup': '`at` through a mapping', + 'grouped_once': 'Sum into two mappings', + 'looked_up_once': '`at` through two mappings', + 'within_bus': 'Shift within one mapping', 'relational': 'Sum through a relation', 'connected': 'Relation as a condition', - 'representative': 'Map into its own dimension', - 'zonal': 'Sum through a map of a relation', + 'representative': 'Mapping into its own dimension', + 'zonal': 'Sum through a mapping of a relation', 'zonal_history': 'Sum over the other column of a relation', 'zonal_membership': 'Sum between the two columns of a relation', - 'zonal_lookup': '`at` through a map of a relation', + 'zonal_lookup': '`at` through a mapping of a relation', }, 'Arithmetic and literals': { 'arithmetic': 'Signs, division and number literals', @@ -143,18 +143,18 @@ 'bounds_do_not_cross': 'Two parameters compared', 'efficiency_is_a_fraction': 'Connective in an assumption', 'lead_times_are_short': 'Parameter compared to a literal', - 'zones_agree': 'Two maps compared', + 'zones_agree': 'Two mappings compared', 'budget_covers_the_peak': 'Reduction in an assumption', 'ramps_are_gentle': 'Shift in an assumption', 'flexible_units_have_headroom': 'Assumption with a boolean condition', - 'northern_demand_is_real': 'Assumption with a map condition', + 'northern_demand_is_real': 'Assumption with a mapping condition', }, 'Where conditions': { 'scalar': 'Parameter as a condition', 'running': 'Variable and label conditions', 'first': 'Position in a dimension', 'last': 'Position counted from the end', - 'northern': 'Map compared to a label', + 'northern': 'Mapping compared to a label', 'always': 'Constant true condition', 'redundant': 'Constant true inside a condition', 'never': 'Constant false condition', @@ -164,7 +164,7 @@ 'counted': 'Count over a dimension', 'counted_here': 'Count along a dimension of the frame', 'run_start': 'Condition at the previous coordinate', - 'zoned': 'Condition through a map', + 'zoned': 'Condition through a mapping', }, } @@ -295,11 +295,11 @@ def legend() -> str: #: What the legend is made of. No equation comes from these, so they are shown #: once, together, above the tables they turn into. -DECLARED = ('dimensions', 'relations', 'maps', 'parameters') +DECLARED = ('dimensions', 'relations', 'mappings', 'parameters') def preamble(text: str) -> str: - """The fixture's ``dimensions``/``relations``/``maps``/``parameters`` sections, verbatim.""" + """The fixture's ``dimensions``/``relations``/``mappings``/``parameters`` sections, verbatim.""" sections = [] for name in DECLARED: body = text[text.index(f'\n{name}:') + 1 :] @@ -313,7 +313,7 @@ def block() -> str: rendered = to_markdown(MODEL, numbered=False) parts = [ '### Legend', - 'A dimension, a relation, a map and a parameter declare no equation; what they ' + 'A dimension, a relation, a mapping and a parameter declare no equation; what they ' 'print is the legend every spec opens with.', f'```yaml\n{preamble(MODEL.read_text())}\n```', legend(), diff --git a/tools/pypsa_split.py b/tools/pypsa_split.py index 20bdbac6f..0d12aeb10 100644 --- a/tools/pypsa_split.py +++ b/tools/pypsa_split.py @@ -55,7 +55,7 @@ SECTIONS = ( 'dimensions', 'relations', - 'maps', + 'mappings', 'parameters', 'variables', 'expressions', @@ -64,7 +64,7 @@ 'constraints', 'assumptions', ) -FRAME = ('dimensions', 'relations', 'maps') +FRAME = ('dimensions', 'relations', 'mappings') IDENT = re.compile(r'[A-Za-z_][A-Za-z0-9_]*') READ = re.compile(r'(? set[str]: def _subjects_in(value: object, subjects: set[str]) -> set[str]: - """Every subject in *subjects* whose maps *value* reads, as ``subject[map]``, prose left out.""" + """Every subject in *subjects* whose mappings *value* reads, as ``subject[mapping]``, prose left out.""" if isinstance(value, str): return {token for token in READ.findall(value) if token in subjects} if isinstance(value, dict): @@ -232,11 +232,11 @@ def __init__(self, path: Path = SOURCE) -> None: self.kind = { n: s for s in SECTIONS - if s not in ('maps', 'piecewise', 'constraints', 'assumptions') + if s not in ('mappings', 'piecewise', 'constraints', 'assumptions') for n in self.data.get(s, {}) } - #: Every subject with maps. A subject shares its name with its dimension or relation, so it is not in `kind`. - self.subjects = set(self.data.get('maps', {})) + #: Every subject with mappings. A subject shares its name with its dimension or relation, so it is not in `kind`. + self.subjects = set(self.data.get('mappings', {})) #: hub -> the topic of each term -> the term, in the order the topics sort in. self.shares: dict[str, dict[str, str]] = {} for hub in HUBS: @@ -269,9 +269,9 @@ def _owner(self, text: str) -> str: def names_in(self, value: object) -> set[str]: return _names_in(value, self.kind) - def maps_read(self, value: object) -> set[Key]: - """The ``maps:`` entry of every subject *value* reads a map of.""" - return {('maps', subject) for subject in _subjects_in(value, self.subjects)} + def mappings_read(self, value: object) -> set[Key]: + """The ``mappings:`` entry of every subject *value* reads a mapping of.""" + return {('mappings', subject) for subject in _subjects_in(value, self.subjects)} def key(self, name: str) -> Key: return self.kind[name], name @@ -328,7 +328,7 @@ def fragments(model: Model) -> dict[str, str]: } frame_reads = read | set().union(*(model.names_in(dims) for dims in stated.values())) frame = {model.key(n) for n in frame_reads if model.key(n)[0] in FRAME} - frame |= set().union(*(model.maps_read(model.data[s][n]) for s, n in mine)) + frame |= set().union(*(model.mappings_read(model.data[s][n]) for s, n in mine)) frame |= {model.key(n) for key in list(frame) for n in model.names_in(model.data[key[0]][key[1]])} written[name] = _fragment(model, mine | frame, given, stated, adds, homes_here) return written diff --git a/tools/spec_math.py b/tools/spec_math.py index fffdd56d0..55a14d15e 100644 --- a/tools/spec_math.py +++ b/tools/spec_math.py @@ -33,7 +33,7 @@ 'sum(array, over=dim, by=subject[m]), joining on the rest of the key': 'sum_by_columns', 'sum(array, over=[dim, …], by=subject[m, …])': 'sum_by_column_lists', 'at(array, by=subject[m])': 'at', - 'at(array, by=subject[m]), two maps into one dimension': 'at_columns', + 'at(array, by=subject[m]), two mappings into one dimension': 'at_columns', 'shift(array, along=dim, offset=n)': 'shift', "shift(array, along=dim, offset=n, edge='wrap')": 'shift_wrap', 'shift(array, along=dim, offset=n, edge=v)': 'shift_edge', From ab510b901292a252b66f09f084e4fcf4f1cd6261 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 20:45:42 +0000 Subject: [PATCH 11/11] feat(language)!: the file has no relations: section A set of combinations of labels is a dimension with over:. The schema refuses relations: as an unknown key, and the program keeps one table per subject with maps or members. The maps page replaces the relations page; the reference, limits.md and the explanation pages say the same. A tuple named only in a where: counts as a use for check. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP --- CHANGELOG.md | 3 +- docs/about/index.md | 4 +- docs/about/limits.md | 21 +- docs/about/overview.md | 4 +- docs/about/relations-as-linear-maps.md | 160 +++---- docs/about/sql-and-dataframes.md | 10 +- docs/contributing.md | 2 +- docs/examples/index.md | 2 +- docs/examples/library/generator.md | 2 +- docs/examples/library/load.md | 2 +- docs/howto/declare-a-column.md | 23 +- docs/howto/index.md | 2 +- docs/reference/composition.md | 47 +- docs/reference/glossary.md | 24 +- docs/reference/index.md | 4 +- docs/reference/language/absence.md | 22 +- docs/reference/language/dimensions.md | 17 +- docs/reference/language/errors.md | 4 +- docs/reference/language/expressions.md | 14 +- docs/reference/language/file.md | 3 +- docs/reference/language/index.md | 2 +- docs/reference/language/maps.md | 330 +++++++++++++ docs/reference/language/operators.md | 22 +- .../parameters-variables-constraints.md | 20 +- docs/reference/language/piecewise.md | 10 +- docs/reference/language/relations.md | 439 ------------------ docs/reference/notation.md | 248 +++++----- docs/reference/reading.md | 26 +- docs/static/linear-maps-at.svg | 4 +- docs/static/linear-maps-empty.svg | 4 +- docs/static/linear-maps-join.svg | 4 +- docs/static/parameters-where.svg | 15 +- docs/static/relations-where-bare.svg | 8 +- docs/tutorials/first-spec.md | 4 +- docs/tutorials/several-files.md | 2 +- docs/tutorials/storage.md | 4 +- mkdocs.yml | 4 +- schema/mathspec.schema.json | 64 +-- src/mathspec/_advising.py | 16 +- src/mathspec/_composition.py | 34 +- src/mathspec/_condition_parser.py | 2 +- src/mathspec/_condition_resolver.py | 18 +- src/mathspec/_dimensions.py | 4 +- src/mathspec/_expression_resolver.py | 20 +- src/mathspec/_renaming.py | 39 +- src/mathspec/_resolution.py | 9 +- src/mathspec/_validation.py | 96 +--- src/mathspec/program.py | 2 +- src/mathspec/spec.py | 113 +---- tests/test_composition.py | 44 +- tests/test_dimensions.py | 147 +----- tests/test_expansion.py | 10 +- tests/test_lowering.py | 109 ++--- tests/test_piecewise.py | 110 +---- tests/test_pypsa_references.py | 2 +- tests/test_renaming.py | 25 +- tests/test_schema.py | 6 +- tests/test_tuple_dimensions.py | 40 +- tests/test_validation.py | 338 ++------------ tests/typesetting/golden/latex.out | 246 +++++----- tests/typesetting/golden/markdown.out | 246 +++++----- tests/typesetting/golden/model.yaml | 32 +- tests/typesetting/golden/typst.out | 246 +++++----- tests/typesetting/test_formats.py | 2 +- tests/typesetting/test_walk.py | 29 +- tools/notation.py | 23 +- tools/pypsa_split.py | 5 +- 67 files changed, 1369 insertions(+), 2224 deletions(-) create mode 100644 docs/reference/language/maps.md delete mode 100644 docs/reference/language/relations.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0797b9f00..1140ff960 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,8 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp ## Upcoming version -- feat(language): a dimension lists its members, strictly ([#9](https://github.com/fluxopt/mathspec/pull/9)) +- feat(language)!: a dimension lists its members, strictly ([#9](https://github.com/fluxopt/mathspec/pull/9)) + - Breaks a file: `relations:` is gone. A set of combinations of labels is a dimension with `over:`, read through its members with `at()` and tested by its bare name in a `where:`. A dimension twice in a relation is an alias member. - feat(language): a dimension lists its members ([#1017](https://github.com/energy-models/mathspec/pull/1017)) - feat(language): a dimension may alias another's labels ([#1020](https://github.com/energy-models/mathspec/pull/1020)) - feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015)) diff --git a/docs/about/index.md b/docs/about/index.md index 397777f88..a4b7abc1e 100644 --- a/docs/about/index.md +++ b/docs/about/index.md @@ -23,9 +23,9 @@ understand a rule before you rely on it. added to the language, and which requests mathspec refuses and why. - **[Versions](versions.md)** describes how the version of the package and the version of the language relate, and why there are two. -- **[Relations as linear maps](relations-as-linear-maps.md)** describes a sum +- **[Maps as linear maps](relations-as-linear-maps.md)** describes a sum through a table that pairs labels - ([a relation](../reference/language/relations.md)) as the product of a matrix and a vector. + ([a map](../reference/language/maps.md)) as the product of a matrix and a vector. - **[Understanding a spec in SQL and dataframe terms](sql-and-dataframes.md)** describes each declaration and operator of a spec as a table or a query, in SQL and in polars. diff --git a/docs/about/limits.md b/docs/about/limits.md index a6d761331..bad052cd3 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -110,16 +110,17 @@ limit does not depend on what solvers take. mathspec refuses a request when a construct that exists already states the same thing. -| Request | Why refused | What you write instead | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| A `where` comparing the label that each row has ([a map](../reference/language/relations.md#maps)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The map already gives each row its label. | A sum or a lookup through the map. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the map gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). | -| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. | -| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | -| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | -| Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a map](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that map: `at(capacity, by=connection[unit])`. | -| Two dimensions in one `dims:` that share a member, or a dimension beside its own member, read as their cross product | A tool may store each dimension as the columns of its members, so the shared member would index the entry twice. | One of the two in `dims:`, and a `where:` that reads a relation through the shared member, or an alias of the member: `site: { over: [from_unit, bus] }`. | -| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` the bare name of the dimension. The construct then steps along an ordered member. | -| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | +| Request | Why refused | What you write instead | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A `where` comparing the label that each row has ([a map](../reference/language/maps.md#maps)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The map already gives each row its label. | A sum or a lookup through the map. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the map gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). | +| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. | +| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. | +| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. | +| Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a map](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that map: `at(capacity, by=connection[unit])`. | +| A `relations:` section for a set of combinations of labels | A [dimension with members](../reference/language/dimensions.md#over) already lists the combinations, and its maps already give each one its labels. | `dimensions: { connection: { over: [generator, bus] } }`, tested by its bare name in a `where:` on an entry over every member. | +| Two dimensions in one `dims:` that share a member, or a dimension beside its own member, read as their cross product | A tool may store each dimension as the columns of its members, so the shared member would index the entry twice. | One of the two in `dims:`, and a `where:` that reads a relation through the shared member, or an alias of the member: `site: { over: [from_unit, bus] }`. | +| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` the bare name of the dimension. The construct then steps along an ordered member. | +| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. | ### Data preparation diff --git a/docs/about/overview.md b/docs/about/overview.md index a91b76880..c0bbc1bc9 100644 --- a/docs/about/overview.md +++ b/docs/about/overview.md @@ -93,8 +93,8 @@ generator either. The file specifies the condition that the data must meet, and the engine that attaches the data checks the condition. - [`missing:`](../reference/language/absence.md#missing) on a parameter, a table that pairs labels - ([a relation](../reference/language/relations.md)) or a - [map](../reference/language/relations.md#maps) sets what a missing row or + ([a map](../reference/language/maps.md)) or a + [map](../reference/language/maps.md#maps) sets what a missing row or label means. When the engine attaches the data, it refuses a missing row by default. - An [`assumptions:`](../reference/language/assumptions.md) entry is a condition that the data must meet. diff --git a/docs/about/relations-as-linear-maps.md b/docs/about/relations-as-linear-maps.md index 30aca65a5..02674dc8c 100644 --- a/docs/about/relations-as-linear-maps.md +++ b/docs/about/relations-as-linear-maps.md @@ -3,12 +3,12 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> -# Relations as linear maps +# Maps as linear maps A [`sum`](../reference/language/operators.md#sum) or an [`at`](../reference/language/operators.md#at) through a table that gives each -row a label ([a map](../reference/language/relations.md#maps)) is the product -of a matrix and a vector. The relations page describes the same sum in +label a label ([a map](../reference/language/maps.md#maps)) is the product +of a matrix and a vector. The maps page describes the same sum in database words, "joined on" and "grouped by". The matrix form is the sum in the form a paper uses. @@ -19,8 +19,7 @@ dimensions: snapshot: { dtype: int } generator: { dtype: str } zone: { dtype: str } -relations: - zone_of: { dims: [generator, snapshot], missing: absent } + zone_of: { over: [generator, snapshot] } maps: zone_of: { zone: { dim: zone } } parameters: @@ -30,11 +29,10 @@ variables: constraints: zonal: dims: [snapshot, zone] - expression: sum(p, over=generator, by=zone_of[zone]) <= zone_cap + expression: sum(at(p, by=zone_of[generator, snapshot]), over=zone_of, by=zone_of[snapshot, zone]) <= zone_cap looked_up: - dims: [snapshot, generator] - where: zone_of - expression: p <= at(zone_cap, by=zone_of[zone]) + dims: [zone_of] + expression: at(p, by=zone_of[generator, snapshot]) <= at(zone_cap, by=zone_of[snapshot, zone]) objective: sense: minimize expression: sum(p) @@ -43,16 +41,16 @@ objective: `zonal` contains a sum of `p` through the map `zone_of[zone]`, and `looked_up` a lookup of `zone_cap` through the same map. The spec loads. -## The indicator of a relation +## The indicator of a set of tuples -A relation with columns over the dimensions $`D_1, \dots, D_n`$ is a set of -rows, so it is a subset $`R \subseteq D_1 \times \dots \times D_n`$. Its -**indicator** $`\mathbf{1}_R`$ is $`1`$ at a row of the table and $`0`$ -everywhere else. A [map](../reference/language/relations.md#maps) gives each -row of its subject one label, and a row is one combination of key labels (a -key tuple). So a map from the key $`K`$ of its subject into the dimension -$`V`$ is a function $`f: K \to V`$. The set of pairs $`(k, f(k))`$ is a -relation $`R`$ (the graph of $`f`$), and its indicator is +A dimension with [members](../reference/language/dimensions.md#over) +$`D_1, \dots, D_n`$ is a set of tuples, so it is a subset +$`K \subseteq D_1 \times \dots \times D_n`$. Its **indicator** +$`\mathbf{1}_K`$ is $`1`$ at a listed tuple and $`0`$ everywhere else. A +[map](../reference/language/maps.md#maps) gives each label of its subject one +label, so a map from the subject $`K`$ into the dimension $`V`$ is a function +$`f: K \to V`$. The set of pairs $`(k, f(k))`$ is a relation $`R`$ (the graph +of $`f`$), and its indicator is ```math \mathbf{1}_R(k, v) = [\, f(k) = v \,]. @@ -60,54 +58,50 @@ relation $`R`$ (the graph of $`f`$), and its indicator is The bracket is $`1`$ where $`f(k) = v`$ and $`0`$ elsewhere. -By default the function has a value at every key tuple (it is total). With data attached, the tool that builds the model +By default the function has a value at every tuple (it is total). With data +attached, the tool that builds the model ([an engine](../reference/glossary.md#tool)) checks for -[one row per key tuple](../reference/language/relations.md#the-data-contract). -The engine refuses a key tuple with no row or no label. -Under [`missing: absent`](../reference/language/relations.md#missing), the -function has no value at a key tuple with no row or no label (it is partial). With $`\mathcal{G}`$, $`\mathcal{T}`$ and $`\mathcal{Z}`$ the sets of -generators, snapshots and zones, `zone_of[zone]` in the spec above is -a partial $`f: \mathcal{G} \times \mathcal{T} \to \mathcal{Z}`$, because the relation -`zone_of` declares `missing: absent`. - -A [relation](../reference/language/relations.md#relations) with no map is a -subset with no function behind it. So one generator may sit in several -rows, each with its own bus. By default a relation also lists every key tuple, so one -that does not must declare `missing: absent`. - -Every column of a relation is in its key, so a relation with no map has no -label for `at` to read. At load, mathspec refuses `at` through a relation with -no map. +[one row per label](../reference/language/maps.md#the-data-contract) of the +subject. Under [`missing: absent`](../reference/language/maps.md#missing), the +function has no value at a tuple with no label (it is partial). With +$`\mathcal{G}`$, $`\mathcal{T}`$ and $`\mathcal{Z}`$ the sets of generators, +snapshots and zones, `zone_of[zone]` in the spec above is a function +$`f: K \to \mathcal{Z}`$ on the tuples $`K \subseteq \mathcal{G} \times \mathcal{T}`$ +that `zone_of` lists. + +Each member is a map too: `zone_of[generator]` and `zone_of[snapshot]` send a +tuple to its labels. A dimension with members and no declared map has only +these maps, so one generator may sit in several tuples, each with its own +snapshot. ## A join and group-by as a contraction -`sum(p, over=generator, by=zone_of[zone])` multiplies the indicator of the -graph of `zone_of[zone]` by `p`, and sums over the one index that they share and that the -call lists in `over=`: +`zonal` reads `p` at each tuple $`k = (g, t)`$ with `at`, multiplies by the +indicator of the graph of `zone_of[zone]`, and sums over the tuples: ```math -y_{t,z} = \sum_{g} \mathbf{1}_R(g, t, z) \cdot p_{g,t} = \sum_{g \,:\, f(g,\,t) = z} p_{g,t} +y_{t,z} = \sum_{k = (g,\,t) \in K} \mathbf{1}_R(k, z) \cdot p_{g,t} = \sum_{k \in K \,:\, \mathrm{snapshot}(k) = t \wedge f(k) = z} p_{\mathrm{generator}(k),\,\mathrm{snapshot}(k)} ```
--8<-- "docs/static/linear-maps-join.svg"
-With the data in the figure, the join pairs each row of `p` with the row of +With the data in the figure, the join pairs each row of `p` with the tuple of `zone_of` that has the same generator and snapshot. The group-by adds the two pairs in zone `north` at snapshot `0`, so the result `y` has three rows. The typesetter [prints](../reference/notation.md) the right-hand form. The left-hand form is a sum over an index that two factors share (a -**tensor contraction**). The relations page describes each column of the -relation by two properties. Each pair of properties is a position that an -index can take in the formula: +**tensor contraction**). The maps page describes each column of the table +by two properties. Each pair of properties is a position that an index can +take in the formula: -| On the relations page | In the formula | -| ------------------------------------------------------------- | -------------------------------------------------------------------- | -| joined on, the column in `over=` | $`g`$ is on both factors and summed. It is not in the result. | -| grouped by, the column in `by=` | $`z`$ is on the indicator alone and not summed. It is in the result. | -| joined on and grouped by, a key column the call does not name | $`t`$ is on both factors and not summed. It is in the result. | -| neither, a map the call does not name | The map is not in the formula, and the sum does not use it. | +| On the maps page | In the formula | +| ------------------------------------- | -------------------------------------------------------------------- | +| joined on, the subject in `over=` | $`k`$ is on both factors and summed. It is not in the result. | +| grouped by, a map in `by=` | $`z`$ is on the indicator alone and not summed. It is in the result. | +| grouped by, a member in `by=` | $`t`$ is read off $`k`$ and not summed. It is in the result. | +| neither, a map the call does not name | The map is not in the formula, and the sum does not use it. | The result has the **free indices**, which are the indices that are not summed. They are the indices of the operand and of the indicator together, @@ -116,52 +110,47 @@ less the summed one. mathspec refuses a sum at load when the sum breaks one of two conditions, and the formula needs each of them: -- The operand has every column joined on, including each key column that the - call does not name. Without `snapshot`, $`t`$ would sit on the indicator - alone, which is the grouped position, and a sum lists the columns it groups - by in `by=`. +- The operand is over the subject. `p` is over `generator` and `snapshot`, so + `at` reads it at each tuple first. - The operand has no column grouped by. Otherwise $`z`$ would sit on both factors and not be summed. Then the product would match the two occurrences of $`z`$, and the result would gain no extra index (an axis) for $`z`$. You - write that match outside the operator, as in - `zone_cap * sum(p, over=generator, by=zone_of[zone])`. + write that match outside the operator, as `zone_cap` times the sum. -At each $`t`$, the matrix $`M_t[z, g] = \mathbf{1}_R(g, t, z)`$ has one row +At each $`t`$, the matrix $`M_t[z, g] = \mathbf{1}_R((g, t), z)`$ has one row per zone and one column per generator, with entries of zero and one, and -$`y_t = M_t\, p_t`$. Over all snapshots, the key column that the call does not name makes the -matrix zero outside one block per snapshot (**block-diagonal**). A map of a subject with one key column has one block. +$`y_t = M_t\, p_t`$. Over all snapshots, the member `snapshot` that the call +groups by makes the matrix zero outside one block per snapshot +(**block-diagonal**). ## A lookup through a map -`at(zone_cap, by=zone_of[zone])` joins the same table, and sums over the -other index: +`at(zone_cap, by=zone_of[snapshot, zone])` joins the same table, and sums +over the other index: ```math -w_{g,t} = \sum_{z} \mathbf{1}_R(g, t, z) \cdot \mathrm{zone\_cap}_{t,z} = \mathrm{zone\_cap}_{t,\, f(g,\,t)} +w_{k} = \sum_{z} \mathbf{1}_R(k, z) \cdot \mathrm{zone\_cap}_{\mathrm{snapshot}(k),z} = \mathrm{zone\_cap}_{\mathrm{snapshot}(k),\, f(k)} ```
--8<-- "docs/static/linear-maps-at.svg"
-With the data in the figure, each row of `zone_of` takes the value of +With the data in the figure, each tuple of `zone_of` takes the value of `zone_cap` at its snapshot and zone. So at snapshot `0`, wind and gas both take the value at `north`, and no row takes the value at `south`. The indicator and the contraction are the same as for the sum, so the same free-index rule sets the dimensions of the result. As a matrix, `at` is -$`M_t^{\mathsf{T}}`$. The key tuples where $`f`$ has a value are its domain. Because $`R`$ is the -graph of $`f`$, the sum over $`z`$ has exactly one term at each key tuple in +$`M_t^{\mathsf{T}}`$. The tuples where $`f`$ has a value are its domain. Because $`R`$ is the +graph of $`f`$, the sum over $`z`$ has exactly one term at each tuple in the domain. It has no term elsewhere. So the contraction is the composition $`\mathrm{zone\_cap} \circ f`$, which is a **pullback**: the value of -`zone_cap` at $`f(g, t)`$. +`zone_cap` at $`f(k)`$. -That one term is the difference between `at` and `sum`, and mathspec decides -the difference at load from the key alone. Where the columns a call groups by -include the whole key, every group is one row. An `at` is evaluated at the -whole key, so each of its groups is always one row. A `sum` with one row per -group adds up nothing, so mathspec refuses it, and the message suggests `at`. +That one term is the difference between `at` and `sum`. An `at` is evaluated +at the subject, so each of its groups is always one tuple. The two maps are **adjoint**. The sum of elementwise products (the inner product) does not change when the matrix moves to the other side, flipped @@ -193,7 +182,7 @@ where $`\mathbf{1}_R`$ is $`1`$. An engine can multiply a matrix stored that way by a vector in two steps: 1. The engine pairs each row of the table with each row of the operand that - agrees on every shared index, here $`g`$ and $`t`$. That is a join on the columns joined on that + agrees on every shared index, here $`g`$ and $`t`$ of each tuple. That is a join on the columns joined on that matches equal values (an inner equi-join). Each pair is one nonzero product $`1 \cdot p_{g,t}`$, and it takes the label of the column grouped by, $`z`$. @@ -201,7 +190,7 @@ way by a vector in two steps: That is a sum grouped by the dimensions of the result. For `at`, an engine runs step 1 only, because with one row per group no two -pairs have the same coordinate. Where several $`(g, t)`$ share one $`z`$, the +pairs have the same coordinate. Where several tuples share one $`z`$, the engine gets several rows for that $`z`$. Those rows are a column of $`M_t^{\mathsf{T}}`$ with several ones. @@ -221,24 +210,22 @@ At two kinds of position the matrix product has no term. $`\mathrm{zone\_cap} \circ f`$ is undefined where $`f`$ is undefined, so `at` has no row there (it is [absent](../reference/glossary.md#absence)), and [absence spreads](../reference/language/absence.md#how-absence-travels) to - the row. Under the default, no key tuple is outside the domain. With - [`where: zone_of`](../reference/language/absence.md#where), `looked_up` - declares the domain of $`f`$ in the spec, so a reader sees which rows exist - without opening the data. + the row. Under the default, no tuple is outside the domain. `looked_up` is + over `zone_of`, so a reader sees in the spec which rows exist.
--8<-- "docs/static/linear-maps-empty.svg"
With the data in the figure, no generator maps to `south`, so both rows of -`zonal` at `south` are empty groups with no variable. `zone_of` has no row for -`gas` at snapshot `1`, so the lookup has no row there either. +`zonal` at `south` are empty groups with no variable. `zone_of` lists no tuple +for `gas` at snapshot `1`, so the lookup has no row there either. ## Partitions and tests The other two uses of a map, a -[partition](../reference/language/relations.md#partitions) and a -[test](../reference/language/relations.md#tests), are not matrix products. An +[partition](../reference/language/maps.md#partitions) and a +[test](../reference/language/maps.md#tests), are not matrix products. An operator with `within=`, such as `shift`, works separately on each set of members that $`f`$ sends to one value (a fibre). The dimensions of the result do not change. With the map `snapshot: { season: { dim: season } }`, @@ -252,23 +239,22 @@ steps back within each season: Each season is one fibre of `snapshot[season]`, so no value crosses from winter to summer. -A test is an indicator. In a `where`, the name of a relation is -$`\mathbf{1}_R`$ at the coordinate of the entry, and a map alone, such as -`zone_of[zone]`, is the indicator of the domain of $`f`$. +A test is an indicator. In a `where`, the bare name of a dimension with +members is $`\mathbf{1}_K`$ at the coordinate of the entry, and a map alone, +such as `zone_of[zone]`, is the indicator of the domain of $`f`$. You can now judge the dimensions of a sum or an `at` through a map, and why the language has no `join` operator. !!! info "See also" - - [relations and maps](../reference/language/relations.md), for every key a - relation and a map accept + - [maps](../reference/language/maps.md), for every key a map accepts - [how dimensions combine](../reference/language/expressions.md#how-dimensions-combine), for the rule that sets the free indices of every expression - [how absence travels](../reference/language/absence.md#how-absence-travels), for figures of the rows that absence removes - - [sums through a relation](../reference/language/relations.md#sums), - for the message mathspec prints when it refuses a sum with one row per group + - [sums through a map](../reference/language/maps.md#sums), + for the messages mathspec prints when it refuses a sum - [constructs the language already has](limits.md#constructs-the-language-already-has), for the refused `join` operator and what you write instead - [the notation page](../reference/notation.md), for how the typesetter diff --git a/docs/about/sql-and-dataframes.md b/docs/about/sql-and-dataframes.md index ca0905eb7..3454ed3a8 100644 --- a/docs/about/sql-and-dataframes.md +++ b/docs/about/sql-and-dataframes.md @@ -70,13 +70,13 @@ are tables of the rows that a tool builds. `dispatch` has one decision variable per coordinate of `(snapshot, generator)`, and `power_balance` has one row per coordinate of `(snapshot, bus)`. -A [relation](../reference/language/relations.md#relations) is a table whose -columns are all in its primary key, so it lists which combinations of labels -exist. A [map](../reference/language/relations.md#maps) is a column of the +A dimension with [members](../reference/language/dimensions.md#over) is a +table whose member columns are its primary key, so it lists which +combinations of labels exist. A [map](../reference/language/maps.md#maps) is a column of the table of its subject. `generator: { bus: { dim: bus } }` under `maps:` is a table `generator` with the columns `generator` and `bus`, and one row per generator. Under the default `missing: refused`, every generator needs a bus. Under -[`missing: absent`](../reference/language/relations.md#missing), the bus of a +[`missing: absent`](../reference/language/maps.md#missing), the bus of a generator may be null. ## Absence @@ -141,7 +141,7 @@ exact except in four cases: ## Queries outside the language A spec combines two tables only through arithmetic, `sum(by=)` and `at(by=)`. -Each of `sum(by=)` and `at(by=)` joins with the table of a relation or a +Each of `sum(by=)` and `at(by=)` joins with the table of a subject, and drops the key column of the join in the same call. A separate `join` would return a table with a key column that no dimension declares, so mathspec has no `join` operator. diff --git a/docs/contributing.md b/docs/contributing.md index 0f7c8ac9e..c6bb2103b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -183,7 +183,7 @@ only when it meets these conditions: argument, such as `over=snapshot`. - It reads a bounded number of rows for each row of its result. It may filter rows on a column they already have, or join each row against a parameter, a - relation or a map. It may also read neighbouring rows at a fixed offset, or only + dimension with members or a map. It may also read neighbouring rows at a fixed offset, or only the coordinate labels. - If it reads every row, it reads them in one pass over the data. That pass ends before a tool that builds the model diff --git a/docs/examples/index.md b/docs/examples/index.md index 6f08b0868..04d7fc389 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -23,7 +23,7 @@ like yours, and what each line of the file means. inequality covers a running unit and a starting unit. [Open →](commitment.md) - **Units with ports** - One relation lists the ports of each unit, maps give each port a bus and + One dimension lists the ports of each unit, maps give each port a bus and a role, and a parameter with `where:` keeps only the output ports. [Open →](connection.md) - **A sparse set, read four ways** diff --git a/docs/examples/library/generator.md b/docs/examples/library/generator.md index f85e64db7..bbef71774 100644 --- a/docs/examples/library/generator.md +++ b/docs/examples/library/generator.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: CC-BY-4.0 This [fragment](../../reference/glossary.md#fragment) states `Generator` from an open-source power system framework ([PyPSA](https://pypsa.org)). The file declares its three dimensions, the -relation `Generator_port`, two parameters and the variable `Generator_p`. The file +map `generator[port]`, two parameters and the variable `Generator_p`. The file lists `Port_p` and `total_cost` under [`given`](../../reference/language/parameters-variables-constraints.md#given), and [the surface](surface.md) declares them. `Generator_cost` is a [named expression](../../reference/language/named.md#expressions) that adds to diff --git a/docs/examples/library/load.md b/docs/examples/library/load.md index cbe13e09e..6d63e6103 100644 --- a/docs/examples/library/load.md +++ b/docs/examples/library/load.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: CC-BY-4.0 # Loads This [fragment](../../reference/glossary.md#fragment) states `Load` from an open-source power system framework ([PyPSA](https://pypsa.org)). -The file declares the relation `Load_port`, the parameter `Load_p_set` and the +The file declares the map `load[port]`, the parameter `Load_p_set` and the constraint `Load_withdrawal`. The minus sign in front of `Load_p_set` is the only place where the file uses the sign convention of [the surface](surface.md). diff --git a/docs/howto/declare-a-column.md b/docs/howto/declare-a-column.md index 3385d61f0..155a31ea2 100644 --- a/docs/howto/declare-a-column.md +++ b/docs/howto/declare-a-column.md @@ -3,7 +3,7 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> -# Choose between a dimension, a relation, a map and a parameter +# Choose between a dimension, a map and a parameter This guide shows how to choose the declaration for a [column](../reference/glossary.md#column) of your data, in @@ -16,14 +16,13 @@ file and the columns of the data you plan to attach to the spec. Use the first row that fits what you do with the column in the spec: -| In the spec you… | For example | So declare it as | -| -------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| index parameters, variables or constraints over the rows the column lists | `generator`, `snapshot` | a [`dimension`](../reference/language/dimensions.md) | -| index parameters, variables or constraints over the pairs of two dimensions that exist | `connection`, the ports of each unit | a `dimension` with [`over:`](../reference/language/dimensions.md#over) | -| look up a label of another dimension, one per row | the bus of each generator | a [`map`](../reference/language/relations.md#maps) of `generator` into `bus`, a dimension | -| list which pairs of two dimensions exist, with no value | `connection`, the buses a generator may connect to | a [`relation`](../reference/language/relations.md#relations) with [`missing: absent`](../reference/language/relations.md#missing) | -| use its numbers in an expression or a bound | `cost` per generator, `availability` per generator and snapshot | a [`parameter`](../reference/language/parameters-variables-constraints.md#parameters) over the dimensions that index it | -| test its values in a [condition](../reference/language/expressions.md#conditions) | `fuel`, `is_committable` | a `str` or `bool` parameter | +| In the spec you… | For example | So declare it as | +| --------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| index parameters, variables or constraints over the rows the column lists | `generator`, `snapshot` | a [`dimension`](../reference/language/dimensions.md) | +| index or confine entries to the pairs of two dimensions that exist | `connection`, the buses a generator may connect to | a `dimension` with [`over:`](../reference/language/dimensions.md#over) | +| look up a label of another dimension, one per row | the bus of each generator | a [`map`](../reference/language/maps.md#maps) of `generator` into `bus`, a dimension | +| use its numbers in an expression or a bound | `cost` per generator, `availability` per generator and snapshot | a [`parameter`](../reference/language/parameters-variables-constraints.md#parameters) over the dimensions that index it | +| test its values in a [condition](../reference/language/expressions.md#conditions) | `fuel`, `is_committable` | a `str` or `bool` parameter | ## Declare each kind of column @@ -34,9 +33,7 @@ dimensions: generator: { dtype: str } snapshot: { dtype: int } bus: { dtype: str } - -relations: - connection: { dims: [generator, bus], missing: absent } + connection: { over: [generator, bus] } maps: generator: { bus: { dim: bus } } @@ -107,6 +104,6 @@ spec and has no remark that is not a refusal - [Check a spec without data](check.md), for how to read a refusal or advice. - [Dimensions](../reference/language/dimensions.md), - [relations and maps](../reference/language/relations.md) and + [maps](../reference/language/maps.md) and [parameters](../reference/language/parameters-variables-constraints.md#parameters), for every key of each declaration. diff --git a/docs/howto/index.md b/docs/howto/index.md index 5560aa699..eff023785 100644 --- a/docs/howto/index.md +++ b/docs/howto/index.md @@ -28,7 +28,7 @@ To learn the language from the start, follow the
-- **[Choose between a dimension, a relation, a map and a parameter](declare-a-column.md)** +- **[Choose between a dimension, a map and a parameter](declare-a-column.md)** for a column of your data. - **[State a rule that differs by case](cases.md)**, such as committable and non-committable generators, in one spec. diff --git a/docs/reference/composition.md b/docs/reference/composition.md index a14bc4936..344594e7a 100644 --- a/docs/reference/composition.md +++ b/docs/reference/composition.md @@ -176,21 +176,20 @@ The objective is the one that `network.yaml` sets. ### Each kind of entry Two fragments may share a [dimension](language/dimensions.md), a -[relation](language/relations.md#relations), a [map](language/relations.md#maps), a given entry or a -sum. - -| The entry | What `merge` does | -| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| a dimension, a relation or a map | accepts it from every fragment that declares it, where every fragment declares it the same way | -| a `description` on a shared dimension, relation or map | keeps the first wording in the list | -| `ordered: true` on a shared dimension | makes the dimension ordered if one fragment sets it | -| `missing:` on a shared relation or map | requires the same value from every fragment that declares it, where `missing: refused` and no `missing:` are one value | -| an entry under `given:` | checks it against the fragment that declares the name, then folds it in ([given entries](#given-entries)) | -| an expression with `adds_to:` | adds it as a term to the sum in its `adds_to:` ([terms and sums](#terms-and-sums)) | -| `objective` | takes it from the one fragment that sets it, and refuses a second | -| `version` | requires the same value from every fragment | -| `description` at the top of a fragment | drops it | -| any other entry | takes it from the one fragment that declares it, and refuses a second | +[map](language/maps.md#maps), a given entry or a sum. + +| The entry | What `merge` does | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| a dimension or a map | accepts it from every fragment that declares it, where every fragment declares it the same way | +| a `description` on a shared dimension or map | keeps the first wording in the list | +| `ordered: true` on a shared dimension | makes the dimension ordered if one fragment sets it | +| `missing:` on a shared dimension or map | requires the same value from every fragment that declares it, where the default and no `missing:` are one value | +| an entry under `given:` | checks it against the fragment that declares the name, then folds it in ([given entries](#given-entries)) | +| an expression with `adds_to:` | adds it as a term to the sum in its `adds_to:` ([terms and sums](#terms-and-sums)) | +| `objective` | takes it from the one fragment that sets it, and refuses a second | +| `version` | requires the same value from every fragment | +| `description` at the top of a fragment | drops it | +| any other entry | takes it from the one fragment that declares it, and refuses a second | ### Terms and sums @@ -432,10 +431,10 @@ patched `dispatch` has no row at `old`. | a whole entry under a new name | adds it | | a named expression as a [bare string](language/named.md#expressions) | replaces only its body, `expression:` or `cases:`, and keeps its `dims:`, description and `adds_to:`, so the new body may have no dimension outside those `dims:` | | `null` on an entry, a field or a section | applies the rule in [`null` in a patch](#null-in-a-patch) | -| a dimension, a relation or a map | adds it, or accepts it restated as the base declares it, field by field, where a field left out equals its default | -| `description:` on a dimension, a relation or a map of the base | replaces the description of the base, alone or with other fields, and `null` removes it | +| a dimension or a map | adds it, or accepts it restated as the base declares it, field by field, where a field left out equals its default | +| `description:` on a dimension or a map of the base | replaces the description of the base, alone or with other fields, and `null` removes it | | `ordered:` on a restated dimension | makes the dimension ordered for `true`, and refuses `false` over an ordered dimension | -| `missing:` on a relation or a map, alone or with other fields | changes whether every combination needs a row, or every row a label, as on a parameter | +| `missing:` on a map, alone or with other fields | changes whether every label of the subject needs a label of the map, as on a parameter | | an entry under one kind of `given:` | edits, adds or removes it like any entry, and keeps the other kinds | | `version`, `description` | replaces the value of the base | | a field that an earlier patch writes | replaces that value | @@ -522,8 +521,8 @@ A second call with the inverse map returns a spec with the | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | a name as the key of an entry, in `dims:`, under `maps:`, in `adds_to:` or in `given:` | replaces the name | | a name in an expression, `where:`, bound, case or assumption | replaces the name, and keeps the spaces and line breaks around it | -| a map or a relation column named after its dimension, such as `bus` in `unit[bus]` | replaces it with the dimension | -| a map or a relation column named after something else, such as `bus0` in `{bus0: bus}` | keeps it, and refuses a map that changes a name to or from it | +| a map or a member named after its dimension, such as `bus` in `unit[bus]` | replaces it with the dimension | +| a map named after something else, such as `bus0` in `{bus0: bus}` | keeps it, and refuses a map that changes a name to or from it | | a longer name that contains a renamed name, such as `Unit_p_nom` for `Unit_p` | keeps the longer name | | a keyword of an operator, such as `over=` | keeps the keyword | | a quoted label, a label under `one_of:`, or a number such as `1e6` | keeps the label or the number | @@ -601,9 +600,8 @@ patch 'project.yaml' edits the constraint 'power_balnce', which its base does no ### A dimension restated differently -Over a dimension, a relation or a map that its base declares, a patch may -change only `description`, a dimension's `ordered`, and the `missing` of a -relation or a map. A patch +Over a dimension or a map that its base declares, a patch may change only +`description`, a dimension's `ordered`, and the `missing` of a map. A patch that writes any other field restates the entry. Every other field must then be as the base declares it, and a field the patch leaves out equals its default. @@ -697,8 +695,7 @@ rename gives the parameter 'Unit_marginal_cost' the name 'x', which is an argume ### A name that is also a map `rename` refuses a map that changes a name to or from the name of a -[map](language/relations.md#maps) or a relation column that is not named after -its dimension. An expression such as `line[bus0]` reads the map by its name, +[map](language/maps.md#maps) that is not named after its dimension. An expression such as `line[bus0]` reads the map by its name, so the rename would change the map too. Here `line` has the maps `{bus0: bus, bus1: bus}`, and the map is `{'bus0': 'price'}`: diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 68f458364..db70c7fac 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -61,8 +61,8 @@ line](cli.md)). ## Column A column is one variable at one coordinate, so a variable indexed over -`generator` has one column per generator. In a data table or a relation, a -column is one named field of the table. +`generator` has one column per generator. In a data table, a column is one +named field of the table. ## Compile @@ -91,7 +91,7 @@ and a constraint has one row at each coordinate. ## Data preparation Before the data is attached, data preparation is the work of turning raw data -into the tables that a spec declares as parameters and relations. You compute +into the tables that a spec declares as parameters, dimensions and maps. You compute in data preparation anything that the mathspec language cannot state ([what counts as data preparation](../about/limits.md#data-preparation)). @@ -148,10 +148,10 @@ does not build](reading.md#what-a-program-does-not-build)). ## Group -A group is the set of rows of a dimension or a relation to which one +A group is the set of labels of a dimension to which one [map](#map) gives one label. `within=[]` makes `shift`, `sum_back` or `position()` work separately in each group, such as each season -of a year ([partitions](language/relations.md#partitions)). +of a year ([partitions](language/maps.md#partitions)). ## Label @@ -176,10 +176,10 @@ expression before any tool reads it. A file declares its own macros under ## Map -A map gives each row of a dimension or a relation (its +A map gives each label of a dimension (its [subject](#subject)) one label of a dimension, such as the bus of each generator. A condition or an operator reads it as `subject[map]`, as in -`generator[bus]` ([maps](language/relations.md#maps)). +`generator[bus]` ([maps](language/maps.md#maps)). ## Member @@ -190,7 +190,7 @@ a member as a map of the dimension, as in `connection[unit]` ## Missing row -A missing row is a coordinate for which the table of a parameter or a relation +A missing row is a coordinate for which the table of a parameter or a map has no row. The `missing:` key of the entry sets how a tool treats that coordinate ([`missing` on a parameter](language/absence.md#missing-on-a-parameter)). @@ -247,8 +247,8 @@ program in this sense. ## Row A row is one constraint at one coordinate, so a constraint indexed over -`snapshot` has one row per snapshot. In a data table or a relation, a row is -one line of the table ([missing row](#missing-row)). +`snapshot` has one row per snapshot. In a data table, a row is one line of +the table ([missing row](#missing-row)). ## Rung @@ -287,8 +287,8 @@ most two consecutive elements are non-zero ([sos](language/piecewise.md#sos)). ## Subject -The subject of a map is a dimension or a relation, such as `generator` in -`generator[bus]` ([maps](language/relations.md#maps)). +The subject of a map is a dimension, such as `generator` in +`generator[bus]` ([maps](language/maps.md#maps)). ## Surface diff --git a/docs/reference/index.md b/docs/reference/index.md index 11a935b6b..82f7969d9 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -24,8 +24,8 @@ optimisation model ([a spec](glossary.md#spec)). `given:` section. - **[Dimensions](language/dimensions.md)** lists the keys of a named set of labels (a dimension). -- **[Relations and maps](language/relations.md)** lists the keys of a set of - combinations of labels (a relation) and of the label each row has (a map), +- **[Maps](language/maps.md)** lists the keys of the label each label of a + dimension has (a map), and how an expression uses them. - **[Expressions](language/expressions.md)** defines the grammar of arithmetic and of conditions, and how dimensions combine. diff --git a/docs/reference/language/absence.md b/docs/reference/language/absence.md index 731c34885..0e9e5c8b2 100644 --- a/docs/reference/language/absence.md +++ b/docs/reference/language/absence.md @@ -53,17 +53,17 @@ contain. Eight constructs make a coordinate absent: -| Construct | What is absent | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `where:` on a variable | the variable, at the coordinates the condition excludes ([`where`](#where)) | -| `where:` on a parameter | the parameter, at the coordinates the condition excludes ([`where` on a parameter](parameters-variables-constraints.md#where)) | -| `where:` on a constraint | the row ([`where`](#where)) | -| `shift(x, along=d, offset=n)` without `edge=` | the expression, at the edge coordinate ([shift](operators.md#shift)) | -| a key with no row in a `missing: absent` relation | the relation, at that key ([relations](relations.md#missing)) | -| a row with no label in a `missing: absent` map | the map, at that row ([maps](relations.md#missing)) | -| a missing row of a `missing: absent` parameter | the parameter, at that coordinate ([`missing`](#missing)) | -| `within=` at a coordinate in no group | the expression, at that coordinate ([`within=`](operators.md#within)) | -| a quotient whose divisor is zero | the quotient, at that coordinate ([reported values](#reported-values)) | +| Construct | What is absent | +| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `where:` on a variable | the variable, at the coordinates the condition excludes ([`where`](#where)) | +| `where:` on a parameter | the parameter, at the coordinates the condition excludes ([`where` on a parameter](parameters-variables-constraints.md#where)) | +| `where:` on a constraint | the row ([`where`](#where)) | +| `shift(x, along=d, offset=n)` without `edge=` | the expression, at the edge coordinate ([shift](operators.md#shift)) | +| a combination that a dimension with members does not list | the dimension, at that combination ([`missing`](dimensions.md#missing)) | +| a row with no label in a `missing: absent` map | the map, at that row ([maps](maps.md#missing)) | +| a missing row of a `missing: absent` parameter | the parameter, at that coordinate ([`missing`](#missing)) | +| `within=` at a coordinate in no group | the expression, at that coordinate ([`within=`](operators.md#within)) | +| a quotient whose divisor is zero | the quotient, at that coordinate ([reported values](#reported-values)) | No value shifts in at the edge, so a `shift` without `edge=` has no row there: diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index dbc419e75..795c34fdc 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -59,7 +59,7 @@ mathspec loads a dimension that no entry uses, and for that dimension ([advice](../glossary.md#advice)). The label of another dimension that each label has, such as the carrier of -each generator, is a [map](relations.md#maps), not a dimension. +each generator, is a [map](maps.md#maps), not a dimension. ## `one_of` @@ -105,8 +105,8 @@ Variable 'p': 'gnrtr' is not a label of 'carrier', which allows only ['ccgt', 'o mathspec lists the allowed labels and suggests two rewrites. With data attached, a tool refuses a label -outside the list: in the table of the dimension, in every column of a relation -over it, and in the column of every map into it. +outside the list: in the table of the dimension, in every field of a tuple of +a dimension it is a member of, and in the column of every map into it. Only a dimension takes `one_of`, and a `one_of` key on a parameter is refused as an unknown key. @@ -220,7 +220,7 @@ members changes nothing, because mathspec sorts them by name at load. ### The maps of the dimension -Each member is also a [map](relations.md#maps) of the dimension, named after +Each member is also a [map](maps.md#maps) of the dimension, named after the member, with `dim:` the dimension of the member and `missing: refused`. So `connection` above has the maps `unit` and `port` beside the map `bus` that the file declares, and a call reads a member as it reads any map: @@ -335,7 +335,7 @@ The test aligns nothing by name. An entry over `[unit]`, or over `[active]`, does not have every member, so mathspec refuses `where: active` there: ```text -Variable 'built': where-relation 'active' reads dims ['period'] outside the declared dims ['unit']. Add them to dims:, or test a name over the declared dims. +Variable 'built': where-tuple 'active' reads dims ['period'] outside the declared dims ['unit']. Add them to dims:, or test a name over the declared dims. ``` ### `missing` @@ -374,8 +374,7 @@ each pair of regions that trade: dimensions: region: { dtype: str } from_region: { alias: region } -relations: - trade: { dims: [from_region, region], missing: absent } + trade: { over: [from_region, region] } parameters: ire_flo: { dims: [from_region, region], where: trade } variables: @@ -404,7 +403,7 @@ An alias names a declared dimension that is no alias itself. A second alias of !!! info "See also" - - [Relations and maps](relations.md#maps), for the calls that read a member. + - [Maps](maps.md#maps), for the calls that read a member. - - [choose between a dimension, a relation, a map and a parameter](../../howto/declare-a-column.md) + - [choose between a dimension, a map and a parameter](../../howto/declare-a-column.md) for a column of data. diff --git a/docs/reference/language/errors.md b/docs/reference/language/errors.md index a075238b4..35937e701 100644 --- a/docs/reference/language/errors.md +++ b/docs/reference/language/errors.md @@ -142,7 +142,7 @@ advice, so the file still loads and `check` exits `0`. | `kind` | The file has… | The advice is… | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| `never-an-axis` | a dimension that indexes nothing, that nothing sums into, and that no relation or map has a column over | remove it, or keep it if the entries that use it are still to be written | +| `never-an-axis` | a dimension that indexes nothing, that nothing sums into, and that no condition tests, and that no map has a column over | remove it, or keep it if the entries that use it are still to be written | | `given` | a parameter, column, named expression or set of constraint rows (a row family) that it uses and does not declare ([given](parameters-variables-constraints.md#given)) | the file this one is layered onto provides it | | `unbounded` | a variable that no constraint, set or curve uses, whose objective term pushes it towards a bound it does not have | give it a finite bound, or the constraint that was meant to define it | @@ -185,7 +185,7 @@ objective: Both commands print the same two messages of advice: ```text -dimension 'region' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'region' is never used: nothing is indexed by it, nothing sums into it, no condition tests it, and no map is over it. Remove it, or keep it if the entries that use it are still to be written. Variable 'slack' makes this spec unbounded: no constraint names it, and bounds.lower is open, and the +slack term in the minimize objective improves toward it. Give it a finite bounds.lower, or the constraint that was meant to define it. ``` diff --git a/docs/reference/language/expressions.md b/docs/reference/language/expressions.md index 9f5df20d9..441cefda7 100644 --- a/docs/reference/language/expressions.md +++ b/docs/reference/language/expressions.md @@ -207,7 +207,7 @@ An addition is `0` only where every term can be, so Every name a spec declares is in one flat set of names (a namespace). That namespace contains -the dimensions, [relations](relations.md), parameters, variables, named +the dimensions, [maps](maps.md), parameters, variables, named expressions, [named conditions](named.md#conditions), [macros](named.md#macros) and the built-in operators. Two entries with one name are refused at load, and mathspec names both, so no name hides another. For @@ -226,7 +226,7 @@ The place of a name in a string sets which kinds of name it may be: | expression (`p * cost`) | a variable, or a parameter whose values are numbers ([dtype](parameters-variables-constraints.md#parameters)) | | dimension argument (`over=`, `along=`) | a dimension, a list of them for `over=`, or with `by=` a column of the table in `by=` where one has that name | | column argument (`by=`, `within=`) | maps or columns of one subject, written `subject[column]` or `subject[column, …]` | -| condition | a parameter, variable, dimension, relation, map or named condition ([conditions](#conditions)) | +| condition | a parameter, variable, dimension, map or named condition ([conditions](#conditions)) | | `bounds.lower` / `bounds.upper` | a parameter name, or a number | | the `edge` key of `shift` | `'wrap'` in quotes, or a bare number | | `dual` argument (`dual(c)`) | a constraint, resolved against the constraints alone ([named expressions](named.md#dual)) | @@ -259,7 +259,7 @@ dimensions of every expression. Each part of an expression (a node) has a set of | `a + b`, `a * b`, `a / b` | `dims(a) ∪ dims(b)` | one side carries a [member](dimensions.md#over) of a dimension the other carries without it, and the `dims:` of the entry does not list both | | `sum(x)` | `{}` | `dims(x)` is already empty | | `sum(x, over=d)` | `dims(x) − {d}` | `d ∉ dims(x)` | -| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how relations and maps are used](relations.md#how-relations-and-maps-are-used) applies | +| `sum(x, over=d, by=s[c])` | `(dims(x) − joined) ∪ grouped` | a refusal under [how maps are used](maps.md#how-maps-are-used) applies | | `at(x, by=s[m])` | `(dims(x) − joined) ∪ grouped` | the same refusals apply | | `shift(x, along=d, offset=n)` | `dims(x)` | `d ∉ dims(x)` | | `sum_back(x, along=d, window=n)` | `dims(x)` | `d ∉ dims(x)` | @@ -326,8 +326,7 @@ its entry. | ---------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` (bare) | parameter | For a number, it is true where the data has a row, whatever the `missing:`. For a `bool`, it is its value, and the `missing:` sets the value at a missing row ([`missing`](parameters-variables-constraints.md#missing)). `0.0` is a row, and `inflow != 0` tests for non-zero | | `name` (bare) | variable | It is true where the variable exists | -| `name` (bare) | relation | It is true where the relation has a row. A `missing: absent` relation has no row for some combinations ([`missing`](relations.md#missing)), and the bare name selects the combinations it lists | -| `subject[map]` (bare) | map | It is true where the map gives the row of its subject a label. A `missing: absent` map gives some rows no label ([`missing`](relations.md#missing)) | +| `subject[map]` (bare) | map | It is true where the map gives the row of its subject a label. A `missing: absent` map gives some rows no label ([`missing`](maps.md#missing)) | | `name` (bare) | dimension | For a dimension with [members](dimensions.md#the-bare-name-in-a-condition), it is true where the tuple of the frame's member labels is listed. The entry must be over every member. mathspec refuses it on any other dimension | | `name` (bare) | named condition | It tests the [named condition](named.md#conditions). A given condition is true or false at each coordinate, as a `bool` parameter is | | `name OP value` | parameter | It compares element by element. A missing row with no `missing:` value compares false | @@ -360,7 +359,6 @@ under Variable 'p': 'undeclared_thing' not found. Parameters: ['bp_x', 'points'] Dimensions: ['bp', 'generator'] - Relations: [] Check the spelling, or declare 'undeclared_thing'. ``` @@ -522,7 +520,7 @@ adds the subject, `flow`. So the condition is over `flow` alone, which is the fr `rate`. `by=` lists one map, or several as `subject[a, …]`, and every other -rule of [`at` in an expression](relations.md#lookups) applies. +rule of [`at` in an expression](maps.md#lookups) applies. !!! info "See also" @@ -687,7 +685,7 @@ attached, a tool refuses a position that no coordinate occupies, such as `position(snapshot) == 10` over five snapshots. `within=` counts the position inside each group that a -[partition](relations.md#partitions) makes. In the spec below, each period has +[partition](maps.md#partitions) makes. In the spec below, each period has one starting row: ```yaml diff --git a/docs/reference/language/file.md b/docs/reference/language/file.md index 8ed84a423..019591d62 100644 --- a/docs/reference/language/file.md +++ b/docs/reference/language/file.md @@ -18,8 +18,7 @@ declares only `dimensions:` loads. | ------------- | ------------------------------------------------------------------------------------------------------------------ | | `given` | what this file uses and another file declares ([given](parameters-variables-constraints.md#given)) | | `dimensions` | the sets of labels that entries are indexed over ([dimensions](dimensions.md)) | -| `relations` | named sets of combinations of labels of two or more dimensions ([relations](relations.md#relations)) | -| `maps` | the label of a dimension that each row of a dimension or a relation has ([maps](relations.md#maps)) | +| `maps` | the label of a dimension that each label of a dimension has ([maps](maps.md#maps)) | | `parameters` | the data the spec expects ([parameters](parameters-variables-constraints.md#parameters)) | | `conditions` | named conditions, used by name in a `where:`, a `when:` or a `holds:` ([conditions](named.md#conditions)) | | `variables` | what the solver decides ([variables](parameters-variables-constraints.md#variables)) | diff --git a/docs/reference/language/index.md b/docs/reference/language/index.md index 00c34ec68..82c941937 100644 --- a/docs/reference/language/index.md +++ b/docs/reference/language/index.md @@ -18,7 +18,7 @@ _entry_, _coordinate_ and _absent_, in one fixed sense. - **[File shape](file.md)** lists the top-level keys of a spec file, and how mathspec reads the YAML. - **[Given, parameters, variables, objective and constraints](parameters-variables-constraints.md)** lists the keys of the data, the decisions, the goal and the rules, and of the `given:` section. - **[Dimensions](dimensions.md)** lists the keys of a dimension, the set of labels that entries are indexed over, and how a dimension lists tuples of other dimensions. -- **[Relations and maps](relations.md)** lists the keys of a relation, a set of combinations of labels, and of a map, which gives each row one label, and how each operator uses them. +- **[Maps](maps.md)** lists the keys of a map, which gives each label of a dimension one label of another, and how each operator uses them. - **[Expressions](expressions.md)** defines the grammar of arithmetic and of conditions, and how dimensions combine. - **[Named expressions, conditions and macros](named.md)** lists the keys of the three kinds of named piece of an expression. - **[Operators](operators.md)** lists every operator, such as `sum` and `shift`, and the math each one prints. diff --git a/docs/reference/language/maps.md b/docs/reference/language/maps.md new file mode 100644 index 000000000..382b2f675 --- /dev/null +++ b/docs/reference/language/maps.md @@ -0,0 +1,330 @@ + + +# Maps + +A **map** gives each label of a [dimension](dimensions.md) one label of +another dimension, such as the bus of each generator. With maps declared, a +sum can group by them, a lookup can read through them, and a condition can +test them. The file declares the maps, and the labels come with the data. A +set of combinations of labels, such as the buses that each generator may +connect to, is a dimension with [members](dimensions.md#over). + +## `maps` + +Each key under `maps:` names a **subject**, which is a dimension. Each key +under the subject declares one map, which gives every label of the subject one +label of the dimension that `dim:` names. + +```yaml +dimensions: + bus: { dtype: str } + generator: { dtype: str } + line: { dtype: str } +maps: + generator: + bus: { dim: bus } # each generator is on one bus + line: + bus0: { dim: bus } + bus1: { dim: bus, missing: absent } # a line may have an open end +``` + +A map always writes `dim:`, and has no shorter form. A condition or an operator +reads a map as `subject[map]`, so `generator[bus]` is the bus of a generator. + +A dimension that lists its members under [`over:`](dimensions.md#over) already +has a map per member, named after the member and under `missing: refused`. So +`connection[unit]` is the unit of a connection, and every call on this page +reads a member as it reads a map under `maps:`. + +| Key | What it sets | Default | +| ------------- | ----------------------------------------------------------------------------------- | --------- | +| `dim` | required. The dimension whose labels the map gives | | +| `missing` | [`refused` or `absent`](#missing): whether every label of the subject needs a label | `refused` | +| `description` | free text | `null` | + +A map is named after the dimension it refers to, or after no dimension. The +typesetter prints a map as a function from its subject into that dimension, so +`generator[bus]` prints as $`\mathrm{bus}: \mathcal{G} \to \mathcal{B}`$. +mathspec refuses a map at load in five cases: + +- The subject is not a dimension. +- `dim:` names no dimension. +- The map is named after a dimension that it does not refer to. +- The map has the name of its subject. +- The map has the name of a member of its subject. + +With `generator: { period: { dim: zone } }`, mathspec prints: + +```text +maps: 'generator': map 'period' is named after dimension 'period', but refers to 'zone'. Rename the map after what it holds. +``` + +### Cardinalities + +How many labels a label may have (the cardinality) decides whether a fact is a +map or a dimension with members: + +| What the file states | Written | Cardinality | +| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------- | +| each generator has one bus | `maps: { generator: { bus: { dim: bus } } }` | many-to-one | +| a generator may connect to several buses | `dimensions: { connection: { over: [generator, bus] } }` | many-to-many | +| a generator has one zone in each period | `dimensions: { zone_of: { over: [generator, period] } }` and `maps: { zone_of: { zone: { dim: zone } } }` | many-to-one, from a pair | +| a snapshot has a month, a week and a weekday | `maps: { snapshot: { month: { dim: month }, week: { dim: week }, weekday: { dim: weekday } } }` | three maps of one subject | +| a line has two ends, both buses | `maps: { line: { bus0: { dim: bus }, bus1: { dim: bus } } }` | two maps into one dimension | +| a snapshot has a representative snapshot | `maps: { snapshot: { rep: { dim: snapshot } } }` | many-to-one, onto itself | +| a snapshot has neighbours | `dimensions: { next_snapshot: { alias: snapshot }, neighbour: { over: [snapshot, next_snapshot] } }` | many-to-many, onto itself | + +## `missing` + +`missing:` on a map sets whether every label of the subject needs a label of +the map. On a dimension with members, it sets whether every combination of the +members needs a tuple ([`missing` of a dimension](dimensions.md#missing)). + +```yaml +dimensions: + generator: { dtype: str } + bus: { dtype: str } + line: { dtype: str } +maps: + generator: + bus: { dim: bus } # refused: every generator is on a bus + line: + bus0: { dim: bus } + bus1: { dim: bus, missing: absent } # an open end is meant +``` + +
+--8<-- "docs/static/relations-missing.svg" +
+ +At `l3`, the data gives `line[bus1]` no label, so `line[bus1]` is absent there. + +| `missing:` | Result | +| --------------------- | ------------------------------------------------------------------------------- | +| `refused`, by default | a tool refuses the data when it is attached, and names the label | +| `absent` | a label with no label of the map maps to nothing, which is [absent](absence.md) | + +No number can replace a missing label, so at load mathspec refuses a value +such as `missing: 0`: + +```text +maps.generator.bus.missing: missing: 0 on a map, which takes refused or absent. A row with nothing there is refused, or is not in the data. +``` + +The typeset legend lists `` `line[bus1]` is `absent` where the data gives no label `` +beside the dimension of the subject, and nothing for `refused`. + +## The data contract + +With data attached, each subject with maps has one table, named after it. The +table has one column for the subject and one column per map, named after the +map. So the data for the maps of `line` is a table `line` with the columns +`line`, `bus0` and `bus1`. A piece of software that reads a spec +([a tool](../glossary.md#tool)) requires five things of a table: + +- The table has one row per label of the subject, so a generator with two + rows, on two buses, is refused. +- Every label in the column of a map is a label of the dimension it refers to, + and a label that matches none is refused. +- The table has a row for every label of the subject. +- A null is refused, except in the column of a map that declares + `missing: absent`. +- The order of the rows has no meaning, because the order comes from the + [dimension](dimensions.md#ordered). + +A map has no `where:`, so its labels come from the data alone. A tool +therefore knows them before it evaluates any condition, such as the +[`where:` of a parameter](parameters-variables-constraints.md#where). + +An [assumption](assumptions.md) can require labels of a map. For `line[bus1]` +[above](#missing), `{holds: "line[bus1]", where: "closed"}` requires an end for +every closed line, where `closed` is a `bool` parameter over `line`. + +## How maps are used + +A call **joins** the expression it acts on (its operand) to the table of a +subject on their shared columns, and then **groups** the rows it has joined. +In a call, `s[c]` names the subject `s` and its column `c`, and `s[c, …]` +names several columns of one table. A column is a map of `s`, or a member of +`s`. The subject appears once, so one call uses one table. + +| Kind | What it does | Written as | +| ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------- | +| join and group by | rows of the operand match rows of the table, and each group is added up | `sum(x, over=d, by=s[c])` | +| join | each row of the operand matches one row of the table, and takes its label | `at(x, by=s[m])` | +| partition | the dimensions stay, and the rows are grouped | `shift`, `sum_back`, `position` with `within=s[m]` | +| test | a coordinate stays where the map has a label | `s[m]` in a condition | + +Four rules apply to every call: + +1. A call lists every column it uses. +2. A map that the call does not list is not used. +3. The key of a subject, the subject itself, cannot change in a call. +4. A dimension that no column of the table is over passes through to the + result. + +Under the first rule, mathspec refuses `at(x, by=generator)`, and the message +lists the maps of the subject: + +```text +Constraint 'c': at(by=generator) names the subject and none of its maps. Write by=generator[], with a map of 'generator': ['bus']. +``` + +### Sums + +`sum(x, over=d, by=s[c])` sums `x` over the dimensions in `over=`, grouped by +the columns in `by=`. As in `sum(x, over=d)`, `over=` lists what the result +loses and `by=` lists what it gains, and either one may be a list. A sum +through a table adds each row of `x` only to the group that the table gives +it. + +
+--8<-- "docs/static/relations-sum-by.svg" +
+ +`north` adds up `wind` and `gas`, and `south` is `solar` alone. + +Over a dimension with members, a sum groups by members and maps alike. With +`zone_of` over `[generator, period]` and its map `zone`, `connection` over +`[generator, bus]`, and a variable `p` over `[generator, period]`, three sums +have three results: + +| Call | Result | +| -------------------------------------------------------------------------------------- | ------------------- | +| `sum(at(p, by=zone_of[generator, period]), over=zone_of, by=zone_of[period, zone])` | `[period, zone]` | +| `sum(at(p, by=zone_of[generator, period]), over=zone_of, by=zone_of[generator, zone])` | `[generator, zone]` | +| `sum(at(p, by=connection[generator]), over=connection, by=connection[bus])` | `[bus, period]` | + +`at()` reads `p` at each tuple first, and the sum then adds the tuples of each +group. Four more rules apply to a sum through a table: + +- The operand is over the subject, and over no column that the call groups by. +- A name in `over=` is the subject, or else a dimension. With the map `rep` of + `snapshot`, `sum(x, over=snapshot, by=snapshot[rep])` sums over `snapshot` + and groups by `rep`. +- A name in both `over=` and `by=` is refused. +- A dimension in `over=` that no column is named after is summed away after + the call groups the rows. So + `sum(p, over=[generator, period], by=generator[bus])` adds up each bus over + every period. + +Under the first rule, with `load` over `[bus]`, mathspec refuses +`sum(load * p, over=generator, by=generator[bus])` and prints: + +```text +Constraint 'c': sum(by=generator[bus]) groups by ['bus'], which the expression already carries. +Move the factor carrying ['bus'] outside the operator, or group by a map into another dimension. +``` + +`load * sum(p, over=generator, by=generator[bus])` is accepted, because the +sum no longer has `load` inside it. A sum over a member of a dimension with +members is refused, with the rewrite through the dimension: + +```text +Constraint 'c': sum(by=zone_of[zone]): over=generator names a member of 'zone_of', which is one dimension here. Write sum(at(p, by=zone_of[generator]), over=zone_of, by=zone_of[zone]). +``` + +### Lookups + +`at(x, by=s[m])` takes the value of `x` at the label that map `m` gives each +label of `s`. It joins `x` on the maps in `by=` and groups by the subject, so +every group is one row. A lookup adds up nothing, and each row of the result +is the value of `x` at one coordinate. With a variable `build` over `[bus]`, +`at(build, by=line[bus0])` has one row per line: + +
+--8<-- "docs/static/relations-at.svg" +
+ +Lines `l1` and `l2` both take the value of `build` at `north`, and `l3` takes +it at `south`. + +Three rules apply to a lookup: + +- A lookup reads only maps and members. The subject in `by=` is refused. +- The result gains the subject, unless the operand is already over it. + `at(x, by=snapshot[rep])` joins on `rep` alone, so the result gains + `snapshot`. With `p` over `[generator, period]`, + `at(p, by=zone_of[generator, period])` is over `[zone_of]`. +- No two maps in `by=` refer to one dimension, because the operand has one + coordinate along each of its dimensions. + +With `at(build, by=line[line])`, mathspec prints: + +```text +Constraint 'c': at(by=line[line]) names ['line'], a column of 'line' itself. A lookup reads maps at the row. Name one of its maps, ['bus0', 'bus1']. +``` + +### Partitions + +`shift(x, along=d, within=s[m])`, `sum_back(x, along=d, within=s[m])` and +`position(d, within=s[m])` step along `d`, the subject, and split its labels +into groups by the maps in `within=`. The dimensions of the result do not +change. The result is absent at a coordinate that the map gives +[no group](operators.md#within). With the map `season` of `snapshot`, +`shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[season])` +steps back within each season: + +
+--8<-- "docs/static/relations-partition.svg" +
+ +The first snapshot of each season takes the value of the last snapshot of the +same season, and no value crosses from winter to summer. + +`within=` may list two maps into one dimension, but not the subject. A +dimension with members has no order, so mathspec refuses it in `along=` and in +`within=`, and names an entry over the members as the rewrite. + +### Tests + +A condition tests a map at the coordinates of its own entry. It compares a +map, written `s[m]`, against a label, compares two maps, or tests that a label +exists. [Conditions](expressions.md#conditions) lists when two maps may be +compared. A comparison reads one map, so `snapshot[month, weekday] == 'x'` is +refused, and mathspec suggests the rewrite on the second line of the message: + +```text +Variable 'x': Cannot parse the condition "snapshot[month, weekday] == 'x'". +a comparison reads one map of 'snapshot'. Compare each map on its own: snapshot[month] == … AND snapshot[weekday] == …. +Expected end of text, found '[' (at char 8), (line:1, col:9) +``` + +A map alone in a condition, such as `line[bus1]`, is true where the map gives +the label a label, and prints as $`\mathrm{bus1}(l) \text{ is defined}`$. The +bare name of a dimension with members tests its tuples +([the bare name in a condition](dimensions.md#the-bare-name-in-a-condition)): + +```yaml title="flow.yaml" +dimensions: + generator: { dtype: str } + bus: { dtype: str } + snapshot: { dtype: int } + connection: { over: [generator, bus] } # the pairs that are wired +parameters: + load: { dims: [bus, snapshot] } +variables: + flow: + dims: [generator, bus, snapshot] + where: connection + bounds: { lower: 0 } +constraints: + balance: + dims: [bus, snapshot] + expression: sum(flow, over=generator) == load +``` + +
+--8<-- "docs/static/relations-where-bare.svg" +
+ +`flow` exists at the pairs that `connection` lists and is [absent](absence.md) +at every other pair, so `balance` adds up the generators wired to each bus. + +!!! info "See also" + + - [maps as linear maps](../../about/relations-as-linear-maps.md) for the + same calls written as matrices diff --git a/docs/reference/language/operators.md b/docs/reference/language/operators.md index 46a731ea0..74442808b 100644 --- a/docs/reference/language/operators.md +++ b/docs/reference/language/operators.md @@ -26,7 +26,7 @@ A file cannot add an operator, and only | `sum(array)` | `sum` removes every [dimension](dimensions.md) of `array`. The result is a scalar | | `sum(array, over=dim)` | `sum` removes `dim` | | `sum(array, over=[a, …])` | `sum` removes each dimension in the list | -| `sum(array, over=dim, by=subject[c])` | `sum` removes `dim`, and groups the result by the column `c` of the table of `subject`, a [map](relations.md#maps) or a column of a [relation](relations.md#relations). The call joins on the other key columns, so `array` and the result are indexed over them | +| `sum(array, over=dim, by=subject[c])` | `sum` removes `dim`, and groups the result by the column `c` of the table of `subject`, a [map](maps.md#maps) or a [member](dimensions.md#over). The call joins on the key of `subject`, which `array` is indexed over | | `sum(array, over=[dim, …], by=subject[c, …])` | The call does the same with several dimensions and several columns of one table, joins on them together, and groups by their product | | `at(array, by=subject[m])` | The result is `array` read at the label that the map `m` gives each row of `subject`, once per row. The result gains the key of `subject` | | `shift(array, along=dim, offset=n)` | The result is the value `n` positions earlier along `dim`, and the vacated edge is [absent](absence.md) | @@ -53,8 +53,8 @@ each dimension once. `sum(x, over=[a, b])` is the same as `sum(sum(x, over=a), over=b)`, and the [typesetter](../typeset.md) prints it as one sum over both sets. -With `by=`, the sum adds up each group that a [map](relations.md#maps) or a -column of a [relation](relations.md#relations) makes, and the result is +With `by=`, the sum adds up each group that a [map](maps.md#maps) or a +[member](dimensions.md#over) makes, and the result is indexed over that column. The balance at each bus (a nodal balance) is one `sum(by=)` per kind of component: @@ -110,15 +110,15 @@ sum. !!! info "See also" - - [How relations and maps are used](relations.md#how-relations-and-maps-are-used), - for the dimensions that a call through a relation or a map joins on, and + - [How maps are used](maps.md#how-maps-are-used), + for the dimensions that a call through a map joins on, and those its result has. ## `at` -`at` takes, for each row of the subject of a [map](relations.md#maps), the +`at` takes, for each row of the subject of a [map](maps.md#maps), the value of an expression at the label that the map gives the row. `at` adds -nothing up (a [lookup](relations.md#lookups)), and takes one row for each row +nothing up (a [lookup](maps.md#lookups)), and takes one row for each row of the subject. Here `at` takes, for every line, the build decision of its bus: @@ -228,7 +228,7 @@ zero, or no row. ### `within=` -`within=` takes a [partition](relations.md#partitions), such as one into +`within=` takes a [partition](maps.md#partitions), such as one into seasons, and the neighbour of a coordinate is then the one before it in its own group: @@ -392,7 +392,7 @@ Constraint 'stays_up_its_own_time': sum_back(edge=...) takes 'wrap' or nothing. mathspec suggests the rewrite: the constant, written in the expression. As for [`shift`](#within), `within=` takes a -[partition](relations.md#partitions), and the window then stays inside each +[partition](maps.md#partitions), and the window then stays inside each group. ## Every operator as math @@ -428,8 +428,8 @@ The typesetter prints each form from the smallest spec that uses it. - [Absence and where](absence.md) for what each operator does with an absent input. - - [Relations and maps](relations.md#how-relations-and-maps-are-used) for the - relation or the map that `by=` and `within=` take. + - [Maps](maps.md#how-maps-are-used) for the + map or the member that `by=` and `within=` take. - [Macros](named.md#macros) for a composition of operators under one name. - [One construct per spec](../../examples/operators.md) for the smallest spec that uses each form. diff --git a/docs/reference/language/parameters-variables-constraints.md b/docs/reference/language/parameters-variables-constraints.md index 2240d688b..fa3661d35 100644 --- a/docs/reference/language/parameters-variables-constraints.md +++ b/docs/reference/language/parameters-variables-constraints.md @@ -395,23 +395,18 @@ as `` `0` where the data has no row ``. It lists nothing for `refused`. `where:` limits a parameter to the coordinates where a [condition](expressions.md#conditions) is true. The dimensions keep every label, and only the parameter loses coordinates. In this example, `efficiency` -has a value only at the pairs of an entity and a bus that are wired as an -output: +has a value only at the pairs of an entity and a bus that are wired: ```yaml dimensions: entity: { dtype: str } bus: { dtype: str } - role: { dtype: str } snapshot: { dtype: int } -relations: - connection: { dims: [entity, bus], missing: absent } -maps: - connection: { role: { dim: role } } + connection: { over: [entity, bus] } parameters: efficiency: dims: [entity, bus, snapshot] - where: "connection[role] == 'output'" + where: connection missing: 1 variables: p: { dims: [entity, snapshot] } @@ -428,8 +423,8 @@ $$\sum_{e \in \mathcal{E}} \mathrm{efficiency}_{b,e,t} \cdot p_{e,t} = 0 \qquad With the data in the figure, `efficiency` has rows only at the pairs that -`connection` lists as an output. `connection` does not list `boiler` at `el`, -so that pair has no role, and a tool drops its data row. `missing: 1` gives +`connection` lists. `connection` does not list `boiler` at `el`, so a tool +drops that data row. `missing: 1` gives `chp` at `heat` the value `1`. In `balance`, `efficiency * p` is absent at an entity that is not wired to the bus, so the sum adds only the wired entities. @@ -444,7 +439,7 @@ steps: A missing row there is refused, absent or a value, as [`missing:`](#missing) sets. -Under `missing: refused`, a tool requires a row at each output pair and +Under `missing: refused`, a tool requires a row at each wired pair and snapshot of the example, and drops every other row. A tool drops a row of the data outside the condition without refusing the @@ -453,7 +448,8 @@ either, because the parameter has no row there. A tool evaluates the condition from the data alone, before it reads the parameter. So the condition may contain [dimensions](dimensions.md), -[relations](relations.md) and parameters without a `where:`. +dimensions with [members](dimensions.md#over), [maps](maps.md) and parameters +without a `where:`. mathspec refuses four conditions at load: diff --git a/docs/reference/language/piecewise.md b/docs/reference/language/piecewise.md index ef97deba5..c3bd74acd 100644 --- a/docs/reference/language/piecewise.md +++ b/docs/reference/language/piecewise.md @@ -394,7 +394,7 @@ mathspec refuses a sign other than `<=`, `>=` and `==`. ### A link that walks a map On a link with `by: subject[map]`, mathspec looks the weights of the curve -up through a [map](relations.md#lookups), as +up through a [map](maps.md#lookups), as [`at(x, by=subject[map])`](operators.md#at) looks up the value of `x`. The row of the link is over `dims:`, with the dimension that `map` refers to replaced by the key columns of the subject. Each row lies on the curve of the @@ -450,10 +450,10 @@ These rules apply to a walked link: subject that are over dimensions outside `dims:`, and joins on those over dimensions of `dims:`. mathspec refuses a key column over `along`, because a row could then take each breakpoint from a different curve. -- mathspec holds a walk to every rule of [`at`](relations.md#lookups), and quotes +- mathspec holds a walk to every rule of [`at`](maps.md#lookups), and quotes the link in the refusal. - If the map or its subject declares - [`missing: absent`](relations.md#missing), the expansion adds the map test + [`missing: absent`](maps.md#missing), the expansion adds the map test `flow[converter]` to the `where:` of the row, so a flow with no converter has no row. - `method: convex` and `method: lp` take no walked link, and the other methods @@ -786,7 +786,7 @@ at every snapshot. On a gate written as [`at(, by=[])`](operators.md#at), mathspec looks -the variable up through a [map](relations.md#lookups), as `at` looks up +the variable up through a [map](maps.md#lookups), as `at` looks up any value. Here `running` is per unit, and the status of its unit switches the curve of each generator: @@ -824,7 +824,7 @@ objective: ``` The weights of each curve sum to `at(running, by=generator[unit])`. Because -`generator[unit]` declares [`missing: absent`](relations.md#missing), the +`generator[unit]` declares [`missing: absent`](maps.md#missing), the data may give a generator no unit. That generator has no gate, so its curve is ungated. With `missing: 0` on the gate, the gate is `0` outside its `where:`, so the curve is switched off there. Only a generator with no unit then stays ungated. diff --git a/docs/reference/language/relations.md b/docs/reference/language/relations.md deleted file mode 100644 index 17efc3605..000000000 --- a/docs/reference/language/relations.md +++ /dev/null @@ -1,439 +0,0 @@ - - -# Relations and maps - -A **relation** is a set of combinations of labels of -[dimensions](dimensions.md), such as the buses that each generator may connect -to. A **map** gives each row of a dimension or a relation one label of a -dimension, such as the bus of each generator. The file declares both, and the -rows come with the data. This page lists the keys of `relations:` and `maps:`, -the data they expect, and how each operator uses them. - -## `relations` - -Each key under `relations:` declares one relation. - -```yaml -dimensions: - bus: { dtype: str } - generator: { dtype: str } - snapshot: { dtype: int } -relations: - connection: { dims: [generator, bus], missing: absent } # the pairs that are wired - neighbour: { dims: { from: snapshot, to: snapshot }, missing: absent } -``` - -Each row of `connection` is one pair of a generator and a bus, and a pair with -no row is not in the relation. - -| Key | What it sets | Default | -| ------------- | ------------------------------------------------------------------------ | --------- | -| `dims` | required. The columns of the relation, at least two | | -| `missing` | [`refused` or `absent`](#missing): whether every combination needs a row | `refused` | -| `description` | free text | `null` | - -A column is named after its dimension, or after no dimension. Where two -columns share a dimension, each column has its own name in the mapping form, -as in `{from: snapshot, to: snapshot}`. A column named after a dimension that -it is not over is refused, because mathspec reads the name of a column as its -dimension. With `zp: { dims: { period: zone, generator: generator } }`, -mathspec prints: - -```text -Relation 'zp' names column 'period' after dimension 'period', but the column is over 'zone'. Rename the column after what it holds. -``` - -A relation with one column is refused, because one column holds labels of one -dimension, and a map or a condition states that. With -`r: { dims: [generator] }`, mathspec prints: - -```text -Relation 'r' has one column under 'dims:', and a relation needs at least two. To give each generator a label, declare a map under maps: generator:. To mark some of them, declare a bool parameter or a condition. -``` - -A relation is not a dimension, so its name does not go in `dims:`, `over=` or -`along=`. With `flow: { dims: [connection] }`, mathspec prints: - -```text -Variable 'flow' names the relation 'connection', and a relation is not a dimension. Name its dimensions, ['bus', 'generator'], under dims:, and confine the entry with where: connection. -``` - -The order of the columns under `dims:` changes nothing. The typesetter sorts -the columns by name, so `connection` above prints as -$`\mathrm{connection} \subseteq \mathcal{B} \times \mathcal{G}`$. - -## `maps` - -Each key under `maps:` names a **subject**, which is a dimension or a relation. -Each key under the subject declares one map, which gives every row of the -subject one label of the dimension that `dim:` names. - -```yaml -dimensions: - bus: { dtype: str } - generator: { dtype: str } - line: { dtype: str } -maps: - generator: - bus: { dim: bus } # each generator is on one bus - line: - bus0: { dim: bus } - bus1: { dim: bus, missing: absent } # a line may have an open end -``` - -A map always writes `dim:`, and has no shorter form. A condition or an operator -reads a map as `subject[map]`, so `generator[bus]` is the bus of a generator. - -A dimension that lists its members under [`over:`](dimensions.md#over) already -has a map per member, named after the member and under `missing: refused`. So -`connection[unit]` is the unit of a connection, and every call on this page -reads a member as it reads a map under `maps:`. - -| Key | What it sets | Default | -| ------------- | --------------------------------------------------------------------------------- | --------- | -| `dim` | required. The dimension whose labels the map gives | | -| `missing` | [`refused` or `absent`](#missing): whether every row of the subject needs a label | `refused` | -| `description` | free text | `null` | - -A map is named after the dimension it refers to, or after no dimension. The -typesetter prints a map as a function from its subject into that dimension, so -`generator[bus]` prints as $`\mathrm{bus}: \mathcal{G} \to \mathcal{B}`$. -mathspec refuses a map at load in five cases: - -- The subject is neither a dimension nor a relation. -- `dim:` names a relation, or names no dimension. -- The map is named after a dimension that it does not refer to. -- The map has the name of a column of its subject. -- The map has the name of a member of its subject. - -With `generator: { period: { dim: zone } }`, mathspec prints: - -```text -maps: 'generator': map 'period' is named after dimension 'period', but refers to 'zone'. Rename the map after what it holds. -``` - -A relation with two columns over one dimension takes no maps, because a map -gives one label per combination of the dimensions of its subject. - -### Cardinalities - -How many labels a row may have (the cardinality) decides whether a fact is a -map or a relation: - -| What the file states | Written | Cardinality | -| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------- | -| each generator has one bus | `maps: { generator: { bus: { dim: bus } } }` | many-to-one | -| a generator may connect to several buses | `relations: { connection: { dims: [generator, bus], missing: absent } }` | many-to-many | -| a generator has one zone in each period | `relations: { zone_of: { dims: [generator, period] } }` and `maps: { zone_of: { zone: { dim: zone } } }` | many-to-one, from a pair | -| a snapshot has a month, a week and a weekday | `maps: { snapshot: { month: { dim: month }, week: { dim: week }, weekday: { dim: weekday } } }` | three maps of one subject | -| a line has two ends, both buses | `maps: { line: { bus0: { dim: bus }, bus1: { dim: bus } } }` | two maps into one dimension | -| a snapshot has a representative snapshot | `maps: { snapshot: { rep: { dim: snapshot } } }` | many-to-one, onto itself | -| a snapshot has neighbours | `relations: { neighbour: { dims: { from: snapshot, to: snapshot }, missing: absent } }` | many-to-many, onto itself | - -## `missing` - -`missing:` sets whether the data may leave something out. On a relation, it -sets whether every combination of the dimensions under `dims:` needs a row. On -a map, it sets whether every row of the subject needs a label. - -```yaml -dimensions: - generator: { dtype: str } - bus: { dtype: str } - line: { dtype: str } -relations: - connection: { dims: [generator, bus], missing: absent } # most pairs are not wired -maps: - generator: - bus: { dim: bus } # refused: every generator is on a bus - line: - bus0: { dim: bus } - bus1: { dim: bus, missing: absent } # an open end is meant -``` - -
---8<-- "docs/static/relations-missing.svg" -
- -At `l3`, the data gives `line[bus1]` no label, so `line[bus1]` is absent there. - -| `missing:` | Result | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `refused`, by default | a tool refuses the data when it is attached, and names the combination or the row | -| `absent` | a combination with no row is not in the relation, and a row with no label maps to nothing, which is [absent](absence.md) | - -No number can replace a missing label, so at load mathspec refuses a value -such as `missing: 0`: - -```text -maps.generator.bus.missing: missing: 0 on a map, which takes refused or absent. A row with nothing there is refused, or is not in the data. -``` - -Under the default `refused`, a relation needs a row for every combination, so -`connection` would need every generator wired to every bus. Most relations are -sparse, so they declare `missing: absent`. - -The typeset legend lists `` `connection` is `absent` where the data has no row `` -and `` `line[bus1]` is `absent` where the data gives no label `` beside each -dimension they are over, and nothing for `refused`. - -## The data contract - -With data attached, each relation and each subject with maps has one table, -named after it. The table of a relation has one column per column under -`dims:`. The table of a subject also has one column per map, named after the -map. So the data for the maps of `line` is a table `line` with the columns -`line`, `bus0` and `bus1`. A piece of software that reads a spec -([a tool](../glossary.md#tool)) requires five things of a table: - -- The table has one row per combination of the columns of its subject, so a - generator with two rows, on two buses, is refused. -- Every label in the column of a map is a label of the dimension it refers to, - and a label that matches none is refused. -- The table has a row for every combination of its dimensions, unless the - relation declares `missing: absent`. The table of a dimension has a row for - every label of the dimension. -- A null is refused, except in the column of a map that declares - `missing: absent`. -- The order of the rows has no meaning, because the order comes from the - [dimension](dimensions.md#ordered). - -A relation and a map have no `where:`, so their rows and labels come from the -data alone. A tool therefore knows them before it evaluates any condition, -such as the [`where:` of a parameter](parameters-variables-constraints.md#where). - -An [assumption](assumptions.md) can require rows of a relation or labels of a -map. For `line[bus1]` [above](#missing), `{holds: "line[bus1]", where: "closed"}` -requires an end for every closed line, where `closed` is a `bool` parameter -over `line`. - -## How relations and maps are used - -A relation fixes no direction, so the same table can map generators to buses -or buses to generators. A call **joins** the expression it acts on (its -operand) to the table on their shared columns, and then **groups** the rows it -has joined. In a call, `s[c]` names the subject `s` and its column `c`, and -`s[c, …]` names several columns of one table. A column is a map of `s`, or one -of the columns of a relation under `dims:`. The subject appears once, so one -call uses one table. - -| Kind | What it does | Written as | -| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | -| join and group by | rows of the operand match rows of the table, and each group is added up | `sum(x, over=d, by=s[c])` | -| join | each row of the operand matches one row of the table, and takes its label | `at(x, by=s[m])` | -| partition | the dimensions stay, and the rows are grouped | `shift`, `sum_back`, `position` with `within=s[m]` | -| test | a coordinate stays where the relation has a row, or where the map has a label | `r` or `s[m]` in a condition | - -Four rules apply to every call: - -1. A call lists every column it uses. -2. A map that the call does not list is not used. -3. The key of a subject cannot change in a call. -4. A dimension that no column of the table is over passes through to the - result. - -Under the first rule, mathspec refuses `at(x, by=generator)`, and the message -lists the maps of the subject: - -```text -Constraint 'c': at(by=generator) names the subject and none of its maps. Write by=generator[], with a map of 'generator': ['bus']. -``` - -### Sums - -`sum(x, over=d, by=s[c])` sums `x` over the columns in `over=`, grouped by -the columns in `by=`. As in `sum(x, over=d)`, `over=` lists what the result -loses and `by=` lists what it gains, and either one may be a list. A sum -through a table adds each row of `x` only to the groups that the table lists -for it. A row that the table does not list is left out. - -
---8<-- "docs/static/relations-sum-by.svg" -
- -`north` adds up `wind` and `gas`, and `south` is `solar` alone. - -Each column of the table is either **joined on** or not, and either -**grouped by** or not, and the call sets both: - -| Column of the table | Joined on | Grouped by | In the result | -| ----------------------------------- | --------- | ---------- | ------------- | -| a column in `over=` | yes | no | removed | -| a column in `by=` | no | yes | added | -| a key column the call does not list | yes | yes | kept | -| a map the call does not list | no | no | not used | - -With the relation `zone_of` over `[generator, period]` and its map `zone`, the -relation `connection` over `[generator, bus]`, and a variable `p` over -`[generator, period]`, three sums have three results: - -| Call | Joins on | Groups by | Result | -| -------------------------------------------- | ------------------- | ----------------- | ------------------- | -| `sum(p, over=generator, by=zone_of[zone])` | `generator, period` | `zone, period` | `[period, zone]` | -| `sum(p, over=period, by=zone_of[zone])` | `period, generator` | `zone, generator` | `[generator, zone]` | -| `sum(p, over=generator, by=connection[bus])` | `generator` | `bus` | `[bus, period]` | - -Five more rules apply to a sum through a table: - -- The operand is over every column that the call joins on, and over none that - it groups by. A column that the operand is over is joined on. -- A name in `over=` is a column of the table, or else a dimension. With the - map `rep` of `snapshot`, `sum(x, over=snapshot, by=snapshot[rep])` joins on - the key column `snapshot` and groups by `rep`. Where two columns are over one - dimension, the name selects which one, so - `sum(x, over=from, by=neighbour[to])` joins on `from` and groups by `to`. -- A name in both `over=` and `by=` is refused. -- A dimension in `over=` that no column is named after is summed away after - the call groups the rows. So - `sum(p, over=[generator, period], by=generator[bus])` adds up each bus over - every period. -- A sum adds up several rows per group, and where the columns grouped by are - the whole key, every group is one row. A sum whose groups are one row each - is a join with no group-by, which is `at`. - -Under the first rule, with `load` over `[bus]`, mathspec refuses -`sum(load * p, over=generator, by=generator[bus])` and prints: - -```text -Constraint 'c': sum(by=generator[bus]) groups by ['bus'], which the expression already carries. -Move the factor carrying ['bus'] outside the operator, or group by a map into another dimension. -``` - -`load * sum(p, over=generator, by=generator[bus])` is accepted, because the -sum no longer has `load` inside it. - -Under the last rule, with `p` over `[generator, period, zone]`, mathspec -refuses `sum(p, over=zone, by=zone_of[generator, period])` and prints: - -```text -Constraint 'cap': sum(by=zone_of[generator, period]): the columns this sum groups by, ['generator', 'period'], hold the whole key ['generator', 'period'], so every group is one row and the sum adds nothing. Write at(..., by=zone_of[zone]), or group by a map. -``` - -### Lookups - -`at(x, by=s[m])` takes the value of `x` at the label that map `m` gives each -row of `s`. It joins `x` on the maps in `by=` and groups by the key, so every -group is one row. A lookup adds up nothing, and each row of the result is the -value of `x` at one coordinate. With a variable `build` over `[bus]`, -`at(build, by=line[bus0])` has one row per line: - -
---8<-- "docs/static/relations-at.svg" -
- -Lines `l1` and `l2` both take the value of `build` at `north`, and `l3` takes -it at `south`. - -Three rules apply to a lookup: - -- A lookup reads only maps. A key column in `by=` is refused, and so is a - relation with no map, where one combination can have several rows. -- The result gains every key column that the operand is not already over. A - key column over a dimension that the operand is over is joined on too, - unless a map in `by=` already refers to that dimension. With `price` over - `[zone, period]`, `at(price, by=zone_of[zone])` joins on `zone` and - `period`, and its result is `[generator, period]`. `at(x, by=snapshot[rep])` - joins on `rep` alone, so the result gains the key column `snapshot`. -- No two maps in `by=` refer to one dimension, because the operand has one - coordinate along each of its dimensions. - -With `at(build, by=line[line])`, mathspec prints: - -```text -Constraint 'c': at(by=line[line]) names ['line'], a column of 'line' itself. A lookup reads maps at the row. Name one of its maps, ['bus0', 'bus1']. -``` - -### Partitions - -`shift(x, along=d, within=s[m])`, `sum_back(x, along=d, within=s[m])` and -`position(d, within=s[m])` step along the key column over `d`. They join on -the other key columns, and split the rows into groups by the maps in -`within=`. The dimensions of the result do not change. The result is absent -at a coordinate that the map gives [no group](operators.md#within). With the -map `season` of `snapshot`, -`shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[season])` -steps back within each season: - -
---8<-- "docs/static/relations-partition.svg" -
- -The first snapshot of each season takes the value of the last snapshot of the -same season, and no value crosses from winter to summer. - -`within=` may list two maps into one dimension, but not a key column. A -relation with no map makes no groups, so mathspec refuses it in `within=`: - -```text -Constraint 'd': shift(within=sp[period]): 'sp' has no map, so it makes no groups. Declare the group as a map of the dimension shift steps along, under maps: snapshot:. -``` - -### Tests - -A condition tests a relation or a map at the coordinates of its own entry. It -compares a map, written `s[m]`, against a label, compares two maps, or tests -that a row or a label exists. [Conditions](expressions.md#conditions) lists -when two maps may be compared. A comparison reads one map, so -`snapshot[month, weekday] == 'x'` is refused, and mathspec suggests the -rewrite on the second line of the message: - -```text -Variable 'x': Cannot parse the condition "snapshot[month, weekday] == 'x'". -a comparison reads one map of 'snapshot'. Compare each map on its own: snapshot[month] == … AND snapshot[weekday] == …. -Expected end of text, found '[' (at char 8), (line:1, col:9) -``` - -A map alone in a condition, such as `line[bus1]`, is true where the map gives -the row a label. A relation name alone is true where the relation has a row. -On a variable, the condition leaves the variable absent at every pair that the -relation does not list: - -```yaml title="flow.yaml" -dimensions: - generator: { dtype: str } - bus: { dtype: str } - snapshot: { dtype: int } -relations: - connection: { dims: [generator, bus], missing: absent } # the pairs that are wired -parameters: - load: { dims: [bus, snapshot] } -variables: - flow: - dims: [generator, bus, snapshot] - where: connection - bounds: { lower: 0 } -constraints: - balance: - dims: [bus, snapshot] - expression: sum(flow, over=generator) == load -``` - -
---8<-- "docs/static/relations-where-bare.svg" -
- -`flow` exists at the pairs that `connection` lists and is [absent](absence.md) -at every other pair, so `balance` adds up the generators wired to each bus. - -`python -m mathspec markdown flow.yaml` prints the domain of `flow` and the -constraint: - -```math -\mathit{flow}_{b,g,t} \ge 0 \qquad \forall\, \left( b,\ g \right) \in \mathrm{connection},\ t \in \mathcal{T} -``` - -```math -\sum_{g \in \mathcal{G}} \mathit{flow}_{b,g,t} = \mathrm{load}_{b,t} \qquad \forall\, b \in \mathcal{B},\ t \in \mathcal{T} -``` - -The domain of `flow` is the pairs `(b, g)` in `connection`, at every snapshot. -The columns are sorted to `(bus, generator)`. A map test prints as -$`\mathrm{bus1}(l) \text{ is defined}`$. - -!!! info "See also" - - - [relations as linear maps](../../about/relations-as-linear-maps.md) for the - same calls written as matrices diff --git a/docs/reference/notation.md b/docs/reference/notation.md index edd90fed6..f0f03f626 100644 --- a/docs/reference/notation.md +++ b/docs/reference/notation.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: CC-BY-4.0 This page lists each construct of the language beside the math that [the typesetter](typeset.md) prints for it. Each section has the math of one -kind of construct, and the legend lists the symbol of each dimension, relation and parameter. +kind of construct, and the legend lists the symbol of each dimension, map and parameter. Each construct is printed as its YAML and then its equation. Most of the YAML comes from one test spec, @@ -23,7 +23,7 @@ typesetter changes nothing else. ### Legend -A dimension, a relation, a map and a parameter declare no equation; what they print is the legend every spec opens with. +A dimension, a map and a parameter declare no equation; what they print is the legend every spec opens with. ```yaml dimensions: @@ -37,10 +37,8 @@ dimensions: bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through site: { over: [generator, bus] } # a dimension that lists its members: the legend prints it as a subset of their product corridor: { over: [from_bus, bus], missing: refused } # a member and its alias, and every combination required: the product itself - -relations: - gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other - connection: { dims: [generator, bus], missing: absent } # a relation with no map: many-to-many, read only by sum with both ends named + gen_zone: { over: [generator, snapshot], missing: refused } # a tuple over two dimensions, with a map: a call reads an entry at each tuple and groups by a member + connection: { over: [generator, bus] } # a tuple with no map: many-to-many, read only through its members maps: generator: { bus: { dim: bus }, technology: { dim: technology } } # two maps of one subject, read to both at once @@ -80,67 +78,69 @@ parameters: | Symbol | Meaning | |---|---| | $`\mathcal{B}`$ | index $`b`$ — `bp` | -| $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}`$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label | -| $`\mathcal{C}`$ | index $`c`$ — `corridor`, $`\mathcal{C} = \mathcal{U} \times \mathcal{U}`$ | +| $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{E} \to \mathcal{U}`$, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{C}`$ | index $`c`$ — `connection`, $`\mathcal{C} \subseteq \mathcal{U} \times \mathcal{E}`$ | +| $`\mathcal{O}`$ | index $`o`$ — `corridor`, $`\mathcal{O} = \mathcal{U} \times \mathcal{U}`$ | | $`\mathcal{U}`$ | index $`u'`$ — `from_bus`, an alias of `bus` | -| $`\mathcal{G}`$ | index $`g`$ — `generator` with $`\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}`$, `connection` is `absent` where the data has no row | +| $`\mathcal{G}`$ | index $`g`$ — `gen_zone`, $`\mathcal{G} = \mathcal{E} \times \mathcal{T}`$ with $`\mathrm{zone}: \mathcal{G} \to \mathcal{Z}`$ | +| $`\mathcal{E}`$ | index $`e`$ — `generator` with $`\mathrm{bus}: \mathcal{E} \to \mathcal{U},\ \mathrm{technology}: \mathcal{E} \to \mathcal{H}`$ | | $`\mathcal{S}`$ | index $`s`$ — `season` with $`\mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | -| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}`$ | -| $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | -| $`\mathcal{E}`$ | index $`e`$ — `technology` with $`\mathrm{technology}: \mathcal{G} \to \mathcal{E}`$ | -| $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{E}`$ | +| $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | +| $`\mathcal{H}`$ | index $`h`$ — `technology` with $`\mathrm{technology}: \mathcal{E} \to \mathcal{H}`$ | +| $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{G} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | #### Parameters | Symbol | Meaning | |---|---| | $`\mathrm{area\_weight}`$ | `area_weight` over $`\mathcal{U}`$, only where $`\mathrm{area}(u) \text{ is defined}`$ | -| $`\mathrm{bp\_heat}`$ | `bp_heat` over $`\mathcal{B} \times \mathcal{G}`$ | -| $`\mathrm{bp\_run}`$ | `bp_run` over $`\mathcal{B} \times \mathcal{G}`$ | -| $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | -| $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | +| $`\mathrm{bp\_heat}`$ | `bp_heat` over $`\mathcal{B} \times \mathcal{E}`$ | +| $`\mathrm{bp\_run}`$ | `bp_run` over $`\mathcal{B} \times \mathcal{E}`$ | +| $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{E}`$, $`0`$ where the data has no row | +| $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{E}`$, $`0`$ where the data has no row | | $`\mathrm{budget}`$ | `budget` (scalar) | -| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{C}`$ | -| $`\mathrm{cost}`$ | `cost` over $`\mathcal{G}`$, $`0`$ where the data has no row | -| $`\mathrm{eta}`$ | `eta` over $`\mathcal{G}`$ | +| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{O}`$ | +| $`\mathrm{cost}`$ | `cost` over $`\mathcal{E}`$, $`0`$ where the data has no row | +| $`\mathrm{eta}`$ | `eta` over $`\mathcal{E}`$ | | $`\mathrm{growth}`$ | `growth` (scalar) | -| $`\mathrm{is\_flexible}`$ | `is_flexible` over $`\mathcal{G}`$, `false` where the data has no row | -| $`\mathrm{lead}`$ | `lead` over $`\mathcal{G}`$ | -| $`\mathrm{link\_eff}`$ | `link_eff` over $`\mathcal{U} \times \mathcal{G}`$, only where $`\left( u,\ g \right) \in \mathrm{connection}`$, $`1`$ where the data has no row | +| $`\mathrm{is\_flexible}`$ | `is_flexible` over $`\mathcal{E}`$, `false` where the data has no row | +| $`\mathrm{lead}`$ | `lead` over $`\mathcal{E}`$ | +| $`\mathrm{link\_eff}`$ | `link_eff` over $`\mathcal{U} \times \mathcal{E}`$, only where $`\left( u,\ e \right) \in \mathrm{connection}`$, $`1`$ where the data has no row | | $`\mathrm{load}`$ | `load` over $`\mathcal{U} \times \mathcal{T}`$ | -| $`\mathrm{min\_up}`$ | `min_up` over $`\mathcal{G}`$ | -| $`\mathrm{p}^{\mathrm{max}}`$ | `p_max` over $`\mathcal{G}`$, $`\infty`$ where the data has no row | -| $`\mathrm{p}^{\mathrm{min}}`$ | `p_min` over $`\mathcal{G}`$ | +| $`\mathrm{min\_up}`$ | `min_up` over $`\mathcal{E}`$ | +| $`\mathrm{p}^{\mathrm{max}}`$ | `p_max` over $`\mathcal{E}`$, $`\infty`$ where the data has no row | +| $`\mathrm{p}^{\mathrm{min}}`$ | `p_min` over $`\mathcal{E}`$ | | $`\mathrm{susceptance}`$ | `susceptance` over $`\mathcal{U} \times \mathcal{U}`$, $`0`$ where the data has no row | -| $`\mathrm{tech\_cap}`$ | `tech_cap` over $`\mathcal{U} \times \mathcal{E}`$, `absent` where the data has no row | +| $`\mathrm{tech\_cap}`$ | `tech_cap` over $`\mathcal{U} \times \mathcal{H}`$, `absent` where the data has no row | | $`\mathrm{zone\_cap}`$ | `zone_cap` over $`\mathcal{Z}`$ | #### Conditions | Symbol | Meaning | |---|---| -| $`\mathrm{dispatchable}`$ | `dispatchable` over $`\mathcal{G}`$ — a unit that dispatches and cannot be turned down | -| $`\mathrm{priced\_dispatch}`$ | `priced_dispatch` over $`\mathcal{G}`$ | +| $`\mathrm{dispatchable}`$ | `dispatchable` over $`\mathcal{E}`$ — a unit that dispatches and cannot be turned down | +| $`\mathrm{priced\_dispatch}`$ | `priced_dispatch` over $`\mathcal{E}`$ | #### Variables | Symbol | Meaning | |---|---| -| $`\mathit{fuel}`$ | `fuel` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{fuel}`$ | `fuel` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{headroom}`$ | `headroom` (scalar), $`0`$ where the mask leaves it out | -| $`\mathit{heat}`$ | `heat` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{on}`$ | `on` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`p`$ | `p` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{heat}`$ | `heat` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{on}`$ | `on` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`p`$ | `p` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{reserve}`$ | `reserve` (scalar) | | $`\mathit{site\_out}`$ | `site_out` over $`\mathcal{I} \times \mathcal{T}`$ | | $`\mathit{slack}`$ | `slack` over $`\mathcal{T}`$ | -| $`\mathit{spare}`$ | `spare` over $`\mathcal{G}`$ | +| $`\mathit{spare}`$ | `spare` over $`\mathcal{E}`$ | | $`\mathit{spill}`$ | `spill` over $`\mathcal{T}`$ | | $`\theta`$ | `theta` over $`\mathcal{U}`$ | -| $`\mathit{units}`$ | `units` over $`\mathcal{G}`$ | -| $`\mathit{warm}`$ | `warm` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{weight}`$ | `weight` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{units}`$ | `units` over $`\mathcal{E}`$ | +| $`\mathit{warm}`$ | `warm` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{weight}`$ | `weight` over $`\mathcal{E} \times \mathcal{T}`$ | #### Definitions @@ -149,10 +149,10 @@ parameters: | $`\mathit{lcoe}`$ | `lcoe` (scalar) | | $`\mathit{marginal\_price}`$ | `marginal_price` over $`\mathcal{U} \times \mathcal{T}`$ | | $`\mathit{net}`$ | `net` over $`\mathcal{T}`$ — what a snapshot spills, less what it lacks | -| $`\mathrm{rating}`$ | `rating` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathrm{rating}`$ | `rating` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{spend}`$ | `spend` over $`\mathcal{T}`$ — what a snapshot's dispatch costs | -| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{G}`$ | -| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{G} \times \mathcal{T}`$ — what starting a unit in this snapshot costs, which the horizon's edge changes | +| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{E}`$ | +| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{E} \times \mathcal{T}`$ — what starting a unit in this snapshot costs, which the horizon's edge changes | #### Notation @@ -180,7 +180,7 @@ variables: ``` ```math -\mathrm{p}^{\mathrm{min}}_{g} \le p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \vee \mathrm{p}^{\mathrm{min}}_{g} > 0 +\mathrm{p}^{\mathrm{min}}_{e} \le p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} \vee \mathrm{p}^{\mathrm{min}}_{e} > 0 ``` #### Lower bound only @@ -249,7 +249,7 @@ variables: ``` ```math -\mathit{on}_{g,t} \in \{0, 1\} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{on}_{e,t} \in \{0, 1\} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Bounded integer domain @@ -265,7 +265,7 @@ variables: ``` ```math -0 \le \mathit{units}_{g} \le 10, \mathit{units}_{g} \in \mathbb{Z} \qquad \forall\, g \in \mathcal{G} +0 \le \mathit{units}_{e} \le 10, \mathit{units}_{e} \in \mathbb{Z} \qquad \forall\, e \in \mathcal{E} ``` #### Unbounded integer domain @@ -280,7 +280,7 @@ variables: ``` ```math -\mathit{spare}_{g} \in \mathbb{Z} \qquad \forall\, g \in \mathcal{G} +\mathit{spare}_{e} \in \mathbb{Z} \qquad \forall\, e \in \mathcal{E} ``` #### Scalar variable @@ -327,7 +327,7 @@ variables: ``` ```math -0 \le \mathit{weight}_{g,t} \le 1 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +0 \le \mathit{weight}_{e,t} \le 1 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Second axis of a curve @@ -342,7 +342,7 @@ variables: ``` ```math -\mathit{fuel}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{fuel}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Third axis of a curve @@ -357,7 +357,7 @@ variables: ``` ```math -\mathit{heat}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{heat}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Variable bounded by a curve @@ -372,7 +372,7 @@ variables: ``` ```math -\mathit{op\_cost}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{op\_cost}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Binary variable with a condition @@ -388,7 +388,7 @@ variables: ``` ```math -\mathit{warm}_{g,t} \in \{0, 1\} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{g} +\mathit{warm}_{e,t} \in \{0, 1\} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{e} ``` ### Objective @@ -404,10 +404,10 @@ objective: ``` ```math -\max \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} \cdot \mathrm{growth}^{\mathrm{lead}_{g}} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{g}} \right)^{2} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{p}^{\mathrm{max}}_{g} - \mathit{reserve} - \mathit{headroom} +\max \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} \cdot \mathrm{growth}^{\mathrm{lead}_{e}} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{e}} \right)^{2} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{p}^{\mathrm{max}}_{e} - \mathit{reserve} - \mathit{headroom} ``` -### Relations and maps +### Maps and tuples #### Sum through a map @@ -419,7 +419,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{spill}_{t} - \mathit{slack}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{spill}_{t} - \mathit{slack}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` #### Sum over every dimension @@ -434,7 +434,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \le \mathrm{budget} +\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \le \mathrm{budget} ``` #### `at` through a map @@ -464,7 +464,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u \wedge \mathrm{technology}(g) = e} p_{g,t} \le \mathrm{tech\_cap}_{u,e} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ e \in \mathcal{E} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u \wedge \mathrm{technology}(e) = h} p_{e,t} \le \mathrm{tech\_cap}_{u,h} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ h \in \mathcal{H} ``` #### `at` through two maps @@ -479,7 +479,7 @@ constraints: ``` ```math -\mathit{units}_{g} \le \mathrm{tech\_cap}_{\mathrm{bus}(g),\mathrm{technology}(g)} \qquad \forall\, g \in \mathcal{G} +\mathit{units}_{e} \le \mathrm{tech\_cap}_{\mathrm{bus}(e),\mathrm{technology}(e)} \qquad \forall\, e \in \mathcal{E} ``` #### Shift within one map @@ -495,27 +495,27 @@ constraints: ``` ```math -\mathit{units}_{g} \le \mathit{units}_{g \boxminus_{0}^{\mathrm{bus}(g)} 1} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(g),\ \mathrm{technology}(g) \right)}(g) = 0 +\mathit{units}_{e} \le \mathit{units}_{e \boxminus_{0}^{\mathrm{bus}(e)} 1} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(e),\ \mathrm{technology}(e) \right)}(e) = 0 ``` -#### Sum through a relation +#### Sum over a tuple -a sum through a relation with no map: the domain is a row of the relation rather than a label +a sum over a tuple with no map: the domain is a tuple rather than a label ```yaml constraints: relational: dims: [snapshot, bus] - expression: sum(p, over=generator, by=connection[bus]) <= load + expression: sum(at(p, by=connection[generator]), over=connection, by=connection[bus]) <= load ``` ```math -\sum_{g \in \mathcal{G} \,:\, \left( u,\ g \right) \in \mathrm{connection}} p_{g,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{c \in \mathcal{C} \,:\, \mathrm{bus}(c) = u} p_{\mathrm{generator}(c),t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` -#### Relation as a condition +#### Tuple as a condition -a relation as a where: the row of the frame has to be a member of the relation +a tuple as a where: the frame's member labels have to form a listed tuple ```yaml constraints: @@ -526,7 +526,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \left( u,\ g \right) \in \mathrm{connection} +p_{e,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \left( u,\ e \right) \in \mathrm{connection} ``` #### Map into its own dimension @@ -574,65 +574,65 @@ constraints: \theta_{u} = \sum_{u' \in \mathcal{U} \,:\, u' = u} \sum_{u'' \in \mathcal{U}} \mathrm{susceptance}_{u'',u'} \qquad \forall\, u \in \mathcal{U} ``` -#### Sum through a map of a relation +#### Sum through a map of a tuple -a grouping through a two-key map, summing one key away: the condition reads the other, and the row keeps it +a grouping through a map of a tuple, keeping one member: the row keeps the snapshot ```yaml constraints: zonal: dims: [snapshot, zone] - expression: sum(p, over=generator, by=gen_zone[zone]) <= zone_cap + expression: sum(at(p, by=gen_zone[generator, snapshot]), over=gen_zone, by=gen_zone[snapshot, zone]) <= zone_cap ``` ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} \le \mathrm{zone\_cap}_{z} \qquad \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} +\sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathrm{zone\_cap}_{z} \qquad \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} ``` -#### Sum over the other column of a relation +#### Sum keeping the other member of a tuple -the same table summing its other key away +the same tuple keeping its other member ```yaml constraints: zonal_history: dims: [generator, zone] - expression: sum(p, over=snapshot, by=gen_zone[zone]) <= zone_cap + expression: sum(at(p, by=gen_zone[generator, snapshot]), over=gen_zone, by=gen_zone[generator, zone]) <= zone_cap ``` ```math -\sum_{t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} \le \mathrm{zone\_cap}_{z} \qquad \forall\, g \in \mathcal{G},\ z \in \mathcal{Z} +\sum_{g \in \mathcal{G} \,:\, \mathrm{generator}(g) = e \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathrm{zone\_cap}_{z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z} ``` -#### Sum between the two columns of a relation +#### Sum grouped by one member of a tuple -the same relation read between its own two columns: no map is read, so the domain asks only that the row is there +the same tuple grouped by a member alone: no map is read, so the domain asks only that the tuple is there ```yaml constraints: zonal_membership: dims: [snapshot] - expression: sum(units, over=generator, by=gen_zone[snapshot]) <= budget + expression: sum(at(units, by=gen_zone[generator]), over=gen_zone, by=gen_zone[snapshot]) <= budget ``` ```math -\sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}} \mathit{units}_{g} \le \mathrm{budget} \qquad \forall\, t \in \mathcal{T} +\sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t} \mathit{units}_{\mathrm{generator}(g)} \le \mathrm{budget} \qquad \forall\, t \in \mathcal{T} ``` -#### `at` through a map of a relation +#### `at` through a map of a tuple -the same table joined the other way, reading the slot the row's own snapshot puts the generator in +the same tuple as the frame, reading the zone each tuple maps to ```yaml constraints: zonal_lookup: - dims: [snapshot, generator] - where: "gen_zone[zone] == 'north' AND position(generator, within=gen_zone[zone]) == 0" - expression: p <= at(spill * zone_cap, by=gen_zone[zone]) + dims: [gen_zone] + where: "gen_zone[zone] == 'north'" + expression: at(p, by=gen_zone[generator, snapshot]) <= at(spill * zone_cap, by=gen_zone[snapshot, zone]) ``` ```math -p_{g,t} \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = \text{'}\mathrm{north}\text{'} \wedge \mathrm{pos}_{\mathrm{zone}(g,\ t)}(g) = 0 +p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathit{spill}_{\mathrm{snapshot}(g)} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g)} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{zone}(g) = \text{'}\mathrm{north}\text{'} ``` ### Arithmetic and literals @@ -651,7 +651,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G}} \left( \frac{p_{g,t}}{2} - \mathrm{cost}_{g} + 10^{-5} \cdot p_{g,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{g} + 0.5 \cdot p_{g,t} \right) \ge -\left( \sum_{g \in \mathcal{G}} p_{g,t} \right) \cdot \left( -3 \right) \qquad \forall\, t \in \mathcal{T} +\sum_{e \in \mathcal{E}} \left( \frac{p_{e,t}}{2} - \mathrm{cost}_{e} + 10^{-5} \cdot p_{e,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{e} + 0.5 \cdot p_{e,t} \right) \ge -\left( \sum_{e \in \mathcal{E}} p_{e,t} \right) \cdot \left( -3 \right) \qquad \forall\, t \in \mathcal{T} ``` #### Greek parameter name @@ -666,7 +666,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Infinity literal @@ -713,7 +713,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{net}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{net}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` #### Cased expression in a constraint @@ -728,7 +728,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{startup\_cost}_{g,t} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{startup\_cost}_{e,t} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Expression with a declared frame in a constraint @@ -743,7 +743,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{rating}_{g,t} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{rating}_{e,t} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Plain named expression @@ -757,7 +757,7 @@ expressions: ``` ```math -\mathit{spend}_{t} = \sum_{g \in \mathcal{G}} p_{g,t} \cdot \mathrm{cost}_{g} \qquad \forall\, t \in \mathcal{T} +\mathit{spend}_{t} = \sum_{e \in \mathcal{E}} p_{e,t} \cdot \mathrm{cost}_{e} \qquad \forall\, t \in \mathcal{T} ``` #### Named expression with a declared frame @@ -772,7 +772,7 @@ expressions: ``` ```math -\mathrm{rating}_{g,t} = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathrm{rating}_{e,t} = \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Plain expression that is a signed sum @@ -804,7 +804,7 @@ expressions: ``` ```math -\mathrm{startup\_cost}_{g,t} = \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}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathrm{startup\_cost}_{e,t} = \begin{cases} \mathrm{cost}_{e} & \text{if } \mathrm{pos}(t) = 0 \\ \mathrm{cost}_{e} \cdot 2 & \text{if } \mathrm{pos}(t) > 0 \wedge \mathrm{season}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Data-only expression @@ -817,7 +817,7 @@ expressions: ``` ```math -\mathrm{spend}^{\mathrm{cap}}_{g} = \mathrm{cost}_{g} \cdot 2 \qquad \forall\, g \in \mathcal{G} +\mathrm{spend}^{\mathrm{cap}}_{e} = \mathrm{cost}_{e} \cdot 2 \qquad \forall\, e \in \mathcal{E} ``` #### Named expression in a condition @@ -833,7 +833,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{g} > 0 \vee \neg \mathrm{is\_flexible}_{g} +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{e} > 0 \vee \neg \mathrm{is\_flexible}_{e} ``` #### Reported expression @@ -846,7 +846,7 @@ expressions: ``` ```math -\mathit{lcoe} = \frac{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g}}{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t}} +\mathit{lcoe} = \frac{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e}}{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t}} ``` #### Dual of a constraint @@ -875,7 +875,7 @@ conditions: ``` ```math -\mathrm{dispatchable}_{g} \iff \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \qquad \forall\, g \in \mathcal{G} +\mathrm{dispatchable}_{e} \iff \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} \qquad \forall\, e \in \mathcal{E} ``` #### Condition that reads a condition @@ -888,7 +888,7 @@ conditions: ``` ```math -\mathrm{priced\_dispatch}_{g} \iff \mathrm{dispatchable}_{g} \wedge \mathrm{spend}^{\mathrm{cap}}_{g} > 0 \qquad \forall\, g \in \mathcal{G} +\mathrm{priced\_dispatch}_{e} \iff \mathrm{dispatchable}_{e} \wedge \mathrm{spend}^{\mathrm{cap}}_{e} > 0 \qquad \forall\, e \in \mathcal{E} ``` #### Named condition in a condition @@ -904,7 +904,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{g} \wedge \mathrm{pos}(t) > 0 +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{e} \wedge \mathrm{pos}(t) > 0 ``` ### Shifts @@ -921,7 +921,7 @@ constraints: ``` ```math -p_{g,t} - p_{g,t \ominus 1} \le p_{g,t - 1} + \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} - p_{e,t \ominus 1} \le p_{e,t - 1} + \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Filled and forward shifts @@ -938,7 +938,7 @@ constraints: ``` ```math -p_{g,t \boxminus_{0} 1} \le p_{g,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t \boxminus_{0} 1} \le p_{e,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Cyclic forward shift @@ -953,7 +953,7 @@ constraints: ``` ```math -p_{g,t} \le p_{g,t \oplus 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \oplus 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Composed shifts @@ -968,7 +968,7 @@ constraints: ``` ```math -p_{g,t - 2} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t - 2} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Nested shifts that do not compose @@ -983,7 +983,7 @@ constraints: ``` ```math -p_{g,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Shift along two dimensions @@ -998,7 +998,7 @@ constraints: ``` ```math -p_{g + 1,t \ominus 1} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e + 1,t \ominus 1} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Shift by a parameter offset @@ -1013,7 +1013,7 @@ constraints: ``` ```math -p_{g,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Cyclic shift within a group @@ -1028,7 +1028,7 @@ constraints: ``` ```math -p_{g,t} \le p_{g,t \ominus^{\mathrm{season}(t)} 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \ominus^{\mathrm{season}(t)} 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Filled shift within a group @@ -1043,7 +1043,7 @@ constraints: ``` ```math -p_{g,t} \le p_{g,t \boxminus_{0}^{\mathrm{season}(t)} 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \boxminus_{0}^{\mathrm{season}(t)} 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` ### Trailing windows @@ -1060,7 +1060,7 @@ constraints: ``` ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Window with a parameter width @@ -1075,7 +1075,7 @@ constraints: ``` ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Window within a group @@ -1090,7 +1090,7 @@ constraints: ``` ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` ### Piecewise curves @@ -1424,21 +1424,21 @@ sos: ``` ```math -\left( \mathit{weight}_{g,t} \right)_{g \in \mathcal{G}} \in \mathrm{SOS}2 \qquad \forall\, t \in \mathcal{T} +\left( \mathit{weight}_{e,t} \right)_{e \in \mathcal{E}} \in \mathrm{SOS}2 \qquad \forall\, t \in \mathcal{T} ``` Written out by `spec.expand()`: ```math -\mathit{adjacent\_seg}_{g,t} \in \{0, 1\} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{adjacent\_seg}_{e,t} \in \{0, 1\} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` ```math -\mathit{weight}_{g,t} \le \mathit{adjacent\_seg}_{g,t} + \mathit{adjacent\_seg}_{g \boxminus_{0} 1,t} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{weight}_{e,t} \le \mathit{adjacent\_seg}_{e,t} + \mathit{adjacent\_seg}_{e \boxminus_{0} 1,t} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` ```math -\sum_{g \in \mathcal{G}} \mathit{adjacent\_seg}_{g,t} \le 1 \qquad \forall\, t \in \mathcal{T} +\sum_{e \in \mathcal{E}} \mathit{adjacent\_seg}_{e,t} \le 1 \qquad \forall\, t \in \mathcal{T} ``` ### Assumptions @@ -1453,7 +1453,7 @@ assumptions: ``` ```math -\mathrm{p}^{\mathrm{min}}_{g} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G} +\mathrm{p}^{\mathrm{min}}_{e} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E} ``` #### Connective in an assumption @@ -1466,7 +1466,7 @@ assumptions: ``` ```math -\mathrm{eta}_{g} > 0 \wedge \mathrm{eta}_{g} \le 1 \qquad \forall\, g \in \mathcal{G} +\mathrm{eta}_{e} > 0 \wedge \mathrm{eta}_{e} \le 1 \qquad \forall\, e \in \mathcal{E} ``` #### Parameter compared to a literal @@ -1479,7 +1479,7 @@ assumptions: ``` ```math -\mathrm{lead}_{g} \le 3 \qquad \forall\, g \in \mathcal{G} +\mathrm{lead}_{e} \le 3 \qquad \forall\, e \in \mathcal{E} ``` #### Two maps compared @@ -1505,7 +1505,7 @@ assumptions: ``` ```math -\sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} \ge \mathrm{budget} +\sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} \ge \mathrm{budget} ``` #### Shift in an assumption @@ -1535,7 +1535,7 @@ assumptions: ``` ```math -\mathrm{p}^{\mathrm{min}}_{g} < \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{is\_flexible}_{g} +\mathrm{p}^{\mathrm{min}}_{e} < \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{is\_flexible}_{e} ``` #### Assumption with a map condition @@ -1568,7 +1568,7 @@ constraints: ``` ```math -\mathit{units}_{g} \le \mathrm{budget} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{cost}_{g} \text{ is defined} +\mathit{units}_{e} \le \mathrm{budget} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{cost}_{e} \text{ is defined} ``` #### Variable and label conditions @@ -1600,7 +1600,7 @@ constraints: ``` ```math -\mathit{on}_{g,t} = 1 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 +\mathit{on}_{e,t} = 1 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 ``` #### Position counted from the end @@ -1616,7 +1616,7 @@ constraints: ``` ```math -\mathit{on}_{g,t} = 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 +\mathit{on}_{e,t} = 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 ``` #### Map compared to a label @@ -1696,7 +1696,7 @@ constraints: ``` ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} - \mathrm{p}^{\mathrm{min}}_{g} > \frac{\mathrm{cost}_{g}}{2} +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} - \mathrm{p}^{\mathrm{min}}_{e} > \frac{\mathrm{cost}_{e}}{2} ``` #### Shift and lookup in a condition @@ -1728,7 +1728,7 @@ constraints: ``` ```math -\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \le \mathrm{budget} \qquad \text{where } \sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} \ge \mathrm{budget} +\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \le \mathrm{budget} \qquad \text{where } \sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} \ge \mathrm{budget} ``` #### Count over a dimension @@ -1744,7 +1744,7 @@ constraints: ``` ```math -\theta_{u} \le \mathrm{budget} \qquad \forall\, u \in \mathcal{U} \,:\, \lvert \{ e \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e} > 0 \} \rvert \ge 2 +\theta_{u} \le \mathrm{budget} \qquad \forall\, u \in \mathcal{U} \,:\, \lvert \{ h \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h} > 0 \} \rvert \ge 2 ``` #### Count along a dimension of the frame @@ -1760,7 +1760,7 @@ constraints: ``` ```math -\theta_{u} \le \mathrm{tech\_cap}_{u,e} \qquad \forall\, u \in \mathcal{U},\ e \in \mathcal{E} \,:\, \lvert \{ e' \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e'} > 0 \} \rvert \ge 2 +\theta_{u} \le \mathrm{tech\_cap}_{u,h} \qquad \forall\, u \in \mathcal{U},\ h \in \mathcal{H} \,:\, \lvert \{ h' \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h'} > 0 \} \rvert \ge 2 ``` #### Condition at the previous coordinate diff --git a/docs/reference/reading.md b/docs/reference/reading.md index e62cb92ea..923ddf27f 100644 --- a/docs/reference/reading.md +++ b/docs/reference/reading.md @@ -42,7 +42,7 @@ the file changes nothing: - the entries of each section, and of each kind under `given:` - each `dims:` list -- the columns of each relation, and the maps of each subject +- the members of each dimension, and the maps of each subject - the cases under `cases:` - the `kwargs:` of a macro - the labels under `one_of:` @@ -164,11 +164,12 @@ the colon is the description that the file sets. `program.parameters[name].missing` is what the file sets under [`missing:`](language/absence.md#missing) for a missing row of that parameter. It is `'refused'`, `'absent'`, or the value that a tool uses for the row. -`program.relations` has one table per relation and per subject with -[maps](language/relations.md#the-data-contract), named after it, and each map -is one of its `values`. `program.relations[name].missing` is `'refused'` or -`'absent'`, and `partial` lists the maps under `missing: absent`. The program of -`spec.expand(...)` has the same `missing` values. +`program.relations` has one table per subject with +[maps](language/maps.md#the-data-contract), named after it, and each map +is one of its `values`. `partial` lists the maps under `missing: absent`. +`program.dimensions[name].missing` is `'refused'` or `'absent'` for a +dimension with members. The program of `spec.expand(...)` has the same +`missing` values. The table of a dimension with [members](language/dimensions.md#over) is in `program.relations` under the name of the dimension, whether or not the file @@ -230,7 +231,7 @@ An `ExpressionReference` is the node for a use of an `expressions:` entry. Its Every expression node has `dims`, the dimensions that it is indexed over, sorted by name. A sum has the dimensions of its operand, less the ones it sums -over. A `Join` under a sum through a relation has the dimensions of that sum. +over. A `Join` under a sum through a map has the dimensions of that sum. A `Join` also opens an index per dropped column (an `Axis`). An axis is not a dimension and is not in `dims`. An `ExpressionReference` has the dimensions of its body. @@ -263,7 +264,7 @@ A `Region`'s `when` is a `Mask` too, and every `Mask` has five attributes: A comparison of expressions arrives as an `ExpressionComparison`. Its two sides are program expressions, as a constraint's are, and its `dims` are every dimension that either side has. Its `names_read` are every parameter and -relation that the sides use, including the relation of a grouping. +subject that the sides use, including the subject of a grouping. A name compared against a literal is a different node. `p_max > 5` is a `ParameterComparison` and `1 * p_max > 5` is an `ExpressionComparison`, though @@ -271,9 +272,10 @@ both are true at the same coordinates. A comparison of a map against a label is a `RelationComparison`, and a comparison of two maps is a `RelationPairComparison`. The page on [conditions](language/expressions.md#conditions) defines both, -and both are false for every operator where the map gives no label. A -relation name alone is a `RelationDefined`, and a map alone, `subject[map]`, is a -`RelationDefined` with `column` set to the map. +and both are false for every operator where the map gives no label. The bare +name of a dimension with members is a `RelationDefined` whose `dims` are the +members, and a map alone, `subject[map]`, is a `RelationDefined` with `column` +set to the map. Three conditions contain another condition rather than an entry. A `CountComparison` contains the condition that it counts and the dimension that @@ -452,7 +454,7 @@ Writing the canonical form out again gives the same text. The canonical form has these rules: - The sections come in one fixed order: `version`, `description`, `given`, - `dimensions`, `relations`, `maps`, `parameters`, `conditions`, `variables`, + `dimensions`, `maps`, `parameters`, `conditions`, `variables`, `expressions`, `objective`, `constraints`, `sos`, `piecewise`, `assumptions`, `macros`. The keys of an entry also come in one order. - Entries are sorted by name within each section, and so is every other list diff --git a/docs/static/linear-maps-at.svg b/docs/static/linear-maps-at.svg index 9f8ce2968..8368f8517 100644 --- a/docs/static/linear-maps-at.svg +++ b/docs/static/linear-maps-at.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A lookup through a map is a join with one row per key - The parameter zone_cap has a value at each snapshot, 0 and 1, and each zone, north and south: 5 and 2 at snapshot 0, 6 and 3 at snapshot 1. The map zone_of[zone], of the relation zone_of over generator and snapshot, puts wind in zone north at both snapshots, and gas in zone north at snapshot 0 and in zone south at snapshot 1. The lookup joins each row of zone_of with the row of zone_cap that has the same snapshot and zone. The result has one row per row of zone_of: at snapshot 0, wind and gas both take 5, the value at north. At snapshot 1, wind takes 6, the value at north, and gas takes 3, the value at south. No row of the result takes the value 2 at snapshot 0 and zone south. + The parameter zone_cap has a value at each snapshot, 0 and 1, and each zone, north and south: 5 and 2 at snapshot 0, 6 and 3 at snapshot 1. The map zone_of[zone], of the dimension zone_of over generator and snapshot, puts wind in zone north at both snapshots, and gas in zone north at snapshot 0 and in zone south at snapshot 1. The lookup joins each row of zone_of with the row of zone_cap that has the same snapshot and zone. The result has one row per row of zone_of: at snapshot 0, wind and gas both take 5, the value at north. At snapshot 1, wind takes 6, the value at north, and gas takes 3, the value at south. No row of the result takes the value 2 at snapshot 0 and zone south. @@ -20,7 +20,7 @@ SPDX-License-Identifier: CC-BY-4.0 - relations: { zone_of: { dims: [generator, snapshot], missing: absent } } + dimensions: { zone_of: { over: [generator, snapshot] } } maps: { zone_of: { zone: { dim: zone } } } parameters: zone_cap: { dims: [snapshot, zone] } diff --git a/docs/static/linear-maps-empty.svg b/docs/static/linear-maps-empty.svg index fccb85683..c55f937e6 100644 --- a/docs/static/linear-maps-empty.svg +++ b/docs/static/linear-maps-empty.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> An empty group is a row with no variable, and a key tuple outside the domain has no row - The map zone_of[zone], of the relation zone_of over generator and snapshot with missing: absent, puts wind in zone north at snapshots 0 and 1, and gas in zone north at snapshot 0. It has no row for gas at snapshot 1, so f has no value there. The constraint zonal sums p by zone and has one row per snapshot and zone. At snapshot 0, north is p of wind plus p of gas, at most 5. At snapshot 1, north is p of wind, at most 6. South has no generator at either snapshot, so its rows are 0 at most 2 and 0 at most 3: empty groups with no variable. The lookup at of zone_cap by zone_of[zone] has one row per row of zone_of: wind at 0 takes 5, gas at 0 takes 5, wind at 1 takes 6. It has no row for gas at snapshot 1, where at is absent. + The map zone_of[zone], of the dimension zone_of over generator and snapshot, puts wind in zone north at snapshots 0 and 1, and gas in zone north at snapshot 0. It lists no tuple for gas at snapshot 1, so f has no value there. The constraint zonal sums p by zone and has one row per snapshot and zone. At snapshot 0, north is p of wind plus p of gas, at most 5. At snapshot 1, north is p of wind, at most 6. South has no generator at either snapshot, so its rows are 0 at most 2 and 0 at most 3: empty groups with no variable. The lookup at of zone_cap by zone_of[zone] has one row per row of zone_of: wind at 0 takes 5, gas at 0 takes 5, wind at 1 takes 6. It lists no tuple for gas at snapshot 1, where at is absent. @@ -20,7 +20,7 @@ SPDX-License-Identifier: CC-BY-4.0 - relations: { zone_of: { dims: [generator, snapshot], missing: absent } } + dimensions: { zone_of: { over: [generator, snapshot] } } maps: { zone_of: { zone: { dim: zone } } } sum(p, over=generator, by=zone_of[zone]) <= zone_cap at(zone_cap, by=zone_of[zone]) diff --git a/docs/static/linear-maps-join.svg b/docs/static/linear-maps-join.svg index b8c7fd45a..f449fc327 100644 --- a/docs/static/linear-maps-join.svg +++ b/docs/static/linear-maps-join.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A sum through a map is a join, then a group-by with a sum - The variable p has a row at each generator, gas and wind, and each snapshot, 0 and 1. The map zone_of[zone], of the relation zone_of over generator and snapshot, puts gas in zone north at snapshot 0 and in zone south at snapshot 1, and wind in zone north at both snapshots. The join pairs each row of p with the row of zone_of that has the same generator and snapshot, and each pair takes the zone of that row. The group-by adds the pairs that have the same snapshot and zone. The result y has three rows: at snapshot 0 and zone north, p of gas and 0 plus p of wind and 0. At snapshot 1 and zone north, p of wind and 1. At snapshot 1 and zone south, p of gas and 1. + The variable p has a row at each generator, gas and wind, and each snapshot, 0 and 1. The map zone_of[zone], of the dimension zone_of over generator and snapshot, puts gas in zone north at snapshot 0 and in zone south at snapshot 1, and wind in zone north at both snapshots. The join pairs each row of p with the row of zone_of that has the same generator and snapshot, and each pair takes the zone of that row. The group-by adds the pairs that have the same snapshot and zone. The result y has three rows: at snapshot 0 and zone north, p of gas and 0 plus p of wind and 0. At snapshot 1 and zone north, p of wind and 1. At snapshot 1 and zone south, p of gas and 1. @@ -25,7 +25,7 @@ SPDX-License-Identifier: CC-BY-4.0 - relations: { zone_of: { dims: [generator, snapshot], missing: absent } } + dimensions: { zone_of: { over: [generator, snapshot] } } maps: { zone_of: { zone: { dim: zone } } } variables: p: { dims: [snapshot, generator] } diff --git a/docs/static/parameters-where.svg b/docs/static/parameters-where.svg index fa949fd80..1df54f851 100644 --- a/docs/static/parameters-where.svg +++ b/docs/static/parameters-where.svg @@ -4,7 +4,7 @@ SPDX-License-Identifier: CC-BY-4.0 --> A where condition on a parameter drops rows of its data - At one snapshot, the relation connection has three rows: chp to el, chp to heat and boiler to heat, and its map role gives each of them the label output. The data of efficiency has three rows: chp el 0.4, boiler heat 0.9 and boiler el 0.5. With where connection[role] == output and missing 1, the parameter efficiency has three rows: chp el 0.4, chp heat 1 and boiler heat 0.9. The data row for boiler el, which connection does not list, has no role, so it is dropped, so efficiency is absent there. The row for chp heat, which the data does not have, takes the value 1. + At one snapshot, the dimension connection lists three pairs: chp and el, chp and heat, and boiler and heat. The data of efficiency has three rows: chp el 0.4, boiler heat 0.9 and boiler el 0.5. With where connection and missing 1, the parameter efficiency has three rows: chp el 0.4, chp heat 1 and boiler heat 0.9. The data row for boiler el, which connection does not list, is dropped, so efficiency is absent there. The row for chp heat, which the data does not have, takes the value 1. @@ -23,16 +23,16 @@ SPDX-License-Identifier: CC-BY-4.0 connection - a relation with the map role + a dimension over entity and bus efficiency the data, at one snapshot efficiency a parameter, at one snapshot - entitybusrole - chpeloutput - chpheatoutput - boilerheatoutput + entitybus + chpel + chpheat + boilerheat entitybusvalue chpel0.4 boilerheat0.9 @@ -60,8 +60,7 @@ SPDX-License-Identifier: CC-BY-4.0 - where: connection[role] - == 'output' + where: connection drops a data row where it is false missing: 1 fills a pair the data lacks diff --git a/docs/static/relations-where-bare.svg b/docs/static/relations-where-bare.svg index 9d1806b52..d2151931d 100644 --- a/docs/static/relations-where-bare.svg +++ b/docs/static/relations-where-bare.svg @@ -3,8 +3,8 @@ SPDX-FileCopyrightText: mathspec contributors SPDX-License-Identifier: CC-BY-4.0 --> - A bare relation in a where condition keeps the pairs it lists - The bare relation connection is a table with three rows: wind and north, gas and north, and gas and south. The variable flow, declared with where connection, is a table with the same three pairs of generator and bus. The pair wind and south, which connection does not list, has no row, so flow is absent there. + The bare name of a dimension with members in a where condition keeps the pairs it lists + The dimension connection lists three pairs: wind and north, gas and north, and gas and south. The variable flow, declared with where connection, is a table with the same three pairs of generator and bus. The pair wind and south, which connection does not list, has no row, so flow is absent there. @@ -19,7 +19,7 @@ SPDX-License-Identifier: CC-BY-4.0 connection - a relation + a dimension over generator and bus generator bus @@ -38,7 +38,7 @@ SPDX-License-Identifier: CC-BY-4.0 where: connection keeps the pairs - the relation lists + the dimension lists flow diff --git a/docs/tutorials/first-spec.md b/docs/tutorials/first-spec.md index bb3ad7c45..10f672873 100644 --- a/docs/tutorials/first-spec.md +++ b/docs/tutorials/first-spec.md @@ -46,8 +46,8 @@ Check the file: ``` ```text -dimension 'generator' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. -dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'generator' is never used: nothing is indexed by it, nothing sums into it, no condition tests it, and no map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, no condition tests it, and no map is over it. Remove it, or keep it if the entries that use it are still to be written. ``` mathspec accepts the file. `check` prints one remark that is not a refusal (a line of diff --git a/docs/tutorials/several-files.md b/docs/tutorials/several-files.md index 59ceb055a..04eedbd47 100644 --- a/docs/tutorials/several-files.md +++ b/docs/tutorials/several-files.md @@ -81,7 +81,7 @@ Make a file `generators.yaml`. The file declares the [shared dimensions](../refe [`adds_to:`](../reference/language/named.md#adds_to) keys of the file make `generation` a term of the injection and `generation_cost` a term of the total cost. `generator[bus]` gives each generator its bus -(a [map](../reference/language/relations.md#maps)). `generation` uses `generator[bus]` to sum the dispatch by bus. +(a [map](../reference/language/maps.md#maps)). `generation` uses `generator[bus]` to sum the dispatch by bus. ```yaml title="generators.yaml" description: A generator fleet, each unit on one bus. diff --git a/docs/tutorials/storage.md b/docs/tutorials/storage.md index 4df67b0b1..b21811eb8 100644 --- a/docs/tutorials/storage.md +++ b/docs/tutorials/storage.md @@ -44,8 +44,8 @@ Check the file: ``` ```text -dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. -dimension 'store' is never used: nothing is indexed by it, nothing sums into it, and no relation or map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'snapshot' is never used: nothing is indexed by it, nothing sums into it, no condition tests it, and no map is over it. Remove it, or keep it if the entries that use it are still to be written. +dimension 'store' is never used: nothing is indexed by it, nothing sums into it, no condition tests it, and no map is over it. Remove it, or keep it if the entries that use it are still to be written. ``` mathspec accepts the file. `check` prints one remark that is not a refusal (a line of diff --git a/mkdocs.yml b/mkdocs.yml index dd6f992f3..781895804 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,7 +54,7 @@ nav: - File shape: reference/language/file.md - Given, parameters, variables, objective and constraints: reference/language/parameters-variables-constraints.md - Dimensions: reference/language/dimensions.md - - Relations and maps: reference/language/relations.md + - Maps: reference/language/maps.md - Expressions: reference/language/expressions.md - Named expressions, conditions and macros: reference/language/named.md - Operators: reference/language/operators.md @@ -102,7 +102,7 @@ nav: - How mathspec works: about/overview.md - The limits of the language: about/limits.md - Versions: about/versions.md - - Relations as linear maps: about/relations-as-linear-maps.md + - Maps as linear maps: about/relations-as-linear-maps.md - Understanding a spec in SQL and dataframe terms: about/sql-and-dataframes.md - What counts as language: about/what-counts-as-language.md - What counts as public API: about/what-counts-as-public-api.md diff --git a/schema/mathspec.schema.json b/schema/mathspec.schema.json index e69b6734e..3235905ef 100644 --- a/schema/mathspec.schema.json +++ b/schema/mathspec.schema.json @@ -638,7 +638,7 @@ }, "MapSpec": { "additionalProperties": false, - "description": "A map: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names.\n\nWritten in YAML under its subject, with ``dim:`` always written::\n\n maps:\n unit:\n carrier: {dim: carrier, missing: absent}\n connection:\n bus: {dim: bus}\n line:\n bus0: {dim: bus}\n bus1: {dim: bus}\n\nThe map's name is a column of its subject's table, beside the subject's\nown columns. A call reads it as ``subject[map]``: ``sum(by=)`` totals\nalong it, ``at(by=)`` reads through it, ``within=`` works in each group\nof rows it sends to one label, and a condition compares it or tests that\na row has a label.", + "description": "A map: one label per label of its subject, a dimension, from the dimension that ``dim:`` names.\n\nWritten in YAML under its subject, with ``dim:`` always written::\n\n maps:\n unit:\n carrier: {dim: carrier, missing: absent}\n connection:\n bus: {dim: bus}\n line:\n bus0: {dim: bus}\n bus1: {dim: bus}\n\nThe map's name is a column of its subject's table, beside the subject's\nown columns. A call reads it as ``subject[map]``: ``sum(by=)`` totals\nalong it, ``at(by=)`` reads through it, ``within=`` works in each group\nof rows it sends to one label, and a condition compares it or tests that\na row has a label.", "properties": { "description": { "anyOf": [ @@ -789,7 +789,7 @@ "anyOf": [ { "additionalProperties": false, - "description": "One link of a piecewise entry: an expression tied to the curve through a values parameter.\n\nWritten in YAML as ``[expression, values]`` or ``[expression, values,\nsign]``, and serialised back to exactly that form, so a round trip through\n[`Spec.to_yaml`][] reproduces the file.\n\nA link that names ``by: subject[map]`` reads the curve's weights\nthrough the relation, as ``at`` reads an array, and is written as a\nmapping. Its row is the entry's ``dims:`` with the dims the lookup reads\nreplaced by the key columns it arrives at, so one link emits a row per fine\ncoordinate and each reads the curve of the coarse coordinate it maps to.", + "description": "One link of a piecewise entry: an expression tied to the curve through a values parameter.\n\nWritten in YAML as ``[expression, values]`` or ``[expression, values,\nsign]``, and serialised back to exactly that form, so a round trip through\n[`Spec.to_yaml`][] reproduces the file.\n\nA link that names ``by: subject[map]`` reads the curve's weights\nthrough the map, as ``at`` reads an array, and is written as a\nmapping. Its row is the entry's ``dims:`` with the dims the lookup reads\nreplaced by the key columns it arrives at, so one link emits a row per fine\ncoordinate and each reads the curve of the coarse coordinate it maps to.", "properties": { "by": { "anyOf": [ @@ -918,58 +918,6 @@ "title": "PiecewiseSpec", "type": "object" }, - "RelationSpec": { - "additionalProperties": false, - "description": "A named relation: the combinations of its dimensions that exist, one row each.\n\n``dims:`` is a list of dimensions, or a mapping of column name to\ndimension where two columns share one. A row is its own identity, so the\nrelation is a subset of the product of its dimensions::\n\n relations:\n connection: {dims: [unit, port], missing: absent}\n corridor: {dims: {from: bus, to: bus}}\n\nA relation is not a dimension. Its name stands in a condition, where it\nis true at the rows it lists, and before a\nbracket, where it reads one of its maps (``maps:``, [`MapSpec`][]). The\nrows are data, and arrive under the relation's name, one column per\ncolumn name, with a column per map beside them.", - "properties": { - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "default": null, - "title": "Description" - }, - "dims": { - "anyOf": [ - { - "type": "string" - }, - { - "items": { - "type": "string" - }, - "type": "array" - }, - { - "additionalProperties": { - "type": "string" - }, - "type": "object" - } - ], - "title": "Dims" - }, - "missing": { - "default": "refused", - "enum": [ - "refused", - "absent" - ], - "title": "Missing", - "type": "string" - } - }, - "required": [ - "dims" - ], - "title": "RelationSpec", - "type": "object" - }, "SosSpec": { "additionalProperties": false, "description": "A special-ordered set over one dimension of one variable.\n\nOne set per coordinate of the variable's ``dims`` minus ``along``; the\nmembers are the variable's *existing* coordinates along ``along``, in that\ndimension's declared order.\n\n``type: 1`` admits at most one nonzero member, ``type: 2`` at most two,\nand those two consecutive. A consumer with the concept takes the set as\none; [`Spec.expand`][] states it as binaries instead, and the rows it\nwrites multiply by the member's own ``bounds``, which is why a member\nneeds both.", @@ -1188,14 +1136,6 @@ "title": "Piecewise", "type": "object" }, - "relations": { - "additionalProperties": { - "$ref": "#/$defs/RelationSpec" - }, - "default": {}, - "title": "Relations", - "type": "object" - }, "sos": { "additionalProperties": { "$ref": "#/$defs/SosSpec" diff --git a/src/mathspec/_advising.py b/src/mathspec/_advising.py index e699ac21d..0aeb920b3 100644 --- a/src/mathspec/_advising.py +++ b/src/mathspec/_advising.py @@ -13,7 +13,7 @@ from mathspec._boundedness import unbounded_notes from mathspec._validation import to_spec -from mathspec.program import Advice, Join, Program, walk +from mathspec.program import Advice, Join, Program, walk, walk_regions if TYPE_CHECKING: from collections.abc import Mapping @@ -110,6 +110,7 @@ def _never_an_axis(program: Program) -> list[Advice]: ): reached.update(entry.dims) reached |= _grouped_axes(program) + reached |= _tested_tuples(program) for lk in program.relations.values(): declared = [role for role in lk.values if role not in lk.members] if declared or not lk.members: @@ -121,7 +122,7 @@ def _never_an_axis(program: Program) -> list[Advice]: 'never-an-axis', name, f"dimension '{name}' is never used: nothing is indexed by it, nothing " - f'sums into it, and no relation or map is over it. Remove it, or keep it ' + f'sums into it, no condition tests it, and no map is over it. Remove it, or keep it ' f'if the entries that use it are still to be written.', ) for name in program.dimensions @@ -129,6 +130,17 @@ def _never_an_axis(program: Program) -> list[Advice]: ] +def _tested_tuples(program: Program) -> set[str]: + """The dimensions a condition tests by bare name: a tuple named only in a ``where`` is in use.""" + masks = [ + entry.where + for entry in (*program.parameters.values(), *program.variables.values(), *program.constraints.values()) + if entry.where is not None + ] + masks += [mask for _, regions in walk_regions(*program.roots) for mask in regions] + return {name for mask in masks for name in mask.names_read if name in program.dimensions} + + def _grouped_axes(program: Program) -> set[str]: """The axes the expressions create beyond what any entry indexes. diff --git a/src/mathspec/_composition.py b/src/mathspec/_composition.py index 6bf124783..a0892b605 100644 --- a/src/mathspec/_composition.py +++ b/src/mathspec/_composition.py @@ -19,17 +19,17 @@ [`merge`][] writes nothing a fragment did not write, except a ``+``. It joins fragments' text in one place, a named expression that terms add to; every other entry is copied as written, refused where two fragments own it, -or held identical where it is a dimension or a relation. +or held identical where it is a dimension. What that means for each section: -* **A dimension or a relation every fragment may declare**, and the ones that +* **A dimension every fragment may declare**, and the ones that do have to say the same thing about it. Prose is not a claim, so two descriptions of one dimension agree, and the first one given is carried. ``ordered`` is a claim about the space, not the space, so a dimension one fragment declares ordered is ordered. - A relation's ``missing:`` is a claim about the data, and the fragments + A dimension's ``missing:`` is a claim about the data, and the fragments agree on it: ``absent`` and ``refused`` change the result differently, so - neither folds into the other. ``missing: refused`` is the same as none. + neither folds into the other. * **Every other entry is owned.** A name two fragments declare is refused, both named. * **One fragment sets the objective.** A second one is refused, both named. @@ -79,9 +79,9 @@ * **Patches are laid in order.** Each is laid on the base with every earlier patch laid on it, so a later patch wins a field an earlier one writes, and edits or removes an entry an earlier one creates. -* **A patch adds a dimension or a relation, and does not change one its - base declares.** It may change only the ``description``, a dimension's - ``ordered`` and a relation's ``missing``, and may write them alone. A +* **A patch adds a dimension, and does not change one its + base declares.** It may change only the ``description`` and a dimension's + ``ordered``, and may write them alone. A dimension may gain ``ordered: true`` and may not lose it. An entry that writes any other field must declare it as the base does, a field it leaves out reading as its default. @@ -116,14 +116,13 @@ from mathspec.program import Program from mathspec.spec import DimensionSpec -SHARED_SECTIONS = ('dimensions', 'relations', 'maps') +SHARED_SECTIONS = ('dimensions', 'maps') SETTINGS: dict[str, frozenset[str]] = { 'dimensions': frozenset({'ordered'}), - 'relations': frozenset({'missing'}), 'maps': frozenset({'missing'}), } -"""The fields of a dimension, a relation or a map, other than ``description``, that a patch may change. A patch may +"""The fields of a dimension or a map, other than ``description``, that a patch may change. A patch may change no other field of one that its base declares. """ @@ -174,7 +173,7 @@ def merge(fragments: Sequence[Source], description: str | None = None) -> Spec: Raises: LanguageError: A fragment does not load on its own; two fragments declare one name; two fragments say different things about one - dimension, relation, map or given entry; a fragment reads a name as + dimension, map or given entry; a fragment reads a name as something other than what its sibling introduces, as another kind of thing, or over fewer dimensions than its body carries; a fragment adds a term to a variable, a parameter, a constraint or a @@ -191,9 +190,8 @@ def merge(fragments: Sequence[Source], description: str | None = None) -> Spec: merged: dict[str, object] = {'version': _one_version(read)} if description is not None: merged['description'] = description - for section in ('dimensions', 'relations'): - if agreed := _agreed(read, section, _singular(section), 'give one of them a name of its own'): - merged[section] = agreed + if agreed := _agreed(read, 'dimensions', 'dimension', 'give one of them a name of its own'): + merged['dimensions'] = agreed flat: dict[str, dict[str, object]] = { name: {'maps': _flat_maps(sections.get('maps'))} for name, sections in read.items() } @@ -305,8 +303,8 @@ def _restates( ) -> bool: """Whether a patch's *restated* fields declare an entry as *declared* does, each field in *aside* apart. - A restatement the schema refuses on its own, such as a relation with no - ``dims:``, does not say what the base says, so the patch's refusal names + A restatement the schema refuses on its own, such as a map with no + ``dim:``, does not say what the base says, so the patch's refusal names the rewrite. A key the schema does not know stays a schema error, which names the near-miss. """ @@ -717,7 +715,7 @@ def override(base: Source, patches: Sequence[Source]) -> Spec: LanguageError: The base does not load; the patched spec does not load; a patch edits or removes an entry its base does not declare; a patch creates one that is not whole; a patch redeclares - or removes a dimension or a relation; or a patch sets a whole + or removes a dimension; or a patch sets a whole section to ``null``. FileNotFoundError: A ``str`` with no newline that names no file. TypeError: *patches* is one path rather than a list. @@ -904,7 +902,7 @@ def _shared( *, owner: type[BaseModel] = Spec, ) -> dict[str, object]: - """One ``dimensions``, ``relations`` or ``maps`` section: a patch adds one or restates one, never changes or drops it. + """One ``dimensions`` or ``maps`` section: a patch adds one or restates one, never changes or drops it. A patch may change the description and the [`SETTINGS`][] of one its base declares, and ``null`` puts back the default. A dimension may gain diff --git a/src/mathspec/_condition_parser.py b/src/mathspec/_condition_parser.py index 66d30e6dd..1ab64d56b 100644 --- a/src/mathspec/_condition_parser.py +++ b/src/mathspec/_condition_parser.py @@ -251,7 +251,7 @@ def _named_rewrite(text: str, loc: int) -> str | None: _DEEP_REWRITE = ( - 'Declare a parameter or relation carrying part of the test and name that here, or split the ' + 'Declare a parameter or a condition carrying part of the test and name that here, or split the ' 'entry into two, each masked by one half.' ) diff --git a/src/mathspec/_condition_resolver.py b/src/mathspec/_condition_resolver.py index c6595dcde..508dbeb4f 100644 --- a/src/mathspec/_condition_resolver.py +++ b/src/mathspec/_condition_resolver.py @@ -138,7 +138,7 @@ def _child(self, node: Condition | UnresolvedConditionNode) -> Condition: return cast('Condition', self.build(node)) def _bare_name(self, node: NameNode) -> Condition | UnresolvedConditionNode: - """A bare name: a named condition's body, a parameter's or relation's definedness, or a variable's existence.""" + """A bare name: a named condition's body, a parameter's definedness, a tuple's membership, or a variable's existence.""" ns, context = self.ns, self.context if node.name in ns.conditions: try: @@ -179,16 +179,6 @@ def _bare_name(self, node: NameNode) -> Condition | UnresolvedConditionNode: f'name is true at every coordinate. ' f'Remove it, or compare it: where: "{node.name} > 0".' ) - case 'relation': - shape = ns.relations[node.name] - dims = tuple(sorted(shape.dim(k) for k in shape.key)) - if len(set(dims)) < len(dims): - self.errors.append( - f"{context}: '{node.name}' has two columns over one dimension ({list(shape.roles)}), so a " - f'bare name is ambiguous. Declare the rows it tests as a bool parameter over {dims[0]!r}.' - ) - return node - return RelationDefined(node.name, dims) case 'variable': if node.name == self.self_variable: self.errors.append( @@ -566,13 +556,13 @@ def _relation_column(self, name: str, column: str | None, spelling: str, op: Com shape = ns.relations[name] if not shape.values: self.errors.append( - f"{context}: '{spelling}' compares the relation '{name}', which has no map, so its rows hold no " - f"label. Test the bare name '{name}' for whether a row exists, or declare a map under maps: {name}:." + f"{context}: '{spelling}' compares '{name}', which has no map, so it holds no label. Declare a map " + f'under maps: {name}:.' ) return None if column is None: self.errors.append( - f"{context}: '{spelling}' compares the relation '{name}' itself, and a comparison reads a label. " + f"{context}: '{spelling}' compares '{name}' itself, and a comparison reads a label. " f'Name one of its maps: {name}[{shape.values[0]}].' ) return None diff --git a/src/mathspec/_dimensions.py b/src/mathspec/_dimensions.py index 57656cdee..b2e6ac7aa 100644 --- a/src/mathspec/_dimensions.py +++ b/src/mathspec/_dimensions.py @@ -195,7 +195,7 @@ def _check_joined(call: str, use: JoinColumns | Partition, inner: frozenset[str] if twice := sorted({d for d in dims if dims.count(d) > 1}): raise DimensionError( f"{context}: {call} joins '{use.name}' on {twice} through more than one column. Join on " - f'different dimensions, or use a relation whose columns are over different dimensions.' + f'different dimensions, or declare an alias so that the members differ.' ) @@ -467,7 +467,7 @@ def _check_condition_dims(mask: Mask | None, frame: frozenset[str], context: str case DimensionComparison() | DimensionPosition(): leaf = f"where-dimension '{atom.name}'" case RelationDefined(column=None): - leaf = f"where-relation '{atom.name}'" + leaf = f"where-tuple '{atom.name}'" case RelationComparison() | RelationPairComparison() | RelationDefined(): leaf = f"where-map '{atom.name}[{atom.column}]'" case ExpressionComparison(): diff --git a/src/mathspec/_expression_resolver.py b/src/mathspec/_expression_resolver.py index 27232ed16..1c6fde0c9 100644 --- a/src/mathspec/_expression_resolver.py +++ b/src/mathspec/_expression_resolver.py @@ -185,7 +185,7 @@ def met(self, left: Expression, right: Expression) -> bool: return False def _name(self, node: NameNode) -> Expression | None: - """A bare name as the variable, parameter or named expression it declares; a dimension or relation is not a value. + """A bare name as the variable, parameter or named expression it declares; a dimension is not a value. A named expression arrives as the one node [`Namespace.named`][] built for it; the cast is the one place a @@ -218,13 +218,6 @@ def _name(self, node: NameNode) -> Expression | None: f'not a value. To use its coordinates as data, declare a parameter over it.' ) return None - case 'relation': - self.errors.append( - f"{self.context}: '{node.name}' is a relation, and a relation is not a value. Sum through it " - f'as sum(x, over=, by={node.name}[]), test it in a condition, or declare a ' - f'parameter to carry numbers.' - ) - return None case _: self.errors.append(self.ns.unknown(node.name, self.context, allow_dims=False, formals=self.formals)) return None @@ -750,9 +743,9 @@ def not_a_relation(self, name: str, operator: str, key: str) -> str | None: f'under maps: {name}:, or read a subject that has it: {key}=[].' ) kinds = ( - 'a relation, a dimension with maps or a formal argument of this macro' + 'a dimension with maps or members, or a formal argument of this macro' if self.formals - else 'a relation or a dimension with maps' + else 'a dimension with maps or members' ) return ( f'{context}: {operator}({key}={name}[...]): {name!r} is not {kinds}. ' @@ -775,13 +768,6 @@ def not_a_number(name: str, dtype: str, context: str) -> str: def _undeclared_dim(context: str, operator: str, call: str, name: str, ns: Namespace, formals: frozenset[str]) -> str: - if name in ns.relations and name not in ns.dimensions: - dims = list(ns.relations[name].dims) - which = 'its dimensions' if call.startswith('over=') else 'one of its dimensions' - return ( - f"{context}: {operator}({call}) names the relation '{name}', and a relation is not a dimension. " - f'Name {which}, {dims}.' - ) return ( f'{context}: {operator}({call}) does not name a declared dimension{_or_a_formal(formals)}. ' f'{did_you_mean(name, ns.dimensions, label="Dimensions")}\n' diff --git a/src/mathspec/_renaming.py b/src/mathspec/_renaming.py index c3ceb3a18..27340ab20 100644 --- a/src/mathspec/_renaming.py +++ b/src/mathspec/_renaming.py @@ -41,7 +41,7 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str entry, in ``dims:``, under ``maps:``, in ``adds_to:``, under ``given:``, and in the text of every expression, ``where:``, bound, case and assumption. Only whole names are replaced, and the text around each name - is unchanged. A map or a relation column named after its dimension is + is unchanged. A map named after its dimension is renamed with the dimension, because an expression reads a map as ``subject[map]``. @@ -74,7 +74,7 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str name of an entry that is not renamed, or an argument of a macro whose template uses the old name. Also when two names get the same new name, or when an old or a new - name is a map or a relation column that is not named after its + name is a map that is not named after its dimension. FileNotFoundError: A ``str`` with no newline that names no file. TypeError: *names* is neither a mapping nor a function. @@ -95,7 +95,7 @@ def rename(source: Source, names: Mapping[str, str | None] | Callable[[str], str def _declared(spec: Spec) -> dict[str, str]: """Every name that *spec* declares or lists under ``given:``, with the kind of its entry for a refusal. - ``maps:`` declares no name of its own: its keys are dimensions and relations. + ``maps:`` declares no name of its own: its keys are dimensions. """ declared = {name: GIVEN_KINDS[kind] for kind in GIVEN_KINDS for name in getattr(spec.given, kind)} for section in (s for s in (*SHARED_SECTIONS, *OWNED_SECTIONS) if s != 'maps'): @@ -108,7 +108,7 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: A token in text is renamed wherever it has the spelling, so a new name that is the argument of a macro whose template uses the old name, or a name that - is a map, a relation column or a member named after something else, would + is a map or a member named after something else, would change an expression without a refusal. """ for old in names: @@ -119,26 +119,17 @@ def _checked(names: Mapping[str, str | None], declared: Mapping[str, str], spec: ) raise LanguageError(msg) changed = {old: new for old, new in names.items() if new is not None and new != old} - columns = ( - { - column: f"a column of the relation '{relation}'" - for relation, entry in spec.relations.items() - for column, dimension in entry.pairs - if column != dimension - } - | { - name: f"a map of '{subject}'" - for subject, maps in spec.maps.items() - for name, entry in maps.items() - if name != entry.dim - } - | { - role: f"a member of the dimension '{name}'" - for name, entry in spec.dimensions.items() - for role, dimension in entry.members - if role != dimension - } - ) + columns = { + name: f"a map of '{subject}'" + for subject, maps in spec.maps.items() + for name, entry in maps.items() + if name != entry.dim + } | { + role: f"a member of the dimension '{name}'" + for name, entry in spec.dimensions.items() + for role, dimension in entry.members + if role != dimension + } for old, new in changed.items(): for macro, entry in spec.macros.items(): if new in (*entry.args, *entry.kwargs) and old in _names_in(entry.template): diff --git a/src/mathspec/_resolution.py b/src/mathspec/_resolution.py index 5a4b96910..dfdd576b5 100644 --- a/src/mathspec/_resolution.py +++ b/src/mathspec/_resolution.py @@ -59,7 +59,7 @@ from mathspec.spec import ConditionSpec, ExpressionSpec, Spec -NameKind = Literal['variable', 'parameter', 'dimension', 'relation'] +NameKind = Literal['variable', 'parameter', 'dimension'] class Namespace: @@ -266,8 +266,6 @@ def kind(self, name: str) -> NameKind | None: return 'parameter' if name in self.dimensions: return 'dimension' - if name in self.relations: - return 'relation' return None def unknown(self, name: str, context: str, *, allow_dims: bool, formals: Iterable[str] = ()) -> str: @@ -277,8 +275,8 @@ def unknown(self, name: str, context: str, *, allow_dims: bool, formals: Iterabl name: The name the file wrote. context: The entry it was found in. allow_dims: Whether a dimension would have been accepted there. It marks a - condition, which reads a relation as readily as a parameter, so the - listing carries the relations too; an expression, where a relation is not a + condition, which reads a dimension as readily as a parameter, so the + listing carries the dimensions too; an expression, where a dimension is not a value, lists the variables instead. formals: A macro's formals, listed first when there are any. """ @@ -287,7 +285,6 @@ def unknown(self, name: str, context: str, *, allow_dims: bool, formals: Iterabl [ ('Parameters', self.parameters), ('Dimensions', self.dimensions), - ('Relations', [r for r in self.relations if r not in self.dimensions]), *([('Conditions', self.conditions)] if self.conditions else []), ] if allow_dims diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index 4465886ad..74d21ef12 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -110,7 +110,6 @@ def reference_errors(spec: Spec) -> list[str]: *_name_collisions(spec), *_frame_dimensions(spec), *_members(spec), - *_relation_targets(spec), *_map_targets(spec), *_aliases(spec), *_bound_names(spec), @@ -121,25 +120,15 @@ def reference_errors(spec: Spec) -> list[str]: ] -def undeclared_dimension(kind: str, name: str, dimension: str, spec: Spec, *, along: bool = False) -> str: - """The one wording for an entry naming a dimension the file does not declare, or naming a relation as one.""" - if (relation := spec.relations.get(dimension)) is None: - return f"{kind} '{name}' references undeclared dimension '{dimension}'. Declare it under 'dimensions:'." - dims = sorted({d for _, d in relation.pairs}) - if along: - rewrite = f'Name one of its dimensions, {dims}.' - elif kind in ('Parameter', 'Variable'): - rewrite = f'Name its dimensions, {dims}, under dims:, and confine the entry with where: {dimension}.' - else: - rewrite = f'Name its dimensions, {dims}.' - return f"{kind} '{name}' names the relation '{dimension}', and a relation is not a dimension. {rewrite}" +def undeclared_dimension(kind: str, name: str, dimension: str) -> str: + """The one wording for an entry naming a dimension the file does not declare.""" + return f"{kind} '{name}' references undeclared dimension '{dimension}'. Declare it under 'dimensions:'." def _flat_namespace(spec: Spec) -> list[tuple[str, Iterable[str]]]: """Each kind of entry whose names share the one namespace an expression reads.""" return [ ('dimension', spec.dimensions), - ('relation', spec.relations), ('parameter', spec.parameters), ('given parameter', spec.given.parameters), ('variable', spec.variables), @@ -192,7 +181,7 @@ def _frame_dimensions(spec: Spec) -> Iterator[str]: *(('Named expression', name, e.dims or ()) for name, e in spec.expressions.items()), ] for kind, name, dims in frames: - yield from (undeclared_dimension(kind, name, d, spec) for d in dims if d not in spec.dimensions) + yield from (undeclared_dimension(kind, name, d) for d in dims if d not in spec.dimensions) yield from ( f"{kind} '{name}' names dimension '{d}' twice. Delete one." for d, count in Counter(dims).items() @@ -233,9 +222,7 @@ def _members(spec: Spec) -> Iterator[str]: """A dimension lists plain, declared dimensions as its members, each once.""" for name, entry in spec.dimensions.items(): dims = [dim for _, dim in entry.members] - yield from ( - undeclared_dimension('Dimension', name, d, spec) for d in dict.fromkeys(dims) if d not in spec.dimensions - ) + yield from (undeclared_dimension('Dimension', name, d) for d in dict.fromkeys(dims) if d not in spec.dimensions) for d in dict.fromkeys(dims): if d in spec.dimensions and (inner := spec.dimensions[d].members): flat = sorted({*dims, *(dim for _, dim in inner)} - {d, name}) @@ -251,61 +238,17 @@ def _members(spec: Spec) -> Iterator[str]: ) -def _relation_targets(spec: Spec) -> Iterator[str]: - """A relation has at least two columns, over declared dimensions, each named once.""" - for lname, lk in spec.relations.items(): - if len(lk.pairs) < 2: - dim = lk.pairs[0][1] if lk.pairs else '' - yield ( - f"Relation '{lname}' has {'one column' if lk.pairs else 'no column'} under 'dims:', and a relation " - f'needs at least two. To give each {dim} a label, declare a map under maps: {dim}:. To mark some ' - f'of them, declare a bool parameter or a condition.' - ) - if not isinstance(lk.dims, Mapping): - yield from ( - f"Relation '{lname}' names dimension '{d}' twice under 'dims:'. Give the two columns names: " - f'dims: {{{d}0: {d}, {d}1: {d}}}.' - for d, count in Counter(lk.dims if isinstance(lk.dims, tuple) else (lk.dims,)).items() - if count > 1 - ) - yield from ( - undeclared_dimension('Relation', lname, d, spec) - for d in dict.fromkeys(d for _, d in lk.pairs) - if d not in spec.dimensions - ) - yield from ( - f"Relation '{lname}' names column '{role}' after dimension '{role}', but the column is over " - f"'{dim}'. Rename the column after what it holds." - for role, dim in lk.pairs - if role in spec.dimensions and role != dim - ) - - def _map_targets(spec: Spec) -> Iterator[str]: - """A map's subject is a dimension or a relation, its name is no column of the subject, and it refers to a dimension. - - A relation with two columns over one dimension takes no map, since a call - through it would not know which of the two the frame's dimension meets. - """ + """A map's subject is a dimension, its name is no member of the subject, and it refers to a dimension.""" for subject, maps in spec.maps.items(): head = f"maps: '{subject}'" - members = dict(spec.dimensions[subject].members if subject in spec.dimensions else ()) - if subject in spec.relations: - pairs = spec.relations[subject].pairs - if twice := [d for d, count in Counter(d for _, d in pairs).items() if count > 1]: - yield ( - f"{head} is a relation with two columns over '{twice[0]}', and a map reads one row per " - f'combination of its dimensions. Declare the maps on a relation over each dimension once.' - ) - elif subject in spec.dimensions: - pairs = ((subject, subject),) - else: - subjects = [*spec.dimensions, *spec.relations] + if subject not in spec.dimensions: yield ( - f'{head} is neither a dimension nor a relation, and a map gives each row of one a label. ' - f'{did_you_mean(subject, subjects, label="Subjects")}' + f'{head} is not a dimension, and a map gives each label of one a label. ' + f'{did_you_mean(subject, spec.dimensions, label="Dimensions")}' ) continue + members = dict(spec.dimensions[subject].members) for role, m in maps.items(): if not re.fullmatch(NAME, role): yield ( @@ -317,17 +260,12 @@ def _map_targets(spec: Spec) -> Iterator[str]: f"{head}: map '{role}' has the name of a member of '{subject}', which already gives each tuple " f"its label of '{members[role]}'. Read the member as {subject}[{role}], or rename the map." ) - elif role in dict(pairs): - yield ( - f"{head}: map '{role}' has the name of a column of '{subject}', which holds the row, not a " - f'label of it. Rename the map after what it holds.' - ) - if m.dim in spec.relations: + elif role == subject: yield ( - f"{head}: map '{role}' refers to the relation '{m.dim}', and a map gives a label of one " - f"dimension. Refer to one of its dimensions, or declare '{role}' on the relation instead." + f"{head}: map '{role}' has the name of its subject, which holds the label, not a label of it. " + f'Rename the map after what it holds.' ) - elif m.dim not in spec.dimensions: + if m.dim not in spec.dimensions: yield ( f"{head}: map '{role}' refers to undeclared dimension '{m.dim}'. Declare it under 'dimensions:'." ) @@ -388,7 +326,7 @@ def _sos_shapes(spec: Spec) -> Iterator[str]: for sname, entry in spec.sos.items(): context = f"Sos '{sname}'" if entry.along not in spec.dimensions: - yield undeclared_dimension('Sos', sname, entry.along, spec, along=True) + yield undeclared_dimension('Sos', sname, entry.along) elif entry.variable not in spec.variables: yield ( f"{context}: '{entry.variable}' is not a declared variable.\n" @@ -453,13 +391,13 @@ def _piecewise_references(spec: Spec) -> Iterator[str]: for name, pw in spec.piecewise.items(): context = f"piecewise '{name}'" if pw.along not in spec.dimensions: - yield undeclared_dimension('piecewise', name, pw.along, spec, along=True) + yield undeclared_dimension('piecewise', name, pw.along) continue if not labels_of(spec, pw.along).ordered: yield unordered(context, f'along: {pw.along}', pw.along, spec.dimensions[pw.along].members) for d in pw.dims: if d not in spec.dimensions: - yield undeclared_dimension('piecewise', name, d, spec) + yield undeclared_dimension('piecewise', name, d) elif d == pw.along: yield ( f"{context}: dims: lists '{pw.along}', the breakpoint dimension. Every curve runs along it, so drop " diff --git a/src/mathspec/program.py b/src/mathspec/program.py index a7b1e6882..69b0bf9a4 100644 --- a/src/mathspec/program.py +++ b/src/mathspec/program.py @@ -674,7 +674,7 @@ class Dimension: """ one_of: tuple[str, ...] | None = None """The labels that the file lists under ``one_of:``, sorted by name, or ``None`` when it lists none. With data attached, - a tool refuses any other label, in the table of the dimension and in every relation column over it. + a tool refuses any other label, in the table of the dimension and in every field of a tuple over it. """ ordered: bool = False """Whether the order of the labels is part of the spec. When it is, a tool keeps the labels in the order the data gives diff --git a/src/mathspec/spec.py b/src/mathspec/spec.py index 3b904dc45..a6796f479 100644 --- a/src/mathspec/spec.py +++ b/src/mathspec/spec.py @@ -14,7 +14,7 @@ import math import re -from collections.abc import Mapping, Sequence +from collections.abc import Mapping from functools import cached_property from typing import TYPE_CHECKING, Annotated, ClassVar, Literal, Self, TypeVar, cast, get_args, override @@ -79,7 +79,6 @@ 'ParameterSpec', 'PiecewiseLinkSpec', 'PiecewiseSpec', - 'RelationSpec', 'SosSpec', 'Spec', 'VariableSpec', @@ -232,68 +231,8 @@ def _also_written_as( return {'anyOf': [dict(generated), shorthand]} -def relation_columns(written: str | Sequence[str] | Mapping[str, str]) -> tuple[tuple[str, str], ...]: - """``(column, dimension)`` per column of a relation's ``dims:``, in the order the spec holds them. - - A bare name or a list names each column after the dimension it is over; a - mapping names the columns, which is what two columns over one dimension need. - """ - if isinstance(written, Mapping): - return tuple(written.items()) - return tuple((d, d) for d in ((written,) if isinstance(written, str) else written)) - - -class RelationSpec(_StrictSpec): - """A named relation: the combinations of its dimensions that exist, one row each. - - ``dims:`` is a list of dimensions, or a mapping of column name to - dimension where two columns share one. A row is its own identity, so the - relation is a subset of the product of its dimensions:: - - relations: - connection: {dims: [unit, port], missing: absent} - corridor: {dims: {from: bus, to: bus}} - - A relation is not a dimension. Its name stands in a condition, where it - is true at the rows it lists, and before a - bracket, where it reads one of its maps (``maps:``, [`MapSpec`][]). The - rows are data, and arrive under the relation's name, one column per - column name, with a column per map beside them. - """ - - _label: ClassVar[str] = 'a relation entry' - - dims: str | Dims | ByName[str] - """The relation's columns: a list of dimensions, each a column named after it, or a mapping of column name to - dimension. - """ - missing: RelationMissing = 'refused' - """Whether every combination of its dimensions is a row. Under ``refused``, a tool refuses data that leaves one out. - Under ``absent``, that combination is not in the relation. - """ - description: str | None = None - - @field_validator('missing', mode='before') - @classmethod - def _refused_or_absent(cls, v: object) -> object: - """A row is data, so no value fills a gap in a relation.""" - return _refused_or_absent(v, 'a relation', 'Write absent where a combination may have no row, or leave it out.') - - @property - def pairs(self) -> tuple[tuple[str, str], ...]: - """``(column, dimension)`` per column, sorted by column. - - The program calls the same thing [`columns`][mathspec.program.Relation.columns]. - """ - return relation_columns(self.dims) - - @property - def roles(self) -> tuple[str, ...]: - return tuple(role for role, _ in self.pairs) - - class MapSpec(_StrictSpec): - """A map: one label per row of its subject, a dimension or a relation, from the dimension that ``dim:`` names. + """A map: one label per label of its subject, a dimension, from the dimension that ``dim:`` names. Written in YAML under its subject, with ``dim:`` always written:: @@ -331,7 +270,7 @@ def _refused_or_absent(cls, v: object) -> object: def _refused_or_absent(v: object, kind: str, rewrite: str) -> object: - """*v* where it is ``refused`` or ``absent``, the two words a ``missing:`` of a relation or a map takes.""" + """*v* where it is ``refused`` or ``absent``, the two words a ``missing:`` of a map takes.""" if v is None: raise _missing_null(kind, rewrite) if v not in get_args(RelationMissing): @@ -1004,7 +943,7 @@ class PiecewiseLinkSpec(_StrictSpec): [`Spec.to_yaml`][] reproduces the file. A link that names ``by: subject[map]`` reads the curve's weights - through the relation, as ``at`` reads an array, and is written as a + through the map, as ``at`` reads an array, and is written as a mapping. Its row is the entry's ``dims:`` with the dims the lookup reads replaced by the key columns it arrives at, so one link emits a row per fine coordinate and each reads the curve of the coarse coordinate it maps to. @@ -1016,11 +955,11 @@ class PiecewiseLinkSpec(_StrictSpec): values: str sign: Sense = '==' by: str | None = None - """The relation and column that the link reads the weights of the curve at, as ``at(..., by=)`` names them.""" + """The subject and map that the link reads the weights of the curve at, as ``at(..., by=)`` names them.""" @property def walks(self) -> bool: - """Whether the link reads the curve's weights through a relation, rather than on the entry's own dims.""" + """Whether the link reads the curve's weights through a map, rather than on the entry's own dims.""" return self.by is not None @model_validator(mode='before') @@ -1132,7 +1071,7 @@ def _check_dims(cls, data: object) -> object: msg = ( 'a piecewise entry declares dims:, the dimensions with one curve per coordinate, as a variable ' 'declares its own. Write the dimensions its links are over, without any that a link adds through ' - 'a relation: dims: [generator, snapshot] for a link on p over [generator, snapshot].' + 'a map: dims: [generator, snapshot] for a link on p over [generator, snapshot].' ) raise ValueError(msg) return data @@ -1183,7 +1122,7 @@ def _check_links(cls, v: Frozen[str, PiecewiseLinkSpec]) -> Frozen[str, Piecewis if len(v) < 2 and not any(link.walks for link in v.values()): msg = ( 'piecewise needs at least two links ([expression, values, sign?]), or one link that walks a ' - 'relation. One quantity on a curve is a bound, not a curve.' + 'map. One quantity on a curve is a bound, not a curve.' ) raise ValueError(msg) if all(link.sign != '==' for link in v.values()): @@ -1274,9 +1213,8 @@ class is pydantic's, not a contract this package keeps. given: GivenSpec = GivenSpec() """What this file uses and does not build ([`GivenSpec`][]). It is empty when the file has no ``given:``.""" dimensions: ByName[DimensionSpec] = Frozen({}) - relations: ByName[RelationSpec] = Frozen({}) maps: ByName[ByName[MapSpec]] = Frozen({}) - """Each subject's maps, by subject, a dimension or a relation, and then by map ([`MapSpec`][]).""" + """Each subject's maps, by subject, a dimension, and then by map ([`MapSpec`][]).""" parameters: ByName[ParameterSpec] = Frozen({}) conditions: ByName[ConditionSpec] = Frozen({}) variables: ByName[VariableSpec] = Frozen({}) @@ -1469,37 +1407,30 @@ def labels_of(spec: Spec, name: str) -> DimensionSpec: def subject_tables(spec: Spec) -> dict[str, Relation]: - """Each table the data supplies, by name: a relation with its maps as columns beside its own, and a dimension with maps. - - A relation's table has one row per row of the relation, keyed by all of its - own columns. A dimension's table has one row per label, keyed by the - dimension, and an alias has the map to the dimension it aliases. Each map is - a column of its subject's table, and a map under - ``missing: absent`` is listed as [`partial`][mathspec.program.Relation.partial]. - A dimension with members has a table whether or not the file declares maps - of it: each member is a map that every label has, listed as - [`members`][mathspec.program.Relation.members]. + """Each table the data supplies, by name: a dimension with maps, or with members. + + A dimension's table has one row per label, keyed by the dimension, and an + alias has the map to the dimension it aliases. Each map is a column of its + subject's table, and a map under ``missing: absent`` is listed as + [`partial`][mathspec.program.Relation.partial]. A dimension with members + has a table whether or not the file declares maps of it: each member is a + map that every label has, listed as [`members`][mathspec.program.Relation.members]. A subject the file does not declare is left out, which the load refuses. """ tables: dict[str, Relation] = {} tuples = {d: dd.members for d, dd in spec.dimensions.items() if dd.over} aliases = {name: d.alias for name, d in spec.dimensions.items() if d.alias in spec.dimensions} - for name in sorted({*spec.relations, *spec.maps, *tuples, *aliases}): + for name in sorted({*spec.maps, *tuples, *aliases}): + if name not in spec.dimensions: + continue maps = spec.maps.get(name, Frozen({})) if name in aliases: maps = {aliases[name]: MapSpec(dim=aliases[name]), **maps} - if (relation := spec.relations.get(name)) is not None: - key, missing, description = relation.pairs, relation.missing, relation.description - elif name in spec.dimensions: - key, missing, description = ((name, name),), cast('RelationMissing', 'refused'), None - else: - continue - members = tuples.get(name, ()) if relation is None else () + members = tuples.get(name, ()) values = tuple(sorted((*members, *((role, m.dim) for role, m in maps.items())))) partial = tuple(role for role, m in maps.items() if m.missing == 'absent') - key_roles = tuple(r for r, _ in key) tables[name] = Relation( - (*key, *values), key_roles, missing, description, partial, tuple(role for role, _ in members) + ((name, name), *values), (name,), 'refused', None, partial, tuple(role for role, _ in members) ) return tables diff --git a/tests/test_composition.py b/tests/test_composition.py index 47996afe7..24a07b9f9 100644 --- a/tests/test_composition.py +++ b/tests/test_composition.py @@ -230,9 +230,9 @@ def _mapped(missing: str | None = None, dim: str = 'bus') -> dict[str, object]: def _wired(missing: str | None = None) -> dict[str, object]: - """A fragment that declares only the relation `wired` over `port` and `bus`, as `_mapped` does a map.""" - entry = {'dims': ['port', 'bus']} | ({} if missing is None else {'missing': missing}) - return {'dimensions': {'port': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, 'relations': {'wired': entry}} + """A fragment that declares only the dimension `wired` over `port` and `bus`, as `_mapped` does a map.""" + entry = {'over': ['port', 'bus']} | ({} if missing is None else {'missing': missing}) + return {'dimensions': {'port': {'dtype': 'str'}, 'bus': {'dtype': 'str'}, 'wired': entry}} #: A fragment that gives `port` a map of its own beside the one `SURFACE` gives it. @@ -276,7 +276,7 @@ def test_two_fragments_that_say_one_missing_agree(fragments, missing): pytest.param([SURFACE, _mapped('absent')], "map 'port[bus]'", id='refused-against-absent'), pytest.param([_mapped('absent'), SURFACE], "map 'port[bus]'", id='absent-against-refused'), pytest.param([SURFACE, _mapped(dim='node')], "map 'port[bus]'", id='two-dimensions-referred-to'), - pytest.param([_wired(), _wired('absent')], "relation 'wired'", id='a-relation-refused-against-absent'), + pytest.param([_wired('refused'), _wired()], "dimension 'wired'", id='a-tuple-refused-against-absent'), ], ) def test_two_fragments_that_say_different_things_about_one_entry_are_refused(fragments, entry): @@ -598,8 +598,8 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated assert laid.dimensions[dimension].ordered is ordered -#: `SURFACE` with a relation, `wired`, over the two dimensions `port[bus]` maps between. -WIRED = varied(SURFACE, **{'relations.wired': {'dims': ['port', 'bus']}}) +#: `SURFACE` with a dimension, `wired`, over the two dimensions `port[bus]` maps between. +WIRED = varied(SURFACE, **{'dimensions.wired': {'over': ['port', 'bus']}}) @pytest.mark.parametrize( @@ -613,11 +613,11 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated id='a-dimension', ), pytest.param( - varied(WIRED, **{'relations.wired.description': 'which ports reach which buses'}), - {'relations': {'wired': {'dims': ['port', 'bus'], 'description': 'a port and the buses it reaches'}}}, - lambda spec: spec.relations['wired'].description, + varied(WIRED, **{'dimensions.wired.description': 'which ports reach which buses'}), + {'dimensions': {'wired': {'over': ['port', 'bus'], 'description': 'a port and the buses it reaches'}}}, + lambda spec: spec.dimensions['wired'].description, 'a port and the buses it reaches', - id='a-relation', + id='a-tuple-dimension', ), pytest.param( varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), @@ -641,11 +641,11 @@ def test_a_patch_restates_a_dimension_as_the_schema_reads_it(dimension, restated id='null-removes-a-dimension-description', ), pytest.param( - varied(WIRED, **{'relations.wired.description': 'which ports reach which buses'}), - {'relations': {'wired': {'description': None}}}, - lambda spec: spec.relations['wired'].description, + varied(WIRED, **{'dimensions.wired.description': 'which ports reach which buses'}), + {'dimensions': {'wired': {'description': None}}}, + lambda spec: spec.dimensions['wired'].description, None, - id='null-removes-a-relation-description', + id='null-removes-a-tuple-dimension-description', ), pytest.param( varied(SURFACE, **{'maps.port.bus': {'dim': 'bus', 'description': 'where a port connects'}}), @@ -725,17 +725,13 @@ def test_a_patch_that_rewrites_a_dimension_is_refused(patch, says): @pytest.mark.parametrize( ('patch', 'kind', 'name'), [ - pytest.param({'relations': {'wired': {}}}, 'relation', 'wired', id='a-relation-with-no-field'), - pytest.param( - {'relations': {'wired': {'dims': ['port']}}}, 'relation', 'wired', id='a-relation-over-one-dimension' - ), pytest.param({'maps': {'port': {'bus': {}}}}, 'map', 'port[bus]', id='a-map-with-no-field'), ], ) def test_a_patch_that_restates_an_entry_in_part_is_refused_with_the_rewrite(patch, kind, name): """An entry the schema refuses on its own was refused by the schema, without the patch or the rewrite. - A relation restated as `{}` failed with `Field required`, where the same entry under + A map restated as `{}` failed with `Field required`, where the same entry under `dimensions:` names the patch and says how to restate the entry. """ with pytest.raises(LanguageError, match=re.escape(f"patch '#1' declares the {kind} '{name}'")) as raised: @@ -746,11 +742,6 @@ def test_a_patch_that_restates_an_entry_in_part_is_refused_with_the_rewrite(patc @pytest.mark.parametrize( ('patch', 'says'), [ - pytest.param( - {'relations': {'wired': {'dmis': ['port', 'bus']}}}, - "unknown key 'dmis' in a relation entry. Did you mean 'dims'?", - id='a-relation', - ), pytest.param( {'maps': {'port': {'bus': {'dmi': 'bus'}}}}, "unknown key 'dmi' in a map entry. Did you mean 'dim'?", @@ -803,10 +794,6 @@ def test_a_patch_changes_what_a_row_the_map_gives_no_label_means(base, map_, mis assert override(base, [{'maps': {'port': {'bus': map_}}}]).maps['port']['bus'].missing == missing -def test_a_patch_changes_what_a_combination_the_relation_leaves_out_means(): - assert override(WIRED, [{'relations': {'wired': {'missing': 'absent'}}}]).relations['wired'].missing == 'absent' - - @pytest.mark.parametrize( ('base', 'written', 'missing'), [ @@ -827,7 +814,6 @@ def test_a_patch_changes_what_a_missing_row_of_a_parameter_means(base, written, ('section', 'name', 'declared'), [ pytest.param('parameters', 'c', {'dims': ['g']}, id='a-parameter'), - pytest.param('relations', 'gh', {'dims': ['g', 'h']}, id='a-relation'), pytest.param('maps', 'g.h', {'dim': 'h'}, id='a-map'), ], ) diff --git a/tests/test_dimensions.py b/tests/test_dimensions.py index 2337fff82..627f5b209 100644 --- a/tests/test_dimensions.py +++ b/tests/test_dimensions.py @@ -66,8 +66,8 @@ 'generator': {'dtype': 'str', 'ordered': True}, 'bus': {'dtype': 'str'}, 'zone': {'dtype': 'str'}, + 'gen_zone': {'over': ['generator', 'snapshot'], 'missing': 'refused'}, }, - 'relations': {'gen_zone': {'dims': ['generator', 'snapshot']}}, 'maps': { 'generator': {'bus': {'dim': 'bus'}, 'zone': {'dim': 'zone'}, 'b0': {'dim': 'bus'}, 'b1': {'dim': 'bus'}}, 'snapshot': {'bus': {'dim': 'bus'}, 'rep': {'dim': 'snapshot'}}, @@ -143,26 +143,6 @@ def namespace() -> Namespace: id='a-by-makes-a-width-over-another-dim-readable-one-window-per-group', ), pytest.param('p + 1', {'snapshot', 'generator'}, id='a-scalar-broadcasts'), - pytest.param( - 'sum(p, over=generator, by=gen_zone[zone])', - {'snapshot', 'zone'}, - id='a-two-key-relation-sums-away-the-key-it-names-and-keeps-the-other', - ), - pytest.param( - 'sum(p, over=snapshot, by=gen_zone[zone])', - {'generator', 'zone'}, - id='the-same-table-read-along-its-other-key', - ), - pytest.param( - 'at(zone_load, by=gen_zone[zone])', - {'snapshot', 'generator'}, - id='its-lookup-keeps-the-joined-key-too', - ), - pytest.param( - "shift(p, along=generator, offset=1, edge='wrap', within=gen_zone[zone])", - {'snapshot', 'generator'}, - id='a-partition-along-one-key-joined-on-the-other', - ), pytest.param( "shift(p, along=generator, offset=1, edge='wrap', within=generator[bus])", {'snapshot', 'generator'}, @@ -181,7 +161,7 @@ def namespace() -> Namespace: pytest.param( 'sum(p, over=generator, by=generator[bus])', {'snapshot', 'bus'}, - id='the-dot-is-legal-on-a-one-key-relation', + id='the-dot-is-legal-on-a-map-of-a-dimension', ), pytest.param( 'sum(p, over=generator, by=generator[bus, zone])', @@ -193,11 +173,6 @@ def namespace() -> Namespace: {'generator'}, id='a-from-list-reads-two-value-columns-at-once', ), - pytest.param( - 'sum(p, over=[generator, snapshot], by=gen_zone[zone])', - {'zone'}, - id='an-over-list-joins-on-two-key-columns-at-once', - ), pytest.param( 'sum(p, over=generator, by=generator[bus])', {'snapshot', 'bus'}, @@ -218,7 +193,7 @@ def namespace() -> Namespace: pytest.param( 'sum(p, over=[generator, snapshot], by=generator[bus])', {'bus'}, - id='a-dim-the-relation-has-no-column-over-is-summed-after-the-group-by', + id='a-dim-the-map-is-not-over-is-summed-after-the-group-by', ), pytest.param( "shift(p, along=snapshot, offset=1, edge='wrap', within=snapshot[rep])", @@ -236,27 +211,7 @@ def _dims_with(expr: str, **overrides) -> frozenset[str]: return frozenset(expression_of(expr, Namespace(s), 't').dims) -@pytest.mark.parametrize( - ('expr', 'expected'), - [ - pytest.param( - 'sum(p, over=generator, by=connection[bus])', - {'snapshot', 'bus'}, - id='a-sum-through-a-bare-relation-groups-by-a-key-column', - ), - pytest.param( - 'sum(load, over=bus, by=connection[generator])', - {'snapshot', 'generator'}, - id='and-the-same-table-summed-the-other-way', - ), - ], -) -def test_a_bare_relation_is_summed_between_its_key_columns(expr, expected): - """A bare relation holds no value column, so the column a sum groups by is a key column.""" - assert _dims_with(expr, **{'relations.connection': {'dims': ['generator', 'bus']}}) == expected - - -def test_a_value_column_added_to_a_relation_changes_no_call(): +def test_a_map_added_to_a_dimension_changes_no_call(): """A name in `over=` is a column of the table, so `snapshot` gaining a map `alt` leaves every call as it was. `over=snapshot` read as a dimension would match two columns once `alt` @@ -403,18 +358,6 @@ def test_a_bare_name_reaches_the_variable_a_dual_the_same_named_constraint(): r"varies over \['bus'\], which the expression does not carry", id='a-named-offset-is-read-where-the-expression-has-a-coordinate', ), - pytest.param( - 'sum(cost, over=generator, by=gen_zone[zone])', - DimensionError, - r"sum\(by=gen_zone\[zone\]\) joins on \['snapshot'\]", - id='a-grouped-sum-needs-the-keys-it-joins-on', - ), - pytest.param( - "shift(cost, along=generator, offset=1, edge='wrap', within=gen_zone[zone])", - DimensionError, - r"within=gen_zone\[zone\]\) joins on \['snapshot'\]", - id='a-partition-needs-the-keys-it-joins-on', - ), ], ) def test_an_ill_dimensioned_expression_is_rejected(expr, error, match): @@ -428,52 +371,6 @@ def test_an_ill_dimensioned_expression_is_rejected(expr, error, match): _dims(expr) -@pytest.mark.parametrize( - ('expr', 'diag'), - [ - pytest.param( - 'sum(p, over=k, by=diag[z])', - {'dims': {'k': 'generator', 'j': 'generator', 'z': 'zone'}}, - id='a-sum-summing-away-a-column-over-a-dimension-it-also-joins-on', - ), - ], -) -def test_two_joined_columns_do_not_share_a_dimension(expr, diag): - """The operand carries one coordinate per dimension, so the `over=` column and an unnamed key column cannot share one.""" - with pytest.raises(DimensionError, match=r"joins 'diag' on \[.*\] through more than one column"): - _dims_with(expr, **{'relations.diag': diag}) - - -@pytest.mark.parametrize( - ('expr', 'maps', 'expected'), - [ - pytest.param( - 'at(zone_cap, by=gen_zone[zone])', - {'zone': {'dim': 'zone'}}, - {'generator', 'snapshot'}, - id='a-key-column-the-operand-lacks-arrives', - ), - pytest.param( - 'at(load, by=gen_zone[rep])', - {'rep': {'dim': 'snapshot'}}, - {'bus', 'snapshot', 'generator'}, - id='a-key-column-over-the-dimension-the-read-column-matches-arrives', - ), - ], -) -def test_a_lookup_joins_on_the_key_columns_the_operand_carries_and_the_read_does_not_match(expr, maps, expected): - """`at` joins on each key column over a dim the operand carries, unless the column it reads already matches that dim. - - `at(load, by=diag, over=rep, into=generator)` once joined on the key's - `snapshot` beside `rep`, at the operand's one snapshot coordinate. The - call names only the column it reads now, so the key's `snapshot` arrives - and the result is `load` read at `rep(t, g)` for every `(t, g)`. - """ - assert _dims_with(expr, **{'maps.gen_zone': maps}) == frozenset(expected), ( - 'the frame is the operand less the dim read, plus the key' - ) - - def test_an_outer_product_is_legal_and_carries_both_dim_sets(): """Binary ops union. Requiring subset instead would reject the convex piecewise epigraph, which multiplies a per-segment slope by a per-snapshot @@ -609,17 +506,11 @@ def test_a_zero_step_vacates_nothing_and_needs_no_edge(self): pytest.param('snapshot == 0', {'snapshot'}, id='a-dimension-through-itself'), pytest.param('position(snapshot) == 0', {'snapshot'}, id='a-position-through-the-axis-it-counts'), pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-map-through-the-dim-it-maps-out-of'), - pytest.param('gen_zone[zone] == "z1"', {'generator', 'snapshot'}, id='a-two-key-relation-through-both-keys'), - pytest.param('gen_zone', {'generator', 'snapshot'}, id='a-bare-two-key-relation-the-same'), + pytest.param('gen_zone', {'generator', 'snapshot'}, id='a-bare-tuple-reads-its-members'), pytest.param('snapshot[rep] == 3', {'snapshot'}, id='a-map-into-its-own-dimension-through-its-key'), pytest.param( 'position(snapshot, within=snapshot[rep]) == 0', {'snapshot'}, id='a-position-within-a-representative' ), - pytest.param( - 'position(generator, within=gen_zone[zone]) == 0', - {'generator', 'snapshot'}, - id='a-position-within-a-group-of-a-two-key-relation-reads-both-keys', - ), pytest.param( 'position(generator, within=generator[zone]) == 0', {'generator'}, @@ -667,7 +558,7 @@ def test_the_frame_check_and_the_reading_walk_the_same_leaves(namespace): pytest.param('p', {'p'}, id='a-variable-bare-names-the-variable'), pytest.param('snapshot[bus] == "b1"', {'snapshot'}, id='a-map-comparison-names-its-subject'), pytest.param('generator[bus]', {'generator'}, id='a-map-test-names-its-subject'), - pytest.param('gen_zone', {'gen_zone'}, id='a-relation-bare-names-the-relation'), + pytest.param('gen_zone', {'gen_zone'}, id='a-bare-tuple-names-the-tuple'), pytest.param('snapshot == 0', set(), id='a-dimension-names-nothing-it-is-a-coordinate'), pytest.param('position(snapshot) == 0', set(), id='a-position-names-nothing'), pytest.param('p_max > 0 AND snapshot == 0', {'p_max'}, id='a-conjunction-drops-the-dimension-side'), @@ -689,13 +580,12 @@ def test_a_condition_names_the_entries_its_leaves_test(namespace, condition, exp @pytest.mark.parametrize( ('condition', 'expected'), [ - pytest.param('gen_zone[zone] != home_of[zone]', {'gen_zone', 'home_of'}, id='two-subjects-are-both-named'), pytest.param('generator[b0] != generator[b1]', {'generator'}, id='one-subject-is-named-once'), ], ) def test_names_read_takes_both_sides_of_a_map_pair(condition, expected): """The one leaf that can name two entries — two maps compared row by row on the key their subjects share.""" - home_of = {'relations.home_of': {'dims': ['generator', 'snapshot']}, 'maps.home_of': {'zone': {'dim': 'zone'}}} + home_of = {'dimensions.home_of': {'over': ['generator', 'snapshot']}, 'maps.home_of': {'zone': {'dim': 'zone'}}} where = where_of(condition, Namespace(_spec(**home_of)), 'test') assert where is not None, 'a condition the connectives cannot settle survives the fold' @@ -895,13 +785,11 @@ def test_the_order_a_file_writes_dimensions_in_reaches_no_value_of_the_program(p @pytest.mark.parametrize('path', SPECS, ids=lambda path: str(path.relative_to(EXAMPLES))) def test_the_order_a_file_writes_a_list_in_reaches_no_value_of_the_spec(path): - """A spec held each `dims:` list and each side of a relation as its file wrote them, so two files that state + """A spec held each `dims:` list and each `over:` list as its file wrote them, so two files that state one spec loaded to two specs, and wrote back two texts.""" spec = to_spec(path) backwards = to_spec(sets_reversed(spec.to_dict())) - assert backwards == spec, ( - 'every dims:, one_of: and kwargs: list and each side of a relation is sorted as the spec loads' - ) + assert backwards == spec, 'every dims:, over:, one_of: and kwargs: list is sorted as the spec loads' assert backwards.to_yaml() == spec.to_yaml(), 'so the spec writes back one text' @@ -914,7 +802,6 @@ def test_the_order_a_file_lists_its_entries_in_reaches_no_value_of_the_spec(path assert backwards.to_yaml() == spec.to_yaml(), 'the entries of each section are sorted as the spec loads' for section in ( 'dimensions', - 'relations', 'parameters', 'conditions', 'variables', @@ -969,18 +856,16 @@ def test_every_dims_of_the_program_is_sorted_by_name(path): @pytest.mark.parametrize( 'entry', [ - pytest.param({'where': 'zone_of'}, id='the-rows-of-the-relation'), - pytest.param({'where': "zone_of[zone] == 'north'"}, id='a-column-against-a-label'), - pytest.param({'where': 'zone_of[zone] == home_of[zone]'}, id='a-column-against-another-relation'), + pytest.param({'where': 'zone_of'}, id='the-tuples-of-the-dimension'), ], ) -def test_a_condition_on_a_relation_states_its_key_dims_sorted_by_name(entry): - """A condition on a relation stated the dims in the order the relation lists its key.""" - keyed_backwards = {'dims': ['snapshot', 'generator'], 'missing': 'absent'} +def test_a_membership_test_states_its_member_dims_sorted_by_name(entry): + """A membership test states its member dims sorted, whatever order `over:` lists them in.""" + keyed_backwards = {'over': ['snapshot', 'generator']} spec = _spec( **{ - 'relations.zone_of': keyed_backwards, - 'relations.home_of': keyed_backwards, + 'dimensions.zone_of': keyed_backwards, + 'dimensions.home_of': keyed_backwards, 'maps.zone_of': {'zone': {'dim': 'zone'}}, 'maps.home_of': {'zone': {'dim': 'zone'}}, } @@ -989,5 +874,5 @@ def test_a_condition_on_a_relation_states_its_key_dims_sorted_by_name(entry): where = to_spec(varied(spec.to_dict(), **patch)).program.variables['p'].where assert where is not None assert [dims for _, dims in _dims_tuples(where.root)] == [('generator', 'snapshot')], ( - 'the condition states the relation key dims, sorted by name' + 'the condition states the member dims, sorted by name' ) diff --git a/tests/test_expansion.py b/tests/test_expansion.py index e5d3d33a9..9499d4787 100644 --- a/tests/test_expansion.py +++ b/tests/test_expansion.py @@ -290,8 +290,8 @@ def test_macro_collisions_rejected(patch, match): ), pytest.param( {'grouped': {'args': ['x'], 'template': 'sum(x, over=g, by=nope[h])'}}, - r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a relation", - id='a-typo-in-a-relation-kwarg', + r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a dimension with maps or members", + id='a-typo-in-a-subject-kwarg', ), pytest.param( {'grouped': {'args': ['x'], 'template': 'sum(x, over=g, by=[nope, also])'}}, @@ -300,8 +300,8 @@ def test_macro_collisions_rejected(patch, match): ), pytest.param( {'grouped': {'args': ['x', 'a', 'b'], 'template': 'sum(x, over=a, by=nope[b])'}}, - r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a relation, a dimension with maps or a formal argument of this macro", - id='a-typo-in-a-relation-beside-formal-columns', + r"Macro 'grouped'.*sum\(by=nope\[\.\.\.\]\): 'nope' is not a dimension with maps or members, or a formal argument of this macro", + id='a-typo-in-a-subject-beside-formal-columns', ), pytest.param( {'reduced': {'args': ['x'], 'template': 'sum(x, over=nope)'}}, @@ -370,7 +370,7 @@ def test_an_unknown_operator_names_no_construct_the_language_lacks(): [ pytest.param(['x', 'e'], 'shift(x, along=g, offset=1, edge=e)', id='an-edge'), pytest.param(['row'], 'dual(row)', id='a-constraint'), - pytest.param(['x', 'rel', 'a', 'b'], 'sum(x, over=a, by=rel[b])', id='a-relation-and-its-columns'), + pytest.param(['x', 'rel', 'a', 'b'], 'sum(x, over=a, by=rel[b])', id='a-subject-and-its-columns'), pytest.param(['x', 'a', 'b'], 'sum(x, over=a, by=g[b])', id='the-maps-of-a-declared-subject'), pytest.param( ['x', 'd'], 'shift(x, along=d, offset=1, within=g[h])', id='the-dimension-a-partition-steps-along' diff --git a/tests/test_lowering.py b/tests/test_lowering.py index fd0067258..ca77a30d4 100644 --- a/tests/test_lowering.py +++ b/tests/test_lowering.py @@ -715,104 +715,64 @@ def _partition_of(row): return partition -def test_a_relation_lowers_with_the_join_each_call_names(): - """Every node reading a relation carries its columns, its key and the join, so a consumer joins on the right columns.""" +def test_a_tuple_lowers_with_the_join_each_call_names(): + """Every node reading a tuple's maps carries the table, its key and the join, so a consumer joins on the right columns.""" program = to_spec( { - 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'generator': {'ordered': True}, 'zone': {}}, - 'relations': {'zone_of': {'dims': ['generator', 'snapshot'], 'missing': 'absent'}}, + 'dimensions': { + 'snapshot': {'dtype': 'int', 'ordered': True}, + 'generator': {}, + 'zone': {}, + 'zone_of': {'over': ['generator', 'snapshot']}, + }, 'maps': {'zone_of': {'zone': {'dim': 'zone'}}}, 'parameters': {'price': {'dims': ['snapshot', 'zone']}}, - 'variables': { - 'p': {'dims': ['snapshot', 'generator'], 'where': "zone_of AND zone_of[zone] == 'A'"}, - 'first': { - 'dims': ['snapshot', 'generator'], - 'where': 'position(generator, within=zone_of[zone]) == 0', - }, - }, + 'variables': {'p': {'dims': ['zone_of']}}, 'constraints': { 'zonal': { 'dims': ['snapshot', 'zone'], - 'expression': 'sum(p, over=generator, by=zone_of[zone]) <= 1', - }, - 'priced': { - 'dims': ['snapshot', 'generator'], - 'expression': 'p <= at(price, by=zone_of[zone])', - }, - 'history': { - 'dims': ['generator', 'zone'], - 'expression': 'sum(p, over=snapshot, by=zone_of[zone]) <= 1', + 'expression': 'sum(p, over=zone_of, by=zone_of[snapshot, zone]) <= 1', }, + 'priced': {'dims': ['zone_of'], 'expression': 'p <= at(price, by=zone_of[snapshot, zone])'}, }, } ).program - columns = (('generator', 'generator'), ('snapshot', 'snapshot'), ('zone', 'zone')) - declared = Relation(columns, ('generator', 'snapshot'), missing='absent') - assert program.relations == {'zone_of': declared}, 'the relation sits once in the program, under its name' + columns = (('zone_of', 'zone_of'), ('generator', 'generator'), ('snapshot', 'snapshot'), ('zone', 'zone')) + table = Relation(columns, ('zone_of',), members=('generator', 'snapshot')) + assert program.relations == {'zone_of': table}, 'the tuple has one table, keyed by itself, a column per member' zonal = program.constraints['zonal'].lhs - columns = JoinColumns('zone_of', declared, ('generator', 'snapshot'), ('snapshot', 'zone')) assert zonal == Sum( - Join(VariableReference('p', dims=('generator', 'snapshot')), columns, dims=('snapshot', 'zone')), - (Axis('generator', Column('zone_of', 'generator')),), + Join( + VariableReference('p', dims=('zone_of',)), + JoinColumns('zone_of', table, ('zone_of',), ('snapshot', 'zone')), + dims=('snapshot', 'zone'), + ), + (Axis('zone_of', Column('zone_of', 'zone_of')),), dims=('snapshot', 'zone'), - ), ( - 'a grouped sum is a sum over a join: the join names the column over the over= dim and the unnamed key ' - 'column as joined on, the by= column and that key column as grouped by, and the sum stands over the axis ' - 'the join opens for the column it drops' - ) + ), 'a grouped sum is a sum over a join on the tuple, grouped by the member and the map it names' assert isinstance(zonal, Sum) and isinstance(zonal.operand, Join) - assert (zonal.operand.columns.dropped_dims, zonal.operand.columns.added_dims, zonal.operand.columns.kept) == ( - ('generator',), - ('zone',), - ('snapshot',), - ), 'the dims a consumer reads are read off the join: dropped, added, and the key columns kept' assert zonal.operand.columns.relation is program.relations['zone_of'], ( 'the join holds the one entry the program holds, not an equal copy built again' ) - assert program.constraints['history'].lhs == Sum( - Join( - VariableReference('p', dims=('generator', 'snapshot')), - JoinColumns('zone_of', declared, ('generator', 'snapshot'), ('generator', 'zone')), - dims=('generator', 'zone'), - ), - (Axis('snapshot', Column('zone_of', 'snapshot')),), - dims=('generator', 'zone'), - ), 'the same table joined on its other key column' - priced = program.constraints['priced'].rhs - assert priced == Join( + assert program.constraints['priced'].rhs == Join( ParameterReference('price', dims=('snapshot', 'zone')), - JoinColumns('zone_of', declared, ('snapshot', 'zone'), ('generator', 'snapshot')), - dims=('generator', 'snapshot'), - ), 'and an at is the bare join, on the value column, grouped by the key columns' - assert isinstance(priced, Join) - assert (priced.columns.dropped_dims, priced.columns.added_dims, priced.columns.kept) == ( - ('zone',), - ('generator',), - ('snapshot',), - ), 'an at joins on the coarse dims, groups by the fine, and keeps the rest of the key' - p_where = program.variables['p'].where - assert p_where is not None - assert [(type(a).__name__, a.dims) for a in p_where.atoms] == [ - ('RelationDefined', ('generator', 'snapshot')), - ('RelationComparison', ('generator', 'snapshot')), - ], 'a row and a comparison are both read at the key of a keyed relation' - first_where = program.variables['first'].where - assert first_where is not None - assert first_where.dims == ('generator', 'snapshot'), 'a position within a group is read at every key column' + JoinColumns('zone_of', table, ('snapshot', 'zone'), ('zone_of',)), + dims=('zone_of',), + ), 'an at is the bare join: on the member and the map it names, grouped by the tuple' @pytest.mark.parametrize( ('variable', 'entry', 'atom'), [ - pytest.param('q', {'where': 'link'}, RelationDefined('link', ('g', 'h')), id='a-bare-relation-tests-a-row'), + pytest.param('q', {'where': 'link'}, RelationDefined('link', ('g', 'h')), id='a-bare-tuple-tests-its-members'), pytest.param('p', {'where': 'g[h]'}, RelationDefined('g', ('g',), 'h'), id='a-map-alone-tests-a-label'), ], ) def test_a_condition_tests_a_row_or_a_label_by_how_it_is_written(variable, entry, atom): - """A relation's bare name asks for a row, and `subject[map]` alone asks whether the map gives the row a label.""" + """A tuple's bare name asks for its member tuple, and `subject[map]` alone asks whether the map gives a label.""" patch = { - 'relations.link': {'dims': ['g', 'h'], 'missing': 'absent'}, + 'dimensions.link': {'over': ['g', 'h']}, 'maps.g.h': {'dim': 'h', 'missing': 'absent'}, **{f'variables.{variable}.{key}': value for key, value in entry.items()}, } @@ -891,23 +851,22 @@ def test_walk_is_the_node_column_of_walk_regions(): assert list(walk(NESTED)) == [node for node, _ in walk_regions(NESTED)] -def test_a_relation_is_declared_as_the_file_declares_it(): - """One table per subject, keyed by its name: a relation's rows, and a dimension's labels once it has maps.""" +def test_a_subject_is_declared_as_the_file_declares_it(): + """One table per subject, keyed by its name: a tuple with its members, and a dimension once it has maps.""" program = to_spec( varied( TINY, - dimensions={'g': {}, 'bus': {}, 'season': {}}, - relations={'link': {'dims': ['g', 'bus'], 'missing': 'absent'}}, + dimensions={'g': {}, 'bus': {}, 'season': {}, 'link': {'over': ['g', 'bus']}}, maps={'g': {'season': {'dim': 'season'}, 'bus': {'dim': 'bus', 'missing': 'absent'}}}, ) ).program assert program.relations == { 'g': Relation((('g', 'g'), ('bus', 'bus'), ('season', 'season')), ('g',), partial=('bus',)), - 'link': Relation((('bus', 'bus'), ('g', 'g')), ('bus', 'g'), missing='absent'), - }, 'a table per subject, its own columns first, then one column per map' + 'link': Relation((('link', 'link'), ('bus', 'bus'), ('g', 'g')), ('link',), members=('bus', 'g')), + }, 'a table per subject, its own column first, then one column per member or map' assert program.relations['g'].values == ('bus', 'season'), 'the maps are what a row of the subject determines' - assert program.relations['link'].values == (), 'a relation with no maps determines nothing' + assert program.relations['link'].values == ('bus', 'g'), 'a tuple determines its members' assert program.dimensions['g'] == Dimension(dtype='str'), 'a dimension carries its dtype and no map' diff --git a/tests/test_piecewise.py b/tests/test_piecewise.py index cafd5c33d..903b9733d 100644 --- a/tests/test_piecewise.py +++ b/tests/test_piecewise.py @@ -516,7 +516,7 @@ def test_a_link_reading_a_dual_entry_is_refused(): @pytest.mark.parametrize( ('activity', 'match'), [ - pytest.param('at(u_unit, by=generator[unit])', 'is not a declared variable', id='a-lookup-through-a-relation'), + pytest.param('at(u_unit, by=generator[unit])', 'is not a declared variable', id='a-lookup-through-a-subject'), pytest.param( 'shift(u, along=snapshot, offset=1)', 'is neither a variable nor a variable read', id='a-shifted-gate' ), @@ -973,13 +973,6 @@ def _walk(**written: object) -> dict[str, object]: return {'piecewise.coupling.links.power': {k: v for k, v in link.items() if v is not None}} -def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: - """The `power` link walked through `generator_of`, a relation over *dims* that maps each row to a generator.""" - return {'relations.generator_of': {'dims': dims}, 'maps.generator_of.generator': {'dim': 'generator'}} | _walk( - by='generator_of[generator]' - ) - - @pytest.mark.parametrize( ('patch', 'match'), [ @@ -999,7 +992,7 @@ def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: pytest.param( _walk(by='flow[snapshot]'), r"at\(by=flow\[snapshot\]\) names \['snapshot'\], which is no map of 'flow'", - id='a-walk-naming-a-column-the-relation-lacks', + id='a-walk-naming-a-column-the-subject-lacks', ), pytest.param( {'piecewise.coupling.dims': ['generator', 'snapshot', 'bp']}, @@ -1011,7 +1004,7 @@ def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: r"link 'power' expression is over \['snapshot'\], and its row \['flow'\] is not", id='dims-a-link-expression-leaves', ), - pytest.param(_walk(by='nowhere_of[generator]'), 'nowhere_of', id='a-walk-through-an-undeclared-relation'), + pytest.param(_walk(by='nowhere_of[generator]'), 'nowhere_of', id='a-walk-through-an-undeclared-subject'), pytest.param( {'piecewise.coupling.dims': ['snapshot']}, r"link 'power': by: flow looks the curve up at \['generator'\], which is not in dims: \['snapshot'\]", @@ -1043,16 +1036,6 @@ def _joined(dims: list[str] | dict[str, str]) -> dict[str, object]: r"link 'fuel': at\(by=flow\[flow\]\) names \['flow'\], a column of 'flow' itself", id='a-walk-landing-off-the-key', ), - pytest.param( - {'dimensions.period': {'dtype': 'int'}} | _joined(['flow', 'period']), - r"link 'power' expression is not over \['period'\]", - id='a-walk-joining-on-a-dim-the-block-lacks', - ), - pytest.param( - _joined({'flow': 'flow', 'site': 'generator'}), - r"link 'power': by: generator_of adds \['generator'\], which the curve is already over", - id='a-walk-joining-on-the-dim-it-consumes', - ), ], ) def test_a_walked_block_the_language_cannot_read_is_refused(patch, match): @@ -1075,13 +1058,6 @@ def test_a_walked_block_the_language_cannot_read_is_refused(patch, match): _walk(by='flow[generator]'), id='a-walk-naming-a-column-over-the-breakpoint-dim', ), - pytest.param( - WALKED, - _joined(['flow', 'bp']), - r"by: generator_of is keyed on 'bp', the breakpoint dimension", - _walk(), - id='a-walk-keyed-on-the-breakpoint-dim', - ), pytest.param( WALKED, {'parameters.bp_power.dims': ['generator', 'bp']}, @@ -1103,13 +1079,6 @@ def test_a_walked_block_the_language_cannot_read_is_refused(patch, match): {'variables.u.dims': ['snapshot']}, id='a-gate-over-the-breakpoint-dim', ), - pytest.param( - WALKED, - {'dimensions.period': {'dtype': 'int'}} | _joined(['flow', 'period']), - r"link 'power' expression is not over \['period'\], which by: generator_of\[generator\] adds", - _walk(), - id='a-walk-adding-a-dim-the-expression-lacks', - ), ], ) def test_a_refusal_suggests_a_rewrite_that_loads(model, refused, match, rewrite): @@ -1400,13 +1369,13 @@ def test_a_gate_read_through_a_relation_prints_as_the_read(): ), pytest.param( {'piecewise.curve.activity': 'at(running, by=bp_p[converter])'}, - r"piecewise 'curve' activity: at\(by=bp_p\[\.\.\.\]\): 'bp_p' is not a relation", - id='a-walk-through-something-no-relation', + r"piecewise 'curve' activity: at\(by=bp_p\[\.\.\.\]\): 'bp_p' is not a dimension with maps or members", + id='a-walk-through-something-with-no-map', ), pytest.param( {'piecewise.curve.activity': 'at(running, by=converter[snapshot])'}, r"at\(by=converter\[snapshot\]\) names \['snapshot'\], which is no map of 'converter'", - id='a-walk-naming-a-column-the-relation-lacks', + id='a-walk-naming-a-column-the-subject-lacks', ), pytest.param( {'piecewise.curve.activity': {'variable': 'running', 'by': 'converter[status_entity]'}}, @@ -1500,7 +1469,7 @@ def test_a_block_mask_reaches_a_walked_link_through_its_relation(): pytest.param( PARTIAL | {'parameters.curved': CURVED['parameters']['curved'], 'piecewise.coupling.where': 'curved'}, 'at(curved, by=flow[generator])', - id='a-mask-read-through-the-relation', + id='a-mask-read-through-the-subject', ), ], ) @@ -1517,15 +1486,14 @@ def test_a_walked_row_exists_only_where_its_relation_has_a_row(patch, where): #: fluxopt's investment cost curve (fluxopt/fluxopt#26): each effect of a sized flow is read off its curve. INVESTED = { 'dimensions': {name: {'dtype': 'str'} for name in ('cost_curve', 'effect', 'flow')} - | {'bp': {'dtype': 'int', 'ordered': True}}, - 'relations': {'cost_of': {'dims': ['flow', 'effect']}}, + | {'bp': {'dtype': 'int', 'ordered': True}, 'cost_of': {'over': ['flow', 'effect'], 'missing': 'refused'}}, 'maps': {'cost_of': {'cost_curve': {'dim': 'cost_curve'}}}, 'parameters': { 'has_cost_curve': {'dims': ['cost_curve'], 'dtype': 'bool'}, 'size_bp': {'dims': ['cost_curve', 'bp']}, - 'cost_bp': {'dims': ['flow', 'effect', 'bp']}, + 'cost_bp': {'dims': ['cost_of', 'bp']}, }, - 'variables': {'size': {'dims': ['cost_curve']}, 'invest': {'dims': ['flow', 'effect']}}, + 'variables': {'size': {'dims': ['cost_curve']}, 'invest': {'dims': ['cost_of']}}, 'piecewise': { 'invest_curve': { 'along': 'bp', @@ -1542,7 +1510,7 @@ def test_a_walked_row_exists_only_where_its_relation_has_a_row(patch, where): def test_a_block_mask_reaches_a_walk_into_several_columns(): - """The mask is read through the walk into two key columns, which a where string could not parse (#781). + """The mask is read through the walk into a tuple of two members, which a where string could not parse (#781). The block loaded without its `where:`, and with it the load failed on the assertion that what a method assumes is stated in the language. @@ -1550,7 +1518,7 @@ def test_a_block_mask_reaches_a_walk_into_several_columns(): expanded = spec_of(INVESTED).expand() read = 'at(has_cost_curve, by=cost_of[cost_curve])' assert expanded.constraints['invest_curve_cost'].where == read, ( - 'the cost row reads the mask at each flow and effect' + 'the cost row reads the mask at each tuple of a flow and an effect' ) assert expanded.assumptions['invest_curve_cost_complete'].where == read, 'and so does its breakpoint check' assert to_spec(expanded.to_yaml()).program == expanded.program, 'the rows it writes load again' @@ -1586,54 +1554,6 @@ def test_a_mask_over_dims_the_walk_keeps_reaches_the_walked_row_as_written(): assert expanded.constraints['coupling_power'].where == 'season' -def test_a_mask_over_a_dim_the_walk_joins_on_reaches_the_walked_row_as_written(): - """The relation is keyed by flow and snapshot, and `season` tests only `snapshot`, which the walked row keeps. - - The join column was counted with the ones the walk consumes, so this mask - was refused as carrying part of what the walk reads through, and no - rewrite kept it. - """ - expanded = expand_piecewise( - spec_of( - WALKED, - **{ - **_joined(['flow', 'snapshot']), - 'parameters.season': {'dims': ['snapshot'], 'dtype': 'bool'}, - 'piecewise.coupling.where': 'season', - }, - ) - ) - assert expanded.constraints['coupling_power'].where == 'season' - - -@pytest.mark.parametrize( - ('method', 'where'), - [ - pytest.param('sos2', 'at(curved, by=generator_of[generator])', id='sos2'), - pytest.param( - 'incremental', 'at((curved) AND (position(bp) == 0), by=generator_of[generator])', id='incremental' - ), - ], -) -def test_a_mask_over_part_of_what_a_walk_joins_on_reaches_the_walked_row_through_its_relation(method, where): - """The relation is keyed by flow and snapshot, and `curved` tests only `generator`. - - The mask was refused for not testing `snapshot` too, though reading it - through the relation at each flow and snapshot is the row a hand-written - constraint with that where loads to. - """ - expanded = spec_of( - CURVED, - **{ - **_joined(['flow', 'snapshot']), - 'piecewise.coupling.method': method, - }, - ).expand() - assert expanded.constraints['coupling_power'].where == where - assert expanded.assumptions['coupling_power_complete'].where == 'at(curved, by=generator_of[generator])' - assert to_spec(expanded.to_yaml()).program == expanded.program, 'the rows it writes load again' - - @pytest.mark.parametrize( ('model', 'read'), [ @@ -2004,7 +1924,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod 'coupling_power', FIRST, f'bp_power * ({UNIT_STATUS})', - id='a-walked-link-reads-the-read-through-its-own-relation', + id='a-walked-link-reads-the-read-through-its-own-subject', ), pytest.param( INCREMENTAL, @@ -2012,7 +1932,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod 'coupling_power', f'({FIRST}) AND ({UNIT_STATUS})', f'bp_power * ({UNIT_STATUS})', - id='a-walked-link-reads-the-read-through-its-own-relation-where-it-may-be-absent', + id='a-walked-link-reads-the-read-through-its-own-subject-where-it-may-be-absent', ), pytest.param( INCREMENTAL, @@ -2044,7 +1964,7 @@ def test_an_integer_gate_under_incremental_writes_the_rows_a_binary_one_does(mod 'curve_heat', f'({FIRST}) AND (converter[status_entity])', f'bp_heat * (at({RUNNING}, by=hour[snapshot]))', - id='a-walked-link-reads-the-relation-where-as-written', + id='a-walked-link-reads-the-subject-where-as-written', ), ], ) diff --git a/tests/test_pypsa_references.py b/tests/test_pypsa_references.py index 9532b9310..622168c1d 100644 --- a/tests/test_pypsa_references.py +++ b/tests/test_pypsa_references.py @@ -180,7 +180,7 @@ def test_a_patch_keeps_the_pypsa_name_of_what_it_changes(page: str): """A patch rewrites entries of the base; a rewritten name keeps its PyPSA name and its dtype, or it has drifted.""" own = SPECS[page] drifted = [] - for section in ('parameters', 'relations', 'variables', 'constraints'): + for section in ('parameters', 'variables', 'constraints'): theirs, ours = getattr(BASE, section), getattr(own, section) for name in set(theirs) & set(ours): if (theirs[name].description or '').split(' — ')[0] != (ours[name].description or '').split(' — ')[0]: diff --git a/tests/test_renaming.py b/tests/test_renaming.py index a6c741a4e..ec6a79abb 100644 --- a/tests/test_renaming.py +++ b/tests/test_renaming.py @@ -24,8 +24,12 @@ #: One class written over placeholder names: the `unit` dimension and the #: `unit_` entries. Every place a name can stand appears once. UNIT = { - 'dimensions': {'snapshot': {'dtype': 'int', 'ordered': True}, 'unit': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, - 'relations': {'unit_link': {'dims': ['bus', 'unit'], 'missing': 'absent'}}, + 'dimensions': { + 'snapshot': {'dtype': 'int', 'ordered': True}, + 'unit': {'dtype': 'str'}, + 'bus': {'dtype': 'str'}, + 'unit_link': {'over': ['bus', 'unit']}, + }, 'maps': {'unit': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, 'given': {'expressions': {'total_cost': {'dims': []}}}, 'parameters': { @@ -61,11 +65,8 @@ #: The placeholder names, as a class takes them. PLACEHOLDERS = ( - *( - name - for section in ('relations', 'parameters', 'conditions', 'variables', 'expressions') - for name in UNIT[section] - ), + 'unit_link', + *(name for section in ('parameters', 'conditions', 'variables', 'expressions') for name in UNIT[section]), 'unit_ramp', 'unit_bounded', 'unit_twice', @@ -91,12 +92,10 @@ def _as(prefix: str, dim: str) -> dict[str, str]: @pytest.mark.parametrize( ('where', 'expected'), [ - pytest.param(lambda s: list(s['dimensions']), ['bus', 'generator', 'snapshot'], id='dimension'), pytest.param( - lambda s: s['relations']['Generator_link'], - {'dims': ['bus', 'generator'], 'missing': 'absent'}, - id='relation', + lambda s: list(s['dimensions']), ['Generator_link', 'bus', 'generator', 'snapshot'], id='dimension' ), + pytest.param(lambda s: s['dimensions']['Generator_link'], {'over': ['bus', 'generator']}, id='members'), pytest.param(lambda s: s['maps'], {'generator': {'bus': {'dim': 'bus'}, 'bus0': {'dim': 'bus'}}}, id='map'), pytest.param(lambda s: s['parameters']['Generator_cost']['dims'], ['generator', 'snapshot'], id='dims'), pytest.param(lambda s: s['variables']['Generator_p']['where'], 'Generator_on', id='where'), @@ -348,14 +347,12 @@ def test_a_map_the_spec_cannot_take_is_refused(names, message): ('old', 'message'), [ pytest.param('bus0', "'bus0' is also a map of 'line'", id='a-map'), - pytest.param('from_bus', "'from_bus' is also a column of the relation 'corridor'", id='a-relation-column'), ], ) -def test_a_name_that_is_also_a_map_or_a_relation_column_is_refused(old, message): +def test_a_name_that_is_also_a_map_is_refused(old, message): """`line[bus0]` reads a map, and a rename of the parameter `bus0` would change it too.""" spec = { 'dimensions': {'line': {'dtype': 'str'}, 'bus': {'dtype': 'str'}}, - 'relations': {'corridor': {'dims': {'from_bus': 'bus', 'to_bus': 'bus'}}}, 'maps': {'line': {'bus0': {'dim': 'bus'}, 'bus1': {'dim': 'bus'}}}, 'parameters': {'bus0': {'dims': ['bus']}, 'from_bus': {'dims': ['bus']}}, 'variables': {'flow': {'dims': ['line']}}, diff --git a/tests/test_schema.py b/tests/test_schema.py index 31c409289..74b45530d 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -59,7 +59,7 @@ def test_no_definition_refers_only_to_itself(): pytest.param('ObjectiveSpec', 'sense', spec.ObjectiveSense, id='sense'), pytest.param('VariableSpec', 'domain', spec.VariableDomain, id='domain'), pytest.param('VariableSpec', 'missing', Literal['absent'], id='variable-missing'), - pytest.param('RelationSpec', 'missing', spec.RelationMissing, id='relation-missing'), + pytest.param('MapSpec', 'missing', spec.RelationMissing, id='map-missing'), pytest.param('ParameterSpec', 'missing', spec.RelationMissing, id='parameter-missing'), pytest.param('ParameterSpec', 'dtype', spec.ParameterDtype, id='parameter-dtype'), pytest.param('DimensionSpec', 'dtype', spec.DimensionDtype, id='dimension-dtype'), @@ -80,12 +80,12 @@ def test_a_closed_vocabulary_is_published_as_an_enum(entry, field, alias): ('entry', 'default'), [ pytest.param('ParameterSpec', 'refused', id='parameter'), - pytest.param('RelationSpec', 'refused', id='relation'), + pytest.param('MapSpec', 'refused', id='map'), pytest.param('VariableSpec', 'absent', id='variable'), ], ) def test_the_schema_publishes_the_reading_a_file_gets_by_leaving_missing_out(entry, default): - """The parameter and the relation hold `None` until read, and the schema published that `null`, not `refused`.""" + """The parameter and the map hold `None` until read, and the schema published that `null`, not `refused`.""" published = json.loads(schema.PATH.read_text())['$defs'][entry]['properties']['missing'] assert published['default'] == default diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py index e4fd24ace..822bb0e6a 100644 --- a/tests/test_tuple_dimensions.py +++ b/tests/test_tuple_dimensions.py @@ -35,8 +35,8 @@ 'period': {'dtype': 'int', 'ordered': True}, 'connection': {'over': ['unit', 'port']}, 'trade': {'over': ['from_region', 'region']}, + 'active': {'over': ['unit', 'period']}, }, - 'relations': {'active': {'dims': ['unit', 'period'], 'missing': 'absent'}}, 'maps': {'connection': {'bus': {'dim': 'bus'}}}, 'parameters': { 'capacity': {'dims': ['unit']}, @@ -239,18 +239,18 @@ def test_a_tuple_dimension_tests_membership_on_an_entry_over_every_member(patch, assert read(spec).atoms == (RelationDefined('span', ('period', 'unit')),), 'a test of the member tuple' -@pytest.mark.parametrize('fmt', FORMATS) -def test_a_membership_test_prints_the_member_indices(fmt): - """It prints as the bare relation over the same members does, not at an index of the dimension.""" - patch = { - 'variables.built': {'dims': ['unit', 'period'], 'where': 'span'}, - 'variables.kept': {'dims': ['unit', 'period'], 'where': 'active'}, - } - text = typeset(to_spec(varied(MODEL, **_SPAN, **patch)), fmt) - name = r'upright("%s")' if fmt == 'typst' else r'\mathrm{%s}' - line = next(line for line in text.splitlines() if 'built' in line and name % 'span' in line) - condition = line[line.index('forall') :] - assert condition.replace(name % 'span', name % 'active') in text, condition +@pytest.mark.parametrize( + ('fmt', 'printed'), + [ + pytest.param('latex', r'\left( p,\ u \right) \in \mathrm{span}', id='latex'), + pytest.param('markdown', r'\left( p,\ u \right) \in \mathrm{span}', id='markdown'), + pytest.param('typst', 'colon (p, u) in upright("span")', id='typst'), + ], +) +def test_a_membership_test_prints_the_member_indices(fmt, printed): + """It prints the tuple of the frame's member indices, not an index of the dimension.""" + patch = {'variables.built': {'dims': ['unit', 'period'], 'where': 'span'}} + assert printed in typeset(to_spec(varied(MODEL, **_SPAN, **patch)), fmt) def test_a_tuple_dimension_tests_membership_in_a_case(): @@ -271,7 +271,7 @@ def test_a_tuple_dimension_tests_membership_in_a_case(): ) def test_a_tuple_dimension_tests_membership_only_where_the_entry_has_every_member(patch): message = _refusal(**_SPAN, **patch) - assert "where-relation 'span' reads dims" in message, message + assert "where-tuple 'span' reads dims" in message, message assert 'outside the declared dims' in message @@ -303,7 +303,7 @@ def test_a_condition_compares_a_member_label(): def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): - """Rule 9 of #1011: `active` stays a bare relation over (unit, period), and an entry over `connection` reads it with `at`.""" + """Rule 9 of #1011: `active` is a tuple with an ordered member, and an entry over `connection` reads it with `at`.""" built = {'dims': ['connection', 'period'], 'where': 'at(active, by=connection[unit])'} spec = to_spec(varied(MODEL, **{'variables.built': built})) (atom,) = spec.program.variables['built'].where.atoms @@ -362,11 +362,6 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): ("Dimension 'pair' lists 'region' twice under 'over:'", "Declare an alias of 'region'"), id='a-dimension-twice', ), - pytest.param( - {'relations.connection': {'dims': ['unit', 'port']}}, - ("Relation 'connection' collides with the dimension of the same name",), - id='a-declared-relation-of-the-same-name', - ), pytest.param( {'maps.connection.unit': {'dim': 'unit'}}, ("maps: 'connection': map 'unit' has the name of a member of 'connection'", 'connection[unit]'), @@ -558,7 +553,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): ), pytest.param( {'variables.flow.where': 'connection'}, - ("where-relation 'connection' reads dims ['port', 'unit'] outside the declared dims",), + ("where-tuple 'connection' reads dims ['port', 'unit'] outside the declared dims",), id='a-bare-dimension-with-members', ), pytest.param( @@ -606,6 +601,9 @@ def test_a_set_of_type_1_runs_along_a_dimension_with_members(): [ pytest.param({'x': {'dims': ['snapshot']}}, ['connection', 'port', 'unit'], id='nothing-is-over-the-dimension'), pytest.param({'x': {'dims': ['connection']}}, ['snapshot'], id='an-entry-is-over-the-dimension'), + pytest.param( + {'x': {'dims': ['port', 'unit'], 'where': 'connection'}}, ['snapshot'], id='a-where-tests-the-dimension' + ), ], ) def test_a_member_does_not_count_as_a_use(variables, unused): diff --git a/tests/test_validation.py b/tests/test_validation.py index dce69a3d7..bbe7d6f0c 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -86,14 +86,6 @@ class TestValidateExpressions: ("'not_a_param' not found",), id='an-unknown-name-in-a-where-used-to-evaluate-to-false', ), - pytest.param( - { - 'relations.link': {'dims': ['g', 'h'], 'missing': 'absent'}, - 'constraints': {'cap': {'dims': ['g'], 'where': 'lnk', 'expression': 'p <= c'}}, - }, - ("'lnk' not found", "'link']"), - id='a-mistyped-relation-in-a-where-lists-the-relations', - ), ], ) def test_a_bad_entry_is_refused_at_load(self, patch, fragments): @@ -329,8 +321,8 @@ class TestDimensionKwargs: ), pytest.param( 'sum(p, over=generator, by=generatr[zone]) == load', - ("'generatr' is not a relation or a dimension with maps", "Did you mean 'generator'?"), - id='by-relation-typo', + ("'generatr' is not a dimension with maps or members", "Did you mean 'generator'?"), + id='by-subject-typo', ), pytest.param( 'shift(p, along=snapshto, offset=1) == load', @@ -779,7 +771,7 @@ def test_it_resolves(self, mask: str, position: int, by: str | None): ( 'position(snapshot, within=load[snapshot]) == 0', [ - "position(within=load[...]): 'load' is not a relation or a dimension with maps", + "position(within=load[...]): 'load' is not a dimension with maps or members", 'Write within=[]', ], ), @@ -788,7 +780,7 @@ def test_it_resolves(self, mask: str, position: int, by: str | None): ["'period' has no column of its own over 'snapshot'", "Its own columns are ['period']"], ), ], - ids=['a parameter', 'undeclared', 'within= is not a relation', 'within= is over another dim'], + ids=['a parameter', 'undeclared', 'within= is not a subject', 'within= is over another dim'], ) def test_it_refuses(self, mask: str, fragments: list[str]): with pytest.raises(LanguageError) as excinfo: @@ -1031,7 +1023,7 @@ def test_a_shape_the_language_admits(self, where): [ pytest.param( 'at(has_curve, by=cost_of[curve])', - ['effect', 'flow'], + ['cost_of'], {'has_curve', 'cost_of'}, {'has_curve', 'curve'}, id='the-row-that-arrives-is-several-columns', @@ -1053,8 +1045,10 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r """ spec = to_spec( { - 'dimensions': {name: {'dtype': 'str'} for name in ('curve', 'effect', 'flow')}, - 'relations': {'cost_of': {'dims': ['flow', 'effect']}}, + 'dimensions': { + **{name: {'dtype': 'str'} for name in ('curve', 'effect', 'flow')}, + 'cost_of': {'over': ['flow', 'effect']}, + }, 'maps': { 'cost_of': {'curve': {'dim': 'curve'}}, 'curve': {'flow': {'dim': 'flow'}, 'effect': {'dim': 'effect'}}, @@ -1198,8 +1192,8 @@ def test_a_read_names_several_columns_as_an_expression_does(self, where, dims, r ), pytest.param( 'at(r, by=nope[h])', - ("at(by=nope[...]): 'nope' is not a relation or a dimension with maps",), - id='a-read-through-no-relation', + ("at(by=nope[...]): 'nope' is not a dimension with maps or members",), + id='a-read-through-no-subject', ), pytest.param( 'sum_back(flag, along=g, window=2)', @@ -1252,7 +1246,7 @@ def test_a_count_is_undecidable_in_a_case_when(self): def test_an_inequality_between_two_maps_is_undecidable_in_a_case_when(self): """The analysis does not decide an inequality between two maps, whatever their dtype. - Before, the refusal said that two relations have no order, which is false for two int columns. + Before, the refusal said that two maps have no order, which is false for two int columns. """ message = _refusal( **{'dimensions.h': {'dtype': 'int'}, 'maps.g.h2': {'dim': 'h'}}, @@ -1434,42 +1428,9 @@ class TestRulesDecidedWithoutData: ("its expansion writes variable 's_seg'",), id='sos-whose-expansion-collides-with-an-entry', ), - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'dtype': 'str'}}, - ("unknown key 'dtype' in a relation entry. Valid keys: description, dims, missing.",), - id='relation-with-a-dtype-of-its-own', - ), - pytest.param( - {'relations.link': {'dims': ['g']}}, - ( - "Relation 'link' has one column under 'dims:', and a relation needs at least two", - 'To give each g a label, declare a map under maps: g:.', - ), - id='relation-with-one-column', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'z']}}, - ("Relation 'link' references undeclared dimension 'z'",), - id='relation-over-undeclared', - ), - pytest.param( - {'relations.odd': {'dims': {'h': 'g', 'x': 'h'}}}, - ("names column 'h' after dimension 'h', but the column is over 'g'",), - id='relation-column-named-after-a-dimension-it-is-not-over', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'g']}}, - ("names dimension 'g' twice under 'dims:'", 'dims: {g0: g, g1: g}'), - id='relation-naming-a-dim-twice-without-names', - ), - pytest.param( - {'relations.link': {'dims': []}}, - ("Relation 'link' has no column under 'dims:', and a relation needs at least two",), - id='relation-with-no-columns', - ), pytest.param( {'maps.nope': {'h': {'dim': 'h'}}}, - ("maps: 'nope' is neither a dimension nor a relation", 'Subjects: g, h.'), + ("maps: 'nope' is not a dimension", 'Dimensions: g, h.'), id='map-of-no-subject', ), pytest.param( @@ -1477,16 +1438,6 @@ class TestRulesDecidedWithoutData: ("maps: 'g': 'two words' is not a name",), id='map-whose-name-is-not-a-name', ), - pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.link': {'g': {'dim': 'g'}}}, - ("maps: 'link': map 'g' has the name of a column of 'link'", 'Rename the map after what it holds'), - id='map-named-after-a-column-of-its-subject', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.g': {'x': {'dim': 'link'}}}, - ("maps: 'g': map 'x' refers to the relation 'link', and a map gives a label of one dimension",), - id='map-referring-to-a-relation', - ), pytest.param( {'maps.g': {'x': {'dim': 'z'}}}, ("maps: 'g': map 'x' refers to undeclared dimension 'z'",), @@ -1497,11 +1448,6 @@ class TestRulesDecidedWithoutData: ("maps: 'g': map 'h' is named after dimension 'h', but refers to 'g'",), id='map-named-after-another-dimension', ), - pytest.param( - {'relations.pair': {'dims': {'g0': 'g', 'g1': 'g'}}, 'maps.pair': {'x': {'dim': 'h'}}}, - ("maps: 'pair' is a relation with two columns over 'g'", 'Declare the maps on a relation over each'), - id='map-on-a-relation-with-two-columns-over-one-dimension', - ), pytest.param( {'maps.g.h': 'h'}, ('maps.g.h: Input should be a valid dictionary',), @@ -1522,27 +1468,6 @@ class TestRulesDecidedWithoutData: ("sum(by=g[z]) names ['z'], which is no map of 'g'. Name one of its maps, ['h'].",), id='a-map-the-subject-lacks', ), - pytest.param( - { - 'dimensions.z': {}, - 'relations.bare': {'dims': {'a': 'g', 'b': 'g', 'm': 'z'}}, - 'objective': {'expression': 'sum(sum(p, over=g, by=bare[m]))'}, - }, - ( - "over=g names no column of 'bare', so the sum reads nothing through 'bare'", - "the columns over 'g' are ['a', 'b']", - ), - id='a-dimension-two-columns-are-over-is-no-column', - ), - pytest.param( - { - 'dimensions.z': {}, - 'relations.gz': {'dims': ['g', 'z']}, - 'objective': {'expression': 'sum(sum(q, over=h, by=gz[z]))'}, - }, - ("over=h names no column of 'gz', so the sum reads nothing through 'gz'", "its columns are ['g', 'z']"), - id='a-sum-reading-nothing-through-its-relation', - ), pytest.param( { 'dimensions.z': {}, @@ -1606,11 +1531,6 @@ class TestRulesDecidedWithoutData: ('sum(over=g[h]) names maps of a subject, and over= takes bare names. Write over=h',), id='a-selection-in-over-without-by', ), - pytest.param( - {'relations.rel': {'dims': ['g', 'h']}, 'objective': {'expression': 'sum(sum(p, by=rel[h]))'}}, - ('sum() through a relation does not name over=', 'names in over= the columns it sums away'), - id='a-sum-through-a-relation-names-what-leaves', - ), pytest.param( {'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=g))'}}, ('shift(within=g) names the subject and none of its maps. Write within=g[]',), @@ -1630,14 +1550,6 @@ class TestRulesDecidedWithoutData: ), id='a-position-names-the-columns-it-counts-within', ), - pytest.param( - { - 'relations.rel': {'dims': ['g', 'h']}, - 'objective': {'expression': 'sum(at(r, by=rel[h]))'}, - }, - ("'rel' has no map for at() to read. Sum through it instead, or declare a map under maps: rel:.",), - id='at-through-a-relation-with-no-map', - ), pytest.param( {'objective': {'expression': 'sum(sum(q, over=h, by=g[g]))'}}, ( @@ -1647,50 +1559,11 @@ class TestRulesDecidedWithoutData: ), id='a-sum-grouped-by-the-whole-key-is-a-lookup', ), - pytest.param( - { - 'relations.rel': {'dims': ['g', 'h']}, - 'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=0, within=rel[h]))'}, - }, - ("'rel' has no map, so it makes no groups", 'under maps: g:'), - id='a-partition-through-a-relation-with-no-map', - ), - pytest.param( - {'relations.rel': {'dims': ['g', 'h']}, 'variables.q.where': "rel[h] == 'x'"}, - ( - "compares the relation 'rel', which has no map, so its rows hold no label", - "Test the bare name 'rel' for whether a row exists, or declare a map under maps: rel:.", - ), - id='where-compares-a-relation-with-no-map', - ), pytest.param( {'variables.q.where': "g[g] == 'x'"}, ("'g' is a column of 'g' itself. Compare the coordinate, g == ..., or a map.",), id='where-compares-the-subject-column', ), - pytest.param( - { - 'relations.pair': {'dims': {'g0': 'g', 'g1': 'g'}}, - 'variables.q.where': 'pair', - }, - ("'pair' has two columns over one dimension (['g0', 'g1']), so a bare name is ambiguous",), - id='where-bare-name-of-a-relation-with-two-columns-over-one-dim', - ), - pytest.param( - {'relations.h': {'dims': ['g', 'h']}}, - ("Relation 'h' collides with the dimension",), - id='relation-named-after-a-dimension', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'rows': {'g1': 'h1'}}}, - ("unknown key 'rows' in a relation entry", 'Valid keys'), - id='a-relation-declaring-its-rows', - ), - pytest.param( - {'relations.link': {'dim': ['g', 'h']}}, - ("unknown key 'dim' in a relation entry", "Did you mean 'dims'?"), - id='a-relation-with-a-misspelt-key', - ), pytest.param({'variables.p.missing': 0}, ('missing: 0 needs a `where:`',), id='zero-without-a-mask'), pytest.param( {'variables.p.bounds.upper': 'c * 2'}, @@ -1766,11 +1639,6 @@ class TestRulesDecidedWithoutData: ("'g' is a dimension, and a dimension is not a value",), id='a-dimension-as-a-value', ), - pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'objective': {'expression': 'sum(link + p, over=g)'}}, - ("'link' is a relation, and a relation is not a value",), - id='a-relation-as-a-value', - ), pytest.param( {'objective': {'expression': 'sum(shift(p, along=g, offset=1, edge=wrap), over=g)'}}, ("shift(edge=wrap) has no quotes. Write edge='wrap'",), @@ -1813,35 +1681,11 @@ class TestRulesDecidedWithoutData: ("at(by=g[h]) joins on ['h'], which the expression does not carry (dims ['g'])",), id='a-lookup-whose-operand-lacks-the-column-it-joins-on', ), - pytest.param( - { - 'dimensions.z': {}, - 'relations.bare': {'dims': {'k': 'g', 'j0': 'h', 'j1': 'h', 'm': 'z'}}, - 'objective': {'expression': 'sum(sum(q, over=k, by=bare[m]))'}, - }, - ("joins 'bare' on ['h'] through more than one column",), - id='a-call-joining-one-dimension-through-two-columns', - ), - pytest.param( - { - 'dimensions.z': {}, - 'relations.gz': {'dims': ['g', 'z']}, - 'maps.gz': {'h': {'dim': 'h'}}, - 'variables.q.where': 'g[h] != gz[h]', - }, - ("compares maps of subjects over different dimensions ('g' over ['g'], 'gz' over ['g', 'z'])",), - id='where-two-subjects-over-different-dimensions', - ), pytest.param( {'variables.p.where': 'c > q'}, ('compares against variable', 'Test only parameters and dimension coordinates'), id='where-against-a-variable', ), - pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'variables.p.where': 'c > link'}, - ("compares 'c' against 'link', which is no label", 'Compare against a literal'), - id='where-against-a-relation', - ), pytest.param( {'variables.p.where': 'c > h'}, ("compares against dimension 'h'", 'two dimensions cannot be compared'), @@ -1919,15 +1763,6 @@ class TestRulesDecidedWithoutData: ("where references variable 'r'", 'Test only parameters and dimension coordinates'), id='where-a-variable-on-the-left', ), - pytest.param( - { - 'relations.link': {'dims': ['g', 'h']}, - 'maps.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}, - 'variables.q.where': "link == 'x'", - }, - ("'link' compares the relation 'link' itself, and a comparison reads a label", 'link[y]'), - id='where-a-relation-compared-bare', - ), pytest.param( {'variables.p.where': "g[zz] == 'x'"}, ("'g[zz]': 'zz' is no map of 'g'. Maps: h.",), @@ -1982,69 +1817,10 @@ def test_the_rewrite_a_sum_grouped_by_the_whole_key_names_is_one_the_language_ta rewrite = named.group(1).replace('...', operand) _spec(**{'constraints.k': {'dims': ['g'], 'expression': f'{rewrite} >= 0'}}, **patch) - @pytest.mark.parametrize( - ('patch', 'where'), - [ - pytest.param( - {'relations.link': {'dims': ['g', 'h']}, 'maps.link': {'y': {'dim': 'h'}, 'z': {'dim': 'h'}}}, - "link == 'x'", - id='a-relation-with-two-maps-read-bare', - ), - ], - ) - def test_the_map_a_bare_comparison_is_told_to_read_is_one_the_language_takes(self, patch, where): - """A refusal that names a map is holding out a rewrite, so the rewrite has to load. - - Was: the message named the column as `lk.h`, which the where grammar - no longer parses. A map is written `subject[map]`. - """ - message = _refusal(**{'variables.q.where': where}, **patch) - named = re.search(r'Name one of its maps: (\S+)\.$', message) - assert named is not None, f'the refusal holds out no map to read instead: {message}' - _spec(**{'variables.q.where': where.replace('link', named.group(1), 1)}, **patch) - - -_LINKED = {'relations.link': {'dims': ['g', 'h'], 'missing': 'absent'}} - -@pytest.mark.parametrize( - ('patch', 'message'), - [ - pytest.param( - {'variables.x': {'dims': ['link']}}, - "Variable 'x' names the relation 'link', and a relation is not a dimension. Name its dimensions, " - "['g', 'h'], under dims:, and confine the entry with where: link.", - id='dims-of-a-variable', - ), - pytest.param( - {'constraints.c': {'dims': ['link'], 'expression': 'k >= 0'}}, - "Constraint 'c' names the relation 'link', and a relation is not a dimension. Name its dimensions, " - "['g', 'h'].", - id='dims-of-a-constraint', - ), - pytest.param( - {'constraints.c': {'dims': [], 'expression': 'sum(q, over=link) >= 0'}}, - "Constraint 'c': sum(over=link) names the relation 'link', and a relation is not a dimension. Name its " - "dimensions, ['g', 'h'].", - id='over', - ), - pytest.param( - {'constraints.c': {'dims': ['g'], 'expression': 'p <= shift(p, along=link, offset=1)'}}, - "Constraint 'c': shift(along=link) names the relation 'link', and a relation is not a dimension. Name " - "one of its dimensions, ['g', 'h'].", - id='along', - ), - ], -) -def test_a_relation_named_where_a_dimension_belongs_is_refused(patch: dict[str, Any], message: str): - """mathspec told the writer to declare the relation under `dimensions:`, which makes a second, unrelated name.""" - assert message in _refusal(**_LINKED, **patch) - - -#: `p` over the pairs of `g` and `h`, with two relations that list some of them. +#: `p` over the pairs of `g` and `h`, with two tuples that list some of them. ON_A_RELATION: dict[str, Any] = { - 'dimensions': {'g': {}, 'h': {}}, - 'relations': {'pair': {'dims': ['g', 'h'], 'missing': 'absent'}, 'link': {'dims': ['g', 'h'], 'missing': 'absent'}}, + 'dimensions': {'g': {}, 'h': {}, 'pair': {'over': ['g', 'h']}, 'link': {'over': ['g', 'h']}}, 'parameters': {'flag': {'dims': ['g', 'h'], 'dtype': 'bool'}}, 'variables': {'p': {'dims': ['g', 'h'], 'where': 'pair'}}, } @@ -2053,17 +1829,13 @@ def test_a_relation_named_where_a_dimension_belongs_is_refused(patch: dict[str, @pytest.mark.parametrize( 'patch', [ - pytest.param({}, id='the-rows-of-a-relation'), - pytest.param({'variables.p.where': 'pair AND NOT link'}, id='the-rows-of-two-relations'), + pytest.param({}, id='the-tuples-of-a-dimension'), + pytest.param({'variables.p.where': 'pair AND NOT link'}, id='the-tuples-of-two-dimensions'), pytest.param({'variables.p.where': 'flag'}, id='a-test-of-a-value'), pytest.param( {'maps.g.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'g[zone]'}, id='a-label-of-a-map-of-a-dimension', ), - pytest.param( - {'maps.pair.zone': {'dim': 'h', 'missing': 'absent'}, 'variables.p.where': 'pair[zone]'}, - id='a-label-of-a-map-of-the-relation', - ), pytest.param( { 'variables.p': {'dims': ['g', 'h']}, @@ -2073,7 +1845,7 @@ def test_a_relation_named_where_a_dimension_belongs_is_refused(patch: dict[str, ), ], ) -def test_a_where_that_reads_a_relation_or_a_map_loads(patch: dict[str, Any]): +def test_a_where_that_reads_a_tuple_or_a_map_loads(patch: dict[str, Any]): to_spec(varied(ON_A_RELATION, **patch)) @@ -2216,7 +1988,7 @@ def test_an_empty_list_survives_the_round_trip(self): def test_an_empty_section_is_not_written(self): written = to_spec(DISPATCH_MODEL).to_yaml() - assert 'relations' not in written and 'macros' not in written, 'a section declaring nothing says nothing' + assert 'maps' not in written and 'macros' not in written, 'a section declaring nothing says nothing' def test_an_empty_kind_under_given_is_not_written(self): """`given: {parameters: {}}` was written back, though an empty section says nothing.""" @@ -2281,11 +2053,15 @@ def _cased(cases: dict[str, Any] | None = None, **entry: Any) -> dict[str, Any]: #: Every kind of thing a spec holds: an entry, a field two levels down, a list, -#: a section, the given sections, the cases of an expression, a relation's -#: columns written as a mapping, and the maps of a subject. +#: a section, the given sections, the cases of an expression, the members of a +#: dimension, and the maps of a subject. _PROBED = { **DISPATCH_MODEL, - 'relations': {'pair': {'dims': {'from_gen': 'generator', 'to_gen': 'generator'}}}, + 'dimensions': { + **DISPATCH_MODEL['dimensions'], + 'rival': {'alias': 'generator'}, + 'pair': {'over': ['generator', 'rival']}, + }, 'maps': {'generator': {'peer': {'dim': 'generator'}}}, 'expressions': { 'price': { @@ -2308,7 +2084,7 @@ def _cased(cases: dict[str, Any] | None = None, **entry: Any) -> dict[str, Any]: pytest.param(lambda s: s.parameters.pop('cost'), id='an-entry-removed'), pytest.param(lambda s: s.given.parameters.__setitem__('extra', None), id='a-given-entry-added'), pytest.param(lambda s: s.expressions['price'].cases.pop('cheap'), id='a-case-removed'), - pytest.param(lambda s: s.relations['pair'].dims.pop('to_gen'), id='a-relation-column-removed'), + pytest.param(lambda s: s.dimensions['pair'].over.append('snapshot'), id='a-member-appended'), pytest.param(lambda s: s.maps['generator'].pop('peer'), id='a-map-removed'), ], ) @@ -2562,7 +2338,6 @@ class TestAnEntryIsNamed: 'section', [ 'dimensions', - 'relations', 'parameters', 'variables', 'expressions', @@ -2575,7 +2350,6 @@ class TestAnEntryIsNamed: def test_a_name_no_expression_could_write_is_refused(self, section: str, name: str): entries: dict[str, Any] = { 'dimensions': {'dtype': 'str'}, - 'relations': {'dims': ['g', 'h']}, 'parameters': {'dims': ['g']}, 'variables': {'dims': ['g']}, 'expressions': {'expression': 'c'}, @@ -2879,11 +2653,11 @@ def test_a_bare_parameter_whose_answer_needs_the_data_loads(patch): assert spec.program.variables['p'].where is not None, 'the bare name stays a mask' -#: A parameter over the pairs of `g` and `h` that a relation lists, with a fill. +#: A parameter over the pairs of `g` and `h` that a dimension lists, with a fill. _MASKED = { - 'relations.pair': {'dims': ['g', 'h'], 'missing': 'absent'}, + 'dimensions.pair': {'over': ['g', 'h']}, 'maps.pair.kind': {'dim': 'h', 'missing': 'absent'}, - 'parameters.w': {'dims': ['g', 'h'], 'where': 'pair[kind]', 'missing': 1}, + 'parameters.w': {'dims': ['pair'], 'where': 'pair[kind]', 'missing': 1}, } @@ -2891,7 +2665,9 @@ def test_a_parameter_mask_is_part_of_the_program(): """A tool reads where a parameter has coordinates off the program, and the file writes the mask back.""" spec = _spec(**_MASKED) assert spec.program.parameters['w'].where is not None, 'the mask reaches the program' - assert spec.program.parameters['w'].where.names_read == {'pair'}, 'the mask reads the relation and nothing else' + assert spec.program.parameters['w'].where.names_read == {'pair'}, ( + 'the mask reads the map of the tuple and nothing else' + ) assert spec.program.parameters['c'].where is None, 'a parameter with no `where:` has every coordinate' assert to_spec(spec.to_yaml()).program == spec.program, 'the mask survives a round trip through YAML' @@ -2958,14 +2734,18 @@ def test_a_masked_parameter_is_not_read_as_its_fill_outside_the_mask(): 'expressions.level': {'dims': ['g', 'h'], 'cases': cases, 'otherwise': 0}, } assert _spec(**patch).program.expressions['level'] is not None, 'unmasked, a missing row reads 0 and no case holds' - masked = {**patch, **_MASKED, 'parameters.cost': {**patch['parameters.cost'], 'where': 'pair[kind]'}} + masked = { + **_MASKED, + 'parameters.cost': {'dims': ['pair'], 'missing': 0, 'where': 'pair[kind]'}, + 'expressions.level': {'dims': ['pair'], 'cases': cases, 'otherwise': 0}, + } assert "cases 'high' and 'low' both claim the value where cost has no row" in _refusal(**masked) @pytest.mark.parametrize('fmt', FORMATS) def test_the_legend_says_where_a_parameter_has_coordinates(fmt: FormatName): """The mask decides which rows of the data count, so a reader of the legend sees it beside the dims.""" - spec = _spec(**_MASKED, **{'variables.q.bounds': {'upper': 'w'}}) + spec = _spec(**_MASKED, **{'variables.q': {'dims': ['pair'], 'bounds': {'upper': 'w'}}}) row = next(line for line in typeset(spec, fmt).splitlines() if 'only where' in line) assert 'kind' in row, 'the legend row names the map the mask reads' assert row.index('only where') < row.index('where the data has no row'), 'the mask comes before the fill' @@ -2977,20 +2757,6 @@ def test_a_given_parameter_has_no_missing(): assert "unknown key 'missing' in a given parameter entry" in message -@pytest.mark.parametrize( - ('declared', 'read'), - [ - pytest.param({'dims': ['g', 'h']}, 'refused', id='left-out-is-refused'), - pytest.param({'dims': ['g', 'h'], 'missing': 'refused'}, 'refused', id='refused'), - pytest.param({'dims': ['g', 'h'], 'missing': 'absent'}, 'absent', id='absent'), - ], -) -def test_a_relation_says_whether_every_combination_needs_a_row(declared, read): - """A relation takes `missing:`, and reads `refused` where it is left out.""" - spec = to_spec(varied(SMALL_MODEL, **{'relations.pair': declared})) - assert spec.program.relations['pair'].missing == read - - @pytest.mark.parametrize( ('declared', 'partial'), [ @@ -3009,26 +2775,6 @@ def test_a_map_says_whether_every_row_needs_a_label(declared, partial): @pytest.mark.parametrize( ('patch', 'fragment'), [ - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'missing': 0}}, - 'missing: 0 on a relation, which takes refused or absent', - id='a-number-on-a-relation', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'missing': 'h1'}}, - 'missing: h1 on a relation', - id='a-label-on-a-relation', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'missing': True}}, - 'missing: true on a relation', - id='a-flag-on-a-relation', - ), - pytest.param( - {'relations.link': {'dims': ['g', 'h'], 'missing': None}}, - 'missing: null on a relation says nothing', - id='null-on-a-relation', - ), pytest.param( {'maps.g.h': {'dim': 'h', 'missing': 0}}, 'maps.g.h.missing: missing: 0 on a map, which takes refused or absent', @@ -3618,3 +3364,9 @@ def test_the_rewrite_of_a_shared_member_loads(): rewrite = {'dims': ['connection', 'bus'], 'where': 'at(site, by=connection[unit])'} spec = to_spec(varied(_SHARED_MEMBER, **{'variables.pair': rewrite})) assert spec.program.variables['pair'].where.dims == ('bus', 'connection'), 'the where stays on the frame' + + +def test_a_relations_section_is_refused_by_the_schema(): + """A set of tuples is a dimension with `over:`, so the file has no `relations:` section to declare one in.""" + message = _refusal(**{'relations.pair': {'dims': ['g', 'h']}}) + assert "unknown key 'relations' in the top level of the file" in message, message diff --git a/tests/typesetting/golden/latex.out b/tests/typesetting/golden/latex.out index f3a88f959..7f96c8521 100644 --- a/tests/typesetting/golden/latex.out +++ b/tests/typesetting/golden/latex.out @@ -10,64 +10,66 @@ \paragraph{Sets} \begin{description} \item[{$\mathcal{B}$}] index $b$ --- \texttt{bp} -\item[{$\mathcal{U}$}] index $u$ --- \texttt{bus} with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}$, \texttt{connection} is \texttt{absent} where the data has no row, \texttt{bus[area]} is \texttt{absent} where the data gives no label -\item[{$\mathcal{C}$}] index $c$ --- \texttt{corridor}, $\mathcal{C} = \mathcal{U} \times \mathcal{U}$ +\item[{$\mathcal{U}$}] index $u$ --- \texttt{bus} with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{E} \to \mathcal{U}$, \texttt{bus[area]} is \texttt{absent} where the data gives no label +\item[{$\mathcal{C}$}] index $c$ --- \texttt{connection}, $\mathcal{C} \subseteq \mathcal{U} \times \mathcal{E}$ +\item[{$\mathcal{O}$}] index $o$ --- \texttt{corridor}, $\mathcal{O} = \mathcal{U} \times \mathcal{U}$ \item[{$\mathcal{U}$}] index $u'$ --- \texttt{from\_bus}, an alias of \texttt{bus} -\item[{$\mathcal{G}$}] index $g$ --- \texttt{generator} with $\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}$, \texttt{connection} is \texttt{absent} where the data has no row +\item[{$\mathcal{G}$}] index $g$ --- \texttt{gen\_zone}, $\mathcal{G} = \mathcal{E} \times \mathcal{T}$ with $\mathrm{zone}: \mathcal{G} \to \mathcal{Z}$ +\item[{$\mathcal{E}$}] index $e$ --- \texttt{generator} with $\mathrm{bus}: \mathcal{E} \to \mathcal{U},\ \mathrm{technology}: \mathcal{E} \to \mathcal{H}$ \item[{$\mathcal{S}$}] index $s$ --- \texttt{season} with $\mathrm{season}: \mathcal{T} \to \mathcal{S}$ -\item[{$\mathcal{I}$}] index $i$ --- \texttt{site}, $\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}$ -\item[{$\mathcal{T}$}] index $t$ --- \texttt{snapshot} (\texttt{int} coordinates) with $\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}$ -\item[{$\mathcal{E}$}] index $e$ --- \texttt{technology} with $\mathrm{technology}: \mathcal{G} \to \mathcal{E}$ -\item[{$\mathcal{Z}$}] index $z$ --- \texttt{zone} (labels \texttt{north}, \texttt{south}) with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}$, \texttt{bus[area]} is \texttt{absent} where the data gives no label +\item[{$\mathcal{I}$}] index $i$ --- \texttt{site}, $\mathcal{I} \subseteq \mathcal{U} \times \mathcal{E}$ +\item[{$\mathcal{T}$}] index $t$ --- \texttt{snapshot} (\texttt{int} coordinates) with $\mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}$ +\item[{$\mathcal{H}$}] index $h$ --- \texttt{technology} with $\mathrm{technology}: \mathcal{E} \to \mathcal{H}$ +\item[{$\mathcal{Z}$}] index $z$ --- \texttt{zone} (labels \texttt{north}, \texttt{south}) with $\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{G} \to \mathcal{Z}$, \texttt{bus[area]} is \texttt{absent} where the data gives no label \end{description} \paragraph{Parameters} \begin{description} \item[{$\mathrm{area\_weight}$}] \texttt{area\_weight} over $\mathcal{U}$, only where $\mathrm{area}(u) \text{ is defined}$ -\item[{$\mathrm{bp\_heat}$}] \texttt{bp\_heat} over $\mathcal{B} \times \mathcal{G}$ -\item[{$\mathrm{bp\_run}$}] \texttt{bp\_run} over $\mathcal{B} \times \mathcal{G}$ -\item[{$\mathrm{bp\_x}$}] \texttt{bp\_x} over $\mathcal{B} \times \mathcal{G}$, $0$ where the data has no row -\item[{$\mathrm{bp\_y}$}] \texttt{bp\_y} over $\mathcal{B} \times \mathcal{G}$, $0$ where the data has no row +\item[{$\mathrm{bp\_heat}$}] \texttt{bp\_heat} over $\mathcal{B} \times \mathcal{E}$ +\item[{$\mathrm{bp\_run}$}] \texttt{bp\_run} over $\mathcal{B} \times \mathcal{E}$ +\item[{$\mathrm{bp\_x}$}] \texttt{bp\_x} over $\mathcal{B} \times \mathcal{E}$, $0$ where the data has no row +\item[{$\mathrm{bp\_y}$}] \texttt{bp\_y} over $\mathcal{B} \times \mathcal{E}$, $0$ where the data has no row \item[{$\mathrm{budget}$}] \texttt{budget} (scalar) -\item[{$\mathrm{corridor\_cap}$}] \texttt{corridor\_cap} over $\mathcal{C}$ -\item[{$\mathrm{cost}$}] \texttt{cost} over $\mathcal{G}$, $0$ where the data has no row -\item[{$\mathrm{eta}$}] \texttt{eta} over $\mathcal{G}$ +\item[{$\mathrm{corridor\_cap}$}] \texttt{corridor\_cap} over $\mathcal{O}$ +\item[{$\mathrm{cost}$}] \texttt{cost} over $\mathcal{E}$, $0$ where the data has no row +\item[{$\mathrm{eta}$}] \texttt{eta} over $\mathcal{E}$ \item[{$\mathrm{growth}$}] \texttt{growth} (scalar) -\item[{$\mathrm{is\_flexible}$}] \texttt{is\_flexible} over $\mathcal{G}$, \texttt{false} where the data has no row -\item[{$\mathrm{lead}$}] \texttt{lead} over $\mathcal{G}$ -\item[{$\mathrm{link\_eff}$}] \texttt{link\_eff} over $\mathcal{U} \times \mathcal{G}$, only where $\left( u,\ g \right) \in \mathrm{connection}$, $1$ where the data has no row +\item[{$\mathrm{is\_flexible}$}] \texttt{is\_flexible} over $\mathcal{E}$, \texttt{false} where the data has no row +\item[{$\mathrm{lead}$}] \texttt{lead} over $\mathcal{E}$ +\item[{$\mathrm{link\_eff}$}] \texttt{link\_eff} over $\mathcal{U} \times \mathcal{E}$, only where $\left( u,\ e \right) \in \mathrm{connection}$, $1$ where the data has no row \item[{$\mathrm{load}$}] \texttt{load} over $\mathcal{U} \times \mathcal{T}$ -\item[{$\mathrm{min\_up}$}] \texttt{min\_up} over $\mathcal{G}$ -\item[{$\mathrm{p}^{\mathrm{max}}$}] \texttt{p\_max} over $\mathcal{G}$, $\infty$ where the data has no row -\item[{$\mathrm{p}^{\mathrm{min}}$}] \texttt{p\_min} over $\mathcal{G}$ +\item[{$\mathrm{min\_up}$}] \texttt{min\_up} over $\mathcal{E}$ +\item[{$\mathrm{p}^{\mathrm{max}}$}] \texttt{p\_max} over $\mathcal{E}$, $\infty$ where the data has no row +\item[{$\mathrm{p}^{\mathrm{min}}$}] \texttt{p\_min} over $\mathcal{E}$ \item[{$\mathrm{susceptance}$}] \texttt{susceptance} over $\mathcal{U} \times \mathcal{U}$, $0$ where the data has no row -\item[{$\mathrm{tech\_cap}$}] \texttt{tech\_cap} over $\mathcal{U} \times \mathcal{E}$, \texttt{absent} where the data has no row +\item[{$\mathrm{tech\_cap}$}] \texttt{tech\_cap} over $\mathcal{U} \times \mathcal{H}$, \texttt{absent} where the data has no row \item[{$\mathrm{zone\_cap}$}] \texttt{zone\_cap} over $\mathcal{Z}$ \end{description} \paragraph{Conditions} \begin{description} -\item[{$\mathrm{dispatchable}$}] \texttt{dispatchable} over $\mathcal{G}$ --- a unit that dispatches and cannot be turned down -\item[{$\mathrm{priced\_dispatch}$}] \texttt{priced\_dispatch} over $\mathcal{G}$ +\item[{$\mathrm{dispatchable}$}] \texttt{dispatchable} over $\mathcal{E}$ --- a unit that dispatches and cannot be turned down +\item[{$\mathrm{priced\_dispatch}$}] \texttt{priced\_dispatch} over $\mathcal{E}$ \end{description} \paragraph{Variables} \begin{description} -\item[{$\mathit{fuel}$}] \texttt{fuel} over $\mathcal{G} \times \mathcal{T}$ +\item[{$\mathit{fuel}$}] \texttt{fuel} over $\mathcal{E} \times \mathcal{T}$ \item[{$\mathit{headroom}$}] \texttt{headroom} (scalar), $0$ where the mask leaves it out -\item[{$\mathit{heat}$}] \texttt{heat} over $\mathcal{G} \times \mathcal{T}$ -\item[{$\mathit{on}$}] \texttt{on} over $\mathcal{G} \times \mathcal{T}$ -\item[{$\mathit{op\_cost}$}] \texttt{op\_cost} over $\mathcal{G} \times \mathcal{T}$ -\item[{$p$}] \texttt{p} over $\mathcal{G} \times \mathcal{T}$ +\item[{$\mathit{heat}$}] \texttt{heat} over $\mathcal{E} \times \mathcal{T}$ +\item[{$\mathit{on}$}] \texttt{on} over $\mathcal{E} \times \mathcal{T}$ +\item[{$\mathit{op\_cost}$}] \texttt{op\_cost} over $\mathcal{E} \times \mathcal{T}$ +\item[{$p$}] \texttt{p} over $\mathcal{E} \times \mathcal{T}$ \item[{$\mathit{reserve}$}] \texttt{reserve} (scalar) \item[{$\mathit{site\_out}$}] \texttt{site\_out} over $\mathcal{I} \times \mathcal{T}$ \item[{$\mathit{slack}$}] \texttt{slack} over $\mathcal{T}$ -\item[{$\mathit{spare}$}] \texttt{spare} over $\mathcal{G}$ +\item[{$\mathit{spare}$}] \texttt{spare} over $\mathcal{E}$ \item[{$\mathit{spill}$}] \texttt{spill} over $\mathcal{T}$ \item[{$\theta$}] \texttt{theta} over $\mathcal{U}$ -\item[{$\mathit{units}$}] \texttt{units} over $\mathcal{G}$ -\item[{$\mathit{warm}$}] \texttt{warm} over $\mathcal{G} \times \mathcal{T}$ -\item[{$\mathit{weight}$}] \texttt{weight} over $\mathcal{G} \times \mathcal{T}$ +\item[{$\mathit{units}$}] \texttt{units} over $\mathcal{E}$ +\item[{$\mathit{warm}$}] \texttt{warm} over $\mathcal{E} \times \mathcal{T}$ +\item[{$\mathit{weight}$}] \texttt{weight} over $\mathcal{E} \times \mathcal{T}$ \end{description} \paragraph{Definitions} @@ -75,10 +77,10 @@ \item[{$\mathit{lcoe}$}] \texttt{lcoe} (scalar) \item[{$\mathit{marginal\_price}$}] \texttt{marginal\_price} over $\mathcal{U} \times \mathcal{T}$ \item[{$\mathit{net}$}] \texttt{net} over $\mathcal{T}$ --- what a snapshot spills, less what it lacks -\item[{$\mathrm{rating}$}] \texttt{rating} over $\mathcal{G} \times \mathcal{T}$ +\item[{$\mathrm{rating}$}] \texttt{rating} over $\mathcal{E} \times \mathcal{T}$ \item[{$\mathit{spend}$}] \texttt{spend} over $\mathcal{T}$ --- what a snapshot's dispatch costs -\item[{$\mathrm{spend}^{\mathrm{cap}}$}] \texttt{spend\_cap} over $\mathcal{G}$ -\item[{$\mathrm{startup\_cost}$}] \texttt{startup\_cost} over $\mathcal{G} \times \mathcal{T}$ --- what starting a unit in this snapshot costs, which the horizon's edge changes +\item[{$\mathrm{spend}^{\mathrm{cap}}$}] \texttt{spend\_cap} over $\mathcal{E}$ +\item[{$\mathrm{startup\_cost}$}] \texttt{startup\_cost} over $\mathcal{E} \times \mathcal{T}$ --- what starting a unit in this snapshot costs, which the horizon's edge changes \end{description} \paragraph{Notation} @@ -93,138 +95,138 @@ \paragraph{Conditions} \begin{align} -\text{dispatchable} && \mathrm{dispatchable}_{g} & \iff \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} && \forall\, g \in \mathcal{G} \\ -\text{priced\_dispatch} && \mathrm{priced\_dispatch}_{g} & \iff \mathrm{dispatchable}_{g} \wedge \mathrm{spend}^{\mathrm{cap}}_{g} > 0 && \forall\, g \in \mathcal{G} +\text{dispatchable} && \mathrm{dispatchable}_{e} & \iff \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} && \forall\, e \in \mathcal{E} \\ +\text{priced\_dispatch} && \mathrm{priced\_dispatch}_{e} & \iff \mathrm{dispatchable}_{e} \wedge \mathrm{spend}^{\mathrm{cap}}_{e} > 0 && \forall\, e \in \mathcal{E} \end{align} \paragraph{Variable domains} \begin{align} -\text{fuel} && \mathit{fuel}_{g,t} & \ge 0 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ +\text{fuel} && \mathit{fuel}_{e,t} & \ge 0 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ \text{headroom} && \mathit{headroom} & \ge 0 && \text{where } \mathrm{budget} \text{ is defined} \\ -\text{heat} && \mathit{heat}_{g,t} & \ge 0 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{on} && \mathit{on}_{g,t} & \in \{0, 1\} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{op\_cost} && \mathit{op\_cost}_{g,t} & \ge 0 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{p} && \mathrm{p}^{\mathrm{min}}_{g} \le p_{g,t} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \vee \mathrm{p}^{\mathrm{min}}_{g} > 0 \\ +\text{heat} && \mathit{heat}_{e,t} & \ge 0 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{on} && \mathit{on}_{e,t} & \in \{0, 1\} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{op\_cost} && \mathit{op\_cost}_{e,t} & \ge 0 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{p} && \mathrm{p}^{\mathrm{min}}_{e} \le p_{e,t} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} \vee \mathrm{p}^{\mathrm{min}}_{e} > 0 \\ \text{reserve} && \mathit{reserve} & \ge 0 \\ \text{site\_out} && \mathit{site\_out}_{i,t} & \ge 0 && \forall\, i \in \mathcal{I},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{\mathrm{generator}(i)} \\ \text{slack} && \mathit{slack}_{t} & \le 100 && \forall\, t \in \mathcal{T} \\ -\text{spare} && \mathit{spare}_{g} & \in \mathbb{Z} && \forall\, g \in \mathcal{G} \\ +\text{spare} && \mathit{spare}_{e} & \in \mathbb{Z} && \forall\, e \in \mathcal{E} \\ \text{spill} && \mathit{spill}_{t} & \ge 0 && \forall\, t \in \mathcal{T} \\ \text{theta} && \theta_{u} & \in \mathbb{R} && \forall\, u \in \mathcal{U} \\ -\text{units} && 0 \le \mathit{units}_{g} & \le 10, \mathit{units}_{g} \in \mathbb{Z} && \forall\, g \in \mathcal{G} \\ -\text{warm} && \mathit{warm}_{g,t} & \in \{0, 1\} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{g} \\ -\text{weight} && 0 \le \mathit{weight}_{g,t} & \le 1 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\text{units} && 0 \le \mathit{units}_{e} & \le 10, \mathit{units}_{e} \in \mathbb{Z} && \forall\, e \in \mathcal{E} \\ +\text{warm} && \mathit{warm}_{e,t} & \in \{0, 1\} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{e} \\ +\text{weight} && 0 \le \mathit{weight}_{e,t} & \le 1 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \end{align} \paragraph{Definitions} \begin{align} -\text{lcoe} && \mathit{lcoe} & = \frac{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g}}{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t}} \\ +\text{lcoe} && \mathit{lcoe} & = \frac{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e}}{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t}} \\ \text{marginal\_price} && \mathit{marginal\_price}_{u,t} & = \lambda_{\mathrm{balance},u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ \text{net} && \mathit{net}_{t} & = -\mathit{spill}_{t} + \mathit{slack}_{t} && \forall\, t \in \mathcal{T} \\ -\text{rating} && \mathrm{rating}_{g,t} & = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{spend} && \mathit{spend}_{t} & = \sum_{g \in \mathcal{G}} p_{g,t} \cdot \mathrm{cost}_{g} && \forall\, t \in \mathcal{T} \\ -\text{spend\_cap} && \mathrm{spend}^{\mathrm{cap}}_{g} & = \mathrm{cost}_{g} \cdot 2 && \forall\, g \in \mathcal{G} \\ -\text{startup\_cost} && \mathrm{startup\_cost}_{g,t} & = \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}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\text{rating} && \mathrm{rating}_{e,t} & = \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{spend} && \mathit{spend}_{t} & = \sum_{e \in \mathcal{E}} p_{e,t} \cdot \mathrm{cost}_{e} && \forall\, t \in \mathcal{T} \\ +\text{spend\_cap} && \mathrm{spend}^{\mathrm{cap}}_{e} & = \mathrm{cost}_{e} \cdot 2 && \forall\, e \in \mathcal{E} \\ +\text{startup\_cost} && \mathrm{startup\_cost}_{e,t} & = \begin{cases} \mathrm{cost}_{e} & \text{if } \mathrm{pos}(t) = 0 \\ \mathrm{cost}_{e} \cdot 2 & \text{if } \mathrm{pos}(t) > 0 \wedge \mathrm{season}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \end{align} \paragraph{Objective} \begin{align} - && \max & \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} \cdot \mathrm{growth}^{\mathrm{lead}_{g}} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{g}} \right)^{2} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{p}^{\mathrm{max}}_{g} - \mathit{reserve} - \mathit{headroom} + && \max & \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} \cdot \mathrm{growth}^{\mathrm{lead}_{e}} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{e}} \right)^{2} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{p}^{\mathrm{max}}_{e} - \mathit{reserve} - \mathit{headroom} \end{align} \paragraph{Subject to} \begin{align} -\text{ahead} && p_{g,t} & \le p_{g,t \oplus 1} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ +\text{ahead} && p_{e,t} & \le p_{e,t \oplus 1} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ \text{always} && \mathit{spill}_{t} & \ge 0 && \forall\, t \in \mathcal{T} \\ -\text{arithmetic} && \sum_{g \in \mathcal{G}} \left( \frac{p_{g,t}}{2} - \mathrm{cost}_{g} + 10^{-5} \cdot p_{g,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{g} + 0.5 \cdot p_{g,t} \right) & \ge -\left( \sum_{g \in \mathcal{G}} p_{g,t} \right) \cdot \left( -3 \right) && \forall\, t \in \mathcal{T} \\ -\text{balance} && \sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{spill}_{t} - \mathit{slack}_{t} & = \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ +\text{arithmetic} && \sum_{e \in \mathcal{E}} \left( \frac{p_{e,t}}{2} - \mathrm{cost}_{e} + 10^{-5} \cdot p_{e,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{e} + 0.5 \cdot p_{e,t} \right) & \ge -\left( \sum_{e \in \mathcal{E}} p_{e,t} \right) \cdot \left( -3 \right) && \forall\, t \in \mathcal{T} \\ +\text{balance} && \sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{spill}_{t} - \mathit{slack}_{t} & = \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ \text{budgeted} && \mathit{spend}_{t} & \le \mathrm{budget} && \forall\, t \in \mathcal{T} \\ -\text{capped} && p_{g,t} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{g} > 0 \vee \neg \mathrm{is\_flexible}_{g} \\ +\text{capped} && p_{e,t} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{e} > 0 \vee \neg \mathrm{is\_flexible}_{e} \\ \text{ceiling} && \theta_{u} & \le \infty && \forall\, u \in \mathcal{U} \\ -\text{composed} && p_{g,t - 2} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{connected} && p_{g,t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \left( u,\ g \right) \in \mathrm{connection} \\ -\text{counted} && \theta_{u} & \le \mathrm{budget} && \forall\, u \in \mathcal{U} \,:\, \lvert \{ e \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e} > 0 \} \rvert \ge 2 \\ -\text{counted\_here} && \theta_{u} & \le \mathrm{tech\_cap}_{u,e} && \forall\, u \in \mathcal{U},\ e \in \mathcal{E} \,:\, \lvert \{ e' \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e'} > 0 \} \rvert \ge 2 \\ -\text{covered} && \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} & \le \mathrm{budget} && \text{where } \sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} \ge \mathrm{budget} \\ -\text{crossed} && p_{g + 1,t \ominus 1} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{edges} && p_{g,t \boxminus_{0} 1} & \le p_{g,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{efficiency} && p_{g,t} & \le \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ +\text{composed} && p_{e,t - 2} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{connected} && p_{e,t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \left( u,\ e \right) \in \mathrm{connection} \\ +\text{counted} && \theta_{u} & \le \mathrm{budget} && \forall\, u \in \mathcal{U} \,:\, \lvert \{ h \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h} > 0 \} \rvert \ge 2 \\ +\text{counted\_here} && \theta_{u} & \le \mathrm{tech\_cap}_{u,h} && \forall\, u \in \mathcal{U},\ h \in \mathcal{H} \,:\, \lvert \{ h' \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h'} > 0 \} \rvert \ge 2 \\ +\text{covered} && \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} & \le \mathrm{budget} && \text{where } \sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} \ge \mathrm{budget} \\ +\text{crossed} && p_{e + 1,t \ominus 1} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{edges} && p_{e,t \boxminus_{0} 1} & \le p_{e,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{efficiency} && p_{e,t} & \le \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ \text{exchanged} && \theta_{u} & = \sum_{u' \in \mathcal{U} \,:\, u' = u} \sum_{u'' \in \mathcal{U}} \mathrm{susceptance}_{u'',u'} && \forall\, u \in \mathcal{U} \\ -\text{first} && \mathit{on}_{g,t} & = 1 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 \\ +\text{first} && \mathit{on}_{e,t} & = 1 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 \\ \text{flow\_angle} && \theta_{u} & = \sum_{u' \in \mathcal{U}} \mathrm{susceptance}_{u,u'} \cdot \theta_{u'} && \forall\, u \in \mathcal{U} \\ -\text{grouped\_once} && \sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u \wedge \mathrm{technology}(g) = e} p_{g,t} & \le \mathrm{tech\_cap}_{u,e} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ e \in \mathcal{E} \\ -\text{held\_in\_season} && p_{g,t} & \le p_{g,t \boxminus_{0}^{\mathrm{season}(t)} 1} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{history} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{g,t'} & \le \mathit{units}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{in\_season} && p_{g,t} & \le p_{g,t \ominus^{\mathrm{season}(t)} 1} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{last} && \mathit{on}_{g,t} & = 0 && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 \\ -\text{lead\_time} && p_{g,t \boxminus_{0} \mathrm{lead}} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{looked\_up\_once} && \mathit{units}_{g} & \le \mathrm{tech\_cap}_{\mathrm{bus}(g),\mathrm{technology}(g)} && \forall\, g \in \mathcal{G} \\ +\text{grouped\_once} && \sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u \wedge \mathrm{technology}(e) = h} p_{e,t} & \le \mathrm{tech\_cap}_{u,h} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ h \in \mathcal{H} \\ +\text{held\_in\_season} && p_{e,t} & \le p_{e,t \boxminus_{0}^{\mathrm{season}(t)} 1} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{history} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{e,t'} & \le \mathit{units}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{in\_season} && p_{e,t} & \le p_{e,t \ominus^{\mathrm{season}(t)} 1} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{last} && \mathit{on}_{e,t} & = 0 && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 \\ +\text{lead\_time} && p_{e,t \boxminus_{0} \mathrm{lead}} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{looked\_up\_once} && \mathit{units}_{e} & \le \mathrm{tech\_cap}_{\mathrm{bus}(e),\mathrm{technology}(e)} && \forall\, e \in \mathcal{E} \\ \text{lookup} && \mathit{spill}_{t} & \le \mathrm{zone\_cap}_{\mathrm{zone}(u)} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ -\text{margin} && p_{g,t} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} - \mathrm{p}^{\mathrm{min}}_{g} > \frac{\mathrm{cost}_{g}}{2} \\ -\text{masked} && p_{g,t} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{g} \wedge \mathrm{pos}(t) > 0 \\ -\text{netted} && \sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{net}_{t} & = \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ +\text{margin} && p_{e,t} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} - \mathrm{p}^{\mathrm{min}}_{e} > \frac{\mathrm{cost}_{e}}{2} \\ +\text{masked} && p_{e,t} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{e} \wedge \mathrm{pos}(t) > 0 \\ +\text{netted} && \sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{net}_{t} & = \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ \text{never} && \mathit{slack}_{t} & \ge 0 && \forall\, t \in \mathcal{T} \,:\, \bot \\ \text{northern} && \mathit{slack}_{t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{zone}(u) = \text{'}\mathrm{north}\text{'} \wedge \mathrm{zone}(u) \neq \mathrm{area}(u) \wedge \mathrm{area}(u) \text{ is defined} \\ -\text{ramp} && p_{g,t} - p_{g,t \ominus 1} & \le p_{g,t - 1} + \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ +\text{ramp} && p_{e,t} - p_{e,t \ominus 1} & \le p_{e,t - 1} + \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ \text{ramped} && \mathit{slack}_{t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} - \mathrm{load}_{u,t \boxminus_{0} 1} \le \mathrm{zone\_cap}_{\mathrm{zone}(u)} \wedge \mathrm{pos}(t) > 0 \\ \text{redundant} && \mathit{spill}_{t} & \ge 0 && \forall\, t \in \mathcal{T} \,:\, \mathit{spill}_{t} \text{ exists} \\ -\text{relational} && \sum_{g \in \mathcal{G} \,:\, \left( u,\ g \right) \in \mathrm{connection}} p_{g,t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ +\text{relational} && \sum_{c \in \mathcal{C} \,:\, \mathrm{bus}(c) = u} p_{\mathrm{generator}(c),t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \\ \text{representative} && \sum_{t' \in \mathcal{T} \,:\, \mathrm{rep}(t') = t} \mathit{spill}_{t'} & \le \mathit{spill}_{\mathrm{rep}(t)} && \forall\, t \in \mathcal{T} \\ \text{run\_start} && \mathit{slack}_{t} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} \wedge \neg \left( \mathrm{load}_{u,t - 1} \text{ is defined} \right) \\ \text{running} && \theta_{u} & \le \mathrm{load}_{u,t} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \theta_{u} \text{ exists} \wedge t \ge 3 \\ -\text{scalar} && \mathit{units}_{g} & \le \mathrm{budget} && \forall\, g \in \mathcal{G} \,:\, \mathrm{cost}_{g} \text{ is defined} \\ -\text{seasonal\_window} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{g,t'} & \le \mathit{units}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{starts} && p_{g,t} & \le \mathrm{startup\_cost}_{g,t} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{total} && \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} & \le \mathrm{budget} \\ -\text{uncomposed} && p_{g,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{under\_rating} && p_{g,t} & \le \mathrm{rating}_{g,t} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{window} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{g,t'} & \le \mathit{units}_{g} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{within\_bus} && \mathit{units}_{g} & \le \mathit{units}_{g \boxminus_{0}^{\mathrm{bus}(g)} 1} && \forall\, g \in \mathcal{G} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(g),\ \mathrm{technology}(g) \right)}(g) = 0 \\ -\text{zonal} && \sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} & \le \mathrm{zone\_cap}_{z} && \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} \\ -\text{zonal\_history} && \sum_{t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} & \le \mathrm{zone\_cap}_{z} && \forall\, g \in \mathcal{G},\ z \in \mathcal{Z} \\ -\text{zonal\_lookup} && p_{g,t} & \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = \text{'}\mathrm{north}\text{'} \wedge \mathrm{pos}_{\mathrm{zone}(g,\ t)}(g) = 0 \\ -\text{zonal\_membership} && \sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}} \mathit{units}_{g} & \le \mathrm{budget} && \forall\, t \in \mathcal{T} \\ +\text{scalar} && \mathit{units}_{e} & \le \mathrm{budget} && \forall\, e \in \mathcal{E} \,:\, \mathrm{cost}_{e} \text{ is defined} \\ +\text{seasonal\_window} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{e,t'} & \le \mathit{units}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{starts} && p_{e,t} & \le \mathrm{startup\_cost}_{e,t} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{total} && \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} & \le \mathrm{budget} \\ +\text{uncomposed} && p_{e,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{under\_rating} && p_{e,t} & \le \mathrm{rating}_{e,t} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{window} && \sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{e,t'} & \le \mathit{units}_{e} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{within\_bus} && \mathit{units}_{e} & \le \mathit{units}_{e \boxminus_{0}^{\mathrm{bus}(e)} 1} && \forall\, e \in \mathcal{E} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(e),\ \mathrm{technology}(e) \right)}(e) = 0 \\ +\text{zonal} && \sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} & \le \mathrm{zone\_cap}_{z} && \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} \\ +\text{zonal\_history} && \sum_{g \in \mathcal{G} \,:\, \mathrm{generator}(g) = e \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} & \le \mathrm{zone\_cap}_{z} && \forall\, e \in \mathcal{E},\ z \in \mathcal{Z} \\ +\text{zonal\_lookup} && p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} & \le \mathit{spill}_{\mathrm{snapshot}(g)} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g)} && \forall\, g \in \mathcal{G} \,:\, \mathrm{zone}(g) = \text{'}\mathrm{north}\text{'} \\ +\text{zonal\_membership} && \sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t} \mathit{units}_{\mathrm{generator}(g)} & \le \mathrm{budget} && \forall\, t \in \mathcal{T} \\ \text{zoned} && \theta_{u} & \le \mathrm{budget} && \forall\, u \in \mathcal{U} \,:\, \mathrm{zone\_cap}_{\mathrm{zone}(u)} \text{ is defined} \\ -\text{adjacent} && \left( \mathit{weight}_{g,t} \right)_{g \in \mathcal{G}} & \in \mathrm{SOS}2 && \forall\, t \in \mathcal{T} \\ -\text{bus\_curve} && \left( p_{g,t} \right)_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} & \in \mathrm{pwl}_{b \in \mathcal{B}}(\left( \mathrm{bp\_x}_{b,g} \right)_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u}) && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} \\ -\text{chp\_curve} && \left( p_{g,t},\ \mathit{fuel}_{g,t},\ \mathit{heat}_{g,t} \right) & \in \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g},\ \mathrm{bp\_heat}_{b,g}) + \{0\} \times \mathbb{R}_{\ge 0} \times \mathbb{R}_{\le 0} && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{cost\_curve} && \mathit{op\_cost}_{g,t} & \ge \begin{cases} \mathit{warm}_{g,t} & \text{if } \mathrm{is\_flexible}_{g} \\ 1 & \text{otherwise} \end{cases} \cdot \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g})(p_{g,t}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{fuel\_curve} && \left( p_{g,t},\ \mathit{fuel}_{g,t},\ \mathit{heat}_{g,t} \right) & \in \mathit{on}_{g,t} \cdot \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g},\ \mathrm{bp\_heat}_{b,g}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{hull\_curve} && \left( p_{g,t},\ \mathit{fuel}_{g,t} \right) & \in \mathrm{conv}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_heat}_{b,g}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{lp\_curve} && \mathit{fuel}_{g,t} & \ge \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g})(p_{g,t}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{module\_curve} && \mathit{fuel}_{g,t} & \ge \left( \mathit{units}_{g} \cdot \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g} \right) + \min(\mathit{units}_{g},\ 1) \cdot \left( \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g}) - \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g} \right) \right) \right)(p_{g,t}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \\ -\text{ramp\_curve} && \mathit{heat}_{g,t} & \le \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_heat}_{b,g})(p_{g,t}) && \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\text{adjacent} && \left( \mathit{weight}_{e,t} \right)_{e \in \mathcal{E}} & \in \mathrm{SOS}2 && \forall\, t \in \mathcal{T} \\ +\text{bus\_curve} && \left( p_{e,t} \right)_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} & \in \mathrm{pwl}_{b \in \mathcal{B}}(\left( \mathrm{bp\_x}_{b,e} \right)_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u}) && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} \\ +\text{chp\_curve} && \left( p_{e,t},\ \mathit{fuel}_{e,t},\ \mathit{heat}_{e,t} \right) & \in \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e},\ \mathrm{bp\_heat}_{b,e}) + \{0\} \times \mathbb{R}_{\ge 0} \times \mathbb{R}_{\le 0} && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{cost\_curve} && \mathit{op\_cost}_{e,t} & \ge \begin{cases} \mathit{warm}_{e,t} & \text{if } \mathrm{is\_flexible}_{e} \\ 1 & \text{otherwise} \end{cases} \cdot \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e})(p_{e,t}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{fuel\_curve} && \left( p_{e,t},\ \mathit{fuel}_{e,t},\ \mathit{heat}_{e,t} \right) & \in \mathit{on}_{e,t} \cdot \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e},\ \mathrm{bp\_heat}_{b,e}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{hull\_curve} && \left( p_{e,t},\ \mathit{fuel}_{e,t} \right) & \in \mathrm{conv}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_heat}_{b,e}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{lp\_curve} && \mathit{fuel}_{e,t} & \ge \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e})(p_{e,t}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{module\_curve} && \mathit{fuel}_{e,t} & \ge \left( \mathit{units}_{e} \cdot \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e} \right) + \min(\mathit{units}_{e},\ 1) \cdot \left( \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e}) - \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e} \right) \right) \right)(p_{e,t}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \\ +\text{ramp\_curve} && \mathit{heat}_{e,t} & \le \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_heat}_{b,e})(p_{e,t}) && \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \end{align} \paragraph{Assumptions} \begin{align} -\text{bounds\_do\_not\_cross} && \mathrm{p}^{\mathrm{min}}_{g} & \le \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G} \\ -\text{budget\_covers\_the\_peak} && \sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} & \ge \mathrm{budget} \\ -\text{efficiency\_is\_a\_fraction} && \mathrm{eta}_{g} > 0 \wedge \mathrm{eta}_{g} \le 1 & && \forall\, g \in \mathcal{G} \\ -\text{flexible\_units\_have\_headroom} && \mathrm{p}^{\mathrm{min}}_{g} & < \mathrm{p}^{\mathrm{max}}_{g} && \forall\, g \in \mathcal{G} \,:\, \mathrm{is\_flexible}_{g} \\ -\text{lead\_times\_are\_short} && \mathrm{lead}_{g} & \le 3 && \forall\, g \in \mathcal{G} \\ +\text{bounds\_do\_not\_cross} && \mathrm{p}^{\mathrm{min}}_{e} & \le \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E} \\ +\text{budget\_covers\_the\_peak} && \sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} & \ge \mathrm{budget} \\ +\text{efficiency\_is\_a\_fraction} && \mathrm{eta}_{e} > 0 \wedge \mathrm{eta}_{e} \le 1 & && \forall\, e \in \mathcal{E} \\ +\text{flexible\_units\_have\_headroom} && \mathrm{p}^{\mathrm{min}}_{e} & < \mathrm{p}^{\mathrm{max}}_{e} && \forall\, e \in \mathcal{E} \,:\, \mathrm{is\_flexible}_{e} \\ +\text{lead\_times\_are\_short} && \mathrm{lead}_{e} & \le 3 && \forall\, e \in \mathcal{E} \\ \text{northern\_demand\_is\_real} && \mathrm{load}_{u,t} & \ge 0 && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{zone}(u) = \text{'}\mathrm{north}\text{'} \\ \text{ramps\_are\_gentle} && \mathrm{load}_{u,t} - \mathrm{load}_{u,t \boxminus_{0} 1} & \le \mathrm{budget} && \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) > 0 \\ \text{zones\_agree} && \mathrm{zone}(u) & = \mathrm{area}(u) && \forall\, u \in \mathcal{U} \\ -\text{bus\_curve\_p\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{load}_{\mathrm{bus}(g),t} \text{ is defined} \\ -\text{chp\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \\ -\text{cost\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_run}_{b,g} \\ -\text{cost\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \wedge \neg \mathrm{bp\_run}_{b - 1,g} \} \rvert & = 1 && \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \} \rvert > 0 \\ -\text{fuel\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \\ -\text{hull\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \\ -\text{hull\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,g} & < \mathrm{bp\_x}_{b,g} && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 \\ -\text{hull\_curve\_curvature} && \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) > \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \vee \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) < \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 & && \forall\, g \in \mathcal{G} \\ -\text{lp\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \\ -\text{lp\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,g} & < \mathrm{bp\_x}_{b,g} && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,g} \text{ is defined} \\ -\text{lp\_curve\_curvature} && \left( \mathrm{bp\_y}_{b,g} - \mathrm{bp\_y}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) & \le \left( \mathrm{bp\_y}_{b \boxplus_{0} 1,g} - \mathrm{bp\_y}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b + 1,g} \text{ is defined} \\ -\text{lp\_curve\_breakpoints} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert & \ge 2 && \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert > 0 \\ -\text{lp\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \neg \left( \mathrm{bp\_x}_{b - 1,g} \text{ is defined} \right) \} \rvert & = 1 && \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert > 0 \\ -\text{module\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_run}_{b,g} \\ -\text{module\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \wedge \neg \mathrm{bp\_run}_{b - 1,g} \} \rvert & = 1 && \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \} \rvert > 0 \\ -\text{ramp\_curve\_complete} && \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} & && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \\ -\text{ramp\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,g} & < \mathrm{bp\_x}_{b,g} && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 \\ -\text{ramp\_curve\_curvature} && \left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) & \ge \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) && \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \\ -\text{ramp\_curve\_breakpoints} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert & \ge 2 && \forall\, g \in \mathcal{G} +\text{bus\_curve\_p\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{load}_{\mathrm{bus}(e),t} \text{ is defined} \\ +\text{chp\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \\ +\text{cost\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_run}_{b,e} \\ +\text{cost\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \wedge \neg \mathrm{bp\_run}_{b - 1,e} \} \rvert & = 1 && \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \} \rvert > 0 \\ +\text{fuel\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \\ +\text{hull\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \\ +\text{hull\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,e} & < \mathrm{bp\_x}_{b,e} && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 \\ +\text{hull\_curve\_curvature} && \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) > \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \vee \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) < \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 & && \forall\, e \in \mathcal{E} \\ +\text{lp\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \\ +\text{lp\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,e} & < \mathrm{bp\_x}_{b,e} && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,e} \text{ is defined} \\ +\text{lp\_curve\_curvature} && \left( \mathrm{bp\_y}_{b,e} - \mathrm{bp\_y}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) & \le \left( \mathrm{bp\_y}_{b \boxplus_{0} 1,e} - \mathrm{bp\_y}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b + 1,e} \text{ is defined} \\ +\text{lp\_curve\_breakpoints} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert & \ge 2 && \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert > 0 \\ +\text{lp\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \neg \left( \mathrm{bp\_x}_{b - 1,e} \text{ is defined} \right) \} \rvert & = 1 && \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert > 0 \\ +\text{module\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_run}_{b,e} \\ +\text{module\_curve\_contiguous} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \wedge \neg \mathrm{bp\_run}_{b - 1,e} \} \rvert & = 1 && \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \} \rvert > 0 \\ +\text{ramp\_curve\_complete} && \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} & && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \\ +\text{ramp\_curve\_increasing} && \mathrm{bp\_x}_{b \boxminus_{0} 1,e} & < \mathrm{bp\_x}_{b,e} && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 \\ +\text{ramp\_curve\_curvature} && \left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) & \ge \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) && \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \\ +\text{ramp\_curve\_breakpoints} && \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert & \ge 2 && \forall\, e \in \mathcal{E} \end{align} \end{document} diff --git a/tests/typesetting/golden/markdown.out b/tests/typesetting/golden/markdown.out index 455f09f7d..e163c09d4 100644 --- a/tests/typesetting/golden/markdown.out +++ b/tests/typesetting/golden/markdown.out @@ -7,67 +7,69 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 | Symbol | Meaning | |---|---| | $`\mathcal{B}`$ | index $`b`$ — `bp` | -| $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U}`$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label | -| $`\mathcal{C}`$ | index $`c`$ — `corridor`, $`\mathcal{C} = \mathcal{U} \times \mathcal{U}`$ | +| $`\mathcal{U}`$ | index $`u`$ — `bus` with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{E} \to \mathcal{U}`$, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{C}`$ | index $`c`$ — `connection`, $`\mathcal{C} \subseteq \mathcal{U} \times \mathcal{E}`$ | +| $`\mathcal{O}`$ | index $`o`$ — `corridor`, $`\mathcal{O} = \mathcal{U} \times \mathcal{U}`$ | | $`\mathcal{U}`$ | index $`u'`$ — `from_bus`, an alias of `bus` | -| $`\mathcal{G}`$ | index $`g`$ — `generator` with $`\mathrm{connection} \subseteq \mathcal{U} \times \mathcal{G},\ \mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{bus}: \mathcal{G} \to \mathcal{U},\ \mathrm{technology}: \mathcal{G} \to \mathcal{E}`$, `connection` is `absent` where the data has no row | +| $`\mathcal{G}`$ | index $`g`$ — `gen_zone`, $`\mathcal{G} = \mathcal{E} \times \mathcal{T}`$ with $`\mathrm{zone}: \mathcal{G} \to \mathcal{Z}`$ | +| $`\mathcal{E}`$ | index $`e`$ — `generator` with $`\mathrm{bus}: \mathcal{E} \to \mathcal{U},\ \mathrm{technology}: \mathcal{E} \to \mathcal{H}`$ | | $`\mathcal{S}`$ | index $`s`$ — `season` with $`\mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | -| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{G}`$ | -| $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{gen\_zone} \subseteq \mathcal{G} \times \mathcal{T},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z},\ \mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | -| $`\mathcal{E}`$ | index $`e`$ — `technology` with $`\mathrm{technology}: \mathcal{G} \to \mathcal{E}`$ | -| $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathrm{gen\_zone} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | +| $`\mathcal{I}`$ | index $`i`$ — `site`, $`\mathcal{I} \subseteq \mathcal{U} \times \mathcal{E}`$ | +| $`\mathcal{T}`$ | index $`t`$ — `snapshot` (`int` coordinates) with $`\mathrm{rep}: \mathcal{T} \to \mathcal{T},\ \mathrm{season}: \mathcal{T} \to \mathcal{S}`$ | +| $`\mathcal{H}`$ | index $`h`$ — `technology` with $`\mathrm{technology}: \mathcal{E} \to \mathcal{H}`$ | +| $`\mathcal{Z}`$ | index $`z`$ — `zone` (labels `north`, `south`) with $`\mathrm{area}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{U} \to \mathcal{Z},\ \mathrm{zone}: \mathcal{G} \to \mathcal{Z}`$, `bus[area]` is `absent` where the data gives no label | #### Parameters | Symbol | Meaning | |---|---| | $`\mathrm{area\_weight}`$ | `area_weight` over $`\mathcal{U}`$, only where $`\mathrm{area}(u) \text{ is defined}`$ | -| $`\mathrm{bp\_heat}`$ | `bp_heat` over $`\mathcal{B} \times \mathcal{G}`$ | -| $`\mathrm{bp\_run}`$ | `bp_run` over $`\mathcal{B} \times \mathcal{G}`$ | -| $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | -| $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{G}`$, $`0`$ where the data has no row | +| $`\mathrm{bp\_heat}`$ | `bp_heat` over $`\mathcal{B} \times \mathcal{E}`$ | +| $`\mathrm{bp\_run}`$ | `bp_run` over $`\mathcal{B} \times \mathcal{E}`$ | +| $`\mathrm{bp\_x}`$ | `bp_x` over $`\mathcal{B} \times \mathcal{E}`$, $`0`$ where the data has no row | +| $`\mathrm{bp\_y}`$ | `bp_y` over $`\mathcal{B} \times \mathcal{E}`$, $`0`$ where the data has no row | | $`\mathrm{budget}`$ | `budget` (scalar) | -| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{C}`$ | -| $`\mathrm{cost}`$ | `cost` over $`\mathcal{G}`$, $`0`$ where the data has no row | -| $`\mathrm{eta}`$ | `eta` over $`\mathcal{G}`$ | +| $`\mathrm{corridor\_cap}`$ | `corridor_cap` over $`\mathcal{O}`$ | +| $`\mathrm{cost}`$ | `cost` over $`\mathcal{E}`$, $`0`$ where the data has no row | +| $`\mathrm{eta}`$ | `eta` over $`\mathcal{E}`$ | | $`\mathrm{growth}`$ | `growth` (scalar) | -| $`\mathrm{is\_flexible}`$ | `is_flexible` over $`\mathcal{G}`$, `false` where the data has no row | -| $`\mathrm{lead}`$ | `lead` over $`\mathcal{G}`$ | -| $`\mathrm{link\_eff}`$ | `link_eff` over $`\mathcal{U} \times \mathcal{G}`$, only where $`\left( u,\ g \right) \in \mathrm{connection}`$, $`1`$ where the data has no row | +| $`\mathrm{is\_flexible}`$ | `is_flexible` over $`\mathcal{E}`$, `false` where the data has no row | +| $`\mathrm{lead}`$ | `lead` over $`\mathcal{E}`$ | +| $`\mathrm{link\_eff}`$ | `link_eff` over $`\mathcal{U} \times \mathcal{E}`$, only where $`\left( u,\ e \right) \in \mathrm{connection}`$, $`1`$ where the data has no row | | $`\mathrm{load}`$ | `load` over $`\mathcal{U} \times \mathcal{T}`$ | -| $`\mathrm{min\_up}`$ | `min_up` over $`\mathcal{G}`$ | -| $`\mathrm{p}^{\mathrm{max}}`$ | `p_max` over $`\mathcal{G}`$, $`\infty`$ where the data has no row | -| $`\mathrm{p}^{\mathrm{min}}`$ | `p_min` over $`\mathcal{G}`$ | +| $`\mathrm{min\_up}`$ | `min_up` over $`\mathcal{E}`$ | +| $`\mathrm{p}^{\mathrm{max}}`$ | `p_max` over $`\mathcal{E}`$, $`\infty`$ where the data has no row | +| $`\mathrm{p}^{\mathrm{min}}`$ | `p_min` over $`\mathcal{E}`$ | | $`\mathrm{susceptance}`$ | `susceptance` over $`\mathcal{U} \times \mathcal{U}`$, $`0`$ where the data has no row | -| $`\mathrm{tech\_cap}`$ | `tech_cap` over $`\mathcal{U} \times \mathcal{E}`$, `absent` where the data has no row | +| $`\mathrm{tech\_cap}`$ | `tech_cap` over $`\mathcal{U} \times \mathcal{H}`$, `absent` where the data has no row | | $`\mathrm{zone\_cap}`$ | `zone_cap` over $`\mathcal{Z}`$ | #### Conditions | Symbol | Meaning | |---|---| -| $`\mathrm{dispatchable}`$ | `dispatchable` over $`\mathcal{G}`$ — a unit that dispatches and cannot be turned down | -| $`\mathrm{priced\_dispatch}`$ | `priced_dispatch` over $`\mathcal{G}`$ | +| $`\mathrm{dispatchable}`$ | `dispatchable` over $`\mathcal{E}`$ — a unit that dispatches and cannot be turned down | +| $`\mathrm{priced\_dispatch}`$ | `priced_dispatch` over $`\mathcal{E}`$ | #### Variables | Symbol | Meaning | |---|---| -| $`\mathit{fuel}`$ | `fuel` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{fuel}`$ | `fuel` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{headroom}`$ | `headroom` (scalar), $`0`$ where the mask leaves it out | -| $`\mathit{heat}`$ | `heat` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{on}`$ | `on` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`p`$ | `p` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{heat}`$ | `heat` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{on}`$ | `on` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{op\_cost}`$ | `op_cost` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`p`$ | `p` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{reserve}`$ | `reserve` (scalar) | | $`\mathit{site\_out}`$ | `site_out` over $`\mathcal{I} \times \mathcal{T}`$ | | $`\mathit{slack}`$ | `slack` over $`\mathcal{T}`$ | -| $`\mathit{spare}`$ | `spare` over $`\mathcal{G}`$ | +| $`\mathit{spare}`$ | `spare` over $`\mathcal{E}`$ | | $`\mathit{spill}`$ | `spill` over $`\mathcal{T}`$ | | $`\theta`$ | `theta` over $`\mathcal{U}`$ | -| $`\mathit{units}`$ | `units` over $`\mathcal{G}`$ | -| $`\mathit{warm}`$ | `warm` over $`\mathcal{G} \times \mathcal{T}`$ | -| $`\mathit{weight}`$ | `weight` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathit{units}`$ | `units` over $`\mathcal{E}`$ | +| $`\mathit{warm}`$ | `warm` over $`\mathcal{E} \times \mathcal{T}`$ | +| $`\mathit{weight}`$ | `weight` over $`\mathcal{E} \times \mathcal{T}`$ | #### Definitions @@ -76,10 +78,10 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 | $`\mathit{lcoe}`$ | `lcoe` (scalar) | | $`\mathit{marginal\_price}`$ | `marginal_price` over $`\mathcal{U} \times \mathcal{T}`$ | | $`\mathit{net}`$ | `net` over $`\mathcal{T}`$ — what a snapshot spills, less what it lacks | -| $`\mathrm{rating}`$ | `rating` over $`\mathcal{G} \times \mathcal{T}`$ | +| $`\mathrm{rating}`$ | `rating` over $`\mathcal{E} \times \mathcal{T}`$ | | $`\mathit{spend}`$ | `spend` over $`\mathcal{T}`$ — what a snapshot's dispatch costs | -| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{G}`$ | -| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{G} \times \mathcal{T}`$ — what starting a unit in this snapshot costs, which the horizon's edge changes | +| $`\mathrm{spend}^{\mathrm{cap}}`$ | `spend_cap` over $`\mathcal{E}`$ | +| $`\mathrm{startup\_cost}`$ | `startup_cost` over $`\mathcal{E} \times \mathcal{T}`$ — what starting a unit in this snapshot costs, which the horizon's edge changes | #### Notation @@ -97,13 +99,13 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`dispatchable`** ```math -\mathrm{dispatchable}_{g} \iff \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \qquad \forall\, g \in \mathcal{G} +\mathrm{dispatchable}_{e} \iff \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} \qquad \forall\, e \in \mathcal{E} ``` **`priced_dispatch`** ```math -\mathrm{priced\_dispatch}_{g} \iff \mathrm{dispatchable}_{g} \wedge \mathrm{spend}^{\mathrm{cap}}_{g} > 0 \qquad \forall\, g \in \mathcal{G} +\mathrm{priced\_dispatch}_{e} \iff \mathrm{dispatchable}_{e} \wedge \mathrm{spend}^{\mathrm{cap}}_{e} > 0 \qquad \forall\, e \in \mathcal{E} ``` #### Variable domains @@ -111,7 +113,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`fuel`** ```math -\mathit{fuel}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{fuel}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`headroom`** @@ -123,25 +125,25 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`heat`** ```math -\mathit{heat}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{heat}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`on`** ```math -\mathit{on}_{g,t} \in \{0, 1\} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{on}_{e,t} \in \{0, 1\} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`op_cost`** ```math -\mathit{op\_cost}_{g,t} \ge 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{op\_cost}_{e,t} \ge 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`p`** ```math -\mathrm{p}^{\mathrm{min}}_{g} \le p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} > 0 \wedge \neg \mathrm{is\_flexible}_{g} \vee \mathrm{p}^{\mathrm{min}}_{g} > 0 +\mathrm{p}^{\mathrm{min}}_{e} \le p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} > 0 \wedge \neg \mathrm{is\_flexible}_{e} \vee \mathrm{p}^{\mathrm{min}}_{e} > 0 ``` **`reserve`** @@ -165,7 +167,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`spare`** ```math -\mathit{spare}_{g} \in \mathbb{Z} \qquad \forall\, g \in \mathcal{G} +\mathit{spare}_{e} \in \mathbb{Z} \qquad \forall\, e \in \mathcal{E} ``` **`spill`** @@ -183,19 +185,19 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`units`** ```math -0 \le \mathit{units}_{g} \le 10, \mathit{units}_{g} \in \mathbb{Z} \qquad \forall\, g \in \mathcal{G} +0 \le \mathit{units}_{e} \le 10, \mathit{units}_{e} \in \mathbb{Z} \qquad \forall\, e \in \mathcal{E} ``` **`warm`** ```math -\mathit{warm}_{g,t} \in \{0, 1\} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{g} +\mathit{warm}_{e,t} \in \{0, 1\} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{is\_flexible}_{e} ``` **`weight`** ```math -0 \le \mathit{weight}_{g,t} \le 1 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +0 \le \mathit{weight}_{e,t} \le 1 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Definitions @@ -203,7 +205,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`lcoe`** ```math -\mathit{lcoe} = \frac{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g}}{\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t}} +\mathit{lcoe} = \frac{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e}}{\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t}} ``` **`marginal_price`** @@ -221,31 +223,31 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`rating`** ```math -\mathrm{rating}_{g,t} = \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathrm{rating}_{e,t} = \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} \cdot \left( \sum_{u \in \mathcal{U}} \mathrm{load}_{u,t} \right) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`spend`** ```math -\mathit{spend}_{t} = \sum_{g \in \mathcal{G}} p_{g,t} \cdot \mathrm{cost}_{g} \qquad \forall\, t \in \mathcal{T} +\mathit{spend}_{t} = \sum_{e \in \mathcal{E}} p_{e,t} \cdot \mathrm{cost}_{e} \qquad \forall\, t \in \mathcal{T} ``` **`spend_cap`** ```math -\mathrm{spend}^{\mathrm{cap}}_{g} = \mathrm{cost}_{g} \cdot 2 \qquad \forall\, g \in \mathcal{G} +\mathrm{spend}^{\mathrm{cap}}_{e} = \mathrm{cost}_{e} \cdot 2 \qquad \forall\, e \in \mathcal{E} ``` **`startup_cost`** ```math -\mathrm{startup\_cost}_{g,t} = \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}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathrm{startup\_cost}_{e,t} = \begin{cases} \mathrm{cost}_{e} & \text{if } \mathrm{pos}(t) = 0 \\ \mathrm{cost}_{e} \cdot 2 & \text{if } \mathrm{pos}(t) > 0 \wedge \mathrm{season}(t) = \text{'}\mathrm{winter}\text{'} \\ 0 & \text{otherwise} \end{cases} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Objective ```math -\max \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot p_{g,t} \cdot \mathrm{cost}_{g} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{cost}_{g} \cdot \mathrm{growth}^{\mathrm{lead}_{g}} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{g}} \right)^{2} + \sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \cdot \mathrm{p}^{\mathrm{max}}_{g} - \mathit{reserve} - \mathit{headroom} +\max \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot p_{e,t} \cdot \mathrm{cost}_{e} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{cost}_{e} \cdot \mathrm{growth}^{\mathrm{lead}_{e}} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \left( \mathrm{growth}^{\mathrm{lead}_{e}} \right)^{2} + \sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \cdot \mathrm{p}^{\mathrm{max}}_{e} - \mathit{reserve} - \mathit{headroom} ``` #### Subject to @@ -253,7 +255,7 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 **`ahead`** ```math -p_{g,t} \le p_{g,t \oplus 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \oplus 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`always`** @@ -265,13 +267,13 @@ p_{g,t} \le p_{g,t \oplus 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal **`arithmetic`** ```math -\sum_{g \in \mathcal{G}} \left( \frac{p_{g,t}}{2} - \mathrm{cost}_{g} + 10^{-5} \cdot p_{g,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{g} + 0.5 \cdot p_{g,t} \right) \ge -\left( \sum_{g \in \mathcal{G}} p_{g,t} \right) \cdot \left( -3 \right) \qquad \forall\, t \in \mathcal{T} +\sum_{e \in \mathcal{E}} \left( \frac{p_{e,t}}{2} - \mathrm{cost}_{e} + 10^{-5} \cdot p_{e,t} + 2.5 \times 10^{-7} \cdot \mathrm{cost}_{e} + 0.5 \cdot p_{e,t} \right) \ge -\left( \sum_{e \in \mathcal{E}} p_{e,t} \right) \cdot \left( -3 \right) \qquad \forall\, t \in \mathcal{T} ``` **`balance`** ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{spill}_{t} - \mathit{slack}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{spill}_{t} - \mathit{slack}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` **`budgeted`** @@ -283,7 +285,7 @@ p_{g,t} \le p_{g,t \oplus 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal **`capped`** ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{g} > 0 \vee \neg \mathrm{is\_flexible}_{g} +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{spend}^{\mathrm{cap}}_{e} > 0 \vee \neg \mathrm{is\_flexible}_{e} ``` **`ceiling`** @@ -295,49 +297,49 @@ p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t **`composed`** ```math -p_{g,t - 2} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t - 2} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`connected`** ```math -p_{g,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \left( u,\ g \right) \in \mathrm{connection} +p_{e,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \left( u,\ e \right) \in \mathrm{connection} ``` **`counted`** ```math -\theta_{u} \le \mathrm{budget} \qquad \forall\, u \in \mathcal{U} \,:\, \lvert \{ e \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e} > 0 \} \rvert \ge 2 +\theta_{u} \le \mathrm{budget} \qquad \forall\, u \in \mathcal{U} \,:\, \lvert \{ h \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h} > 0 \} \rvert \ge 2 ``` **`counted_here`** ```math -\theta_{u} \le \mathrm{tech\_cap}_{u,e} \qquad \forall\, u \in \mathcal{U},\ e \in \mathcal{E} \,:\, \lvert \{ e' \in \mathcal{E} \,:\, \mathrm{tech\_cap}_{u,e'} > 0 \} \rvert \ge 2 +\theta_{u} \le \mathrm{tech\_cap}_{u,h} \qquad \forall\, u \in \mathcal{U},\ h \in \mathcal{H} \,:\, \lvert \{ h' \in \mathcal{H} \,:\, \mathrm{tech\_cap}_{u,h'} > 0 \} \rvert \ge 2 ``` **`covered`** ```math -\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \le \mathrm{budget} \qquad \text{where } \sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} \ge \mathrm{budget} +\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \le \mathrm{budget} \qquad \text{where } \sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} \ge \mathrm{budget} ``` **`crossed`** ```math -p_{g + 1,t \ominus 1} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e + 1,t \ominus 1} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`edges`** ```math -p_{g,t \boxminus_{0} 1} \le p_{g,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t \boxminus_{0} 1} \le p_{e,t \boxplus_{0} 1} + \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`efficiency`** ```math -p_{g,t} \le \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{eta}_{e} \cdot \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`exchanged`** @@ -349,7 +351,7 @@ p_{g,t} \le \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\ **`first`** ```math -\mathit{on}_{g,t} = 1 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 +\mathit{on}_{e,t} = 1 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = 0 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = 0 ``` **`flow_angle`** @@ -361,43 +363,43 @@ p_{g,t} \le \mathrm{eta}_{g} \cdot \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\ **`grouped_once`** ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u \wedge \mathrm{technology}(g) = e} p_{g,t} \le \mathrm{tech\_cap}_{u,e} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ e \in \mathcal{E} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u \wedge \mathrm{technology}(e) = h} p_{e,t} \le \mathrm{tech\_cap}_{u,h} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T},\ h \in \mathcal{H} ``` **`held_in_season`** ```math -p_{g,t} \le p_{g,t \boxminus_{0}^{\mathrm{season}(t)} 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \boxminus_{0}^{\mathrm{season}(t)} 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`history`** ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t \ominus t' < \mathrm{min\_up}} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`in_season`** ```math -p_{g,t} \le p_{g,t \ominus^{\mathrm{season}(t)} 1} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le p_{e,t \ominus^{\mathrm{season}(t)} 1} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`last`** ```math -\mathit{on}_{g,t} = 0 \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 +\mathit{on}_{e,t} = 0 \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{pos}(t) = \lvert \mathcal{T} \rvert - 1 \vee \mathrm{pos}_{\mathrm{season}(t)}(t) = \lvert \mathcal{T}_{\mathrm{season}(t)} \rvert - 1 ``` **`lead_time`** ```math -p_{g,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`looked_up_once`** ```math -\mathit{units}_{g} \le \mathrm{tech\_cap}_{\mathrm{bus}(g),\mathrm{technology}(g)} \qquad \forall\, g \in \mathcal{G} +\mathit{units}_{e} \le \mathrm{tech\_cap}_{\mathrm{bus}(e),\mathrm{technology}(e)} \qquad \forall\, e \in \mathcal{E} ``` **`lookup`** @@ -409,19 +411,19 @@ p_{g,t \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \fo **`margin`** ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{g} - \mathrm{p}^{\mathrm{min}}_{g} > \frac{\mathrm{cost}_{g}}{2} +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{p}^{\mathrm{max}}_{e} - \mathrm{p}^{\mathrm{min}}_{e} > \frac{\mathrm{cost}_{e}}{2} ``` **`masked`** ```math -p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{g} \wedge \mathrm{pos}(t) > 0 +p_{e,t} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{priced\_dispatch}_{e} \wedge \mathrm{pos}(t) > 0 ``` **`netted`** ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} p_{g,t} + \mathit{net}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} p_{e,t} + \mathit{net}_{t} = \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` **`never`** @@ -439,7 +441,7 @@ p_{g,t} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t **`ramp`** ```math -p_{g,t} - p_{g,t \ominus 1} \le p_{g,t - 1} + \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} - p_{e,t \ominus 1} \le p_{e,t - 1} + \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`ramped`** @@ -457,7 +459,7 @@ p_{g,t} - p_{g,t \ominus 1} \le p_{g,t - 1} + \mathrm{p}^{\mathrm{max}}_{g} \qqu **`relational`** ```math -\sum_{g \in \mathcal{G} \,:\, \left( u,\ g \right) \in \mathrm{connection}} p_{g,t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} +\sum_{c \in \mathcal{C} \,:\, \mathrm{bus}(c) = u} p_{\mathrm{generator}(c),t} \le \mathrm{load}_{u,t} \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} ``` **`representative`** @@ -481,73 +483,73 @@ p_{g,t} - p_{g,t \ominus 1} \le p_{g,t - 1} + \mathrm{p}^{\mathrm{max}}_{g} \qqu **`scalar`** ```math -\mathit{units}_{g} \le \mathrm{budget} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{cost}_{g} \text{ is defined} +\mathit{units}_{e} \le \mathrm{budget} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{cost}_{e} \text{ is defined} ``` **`seasonal_window`** ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t -^{\mathrm{season}(t)} t' < 3} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`starts`** ```math -p_{g,t} \le \mathrm{startup\_cost}_{g,t} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{startup\_cost}_{e,t} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`total`** ```math -\sum_{g \in \mathcal{G},\ t \in \mathcal{T}} p_{g,t} \le \mathrm{budget} +\sum_{e \in \mathcal{E},\ t \in \mathcal{T}} p_{e,t} \le \mathrm{budget} ``` **`uncomposed`** ```math -p_{g,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,\left( t - 1 \right) \boxminus_{0} \mathrm{lead}} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`under_rating`** ```math -p_{g,t} \le \mathrm{rating}_{g,t} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +p_{e,t} \le \mathrm{rating}_{e,t} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`window`** ```math -\sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{g,t'} \le \mathit{units}_{g} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\sum_{t' \in \mathcal{T} \,:\, 0 \le t - t' < 3} \mathit{on}_{e,t'} \le \mathit{units}_{e} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`within_bus`** ```math -\mathit{units}_{g} \le \mathit{units}_{g \boxminus_{0}^{\mathrm{bus}(g)} 1} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(g),\ \mathrm{technology}(g) \right)}(g) = 0 +\mathit{units}_{e} \le \mathit{units}_{e \boxminus_{0}^{\mathrm{bus}(e)} 1} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{pos}_{\left( \mathrm{bus}(e),\ \mathrm{technology}(e) \right)}(e) = 0 ``` **`zonal`** ```math -\sum_{g \in \mathcal{G} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} \le \mathrm{zone\_cap}_{z} \qquad \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} +\sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathrm{zone\_cap}_{z} \qquad \forall\, t \in \mathcal{T},\ z \in \mathcal{Z} ``` **`zonal_history`** ```math -\sum_{t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = z} p_{g,t} \le \mathrm{zone\_cap}_{z} \qquad \forall\, g \in \mathcal{G},\ z \in \mathcal{Z} +\sum_{g \in \mathcal{G} \,:\, \mathrm{generator}(g) = e \wedge \mathrm{zone}(g) = z} p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathrm{zone\_cap}_{z} \qquad \forall\, e \in \mathcal{E},\ z \in \mathcal{Z} ``` **`zonal_lookup`** ```math -p_{g,t} \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{zone}(g,\ t) = \text{'}\mathrm{north}\text{'} \wedge \mathrm{pos}_{\mathrm{zone}(g,\ t)}(g) = 0 +p_{\mathrm{generator}(g),\mathrm{snapshot}(g)} \le \mathit{spill}_{\mathrm{snapshot}(g)} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g)} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{zone}(g) = \text{'}\mathrm{north}\text{'} ``` **`zonal_membership`** ```math -\sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}} \mathit{units}_{g} \le \mathrm{budget} \qquad \forall\, t \in \mathcal{T} +\sum_{g \in \mathcal{G} \,:\, \mathrm{snapshot}(g) = t} \mathit{units}_{\mathrm{generator}(g)} \le \mathrm{budget} \qquad \forall\, t \in \mathcal{T} ``` **`zoned`** @@ -559,55 +561,55 @@ p_{g,t} \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} \ **`adjacent`** ```math -\left( \mathit{weight}_{g,t} \right)_{g \in \mathcal{G}} \in \mathrm{SOS}2 \qquad \forall\, t \in \mathcal{T} +\left( \mathit{weight}_{e,t} \right)_{e \in \mathcal{E}} \in \mathrm{SOS}2 \qquad \forall\, t \in \mathcal{T} ``` **`bus_curve`** ```math -\left( p_{g,t} \right)_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u} \in \mathrm{pwl}_{b \in \mathcal{B}}(\left( \mathrm{bp\_x}_{b,g} \right)_{g \in \mathcal{G} \,:\, \mathrm{bus}(g) = u}) \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} +\left( p_{e,t} \right)_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u} \in \mathrm{pwl}_{b \in \mathcal{B}}(\left( \mathrm{bp\_x}_{b,e} \right)_{e \in \mathcal{E} \,:\, \mathrm{bus}(e) = u}) \qquad \forall\, u \in \mathcal{U},\ t \in \mathcal{T} \,:\, \mathrm{load}_{u,t} \text{ is defined} ``` **`chp_curve`** ```math -\left( p_{g,t},\ \mathit{fuel}_{g,t},\ \mathit{heat}_{g,t} \right) \in \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g},\ \mathrm{bp\_heat}_{b,g}) + \{0\} \times \mathbb{R}_{\ge 0} \times \mathbb{R}_{\le 0} \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\left( p_{e,t},\ \mathit{fuel}_{e,t},\ \mathit{heat}_{e,t} \right) \in \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e},\ \mathrm{bp\_heat}_{b,e}) + \{0\} \times \mathbb{R}_{\ge 0} \times \mathbb{R}_{\le 0} \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`cost_curve`** ```math -\mathit{op\_cost}_{g,t} \ge \begin{cases} \mathit{warm}_{g,t} & \text{if } \mathrm{is\_flexible}_{g} \\ 1 & \text{otherwise} \end{cases} \cdot \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g})(p_{g,t}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{op\_cost}_{e,t} \ge \begin{cases} \mathit{warm}_{e,t} & \text{if } \mathrm{is\_flexible}_{e} \\ 1 & \text{otherwise} \end{cases} \cdot \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e})(p_{e,t}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`fuel_curve`** ```math -\left( p_{g,t},\ \mathit{fuel}_{g,t},\ \mathit{heat}_{g,t} \right) \in \mathit{on}_{g,t} \cdot \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g},\ \mathrm{bp\_heat}_{b,g}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\left( p_{e,t},\ \mathit{fuel}_{e,t},\ \mathit{heat}_{e,t} \right) \in \mathit{on}_{e,t} \cdot \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e},\ \mathrm{bp\_heat}_{b,e}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`hull_curve`** ```math -\left( p_{g,t},\ \mathit{fuel}_{g,t} \right) \in \mathrm{conv}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_heat}_{b,g}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\left( p_{e,t},\ \mathit{fuel}_{e,t} \right) \in \mathrm{conv}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_heat}_{b,e}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`lp_curve`** ```math -\mathit{fuel}_{g,t} \ge \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g})(p_{g,t}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{fuel}_{e,t} \ge \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e})(p_{e,t}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`module_curve`** ```math -\mathit{fuel}_{g,t} \ge \left( \mathit{units}_{g} \cdot \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g} \right) + \min(\mathit{units}_{g},\ 1) \cdot \left( \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_y}_{b,g}) - \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \},g} \right) \right) \right)(p_{g,t}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{fuel}_{e,t} \ge \left( \mathit{units}_{e} \cdot \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e} \right) + \min(\mathit{units}_{e},\ 1) \cdot \left( \mathrm{pwl}_{b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_y}_{b,e}) - \left( \mathrm{bp\_x}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e},\ \mathrm{bp\_y}_{\min \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \},e} \right) \right) \right)(p_{e,t}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` **`ramp_curve`** ```math -\mathit{heat}_{g,t} \le \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,g},\ \mathrm{bp\_heat}_{b,g})(p_{g,t}) \qquad \forall\, g \in \mathcal{G},\ t \in \mathcal{T} +\mathit{heat}_{e,t} \le \mathrm{pwl}_{b \in \mathcal{B}}(\mathrm{bp\_x}_{b,e},\ \mathrm{bp\_heat}_{b,e})(p_{e,t}) \qquad \forall\, e \in \mathcal{E},\ t \in \mathcal{T} ``` #### Assumptions @@ -615,31 +617,31 @@ p_{g,t} \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} \ **`bounds_do_not_cross`** ```math -\mathrm{p}^{\mathrm{min}}_{g} \le \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G} +\mathrm{p}^{\mathrm{min}}_{e} \le \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E} ``` **`budget_covers_the_peak`** ```math -\sum_{g \in \mathcal{G}} \mathrm{p}^{\mathrm{max}}_{g} \ge \mathrm{budget} +\sum_{e \in \mathcal{E}} \mathrm{p}^{\mathrm{max}}_{e} \ge \mathrm{budget} ``` **`efficiency_is_a_fraction`** ```math -\mathrm{eta}_{g} > 0 \wedge \mathrm{eta}_{g} \le 1 \qquad \forall\, g \in \mathcal{G} +\mathrm{eta}_{e} > 0 \wedge \mathrm{eta}_{e} \le 1 \qquad \forall\, e \in \mathcal{E} ``` **`flexible_units_have_headroom`** ```math -\mathrm{p}^{\mathrm{min}}_{g} < \mathrm{p}^{\mathrm{max}}_{g} \qquad \forall\, g \in \mathcal{G} \,:\, \mathrm{is\_flexible}_{g} +\mathrm{p}^{\mathrm{min}}_{e} < \mathrm{p}^{\mathrm{max}}_{e} \qquad \forall\, e \in \mathcal{E} \,:\, \mathrm{is\_flexible}_{e} ``` **`lead_times_are_short`** ```math -\mathrm{lead}_{g} \le 3 \qquad \forall\, g \in \mathcal{G} +\mathrm{lead}_{e} \le 3 \qquad \forall\, e \in \mathcal{E} ``` **`northern_demand_is_real`** @@ -663,113 +665,113 @@ p_{g,t} \le \mathit{spill}_{t} \cdot \mathrm{zone\_cap}_{\mathrm{zone}(g,\ t)} \ **`bus_curve_p_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G},\ t \in \mathcal{T} \,:\, \mathrm{load}_{\mathrm{bus}(g),t} \text{ is defined} +\mathrm{bp\_x}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E},\ t \in \mathcal{T} \,:\, \mathrm{load}_{\mathrm{bus}(e),t} \text{ is defined} ``` **`chp_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} ``` **`cost_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_run}_{b,g} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_run}_{b,e} ``` **`cost_curve_contiguous`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \wedge \neg \mathrm{bp\_run}_{b - 1,g} \} \rvert = 1 \qquad \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \} \rvert > 0 +\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \wedge \neg \mathrm{bp\_run}_{b - 1,e} \} \rvert = 1 \qquad \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \} \rvert > 0 ``` **`fuel_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} ``` **`hull_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} ``` **`hull_curve_increasing`** ```math -\mathrm{bp\_x}_{b \boxminus_{0} 1,g} < \mathrm{bp\_x}_{b,g} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 +\mathrm{bp\_x}_{b \boxminus_{0} 1,e} < \mathrm{bp\_x}_{b,e} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 ``` **`hull_curve_curvature`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) > \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \vee \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) < \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \qquad \forall\, g \in \mathcal{G} +\lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) > \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \vee \lvert \{ b \in \mathcal{B} \,:\, \left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) < \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \wedge \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 \} \rvert = 0 \qquad \forall\, e \in \mathcal{E} ``` **`lp_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} ``` **`lp_curve_increasing`** ```math -\mathrm{bp\_x}_{b \boxminus_{0} 1,g} < \mathrm{bp\_x}_{b,g} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,g} \text{ is defined} +\mathrm{bp\_x}_{b \boxminus_{0} 1,e} < \mathrm{bp\_x}_{b,e} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,e} \text{ is defined} ``` **`lp_curve_curvature`** ```math -\left( \mathrm{bp\_y}_{b,g} - \mathrm{bp\_y}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) \le \left( \mathrm{bp\_y}_{b \boxplus_{0} 1,g} - \mathrm{bp\_y}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,g} \text{ is defined} \wedge \mathrm{bp\_x}_{b + 1,g} \text{ is defined} +\left( \mathrm{bp\_y}_{b,e} - \mathrm{bp\_y}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) \le \left( \mathrm{bp\_y}_{b \boxplus_{0} 1,e} - \mathrm{bp\_y}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b - 1,e} \text{ is defined} \wedge \mathrm{bp\_x}_{b + 1,e} \text{ is defined} ``` **`lp_curve_breakpoints`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert \ge 2 \qquad \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert > 0 +\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert \ge 2 \qquad \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert > 0 ``` **`lp_curve_contiguous`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \neg \left( \mathrm{bp\_x}_{b - 1,g} \text{ is defined} \right) \} \rvert = 1 \qquad \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert > 0 +\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \neg \left( \mathrm{bp\_x}_{b - 1,e} \text{ is defined} \right) \} \rvert = 1 \qquad \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert > 0 ``` **`module_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_y}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{bp\_run}_{b,g} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_y}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{bp\_run}_{b,e} ``` **`module_curve_contiguous`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \wedge \neg \mathrm{bp\_run}_{b - 1,g} \} \rvert = 1 \qquad \forall\, g \in \mathcal{G} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,g} \} \rvert > 0 +\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \wedge \neg \mathrm{bp\_run}_{b - 1,e} \} \rvert = 1 \qquad \forall\, e \in \mathcal{E} \,:\, \lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_run}_{b,e} \} \rvert > 0 ``` **`ramp_curve_complete`** ```math -\mathrm{bp\_x}_{b,g} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,g} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} +\mathrm{bp\_x}_{b,e} \text{ is defined} \wedge \mathrm{bp\_heat}_{b,e} \text{ is defined} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} ``` **`ramp_curve_increasing`** ```math -\mathrm{bp\_x}_{b \boxminus_{0} 1,g} < \mathrm{bp\_x}_{b,g} \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 +\mathrm{bp\_x}_{b \boxminus_{0} 1,e} < \mathrm{bp\_x}_{b,e} \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 ``` **`ramp_curve_curvature`** ```math -\left( \mathrm{bp\_heat}_{b,g} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,g} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,g} - \mathrm{bp\_x}_{b,g} \right) \ge \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,g} - \mathrm{bp\_heat}_{b,g} \right) \cdot \left( \mathrm{bp\_x}_{b,g} - \mathrm{bp\_x}_{b \boxminus_{0} 1,g} \right) \qquad \forall\, b \in \mathcal{B},\ g \in \mathcal{G} \,:\, \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 +\left( \mathrm{bp\_heat}_{b,e} - \mathrm{bp\_heat}_{b \boxminus_{0} 1,e} \right) \cdot \left( \mathrm{bp\_x}_{b \boxplus_{0} 1,e} - \mathrm{bp\_x}_{b,e} \right) \ge \left( \mathrm{bp\_heat}_{b \boxplus_{0} 1,e} - \mathrm{bp\_heat}_{b,e} \right) \cdot \left( \mathrm{bp\_x}_{b,e} - \mathrm{bp\_x}_{b \boxminus_{0} 1,e} \right) \qquad \forall\, b \in \mathcal{B},\ e \in \mathcal{E} \,:\, \mathrm{pos}(b) > 0 \wedge \mathrm{pos}(b) \neq \lvert \mathcal{B} \rvert - 1 ``` **`ramp_curve_breakpoints`** ```math -\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,g} \text{ is defined} \} \rvert \ge 2 \qquad \forall\, g \in \mathcal{G} +\lvert \{ b \in \mathcal{B} \,:\, \mathrm{bp\_x}_{b,e} \text{ is defined} \} \rvert \ge 2 \qquad \forall\, e \in \mathcal{E} ``` diff --git a/tests/typesetting/golden/model.yaml b/tests/typesetting/golden/model.yaml index 91b979659..08711e820 100644 --- a/tests/typesetting/golden/model.yaml +++ b/tests/typesetting/golden/model.yaml @@ -23,10 +23,8 @@ dimensions: bp: { dtype: int, ordered: true } # the breakpoints every curve below runs through site: { over: [generator, bus] } # a dimension that lists its members: the legend prints it as a subset of their product corridor: { over: [from_bus, bus], missing: refused } # a member and its alias, and every combination required: the product itself - -relations: - gen_zone: { dims: [generator, snapshot] } # a relation over two dimensions, with a map: a call sums one away and joins on the other - connection: { dims: [generator, bus], missing: absent } # a relation with no map: many-to-many, read only by sum with both ends named + gen_zone: { over: [generator, snapshot], missing: refused } # a tuple over two dimensions, with a map: a call reads an entry at each tuple and groups by a member + connection: { over: [generator, bus] } # a tuple with no map: many-to-many, read only through its members maps: generator: { bus: { dim: bus }, technology: { dim: technology } } # two maps of one subject, read to both at once @@ -281,29 +279,29 @@ constraints: dims: [generator] where: "position(generator, within=generator[bus, technology]) == 0" expression: units <= shift(units, along=generator, offset=1, edge=0, within=generator[bus]) - relational: # a sum through a relation with no map: the domain is a row of the relation rather than a label + relational: # a sum over a tuple with no map: the domain is a tuple rather than a label dims: [snapshot, bus] - expression: sum(p, over=generator, by=connection[bus]) <= load - connected: # a relation as a where: the row of the frame has to be a member of the relation + expression: sum(at(p, by=connection[generator]), over=connection, by=connection[bus]) <= load + connected: # a tuple as a where: the frame's member labels have to form a listed tuple dims: [snapshot, generator, bus] where: "connection" expression: p <= load representative: # a map into its own dimension, read both ways: the frame is unchanged and the index is primed dims: [snapshot] expression: sum(spill, over=snapshot, by=snapshot[rep]) <= at(spill, by=snapshot[rep]) - zonal: # a grouping through a two-key map, summing one key away: the condition reads the other, and the row keeps it + zonal: # a grouping through a map of a tuple, keeping one member: the row keeps the snapshot dims: [snapshot, zone] - expression: sum(p, over=generator, by=gen_zone[zone]) <= zone_cap - zonal_history: # the same table summing its other key away + expression: sum(at(p, by=gen_zone[generator, snapshot]), over=gen_zone, by=gen_zone[snapshot, zone]) <= zone_cap + zonal_history: # the same tuple keeping its other member dims: [generator, zone] - expression: sum(p, over=snapshot, by=gen_zone[zone]) <= zone_cap - zonal_membership: # the same relation read between its own two columns: no map is read, so the domain asks only that the row is there + expression: sum(at(p, by=gen_zone[generator, snapshot]), over=gen_zone, by=gen_zone[generator, zone]) <= zone_cap + zonal_membership: # the same tuple grouped by a member alone: no map is read, so the domain asks only that the tuple is there dims: [snapshot] - expression: sum(units, over=generator, by=gen_zone[snapshot]) <= budget - zonal_lookup: # the same table joined the other way, reading the slot the row's own snapshot puts the generator in - dims: [snapshot, generator] - where: "gen_zone[zone] == 'north' AND position(generator, within=gen_zone[zone]) == 0" - expression: p <= at(spill * zone_cap, by=gen_zone[zone]) + expression: sum(at(units, by=gen_zone[generator]), over=gen_zone, by=gen_zone[snapshot]) <= budget + zonal_lookup: # the same tuple as the frame, reading the zone each tuple maps to + dims: [gen_zone] + where: "gen_zone[zone] == 'north'" + expression: at(p, by=gen_zone[generator, snapshot]) <= at(spill * zone_cap, by=gen_zone[snapshot, zone]) arithmetic: # division, both unary signs, a sign beside a sign, floats with and without an exponent, bracketing dims: [snapshot] expression: >- diff --git a/tests/typesetting/golden/typst.out b/tests/typesetting/golden/typst.out index 9a98347bc..c6adfbaeb 100644 --- a/tests/typesetting/golden/typst.out +++ b/tests/typesetting/golden/typst.out @@ -5,67 +5,69 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 == Sets / $cal(B)$: index $b$ --- `bp` -/ $cal(U)$: index $u$ --- `bus` with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("connection") subset.eq cal(U) times cal(G), upright("bus"): cal(G) arrow.r cal(U)$, `connection` is `absent` where the data has no row, `bus[area]` is `absent` where the data gives no label -/ $cal(C)$: index $c$ --- `corridor`, $cal(C) = cal(U) times cal(U)$ +/ $cal(U)$: index $u$ --- `bus` with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("bus"): cal(E) arrow.r cal(U)$, `bus[area]` is `absent` where the data gives no label +/ $cal(C)$: index $c$ --- `connection`, $cal(C) subset.eq cal(U) times cal(E)$ +/ $cal(O)$: index $o$ --- `corridor`, $cal(O) = cal(U) times cal(U)$ / $cal(U)$: index $u'$ --- `from_bus`, an alias of `bus` -/ $cal(G)$: index $g$ --- `generator` with $upright("connection") subset.eq cal(U) times cal(G), upright("gen_zone") subset.eq cal(G) times cal(T), upright("zone"): upright("gen_zone") arrow.r cal(Z), upright("bus"): cal(G) arrow.r cal(U), upright("technology"): cal(G) arrow.r cal(E)$, `connection` is `absent` where the data has no row +/ $cal(G)$: index $g$ --- `gen_zone`, $cal(G) = cal(E) times cal(T)$ with $upright("zone"): cal(G) arrow.r cal(Z)$ +/ $cal(E)$: index $e$ --- `generator` with $upright("bus"): cal(E) arrow.r cal(U), upright("technology"): cal(E) arrow.r cal(H)$ / $cal(S)$: index $s$ --- `season` with $upright("season"): cal(T) arrow.r cal(S)$ -/ $cal(I)$: index $i$ --- `site`, $cal(I) subset.eq cal(U) times cal(G)$ -/ $cal(T)$: index $t$ --- `snapshot` (`int` coordinates) with $upright("gen_zone") subset.eq cal(G) times cal(T), upright("zone"): upright("gen_zone") arrow.r cal(Z), upright("rep"): cal(T) arrow.r cal(T), upright("season"): cal(T) arrow.r cal(S)$ -/ $cal(E)$: index $e$ --- `technology` with $upright("technology"): cal(G) arrow.r cal(E)$ -/ $cal(Z)$: index $z$ --- `zone` (labels `north`, `south`) with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("zone"): upright("gen_zone") arrow.r cal(Z)$, `bus[area]` is `absent` where the data gives no label +/ $cal(I)$: index $i$ --- `site`, $cal(I) subset.eq cal(U) times cal(E)$ +/ $cal(T)$: index $t$ --- `snapshot` (`int` coordinates) with $upright("rep"): cal(T) arrow.r cal(T), upright("season"): cal(T) arrow.r cal(S)$ +/ $cal(H)$: index $h$ --- `technology` with $upright("technology"): cal(E) arrow.r cal(H)$ +/ $cal(Z)$: index $z$ --- `zone` (labels `north`, `south`) with $upright("area"): cal(U) arrow.r cal(Z), upright("zone"): cal(U) arrow.r cal(Z), upright("zone"): cal(G) arrow.r cal(Z)$, `bus[area]` is `absent` where the data gives no label == Parameters / $upright("area_weight")$: `area_weight` over $cal(U)$, only where $upright("area")(u) upright(" is defined")$ -/ $upright("bp_heat")$: `bp_heat` over $cal(B) times cal(G)$ -/ $upright("bp_run")$: `bp_run` over $cal(B) times cal(G)$ -/ $upright("bp_x")$: `bp_x` over $cal(B) times cal(G)$, $0$ where the data has no row -/ $upright("bp_y")$: `bp_y` over $cal(B) times cal(G)$, $0$ where the data has no row +/ $upright("bp_heat")$: `bp_heat` over $cal(B) times cal(E)$ +/ $upright("bp_run")$: `bp_run` over $cal(B) times cal(E)$ +/ $upright("bp_x")$: `bp_x` over $cal(B) times cal(E)$, $0$ where the data has no row +/ $upright("bp_y")$: `bp_y` over $cal(B) times cal(E)$, $0$ where the data has no row / $upright("budget")$: `budget` (scalar) -/ $upright("corridor_cap")$: `corridor_cap` over $cal(C)$ -/ $upright("cost")$: `cost` over $cal(G)$, $0$ where the data has no row -/ $upright("eta")$: `eta` over $cal(G)$ +/ $upright("corridor_cap")$: `corridor_cap` over $cal(O)$ +/ $upright("cost")$: `cost` over $cal(E)$, $0$ where the data has no row +/ $upright("eta")$: `eta` over $cal(E)$ / $upright("growth")$: `growth` (scalar) -/ $upright("is_flexible")$: `is_flexible` over $cal(G)$, `false` where the data has no row -/ $upright("lead")$: `lead` over $cal(G)$ -/ $upright("link_eff")$: `link_eff` over $cal(U) times cal(G)$, only where $(u, g) in upright("connection")$, $1$ where the data has no row +/ $upright("is_flexible")$: `is_flexible` over $cal(E)$, `false` where the data has no row +/ $upright("lead")$: `lead` over $cal(E)$ +/ $upright("link_eff")$: `link_eff` over $cal(U) times cal(E)$, only where $(u, e) in upright("connection")$, $1$ where the data has no row / $upright("load")$: `load` over $cal(U) times cal(T)$ -/ $upright("min_up")$: `min_up` over $cal(G)$ -/ $upright("p")^(upright("max"))$: `p_max` over $cal(G)$, $infinity$ where the data has no row -/ $upright("p")^(upright("min"))$: `p_min` over $cal(G)$ +/ $upright("min_up")$: `min_up` over $cal(E)$ +/ $upright("p")^(upright("max"))$: `p_max` over $cal(E)$, $infinity$ where the data has no row +/ $upright("p")^(upright("min"))$: `p_min` over $cal(E)$ / $upright("susceptance")$: `susceptance` over $cal(U) times cal(U)$, $0$ where the data has no row -/ $upright("tech_cap")$: `tech_cap` over $cal(U) times cal(E)$, `absent` where the data has no row +/ $upright("tech_cap")$: `tech_cap` over $cal(U) times cal(H)$, `absent` where the data has no row / $upright("zone_cap")$: `zone_cap` over $cal(Z)$ == Conditions -/ $upright("dispatchable")$: `dispatchable` over $cal(G)$ --- a unit that dispatches and cannot be turned down -/ $upright("priced_dispatch")$: `priced_dispatch` over $cal(G)$ +/ $upright("dispatchable")$: `dispatchable` over $cal(E)$ --- a unit that dispatches and cannot be turned down +/ $upright("priced_dispatch")$: `priced_dispatch` over $cal(E)$ == Variables -/ $italic("fuel")$: `fuel` over $cal(G) times cal(T)$ +/ $italic("fuel")$: `fuel` over $cal(E) times cal(T)$ / $italic("headroom")$: `headroom` (scalar), $0$ where the mask leaves it out -/ $italic("heat")$: `heat` over $cal(G) times cal(T)$ -/ $italic("on")$: `on` over $cal(G) times cal(T)$ -/ $italic("op_cost")$: `op_cost` over $cal(G) times cal(T)$ -/ $p$: `p` over $cal(G) times cal(T)$ +/ $italic("heat")$: `heat` over $cal(E) times cal(T)$ +/ $italic("on")$: `on` over $cal(E) times cal(T)$ +/ $italic("op_cost")$: `op_cost` over $cal(E) times cal(T)$ +/ $p$: `p` over $cal(E) times cal(T)$ / $italic("reserve")$: `reserve` (scalar) / $italic("site_out")$: `site_out` over $cal(I) times cal(T)$ / $italic("slack")$: `slack` over $cal(T)$ -/ $italic("spare")$: `spare` over $cal(G)$ +/ $italic("spare")$: `spare` over $cal(E)$ / $italic("spill")$: `spill` over $cal(T)$ / $theta$: `theta` over $cal(U)$ -/ $italic("units")$: `units` over $cal(G)$ -/ $italic("warm")$: `warm` over $cal(G) times cal(T)$ -/ $italic("weight")$: `weight` over $cal(G) times cal(T)$ +/ $italic("units")$: `units` over $cal(E)$ +/ $italic("warm")$: `warm` over $cal(E) times cal(T)$ +/ $italic("weight")$: `weight` over $cal(E) times cal(T)$ == Definitions / $italic("lcoe")$: `lcoe` (scalar) / $italic("marginal_price")$: `marginal_price` over $cal(U) times cal(T)$ / $italic("net")$: `net` over $cal(T)$ --- what a snapshot spills, less what it lacks -/ $upright("rating")$: `rating` over $cal(G) times cal(T)$ +/ $upright("rating")$: `rating` over $cal(E) times cal(T)$ / $italic("spend")$: `spend` over $cal(T)$ --- what a snapshot's dispatch costs -/ $upright("spend")^(upright("cap"))$: `spend_cap` over $cal(G)$ -/ $upright("startup_cost")$: `startup_cost` over $cal(G) times cal(T)$ --- what starting a unit in this snapshot costs, which the horizon's edge changes +/ $upright("spend")^(upright("cap"))$: `spend_cap` over $cal(E)$ +/ $upright("startup_cost")$: `startup_cost` over $cal(E) times cal(T)$ --- what starting a unit in this snapshot costs, which the horizon's edge changes == Notation / $t minus.o k$: `edge='wrap'` --- $t-k$, cyclic @@ -77,130 +79,130 @@ every character a notation escapes, set as text: link\_to, 100% & \#1 costs \$5 == Conditions #set math.equation(numbering: "(1)") -$ upright("dispatchable") & upright("dispatchable")_(g) & arrow.l.r.double.long upright("p")^(upright("max"))_(g) > 0 and not upright("is_flexible")_(g) & forall g in cal(G) \ - upright("priced_dispatch") & upright("priced_dispatch")_(g) & arrow.l.r.double.long upright("dispatchable")_(g) and upright("spend")^(upright("cap"))_(g) > 0 & forall g in cal(G) $ +$ upright("dispatchable") & upright("dispatchable")_(e) & arrow.l.r.double.long upright("p")^(upright("max"))_(e) > 0 and not upright("is_flexible")_(e) & forall e in cal(E) \ + upright("priced_dispatch") & upright("priced_dispatch")_(e) & arrow.l.r.double.long upright("dispatchable")_(e) and upright("spend")^(upright("cap"))_(e) > 0 & forall e in cal(E) $ == Variable domains #set math.equation(numbering: "(1)") -$ upright("fuel") & italic("fuel")_(g,t) & >= 0 & forall g in cal(G), t in cal(T) \ +$ upright("fuel") & italic("fuel")_(e,t) & >= 0 & forall e in cal(E), t in cal(T) \ upright("headroom") & italic("headroom") & >= 0 & upright("where ") upright("budget") upright(" is defined") \ - upright("heat") & italic("heat")_(g,t) & >= 0 & forall g in cal(G), t in cal(T) \ - upright("on") & italic("on")_(g,t) & in {0, 1} & forall g in cal(G), t in cal(T) \ - upright("op_cost") & italic("op_cost")_(g,t) & >= 0 & forall g in cal(G), t in cal(T) \ - upright("p") & upright("p")^(upright("min"))_(g) <= p_(g,t) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) colon upright("p")^(upright("max"))_(g) > 0 and not upright("is_flexible")_(g) or upright("p")^(upright("min"))_(g) > 0 \ + upright("heat") & italic("heat")_(e,t) & >= 0 & forall e in cal(E), t in cal(T) \ + upright("on") & italic("on")_(e,t) & in {0, 1} & forall e in cal(E), t in cal(T) \ + upright("op_cost") & italic("op_cost")_(e,t) & >= 0 & forall e in cal(E), t in cal(T) \ + upright("p") & upright("p")^(upright("min"))_(e) <= p_(e,t) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) colon upright("p")^(upright("max"))_(e) > 0 and not upright("is_flexible")_(e) or upright("p")^(upright("min"))_(e) > 0 \ upright("reserve") & italic("reserve") & >= 0 \ upright("site_out") & italic("site_out")_(i,t) & >= 0 & forall i in cal(I), t in cal(T) colon upright("is_flexible")_(upright("generator")(i)) \ upright("slack") & italic("slack")_(t) & <= 100 & forall t in cal(T) \ - upright("spare") & italic("spare")_(g) & in ZZ & forall g in cal(G) \ + upright("spare") & italic("spare")_(e) & in ZZ & forall e in cal(E) \ upright("spill") & italic("spill")_(t) & >= 0 & forall t in cal(T) \ upright("theta") & theta_(u) & in RR & forall u in cal(U) \ - upright("units") & 0 <= italic("units")_(g) & <= 10, italic("units")_(g) in ZZ & forall g in cal(G) \ - upright("warm") & italic("warm")_(g,t) & in {0, 1} & forall g in cal(G), t in cal(T) colon upright("is_flexible")_(g) \ - upright("weight") & 0 <= italic("weight")_(g,t) & <= 1 & forall g in cal(G), t in cal(T) $ + upright("units") & 0 <= italic("units")_(e) & <= 10, italic("units")_(e) in ZZ & forall e in cal(E) \ + upright("warm") & italic("warm")_(e,t) & in {0, 1} & forall e in cal(E), t in cal(T) colon upright("is_flexible")_(e) \ + upright("weight") & 0 <= italic("weight")_(e,t) & <= 1 & forall e in cal(E), t in cal(T) $ == Definitions #set math.equation(numbering: "(1)") -$ upright("lcoe") & italic("lcoe") & = frac(sum_(g in cal(G), t in cal(T)) p_(g,t) dot upright("cost")_(g), sum_(g in cal(G), t in cal(T)) p_(g,t)) \ +$ upright("lcoe") & italic("lcoe") & = frac(sum_(e in cal(E), t in cal(T)) p_(e,t) dot upright("cost")_(e), sum_(e in cal(E), t in cal(T)) p_(e,t)) \ upright("marginal_price") & italic("marginal_price")_(u,t) & = lambda_(upright("balance"),u,t) & forall u in cal(U), t in cal(T) \ upright("net") & italic("net")_(t) & = -italic("spill")_(t) + italic("slack")_(t) & forall t in cal(T) \ - upright("rating") & upright("rating")_(g,t) & = upright("eta")_(g) dot upright("p")^(upright("max"))_(g) dot (sum_(u in cal(U)) upright("load")_(u,t)) & forall g in cal(G), t in cal(T) \ - upright("spend") & italic("spend")_(t) & = sum_(g in cal(G)) p_(g,t) dot upright("cost")_(g) & forall t in cal(T) \ - upright("spend_cap") & upright("spend")^(upright("cap"))_(g) & = upright("cost")_(g) dot 2 & forall g in cal(G) \ - upright("startup_cost") & upright("startup_cost")_(g,t) & = cases(upright("cost")_(g) & upright("if ") upright("pos")(t) = 0, upright("cost")_(g) dot 2 & upright("if ") upright("pos")(t) > 0 and upright("season")(t) = upright("'winter'"), 0 & upright("otherwise")) & forall g in cal(G), t in cal(T) $ + upright("rating") & upright("rating")_(e,t) & = upright("eta")_(e) dot upright("p")^(upright("max"))_(e) dot (sum_(u in cal(U)) upright("load")_(u,t)) & forall e in cal(E), t in cal(T) \ + upright("spend") & italic("spend")_(t) & = sum_(e in cal(E)) p_(e,t) dot upright("cost")_(e) & forall t in cal(T) \ + upright("spend_cap") & upright("spend")^(upright("cap"))_(e) & = upright("cost")_(e) dot 2 & forall e in cal(E) \ + upright("startup_cost") & upright("startup_cost")_(e,t) & = cases(upright("cost")_(e) & upright("if ") upright("pos")(t) = 0, upright("cost")_(e) dot 2 & upright("if ") upright("pos")(t) > 0 and upright("season")(t) = upright("'winter'"), 0 & upright("otherwise")) & forall e in cal(E), t in cal(T) $ == Objective #set math.equation(numbering: "(1)") -$ & max & sum_(g in cal(G), t in cal(T)) p_(g,t) dot upright("cost")_(g) + sum_(g in cal(G), t in cal(T)) p_(g,t) dot p_(g,t) dot upright("cost")_(g) + sum_(g in cal(G), t in cal(T)) p_(g,t) dot upright("cost")_(g) dot upright("growth")^(upright("lead")_(g)) + sum_(g in cal(G), t in cal(T)) p_(g,t) dot (upright("growth")^(upright("lead")_(g)))^(2) + sum_(g in cal(G), t in cal(T)) p_(g,t) dot upright("p")^(upright("max"))_(g) - italic("reserve") - italic("headroom") $ +$ & max & sum_(e in cal(E), t in cal(T)) p_(e,t) dot upright("cost")_(e) + sum_(e in cal(E), t in cal(T)) p_(e,t) dot p_(e,t) dot upright("cost")_(e) + sum_(e in cal(E), t in cal(T)) p_(e,t) dot upright("cost")_(e) dot upright("growth")^(upright("lead")_(e)) + sum_(e in cal(E), t in cal(T)) p_(e,t) dot (upright("growth")^(upright("lead")_(e)))^(2) + sum_(e in cal(E), t in cal(T)) p_(e,t) dot upright("p")^(upright("max"))_(e) - italic("reserve") - italic("headroom") $ == Subject to #set math.equation(numbering: "(1)") -$ upright("ahead") & p_(g,t) & <= p_(g,t plus.o 1) & forall g in cal(G), t in cal(T) \ +$ upright("ahead") & p_(e,t) & <= p_(e,t plus.o 1) & forall e in cal(E), t in cal(T) \ upright("always") & italic("spill")_(t) & >= 0 & forall t in cal(T) \ - upright("arithmetic") & sum_(g in cal(G)) (frac(p_(g,t), 2) - upright("cost")_(g) + 10^(-5) dot p_(g,t) + 2.5 times 10^(-7) dot upright("cost")_(g) + 0.5 dot p_(g,t)) & >= -(sum_(g in cal(G)) p_(g,t)) dot (-3) & forall t in cal(T) \ - upright("balance") & sum_(g in cal(G) colon upright("bus")(g) = u) p_(g,t) + italic("spill")_(t) - italic("slack")_(t) & = upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ + upright("arithmetic") & sum_(e in cal(E)) (frac(p_(e,t), 2) - upright("cost")_(e) + 10^(-5) dot p_(e,t) + 2.5 times 10^(-7) dot upright("cost")_(e) + 0.5 dot p_(e,t)) & >= -(sum_(e in cal(E)) p_(e,t)) dot (-3) & forall t in cal(T) \ + upright("balance") & sum_(e in cal(E) colon upright("bus")(e) = u) p_(e,t) + italic("spill")_(t) - italic("slack")_(t) & = upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ upright("budgeted") & italic("spend")_(t) & <= upright("budget") & forall t in cal(T) \ - upright("capped") & p_(g,t) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) colon upright("spend")^(upright("cap"))_(g) > 0 or not upright("is_flexible")_(g) \ + upright("capped") & p_(e,t) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) colon upright("spend")^(upright("cap"))_(e) > 0 or not upright("is_flexible")_(e) \ upright("ceiling") & theta_(u) & <= infinity & forall u in cal(U) \ - upright("composed") & p_(g,t - 2) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ - upright("connected") & p_(g,t) & <= upright("load")_(u,t) & forall u in cal(U), g in cal(G), t in cal(T) colon (u, g) in upright("connection") \ - upright("counted") & theta_(u) & <= upright("budget") & forall u in cal(U) colon abs({e in cal(E) colon upright("tech_cap")_(u,e) > 0}) >= 2 \ - upright("counted_here") & theta_(u) & <= upright("tech_cap")_(u,e) & forall u in cal(U), e in cal(E) colon abs({e' in cal(E) colon upright("tech_cap")_(u,e') > 0}) >= 2 \ - upright("covered") & sum_(g in cal(G), t in cal(T)) p_(g,t) & <= upright("budget") & upright("where ") sum_(g in cal(G)) upright("p")^(upright("max"))_(g) >= upright("budget") \ - upright("crossed") & p_(g + 1,t minus.o 1) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ - upright("edges") & p_(g,t minus.square_(0) 1) & <= p_(g,t plus.square_(0) 1) + upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ - upright("efficiency") & p_(g,t) & <= upright("eta")_(g) dot upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ + upright("composed") & p_(e,t - 2) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ + upright("connected") & p_(e,t) & <= upright("load")_(u,t) & forall u in cal(U), e in cal(E), t in cal(T) colon (u, e) in upright("connection") \ + upright("counted") & theta_(u) & <= upright("budget") & forall u in cal(U) colon abs({h in cal(H) colon upright("tech_cap")_(u,h) > 0}) >= 2 \ + upright("counted_here") & theta_(u) & <= upright("tech_cap")_(u,h) & forall u in cal(U), h in cal(H) colon abs({h' in cal(H) colon upright("tech_cap")_(u,h') > 0}) >= 2 \ + upright("covered") & sum_(e in cal(E), t in cal(T)) p_(e,t) & <= upright("budget") & upright("where ") sum_(e in cal(E)) upright("p")^(upright("max"))_(e) >= upright("budget") \ + upright("crossed") & p_(e + 1,t minus.o 1) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ + upright("edges") & p_(e,t minus.square_(0) 1) & <= p_(e,t plus.square_(0) 1) + upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ + upright("efficiency") & p_(e,t) & <= upright("eta")_(e) dot upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ upright("exchanged") & theta_(u) & = sum_(u' in cal(U) colon u' = u) sum_(u'' in cal(U)) upright("susceptance")_(u'',u') & forall u in cal(U) \ - upright("first") & italic("on")_(g,t) & = 1 & forall g in cal(G), t in cal(T) colon upright("pos")(t) = 0 or upright("pos")_(upright("season")(t))(t) = 0 \ + upright("first") & italic("on")_(e,t) & = 1 & forall e in cal(E), t in cal(T) colon upright("pos")(t) = 0 or upright("pos")_(upright("season")(t))(t) = 0 \ upright("flow_angle") & theta_(u) & = sum_(u' in cal(U)) upright("susceptance")_(u,u') dot theta_(u') & forall u in cal(U) \ - upright("grouped_once") & sum_(g in cal(G) colon upright("bus")(g) = u and upright("technology")(g) = e) p_(g,t) & <= upright("tech_cap")_(u,e) & forall u in cal(U), t in cal(T), e in cal(E) \ - upright("held_in_season") & p_(g,t) & <= p_(g,t minus.square_(0)^(upright("season")(t)) 1) & forall g in cal(G), t in cal(T) \ - upright("history") & sum_(t' in cal(T) colon 0 <= t minus.o t' < upright("min_up")) italic("on")_(g,t') & <= italic("units")_(g) & forall g in cal(G), t in cal(T) \ - upright("in_season") & p_(g,t) & <= p_(g,t minus.o^(upright("season")(t)) 1) & forall g in cal(G), t in cal(T) \ - upright("last") & italic("on")_(g,t) & = 0 & forall g in cal(G), t in cal(T) colon upright("pos")(t) = abs(cal(T)) - 1 or upright("pos")_(upright("season")(t))(t) = abs(cal(T)_(upright("season")(t))) - 1 \ - upright("lead_time") & p_(g,t minus.square_(0) upright("lead")) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ - upright("looked_up_once") & italic("units")_(g) & <= upright("tech_cap")_(upright("bus")(g),upright("technology")(g)) & forall g in cal(G) \ + upright("grouped_once") & sum_(e in cal(E) colon upright("bus")(e) = u and upright("technology")(e) = h) p_(e,t) & <= upright("tech_cap")_(u,h) & forall u in cal(U), t in cal(T), h in cal(H) \ + upright("held_in_season") & p_(e,t) & <= p_(e,t minus.square_(0)^(upright("season")(t)) 1) & forall e in cal(E), t in cal(T) \ + upright("history") & sum_(t' in cal(T) colon 0 <= t minus.o t' < upright("min_up")) italic("on")_(e,t') & <= italic("units")_(e) & forall e in cal(E), t in cal(T) \ + upright("in_season") & p_(e,t) & <= p_(e,t minus.o^(upright("season")(t)) 1) & forall e in cal(E), t in cal(T) \ + upright("last") & italic("on")_(e,t) & = 0 & forall e in cal(E), t in cal(T) colon upright("pos")(t) = abs(cal(T)) - 1 or upright("pos")_(upright("season")(t))(t) = abs(cal(T)_(upright("season")(t))) - 1 \ + upright("lead_time") & p_(e,t minus.square_(0) upright("lead")) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ + upright("looked_up_once") & italic("units")_(e) & <= upright("tech_cap")_(upright("bus")(e),upright("technology")(e)) & forall e in cal(E) \ upright("lookup") & italic("spill")_(t) & <= upright("zone_cap")_(upright("zone")(u)) & forall u in cal(U), t in cal(T) \ - upright("margin") & p_(g,t) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) colon upright("p")^(upright("max"))_(g) - upright("p")^(upright("min"))_(g) > frac(upright("cost")_(g), 2) \ - upright("masked") & p_(g,t) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) colon upright("priced_dispatch")_(g) and upright("pos")(t) > 0 \ - upright("netted") & sum_(g in cal(G) colon upright("bus")(g) = u) p_(g,t) + italic("net")_(t) & = upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ + upright("margin") & p_(e,t) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) colon upright("p")^(upright("max"))_(e) - upright("p")^(upright("min"))_(e) > frac(upright("cost")_(e), 2) \ + upright("masked") & p_(e,t) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) colon upright("priced_dispatch")_(e) and upright("pos")(t) > 0 \ + upright("netted") & sum_(e in cal(E) colon upright("bus")(e) = u) p_(e,t) + italic("net")_(t) & = upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ upright("never") & italic("slack")_(t) & >= 0 & forall t in cal(T) colon bot \ upright("northern") & italic("slack")_(t) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) colon upright("zone")(u) = upright("'north'") and upright("zone")(u) != upright("area")(u) and upright("area")(u) upright(" is defined") \ - upright("ramp") & p_(g,t) - p_(g,t minus.o 1) & <= p_(g,t - 1) + upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ + upright("ramp") & p_(e,t) - p_(e,t minus.o 1) & <= p_(e,t - 1) + upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ upright("ramped") & italic("slack")_(t) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) colon upright("load")_(u,t) - upright("load")_(u,t minus.square_(0) 1) <= upright("zone_cap")_(upright("zone")(u)) and upright("pos")(t) > 0 \ upright("redundant") & italic("spill")_(t) & >= 0 & forall t in cal(T) colon italic("spill")_(t) upright(" exists") \ - upright("relational") & sum_(g in cal(G) colon (u, g) in upright("connection")) p_(g,t) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ + upright("relational") & sum_(c in cal(C) colon upright("bus")(c) = u) p_(upright("generator")(c),t) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) \ upright("representative") & sum_(t' in cal(T) colon upright("rep")(t') = t) italic("spill")_(t') & <= italic("spill")_(upright("rep")(t)) & forall t in cal(T) \ upright("run_start") & italic("slack")_(t) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) colon upright("load")_(u,t) upright(" is defined") and not (upright("load")_(u,t - 1) upright(" is defined")) \ upright("running") & theta_(u) & <= upright("load")_(u,t) & forall u in cal(U), t in cal(T) colon theta_(u) upright(" exists") and t >= 3 \ - upright("scalar") & italic("units")_(g) & <= upright("budget") & forall g in cal(G) colon upright("cost")_(g) upright(" is defined") \ - upright("seasonal_window") & sum_(t' in cal(T) colon 0 <= t -^(upright("season")(t)) t' < 3) italic("on")_(g,t') & <= italic("units")_(g) & forall g in cal(G), t in cal(T) \ - upright("starts") & p_(g,t) & <= upright("startup_cost")_(g,t) & forall g in cal(G), t in cal(T) \ - upright("total") & sum_(g in cal(G), t in cal(T)) p_(g,t) & <= upright("budget") \ - upright("uncomposed") & p_(g,(t - 1) minus.square_(0) upright("lead")) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G), t in cal(T) \ - upright("under_rating") & p_(g,t) & <= upright("rating")_(g,t) & forall g in cal(G), t in cal(T) \ - upright("window") & sum_(t' in cal(T) colon 0 <= t - t' < 3) italic("on")_(g,t') & <= italic("units")_(g) & forall g in cal(G), t in cal(T) \ - upright("within_bus") & italic("units")_(g) & <= italic("units")_(g minus.square_(0)^(upright("bus")(g)) 1) & forall g in cal(G) colon upright("pos")_((upright("bus")(g), upright("technology")(g)))(g) = 0 \ - upright("zonal") & sum_(g in cal(G) colon upright("zone")(g, t) = z) p_(g,t) & <= upright("zone_cap")_(z) & forall t in cal(T), z in cal(Z) \ - upright("zonal_history") & sum_(t in cal(T) colon upright("zone")(g, t) = z) p_(g,t) & <= upright("zone_cap")_(z) & forall g in cal(G), z in cal(Z) \ - upright("zonal_lookup") & p_(g,t) & <= italic("spill")_(t) dot upright("zone_cap")_(upright("zone")(g, t)) & forall g in cal(G), t in cal(T) colon upright("zone")(g, t) = upright("'north'") and upright("pos")_(upright("zone")(g, t))(g) = 0 \ - upright("zonal_membership") & sum_(g in cal(G) colon (g, t) in upright("gen_zone")) italic("units")_(g) & <= upright("budget") & forall t in cal(T) \ + upright("scalar") & italic("units")_(e) & <= upright("budget") & forall e in cal(E) colon upright("cost")_(e) upright(" is defined") \ + upright("seasonal_window") & sum_(t' in cal(T) colon 0 <= t -^(upright("season")(t)) t' < 3) italic("on")_(e,t') & <= italic("units")_(e) & forall e in cal(E), t in cal(T) \ + upright("starts") & p_(e,t) & <= upright("startup_cost")_(e,t) & forall e in cal(E), t in cal(T) \ + upright("total") & sum_(e in cal(E), t in cal(T)) p_(e,t) & <= upright("budget") \ + upright("uncomposed") & p_(e,(t - 1) minus.square_(0) upright("lead")) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E), t in cal(T) \ + upright("under_rating") & p_(e,t) & <= upright("rating")_(e,t) & forall e in cal(E), t in cal(T) \ + upright("window") & sum_(t' in cal(T) colon 0 <= t - t' < 3) italic("on")_(e,t') & <= italic("units")_(e) & forall e in cal(E), t in cal(T) \ + upright("within_bus") & italic("units")_(e) & <= italic("units")_(e minus.square_(0)^(upright("bus")(e)) 1) & forall e in cal(E) colon upright("pos")_((upright("bus")(e), upright("technology")(e)))(e) = 0 \ + upright("zonal") & sum_(g in cal(G) colon upright("snapshot")(g) = t and upright("zone")(g) = z) p_(upright("generator")(g),upright("snapshot")(g)) & <= upright("zone_cap")_(z) & forall t in cal(T), z in cal(Z) \ + upright("zonal_history") & sum_(g in cal(G) colon upright("generator")(g) = e and upright("zone")(g) = z) p_(upright("generator")(g),upright("snapshot")(g)) & <= upright("zone_cap")_(z) & forall e in cal(E), z in cal(Z) \ + upright("zonal_lookup") & p_(upright("generator")(g),upright("snapshot")(g)) & <= italic("spill")_(upright("snapshot")(g)) dot upright("zone_cap")_(upright("zone")(g)) & forall g in cal(G) colon upright("zone")(g) = upright("'north'") \ + upright("zonal_membership") & sum_(g in cal(G) colon upright("snapshot")(g) = t) italic("units")_(upright("generator")(g)) & <= upright("budget") & forall t in cal(T) \ upright("zoned") & theta_(u) & <= upright("budget") & forall u in cal(U) colon upright("zone_cap")_(upright("zone")(u)) upright(" is defined") \ - upright("adjacent") & (italic("weight")_(g,t))_(g in cal(G)) & in upright("SOS")2 & forall t in cal(T) \ - upright("bus_curve") & (p_(g,t))_(g in cal(G) colon upright("bus")(g) = u) & in upright("pwl")_(b in cal(B))((upright("bp_x")_(b,g))_(g in cal(G) colon upright("bus")(g) = u)) & forall u in cal(U), t in cal(T) colon upright("load")_(u,t) upright(" is defined") \ - upright("chp_curve") & (p_(g,t), italic("fuel")_(g,t), italic("heat")_(g,t)) & in upright("pwl")_(b in cal(B))(upright("bp_x")_(b,g), upright("bp_y")_(b,g), upright("bp_heat")_(b,g)) + {0} times RR_(>= 0) times RR_(<= 0) & forall g in cal(G), t in cal(T) \ - upright("cost_curve") & italic("op_cost")_(g,t) & >= cases(italic("warm")_(g,t) & upright("if ") upright("is_flexible")_(g), 1 & upright("otherwise")) dot upright("pwl")_(b in cal(B) colon upright("bp_run")_(b,g))(upright("bp_x")_(b,g), upright("bp_y")_(b,g))(p_(g,t)) & forall g in cal(G), t in cal(T) \ - upright("fuel_curve") & (p_(g,t), italic("fuel")_(g,t), italic("heat")_(g,t)) & in italic("on")_(g,t) dot upright("pwl")_(b in cal(B))(upright("bp_x")_(b,g), upright("bp_y")_(b,g), upright("bp_heat")_(b,g)) & forall g in cal(G), t in cal(T) \ - upright("hull_curve") & (p_(g,t), italic("fuel")_(g,t)) & in upright("conv")_(b in cal(B))(upright("bp_x")_(b,g), upright("bp_heat")_(b,g)) & forall g in cal(G), t in cal(T) \ - upright("lp_curve") & italic("fuel")_(g,t) & >= upright("pwl")_(b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined"))(upright("bp_x")_(b,g), upright("bp_y")_(b,g))(p_(g,t)) & forall g in cal(G), t in cal(T) \ - upright("module_curve") & italic("fuel")_(g,t) & >= (italic("units")_(g) dot (upright("bp_x")_(min {b in cal(B) colon upright("bp_run")_(b,g)},g), upright("bp_y")_(min {b in cal(B) colon upright("bp_run")_(b,g)},g)) + min(italic("units")_(g), 1) dot (upright("pwl")_(b in cal(B) colon upright("bp_run")_(b,g))(upright("bp_x")_(b,g), upright("bp_y")_(b,g)) - (upright("bp_x")_(min {b in cal(B) colon upright("bp_run")_(b,g)},g), upright("bp_y")_(min {b in cal(B) colon upright("bp_run")_(b,g)},g))))(p_(g,t)) & forall g in cal(G), t in cal(T) \ - upright("ramp_curve") & italic("heat")_(g,t) & <= upright("pwl")_(b in cal(B))(upright("bp_x")_(b,g), upright("bp_heat")_(b,g))(p_(g,t)) & forall g in cal(G), t in cal(T) $ + upright("adjacent") & (italic("weight")_(e,t))_(e in cal(E)) & in upright("SOS")2 & forall t in cal(T) \ + upright("bus_curve") & (p_(e,t))_(e in cal(E) colon upright("bus")(e) = u) & in upright("pwl")_(b in cal(B))((upright("bp_x")_(b,e))_(e in cal(E) colon upright("bus")(e) = u)) & forall u in cal(U), t in cal(T) colon upright("load")_(u,t) upright(" is defined") \ + upright("chp_curve") & (p_(e,t), italic("fuel")_(e,t), italic("heat")_(e,t)) & in upright("pwl")_(b in cal(B))(upright("bp_x")_(b,e), upright("bp_y")_(b,e), upright("bp_heat")_(b,e)) + {0} times RR_(>= 0) times RR_(<= 0) & forall e in cal(E), t in cal(T) \ + upright("cost_curve") & italic("op_cost")_(e,t) & >= cases(italic("warm")_(e,t) & upright("if ") upright("is_flexible")_(e), 1 & upright("otherwise")) dot upright("pwl")_(b in cal(B) colon upright("bp_run")_(b,e))(upright("bp_x")_(b,e), upright("bp_y")_(b,e))(p_(e,t)) & forall e in cal(E), t in cal(T) \ + upright("fuel_curve") & (p_(e,t), italic("fuel")_(e,t), italic("heat")_(e,t)) & in italic("on")_(e,t) dot upright("pwl")_(b in cal(B))(upright("bp_x")_(b,e), upright("bp_y")_(b,e), upright("bp_heat")_(b,e)) & forall e in cal(E), t in cal(T) \ + upright("hull_curve") & (p_(e,t), italic("fuel")_(e,t)) & in upright("conv")_(b in cal(B))(upright("bp_x")_(b,e), upright("bp_heat")_(b,e)) & forall e in cal(E), t in cal(T) \ + upright("lp_curve") & italic("fuel")_(e,t) & >= upright("pwl")_(b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined"))(upright("bp_x")_(b,e), upright("bp_y")_(b,e))(p_(e,t)) & forall e in cal(E), t in cal(T) \ + upright("module_curve") & italic("fuel")_(e,t) & >= (italic("units")_(e) dot (upright("bp_x")_(min {b in cal(B) colon upright("bp_run")_(b,e)},e), upright("bp_y")_(min {b in cal(B) colon upright("bp_run")_(b,e)},e)) + min(italic("units")_(e), 1) dot (upright("pwl")_(b in cal(B) colon upright("bp_run")_(b,e))(upright("bp_x")_(b,e), upright("bp_y")_(b,e)) - (upright("bp_x")_(min {b in cal(B) colon upright("bp_run")_(b,e)},e), upright("bp_y")_(min {b in cal(B) colon upright("bp_run")_(b,e)},e))))(p_(e,t)) & forall e in cal(E), t in cal(T) \ + upright("ramp_curve") & italic("heat")_(e,t) & <= upright("pwl")_(b in cal(B))(upright("bp_x")_(b,e), upright("bp_heat")_(b,e))(p_(e,t)) & forall e in cal(E), t in cal(T) $ == Assumptions #set math.equation(numbering: "(1)") -$ upright("bounds_do_not_cross") & upright("p")^(upright("min"))_(g) & <= upright("p")^(upright("max"))_(g) & forall g in cal(G) \ - upright("budget_covers_the_peak") & sum_(g in cal(G)) upright("p")^(upright("max"))_(g) & >= upright("budget") \ - upright("efficiency_is_a_fraction") & upright("eta")_(g) > 0 and upright("eta")_(g) <= 1 & & forall g in cal(G) \ - upright("flexible_units_have_headroom") & upright("p")^(upright("min"))_(g) & < upright("p")^(upright("max"))_(g) & forall g in cal(G) colon upright("is_flexible")_(g) \ - upright("lead_times_are_short") & upright("lead")_(g) & <= 3 & forall g in cal(G) \ +$ upright("bounds_do_not_cross") & upright("p")^(upright("min"))_(e) & <= upright("p")^(upright("max"))_(e) & forall e in cal(E) \ + upright("budget_covers_the_peak") & sum_(e in cal(E)) upright("p")^(upright("max"))_(e) & >= upright("budget") \ + upright("efficiency_is_a_fraction") & upright("eta")_(e) > 0 and upright("eta")_(e) <= 1 & & forall e in cal(E) \ + upright("flexible_units_have_headroom") & upright("p")^(upright("min"))_(e) & < upright("p")^(upright("max"))_(e) & forall e in cal(E) colon upright("is_flexible")_(e) \ + upright("lead_times_are_short") & upright("lead")_(e) & <= 3 & forall e in cal(E) \ upright("northern_demand_is_real") & upright("load")_(u,t) & >= 0 & forall u in cal(U), t in cal(T) colon upright("zone")(u) = upright("'north'") \ upright("ramps_are_gentle") & upright("load")_(u,t) - upright("load")_(u,t minus.square_(0) 1) & <= upright("budget") & forall u in cal(U), t in cal(T) colon upright("pos")(t) > 0 \ upright("zones_agree") & upright("zone")(u) & = upright("area")(u) & forall u in cal(U) \ - upright("bus_curve_p_complete") & upright("bp_x")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G), t in cal(T) colon upright("load")_(upright("bus")(g),t) upright(" is defined") \ - upright("chp_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_y")_(b,g) upright(" is defined") and upright("bp_heat")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) \ - upright("cost_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_y")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) colon upright("bp_run")_(b,g) \ - upright("cost_curve_contiguous") & abs({b in cal(B) colon upright("bp_run")_(b,g) and not upright("bp_run")_(b - 1,g)}) & = 1 & forall g in cal(G) colon abs({b in cal(B) colon upright("bp_run")_(b,g)}) > 0 \ - upright("fuel_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_y")_(b,g) upright(" is defined") and upright("bp_heat")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) \ - upright("hull_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_heat")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) \ - upright("hull_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,g) & < upright("bp_x")_(b,g) & forall b in cal(B), g in cal(G) colon upright("pos")(b) > 0 \ - upright("hull_curve_curvature") & abs({b in cal(B) colon (upright("bp_heat")_(b,g) - upright("bp_heat")_(b minus.square_(0) 1,g)) dot (upright("bp_x")_(b plus.square_(0) 1,g) - upright("bp_x")_(b,g)) > (upright("bp_heat")_(b plus.square_(0) 1,g) - upright("bp_heat")_(b,g)) dot (upright("bp_x")_(b,g) - upright("bp_x")_(b minus.square_(0) 1,g)) and upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1}) = 0 or abs({b in cal(B) colon (upright("bp_heat")_(b,g) - upright("bp_heat")_(b minus.square_(0) 1,g)) dot (upright("bp_x")_(b plus.square_(0) 1,g) - upright("bp_x")_(b,g)) < (upright("bp_heat")_(b plus.square_(0) 1,g) - upright("bp_heat")_(b,g)) dot (upright("bp_x")_(b,g) - upright("bp_x")_(b minus.square_(0) 1,g)) and upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1}) = 0 & & forall g in cal(G) \ - upright("lp_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_y")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) colon upright("bp_x")_(b,g) upright(" is defined") \ - upright("lp_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,g) & < upright("bp_x")_(b,g) & forall b in cal(B), g in cal(G) colon upright("bp_x")_(b,g) upright(" is defined") and upright("bp_x")_(b - 1,g) upright(" is defined") \ - upright("lp_curve_curvature") & (upright("bp_y")_(b,g) - upright("bp_y")_(b minus.square_(0) 1,g)) dot (upright("bp_x")_(b plus.square_(0) 1,g) - upright("bp_x")_(b,g)) & <= (upright("bp_y")_(b plus.square_(0) 1,g) - upright("bp_y")_(b,g)) dot (upright("bp_x")_(b,g) - upright("bp_x")_(b minus.square_(0) 1,g)) & forall b in cal(B), g in cal(G) colon upright("bp_x")_(b,g) upright(" is defined") and upright("bp_x")_(b - 1,g) upright(" is defined") and upright("bp_x")_(b + 1,g) upright(" is defined") \ - upright("lp_curve_breakpoints") & abs({b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined")}) & >= 2 & forall g in cal(G) colon abs({b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined")}) > 0 \ - upright("lp_curve_contiguous") & abs({b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined") and not (upright("bp_x")_(b - 1,g) upright(" is defined"))}) & = 1 & forall g in cal(G) colon abs({b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined")}) > 0 \ - upright("module_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_y")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) colon upright("bp_run")_(b,g) \ - upright("module_curve_contiguous") & abs({b in cal(B) colon upright("bp_run")_(b,g) and not upright("bp_run")_(b - 1,g)}) & = 1 & forall g in cal(G) colon abs({b in cal(B) colon upright("bp_run")_(b,g)}) > 0 \ - upright("ramp_curve_complete") & upright("bp_x")_(b,g) upright(" is defined") and upright("bp_heat")_(b,g) upright(" is defined") & & forall b in cal(B), g in cal(G) \ - upright("ramp_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,g) & < upright("bp_x")_(b,g) & forall b in cal(B), g in cal(G) colon upright("pos")(b) > 0 \ - upright("ramp_curve_curvature") & (upright("bp_heat")_(b,g) - upright("bp_heat")_(b minus.square_(0) 1,g)) dot (upright("bp_x")_(b plus.square_(0) 1,g) - upright("bp_x")_(b,g)) & >= (upright("bp_heat")_(b plus.square_(0) 1,g) - upright("bp_heat")_(b,g)) dot (upright("bp_x")_(b,g) - upright("bp_x")_(b minus.square_(0) 1,g)) & forall b in cal(B), g in cal(G) colon upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1 \ - upright("ramp_curve_breakpoints") & abs({b in cal(B) colon upright("bp_x")_(b,g) upright(" is defined")}) & >= 2 & forall g in cal(G) $ + upright("bus_curve_p_complete") & upright("bp_x")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E), t in cal(T) colon upright("load")_(upright("bus")(e),t) upright(" is defined") \ + upright("chp_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_y")_(b,e) upright(" is defined") and upright("bp_heat")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) \ + upright("cost_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_y")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) colon upright("bp_run")_(b,e) \ + upright("cost_curve_contiguous") & abs({b in cal(B) colon upright("bp_run")_(b,e) and not upright("bp_run")_(b - 1,e)}) & = 1 & forall e in cal(E) colon abs({b in cal(B) colon upright("bp_run")_(b,e)}) > 0 \ + upright("fuel_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_y")_(b,e) upright(" is defined") and upright("bp_heat")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) \ + upright("hull_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_heat")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) \ + upright("hull_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,e) & < upright("bp_x")_(b,e) & forall b in cal(B), e in cal(E) colon upright("pos")(b) > 0 \ + upright("hull_curve_curvature") & abs({b in cal(B) colon (upright("bp_heat")_(b,e) - upright("bp_heat")_(b minus.square_(0) 1,e)) dot (upright("bp_x")_(b plus.square_(0) 1,e) - upright("bp_x")_(b,e)) > (upright("bp_heat")_(b plus.square_(0) 1,e) - upright("bp_heat")_(b,e)) dot (upright("bp_x")_(b,e) - upright("bp_x")_(b minus.square_(0) 1,e)) and upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1}) = 0 or abs({b in cal(B) colon (upright("bp_heat")_(b,e) - upright("bp_heat")_(b minus.square_(0) 1,e)) dot (upright("bp_x")_(b plus.square_(0) 1,e) - upright("bp_x")_(b,e)) < (upright("bp_heat")_(b plus.square_(0) 1,e) - upright("bp_heat")_(b,e)) dot (upright("bp_x")_(b,e) - upright("bp_x")_(b minus.square_(0) 1,e)) and upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1}) = 0 & & forall e in cal(E) \ + upright("lp_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_y")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) colon upright("bp_x")_(b,e) upright(" is defined") \ + upright("lp_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,e) & < upright("bp_x")_(b,e) & forall b in cal(B), e in cal(E) colon upright("bp_x")_(b,e) upright(" is defined") and upright("bp_x")_(b - 1,e) upright(" is defined") \ + upright("lp_curve_curvature") & (upright("bp_y")_(b,e) - upright("bp_y")_(b minus.square_(0) 1,e)) dot (upright("bp_x")_(b plus.square_(0) 1,e) - upright("bp_x")_(b,e)) & <= (upright("bp_y")_(b plus.square_(0) 1,e) - upright("bp_y")_(b,e)) dot (upright("bp_x")_(b,e) - upright("bp_x")_(b minus.square_(0) 1,e)) & forall b in cal(B), e in cal(E) colon upright("bp_x")_(b,e) upright(" is defined") and upright("bp_x")_(b - 1,e) upright(" is defined") and upright("bp_x")_(b + 1,e) upright(" is defined") \ + upright("lp_curve_breakpoints") & abs({b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined")}) & >= 2 & forall e in cal(E) colon abs({b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined")}) > 0 \ + upright("lp_curve_contiguous") & abs({b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined") and not (upright("bp_x")_(b - 1,e) upright(" is defined"))}) & = 1 & forall e in cal(E) colon abs({b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined")}) > 0 \ + upright("module_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_y")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) colon upright("bp_run")_(b,e) \ + upright("module_curve_contiguous") & abs({b in cal(B) colon upright("bp_run")_(b,e) and not upright("bp_run")_(b - 1,e)}) & = 1 & forall e in cal(E) colon abs({b in cal(B) colon upright("bp_run")_(b,e)}) > 0 \ + upright("ramp_curve_complete") & upright("bp_x")_(b,e) upright(" is defined") and upright("bp_heat")_(b,e) upright(" is defined") & & forall b in cal(B), e in cal(E) \ + upright("ramp_curve_increasing") & upright("bp_x")_(b minus.square_(0) 1,e) & < upright("bp_x")_(b,e) & forall b in cal(B), e in cal(E) colon upright("pos")(b) > 0 \ + upright("ramp_curve_curvature") & (upright("bp_heat")_(b,e) - upright("bp_heat")_(b minus.square_(0) 1,e)) dot (upright("bp_x")_(b plus.square_(0) 1,e) - upright("bp_x")_(b,e)) & >= (upright("bp_heat")_(b plus.square_(0) 1,e) - upright("bp_heat")_(b,e)) dot (upright("bp_x")_(b,e) - upright("bp_x")_(b minus.square_(0) 1,e)) & forall b in cal(B), e in cal(E) colon upright("pos")(b) > 0 and upright("pos")(b) != abs(cal(B)) - 1 \ + upright("ramp_curve_breakpoints") & abs({b in cal(B) colon upright("bp_x")_(b,e) upright(" is defined")}) & >= 2 & forall e in cal(E) $ diff --git a/tests/typesetting/test_formats.py b/tests/typesetting/test_formats.py index 5ed41fa4f..ff795f2fd 100644 --- a/tests/typesetting/test_formats.py +++ b/tests/typesetting/test_formats.py @@ -66,7 +66,7 @@ def test_markdown_delimits_math_the_one_way_github_hands_over_verbatim(): md = typeset(golden.MODEL, 'markdown', standalone=True) assert _math_spans(md), 'the golden model prints math to scan' assert r'$\mathrm' not in md and '$$' not in md, 'no span is left in the pair GitHub reaches into' - assert r'\mathrm{gen\_zone}' in md, 'the escape TeX needs survives, because nothing is going to eat it' + assert r'\mathrm{is\_flexible}' in md, 'the escape TeX needs survives, because nothing is going to eat it' @pytest.mark.parametrize('entry', sorted(_ENTRIES), ids=sorted(_ENTRIES)) diff --git a/tests/typesetting/test_walk.py b/tests/typesetting/test_walk.py index 0c9b3fcc8..4d850e165 100644 --- a/tests/typesetting/test_walk.py +++ b/tests/typesetting/test_walk.py @@ -658,8 +658,8 @@ def test_every_operator_probe_renders(path, name: FormatName, fmt: Format): # --------------------------------------------------------------------------- -#: Two tables a call can leave a map unread. A sum between `gen_zone`'s own -#: two columns reads no map at all, and a sum that consumes one of +#: Two tables a call can leave a map unread. A sum over `zone_of` grouped by +#: a member reads no declared map, and a sum that consumes one of #: `generator`'s two maps leaves the other one. UNREAD = { 'dimensions': { @@ -668,17 +668,17 @@ def test_every_operator_probe_renders(path, name: FormatName, fmt: Format): 'zone': {'dtype': 'str'}, 'bus': {'dtype': 'str'}, 'technology': {'dtype': 'str'}, + 'zone_of': {'over': ['generator', 'snapshot'], 'missing': 'refused'}, }, - 'relations': {'gen_zone': {'dims': ['generator', 'snapshot']}}, 'maps': { - 'gen_zone': {'zone': {'dim': 'zone'}}, + 'zone_of': {'zone': {'dim': 'zone'}}, 'generator': {'bus': {'dim': 'bus'}, 'technology': {'dim': 'technology'}}, }, 'parameters': {'cap': {'dims': []}}, 'variables': { 'p': {'dims': ['snapshot', 'generator']}, 'f': {'dims': ['generator', 'bus']}, - # indexed by the column of gen_zone the sum consumes alone, so the column it lands on is one it brings + # indexed by the member of zone_of the sum reads it at 'u': {'dims': ['generator']}, }, } @@ -690,18 +690,15 @@ def _grouped(dims: list[str], expression: str) -> str: return next(line for line in to_latex(model, legend=False).splitlines() if line.startswith(r'\text{c}')) -def test_a_sum_that_reads_no_map_asks_only_that_the_relation_has_the_row(): - """`sum(u, over=generator, by=gen_zone[snapshot])` died with `KeyError: 'zone'`. +def test_a_sum_that_reads_no_map_asks_only_for_the_member_it_groups_by(): + """A sum through a relation's own two columns died with `KeyError: 'zone'`, the map it did not read. - The domain was written as a whole row of the table, which needs an index - for every column, and this sum goes between the relation's own two - columns: it reads no map, so there is no index to write in `zone`'s place. - What the sum asks of the relation is that it has the row at all. + The sum over the tuple groups by a member and reads no declared map, so + the map `zone` is written nowhere. """ - row = _grouped(['snapshot'], 'sum(u, over=generator, by=gen_zone[snapshot]) <= cap') - assert r'\sum_{g \in \mathcal{G} \,:\, \left( g,\ t \right) \in \mathrm{gen\_zone}}' in row, ( - 'the condition is that the row is in the relation, and the unread map is written nowhere' - ) + row = _grouped(['snapshot'], 'sum(at(u, by=zone_of[generator]), over=zone_of, by=zone_of[snapshot]) <= cap') + assert r'\mathrm{snapshot}(o) = t' in row, 'the condition is the member the sum groups by' + assert 'zone(' not in row.replace('zone\\_of', ''), 'the unread map is written nowhere' def test_a_map_the_call_consumes_is_a_condition_like_a_produced_one(): @@ -753,7 +750,7 @@ def _row(expression: str, where: str | None = None, **patch: object) -> str: pytest.param( 'p == at(sum(q, over=generator, by=generator[bus]), by=generator[bus])', r"\sum_{g' \in \mathcal{G} \,:\, \mathrm{bus}(g') = \mathrm{bus}(g)} q_{g',t}", - id='grouped-by-a-relation', + id='grouped-by-a-subject', ), pytest.param('p == q - sum(q, over=generator)', r"\sum_{g' \in \mathcal{G}} q_{g',t}", id='over-the-whole-dim'), ], diff --git a/tools/notation.py b/tools/notation.py index c254688cf..cdc6e5a0e 100644 --- a/tools/notation.py +++ b/tools/notation.py @@ -47,7 +47,7 @@ } BEGIN, END = '', '' -#: The sections of the fixture that declare math. ``dimensions``, ``relations``, +#: The sections of the fixture that declare math. ``dimensions``, #: ``maps`` and ``parameters`` are absent on purpose: they declare no equation, and what #: they print is the legend, which the page shows once rather than a row at a #: time. @@ -81,22 +81,22 @@ 'Objective': { 'objective': 'Products and powers in the objective', }, - 'Relations and maps': { + 'Maps and tuples': { 'balance': 'Sum through a map', 'total': 'Sum over every dimension', 'lookup': '`at` through a map', 'grouped_once': 'Sum into two maps', 'looked_up_once': '`at` through two maps', 'within_bus': 'Shift within one map', - 'relational': 'Sum through a relation', - 'connected': 'Relation as a condition', + 'relational': 'Sum over a tuple', + 'connected': 'Tuple as a condition', 'representative': 'Map into its own dimension', 'flow_angle': 'Alias of a dimension', 'exchanged': 'Sum under an alias of its dimension', - 'zonal': 'Sum through a map of a relation', - 'zonal_history': 'Sum over the other column of a relation', - 'zonal_membership': 'Sum between the two columns of a relation', - 'zonal_lookup': '`at` through a map of a relation', + 'zonal': 'Sum through a map of a tuple', + 'zonal_history': 'Sum keeping the other member of a tuple', + 'zonal_membership': 'Sum grouped by one member of a tuple', + 'zonal_lookup': '`at` through a map of a tuple', }, 'Arithmetic and literals': { 'arithmetic': 'Signs, division and number literals', @@ -298,11 +298,11 @@ def legend() -> str: #: What the legend is made of. No equation comes from these, so they are shown #: once, together, above the tables they turn into. -DECLARED = ('dimensions', 'relations', 'maps', 'parameters') +DECLARED = ('dimensions', 'maps', 'parameters') def preamble(text: str) -> str: - """The fixture's ``dimensions``/``relations``/``maps``/``parameters`` sections, verbatim.""" + """The fixture's ``dimensions``/``maps``/``parameters`` sections, verbatim.""" sections = [] for name in DECLARED: body = text[text.index(f'\n{name}:') + 1 :] @@ -316,8 +316,7 @@ def block() -> str: rendered = to_markdown(MODEL, numbered=False) parts = [ '### Legend', - 'A dimension, a relation, a map and a parameter declare no equation; what they ' - 'print is the legend every spec opens with.', + 'A dimension, a map and a parameter declare no equation; what they print is the legend every spec opens with.', f'```yaml\n{preamble(MODEL.read_text())}\n```', legend(), ] diff --git a/tools/pypsa_split.py b/tools/pypsa_split.py index 20bdbac6f..f920b9776 100644 --- a/tools/pypsa_split.py +++ b/tools/pypsa_split.py @@ -54,7 +54,6 @@ SOURCE = Path('examples/pypsa.yaml') SECTIONS = ( 'dimensions', - 'relations', 'maps', 'parameters', 'variables', @@ -64,7 +63,7 @@ 'constraints', 'assumptions', ) -FRAME = ('dimensions', 'relations', 'maps') +FRAME = ('dimensions', 'maps') IDENT = re.compile(r'[A-Za-z_][A-Za-z0-9_]*') READ = re.compile(r'(? None: if s not in ('maps', 'piecewise', 'constraints', 'assumptions') for n in self.data.get(s, {}) } - #: Every subject with maps. A subject shares its name with its dimension or relation, so it is not in `kind`. + #: Every subject with maps. A subject shares its name with its dimension, so it is not in `kind`. self.subjects = set(self.data.get('maps', {})) #: hub -> the topic of each term -> the term, in the order the topics sort in. self.shares: dict[str, dict[str, str]] = {}