llevant 0.1.3

Fast MCNP constructive solid geometry engine
Documentation

Fast, exact geometry queries on MCNP models: an interactive viewer, a command line and a Python module, on a Rust engine. llevant answers:

  • where points are, and what lines cross;
  • slices and 3D views;
  • volumes, and the gaps and overlaps of a model;
  • fingerprints that tell two versions of a model apart;
  • tally results (meshtal, MCTAL, per cell) drawn over the geometry.

It reads the MCNP input (through migjorn), with every surface and macrobody, universes at any depth, lattices and transforms.

Documentation: https://fusion4energy.github.io/llevant/: install, a ten-minute tour, how-to guides and references.

The viewer: a reactor core cut open in 3D

Results over the geometry (mock pin powers) A check finds the lid overlapping the cask
Pin powers drawn over the core in 3D and in a slice The Check workspace listing two overlaps, hatched in the slice

The models are in docs/examples.

Install

pip install llevant          # Python 3.9+: the module, the `llevant` command and the viewer

Windows and Linux (x86-64). The releases also have the llevant and llevant-viewer programs to download, and cargo install llevant-cli --features gpu,viewer builds them from source. Details, and what your computer needs: Install.

Try it

docs/examples/cask.i is a small model to try (a cask of fuel pins on a concrete floor); Getting started walks through it.

llevant info   cask.i                          # sizes, extent, diagnostics
llevant locate cask.i 0 0 100  80 0 100        # cell path, material, density of each point
llevant slice  cask.i --plane z=100 --colour material -o slice.png
llevant render cask.i --hide 5 --clip 0,0,0,0,-1,0 --colour realistic -o view.png
llevant check  cask.i --h 2                    # exit status 1 if gaps or overlaps
llevant view   cask.i                          # the viewer (or: llevant-viewer cask.i)

With pip, llevant is python -m llevant. From Python:

import llevant

m = llevant.load("cask.i")             # compiled once, cached on disk
m.locate(0, 0, 100)                    # <Label inside 4 > 30[0,0,0] > 41>
m.classify(points)                     # (N, 3) numpy array -> numpy columns
m.slice(z=100, colour="material")      # an image, shown inline in Jupyter
m.volumes(h=2).by("material")          # volumes with their uncertainty
m.check(h=2)                           # gaps and overlaps

How fast

On a 425 k-cell fusion reactor model, on a 16-thread laptop (docs/benchmarks.md):

Load 1.3 s from the cache (36 s to compile the first time)
Points 5.4 million classified per second
Lines 3.3·10⁵ lines of 100 cm traced per second
Slices 110 ms for 1000 rows
Gaps and overlaps the 36 × 37 × 35 m building checked on lines 5 cm apart in under 3 minutes
Viewer 60 fps while orbiting (GPU)

What it does

Query Command Library
Where points are: cell path, material, density; gaps, overlaps, on-surface locate Model::classify
What lines cross: exact segments, the surface at each end trace (--lines for a file of them) Model::trace
2D slices with exact boundaries, cell and surface labels slice Model::slice, llevant_render::labels
3D views: hidden cells, cutaways, universe levels, ghost shells render (--gpu) Model::render, Model::first_hits, llevant-gpu
Realistic images: materials sorted by composition, physically based shading render --colour realistic, materials llevant_scene::materials, llevant_render::shading
Volumes by cell, material, universe or tally bin, with an honest uncertainty volume Model::volumes, volumes_to, instance_volumes
Gaps and overlaps, with volume and location check Volumes::problems
Fingerprints of cells and universes; model diffs fingerprint Model::fingerprints
A universe (a filler) as a model of its own --universe Model::universe
Cell instances: each place a cell occupies, numbered locate Model::instances
Results over the geometry: values per cell, instance or mesh voxel (CSV, meshtal, MCTAL, D1SUNED cuvmsh) slice/render --field llevant_scene::field
An interactive viewer: 3D view and slice, picking, rules, cuts, fields, FMESH layout, card editing llevant-viewer, llevant view crates/llevant-viewer
Python: models kept in memory, numpy batch queries, inline images, the viewer python -m llevant crates/llevant-py

What MCNP input is read, and what is not: Supported input.

Library

use llevant::{Depth, Line, Model, Options, Status, DEFAULT_PRECISION};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Model::load("model.mcnp", &Options::default(), None)?;
    let res = model.classify(&[[0.0, 0.0, 0.0], [120.0, -3.5, 40.0]], Depth::All);
    for &id in &res.ids {
        let label = &res.labels[id as usize];
        println!("{}", model.describe(label)); // e.g. "inside 12 > 304[1,-2,0] > 7"
        if label.status == Status::Inside {
            let cell = model.cell(label.cell().unwrap());
            println!("cell {} material {} density {}", cell.id, cell.material, cell.density);
        }
    }

    let line = Line::between([-100.0, 0.0, 0.0], [100.0, 0.0, 0.0]);
    let tr = model.trace(&[line], Depth::All)?;
    for k in tr.segments(0) {
        let out = model.surface_id(tr.surface_out[k]); // MCNP surface (and facet), if any
        let label = &tr.labels[tr.ids[k] as usize];
        println!("{} .. {}: {} -> {out:?}", tr.t0[k], tr.t1[k], model.describe(label));
    }

    let fp = model.fingerprints(DEFAULT_PRECISION)?; // fp.cells[i].geometry, fp.units[u].content
    println!("{} cells fingerprinted", fp.cells.len());
    Ok(())
}
  • Batches. Queries take batches and return flat arrays, ready for numpy: one label id per point or segment, with the labels interned.
  • Indices and numbers. Labels refer to cells by index into model.cells(); describe, cell_id and surface_id give MCNP numbers.
  • Determinism. Results are identical for any number of threads.
  • Errors. Bad arguments are an Error, never a panic.

The API is on docs.rs (views, volumes and images included), and docs/contracts.md lists what each query guarantees.

Layout

Path Purpose
crates/llevant The engine (pure Rust, geometry only)
crates/llevant-scene What frontends build from a model: cell rules, hidden cells, material looks, field data and tally files, the input's cards, the cache of compiled models
crates/llevant-render Images: colours, colour scales, field looks, physically based shading, labels, PNG
crates/llevant-gpu The GPU renderer (wgpu)
crates/llevant-viewer The llevant-viewer desktop app and its egui widgets
crates/llevant-cli The llevant command
crates/llevant-py The Python module llevant (PyO3, abi3 wheels)
tools/bench llevant-bench: benchmarks, checks against brute force and of the GPU against the CPU
tools/mcnp-oracle Checks llevant against MCNP itself
tools/synthetic Generators of benchmark models
docs/ The documentation site's pages: user guides, and for developers the architecture, contracts, decisions, benchmarks and internals

Develop

docs/CONTRIBUTING.md has the commands, the rules and how to check against MCNP.

cargo test --release                       # unit, MCNP golden, property and CLI tests
cargo test --release -p llevant-gpu -p llevant-viewer   # GPU renderer and viewer (skip without an adapter)
cargo run --release -p llevant-bench       # benchmarks and checks: every command

Licence: EUPL-1.2.