Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

Assemblies: one children-by-parent index for the occurrence walk (#12173)

CamWightbcdbb91f2622
diff --git a/crates/doc/src/assembly.rs b/crates/doc/src/assembly.rs
index fb567ecf39..071064a852 100644
--- a/crates/doc/src/assembly.rs
+++ b/crates/doc/src/assembly.rs
@@ -353,25 +353,7 @@ impl Document {
/// Every placement of each component: (component, occurrence path ids, world transform).
/// A branch stops past [`MAX_PLACEMENT_DEPTH`] levels, the walk past [`MAX_PLACEMENTS`] placements.
pub fn placements(&self) -> Vec<(u64, Vec<u64>, Mat)> {
- let mut out = vec![(0, Vec::new(), IDENTITY)];
- let mut stack: Vec<(u64, Vec<u64>, Mat)> = vec![(0, Vec::new(), IDENTITY)];
- while let Some((comp, path, m)) = stack.pop() {
- if out.len() > MAX_PLACEMENTS {
- break;
- }
- // Only this branch stops past the depth limit; the others are still walked.
- if path.len() > MAX_PLACEMENT_DEPTH {
- continue;
- }
- for o in self.occurrences.iter().filter(|o| o.parent == comp) {
- let mut p = path.clone();
- p.push(o.id);
- let w = mat_mul(&m, &o.transform);
- out.push((o.component, p.clone(), w));
- stack.push((o.component, p, w));
- }
- }
- out
+ crate::occurrence_tree::OccurrenceTree::new(self).placements_with(|o| o.transform)
}
/// Every body as the world shows it: its world name ("Body1", or "Body1 (Occ:2)" for a
@@ -461,13 +443,14 @@ impl Document {
if self.component_within(parent, component) {
return true;
}
+ let tree = crate::occurrence_tree::OccurrenceTree::new(self);
let mut stack = vec![component];
let mut seen = std::collections::BTreeSet::new();
while let Some(c) = stack.pop() {
if !seen.insert(c) || seen.len() > MAX_PLACEMENTS {
continue;
}
- for o in self.occurrences.iter().filter(|o| o.parent == c) {
+ for o in tree.children(c) {
if o.component == parent {
return true;
}
diff --git a/crates/doc/src/lib.rs b/crates/doc/src/lib.rs
index e88aafc4d0..ef1909c2f3 100644
--- a/crates/doc/src/lib.rs
+++ b/crates/doc/src/lib.rs
@@ -49,6 +49,7 @@ pub mod motion;
mod name_lookup;
mod names;
pub mod naming;
+mod occurrence_tree;
mod params;
pub mod persistent_name;
pub mod physical_material;
diff --git a/crates/doc/src/occurrence_tree.rs b/crates/doc/src/occurrence_tree.rs
new file mode 100644
index 0000000000..59f4db90ba
--- /dev/null
+++ b/crates/doc/src/occurrence_tree.rs
@@ -0,0 +1,57 @@
+//! The occurrence tree of a document: each component's child occurrences, gathered in one pass,
+//! and the walk of every placement from the root over them. Walking it costs the placements,
+//! where scanning every occurrence for each component visited cost placements times occurrences.
+
+use std::collections::HashMap;
+
+use crate::{Document, IDENTITY, MAX_PLACEMENT_DEPTH, MAX_PLACEMENTS, Mat, Occurrence, mat_mul};
+
+/// Each component's child occurrences, in document order, as a document held them when made.
+pub(crate) struct OccurrenceTree<'a> {
+ children: HashMap<u64, Vec<&'a Occurrence>>,
+}
+
+impl<'a> OccurrenceTree<'a> {
+ pub(crate) fn new(doc: &'a Document) -> Self {
+ let mut children: HashMap<u64, Vec<&Occurrence>> = HashMap::new();
+ for o in &doc.occurrences {
+ children.entry(o.parent).or_default().push(o);
+ }
+ OccurrenceTree { children }
+ }
+
+ /// The occurrences placed in `component`, in document order.
+ pub(crate) fn children(&self, component: u64) -> &[&'a Occurrence] {
+ self.children.get(&component).map_or(&[], Vec::as_slice)
+ }
+
+ /// Every placement from the root: (component, occurrence path ids, world transform), with
+ /// each occurrence placed in its parent by `transform`. Depth first, children in document
+ /// order. A branch stops past [`MAX_PLACEMENT_DEPTH`] levels, the walk past [`MAX_PLACEMENTS`]
+ /// placements.
+ pub(crate) fn placements_with(&self, transform: impl Fn(&Occurrence) -> Mat) -> Vec<(u64, Vec<u64>, Mat)> {
+ let mut out = vec![(0, Vec::new(), IDENTITY)];
+ let mut stack: Vec<(u64, Vec<u64>, Mat)> = vec![(0, Vec::new(), IDENTITY)];
+ while let Some((comp, path, m)) = stack.pop() {
+ if out.len() > MAX_PLACEMENTS {
+ break;
+ }
+ // Only this branch stops past the depth limit; the others are still walked.
+ if path.len() > MAX_PLACEMENT_DEPTH {
+ continue;
+ }
+ for o in self.children(comp) {
+ let mut p = path.clone();
+ p.push(o.id);
+ let w = mat_mul(&m, &transform(o));
+ out.push((o.component, p.clone(), w));
+ stack.push((o.component, p, w));
+ }
+ }
+ out
+ }
+}
+
+#[cfg(test)]
+#[path = "occurrence_tree_tests.rs"]
+mod tests;
diff --git a/crates/doc/src/occurrence_tree_tests.rs b/crates/doc/src/occurrence_tree_tests.rs
new file mode 100644
index 0000000000..30776de4b2
--- /dev/null
+++ b/crates/doc/src/occurrence_tree_tests.rs
@@ -0,0 +1,253 @@
+use solidcore_record::Vec3;
+
+use super::OccurrenceTree;
+use crate::*;
+
+/// `placements` as it walked before the tree: a scan of every occurrence for each component
+/// visited. The tree must give exactly this, in this order, for every document.
+fn scanning_placements(doc: &Document) -> Vec<(u64, Vec<u64>, Mat)> {
+ let mut out = vec![(0, Vec::new(), IDENTITY)];
+ let mut stack: Vec<(u64, Vec<u64>, Mat)> = vec![(0, Vec::new(), IDENTITY)];
+ while let Some((comp, path, m)) = stack.pop() {
+ if out.len() > MAX_PLACEMENTS {
+ break;
+ }
+ if path.len() > MAX_PLACEMENT_DEPTH {
+ continue;
+ }
+ for o in doc.occurrences.iter().filter(|o| o.parent == comp) {
+ let mut p = path.clone();
+ p.push(o.id);
+ let w = mat_mul(&m, &o.transform);
+ out.push((o.component, p.clone(), w));
+ stack.push((o.component, p, w));
+ }
+ }
+ out
+}
+
+/// `inside_component`'s walk as it was before the tree: is `parent` placed anywhere below `component`?
+fn scanning_inside(doc: &Document, parent: u64, component: u64) -> bool {
+ if doc.component_within(parent, component) {
+ return true;
+ }
+ let mut stack = vec![component];
+ let mut seen = std::collections::BTreeSet::new();
+ while let Some(c) = stack.pop() {
+ if !seen.insert(c) || seen.len() > MAX_PLACEMENTS {
+ continue;
+ }
+ for o in doc.occurrences.iter().filter(|o| o.parent == c) {
+ if o.component == parent {
+ return true;
+ }
+ stack.push(o.component);
+ }
+ }
+ false
+}
+
+/// Every (parent, component) pair over the ids a document names, and one id it doesn't.
+fn same_inside(doc: &Document) -> std::result::Result<(), String> {
+ let mut ids: Vec<u64> = doc.occurrences.iter().flat_map(|o| [o.parent, o.component]).chain([0, 999]).collect();
+ ids.sort_unstable();
+ ids.dedup();
+ for &parent in &ids {
+ for &component in &ids {
+ if doc.inside_component(parent, component) != scanning_inside(doc, parent, component) {
+ return Err(format!("inside_component({parent}, {component})"));
+ }
+ }
+ }
+ Ok(())
+}
+
+/// An occurrence of `component` in `parent`, moved by its id so every path's transform differs.
+fn occurrence(id: u64, component: u64, parent: u64) -> Occurrence {
+ let t = Vec3::new(id as f64, (id % 7) as f64, 0.5 * (id % 3) as f64);
+ Occurrence {
+ id,
+ component,
+ parent,
+ name: format!("C{component}:{id}"),
+ transform: rigid(t, Vec3::ZERO, Vec3::Z, 0.01 * id as f64),
+ grounded: false,
+ }
+}
+
+fn with(occurrences: Vec<Occurrence>) -> Document {
+ let mut doc = Document::new("tree");
+ doc.occurrences = occurrences;
+ doc
+}
+
+/// Component `k` placed once in component `k - 1`, `depth` levels below the root.
+fn chain(depth: u64) -> Document {
+ with((1..=depth).map(|k| occurrence(k, k, k - 1)).collect())
+}
+
+/// The documents whose walks must not move: the walk's boundaries and the hostile shapes a file
+/// can hold.
+fn shapes() -> Vec<(&'static str, Document)> {
+ // 2 under the root, each holding 400 of component 3, each holding 150 of component 4: past
+ // MAX_PLACEMENTS, so the walk stops part way.
+ let mut wide = vec![occurrence(1, 1, 0), occurrence(2, 1, 0)];
+ wide.extend((0..400).map(|i| occurrence(10 + i, 3, 1)));
+ wide.extend((0..150).map(|i| occurrence(1000 + i, 4, 3)));
+ vec![
+ ("empty", with(Vec::new())),
+ ("one level", with(vec![occurrence(1, 1, 0), occurrence(2, 2, 0), occurrence(3, 1, 0)])),
+ ("depth 63", chain(63)),
+ ("depth 64", chain(64)),
+ ("depth 65", chain(65)),
+ ("depth 66", chain(66)),
+ ("a component twice under one parent", with(vec![occurrence(1, 1, 0), occurrence(2, 2, 1), occurrence(3, 2, 1), occurrence(4, 3, 2)])),
+ ("an occurrence whose parent is missing", with(vec![occurrence(1, 1, 0), occurrence(2, 2, 99), occurrence(3, 3, 2)])),
+ ("a cycle", with(vec![occurrence(1, 1, 0), occurrence(2, 2, 1), occurrence(3, 1, 2)])),
+ ("a component inside itself", with(vec![occurrence(1, 1, 0), occurrence(2, 1, 1)])),
+ ("duplicated occurrence ids", with(vec![occurrence(1, 1, 0), occurrence(1, 2, 0), occurrence(2, 3, 1), occurrence(2, 3, 2)])),
+ ("children listed out of order", with(vec![occurrence(5, 2, 1), occurrence(1, 1, 0), occurrence(4, 3, 2), occurrence(2, 2, 1)])),
+ ("past MAX_PLACEMENTS", with(wide)),
+ ]
+}
+
+#[test]
+fn the_walk_is_the_scanning_walk_for_every_shape() {
+ for (name, doc) in shapes() {
+ let walked = doc.placements();
+ assert_eq!(walked, scanning_placements(&doc), "{name}");
+ assert_eq!(OccurrenceTree::new(&doc).placements_with(|o| o.transform), walked, "{name}");
+ if doc.occurrences.len() < 100 {
+ assert_eq!(same_inside(&doc), Ok(()), "{name}");
+ }
+ }
+}
+
+#[test]
+fn the_walk_stops_at_its_caps_as_before() {
+ let deepest = |doc: &Document| doc.placements().iter().map(|(_, path, _)| path.len()).max();
+ // A branch is walked to MAX_PLACEMENT_DEPTH levels and one past it (today's 65-id path), no further.
+ assert_eq!(deepest(&chain(64)), Some(64));
+ assert_eq!(deepest(&chain(66)), Some(MAX_PLACEMENT_DEPTH + 1));
+ let (_, wide) = shapes().pop().unwrap();
+ let n = wide.placements().len();
+ assert!(n > MAX_PLACEMENTS && n <= MAX_PLACEMENTS + 400, "stops once past the cap: {n}");
+ // A cycle ends at the depth cap, not in a loop.
+ let (_, cycle) = shapes().into_iter().find(|(name, _)| *name == "a cycle").unwrap();
+ assert_eq!(deepest(&cycle), Some(MAX_PLACEMENT_DEPTH + 1));
+}
+
+#[test]
+fn children_are_listed_in_document_order() {
+ let doc = with(vec![occurrence(5, 2, 1), occurrence(1, 1, 0), occurrence(4, 3, 1), occurrence(2, 2, 1), occurrence(3, 9, 7)]);
+ let tree = OccurrenceTree::new(&doc);
+ let ids = |c: u64| tree.children(c).iter().map(|o| o.id).collect::<Vec<_>>();
+ assert_eq!(ids(1), [5, 4, 2]);
+ assert_eq!(ids(0), [1]);
+ assert_eq!(ids(7), [3], "an occurrence under a missing parent is still its child");
+ assert!(ids(2).is_empty());
+}
+
+#[test]
+fn a_walk_uses_the_transform_it_is_given() {
+ let doc = with(vec![occurrence(1, 1, 0), occurrence(2, 2, 1)]);
+ let moved = rigid(Vec3::new(0.0, 0.0, 9.0), Vec3::ZERO, Vec3::Z, 0.0);
+ let walked = OccurrenceTree::new(&doc).placements_with(|o| if o.id == 1 { moved } else { o.transform });
+ let child = &doc.occurrences[1].transform;
+ assert_eq!(walked[1], (1, vec![1], moved));
+ assert_eq!(walked[2], (2, vec![1, 2], mat_mul(&moved, child)));
+}
+
+/// splitmix64, so each run makes the same documents.
+fn next(state: &mut u64) -> u64 {
+ *state = state.wrapping_add(0x9e37_79b9_7f4a_7c15);
+ let mut z = *state;
+ z = (z ^ (z >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
+ z = (z ^ (z >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
+ z ^ (z >> 31)
+}
+
+#[test]
+fn hostile_documents_walk_as_before() {
+ // Few component ids and parents drawn from them, so repeats, missing parents, cycles and
+ // duplicated ids all come up.
+ let mut state = 4032;
+ for round in 0..300 {
+ let n = next(&mut state) % 40;
+ let components = 1 + next(&mut state) % 12;
+ let occurrences = (0..n)
+ .map(|i| {
+ let id = if next(&mut state).is_multiple_of(9) { i / 2 } else { i + 1 };
+ let component = 1 + next(&mut state) % components;
+ let parent = next(&mut state) % (components + 2);
+ occurrence(id, component, parent)
+ })
+ .collect();
+ let doc = with(occurrences);
+ assert_eq!(doc.placements(), scanning_placements(&doc), "round {round}");
+ assert_eq!(same_inside(&doc), Ok(()), "round {round}");
+ }
+}
+
+/// A generated assembly of `top` modules, each holding `parts` parts, each part holding `pins`
+/// pins: the shape of a large imported board.
+fn assembly(top: u64, parts: u64, pins: u64) -> Document {
+ let mut occurrences = Vec::new();
+ let mut id = 0;
+ let mut add = |component: u64, parent: u64, n: u64| {
+ for _ in 0..n {
+ id += 1;
+ occurrences.push(occurrence(id, component, parent));
+ }
+ };
+ add(1, 0, top);
+ for part in 0..parts {
+ add(10 + part, 1, 1);
+ add(5, 10 + part, pins);
+ }
+ with(occurrences)
+}
+
+#[test]
+#[ignore = "manual optimized walk microbenchmark; no timing assertion"]
+fn benchmark_placements_walk() {
+ // About 10,000 and 97,500 placements, under MAX_PLACEMENTS.
+ for (top, parts, pins) in [(10, 100, 9), (39, 250, 9)] {
+ let doc = assembly(top, parts, pins);
+ let time = |walk: &dyn Fn() -> Vec<(u64, Vec<u64>, Mat)>| {
+ let start = std::time::Instant::now();
+ let walked = walk();
+ let elapsed = start.elapsed().as_secs_f64() * 1000.;
+ std::hint::black_box(walked);
+ elapsed
+ };
+ let median = |mut ms: Vec<f64>| {
+ ms.sort_by(f64::total_cmp);
+ ms[ms.len() / 2]
+ };
+ let walked = doc.placements();
+ assert_eq!(walked, scanning_placements(&doc));
+ let (scan, tree) = (|| scanning_placements(&doc), || doc.placements());
+ // Each order in turn, so neither walk always runs on a cache the other warmed.
+ for scanning_first in [true, false] {
+ let (mut old, mut new) = (Vec::new(), Vec::new());
+ for _ in 0..9 {
+ if scanning_first {
+ old.push(time(&scan));
+ new.push(time(&tree));
+ } else {
+ new.push(time(&tree));
+ old.push(time(&scan));
+ }
+ }
+ eprintln!(
+ "{} occurrences, {} placements, {} first: scanning={:.3}ms tree={:.3}ms (median of 9, tree includes building it)",
+ doc.occurrences.len(),
+ walked.len(),
+ if scanning_first { "scanning" } else { "tree" },
+ median(old),
+ median(new)
+ );
+ }
+ }
+}
diff --git a/docs/perf.md b/docs/perf.md
index 7b64405d5d..55aeaeaeae 100644
--- a/docs/perf.md
+++ b/docs/perf.md
@@ -1012,3 +1012,32 @@ cache. These counting-only hooks/switch are absent from the published source and
[Reproduction code, exact source/executable hashes and per-operation release samples](https://gist.github.com/takuto-NA/cf4c0c9a40f50d44e1b6cda96bba18bd)
cover both baseline contexts and the independent counting probe.
+
+## Occurrence placements: one children-by-parent index (2026-11-05)
+
+`Document::placements` walks the assembly tree from the root and, for each component it visits,
+scanned every occurrence for that component's children: placements times occurrences. It runs
+for every world placement (`body_frames`), the Browser, the viewport, edit in place, motion and
+export. `OccurrenceTree` (`crates/doc/src/occurrence_tree.rs`) builds the children of each
+component once, in one pass and in document order, and the walk reads them from it. The walk's
+order, its depth and count caps and where it stops are unchanged; a test compares it with the
+scanning walk on 13 shapes and on hostile generated documents. `inside_component` uses the same
+index.
+
+`benchmark_placements_walk` (ignored; `cargo test --release -p solidcraft-doc --lib
+benchmark_placements_walk -- --ignored --nocapture`) times both walks on a generated board-like
+assembly: `top` modules, each holding `parts` parts of 9 pins. It runs each order in turn (the
+scanning walk first in each round, then the tree first), so neither walk always runs on a cache
+the other warmed. Windows x64, AMD Ryzen 7 7800X3D, Rust 1.99.1, release profile; median of 9
+rounds per order, in milliseconds, the tree's time including building it:
+
+| Occurrences | Placements | First | Scanning | Tree |
+| ---: | ---: | --- | ---: | ---: |
+| 1,010 | 10,011 | scanning | 6.118 | 1.645 |
+| 1,010 | 10,011 | tree | 6.022 | 1.643 |
+| 2,539 | 97,540 | scanning | 121.283 | 15.711 |
+| 2,539 | 97,540 | tree | 120.094 | 15.456 |
+
+The order moves either walk by about 1%.
+
+Both walks return the same placements in the same order (the benchmark asserts it).