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
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,10 @@ runs:
- The descriptor-placement scalar construction placer
(`RuntimeScalarConstructionPlacer`) and the compiled runtime phase runner
that solves first-fit construction.
- Route moves executed against a scored model: the score director's
cascading list-shadow row maintenance (`route_rows`), and grouped list
ruin-and-recreate with joint placement of each element group
(`group_ruin`), each candidate done, scored and undone.

The standalone `heuristic/selector` selectors, decorators, and
`QueuedEntityPlacer` are test oracles only; no production path runs them.
Expand Down
1 change: 1 addition & 0 deletions crates/solverforge-core/WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,7 @@ Additionally, `pub mod constraint`, `pub mod constraint_weights`, `pub mod domai
| `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 |
| `list_structure_unchanged` | `fn list_structure_unchanged(&self, element: usize, owner_descriptor: usize, owner_index: usize, index: usize, previous: Option<usize>, next: Option<usize>) -> bool` | Default: `false`; whether the element's owner, previous and next (and index, when declared) shadows already hold the given place. A score director with a cascading shadow asks it before rewriting an owner's structure and keeps the row of an element that answers `true` and whose cascading value is unchanged |
| `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
3 changes: 2 additions & 1 deletion crates/solverforge-core/public-api.txt
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,7 @@ trait domain::PlanningEntity: pub trait PlanningEntity: Clone + Send + Sync + An
trait domain::PlanningId: pub trait PlanningId { type Id: Eq + Hash + Clone + Send + Sync + 'static; // Required method fn planning_id(&self) -> Self::Id; }
domain::PlanningId: type Id: Eq + Hash + Clone + Send + Sync + 'static
domain::PlanningId: fn planning_id(&self) -> Self::Id
trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync + 'static { type Score: Score; const HAS_CONSTRAINT_WEIGHTS: bool = false; const HAS_CASCADING_SHADOWS: bool = false; Show 17 methods // Required methods fn score(&self) -> Option<Self::Score>; fn set_score(&mut self, score: Option<Self::Score>); // Provided methods fn update_entity_shadows( &mut self, _descriptor_index: usize, _entity_index: usize, ) { ... } fn update_all_shadows(&mut self) { ... } fn constraint_weights(&self) -> Option<&ConstraintWeights> { ... } fn list_shadow_elements( &self, _descriptor_index: usize, _entity_index: usize, ) -> Option<(usize, &[usize])> { ... } fn clear_list_shadows(&mut self, _element: usize) { ... } fn list_shadow_source(_collection: &str) -> Option<usize> { ... } fn cascading_element_count(&self) -> usize { ... } fn cascading_assigned(&self, _element: usize) -> bool { ... } fn cascading_next(&self, _element: usize) -> Option<usize> { ... } fn cascading_dependencies( &self, _element: usize, _dependencies: &mut Vec<usize>, ) { ... } fn cascading_peers(&self, _element: usize, _peers: &mut Vec<usize>) { ... } fn cascading_unset(&self, _element: usize) -> bool { ... } fn update_cascading_shadow<W: FnOnce(&Self)>( &mut self, _element: usize, _computable: bool, _before_write: W, ) -> bool { ... } fn update_list_structure_shadows( &mut self, descriptor_index: usize, entity_index: usize, ) { ... } fn is_initialized(&self) -> bool { ... } }
trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync + 'static { type Score: Score; const HAS_CONSTRAINT_WEIGHTS: bool = false; const HAS_CASCADING_SHADOWS: bool = false; Show 18 methods // Required methods fn score(&self) -> Option<Self::Score>; fn set_score(&mut self, score: Option<Self::Score>); // Provided methods fn update_entity_shadows( &mut self, _descriptor_index: usize, _entity_index: usize, ) { ... } fn update_all_shadows(&mut self) { ... } fn constraint_weights(&self) -> Option<&ConstraintWeights> { ... } fn list_shadow_elements( &self, _descriptor_index: usize, _entity_index: usize, ) -> Option<(usize, &[usize])> { ... } fn clear_list_shadows(&mut self, _element: usize) { ... } fn list_shadow_source(_collection: &str) -> Option<usize> { ... } fn cascading_element_count(&self) -> usize { ... } fn cascading_assigned(&self, _element: usize) -> bool { ... } fn cascading_next(&self, _element: usize) -> Option<usize> { ... } fn cascading_dependencies( &self, _element: usize, _dependencies: &mut Vec<usize>, ) { ... } fn cascading_peers(&self, _element: usize, _peers: &mut Vec<usize>) { ... } fn list_structure_unchanged( &self, _element: usize, _owner_descriptor: usize, _owner_index: usize, _index: usize, _previous: Option<usize>, _next: Option<usize>, ) -> bool { ... } fn cascading_unset(&self, _element: usize) -> bool { ... } fn update_cascading_shadow<W: FnOnce(&Self)>( &mut self, _element: usize, _computable: bool, _before_write: W, ) -> bool { ... } fn update_list_structure_shadows( &mut self, descriptor_index: usize, entity_index: usize, ) { ... } fn is_initialized(&self) -> bool { ... } }
domain::PlanningSolution: const HAS_CONSTRAINT_WEIGHTS: bool = false
domain::PlanningSolution: const HAS_CASCADING_SHADOWS: bool = false
domain::PlanningSolution: type Score: Score
Expand All @@ -313,6 +313,7 @@ trait domain::PlanningSolution: pub trait PlanningSolution: Clone + Send + Sync
domain::PlanningSolution: fn cascading_next(&self, _element: usize) -> Option<usize>
domain::PlanningSolution: fn cascading_dependencies( &self, _element: usize, _dependencies: &mut Vec<usize>, )
domain::PlanningSolution: fn cascading_peers(&self, _element: usize, _peers: &mut Vec<usize>)
domain::PlanningSolution: fn list_structure_unchanged( &self, _element: usize, _owner_descriptor: usize, _owner_index: usize, _index: usize, _previous: Option<usize>, _next: Option<usize>, ) -> bool
domain::PlanningSolution: fn cascading_unset(&self, _element: usize) -> bool
domain::PlanningSolution: fn update_cascading_shadow<W: FnOnce(&Self)>( &mut self, _element: usize, _computable: bool, _before_write: W, ) -> bool
domain::PlanningSolution: fn update_list_structure_shadows( &mut self, descriptor_index: usize, entity_index: usize, )
Expand Down
22 changes: 22 additions & 0 deletions crates/solverforge-core/src/domain/traits.rs
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,28 @@ pub trait PlanningSolution: Clone + Send + Sync + 'static {
/// never change them.
fn cascading_peers(&self, _element: usize, _peers: &mut Vec<usize>) {}

/// Whether `element`'s list structure shadows already describe the place
/// `owner_descriptor`/`owner_index`, position `index`, between `previous`
/// and `next`: its owner, previous and next shadows (and index shadow,
/// when declared) hold those values.
///
/// A score director with a cascading shadow asks this before rewriting an
/// owner's structure and keeps the stream row of an element that answers
/// `true` and whose cascading value does not change. `false` (the default)
/// rescores the element. `#[shadow_variable_updates(cascading_field =
/// ...)]` generates it from the configured structure fields.
fn list_structure_unchanged(
&self,
_element: usize,
_owner_descriptor: usize,
_owner_index: usize,
_index: usize,
_previous: Option<usize>,
_next: Option<usize>,
) -> bool {
false
}

/// Whether `element`'s cascading value is unset.
fn cascading_unset(&self, _element: usize) -> bool {
true
Expand Down
3 changes: 2 additions & 1 deletion crates/solverforge-macros/WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -397,7 +397,8 @@ element shadows score incrementally.

With `cascading_field`, the generated support sets
`PlanningSolution::HAS_CASCADING_SHADOWS = true` and implements the
`cascading_*` hooks, `update_cascading_shadow` and
`cascading_*` hooks, `list_structure_unchanged` (comparing the inverse,
previous, next and, when configured, index fields), `update_cascading_shadow` and
`update_list_structure_shadows` (the owner update without the cascading
shadow). `update_entity_shadows` refreshes the owner's structure, then
propagates the cascading values from its elements with `CascadePropagation`;
Expand Down
30 changes: 30 additions & 0 deletions crates/solverforge-macros/src/planning_model/cascade.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ propagation itself, its ordering and its change reporting are SolverForge's.

struct CascadeContext<'a> {
solution_path: &'a TokenStream,
// The list owner's descriptor index.
descriptor_index: usize,
element_accessor: &'a Ident,
element_mut_accessor: &'a Ident,
}
Expand Down Expand Up @@ -53,13 +55,23 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) -
let span = proc_macro2::Span::call_site();
let CascadeContext {
solution_path,
descriptor_index,
element_accessor,
element_mut_accessor,
} = context;
let field = Ident::new(config.cascading_field.as_deref().unwrap(), span);
let compute = Ident::new(config.cascading_compute.as_deref().unwrap(), span);
let inverse = Ident::new(config.inverse_field.as_deref().unwrap(), span);
let next = Ident::new(config.next_field.as_deref().unwrap(), span);
let previous = Ident::new(config.previous_field.as_deref().unwrap(), span);
let index_matches = config
.index_field
.as_deref()
.map(|field| {
let field = Ident::new(field, span);
quote! { && stored.#field == ::core::option::Option::Some(index) }
})
.unwrap_or_default();
let dependencies = config
.cascading_dependencies
.as_deref()
Expand Down Expand Up @@ -103,6 +115,24 @@ fn generate_cascade_hooks(config: &ShadowConfig, context: &CascadeContext<'_>) -
#peers
}

#[allow(unused_variables)]
fn list_structure_unchanged(
solution: &Self,
element: usize,
owner_descriptor: usize,
owner_index: usize,
index: usize,
previous: ::core::option::Option<usize>,
next: ::core::option::Option<usize>,
) -> bool {
let stored = &#solution_path::#element_accessor(solution)[element];
owner_descriptor == #descriptor_index
&& stored.#inverse == ::core::option::Option::Some(owner_index)
&& stored.#previous == previous
&& stored.#next == next
#index_matches
}

fn cascading_unset(solution: &Self, element: usize) -> bool {
#solution_path::#element_accessor(solution)[element].#field.is_none()
}
Expand Down
1 change: 1 addition & 0 deletions crates/solverforge-macros/src/planning_model/shadows.rs
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,7 @@ fn generate_list_shadow_update(
config,
&CascadeContext {
solution_path,
descriptor_index,
element_accessor: &element_accessor,
element_mut_accessor: &element_mut_accessor,
},
Expand Down
21 changes: 21 additions & 0 deletions crates/solverforge-macros/src/planning_solution/shadow.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,27 @@ pub(super) fn generate_shadow_support(
)
}

#[inline]
fn list_structure_unchanged(
&self,
element: usize,
owner_descriptor: usize,
owner_index: usize,
index: usize,
previous: ::core::option::Option<usize>,
next: ::core::option::Option<usize>,
) -> bool {
<Self as ::solverforge::__internal::PlanningModelSupport>::list_structure_unchanged(
self,
element,
owner_descriptor,
owner_index,
index,
previous,
next,
)
}

#[inline]
fn cascading_unset(&self, element: usize) -> bool {
<Self as ::solverforge::__internal::PlanningModelSupport>::cascading_unset(self, element)
Expand Down
24 changes: 15 additions & 9 deletions crates/solverforge-scoring/WIREFRAME.md
Original file line number Diff line number Diff line change
Expand Up @@ -250,7 +250,7 @@ src/
│ │ ├── score_director/incremental.rs — ScoreDirector<S,C,Desc,M> (zero-erasure incremental)
│ │ ├── score_director/constructors.rs — ScoreDirector constructors, weighted constructors, replica-forking constructors, into_weight_mode
│ │ ├── score_director/descriptor.rs — DirectorDescriptor (owned or borrowed SolutionDescriptor)
│ │ ├── score_director/list_shadows.rs — Retract/insert of list-shadowed element rows around owner shadow updates
│ │ ├── score_director/list_shadows.rs — Retract/insert of list-shadowed element rows around owner shadow updates; with a cascading shadow, only rows whose structure or cascading value changes
│ │ ├── score_director/weight_mode.rs — WeightMode (sealed), UnweightedMode, WeightedMode, requires_weighted_mode, static per-mode scoring dispatch
│ │ ├── score_director/analysis.rs — ScoreDirector constraint_results/constraint_analyses/constraint_match_totals
│ │ └── score_director/adapters.rs — Debug and Director trait impls for ScoreDirector
Expand Down Expand Up @@ -501,14 +501,20 @@ inserts the owner and every element it now holds, and clears and re-inserts
elements that left the owner without joining another list. Element rows
therefore always hold the shadows they were inserted with.

When `S::HAS_CASCADING_SHADOWS` is `true`, element rows are deferred to the
end of the move: each `after_variable_changed` refreshes only the owner's list
structure (`update_list_structure_shadows`) and inserts the owner, and when the
move's last notified owner has been refreshed the director propagates the
cascading values (`CascadePropagation`) from every element those owners held
before or after the move. An element written during propagation is retracted
before its write unless it is already pending, and every pending element is
inserted once. The branch is on the associated constant, so other solutions
When `S::HAS_CASCADING_SHADOWS` is `true`, only rows whose shadows change are
rescored, and they are deferred to the end of the move.
`before_variable_changed` records the elements the owner holds and retracts
no element row. Each `after_variable_changed` retracts the rows of the
owner's elements whose structure shadows do not already describe their new
place (`list_structure_unchanged`, asked before the rewrite), arrivals from
no list included, then
refreshes only the owner's list structure (`update_list_structure_shadows`)
and inserts the owner. When the move's last notified owner has been
refreshed, an element that was held and is now in no list is retracted and
cleared, the director propagates the cascading values (`CascadePropagation`)
from the retracted elements, an element written during propagation is
retracted before its write unless it is already pending, and every pending
element is inserted once. The branch is on the associated constant, so other solutions
compile none of it.

### `SolvableSolution` — `: PlanningSolution`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -208,19 +208,24 @@ where
entity_index,
descriptor_index,
);
let element_delta = self.list_shadow_rows.retract_held(
&self.working_solution,
&mut ModeRows {
constraints: &mut self.constraints,
mode: &self.weight_mode,
},
descriptor_index,
entity_index,
);
if S::HAS_CASCADING_SHADOWS {
self.list_shadow_rows
.begin_cascading_change(&self.working_solution);
}
let element_delta = if S::HAS_CASCADING_SHADOWS {
self.list_shadow_rows.begin_cascading_change(
&self.working_solution,
descriptor_index,
entity_index,
);
S::Score::zero()
} else {
self.list_shadow_rows.retract_held(
&self.working_solution,
&mut ModeRows {
constraints: &mut self.constraints,
mode: &self.weight_mode,
},
descriptor_index,
entity_index,
)
};
let mut score = ScoreSum::new();
score.add(self.cached_score);
score.add(delta);
Expand Down
Loading
Loading