Skip to content

Architecture

llevant compiles an MCNP input into a read-only model and answers geometry questions about it exactly and fast:

  • where points are, and what lines cross;
  • where rays first meet visible cells;
  • slices and 3D views;
  • volumes, and the gaps and overlaps of a model;
  • fingerprints that tell two versions of a model apart.

It answers from the command line, from Python and in an interactive viewer. Results of a transport run (per cell, per cell instance or on a mesh) can be drawn over the geometry.

This page is the map: why llevant exists, the crates and the rules between them, how data flows, and how it is tested. Details:

Document Contents
contracts.md What each query guarantees, and the test that holds it
internals/engine.md The engine: compiled model, search structures, queries, fingerprints, instances, volumes, deliberate semantics
internals/rendering.md Colours, fields, realistic shading, the GPU renderer, slices, the viewer
decisions/ Lasting decisions and the measurements behind them
mcnp-behaviour.md What MCNP does where the manual is silent, and how llevant is checked against it
benchmarks.md Current numbers, generated by llevant-bench report
guide/, how-to.md, reference/ Using the CLI, Python and the viewer (the user pages of the documentation site)

Why

Production MCNP models are large:

  • 20 m long, with features down to millimetres;
  • 10⁵–10⁶ surfaces and cells;
  • several universe levels and lattices.

Questions about their geometry come up all the time, and MCNP answers them slowly or not at all:

  • Which cell is here?
  • What does this line cross?
  • What does this plane or this view look like?
  • What is the volume of each cell and material?
  • Where are the gaps and overlaps? MCNP finds them as lost particles, one at a time.
  • What changed between two versions of a model?

In an envelope-based workflow (gitronics, or any similar one), a reactor model is assembled from an envelope structure converted from CAD, with filler universes placed inside the envelopes. Each new version can go wrong silently:

  • an envelope that shrank clips its filler;
  • one that grew leaves a gap;
  • filler cells overlap;
  • a transform is wrong.

Random points do not find these: a 1 cm³ change in 10¹⁰ cm³ needs ~10¹⁰ points and still misses 1 mm gaps. Lines traced exactly do not miss them along their direction. Tracing is many small, uneven tasks, which suits compiled code and threads sharing one model; at 10⁶ surfaces, one copy of the model per process does not fit.

Goals and non-goals

Goals:

  • Exact answers. Exact line tracing (segments per cell at every level, with the surface crossed at each boundary). Points classified with their full path. Gaps and overlaps found while tracing.
  • Every MCNP geometry feature the models use: universes, FILL/*FILL, TRCL, lattices, all macrobodies, nested to any depth.
  • Fingerprints of each universe and cell, independent of numbering.
  • Scale. The largest models load in seconds, and threads share one read-only model.
  • Views. Slices with exact boundaries; 3D views with hidden cells and cutaways; realistic images; an interactive viewer that stays smooth on any model.
  • Volumes and checks. Volumes per cell, material, universe or tally bin, with an honest uncertainty; every gap and overlap with its volume and location.
  • Frontends. A CLI usable in CI, Python with a numpy batch API, and a desktop viewer whose views other programs can embed.

Non-goals:

  • Writing MCNP: inputs are edited through migjorn's lossless tree (the viewer edits one card's text at a time); llevant writes no MCNP of its own.
  • Transport or tallies: frontends draw results, but llevant computes none.
  • Workflows across versions of a model (segment caches, policies about which envelopes may change): these belong to downstream tools.
  • GPU computation outside the 3D view (decision 0001).
  • Matching the CAD.

Planned, not built yet:

  • A persistent mode for scripts and agents (llevant serve over JSON lines, or an MCP server): a model loaded once and queried many times, answering in the CLI's JSON (guide/cli.md). Python covers this today.

Crates

                    llevant  (engine: geometry only)
                    ▲      ▲
                    │   llevant-scene  (rules, hiding, looks, field data, input cards, cache)
                    │      ▲  ◄── aci-tallies-geom, aci-tallies (crates.io)
                    │   llevant-render  (colours, scales, field looks, shading, labels, PNG)
                    │      ▲      ▲
                    │      │   llevant-gpu  (first hits on the GPU)
                    │      │      ▲
        ┌───────────┴──────┴──────┴─────────┐
        │                                   │
   llevant-cli ◄── llevant-viewer      llevant-py
   (`llevant`)     (app, widgets)      (Python; `python -m llevant` runs the CLI)
Crate Owns Default member
crates/llevant The engine: compile, classify, trace, first hits, slices and cameras, fingerprints, instances, universes on their own, volumes, save/read, export (the GPU's format) yes
crates/llevant-scene What frontends build from a model: cell rules (query, index), what 3D views hide (hiding), material looks (Looks), field data and tally reading (field), the input's cards (source), the disk cache (store) yes
crates/llevant-render Pixels: colours (Paint), colour scales, how fields are drawn, direct physically based shading, labels, ghost shells, PNG yes
crates/llevant-cli The llevant command (run_cli, also behind python -m llevant; one JSON vocabulary in json.rs); features gpu and viewer yes
crates/llevant-gpu The GPU renderer (wgpu compute): first hits of camera rays no (slow to build, needs a GPU)
crates/llevant-viewer llevant-viewer, and the View3d and SliceView egui widgets no
crates/llevant-py The Python module llevant (PyO3, abi3 wheels, with the GPU and the viewer) no
tools/bench llevant-bench: benchmarks, checks against brute force and of the GPU against the CPU, work counters, the benchmark report no
tools/mcnp-oracle Checks llevant against MCNP itself; cuts sub-models no (needs MCNP)
tools/synthetic Generators of benchmark models of other shapes —
tools/release.sh Raises the version for a release: workspace version, pins, Cargo.lock (docs/CONTRIBUTING.md, "Releases") —

migjorn, the MCNP parser, and aci-tallies (mesh geometry and the meshtal, MCTAL and D1SUNED cell-under-voxel readers) come from crates.io. The tally files the tests read (MCNP output) are copies of aci-tallies' fixtures, in tests/fixtures/tallies.

Rules

  • The engine answers geometry questions only. It knows nothing of images, GPUs, UIs, Python or the environment (no std::env). Options come in as Options.
  • The model is read-only after compiling. What a frontend varies (material looks, visibility, cameras, view state, fields) is a value the frontend owns and passes in. An edit is a new model: Model::recompile against the old one, which reuses the universes whose content is unchanged (decision 0010). The text goes through migjorn.
  • The fast path equals brute force. Points get exactly the labels of llevant::reference. Lines agree with it as reference::traces_agree says. Boxes are conservative. contracts.md lists every guarantee and its test.
  • Results do not depend on the number of threads. Results are written by index, never in the order threads finish.
  • MCNP is the reference for semantics. Deliberate departures are listed in internals/engine.md, "Deliberate semantics".
  • Exact answers come from the CPU engine. The GPU renderer is approximate by design and only draws (decision 0001).
  • Frontends use the public API. llevant::internals (hidden, unstable) serves llevant-gpu, llevant-bench and the oracle. What a frontend needs from the engine becomes an engine feature, designed and tested there, never worked around in the frontend.
  • Shared frontend code goes down a layer, not sideways. What the CLI, Python and the viewer all need lives in llevant-scene, llevant-render or llevant-gpu.
  • The viewer's UI thread does no model-sized work. It reads state, swaps Arcs and buffers, and lays out what is on screen. Anything that scales with cells, instances, voxels or pixels runs on the deriver, a task, a worker or a pool of its own, and the views keep showing what they had until the result lands (decision 0008). llevant-viewer --storm checks it.

Data flow

 MCNP input ──migjorn──► compile ──► Model ──save/read──► disk cache (llevant-scene::store)
                                       │
            ┌──────────────┬───────────┼──────────────┬────────────────┐
            ▼              ▼           ▼              ▼                ▼
        classify         trace     first_hits     fingerprints      volumes
        (labels)      (segments)    (hits)        (digests)     (estimates, problems)
            │              │           │
            │      slices, labels  render ◄── Visibility (llevant-scene::hiding)
            ▼              ▼           ▼
      CLI tables     llevant-render: Paint (colours, Looks, field) ──► PNG, Python Image
                                       │
                         Model::export ──► llevant-gpu ──► viewer G-buffer ──► passes ──► window
  1. Load. Store::load hashes the input, the Options and the engine build. It reads the compiled model from the cache, or else recompiles it against the last version of the same path (or compiles it), and stores it (decision 0004, decision 0010). The viewer loads staged: it shows the model once its BVHs are built and swaps in the complete one when its octrees are.
  2. Compile. migjorn parses; llevant resolves LIKE BUT, transforms, macrobody facets, fills and lattices into flat arrays. Then it builds boxes, a BVH per universe, octrees with residual programs where boxes overlap a lot (decision 0002), and the problem box (decision 0003).
  3. Query. Every query takes a batch and returns flat arrays: label ids interned per batch, ready for numpy.
  4. Draw. llevant-render colours labels and hits with a Paint. The GPU renderer reads Model::export and traces camera rays in short slices (decision 0005). The viewer reprojects the hits it has every frame (decision 0006) and runs a chain of WGSL passes over them.
  5. Edit. The viewer writes an edited card into migjorn's tree and recompiles against the model shown. While a surface is dragged, a Draft previews it: the cells, rois and BVHs it touches are updated in a few ms, and the GPU copy is patched in place. The edit itself compiles on release (decision 0011).

Frontends

  • CLI (llevant): info, bbox, locate, trace, slice, render, materials, fingerprint [--diff], volume, check, view. It prints tables as text, CSV or JSON, and writes PNG images; check exits with 1 on gaps or overlaps. guide/cli.md.
  • Python (import llevant): a Model kept in memory. Batch queries take anything numpy.asarray accepts and return read-only numpy columns that Rust built, without holding the GIL. Images show inline in Jupyter. python -m llevant view opens the viewer from the wheel. guide/python.md.
  • Viewer (llevant-viewer): the 3D view and an exact slice side by side, with tools, rules, undo, fields, FMESH layout and analyses as background tasks. Its use in reference/viewer.md; embedding and the application's structure in its README; internals/rendering.md, "The viewer".

Testing

  • Against MCNP (tools/mcnp-oracle): random points are classified by llevant and by MCNP, and must agree. Confirmed points become golden tables that cargo test replays. No disagreement so far (mcnp-behaviour.md).
  • Fast path against brute force: property tests on random models, in every GridMode, with and without residual programs; the reference model in --ignored tests; llevant-bench verify and compare-trace.
  • Between queries: points along traced segments classify to their labels, and first hits are the first visible segments.
  • Volumes: analytic volumes, planted gaps and overlaps, and an honest sigma.
  • Determinism: identical results with 1 and N threads.
  • Images: GPU against CPU ray by ray; the viewer's images against llevant render; reprojection against fresh traces.
  • The viewer application, driven headlessly with egui_kittest, and the edit storm.
  • CI (.github/workflows):
  • fmt, clippy, and tests on Linux and Windows;
  • the GPU and viewer tests on lavapipe, and the renderer's shader compiled by DXC on D3D12 (WARP, nothing rendered) on Windows;
  • the wheel with pytest;
  • MSRV and cargo deny.
  • Nightly: random proptest seeds, and the work-counter regression on the synthetic models (tools/bench/work-baseline.json).

Test models are built in code, or kept small in tools/mcnp-oracle/models. The reference model (425 k cells, not in git) runs in --ignored tests and benchmarks. Synthetic models of other shapes (tokamak sectors, a lattice core, a sparse world, bricks, torus shells) keep tuning from fitting one model family.

Roadmap

  • Engine.
  • Volumes per voxel of a mesh.
  • Faster fillers (level 1 now dominates the reference model).
  • Cheaper volume convergence: --rel-sigma down to the default --h-min (h / 64) on the reference model would take about two hours, nearly all of it tracing pieces of groups that never converge.
  • CPU first hits in sparse worlds (sparse.i) are slower than full traces of the same rays, from the doubling windows across a 5 km world.
  • Dedicated tests for tangent lines and near-coincident surfaces.
  • Viewer.
  • Numeric fields for surface and TR coefficients in the card editor.
  • Its visual design.
  • Hiding and selecting by instance and by value.
  • Pins hidden behind geometry drawn faded.
  • Downstream.
  • Comparing two versions of a model: segments traced on shared lines, only where fingerprints differ.
  • A stable identity for envelopes across conversions, from $ tags.
  • Later. A browser plotter (WebGPU, or the engine in WebAssembly).

Open questions:

  • Fingerprint stability across two real conversions of the same envelope.
  • The tolerance for "surface noise" (surfaces moved by ~1e-5 cm by a new conversion).
  • Whether the reference model's overlaps are real defects. llevant check --h 5 finds 1 086 overlap labels (0.6 m³); an MCNP check of a few points would settle it.