Deterministic CPU multithreading: supernodal Cholesky, parallel elements, LBM blocks (#50)

* parallel: deterministic thread pool helpers for the solvers (fixed partitions, ordered results)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* solver: supernodal left-looking Cholesky, multithreaded with a fixed operation order

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* solver: parallel element matrices, stresses, Lanczos block solves and products (sums in the sequential order)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* explicit: element updates in parallel, nodal forces added in element order (bit-identical to the sequential loop)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* lbm: collision and streaming by fixed cell blocks in parallel, wall forces in link order (bit-identical)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* engine: threads setting for the solve commands (session default from MODELCRAFT_THREADS or the cores); bit-identity test on 1, 2 and 7 threads

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* docs: rayon threads in ADR 0001, the parallel crate, supernodal Cholesky

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

---------

Co-authored-by: jyviko <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

docs/adr/0001-libraries.md

@@ -38,7 +38,28 @@ build. Our code is sequential with a fixed operation order, `unsafe`-free and wa
 factor size is known (and capped) before any value is computed. Cost if this is wrong: large
 models (beyond a few hundred thousand equations) factor slower than they could; the remedy is a
 supernodal factorization of our own, or `faer` behind the same `Factor` interface with a stated
-tolerance instead of bit-identity, as the GPU exception already does.
+tolerance instead of bit-identity, as the GPU exception already does. *Updated 2026-10-13 (CPU
+parallelism task):* the factorization is now our own supernodal left-looking Cholesky (Liu–Ng–Peyton
+1993 fundamental supernodes on a postordered elimination tree, Ng–Peyton 1993, Rothberg–Gupta
+1994), multithreaded with a fixed operation order (below). Its rounding differs from the old
+up-looking factor in the last digits; every oracle fixture stays within its band.
+
+**Threads: rayon** (MIT OR Apache-2.0), in `modelcraft-parallel` only (an L0 crate with no
+workspace dependencies; *decided 2026-10-13*). The solvers keep the bit-for-bit rule on any
+number of threads by construction: work is cut into blocks whose sizes are constants of the
+algorithm, never derived from the thread count; each floating-point value is computed by one task
+in an order fixed by the input; results come back in block order and every sum over blocks or
+elements (nodal forces, assembly, wall forces, energies) runs on one thread in the order the
+sequential algorithm used. No float atomics, no `reduce` whose tree depends on work stealing:
+rayon decides only when a block runs. `std::thread::scope` was the alternative and needs no
+dependency, but it spawns threads per parallel region; the explicit solver enters several regions
+per time increment (10⁵–10⁷ increments), so a persistent pool is needed, and writing our own would
+re-implement rayon's. rayon was already in the shipped dependency tree (THIRD-PARTY-LICENSES.txt
+unchanged). In the browser build (`wasm32`) the crate does not depend on rayon and runs the same
+blocks one after another, with the same results. The thread count is a session and `solve.*`
+parameter (`threads`, 1–256) whose default is `MODELCRAFT_THREADS` or the available cores. Cost if
+this is wrong: rayon's pool is a process-wide resource and nested pools add latency; replacing it
+touches only `modelcraft-parallel`.
 
 **Allowed:** MIT, BSD-2/3, Apache-2.0, ISC, Zlib, Unicode, MPL-2.0 (as an unmodified dependency),
 CC0 and public domain.

docs/architecture.md

@@ -19,6 +19,7 @@ crates in strictly lower layers.
 | Layer | Crate | Role | Status |
 |---|---|---|---|
 | L0 | `modelcraft-model` | Solver-neutral FE model: nodes and elements by label, their geometry tags, sets, materials, sections, couplings, BCs, loads and steps, the model check and the resolved view the writers read. Knows no file format and no geometry type. | started |
+| L0 | `modelcraft-parallel` | Deterministic data parallelism for the solvers: fixed work partitions on a rayon pool, results in block order, the thread-count setting (`MODELCRAFT_THREADS`, `threads`); sequential in the browser. No workspace dependencies. | started |
 | L1 | `modelcraft-geometry` | The only door to SolidCraft: opens `.solidcraft` designs (rebuilt from their timeline, bodies with persistent face names), B-rep bodies, measures, tessellation into a face-tagged `SurfaceMesh`; face-tagged 3MF files read into the same type without the kernel (docs/formats/tagged-mesh.md). No SolidCraft type in its API. | started |
 | L1 | `modelcraft-mesh` | Surface preparation (weld, watertightness, feature edges), robust predicates, Delaunay tetrahedralization and refinement, Voronoi-based optimization, hex meshing, quality metrics. | started |
 | L1 | `modelcraft-fem` | Element kernels shared by every structural solver: the element table (tet4, tet10, wedge6, hex8 full and incompatible modes, hex20 full and reduced), shape functions, quadrature, element stiffness, consistent and lumped mass, body and pressure loads, stresses and their extrapolation, isotropic and orthotropic elasticity, the uniform-strain (one-point) hex8 and tet4 kinematics, hourglass shape vectors and element frequency bounds of the explicit solver, objective stress rates and J2/Johnson–Cook return mapping. Pure functions, no solver loop. | started |
@@ -185,8 +186,9 @@ module docs; ADR 0001 records why the linear algebra is our own.
    symmetric positive definite (no penalty, no multipliers). Free mesh equations follow the
    node order, reference point equations come last. Without couplings T is a selection and the
    numbers are those of plain elimination, bit for bit.
-4. **Static solution.** Up-looking sparse Cholesky (the factor size is computed and capped before
-   any value), reactions T_pᵀ (K u − f) (at nodes and at prescribed reference points, forces and
+4. **Static solution.** Supernodal left-looking sparse Cholesky on the postordered elimination
+   tree (the factor size is computed and capped before any value; subtrees and dense row tiles on
+   threads with a fixed operation order, so the factor is the same on any thread count), reactions T_pᵀ (K u − f) (at nodes and at prescribed reference points, forces and
    moments), integration-point stresses extrapolated to the nodes and averaged, von Mises. Shells
    report section forces and bottom, middle and top stresses at their nodes (their top surface
    joins the nodal average), beams their end section forces; nodes report rotations and reaction

docs/solvers/literature.md

@@ -974,7 +974,10 @@ the module docs):
 - Ordering: A. George, SIAM J. Numer. Anal. 10(2):345–363, 1973; H. D. Simon, Computing Systems
   in Engineering 2:135–148, 1991.
 - Sparse Cholesky: T. A. Davis, *Direct Methods for Sparse Linear Systems*, SIAM 2006; J. W. H.
-  Liu, SIAM J. Matrix Anal. Appl. 11(1):134–172, 1990.
+  Liu, SIAM J. Matrix Anal. Appl. 11(1):134–172, 1990; supernodes: J. W. H. Liu, E. G. Ng, B. W.
+  Peyton, SIAM J. Matrix Anal. Appl. 14(1):242–252, 1993; left-looking supernodal factorization:
+  E. Ng, B. W. Peyton, SIAM J. Sci. Comput. 14(5):1034–1056, 1993; parallel block factorization:
+  E. Rothberg, A. Gupta, SIAM J. Sci. Comput. 15(6):1413–1439, 1994.
 - Eigenvalues: T. Ericsson, A. Ruhe, Math. Comp. 35(152):1251–1268, 1980; R. G. Grimes, J. G.
   Lewis, H. D. Simon, SIAM J. Matrix Anal. Appl. 15(1):228–272, 1994; B. N. Parlett, *The
   Symmetric Eigenvalue Problem*, SIAM 1998; G. H. Golub, C. F. Van Loan, *Matrix Computations*,