Metadata-Version: 2.4
Name: natf
Version: 4.0.2
Summary: Nuclear Analysis Toolkit for Fusion (MCNP + FISPACT automation)
Home-page: https://github.com/zxkjack123/NATF
Author: Xiaokang Zhang
Author-email: Xiaokang Zhang <zxkjack123@163.com>
License: MIT License
        
        Copyright (c) 2025 Xiaokang Zhang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib==3.9.1
Requires-Dist: msgpack>=1.2.1
Requires-Dist: ndindex==1.8
Requires-Dist: numexpr==2.10.1
Requires-Dist: numpy==1.26.4
Requires-Dist: pandas==2.2.2
Requires-Dist: pillow>=12.3.0
Requires-Dist: progress==1.6
Requires-Dist: pypact==1.3.7
Requires-Dist: seaborn==0.13.2
Requires-Dist: six==1.16.0
Requires-Dist: tables==3.9.2
Requires-Dist: pydantic<3,>=1.10
Requires-Dist: h5py>=3.11.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Provides-Extra: openmc
Requires-Dist: openmc>=0.14.0; extra == "openmc"
Provides-Extra: cad
Requires-Dist: CAD_to_OpenMC>=1.0.1; extra == "cad"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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`](docs/openmc_coupling.md)). Key features include:

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

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](https://github.com/zxkjack123/NATF). A task-by-task view of the NATF-01 → NATF-10 upgrade roadmap lives in [`docs/natf_upgrade_status.md`](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):**
```bash
pip install natf --user  # Install as user package
```
Verify installation:
```bash
natf_run --version  # Expected output: NATF version: x.x.x
```

**2. Source Compilation (Development Version):**
```bash
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`](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`:
```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
```bash
# Run activation post-processing
natf_run --input config.ini  # Load configuration
```

### Validate Installation
Run test suite (development environment):
```bash
# 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

```python
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`.

```ini
[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:

```bash
# 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`](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:

```bash
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:

```bash
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:

```bash
export NATF_LOG_LEVEL=DEBUG
natf fingerprint
```

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

Show version and provenance metadata hash:

```bash
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
```bash
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
| Target                    | Purpose                                                  |
| ------------------------- | -------------------------------------------------------- |
| `make venv`               | Create / update virtual environment and install `.[dev]` |
| `make lint`               | Run `ruff check .`                                       |
| `make lint-fix`           | Run `ruff check --fix .`                                 |
| `make format`             | Apply `ruff format`                                      |
| `make format-check`       | Verify formatting                                        |
| `make test`               | Run pytest (short output)                                |
| `make pre-commit`         | Run all pre-commit hooks                                 |
| `make install-pre-commit` | Install git hooks locally                                |
| `make clean-venv`         | Remove the `.venv` to rebuild cleanly                    |
| `make which-python`       | Show interpreter path & version used                     |

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

### Rebuilding from Scratch
```bash
make clean-venv
make venv
```

### Using Tools Manually
If you still want manual invocation without activation:
```bash
.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.
