Skip to content

feat(language)!: an entry or a sum may range over a set - #1018

Closed
FBumann wants to merge 8 commits into
feat/dimension-aliasfrom
feat/maps-sets
Closed

FBumann wants to merge 8 commits into
feat/dimension-aliasfrom
feat/maps-sets

Conversation

@FBumann

@FBumann FBumann commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Note

The following content was generated by AI.

Why it is a rename: a sum runs over a set, not a relation

In math In a spec
set a collection you range over: $\sum_{(u,p) \in C} x_{u,p}$, $\forall (u,p) \in C$ dims: [connection, …], sum(x, over=connection)
relation a predicate you test: $R(u,p)$ is true or false a filter in where:
  • Mathematically a relation $R \subseteq U \times P$ is a set of pairs; the name says which role it plays
  • Option A (feat(language)!: relation rows may index an entry #1016) keeps the predicate role: relations: filter, entries list in:
  • This PR gives the construct the indexing role: entries are over it, sums run over it. So it is a set, and the section is sets:
  • The same choice as AMPL: set C within U cross P; param f{C}; sum{(u,p) in C}

What this changes

Option B of three for a sparse set. A set in dims: or over= stands for its dimensions at the combinations it lists. No in: key; entries stay flat, so operators and alignment by name are unchanged. Stacked on #1020 (alias), which states a dimension named twice.

# before (#1015)
relations:
  connection: { dims: [unit, port], missing: absent }
parameters:
  efficiency: { dims: [unit, port, snapshot], where: connection, missing: 1 }   # stray row dropped
variables:
  flow: { dims: [unit, port, snapshot], where: connection }
constraints:
  balance: { dims: [bus, snapshot], expression: "sum(flow, over=[unit, port], by=connection[bus]) == load" }

# after
sets:
  connection: { dims: [unit, port], missing: absent }
parameters:
  efficiency: { dims: [connection, snapshot], missing: 1 }   # stray row refused
variables:
  flow: { dims: [connection, snapshot] }
constraints:
  limit:   { dims: [connection, snapshot], expression: flow <= capacity }   # capacity over unit aligns by name
  balance: { dims: [bus, snapshot], expression: "sum(flow, over=connection, by=connection[bus]) == load" }

The TIMES examples (examples/times/)

# before (#1020)
relations: { top_ire: { dims: [from_region, from_commodity, region, commodity], missing: absent } }
act:     { dims: [region, vintage, period, process, timeslice], where: rtp_vintyr AND prc_ts }
ire_flo: { dims: [from_region, from_commodity, region, commodity], where: top_ire }
# after
sets: { top_ire: { dims: [from_region, from_commodity, region, commodity], missing: absent } }
act:     { dims: [prc_ts, rtp_vintyr] }   # their five dimensions, where both list a row
ire_flo: { dims: [top_ire] }              # the aliases make every column distinct, so the set can be named
  • a set that repeats a dimension is refused with the alias as the rewrite: "Declare an alias of 'snapshot' under dimensions:, and one column of the set over it."
Method, gate output, what is not done
  • built on feat(language)!: relation rows may index an entry #1016's in: machinery: a set in dims: is turned into dimensions plus in_ before validation (Spec._sets_in_dims), and folded back on write (_sets_written_back). in is no YAML key; in_ written by hand is refused, and a mistyped key is not told of it (b221638)
  • constraints take a set in dims: too; a named expression does not, it derives its rows from its operands
  • over= a set expands to its dimensions (_members_of_sets)
  • rename: YAML key, schema, SetSpec, Spec.sets, every error message, the reference pages (relations.md keeps its file name, retitled "Sets and maps"), glossary, how-tos, tutorials, the TIMES pages. Not renamed: the program API (Program.relations, Relation, RelationDefined), internal names, docs/about/relations-as-linear-maps.md, docs/development/
  • removed: the glossary entry "Index set", the "dimension of pairs" row in limits.md (this PR admits it)
  • feat(language): a dimension may alias another's labels #1020 merged in (fa45382, 12315cf): the alias docs example names the set in dims:; tests/test_alias.py and examples/times/ state IRE_FLO in this spelling
  • gate at 12315cf: ruff, ruff format, pyrefly (0 errors), pytest (4270 passed, 1 skipped), typos, zensical build --strict, prettier on changed files; schema, goldens, generated pages regenerated. Not run: compile-tex; no pixi, uv venv
  • draft: for comparison, not for merge

🤖 Generated with Claude Code

https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q

claude and others added 2 commits November 16, 2026 16:40
`relations:` is `sets:`. A set named in the `dims:` of a parameter, a
variable or a constraint, or in `over=`, stands for its dimensions at the
combinations it lists: the entry has coordinates only there, and a tool
refuses a data row of a parameter anywhere else. There is no `in:` key.
A set's bare name in the `where:` of such an entry is refused, with the
set in `dims:` as the rewrite.

In math a sum or an index ranges over a set, so the construct that
`dims:` and `over=` take is named a set.

Co-Authored-By: Fabian Hofmann <fab.hof@gmx.de>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
@read-the-docs-community

read-the-docs-community Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

An entry over a dimension twice, as TIMES' IRE_FLO: the alias's docs
example names the set in dims:, a test states IRE_FLO in this spelling,
and a set with two columns over one dimension is refused with an alias as
the rewrite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
@FBumann
FBumann changed the base branch from feat/maps-only to feat/dimension-alias November 16, 2026 17:18
`in:` was answered "Did you mean 'in_'?", the field the load fills from
`dims:` and a file may not write. The suggestion now leaves it out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
The TIMES examples in this PR's spelling: sets: in place of relations:,
act over [prc_ts, rtp_vintyr], and ire_flo, trade_cost and export over
the set top_ire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q
sparse.yaml in this PR's spelling: sets:, and every entry over a set
names it in dims:. Restating balance found that over= a set beside by=
was refused; a set in over= now stands for its dimensions there too,
with the failing test first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018B3nA1xxh6NMJN6mrYY34Q

FBumann commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Note

The following content was generated by AI.


Generated by Claude Code

@FBumann FBumann closed this Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants