Skip to content

feat(advice): check advises on a tuple cross product - #1026

Draft
FabianHofmann wants to merge 4 commits into
feat/tuple-unstackfrom
feat/tuple-advice
Draft

FabianHofmann wants to merge 4 commits into
feat/tuple-unstackfrom
feat/tuple-advice

Conversation

@FabianHofmann

@FabianHofmann FabianHofmann commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Note

The following content was generated by AI.

mathspec check advises, and does not refuse, where dims: crosses a tuple dimension with its own member or with another tuple dimension that shares one.

Part of #1011 (rule 11). Stacked on #1025. Last PR of the stack: Closes #1011. Closes #935.

dimensions:
  unit: { dtype: str }
  port: { dtype: str }
  period: { dtype: int, ordered: true }
  snapshot: { dtype: int, ordered: true }
  connection: { over: [unit, port] }
  assignment: { over: [unit, period] }
parameters:
  capacity: { dims: [unit] }
variables:
  flow: { dims: [connection, snapshot], bounds: { lower: 0 } }
  sent: { dims: [connection], bounds: { lower: 0, upper: 1 } }
  busy: { dims: [assignment], bounds: { lower: 0, upper: 1 } }
constraints:
  limit: { dims: [connection, unit, snapshot], expression: "flow <= capacity" }
  exclusive: { dims: [connection, assignment], expression: "sent + busy <= 1" }

pixi run python -m mathspec check example.yaml, exact output:

# before (#1025 head 2d66182): nothing, exit 0
# after (7535e5c): exit 0
Constraint 'exclusive': dims: lists 'assignment' and 'connection', which share the member 'unit', so the entry is their cross product: each assignment meets every connection, of its own unit or another. For the pairs that agree on unit (the inner join), add assignment[unit] == connection[unit] to where:.
Constraint 'limit': dims: lists 'connection' beside its member 'unit', so the entry is their cross product: each connection meets every unit, not only its own. For its own unit, drop 'unit' from dims: and read capacity at each tuple: at(capacity, by=connection[unit]). To go by unit instead, drop 'connection' from dims: and sum flow to the member: sum(flow, over=connection, by=connection[unit]).

Each suggested rewrite loads, and the note goes away. A member under two roles gets one full call per role:

... read tariff at each tuple: at(tariff, by=trade[dst]) or at(tariff, by=trade[src]). ...
... add site[region] == trade[dst] (or trade[src]) to where:.
Method, gate output, choices, not done

Triage (limits.md): no construct. A new Advice kind in the existing door (_advising.py); no new layer. limits.md unchanged: no limit moves.

Rule

  • new AdviceKind 'cross-product'; order: never-an-axis, cross-product, given, unbounded. Subject: the entry.
  • (a) two tuple dimensions in dims: sharing members → one note per pair, unless every shared member is compared with == in a top-level AND conjunct of where: (either side order). !=, or the join under OR, still advises. Suggests only the members not yet joined.
  • (b) a tuple dimension beside its member → one note per (dimension, member). Skipped where an operand (parameter, variable, named expression, given or not) already carries both: the entry asks for the product.
  • (b) names every operand over the member (at(...) each) and every operand over the dimension (sum(...) each). A side with no such operand, e.g. a declaration, says only drop 'unit' from dims:.
  • roles: one full call per role, joined by or; in (a) trade[dst] (or trade[src]).

Entries advised: parameters, variables, constraints, piecewise (dims: + where:), named expressions. A named expression takes no where:: (a) goes to the entry that reads it when that entry's dims: lists both; otherwise to the named expression itself, naming where the filter goes. Given entries: no; the file that builds them gets the note. After expand(), the note moves from the curve to the weight variables it writes (the rows read them over both, so they get none).

Tests: test_tuple_dimensions.py: 15 advised cases, each applying every rewrite its note names (all roles) and loading it without the note; 11 silent cases (operands over both, given parameter, curve link over both, join through a role, named expression whose reader filters or is advised); rename / merge / override × 2; expand. test_advice.py: one fixture so every kind is still produced.

Guard removal (each deleted, full suite run)

  • (a) loop → 6 fail; join check always false → 4; conjuncts read as atoms → 1; == dropped → 1; only unjoined members suggested → 1 (measured on 30c39a5)
  • (b) loop → 7 fail; piecewise entries dropped → 1 (30c39a5)
  • operand over both skips (b) → 4; reader over both silences a named expression → 2; named expression always skipped in (a) → 2; call printed without an operand → 1; first role only → 2; first operand only → 1; names not deduplicated → 2; named-expression wording → 2 (fcc61e1)

Gates

Docs: dimensions.md (both rule-11 paragraphs, operands over both, expand(), named expressions), errors.md (kind table). check.md and reading.md unchanged.

Where #1011 is silent or off

  • "advise on dims:" fixed as above, per entry kind.
  • a named condition holding the join cannot stand in where: today (refused at load: no frame); so only an inline comparison silences (a).

Not done


Generated by Claude Code

An entry whose dims: lists a dimension with members beside one of its
members, or two such dimensions that share a member without a where:
that compares it, loads as the cross product. advice() now returns a
note of kind cross-product for it, naming the likely rewrite: at(...)
or a sum to the member, or the inner-join filter. Rule 11 of #1011.
@read-the-docs-community

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

Copy link
Copy Markdown

- an entry that reads an operand over both the dimension and its member
  gets no note: it asks for the product, and the rewrite would be refused
- a declaration gets only "drop 'unit' from dims:" or "drop 'connection'
  from dims:", with no call to an operand it does not have
- a member under two roles is named as one full call per role, and the
  join as trade[dst] (or trade[src]); trade[dst or src] did not parse
- every operand over the member is named, not only the first
- a named expression over two dimensions that share a member is advised
  itself, unless an entry whose dims: lists both reads it
…ple-advice

# Conflicts:
#	docs/reference/language/dimensions.md

This branch has not been deployed

No deployments
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