OneCAD-Simulation/docs/adr/0001-libraries.md

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 or scripted, and their input files, text and figures are never copied. Deck formats come from the vendors' public reference manuals, described in our own words with our own examples. Published numerical results (benchmark and verification manuals) may serve as cited reference values for our own models of the same problems (owner decision 2026-10-13; docs/verification.md).

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.