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 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!: 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
16 changes: 9 additions & 7 deletions docs/about/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,15 @@ 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 map. `sum(x, over=d, by=s[m])` adds each value of `x` to the label that the map gives it, and `at(x, by=s[m])` takes the value at that label ([operators](../reference/language/operators.md#sum)). |
| A vocabulary for tracked metrics: `impacts:`, `effects:`, a `costs` dimension | A tracked metric is already a [named expression](../reference/language/named.md#expressions). | An `impact` dimension and one named expression. A constraint can cap the expression, the objective can weight it, and a tool reads it back after the solver runs. |
| Helpers for one domain, such as `reduce_carrier_dim` | A macro already states a helper. | A [component library](../examples/library/index.md) of macros. Its macros use only the operators that exist. |
| A Python application programming interface (API) for building specs | The file is already the API, and the file is what you review and diff. | YAML, or a `dict` with the same keys. A tool can combine dicts before it calls `to_spec`. |
| Access to a member of a dimension that lists its members, by a dot or by aligning `flow <= capacity` | [Each member is already a 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] }`. |
| 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
44 changes: 22 additions & 22 deletions docs/examples/sparse.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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]
Expand All @@ -50,32 +49,32 @@ 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: [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]
expression: output - shift(output, along=period, offset=1) <= ramp
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 @@ -88,33 +87,34 @@ 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 |

#### Variables

| 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

**`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`**
Expand All @@ -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`**
Expand All @@ -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}
```
<!-- gallery:end -->
Loading