sci-solver 0.1.0__tar.gz → 0.2.0__tar.gz

{sci_solver-0.1.0 → sci_solver-0.2.0}/CITATION.cff

@@ -5,7 +5,7 @@ title: "SCI: Sequential Contact Insertion"
 authors:
   - family-names: Kamm
     given-names: Jan
-version: 0.1.0
+version: 0.2.0
 license: Apache-2.0
 repository-code: "https://github.com/jankammeth/sci"
 abstract: "Continuous-time robot fleet planning with sequential contact insertion."

{sci_solver-0.1.0 → sci_solver-0.2.0}/MANIFEST.in

@@ -3,5 +3,5 @@ recursive-include docs *.md
 recursive-include examples *.py *.json
 recursive-include tests *.py *.npz
 recursive-include tools *.py
-recursive-include validation *.json
+recursive-include validation *.json *.json.gz *.csv
 include src/sci_solver/solvers/_cubic_minima.c

{sci_solver-0.1.0 → sci_solver-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sci-solver
-Version: 0.1.0
+Version: 0.2.0
 Summary: Sequential Contact Insertion for continuous-time robot fleet planning.
 Author: Jan Kamm
 License-Expression: Apache-2.0
@@ -38,13 +38,13 @@ checks separation over the entire trajectory.
 
 ## Installation
 
-Python 3.10 or newer is required. After the first PyPI release:
+Python 3.10 or newer is required. Install from [PyPI](https://pypi.org/project/sci-solver/):
 
 ```sh
 pip install sci-solver
 ```
 
-To install directly from GitHub now:
+To install directly from GitHub:
 
 ```sh
 python -m pip install git+https://github.com/jankammeth/sci.git
@@ -116,6 +116,21 @@ and diagnostics; it is not a usable collision-free plan. Tolerances are absolute
 and should be chosen for the physical scale of the problem. The reference default
 separation allowance is zero; the examples explicitly use `1e-6`.
 
+Starting with 0.2.0, the default `sci_fleet_mode="components"` uses union-find to
+group robots connected by contacts and solves one system per group. Robots with
+no contacts follow their unconstrained trajectories. Unchanged groups reuse their
+solutions and checks. All modes check continuous separation across the entire fleet.
+
+Select `SolverConfig(sci_fleet_mode="full")` to reproduce the earlier full-fleet
+formulation, or `sci_fleet_mode="active"` to solve one system containing all
+participating robots. The default uses the same component algorithm for every
+fleet size; it has no robot-count threshold. Small contacting fleets can incur
+extra bookkeeping overhead; the benchmarks report those cases as well.
+[The component reuse benchmark](docs/component-reuse.md) compares the optimized
+driver with its prototype and full-fleet mode on saved 2-, 4-, and 20-robot cases,
+including a detailed Newton breakdown. Unchanged components retain their solved
+states and checks; graph rebuilding remains simple union-find.
+
 ## Development and provenance
 
 ```sh
@@ -127,10 +142,14 @@ ruff check .
 The numerical implementation is preserved from
 [`contact-solver` at `641a234`](https://github.com/jankammeth/contact-solver/tree/641a2341a6a59938e285b8ff872bd484713e0605).
 [UPSTREAM.json](UPSTREAM.json) records source paths, SHA-256 hashes, and every
-extraction edit. Six core files are byte-identical. The collision wrapper changes
+extraction edit. Four core files remain byte-identical. The collision wrapper changes
 only the package name in its fallback warning; the C kernel adds equivalent
 stack workspace allocation for Microsoft's C compiler. Numerical formulas and
-control flow are unchanged.
+control flow in the explicit full-fleet mode are retained; its driver records
+stage timings and dispatches the default component solver. Contact initialization,
+recovery, and validation are shared with the component driver; Newton has optional
+fine stage profiling. Original extraction hashes are retained alongside current
+hashes and change descriptions.
 [The migration guide](docs/migration.md) describes the extraction and comparison
 procedure. The paper and historical experiment infrastructure remain separate.
 

{sci_solver-0.1.0 → sci_solver-0.2.0}/README.md

@@ -10,13 +10,13 @@ checks separation over the entire trajectory.
 
 ## Installation
 
-Python 3.10 or newer is required. After the first PyPI release:
+Python 3.10 or newer is required. Install from [PyPI](https://pypi.org/project/sci-solver/):
 
 ```sh
 pip install sci-solver
 ```
 
-To install directly from GitHub now:
+To install directly from GitHub:
 
 ```sh
 python -m pip install git+https://github.com/jankammeth/sci.git
@@ -88,6 +88,21 @@ and diagnostics; it is not a usable collision-free plan. Tolerances are absolute
 and should be chosen for the physical scale of the problem. The reference default
 separation allowance is zero; the examples explicitly use `1e-6`.
 
+Starting with 0.2.0, the default `sci_fleet_mode="components"` uses union-find to
+group robots connected by contacts and solves one system per group. Robots with
+no contacts follow their unconstrained trajectories. Unchanged groups reuse their
+solutions and checks. All modes check continuous separation across the entire fleet.
+
+Select `SolverConfig(sci_fleet_mode="full")` to reproduce the earlier full-fleet
+formulation, or `sci_fleet_mode="active"` to solve one system containing all
+participating robots. The default uses the same component algorithm for every
+fleet size; it has no robot-count threshold. Small contacting fleets can incur
+extra bookkeeping overhead; the benchmarks report those cases as well.
+[The component reuse benchmark](docs/component-reuse.md) compares the optimized
+driver with its prototype and full-fleet mode on saved 2-, 4-, and 20-robot cases,
+including a detailed Newton breakdown. Unchanged components retain their solved
+states and checks; graph rebuilding remains simple union-find.
+
 ## Development and provenance
 
 ```sh
@@ -99,10 +114,14 @@ ruff check .
 The numerical implementation is preserved from
 [`contact-solver` at `641a234`](https://github.com/jankammeth/contact-solver/tree/641a2341a6a59938e285b8ff872bd484713e0605).
 [UPSTREAM.json](UPSTREAM.json) records source paths, SHA-256 hashes, and every
-extraction edit. Six core files are byte-identical. The collision wrapper changes
+extraction edit. Four core files remain byte-identical. The collision wrapper changes
 only the package name in its fallback warning; the C kernel adds equivalent
 stack workspace allocation for Microsoft's C compiler. Numerical formulas and
-control flow are unchanged.
+control flow in the explicit full-fleet mode are retained; its driver records
+stage timings and dispatches the default component solver. Contact initialization,
+recovery, and validation are shared with the component driver; Newton has optional
+fine stage profiling. Original extraction hashes are retained alongside current
+hashes and change descriptions.
 [The migration guide](docs/migration.md) describes the extraction and comparison
 procedure. The paper and historical experiment infrastructure remain separate.
 

{sci_solver-0.1.0 → sci_solver-0.2.0}/UPSTREAM.json

@@ -10,7 +10,14 @@
     "src/sci_solver/solvers/contact_solver.py": {
       "upstream_path": "src/contact_solver/solvers/contact_solver.py",
       "sha256": "9ae40bc11838b8fc0ca76f439f21af878d27669f3d3440bfd8519196e624b7a1",
-      "extracted_sha256": "9ae40bc11838b8fc0ca76f439f21af878d27669f3d3440bfd8519196e624b7a1"
+      "extracted_sha256": "9ae40bc11838b8fc0ca76f439f21af878d27669f3d3440bfd8519196e624b7a1",
+      "current_sha256": "08214666e733cfe2fe8c3f5b249ab08ec4c6ee6475cc6c771914cd46a46f6cc6",
+      "post_extraction_changes": [
+        "Active-robot and connected-component matching drivers; components become the default in 0.2.0, with explicit full mode retained.",
+        "Disjoint stage timings and system sizes for benchmark comparisons.",
+        "Share pure contact initialization, recovery and validation operations with lightweight components; allow selected-coordinate evaluation.",
+        "Configuration objects without a fleet-mode field inherit the public SolverConfig default."
+      ]
     },
     "src/sci_solver/solvers/collision_search.py": {
       "upstream_path": "src/contact_solver/solvers/collision_search.py",
@@ -31,7 +38,11 @@
     "src/sci_solver/solvers/matching_numerics.py": {
       "upstream_path": "src/contact_solver/solvers/matching_numerics.py",
       "sha256": "e10f5dbf0747163754355cdffd62b9067b2dea82a31d72222e368f67f7a8cd66",
-      "extracted_sha256": "e10f5dbf0747163754355cdffd62b9067b2dea82a31d72222e368f67f7a8cd66"
+      "extracted_sha256": "e10f5dbf0747163754355cdffd62b9067b2dea82a31d72222e368f67f7a8cd66",
+      "current_sha256": "67abc420c4b84ea8947a798b3913597baee9aaa9b5c9ad069dac82811b400889",
+      "post_extraction_changes": [
+        "Optional Newton-stage timing and LSMR iteration diagnostics; numerical algorithm and tolerances unchanged."
+      ]
     },
     "src/sci_solver/solvers/reaction_matching.py": {
       "upstream_path": "src/contact_solver/solvers/reaction_matching.py",

sci_solver-0.2.0/docs/api.md

@@ -0,0 +1,121 @@
+# API and numerical options
+
+`solve(initial_positions, final_positions, *, time_horizon, min_distance,
+initial_velocities=None, final_velocities=None, options=None)` returns a `Solution`.
+Endpoint arrays have shape `(N, d)` with `N >= 2` and `d >= 2`.
+
+## Results
+
+| Member | Meaning |
+| --- | --- |
+| `success` | Matching checks and continuous separation both passed. |
+| `sample(times, derivative=0)` | Array with shape `(N, len(times), d)`; derivative orders 0–3. |
+| `trajectory` | Knot times, relative cubic coefficients, and barycenter coefficients. |
+| `contacts` | Pair indices, times, normals, relative velocities, and reaction masses. |
+| `acceleration_cost` | Integrated sum of squared robot accelerations. |
+| `metrics` | Status, reason, residuals, separation, backend, timing, and recovery details. |
+
+Times may be unordered but must be finite and inside the horizon. At a contact,
+the third derivative uses the segment to its right; the final endpoint uses the
+last segment. Orders 0–2 are continuous up to the matching tolerance.
+
+## Options
+
+Pass `SolverConfig(...)` through `options`. Numerical tolerances retain the
+reference defaults; equation systems use contact components by default since 0.2.0.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `sci_detection_tol` | `0.0` | Allowed absolute separation deficit. |
+| `sci_residual_tol` | `1e-7` | Matching and endpoint residual tolerance. |
+| `sci_mass_tol` | `1e-9` | Allowed negative reaction mass within tolerance. |
+| `sci_min_contact_gap` | `0.0` | Minimum knot gap; zero still requires strict ordering. |
+| `sci_root_max_iterations` | `100` | Newton iterations per matching solve. |
+| `sci_reaction_recovery` | `True` | Enable condensed recovery when matching fails. |
+| `timeout` | `300.0` | Cooperative solve deadline in seconds. |
+| `use_analytical_jacobian` | `True` | Use the analytical matching Jacobian. |
+| `sci_fleet_mode` | `"components"` | `"full"`, `"active"`, or `"components"`; see below. |
+| `sci_profile_newton` | `False` | Record detailed Newton-stage times and LSMR iteration counts. |
+
+Statuses are `success`, `unresolved`, `root_failure`, and `invalid_solution`.
+`metrics["convergence_reason"]` supplies details. Unsuccessful iterates remain
+available for diagnosis. The deadline is checked between numerical operations;
+it does not interrupt an in-progress linear solve.
+
+For direct control, use `Config`, `ProblemConfig`, and `ContactSolver`, followed by
+`set_initial_states`, `set_final_states`, and `generate_trajectories`. This retains
+the reference interface. Its `ProblemConfig.timestep` is a legacy configuration
+field used by automatic horizon selection when the horizon is omitted; it does
+not discretize contact matching or collision checking. The convenience `solve`
+function requires an explicit horizon.
+
+## Contact components
+
+`components` is the default for `solve`, `ContactSolver`, and the CLI, including
+saved configurations that omit `sci_fleet_mode`. `full` uses all robots in every
+contact block. `active` eliminates robots with no
+current contacts and solves one system for the remaining robots. `components`
+also partitions the contact graph and solves one system per connected group.
+The graph is rebuilt with union-find after every insertion or removal; there is
+no persistent graph cache. Groups whose robot and contact identities have not
+changed retain their solution, trajectory, and validation checks. Changed groups,
+including merges and splits, are rebuilt. Every group uses the same Newton and
+recovery routines and its own endpoint barycenter. Uninvolved robots follow their unconstrained
+endpoint cubics. Collision search still covers all pairs and can activate robots
+or join components on later iterations.
+
+Component trajectories are joined by translating cubic coefficients onto the
+union of their knots. Independent components can have simultaneous contacts.
+Minimum knot gaps and ordering constraints apply within each component. If a
+new edge joins components whose existing contact times coincide or violate the
+configured gap, the solver returns `unresolved` with reason
+`merged_component_knot_gap`; it does not move already solved contact times to
+make the merge fit the current Hermite representation.
+
+`Solution`, sampling, contact indices, and CLI exports retain their fleet-wide
+shape. For low-level diagnostics in the reduced modes, `ContactSolver.system`
+is a tuple of local matching systems, `solution` concatenates their local vectors,
+and `matching_components` associates each local system/vector/trajectory with
+its original robot IDs. `metrics["system_size"]` is the sum of local system sizes;
+`partition_history` records robot groups, contact counts, sizes, and `rebuilt` and
+`reused` groups after each contact-set change. `component_builds` and
+`component_reuses` total these events. Each root record reports a solve actually
+performed; reused components do not add root records.
+
+`metrics["timing"]` includes `stage_seconds` and `stage_calls` for partitioning,
+assembly, Newton, recovery, reconstruction, validation, and collision search.
+Stages do not overlap. Partitioning includes union-find, index grouping, and
+sorting; assembly includes local systems and initial vectors; recovery includes its own
+assembly/reconstruction/checks. `other` accounts for remaining solve overhead.
+Final output sampling and export of fleet-indexed contact vectors are separately
+reported as `postprocess_time`; `contact_export_seconds` is the export portion in
+reduced modes. `wall_time` includes postprocessing.
+Use these stages for comparisons: the legacy `matching_seconds` in full mode
+also contains active-set bookkeeping, while reduced modes report Newton plus
+recovery there. Timings are wall-clock seconds, not CPU-time measurements.
+
+When `sci_profile_newton=True`, Newton root records additionally contain
+`newton_timing.stage_seconds`, `newton_timing.stage_calls`, and `lsmr_iterations`.
+These nested stages separate residual/Jacobian evaluation, band assembly, band
+solve, sparse assembly/scaling, LSMR, line-search residual evaluation, and other
+Newton work. They are subdivisions of the outer `newton` stage, not additional
+solve time. Recovery retains its own outer timer. Use profiling separately from
+baseline timing comparisons because instrumentation itself adds overhead.
+
+See [the component reuse benchmark](component-reuse.md) for current measured
+costs and [the original fleet benchmark](fleet-partitions.md) for the prototype.
+
+## Saved problems
+
+```sh
+sci-solve --states endpoints.npz --config examples/config.json \
+  --output outputs/metrics.json --trajectories outputs/trajectories.npz
+```
+
+Input NPZ keys are `initial_positions`, `final_positions`, and optionally
+`initial_velocities`, `final_velocities`. JSON configuration uses `problem` and
+`solver` objects; unknown fields are rejected. `Config.to_json` and
+`Config.from_json` support roundtrips without a YAML dependency.
+
+The CLI exits zero only for a successful solve. Sampled output includes times,
+positions, velocities, accelerations, contact states, and contact pairs.

sci_solver-0.2.0/docs/component-reuse.md

@@ -0,0 +1,215 @@
+# Component reuse benchmark
+
+This report records the benchmark before the 0.2.0 release. At that time, full
+mode remained the default. Version 0.2.0 adopts the optimized component method;
+the measurements and source hashes below retain their original meaning.
+
+The three general improvements reduce component-driver overhead without any
+fleet-size threshold. The selected small interacting cases improve by 11–24%
+against the prototype, but remain 9–24% slower than full-fleet solves. At N=20,
+three cases improve by 22–30%; the other two change little. The optimized
+components are 3–10 times faster than full-fleet solves on these five N=20 cases.
+Union-find is a small fraction of runtime. Newton evaluation and sparse fallback
+are the useful next profiling targets.
+
+## Changes
+
+1. Components hold a matching system, vector, endpoint data, and trajectory.
+   They no longer construct nested `Config` and `ContactSolver` objects. Contact
+   initialization, recovery, and validation use shared numerical functions.
+2. Initialization reads only the selected relative coordinates. Reconstruction
+   assembles relative cubic coefficients directly. Fleet-indexed public contact
+   vectors are exported once at the end. When a single component already has the
+   full fleet layout, its trajectory is returned directly; this is a representation
+   identity that applies at every N.
+3. Unchanged robot/contact groups retain their solution, trajectory, and checks.
+   Stable contact identities distinguish retained contacts from newly inserted
+   ones, including after recovery reorders contacts. Merges, splits, insertions,
+   and removals rebuild affected groups. No component state persists across solves.
+
+Union-find is still rebuilt after every contact-set update. No dependencies,
+matching equations, numerical tolerances, or solver selection thresholds were
+added. The default remains `full`; no full experiment campaign was rerun.
+
+These measurements evaluate the three changes together, not their isolated
+contributions. Stage timings and component reuse counts explain where work was
+removed, but are not a three-way ablation.
+
+## Protocol
+
+Measured on 2026-10-17, macOS arm64, Python 3.14.7, NumPy 2.5.3, SciPy 1.18.1,
+native collision backend, and numerical-library thread limits of one. The input
+settings match the prior benchmarks: minimum distance 0.5, separation allowance
+0.001, residual tolerance 1e-7, recovery enabled, and a 30-second deadline.
+
+The selection was fixed before timing: N=2 uses the first free seed and first two
+interacting seeds; N=4 uses the first seed at each observed contact count 0–3;
+N=20 uses all five previously benchmarked regression cases. Endpoints and
+configuration are embedded in the raw report.
+
+`Before` is SCI commit `5e7a8e3c667f70c7230db2024d9525254eb409f2`, archived
+before editing and imported as a separate package. `Full` and `After` use the
+current sources, whose hashes are recorded. All run in the same process with one
+warmup per case/variant, then 21 repetitions for N=2/4 and seven for N=20. Case
+and variant order are shuffled deterministically. This gives 546 timed solves.
+
+Detailed Newton profiling is disabled in this comparison. A separate pass uses
+three profiled repetitions per N=20 case. Reported times are medians; stage
+medians need not sum exactly to the median total. Quartiles are in the CSV.
+
+## Solve times
+
+Milliseconds. `Reduction` compares optimized components against the prototype.
+Solve time excludes final output sampling and contact-vector export.
+
+| N | Seed | Final contacts | Full | Components before | Components after | Reduction |
+| ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| 2 | 0 | 0 | 0.117 | 0.129 | 0.100 | 22.9% |
+| 2 | 2 | 1 | 0.825 | 1.212 | 0.925 | 23.7% |
+| 2 | 10 | 1 | 0.837 | 1.208 | 0.915 | 24.3% |
+| 4 | 0 | 1 | 0.869 | 1.220 | 1.078 | 11.7% |
+| 4 | 1 | 0 | 0.128 | 0.136 | 0.106 | 22.4% |
+| 4 | 8 | 3 | 3.638 | 4.917 | 4.001 | 18.6% |
+| 4 | 40 | 2 | 1.951 | 2.616 | 2.336 | 10.7% |
+| 20 | 2 | 3 | 82.280 | 19.562 | 19.436 | 0.6% |
+| 20 | 9 | 13 | 1610.075 | 545.170 | 537.159 | 1.5% |
+| 20 | 15 | 8 | 101.151 | 24.667 | 17.956 | 27.2% |
+| 20 | 35 | 7 | 1101.601 | 169.983 | 118.573 | 30.2% |
+| 20 | 47 | 6 | 135.752 | 17.466 | 13.587 | 22.2% |
+
+Seed 2 has overlapping interquartile ranges (before 19.353–20.522 ms,
+after 19.160–20.046 ms); its apparent 0.6% gain should be treated as inconclusive.
+Seed 9 improves little because most time is inside Newton, not component setup.
+The small-case selection is representative of contact counts, not an estimate
+over the entire previous 100-case set.
+
+The CSV also records the complete `generate_trajectories` call, including final
+contact export and sampled output. Its before/after reduction is 8–17% on the
+small interacting cases, and 0.7%, 1.4%, 24.8%, 29.9%, and 19.2% on the five N=20
+cases respectively. Thus the improvement remains when moved export work is
+included. For N=20 the export itself takes 0.066–0.106 ms. Configuration and cost
+evaluation are outside both timers.
+
+For N=2 seed 2, component assembly falls from 0.171 to 0.076 ms and reconstruction
+from 0.221 to 0.053 ms. Newton stays at about 0.473 ms in all three variants.
+The remaining component/full gap is 0.100 ms. For N=4 seed 40, the gap is 0.386 ms
+over two contact updates, with reconstruction contributing 0.290 ms in components
+versus 0.069 ms in full mode. The overhead scales with components, knots, and
+updates; it is not a constant tax determined only by the fleet size.
+
+## N=20 outer stages
+
+Accumulated milliseconds per optimized component solve, from the unprofiled
+seven-repeat comparison. Stages are disjoint.
+
+| Stage | Seed 2 | Seed 9 | Seed 15 | Seed 35 | Seed 47 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Partition: union-find, grouping, sorting | 0.028 | 0.135 | 0.059 | 0.064 | 0.049 |
+| Component assembly | 0.604 | 3.122 | 0.878 | 0.980 | 0.903 |
+| Newton | 16.189 | 516.226 | 11.606 | 111.093 | 7.882 |
+| Reaction recovery | 0.000 | 7.170 | 0.000 | 1.185 | 0.000 |
+| Trajectory reconstruction | 0.840 | 3.204 | 1.854 | 1.886 | 1.654 |
+| Validation | 0.637 | 2.609 | 1.250 | 1.107 | 1.130 |
+| Collision search | 0.562 | 2.705 | 1.224 | 1.187 | 1.020 |
+| Other bookkeeping | 0.600 | 2.095 | 1.128 | 1.156 | 0.989 |
+| Total solve | 19.436 | 537.159 | 17.956 | 118.573 | 13.587 |
+
+There are respectively 5, 15, 8, 9, and 8 partition calls: approximately
+5.6–9.0 microseconds per call. Partitioning is 0.025–0.362% of solve time and
+includes more than union-find alone. Graph rebuilding costs
+O(m alpha(A)) plus O(A log A) deterministic ordering, for m contacts and A active
+robots. It is not constant, but is negligible on these cases.
+
+Actual component solves and reuse events explain the savings:
+
+| Seed | Newton calls before | Newton calls after | Unchanged groups reused | Function evaluations before → after |
+| ---: | ---: | ---: | ---: | ---: |
+| 2 | 5 | 5 | 0 | 143 → 143 |
+| 9 | 32 | 15 | 17 | 658 → 641 |
+| 15 | 22 | 8 | 14 | 96 → 82 |
+| 35 | 20 | 9 | 11 | 598 → 470 |
+| 47 | 17 | 9 | 8 | 78 → 70 |
+
+Recovery evaluations are included in the last column, separately timed above.
+The changes also alter floating-point warm starts by avoiding global coordinate
+round trips; all numerical comparisons and physical checks pass below. The
+seed-35 gain should not be attributed entirely to its 11 skipped initial residual
+evaluations: its total evaluation count also falls substantially.
+
+## Inside Newton
+
+Milliseconds accumulated across all Newton calls in each solve, measured in the
+separate three-repeat profiling pass. These are subdivisions of Newton, not
+additional time to add to the outer table. Recovery has its own timer.
+
+| Newton stage | Seed 2 | Seed 9 | Seed 15 | Seed 35 | Seed 47 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Residual and Jacobian evaluation | 5.723 | 44.742 | 5.557 | 14.398 | 3.791 |
+| Band matrix assembly | 0.989 | 17.833 | 0.955 | 3.013 | 0.576 |
+| Banded linear solve | 1.088 | 28.689 | 1.155 | 3.352 | 0.789 |
+| Sparse assembly and scaling | 0.000 | 12.852 | 0.000 | 3.455 | 0.000 |
+| Sparse LSMR solve | 0.000 | 332.378 | 0.000 | 55.412 | 0.000 |
+| Line-search residual evaluations | 6.827 | 71.132 | 2.647 | 28.192 | 1.732 |
+| Other Newton work | 1.593 | 7.558 | 1.237 | 4.734 | 1.057 |
+| Total Newton | 16.273 | 514.929 | 11.608 | 112.604 | 7.986 |
+| Total profiled solve | 19.377 | 535.144 | 17.900 | 120.019 | 13.723 |
+
+| Seed | Newton iterations | Residual/Jacobian calls | Line-search residual calls | LSMR calls | LSMR iterations |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 2 | 37 | 42 | 101 | 0 | 0 |
+| 9 | 106 | 121 | 482 | 14 | 15,232 |
+| 15 | 34 | 42 | 40 | 0 | 0 |
+| 35 | 82 | 91 | 369 | 10 | 2,880 |
+| 47 | 29 | 38 | 32 | 0 | 0 |
+
+Seed 9 spends 62% of its complete profiled solve in LSMR and another 22% in
+residual/Jacobian and line-search evaluation. For seed 35 those shares are 46%
+and 35%. The easier cases use no LSMR; evaluation accounts for 40–65% of their
+total solve time. Banded linear solves take only 3–6% across these cases.
+
+The next general optimization target is therefore numerical evaluation and the
+fallback path. For the hard cases, inspect why fallback needs so many iterations
+before changing the linear solver or safeguards. For the easier cases, reducing
+repeated residual/Jacobian allocations and polynomial work is more promising
+than a more elaborate graph algorithm. These are directions justified by the
+profile, not measured speedup claims. The current results do not justify an
+N-dependent policy.
+
+## Validation and reproduction
+
+All 546 timed runs and 15 profiled runs converge with valid matching checks and
+continuous separation. The largest relative cost difference from paired full
+mode is 1.19e-11; the largest position-coordinate difference over 201 times is
+6.31e-7. Separate independent polynomial checks pass for all 12 cases in
+`full`, `active`, and `components` (36 checks): endpoints, continuity, jerk
+balance, contact geometry, reaction signs, and continuous separation.
+
+Profiling on/off produces exactly equal knot times and trajectory coefficients
+on all five N=20 cases. The refactored full mode matches the preserved version
+exactly across the existing 29-case comparison: identical records and zero
+difference in all 174 arrays, including sampled derivatives and failed solves.
+The complete test suite passes 172 tests; lint and whitespace checks pass.
+
+From the SCI checkout, prepare an archive of `5e7a8e3` at `SCI_REFERENCE` with
+the same native collision extension built for the current Python interpreter.
+Then run:
+
+```sh
+PYTHONPATH=src python tools/benchmark_component_reuse.py \
+  --reference-source "$SCI_REFERENCE"
+
+PYTHONPATH="$SCI_REFERENCE/src" python tools/compare_upstream.py \
+  --worker sci_solver --output /tmp/sci-reuse-reference-full.json
+PYTHONPATH=src python tools/compare_upstream.py \
+  --worker sci_solver --output /tmp/sci-reuse-current-full.json
+PYTHONPATH=src python tools/validate_component_reuse.py \
+  --full-before /tmp/sci-reuse-reference-full.json \
+  --full-after /tmp/sci-reuse-current-full.json
+PYTHONPATH=src python -m pytest -q
+ruff check .
+```
+
+- [Raw runs and source hashes](../validation/component-reuse.json.gz)
+- [Per-case timing CSV and quartiles](../validation/component-reuse.csv)
+- [Detailed Newton profiling CSV](../validation/component-reuse-profile.csv)
+- [Validation records](../validation/component-reuse-validation.json)

sci_solver-0.2.0/docs/fleet-partitions-small.md

@@ -0,0 +1,119 @@
+# Fleet reductions at N=2 and N=4
+
+The original component prototype was slower than the full-fleet solver for
+these small cases. The subsequent [component reuse benchmark](component-reuse.md)
+measures a general optimization of that implementation. The results below are
+historical measurements; they do not prescribe fleet-size dispatch. No solver
+code, defaults, experiment campaigns, or manuscript data were changed for this
+original comparison.
+
+## Inputs and protocol
+
+All 50 saved fleet-study seeds for N=2 and all 50 for N=4 are included, without
+filtering by outcome. The exact endpoints, velocities, horizons, minimum distance,
+and separation allowance are copied into the self-contained
+[input snapshot](../validation/fleet-small-inputs.json). It records the original
+table, input, and configuration hashes. The selected settings are minimum
+distance 0.5 and separation allowance 0.001; matching uses the current defaults
+including reaction recovery and a 30-second deadline.
+
+Each case/mode receives one warmup and 21 timed repetitions. Case and mode order
+are deterministically shuffled within every repetition; execution is sequential
+in one process. The native collision backend is used, with numerical-library
+thread limits set to one. Environment: macOS arm64, Python 3.14.7, NumPy 2.5.3,
+SciPy 1.18.1. The solver implementation is unchanged from the N=20 comparison.
+
+Reported times are the median across cases of each case's median over 21 runs.
+They include planning, reconstruction within planning, and collision search,
+and exclude final output sampling. Setup and complete wall time are also logged.
+Input loading is outside the solve timer. Contact-free and interacting cases are
+reported separately because 74 of the 100 cases need no matching equations.
+
+## Results
+
+Times in milliseconds:
+
+| N | Cases | Count | Full | Active | Components |
+| --- | --- | ---: | ---: | ---: | ---: |
+| 2 | Contact-free | 41 | 0.115 | 0.121 | 0.122 |
+| 2 | Interacting | 9 | 0.818 | 1.196 | 1.189 |
+| 4 | Contact-free | 33 | 0.121 | 0.129 | 0.129 |
+| 4 | Interacting | 17 | 0.873 | 1.225 | 1.214 |
+
+On the interacting cases, the median paired slowdown for components is 45.5%
+at N=2 and 39.9% at N=4. Components are slower on every interacting case.
+Contact-free cases show a smaller median paired slowdown of 5.4% and 6.7%.
+Summing all 50 per-case median times gives:
+
+| N | Full sum (ms) | Active sum (ms) | Components sum (ms) |
+| --- | ---: | ---: | ---: |
+| 2 | 12.095 | 15.632 | 15.596 |
+| 4 | 23.054 | 30.556 | 30.765 |
+
+Thus the component implementation takes 28.9% and 33.4% more total time across
+the two respective 50-case sets. This is a ratio of summed per-case medians,
+distinct from the median paired slowdown above. All 6,300 timed solves succeeded.
+The largest relative cost difference from the paired full solve is 4.27e-15;
+the largest coordinate difference over 201 comparison times is 1.21e-7.
+
+## Why it is slower
+
+Median accumulated stages over the interacting cases, in microseconds:
+
+| N | Mode | Partition including UFDS | Assembly | Newton | Reconstruction | Validation | Collision search |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 2 | Full | 0 | 69.5 | 468.6 | 41.5 | 111.3 | 77.0 |
+| 2 | Active | 1.9 | 170.4 | 472.0 | 208.1 | 145.4 | 77.7 |
+| 2 | Components | 4.0 | 170.0 | 470.9 | 208.1 | 145.0 | 75.8 |
+| 4 | Full | 0 | 77.2 | 489.5 | 41.6 | 117.1 | 87.4 |
+| 4 | Active | 1.9 | 174.0 | 470.7 | 215.0 | 152.0 | 84.8 |
+| 4 | Components | 4.3 | 173.4 | 468.0 | 213.0 | 151.5 | 86.4 |
+
+Recovery was unused. Other bookkeeping is separately logged, and medians need
+not add to the median total. Partition timing includes union-find, grouping,
+and sorting, so it bounds union-find alone from above. It is zero on all
+contact-free runs and about four microseconds per interacting solve.
+
+With N=2 there are no variables to eliminate once the two robots interact.
+At N=4 the smaller Newton systems save little time. In both sizes, the extra
+local system assembly, trajectory reconstruction, and bookkeeping outweigh that
+saving. Graph construction contributes only about 1% of the added time in the
+typical interacting case.
+
+These measurements identify avoidable setup and reconstruction overhead in the
+prototype. They do not establish a crossover for intermediate fleet sizes.
+The subsequent implementation removes duplicate work and reuses unchanged
+components without introducing any fleet-size thresholds.
+
+## Validation and reproduction
+
+All 100 cases and three modes also passed separate physical checks outside the
+timing runs: independent polynomial separation, endpoints, continuity, jerk
+balance, contact geometry, and multiplier signs. This gives 300 independent
+case/mode checks. All 6,300 timed records were checked for convergence, residuals,
+continuous separation, paired cost/position differences, and timing accounting.
+[Validation details](../validation/fleet-partitions-small-validation.json) record
+the checker and solver source hashes.
+
+From the SCI repository:
+
+```sh
+PYTHONPATH=src python tools/benchmark_partitions.py \
+  --cases validation/fleet-small-inputs.json --repeats 21 --warmups 1 \
+  --output validation/fleet-partitions-small.json
+gzip -n validation/fleet-partitions-small.json
+```
+
+The original five-case N=20 benchmark remains the default when `--cases` is
+omitted. The new input snapshot is portable and needs no local paper run files.
+
+- [Raw runs, compressed JSON](../validation/fleet-partitions-small.json.gz): every
+  run, stage timing, root record, environment, and source/input hash.
+- [Per-case CSV](../validation/fleet-partitions-small.csv): medians and quartiles
+  for all 300 case/mode combinations.
+- [Aggregate summary](../validation/fleet-partitions-small-summary.json): the
+  grouped figures and paired slowdown calculations used above.
+
+The benchmark's recorded Git commit is its pre-change base; source hashes
+identify the benchmark script used in the working tree. Only benchmark tooling,
+inputs, results, and documentation changed in this comparison.