40f98f0af9
* Renumber the layer table for solver crates: fem at L1, solver at L2, fsi at L3 L0 model -> L1 geometry, mesh, fem, decks, render -> L2 solver (explicit, lbm later) -> L3 fsi (later) -> L4 doc -> L5 io -> L6 engine -> L7 ui-egui, mcp -> apps. UI_MIN_LAYER moves to 7, the testkit sits above it. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * modelcraft-fem: element kernels for tet4, tet10, hex8 (full, incompatible modes), hex20 (full, reduced) Shape functions, Gauss and conical-product quadrature, stiffness, consistent and HRZ-lumped mass, body forces, consistent pressure loads on faces, integration-point stresses and their least-squares extrapolation to nodes, isotropic and orthotropic elasticity. The element table is one row per kind, so wedges, shells and beams are added locally. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * modelcraft-solver: linear static and frequency analysis with an analytic verification suite Assembly from the resolved model on the node graph, boundary conditions by elimination, consistent pressure, gravity and body-force loads, nested-dissection ordering, sparse up-looking Cholesky with a factor-size cap, reactions, integration-point and nodal-averaged stresses, von Mises; shift-invert block Lanczos with full reorthogonalization for natural modes, participation and effective mass. ADR 0001 records the own-linear-algebra decision (determinism, wasm). Verified against closed forms: displacement and traction patch tests for every element, cantilever tip deflection (Timoshenko) with convergence rates, Lamé cylinder, Kirsch hole (Kt -> 3), cantilever and free-free beam frequencies with six rigid-body modes. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * Engine: solve.static, solve.frequency and solve.probe; results kept in the session Results are stored per step, restored on a failed command and cleared when the model changes. Caps (degrees of freedom, factor entries, Lanczos vectors) may only be lowered; hostile parameters are tested against a solvable session. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * docs: implicit solver architecture, roadmap M4, parity and references Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * Simplify the solver: shared face integration, block assembly, cached extrapolation - model: one face integrator (nodal::face_normal_weights) for tractions and pressures - fem: mid-side tables from ElementKind::edges, orthotropic via inverse3, symmetric accumulation without a symmetrize pass, incompatible-mode recovery without K_uu, model's coordinate check, dead table rows removed - solver: one pattern search per node pair (block, scalar and diagonal adds), extrapolation built once per element type, reactions from the prescribed rows only, matrices dropped after restriction, the free-body shift keyed on the factorization error, step selection in the solver, Error::Element naming the element - engine: the solver owns the default step and the shift check; the model comparison runs once Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * docs: results are stamped with the session revision 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]>
6.7 KiB
ADR 0001: Libraries and licences
Status: accepted (2026-10-13)
Context
ModelCraft is MIT OR Apache-2.0. Everything it links must allow that, and the meshing and solver algorithms, where the obvious open-source implementations are GPL-family, must come from papers.
Decision
Geometry: SolidCraft, as git dependencies pinned by rev (solidcraft-kernel,
solidcraft-geom, solidcraft-doc, solidcraft-io; MIT OR Apache-2.0, built on the Apache-2.0
truck crates). SolidCraft is the primary geometry source: ModelCraft opens SolidCraft designs and
meshes from SolidCraft's tessellation, and reads face-tagged meshes SolidCraft exports. Other CAD
exchange files (STEP, which SolidCraft's kernel already reads) can be added as secondary inputs
through the same crate. Only modelcraft-geometry may depend on SolidCraft.
Meshing: our own, implemented from published papers (docs/meshing/literature.md).
Robust predicates follow Shewchuk's adaptive-precision arithmetic (the paper; his reference
predicates.c is public domain). A permissive crate may be adopted instead after review; record
it here. Decided 2026-10-13: our own implementation, modelcraft_mesh::predicates, written from
Shewchuk 1997, Devillers–Teillaud 2011 and Attene 2020 (no unsafe, deterministic, wasm-safe, a
validated coordinate domain instead of Shewchuk's overflow/underflow caveat, and indirect
predicates that robust lacks). robust (georust, MIT OR Apache-2.0) and num-bigint /
num-rational / num-traits (MIT OR Apache-2.0) are dev-dependencies only: differential test
oracles, never linked into ModelCraft.
Linear algebra: our own. Decided 2026-10-13 (implicit solver task): modelcraft-solver
has its own sparse symmetric storage, nested-dissection ordering (George 1973, by coordinate
bisection), up-looking sparse Cholesky (Davis 2006, elimination trees per Liu 1990) and
shift-invert block Lanczos with full reorthogonalization (Ericsson–Ruhe 1980, Grimes–Lewis–Simon
1994) on a Householder + implicit-QR dense eigensolver (Golub–Van Loan). faer (MIT) was the
alternative and is faster on large problems, but it selects SIMD kernels by CPU feature at run
time (AVX2, AVX-512, NEON), which changes floating-point reduction order between machines and
breaks the bit-for-bit determinism rule; it is also a large dependency tree for the browser
build. Our code is sequential with a fixed operation order, unsafe-free and wasm-safe, and its
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.
Allowed: MIT, BSD-2/3, Apache-2.0, ISC, Zlib, Unicode, MPL-2.0 (as an unmodified dependency), CC0 and public domain.
Rejected — never read, copy or link:
| Project | Licence | Would have offered |
|---|---|---|
| TetGen | AGPL-3.0 | constrained Delaunay tetrahedralization |
| CGAL | GPL-3.0 / LGPL-3.0 | Delaunay, mesh generation |
| Gmsh | GPL-2.0+ | tet and hex meshing |
| Netgen | LGPL-2.1 | tet meshing |
| CalculiX | GPL-2.0 | implicit solver, Abaqus-like input |
| Code_Aster | GPL-3.0 | implicit solver |
| OpenRadioss | AGPL-3.0 | explicit solver |
| Elmer | GPL-2.0 / LGPL-2.1 | multiphysics solver |
| FreeFEM, Salome | LGPL | FE libraries, pre-processing |
| Palabos, OpenLB, waLBerla, lbmpy, VirtualFluids, TCLB | AGPL / GPL | lattice Boltzmann (implement from the papers) |
| OpenFOAM, SU2, 4C, DualSPHysics, preCICE | GPL / LGPL | CFD, FSI coupling, SPH |
| FluidX3D | non-commercial only | GPU lattice Boltzmann |
| LULESH | no licence | explicit hydrodynamics proxy |
| OpenCASCADE | LGPL-2.1 | B-rep kernel |
| Attene's CDT, Indirect_Predicates, VolumeMesher | GPL / LGPL | robust CDT, indirect predicates (implement from the papers) |
| TetWild (original), Evocube, robustPolycube, ultimaille, invertible-maps | GPL-3.0 / AGPL-3.0 | tet meshing, polycube, injective maps |
| libHexEx, libHexHex, QGP3D, MC3D, CoMISo, Graphite | GPL | integer-grid-map hex extraction, quantization |
| Shewchuk's Triangle | non-commercial only | 2D meshing |
geogram third_party/tetgen, third_party/triangle and their wrappers |
AGPL / non-commercial | (the rest of geogram is BSD-3 and readable) |
libigl copyleft/ modules |
GPL | (libigl core is MPL-2.0 and readable) |
| OpenVolumeMesh, CGoGN | believed LGPL, unverified | treat as forbidden until checked |
deal.II is now dual-licensed Apache-2.0 (with LLVM exception) or LGPL, so it is readable under its Apache-2.0 option. Readable solver references (re-implement from the papers): STLBM (MIT), XLB, lettuce, pylbm, Laghos, MFEM, IBAMR, the Kratos core, MUI, FEBio, SPHinXsys, SPlisHSPlasH, fenris; full table in docs/solvers/literature.md.
Repositories without a licence are all rights reserved: never read them (for example Gao
2019's octree hex code, LoopyCuts). Readable references for the meshing work (re-implement from
the paper, note anything adapted in ATTRIBUTION.md): Shewchuk's predicates.c (public domain),
georust/robust (Apache-2.0), geogram (BSD-3, exclusions above), fTetWild (MPL-2.0), CinoLib,
Gen-Adapt-Ref, HexaLab, robust_hex_dominant_meshing (MIT), quartet (ISC). The full table with
sources is in docs/meshing/literature.md.
Test geometry follows the same rule as test data: nothing produced with a commercial CAD or
CAE product. That excludes ABC (Onshape), MAMBO (files from commercial translators) and the HexMe
models that come from ABC, GrabCAD or Siemens NX; HexMe's Gmsh-made models are allowed (CC-BY-4.0).
Thingi10K is not used either (owner decision 2026-10-13: authoring tools unrecorded). The test
corpus is our own: parts built with SolidCraft (scripts or designs authored in SolidCraft,
committed as their recipes so the geometry is regenerated, not stored) and analytic shapes.
Recipes are SolidCraft command scripts run through solidcraft-engine (same pinned rev), a
dependency of modelcraft-geometry only behind its non-default scripts feature, which the test
tooling (modelcraft-testkit) enables; the shipped library opens designs without it.
Commercial products (Abaqus, Nastran, LS-DYNA, LS-PrePost, HyperMesh, ANSA, Femap, Patran, ANSYS) are never run, scripted or used as a source of data. Deck formats come from the vendors' public reference manuals, described in our own words with our own examples.
Consequences
- The tet and hex meshers are significant original work; the literature survey decides the order and the methods.
- SolidCraft and ModelCraft move together: bumping the pinned rev bumps the repeated
[patch.crates-io]entries in the same commit.