selene-isru

A single-page, client-side engineering trade-space simulator for an integrated conceptual lunar ISRU chain. Move a slider; the entire lunar industrial chain — 3D diorama, energy Sankey, mass manifest, mission count, plant-mass throughput equivalent clock — recomputes and re-renders the same frame. No server, no debounce, no workers: the physics engine runs in well under a millisecond.

Model boundary: SELENE-ISRU is a conceptual systems and comparative trade tool, not a flight, hardware, safety, cost, or mission-readiness model. TypeScript/Python parity proves implementation agreement, not physical validation.

The renderer uses a hybrid procedural/Blender pipeline. Lunar terrain, regolith PBR maps, star fields, Earth, environment lighting, and effects are generated from code at runtime. Hero equipment can be generated reproducibly from checked-in Blender/Python source, exported as optimized GLB, and driven by live simulator state. The equatorial site now uses this workflow for the MRE reactor, excavation fleet, casting yard, cryogenic farm, power hub, landing system, and surface habitat. The polar site uses the same workflow for its tracked ice excavator, sublimation camp, beam receiver and Sabatier skid, cryogenic farm, rim power towers, nuclear station, and occupied habitat.

Live demo: dogum.github.io/selene-isru (deployed from main by GitHub Actions).

Two reference sites, one live engineering model

Equatorial MRE industry	Shackleton ice industry
Molten-regolith electrolysis, casting, surface power, and reusable logistics.	Ice excavation, sublimation, beamed power, and cryogenic storage, delivering water, LOX/LH₂ propellant, or Sabatier methane.

Build a custom lunar site

Custom Site turns the same model and equipment catalog into a durable site planning sandbox. Start with blank Equatorial or Polar terrain—or seed either reference layout—then place equipment, connect typed ports, route links, inspect clearances, and compare planned output with topology- and capacity-limited achievable output.

Blank Planner	Connected Planner	Explore

The complete desktop loop is:

1. Open CUSTOM SITE, choose an environment, and place equipment from the catalog.
2. Select an output port and then a compatible input port. Design Check keeps incomplete, dangling, or incompatible topology from reporting nominal output.
3. Use numeric X/Z/heading and route-bend fields, snapping, multi-select, group transforms, clearances, and measured extents to refine the plan.
4. Review installed capacity, route consequences, bottleneck, and achievable output; switch to EXPLORE without creating a second scene document.
5. Save the design into Trade Study or export its versioned JSON. Imports show findings and require explicit acceptance before replacing the working design.

Mobile intentionally provides select-and-inspect review rather than suggesting unsupported precision editing. Designs autosave locally with a valid backup, and large layouts retain selectable lightweight placeholders after the active graphics tier’s detailed-model budget.

Importable v1 examples:

• Equatorial First Camp
• Shackleton Ice Camp

Release screenshots, the reproducible browser smoke flow, performance sample, and known limits are recorded in the Custom Site release evidence.

Cinematic demonstrations

The repository includes five production-app videos: a branded simulator tour, the release-evidence workflow, a one-minute Custom Site story, its native-speed 30-second companion, and a deeper engineering analysis. All are silent 1080p H.264 MP4s so narration, music, or platform-native audio can be added in post.

Product cinematic	Detailed Custom Site cinematic
Watch the 32-second product tour	Watch the 60-second detailed story

Also available: the 30-second short Custom Site cut, the 45-second release workflow, and the 86-second engineering analysis. See the video showcase for storyboards, intended uses, and reproducible capture commands.

Equipment that explains itself

Select a subsystem to focus the camera, inspect its live engineering state, and tune the same model inputs that drive the full simulation. The interaction works on desktop and as a touch-friendly inspector on mobile.

Progressive learning and analysis

The default view stays simulator-first. Optional layers add explanation only when they are useful:

• Learn projects clickable asset labels and leader lines into the 3D scene, adds a reset-camera control and readability lock, and can overlay live, directional material and power paths between equipment. Selecting one asset isolates its connected subsystem even when Learn is off.
• Undo and redo step back through every change to the case on screen and the comparison beside it: slider drags (one step each), typed values and resets, presets, applied Brief, frontier and sweep points, loaded cases, comparison snapshots, swaps, and site switches (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, or the arrows in the top bar). Tours put your case back when they end, or keep theirs with KEEP THIS CASE, one undo away from yours.
• Trade Study is the scenario workspace:
  • Scenarios. It stores up to 24 named browser-local cases, each with notes that travel with its exports. UPDATE overwrites a saved case with the live one, keeping its name, notes, and pin; a Custom Site design is updated from the planner, over the case it was opened from or saved as. Each card says whether it matches the live case. Up to four pinned cases are compared side by side, outputs and every input that differs between them.
  • Sweep. It runs any input the rail shows across its full engine range against any numeric output, as a line or as a 2-D map, and exports every point.
  • Pareto, sensitivity, and report. It searches a constrained Pareto grid over curated or any other axes, ranks local sensitivity, and produces a print/PDF-ready engineering report.
  • Sharing. It shares reproducible URLs and imports and exports JSON and CSV.
• Brief is an opt-in goal workflow for questions such as a polar water camp, minimum landed mass, or the solar/nuclear crossover. It performs a transparent bounded design search, ranks designs inside active implemented constraints, and reports the bottleneck, largest drivers, illustrative sensitivity range, and caveats. You can apply a pick, or save it or the top three to the library with notes on the search that produced them.
• Inputs use plain engineering names by default, can toggle to engine variable names, and expose model maturity, source links/sections, illustrative input spreads, range rationale, applicability, and validity limits beside the control.
• Campaign follows the plant from its first landing to the end of its mission. It counts the mass in low Earth orbit spent landing and sustaining the plant against the mass its product saves, and reports when the product has repaid the launch mass. The model covers deployment cadence, commissioning, downtime, spares, and dedicated versus shared landers. It is a mass account only, not cost or schedule risk (). An optional refuelling demand, a reusable lander flying sorties from the plant, credits only the propellant it burns and charts how its stores draw down ().

Getting data out

Every export carries the model boundary and the build that produced it (app and engine versions plus commit), so a file read out of context can be traced.

• Case JSON (Report tab, or any library card): every input with its unit, the full engine result, the day/night timeseries, the inputs that differ from defaults, and a reproducibility link; custom sites add their design and evaluation. It imports back into the library, and on import the case is re-run and any headline value the current model computes differently is reported.
• Study CSV (library and Report): one row per case with headline outputs, every energy-flow stage, every input as param.<key> [unit], and the case's notes.
• Panel CSVs: energy flows, mass manifest, the 96-sample timeseries, the campaign ledger over time, every sweep point, every Pareto grid point, the sensitivity ranking and uncertainty bands (with sample count and seed), and every candidate the Brief evaluated.

Numbers are written at full precision. Result columns are named by engine field, which carries its unit (energy.secTotal_kWhPerKg, logistics.totalInfraMassKg).

Implementation parity and evidence

Every core process equation used by the authored simulation lives twice:

• TypeScript (packages/engine) — the runtime engine the app calls on every input event. Zero dependencies, pure ESM, with a 176 KiB CI budget including the versioned custom-site schema, graph validator, installed capacity evaluator, and disclosed cable/haul screening models.
• Python (python/selene_isru) — an independent mirror used for derivations, citations, and golden-vector generation.

The custom-site compiler is a TypeScript-only evaluation layer around that shared process model. Its screening capacity and route equations are isolated, disclosed in the planner, and covered by dedicated deterministic unit tests; they are not represented as Python-parity-validated hardware models.

python/tools/generate_golden.py Latin-hypercube samples 200 points across the full parameter box (plus named corner scenarios), runs the Python engine, and writes packages/engine/test/golden_vectors.json. Vitest then asserts that the TypeScript engine reproduces every numeric leaf to 1e-9 relative tolerance. CI regenerates the vectors from Python on every push — a unilateral edit to either implementation breaks the build.

External analytical anchors and conservation invariants are tested separately from the parity vectors. The original review is recorded in docs/model-audit-v02.md; its five major continuation items and their remaining limits are documented in docs/model-depth-v03.md. The v0.4 fidelity pass (polar capture loss, heater loss, and extractor mass anchored to NASA's polar-water case study, and storage provenance moved into constants.json) is in docs/model-fidelity-v04.md. The v0.5 campaign ledger (launch-mass payback with deployment, commissioning, downtime, and spares) is in docs/model-campaign-v05.md. The v0.6 polar propellant chain (water split into LOX/LH₂, with liquefaction energy and hardware derived from NASA's polar propellant design) is in docs/model-propellant-v06.md. The v0.7 refuelling demand (a reusable lander's propellant per sortie, with the ledger crediting only what it burns) is in docs/model-refuel-v07.md. The v0.8 ilmenite hydrogen-reduction process (soil sizing, magnetic concentration, reduction at 1,000 °C, and water electrolysis, calibrated to Eagle Engineering 1988) is in docs/model-ilmenite-v08.md. The v0.9 excavation basis (every plant's mining energy and fleet sized on the soil it moves, with the overburden a polar pit mine strips) is in docs/model-excavation-v09.md. The v0.10 ilmenite reactor (conversion from temperature and residence time, and a fluidized bed sized by the solids it holds, calibrated to Eagle's no-separation trade) is in . The v0.11 basalt feed (Eagle's crushed high-Ti basalt as a second ilmenite feedstock, with crushing, grinding, and overburden, calibrated to Eagle's basalt-fed plant) is in . The v0.12 excavator fleet (whole RASSOR-class vehicles sized from their payload, speed, loading time, shift, and haul distance, calibrated to Guerrero-Gonzalez & Zabel's 2.7 t/day) is in . The v0.13 Sabatier plant mass (the water electrolyzer plus a Sabatier block per kg/day of methane from NASA's 2017 Mars propellant plant, in place of the borrowed MRE coefficient) is in . The v0.14 electrolysis balance of plant (pumps, deionizer, dryers, and controls as a fraction of stack power, calibrated to NASA's polar electrolyzer and cross-checked against DOE's PEM targets) is in . The v0.15 overburden timing (the fleet's initial strip run alongside commissioning, delaying production when it takes longer) is in . The v0.16 demand sizing (a solver and a rail control that set the plant target to the smallest plant meeting a refuelling demand for everything it makes) is in .

Architecture

constants/constants.json ──── single source of truth (values, bounds, units, citations)
        │ codegen                       │ import
        ▼                               ▼
packages/engine (TS)  ◄── parity ──►  python/selene_isru
        │  simulate(params) → SimResult         │
        ▼                                       ▼
packages/app (React + Three.js)         notebooks / golden vectors
  ├─ state/store.ts    zustand: setParam → simulate() → render, URL sync
  ├─ viewer/           vanilla Three.js Viewer class (no react-three-fiber)
  │   ├─ bindings.ts   SimResult → scene contract + graphics tiers (§ tested)
  │   ├─ post.ts       EffectComposer chain: GTAO, bloom, SMAA, output
  │   ├─ textures.ts   generated PBR maps + PMREM environment
  │   └─ dioramas/     equatorial + polar authored scenes + dynamic custom planner
  └─ components/       control rail, KPI strip, Sankey/Mass/Power panels
assets/blender/         reproducible hero-asset generators + editable .blend source

The app consumes only the engine's public API (simulate, DEFAULTS, PARAM_META, and the exported pure helpers) — zero physics re-derivation in UI code. The starfield, Earth, and terrain/textures remain seeded math; authored hero equipment includes its generator, editable Blender source, optimized web asset, and license entry in assets/ASSET_LICENSES.md. The top-bar graphics menu exposes Auto/Low/Medium/High/Ultra tiers, bloom, the dev HUD, photo mode, and PNG export.

Visual QA and performance notes are recorded in the MRE vertical slice, the equatorial equipment overhaul, the polar equipment overhaul, and the analysis and explainability sprint.

The implemented model-backed site editor is defined in the Custom Site Sandbox product and implementation specification and reviewed in the release evidence.

Workspace

• constants/constants.json — constants, defaults, slider bounds, units, citations.
• packages/engine — TS physics engine (frozen public API).
• packages/app — React + Three.js frontend (Vite, deployed to Pages).
• assets/blender — original Blender/Python source for reproducible 3D assets.
• python/ — mirror package, pytest suite, derivation notebook, golden generator.
• docs/screenshots/ — captured via pnpm screenshots against a dev server.
• docs/examples/ — importable site profiles and versioned custom-site documents.

Commands

pnpm install
pnpm dev                     # app dev server (http://localhost:5173)
pnpm test                    # engine + app vitest suites
pnpm build                   # engine build + app production build
pnpm asset:mre               # regenerate the MRE .blend and optimized GLB
pnpm asset:equatorial        # regenerate the remaining equatorial equipment library
pnpm asset:polar             # regenerate the polar equipment library
pnpm demo:analysis -- http://localhost:4173/selene-isru/ /tmp/selene-video-candidates
                             # record the 86-second engineering-analysis tour
pnpm demo:cinematic -- http://localhost:4173/selene-isru/ /tmp/selene-video-candidates
                             # record the scripted 32 s / 1080p cinematic product tour
pnpm demo:custom-cinematic -- http://localhost:4173/selene-isru/ \
  /tmp/selene-video-candidates
                             # record the detailed Custom Site story and fast cut
pnpm evidence:custom -- http://localhost:4173/selene-isru/
                             # smoke-test Custom Site and regenerate screenshots
                             # and performance evidence (videos are separate)
pnpm smoke:custom -- http://localhost:4173/selene-isru/
                             # run the same browser workflow without writing evidence

# Python mirror (uv creates and manages the project environment)
uv sync --project python --locked --group dev
uv run --project python pytest python/tests
uv run --project python python python/tools/generate_golden.py

Run the complete parity, test, lint, and production-build pipeline with pnpm run ci. See CONTRIBUTING.md for model-change guidance.

Engine API

import { simulate, DEFAULTS, PARAM_META } from "@selene-isru/engine";

const result = simulate({ targetKgPerDay: 1000, site: "equatorial" });

Units are annotated on every input (constants/constants.json) and carried in every result field name (secElec_JPerKg, gridPowerW, paybackDays). Most process equations are SI, but storage sizing, the timeseries, and the campaign ledger work in hours, watt-hours, and days. Energy Sankey lines are exposed as kWhPerKg, and all out-of-range numeric inputs are clamped to constants/constants.json bounds with a param-clamped warning.

Scenarios share via URL — non-default params serialize to a compact query string (?site=polar&chiIce=0.03) that round-trips to an identical SimResult (asserted in tests).

Time-resolved polar profiles can be imported in the Power controls. See the checked-in JSON profile example for the supported schema and docs/model-depth-v03.md for interpolation, validation, and model-boundary details.