Skip to content

feat(composition): fragments join the properties of a subject, and a set two fragments declare differently is refused #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
FBumann wants to merge 2 commits into
base: claude/sets-properties-prototype-9m3zu6-2-calls
Choose a base branch
from
Draft

feat(composition): fragments join the properties of a subject, and a set two fragments declare differently is refused #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93936e3
feat(composition): fragments join the properties of a subject, and a …
claude Oct 23, 2026
358ea36
docs(changelog): add the line for merging sets and properties
claude Oct 23, 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
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
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(composition): fragments join the properties of a subject, and a set two fragments declare differently is refused ([#3](https://github.com/fluxopt/mathspec/pull/3))
- feat(language): a call reads a property of a dimension or a set, written subject[property] ([#2](https://github.com/fluxopt/mathspec/pull/2))
- feat(language): a file may declare sets of labels and the properties of a dimension or a set ([#1](https://github.com/fluxopt/mathspec/pull/1))
- feat(language): a parameter may declare the coordinates it has with `where:`, and outside them it is absent ([#945](https://github.com/energy-models/mathspec/pull/945))
Expand Down
45 changes: 24 additions & 21 deletions docs/howto/compose.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,21 +200,22 @@ which each component pins at its own port.

## What a fragment may share

| The entry | What happens |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| a dimension or a relation | every fragment may declare it, and the ones that do say the same thing about it |
| a `description` on a shared dimension or relation | it is prose rather than a claim, and the first wording in the list is carried |
| `ordered: true` on a shared dimension | it says that the members have an order and does not change them, so the dimension is ordered if one fragment says so |
| `missing:` on a shared relation | it says what a missing row of the data means, so every fragment that declares the relation gives the same value. `missing: refused` is the same as no `missing:` |
| any other entry | one fragment declares it, and a second is refused |
| an entry under `given:` | it is checked against the fragment that introduces the name, then folded into it. Its description fills the entry where the introducer wrote none |
| a given expression | the body of the definition carries no dimension that the `dims` of the reading fragment do not name |
| a given condition | the `dims` of the reading fragment name exactly the dimensions that the condition of the defining fragment reads |
| a given entry no fragment introduces | it stays under `given:` until a host model provides it |
| an expression with `adds_to:` | the sum it names is the body one fragment defines, if any, followed by every term by its name, in the order of the list. [Terms](../reference/language/parameters-variables-constraints.md#terms) gives what is refused |
| `objective` | one fragment sets it, and a second is refused. Several fragments contribute to it as terms of a sum the objective reads |
| `version` | every fragment is written against the same one |
| `description` at the top of a fragment | it is about the fragment and is not carried. Pass the composed spec's as `description=` |
| The entry | What happens |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| a dimension, a relation or a set | every fragment may declare it, and the ones that do say the same thing about it |
| the properties of one subject | every fragment may give the subject properties, and the subject has all of them. A property that two fragments declare says the same thing in both ([properties](../reference/language/sets.md#properties)) |
| a `description` on a shared entry | it is prose rather than a claim, and the first wording in the list is carried |
| `ordered: true` on a shared dimension | it says that the members have an order and does not change them, so the dimension is ordered if one fragment says so |
| `missing:` on a shared relation, set or property | it says what a missing row of the data means, so every fragment that declares the entry gives the same value. `missing: refused` is the same as no `missing:` |
| any other entry | one fragment declares it, and a second is refused |
| an entry under `given:` | it is checked against the fragment that introduces the name, then folded into it. Its description fills the entry where the introducer wrote none |
| a given expression | the body of the definition carries no dimension that the `dims` of the reading fragment do not name |
| a given condition | the `dims` of the reading fragment name exactly the dimensions that the condition of the defining fragment reads |
| a given entry no fragment introduces | it stays under `given:` until a host model provides it |
| an expression with `adds_to:` | the sum it names is the body one fragment defines, if any, followed by every term by its name, in the order of the list. [Terms](../reference/language/parameters-variables-constraints.md#terms) gives what is refused |
| `objective` | one fragment sets it, and a second is refused. Several fragments contribute to it as terms of a sum the objective reads |
| `version` | every fragment is written against the same one |
| `description` at the top of a fragment | it is about the fragment and is not carried. Pass the composed spec's as `description=` |

## A name two fragments declare

Expand Down Expand Up @@ -364,9 +365,11 @@ Given variable 'Generator_p' collides with the variable of the same name. Rename
| `null` under an entry's name | it is removed |
| `null` on a field of an entry | the field takes its default, and the rest of the entry stays |
| `null` under a section's name | it is refused |
| a dimension or a relation | it is added, or restated as the base declares it |
| a dimension, a relation, a set | it is added, or restated as the base declares it |
| a property | it is added, or restated as the base declares it |
| `ordered:` on a restated dimension | `true` makes the dimension ordered; `false` over an ordered one is refused |
| `missing:` on a relation | it changes whether every key combination needs a row, as on a parameter |
| `missing:` on a relation, a set | it changes whether every key combination needs a row, as on a parameter |
| `missing:` on a property | it changes whether every row of the subject has the property |
| an entry under one kind of `given:` | it is edited, added or removed like any entry, and the other kinds stay |
| `version`, `description` | the patch's value replaces the base's |
| a field an earlier patch writes | the later patch's value replaces it |
Expand All @@ -389,8 +392,8 @@ as the base spells it.

## A dimension redeclared

A patch may add a dimension or a relation, and may restate one the base
declares. The restatement says what the base says: half an entry is a
A patch may add a dimension, a relation, a set or a property, and may
restate one the base declares. The restatement says what the base says: half an entry is a
second reading of the same name, and a field written at its default is the
same as one left out. Changing one under the expressions already written
over it is refused, and so is removing one:
Expand All @@ -409,8 +412,8 @@ patch 'unordered.yaml' says the dimension 'snapshot' is not ordered, where its b
```

`missing:` is a claim about the data, not the coordinate space. A patch may
change it on a relation as on a parameter, and may name it alone:
`relations: {gen_bus: {missing: absent}}`. `null` puts the default, `refused`,
change it on a relation, a set or a property as on a parameter, and may name
it alone: `properties: {line: {bus1: {missing: absent}}}`. `null` puts the default, `refused`,
back.

## A section set to `null`
Expand Down
Loading