feat(solver): graph decomposition for cluster-by-cluster solving (phase 3)

Add a Python decomposition layer using NetworkX that partitions the
constraint graph into biconnected components (rigid clusters), orders
them via a block-cut tree, and solves each cluster independently.
Articulation-point bodies propagate as boundary conditions between
clusters.

New module kindred_solver/decompose.py:
- DOF table mapping BaseJointKind to residual counts
- Constraint graph construction (nx.MultiGraph)
- Biconnected component detection + articulation points
- Block-cut tree solve ordering (root-first from grounded cluster)
- Cluster-by-cluster solver with boundary body fix/unfix cycling
- Pebble game integration for per-cluster rigidity classification

Changes to existing modules:
- params.py: add unfix() for boundary body cycling
- solver.py: extract _monolithic_solve(), add decomposition branch
  for assemblies with >= 8 free bodies

Performance: for k clusters of ~n/k params each, total cost drops
from O(n^3) to O(n^3/k^2).

220 tests passing (up from 207).
This commit is contained in:
forbes-0023
2026-02-20 22:19:35 -06:00
parent 533ca91774
commit 92ae57751f
5 changed files with 1804 additions and 19 deletions

1052
tests/test_decompose.py Normal file

File diff suppressed because it is too large Load Diff

View File

@@ -65,3 +65,37 @@ class TestParamTable:
pt.add("b", 0.0, fixed=True)
pt.add("c", 0.0)
assert pt.n_free() == 2
def test_unfix(self):
pt = ParamTable()
pt.add("a", 1.0)
pt.add("b", 2.0)
pt.fix("a")
assert pt.is_fixed("a")
assert "a" not in pt.free_names()
pt.unfix("a")
assert not pt.is_fixed("a")
assert "a" in pt.free_names()
assert pt.n_free() == 2
def test_fix_unfix_roundtrip(self):
"""Fix then unfix preserves value and makes param free again."""
pt = ParamTable()
pt.add("x", 5.0)
pt.add("y", 3.0)
pt.fix("x")
pt.set_value("x", 10.0)
pt.unfix("x")
assert pt.get_value("x") == 10.0
assert "x" in pt.free_names()
# x moves to end of free list
assert pt.free_names() == ["y", "x"]
def test_unfix_noop_if_already_free(self):
"""Unfixing a free parameter is a no-op."""
pt = ParamTable()
pt.add("a", 1.0)
pt.unfix("a")
assert pt.free_names() == ["a"]
assert pt.n_free() == 1