Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

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

## Upcoming version

- feat(language): a dimension's members are read by name ([#8](https://github.com/fluxopt/mathspec/pull/8))
- 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))
Expand Down
6 changes: 3 additions & 3 deletions docs/about/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,10 +116,10 @@ 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 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])`. |
| Access to a member of a dimension that lists its members, by a dot, as in `connection.unit` | [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. |
| Two dimensions in one `dims:` that share a 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. | The entry over the members, at the rows both list: mathspec [reads `dims: [connection, active]` so](../reference/language/dimensions.md#members-by-name). An alias of the member keeps the two apart. |
| 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. | A step along an ordered member, which [reads the entry over the members](../reference/language/dimensions.md#members-by-name). |
| 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
5 changes: 3 additions & 2 deletions docs/examples/connection.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ the bus, so two ports of one unit may attach to the same bus.
[`where:`](../reference/language/parameters-variables-constraints.md#where)
keeps only the output ports, and `missing: 1` applies only there. At an input
port, `injection` takes its case, and elsewhere `efficiency` times the flow of
the unit, read with `at`. The sum in `balance` adds each connection to the bus
the unit, read at each connection
[by member name](../reference/language/dimensions.md#members-by-name). The sum in `balance` adds each connection to the bus
it attaches to.

<!-- gallery:begin -->
Expand Down Expand Up @@ -64,7 +65,7 @@ expressions:
dims: [connection, snapshot]
cases:
draws: { when: "connection[role] == 'input'", expression: "-at(flow, by=connection[unit])" }
otherwise: efficiency * at(flow, by=connection[unit])
otherwise: efficiency * flow

constraints:
balance:
Expand Down
16 changes: 9 additions & 7 deletions docs/examples/sparse.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@ the sets in one way:

`connection` is a dimension whose labels are the pairs of a unit and a port.
`efficiency` and `flow` are over it, so `missing: 1` fills only the ports it
lists, and a data row for a port it does not list is refused. `active` is a
dimension over `unit` and `period`. `output` is over both members, and
`where: active` keeps the pairs that `active` lists, so `ramp_up` can step
along the ordered member `period`.
lists, and a data row for a port it does not list is refused. `port_limit`
reads `capacity` at the unit of each connection, and `split` sums over `port`,
both [by member name](../reference/language/dimensions.md#members-by-name).
`active` is a dimension over `unit` and `period`, and `output` is over it.
`ramp_up` steps `output` along the ordered member `period`, so mathspec reads
`output` over `unit` and `period`, confined to the pairs that `active` lists.
[#1019](https://github.com/energy-models/mathspec/issues/1019) compares how
three designs for sparse sets write this spec.

Expand Down Expand Up @@ -51,18 +53,18 @@ parameters:
load: { dims: [bus, period], description: demand to be met }

variables:
output: { dims: [unit, period], where: active, bounds: { lower: 0 }, description: what a unit produces }
output: { dims: [active], bounds: { lower: 0 }, description: what a unit produces }
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: [connection, period]
expression: flow <= at(capacity, by=connection[unit])
expression: flow <= capacity
split:
description: the ports of a unit take what it produces
dims: [unit, period]
expression: sum(flow, over=connection, by=connection[unit]) == output
expression: sum(flow, over=port) == output
ramp_up:
description: output rises by at most the ramp from one active period to the next
dims: [unit, period]
Expand Down
10 changes: 5 additions & 5 deletions docs/examples/times/capacity.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@ without storage, with the upper bound only.
The GAMS conditions map to the spec as follows:

- `RTP_VINTYR` and `PRC_TS` are dimensions with
[members](../../reference/language/dimensions.md#over). `act` is over every
member of both, and `where: "prc_ts AND rtp_vintyr"` keeps the coordinates
that both list.
[members](../../reference/language/dimensions.md#over). `act` is over both,
which share `region` and `process`, so mathspec
[reads it over their members](../../reference/language/dimensions.md#members-by-name),
at the coordinates that both list.
- `TS_MAP(R,S,TS)` is the dimension `ts_map`. Its upper timeslice is the
alias `upper_timeslice`, so the two timeslices are two members.
`eq_capact_up` reads the activity at each tuple of `ts_map`, sums it to each
Expand Down Expand Up @@ -69,8 +70,7 @@ variables:
cap: { dims: [region, period, process], bounds: { lower: 0 }, description: installed capacity (VAR_CAP) }
act:
description: activity of a vintage of a process in a timeslice (VAR_ACT)
dims: [region, vintage, period, process, timeslice]
where: "prc_ts AND rtp_vintyr"
dims: [prc_ts, rtp_vintyr]
bounds: { lower: 0 }

constraints:
Expand Down
12 changes: 7 additions & 5 deletions docs/examples/times/trade.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@ as TIMES' `TOP_IRE` does, each a tuple of its five members, and `ire_flo`,
exist is refused. The data of `ire_flo` has the five columns that the TIMES
data already has, and no label is invented.

`balance` adds the imports of each region and commodity through the members
`region` and `commodity` of each link. It sums the exports to each
`balance` adds the imports of each region and commodity: it sums over the
other three members of each link, which
[groups by the two it leaves](../../reference/language/dimensions.md#members-by-name).
It sums the exports to each
`from_region` and `from_commodity`, and reads those back onto `region` and
`commodity` through the mapping of each alias.

Expand Down Expand Up @@ -66,9 +68,9 @@ constraints:
dims: [commodity, region]
expression: >-
supply
+ 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])
+ sum(ire_flo * export, over=[from_commodity, from_region, process])
- sum(sum(sum(export, over=[commodity, process, region]), over=from_region, by=from_region[region]),
over=from_commodity, by=from_commodity[commodity])
>= demand

objective:
Expand Down
Loading
Loading