FrankenSim is an active Rust source workspace for deterministic geometry, certified numerics, meshing, execution, evidence, and design-ledger infrastructure for simulation and design optimization.
The tree contains 184 fs-* crate directories: 164 in the native Cargo workspace
and 20 standalone workspaces listed below. They include numerical kernels,
geometry representations, meshing, physics, solvers, adjoints, optimization,
imaging, evidence, packaging and ledger implementations, together with their
contracts and tests.
The inventory numbers in this README are derived from the root workspace
manifest, each crate's declared layer metadata, and the portable tracked-input
registry in doc-facts-inventory.json by
cargo run -p xtask -- check-docs. The inventory includes committed paths;
the check also checks their presence in the current index. Staged removals can
therefore block this check until their inventory change lands. An RCH or archive source snapshot
without .git validates the same checked path set instead of counting arbitrary
filesystem dirt. Untracked files are deliberately excluded. The layer row
inventories declarations and is not, by itself, proof that every dependency
edge is valid.
| Derived repository fact | Value |
|---|---|
Native workspace fs-* crates |
164 |
Standalone fs-* workspaces |
20 (fs-cmaes-viz-wasm, fs-crump-wasm, fs-daimler-wasm, fs-davinci-wasm, fs-demo-physics-wasm, fs-edison-wasm, fs-flyer-wasm, fs-g1-train, fs-goddard-wasm, fs-heatmap-wasm, fs-howe-wasm, fs-kamen-wasm, fs-lenia-wasm, fs-otis-wasm, fs-otto-wasm, fs-roomba-wasm, fs-salisbury-wasm, fs-tesla-wasm, fs-versatran-wasm, fs-wasm) |
Tracked fs-* crate directories |
184 |
Tracked CONTRACT.md files |
184 of 184 |
| Tracked crate integration-test files | 1188 |
fs-* layer inventory |
UTIL=15, L0=7, L1=14, L2=22, L3=42, L4=33, L5=4, L6=46, TOOL=1 |
The CLI integrates bounded thermal/airflow solves and a normalized thermal radius study with ledger, report and package outputs. It is still a source workspace: no general CAD/CAE application or crates.io release is claimed.
The problem: simulation systems often split physical units, numerical error, runtime behavior, geometry validity, evidence, and reproducibility across separate tools. That makes it too easy for an optimization run to produce an answer without a durable explanation of which assumptions, approximations, kernels, and machine conditions made the answer valid.
The solution: FrankenSim builds those concerns into the workspace architecture. Units are represented explicitly, kernels have deterministic contracts, geometry conversions carry evidence, runtime behavior is structured around cancellable work contexts, and the ledger records artifacts, operations, events, roofline measurements, and time-travelable design state.
| Area | Current implementation |
|---|---|
| Workspace | Rust 2024 nightly Cargo workspace with 164 native fs-* workspace crates plus xtask; 20 nested workspaces are listed above |
| Contracts | The committed inventory contains 184 contracts for 184 crates; contract presence does not establish implementation completeness or passing conformance |
| Runtime substrate | Capability probing, SIMD facades, aligned arenas, two-lane execution, cancellation contexts, tile pools, tuner and race scaffolding |
| Numerics | Deterministic elementary math, dense/sparse linear algebra, FFT/DCT, interval/affine/Taylor arithmetic, Chebyshev collocation, random/QMC streams, AD/adjoint infrastructure, e-process inference |
| Geometry | Region/chart abstraction, SDF, mesh and F-rep charts, representation conversion hooks, transformations, tet meshing, remeshing, quality audits |
| Thermal and airflow | fs-conduction provides a steady P1 FEM kernel, card-backed thermal contact on exact matching traces, card-backed linearized surface radiation, and deterministic gray-diffuse enclosure exchange over admitted view-factor matrices; fs-convection provides 12 validity-gated Nusselt cards, including one narrow Shah-London developing-rectangular table slice at Pr=0.72 and aspect ratio 0.5; and fs-airflow provides typed fan curves, series/parallel quadratic loss networks with explicit leakage, nominal-model interval-Newton operating-point brackets, and an evidence-preserving branch-flow handoff to convection. Only conduction is currently registered for capability maturity |
| Evidence and ledger | L2 evidence-colour and evidence-packaging capabilities; fs-vvreg now has a fail-closed validation-corpus schema with 20 Level-A thermal definitions/targets (including the forced-air heatsink NTU anchor at the retained operating point), five thermal Level-B cross-code cases, and four retained Level-C published-experiment records (Martin–Moyce plus three further digitized curves), while the FrankenSQLite-backed design ledger remains registered at L1 with known suite failures open |
| Euler-disc flagship contract and bounded campaign | fs-euler-disc-e2e freezes an exact Context of Use, nine claim kinds, a 15-role owner/schema-routing matrix, evidence minima, binding no-claims, permutation-invariant prerequisite assessment, and a literal-digest structural self-consistency checker. Its deterministic JSONL campaign now adds twelve profile-native reduced closed trajectories, 2/4/8/16/32 s censor-aware continuation, bounded interior contact-event scanning plus bracketed terminal events, five-rung timestep/ranking diagnostics, and a typed physical-calibration NO-DATA record. The ranking refinement compares matched 1 mm outer fillets and derives the ring's equal-mass density from resolved chart volume. Separately, Estimate-only finite-patch normal, partial-slip, rolling, exterior-air, thin-gap gas-film, and reduced-base adapters compose atomically for restartable smooth-contact prefixes. The campaign is still a reduced numerical model, not experimental or video validation, calibrated physics, or a spin-time prediction |
| Policy tooling | xtask checks for layer direction, Franken-only runtime dependencies, contracts, unsafe capsules, and constellation lock verification |
| Tests | 1179 Rust files under crate tests/ directories in the committed inventory, in addition to inline unit tests; this count does not imply that every test is green |
The committed, deterministic numerical/software campaign is invoked with fresh output paths:
scripts/e2e/euler_disc_campaign.sh \
--output target/euler-disc-campaign/campaign.jsonl \
--stderr-log target/euler-disc-campaign/campaign.stderr.logThe script uses strict remote RCH for the committed campaign executable and
refuses existing output paths or dirty/untracked Cargo inputs. It emits the
original bounded component rungs, then twelve profile-native reduced closed
cases, fixed-policy horizon continuation, five-rung state/ranking diagnostics,
an explicit calibration NO-DATA record, and deterministic manifests. The JSONL
and stderr log are the retained software receipts. If the remote command exits zero but RCH then
returns RCH-E309 while retrieving the separately built executable, the
wrapper recovers only exact LF-framed campaign records after checking the
ordered job, worker, executable, remote-exit, retrieval, and terminal receipt
chain. Its retained final receipt marks executable retrieval incomplete and
the local transcript non-cryptographic; every other nonzero result, and empty
stdout under an ordinary zero result, refuses. Host-local output paths and
observed values are run evidence rather than frozen documentation.
The closed campaign lane couples only its declared reduced rigid-body, unilateral-contact, one-mode-base, rolling, and gas-damping laws through one explicit-midpoint stage. The separate higher-fidelity transactional stack is not yet the campaign's impact/event-loop backend. Reduced decay exponents and channel laws remain encoded model inputs, not experimentally identified laws. Right-censored horizons remain lower bounds, the four-subinterval event scan does not exclude excursions entirely between adjacent scan nodes, and the absence of independent raw/calibration/holdout evidence remains a typed NO-DATA result. Consequently this makes no experiment- or video-backed Mould claim, no validated edge optimum or material/configuration ranking, and no physical spin-time prediction.
For numerical iteration without paying for every 32-second continuation case,
cargo run -p fs-euler-disc-e2e --bin euler_disc_campaign -- --convergence-only
emits only the five-rung matched-fillet state/ranking records and a dedicated
digest manifest. It uses the same production binary and model path as the full
campaign; it is a bounded numerical diagnostic, not a reduced substitute for
experimental validation.
Crate presence is not evidence that a user-facing capability is integrated or
validated. The authoritative snapshot is
capability-maturity.json, whose level definitions
are enforced from docs/MATURITY_LEVELS.md. As of
2026-07-23 it registers 15 product-meaningful capabilities:
| Level | Meaning | Registered capabilities | Current boundary |
|---|---|---|---|
| L1 | Experimental component | 3 | Mesh and strict faceted STEP admission is implemented under explicit format, unit, root, and repair policy; the design ledger has known suite failures; and browser flagships retain their recorded test boundary |
| L2 | Numerically verified | 11 | Evidence colour/packaging, chart conversion, topology certificates, sparse assembly, certified arithmetic, Krylov solves, adjoint verification, the point-vortex quality-diversity campaign, claim-integrity governance, and capability-maturity governance cite independent tests |
| L3 | Integrated workflow | 1 | thermal.conduction-solve holds the first receipt-backed integration claim, which asserts that the pipeline executes conduction end to end with retained receipts, not that the answer is converged or validated: the no-mock lane drives the real frankensim binary through all seven solve stages on the tracked reference project and the retained receipt (spine-e2e-summary.json) lists the conduction stage as executed at a HEAD at or after the lane's own commit. The claim covers the single-command pipeline, card-backed contact, and the declared or one-branch conjugate-airflow Robin rows; it does not cover corpus validation, CFD or transients, multi-branch air networks, or mesh convergence, and the retained QoI verdict is Indeterminate with eight NO-DATA terms |
| L4 | Experimentally validated | 0 | The V&V corpus registry contains 20 Level-A thermal definitions/targets, five thermal Level-B cross-code cases, and four retained Level-C published-experiment records (Martin–Moyce plus three further digitized curves). Eighteen of the 20 Level-A rows have test-time executing-kernel bindings; the infinite-parallel-plate view-factor row remains reference-only because the current constructor stores its limiting value rather than computing it. No binding persists a corpus receipt or machine fingerprint; the experimental row also lacks original raw data, metrology, replayable digitization lineage, resolved redistribution authority, and a defensible scalar envelope. Every row is capped Estimated, so no L4 claim exists |
| L5 | Supported product | 0 | No written support and migration policy exists |
| Capability | Registry level | Crate scope | Registry boundary |
|---|---|---|---|
campaign.quality-diversity — Certify-or-escalate quality-diversity campaign (point-vortex thruster) |
L2 | fs-thrust-e2e |
Deliberately NOT L3 despite being an e2e crate: impulse conservation is a screen, every drift is Estimated, and no interval certificate exists for the QoI. A validated drift bound needs validated integration in fs-vpm. |
evidence.colour-algebra — Evidence colours and conservative composition |
L2 | fs-evidence |
G0 algebraic laws green: composition cannot outrank its weakest operand. Not L3 -- no e2e lane exercises colour composition across a full study. |
evidence.packaging — Content-addressed evidence packages and solver-free re-checking |
L2 | fs-package, fs-checker, fs-crosswalk |
Merkle roots, deny-all verification and the Phase-0A release gate are tested. Structural integrity is NOT authenticity: authority requires a caller-supplied verifier and an independent trust channel. |
geometry.chart-conversion — Region/chart abstraction and conversion with recorded error authority |
L2 | fs-geom |
Conversion promotes to Enclosure only from an ExactDistance source; everything else stays Estimate. The sheaf seam result means agreement at retained finite interface samples -- not watertightness. |
geometry.import-formats — Quarantined mesh and strict faceted STEP admission |
L1 | fs-io, fs-cli, fs-project |
CLI import admits caller-bound STL, OBJ, and PLY through the mesh quarantine path and one caller-selected strict triangular FACETED_BREP subset through the STEP path; current executable product evidence proves STL and faceted STEP only. It does not discover AP242 assemblies or occurrence transforms, unit contexts, part names/attributes, trimmed NURBS, PMI/GD&T, or persistent topology. Units and named groups are caller/project declarations. The pending f85xj.6.11 lane is not claimed. |
geometry.topology-certificates — Self-intersection and manifoldness certificates on triangle soups |
L2 | fs-topo |
Exact predicates decide every pair including vertex-sharing ones; non-finite input refuses rather than passing. Exactly-degenerate faces are REFUSED, not analysed -- a soup containing one carries no non-intersection claim. |
governance.capability-maturity — Capability maturity registry and promotion events |
L2 | xtask |
L2 structural maturity evidence is live in xtask. L3+ now requires a cited lane plus a retained receipt that records the capability stage as executed at a HEAD no older than that lane. No capability currently meets that bar. |
governance.claim-integrity — Claim-integrity defect class, inventory, and burn-down |
L2 | xtask |
Definition, taxonomy, doc lint, inventory lane, one full sweep (40 of 47 defects closed) and the promotion gate are all live; the gate demonstrably blocks a real in-scope promotion and admits a clean one. Still L2, not L3: no e2e lane composes it with a downstream consumer. |
gradients.adjoint-verification — IFT adjoints and the gradient verification gate |
L2 | fs-adjoint |
Finite differences are the independent check. The gate now counts informative directions, so a bit-insensitive probe cannot score a pass. |
ledger.design-ledger — Design ledger: artifacts, operations, lineage, time travel |
L1 | fs-ledger |
Partially repaired: b4ece64b froze semantically bound evidence bodies (a confirmed claim-integrity defect) and 60b3041b adapted the FrankenSQLite rowid-migration probes. FOUR GC tests remain red on one upstream root cause -- FrankenSQLite runs ON DELETE CASCADE actions before deleting the parent row (bead frankensim-fsqlite-fk-cascade-ordering-f2jag). No test evidence is cited and the level stays L1 rather than inferring closure from two targeted repairs. |
numerics.certified-arithmetic — Outward-rounded intervals and exact geometric predicates |
L2 | fs-ivl |
Containment under randomized expression trees is the independent oracle. Rigor is conditional on fs-math ULP budgets, per the crate's own no-claim section. |
numerics.sparse-assembly — Deterministic sparse assembly and cross-format SpMV |
L2 | fs-sparse |
Cross-format bitwise equality is an independent check, not only a golden: COO/CSR/BSR/SELL are separate implementations agreeing exactly. |
solvers.krylov — Resumable Krylov solves with typed residual provenance |
L2 | fs-solver |
SolveReport now carries a private ResidualClaim plus fail-closed Euclidean accessors (commit 8493ab35), so a driver holding only the report can distinguish recomputed-Euclidean, recursive-estimate and M-norm quantities; bead f85xj.2.24 is closed. Still L2, not L3: no admitted end-to-end lane exercises it, and the untyped rel_residual field remains readable pending a 3-crate slice named in the CONTRACT. |
thermal.conduction-solve — Steady conduction FEM solve on solids |
L3 | fs-conduction, fs-feec, fs-solid |
L3 asserts that the pipeline executes conduction end to end with retained receipts, not that the answer is converged or validated. Under the receipt rule (bead frankensim-rc-root-q61wp.13): the cited lane drives the real frankensim binary through validate/import/solve/report/package on the tracked reference project and its retained receipt (spine-e2e-summary.json) lists the conduction stage as executed at a HEAD at or after the lane's own commit, with the seven-stage run, the export verbs, determinism repeat and resume drills green. What L3 covers: the single-command pipeline through all seven stages; the heterogeneous steady conduction solve with card-backed matching-P1 contact; the declared-Robin and the one-branch conjugate airflow path (card-bounded convection, frozen dry-air properties) when a project declares it; the retained QoI/report/package projections. What it does NOT cover: L4 corpus validation (every row is Estimated), CFD or transient thermal physics, multi-branch air networks, mesh-convergence claims, cross-ISA bit-exactness outside the declared platforms, or any authority beyond what each stage receipt records; the QoI verdict in the retained run is Indeterminate with eight explicit NO-DATA terms. |
wasm.browser-flagships — Browser-facing reduced flagship campaigns |
L1 | fs-wasm |
Builds again as of the safe-step propagation (bead f85xj.2.39): the browser payload now carries an interval-derived certified sign margin at schema v3 instead of a nominal |f|/L quotient; v3 also crosses the typed surface-localization record through the ABI (bead frankensim-o33vo). Still L1: two campaign tests (grammarforge, sensorforge) are red from an earlier code-first slice, so no test evidence is cited yet. |
These levels apply to capabilities, not crates. A crate can contain multiple capabilities, and one capability can span several crates. The broad workspace and its e2e fixtures therefore must not be read as a product-maturity claim. The registry currently uses L1 as its lowest recordable tier, including entries whose notes say a capability is not built or is temporarily build-broken. For those entries, the note is the operative boundary; the L1 label is not evidence of a green build. The live distribution can be reproduced with:
jq -r '.capabilities | group_by(.level)[] | "\(.[0].level)\t\(length)"' capability-maturity.jsonThis table maps implemented source surfaces; it does not upgrade them beyond
the capability level recorded above. Read the hosting crate's CONTRACT.md and
the registry notes before treating a surface as verified, integrated, or
validated.
| Task | Implemented path |
|---|---|
| Build source crates and run conformance tests | cargo test --workspace |
| Enforce repo architecture rules | cargo run -p xtask -- check-all |
| Assemble deterministic sparse matrices and multiply them | fs_sparse::{Coo, Csr, Bsr, Sell} |
| Run Chebyshev collocation and Orr-Sommerfeld stability probes | fs_cheb::Cheb1 and fs_cheb::orr_sommerfeld |
| Attach numerical/model/statistical evidence to values | fs_evidence::{Evidence, Certified} |
| Use physical quantities with dimensional checks | fs_qty compile-time quantities and runtime QtyAny |
| Work with SDF, mesh, and F-rep geometry charts | fs_geom, fs_rep_sdf, fs_rep_mesh, fs_rep_frep |
| Work with NURBS, voxel, point-cloud, and lattice representations | fs_rep_nurbs and fs_rep_voxel |
| Assemble exterior-calculus operators and cohomology probes | fs_feec cochains, incidence, Hodge stars, Betti checks, and Hodge decomposition |
| Run matrix-free/resumable linear solves | fs_solver CG, MINRES, GMRES, transposed solves, and p-multigrid support |
| Build CutFEM and elasticity fixtures | fs_cutfem, fs_solid, fs_material, and fs_scenario |
| Solve steady conduction and derive evidence-bearing airflow/Robin inputs | fs_conduction, the validity-gated fs_convection catalog, and fs_airflow fan/network operating points; only the nominal airflow-model root is interval-certified, while physical tolerance propagation and correlation output remain estimates without a registered maturity level |
| Verify gradients and build adjoint pipelines | fs_ad, fs_adjoint, and the gradient verification gate |
| Track spectral health signals | fs_spectral sheaf-Laplacian gap monitoring and low-confidence propagation |
| Harvest cyclic symmetry in solves | fs_symmetry cyclic residuals, DFT block-diagonalized circulant solves, and perturbation bounds |
| Run gradient-based, derivative-free, or density-based optimizers | fs_ascent, fs_dfo, fs_constraint, fs_topopt, and fs_opt |
| Keep objective uncertainty honest | fs_robust CVaR, weakest-input colors, robust optima, and colored fragility curves |
| Apply design parameterizations and detect foldover | fs_xform FFD, RBF, velocity band, density, and composition types |
| Encode image artifacts and apply deterministic film/denoising transforms | fs_img PNG/OpenEXR subset plumbing, film transforms, and bias-labeled denoising |
| Experiment with recording artifacts, operations, metrics, events, and tune rows | fs_ledger on FrankenSQLite; currently L1 with known failing tests tracked in Beads |
| Package solver evidence for independent review | fs_package, fs_checker, and fs_crosswalk |
| Check plugin conformance and restriction-map behavior | fs_conform restriction-map compatibility checks and diagnostics |
| Keep the go-to-market wedge explicit | fs_wedge vertical ranking, proposal mapping, and cycle-time kill-criterion data |
| Probe machine axes and record roofline measurements | fs_roofline plus fs_substrate |
FrankenSim currently builds from source. The workspace expects exact pinned
sibling Franken projects for path dependencies, especially
~/projects/asupersync and ~/projects/frankensqlite. On a fresh checkout,
materialize those siblings first with the standalone, zero-dependency bootstrap
at tools/bootstrap; it is deliberately outside the root workspace so Cargo
does not have to resolve the missing path dependencies before building it. The
current FrankenNumpy pin is case-collision-safe on default macOS filesystems.
See docs/BOOTSTRAP.md for offline and mirror modes, the
fail-closed verification contract, and the remaining blank-machine evidence
boundary.
git clone https://github.com/Dicklesworthstone/frankensim.git
cd frankensim
# Use the pinned nightly toolchain from rust-toolchain.toml.
rustup toolchain install nightly
rustup component add rustfmt clippy --toolchain nightly
# Materialize every sibling at the exact constellation.lock pin.
cargo run --manifest-path tools/bootstrap/Cargo.toml
# Build and test the workspace.
cargo test --workspaceRun the repository policy checks:
cargo run -p xtask -- check-allThe ios/ product is a real SwiftUI studio for iPhone, iPad, and resizable
Mac Catalyst windows. Its 43-entry catalog calls the same bounded Rust kernels
used by the browser laboratory; it does not replay bundled videos or random
decorative data. Completed non-streaming runs can be shared as full JSON
snapshots containing the native payload, dimensions, seed, budget, timing,
evidence label, and no-claim boundary; those snapshots explicitly are not
Design Ledger certificates. Build the Apple-only static slices on a Darwin host
with Xcode, then generate the project:
./ios/build-rust.sh
(cd ios && xcodegen generate)
open ios/FrankenSim.xcodeprojThe product architecture, evidence-language boundary, adaptive layouts, and
acceptance gates are documented in docs/APPLE_APP_PLAN.md.
The tracked structural source manifest
enumerates exact Git-index non-tracker source bytes, all seven sibling pins and
measured usage boundaries, the crate/layer inventory, pinned toolchain
configuration, unsafe capsules, and isolated external-tool surfaces. Its
SPDX 2.3 JSON projection carries the
same exact file set as BLAKE3-checksummed SPDX files, plus component packages
for every fs-* crate, sibling pin, and external tool boundary. Regenerate and
check both artifacts with:
cargo run -p xtask -- generate-source-manifest
cargo run -p xtask -- check-source-manifestExtracted source snapshots without .git use the retained manifest as a
bounded path/mode inventory and still re-read and re-hash every listed file.
Extra-file completeness remains a Git-index property. In a live checkout,
index-blob capture describes the exact commit candidate without absorbing
unrelated unstaged shared-tree edits.
fs-package format 9 can carry the canonical manifest identity through
Provenance::with_source_manifest_identity. Citation absence is explicit;
when present, the exact 32-byte identity is bound into the package root and
authorization context and survives the strict JSON round trip. That is
tamper-evident provenance, not proof that the manifest is authentic, complete,
release-attached, or actually produced the package.
The SPDX package verification code uses the SPDX-mandated SHA-1 construction only as a format-compatibility field; BLAKE3 remains the content digest in the canonical manifest and on every SPDX file row. Neither artifact is yet a release SBOM or self-contained distribution. The final Git commit, complete tree snapshot, build host, and retained bootstrap-provenance receipt must be attached by the still-open E13.3 release-bundle work.
Run the project validation lane through DSR, which is the preferred verification path for this repo:
DSR_BIN="$(command -v dsr || printf '%s' /Users/jemanuel/projects/doodlestein_self_releaser/dsr)"
"$DSR_BIN" repos info frankensim
"$DSR_BIN" quality --tool frankensimGitHub Actions is not the source of truth for this project. Use DSR for automation and verification.
FrankenSim ships a strict validation CLI whose solve verb runs seven durable
stages: import-verify, assign, material-resolve, an interval-certified
flow-network operating point, a heterogeneous steady conduction stage (exact
matching-P1 finite contact; convection either declared or derived from the
fan network through an fs-convection card with domain gating), a
requirement-checked QoI with an explicit eight-term uncertainty budget, and a
report stage that seals an HTML report, its JSON twin and a format-9 evidence
package in the ledger. report, package and run are projections of those
retained receipts. run also executes FrankenScript programs (*.fs,
*.fs.json): frankensim --json run examples/heatsink-fan/heatsink-fan.fs L.db admits the study through fs-ir, binds its cooling.import /
cooling.solve / cooling.run verbs to these same stage drivers, and
reproduces the .fsim command sequence's run id, report hash and package root
exactly; examples/marquee/bracket-2d.fs drives the 2-D marquee through
study.run; any other operator refuses as not executable before a ledger
opens. A project that omits cooling.conduction refuses at
conduction by name (cli-solve-conduction-undeclared); one that omits a
temperature-max requirement refuses at qoi. Every QoI today is Estimated;
its verdict stays indeterminate while any budget term is NO-DATA. A project
that declares (solver :fidelity "ladder") gets a measured discretization
term from a three-rung uniform h-ladder (Richardson/GCI, or the Eça–Hoekstra
data-range fallback when no order is observable). (solver :fidelity "adaptive") runs goal-oriented refinement (including the conjugate airflow
case) and, when it meets its tolerance, supplies the term as twice the larger
enrichment change (Richardson at an assumed order of at least one).
When the project declares an operating envelope and one temperature-maximum
requirement, the conduction stage also propagates the declared INTERVAL inputs
by re-solving at their vertices on the base mesh: inlet/reference temperature
across the envelope crossed with the fan-curve pressure tolerance (the
boundary-conditions term), the convection card's discrepancy allowance on the
derived coefficient (model form), and an outward enclosure of the published
coupled solid/air system (solver algebraic), which stays NO-DATA when no
verified solid inverse is available; measurement is negligible because no
observation data enter. The
published solve also bounds its maximum's roundoff: a componentwise
γ_k (|b| + |A||T|) row bound on the assembled solid operator, mapped through
the adjoint at the hottest region vertex. On the tracked finned heatsink this
measures all eight terms on the ladder variant: boundary conditions about
20.0 K, model form about 1.34 K, geometry about 0.018 K, discretization about
0.001 K with the ladder (about 0.0016 K adaptively), material parameters
about 0.0012 K, solver algebraic about 7e-4 K, and roundoff about 9e-6 K. The parameters term is a declared
+/-8% AA6061 conductivity tolerance, sourced from the gap between the fixture
card and the in-repo NIST 6061-T6 fit (fsim v6 :conductivity-tolerance-rel).
The geometry term is an illustrative +/-0.05 mm surface offset (fsim v7
:surface-offset-m), re-solved on the same topology with watts conserved.
The conservative total is about 21.4 K against a 51.2 K nominal margin and a
5 K required margin, so the requirement reads satisfied. That is an Estimated
decision from declared engineering intervals and an h-ladder half-width, not
a certificate or validation. The solver term is a verified coupled
enclosure, not a tolerance comparison (a frozen-reference comparison missed a
30 K coupled error). On the 43,840-tet finest rung, bounded interval LDL
elimination proves the solid inverse (9,295 rows, about 1.2M peak entries,
inside the ladder project's declared 256 MiB and its stability-work budget).
The base-mesh heatsink-fan.fsim encloses its solver term (about 1e-7 K) but
has no discretization estimate, so it stays indeterminate.
| Command | Purpose |
|---|---|
cargo run -p fs-cli --bin frankensim -- validate <project.fsim> |
Parse a canonical fs-project file, report all structural findings, and emit its canonical hash |
frankensim [--json] import <project> <source>... <ledger.db> --unit <unit> (--max-hole-edges N | --step-root ID --target-h H) |
Admit STL/OBJ/PLY (one source per geometry row, in declaration order) or a strict faceted STEP subset (one source) through the quarantine path into the ledger |
frankensim [--json] solve <project> <ledger.db> [--materials <pack>]... [--interfaces <pack>]... |
Run the seven durable stages (import-verify, assign, material-resolve, flow-network, conduction, qoi, report); solve --resume <run-id> continues a retained run |
frankensim [--json] run <project> <ledger.db> [--materials <pack>]... |
solve followed by report and package export |
frankensim [--json] compare <left-run> <right-run> [<ledger.db>] |
Diff two retained runs' receipts without re-running physics |
frankensim [--json] discover <request.json> <pack>... |
Report data coverage for a law-discovery request; the CLI registers no executable law yet, so nothing is admitted as a model |
frankensim cooling-network <request.json> (+ cooling-network-uq, cooling-component-design) |
Experimental JSON workflows: 1-D air network coupled to a hand-authored P1 tet solid with contact, radiation, transients, adjoints, sizing, QMC propagation and power allocation. Not a .fsim project, not ledger-backed; see examples/cooling-network/ |
frankensim [--json] study <study.fsim|study.json> <ledger.db> [--budget N] |
Run a declared study: the normalized scalar thermal radius study or the 2-D free-boundary elasticity study (bracket-*.fsim); retain accepted iterates, final geometry, SVG report and Estimated package. Unsupported physics, wrong units, invalid geometry and missing budgets refuse before creating a ledger |
frankensim [--json] study --resume <study-run-id> <ledger.db> [--budget N] |
Replay the retained prefix using the returned run_id (study-<receipt-hash>) and continue with its original wall/iteration budget; budget exhaustion and cancellation remain explicit partial outcomes |
frankensim [--json] report <study-run-id> <ledger.db> |
Export the retained HTML/SVG and JSON study report, preserving conflicting destination files |
frankensim [--json] package <study-run-id> <ledger.db> |
Re-check and export the retained package; structural verification does not upgrade its Estimated numerical claims |
cargo run --manifest-path tools/bootstrap/Cargo.toml |
From a fresh checkout, materialize and verify the pinned sibling constellation before the root workspace resolves |
cargo test --workspace |
Build the workspace and run crate-level unit, integration, and conformance tests |
cargo fmt --check |
Check formatting under the pinned nightly toolchain |
cargo clippy --workspace --all-targets -- -D warnings |
Run the strict local lint lane |
cargo run -p xtask -- check-layers |
Enforce the layer dependency direction |
cargo run -p xtask -- check-deps |
Enforce the Franken-only runtime dependency policy |
cargo run -p xtask -- check-contracts |
Verify fs-* crate contracts and required sections |
cargo run -p xtask -- check-unsafe |
Check unsafe code against registered capsules |
cargo run -p xtask -- check-constellation |
Verify sibling Franken repository pins |
cargo run -p xtask -- check-source-manifest |
Verify the canonical structural source/SBOM inventory and its SPDX 2.3 JSON projection |
cargo run -p xtask -- check-schemas |
Verify the frozen public schema set, its migration obligations, and accretion control |
cargo run -p xtask -- check-all |
Run the implemented xtask policy checks together |
cargo run -p xtask -- check-all --only <checks> |
Restrict the verdict and exit code to the named checks ("is my lane clean?") |
dsr quality --tool frankensim |
Run the configured repo-level DSR quality gate when DSR is available |
dsr build frankensim --target darwin/arm64 |
Run the configured native DSR build lane |
The executable study fixture is
examples/marquee/thermal-2d.fsim.
It minimizes J = integral(f*u) for scalar Poisson on the normalized unit plate
with circular cooling holes, a unit source and zero temperature on all boundaries.
Only the hole radii move, at fixed centers and material area. The CLI admits at
most 256 iterations, 32 holes and mesh level 5, with explicit wall time and at
least 128 MiB declared memory. Memory is an admission estimate; cancellation is
checked between bounded iterations.
examples/marquee/bracket-2d.fsim runs a
free-boundary 2-D plane-strain elasticity study through the same verb: a
bilinear level set on a uniform grid, CutFEM on the evolving level set,
topological-derivative hole nucleation, and an augmented-Lagrangian area
multiplier with a scheduled area projection that reaches the target by about
step 12 and holds it. Holes nucleate where the topological derivative beats
the interface exchange rate. At mesh level 5 the 32-step bracket punches 6
holes and ends at 23.38 J: 31.1% below its first feasible design, and half the
48.07 J it reached with no holes at the same 0.45 area. The bracket-* variants add a projected hard-area mode, sampled
von Mises limits, protected regions and independent load families. Each run
retains iterates, the final level set, an HTML/JSON report and a structural
package, and resumes from accepted state. The report states whether the area
target was met at termination; "completed" only means every requested update
ran. No 3-D, adaptive, error-estimated, KKT/global-optimality or guaranteed
continuum error claim is made, and the elasticity path has no independent
body-fitted oracle yet.
FrankenSim promises a small set of serialized schemas. Everything else is
internal and breakable. The list is the promise: there is no implicit public
schema, no matter how stable a format looks or how many readers it has
acquired. The authoritative registry is
schema-policy.json; the doctrine, including the
per-schema compatibility and deprecation rules, is
docs/SCHEMA_POLICY.md.
| Frozen schema | Owner | Version | If an older document appears |
|---|---|---|---|
.fsim project schema |
fs-project |
10 | migrates, with a receipt |
.fsim study schema |
fs-project |
1 | no predecessor yet |
| Evidence-package format | fs-package |
9 | refused by name |
| Checker protocol | fs-checker |
7 | refused by name |
| Euler scientific Context and composite contract | fs-euler-disc-e2e |
1 | no predecessor yet; every other version refuses |
| Euler artifact owner and schema-routing matrix | fs-euler-disc-e2e |
1 | no predecessor yet; every other version refuses |
| Euler claim and minimum-evidence policy | fs-euler-disc-e2e |
1 | no predecessor yet; unknown versions refuse |
| Euler structural checker and local evidence-reference assessment protocol | fs-euler-disc-e2e |
1 | no predecessor; the receipt decoder and complete canonical assessment-log reader refuse mismatches, while other bytes are identity preimages |
| Scenario IR | fs-scenario |
2 | migrates, with a receipt |
| Assembly Description sidecar | fs-scenario |
1 | no predecessor yet; other versions refuse |
| FSMATPK material pack family | fs-matdb |
1 | no predecessor yet |
| Design-ledger schema | fs-ledger |
20 | migrates in place, history intact |
| Source manifest + SPDX projection | xtask |
frankensim-source-manifest-v1 |
no predecessor yet |
| Capability-maturity registry | xtask |
frankensim-capability-maturity-v1 |
no predecessor yet |
Five frozen schemas carry explicit lockstep obligations:
| Frozen schema | Lockstep constants and recorded values |
|---|---|
| Evidence-package format | CHECKER_SUPPORTED_PACKAGE_FORMAT=9, CHECKER_DECISION_IDENTITY_VERSION=9, SUPPORTED_PACKAGE_FORMAT=9 |
| Euler scientific Context and composite contract | VV_SCHEMA_VERSION=3, VV_ARTIFACT_FAMILY="org.frankensim.fs-evidence.vv-artifact.v3", AUTHORITY_ALGEBRA_VERSION=2, EXPERIMENT_CAMPAIGN_SCHEMA_VERSION_V1=1 |
| Scenario IR | LEGACY_SCENARIO_IR_VERSION=1 |
| FSMATPK material pack family | SPECIES_PACK_SCHEMA_VERSION=1, INTERFACE_PACK_SCHEMA_VERSION=1, MODEL_PACK_SCHEMA_VERSION=1, MATERIAL_CARD_PACK_SCHEMA_VERSION=1 |
| Source manifest + SPDX projection | SPDX_VERSION="SPDX-2.3" |
The four Euler schema entries freeze structural compatibility boundaries. The separate bounded campaign runner supplies deterministic numerical/software rungs only; neither surface validates Euler-disc physics, experiments, or the effects reported in the motivating video.
cargo run -p xtask -- check-schemas reads each version constant out of its
declared source file, so a promise cannot describe a format that no longer
exists. It also enforces the migration obligation each record declares, and
scans the product-boundary crates for public version constants that are neither
promised nor explicitly disclaimed, so a new serialized format cannot drift into
accidental-public status.
Two boundaries are worth stating plainly. Refusal is an obligation, not an
absence of one: the evidence-package format and checker protocol deliberately
have no migration path, because silently reinterpreting a stale package is worse
than refusing it. And a no-predecessor schema is not a claim that migration
works — it records that the schema has never been bumped, and the gate refuses
the first bump until the record declares how the predecessor is handled. The seven
such promises are euler.scientific-contract, euler.owner-matrix,
euler.claim-policy, euler.protocol, matdb.pack, sbom.source_manifest, and
maturity.registry.
Because there is no crates.io release yet, these records currently bind the
tree and the check-all gate rather than a published artifact; they become the
compatibility promise of the first tagged release.
FrankenSim is organized as layered Rust crates. The names below are crates present under crates/.
| Crate | What is implemented |
|---|---|
fs-qty |
Compile-time dimensional quantities, runtime QtyAny, SI parsing, dynamic dimension checks, and serialization support |
fs-obs |
Structured event schema, event kinds, emitters, content hashing, and shared observability types for kernels and ledgers |
fs-evidence |
Evidence<T> and Certified<T> wrappers, numerical/statistical/model evidence, model cards, discrepancy records, bracketing, composition, and conservative assessment |
| Crate | What is implemented |
|---|---|
fs-substrate |
Machine capability probes, fingerprints, topology maps, dispatch tiers, bandwidth measurement, Morton/tile identifiers, tiled field helpers, and CCD topology primitives |
fs-simd |
Scalar baseline operations plus registered NEON/x86 unsafe capsules behind safe facades and alignment contracts |
fs-alloc |
128-byte aligned allocation helpers, cache padding, scoped arenas, arena pools, site stats, hugepage policy/outcome types, and sharded pools |
fs-exec |
Cx execution context, stream keys, cancellation gates, tile kernels, tile pools, reductions, latency lane hooks, work distribution, race/tuner scaffolding, solver state, and kill registry |
| Crate | What is implemented |
|---|---|
fs-math |
Deterministic exp, expm1, ln, sin, cos, tanh, sqrt, complex numbers, error-free transforms, double-double helpers, and conformance boundaries |
fs-la |
Dense GEMM, batched small dense operations, factorizations, mixed-precision helpers, real and complex eigensolver scaffolding, randomized NLA range/trace estimators, and conformance tests |
fs-sparse |
COO, CSR, BSR, and SELL formats, deterministic assembly, transpose/symmetrize, SpMV/SpMM, Chebyshev, ILU0, PCG, and smoothed-aggregation AMG pieces |
fs-fft |
Complex FFT, real FFT, DCT-II/DCT-III, Stockham-style transform structure, and transform conformance tests |
fs-ivl |
Outward-rounded intervals, affine arithmetic, bounded fixed-order univariate Taylor models, Newton/Krawczyk root helpers, expansions, and exact predicates (orient, incircle, insphere) |
fs-cheb |
Adaptive 1D Chebyshev functions, Lobatto points, differentiation matrices, Dirichlet Laplacian eigen checks, and Orr-Sommerfeld growth-rate utilities |
fs-rand |
Philox counter-based streams keyed by logical identity, distributions, Sobol sequences, Owen/QMC-style components, and lattice helpers |
fs-ad |
Real trait, forward-mode dual numbers, gradient checks, implicit-function adjoint hooks, and checkpointed/full adjoint scaffolding |
fs-eproc |
Betting e-processes, pairwise races, Gaussian mixture confidence sequences, and e-Benjamini-Hochberg support |
| Crate | What is implemented |
|---|---|
fs-geom |
Points, vectors, AABBs, Betti-bound summaries, Chart and Region traits, conversion records, sampled SDF fixtures, and representation-router scaffolding |
fs-rep-sdf |
Dense tiled SDF grids, FrankenVDB-style sparse tree structure, adaptive octree SDF, narrow-band helpers, and SDF chart implementations |
fs-rep-mesh |
Half-edge surfaces, oriented tet complexes, soup repair, generalized winding-number support, point-triangle distance, mesh charts, shapes, dual contouring, mesh-to-SDF, and quality assessment |
fs-rep-frep |
CSG/F-rep builders, differentiable Boolean operations, chart implementation, finite-difference parameter derivatives, and interval/Lipschitz/gradient-style evaluation hooks |
fs-xform |
Free-form deformation lattices, RBF morphs, level-set velocity bands, SIMP-style density fields, composed parameterizations, Jacobian actions, and foldover detection |
fs-mesh |
Incremental Delaunay/tetrahedralization scaffolding, exact audits, quality refinement, ghost/refinement helpers, metric fields, remeshing, and execution-aware meshing hooks |
| Crate | What is implemented |
|---|---|
fs-ledger |
Versioned Design Ledger schema (currently v20) on FrankenSQLite, immutable persisted ledger identity, dual-index fail-closed discovery and durable session-mutation receipts, content-addressed artifacts, exact five-to-six quantity crosswalks, semantic state-checkpoint bindings, operations, event streams, lineage, metrics, tune cache, extension rows, integrity/lint checks, and time-travel queries |
fs-ir |
FrankenScript typed AST with spans, isomorphic s-expression and JSON syntaxes, shape comparison, study recognition, lowering, structured IR errors, durable Machine-IR entity/topology lineage, dependency-neutral machine-graph admission, separately identified behavior and assurance overlays, and cancellation-correct one-way admission of caller-materialized fs-scenario plus exact external-domain artifacts through a complete stable-ID crosswalk and replayable manifest |
fs-plan |
Cost model types, error and time ledgers, plan-cost oracle, and cost-model construction from tune records |
fs-roofline |
Machine-axis probing, protected historical baselines, kernel registry, measurement receipts, baseline-bound ledger recording, and staleness checks |
fs-img |
LUMEN image pipeline crate with deterministic PNG/OpenEXR subset plumbing, film/display transforms, bias-labeled denoising, and conformance tests |
fs-vskeleton |
Photovoltaic vertical skeleton tying SDF/PDE/objective/adjoint/optimization/ledger concepts into a narrow demonstrator path |
fs-opt |
ASCENT optimization problem IR crate with typed objective/constraint graphs, dimensional validation, differentiability-class routing, canonical serialization, manifold metadata, and a conformance contract |
The current positive fs-geom seam result can be emitted only by the immutable
chart-sampling builder and means agreement at its retained finite interface
samples. Caller-constructed raw complexes remain diagnostics and always yield
Unknown/NoClaim. Even builder admission does not independently prove an
arbitrary chart producer truthful. The result is not continuum coverage, manifoldness,
self-intersection freedom, or global watertightness. Likewise, the current
outside-to-outside ray routine is only a bounded input/sample validator: under
its own endpoint precondition its Boolean toggle count is necessarily even, so
it supplies no orientation, sign, topology, or independent falsification
authority. The continuum and oriented-intersection/winding successors remain
explicit planned work.
The workspace has grown beyond the first substrate and geometry layer. These crates are also implemented today and fill in the physics, optimization, audit, and orchestration layers.
| Crate family | Implemented role |
|---|---|
fs-query, fs-topo, fs-geocon |
Geometry query and certificate layer: closest-point, raycast, offset, clearance, thickness, curvature, topology validity, and geometric constraints |
fs-rep-nurbs, fs-rep-voxel |
Additional MORPH representations: rational B-spline charts with exact rational refinement/elevation while every i128 intermediate remains representable (the current exact backend fails loudly rather than wrapping on overflow), plus measured f64 closest-point brackets whose outward-rounded certification remains tracked; voxel, point-cloud, and lattice/strut representations |
fs-feec |
Exterior-calculus core: cochains, Whitney forms, exact incidence operators, Hodge stars, Betti checks, high-order tensor/simplex spaces, and cohomology/Hodge-decomposition utilities |
fs-opdsl, fs-tilelang, fs-tilelang-macros, fs-soa, fs-soa-derive |
Operator and layout tooling: DSL scaffolding for operators, deterministic tile-language lowering, and structured data layouts for stable kernel memory behavior |
fs-solver |
Resumable Krylov and multigrid stack: CG, MINRES, GMRES, matrix-free operators, transposed solves, mixed-precision refinement, and p-multigrid over the FEEC hierarchy |
fs-cutfem, fs-solid, fs-material, fs-scenario, fs-time, fs-conduction, fs-convection, fs-airflow |
FLUX physics layer: CutFEM on certified SDF cuts, elasticity/hyperelasticity, constitutive laws, typed boundary/load scenarios, time-support primitives, steady heat conduction with matching-P1 contact and surface-radiation couplings, validity-gated heat-transfer correlations, and fan/loss-network operating points that retain estimate authority through the convection handoff |
fs-iga, fs-vpm, fs-fmm, fs-lbm, fs-flux, fs-bem |
Physics scaffolds at their actual scope: fs-iga is a 1-D clamped B-spline Poisson fixture (Kirchhoff–Love shells retired from v1, deferred epic frankensim-rc-root-q61wp.40); fs-vpm is a 2-D direct O(N²) point-vortex core and fs-fmm a uniform-depth Laplace FMM (FMM-accelerated VPM retired from v1, epic .43); fs-lbm is BGK D2Q9/D3Q19 with a thermal port and no turbulence model (turbulence retired from v1, epic .41; the fs-scenario RANS rung is a 1-D channel fixture); fs-flux is 2-D H(div)-DG incompressible flow on triangle fixtures; compressible flow has no code (epic .42); fs-bem is a 2-D panel/wake method plus 3-D non-lifting FMM panels and Helmholtz radiation |
fs-adjoint |
Gradient truth layer: IFT adjoints, density/SIMP pullbacks, Sobolev smoothing, Hadamard shape gradients, revolve-style time adjoints, gradient verification, and feature-gated ledger transposition |
fs-spectral, fs-symmetry |
Spectral and symmetry health tools: sheaf-Laplacian gap tracking, hysteresis, confidence propagation, cyclic residuals, DFT block-diagonalized circulant solves, and perturbation bounds |
fs-constraint, fs-ascent, fs-dfo, fs-dimine, fs-regime, fs-topopt, fs-robust |
ASCENT layer: typed constraints with unsat cores and repairs, L-BFGS/TR-Newton/augmented-Lagrangian/Riemannian optimizers, derivative-free CMA-ES/BIPOP/Nelder-Mead, dimensional law mining, regime/validity-domain machinery, density-based topology optimization, and objective epistemics |
fs-contract, fs-verify, fs-bisect, fs-conform |
Verification layer: assume-guarantee component contracts, certified speculation verification, bisect-style proof/debug infrastructure, and restriction-map plugin conformance |
fs-package, fs-checker, fs-crosswalk |
Evidence distribution layer: content-addressed evidence packages, a solver-free standalone checker, and a standards-language crosswalk for ASME V&V and FAA/EASA certification-by-analysis concepts |
fs-project, fs-cli, fs-recompute, fs-session, fs-govern, fs-probe, fs-iface, fs-ladder, fs-spececo, fs-wedge, fs-io |
HELM and utility layer: a versioned project schema, strict validation CLI with fail-closed product-stage seams, incremental recomputation, sessions/resource governance, machine-readable proposal governance, probes, interfaces, degradation ladders, specialization ecology, wedge-selection data, and I/O boundaries |
These are library-level examples. The CLI surface is described in the
Command Reference above: the seven-stage solve/run pipeline with retained
report and package exports, the study verb, and the experimental
cooling-network* JSON workflows.
use fs_sparse::{Coo, Csr};
let mut coo = Coo::new(3, 3);
coo.push(0, 0, 2.0);
coo.push(0, 1, -1.0);
coo.push(1, 0, -1.0);
coo.push(1, 1, 2.0);
coo.push(1, 2, -1.0);
coo.push(2, 1, -1.0);
coo.push(2, 2, 2.0);
let csr: Csr = coo.assemble();
let mut y = vec![0.0; 3];
csr.spmv(&[1.0, 2.0, 3.0], &mut y);
assert_eq!(y, vec![0.0, 0.0, 4.0]);use fs_cheb::orr_sommerfeld::{critical_reynolds, max_growth};
let growth = max_growth(5772.0, 1.02, 48).expect("eigen solve");
let critical = critical_reynolds(1.02, 48, 4000.0, 8000.0).expect("bracketed solve");
assert!(growth.is_finite());
assert!(critical > 5000.0);use fs_evidence::{Evidence, ProvenanceHash};
let provenance = ProvenanceHash::of_bytes(b"example kernel output");
let value = Evidence::exact(42.0, provenance)
.certified()
.expect("the wrapper is structurally self-consistent");
assert_eq!(value.value, 42.0);This demonstrates the wrapper mechanics only. Calling a literal exact and
checking its internal consistency does not prove that a scientific computation
was exact; that authority must enter through an admitted trusted kernel or an
independently checked proof receipt bound to the actual operation and inputs.
ProvenanceHash is currently a deterministic legacy FNV fingerprint. It is
useful for deterministic correlation and accidental-corruption detection, but it is not
collision-resistant, cryptographic, or an authenticity anchor. Authority must
come through an independent trust channel carrying either the expected exact
canonical bytes or an expected collision-resistant canonical digest of those
bytes; recomputing a digest from the received payload alone proves no origin or
scientific correctness. Signing or trusting the
same 64-bit FNV value does not repair its collision weakness; typed
cryptographic identity migration remains tracked work.
use fs_checker::check_against_root;
use fs_package::{Claim, EvidencePackage, Provenance};
let claim = Claim::estimated(
"lift-preview",
"surrogate lift estimate before wind-tunnel admission",
"pod-surrogate-v3",
0.04,
);
let pkg = EvidencePackage::new(Provenance::new("commit-abc", "lock-def"))
.with_claim(claim);
let computed_root = pkg.try_merkle_root().expect("bounded example package");
let report = check_against_root(&pkg, computed_root);
assert!(report.passed());
assert_eq!(report.merkle_root(), computed_root);
assert!(report.render_pie().contains("estimated"));This deny-all example demonstrates package self-consistency for an honestly
Estimated claim. It deliberately omits the optional format-v9 source-manifest
citation and therefore claims no exact source closure. Producers with a
retained canonical manifest identity add it through
Provenance::with_source_manifest_identity; because the root above is still
computed from the package immediately before checking, this is not an
authenticity demonstration. Authoritative replay
must receive the expected collision-resistant root or signature from an
independent trust channel. Verified certificates, anchoring datasets, waivers,
signatures, and falsifier artifacts never authorize themselves: use the
corresponding typed verifier capabilities and retain the returned verification receipt.
The current Phase-0A scientific release API additionally requires a
purpose-bound approval signature over the exact checker protocol, expected
root, scientific policy fingerprints, waiver clock, and per-claim admission
context, at least one admitted scientific Verified or Validated claim, and an
authenticated, content-addressed declared falsifier artifact for every
certificate-class claim. It does not infer signer identity, role, or authorship
from detached signature bytes. This is exact package/artifact authentication,
not yet the complete Proposal-6 authority: Phase 0B adds risk-matched
threat-graph portfolios, nonzero coverage floors, optional-stopping and
multiplicity semantics, adjudicated outcomes, residual common-mode-risk
accounting, and transitive revocation.
xtask is part of the workspace and emits JSON-lines verdicts so agents and DSR can parse results without scraping prose.
cargo run -p xtask -- check-layers
cargo run -p xtask -- check-deps
cargo run -p xtask -- check-contracts
cargo run -p xtask -- check-unsafe
cargo run -p xtask -- check-all
cargo run -p xtask -- check-constellation
cargo run -p xtask -- check-source-manifest
cargo run -p xtask -- check-schemasThe implemented crates follow a layered architecture. Lower layers do not depend on higher layers; xtask check-layers enforces that direction.
fs-vskeleton
|
+-------------+-------------+
| |
fs-plan fs-roofline
| |
+-------------+-------------+
|
fs-ledger
|
+---------------------+---------------------+
| |
fs-ir fs-mesh
|
+----------------------+--------------------+----------------------+
| | | |
fs-geom fs-rep-sdf fs-rep-mesh fs-rep-frep
| | | |
+----------------------+---------+----------+----------------------+
|
fs-xform
|
+----------------------+---------+----------+----------------------+
| | | |
fs-math fs-la fs-sparse fs-fft
| | | |
fs-ivl fs-cheb fs-rand fs-ad
| |
+----------------------+--------------------+
|
+------------------+------------------+
| | |
fs-exec fs-alloc fs-simd
| | |
+------------------+------------------+
|
fs-substrate
|
fs-qty fs-obs fs-evidence
The diagram is simplified: some crates are siblings rather than strict parents, and fs-qty, fs-obs, and fs-evidence provide cross-cutting utility contracts. The authoritative dependency rule is the layer metadata in each crate manifest plus xtask check-layers.
FrankenSim treats determinism as something each crate must state. Crate contracts identify determinism class, cancellation behavior, unsafe boundaries, and no-claim boundaries. The goal is not to pretend every floating-point path is identical on every machine; it is to say exactly what is stable, what is measured, and what evidence travels with a result.
The workspace uses explicit evidence wrappers instead of leaving proof obligations in comments. fs-evidence provides numerical, statistical, and model-form evidence; geometry conversion crates and ledger code can carry these records forward instead of discarding them at API boundaries.
fs-geom defines chart and region contracts, while SDF, mesh, and F-rep crates implement specific representation behavior. This lets conversion, meshing, and transformation code reason about representation validity instead of treating geometry as an opaque blob.
Execution contexts, cancellation gates, stream keys, tile pools, event schemas, and roofline measurement are regular workspace concepts. Long-running kernels are expected to be cancellable, observable, and attributable to ledgered artifacts and machine fingerprints.
The repo does not rely on prose alone for architecture rules. xtask enforces layer direction, dependency policy, contract presence, unsafe-capsule registration, and constellation lock consistency.
The important point is not just that the crate names exist. The workspace already contains concrete algorithms and data structures with tests and contracts around them.
| Area | Implemented mechanics |
|---|---|
| Sparse assembly | fs_sparse::Coo stages triplets, canonicalizes them with deterministic duplicate accumulation, and emits CSR. CSR, BSR, and SELL kernels accumulate rows in a fixed column order so cross-format SpMV behavior is testable. |
| Randomized NLA | fs-la::rand_nla provides seeded range finding, randomized SVD, Nyström PSD approximation, sketch-and-precondition least squares, Hutchinson trace estimation, and Hutch++ trace estimation. Its golden-hash sentinel is recorded and verified identical across both reference ISAs and both build modes. |
| Certified arithmetic | fs-ivl provides outward-rounded intervals, affine arithmetic, Taylor models, Newton/Krawczyk helpers, expansions, and exact predicates for orientation and in-sphere/incircle decisions. |
| Spectral numerics | fs-cheb implements adaptive 1D Chebyshev expansions, Lobatto grids, differentiation matrices, Dirichlet Laplacian checks, and an Orr-Sommerfeld stability battery. |
| Randomness and sampling | fs-rand uses counter-based Philox streams keyed by logical identity, with Sobol/QMC and lattice helpers so replay does not depend on thread arrival order. |
| AD and adjoints | fs-ad includes forward-mode dual numbers, a Real scalar contract, gradient checking, implicit-function hooks, and checkpointed/full-adjoint scaffolding. |
| Anytime inference | fs-eproc implements betting e-processes, pairwise races, Gaussian mixture confidence sequences, and e-BH support for conservative stopping decisions. |
| Geometry representations | fs-geom defines chart/region contracts; SDF, mesh, and F-rep crates implement concrete chart families, conversion records, quality checks, and representation-specific query behavior. |
| Transformations | fs-xform implements FFD lattices, RBF morphs, velocity bands, density fields, composed parameterizations, Jacobian actions, and foldover detection. |
| Meshing | fs-mesh contains tetrahedralization/refinement scaffolding, exact audits, ghost/refinement helpers, metric fields, remeshing, and execution-aware hooks. |
| Imaging | fs-img contains deterministic image artifact plumbing for the LUMEN layer: PNG/OpenEXR subset handling, film/display transforms, and explicitly bias-labeled denoising. |
| Execution | fs-exec provides cancellation contexts, stream keys, tile kernels, tile pools, deterministic reductions, racing/tuning scaffolding, solver state, and kill registries over asupersync. |
| Ledger | fs-ledger records content-addressed artifacts, operations, events, metrics, tune rows, extension rows, integrity checks, lineage, and time-travel queries on FrankenSQLite. |
| Roofline | fs-roofline probes machine axes, checks pre/post probes against a protected historical baseline, records citable runs under the machine-plus-baseline identity, and reports either kind of drift. |
FrankenSim is not trying to be another wrapper around an external solver. The useful part is that the same workspace owns the path from representation to evidence. A result can carry dimensional meaning, numerical method, solver status, derivative provenance, validity regime, machine fingerprint, and package-level audit data without crossing an untyped boundary.
| Common failure mode | FrankenSim's implemented answer |
|---|---|
| A quantity loses units once it enters a kernel | fs-qty, fs-scenario, and fs-opt keep dimensional information explicit at API boundaries |
| A geometry conversion silently changes validity | fs-geom, representation crates, fs-query, and fs-topo expose chart contracts, conversion records, and validity/topology checks |
| A solve returns a number but not a reason to trust it | fs-solver, fs-adjoint, fs-verify, and fs-evidence return residuals, certificates, brackets, validation domains, and evidence colors |
| An optimizer stalls and nobody knows why | fs-ascent, fs-dfo, and fs-constraint report stop reasons, KKT residuals, unsat cores, repair suggestions, and restart schedules |
| A benchmark only works on one machine | fs-substrate, fs-roofline, fs-ledger, and DSR make machine axes, kernels, measurements, and validation lanes explicit |
| An auditor wants the evidence, not the solver | fs-package, fs-checker, and fs-crosswalk package claims, re-check them without the solver stack, and describe them in existing certification vocabulary |
The design target is a workflow where "what did we compute?" and "why should anyone believe it?" are not separate artifacts.
The crates are deliberately small, but the intended flow is continuous. A design study can move from typed intent to geometry, physics, derivatives, optimization, and audit without dropping provenance.
typed intent / study IR
|
v
fs-ir, fs-opt, fs-scenario
|
v
geometry and representation layer
fs-geom -> fs-rep-sdf / fs-rep-mesh / fs-rep-nurbs / fs-rep-voxel / fs-rep-frep
|
v
validity, queries, topology, and meshing
fs-query -> fs-topo -> fs-mesh -> fs-feec / fs-cutfem / fs-solid
|
v
operators and solves
fs-opdsl / fs-tilelang -> fs-sparse / fs-la -> fs-solver
|
v
derivatives and optimization
fs-ad / fs-adjoint -> fs-ascent / fs-dfo / fs-constraint
|
v
evidence, replay, and audit
fs-evidence -> fs-ledger -> fs-package -> fs-checker -> fs-crosswalk
That flow is still library-level rather than an end-user app, but the important seams already exist in code: geometry knows its chart, physics has typed scenarios and solver reports, adjoints are checked against finite differences, optimizers return certificates, and evidence packages can be verified without running the solver.
FrankenSim uses representation-specific charts instead of flattening all geometry into one mesh too early. SDF grids, triangle/tet meshes, rational NURBS patches, voxel fields, point clouds, lattices, and F-reps each keep their own query and validity contracts. Conversion is treated as an operation with a record, not as a silent cast.
Important mechanics already implemented include bounded, overflow-checked
exact rational spline refinement through the i128 backend in
fs-rep-nurbs (with f64 paths explicitly numerical), sparse VDB-style fields
and exact Euclidean distance transforms in fs-rep-voxel, mesh repair and
winding support in fs-rep-mesh, CSG/F-rep evaluation in fs-rep-frep, and
topology/validity checks in fs-topo.
The FLUX layer is built around discrete exterior calculus and explicit weak forms. fs-feec owns cochains, incidence, Hodge stars, high-order FEEC spaces, Betti checks, and Hodge decomposition. fs-cutfem works directly on certified SDF cuts with ghost penalty, Nitsche embedded boundary conditions, and cut quadrature. fs-solid provides small-strain and finite-strain elasticity, B-bar locking relief, CutFEM/body-fitted frontends, and Newton globalization against constitutive laws from fs-material.
The principle is that numerical stabilization should either follow from the complex/operator structure or be recorded as a named method with tests. Spurious modes, checkerboarding, cut-cell conditioning, locking, and buckling-adjacent tangents are treated as design constraints rather than after-the-fact patches.
The solver stack is resumable and transposition-aware. fs-solver implements CG, MINRES, GMRES, matrix-free operators, mixed-precision refinement, and p-multigrid with deterministic reductions. fs-adjoint builds gradients by transposed solves and IFT machinery rather than differentiating through Krylov iterations. The feature-gated ledger-transposition module records a DAG and pulls cotangents backward through registered VJPs, refusing missing or declared non-differentiable seams loudly instead of returning a silent zero.
On top of that, fs-ascent provides L-BFGS with strong-Wolfe search, trust-region Newton-Krylov with Steihaug negative-curvature handling, augmented-Lagrangian constraints with KKT certificates, Riemannian L-BFGS over manifold metadata, and a stop-rule algebra that attributes why a run ended. fs-dfo adds deterministic CMA-ES, BIPOP restarts, and Nelder-Mead for cases where gradients are unavailable or untrusted.
fs-evidence gives values a claim type. fs-package groups color-typed claims
and provenance into a content-addressed Merkle bundle. fs-checker re-verifies
package completeness, content address, signature status, and budget breakdown
without depending on solvers, geometry, or license gates. Its distinct
Phase-0A release gate additionally requires injected signature and artifact
verifiers, exact subject binding for declared falsifiers, and matching anchors;
ordinary integrity checking does not authenticate a signature merely because
text is present. Phase 0B is the PLANNED promotion of that spine into
risk-matched exact-instance portfolio authority. Phase 0B-A lands the pure
evidence-contract algebra in fs-govern as descriptive candidate data with no
public minting path; authenticated receipts, current-head advancement,
adjudication, and revocation are Phase 0B-B/0B-C scope and are not implemented.
fs-crosswalk maps the same package concepts onto ASME V&V 10/20/40 and
FAA/EASA certification-by-analysis vocabulary.
That division matters: the expensive solver can produce evidence once, while a reviewer can later check the package structure and provenance without re-running the solver stack.
The README-level principles are backed by concrete implementation patterns:
| Rule | Where it shows up |
|---|---|
| Make invalid states loud | Typed Error/refusal enums in geometry, packages, constraints, solvers, and scenarios; missing VJPs and non-differentiable seams block gradients |
| Keep replay independent of arrival order | Philox stream keys, deterministic reductions, sorted assembly, fixed traversal order, and content-addressed artifacts |
| Put budgets in data | Stop rules, solver iteration reports, cut quadrature depth, roofline runs, package color breakdowns, and session resource estimates |
| Separate production code from oracle code | Franken-only runtime dependency policy plus isolated test/oracle paths checked by xtask |
| Prefer certificates to comments | CONTRACT.md files, fs-evidence, gradient verification gates, package checks, topology checks, and ledger receipts |
| Treat performance as a measured claim | fs-roofline, substrate machine fingerprints, tune rows, and DSR validation lanes |
| Avoid hidden global state | Explicit contexts, stream keys, scenarios, manifests, packages, and ledger records |
Most simulation systems split their real work across several unrelated layers: a CAD kernel owns geometry, a mesher owns discretization, a solver owns residuals, an optimizer owns design changes, a notebook owns provenance, and a separate CI system tries to prove the run still works. FrankenSim keeps those concerns in one typed Rust workspace because the hard bugs usually happen at the boundaries.
| Boundary that usually leaks | Why it matters | FrankenSim's approach |
|---|---|---|
| Geometry to mesh | A conversion can change topology, watertightness, or feature size before physics sees it | Chart and representation crates expose conversion records, validity checks, topology summaries, and no-claim boundaries |
| Mesh/operator to solver | A residual can be small for the wrong norm, wrong operator, or wrong boundary condition | Operator crates, solver reports, and contracts name the algebraic object being solved and the residual semantics |
| Solver to adjoint | A gradient can silently differentiate the wrong fixed point or ignore a transpose seam | fs-adjoint uses IFT/transposed-solve machinery and feature-gated ledger transposition that refuses missing VJPs |
| Optimizer to evidence | An optimizer can return a design without explaining feasibility, stopping reason, or uncertainty | fs-ascent, fs-dfo, fs-constraint, and fs-robust report KKT residuals, stop reasons, CVaR/DRO quantities, unsat cores, and evidence colors |
| Experiment to artifact | A report can preserve plots but lose code version, machine, budgets, or assumptions | fs-ledger, fs-report, fs-package, and fs-checker keep content hashes, provenance, budget pies, package roots, and standalone checks |
The result is not just "many crates." The result is a set of small interfaces that make the expensive parts of simulation inspectable: what representation was used, what numerical contract was in force, what was measured, what was estimated, and which claim boundary still needs proof.
FrankenSim uses certification language carefully. A value is not "certified" because a test passed somewhere; it is certified only when the code path returns an explicit claim with the right evidence color, provenance, and budget context.
| Term | Meaning in this repo | Typical source |
|---|---|---|
Verified |
A property was checked by a deterministic proof, exact computation, residual certificate, invariant, or bounded numerical argument inside the modeled assumptions | Exact predicates, solver residual certificates, KKT residuals, package integrity checks, impulse-conservation bands |
Validated |
A model or result is supported against an external or empirical reference over a stated validity domain | Model cards, benchmark fixtures, calibration data, crosswalk records |
Estimated |
The claim is useful but relies on statistical, model-form, discretization, or approximation evidence that is not upgraded to a hard bound | DWR estimates, stochastic confidence sequences, surrogate bands, model-form evidence |
The important design rule is no laundering: composing a Verified value with
an Estimated value cannot produce a stronger result. That shows up in the
evidence wrappers, the robust/fragility tooling, and the end-to-end smoke
campaigns. For example, fs-thrust-e2e screens full-fidelity point-vortex runs
by impulse conservation and reports every drift as estimated — the conservation
residual discriminates, but it bounds nothing about drift, so it earns no
interval certificate — while surrogate-served
elites remain estimated for a second, independent reason (they are
extrapolations). The campaign-level rank is the weakest elite color, not
the most flattering one.
Several crates are intentionally small capstones. They are not full products, but they prove that lower-level pieces compose into end-to-end workflows.
| Slice | What it demonstrates | Why it matters |
|---|---|---|
fs-marquee |
A feature-gated raw-SDF/CutFEM/DWR smoke runner for a topology-style layout study | Geometry, embedded-boundary physics, gradient checks, and certificate fields can live on the same path without meshing as the first operation |
fs-frame |
A seismic-minimal frame smoke tier: truss layout, sizing, fiber hysteresis, e-stopped fragility, and CVaR sizing | Structural optimization can carry layout diagnostics, nonlinear response evidence, anytime-valid probability intervals, and robust tail metrics together |
fs-thrust-e2e |
CertQD-Thrust: point-vortex thruster simulation, certify-or-escalate surrogate use, MAP-Elites illumination, evidence colors, and a content-addressed notebook | Quality-diversity search can produce an atlas with per-elite trust labels instead of a single unqualified best design |
fs-vskeleton |
A photovoltaic vertical skeleton connecting SDF/PDE/objective/adjoint/optimization/ledger ideas | A narrow domain slice is useful for testing orchestration seams before every physics model is mature |
These slices are deliberately honest about scope. They are smoke tiers and integration fixtures, not claims that every flagship has reached its full production resolution. Their value is that they exercise the architecture under real composition pressure: dependencies point downward, evidence has to survive multiple layers, and tests can catch mismatches between the story and the code.
FrankenSim combines conservative numerical machinery with explicit engineering-grade fallbacks. The algorithms are implemented where they give the workspace a contract it can enforce, not just because they are impressive names.
| Family | Implemented examples | Design principle |
|---|---|---|
| Strict elementary math | fs-math deterministic exp, ln, sin, cos, tan, atan2, erf, pow, double-double helpers, and Payne-Hanek large-argument trig reduction |
Low-level math must not delegate determinism to platform libm when higher layers depend on bit-stable replay |
| Exact and bounded predicates | fs-ivl intervals, affine/Taylor arithmetic, expansions, orient, incircle, and insphere |
Geometry and topology decisions should be made with explicit uncertainty instead of hoping floating-point signs are stable |
| Spectral numerics | fs-cheb adaptive Chebyshev functions, collocation, differentiation matrices, and Orr-Sommerfeld probes |
Smooth 1D and stability problems get compact, high-order representations with conformance batteries |
| Sparse and structured linear algebra | CSR/BSR/SELL sparse formats, deterministic assembly, randomized NLA, eigensolver scaffolding, Krylov solvers, and p-multigrid | Large solves need reproducible assembly order, inspectable residuals, and operator structure that adjoints can reuse |
| Optimization | L-BFGS, trust-region Newton-Krylov, augmented Lagrangian, Riemannian L-BFGS, CMA-ES, BIPOP, Nelder-Mead, NSGA-II, Pareto tracing, CVaR, and discrete-support Wasserstein DRO | Different design regimes need different optimizers, but all of them should report why they stopped and what assumptions their answer uses |
| Anytime and robust inference | Betting e-processes, pairwise races, e-BH, Gaussian mixture confidence sequences, conformal bands, CVaR, and DRO inner suprema | A study should stop when the decision is good enough, not when a preselected sample count happens to be exhausted |
| Evidence packaging | Claim colors, validity domains, Merkle roots, package checks, crosswalk mappings, and budget pies | Solver output should be reviewable as a standalone artifact after the expensive run is over |
Two recent examples show the pattern. fs-math::payne extends trig reduction
beyond the old Cody-Waite domain with self-verifying 2/pi constants generated
from an all-integer Machin bignum in tests. fs-dfo::dro implements the exact
dual for a discrete-support Wasserstein ambiguity set and tests it against
closed-form endpoints, kink cases, and tiny LP oracles. In both cases, the code
does not merely add an algorithm; it adds the tests and contract language that
make the algorithm usable elsewhere in the workspace.
FrankenSim is easier to understand if you look for the same few shapes reappearing in different layers. The crate names are numerous, but the design is not arbitrary: values, fields, operators, budgets, and evidence all have standard carriers.
| Abstraction | Where it appears | What it buys |
|---|---|---|
Qty and dimensional records |
fs-qty, fs-scenario, fs-opt, material and constraint crates |
A boundary condition, objective, or material parameter can reject the wrong unit before it contaminates a solve |
Cx, cancellation gates, and stream keys |
fs-exec, solver drivers, stochastic crates, e2e campaigns |
Work can be interrupted, replayed, and attributed without depending on thread arrival order |
| Chart and region traits | fs-geom, fs-rep-*, fs-query, fs-topo |
Geometry keeps representation-specific meaning instead of becoming an untyped point cloud too early |
| Linear operators and transpose actions | fs-solver, fs-adjoint, fs-bem, fs-opdsl |
Primal solves, adjoint solves, and gradient checks can share the same operator contract |
| Evidence colors | fs-evidence, fs-package, campaign crates, robust/validation crates |
A result says whether it is verified, validated, or estimated, and composition cannot upgrade the weakest ingredient |
| Contract files | Every fs-* crate |
Each crate states public semantics, invariants, determinism, feature flags, tests, and no-claim boundaries in one place |
| Content roots and package checks | fs-ledger, fs-report, fs-package, fs-checker |
A later reader can inspect what was claimed without reconstructing the whole run from a notebook |
This repetition is intentional. A new physics module, optimizer, or campaign does not need to invent its own story for cancellation, uncertainty, provenance, or validation. It plugs into the same carriers and either satisfies their contracts or refuses loudly.
The e2e crates are small, but they are the best way to see the workspace acting as one system. Each campaign composes several lower-level crates and forces a real answer to carry evidence instead of just a number.
| Campaign crate | Composition | Decision or artifact produced |
|---|---|---|
fs-thrust-e2e |
Vortex particle dynamics, conformal surrogate gating, MAP-Elites, evidence colors, report generation | A quality-diversity atlas of self-propelling vortex-thruster designs with per-elite trust labels |
fs-robustopt-e2e |
SOS proof machinery, robust objective epistemics, evidence wrappers | A design choice that is both globally certified in the nominal model and robust under perturbation |
fs-schedule-e2e |
Tropical critical paths, value-of-information, evidence colors | A campaign schedule with named bottlenecks and an act/stop recommendation |
fs-flutter-e2e |
Coupling, spectral health, SOS Lyapunov checks, evidence | A flutter boundary and stability certificate for a partitioned added-mass model |
fs-neuroshape-e2e |
Neural implicit charts, Lipschitz bounds, interval topology checks, visualization evidence | A certified neural-SDF shape with no-tunnel tracing and bounded-component evidence |
fs-grammar-e2e |
Shape-program synthesis, archive illumination, fabrication checks, evidence | A diverse family of simplified CSG programs that match a target while retaining certificates |
fs-oed-e2e |
Kalman assimilation, value-of-information, tolerance allocation, evidence | A sensor placement plan that stops when the design decision is robust |
fs-metamat-e2e |
Lattice homogenization, SOS PSD checks, evidence | A stiffness-density frontier whose points are stable and Voigt-admissible |
fs-truss-e2e |
Ground-structure truss optimization, endpoint-checked tropical load paths, evidence | A deterministic approximate truss iterate plus an advisory connected load path and conditionally unique bottleneck member |
fs-adaptbo-e2e |
Bayesian optimization, e-process stopping, confidence sequences, evidence | An anytime BO run that can stop early under optional-stopping-valid evidence |
fs-flowcert-e2e |
LBM, analytic Poiseuille checks, MAP-Elites, evidence | A CFD credibility map over Reynolds number and resolution |
fs-vessel |
Chebyshev stability objective, free-surface LBM, e-racing, robust CVaR, volume rendering | A laminar-pour vessel study with stability, mass-ledger, robust-family, and render evidence |
fs-ornith |
BEM/VPM screening, e-racing, LBM refinement, SOS stability certificates, conformal surrogate bands, NSGA-II atlas construction | A smoke-tier ornithoid aircraft study that carries lineage, certificates, model-form honesty, and replay evidence through a full design campaign |
fs-topopt cutfem-marquee |
Density fields as CutFEM SDFs, DWR-guided octree refinement, zero-remesh logs, topology/thickness witnesses | A feature-gated topology-optimization lane that keeps the background grid stable while recording exactly where the proof work still lives |
fs-flagship-e2e |
Smoke/mid/full stage wiring, metric-only golden hashes, cross-flagship audits, failure drills, forensic JSON rows, notebook replay | A replay suite with frozen smoke-stage goldens, shared-core drift checks, and ignored mid/full fidelity lanes for later perf cadence |
The common pattern is: generate candidates, evaluate them with a physics or numerical kernel, attach evidence to the result, and stop only when the decision or artifact is good enough under the declared budget. This is why the campaigns are useful even when they are smoke-tier: they stress the boundaries between representations, solvers, optimizers, reports, and evidence.
The fastest way to understand the codebase is to read a few recently landed surfaces that each compress a larger design rule into a small amount of code. They show how FrankenSim tries to turn "a solver produced a number" into "a claim survived a particular chain of assumptions."
| Surface | What was built | Why it is useful |
|---|---|---|
fs-bo::sparse |
Inducing-point sparse Gaussian processes with deterministic farthest-point inducing locations, DTC/SoR prediction, Titsias ELBO accounting, and sparse/exact conformance tests | Bayesian optimization can use large-data approximations without hiding what the approximation discarded |
fs-uq::adaptive_mlmc |
Adaptive MLMC admission checks, rate recovery, CVaR and anytime probability tests | Uncertainty estimates reject invalid budgets and tolerances before they produce misleading evidence |
fs-flutter-e2e |
A partitioned added-mass flutter campaign whose Lyapunov certificate is checked against the actual eigenvalue boundary and a separate numerical-abscissa implementation | Stability certificates are not accepted merely because two equivalent code paths agree; the README now distinguishes a true independent boundary check from an implementation cross-check |
fs-neuroshape-e2e |
A neural-SDF campaign with a closed interval boundary frame, no-tunnel Lipschitz tracing, origin-Hessian curvature evidence, and visualization checks | Neural geometry gets a typed proof that at least one negative component is enclosed, while the exact component count remains unknown instead of being inferred from sampled ring points |
fs-ornith |
A smoke-tier ornithoid aircraft campaign: parameter decoding, BEM/VPM screening, e-raced candidate elimination, LBM refinement, SOS trim certificates, conformal L/D bands, and Pareto atlas rows | A flagship-style study can carry certificates, surrogate uncertainty, model-form honesty, replay, and graceful degradation through one pipeline |
fs-topopt::marquee |
A feature-gated CutFEM-octree topology lane with density-as-SDF geometry, DWR-guided refinement, zero-remesh iteration logs, and thickness/topology witnesses | Topology optimization can be exercised without making remeshing the first operation, while the feature gate keeps the proof state explicit |
The details matter. The sparse GP surface does not just say "approximate GP"; it records the ELBO slack that measures how much covariance mass was thrown away. The flutter surface does not just say "stable"; it separates the sufficient Lyapunov condition, the actual eigenvalue criterion, and the implementation cross-check. The ornith surface does not claim high-fidelity aerodynamics; it labels panel-vs-LBM agreement as model-form evidence and keeps surrogate fallbacks inside conformal bands.
The current main snapshot is no longer just a crate atlas with isolated
building blocks. Several formerly aspirational paths now have concrete, tested
surfaces that show how the layers are meant to compose.
| Surface | What exists now | Why it matters |
|---|---|---|
fs-wasm::flagships |
Source for browser-facing run_ornithoid, run_vessel, and run_frame pipelines |
The source composes reduced flagship workflows and builds again since the safe-step propagation (f85xj.2.39), but the capability registry holds browser flagships at L1 with two campaign tests still red from an earlier code-first slice; the internal "Tier V" campaign label is not an L5 maturity claim |
fs-mesh v2/v3 |
Conforming PLC recovery, non-convex facet triangulation, exact audits, an opt-in perf ladder (--ignored) measured at 10^4/10^5/10^6 points with a further opt-in 10^7 rung (FS_MESH_PERF_FULL=1, otherwise recorded as skipped), and a measured boundary-layer decision |
Meshing claims now include recovery quality, determinism, and honest continuation notes for residual near-coplanar slivers |
fs-sparse::CsrCompact |
Compact u32 column-index CSR, sharded deterministic SpMV, tiled deterministic parallel assembly, and NUMA first-touch helpers | Sparse performance work is framed as a bandwidth and page-placement problem without sacrificing bitwise equality |
fs-rand fast paths |
Ziggurat normal fast path, bulk Philox fills, and dev-only stream statistics | Random performance can improve while the strict deterministic Box-Muller path remains the certification default |
fs-fft N-D transforms |
c2r inverse plus 2D/3D separable pencil transforms | Downstream physics and visualization crates get a broader deterministic transform surface before SIMD/roofline optimization lands |
| IO/risk/probe hardening | PLY face-list integer validation, non-finite CVaR/objective/probe rejection, and package provenance checks | Failure modes that used to look like ordinary inputs now fail closed before they contaminate evidence |
That pattern is important: a new feature is not considered mature simply because the algorithm appears in code. It becomes useful when the contract names its determinism class, tests pin representative behavior, the no-claim boundary is explicit, and any performance claim is tied to a measured lane.
The rows in this snapshot are implementation inventory. They do not supersede
the registry: one capability (thermal.conduction-solve) is registered at L3
on a retained lane receipt; none is registered at L4 or L5.
Several recent implementation slices are useful to read because they show the project's design rules becoming ordinary code rather than project vocabulary.
| Slice | What landed | Why it matters |
|---|---|---|
| Deterministic integer powers | fs-math now owns pinned integer-power semantics and xtask checks for drifting .powi usage across dependent crates |
Golden values no longer depend on libm or build-mode accidents for a common scalar operation |
| Declared run identity | fs-exec and fs-rand bind random streams to a declared run identity instead of pool history |
Stochastic replay follows the logical study, not whichever worker happened to execute first |
| Caller-owned cancellation gates | fs-race and session pressure handling now require gates supplied by the caller/session owner |
A race, pause, or memory-pressure response cannot manufacture private cancellation state that the owner cannot observe |
| Explicit v1/v2 solver snapshot boundary | fs-exec keeps historical u64/FNV snapshots behind LegacySolverStateV1 and the named LegacySnapshotV1Adapter, while independent SolverStateV2 / ResumableSolverV2 APIs require full-width identities and the fallible v2 codec |
A v2-only state has no implicit legacy codec, content-hash, driver, or round-trip obligation. Legacy compatibility calls are explicitly untrusted; caller-pinned admission is capped and cancellable, and transactional v1-to-v2 migration returns a canonical receipt binding the exact source, unchanged legacy fields, migration code/schema/context, and exact v2 target identities. Producer authentication, migration-code correctness, policy admission/PreparedResume activation, registry integration, and semantic v2 fork lineage remain explicit no-claims |
| GEMM performance evidence | fs-la added packed f32 and mixed-precision paths, transposed/strided op-form GEMM, batched perf lanes, and roofline regression hooks |
Dense-kernel speedups are tied to workload shape, denominator, and regression checks instead of prose claims |
| Risk and certificate hardening | CVaR uses fractional boundary weighting, adjoint certificates fail closed on vacuous evidence, and explain/DWR regressions stay executable | Evidence objects stop accepting plausible-but-empty proofs or biased tail estimates |
| Import-order correctness | fs-io accepts legal face-before-vertex PLY element order while still validating face payloads |
The importer distinguishes format legality from malformed data, which is the right failure boundary for quarantined IO |
Together, these slices describe the current engineering center of gravity: determinism is being pushed down into reusable primitives, cancellation is treated as an ownership contract, evidence is allowed to weaken or refuse, and performance work is expected to leave behind a measurable lane.
The implemented workspace has enough surface area that recurring algorithms and design patterns are visible across crates.
| Pattern | Where it appears | Design rule |
|---|---|---|
| Fixed logical identity | Philox stream keys, tile IDs, solver snapshot envelopes, package roots | The identity of work must come from the problem and run record, not scheduler timing |
| Deterministic accumulation | COO/CSR assembly, sharded SpMV, GEMM tests, FFT goldens, evidence composition | Parallelism may change when work runs, but not the semantic order of the claim being checked |
| Fail-closed certification | Evidence colors, adjoint/DWR certificates, CVaR admission, PLY quarantine, package checking | Missing, non-finite, vacuous, or malformed evidence should refuse or downgrade, not pass as a stronger claim |
| Measurement-backed performance | Roofline axes, tune rows, perf lanes, CUSUM/regression gates, machine fingerprints | A performance statement needs a denominator, workload, hardware context, and acceptance band |
| Representation-preserving conversion | Region/chart records, SDF/mesh/NURBS/voxel/F-rep contracts, sheaf and topology witnesses | Geometry conversion is not just data translation; it must carry validity, topology, error, and no-claim context |
| Agent-readable governance | Beads, CONTRACT.md, DSR policy, xtask gates, changelog research notes |
Automated work needs durable intent, exact acceptance criteria, and replayable evidence rather than conversational memory |
This is the useful part of FrankenSim as a source workspace today. The crates are not merely a collection of numerical routines; they are converging on a shared protocol for scientific software: state the claim, encode the assumptions, run under explicit budgets, produce evidence with a color, and retain enough lineage for another process to check the result later.
FrankenSim repeatedly moves the same kinds of records across crate boundaries. The implementation is easier to understand if you track those records rather than memorizing every crate name.
| Record | Carried by | Used for |
|---|---|---|
| Dimensions and units | fs-qty, fs-scenario, material cards, objectives, constraints |
Rejecting unit drift before geometry or physics consumes an invalid scalar |
| Geometry representation | fs-geom, fs-rep-*, fs-query, fs-topo, fs-mesh |
Preserving chart identity, conversion cost, validity, topology, and no-claim boundaries |
| Execution context | fs-exec::Cx, stream keys, cancellation gates, tile identities |
Making cancellation, deterministic reduction, RNG replay, and scheduling explicit |
| Operator semantics | fs-opdsl, fs-feec, fs-cutfem, fs-sparse, fs-solver |
Naming the algebraic object, residual norm, transpose action, and matrix-free/materialized boundary |
| Sensitivity path | fs-ad, fs-adjoint, VJP registries, gradient checks |
Preventing a design update from using a gradient whose transpose or differentiability claim is missing |
| Evidence color | fs-evidence, fs-package, campaign crates |
Distinguishing verified, validated, and estimated claims without laundering weaker evidence into stronger language |
| Provenance root | fs-ledger, fs-package, fs-checker, fs-report |
Letting a later reader inspect the commit, lock state, artifacts, package root, and budget pie |
In practice, a run should not produce just f64. It should produce a value plus
the surrounding records that explain its units, representation, operator,
budget, solver status, evidence color, and provenance. The project is useful
because those records are normal Rust types instead of comments in a notebook.
The runtime model is deliberately plain: work is split into tiles, tiles run under an explicit context, and every stochastic or parallel decision is keyed by logical identity rather than by worker timing.
study / scenario / seed
|
v
Cx + stream keys + budgets
|
v
tile programs
|
+--> deterministic assembly / operator application
+--> cancellable solver or simulator step
+--> stochastic draw keyed by logical identity
|
v
reports, evidence colors, tune rows, ledger artifacts
This is why the code spends so much effort on things that look mundane: canonical sort order, row-range sharding, fixed reduction trees, Philox stream keys, idempotency keys, and content hashes. They make it possible to run a parallel or stochastic computation and still answer: which logical tile did this work, which seed did it use, what budget did it consume, and can the same claim be replayed?
FrankenSim uses the Gauntlet tiers from the project plan as a shared vocabulary for proof strength. Not every crate is at every tier, but the README and contracts should make the intended tier visible.
| Tier | What it proves | Examples in the workspace |
|---|---|---|
| G0 | Algebraic laws and local invariants | FFT round trips, sparse format equality, package root checks, quantity/unit laws |
| G1 | Manufactured solutions or convergence order | PDE and operator fixtures where closed-form or manufactured references exist |
| G2 | Canonical benchmarks | Chebyshev/Orr-Sommerfeld probes, Poiseuille-style flow checks, topology/optimization benchmark envelopes |
| G3 | Metamorphic behavior | Translation, scaling, relabeling, refinement, cross-format, and representation round-trip checks |
| G4 | Chaos and cancellation | Cancellation storms, budget exhaustion drills, ledger crash recovery, losing-branch drain tests |
| G5 | Determinism audits | Bitwise replay, fixed golden hashes, cross-thread sparse assembly, Philox stream identity, flagship smoke-stage hashes |
The strongest tests are usually paired. A deterministic golden catches drift, but a golden alone can freeze a bug. A closed-form oracle catches meaning, but an oracle alone may not exercise parallel replay. The codebase therefore tends to pair fixtures: oracle plus determinism, dense reference plus sparse path, feature gate plus no-claim boundary, or smoke campaign plus failure drill.
Performance work in FrankenSim is framed as an evidence problem, not as a style preference. A kernel is not "fast" because it uses the right algorithmic buzzword; it is fast only when the repo records the machine, denominator, workload, and acceptance band.
| Concern | Implementation direction |
|---|---|
| Memory bandwidth | fs-roofline and fs-substrate measure machine axes and STREAM-like baselines before interpreting kernel throughput |
| Sparse SpMV | CsrCompact reduces index traffic, spmv_sharded balances contiguous row ranges by nnz, and NUMA first-touch places pages with the shard that will read them |
| Assembly | Coo::assemble_parallel tiles by row range and preserves duplicate accumulation order so thread count cannot change the numerical result |
| SIMD | Unsafe or architecture-specific code is kept behind registered capsules and safe facades; exploratory SME2 stays gated rather than becoming a default path |
| FFTs | The current N-D implementation is correctness-first and separable; higher-radix, SIMD, cache-blocked transposes, and executor-tiled pencils remain explicit follow-up work |
| Random generation | Bulk Philox and ziggurat normals are performance paths, while the strict path stays cross-ISA deterministic until the faster path earns the same proof |
| Accelerators | fs-govern now defines the quantitative GPU/accelerator go/no-go doctrine and the required per-run evidence fields; no accelerator backend or runtime dependency exists yet |
The recurring tradeoff is intentional: first make the semantics deterministic and testable, then optimize the hot path while proving it is still the same computation. When the optimized path is not yet equally proven, it stays behind a feature flag, fast-mode API, or no-claim boundary.
Accelerator work is currently policy-first. The end-to-end profiling bead must
show that the top three kernels dominate workflow wall time and, where credible
platform data exists, measured energy, and that one candidate remains suitable
after transfer and synchronization costs. Otherwise the conditional [M]
pilot closes as refused-with-evidence.
Even a passing profile still needs a separate production-dependency ruling and
a moonshot displacement; the permanent CPU reference, numerical comparison
envelope, device/toolchain identities, and request-drain-finalize receipt remain
mandatory. See docs/ACCELERATOR_DOCTRINE.md
for the code-derived evidence map and explicit no-claim boundary.
Every fs-* crate has a CONTRACT.md. These files are not decorative. They are
the quickest way to tell whether a crate's README-level description is backed by
code and what the code refuses to claim.
| Section | Question to ask |
|---|---|
| Purpose and layer | Which architectural layer owns this behavior, and which layers may depend on it? |
| Public types and semantics | What values does this crate expose, and what does each value mean? |
| Invariants | What should remain true across refactors, thread counts, seeds, or representations? |
| Error model | Which failures are recoverable results, which are programmer errors, and which are explicit refusals? |
| Determinism class | Is replay bitwise, same-ISA, cross-ISA, statistical, or intentionally fast-mode-only? |
| Cancellation behavior | Where can long-running work stop, drain, and report structured cancellation? |
| Unsafe boundary | Is there unsafe code, and if so what invariant makes it valid? |
| Feature flags | Which parts are default, frontier, moonshot, or intentionally off the critical path? |
| Conformance tests | Which tests define the reimplementation contract? |
| No-claim boundaries | What would be dishonest to infer from the current implementation? |
If you only have time to read one file inside a crate, read the contract first. Then read the tests named by the contract. The implementation usually makes much more sense after those two files explain the claim surface.
These are good first code paths for understanding how the architecture works in practice.
| If you want to understand... | Read these files first | What to look for |
|---|---|---|
| Evidence packages | crates/fs-package/src/lib.rs, crates/fs-checker/src/lib.rs, their tests |
How claims, provenance, Merkle roots, signatures, and budget pies become independently checkable |
| Deterministic sparse work | crates/fs-sparse/src/lib.rs, crates/fs-sparse/src/perf.rs, crates/fs-sparse/tests/conformance.rs |
Sorted assembly, duplicate accumulation order, compact CSR, sharded SpMV, and cross-thread equality |
| Mesh honesty | crates/fs-mesh/CONTRACT.md, crates/fs-mesh/src/recovery.rs, crates/fs-mesh/tests/conformance.rs |
Exact audits, recovery counters, non-convex facet handling, and measured boundary-layer decisions |
| Browser flagships | crates/fs-wasm/src/flagships.rs, crates/fs-wasm/src/lib.rs |
How reduced aircraft/vessel/frame campaigns compose existing crates into trap-free browser exports |
| Deterministic transforms | crates/fs-fft/src/lib.rs, crates/fs-fft/CONTRACT.md |
Fixed twiddle generation, oracle tests, c2r inverse, N-D pencil decomposition, and no performance overclaiming |
| Random replay | crates/fs-rand/src/lib.rs, crates/fs-rand/CONTRACT.md, crates/fs-rand/tests/ziggurat.rs |
Logical stream identity, random access, bulk fills, fast-mode ziggurat, and strict-mode boundaries |
These paths are intentionally small enough to read in one sitting. Together they show the project style: data structures first, contracts second, tests that define the claim, and implementation details that avoid hidden global state.
FrankenSim is useful because its algorithms are not isolated demos. A typical workflow crosses several crates, and each crossing has a contract.
geometry or design variables
|
v
representation-specific chart / SDF / mesh / field
|
v
operator assembly or matrix-free operator
|
v
solver, verifier, or simulator
|
v
adjoint / sensitivity / uncertainty wrapper
|
v
optimizer, race, or value-of-information planner
|
v
evidence color + ledger/package/report artifact
| Crossing | Implementation shape | Failure it prevents |
|---|---|---|
| Design to geometry | fs-xform, representation crates, interval enclosures, topology checks |
A parameter update silently leaves the geometry validity domain |
| Geometry to physics | CutFEM, FEEC, BEM, LBM, material/scenario records | A solver receives an untyped shape with unknown boundary meaning |
| Physics to solver | Linear-operator traits, Krylov reports, p-multigrid, block preconditioners, deterministic sparse formats | A residual or matrix format looks fine locally but cannot be replayed or checked elsewhere |
| Solver to sensitivity | AD, IFT adjoints, VJP registries, transposed solves, gradient verification | An optimizer follows a gradient that differentiated the wrong computation |
| Sensitivity to decision | L-BFGS/TR-Newton, CMA-ES, NSGA-II, races, MLMC, CVaR, DRO | A campaign optimizes a noisy proxy without recording stop reasons or uncertainty |
| Decision to artifact | Evidence colors, content roots, package checks, crosswalk records, reports | A reviewer sees only a final plot and cannot inspect the chain of assumptions |
This is why the workspace has many small crates instead of one monolith. The crate boundary is where the system can ask a useful question: did this layer preserve dimensions, topology, determinism, residual meaning, evidence color, or provenance?
FrankenSim is written with automated agents as a real workload. Agents are good at running many narrow checks, but they are also prone to losing context, over-trusting a local success, or optimizing for the easiest measurable target. The architecture tries to make the correct behavior the path of least resistance.
| Principle | What it means in practice |
|---|---|
| Make claims local | A crate should state exactly what it can prove, what it estimates, and what it refuses to claim in CONTRACT.md |
| Prefer typed refusal to heroic guessing | Invalid tolerances, missing VJPs, unsupported representation conversions, and incomplete evidence should fail loudly or weaken the evidence color |
| Keep replay independent of scheduling | Stream keys, deterministic reductions, sorted assembly, and cancellation contracts make parallel or stochastic work auditable |
| Separate model-form honesty from numerical accuracy | A low-Re LBM channel, inviscid panel method, surrogate, and SOS proof can coexist only when each says what kind of evidence it provides |
| Use smoke tiers as integration pressure | Small e2e campaigns are valuable because they force geometry, solvers, uncertainty, optimization, and reports to share one evidence language |
| Treat performance as an evidence object | Roofline numbers, tune rows, machine fingerprints, and DSR logs are the claim; architectural intent is not enough |
The result is a codebase where an agent can make progress without inventing a new project philosophy for every task. The same rules keep appearing: check the contract, run the conformance test, preserve the proof state, and do not upgrade a claim just because one path passed.
When a result looks interesting, inspect it in this order:
- Find the crate contract and read the no-claim boundaries.
- Identify the evidence color or certificate type attached to the output.
- Check whether the computation is deterministic, stochastic with a valid stopping rule, or model-form estimated.
- Look for an independent oracle: dense reference, closed-form endpoint, symmetry law, LP enumeration, interval enclosure, conservation law, or cross-ISA golden.
- Check the stop reason, residual norm, budget, and validity domain.
- Confirm that any generated report or package contains enough provenance to rerun or independently check the claim.
- If performance is part of the claim, require a roofline/tune/DSR artifact rather than accepting timing prose.
This checklist is intentionally mundane. The project is trying to make advanced simulation work feel less like a notebook archaeology exercise and more like a chain of inspectable, typed claims.
Many simulation bugs do not look like panics. They look like plausible numbers that lost their assumptions. FrankenSim tries to turn those cases into typed refusals, weaker evidence colors, or failing conformance tests.
| Failure mode | How it can happen | Mechanism in FrankenSim |
|---|---|---|
| Unit drift | A pressure, length, time step, or material constant enters as an unlabelled f64 |
fs-qty, scenario contracts, and objective/constraint records keep dimensions explicit |
| Topology drift | A representation conversion closes a hole, flips orientation, or hides a thin feature | Chart contracts, topology checks, conversion records, and no-claim rows make representation changes auditable |
| False solver confidence | A residual is small in the wrong norm or under the wrong boundary rows | Solver reports, operator contracts, conformance batteries, and explicit stall diagnoses name what was solved |
| Silent gradient loss | A non-differentiable operation returns zero cotangent or a missing transpose is ignored | VJP registries, IFT adjoints, gradient certificates, and merge gates refuse missing derivative paths |
| Stochastic overconfidence | A campaign keeps sampling after seeing lucky early results and treats the final mean as fixed-sample evidence | E-processes, confidence sequences, e-racing, and value-of-information logic keep stopping rules visible |
| Platform-dependent replay | Libm, thread order, or unordered assembly changes a golden value | Deterministic math, Philox stream keys, sorted assembly, fixed reductions, and content roots pin the replay path |
| Evidence laundering | A validated model, estimated surrogate, and verified invariant are collapsed into one flattering status | Evidence colors compose conservatively; the weakest required ingredient limits the claim |
| Performance folklore | A kernel is called fast because the algorithm sounds fast | Roofline records, machine fingerprints, tune rows, DSR lanes, and no-claim boundaries separate measured facts from ambitions |
This is the practical design principle behind the project: failures should be local, named, and inspectable. A user should be able to tell whether a result is blocked by geometry validity, algebraic convergence, model-form uncertainty, budget exhaustion, missing derivative support, or simply an unmeasured performance claim.
The audit path is designed to be mechanical:
- A crate declares what it can and cannot claim in
CONTRACT.md. - A computation returns values with residuals, stop reasons, evidence colors, validity domains, or budget records instead of a naked scalar.
- The ledger records artifacts, events, metrics, tune rows, machine fingerprints, and lineage.
- A report or package bundles the result with its provenance and budget pie.
- A checker can later validate package structure, content roots, signature status, and claim completeness without needing to rerun the full solver; authenticated release admission requires a caller-supplied verifier.
That path is useful for research code, but it is also useful for day-to-day engineering. If a golden hash changes, if a solver starts returning a weaker certificate, if a new representation loses topology, or if a stochastic estimate stops being decision-grade, the failure has a place to surface. The project tries to make those failures boring and local instead of late and forensic.
The evidence-package crates are small, but they define an important workflow:
- A solver, verifier, optimizer, or study runner creates claims with evidence colors: verified, validated, or estimated.
fs-packagebundles those claims with provenance and a deterministic content address.fs-checkerre-verifies the bundle's structural completeness, expected root, signature status, and budget pie without pulling in the solver stack. Its Phase-0A release API additionally requires caller-supplied authenticators for the purpose-bound approval and declared, exact-subject falsifier/source/ derivation artifacts, plus matching validation anchors. That gate does not yet claim Phase-0B risk-matched portfolio coverage, optional-stopping and multiplicity control, or adjudicated transitive revocation.fs-crosswalkgives the package a standards-facing vocabulary so the same artifact can be discussed as validation metrics, domain of validation, provenance, certified bounds, and content integrity.fs-ledgercan retain artifacts, operations, events, tune rows, roofline measurements, and lineage so a later report can connect package claims back to the actual run history.
This is why the package/checker/crosswalk layer is useful even before FrankenSim has a polished application: it turns internal numerical claims into an inspectable artifact boundary.
Different readers should start in different places.
| Goal | Start here |
|---|---|
| Understand the architecture | COMPREHENSIVE_PLAN_FOR_FRANKENSIM.md, then this README's architecture and crate-map sections |
| Check repository policy | AGENTS.md, docs/CI_GATES.md, xtask, and constellation.lock |
| Study numerical kernels | crates/fs-math, crates/fs-la, crates/fs-sparse, crates/fs-fft, crates/fs-ivl, crates/fs-cheb |
| Study geometry | crates/fs-geom, crates/fs-rep-*, crates/fs-query, crates/fs-topo, crates/fs-mesh |
| Study physics and solvers | crates/fs-feec, crates/fs-cutfem, crates/fs-solid, crates/fs-material, crates/fs-conduction, crates/fs-convection, crates/fs-airflow, crates/fs-solver |
| Study gradients and optimization | crates/fs-ad, crates/fs-adjoint, crates/fs-ascent, crates/fs-dfo, crates/fs-constraint |
| Study audit and packaging | crates/fs-evidence, crates/fs-ledger, crates/fs-package, crates/fs-checker, crates/fs-crosswalk |
| Study the Euler-disc scientific boundary | crates/fs-euler-disc-e2e/CONTRACT.md, then its contract and protocol modules |
The committed inventory contains 184 CONTRACT.md files for 184 fs-* crate
directories, including the scene query contract.
The contract count is meant to be checkable, not aspirational.
Existing contracts use these required sections:
- purpose and layer
- public types and semantics
- invariants
- error model
- determinism class
- cancellation behavior
- unsafe boundary
- feature flags
- conformance tests
- no-claim boundaries
Use these commands for local checks:
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p xtask -- check-allUse DSR for the project validation path:
DSR_BIN="$(command -v dsr || printf '%s' /Users/jemanuel/projects/doodlestein_self_releaser/dsr)"
"$DSR_BIN" repos info frankensim
"$DSR_BIN" quality --tool frankensimThe current DSR setup is preferred over GitHub Actions for this repository. If a future GitHub workflow appears, do not treat it as authoritative unless AGENTS.md and DSR policy are changed first.
.
|-- Cargo.toml # Workspace manifest
|-- Cargo.lock # Committed lockfile
|-- rust-toolchain.toml # Nightly toolchain and components
|-- crates/ # 184 fs-* crates; selected entries shown below
| |-- fs-qty/ # Dimensional quantities
| |-- fs-obs/ # Structured observability
| |-- fs-evidence/ # Evidence and certification wrappers
| |-- fs-substrate/ # Hardware/substrate probes
| |-- fs-simd/ # SIMD facades and capsules
| |-- fs-alloc/ # Aligned arenas and pools
| |-- fs-exec/ # Execution context, cancellation, tile work
| |-- fs-math/ # Deterministic scalar math
| |-- fs-la/ # Dense linear algebra
| |-- fs-sparse/ # Sparse formats and solvers
| |-- fs-fft/ # FFT and DCT transforms
| |-- fs-ivl/ # Certified arithmetic and predicates
| |-- fs-cheb/ # Chebyshev functions and collocation
| |-- fs-rand/ # Counter-based RNG and QMC
| |-- fs-ad/ # Automatic differentiation
| |-- fs-eproc/ # E-process inference
| |-- fs-euler-disc-e2e/ # Euler-disc scientific contract and no-claim boundary
| |-- fs-geom/ # Chart/region abstractions
| |-- fs-rep-sdf/ # Signed-distance-field charts
| |-- fs-rep-mesh/ # Mesh charts and repair
| |-- fs-rep-frep/ # F-rep/CSG charts
| |-- fs-xform/ # Design parameterizations
| |-- fs-img/ # LUMEN image artifact plumbing
| |-- fs-mesh/ # Tetrahedralization and remeshing
| |-- fs-conduction/ # Steady conduction, contact, and surface radiation
| |-- fs-convection/ # Validity-gated heat-transfer correlations
| |-- fs-airflow/ # Typed fan curves and uncertain loss networks
| |-- fs-ledger/ # Design ledger on FrankenSQLite
| |-- fs-ir/ # FrankenScript IR
| |-- fs-plan/ # Cost and error planning
| |-- fs-opt/ # Optimization problem IR scaffold
| |-- fs-roofline/ # Roofline measurement harness
| `-- fs-vskeleton/ # Narrow PV vertical skeleton
|-- xtask/ # Repository policy checks
|-- docs/ # Conventions, CI/DSR gates, templates
|-- COMPREHENSIVE_PLAN_FOR_FRANKENSIM.md
| # Long-form architecture reference
|-- AGENTS.md # Agent operating rules
|-- unsafe-capsules.json # Registered unsafe capsules
|-- constellation.lock # Franken sibling repository pin file
|-- frankensim-source-manifest.json # Exact structural source/SBOM inventory
`-- frankensim-source-manifest.spdx.json
# Deterministic SPDX 2.3 JSON projection
The complete crate list is the members array in Cargo.toml. Use find crates -mindepth 2 -maxdepth 2 -name Cargo.toml for a filesystem inventory.
| Capability | FrankenSim today | Mature solver stacks | General scientific Python |
|---|---|---|---|
| End-user simulation app | Not yet | Yes, depending on stack | Usually assembled by user |
| Library substrate | Yes, source workspace | Yes | Yes |
| Determinism and cancellation contracts | Explicit crate contracts | Varies by project | Varies by package |
| Evidence-carrying values | Implemented core wrappers | Usually external/ad hoc | Usually external/ad hoc |
| Geometry representation contracts | Implemented SDF/mesh/NURBS/voxel/F-rep chart layer | Often specialized | Usually library-specific |
| Design ledger | Implemented FrankenSQLite-backed crate | Often separate tooling | Usually separate notebooks/files |
| Roofline measurement | Implemented harness crate | Varies | Usually external tooling |
| Packaged distribution | Not yet | Often yes | Yes |
Use FrankenSim today when you want to work inside a deterministic, evidence-oriented Rust substrate for simulation infrastructure. Use a mature solver stack when you need a ready-made production physics solver or GUI today.
FrankenSim uses local path dependencies for the Franken constellation. Keep sibling repositories next to this checkout:
~/projects/frankensim
~/projects/asupersync
~/projects/frankensqlite
From a fresh checkout, the supported way to create and verify that layout is:
cargo run --manifest-path tools/bootstrap/Cargo.tomlThen rerun:
cargo test --workspaceUse the pinned nightly toolchain:
rustup toolchain install nightly
rustup component add rustfmt clippy --toolchain nightly
cargo +nightly test --workspaceRuntime dependencies are intentionally restricted to the Franken constellation and workspace crates. Dev-only oracle dependencies may be allowed in test scope, but runtime additions need an architecture decision and matching contract update.
cargo run -p xtask -- check-depsEvery fs-* crate must ship a CONTRACT.md with the required sections. If this check fails, either a new crate was added without a contract or an existing contract lost one of the required sections. Use an existing crate contract as the local template and keep the no-claim boundaries honest.
cargo run -p xtask -- check-contractsTreat DSR as the project automation source of truth. Local commands are useful for fast iteration; DSR is the lane to cite when reporting repository health.
DSR_BIN="$(command -v dsr || printf '%s' /Users/jemanuel/projects/doodlestein_self_releaser/dsr)"
"$DSR_BIN" quality --tool frankensimFrankenSim has substantial working code, but it is still early infrastructure.
| Capability | Current state |
|---|---|
| Stable public API | Not promised yet; contracts exist, but APIs may still change |
| End-user CLI/application | A source-built CLI, not a packaged application. solve/run execute seven stages (import-verify through report) on declared .fsim projects, and run executes FrankenScript cooling.* programs through the same stages; the QoI verdict is Estimated and remains indeterminate while any of its eight budget terms is NO-DATA. study runs the scalar thermal and 2-D elasticity studies. cooling-network* are experimental JSON workflows on hand-authored tet solids without geometry import or a ledger; cooling-cht is an experimental JSON workflow for voxel conjugate heat transfer on uniform or graded Cartesian grids (finite-volume SIMPLEC airflow, steady or unsteady (BDF2), forced or Boussinesq natural convection with openings, optional LVEL algebraic turbulence, boundary and internal fans with curves, grilles and porous blocks, JEDEC two-resistor compact components, gray surface-to-surface and surroundings radiation, and one conservative energy equation over fluid and solids, plus parametric plate-fin heatsinks, grid-search design studies over any scene value, and three-grid convergence studies with Richardson extrapolation and GCI bands; see examples/cooling-cht/) |
| crates.io distribution | Not published |
| GitHub Actions | Not authoritative for this repo; use DSR |
| Full multiphysics solver suite | Not complete in the current workspace. The only production-grade 3-D solver is steady conduction; the nonlinear solid and fluid solvers are 2-D on fixture meshes. Retired from v1 by owner decision on 2026-09-01 (bead frankensim-rc-root-q61wp.25), each retained as an [M] deferred epic: IGA Kirchhoff–Love shells (.40), turbulence on a mesh (.41), compressible flow (.42), FMM-accelerated VPM (.43). No field-level FSI or transient multiphysics exists; the conduction ↔ 1-D air-path exchange is steady. Separately, fs-lbm::conjugate carries an experimental 3-D voxel conjugate-heat-transfer path (finite-volume SIMPLEC airflow with LVEL algebraic turbulence, Boussinesq buoyancy, fans and resistances, and a conservative energy equation; measured fixture bands in crates/fs-lbm/CONTRACT.md) that no .fsim stage consumes and that holds no registered maturity claim |
| Surface radiation | fs-conduction now admits card-backed hemispherical-total emissivity, builds a validity-bounded 4 ε σ T_mean³ surface-to-ambient Robin row while reporting its pointwise discrepancy from the full T⁴ law, validates closed-enclosure view-factor row sums and area-weighted reciprocity, solves deterministic gray-diffuse radiosity, and couples one uniform frozen flux per named P1 trace through a declared outer fixed point. The crate does not generate view factors or QMC rays, validate an external generator, model participating media or spectral/specular/semitransparent surfaces, support spatially varying emissivity/trace flux, add radiation atop an occupied boundary row, propagate a nonlinear uncertainty certificate, expose a radiation adjoint, or carry retained-corpus/L4 authority |
| Convection correlations | fs-convection implements 12 sourced analytic or empirical relations with machine-readable domains and structured refusal, plus a tested Robin seam into fs-conduction. One card manually encodes a narrow Shah-London developing-rectangular Table 52 slice and labels its lower-Gz limit bridge as an engineering interpolation. Its empirical discrepancy bands are declared engineering allowances rather than source-published confidence intervals; a broader source-table corpus, automatic model selection/blending, interrupted-fin and array-interference cards, conjugate CFD, experimental validation, and a registered maturity claim remain absent |
| Enclosure airflow | fs-airflow validates monotone typed fan curves, bounds fan-law speed scaling, composes quadratic series/parallel losses with a mandatory explicit leakage branch, certifies the unique nominal-model operating root with fs-ivl, and hands evidence-bearing branch velocities/Reynolds inputs to fs-convection. Its retained tests use synthetic fixtures: no manufacturer curve/tolerance corpus, unequal parallel-fan model, installation-effects model, CFD comparison, experimental validation, or registered maturity claim exists |
| Neural representations | fs-rep-neural exists as a first-class crate, but its current work is experimental/in flight and has no registered capability-maturity claim |
| Design ledger | fs-ledger exists, but the registry holds it at L1: the evidence-binding guard was repaired (b4ece64b) and four GC suite failures remain red on one tracked upstream FrankenSQLite cascade-ordering root cause |
| Browser flagships | Source surfaces exist and build; the registry holds the capability at L1 because two campaign tests (grammarforge, sensorforge) are red |
| Randomized NLA golden sentinel | Resolved: rand_nla_golden_hash is deliberately recorded (0xeef1_0550_7daf_c0d5) and verified identical on arm64 and x86-64 in both debug and release, after fixing a build-mode-dependent powi fixture; the workspace-wide powi sweep is tracked in bead frankensim-powi-build-mode-determinism-4xnt |
| Ascent golden sentinels | Resolved: the trajectory and Pareto golden constants (0xe185_4f98_a25e_3663 and 0x301b_04df_db91_3965) under TRAJECTORY_BIT_SEMANTICS_VERSION = 1 are requalified across darwin/arm64 and x86_64 in both debug and release profiles with clean-tree proofs; four retained receipts are archived at crates/fs-ascent/tests/receipts/ascent_golden_{x86_64,aarch64}_{debug,release}.json (bead frankensim-ascent-golden-requalify-o6bne) |
| Long-running stability fixtures | Some structural stability and snap-through tests are active proof lanes and may need targeted runtime/threshold work rather than being treated as cheap smoke tests |
| Production validation corpus | Partial, not production-ready. fs-vvreg registers 20 Level-A thermal formula/order definitions, five thermal Level-B cross-code cases, and four retained Level-C published-experiment records (the Martin-Moyce 1952 digitized curve plus three further published records). fs-conduction resolves eight analytic rows, including pole-free spherical-shell and matching-P1 two-slab contact cases, plus seven MMS rows (four P1 primal, one P1 adjoint, one P2 primal, and one P2 adjoint) while executing its tests; both P2 ladders use the high-order FEEC tetrahedral kernel. The infinite-parallel-plate view-factor row remains reference-only because the current constructor stores F12 = F21 = 1 literally rather than computing visibility from geometry. fs-convection resolves the two circular-duct Nusselt limits; fs-time resolves the normalized small-Biot lumped decay through dense and operator-backed first-order generalized-alpha paths. The complete crosswalks therefore bind 18 of 20 Level-A rows and preserve the view-factor row as an explicit gap. The fourth primal P1 MMS binding combines a rotated orthotropic frame, three distinct linear k_i(T) laws, the full chain-rule manufactured source, and nonlinear iteration; it is observed-order evidence on the declared mesh ladder, not a universal convergence proof. The P1 heat-adjoint binding solves a quartic manufactured dual through fs-adjoint, checks the discrete primal/dual identity on every rung, and gates its L2 order; it is not a goal-oriented error bound. The P2 primal binding runs the existing fs_feec order-2 simplex stiffness/load/L2 path for a constant-isotropic homogeneous-Dirichlet fixture. The P2 heat-adjoint binding solves the manufactured dual through the same high-order operator and fs-adjoint, then checks the discrete primal/dual identity on every rung. Neither P2 binding turns the P1 fs-conduction material/boundary frontend into a general P2 thermal frontend, supplies a P2 design-gradient pullback, or establishes a DWR estimate. These are test-time crosswalks, not retained corpus receipts: solver/model envelopes remain distinct from the catalog's formula-reproduction tolerances, no ladder or machine fingerprint is persisted into fs-vvreg, and registry queries remain Estimated with numerical NoClaim. The contact binding is limited to exact duplicated matching-P1 traces and retains an ordered material-card/property receipt in the solve report; it has no nonmatching/mortar projection, variable contact law, scenario-object auto-lowering, or retained registry authority. The radiation battery proves gray-diffuse algebra for an admitted matrix, an unequal-area enclosure closure, and a coupled closed-form heat balance; it does not implement a view-factor formula, establish a geometry/QMC generator, carry a radiation-dominated retained corpus case, provide nonlinear uncertainty authority, or confer L4 validation. The lumped binding proves only the normalized scalar ODE under the catalog's applicability context, not a spatial transient-conduction model. The external Level-C row is derived-only and still lacks original raw records, instrument/calibration/placement authority, acquisition conditions/date, replayable digitization lineage, resolved redistribution terms, and a defensible scalar acceptance envelope. No capability may infer L4 from registration or these test bindings alone |
| Performance claims | Must be backed by fs-roofline/ledger evidence; do not infer claims from architecture text alone |
| GPU/accelerator execution | Not implemented. A code-derived [M] pilot doctrine, quantitative profiling falsifier, candidate list, and existing-versus-new backend evidence map now exist; they do not admit a runtime, run a device kernel, or establish speedup, energy savings, equivalence, or production fitness |
The long-form architecture reference remains in COMPREHENSIVE_PLAN_FOR_FRANKENSIM.md, but this README describes the code that is already present in the repository.
Yes, as a Rust source workspace and simulation-infrastructure library substrate. It is not yet a polished end-user simulator, and the current maturity registry holds one L3 integrated-workflow capability (steady conduction through the seven-stage solve pipeline, on a retained lane receipt) and no L4 validated or L5 supported capability.
Start with the workspace tests and policy checks:
cargo test --workspace
cargo run -p xtask -- check-allFor the project validation lane, use:
DSR_BIN="$(command -v dsr || printf '%s' /Users/jemanuel/projects/doodlestein_self_releaser/dsr)"
"$DSR_BIN" quality --tool frankensimThe repository pins nightly in rust-toolchain.toml for Rust 2024 plus narrow nightly features documented in the repo, including const-generic dimension arithmetic and optional portable-SIMD experiments. Most code is written so future de-nightlying should be localized rather than a rewrite.
The workspace intentionally depends on other Franken projects by path for runtime pieces such as asupersync and frankensqlite. xtask check-constellation and constellation.lock make that relationship explicit.
Yes. Existing CONTRACT.md files are part of how the workspace communicates implemented behavior. If code and contract disagree, that is a bug to resolve, not a documentation detail to ignore.
No. Use DSR for this repository unless the repository policy changes. GitHub Actions may be absent, stale, or non-authoritative.
Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Codex or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
FrankenSim is licensed under the MIT License with the repository's Anthropic/OpenAI rider. See LICENSE for the exact terms.
