Welcome to ACTINV

ACTINV calculates which nuclides a material contains during irradiation and cooling. Supply a material composition, a particle-flux spectrum, a schedule, and evaluated nuclear data. ACTINV calculates inventories, activity, decay heat, and requested source terms and responses.

This handbook covers ACTINV 1.3.1 and nuclear-data catalog 1.1.0. The downloadable desktop preview has a separate release history; check its solver version before using a feature described here.

The reference also includes additions on current master. Gas production, transport-tally error propagation, and impurity budgets are currently unreleased; Versions and releases distinguishes them from the installed packages.

Choose how to work

The browser prepares inputs and displays results. Run calculations in the desktop, CLI, or Python interface.

Start with one material

Install ACTINV, then follow Your first calculation to run the supplied iron example. You do not need a source checkout. The example supplies a complete spectrum so you can concentrate on the material, schedule, and results.

Once it runs, use Describe a problem to adapt it to your own inputs and Read your results to interpret the output. Keep the specification reference nearby when enabling optional features.

Understand the calculation boundary

ACTINV is an activation and inventory solver. A transport calculation or measurement supplies its particle spectrum; separate transport tools handle spatial shielding and dose transport. Missing evaluated data and incomplete responses appear in the result’s ledger.

ACTINV is research-grade software. Its validation evidence does not approve a calculation for licensing, safety, waste classification, or regulatory use. Read Scope and qualification and Known data limitations when assessing a calculation’s applicability.

Find help

Use the search button or press / to search this handbook. Troubleshooting covers common setup and input errors. Report reproducible software problems through GitHub issues, including your version, command, and error message.

Install ACTINV

Choose the desktop for a graphical workflow, or install the CLI and Python package for scripts and notebooks. Nuclear data are installed separately.

Desktop

Open the ACTINV download page and choose the package for your computer. No Rust or Python installation is required.

The published 0.1.0-preview.1 desktop is unsigned and uses solver 1.0.1. The CLI/Python software release is 1.3.1; features added afterward require a newer desktop build or the current CLI/Python package. Download filenames identify the desktop version and architecture.

For platform launch notices and the optional Linux application-menu shortcut, see the desktop installation details. Use the desktop walkthrough for calculation setup.

CLI and Python

On Python 3.9 or newer, install both import actinv and the actinv terminal command:

python -m pip install actinv
actinv --version

Supported platforms have prebuilt wheels. If a matching wheel is unavailable, pip may attempt a source build; use a standalone executable if you want to avoid setting up a compiler.

For a reproducible installation of this handbook’s software version:

python -m pip install actinv==1.3.1

If you already use Rust, install just the CLI from crates.io:

cargo install --locked actinv-cli --version 1.3.1

The Python package and cargo install actinv-cli install the terminal interface. Get the desktop from the download page.

Install the nuclear data

Choose a working folder for your problems and run:

actinv data fetch
actinv data verify

The default neutron bundle downloads about 79 MiB and installs about 170 MiB in actinv-data/v1.1.0/ inside that folder. The first calculation creates a separate prepared-data cache. Data setup explains custom locations, other particles, covariance bundles, and offline installation.

Continue with Your first calculation.

Your first calculation

Run the supplied iron example from a terminal. This example models a five-minute irradiation followed by cooling and includes the complete measured flux-spectrum shape. You do not need to clone the repository or type a 709-group vector.

1. Prepare a working folder

After installing ACTINV, create and enter an empty folder for this calculation:

mkdir actinv-example
cd actinv-example
actinv --version

2. Install data and create the problem

actinv data fetch
actinv new problem.json

new writes a complete, editable problem and refuses to overwrite an existing file. Its default data references use catalog IDs so the problem can be used on another machine with the same installed data.

3. Validate and run

actinv validate problem.json
actinv validate problem.json --hashes
actinv run problem.json result.json

The first validation checks the JSON specification. --hashes also checks the files it supports and their declared hashes; the solver checks evaluated-data compatibility during the run. A successful run writes the complete result to result.json.

The first run prepares data and can take longer than subsequent runs. If setup fails, run actinv doctor problem.json and follow Troubleshooting.

4. Inspect the final step

If you installed the Python package, inspect the JSON with:

import json
from pathlib import Path

result = json.loads(Path("result.json").read_text(encoding="utf-8"))
last = result["steps"][-1]
print("Time (s):", last["t_s"])
print("Activity (Bq/g):", sum(last["activity_Bq_per_g"].values()))
print("Decay heat (W/g):", last["heat_W_per_g"]["total"])
print("Data and calculation notes:", result["ledger"])

You can also open the result in the browser workbench to explore plots. Read your results explains the units, time steps, and diagnostic fields.

5. Adapt the example

Open problem.json in a text editor. Change the title, material composition, or schedule, then validate and run again with a new output filename. Reuse the supplied spectrum only when it represents your intended irradiation; changing the material does not make that spectrum appropriate for a different facility.

Use Describe a problem for input conventions. The measured iron case provides a fuller comparison against experimental decay-heat measurements.

Use the desktop

The desktop edits a single-material problem, runs the shared ACTINV solver in the background, and displays inventories, activity, heat, photon spectra, and pathways.

Install it from the download page. Published preview packages and current source builds can expose different features; see Versions and releases.

Learn without downloading nuclear data

In Overview & data, choose Try offline results tutorial. It shows a fictional one-hour decay example for learning the interface. Use the iron problem with verified data for an evaluated calculation.

Run a problem

1. In Overview & data, keep the iron example or choose Open problem.
2. Choose your installed activation and decay files, or download the standard neutron data and apply the installed paths.
3. Check Input base. Relative file paths use this folder. Opening a JSON problem sets the base to its directory; older repository examples may need the repository root.
4. Review Material, Irradiation & cooling, and Spectrum. A zero schedule multiplier means cooling. Spectrum values are integrated group fluxes, with explicit ordering and normalization.
5. Choose optional outputs in Calculation options & requested outputs. Apply or discard advanced JSON edits before returning to structured editing.
6. Choose Validate, then Run. The background task reports preparation and solving. In current builds, cancelling a calculation stops its isolated worker without publishing a partial result.

The current desktop uses a private prepared-data cache for each calculation, so setup time can recur between runs. CLI cache behavior is described in Data setup.

Explore and save results

In Results, choose activity, heat, or inventory, then select a computed time step. Filter and select a nuclide to follow its history. Heat remains the whole-material response. Add another result for a comparison; check both files’ physical times and normalizations.

Open Spectra & pathways for optional source information and Ledger & certificate for incomplete inputs and calculation details. Export the full result JSON to preserve the complete calculation. Inventory CSV contains the selected time step; saving the problem or exporting CSV does not save the full result.

Guided help

Choose Help or press F1 for setup and result walkthroughs. Use Back, Next, or Exit, and press Escape to close a tour. Ctrl/Cmd+O opens a problem and Ctrl/Cmd+S saves it.

Mesh runs, bulk library building, and transport-source exports use the CLI. Read Results for interpretation and Troubleshooting for input problems.

Use the browser workbench

Open ACTINV in your browser to learn the interface, edit a problem, or inspect result files without installation. A laptop or desktop with WebGL enabled works best.

Explore results

Choose Try the results tutorial for a fictional one-hour decay example. Switch between activity, heat, and inventory and select a nuclide to follow its history.

For a real calculation, open or drop a result JSON produced by ACTINV. Use Compare result to overlay a second file. Plots use each result’s recorded time and normalization; the browser does not rescale results to make them comparable.

Photon sources and diagnostics appear under Result record when the file contains them. An inventory CSV export contains the selected time step. A result JSON download retains the complete imported result.

Edit a problem

Open Problem, edit the iron example or load your own JSON, then download the problem. Open that file in the desktop or run it with the CLI/Python interface.

The browser checks the specification. It does not run the activation solver, download nuclear-data libraries, or import transport tallies. Local data paths are preserved for the installed application to resolve.

Keep your edits

Files are read on your device and are not uploaded. Download edits before closing or reloading the tab; the workbench does not retain them between visits. Open one file at a time, up to 32 MiB.

Continue with Your first calculation when you are ready to run the solver.

Describe a problem

An actinv-spec-1 JSON problem contains data references, a material, a spectrum, and a schedule. The CLI, desktop, and Python interface use the same contract. Start with actinv new problem.json and edit that complete example.

Unknown fields are errors. Numbers must be finite; misspelt options are rejected instead of being ignored. See Problem specification for the full field reference.

Material

This fragment describes one gram of an iron/chromium mixture:

"material": {
  "mass_g": 1.0,
  "basis": "wt_percent",
  "composition": {"Fe": 90.0, "Cr": 10.0}
}

Composition keys may be natural elements such as Fe or explicit nuclides such as Fe56 and Ba137m1. A natural element and one of its explicit isotopes cannot appear in the same composition. Use explicit nuclides for elements without tabulated natural abundances.

Inventory, activity, and heat are reported per gram. mass_g scales total photon source quantities; it does not turn heat_W_per_g into total watts.

Spectrum

flux_per_group holds group-integrated flux in particles cm⁻² s⁻¹. It is not a spectral density per eV. The ordinary neutron library uses fispact-709 with 709 values. Standard proton, deuteron, and alpha libraries use fispact-162 with 162 values and temperature_K: 0.

descending: true means the values are supplied from highest energy to lowest. When total is present, ACTINV scales the vector to that total while preserving its shape. A positive total with an all-zero vector is rejected.

Custom spectra require increasing energy boundaries, one more boundary than group values, and a compatible activation library. The projectile, temperature, and group structure must match the library. Use transport import for supported transport tallies and review the source-rate normalization.

Irradiation and cooling

This fragment irradiates for five minutes and then cools for one hour:

"schedule": [
  {"dt": "5 min", "flux": 1.0},
  {"dt": "1 h", "flux": 0.0}
]

Each duration is incremental. The final time above is 3,900 seconds from the start, including the irradiation. flux multiplies the chosen spectrum; zero means cooling. Add separate cooling steps for the times you want reported.

Single-problem schedules can supply a per-step spectrum with the same group structure and count. Optional feed gives atoms s⁻¹ g⁻¹ and removal gives first-order rates in s⁻¹; these are described in the specification reference.

Data paths

Catalog references such as catalog:tendl-2025-neutron-709g resolve against ACTINV_DATA_DIR, or ./actinv-data by default. actinv new uses these references unless you supply --data-dir.

Literal relative paths in CLI problems use the current working directory. Desktop problems use Input base. Python Problem.from_file uses the problem’s directory; plain Python mappings use the current directory. JSON does not expand ~ to your home directory.

Use actinv doctor problem.json to inspect setup, then validate and run as shown in Your first calculation.

Read your results

actinv run problem.json result.json saves one JSON document with every computed step, calculation diagnostics, and the input certificate. Keep that file alongside the problem and selected data.

Time steps and units

Each entry in steps reports the end of a schedule segment. step is one-based; t_s is cumulative seconds from the start, including irradiation and cooling.

For a sample of known mass in grams, multiply the per-gram activity or heat by that mass to obtain Bq or W. Check that the composition and its basis describe the material you intend.

total_atoms_per_g is an accounting diagnostic across the solver state vector. It includes sinks and, where present, a unit source state. Use the per-nuclide inventory for physical nuclide populations.

Optional results

Photon sources, dose-response quantities, pathways, uncertainty, radiological responses, and damage observables depend on the requested options and required data. An absent field means that output was not emitted; it is not a zero result.

Photon group values represent source strength integrated over each energy group. Contact gamma dose is a semi-infinite-slab screening proxy; use separate transport for geometry-dependent dose. Radiological indices use your selected coefficient table. NRT dpa uses the supplied damage-energy table and displacement energies. Scope and qualification explains these boundaries.

Pathways identify a source and first product with ranked contributions in trace mode. They do not enumerate every intermediate member of a reaction chain.

Check the ledger

The top-level ledger records missing data, composition issues, leakage, pruning, mode selection, numerical diagnostics, and optional response coverage. Inspect it before interpreting a small value as physical absence.

Positive activity without a radiological coefficient and material targets without damage data are reported as incomplete coverage. For features that support it, require_complete turns missing coverage into a calculation error.

The numerical_floor_atoms_per_g field is a CRAM asymptotic scale, not a bound on total numerical error. Below-floor counts and heat bounds help identify small populations that need closer review.

Read uncertainty with its coverage

An uncertainty response contains its nominal value, propagated standard uncertainty, interval, coverage, and a separate CRAM-order comparison. The default channel is MF=33 cross-section covariance. Half-life and independent fission-yield uncertainties can be enabled explicitly. Current master also supports a requested transport-tally statistical flux channel; check release availability.

Incomplete evaluated covariance does not become complete by requesting a confidence level. Incident-flux uncertainty is excluded unless the flux channel is requested. That channel uses supplied groupwise tally errors and a diagonal model; systematic transport-model, geometry, and nuclear-data errors remain excluded. Composition, response-coefficient, and other model uncertainties also remain outside the band. Aggregate activity uncertainty must be propagated as activity.total; summing individual standard uncertainties does not preserve correlations.

You can declare an additional unmodeled relative term directly or through a hash-pinned calibration/evaluation-spread table. That declared contribution supplements the band; it cannot account for a missing reaction channel or establish complete uncertainty coverage. See additional uncertainty reporting.

Check input identity and comparisons

The certificate records the selected inputs and computed hashes. It establishes which files were used; it does not establish their physical suitability.

Before comparing two results, check the material basis, spectrum normalization, schedule, projectile, library, and decay data. Compare at the same physical time. Record missing-data and mode differences alongside numerical differences.

Choose and install nuclear data

ACTINV software and evaluated nuclear data have separate versions. The embedded catalog identifies fixed release artifacts; installing software does not silently replace your calculation’s data.

Standard neutron setup

actinv data fetch
actinv data verify
actinv data list

The default bundle is tendl-2025-neutron, the full 2,850-target neutron library. Catalog 1.1.0 installs it under actinv-data/v1.1.0/ with its index, ENDF/B-VIII.0 primary decay data, and JEFF-3.3 fallback decay data.

Downloads are checked by size and SHA-256 before installation. Correct existing files are reused. An incorrect existing file is left in place unless you explicitly request replacement with --force.

Choose a bundle

For example:

actinv data fetch tendl-2025-neutron-covariance
actinv data verify tendl-2025-neutron-covariance

A covariance sidecar must match the exact activation library and index. Both full and patched neutron corpora have matching sidecars; mixing them is rejected. Add the corresponding uncertainty section to your problem to request propagation. Downloading a sidecar alone does not enable uncertainty.

The patched subset corrects a bounded upstream defect and excludes many targets. It is not a drop-in accuracy upgrade for every material or spectrum. Read Known data limitations before choosing between the neutron bundles.

Use another location

actinv data fetch --output /data/actinv
actinv data verify --output /data/actinv
actinv new problem.json --data-dir /data/actinv

--data-dir writes absolute paths to the generated problem. To keep symbolic catalog references, set ACTINV_DATA_DIR to your installation root when using the default actinv new output. It names the root above v1.1.0, not the version folder itself.

actinv data fetch and verify use --output for their destination; pass it explicitly when installing or checking a custom location.

Offline installation

Run actinv data manifest to print the embedded catalog. Obtain the listed archives and extracted artifacts through your usual transfer process, retain their names and versioned paths, then run actinv data verify on the destination machine. See the source and extraction record for provider details.

Prepared calculation cache

The CLI creates a verified prepared cache when it first uses a library and spectrum. Later runs reuse those compact files. The public iron example creates about 282 MiB of prepared files; other libraries and spectra differ.

By default, ACTINV uses the platform’s cache location. Set ACTINV_CACHE_DIR to an absolute path to choose another disk. This cache is disposable; removing it causes data preparation to run again. Keep the original nuclear-data inputs, problem, and result for the calculation record.

A corrupt or incompatible final cache artifact produces an error instead of being silently trusted. Troubleshooting explains how to regenerate it. Desktop workers use a private cache per calculation.

Terms and custom data

The installed ACTINV-DATA-NOTICE.md records data attribution and transformations. ACTINV’s MIT/Apache-2.0 software licence does not replace a dataset’s licence or source terms.

Advanced users can build activation, covariance, shielding, and damage tables from evaluated files. See Advanced workflows and the specification reference.

Known data limitations

Library coverage and evaluation defects can dominate an inventory calculation. A successful solve does not establish that every reaction or product is represented.

This page summarizes the shipped catalog 1.1.0. The detailed data disclosure preserves target lists, defect reports, and the underlying evidence.

Full and patched neutron corpora

The default full TENDL-2025 neutron corpus covers 2,850 targets and carries known upstream emitted-state inconsistencies. The derived tendl-2025-patched-neutron corpus repairs only a confirmed contamination signature: 44 leading ordinates in 28 source files are zeroed, with other source values retained.

The patched build also rejects 1,172 source files with remaining unsupported or inconsistent data. Targets absent from the subset cannot contribute the corresponding evaluated reactions. That coverage loss was substantially worse on the recorded fast-spectrum FNS benchmark than retaining the full corpus’s defects.

Check both material-target coverage and the affected reaction channels before deciding. A thermal-spectrum recommendation does not establish that the subset covers your material.

Affected product-state data

The data disclosure identifies 17 affected IRDFF-II benchmark targets, including Ni-58, Nb-93, Ag-109, In-113, and Au-197. Their remaining blockers are not all covered by the bounded patch. Treat predictions involving those targets and affected isomeric production with the disclosed uncertainty and applicability limits.

ACTINV’s current library builder validates product identities and emitted-state conservation. A new build can reject an evaluation that an older released artifact accepted. A parser fix or stricter builder does not retroactively repair an installed library.

Other coverage boundaries

Products absent from the selected decay data remain leakage. Missing fission yields, photon spectra, covariance, response coefficients, and damage tables are reported separately. Complete-coverage switches apply to the feature that supplies them; they do not certify every input in the problem.

Keep the ledger with each result and read Scope and qualification when assessing the effect of missing data. The data setup guide lists correctly matched covariance bundles.

Troubleshoot setup and runs

Start with the installed version and the failing problem:

actinv --version
actinv doctor problem.json
actinv validate problem.json --hashes

doctor reports the current working directory and supported input-file checks. Hash validation supplements those checks; evaluated-data compatibility is checked during a run.

An existing downloaded file is wrong

actinv data verify reports installed-file failures. fetch leaves an incorrect existing file untouched by default. After confirming the intended bundle and destination, request verified replacement:

actinv data fetch --force
actinv data verify

For a custom installation, add --output with its root. For another bundle, name that bundle explicitly.

A prepared cache is corrupt or incompatible

Stop calculations that use the affected cache, then remove the cache artifact or use a new, empty cache directory. ACTINV recreates prepared data from the original inputs. Cache removal affects preparation time; keep your original evaluated data, problems, and results.

Use an absolute ACTINV_CACHE_DIR on a disk with enough space if your normal cache location is unsuitable. Desktop runs use their own private caches.

Small, zero, or unexpected responses

Inspect the ledger for missing material targets, leakage, pruned populations, mode selection, and optional response coverage. Check normalization, irradiation length, cooling time, and the selected library. A missing channel can produce a small prediction without causing a parser error.

Consult Known data limitations before attributing a discrepancy to the solver. Include the software version, a minimal problem, the exact command, and the error message in a bug report. Share data identities or links rather than bulk nuclear-data files.

Command line

The actinv command is included with the Python package or can be installed independently with Rust. Run actinv --version to identify your executable and actinv --help to see its commands. The examples here cover 1.3.1.

Create, check, and solve

actinv new OUT.json [--data-dir DIR]
actinv validate SPEC.json [--schema|--files|--hashes]
actinv doctor [SPEC.json]
actinv run SPEC.json [OUT.json]

new refuses to overwrite an existing file. validate defaults to schema checking; --files checks supported readable inputs and indexes, and --hashes additionally checks declared file hashes. The run validates evaluated-data compatibility and computes input hashes. Without an output path, run writes result JSON to standard output.

Schema checking does not open literal data paths. Symbolic catalog: references must resolve to installed artifacts before validation, so install their bundle first.

Literal relative data paths use the current working directory. Describe a problem explains catalog references and path handling across interfaces.

Install and inspect data

actinv data list
actinv data manifest
actinv data fetch [BUNDLE] [--output DIR] [--force]
actinv data verify [BUNDLE] [--output DIR]

See Data setup for bundle names and library/covariance pairing.

Import flux and run independent cells

actinv import-flux openmc SOURCE.h5 OUT.ndjson --tally ID --source-rate RATE
actinv import-flux meshtal SOURCE OUT.ndjson --tally ID --source-rate RATE
actinv import-flux mctal SOURCE OUT.ndjson --tally ID --source-rate RATE
actinv import-flux fispact FLUXES OUT.ndjson --groups GROUPS.json
actinv mesh SPEC.json OUT.ndjson

Additional import options and mesh fields are in the specification reference. Supply a physically justified source-rate normalization for transport tallies.

Export photon sources

actinv export-openmc RESULT.json STEP OUT.py
actinv export-mcnp RESULT.json STEP OUT.sdef
actinv export-openmc-mesh MESH_RESULT.ndjson STEP OUT.py
actinv export-r2s MESH_RESULT.ndjson STEP OUT.ndjson
actinv export-source openmc R2S_SOURCE.ndjson OUT
actinv export-source mcnp R2S_SOURCE.ndjson OUT
actinv export-source serpent R2S_SOURCE.ndjson OUT

STEP is one-based. The selected step must contain the requested photon source. Ordinary result exports place a point source at the origin; mesh sources need recorded geometry and independent spatial review.

Build data

actinv build-library INPUT OUTPUT.npz [OPTIONS]
actinv build-covariance INPUT ACTIVATION.npz OUTPUT.cov.npz [OPTIONS]
actinv build-damage EVALUATION_DIR OUT.json [OPTIONS]
actinv build-shielding EVALUATION_DIR OUT.json [OPTIONS]

The specification reference describes builder parameters. Activation libraries, covariance, shielding, and damage tables are distinct inputs.

Study and design workflows

actinv study validate STUDY.json
actinv study build STUDY.json [OUTDIR] [--revocations FILE]
actinv study run STUDY.json [OUTDIR] [--revocations FILE]
actinv reverse PROBLEM.json MEASUREMENTS.json [OUT.json] [--segments]
actinv reverse-qualified PROBLEM.json MEASUREMENTS.json OUT.ndjson
actinv optimize OPTSPEC.json [OUTDIR] [--resume]
actinv decide DECISION.json [OUT.json]
actinv budget BUDGET.json [OUT.json] [--no-verify]

Each workflow consumes its own document format. Advanced workflows links the schemas, examples, and applicability limits. Run actinv COMMAND --help for available help; some commands print the shared usage rather than a dedicated page.

Python

Install with python -m pip install actinv, then install the data from your working folder with actinv data fetch. Python calls the same Rust solver as the CLI.

Construct a problem

from actinv import Material, Problem, Schedule, solve

problem = Problem.example()
problem["material"] = Material({"Fe": 100.0}, mass_g=10.0)
problem["schedule"] = Schedule().irradiate("5 min").cool("1 h")
problem.save("iron.json")

result = solve(problem)
print(result.heat())         # List of (seconds, W/g) pairs.
print(result.activity())     # List of (seconds, total Bq/g) pairs.
print(result.activity("Mn56"))
result.save("iron-result.json")

The example includes the iron spectrum and data references. Material keeps the declared composition basis; it does not silently convert weight percentages to fractions. Schedule methods return the same schedule for chaining. Use Spectrum when supplying your own group-integrated flux vector.

mass_g=10.0 does not change the unit returned by heat(): multiply W/g by ten to obtain this sample’s total watts.

Load an existing problem

from pathlib import Path
from actinv import Problem, solve

problem = Problem.from_file("iron.json")
result = solve(problem)
# You can also use: result = solve(Path("iron.json"))
print(result.steps[-1]["heat_W_per_g"]["total"])
print(result.ledger)

Problem.from_file resolves literal relative data references against the file’s directory. Supply base= when an older problem expects a different base folder. Plain dictionaries use the current working directory. Catalog references use ACTINV_DATA_DIR or ./actinv-data.

Result is a mapping: every result field remains accessible by key. Its helpers select existing data and preserve the reported units.

Use the JSON interface

import json
from pathlib import Path
import actinv

text = Path("problem.json").read_text(encoding="utf-8")
print(actinv.validate(text))
result = json.loads(actinv.run(text))
print(result["steps"][-1]["heat_W_per_g"]["total"])

run and its alias run_json accept JSON text and return JSON text. Literal paths in this interface use the current directory. solve returns a Result object instead.

Optional features

Set the corresponding problem blocks to request uncertainty, photon responses, radiological indices, damage, or self-shielding. Continuous feed and removal can be attached to schedule steps:

problem["schedule"] = (
    Schedule()
    .irradiate("5 min", feed={"Co60": 1e12}, removal={"Mn56": 1e-3})
    .cool("1 h")
)

Feed units are atoms s⁻¹ g⁻¹ and removal units are s⁻¹. Other helpers include reverse, decide, and optimize; current master also adds actinv.budget(budget, base_dir=None, verify=True). A failed budget verification is returned in the document rather than raised as an exception. See the Python package reference, Advanced workflows, and release availability.

ACTINV problem specification (actinv-spec-1)

One JSON document drives the CLI, Python API and validation harness. Unknown fields, non-finite numbers and invalid hashes are errors; literal paths use the CLI working directory (shell ~ expansion is not performed inside JSON).

Any path field or decay primary/fallback string may instead carry a symbolic reference catalog:<artifact-id> naming an artifact in the embedded data catalog (actinv data list prints the IDs, e.g. catalog:tendl-2025-patched-neutron-709g). The reference resolves to <data-root>/v<catalog-version>/<artifact path>, where the data root is $ACTINV_DATA_DIR when set and ./actinv-data otherwise. An omitted or null sha256 is filled from the catalog declaration; a declared hash that disagrees with the catalog is an error, as is a reference to an artifact that is not installed. This keeps problem files portable between machines while remaining hash-pinned — actinv new emits catalog references by default.

Start from a complete example

Create a valid, editable problem with its full spectrum:

actinv new problem.json
actinv validate problem.json

Your first calculation walks through installing data and solving it. This reference describes optional fields and advanced input formats. JSON fragments below belong inside a complete problem; they are not standalone runnable inputs.

Required inputs

The certificate records computed SHA-256 values for the activation library, its index, primary/fallback decay data, every fission-yield evaluation, the photon response, covariance sidecar, and radiological table when present. A declaration is a constraint, not a value copied into the certificate.

Material bases

material.mass_g defaults to 1 g. Inventories remain per gram; the mass scales the total photon rates and powers. Composition keys are case-insensitive natural element symbols or explicit SymbolA[mN] nuclides. Bare m means m1, so BA137M, Ba137m and Ba137m1 identify the same state; aliases which collide are an error. A natural element and one of its explicit isotopes cannot appear together. An unknown element symbol is an error, and so is a natural element without tabulated natural isotopic abundances (Tc, Pm, Po, At, Rn, Fr, Ra, Ac): give those as explicit nuclides, since a natural key would otherwise contribute no atoms. Explicit mass-based entries use the selected decay evaluation’s AWR times 1.00866491595 u and fail if that record is absent. A literal atoms_per_g entry may instead be ledgered as absent from the solvable chain; a photon-response calculation still requires its mass.

• wt_percent (default): each value is grams per 100 g. Values are used as stated rather than silently normalized; a total other than 100 is ledgered. Photon-response mixing normalizes them to mass fractions.
• atom_fraction: values are arbitrary elemental atom ratios. Natural isotopes are expanded and the mixture is normalized to one gram using the abundance-weighted elemental masses.
• atoms_per_g: each value is an elemental atom density per gram and is expanded by natural isotopic abundance.

All three bases apply identically to explicit nuclides: literal atom density for atoms_per_g, grams per 100 g for wt_percent, and an arbitrary atom ratio normalized to one gram for atom_fraction. Response-function mixing aggregates explicit isotopes back to elemental mass fractions.

Projectile and spectrum

Neutrons use fispact-709 with exactly 709 values. Proton, deuteron and alpha use fispact-162 with exactly 162 values and require options.temperature_K: 0; charged specs reject fission-yield files. custom requires one more strictly increasing boundary than flux values. Those boundaries must match the activation library to 1e-12 relative. total, when present, rescales group values while preserving shape; a positive total with an all-zero flux_per_group has no shape to scale and is rejected. The spec, library index, group structure and temperature must all identify the same projectile/data build before matrix assembly.

spectrum.relative_error is an optional array, the same length and order as flux_per_group (honouring descending): each group’s transport-tally statistical relative standard uncertainty. It is accepted and carried but otherwise unused unless uncertainty.channels requests "flux" (see below); requesting that channel with no relative_error given is an error naming the spectrum.

Fission yields

fission_yields is optional. Each file is one hash-pinned ENDF evaluation for one parent:

"fission_yields": {
  "files": [
    {
      "path": "/data/endfb-viii.0-nfpy/nfy-092_U_235.endf",
      "sha256": "64 hexadecimal digits"
    }
  ],
  "energy": "fixed",
  "fixed_energy_eV": 0.0253
}

The production source is MF=8/MT=454 independent yield. MF=8/MT=459 cumulative tables are parsed and checked but never used as matrix sources. Every independent table must sum to two fission fragments within 1e-6; values are not renormalized. Duplicate parents, energies or products, malformed/truncated records, negative/nonfinite values and hash mismatches fail closed.

energy: "fixed" requires a finite nonnegative fixed_energy_eV; selection is exact, linearly interpolated, or clamped to the evaluated range. energy: "spectrum_average" is the default and forbids fixed_energy_eV; it uses the fission-rate-weighted representative incident energy separately for each parent. The certificate records the requested energy, selected bracket, interpolation weight, clamp decision, product count and effective yield sum. Fissioning parents without a matching file remain explicit leakage and never borrow another parent’s evaluation.

MF=33 uncertainty

uncertainty is optional and neutron-only. uncertainty.covariance names an actinv-covariance-1 sidecar (path and a mandatory sha256); the adjacent <stem>_index.json must link the exact activation-library/index hashes, neutron projectile, group-boundary hash and every target/source identity. ACTINV recomputes and records both sidecar and index hashes before matrix assembly. covariance may be omitted only when channels is exactly ["flux"] (flux-only mode, below); any other channels value still requires it, and when present MF=33 is propagated exactly as always regardless of what else channels requests.

responses accepts the canonical selectors heat.total, heat.alpha, heat.beta, heat.gamma, activity:Nuclide, activity:*, and activity.total (the aggregate propagated directly through the full covariance — not a root-sum-square combination of per-nuclide bands). Selectors must be unique. An empty or omitted list selects all four heat components plus every activity reported at that step. confidence_level defaults to 0.95 and must be strictly between zero and one. require_complete defaults to false; when true, an active activation row without a valid MF=33 self-covariance — or a nonzero-sensitivity parameter in any requested channel without uncertainty data — fails rather than returning a partial band.

channels is optional and accepts "cross_section_mf33" (the implicit default), "decay_constants", "fission_yields" and "flux". When omitted, only the MF=33 cross-section channel is evaluated and the channel fields are absent from the output. decay_constants propagates each radioactive chain member’s decay-constant uncertainty sigma_lambda = lambda * dT_half/T_half read from the pinned decay file’s MF=8/MT=457 record. fission_yields propagates each populated fission edge’s independent-yield DY read from the pinned MF=8/MT=454 file at the requested yield energy. Both channels are diagonal — the evaluations carry no correlation data — and each reports its own sensitivity list, standard uncertainty and coverage. A nuclide or product with no declared uncertainty is named in uncovered_decay_constants / uncovered_yield_products.

The flux channel is an unreleased addition on master. It propagates each input group’s transport-tally statistical error (spectrum.relative_error, or a mesh cell’s own flux-file relative_error — a mesh cell without one is an error naming that cell) as a first-order, diagonal (uncorrelated group-to-group) channel: the parameter is the log of that group’s absolute flux after total scaling, its direction is the reaction-only burn matrix a unit flux confined to that group alone would produce, and its sensitivity is exactly the response’s own sensitivity to that group’s flux level. Each flux_sensitivities parameter reports its group in the order the spec declared flux_per_group (undoing descending for that label only — energy bounds, flux and standard uncertainty are unaffected, since they name the same physical group either way). The channel’s variance is sum((s_g * e_g)^2) over groups with a positive sensitivity and a given error; a fully-correlated alternative bound, sum(|s_g| * e_g), is reported alongside it (flux_fully_correlated_bound) for a worst-case, correlated-error comparison. flux needs no covariance sidecar by itself: channels: ["flux"] alone (covariance omitted) is flux-only mode — MF=33 is not propagated and the band is the flux channel alone, with the method and band name naming that. Everything else the flux collapse depends on (self-shielding row scale, rate_scale, fission-yield selection, mode and pruning choices) is held at the nominal run’s values. The flux channel is diagonal, needs no covariance and is not a nuclear-data parameter, so it is excluded from voi, isomer and design (below): those report ranks over parameters an experiment could better-measure, and a transport tally’s statistical error only shrinks by running more particle histories.

voi is optional ({"top": N}, 1–256) and emits a value-of-information table inside each requested response: the top parameters ranked by |variance_share| — the share of the propagated variance each parameter carries (s_i·(Σ·s)_i over the MF=33 block, (s_i·σ_i)² for the diagonal decay/yield channels — negative shares are emitted, not hidden, under anticorrelation) — plus the total propagated variance the band was built on and an unranked summary naming sensitivity-bearing parameters with no covariance coverage. The table answers “which measurement most buys down this band”: removing a parameter’s uncertainty drops the variance by its share.

Each requested response reports its nominal value, local sensitivity to every active collapsed row in response units per barn, MF=33 standard uncertainty, relative standard uncertainty when defined, the requested two-sided normal interval, an alternate-CRAM-order difference, and a conservative interval expanded by that numerical-method bound. When extra channels are requested the record adds per-channel sensitivity lists, per-channel standard uncertainties and a combined_standard_uncertainty equal to the root-sum-of-squares across channels, plus a channels report naming each channel’s coverage. Coverage is complete only when every nonzero-sensitivity parameter in every requested channel has evaluated uncertainty data. Missing evaluated cross-reaction terms contribute zero and are counted; they are not invented. These intervals are neither tolerance limits nor safety margins, and exclude MF=32 resonance-parameter and MF=40 production covariance, decay-yield and cross-channel correlation, material-composition, response-coefficient and model uncertainty — the uncovered_remainder channel names these. Absent a requested flux channel, incident-flux uncertainty is excluded there too; with flux requested, that entry instead names the narrower remainder the channel does not cover (systematic flux uncertainty from the transport model, geometry and transport nuclear data — the channel covers only the tally’s own statistical error).

Additional uncertainty reporting

Only one of the three unmodeled_* sources may be declared. A relative error term cannot cover a zero or missing-channel prediction. It supplements the declared band; it does not establish coverage of all excluded uncertainty sources. isomer.top and design.top default to voi.top when set, otherwise 20.

Radiological responses

radiological is optional. Its table is strict JSON with format actinv-radiological-table-1; the declared SHA-256 is mandatory and is recomputed before the calculation. ACTINV ships no default table and makes no jurisdiction or scenario selection. A minimal table is:

{
  "format": "actinv-radiological-table-1",
  "title": "Example only",
  "source": {
    "citation": "Issuing authority and publication",
    "edition": "2026",
    "url": "https://example.invalid/source",
    "jurisdiction": "example"
  },
  "responses": [
    {
      "id": "clearance-2026",
      "kind": "clearance_index",
      "basis": "Describe the applicable material and scenario",
      "coefficients": {"Co60": 100.0, "Mn56": 1000.0}
    }
  ]
}

Response IDs and canonical nuclide keys must be unique. kind is clearance_index, waste_index, ingestion_dose, or inhalation_dose. Clearance/waste coefficients are limits in Bq/kg; ingestion/inhalation coefficients are in Sv/Bq. Every coefficient must be finite and positive. An empty responses selector chooses every table response in table order; otherwise only the named unique IDs are evaluated.

Each step reports the selected value, unit, covered and missing activity, activity-coverage fraction, contributing nuclide count, and sorted active nuclides without a coefficient. Missing coefficients are not treated as zero. require_complete: true rejects the entire calculation when any selected response lacks a coefficient for positive activity. The certificate retains the table hash, source metadata, kind, basis, and coefficient count. See the qualification boundary before using a regulatory table.

Damage observables (dpa)

damage is optional and is required when options.outputs contains "damage". Its table is strict JSON with format actinv-damage-table-1; the declared SHA-256 is mandatory and is recomputed before the calculation. The table’s projectile must match the problem projectile, and its boundaries_eV must be the activation library’s boundaries exactly — actinv build-damage produces tables collapsed onto the same group structure.

A table row is a per-group damage-energy production cross section in barn·eV, keyed by a canonical explicit nuclide (Fe56, Ta180m1) or a canonical element symbol (Fe); an element row covers every material nuclide of that element without its own row. Rows must be nonnegative, finite, and exactly boundaries - 1 in length. Target keys are validated against the canonical naming rules — fe56 is an error, not a synonym.

displacement_energy_eV maps canonical element symbols to positive displacement energies; every covered element must have one, and a nuclide key there is an error. require_complete: true rejects the run when any material composition nuclide lacks a row. Uncovered nuclides are otherwise named in the ledger’s damage.uncovered_targets and reduce covered_atom_fraction; they are never treated as zero data.

Each step reports damage: total damage_energy_eV_per_g_s, material dpa_rate_per_s, cumulative dpa, the covered-atom fraction, and a per-element block of atoms_per_g, damage_energy_eV_per_g_s, dpa_rate_per_s, dpa. The displacement model is NRT: dpa_rate = 0.8 * damage_energy_per_atom_per_s / (2 * E_d); the material rate is the covered-atom-weighted mean of the element rates. Damage targets are the material’s composition-resolved nuclides — transmutation products are not counted, and in coupled mode the evolved target inventories are used. The ledger records the table hash, covered elements, displacement energies, uncovered targets, model, and units; the certificate records the table’s provenance and the computed input hash.

Damage-energy production comes from ENDF-6 MF=3/MT=444 sections. TENDL-2025 and EAF-2010 as distributed do not carry MT=444; build tables from heatr-processed or equivalent damage-energy evaluations.

Self-shielding

self_shielding is optional; omission preserves the ordinary unshielded path byte-for-byte. Its table names a hash-pinned actinv-shield-table-1 artifact — the declared SHA-256 is recomputed before the calculation and a mismatch is an error. Build tables with actinv build-shielding EVAL_DIR OUT.json; the table’s group boundaries must equal the activation library’s exactly.

dilution selects the background dilution each covered nuclide sees: "composition" derives sigma0_i = sum_j(n_j * sigma_p,j) / n_i from the declared material (table potential cross sections where the nuclide is covered, an analytic channel-radius estimate elsewhere, named as estimates in the ledger); "fixed" applies the validated positive sigma0_b to every covered nuclide. Factors interpolate in ln(sigma0) x sqrt(T) and clamp at the grid ends.

Each covered group applies a full-group Bondarenko fold, not a flat lethargy blend: the unresolved-range segment carries its probability-table weight mean w = sigma0/(sigma0+sigma_t) and weighted moment sigma_x*w, and the uncovered part is suppressed by sigma0/(sigma0+sigma_t,background) over the smooth MF=3 background. The emitted group_factors are the applied scale; factors remains the covered-segment factor for reporting, and tables without group_factors fall back to the flat (1-c)+c*f blend.

Material nuclides absent from the table are named shielding_uncovered and their rates are untouched; require_shielding_complete: true fails the run instead. The section rejects any sha256 or boundary mismatch. The ledger and certificate record the table hash, dilution mode, effective sigma0 per nuclide, applied factors, and method limits — including that resolved-region pointwise shielding is not applied and damage observables are not shielded.

When uncertainty is also present, the MF=33 collapse weights each row’s spectrum integral by that row’s shield factors (the collapse_weighted convention: sigma_i = sum_g phi_g * f_i,g * sigma_i,g / sum_g phi_g), so the propagated parameters are the same shielded one-group cross sections the depletion matrix uses; the run checks the collapsed nominals against the shielded fold bitwise. The same fold applies on the study.robustness MF=33 sampling path.

A runnable walkthrough lives at examples/shielding_demo.json: pure W-186 under a 4–25 keV custom spectrum at fixed sigma0_b = 0.1 — the ledger names every applied factor and W-187 activity lands ~28% below the unshielded solve of the same problem.

Gas production (H and He isotopes)

This option is an unreleased addition on master.

options.gas: true (default false) tracks the light charged-particle products of neutron activation — H1, H2, H3, He3 and He4 — as real inventory nuclides, exactly as FISPACT-II does. Every neutron reaction’s light-particle multiplicities (protons, deuterons, tritons, He-3, alphas) are read from a table built from the ENDF-6 reaction definitions for MT 11–45 (excluding the 18–21 and 38 fission MTs), 102–117 and 152–200; MT 4 and 51–91 (inelastic) and MT 102 emit none. A product row whose MT is not in the table (MT 18, fission, is the practical case: ternary gas is not modelled) contributes no ejectiles and is named in the ledger’s gas.uncovered, keyed by MT, with its share of the reaction rate. Each decaying nuclide’s own modes also feed the gas states directly: branching × λ into He4 for every RTYP digit 4 (alpha) and into H1 for every digit 7 (proton).

Because the five gas states are real chain nuclides, they decay and react further like any other state — H3 decays to He3 at its own tabulated half-life, and a secondary reaction such as He3(n,p)H3 applies when the library carries it — and they appear in the ordinary inventory, activity_Bq_per_g and heat_W_per_g output, not only in the block below. If a light nuclide is absent from the decay library, a stable sink stands in for it and the ledger’s gas.missing_light_states names it. Trace mode feeds the gas states from bulk material targets through the unit-source mechanism exactly as it feeds any other product, including the hybrid reservoir treatment when H or He is itself a bulk material constituent; the gas edges are ordinary edges in the graph pruning already operates on, so options.prune needs no gas-specific handling.

options.gas is refused together with uncertainty, and for any projectile other than neutron (v1). With gas off, every byte of PreparedRun, the result and the ledger is unchanged from a pre-P92 run; gas is absent from the spec echo and fingerprint entirely rather than serialized as false.

Each step gains a gas block when enabled: per species (H1, H2, H3, He3, He4) it gives atoms_per_g (the same quantity the main inventory reports for that nuclide), produced_atoms_per_g (atoms_per_g minus the material’s initial population of that nuclide, ordinarily zero) and appm (produced_atoms_per_g per 1e6 atoms of the material’s total initial population). It also gives inventory_appm (atoms_per_g per 1e6 initial atoms, the initial content included). It also gives H_appm (H1+H2+H3), He_appm (He3+He4), their inventory counterparts H_inventory_appm and He_inventory_appm, and initial_atoms_per_g, the appm normalization denominator. The two conventions differ only for a light nuclide the material starts with, e.g. hydrogen in a hydrocarbon. FISPACT-II’s printed APPM OF is the inventory convention (P95); compare against inventory_appm, not appm. These fields are plain f64 inventory populations and dimensionless ratios computed at result serialization, not raw inputs converted at a Spec::physical_inputs boundary, so they stay outside the P16 typed-quantity inventory (docs/QUANTITIES.md, which P16 pins by hash), as inventory[].atoms_per_g does. The ledger’s gas block records the ejectile table version, uncovered and missing_light_states.

Photon options

The entire photon object is optional. Without a response file, ACTINV still emits evaluated line/multigroup photon sources and energy-closure diagnostics, but dose fields are null.

Build response data with scripts/build_photon_response.py; see the data-source record. A response must contain attenuation curves for every material element to produce the contact-dose proxy.

Options and result

mode is auto, trace, or coupled. cram_order is 16 (default) or 48; an uncertainty run evaluates the other order as its separately reported numerical-method comparison. For each initial nuclide, auto computes the base-spectrum reaction-loss optical depth tau = loss_rate * sum(dt * flux_multiplier) and burn-up fraction -expm1(-tau); it selects trace only when the largest fraction is strictly below 1e-6. The controlling nuclide, optical depth and fraction are ledgered. Explicitly requested modes are always honored. prune is rate, reach, or none. The outputs list controls optional pathway and photon/dose calculations; the core inventory/activity/heat diagnostics remain in each result step.

The ordered schedule is the pulse representation: every positive flux multiplier scales all base projectile rates, and zero is an exact decay-only gap. Results are emitted after every segment. Each step records the current multiplier as flux, cumulative elapsed t_s, cumulative multiplier-weighted exposure flux_weighted_time_s, and physical fluence_n_cm2 (base total flux times weighted exposure). Scientific notation in a duration, such as 1e-8 s, is accepted as a number rather than mistaken for a unit suffix.

Any step may also carry its own spectrum — the same shape as the base spectrum — replacing it for that step’s duration while flux still scales the step’s total. This expresses pulsed or multi-field irradiations where the spectrum shape itself changes between segments (for example fusion pulses at different field positions or a spallation pulse inside a thermal field). A step spectrum must share the base spectrum’s structure and group count; an override identical to the base deduplicates to it. The physical fluence sums each step’s own spectrum total times its multiplier-weighted duration, and the schedule ledger reports how many steps declared overrides as step_spectra. Multi-spectrum schedules always collapse on the groupwise library rows (never the pre-collapsed artifact). Combined with uncertainty, the MF=33 collapse expands to one parameter per (spectrum, library row): each step’s tangent directions are the rows collapsed under its own spectrum, decay-constant directions stay spectrum-independent, and the propagated covariance carries the cross-spectrum blocks φ_sᵀ C φ_s' so a single physical draw propagates through every step’s collapse. Each sensitivity parameter reports its spectrum index (0 = base).

Any step may also declare optional feed and removal maps. feed entries are explicit nuclides (Co60, Ta180m1) with constant rates in atoms s⁻¹ g⁻¹, applied during the declaring step regardless of the multiplier — a feed on a zero-flux cooling step still delivers atoms. removal entries are nuclides or element symbols with first-order rates in s⁻¹; an element applies its rate to every tracked isotope and isomer of that element, and a nuclide key removes only that state. Removed atoms accumulate in a dedicated sink reported as removed_atoms_per_g, present only when a step declares removal. In trace mode the constant-reservoir material nuclides are exempt from removal — the trace formulation holds them undepleted — unless the same nuclide is also fed, in which case the fed atoms are carried in a real state and are removable. Every exempted reservoir nuclide is named in the ledger under feed_removal.removal_reservoir_exempt, along with the per-nuclide totals fed and the declared removals. Pathway attribution covers production chains only and is suppressed when a schedule declares feed or removal.

For charged projectiles, steps expose the generic fluence_particles_cm2 and identify the projectile in the result, ledger, certificate and prepared/mesh compatibility records. Neutron results retain their historical bytes and fluence_n_cm2 field when projectile is omitted.

Screening and perturbation options

options.screen accepts {"bmin_atoms_per_g": value} with a finite nonnegative value and requires prune: "rate". It applies the declared screening threshold and emits a screen certificate for dropped-state bounds on banded responses. Inspect that certificate and coverage before relying on a screened calculation.

The optional scale maps support explicit perturbations for sensitivity and sampling workflows:

Applied factors are recorded in the ledger. Absent or stable decay targets and absent yield pairs are named errors. Decay scaling changes decay edges and the corresponding activity, heat, photon, and dose responses consistently; yield uncertainties scale with their yields.

Build an activation library

The production builder is part of the actinv binary:

actinv build-library INPUT OUTPUT.npz \
  --format auto --projectile auto --groups fispact-709 \
  --temperature-K 293.6 --workers 4 --cache /data/actinv-cache

INPUT is one ENDF-6 evaluation or a directory. --format accepts auto, tendl or eaf; --projectile accepts auto, neutron, proton, deuteron or alpha; --groups accepts fispact-709, fispact-162 or a custom boundary file. Neutron defaults are 709 groups and 293.6 K; charged defaults are 162 groups and 0 K. The adjacent <stem>_index.json records source hashes, normalized options, group hash, builder fingerprint, target ledgers and the final NPZ hash. A content-addressed cache is optional and revalidated before reuse.

Build a damage-energy table

actinv build-damage INPUT OUTPUT.json \
  --projectile auto --groups fispact-709 --temperature-K 293.6 --cache /data/actinv-damage-cache

INPUT is one ENDF-6 evaluation or a directory. Every MF=3/MT=444 damage-energy production section is collapsed through the same parser, temperature check, and lethargy integration as build-library; --projectile, --groups, --temperature-K, and --cache share that command’s semantics. The result is a strict actinv-damage-table-1 document: group-structure label and boundaries, per-file SHA-256 provenance, a targets map of canonical nuclide rows, and an uncovered list naming every evaluation without MT=444 — absent sections are reported, never zero-filled. The output file’s SHA-256 is printed on success for pinning into damage.table.

Build an MF=33 covariance sidecar

actinv build-covariance INPUT ACTIVATION.npz OUTPUT.cov.npz \
  --workers 4 --cache /data/actinv-cov-cache

INPUT must be the neutron ENDF corpus from which ACTIVATION.npz was built. Source hashes, filenames, MAT, ZA/LISO target identities and the adjacent activation index must all agree. The builder supports strict MF=33 NI forms LB=0–6, 8 and 9; NC components, foreign or cross-sublibrary references, lumped MTL, malformed dimensions and unknown forms fail with MAT/MF/MT context. Its separate <stem>_index.json records the activation identities, source manifest, representation inventory, builder fingerprint and final sidecar hash. Per-source checkpoints are content-addressed and revalidated; worker count and cache reuse do not change canonical bytes. Raw evaluations, checkpoints and generated sidecars remain external data and must not be committed.

When photons are requested (or outputs is omitted), steps[].photon_source contains:

• evaluated discrete line rates and per-nuclide evaluated/source yields;
• group photon rates, energy centroids and emitted powers, per gram and for material.mass_g;
• raw energy moments, explicit E_EM normalization factors and represented-power fraction;
• specific gamma constants in Gy m2/(Bq s) and mGy m2/(GBq h) when a response is supplied;
• contact_gamma_air_dose_proxy_Gy_h, response coverage, and explicit ungrouped/unrepresented power.

Use one-based result step numbers for transport export:

actinv export-openmc result.json 2 source.py
actinv export-mcnp result.json 2 source.sdef

Both exports use the photon-group centroids and total photons/s. The point at the origin is a placeholder, not a spatial activation model. An export fails if custom boundaries omitted any source photons.

For mesh results, actinv export-openmc-mesh mesh_result.ndjson STEP source.py writes a distributed spatial source: one openmc.IndependentSource per mesh cell, sampled uniformly inside the cell’s recorded bounds_cm (openmc.stats.Box), with a discrete photon-energy distribution taken from the cell’s exported group centroids and probabilities, and the cell’s absolute photon rate as strength. The fragment ends with TOTAL_PHOTONS_S, the absolute sum over all cells. Cells whose photon source is zero contribute no entry; a cell with photons but missing geometry, a missing step, an unrequested photon output, or an inconsistent group total fails the export closed.

Flux interchange (actinv-flux-1)

Transport spectra are canonicalized before activation. The format is newline-delimited JSON: exactly one header, the declared number of ordered cell records, and one closing footer. A cell value is integrated neutron flux in n cm^-2 s^-1 for that energy group—not flux density per eV or lethargy. Every ID is unique and every ordinal begins at zero and increases by one. The strict reader rejects blank, malformed, missing, duplicate, extra and trailing records, invalid totals, nonfinite/negative values and inconsistent geometry.

actinv import-flux openmc statepoint.h5 flux.ndjson \
  --tally 7 --source-rate 1.0e15 --energy-floor-eV 1.0e-5 --window-rows 16384
actinv import-flux meshtal meshtal flux.ndjson \
  --tally 24 --source-rate 1.0e15 --energy-floor-eV 1.0e-5
actinv import-flux mctal mctal flux.ndjson \
  --tally 4 --source-rate 1.0e15 --energy-floor-eV 1.0e-5
actinv import-flux fispact fluxes flux.ndjson --groups descending-boundaries.json

The OpenMC and MCNP source rate is mandatory and positive. It converts a per-source-particle tally to physical flux; FISPACT fluxes values are already absolute and are not rescaled. If the source grid starts at zero, an explicit positive --energy-floor-eV below the next boundary is required and both the original zero and replacement are kept in provenance. Every importer hashes and re-stats its input and publishes the canonical file by sibling temporary-file rename only after the footer closes.

Supported subsets are deliberately narrow:

• OpenMC statepoint major 18, one selected flux/total/tracklength tally with exactly one 3D Cartesian regular or rectilinear MeshFilter and one EnergyFilter, in either order;
• MCNP traditional rectangular XYZ neutron FMESH meshtal column output with energy rows and optional checked totals;
• MCNP energy-binned F4:N mctal with one cell-ID F dimension, singleton remaining dimensions and optional checked total energy bins;
• standard FISPACT-II fluxes: N descending group values, first-wall loading, then its identifying title, against an explicitly supplied descending group-boundary JSON file.

Structured meshes (OpenMC, meshtal) above 100,000,000 cells are refused before any allocation is sized by the declared dimensions.

Other scores, particles, estimators, filters, dimensions, mesh shapes, multipliers, responses, cumulative/time bins or file variants produce a named error rather than a guessed interpretation.

Independent mesh specification (actinv-mesh-spec-1)

Mesh mode replaces the ordinary spectrum with a mandatory canonical-file path and SHA-256. All cells receive the same explicit library, decay data, optional fission-yield files, material, schedule, options, photon configuration, uncertainty configuration, and radiological configuration, and solve independently. Covariance and radiological data are verified and prepared once; workers borrow them rather than re-reading or cloning them per cell.

{
  "spec": "actinv-mesh-spec-1",
  "title": "iron activation mesh",
  "projectile": "neutron",
  "library": {
    "path": "/data/actinv_tendl2025_n_709g.npz",
    "sha256": "64 hexadecimal digits"
  },
  "decay": {"primary": "/data/endf-b-viii-0_decay.dat"},
  "material": {
    "mass_g": 1.0,
    "basis": "wt_percent",
    "composition": {"Fe": 100.0}
  },
  "flux": {
    "path": "flux.ndjson",
    "sha256": "64 hexadecimal digits"
  },
  "schedule": [
    {"dt": "5 min", "flux": 1.0},
    {"dt": "1 h", "flux": 0.0}
  ],
  "options": {
    "mode": "auto",
    "prune": "rate",
    "bmin_atoms_per_g": 1e-8,
    "temperature_K": 293.6
  },
  "chunk_cells": 64,
  "threads": 4,
  "group_workloads": true,
  "cell_result_fields": ["steps", "pruned_states", "total_states", "certificate"],
  "memory_limit_bytes": 4000000000,
  "resume": false
}

chunk_cells defaults to 64 and is bounded to 1–65,536. threads defaults to 1 and is bounded to 1–256. Execute it with actinv mesh mesh.json mesh-result.ndjson. Immutable activation/decay/response data are verified, decompressed and prepared once. Canonical cells are read a chunk at a time, restored to input order after Rayon execution, and written as actinv-mesh-result-1 header/cell/footer records.

group_workloads defaults to true: cells whose rebinned activation-group flux vectors are byte-identical share one solved result (keyed by the SHA-256 of the f64 little-endian group bytes, memo bounded to 256 distinct workloads and 512 MiB of memoized result bytes). Reuse changes only scheduling — every cell record is bit-identical to a group_workloads: false run, and the footer records the count as cells_served_from_reuse. cell_result_fields keeps only the named top-level RunResult fields in each cell record; absent means the complete record, and an unknown name is rejected at validation. memory_limit_bytes is a post-hoc guard: after each completed chunk the process peak RSS (/proc/self/status VmHWM) is compared to the limit and the run aborts with a named error carrying both numbers. It is refused at validation on platforms without that accounting (it could never fire there). Without resume the output is written atomically, so a tripped guard keeps no completed cells; pair it with resume: true.

resume: true makes the output file itself the checkpoint. The run writes directly (not via atomic rename); on start it validates any existing file: the header must equal byte-for-byte the header a fresh run would emit — including the spec_fingerprint_sha256 field, the canonical-JSON SHA-256 of the spec with resume, threads, chunk_cells and memory_limit_bytes removed. Complete in-order cell records stand; a torn final line is truncated; a mid-file corrupt or out-of-order record is a named error; a file whose footer is already present returns its summary without re-solving. Only unfinished cells are re-executed, and a completed resume is byte-identical to an uninterrupted run except the footer’s timing fields. A resumed run reproduces the uninterrupted cells_served_from_reuse count because completed prefix cells seed the grouping memo.

Matching source/library boundaries use a bit-identical copy path. Other positive grids use FISPACT’s default equal flux per unit lethargy rule. Every cell result includes source_total, rebinned destination_total, underflow, overflow, closure and method; energy outside the library is never folded into an edge group or renormalized away. The ordinary run result is nested without per-cell timing. Only footer wall_time_s and cells_per_s vary with scheduling; header and ordered cell bytes are deterministic across chunk and thread counts. The header certificate binds the declared/computed canonical hash and its embedded transport/auxiliary hashes. Any cell or footer failure names the failing premise and leaves no final result file.

Numerical floor diagnostic

numerical_floor_atoms_per_g retains its existing serialized name and value alpha0 * max(N) for compatibility. It is a CRAM asymptotic diagnostic scale, not a bound on total numerical error, factorization/solve roundoff or each reported population’s accuracy. heat_bound_from_below_floor_W_per_g is the computed heat subtotal of the reported below-scale populations, not a bound on all numerical dose or heat error. The ledger marks numerical_floor.is_total_numerical_error_bound = false explicitly.

CRAM shifted-system solves use bounded iterative refinement against the original matrix, with compensated residual accumulation and fused-product error terms. This applies to scalar, batched and tangent solves; it does not replace physical inputs, filter small positive populations or establish a universal forward-error bound. Independent numerical checks remain necessary for the claimed domain.

Advanced workflows

Use these workflows after you have run and checked a single-material problem. They share the solver but add their own inputs, coverage requirements, and output formats.

Transport flux and mesh calculations

Import supported OpenMC statepoints, MCNP MESHTAL/MCTAL files, or FISPACT fluxes into actinv-flux-1 NDJSON. Supply a tally identity and source-rate normalization where required. Review energy ordering, units, cell volume, and rebinning before solving.

actinv mesh calculates independent cells and writes actinv-mesh-result-1 NDJSON. Cells do not exchange material or flux and have no transport or thermal feedback. Workload grouping can reuse identical spectra; output selection, a post-hoc memory guard, and checkpoint resume are described in the mesh specification.

Photon exports turn computed sources into transport inputs. Ordinary exports use a point at the origin; mesh exports require cell bounds. Check spatial interpretation in the receiving transport code.

Build libraries and response tables

build-library converts supported evaluated ENDF-6 data into an activation library and adjacent index. Projectile, group structure, temperature, product-state identity, and builder options determine compatibility.

build-covariance creates an MF=33 sidecar for a specific activation library. build-shielding creates a neutron self-shielding table. build-damage creates a damage-energy table. These inputs are requested separately in the problem; an activation-library build alone does not enable those calculations.

See the specification reference for commands and formats. Keep source data and attribution outside the repository.

Uncertainty and self-shielding

The uncertainty section selects response bands and coverage policy. MF=33 cross sections are the default channel; half-life and independent fission-yield uncertainties are optional. Results explains how to read the bands.

Current master adds channels: ["flux"] with groupwise spectrum.relative_error, or each mesh cell’s own supplied errors. This propagates tally statistics and can run without covariance when it is the only requested channel. It excludes systematic transport errors and is omitted from measurement-design rankings. See the uncertainty reference and release availability.

The self_shielding section selects a hash-pinned neutron table and composition-derived or fixed background dilution. It supports bounded unresolved-range Bondarenko treatment; it does not apply resolved-region pointwise shielding or shield damage observables. Use the self-shielding reference for the supported table contract and completeness option.

Studies

An actinv-study-1 document expands cases over declared material, schedule, data, and calculation choices. study validate, build, and run separate document checking, deterministic case generation, and execution.

The study schema also describes refinement and seeded robustness sampling. Consult the study reference for scalar-response restrictions, sampling channels, and execution limits.

Reverse calculation

actinv reverse estimates a common flux multiplier or per-irradiation-step multipliers from measured activities. It requires a linear trace-regime problem and rejects unsupported or unidentifiable cases. It estimates normalization; it does not unfold the spectrum shape.

reverse-qualified adds nuclear-data covariance to the measurement model and reports posterior covariance and identifiability. Its forward problem must request the relevant banded activity responses. See the command reference and reverse example.

Design search and impurity budgets

optimize searches declared composition fractions, flux scale, and schedule durations with a seeded optimizer. Constraints can use propagated uncertainty edges. Banded candidates can take minutes each; use it as a batch workflow. Read the optimization schema and steel example.

decide evaluates declared response constraints and ranks measurement targets. budget estimates and verifies impurity limits against a supplied clearance calculation. These workflows inherit the selected response table’s applicability; they do not choose a jurisdiction or establish regulatory acceptance. See the budget schema.

Numerical method

ACTINV solves a nuclide network under irradiation and during cooling. For a fixed spectrum and schedule segment, the network is a linear system built from decay constants and spectrum-collapsed reaction rates. Optional feed adds a constant source and removal adds first-order losses with a recorded sink.

Data and rates

The Rust data library reads supported ENDF-6 evaluations and builds deterministic activation libraries. Standard neutron data use 709 groups; standard proton, deuteron, and alpha data use 162 groups at 0 K. A calculation must use the projectile, temperature, and group structure its library declares.

Decay data provide half-lives, branching, energies, and available radiation spectra. Natural elements are expanded using tabulated abundances. Products absent from the configured data remain explicit leakage.

Time integration

The solver uses the Chebyshev Rational Approximation Method, with CRAM orders 16 and 48. The default order is 16. Uncertainty runs evaluate the alternate order as a separately reported method comparison; this comparison is not a proof of total numerical error.

options.mode selects auto, trace, or coupled. Trace mode retains an undepleted initial-material reservoir and a linear production system. Coupled mode evolves the material network. Auto uses an estimated initial-material reaction-loss fraction to select the path and records its decision in the ledger. See the options reference for the exact criterion and pruning choices.

Responses and uncertainty

Activity follows radioactive populations and decay constants. Decay heat combines evaluated alpha, beta, and gamma energy contributions. Photon sources use evaluated decay spectra; response quantities use the explicit photon or radiological tables supplied by the analyst.

First-order sensitivities propagate retained MF=33 covariance into selected responses. Optional decay-constant and independent fission-yield channels use the uncertainties in their evaluated records. Coverage and excluded terms remain explicit; see Results.

Self-shielding and damage

A separate neutron table supplies finite-dilution unresolved-range Bondarenko factors. Fixed or composition-derived dilution selects factors on the declared grid, and compatibility is checked against the library. This bounded method does not provide resolved-region pointwise shielding or a geometry-dependent transport solution.

NRT damage uses separate damage-energy production data and declared displacement energies. It reports coverage of the material targets; it does not model damage covariance, recombination, or general material evolution.

For equations, data-processing details, and historical controls, consult the technical method record. Validation evidence explains what the recorded checks establish.

Validation evidence

ACTINV carries numerical controls, reader and data-processing checks, and comparisons with measured activation histories. Evidence establishes behavior for the recorded inputs, implementation, and acceptance bounds. Assess applicability to your own material, spectrum, data, time range, and response separately.

What has been checked

Compare the same data

Engine comparisons and library comparisons answer different questions. A calculation with EAF-2010 and one with TENDL-2025 can disagree because their evaluated inputs differ. Record the activation and decay data for both sides before assigning a difference to a solver.

The older validation record begins with a historical EAF-2010 run. Its figures are tied to that run and are not the current default-library score. Understand the competitive benchmark explains the later comparisons, metrics, and data-choice limits, with links to the full report and evidence.

Follow the evidence

The repository stores protocols, amendments, compact results, and independent checker scripts. Some verdicts are conditional or failed; those records are retained with their stated scope. A later software release does not convert a failed evaluation comparison into a pass.

Use the recorded validation controls, data disclosure, and relevant release notes together. Scope and qualification states the boundary between these checks and approval of an analysis.

Understand the competitive benchmark

The competitive benchmark compares ACTINV with other inventory and depletion codes on accuracy, speed, and capability. It helps you judge which measured differences matter for an activation workflow. The full benchmark report retains the dated results and links to their evidence.

The comparisons below are recorded experiments from September 2026, including ACTINV 1.1.2-era runs. They are not fresh measurements of every 1.3.1 feature or a ranking for every material, spectrum, and operating regime.

Three different comparison questions

Using TENDL-2025 in one code and TENDL-2017 in another compares both software and data choices. A common-cross-section comparison removes an important source of difference, but it does not make the two complete input chains identical.

Read the accuracy metrics

C/E is the calculated response divided by the experimental response. A value of 1 is exact agreement; 0.8 is 20% below the measurement and 1.2 is 20% above it.

The logarithm is natural. It treats a factor-of-two overprediction and a factor-of-two underprediction equally. An absolute log error of about 0.693 corresponds to a factor of two; it is not a 69.3% relative error.

The recorded FNS checker defines its “within 30%” band as abs(ln(C/E)) <= ln(1.3), or approximately 0.769 <= C/E <= 1.3. This is a multiplicative band, not the ordinary 0.7–1.3 arithmetic interval. An experiment counts only when every scored point meets it.

Read the metrics together. A geometric mean near 1 can hide large overpredictions and underpredictions that cancel in the average. Pooled point metrics give more weight to experiments with more scored time points; experiment-level metrics answer a different question. The checker records nonpositive or unaligned exclusions rather than putting them inside a logarithm.

FNS accuracy: ACTINV and FISPACT-II

The FNS benchmark contains 132 experiments across 73 materials. In the recorded common-TENDL-2017 comparison, 2,360 positive aligned point pairs were scored. ACTINV used ENDF/B-VIII.0 primary decay data with JEFF-3.3 fallback; the published FISPACT-II 4.0 reference used its own condensed decay dataset.

ACTINV has a small advantage on the typical error and whole-curve count in this arm; FISPACT has a slightly lower tail error. Switching ACTINV’s primary decay data to JEFF-3.3 changes its median error to 0.1058 and its passing count to 69. The narrow margin therefore depends on the decay-data choice; it does not establish a broad solver advantage independent of evaluation uncertainty.

Evidence: common-TENDL-2017 result and JEFF-primary sensitivity result.

The recorded ACTINV/TENDL-2025 comparison has median error 0.1392 and 59 passing experiments, while the same FISPACT/TENDL-2017 reference has 0.1053 and 69. That is a software-plus-data comparison. It shows why changing evaluations can matter more than a small numerical-method difference. Later decay-aware TENDL-2023 rebuilding improved a separate arm; its metrics and data identities are in the full report.

OpenMC: a common ENDF/B-VIII.1 comparison

This arm compares the activation/depletion responses on common evaluated ENDF/B-VIII.1 cross sections over 21 experiments and 424 measured points. ACTINV and OpenMC 0.15.3 use different chain representations and processing paths.

ACTINV has smaller median and tail errors and bias closer to 1 in this subset. The whole-curve passing count is tied. The detailed comparison attributes important differences to represented isomer-production channels, including tantalum, tungsten, and yttrium. Those findings describe this activation setup; they do not compare transport accuracy or every OpenMC depletion model.

See the ENDF-8 comparison for per-experiment results and shared data-driven misses.

Speed: numerical kernel versus a full calculation

The recorded CRAM-48 benchmark uses identical operators at the same Python-call boundary with both implementations limited to one thread. Its ratio is OpenMC median time / ACTINV median time: above 1 favors ACTINV and below 1 favors OpenMC.

The advantage varies with workload size, with near parity at 2,048 states. Small operators make Python and call overhead a larger fraction of the measured time. These figures do not include the complete cost of installation, library processing, cache preparation, or every response calculation. They cannot be applied as a universal speedup to a desktop run or an uncertainty study.

Evidence: kernel timings and numerical agreement. Use your own complete workflow and comparable hardware when estimating turnaround time.

Capability and error-bar comparisons

Capability is a separate axis: product-state handling, uncertainty channels, source exports, self-shielding, reverse calculation, and design search may matter even when nominal heat predictions are similar. Check the current workflow guide and qualification scope for ACTINV’s implemented boundaries. A feature being available does not establish its accuracy for every application, and an unavailable competitor was not measured.

The report also describes discrepancy calibration on 70 FNS experiments with 62 experiments held out. The recorded two-standard-deviation interval covers 93.1% of holdout points. That is useful evidence about this calibrated corpus, not a guarantee of 95% coverage on a new material or spectrum. See calibration evidence and the uncertainty reference.

Apply the results to your study

Find the comparison closest to your material, reactions, spectrum, cooling times, and response. Check per-material outliers and represented channels, not just the pooled score. Keep software performance, evaluation accuracy, and feature coverage distinct when making a tool choice.

The benchmark supports the recorded comparisons. Your calculation still needs suitable data and an applicability assessment; see Validation evidence, Known data limitations, and Scope and qualification.

Scope and qualification

ACTINV is research-grade calculation software. Recorded controls demonstrate specified numerical, data-handling, and benchmark behavior within their stated bounds. They do not approve ACTINV, or a calculation made with it, for licensing, safety, waste classification, or another regulatory purpose.

Where ACTINV fits

1. A transport calculation or measurement supplies the particle spectrum and its physical normalization.
2. The analyst chooses activation, decay, yield, covariance, and response data appropriate to the problem.
3. ACTINV calculates inventory evolution and requested responses, reporting coverage and omissions.
4. Separate transport or consequence tools use the source terms when spatial or shielding effects matter.
5. The responsible organization reviews applicability, uncertainty, margins, configuration, and acceptance.

The certificate identifies the files used. It does not establish that those inputs are physically suitable.

Supported scope and boundaries

Missing decay modes, fission yields, spectra, response coefficients, or material-target data are not inferred. Read the ledger and feature-specific coverage fields. A complete-coverage option checks its declared feature, not the entire analysis chain.

Uncertainty interpretation

MF=33 cross-section covariance is the default. Half-life and independent fission-yield uncertainties may be requested separately and are treated as diagonal channels. Current master adds a diagonal transport-tally statistical flux channel; it can run alone without an MF=33 sidecar. Check release availability before requesting these additions.

Decay-yield and cross-channel correlations, MF=32 resonance covariance, MF=40 production covariance, composition, response-coefficient, geometry, and model uncertainties are outside the propagated band. Flux uncertainty is excluded unless its channel is requested; even then, systematic errors in the transport model, geometry, and transport nuclear data remain excluded.

An explicitly declared unmodeled relative contribution can supplement that band, including a term drawn from a calibration or evaluation-spread artifact. It does not recover a missing channel or establish coverage of all omitted sources.

These are first-order intervals for retained input uncertainties. They are not tolerance limits or safety margins. The alternate CRAM-order difference is a method diagnostic rather than a proof of total numerical error.

Assess and retain a calculation

Confirm composition, basis, mass, spectrum units and normalization, group ordering, schedule, projectile, temperature, target coverage, and data applicability. Check known evaluation defects and validation evidence for the intended reactions and time range.

Retain the exact software version or commit, complete problem and result, original data and terms, generated libraries and indexes, upstream tally definitions and normalization, selected coefficient tables, and your applicability and uncertainty assessment. Apply the independent reviews and acceptance process required by the organization responsible for the analysis.

Versions and releases

Software, nuclear data, and desktop packages have separate release histories. Record all the versions relevant to your calculation.

Use actinv --version for the executable. actinv data manifest prints its embedded catalog. Source-built desktop candidates may use a newer solver than the published preview; inspect their package/build record.

Current master

The source branch also contains unreleased impurity-budget workflows, the Python budget helper, hydrogen/helium isotope production through options.gas, and transport-tally statistical error propagation through the flux uncertainty channel. These additions are described in the Unreleased changelog; they are not promised by the published 1.3.1 packages or older desktop preview.

For these features, use a source build at a recorded commit and the current field reference. The workspace version can still read 1.3.1 before the next release, so record the commit as well as actinv --version.

Upgrade software

python -m pip install --upgrade actinv

For an exact Rust CLI version:

cargo install --locked --force actinv-cli --version 1.3.1

A software upgrade does not silently replace installed data. Revisit optional settings and coverage when a release changes their behavior, and retain the executable or source version for older results.

Changes that may affect earlier results

The 1.2.1 release notes identify self-shielding interpolation, composition validation, and decay-branch accounting corrections. Review them if your earlier calculations used those paths.

The 1.3.1 release notes describe later capabilities and their qualification boundaries. The changelog retains the full software history; data-release notes describe data changes.

Publishing a new executable does not repair or supersede an evaluation’s recorded failure. See Known data limitations before assuming a newer software version implies better nuclear data.