docs: architecture and integration guide for decomposition solver #32

New Issue

forbes · 2026-02-20T22:28:45Z

forbes commented

2026-02-20 22:28:45 +00:00

Summary

Write developer documentation covering the decomposition solver's architecture, theory, integration with KCSolve, and extension points.

Context

The decomposition solver introduces concepts (body-bar-hinge rigidity, pebble games, biconnected decomposition, solve plan DAGs) that are unfamiliar to most CAD developers. Good documentation is essential for onboarding contributors and for the solver to be maintainable beyond the original authors.

Depends on: #30 (DecompositionSolver — the implementation to document)

Documents to create

1. `docs/ARCHITECTURE.md` — Solver architecture overview

Problem statement: why graph decomposition matters for assembly solving
Body-bar-hinge model: why this model (not bar-joint), Tay's theorem, the 3D Laman gap
Pipeline overview: constraint graph → structural analysis → decomposition → dispatch → reconciliation
Data flow diagram: SolveContext → ConstraintGraph → SolvePlan → SubproblemResults → SolveResult
Component responsibilities: one paragraph per module (constraint_graph, structural_analyzer, decomposer, dispatcher, reconciler, patterns)
Integration with KCSolve: how it registers as "decomposition", how it delegates to backend solvers

2. `docs/THEORY.md` — Mathematical foundations

Rigidity theory primer: DOF counting, sparsity conditions, Laman's theorem (2D) vs Tay's theorem (3D)
Pebble game algorithm: how (6,6)-sparsity testing works, with worked example
Biconnected decomposition: Hopcroft-Tarjan algorithm, articulation points, solve ordering
Owen's triangle decomposition: the original insight and its limitations (triconnected graphs)
Loop closure: cut-joint method, residual evaluation, warm-started refinement
References: key papers (Owen 1991, Hoffmann-Lomonosov-Sitharam 2001, Tay 1984, Lee-Streinu 2008)

3. `docs/PATTERNS.md` — Adding closed-form pattern solvers

Pattern interface: how to implement the Pattern ABC
Existing patterns: fixed joint, shaft-in-hole, planar contact, point lock — with geometry diagrams
Transform conventions: KCSolve quaternion ordering (w,x,y,z), marker semantics
Testing patterns: how to validate analytical solutions against numerical backend
Registration: how to add a new pattern to the PatternMatcher

4. `docs/INTEGRATION.md` — Integration with Kindred Create and Silo

KCSolve plugin registration: C++ plugin vs Python solver, when to use which
AssemblyObject integration: how getOrCreateSolver() selects the solver, how to switch defaults
Silo worker dispatch: solve plan DAG → parallel worker jobs, JSON serialization round-trip
Incremental re-solve: how update() caches the solve plan, what triggers a full re-decomposition
Configuration: solver preferences, backend selection, tolerance settings

Tasks

Write docs/ARCHITECTURE.md
Write docs/THEORY.md
Write docs/PATTERNS.md
Write docs/INTEGRATION.md
Add data flow diagram (text-based or Mermaid)
Cross-reference from solver repo README.md
Review for accuracy against implemented code

Acceptance criteria

A developer unfamiliar with rigidity theory can understand the solver's approach after reading THEORY.md
A developer can add a new pattern solver by following PATTERNS.md alone
ARCHITECTURE.md accurately reflects the implemented pipeline
INTEGRATION.md covers all touchpoints with KCSolve and Silo

## Summary Write developer documentation covering the decomposition solver's architecture, theory, integration with KCSolve, and extension points. ## Context The decomposition solver introduces concepts (body-bar-hinge rigidity, pebble games, biconnected decomposition, solve plan DAGs) that are unfamiliar to most CAD developers. Good documentation is essential for onboarding contributors and for the solver to be maintainable beyond the original authors. Depends on: #30 (DecompositionSolver — the implementation to document) ## Documents to create ### 1. `docs/ARCHITECTURE.md` — Solver architecture overview - **Problem statement**: why graph decomposition matters for assembly solving - **Body-bar-hinge model**: why this model (not bar-joint), Tay's theorem, the 3D Laman gap - **Pipeline overview**: constraint graph → structural analysis → decomposition → dispatch → reconciliation - **Data flow diagram**: SolveContext → ConstraintGraph → SolvePlan → SubproblemResults → SolveResult - **Component responsibilities**: one paragraph per module (constraint_graph, structural_analyzer, decomposer, dispatcher, reconciler, patterns) - **Integration with KCSolve**: how it registers as `"decomposition"`, how it delegates to backend solvers ### 2. `docs/THEORY.md` — Mathematical foundations - **Rigidity theory primer**: DOF counting, sparsity conditions, Laman's theorem (2D) vs Tay's theorem (3D) - **Pebble game algorithm**: how (6,6)-sparsity testing works, with worked example - **Biconnected decomposition**: Hopcroft-Tarjan algorithm, articulation points, solve ordering - **Owen's triangle decomposition**: the original insight and its limitations (triconnected graphs) - **Loop closure**: cut-joint method, residual evaluation, warm-started refinement - **References**: key papers (Owen 1991, Hoffmann-Lomonosov-Sitharam 2001, Tay 1984, Lee-Streinu 2008) ### 3. `docs/PATTERNS.md` — Adding closed-form pattern solvers - **Pattern interface**: how to implement the `Pattern` ABC - **Existing patterns**: fixed joint, shaft-in-hole, planar contact, point lock — with geometry diagrams - **Transform conventions**: KCSolve quaternion ordering (w,x,y,z), marker semantics - **Testing patterns**: how to validate analytical solutions against numerical backend - **Registration**: how to add a new pattern to the `PatternMatcher` ### 4. `docs/INTEGRATION.md` — Integration with Kindred Create and Silo - **KCSolve plugin registration**: C++ plugin vs Python solver, when to use which - **AssemblyObject integration**: how `getOrCreateSolver()` selects the solver, how to switch defaults - **Silo worker dispatch**: solve plan DAG → parallel worker jobs, JSON serialization round-trip - **Incremental re-solve**: how `update()` caches the solve plan, what triggers a full re-decomposition - **Configuration**: solver preferences, backend selection, tolerance settings ## Tasks - [ ] Write `docs/ARCHITECTURE.md` - [ ] Write `docs/THEORY.md` - [ ] Write `docs/PATTERNS.md` - [ ] Write `docs/INTEGRATION.md` - [ ] Add data flow diagram (text-based or Mermaid) - [ ] Cross-reference from solver repo README.md - [ ] Review for accuracy against implemented code ## Acceptance criteria - A developer unfamiliar with rigidity theory can understand the solver's approach after reading THEORY.md - A developer can add a new pattern solver by following PATTERNS.md alone - ARCHITECTURE.md accurately reflects the implemented pipeline - INTEGRATION.md covers all touchpoints with KCSolve and Silo

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/solver#32

docs: architecture and integration guide for decomposition solver #32

Summary

Context

Documents to create

1. docs/ARCHITECTURE.md — Solver architecture overview

2. docs/THEORY.md — Mathematical foundations

3. docs/PATTERNS.md — Adding closed-form pattern solvers

4. docs/INTEGRATION.md — Integration with Kindred Create and Silo