Skip to content

feat(shadows): compute joint groups of cascading elements together - #273

Closed
blackopsrepl wants to merge 1 commit into
mainfrom
feat/cascade-groups
Closed

blackopsrepl wants to merge 1 commit into
mainfrom
feat/cascade-groups

Conversation

@blackopsrepl

Copy link
Copy Markdown
Collaborator

Closes #272.

What

#[shadow_variable_updates(cascading_peers = "method")]: a solution method returning the elements computed together with an element. Peers are joined transitively into a joint group, and CascadePropagation treats the group as one node:

  • its inputs are the previous elements and dependencies of all its members, its outputs their next elements and dependents;
  • it is computed once, after every input is final, each member in ascending element order, and only when a member changed or an input value changed;
  • a member's compute may read its peers' inputs (their previous elements' values), never a peer's cascading value;
  • a group whose members wait on each other through their lists (two members on one route) is a cycle and is unset, like any other cycle.

This is how two technicians start a job together: each visit's start is the later of both arrivals, which a pair of dependencies would make a cycle.

Cost for models without peers

propagate dispatches once per call on whether any group exists. The no-peers instance is const-generic with the group lookups compiled away, so it is the 0.30.1 loop.

  • A real cascading model (a 5-machine factory task-scheduling model, 30 s solves, alternating, three rounds): 31,557 moves/s on 0.30.1 vs 31,240 on this branch, a gap of 1.0%. The same binary varies 2–7% between runs.
  • The compute counts in the existing cascade_tests (propagation stops where values are unchanged) are unchanged.
  • Models without a cascading shadow still compile none of this, so the cursor zero-regression cases don't run this code.

Tests

  • solverforge-core cascade_group_tests: pairs, a triple, dependencies, unassigned members, a group on one route (cycle), early stop on an unchanged group, and 3 × 500 random moves checked against an independent least fixed point of the compute (not against refresh_all). With groups disabled, 5 of the 7 tests fail.
  • solverforge joint_cascading_shadows: a planning_model! crew through the score director (move plus undo vs fresh shadows and score), and a full_assert solve with two pairs and a triple. With groups disabled, the solve fails with score drift.
  • The docs example in docs/modeling.md is compiled through readme_examples/crew.

Gates

  • make lint: fmt, clippy, doc names, file length, facade reachability, public API (blessed: PlanningSolution::cascading_peers), deps.
  • cargo test --workspace --no-fail-fast: 1,616 passed, 0 failed.

A cascading_peers hook joins elements, transitively, into joint groups that propagation computes as one node: after the previous element and every dependency of every member are final, each member once. Two technicians that start a visit together each wait on the other's arrival, which a pair of dependencies would make a cycle. Models without peers run an instance with the group lookups compiled away.

Closes #272
@blackopsrepl

Copy link
Copy Markdown
Collaborator Author

Landed on main through #274 (cherry-picked as authored, plus a docs-example CI fix), together with #270.

@blackopsrepl
blackopsrepl deleted the feat/cascade-groups branch November 17, 2026 05:26
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.

Cascading shadows cannot align elements of different lists (visits that start together)

1 participant