Get Started

Clone the continuum.

An honest status: FrankenSim is a large, working Rust workspace — 54 crates, ~106K lines, 855 tests — but it is not yet a packaged simulator. There is no stable public API, no CLI, and no crates.io release. You build it from source and read the plan.

54 crates~106K lines of Rust855 inline testsPure, memory-safe Rust
Before You Build

Prerequisites

A short list. The toolchain pins itself; you supply Rust and git.

Rust 2024 edition

The workspace targets the 2024 edition across all 54 crates.

A pinned nightly toolchain

rust-toolchain.toml pins the exact nightly, so rustup installs it automatically on first build.

git

To clone the repository and stay in sync with the plan.

Build From Source

Six commands to a live skeleton.

Clone, build, test, and run the vertical skeleton end-to-end — then let xtask check that the repository's own rules still hold.

01

Clone the continuum

One acyclic workspace, seven layers from L0 Substrate to L6 Helm. Everything lives in a single repository.

terminal
$git clone https://github.com/Dicklesworthstone/frankensim
02

Enter the workspace

The root Cargo.toml defines the whole constellation; rust-toolchain.toml pins the toolchain the moment you cd in.

terminal
$cd frankensim
03

Build every crate

Compiles the full workspace. The first build is the long one — it pulls the pinned nightly and warms the cache.

terminal
$cargo build --workspace
04

Run the test suite

855 inline tests plus 82 conformance suites. This is the fastest way to confirm your machine reproduces the reference behavior.

terminal
$cargo test --workspace
05

Run the vertical skeleton

fs-vskeleton is the end-to-end demonstrator: a tiny 2D SDF → PDE → objective → adjoint → optimize → ledger → replay. The whole continuum in one binary.

terminal
$cargo run -p fs-vskeleton
06

Check repository policy

xtask enforces the rules as code: the acyclic layer direction, Franken-only dependencies, contract presence, and unsafe-capsule registration.

terminal
$cargo run -p xtask -- check
The Interface

One True Interface

Agents and humans drive FrankenSim through FrankenScript — a typed, versioned IR with isomorphic s-expression and JSON syntaxes, where the Five Explicits are never left implicit.

FrankenScript — a study
studies/spout-laminar-v3.fscript
01(study "spout-laminar-v3"02  (seed 0x5EED0001) (versions (constellation :lock "2026-07"))03  (budget (wall 2h) (mem 96GiB) (qoi-rel-error 2e-2))04 05  ; geometry: a revolved Chebyshev profile with a filleted lip06  (
let
 vessel (frep (revolve (cheb-profile "body.chb"))07                    (fillet :edge lip :r 3mm)))08 09  ; physics: a free-surface pour, tilted over 3 seconds10  (
let
 pour (flux.free-surface-lbm vessel11              (fluid :model (carreau :mu0 0.12Pa*s :n 0.8) :sigma 0.061N/m)12              (schedule :rate 0.5L/s :tilt (ramp 0deg 65deg 3s))))13 14  ; optimize the lip lever 
for
 pour stability, stop when decisive15  (ascent.optimize J :over lever :method (lbfgs :m 17)16    :until (any (grad-norm 1e-5) (e-value 20) (budget-exhausted))17    :emit (pareto ledger report)))
Syntax_Validation_Active
UTF-8_ENCODED

A FrankenScript program states its seed, versions, and budgets inline; the lowering trace is inspectable, and when a request is infeasible the error is structured and carries ranked fixes. A refusal that teaches is worth ten silent successes.

The Five Explicits — never implicit, ever
Units

Dimensional quantities are compile-time typed. A meter never silently becomes a second.

Seeds

Counter-based RNG keyed by logical identity. Every random draw is reproducible by construction.

Budgets

Accuracy, time, and memory ceilings travel with every call and compose across the whole plan.

Versions

The constellation is locked by hash. The kernels that produced a result are always recoverable.

Capabilities

The Cx context grants exactly what an operation may touch — arena, cancel token, ledger, budget.

And the Rust underneath
examples/laplacian.rs
01
use
 fs_sparse::{Coo, Csr};02 03// Assemble a 1-D Laplacian, deterministically.04
let
 
mut
 coo = Coo::new(3, 3);05coo.push(0, 0,  2.0);06coo.push(0, 1, -1.0);07coo.push(1, 0, -1.0);08coo.push(1, 1,  2.0);09coo.push(1, 2, -1.0);10coo.push(2, 1, -1.0);11coo.push(2, 2,  2.0);12 13
let
 csr: Csr = coo.assemble();      // fixed-shape, order-independent14
let
 
mut
 y = vec![0.0; 3];15csr.spmv(&[1.0, 2.0, 3.0], &
mut
 y); // bit-identical on 1 or 96 cores16assert_eq!(y, vec![0.0, 0.0, 4.0]);
Syntax_Validation_Active
UTF-8_ENCODED

Below the IR, the crates are ordinary safe Rust you can call directly. Sparse assembly is fixed-shape and order-independent, so a SpMV is bit-identical on 1 core or 96.

FAQ

Common Questions

What FrankenSim is, what it is not yet, and how it was built.

What exactly is FrankenSim?
FrankenSim is a working Rust workspace for deterministic geometry, certified numerics, meshing, execution, evidence, and design-ledger infrastructure for simulation and design optimization. Its goal: given a physics-based objective and constraints, synthesize the geometry that optimizes it — faster, more correctly, and more verifiably than any existing system, on commodity many-core CPUs, in pure safe Rust.
Why fuse geometry, physics, optimization, and rendering into one system?
Because the seams between OpenCASCADE, gmsh, FEniCS/OpenFOAM, SciPy/Dakota, and ParaView are where correctness drowns. Derivatives don't cross tool boundaries; error bounds don't either; provenance doesn't exist; cancellation means kill -9; and the hardware is wasted by MPI-shaped codebases. FrankenSim makes derivatives, error bounds, budgets, provenance, and cancellation ride inside the values instead of living in six incompatible tools' heads.
What does 'it returns proofs, not just numbers' mean?
Every result is an Evidence<T>: a value plus a proven interval bound, a provenance hash, an adjoint hook, and a cancellation scope. Quantities are typed verified, validated, or estimated, and composition is checked so an estimate can never wear the badge of a certificate. A false certificate is worse than an ordinary wrong answer — a wrong answer wearing a badge — so the type system exists to prevent exactly that.
Is FrankenSim faster than the incumbents?
The plan states illustrative, failable targets — GEMM ≥ 75% of peak, SpMV ≥ 85% of STREAM bandwidth, LBM ≥ 1.0 GLUP/s on an M4 Max, sphere-traced SDF rays ≥ 80 Mray/s — measured with a roofline harness against real machine peak on both Apple Silicon and 96-core Threadripper. Speed is necessary but not the pitch: the pitch is justified belief at minimum cost.
Who is it for?
AI coding agents and swarms are the primary operator — the whole system is designed around the Five Explicits so a fleet can drive it safely. It also targets simulation-infrastructure engineers who want a deterministic, evidence-oriented Rust substrate, and design-optimization users producing optimal artifacts (aircraft, seismic frames, vessels) at lowest cost.
How is correctness actually enforced?
By the Gauntlet (G0–G5), which gates every merge: property tests, manufactured-solution order verification that fails the build if the convergence slope drifts more than 0.2 from theory, canonical benchmarks, metamorphic tests, chaos and cancellation storms, and determinism / cross-ISA audits. Repository policy is code too — xtask mechanically enforces the acyclic layer direction, Franken-only dependencies, contract presence, and unsafe-capsule registration.
What makes the architecture different from a COMSOL-style platform?
Composition as a first-class certified operation. Incumbents assume a human absorbs the seams between solvers; FrankenSim makes the seam itself a typed, certified value. Merely-decent kernels with impeccable epistemics can beat excellent kernels with folklore epistemics in the verticals that need certification-by-analysis.
Why Rust, and why memory-safe?
Rust is the only mainstream substrate strong enough to hold the typed continuum together without a garbage collector or a C ABI in the hot path. The Decalogue's first principle is pure, memory-safe Rust: unsafe exists only in audited leaf capsules under 300 lines, each behind a safe façade, and each registered with the policy checker.
How does an agent actually talk to it?
Through FrankenScript — a typed, versioned IR with isomorphic s-expression and JSON syntaxes. A program states its seed, versions, and budgets inline; the lowering trace is inspectable; and when a request is infeasible the error is structured and carries ranked fixes with estimated impact. A refusal that teaches is worth ten silent successes.
What are the flagship demos?
Three forcing functions: an ornithoid multi-inlet aircraft that delivers a certified Pareto atlas with Lyapunov region-of-attraction proofs; a seismic-minimal building frame with a certified fragility curve and anytime-valid stopping; and a laminar-pour vessel — the spout that never dribbles — where the marketing shot and the physics are literally the same bytes. Plus the P2 marquee: topology optimization on a raw SDF with no mesh in the loop.
Can I use it today?
FrankenSim is a large, working Rust workspace — 54 crates, ~106K lines, 855 inline tests — implementing a substantial spine of the plan. It is not yet a packaged end-user simulator: there is no stable public API, no CLI, and no crates.io release yet. If you need a ready-made production physics solver or GUI today, the incumbents still win; if you want a deterministic, evidence-oriented Rust substrate to build on, this is it.
How was it built?
Through an AI engineering flywheel — a coordinated swarm of specialized coding agents orchestrated with tmux, guarded by command-safety layers, tracked in a beads issue graph, and given persistent memory and session search. The same toolchain that built FrankenTUI and asupersync built FrankenSim.

Read the plan, then build.

The source is the fastest way to understand the continuum. Start with the architecture, then see the flagships that force every layer to work end-to-end.

View on GitHubRead the ArchitectureSee the Flagships