NATF: Nuclear Analysis Toolkit Framework

Introduction

NATF (Nuclear Analysis Toolkit for Fusion) is a computational framework developed for automating nuclear analysis workflows using MCNP and FISPACT-II. Starting with the 4.x roadmap it also exposes reusable helpers for OpenMC model generation (natf.openmc_input), CAD-to-OpenMC conversion pipelines (natf.cad_utils), statepoint post-processing (natf.openmc_output) and the brand-new OpenMC→FISPACT bridge (natf.coupling.openmc_fispact, see docs/openmc_coupling.md). Key features include:

• Activation Analysis (CELL_ACT): Material activation calculations with pre-processing/post-processing automation
  
• Displacement Damage (CELL_DPA): DPA (Displacements Per Atom) predictions for radiation damage studies
  
• Coolant Activation (COOLANT_ACT): Analysis of coolant systems' radioactive inventory
  

Supported code versions: MCNP5 (1.2-1.6), MCNP6 (6.1-6.2), FISPACT-II 3.0+. Source code available at github.com/zxkjack123/NATF. A task-by-task view of the NATF-01 → NATF-10 upgrade roadmap lives in docs/natf_upgrade_status.md.

Installation Guide

System Requirements

• OS: Linux (Ubuntu 22.04+/CentOS 8+ recommended)
• Python: 3.10+ (3.10 is the minimum supported version)
• Prerequisites: See pinned dependencies in pyproject.toml (numpy/pandas/etc.)

Installation Methods

1. PyPI Installation (Stable Releases):

pip install natf --user  # Install as user package

Verify installation:

natf_run --version  # Expected output: NATF version: x.x.x

2. Source Compilation (Development Version):

git clone -b develop https://github.com/zxkjack123/NATF.git
cd NATF
python setup.py install --user  # Install in user space

# Configure PATH (Linux)
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Optional Extras

• pip install natf[dev] – add lint/test tooling (already used by make venv).
• pip install natf[openmc] – install the OpenMC Python API so that natf.openmc_input, natf.openmc_output 与 natf.coupling.openmc_fispact 可以直接在本地运行。 Refer to docs/openmc_coupling.md for configuration schema examples and the OpenMC→FISPACT workflow.
• pip install natf[cad] – pull in CAD_to_OpenMC + CadQuery + gmsh so natf.cad_utils can convert STEP assemblies into DAGMC .h5m files before feeding them to OpenMC.

Getting Started

Basic Configuration

Create config.ini:

[general]
aim = CELL_ACT_PRE        # Analysis objective
work_dir = ./natf_run       # Working directory

[mcnp]
mcnp_input = mcnp.inp   # MCNP input file
mcnp_ptrac = ptrac_file    # Particle track data

[fispact]
material_list = mat_list  # Material specifications
irradiation = scenarios.txt  # Irradiation history

Execute Analysis

# Run activation post-processing
natf_run --input config.ini  # Load configuration

Validate Installation

Run test suite (development environment):

# Create & activate virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# Run all tests with coverage
./.venv/bin/pytest -q

# Or a single test module
./.venv/bin/pytest tests/test_france_standard.py::test_france_basic_metadata -q

Note: test discovery is configured via pyproject.toml to use the tests directory. Ensure you invoke the venv's pytest binary so dependency versions match those pinned in pyproject.toml.

OpenMC→FISPACT quick start

from natf.coupling.openmc_fispact import export_statepoint_flux_to_fispact

artifacts = export_statepoint_flux_to_fispact(
	statepoint_path="runs/statepoint.200.h5",
	tally_id=1,
	group_structure=709,
	output_dir="build/fispact",
	fispact_data_dir="/opt/fispact/libraries",
)
print("FLX file:", artifacts["flux_file"])
print("FILES file:", artifacts["files_file"])

The helper collapses OpenMC flux tallies onto standard FISPACT energy groups, writes the .flx spectrum (compatible with legacy MCNP workflows), and renders a ready-to-use FILES control deck with your library paths.

Need a full example? examples/openmc_coupling/run_workflow.py now glues the sample INI/JSON into a one-click workflow (python run_workflow.py --cross-sections /path/to/cross_sections.xml) and doubles as the NATF-10 integration smoke test via --dry-run --fake-openmc.

Engine selection & CLI workflow

Starting with NATF-09 the natf_run entry point (and the experimental natf run subcommand) accept a new engine switch so you can choose between the classic MCNP pipeline and the OpenMC workflow orchestrated by natf.openmc_engine.

[general]
aim = OPENMC_INPUT            # Aim is ignored for engine=openmc but kept for compatibility
engine = openmc               # default is mcnp
work_dir = ./openmc_case

[openmc]
config_json = configs/case.json   # OpenMCInputBuilder schema (see docs/openmc_coupling.md)
output_dir = build/openmc_xml     # where materials.xml/geometry.xml/settings.xml land
cross_sections = /opt/openmc/cross_sections.xml

# Optional flux export into FISPACT files
statepoint = runs/statepoint.200.h5
group_structure = 709
flux_output_dir = build/fispact_flux
fispact_data_dir = /opt/fispact/data
files_template = natf/data/fispact_files/FILES-175

• natf_run -i config.ini --engine openmc (or natf run -i config.ini --engine openmc) forces the OpenMC backend regardless of the value in [general].
• When engine = openmc, NATF reads the [openmc] section via OpenMCEngineConfig and performs three phases: cross-section validation, XML export through OpenMCInputBuilder, and (optionally) flux collapsing to produce .flx/FILES artifacts.
• Flux export is activated when all of statepoint, group_structure, flux_output_dir, and fispact_data_dir are provided; other knobs such as tally_id, tally_name, files_filename, or JSON-formatted extra_files_tokens mirror the arguments on export_statepoint_flux_to_fispact.
• The OpenMC dependency remains optional. Install it with pip install natf[openmc] before running the new engine or keep using the default MCNP workflow with no extra packages.

The legacy MCNP aims (CELL_ACT_PRE, CELL_DPA_POST, …) continue to work unchanged; you can upgrade existing pipelines incrementally by adding the [openmc] block to new configs while leaving established files untouched.

Cooling-only decay planner (experimental)

The unified CLI also includes a small cooling-only decay helper for planning activity (and optional decay heat when available) over time without running FISPACT.

Two modes are supported:

• Single nuclide / linear chain mode (--nuclide + --a0): compute decay along a user-specified 1→2→… chain.
• Inventory mode (--inventory-json): evolve a user-provided activity inventory where each nuclide decays independently (no daughter ingrowth).

Examples:

# Single nuclide (uses built-in half-life table when available)
natf decay -n Co60 --a0 1e12 -t 0 1d 7d 1y --json

# Inventory JSON (nuclide -> activity in Bq)
natf decay --inventory-json inventory.json -t 0 1d 30d 1y --json

# Provide half-life overrides explicitly (seconds)
natf decay --inventory-json inventory.json -t 0 1d 30d --half-lives 1.662e8 9.08e8 --json

Notes and limitations:

• The built-in half-life / decay-energy tables in natf.decay are currently minimal (intended for tests and small planning tasks). For nuclides not in the table, you should pass --half-lives.
• Inventory mode does not model daughter ingrowth; use chain mode for a simple linear ingrowth chain.
• Full activation/decay inventories driven by evaluated nuclear data are still handled by the standard MCNP/OpenMC→FISPACT workflows (which read external libraries via FISPACT_DATA_DIR).

NATF v4.0 upgrade tracker

To see how the project-level plan (pm/natf_upgrade_plan.md) maps to the repository, read docs/natf_upgrade_status.md. It lists each NATF-0x milestone, the corresponding modules/docs/tests, and their completion status so you can quickly verify that the OpenMC and FISPACT enhancements are in place.

Unified CLI (experimental)

An experimental unified command line entry point natf has been added (in addition to legacy scripts like natf_run).

List available subcommands:

natf --help

The run subcommand is a thin wrapper around natf_run. Any flags you pass are forwarded verbatim, which means the following two invocations are equivalent and covered by the new NATF-09 regression tests:

natf run -i config_openmc.ini --engine openmc
natf_run --input config_openmc.ini --engine openmc

Pick whichever entrypoint best fits your scripting style; both now share the same code path and validation logic.

Command Line Interface

Usage:

natf fingerprint --log-level DEBUG

Logging Configuration

You can set the log verbosity either via the --log-level argument or the environment variable NATF_LOG_LEVEL. The environment variable (if set) overrides the CLI flag.

Examples:

export NATF_LOG_LEVEL=DEBUG
natf fingerprint

NATF_LOG_LEVEL=WARNING natf fingerprint --log-level INFO  # yields WARNING because env wins

Show version and provenance metadata hash:

natf version
natf metadata

More operational subcommands (radwaste export, activation HDF5 write) will land in upcoming releases. For now this interface is a stable preview layer; underlying APIs may evolve.

Development Workflow

The repository ships with a Makefile that automatically creates and uses a local .venv without requiring you to manually source it each time.

Quick Start

make venv          # create .venv and install editable package + dev deps
make test          # run test suite quietly
make lint          # ruff lint
make format        # ruff format

Common Targets

You never need to activate the environment explicitly; every Make target invokes the tools via .venv/bin/... paths.

Rebuilding from Scratch

make clean-venv
make venv

Using Tools Manually

If you still want manual invocation without activation:

.venv/bin/python -m pytest -q
.venv/bin/ruff check .

Pinning Python Version

The file .python-version (value 3.11) is included to cooperate with tools like pyenv or asdf so that the same interpreter is used during development and CI.