Skip to content

feat(list): element groups, and joint cascading groups - #274

Merged
blackopsrepl merged 3 commits into
mainfrom
feat/list-groups-and-joint-cascades
Nov 17, 2026
Merged

blackopsrepl merged 3 commits into
mainfrom
feat/list-groups-and-joint-cascades

Conversation

@blackopsrepl

Copy link
Copy Markdown
Collaborator

Closes #270. Closes #272 (supersedes #273, cherry-picked as authored).

One branch, one gate, one release.

#272: joint cascading groups (aa944f3c, from #273)

#[shadow_variable_updates(cascading_peers = "method")] names elements computed together. Peers are joined transitively into one node of the dependency graph: its inputs are every member's previous element and dependencies, its outputs every member's next element and dependents. A group whose members wait on each other through their lists is a cycle and is unset. Models without peers run a const-generic instance with the group lookups compiled away.

1d8dbbeb fixes the #273 CI failure: the docs example's Crew re-exports were unused under -D warnings. A readme test now solves the documented crew and checks partners start together.

#270: list element groups

#[planning_list_variable(element_group_fn = "path")], fn(&Solution, element, &mut Vec<usize>), appends the members of an element's group in order. Groups of two or more members share one owner and keep their order; other elements may sit between members.

  • Moves. list_group_change_move_selector relocates a whole group to joint positions of one owner (max_member_distance). list_group_swap_move_selector exchanges equally sized groups on two owners. list_ruin_move_selector ruins whole groups and recreates each jointly (max_member_distance, max_group_owners). Every move has exact undo, tabu signatures and candidate-trace identity.
  • Single-element moves keep grouped elements on their owner (reorder only), so no move splits a group.
  • Construction. list_cheapest_insertion and list_regret_insertion place each group as one unit, all member positions chosen together. A member is never placed alone, and assigned members pin the rest of their group to their owner. list_round_robin, list_clarke_wright and the global first_fit/cheapest_insertion reject a grouped list.
  • Owner restrictions and pinning. A group goes only to an owner every member allows under element_owner_fn and that is not pinned, in moves, ruin and construction.
  • Bounds. Joint placement is bounded by max_member_distance (positions from one member to the next; 1 = adjacent) and an owner shortlist (max_group_owners, best contiguous fit first). Both are Option<NonZeroU8>, so 0 does not parse. They are rejected on lists without groups and on other heuristics.
  • Defaults. A grouped list gets ListCheapestInsertion with max_group_owners = 4 (reason element_groups_declared), group change plus group swap ahead of the other list families, and its own ruin with max_member_distance = 7, max_group_owners = 4.
  • Compile-time rejection. Group selectors and ruin group bounds require the ListElementGroups capability. element_group_fn together with precedence hooks is a macro error (trybuild case).

Models without the hook keep the same hot path. Group data is Option<Box<_>> decided once per step and frozen into the nearby probe, so ungrouped cursors do no per-candidate work.

Every struct this change touches keeps its v0.30.1 size, measured with size_of on both trees before the gate:

  • list recipe 520, move 600, undo 400, slot cursor enum 992;
  • ListVariableSlot 280, RuntimeListSlot 400;
  • MoveSelectorConfig 136, ConstructionHeuristicConfig 224, ListRuinMoveSelectorConfig 128, PhaseConfig 400, SolverConfig 208;
  • list leaf spec 48, plan 120, compiled selector node 608, compiled construction 688.

Two layout decisions keep these sizes:

  • The precedence-successor and element-group hooks are mutually exclusive, so they share one slot field with a 1-byte kind in existing padding.
  • The bounds are single bytes that fit existing padding.

Tests

  • list_groups: index, conflicting answers, joint placement enumeration and bounds.
  • list_leaf::tests::groups: exact group change counts (80 unbounded, 28 at distance 1) and group swap counts (4), with do/undo restoring the lists and every pair intact after each move; grouped ruin drawing whole pairs; list change keeping grouped elements on their owner.
  • Facade list_element_groups: a pick-up and delivery model through the default plan and through regret construction plus every group family, both under full_assert, every job on one vehicle with its pick-up first and hard score 0; round robin rejected.
  • The docs/modeling.md example is compiled through readme_examples.

BREAKING CHANGE: ListVariableSlot::precedence_successors_fn is now a method (the field is private and shared with element_group_fn()); ListRuinMoveSelectorConfig and ConstructionHeuristicConfig gain public fields, and MoveSelectorConfig gains ListGroupChangeMoveSelector and ListGroupSwapMoveSelector. Struct literals and exhaustive matches need updating.

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
The crew example's re-exports were unused, which failed the readme_examples
build under -D warnings. A test now builds the documented crew and checks
that partner visits start together when the later technician arrives.
`#[planning_list_variable(element_group_fn = "path")]` declares element
groups: the hook appends an element's group members in order. Groups of
two or more members share one owner and keep their order, with other
elements allowed between members.

- `list_group_change_move_selector` relocates a whole group to joint
  positions of one owner; `list_group_swap_move_selector` exchanges
  equally sized groups on two owners.
- `list_ruin_move_selector` ruins whole groups and recreates each one
  jointly.
- `list_cheapest_insertion` and `list_regret_insertion` place each group
  as one unit; other construction heuristics reject a grouped list.
- Single-element list moves keep grouped elements on their owner.
- `max_member_distance` and `max_group_owners` (`Option<NonZeroU8>`)
  bound joint placement. Grouped lists get defaults for construction,
  group moves and ruin.
- Group selectors and ruin bounds require the element-groups capability.
  `element_group_fn` with precedence hooks is a macro error.

Ungrouped models keep the same hot path and every touched struct keeps
its size: the precedence-successor and group hooks share one slot field
with a kind byte in existing padding, and the bounds are single bytes.

Closes #270

BREAKING CHANGE: `ListVariableSlot::precedence_successors_fn` is now a
method (`element_group_fn()` shares its private field).
`ListRuinMoveSelectorConfig` and `ConstructionHeuristicConfig` gain
`max_member_distance` and `max_group_owners`, and `MoveSelectorConfig`
gains `ListGroupChangeMoveSelector` and `ListGroupSwapMoveSelector`.
Update struct literals and exhaustive matches.
@blackopsrepl

Copy link
Copy Markdown
Collaborator Author

Zero-regression gate — c2676b16 vs ebab46ba (main = v0.30.1): passed (EXIT 0)

14 cases, 5 layouts, 51 trials. semantic_match on every case: True.

  • wall: -1.11% … +1.49%
  • instructions: -0.24% … +0.87%
  • allocations: +0.00% … +0.00%
  • allocated bytes: +0.00% … +0.00%
  • simulated D1 misses: -1.39% … +0.57%
  • simulated LL misses: +0.03% … +1.22%

Evidence: zr-pr274-c2676b16-vs-ebab46ba/report.json.

@blackopsrepl
blackopsrepl merged commit b5ee4ff into main Nov 17, 2026
7 checks passed
@blackopsrepl
blackopsrepl deleted the feat/list-groups-and-joint-cascades branch November 17, 2026 01:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant