Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
04e9b85
feat(language): a dimension lists its members
claude Nov 16, 2026
3be1b19
docs(changelog): the tuple-dimension line links #1017
claude Nov 16, 2026
029f548
Merge feat/dimension-alias into feat/maps-tuple-dimensions
claude Nov 16, 2026
c06a2fa
Merge remote-tracking branch 'origin/feat/dimension-alias' into feat/…
claude Nov 16, 2026
ce4c86e
Merge feat/dimension-alias into feat/maps-tuple-dimensions
claude Nov 16, 2026
5cb457a
Merge remote-tracking branch 'origin/feat/dimension-alias' into feat/…
claude Nov 16, 2026
16f558c
Merge feat/dimension-alias into feat/maps-tuple-dimensions
claude Nov 16, 2026
7bc8667
Merge feat/dimension-alias into compare/tuple-strict
claude Nov 17, 2026
0cbb7fa
feat(language): a member shared by two dimensions of one frame is ref…
claude Nov 17, 2026
a207fa5
docs(changelog): the strict tuple-dimension line links #9
claude Nov 17, 2026
9a32ef1
feat(language): a tuple dimension's bare name tests membership
claude Nov 17, 2026
91c0535
docs(examples): every example declares its sets as dimensions
claude Nov 17, 2026
9b83fa5
feat(language): a step along a member names the flat entry
claude Nov 17, 2026
ba4ef2b
feat(language)!: the section of lookups is called mappings
claude Nov 17, 2026
06e5295
Merge feat/maps-only into feat/dimension-alias: mappings
claude Nov 17, 2026
ab510b9
feat(language)!: the file has no relations: section
claude Nov 17, 2026
b8a4244
Merge feat/dimension-alias (06e52956) into compare/tuple-strict: mapp…
claude Nov 17, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,13 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp

## Upcoming version

- feat(language)!: a dimension lists its members, strictly ([#9](https://github.com/fluxopt/mathspec/pull/9))
- Breaks a file: `relations:` is gone. A set of combinations of labels is a dimension with `over:`, read through its members with `at()` and tested by its bare name in a `where:`. A dimension twice in a relation is an alias member.
- feat(language): a dimension lists its members ([#1017](https://github.com/energy-models/mathspec/pull/1017))
- feat(language): a dimension may alias another's labels ([#1020](https://github.com/energy-models/mathspec/pull/1020))
- feat(language)!: maps give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015))
- Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a map under `maps:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[map]`, such as `generator[bus]`.
- Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[map]`.
- feat!: mappings give labels, relations give rows ([#1015](https://github.com/energy-models/mathspec/pull/1015))
- Breaks a file: `relations:` takes `dims:`, `missing:` and `description` only. Each value column becomes a mapping under `mappings:`, keyed by its subject, with `dim:` naming its dimension and always written, and is read as `subject[mapping]`, such as `generator[bus]`.
- Breaks the program API: `Program.relations` holds one table per subject, `Relation` gains `partial`, `RelationDefined` gains `column`, `Reach.name` names `subject[mapping]`.
- docs(examples): TIMES examples and a sparse-set example ([#1021](https://github.com/energy-models/mathspec/pull/1021))
- docs(pypsa): the example page shows one fragment ([#1010](https://github.com/energy-models/mathspec/pull/1010))
- feat(composition): rename gives a spec other names ([#1002](https://github.com/energy-models/mathspec/pull/1002))
Expand Down
4 changes: 2 additions & 2 deletions docs/about/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ understand a rule before you rely on it.
added to the language, and which requests mathspec refuses and why.
- **[Versions](versions.md)** describes how the version of the package and the
version of the language relate, and why there are two.
- **[Relations as linear maps](relations-as-linear-maps.md)** describes a sum
- **[Mappings as linear maps](relations-as-linear-maps.md)** describes a sum
through a table that pairs labels
([a relation](../reference/language/relations.md)) as the product of a matrix and a vector.
([a mapping](../reference/language/mappings.md)) as the product of a matrix and a vector.
- **[Understanding a spec in SQL and dataframe terms](sql-and-dataframes.md)**
describes each declaration and operator of a spec as a table or a query, in
SQL and in polars.
Expand Down
18 changes: 11 additions & 7 deletions docs/about/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,17 @@ limit does not depend on what solvers take.
mathspec refuses a request when a construct that exists already states the
same thing.

| Request | Why refused | What you write instead |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A `where` comparing the label that each row has ([a map](../reference/language/relations.md#maps)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The map already gives each row its label. | A sum or a lookup through the map. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the map gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). |
| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. |
| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. |
| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. |
| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. |
| Request | Why refused | What you write instead |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A `where` comparing the label that each row has ([a mapping](../reference/language/mappings.md#mappings)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The mapping already gives each row its label. | A sum or a lookup through the mapping. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the mapping gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). |
| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. |
| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. |
| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. |
| 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])`. |
| A `relations:` section for a set of combinations of labels | A [dimension with members](../reference/language/dimensions.md#over) already lists the combinations, and its mappings already give each one its labels. | `dimensions: { connection: { over: [generator, bus] } }`, tested by its bare name in a `where:` on an entry over every member. |
| Two dimensions in one `dims:` that share a member, or a dimension beside its own member, read as their cross product | A tool may store each dimension as the columns of its members, so the shared member would index the entry twice. | One of the two in `dims:`, and a `where:` that reads a relation through the shared member, or an alias of the member: `site: { over: [from_unit, bus] }`. |
| An order along a dimension that lists its members, for `shift`, `sum_back`, `position`, `piecewise:` or `sos:` of `type: 2` | A tuple of labels has no order, and each member can already declare one. | An entry over the members, with `where:` the bare name of the dimension. The construct then steps along an ordered member. |
| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. |

### Data preparation

Expand Down
4 changes: 2 additions & 2 deletions docs/about/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,8 @@ generator either. The file specifies the condition that the data must meet,
and the engine that attaches the data checks the condition.

- [`missing:`](../reference/language/absence.md#missing) on a parameter, a table that pairs labels
([a relation](../reference/language/relations.md)) or a
[map](../reference/language/relations.md#maps) sets what a missing row or
([a mapping](../reference/language/mappings.md)) or a
[mapping](../reference/language/mappings.md#mappings) sets what a missing row or
label means. When the engine attaches the data, it refuses a missing row by default.
- An [`assumptions:`](../reference/language/assumptions.md) entry is a
condition that the data must meet.
Expand Down
Loading
Loading