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
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ it releases that version ([RELEASING.md](https://github.com/energy-models/mathsp

## Upcoming version

- feat(language)!: relation rows index an entry and a sum ([#7](https://github.com/fluxopt/mathspec/pull/7))
- Breaks a file: the `where:` of a parameter or a variable no longer takes a relation's bare name. Write `in: [relation]`.
- `sum(x, over=<relation>)` sums over the relation's key.
- feat(language): a dimension may alias another's labels ([#1020](https://github.com/energy-models/mathspec/pull/1020))
- 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]`.
Expand Down
15 changes: 8 additions & 7 deletions docs/about/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,14 @@ 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 mapping](../reference/language/relations.md#mappings)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The mapping already gives each row its label. | A sum or a lookup through the mapping. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the mapping gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). |
| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. |
| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. |
| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. |
| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. |
| Request | Why refused | What you write instead |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A `where` comparing the label that each row has ([a mapping](../reference/language/relations.md#mappings)) against the dimension it refers to, such as `generator[bus] == bus` | Two dimensions cannot be compared, so mathspec refuses the comparison. The mapping already gives each row its label. | A sum or a lookup through the mapping. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the mapping gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). |
| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. |
| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. |
| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. |
| A `join` operator apart from `sum` and `at`, such as `sum(join(p, generator[bus]), over=generator)` | [`sum(by=)` and `at(by=)` already state a join](relations-as-linear-maps.md#why-the-language-has-no-join-operator). | A sum or a lookup with `by=`, as in the first row. |
| A dimension of pairs, such as one index over the wired `(entity, bus)` pairs, or one assumption per parameter that refuses data at a pair that is not wired | A relation already lists the pairs, and its `missing:` already sets what a pair with no row means. | A relation over the pairs, named under [`in:`](../reference/language/parameters-variables-constraints.md#in) by each parameter or variable that it indexes. A tool refuses a data row of that parameter at a pair the relation does not list. |

### Data preparation

Expand Down
24 changes: 12 additions & 12 deletions docs/examples/sparse.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ 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.
`efficiency` and `flow` list `connection` under `in:`, so they exist only
where it lists a port, `missing: 1` fills only those ports, and a data row
for a port that `connection` does not list is refused.
[#1019](https://github.com/energy-models/mathspec/issues/1019) compares how
three designs for sparse sets write this spec.

Expand Down Expand Up @@ -50,14 +50,14 @@ mappings:
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: [unit, port, period], in: [connection], 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 }
output: { dims: [unit, period], in: [active], bounds: { lower: 0 }, description: what a unit produces }
flow: { dims: [unit, port, period], in: [connection], bounds: { lower: 0 }, description: what a port takes of it }

constraints:
port_limit:
Expand All @@ -75,7 +75,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
Expand All @@ -98,29 +98,29 @@ Units that feed buses through the ports they have, and run only in the periods t
| 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 $`\left( o,\ u \right) \in \mathrm{connection},\ t \in \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 |

#### Variables

| Symbol | Meaning |
|---|---|
| $`\mathit{flow}`$ | `flow` over $`\mathcal{T} \times \mathcal{O} \times \mathcal{U}`$ — what a port takes of it |
| $`\mathit{output}`$ | `output` over $`\mathcal{T} \times \mathcal{U}`$ — what a unit produces |
| $`\mathit{flow}`$ | `flow` over $`\left( o,\ u \right) \in \mathrm{connection},\ t \in \mathcal{T}`$ — what a port takes of it |
| $`\mathit{output}`$ | `output` over $`\left( t,\ u \right) \in \mathrm{active}`$ — what a unit produces |

#### Variable domains

**`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}_{t,o,u} \ge 0 \qquad \forall\, \left( o,\ u \right) \in \mathrm{connection},\ t \in \mathcal{T}
```

**`output`**

```math
\mathit{output}_{t,u} \ge 0 \qquad \forall\, t \in \mathcal{T},\ u \in \mathcal{U} \,:\, \left( t,\ u \right) \in \mathrm{active}
\mathit{output}_{t,u} \ge 0 \qquad \forall\, \left( t,\ u \right) \in \mathrm{active}
```

#### Objective
Expand Down
9 changes: 5 additions & 4 deletions docs/examples/times/capacity.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ without storage, with the upper bound only.
The GAMS conditions map to the spec as follows:

- `RTP_VINTYR` and `PRC_TS` are [relations](../../reference/language/relations.md),
and `act` exists only at the coordinates that both list.
and `act` lists both under `in:`, so it exists only at the coordinates that
both list.
- `TS_MAP(R,S,TS)` is the relation `ts_map`, which names `timeslice` twice
under two column names.
- `COEF_AF(…,'UP')` is the `where:` of `eq_capact_up`.
Expand Down Expand Up @@ -70,7 +71,7 @@ variables:
act:
description: activity of a vintage of a process in a timeslice (VAR_ACT)
dims: [region, vintage, period, process, timeslice]
where: rtp_vintyr AND prc_ts
in: [prc_ts, rtp_vintyr]
bounds: { lower: 0 }

constraints:
Expand Down Expand Up @@ -121,7 +122,7 @@ Capacity transfer and capacity–activity from TIMES: EQ\_CPT and the upper form

| Symbol | Meaning |
|---|---|
| $`\mathit{act}`$ | `act` over $`\mathcal{T} \times \mathcal{P} \times \mathcal{R} \times \mathcal{S} \times \mathcal{V}`$ — activity of a vintage of a process in a timeslice (VAR\_ACT) |
| $`\mathit{act}`$ | `act` over $`\left( p,\ r,\ s \right) \in \mathrm{prc\_ts},\ \left( t,\ p,\ r,\ v \right) \in \mathrm{rtp\_vintyr}`$ — activity of a vintage of a process in a timeslice (VAR\_ACT) |
| $`\mathit{cap}`$ | `cap` over $`\mathcal{T} \times \mathcal{P} \times \mathcal{R}`$ — installed capacity (VAR\_CAP) |
| $`\mathit{ncap}`$ | `ncap` over $`\mathcal{P} \times \mathcal{R} \times \mathcal{V}`$ — new capacity (VAR\_NCAP) |

Expand All @@ -130,7 +131,7 @@ Capacity transfer and capacity–activity from TIMES: EQ\_CPT and the upper form
**`act`**

```math
\mathit{act}_{t,p,r,s,v} \ge 0 \qquad \forall\, t \in \mathcal{T},\ p \in \mathcal{P},\ r \in \mathcal{R},\ s \in \mathcal{S},\ v \in \mathcal{V} \,:\, \left( t,\ p,\ r,\ v \right) \in \mathrm{rtp\_vintyr} \wedge \left( p,\ r,\ s \right) \in \mathrm{prc\_ts}
\mathit{act}_{t,p,r,s,v} \ge 0 \qquad \forall\, \left( p,\ r,\ s \right) \in \mathrm{prc\_ts},\ \left( t,\ p,\ r,\ v \right) \in \mathrm{rtp\_vintyr}
```

**`cap`**
Expand Down
22 changes: 11 additions & 11 deletions docs/examples/times/trade.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@ 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 processes that carry each link,
as TIMES' `TOP_IRE` does, and `ire_flo`, `trade_cost` and `export` exist only
at its rows. A row of `ire_flo` outside `top_ire` is dropped, not refused.
The data of `ire_flo` has the five columns that the TIMES data already has,
and no label is invented.
as TIMES' `TOP_IRE` does, and `ire_flo`, `trade_cost` and `export` name it
under `in:`, so a data row outside its rows 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 over the far end of
each link. It reads the exports at the near end: it sums them to each
Expand Down Expand Up @@ -50,20 +50,20 @@ parameters:
ire_flo:
description: the share of an export that arrives as an import (IRE_FLO)
dims: [from_region, from_commodity, region, commodity, process]
where: top_ire
in: [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, process]
where: top_ire
in: [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 through a process (VAR_IRE)
dims: [from_region, from_commodity, region, commodity, process]
where: top_ire
in: [top_ire]
bounds: { lower: 0 }

constraints:
Expand Down Expand Up @@ -99,23 +99,23 @@ Trade between regions from TIMES: IRE\_FLO, the efficiency of a flow from one re
| 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{P} \times \mathcal{R}`$, only where $`\left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}`$ — the share of an export that arrives as an import (IRE\_FLO) |
| $`\mathrm{ire\_flo}`$ | `ire_flo` over $`\left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}`$ — 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{P} \times \mathcal{R}`$, only where $`\left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}`$ — the cost of a unit exported along a link |
| $`\mathrm{trade\_cost}`$ | `trade_cost` over $`\left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}`$ — 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{P} \times \mathcal{R}`$ — what leaves along a link through a process (VAR\_IRE) |
| $`\mathit{export}`$ | `export` over $`\left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}`$ — what leaves along a link through a process (VAR\_IRE) |
| $`\mathit{supply}`$ | `supply` over $`\mathcal{C} \times \mathcal{R}`$ — what a region produces of a commodity |

#### Variable domains

**`export`**

```math
\mathit{export}_{c,c',r',p,r} \ge 0 \qquad \forall\, c \in \mathcal{C},\ c' \in \mathcal{C},\ r' \in \mathcal{R},\ p \in \mathcal{P},\ r \in \mathcal{R} \,:\, \left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}
\mathit{export}_{c,c',r',p,r} \ge 0 \qquad \forall\, \left( c,\ c',\ r',\ p,\ r \right) \in \mathrm{top\_ire}
```

**`supply`**
Expand Down
2 changes: 1 addition & 1 deletion docs/howto/declare-a-column.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ variables:
dispatch: { dims: [snapshot, generator], bounds: { lower: 0, upper: availability } }
reserve:
dims: [snapshot, generator, bus]
where: connection
in: [connection]
bounds: { lower: 0, upper: availability }

constraints:
Expand Down
8 changes: 8 additions & 0 deletions docs/reference/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,14 @@ A group is the set of rows of a dimension or a relation to which one
`sum_back` or `position()` work separately in each group, such as each season
of a year ([partitions](language/relations.md#partitions)).

## Index set

The index set of a parameter or a variable is the coordinates its `in:` lists:
the combinations of labels where each of its relations has a row. A mapping is
not an index set. A tool refuses a row of the data of a parameter
outside its index set
([`in`](language/parameters-variables-constraints.md#in)).

## Label

A label is one member of a dimension, such as `wind` in `generator`. The
Expand Down
Loading
Loading