From 04e9b852539f992ea8a910cbcbad7c44b3ddf856 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 16:32:01 +0000 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 3e32778efa847597de611a71391b4ef956db4a66 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 19:48:52 +0000 Subject: [PATCH 5/6] 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:. Two dimensions over different aliases of one dimension share no member, so the alias is the opt-in to their cross product. (cherry picked from commit 0cbb7fabd94237103bad7f6bba014433b7e083c1 of fluxopt/mathspec#9) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA494URRSeWy6wmELGP Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- docs/about/limits.md | 1 + docs/reference/language/dimensions.md | 40 ++++++++++------ src/mathspec/_validation.py | 31 +++++++++++++ tests/test_tuple_dimensions.py | 65 ++++++++++++++++++-------- tests/test_validation.py | 66 +++++++++++++++++++++++++++ 5 files changed, 169 insertions(+), 34 deletions(-) diff --git a/docs/about/limits.md b/docs/about/limits.md index b7921a8d9..5123924aa 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 mapping](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that mapping: `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 469f959ab..2d2acaf43 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 mapping 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 3d68abf31..ffd7d1451 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 eb28f0360..7716463c8 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])'}, @@ -88,7 +87,7 @@ def test_each_member_is_a_map_of_the_dimension(): members=('port', 'unit'), ), 'the table of the dimension has a mapping per member beside the mappings the file declares' assert program.relations['trade'].members == ('from_region', 'region'), ( - 'a dimension with no declared map has its members' + 'a dimension with no declared mapping has its members' ) assert program.dimensions['trade'].over == (('from_region', 'from_region'), ('region', 'region')), ( 'a member is named after its dimension, an alias where the tuple holds one dimension twice' @@ -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,28 @@ 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_an_alias_opts_two_dimensions_into_their_cross_product(): + """The allocation of #1011: each side over its own alias of `region`, so the two share no member.""" + spec = to_spec( + { + 'dimensions': { + 'region': {}, + 'plant': {}, + 'site': {}, + 'supply_region': {'alias': 'region'}, + 'demand_region': {'alias': 'region'}, + 'supply': {'over': ['supply_region', 'plant']}, + 'demand': {'over': ['demand_region', 'site']}, + }, + 'variables': {'x': {'dims': ['supply', 'demand']}}, + } + ) + assert spec.program.variables['x'].dims == ('demand', 'supply') def test_a_condition_compares_a_member_label(): @@ -270,7 +295,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): pytest.param( {'mappings.connection.unit': {'dim': 'unit'}}, ("mappings: 'connection': mapping 'unit' has the name of a member of 'connection'", 'connection[unit]'), - id='a-declared-map-named-after-a-member', + id='a-declared-mapping-named-after-a-member', ), pytest.param( _constraint("shift(flow, along=connection, offset=1, edge='wrap') >= 0", ['connection', 'snapshot']), @@ -307,11 +332,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', ), @@ -331,7 +356,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): 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', + id='over-names-a-member-beside-a-declared-mapping', ), pytest.param( _constraint('sum(flow, over=[unit, port]) >= 0', ['snapshot']), @@ -371,12 +396,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 +414,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 5281abf8b..6947aa870 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -3557,3 +3557,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 249f5414f55070ade227ee1976803c94068ce0af Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 13:25:51 +0000 Subject: [PATCH 6/6] feat(language): a dimension with members may be ordered ordered: true on a dimension with over: makes the row order of its tuples part of the spec, as for any dimension. shift, sum_back, position, piecewise: and sos: of type 2 step from one listed tuple to the next, and within= groups the steps by a member, as in within=snapshot[period]. A step along one member stays refused. Proposed on #1011 for multi-period snapshots; not agreed there yet. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q --- docs/about/limits.md | 1 - docs/reference/language/dimensions.md | 54 ++++++++++++++++------ src/mathspec/_expression_resolver.py | 3 -- src/mathspec/_resolution.py | 2 +- src/mathspec/_validation.py | 4 +- src/mathspec/errors.py | 14 +----- src/mathspec/spec.py | 7 --- tests/test_tuple_dimensions.py | 65 ++++++++++++++++++++++----- 8 files changed, 101 insertions(+), 49 deletions(-) diff --git a/docs/about/limits.md b/docs/about/limits.md index 5123924aa..c3d729b93 100644 --- a/docs/about/limits.md +++ b/docs/about/limits.md @@ -118,7 +118,6 @@ 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 mapping](../reference/language/dimensions.md#over) from each tuple to its label. | A lookup or a sum through that mapping: `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. | ### Data preparation diff --git a/docs/reference/language/dimensions.md b/docs/reference/language/dimensions.md index 2d2acaf43..ce3ce5e83 100644 --- a/docs/reference/language/dimensions.md +++ b/docs/reference/language/dimensions.md @@ -157,8 +157,9 @@ 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. +A dimension with [`over:`](#over) takes `ordered: true` too, and steps from +one listed tuple to the next +([an ordered dimension with members](#an-ordered-dimension-with-members)). [`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 @@ -297,21 +298,48 @@ 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 +| 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 | +| `dtype:` or `one_of:` beside `over:` | the key on a member | +| a step along one member, as `shift(soc, along=period)` on an entry over `snapshot` | a step along the dimension, grouped by the member: `within=snapshot[period]` | +| 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 that an entry steps through along one member, such as the +periods in which each unit is active, 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])"`. +### An ordered dimension with members + +`ordered: true` on a dimension with members makes the order of its tuples part +of the spec, as it does for any dimension: the order is the row order of the +data. `shift`, `sum_back`, `position`, `piecewise:` and `sos:` of `type: 2` +step from one listed tuple to the next. A multi-period snapshot is the pair of +its period and its timestep: + +```yaml +dimensions: + period: { dtype: int, ordered: true } + timestep: { dtype: int } + snapshot: { over: [period, timestep], ordered: true } +``` + +`within=snapshot[period]` groups the steps by a member, so that a store cycles +inside each period: + +```yaml +shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[period]) +``` + +A period with fewer timesteps lists fewer tuples, and a step goes on to the +next listed tuple. mathspec refuses a step along one member, as +`shift(soc, along=period)` on an entry over `snapshot`, because `period` is no +dimension of the entry. + ### `missing` `missing:` on a dimension with members sets whether every combination of diff --git a/src/mathspec/_expression_resolver.py b/src/mathspec/_expression_resolver.py index 9632cbd7f..bf88c1105 100644 --- a/src/mathspec/_expression_resolver.py +++ b/src/mathspec/_expression_resolver.py @@ -711,9 +711,6 @@ 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 mapping, so it makes no groups. Declare the group as a mapping of " diff --git a/src/mathspec/_resolution.py b/src/mathspec/_resolution.py index 5a4b96910..0890d676a 100644 --- a/src/mathspec/_resolution.py +++ b/src/mathspec/_resolution.py @@ -256,7 +256,7 @@ def unordered(self, name: str) -> bool: 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) + return unordered(context, construct, name) def kind(self, name: str) -> NameKind | None: """What *name* was declared as, or ``None`` where the file declares it nowhere.""" diff --git a/src/mathspec/_validation.py b/src/mathspec/_validation.py index ffd7d1451..cce56a931 100644 --- a/src/mathspec/_validation.py +++ b/src/mathspec/_validation.py @@ -403,7 +403,7 @@ def _sos_shapes(spec: Spec) -> Iterator[str]: f'to one of these dims.' ) elif entry.type == 2 and not labels_of(spec, entry.along).ordered: - yield unordered(context, f'type: 2 along {entry.along}', entry.along, spec.dimensions[entry.along].members) + yield unordered(context, f'type: 2 along {entry.along}', entry.along) elif entry.variable in claimed: yield ( f"{context}: variable '{entry.variable}' already carries the set declared by " @@ -457,7 +457,7 @@ def _piecewise_references(spec: Spec) -> Iterator[str]: yield undeclared_dimension('piecewise', name, pw.along, spec, along=True) continue if not labels_of(spec, pw.along).ordered: - yield unordered(context, f'along: {pw.along}', pw.along, spec.dimensions[pw.along].members) + yield unordered(context, f'along: {pw.along}', pw.along) 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 ed5a4f5b7..a0fce4a8f 100644 --- a/src/mathspec/errors.py +++ b/src/mathspec/errors.py @@ -43,18 +43,8 @@ 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, 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.' - ) +def unordered(context: str, construct: str, dimension: str) -> str: + """The refusal for *construct* reading the order of *dimension*, which is not 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/spec.py b/src/mathspec/spec.py index 8d46068b3..648dcee2f 100644 --- a/src/mathspec/spec.py +++ b/src/mathspec/spec.py @@ -417,13 +417,6 @@ def _members_or_labels(self) -> Self: '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( diff --git a/tests/test_tuple_dimensions.py b/tests/test_tuple_dimensions.py index 7716463c8..0b37fd66e 100644 --- a/tests/test_tuple_dimensions.py +++ b/tests/test_tuple_dimensions.py @@ -221,6 +221,56 @@ def test_an_alias_opts_two_dimensions_into_their_cross_product(): assert spec.program.variables['x'].dims == ('demand', 'supply') +#: A multi-period snapshot: the tuple of its period and its timestep, ordered by the row order of the data. +SNAPSHOTS: dict[str, Any] = { + 'dimensions': { + 'period': {'dtype': 'int', 'ordered': True}, + 'timestep': {'dtype': 'int'}, + 'unit': {}, + 'snapshot': {'over': ['period', 'timestep'], 'ordered': True}, + }, + 'parameters': {'ramp': {'dims': ['unit']}, 'p_nom': {'dims': ['period', 'unit']}}, + 'variables': {'soc': {'dims': ['snapshot', 'unit']}, 'p': {'dims': ['snapshot', 'unit']}}, +} + + +@pytest.mark.parametrize( + 'patch', + [ + pytest.param( + _constraint('soc - shift(soc, along=snapshot, offset=1) <= ramp', ['snapshot', 'unit']), id='shift' + ), + pytest.param( + _constraint( + "soc - shift(soc, along=snapshot, offset=1, edge='wrap', within=snapshot[period]) <= ramp", + ['snapshot', 'unit'], + ), + id='shift-within-a-member', + ), + pytest.param(_constraint('sum_back(p, along=snapshot, window=3) <= ramp', ['snapshot', 'unit']), id='sum-back'), + pytest.param({'variables.soc.where': 'position(snapshot, within=snapshot[period]) > 0'}, id='position'), + pytest.param( + { + 'variables.p.bounds': {'lower': 0, 'upper': 1}, + 'sos.pick': {'variable': 'p', 'along': 'snapshot', 'type': 2}, + }, + id='sos-of-type-2', + ), + ], +) +def test_an_ordered_dimension_with_members_takes_the_order_operators(patch): + """The snapshot case of #1011: the order is the data's, and `within=` groups by a member.""" + to_spec(varied(SNAPSHOTS, **patch)) + + +def test_a_step_along_one_member_is_refused(): + """A step along `period` on an entry over `snapshot` would read inside the tuple.""" + with pytest.raises(LanguageError, match=r'shift\(along=period\) but the expression has only the dims'): + to_spec( + varied(SNAPSHOTS, **_constraint('soc - shift(soc, along=period, offset=1) <= ramp', ['snapshot', 'unit'])) + ) + + 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 @@ -252,11 +302,6 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): ("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'), @@ -299,17 +344,17 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): ), 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']"), + ("shift(along=connection) reads the order of 'connection'", 'not declared ordered'), 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'), + ("sum_back(along=connection) reads the order of 'connection'", 'not declared ordered'), id='sum-back', ), pytest.param( {'variables.flow.where': 'position(connection) == 0'}, - ("position(connection) reads the order of 'connection'", 'no order'), + ("position(connection) reads the order of 'connection'", 'not declared ordered'), id='position', ), pytest.param( @@ -320,7 +365,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): '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'), + ("piecewise 'curve': along: connection reads the order of 'connection'", 'not declared ordered'), id='piecewise', ), pytest.param( @@ -328,7 +373,7 @@ def test_a_sparse_set_with_an_ordered_member_is_read_at_a_tuple(): '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']"), + ("Sos 'pick': type: 2 along connection reads the order of 'connection'", 'not declared ordered'), id='sos-of-type-2', ), pytest.param(