<p align="center">
<img src="docs/img/logo.png" alt="" width="110">
</p>
<h1 align="center">llevant</h1>
<p align="center">
<a href="https://github.com/Fusion4Energy/llevant/actions/workflows/ci.yml"><img src="https://github.com/Fusion4Energy/llevant/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
<a href="https://pypi.org/project/llevant/"><img src="https://img.shields.io/pypi/v/llevant" alt="PyPI"></a>
<a href="https://crates.io/crates/llevant"><img src="https://img.shields.io/crates/v/llevant" alt="crates.io"></a>
<a href="https://fusion4energy.github.io/llevant/"><img src="https://img.shields.io/badge/docs-fusion4energy.github.io%2Fllevant-blue" alt="Documentation"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-EUPL--1.2-blue" alt="License: EUPL-1.2"></a>
</p>
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](https://crates.io/crates/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 models are in [`docs/examples`](docs/examples).
## Install
```sh
pip install llevant # Python 3.9+: the module, the `llevant` command and the viewer
```
Windows and Linux (x86-64). The [releases](https://github.com/Fusion4Energy/llevant/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](https://fusion4energy.github.io/llevant/install/).
## Try it
[`docs/examples/cask.i`](docs/examples/cask.i) is a small model to try (a cask of fuel
pins on a concrete floor); [Getting started](https://fusion4energy.github.io/llevant/getting-started/)
walks through it.
```sh
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:
```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`](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
| 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](https://fusion4energy.github.io/llevant/reference/supported-input/).
## Library
```rust,no_run
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](https://docs.rs/llevant) (views, volumes and images included),
and [`docs/contracts.md`](docs/contracts.md) lists what each query guarantees.
## Layout
| `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](docs/architecture.md), [contracts](docs/contracts.md), [decisions](docs/decisions/README.md), [benchmarks](docs/benchmarks.md) and [internals](docs/internals/engine.md) |
## Develop
[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) has the commands, the rules and how to
check against MCNP.
```sh
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](LICENSE).