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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.mdindex 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).