migjorn 0.2.5

A fast, lossless MCNP input parser with whole-geometry editing.

migjorn (Python)

Fast, lossless MCNP input parsing with whole-geometry editing, backed by a Rust core.

Run the examples with uv (no manual build)

uv builds the Rust extension for you. From the repository root:

# Showcase notebook (interactive) — a tour of the whole API. The [notebook]
# extra pulls in jupyterlab/ipykernel/nbconvert:
uv run --with "./crates/migjorn-py[notebook]" \
  jupyter lab crates/migjorn-py/examples/showcase.ipynb

# Notebook (execute headless, refresh outputs in place):
uv run --with "./crates/migjorn-py[notebook]" \
  jupyter nbconvert --to notebook --execute --inplace \
  crates/migjorn-py/examples/showcase.ipynb

# Universe split/merge example (a PEP 723 script — carries its own deps):
uv run crates/migjorn-py/examples/universe_compose.py

uv run compiles the extension via maturin into an isolated environment automatically.

Rebuild gotcha. uv keys its build cache on crates/migjorn-py alone, so edits to the Rust core (crates/migjorn/) do not invalidate it — you can silently keep running an old extension. Neither --refresh nor uv cache clean migjorn helps. Force a rebuild with:

rm -rf ~/.cache/uv/archive-v0 ~/.cache/uv/sdists-v9

Also delete any stale python/migjorn/_migjorn.abi3.so left by an earlier maturin develop: it lives in the packaged python-source dir and shadows freshly built extensions.

Because of this, local test runs use a persistent venv + explicit maturin develop instead — see Development (persistent venv) below.

Use in an IDE (VS Code / Jupyter kernel)

To run the notebook against a persistent, selectable interpreter (rather than uv's ephemeral uv run environments), create a .venv that contains both migjorn and ipykernel. From this directory (crates/migjorn-py):

uv sync --no-editable --extra notebook

This builds the extension and installs the notebook stack (jupyterlab, ipykernel, nbconvert) into crates/migjorn-py/.venv. Then, in your IDE, select the kernel / interpreter:

crates/migjorn-py/.venv/Scripts/python.exe      # Windows
crates/migjorn-py/.venv/bin/python              # macOS / Linux

A kernel without ipykernel (e.g. a bare uv venv, or uv sync without --extra notebook) will fail to start for the notebook — that missing package is the usual cause. After changing the Rust code, re-run uv sync --no-editable --extra notebook (or maturin develop) to rebuild.

Why --no-editable? An editable install points a .pth at the external python/ source dir; Pylance often won't follow that to find the stubs, so you get no autocomplete/typing. A non-editable install places migjorn/__init__.pyi and py.typed physically in site-packages, which every type checker resolves. (Trade-off: after editing the code you must re-sync to pick up changes.)

Development (persistent venv)

This is the reliable path for the local edit/test loop — maturin develop calls cargo build directly, so, unlike uv run --with ./crates/migjorn-py, it can't serve a stale extension after a Rust-core change.

pip install maturin pytest
cd crates/migjorn-py
maturin develop --release
pytest tests -q

Re-run maturin develop --release before pytest every time — pytest alone won't pick up new Rust code, only a fresh maturin develop does.

To build a wheel: maturin build --release (produces an abi3 wheel that works on CPython 3.9+).

To build a Windows wheel on Linux, use maturin build --release --target x86_64-pc-windows-msvc -m crates/migjorn-py/Cargo.toml -i python3.12.

Quick start

import migjorn

model = migjorn.parse(open("model.mcnp").read())
# or: model = migjorn.Model.from_file("model.mcnp")

print(model)                      # Model(cells=..., surfaces=..., ...)
print(model.num_cells, model.num_surfaces)

# Look up by number (fast; uses an id index).
s = model.surface(113)
print(s.id, s.kind, s.coeffs)    # 113 'PX' [-10.0]

c = model.cell(800)
print(c.material, c.density, c.signed_surfaces)

# --- In-place value edits (write straight through, lossless elsewhere) ------
c.material = 124                  # replace the material
c.density  = -7.93               # replace the density

# Assigning a material to a *void* cell just works: it gains a placeholder
# density of 0.0 (never raises, so it's safe in a loop). Set the real density
# next; assigning material 0 makes the cell void again and drops the density.
void = model.cell(2)
void.material = 5                    # 5 0 ...   (placeholder density 0.0)
void.density  = -2.0                # 5 -2.0 ...
void.material = 0                    # 0 ...     (void again, density dropped)

# Diagnostics (empty on a clean parse).
for d in model.diagnostics:
    print(d.severity, d.message)

# --- Whole-geometry renumbering -------------------------------------------
# Definitions AND every reference are updated consistently.

model.offset_surfaces(1_000_000)          # fast: shift all surface numbers
model.renumber_cells(lambda n: n + 500)   # callable: once per distinct cell id
model.renumber_surfaces({1: 100, 2: 200}) # or an explicit dict

# Lossless re-emission: only edited numbers change; comments/spacing preserved.
model.save("model_renumbered.mcnp")
text = str(model)                         # or model.to_source()

Type checking / IDE support

The package is typed (PEP 561): the compiled extension is the private migjorn._migjorn submodule, wrapped by the migjorn package which ships type stubs (python/migjorn/__init__.pyi) and a py.typed marker. Pylance, pyright, and mypy pick these up automatically once the wheel is installed — no more "unknown import"/"untyped" warnings. When you change the bindings in src/lib.rs, update python/migjorn/__init__.pyi to match.

Notes

• model.cells / model.surfaces / model.materials / model.transforms / model.data_cards return full lists. For very large models prefer the id lookups (model.cell(id), model.surface(id)) and the num_* counts.
• Everything is documented inline: help(migjorn.Model), help(migjorn.Surface).