Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
37 changes: 37 additions & 0 deletions crates/solverforge-config/WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,8 @@ Derives: `Debug, Clone, Default, Deserialize, Serialize`.
| `group_name` | `Option<String>` | `None` |
| `group_candidate_limit` | `Option<usize>` | `None`; valid: `>= 1` when set; requires `group_name`; list heuristics reject it |
| `savings_neighbors` | `Option<NonZeroU32>` | `None` (every pair scored); `0` does not parse; `ListClarkeWright` only, which then scores a pair only when one element is among the other's `savings_neighbors` nearest; other heuristics reject it |
| `max_member_distance` | `Option<NonZeroU8>` | `None` (every placement); `0` does not parse; `ListCheapestInsertion` and `ListRegretInsertion` on a list with element groups only, capping the positions from one member of a jointly placed group to the next (`1` keeps members adjacent); other heuristics and lists without groups reject it |
| `max_group_owners` | `Option<NonZeroU8>` | `None` (every allowed owner); `0` does not parse; same heuristics and lists as `max_member_distance`, trying every placement of a group only on that many owners, best contiguous fit first |
| `termination` | `Option<TerminationConfig>` | `None` |

`target` is flattened in serde, so configuration files still use top-level
Expand Down Expand Up @@ -560,9 +562,42 @@ Derives: `Debug, Clone, Deserialize, Serialize`. Manual `Default`.
| `moves_per_step` | `Option<usize>` | `None`; valid: `>= 1` when set |
| `max_source_list_len` | `Option<usize>` | `None`; valid: `>= 1` when set |
| `skip_empty_destinations` | `bool` | `false` |
| `max_member_distance` | `Option<NonZeroU8>` | `None` (every placement); `0` does not parse; with element groups, most positions from one member of a jointly recreated group to the next |
| `max_group_owners` | `Option<NonZeroU8>` | `None` (every allowed owner); `0` does not parse; with element groups, owners tried per recreated group, best contiguous fit first |
| `entity_class` | `Option<String>` | `None` |
| `variable_name` | `Option<String>` | `None` |

Either group bound requires a targeted list variable with `element_group_fn`.

### `ListGroupChangeMoveConfig`

Derives: `Debug, Clone, Default, Deserialize, Serialize`.

| Field | Type | Default |
|-------|------|---------|
| `selection_order` | `Option<SelectionOrder>` | `None` |
| `max_member_distance` | `Option<NonZeroU8>` | `None` (every placement); `0` does not parse |
| `entity_class` | `Option<String>` | `None` |
| `variable_name` | `Option<String>` | `None` |

`list_group_change_move_selector` moves a whole element group, keeping its
members' order, to positions of one owner. It requires a list variable with
`element_group_fn`.

### `ListGroupSwapMoveConfig`

Derives: `Debug, Clone, Default, Deserialize, Serialize`.

| Field | Type | Default |
|-------|------|---------|
| `selection_order` | `Option<SelectionOrder>` | `None` |
| `entity_class` | `Option<String>` | `None` |
| `variable_name` | `Option<String>` | `None` |

`list_group_swap_move_selector` exchanges two element groups of the same size
on different owners, member slot for member slot. It requires a list variable
with `element_group_fn`.

### `RecreateHeuristicType`

Enum: `FirstFit` (default), `CheapestInsertion`.
Expand Down Expand Up @@ -888,6 +923,8 @@ Derives: `Debug, Clone, Deserialize, Serialize`. Tagged `#[serde(tag = "type", r
| `ListReverseMoveSelector` | `ListReverseMoveConfig` |
| `KOptMoveSelector` | `KOptMoveSelectorConfig` |
| `ListRuinMoveSelector` | `ListRuinMoveSelectorConfig` |
| `ListGroupChangeMoveSelector` | `ListGroupChangeMoveConfig` |
| `ListGroupSwapMoveSelector` | `ListGroupSwapMoveConfig` |
| `ConflictRepairMoveSelector` | `ConflictRepairMoveSelectorConfig` |
| `CompoundConflictRepairMoveSelector` | `CompoundConflictRepairMoveSelectorConfig` |
| `LimitedNeighborhood` | `LimitedNeighborhoodConfig` |
Expand Down
15 changes: 8 additions & 7 deletions crates/solverforge-config/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,14 @@ pub use forager::{AcceptedCountForagerConfig, ForagerConfig, ScoreTieBreak};
pub use move_selector::{
CartesianProductConfig, ChangeMoveConfig, CompoundConflictRepairMoveSelectorConfig,
ConflictRepairMoveSelectorConfig, GroupedScalarMoveSelectorConfig, KOptMoveSelectorConfig,
LimitedNeighborhoodConfig, ListChangeMoveConfig, ListPermuteMoveConfig,
ListPrecedenceMoveConfig, ListReverseMoveConfig, ListRuinMoveSelectorConfig,
ListSwapMoveConfig, MoveSelectorConfig, NearbyChangeMoveConfig, NearbyListChangeMoveConfig,
NearbyListSwapMoveConfig, NearbySwapMoveConfig, PillarChangeMoveConfig, PillarSwapMoveConfig,
RecreateHeuristicType, RuinRecreateMoveSelectorConfig, SelectionOrder, SublistChangeMoveConfig,
SublistSwapMoveConfig, SwapMoveConfig, UnionMoveSelectorConfig, UnionSelectionOrder,
UnionWeighting, VariableTargetConfig,
LimitedNeighborhoodConfig, ListChangeMoveConfig, ListGroupChangeMoveConfig,
ListGroupSwapMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig,
ListReverseMoveConfig, ListRuinMoveSelectorConfig, ListSwapMoveConfig, MoveSelectorConfig,
NearbyChangeMoveConfig, NearbyListChangeMoveConfig, NearbyListSwapMoveConfig,
NearbySwapMoveConfig, PillarChangeMoveConfig, PillarSwapMoveConfig, RecreateHeuristicType,
RuinRecreateMoveSelectorConfig, SelectionOrder, SublistChangeMoveConfig, SublistSwapMoveConfig,
SwapMoveConfig, UnionMoveSelectorConfig, UnionSelectionOrder, UnionWeighting,
VariableTargetConfig,
};
pub use phase::{
ConstructionHeuristicConfig, ConstructionHeuristicType, ConstructionObligation,
Expand Down
15 changes: 14 additions & 1 deletion crates/solverforge-config/src/move_selector.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ pub use composite::{
UnionSelectionOrder, UnionWeighting,
};
pub use list::{
KOptMoveSelectorConfig, ListChangeMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig,
KOptMoveSelectorConfig, ListChangeMoveConfig, ListGroupChangeMoveConfig,
ListGroupSwapMoveConfig, ListPermuteMoveConfig, ListPrecedenceMoveConfig,
ListReverseMoveConfig, ListRuinMoveSelectorConfig, ListSwapMoveConfig,
NearbyListChangeMoveConfig, NearbyListSwapMoveConfig, SublistChangeMoveConfig,
SublistSwapMoveConfig,
Expand Down Expand Up @@ -129,6 +130,14 @@ pub enum MoveSelectorConfig {
/// List ruin move selector (LNS) — removes elements for reinsertion.
ListRuinMoveSelector(ListRuinMoveSelectorConfig),

/// List group change move selector — moves a whole element group to
/// joint positions of one owner.
ListGroupChangeMoveSelector(ListGroupChangeMoveConfig),

/// List group swap move selector — exchanges two equally sized element
/// groups on different owners.
ListGroupSwapMoveSelector(ListGroupSwapMoveConfig),

/// Neighborhood that limits the number of yielded candidates from a child selector while
/// preserving selector order.
LimitedNeighborhood(LimitedNeighborhoodConfig),
Expand Down Expand Up @@ -172,6 +181,8 @@ impl MoveSelectorConfig {
Self::ListReverseMoveSelector(config) => config.selection_order,
Self::KOptMoveSelector(config) => config.selection_order,
Self::ListRuinMoveSelector(config) => config.selection_order,
Self::ListGroupChangeMoveSelector(config) => config.selection_order,
Self::ListGroupSwapMoveSelector(config) => config.selection_order,
Self::ConflictRepairMoveSelector(config) => config.selection_order,
Self::CompoundConflictRepairMoveSelector(config) => config.selection_order,
Self::LimitedNeighborhood(_)
Expand Down Expand Up @@ -203,6 +214,8 @@ impl MoveSelectorConfig {
Self::ListReverseMoveSelector(config) => config.selection_metric.as_deref(),
Self::KOptMoveSelector(config) => config.selection_metric.as_deref(),
Self::ListRuinMoveSelector(config) => config.selection_metric.as_deref(),
Self::ListGroupChangeMoveSelector(config) => config.selection_metric.as_deref(),
Self::ListGroupSwapMoveSelector(config) => config.selection_metric.as_deref(),
Self::ConflictRepairMoveSelector(config) => config.selection_metric.as_deref(),
Self::CompoundConflictRepairMoveSelector(config) => config.selection_metric.as_deref(),
Self::LimitedNeighborhood(_)
Expand Down
53 changes: 53 additions & 0 deletions crates/solverforge-config/src/move_selector/list.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
use std::num::NonZeroU8;

use super::*;

/// Configuration for `ListChangeMoveSelector`.
Expand Down Expand Up @@ -316,6 +318,14 @@ pub struct ListRuinMoveSelectorConfig {
/// Whether recreate should skip currently empty destination lists.
#[serde(default)]
pub skip_empty_destinations: bool,
/// With element groups: most positions from one member of a jointly
/// recreated group to the next; `1` keeps members adjacent. Omitted:
/// every placement.
pub max_member_distance: Option<NonZeroU8>,
/// With element groups: tries every placement of a recreated group on at
/// most this many owners, the ones where it fits best contiguously.
/// Omitted: every owner the group allows.
pub max_group_owners: Option<NonZeroU8>,
/// Restricts the selector to one planning variable through the top-level
/// `entity_class` and `variable_name` keys; both omitted means every matching
/// variable.
Expand All @@ -333,7 +343,50 @@ impl Default for ListRuinMoveSelectorConfig {
moves_per_step: None,
max_source_list_len: None,
skip_empty_destinations: false,
max_member_distance: None,
max_group_owners: None,
target: VariableTargetConfig::default(),
}
}
}

/// Configuration for `ListGroupChangeMoveSelector`: moves a whole element
/// group, keeping its members' order, to positions of one owner.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub struct ListGroupChangeMoveConfig {
/// Order in which this selector's candidates are tried. Omitted, the runtime
/// supplies the surrounding default (`random` in local search).
#[serde(default)]
pub selection_order: Option<SelectionOrder>,
/// Name of a registered candidate metric. Required with `sorted` and
/// `probabilistic` order; rejected with any other order.
pub selection_metric: Option<String>,
/// Most positions from one member of a moved group to the next; `1`
/// keeps members adjacent. Omitted: every placement.
pub max_member_distance: Option<NonZeroU8>,
/// Restricts the selector to one planning variable through the top-level
/// `entity_class` and `variable_name` keys; both omitted means every matching
/// variable.
#[serde(flatten)]
pub target: VariableTargetConfig,
}

/// Configuration for `ListGroupSwapMoveSelector`: exchanges two element
/// groups of the same size on different owners, member slot for member slot.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub struct ListGroupSwapMoveConfig {
/// Order in which this selector's candidates are tried. Omitted, the runtime
/// supplies the surrounding default (`random` in local search).
#[serde(default)]
pub selection_order: Option<SelectionOrder>,
/// Name of a registered candidate metric. Required with `sorted` and
/// `probabilistic` order; rejected with any other order.
pub selection_metric: Option<String>,
/// Restricts the selector to one planning variable through the top-level
/// `entity_class` and `variable_name` keys; both omitted means every matching
/// variable.
#[serde(flatten)]
pub target: VariableTargetConfig,
}
17 changes: 16 additions & 1 deletion crates/solverforge-config/src/phase.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
use std::num::NonZeroU32;
use std::num::{NonZeroU32, NonZeroU8};

use serde::{Deserialize, Serialize};

Expand Down Expand Up @@ -70,6 +70,19 @@ pub struct ConstructionHeuristicConfig {
/// every pair is scored. Zero does not parse; other heuristics reject it.
pub savings_neighbors: Option<NonZeroU32>,

/// With element groups: most positions from one member of a group placed
/// jointly by `list_cheapest_insertion` or `list_regret_insertion` to the
/// next; `1` keeps members adjacent. Omitted: every placement. Other
/// heuristics, and lists without groups, reject it.
pub max_member_distance: Option<NonZeroU8>,

/// With element groups: tries every placement of a group on at most this
/// many owners, the ones where it fits best contiguously, in
/// `list_cheapest_insertion` or `list_regret_insertion`. Omitted: every
/// owner the group allows. Other heuristics, and lists without groups,
/// reject it.
pub max_group_owners: Option<NonZeroU8>,

/// Phase termination configuration.
pub termination: Option<TerminationConfig>,
}
Expand All @@ -85,6 +98,8 @@ impl Default for ConstructionHeuristicConfig {
group_name: None,
group_candidate_limit: None,
savings_neighbors: None,
max_member_distance: None,
max_group_owners: None,
termination: None,
}
}
Expand Down
14 changes: 10 additions & 4 deletions crates/solverforge-core/WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ src/
│ ├── mod.rs — Module declarations and re-exports for domain types
│ ├── traits.rs — PlanningSolution, PlanningEntity, ProblemFact, PlanningId
│ ├── cascade.rs — CascadePropagation: cascading list shadow propagation across list owners
│ ├── cascade/
│ │ ├── cycles.rs — Dependency cycles among the nodes of a stalled propagation
│ │ └── groups.rs — Joint groups: peers joined into nodes computed together
│ ├── dynamic.rs — DynamicModelBackend, scalar/list access contracts, explicit list access/metadata capabilities
│ ├── dynamic/
│ │ ├── assignment.rs — Dynamic scalar-assignment metadata contract and structural capabilities
Expand Down Expand Up @@ -157,6 +160,7 @@ Additionally, `pub mod constraint`, `pub mod constraint_weights`, `pub mod domai
| `cascading_assigned` | `fn cascading_assigned(&self, element: usize) -> bool` | Default: `false`; whether a list holds `element` |
| `cascading_next` | `fn cascading_next(&self, element: usize) -> Option<usize>` | Default: `None`; the element after `element` in its list |
| `cascading_dependencies` | `fn cascading_dependencies(&self, element: usize, dependencies: &mut Vec<usize>)` | Default: none; appends the elements `element` waits on besides its previous element. Dependencies are problem facts |
| `cascading_peers` | `fn cascading_peers(&self, element: usize, peers: &mut Vec<usize>)` | Default: none; appends the elements computed together with `element`. Peers join transitively into a joint group that propagation computes as one node. Peers are problem facts |
| `cascading_unset` | `fn cascading_unset(&self, element: usize) -> bool` | Default: `true`; whether the cascading value is unset |
| `update_cascading_shadow` | `fn update_cascading_shadow<W: FnOnce(&Self)>(&mut self, element: usize, computable: bool, before_write: W) -> bool` | Default: `false`; recomputes (or, when `computable` is `false`, unsets) the value, calls `before_write` before writing a changed value, returns whether it changed |
| `update_list_structure_shadows` | `fn update_list_structure_shadows(&mut self, descriptor_index: usize, entity_index: usize)` | Default: `update_entity_shadows`; refreshes one owner's inverse, index, previous and next shadows without the cascading shadow |
Expand Down Expand Up @@ -341,12 +345,14 @@ Derives: `Debug, Clone`

Reusable propagation state for a solution's cascading list shadow (see
`PlanningSolution::HAS_CASCADING_SHADOWS`): the reverse index of the declared
dependencies plus per-element scratch. `Default`.
dependencies, the joint groups of declared peers, plus per-node scratch.
Propagation works on nodes: a joint group, or an element of none; without
peers every element is its own node. `Default`.

- `new<S: PlanningSolution>(&S) -> Self` — state with the dependency index built.
- `rebuild_dependencies<S: PlanningSolution>(&mut self, &S)` — rebuilds the index and resizes scratch; panics on a dependency to a missing element.
- `new<S: PlanningSolution>(&S) -> Self` — state with the dependency index and groups built.
- `rebuild_dependencies<S: PlanningSolution>(&mut self, &S)` — rebuilds the index and the groups and resizes scratch; panics on a dependency or peer to a missing element.
- `refresh_all<S: PlanningSolution>(&mut S)` — recomputes every cascading value.
- `propagate<S, I, W>(&mut self, &mut S, changed: I, before_write: W)` with `I: IntoIterator<Item = usize>`, `W: FnMut(&S, usize)` — recomputes the downstream cone of the `changed` elements in dependency order: each element at most once, after its inputs in the cone, and only when it is changed, an input changed value, or it is held by a list but unset; elements on a dependency cycle are unset. `before_write` sees the solution before each write.
- `propagate<S, I, W>(&mut self, &mut S, changed: I, before_write: W)` with `I: IntoIterator<Item = usize>`, `W: FnMut(&S, usize)` — recomputes the downstream cone of the nodes of the `changed` elements in dependency order: each node at most once, after the inputs of all its members in the cone, its members in ascending element order, and only when a member is changed, an input changed value, or a member is held by a list but unset; elements on a dependency cycle are unset. `before_write` sees the solution before each write.

#### `EntityCollectionExtractor<S, E>`

Expand Down
Loading
Loading