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.7.2 and nuclear-data catalog 1.2.0. The downloadable desktop preview has a separate release history; check its solver version before using a feature described here.
Impurity screening for fusion materials (actinv impurities), a damage table in the data catalog so that dpa needs no setup, new problems from a cited material library, and a reorganised desktop and browser app that reaches most of the command line are new in 1.7; see What’s new in 1.7. Waste classification with nuclear-data uncertainty, impurity budgets under uncertainty, packages of discrete items, and a proven bound for rate pruning are new in 1.6; see What’s new in 1.6. FISPACT-II deck import, step summaries and report tables, photon dose, production routes, regulatory tables, and geometry self-shielding are new in 1.5; see What’s new in 1.5. Coming from FISPACT-II? Start with Coming from FISPACT-II. Gas production, transport-tally error propagation, impurity budgets, lean mesh output, and photonuclear activation arrived in 1.4.0. Versions and releases lists what each release and the desktop include.
Choose how to work
| Interface | Use it for | Start here |
|---|---|---|
| Desktop | Edit a single-material problem, run calculations, and explore plots | Install the desktop |
| Command line | Run JSON problems, import transport fluxes, and automate studies | Your first calculation |
| Python | Construct problems and analyze results in scripts or notebooks | Python guide |
| Browser | Learn the interface, edit problems, and inspect existing results | Browser workbench |
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.
| Computer | Package | First launch |
|---|---|---|
| Windows, Intel or AMD 64-bit | Installer or portable ZIP | Install and open ACTINV from Start; for the ZIP, extract it and open ACTINV.exe |
| Mac, Apple Silicon | Apple Silicon disk image | Open the DMG and drag ACTINV to Applications |
| Mac, Intel | Intel disk image | Open the DMG and drag ACTINV to Applications |
| Linux, Intel or AMD 64-bit | AppImage | Allow execution in file properties, then double-click |
The 0.6.0-preview.1 desktop is unsigned and uses solver 1.7.0; the CLI and Python packages are at 1.7.2, whose changes reach the desktop in its next preview. It organises setup as numbered steps and adds an Export page that saves a report page, charts and tables; see What’s new in 1.7. The Waste class page, which classifies the loaded result against the NRC Part 61 tables, came in 0.5; see What’s new in 1.6. The Outputs, Tables, Photons & dose and Pathways pages and FISPACT-II deck import came in 0.4; see What’s new in 1.5. Its Outputs page has controls for gas production and every uncertainty channel, including the flux channel, and the gamma projectile is on Overview & data. 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.7.2
If you already use Rust, install just the CLI from crates.io:
cargo install --locked actinv-cli --version 1.7.2
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 186 MiB and installs about 276 MiB in actinv-data/v1.2.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.
If fetch stops with http status: 403
The two decay files (endfb-viii-0-decay and jeff-3-3-decay) come from the IAEA Nuclear Data Section, whose site
now refuses automated downloads. ACTINV keeps byte-identical copies in the
decay-sources-v1 release. From 1.7.2, fetch
takes them from there by itself when the IAEA refuses. With 1.7.1 or earlier, install them once in the same working
folder, then run fetch again; it checks them against the catalog and downloads the rest:
mkdir -p actinv-data/v1.2.0/decay && cd actinv-data/v1.2.0/decay
for f in endf-b-viii-0_decay jeff-3-3_decay; do
curl -fLO "https://github.com/AvilaLabs/ACTINV/releases/download/decay-sources-v1/$f.sublib.zip"
unzip -o "$f.sublib.zip" "$f.dat" && rm "$f.sublib.zip"
done
cd ../../.. && actinv data fetch
On Windows, download the two .sublib.zip files from the release page and extract the .dat file inside each into
actinv-data\v1.2.0\decay\. An existing actinv-data folder from an earlier version already has these files, and
fetch reuses them.
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.
How the app is organized
The sidebar follows a calculation from start to answer:
- Start is the home page. Begin a New problem, load the iron example, open a problem, or import a FISPACT-II deck. Under What do you want to find out? each question opens the page that answers it, such as Certify for whether a design meets its limits. Start also shows the current problem and result, and whether the standard nuclear data are installed.
- SET UP holds the numbered steps: 1 Material, 2 Irradiation & cooling, 3 Source & spectrum, 4 What to compute and 5 Check & run. A tick beside a step means its part of the problem is filled in. Each step ends with Back and Continue.
- RESULTS opens on Summary, then Time history, Nuclides, Photons & dose, Pathways, Waste class, Evidence and Export. These pages are dimmed until a result is loaded.
- STUDIES holds Impurities, Certify, Optimize, Sweep, Mesh & transport, Compare, Measurements and Maintenance, which run many calculations or plan from their results. The group is folded away until you open it or one of its pages is current. Certify, optimize and compare designs describes Certify, Optimize and Compare.
- TOOLS holds Data and Advanced JSON, folded the same way. See Check the nuclear data.
Learn without downloading nuclear data
On Start, choose Try the 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
- On Start, choose New problem, Load iron example, Open problem… or Import deck…. If the standard data are not installed, Download standard data… installs them, or run
actinv data fetchin a terminal. - Walk the numbered steps. On Material, density is optional; a step that uses W/cm3, or geometry self-shielding without its own density, needs it. On Source & spectrum, choose the projectile; spectrum values are integrated group fluxes, with explicit ordering and normalization. On What to compute, add what to compute besides inventory, activity and decay heat, which every result includes.
- Check & run reads the problem back in one sentence per step, such as “5 min irradiation, then 20 cooling steps to 57 min after shutdown”. Anything missing is marked with a Fix button that opens the step. Under Settings you changed it lists every setting that differs from its default, each with an Edit button that opens the page that sets it. Under Nuclear data it says whether the data the problem names are installed; Edit opens the Data page.
- Choose Run calculation. The background task reports preparation and solving. Cancelling a calculation stops its isolated worker without publishing a partial result. The result opens on Summary at shutdown.
The toolbar keeps Open problem, Import FISPACT-II deck…, Save, Validate and Run on every page. Apply or discard advanced JSON edits before returning to structured editing.
Start a new problem
New problem on Start opens a blank problem on Material. The material, the schedule and the source are empty and nothing is filled in for you: each step is ticked once its part is complete, and Check & run marks what is still missing. The three starting cards below fill the empty parts quickly. Each card is open while its part is empty and folds under the page’s own controls once it is filled.
Material has Start from a library material. Choose a material from the list, grouped by category, then Use this material. The library holds 19 cited compositions of common reactor and fusion materials: steels (EUROFER97 at its specification maxima, EUROFER97-3 as one measured heat, and stainless 304, 304L and 316), Inconel 718, Zircaloy-4, aluminium 6061, ordinary concrete, water, reactor graphite, tungsten, tantalum, niobium, titanium grade 2, copper, beryllium S-65, V-4Cr-4Ti and Pb-15.7Li. Below the list the page shows the largest elements, what kind of composition it is, the density and the citation. The kinds differ:
- Nominal composition: generic values, not a real heat.
- Specification maxima: trace elements at their allowed maximum, the main element the balance. Trace activation is overstated by design.
- Measured heat: a published analysis of one batch, not the specification.
The entry sets the composition in weight percent and sets the density from the same source, or removes the density when the source gives none. It names an untitled problem after the material. On a filled table the card is the folded Library materials heading, and its button reads Replace the composition with this one. Check a composition against your own material certificate before relying on it; each entry’s note names the trace elements it leaves out. actinv new does the same from a terminal; see Command line.
Source & spectrum has Start from a standard spectrum. Pick a shape, type the Total flux (n/cm²/s) and choose Use this spectrum. The shapes are generic textbook shapes on the 709-group structure, not a facility’s spectrum; for a real facility import its group values from transport. The card appears for neutron problems only. Once the spectrum has flux, it is the folded Standard spectra heading and its button reads Replace the group values with this spectrum.
- D-T fusion (14.1 MeV): all flux in the group that contains 14.1 MeV.
- Fission (Watt): a Watt spectrum for U-235 thermal fission (a = 0.988 MeV, b = 2.249 per MeV).
- Thermal (Maxwellian): a Maxwellian at kT = 0.0253 eV.
- Slowing down (1/E): flux per unit energy proportional to 1/E from 0.5 eV to 1 MeV, zero outside.
Irradiation & cooling has Start with a standard schedule. Type the length in Irradiate for (30 d or 2 y; it starts at 1 y) and choose Use this schedule. It irradiates at the source’s full flux for that time, then cools with results at 1 h, 1 d, 30 d, 1 y and 10 y after shutdown. Afterwards the card is the folded Standard schedule heading, and its button, Replace the steps with this schedule, overwrites every step. Edit the steps below it as usual.
Read the outcome beside Validate and Run
Validate and Run show their outcome in a small chip beside the buttons, so you need not look at the status bar. Validate gives Valid or Not valid. While a calculation runs, the Run button is replaced by a disabled Running… N s counting seconds; other background jobs read Working… N s. When a job ends the chip reads Finished in and the time, or Failed. A cancelled calculation shows Cancelled. Validate only on Check & run shows the same chip. The chip fades after about 4 seconds, or 8 seconds for a failure; hover over it for the full message, which also stays in the status bar.
Check the nuclear data
Data, under TOOLS, is where the nuclear data are set. This problem’s data reports whether the files the problem names are installed. If some are not found, it lists them; when the standard data are installed, Use the installed standard data points the problem at them, which fixes a problem written for an older data release. Data files and input folder holds the library, decay and fission-yield paths, with a SHA-256 pin for the library; relative paths use the input folder, which opening a problem sets to its directory. If the standard data are missing, Download standard neutron data installs them with their size shown, or run actinv data fetch.
Check the installed data has Verify the data. It reads every installed standard file and compares it with the SHA-256 the catalog records, then names any file that was changed or cut short. It reads and hashes every file, so it takes a while. If it fails, actinv data fetch --force replaces the changed file. The command-line equivalent is actinv data verify; see Choose and install nuclear data. Build your own data lists the actinv build-* commands, which libraries, damage tables, shielding factors and covariance files still need.
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.
Import a FISPACT-II deck
Choose Import FISPACT-II deck… in the toolbar (Ctrl/Cmd+I). Pick the deck, and optionally a fluxes file and a files file, then Convert. The dialog lists every keyword with its line and a status of mapped, approximated, noted or unsupported, and you can filter the list. Strict refuses the problem when any keyword is unsupported. Download report saves the same report as actinv import-fispact; see Move a FISPACT-II deck to ACTINV. Use this problem replaces the current problem, after asking about unsaved changes.
A deck that irradiates but comes without a fluxes file converts with a flat placeholder spectrum, flagged as a required input. Replace it on Source & spectrum before running. Under Required additions, each input the deck implies but cannot supply has a button to the page where you add it.
Choose what drives each step
On Irradiation & cooling, each row has a Drive: a flux multiplier, a wall loading (MW/m2), a power density (W/cm3) or a specific power (W/g). A flux multiplier of zero is cooling. A wall-loading step is scaled against the reference loading, spectrum.wall_loading_MW_m2 in Advanced JSON. Power steps need a kerma table pinned by its SHA-256; the page shows a Kerma table field with Choose and pin. Power steps in W/cm3 also need a density on Material. Sweeps over wall-loading or power steps are command-line only. See Kerma heating and power-driven steps for the result side.
Choose what to compute
What to compute has one card for each optional calculation, with an enable box, its settings and a status that reports conflicts with other choices:
- Step summary, which feeds the dominant lists, element table and other report tables.
- Decay photons and dose.
- Production pathways, including Full routes with closure.
- Regulatory tables.
- Geometry self-shielding.
- Uncertainty, with its channels: MF=33 cross sections, half-lives, fission yields and flux tally statistics. The flux channel takes one relative error per flux group, pasted on the card; with flux alone no covariance file is needed. Unmodeled error adds a share of each value to every band, for error the data do not model. Estimate from library disagreement solves the problem with the decay library and again with the fallback library from Data (
actinv eval-spread) and sets it to the largest difference among the banded responses. That difference bounds how far the choice of library moves the answer; it is not a measured uncertainty. - Gas production (H and He), for neutron activation; it cannot be combined with uncertainty.
A result lacks an output you did not enable; the page that would show it says so and offers a link to What to compute.
Explore and save results
The pages under RESULTS read one result. A bar at the top of each has Open result…, Compare with…, Save result…, Export… and the Computed step slider. The chosen step is shared, so every page shows the same step. Add another result for a comparison; check both files’ physical times and normalizations.
- Summary is where a result opens. It gives activity, decay heat, contact dose and, when computed, damage at the selected time, each with a small curve of how it evolves, and the nuclides that dominate activity and heat. Jump to selects shutdown or the step nearest 1 h, 1 d, 1 y and so on after it. With a comparison loaded, each value shows its change against the comparison at the same time. Select a nuclide to follow it on Time history.
- Time history plots activity, total heat or inventory against time. Click the plot to select the nearest step, and filter and select a nuclide to follow its history. Heat remains the whole-material response.
- Nuclides shows the tables that
actinv reportwrites: nuclides (atoms and grams, or activity and heat), step totals, dominant nuclides, elements, depletion, dose, photons, regulatory tables and the time series. Filter a table, click a header to sort it, and choose Export CSV for this step or all steps. The CSV is byte-identical to theactinv reportoutput. A table the result cannot build gives its reason; when the result has nosummary, Enable and re-run addssummary: {}to the problem and runs it again. - Photons & dose shows decay photon groups, dose rates, bremsstrahlung and dose against cooling time. Export photon groups (CSV) saves the groups of the selected step. A result with no photon source links to What to compute.
- Pathways shows how a nuclide is produced. Full routes lists the routes for each target with the part of the inventory they explain and the residual; First products (trace) ranks the first products and needs trace mode.
- Evidence shows the ledger of incomplete inputs and approximations, and the certificate of inputs and data.
- Waste class answers four waste questions: the class of the loaded result, of a container of items, of activity ranges, and how sure the class is; see Classify a result as waste.
- Export saves what the result answers in one new folder; see Export a result.
Save result… keeps the complete result JSON: every step, the ledger and the certificate. Saving the problem does not save the result.
Export a result
Export writes the files you tick into a new folder inside the folder you choose; it never writes over an existing folder. Save to folder… at the top of the page names how many files it will write.
- Report (
report.html): one page to read, share or print to PDF, with the problem in sentences, activity, decay heat, contact dose and damage at shutdown and at round cooling times, charts, the nuclides that dominate and the caveats. When Waste class has classified this result, its classes are included. Describe the problem that produced this result uses the problem as it was when you pressed Run, so later edits never appear beside its numbers. For a result opened from a file the problem is not known, and neither it norproblem.jsonis offered. - Charts (
charts/*.svg): each quantity as the material cools, and the decay photon spectrum at shutdown. - Tables (
tables/): the FISPACT-II style tables ofactinv report, as CSV, TSV, Markdown or fixed-width text, for all steps or only the selected one, optionally restricted to named nuclides. A table the result cannot build is greyed, with the reason on hover. - Transport source (
transport/, not ticked by default): the decay photons of the selected step, or of every step that has them, as the source of a photon transport run:photon_source_openmc.py(anopenmc.IndependentSource) andphoton_source_mcnp.txt(an SDEF card). The source sits at the origin; replace it with your geometry’s spatial distribution. A step without decay photons gives its reason; ask for photons or dose under What to compute. - Files to rerun or reuse:
result.jsonandproblem.json.
The report, charts and tables are the files actinv report writes, and the transport sources the files actinv export-openmc and actinv export-mcnp write; see the CLI reference.
Classify a result as waste
Waste class opens by asking which waste question you have. Each answer comes from the evaluator the actinv waste commands run, against the bundled U.S. NRC 10 CFR 61.55 tables, and each form has Save spec… and Save result… so the command line reproduces the answer.
- What class is this result? classifies the loaded result (
actinv waste). - What class is a container of several items? averages plugs, rod sections, sealed sources and filters in one container (
actinv waste package). - Which classes can it reach if activities are ranges? takes lower and upper activities and lists every class inside them (
actinv waste bounds). It needs no run. - How sure is the class? samples the nuclear-data uncertainty, solving the problem once per sample (
actinv waste uncertainty).
All four need the nuclide properties (Z, half-life, alpha emission) of every nuclide with activity. Press Load from decay data to read them from the problem’s decay data; the page asks only for nuclides it has not looked up, and looks them up again after the decay data change. A nuclide without a decay record stays blank and leaves its class unknown, as the CLI does. Enter replaces a nuclide’s properties with your own entry, marked as yours.
This result describes one homogeneous component, the irradiated material, so the component mass is the material mass of the problem. Choose the waste type (activated metal or general) and the displaced volume, or derive the volume from the material density when the problem declares one. Select the steps to classify; all are selected at first, and Last only keeps the last. If retained H-3 is not in the activation inventory, declare it with its source and a whole-component activity in Bq for each selected step. Tick Also screen the whole container against the draft intrusion table to add the February 2026 draft NUREG-1556 Vol. 22 screen (actinv waste intrusion-screen); activated metal is screened as metal, and general waste takes the waste form you choose. Site acceptance limits and reportable quantities are added from the command line.
Classify runs in the background. For each selected step the page shows the class, status, coverage, the governing table and column with its sum and margin, and the binding nuclides, a strip of the classes against cooling time, and the earliest selected step within Class A, B and C; with the screen, it adds each step’s indicator and the draft rows that apply. Save spec… writes the spec and the result.json it reads into a folder you choose (it will not replace existing files). The classification is nominal screening, not disposal acceptance; see Component waste classes.
A container lists its items: a name, waste type, mass, volume (an envelope volume for a cartridge filter), and, for pieces of one sectioned component, a shared piece of name. Each item’s activity is this result’s activity per gram times its mass, another saved result’s (Choose…), or becquerels you declare at each step. Choose a screen, or tick The items are encapsulated and give the total volume and the encapsulant. The answer shows the container’s class at each step, how each waste type averaged and which items were classed on their own, and every item’s own class.
Activity ranges describe one component by name, mass, waste type and volume, then its whole activity at one or more times as a lower and upper value per nuclide. Fill from this result puts a step of the loaded result times the mass into the ranges, widened by the percentage you give. Say whether the nuclides are the whole inventory, where the ranges come from and what they assume. The answer lists every class the component can reach, and the range of each table sum.
How sure solves the problem in the background once per sample, with the inputs you tick redrawn each time: cross sections (from the TENDL-2025 covariance data, which actinv data fetch tendl-2025-neutron-covariance installs), decay constants, and a flux spread. The problem’s own uncertainty block is left out, because the sampler draws its own. At least 72 samples are needed to establish a class at 95 % confidence. The answer gives the established class at each step and the share of samples in each class with its confidence interval.
Studies and tools
Three studies compare designs or check limits: Certify, Optimize and Compare. They are described in Certify, optimize and compare designs.
Impurities screens the trace elements of the open problem’s material: which drive activity, decay heat, contact dose, a nuclide’s activity, the clearance index or the waste class, the worst case over their specified ranges, and how far each may rise before a limit is reached. It runs actinv impurities in the background; see Screen a material’s impurities.
Sweep solves a family of generated problems along one parameter. Advanced JSON exposes the complete problem. Bulk library building uses the CLI.
Activate a transport mesh
Mesh & transport takes the flux of a transport run cell by cell and walks four steps; each opens once the one before it is done.
- The flux on the mesh imports an OpenMC statepoint, an MCNP meshtal or mctal tally, or FISPACT-II fluxes (
actinv import-flux). A tally needs its ID and the source rate, in source particles per second, that makes the per-particle tally a flux. An ACTINV flux file thatimport-fluxwrote already is read directly. The flux is pinned by its SHA-256. - Activate every cell solves the problem as it is set up now in every cell (
actinv mesh): the material, the irradiation and cooling, the library and what to compute, with each cell’s flux in place of the spectrum. The schedule’s flux multipliers scale it. A step with its own spectrum is refused; pathways, KERMA and named overrides are left out. Uncertainty bands bands the activity, the heat and the nuclides that carry the decay photons in the open result; the banded source and the facility check need them, and they need the TENDL-2025 covariance from Data. A run cancelled from the toolbar keeps the cells it finished; Resume solves the rest. The table lists each cell’s activity, heat and contact dose at a chosen step, highest activity first; Open loads one cell’s result on the result pages. - The shutdown-dose source writes the decay photons of every cell at one step for the photon transport run. The banded source (
actinv export-r2s) carries each cell’s independent and fully correlated sigma, and is converted for OpenMC (XML), MCNP (SDEF), Serpent or ALARA (actinv export-source). Correlate the bands between cells adds the cell-to-cell correlated sigma (actinv export-r2s-joint) and takes about as long as the mesh run. One OpenMC source per cell (actinv export-openmc-mesh) needs no bands. Every source needs the cell bounds a flux mesh with geometry carries. Save to folder… copies the files out. - Facility check applies clearance limits to the band of every cell (
actinv twin): a cell clears only when its whole band does. Each limit names a banded response, at most or at least a value, and When picks the step it applies at, or every step. Components name groups of cells for one verdict each. The answer lists what binds each limit and the cells that do not clear.
The browser leaves this page out: it reads and writes files on your disk.
Bring in measurements
Measurements answers two questions.
- What flux explains these activities? fits the irradiation flux to activities measured in a sample after the run (
actinv reverse). Each row names when it was measured (a step of the schedule), the nuclide, its activity per gram and one standard deviation. One flux for each irradiation step fits every irradiation step on its own, where the measurements can tell them apart. Count the nuclear-data uncertainty (actinv reverse-qualified) gives each flux a confidence interval, says which steps the measurements can tell apart, and checks the measurements agree; it needs the TENDL-2025 covariance and every uncertainty. The answer is the flux as a multiple of the spectrum’s total, with how well the fit reproduces each measurement; Use this flux puts it into the schedule. Load measurements… and Save measurements… read and write thereverseinput. - How does a measurement narrow the bands? folds a measured value with its uncertainty into the bands of the loaded result at one step (
actinv assimilate). It narrows the band of what it measures and, through their shared data, the bands of everything correlated with it. The result needs uncertainty bands at that step. Preview shows each band before and after; Apply to the result replaces the loaded result’s bands. Load a measurement file… reads anactinv-assay-1file instead, which may also hold a mixture such as a gross-gamma count.
Plan maintenance after shutdown
Maintenance plans jobs inside a shut-down machine from the dose rate at each job’s place over cooling time, the same way as actinv maintenance (see Plan maintenance after shutdown). The open result is a place when its problem asks for a point-source dose; Add dose rates… adds another run result, or an actinv-dose-map-1 table with a place for each of its locations. Rename a place in its box, and its jobs follow. Give the access limit and, if you have one, the individual limit, then the jobs in the order they are done, each with its place, hours and crew. The answer appears as soon as the plan is complete: the earliest wait at which every job is allowed, the wait of least cost when Find the wait of least cost is ticked, the dose rate at every place against cooling time with the access limit, when each job could start on its own, and each wait’s doses, cost and, where it is not allowed, why. A warning says when the cooling times are too sparse for the plan. Save result… writes the answer with the plan and the files it used.
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, Ctrl/Cmd+I imports a FISPACT-II deck, and Ctrl/Cmd+S saves the problem.
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, import a FISPACT-II deck, or inspect result files without installation. A laptop or desktop with WebGL enabled works best.
The browser has the same pages and controls as the desktop app, under the same names, laid out the same way: Start, the numbered setup steps ending in Check & run, and the results, which open on Summary. It leaves out what runs or downloads things: the Sweep, Mesh & transport and Measurements studies, the run button, the nuclear-data download and Verify the data. The Data page only records the library and decay paths. On Check & run the browser hands the problem over instead: Download problem, run it with the desktop app or actinv run, then open the result here. Where the site serves the data for it, the browser can also run the problem itself. The pages that differ only in how they choose a file are described below.
Explore results
On Start, Iron example’s result opens what ACTINV computes for the iron example the Start page loads as a problem, and Impurity screen of a steel opens an impurity screen on the Impurities page. Both were computed ahead of time with the desktop solver and are fetched when you click. Under Results, Try the results tutorial opens a fictional one-hour decay example instead. A result opens on Summary: activity, decay heat, contact dose and the dominant nuclides at the selected time. On Time history, switch between activity, heat and inventory, click the plot to select a step, and select a nuclide to follow its history.
For a real calculation, open or drop a result JSON produced by ACTINV. Use Compare with… to overlay a second file. Plots use each result’s recorded time and normalization; the browser does not rescale results to make them comparable. The bar at the top of each results page has the file actions and the Computed step slider, and the chosen step is shared by every page.
- Nuclides shows the tables that
actinv reportwrites. Filter and sort a table, then choose Export CSV to download it for this step or all steps; the file is the textactinv reportwrites. When the result has nosummary, Add to problem addssummary: {}to the problem. The browser does not run the solver, so download the problem and run it with the desktop app or the CLI, then open the new result. - Photons & dose shows decay photon groups, dose rates, bremsstrahlung and dose against cooling time, and downloads the groups of the selected step as CSV. A result with no photon source links to What to compute.
- Pathways shows first products and full production routes, when the result recorded them.
- Evidence shows the ledger of missing data and approximations, and the certificate of inputs and data.
- Waste class reads waste results, edits waste specs and sets up the container, ranges and how-sure questions; see Read waste results and edit waste specs.
- Impurities sets up an impurity screen of the open problem and reads screen results. The browser does not screen: Save screen… downloads
impurities.json, which you run with the desktop app oractinv impurities, and Open result… shows the result; see Screen a material’s impurities.
Download result saves the complete result JSON. Export… opens the Export page, which downloads a report page, charts, tables, a transport photon source and the result and problem files as one zip; it offers the same choices as the desktop Export page except the waste classification.
Read waste results and edit waste specs
Waste class opens an actinv-waste-result-1 file, an intrusion-screen result, or a twin result that has waste_classification, and shows what the desktop page shows: for each selected step the class, status, coverage, governing table and column with its sum and margin, and the binding nuclides, a class strip against cooling time, and the earliest selected step within Class A, B and C. All of it is read from the file. The browser does not classify: the evaluator is not built for the web, so run a spec with the desktop app or actinv waste and open the result here. A file that is not one of these three, or is not valid JSON, shows an error message and changes nothing.
The same page opens an actinv-waste-spec-1 file (or starts from a skeleton), lets you edit it as JSON, checks its structure and downloads it as waste-spec.json. The input member names the run result the spec reads, so keep that result next to the spec when you run it. Dropping a waste file on the window opens it. The other three waste questions of the desktop page are set up here too: a container of items, activity ranges, and how sure the class is. The browser has no decay data, so enter each nuclide’s properties in the table. Each form downloads its spec (package-spec.json, bounds-spec.json, or uncertainty.json with the problem.json it samples) to run with the CLI, and Open its result… shows the answer. See Component waste classes for the document formats.
Edit a problem
The numbered steps Material, Irradiation & cooling, Source & spectrum and What to compute edit the problem, and Check & run reads it back with a Fix button for anything missing. Start from the iron example, Open problem…, or import a deck, edit it, then choose Download problem on Check & run. Open that file in the desktop app or run it with the CLI or Python interface. Advanced JSON exposes every option.
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.
Files you pin by name
Some options point at a data file with its SHA-256: the kerma table, the photon response, a radiological response table, the covariance sidecar and resonance files. Choose and pin opens your browser’s file chooser, reads the file on your device and writes its SHA-256 into the problem. A browser does not reveal where a file lives, so the recorded path is the file name only. Keep each file where you run ACTINV so that name resolves against the input base folder, or edit the path before you run.
Run a problem in the browser
Where the site serves the browser’s nuclear data, Check & run has a Run it here panel with a Run in browser button. ACTINV then solves the problem in the page, in the background, with the standard TENDL-2025 library (709 groups) and the ENDF/B-VIII.0 and JEFF-3.3 decay data. The problem and its result stay on your computer. The result opens on Summary, and Download result keeps it. Cancel stops the run.
The browser does not download the whole library. It fetches the reactions the material can reach in two steps, with the decays between them, and the decay data they lead to, and solves. Then it solves again with more reactions (three, four, six and so on), fetching only what each round adds, until two rounds in a row give the same answer. Meanwhile the progress line says Checking with more reactions. In the tests below, most problems settled at four reactions after about 34 MB of data. A material burnt for years in a strong thermal flux needs most of the library: tungsten at 1e15 n/cm²/s for ten years fetched about 200 MB and took about three minutes.
The browser keeps the files it fetches, so running the problem again, or another one with the same materials, fetches only what it has not kept, even after a restart. A kept file is used only if it still matches the library’s record of it, and is otherwise fetched again. Clearing the site’s data in your browser’s settings removes them. Pages served without HTTPS (other than from your own computer) cannot keep files and fetch everything each run.
Some problems run only on your computer, and the panel says why:
- a library or decay data other than the standard ones;
- fission yields;
- displacement damage;
- self-shielding;
- a schedule whose steps change library.
Download those and run them with the desktop app or actinv run.
How close browser runs come to the desktop, from the registered test P196A:
In the browser, ACTINV solves a problem with the standard TENDL-2025 library, fetching only the reactions its material can reach and the decay data they lead to, and following more reactions, round by round, until the result no longer changes.
On 175 problems (19 materials under four standard spectra at 1e14 n/cm²/s for a year and at 1e15 for ten years, under a thermal spectrum at 3e14 for three years, and 4 of the examples), its total activity, decay heat and photon emission at every step were within 9e-07 of the whole library’s (of 1e-10 of its largest value, where it had fallen below that), and every nuclide carrying 0.1% of the activity within 5e-15.
Run in Chromium, the browser’s result was identical to the native one on all 15 problems tried; a problem fetched a median of 34 MB of data (at most 209 MB).
Agreement outside those problems is not measured, and that the rounds settle does not prove a deeper chain could not matter elsewhere. For a result you will rely on, run the problem with the desktop app or the CLI.
Import a FISPACT-II deck
Choose Import deck… on Start. The dialog is the one the desktop shows: it lists every keyword of the deck with its line and a status of mapped, approximated, noted or unsupported, and Strict refuses a deck with any unsupported keyword. Download report saves the report that actinv import-fispact writes (see Move a FISPACT-II deck to ACTINV). Use this problem replaces the current problem, after asking about unsaved changes.
Each file is chosen on its own: the deck, an optional fluxes file and an optional files file. Dropping a file on the window while the dialog is open takes it as the deck. A deck that irradiates but has no fluxes file converts with a flat placeholder spectrum and a required-input note; a decay-only deck needs none. Each file is read on your device, up to 32 MiB, and non-UTF-8 bytes are replaced rather than refused. The files file is read only for the names it lists, and the browser cannot follow those names to other files, so choose the fluxes file yourself.
Set up studies in the browser
Certify, Optimize and Compare (see Certify, optimize and compare designs) have the same inputs and checks as in the desktop, but the browser does not solve them. Their main button becomes a download, and the page notes the command that runs it:
- Certify: Download the decision file gives
decision.json; runactinv decide decision.json verdict.jsonwhere the nuclear data and the covariance file are installed. - Optimize: Download the search file gives
search.jsonandbase_spec.json. Keep them in one folder and runactinv optimize search.json out. Use this design is a desktop button. - Compare: Download the study file gives
compare.json; runactinv study run compare.json out.
Maintenance plans in the browser itself, as in the desktop: the run results and dose-rate tables it adds are read on your device, and Save result… downloads maintenance-result.json.
The starting cards on Material, Source & spectrum and Irradiation & cooling work in the browser, as does New problem on Start; see Start a new problem.
Keep your edits
Files are read on your device and are not uploaded. Download edits before closing or reloading the tab; the browser asks first while a problem has unsaved edits, and 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.
Avila Labs account (optional)
ACTINV can be used without an account, and every feature works without one. If you like, you can sign in with an Avila Labs account. One sign-in works across ACTINV, Converra and OpenBNCT.
Sign in
- Browser workbench: choose Sign in in the header, or answer the prompt shown on your first visit. You can dismiss the prompt and sign in later.
- Desktop (0.3.0-preview.1 and later): choose Sign in. The desktop shows a short code and opens your web browser, where you approve the sign-in. The desktop then continues by itself.
What is sent and stored
Nothing from your work is sent: no problem inputs, results or files. The sign-in only identifies your account.
The desktop stores its sign-in token in ~/.config/avila/credentials.json. Choosing Sign out
revokes the token and removes it from that file.
Privacy and terms
See the account service’s privacy notice and terms.
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, or with actinv new problem.json --material ss316 --source fission --flux 1e13 for a library material under a standard spectrum (commands).
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.
| Basis | Interpretation |
|---|---|
wt_percent | Grams per 100 g; values are used as supplied and an off-100 total is reported |
atom_fraction | Relative atom amounts, normalized to one gram |
atoms_per_g | Literal atom density per gram |
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 folder. 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.
| Field | Meaning | Unit |
|---|---|---|
inventory[].atoms_per_g | Nuclide population | atoms/g |
activity_Bq_per_g | Activity by nuclide | Bq/g |
heat_W_per_g.total | Total decay heat | W/g |
heat_W_per_g.alpha, .beta, .gamma | Decay-heat components | W/g |
leakage_atoms_per_g | Atoms routed outside the represented evaluated chain | atoms/g |
removed_atoms_per_g | Atoms in the removal sink, when requested | atoms/g |
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. Photon power below the response’s lowest energy (1 keV for the NIST response) is left out of the proxy and shown as dose_response_power_coverage below one and as dose_response_subthreshold_power_W_g. The proxy is still reported when that power is at most 1e-4 of the step’s photon power, because the missing low-energy response then changes it by at most about 1e-3; above that share it is null. Radiological indices use your selected coefficient table, including the a2 transport index (A1 and A2 tables are bundled, or supply your own). A nuclide a table lists as unlimited, or a progeny whose listed parent is present, is counted as covered with zero contribution and named in unlimited_active_nuclides or covered_by_parent instead of missing_active_nuclides. NRT dpa uses the supplied damage-energy table and displacement energies. Kerma heating uses the supplied kerma table. Scope and qualification explains these boundaries.
Two photon components are emitted only when the specification asks for them. With photon.point_source, photon_source.point_source_dose holds the absorbed dose rate in air at the configured distance from the step’s photon source treated as a point source of material.mass_g (1 g by default, FISPACT-II’s convention), plus the same dose per gram. The field names say Sv_h, but the quantity is the air kerma rate, numerically Gy/h (the contact proxy calls the same quantity Gy_h); no quality factor or conversion to ambient dose equivalent H*(10) is applied, and H*(10) is roughly 1.1 to 1.4 times the air kerma between 0.1 and 3 MeV. It is the manual’s Eq. (63): group-centroid energies, air energy absorption, optional air transmission, no build-up. A null dose carries an unavailable_reason, and subthreshold_power_W and excluded_power_W show the power it could not use; decay-record gamma energy with no photon spectrum also makes it null and counts as excluded power. With photon.bremsstrahlung, photon_source.bremsstrahlung is a separate source and dose for the listed beta emitters, following the manual’s thin-target approximation from each nuclide’s beta-minus electrons per decay (electrons_per_decay, from its decay branching), their mean energy and the material’s mean atomic number. Group energy follows the manual’s bin-midpoint rule, so energy_closure (emitted over the analytic a Z E0^2 / 2 per electron) is not 1, and zero_lower_edge_energy_fraction is the share of that energy in the empty zero-lower-edge group. It is never merged into the decay-photon groups or dose proxies, so the total dose from both is the sum of the two fields. Nuclides whose inputs are missing are named in missing_inputs, and inputs_complete is then false. Both are screening estimates with the limits described under photon options, not transport results.
Two more photon options add keys only when set. With photon.missing_spectra: "estimate", a nuclide that has a mean electromagnetic energy but no photon spectrum is given an exponential spectrum; photon_source.estimated_gamma_power_W_g is its power and photon_source.estimated_spectra holds, for the contact proxy and the point-source dose, the value from evaluated spectra alone (represented_only), the estimate and the lower and upper bounds, with each estimated nuclide’s own range. In this mode photon_source.point_source_dose.gamma_air_dose_Sv_h equals the point-source estimate (the evaluated nuclides’ dose plus each estimated nuclide at its own group centroids), and the top-level contact proxy stays the evaluated-only value. The estimate is a model; read it with its bounds. With photon.exclude_xrays, photon_source.excluded_xray_power_W_g is the X-ray power removed from the source.
The pathways array identifies a source and first product with ranked contributions in trace mode, including production fed by the decay of a radioactive bulk nuclide. pathway_closure is the worst relative difference between a nuclide’s listed chains and its inventory, and is 1 when a nuclide in the inventory has no chain at all. The array does not enumerate every intermediate member of a reaction chain; the opt-in pathway_routes analysis does.
Read the pathway routes
When the spec carries a pathways section, the result gains a
top-level pathway_routes object. It is absent otherwise. (The older pathways array identifies a source and
first product only, in trace mode; pathway_routes enumerates the whole reaction and decay chain.)
pathway_routes.targets[] has one entry per target nuclide:
| Field | Meaning |
|---|---|
total_atoms_per_g | The real run’s final-step inventory of the target. |
paths_atoms_per_g | Sum of the reported routes. |
residual_atoms_per_g, residual_fraction | total - paths: the part of the inventory no reported route explains. |
explained_fraction | paths / total. |
loop_atoms_per_g | Portion of the reported routes carried by loop walks. |
paths_dropped_by_cap | Routes that passed the floors but fell outside max_paths. |
candidates_dropped_by_cap | Candidate routes beyond 8 x max_paths that were never integrated (smallest upper bound dropped first). Absent when none. |
search_truncated, truncated_sources | The route search for this target ran out of its tree-node budget, and the sources whose tree was cut short. Absent when the search finished. |
paths[] | Routes ranked by contribution (see below). |
generic[] | Routes grouped by their edge-type sequence, for example (n,g) b-, with n_paths, atoms_per_g and fraction. |
Each route in paths[] gives its source, the nuclides from source to target, the edges between them (a
reaction such as (n,g), (n,2n), fission, or a decay mode: b-, b+/EC, IT, a, n, p), atoms_per_g
at the final step, fraction of the target’s total, and is_loop. Loop walks add loop_gain and base_path;
by_step: true adds atoms_per_g_by_step. Reaction names follow neutron conventions; other projectiles use the ENDF
MTnnn number. Spontaneous-fission products are SF, atoms from a schedule feed are feed, and an edge into the
removal sink is removal; an edge that the label tables do not cover is named edge. Labels come from the decay and
reaction tables, not from this run’s rates, so a library reaction is named even if its collapsed rate is zero here.
The residual is the accounting check. It is small when the floors keep the routes that matter and max_depth is
long enough; a large residual means the target is fed by many small routes, by chains longer than max_depth, or
by loops beyond loop_floor. Lower path_floor and raise max_depth and max_paths to chase it, and read
search_truncated, explored_walks and candidates_dropped_by_cap (per target, and in the top-level notes) for the
search’s own limits. A walk that revisits a nuclide must also pass loop_floor, so the residual can exceed
path_floor unless loop_floor is near zero. In a coupled run a
source that is also the target has a one-node route (the surviving initial atoms).
Contributions are exact for the routes listed, but the dense integration works to the absolute precision of its
largest term, so a route carrying under about 1e-10 of the largest term in its own chain is below the method’s
resolution.
Step summary
The desktop Nuclides page shows these tables for the selected step; see Use the desktop.
When the problem declares summary, each step gains a summary object. Every
quantity is per gram of initial material, except the absolute and per_cm3 totals. A state is counted with the
same population rule as the rest of the output: constant bulk atoms in trace mode (plus the tracked population of a
reservoir nuclide), the evolved state elsewhere, and bulk nuclides absent from the chain at their constant atoms.
The leakage, unit and removal sinks are not nuclide states.
In trace mode the initial material is held constant, so nuclides shows each initial nuclide at its constant bulk
atoms: an initial radionuclide keeps a constant activity and heat there, and mass_g is not a closure test. The
depletion table gives the analytic view of the same step.
nuclides lists one row per nuclide, descending by atoms:
| Field | Meaning |
|---|---|
nuclide, Z, A, LISO | Name and identity, as in inventory |
atoms, grams | Population and mass. grams uses the decay record’s AWR times the neutron mass in u times the atomic mass constant (1.66053906660e-24 g, CODATA 2018). With no AWR it uses A times that constant and sets mass_from_a |
activity_Bq | λ·N |
alpha_W, beta_W, gamma_W | Activity times the record’s mean heavy-particle, light-particle and electromagnetic decay energy, the same split as heat_W_per_g |
half_life_s | null for a stable nuclide or one without a decay record |
stable, initial, decay_data | A decay record exists with no decay constant; present at t = 0; a decay record exists. A state without one is reported with zero activity and heat, and is not called stable |
totals always covers every state, whatever min_atoms or include_stable remove from the table:
activity_Bq,activity_Ci(1 Ci = 3.7e10 Bq exactly),alpha_W,beta_W,gamma_Wandheat_W.activity_by_mode: each nuclide’s λN split by the branching ratios of its decay-mode records, classed by the first digit of RTYP (1 β⁻, 2 EC/β⁺, 3 IT, 4 α, 5 n, 6 SF, 7 p, anything elseother). The ratios are normalised so the eight entries sum toactivity_Bqto rounding; a record whose ratios fall short of one by more than the chain tolerance, or that has no modes, books the shortfall toother.- FISPACT-compatible
alpha_Bq(the α-mode activity),beta_Bq(β⁻, EC/β⁺ and IT modes) andgamma_Bq(the activity of every nuclide whose mean electromagnetic decay energy is positive). These are FISPACT’s report categories;activity_by_modeis the exact partition. activity_excl_H3_Bqandheat_excl_H3_W: the same totals with H-3 removed.mass_g: the current total mass in grams per gram of initial material. Departure from 1 is a mass-closure diagnostic: it reflects mass the represented chain does not carry and the difference between these AWR-based masses and the composition’s molar masses.leakage_atomsandn_nuclides(states with a positive population).absolute: activity (Bq, Ci), heat components and the H-3-excluded values multiplied bymaterial.mass_g(multiplier).per_cm3is the same multiplied bymaterial.density_g_cm3(Bq/cm³, W/cm³) and is present only when a density is given.
elements (omitted with summary.elements: false) lists one row per Z, ascending, with symbol, atoms, grams,
activity_Bq and the three heat components. dominant ranks the nuclides for activity, heat, alpha_heat,
beta_heat and gamma_heat. Each list gives the total, the top dominant_top entries (nuclide, value,
percent, cumulative_percent) and n_for_90_percent and n_for_99_percent, the number of nuclides needed to
reach those shares of the total, counted over the full ranking rather than the truncated list.
Depletion table
The desktop Nuclides page shows this table on its Depletion tab.
With summary.depletion set to true, steps[].summary.depletion reports how
much of each initial-material nuclide the step removed and which channels removed it. Without it the key is absent.
model is coupled when the solver evolves the initial nuclides, and trace_analytic in trace mode, where the
reservoir is held constant in the inventory and is instead depleted analytically,
N(t) = N(0) exp(−∫ removal rate dt), the same first-order law as the ledger’s max_burnup_fraction. Analytic
depletion has no ingrowth from other nuclides. An initial nuclide absent from the decay library has no row at
all; the ledger lists it under ledger.depletion.initial_nuclides_absent_from_decay_library, written as
<ZA>_<LISO> (for example 26056_0 for Fe-56, 47110_1 for Ag-110m), not in the Fe56 style of the table.
nuclides has one row per initial nuclide that is in the decay library, largest first:
| Field | Meaning |
|---|---|
nuclide, Z, A, LISO | Name and identity |
initial_atoms_per_g, atoms_start_per_g, atoms_end_per_g | Atoms per gram of initial material at t = 0, at the start of the step and at its end |
depleted_atoms_per_g, depleted_fraction | Start minus end, and that over the start, for this step. Net of ingrowth from other nuclides (a feed into an initial nuclide, or production from another nuclide, shows up as negative depletion with no channel) and of a partition applied at the step start |
cumulative_depleted_atoms_per_g, cumulative_depleted_fraction | Initial minus end, and that over the initial atoms |
removal_rate_per_s | Total removal rate per atom: decay, the schedule’s first-order removal and every reaction channel. Exactly 0 when nothing removes the nuclide |
channels | The removal split, descending by rate |
removal_rate_relative_standard_uncertainty | With MF=33 covariance and only when every channel is covered |
uncertainty_covered_share | With MF=33 covariance and a nonzero removal rate: the share of the removal carried by channels that have an uncertainty |
Each channel has channel (decay, removal or MT<n>), kind (decay, removal or reaction), mt, reaction (the conventional name such as (n,g) for
a neutron projectile), rate_per_s, share and, with covariance, relative_standard_uncertainty.
The rates are the solver’s own, not a recomputation. A reaction channel is the sum of the nuclide’s loss rows with
that MT, collapsed under the step’s spectrum with self-shielding, options.rate_scale and named overrides applied,
times the flux multiplier the step ran at (the time-weighted mean for a power-driven step). The decay channel is
the effective decay constant after decay_scale and half-life overrides. The removal channel is the
first-order rate a schedule step’s removal map declares for the nuclide (a nuclide or element selector), not
scaled by the flux multiplier and present even in a step with no flux. The channels therefore sum to
removal_rate_per_s, the diagonal of the step matrix, and the shares sum to one. A feed is a source, not a
removal, so it has no channel. In trace mode the removal of an initial nuclide that is not also fed is not applied
to the reservoir (the ledger names these exemptions), so it has no channel; a fed, removable reservoir nuclide
does. A reaction whose loss row is absent from the library is not listed. Fission appears as MT18. The analytic
fractions of trace mode are computed with expm1, so they keep full precision at the tiny exponents trace mode
runs at.
The uncertainty of a reaction channel is the flux-weighted collapse of the MF=33 covariance for its loss rows, the
same collapse the uncertainty bands use: for weights wg = σgφg / Σσφ it is
√(wᵀCw) on the relative covariance. A decay channel takes the half-life uncertainty of the decay data, or a
half_life_uncertainty override, whatever uncertainty.channels lists (the bands add decay-constant uncertainty
only when decay_constants is a listed channel, so the table and the bands can differ there). A removal channel
is an exact input and carries an uncertainty of 0. A reaction channel with a loss row the covariance does not cover,
or whose covariance block was excluded as defective (asymmetric or not positive semidefinite, as in the ledger’s
excluded_blocks), has no uncertainty and is not counted in uncertainty_covered_share. The total includes the correlation between a nuclide’s reaction channels from the
cross-MT covariance blocks. Fission-yield, flux and composition uncertainty do not enter a removal rate.
Fission count, burn-up and spontaneous-fission neutrons
Each step gains a fission block only when options.fission is set (fission.count) or
fission_yields.spontaneous supplies a neutron multiplicity (fission.spontaneous_neutron_source); see the
specification. Absent means not requested.
| Field | Meaning | Unit |
|---|---|---|
fission.count.fissions_per_g | Cumulative fissions since the start of the schedule, per gram of initial material | fissions/g |
fission.count.neutron_induced_fissions_per_g | The part from library fission (MT=18) rates | fissions/g |
fission.count.spontaneous_fissions_per_g | One per spontaneous-fission decay, including states with no yield data | fissions/g |
fission.count.initial_heavy_metal_atoms_per_g | Atoms with Z ≥ 90 in the declared material | atoms/g |
fission.count.burnup_percent | 100 × fissions ÷ initial heavy-metal atoms; absent without heavy metal | % |
fission.count.burnup_MWd_per_kg_hm | Fissions × energy_per_fission_MeV ÷ initial heavy-metal mass; absent without heavy metal or when a heavy-metal isotope has no mass in the decay data | MWd/kg |
fission.spontaneous_neutron_source.neutrons_per_s_per_g | Σ λ · BR_SF · N · ν̄ at the end of the step | neutrons/s/g |
fission.spontaneous_neutron_source.by_nuclide | The same sum split by nuclide | neutrons/s/g |
fission.spontaneous_neutron_source.uncovered_sf_decays_per_s_per_g | Spontaneous-fission decays of populated states with no ν̄; their neutrons are not in the total | decays/s/g |
The count integrates each step’s fission rate times the evolving population, in the same matrix-exponential
solve family as the inventory, so it is not a rectangle or trapezoid estimate. It is the rate integral and differs from
FISPACT-II’s NUMBER OF FISSIONS, which counts the change in the number of fissionable nuclides. Burn-up is per gram
of the initial material and per kilogram of initial heavy metal; the 200 MeV default of energy_per_fission_MeV is a
stated convention, so state the energy you compare with. The source covers only the states in the decay library that
have both a spontaneous-fission branch and a ν̄; ledger spontaneous_fission.nubar_uncovered names the populated
ones that lack it, and uncovered_to_leakage names the populated ones whose SF branch still goes to leakage for lack
of a yield evaluation.
Kerma heating and power-driven steps
A problem with a kerma section (specification) adds a
kerma block to every step and a power block to every power-driven step. Both are absent otherwise; absence is not
a zero result.
kerma field | Meaning | Unit |
|---|---|---|
heating_W_per_g | Instantaneous nuclear heating at the end of the step: sum_i N_i * k_i * flux_multiplier | W/g |
heating_W_cm3 | The same per volume; present only with material.density_g_cm3 | W/cm3 |
flux_multiplier | The multiplier the heating is evaluated at (a power step’s last sub-interval) | dimensionless |
damage_energy_eV_per_g_s | MT=444 damage-energy production; present only when the table has damage-energy rows | eV/(g s) |
top_contributors[] | The largest contributors by magnitude: nuclide, atoms_per_g, heating_W_per_g, fraction of the total | |
n_contributing_nuclides, other_heating_W_per_g | Nuclides with nonzero heating, and the heating of those not listed | W/g |
covered_atom_fraction | Share of the step’s atoms carried by nuclides with a kerma row; the rest contribute nothing |
Heating comes only from nuclides with a table row, and an element row (Fe) is applied to every isotope and
transmutation product of that element, so a high covered_atom_fraction says the rows exist, not that they are
nuclide-specific. A transmutation product without a row adds no heating, so covered_atom_fraction below one is a
lower bound on the heating, not a zero.
power field | Meaning |
|---|---|
requested_W_per_g, requested_W_cm3 | The target (the second only when it was written in W/cm3) |
tolerance, max_substeps | The kerma.power_tolerance and kerma.max_substeps in force |
substeps, substep_duration_s | Equal sub-intervals the accepted solve used, and their length |
flux_multiplier_per_substep, flux_per_substep_cm2_s | The achieved multiplier in each sub-interval and the resulting total flux (particles cm-2 s-1) |
mean_flux_multiplier | Time-weighted mean multiplier; this is the step’s top-level flux, and drives flux_weighted_time_s and fluence |
max_power_drift | Largest relative departure of a sub-interval’s end power from the request |
converged | max_power_drift <= tolerance. false means max_substeps was reached first; actinv run prints a warning on stderr for each such step |
refinement[] | Each attempt, coarsest first: substeps tried and its max_power_drift |
estimated_flux_multiplier | The start-of-run estimate used for pruning and the burnup-mode choice before the solve |
The ledger’s kerma entry records the table hash, require_complete, the material nuclides without a row (a
composition isotope with no decay record counts as without one: it is not a chain state and heats nothing), for a
table with damage-energy rows damage_energy_uncovered_composition_targets (chain nuclides with a heating row and
no damage row, which add nothing to damage_energy_eV_per_g_s), the heating model and units, and for power runs the number of power steps, total sub-intervals, worst drift and the
step numbers that did not converge. The certificate’s kerma entry carries the table’s provenance and
inputs.kerma_table its computed hash. The schedule ledger’s flux_weighted_time_s and fluence_n_cm2 use the
achieved multipliers of power-driven steps.
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. Since 1.4.0 a transport-tally statistical flux channel can also be requested.
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.
Component waste classes and impurity limits
actinv waste evaluates nominal component inventories against an explicitly
selected U.S. 10 CFR 61.55 rule pack. It reports Class A, B, C, or above Class C
at your selected schedule steps, together with the table fractions that control
the result. actinv waste budget calculates and verifies impurity specifications
for a requested class. actinv waste bounds classifies directly declared
whole-component activity intervals and reports a conservative class superset.
actinv waste component.json component-waste.json
actinv waste budget class-budget.json class-budget-result.json
actinv waste budget uncertainty budget-uncertainty.json budget-uncertainty-result.json
actinv waste bounds activity-bounds.json activity-bounds-result.json
actinv waste composition composition.json composition-result.json
actinv waste composition solve native-composition.json native-composition-result.json
actinv waste intrusion-screen intrusion.json intrusion-result.json
actinv waste uncertainty uncertainty.json uncertainty-result.json
actinv waste package package.json package-result.json
This is a concentration calculation for research and design screening. It does
not determine disposal-site acceptance, waste-form compliance, or intrusion dose.
Nominal classification consumes solver results; the bounds command consumes only
the activity intervals declared in its input. These intervals are deterministic
enclosures, not probability distributions, confidence intervals, covariance
propagation, or evidence that an upstream physical model is qualified. Bounds
are absolute total Bq for the whole component, not concentration. They are
simultaneous rectangular intervals across nuclides; all combinations in the box
are admitted. The command does not infer time evolution between target steps or
derive bounds from a RunResult. The separate intrusion-screen command applies
the selected draft screen to nominal inventories.
From Python the same commands are actinv.waste.classify, budget, bounds, composition, composition_solve,
intrusion_screen, uncertainty, budget_uncertainty and package, and actinv.twin; they return the CLI’s result. See Python.
Classify declared waste components in a facility twin
actinv twin can optionally add nominal Part 61 classifications for components
that already group mesh cells. This uses the original mesh activities and the
same actinv waste evaluator; cell assay, mixture, propagated and dose updates
change the twin’s certified-band results, but do not change the waste
classification. Each component needs an explicit mass, either a displaced
volume or density, its waste type, and cell masses that match its existing twin
group and close to the component mass. ACTINV does not infer mass or volume from
mesh geometry.
{
"spec": "actinv-twin-1",
"mesh_output": "facility-mesh.ndjson",
"limits": [{"name":"heat","response":"heat.total","limit":2.0}],
"components": {"primary": ["cell-1", "cell-2"]},
"waste": {
"schema": "actinv-twin-waste-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"targets": [1, 2],
"nuclide_properties": {
"C14": {"z":6,"half_life_s":1.808e11,"alpha_emitting":false}
},
"components": {
"primary": {
"mass_g": 2.0,
"displaced_volume_cm3": 1.5,
"waste_type": "general",
"cell_masses_g": {"cell-1":0.5,"cell-2":1.5},
"external_tritium": {"status":"not_applicable"}
}
}
}
}
The components groups remain the only source of cell membership; names must
match the waste components, groups cannot overlap, and each cell_masses_g
map must contain exactly that group’s cells. Selected steps must exist in each
cell, and timestamps within a component must match exactly. External H-3 is
declared separately and counted once. Missing active-nuclide properties or
required-but-undeclared H-3 preserve an unknown/conditional nominal result.
The twin output adds waste_classification, an ordinary
actinv-waste-result-1 document with per-component, per-target margins and
constraints, and waste_facility_coverage, which lists assigned and unassigned
mesh cells and counts separate component classes at each requested step. The
summary does not combine components into a package class or determine disposal
acceptance. This classification is nominal screening only; upstream physical
reaction and decay completeness remains a separate question.
Screen a whole container against the fusion draft
actinv waste intrusion-screen evaluates the February 2026 draft NUREG-1556
Volume 22 Table 8-5. Select this draft explicitly with
us-nrc-nureg1556-v22-draft-2026-02-v1. The result keeps the complete nominal
Part 61 classification and a separate draft_intrusion_screen. It reports
review_indicated, indeterminate, or
not_indicated_by_implemented_checks; it does not calculate intrusion dose or
determine legal compliance or disposal acceptance.
Embed one ordinary waste specification representing the whole disposal container. Its input result path resolves relative to this outer document. Native run activities are multiplied by component mass; mesh cell activities are weighted by each cell’s mass before aggregation. External H-3 is added once. The following quantities and properties are artificial examples:
{
"schema": "actinv-waste-intrusion-screen-spec-1",
"draft_rules": "us-nrc-nureg1556-v22-draft-2026-02-v1",
"package_basis": "single_component_container",
"waste_form": "equipment",
"inventory_coverage": "complete",
"unbounded_inventory_reasons": [],
"waste_spec": {
"schema": "actinv-waste-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"input": "component-result.json",
"targets": [2],
"nuclide_properties": {
"C14": {"z": 6, "half_life_s": 315576000, "alpha_emitting": false}
},
"components": [{
"id": "whole-container",
"mass_g": 1000,
"displaced_volume_cm3": 128.2,
"waste_type": "general",
"external_tritium": {"status": "not_applicable"}
}]
},
"site_wac": {
"source": "artificial site-WAC example",
"membership_coverage": "complete",
"nuclides": {
"C14": {"status": "listed", "limit": {"value": 100, "unit": "nCi/g"}}
}
},
"dot_rq": {
"source": "artificial caller-declared RQ example",
"coverage": "complete",
"nuclides": {"C14": 40000}
}
}
Site WAC and whole-activity DOT RQs are optional caller declarations. The command
supplies no default WAC or RQ catalog. WAC entries can also declare
listed_no_numeric_limit or unlisted; missing entries in an incomplete map
remain unknown. RQs are positive finite Bq. An individual activity at its RQ is
present; a mixture ratio at or above one does not by itself settle each
below-RQ contributor’s presence. The result preserves all four presence
predicates and their supporting quantities, including unresolved source inputs.
inventory_coverage: "complete" declares that the whole container inventory is
accounted for; ACTINV cannot verify that physical claim. Use incomplete or
unknown with nonempty reasons when inventory is missing. Required undeclared
H-3 or missing properties also leave the total-container denominator unknown.
The 1% activity-share test never uses a known subtotal as a complete container.
metal form requires activated_metal; the other forms use general.
Rows use the computed nominal A/B/C column. Unknown and above-Class-C inventories have no selected column. The strict less-than-five-year sum includes matching named nuclides, while the alpha row uses only its printed eight members. Printed no-limit cells remain explicit; row equality is indeterminate. The literal draft values include Cs-137 Class C at 460 Ci/m³ and activated-metal Nb-94 at 0.2/0.2/2 Ci/m³. These differ from Part 61 and remain separate in the result.
The screen accepts 1–64 selected steps, at most 128 mesh cells, and at most 1024 properties, WAC entries, RQs and positive nuclides per target. Input files must be regular files: the outer document is limited to 8 MiB and the result input to 64 MiB. Duplicate keys, duplicate normalized nuclide identities, nonfinite arithmetic and outputs above 32 MiB are refused before writing a result.
Classify declared composition ranges
actinv waste composition projects caller-supplied fixed-rate affine
pure-element responses over an explicitly bounded natural-element composition
whose coordinates sum to exactly 100 wt%. It does not generate those responses,
run activation, read a nuclear-data library, or infer that rates are physically
linear. The caller must establish that the responses apply under common fixed
conditions and state their basis in each target’s source and assumptions.
Responses are Bq/g for a 100 wt% pure constituent; projected whole-component
activities are Bq after multiplying by the fixed component mass. Geometry and
waste type are fixed across the declared composition range.
The input schema is actinv-waste-composition-spec-1; only the bundled
us-nrc-10cfr61.55-v1 rule pack is accepted. Composition keys are canonical
natural-element symbols, and each target gives a response map for every
constituent. An omitted nuclide within a constituent’s explicit map means zero
only under that caller-declared model. Coverage remains an independent caller
declaration. Each nuclide is projected separately, so the P107 activity box
loses cross-nuclide correlation and its ordered class envelope is a conservative
superset that can contain unattainable classes. The result does not report
probabilities, confidence levels, covariance propagation, automatic physical
uncertainty, disposal acceptance, or intrusion dose.
This artificial example uses a pure-Nb C-14 response of 74,000 Bq/g. With component mass 1 g and volume 1 cm³, Nb can occupy 20–60 wt%; Si is fixed at 10 wt%, and Fe closes the exact 100 wt% total. The resulting C-14 activity range is 14,800–44,400 Bq, corresponding to 5–15% of the applicable Table 1 limit.
{
"schema": "actinv-waste-composition-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"response_model": "fixed_rate_affine_activity",
"components": [{
"id": "artificial-alloy",
"mass_g": 1,
"displaced_volume_cm3": 1,
"waste_type": "general",
"nuclide_properties": {
"C14": {"z": 6, "half_life_s": 315576000, "alpha_emitting": false}
},
"external_tritium": {"status": "not_applicable"},
"composition_wt_percent_bounds": {
"Si": {"lower_wt_percent": 10, "upper_wt_percent": 10},
"Nb": {"lower_wt_percent": 20, "upper_wt_percent": 60},
"Fe": {"lower_wt_percent": 30, "upper_wt_percent": 70}
},
"targets": [{
"step": 1,
"t_s": 0,
"element_activity_bq_per_g": {
"Si": {},
"Nb": {"C14": 74000},
"Fe": {}
},
"inventory_coverage": "complete",
"unbounded_inventory_reasons": [],
"bounds_source": "artificial declared pure-element response",
"bounds_assumptions": "fixed-rate affine model; coefficients are not generated by ACTINV"
}]
}]
}
The actinv-waste-composition-result-1 result records both the original input
SHA-256 and the SHA-256 of the canonical projected P107 bounds input. Each
target carries the canonical response coefficients, per-nuclide lower/upper
activity projections, feasible minimum/maximum witness compositions and dual
multipliers, plus the complete flat P107 endpoint, row, constraint, coverage,
binding and class-envelope fields. External H-3 is passed unchanged to the P107
evaluator and added once. Invalid input is fully checked before the output file
is written.
Generate and verify a native composition basis
The native composition path passed its artificial fixed-rate basis and selected- witness control suite (P110: nine cases, 18 targets and 36 endpoints).
actinv waste composition solve generates pure-element responses by running
ACTINV, projects them over a bounded natural-element composition whose
coordinates sum to exactly 100 wt%, then runs every distinct projection witness
and a canonical feasible reference. This adds native basis generation and
selected-point verification to the caller-declared composition workflow. It
does not prove physical completeness, bound CRAM or solver error, establish
nuclear-data accuracy, or determine disposal acceptance. Selected witness
agreement does not prove that every solver value lies within the arithmetic
projection box.
The actinv-waste-composition-solve-spec-1 schema uses the bundled Part 61
rule pack. Each component supplies an actinv-spec-1 base_spec (embedded
object or file path), component mass and exactly one geometry denominator,
waste type, external-tritium declaration, composition_wt_percent_bounds
coordinates, selected one-based result steps, inventory coverage declaration
and reasons, plus model source and assumptions. ACTINV replaces the base
material composition for each pure-element run and fixes the requested
component mass. The command enforces the P75b-qualified natural-element set
Al, B, C, Ca, Co, Cr, Cu, Eu, Fe, H, K, Mg, Mn, Mo, N, Na, Nb, Ni, O, P, S, Si, Ta, Ti, V, W and supported fixed-rate neutron features. It refuses unsupported nonlinear
options and duplicate JSON keys. A request may contain at most four components,
eight elements and four target steps per component, 32 pure-element runs, and
64 distinct full witness compositions. The wrapper and each path-based base
spec are limited to 8 MiB; a final result is limited to 32 MiB. Unsupported
features include non-neutron projectiles, feed/removal/per-step spectra,
screening, uncertainty, shielding and radiological/damage extensions, scale
overrides, gas output, fission-count and spontaneous-fission options,
non-default photon settings, and CRAM orders other than 16.
The element set comes from P75b’s tested mixtures. Its superposition results apply to the tested neutron spectra and schedules; passing these witness checks does not extend that physical qualification to new conditions.
For a path base_spec, that path resolves relative to the wrapper JSON file.
Paths inside the base spec, including nuclear-data references, retain ordinary
ACTINV current-working-directory and catalog resolution. A PreparedRun is
reused for the basis and witness runs of that component. External H-3 remains
a separate whole-component Bq interval and is added once to the waste
evaluator; the command infers no permeation model.
The result preserves the P108 projections and adds solver certificates and audit evidence for each pure-element basis and verified witness. Activity responses use Bq/g, whole-component class inputs use Bq, composition weights use wt%, and atom inventories use atoms/g. Coverage defects downgrade selected targets to unknown while retaining known-subset calculations. The exact generated P108 document is embedded for reuse. These deterministic calculations do not claim probability or propagated uncertainty.
{
"schema": "actinv-waste-composition-solve-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"components": [{
"id": "declared-alloy",
"base_spec": "activation-base.json",
"mass_g": 1,
"displaced_volume_cm3": 1,
"waste_type": "activated_metal",
"external_tritium": {"status": "not_applicable"},
"composition_wt_percent_bounds": {
"Fe": {"lower_wt_percent": 40, "upper_wt_percent": 80},
"Nb": {"lower_wt_percent": 20, "upper_wt_percent": 60}
},
"targets": [1, 2],
"inventory_coverage": "complete",
"unbounded_inventory_reasons": [],
"model_source": "declared fixed-rate material envelope",
"model_assumptions": "composition fractions form one exact 100 wt% mixture"
}]
}
Here the two weight bounds jointly admit a 100 wt% mixture. The command checks exact binary-float feasibility rather than normalizing an infeasible box.
Classify declared activity bounds
The bounds input schema is actinv-waste-bounds-spec-1. It accepts only the
bundled us-nrc-10cfr61.55-v1 rule pack. Each component declares its fixed
geometry and waste type, nuclide properties, external-tritium status, and one
or more target records. The example uses artificial C-14 values to show the
shape; replace the source and assumptions with the basis for your declared box.
{
"schema": "actinv-waste-bounds-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"components": [{
"id": "example-component",
"mass_g": 1000,
"displaced_volume_cm3": 128.2,
"waste_type": "general",
"nuclide_properties": {
"C14": {"z": 6, "half_life_s": 180808200000, "alpha_emitting": false}
},
"external_tritium": {"status": "not_applicable"},
"targets": [{
"step": 1,
"t_s": 0,
"activity_bounds_bq": {
"C14": {"lower_bq": 100, "upper_bq": 200}
},
"inventory_coverage": "complete",
"unbounded_inventory_reasons": [],
"bounds_source": "illustrative declared enclosure",
"bounds_assumptions": "artificial input; not measured or probability-based"
}]
}]
}
Run it with actinv waste bounds activity-bounds.json. An omitted output path
writes JSON to standard output. The actinv-waste-bounds-result-1 result records
the exact input SHA-256 and rule-pack identity, component geometry and metadata,
activation-only and external-tritium intervals, and the merged evaluated
intervals. Each target includes lower and upper endpoint evaluations, every
Table 1 and Table 2 column constraint, row-fraction ranges, the ordered
class_envelope, conservative_superset, class_is_stable, and stable_class.
The class range is a conservative superset; intermediate
classes are not asserted to be feasible.
inventory_coverage: "complete" is an explicit caller declaration that omitted
nuclides are zero; ACTINV cannot verify its physical truth. Incomplete coverage,
required external tritium, or missing properties for any nuclide with positive
upper activity produce an unknown class envelope, while preserving known-subset
endpoint arithmetic. A bounded external-tritium declaration must identify its
source, set excludes_activation to true, and provide a whole-component Bq
interval for every selected step. The tool adds its lower bound to the
activation lower bound and its upper bound to the activation upper bound once.
An entirely zero merged inventory is stable Class A only with complete coverage
and an explicit external-tritium declaration.
For the bounds command, a bounded external-tritium declaration has this shape
(a fragment to replace the component’s external_tritium object):
{
"status": "bounded",
"source": "retention enclosure or measurement reference",
"excludes_activation": true,
"activity_bounds_bq": {
"1": {"lower_bq": 100000, "upper_bq": 200000}
}
}
The example quantities are illustrative. Supply exactly the selected step keys
and fixed H-3 properties whenever its upper activity is positive. Use
{"status": "required"} when a needed contribution is unavailable; the whole
box then remains unknown. Stability always depends on the declared box being
valid; it does not establish that every physical uncertainty is covered.
Classification under nuclear-data uncertainty
actinv waste uncertainty SPEC.json [OUT.json] asks how likely each class is when the nuclear data are uncertain. It
solves your problem once at its nominal inputs and then once for each correlated draw of the sampled channels, the
sampler that study.robustness uses (correlated MF=33 cross-section draws with the collapsed relative covariance, any
indefinite correlation structure repaired; decay constants and fission yields at their declared uncertainties; and
optionally flux and composition). Every solve carries a consistent inventory, so each sample is classified with the nominal
evaluator and the table sums keep their correlations. The first-order uncertainty block cannot give a band on a
table sum, because it reports no covariance between nuclides.
{
"schema": "actinv-waste-uncertainty-spec-1",
"problem": "fns-iron.json",
"rules": "us-nrc-10cfr61.55-v1",
"targets": [3, 5],
"nuclide_properties": "from_decay_data",
"components": [{
"id": "first-wall-plug",
"mass_g": 1000,
"density_g_cm3": 7.8,
"waste_type": "activated_metal",
"external_tritium": {"status": "not_applicable"}
}],
"sampling": {
"channels": {"cross_section_mf33": true, "decay_constants": true},
"covariance": {"path": "catalog:tendl-2025-neutron-709g-covariance"},
"samples": 512,
"seed": 20261016,
"keep_samples": "samples"
},
"confidence_level": 0.95
}
problem is an actinv-spec-1 file, relative to this one; rules, targets and components are those of the
nominal waste command, with exactly one component and no mesh cells, and the declared H-3 of external_tritium is
added to every sample without being sampled. nuclide_properties is either the object of actinv-waste-spec-1 or the
string "from_decay_data", which derives the properties from the decay data for every nuclide with positive activity
at a target step in the nominal run or any sample. sampling.channels and sampling.covariance are the objects of
study.robustness (cross_section_mf33, flux_rel_std, composition_rel_std, decay_constants,
fission_yields), samples is at least 20 and at most 4096, and confidence_level defaults to 0.95. With
keep_samples, each sample’s perturbed problem and result are written to that folder as rob_<i>.json and
rob_<i>.out.json, byte for byte what a study.robustness run with the same channels, sample count and seed writes,
apart from the wall-clock ms of each solve.
The command refuses, and writes nothing, when the problem enables gas production, switches library or projectile
during the schedule, has power-driven or wall-loading steps, a per-step spectrum or partition, or an uncertainty
block; when no channel is enabled; when samples is below 20; for a confidence level outside (0, 1); and for unknown
keys or another schema.
The actinv-waste-uncertainty-result-1 result gives, per component and target step:
nominal: the target asactinv wastereports it.samplesandfailed_samples([{sample, error}]). A sample whose solve or classification fails counts in every denominator as classunknown, so a failure can only weaken a class.classes:count,probabilityand a two-sided Clopper-Pearson interval (lower,upper) atconfidence_levelforA,B,C,above_class_candunknown; andat_most_class: the same for P(class at most X), X =A,B,C,above_class_c.established_classandneeded_samples. The classes are ordered A, B, C, above Class C. The established class is the first one for which the lower end of the interval of P(class at most X) is at least the confidence level. Even when every sample agrees this needs (α/2)^(1/n) ≥ 1 − α, which is at least 72 samples at confidence 0.95 (minimum_samples_for_establishmentstates the number for your level). When nothing is established the result isnot_established, andneeded_samplesgives, for the first class whose observed cumulative frequency exceeds the level, the smallest sample count (up to 1 000 000) at which that frequency would establish it, or says that the observed frequency cannot establish a class.constraints: for each table constraint (target_class,table,column) the 5th, 50th and 95th nearest-rank percentiles of the normalized sum (the class boundary is 1) over the samples with an inventory, and the count and fraction above 1.
Per component, earliest_established_step names the earliest target step at which each class is the established
class. The coverage block lists channels_sampled, the MF=33 rows, decay constants and yields the sampled channels
left uncovered (by name), the nominal run’s completeness ledger (recorded when the problem lists audit in
options.outputs) and a fixed statement of what the probabilities do not include.
The probabilities are conditional on the sampled channels. They exclude MF=32 and MF=40 covariance, correlation between channels, composition, geometry, model and flux-systematic uncertainty, except where a listed channel samples it, and measured coverage of these channels on the FNS corpus is below nominal (see Data limitations), so the intervals can be overconfident. They are not tolerance limits, a budget at a confidence level, a package class or a disposal acceptance.
Describe a component
The input is an existing actinv run result or actinv mesh NDJSON file. Select
the bundled rules by its id (us-nrc-10cfr61.55-v1) or give a path to a custom
rule-pack JSON file relative to the waste document. Specify
the component mass and displaced volume: its envelope with major voids removed.
Alternatively, provide mass and density to use the conservative solid-volume
basis. For a mesh, list each member cell and its mass. The command adds cell
activities before dividing by the component denominator; cell concentrations
are never averaged without their masses.
For example, a single-run classification document is:
{
"schema": "actinv-waste-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"input": "component-result.json",
"targets": [2, 3],
"nuclide_properties": {
"Nb94": {"z": 41, "half_life_s": 100000000000, "alpha_emitting": false}
},
"components": [{
"id": "synthetic-component",
"mass_g": 1000,
"displaced_volume_cm3": 128.2,
"waste_type": "activated_metal",
"external_tritium": {"status": "not_applicable"}
}]
}
The properties above are artificial values illustrating the format. Supply source-appropriate properties
for every active nuclide in your result: half-life and alpha-emitter status decide
membership in aggregate categories. Missing properties produce an unknown class.
Use general when activated-metal limits do not apply. targets are one-based
result step numbers, so each identifies an actual calculated time.
Include retained tritium
Fuel permeation and retention can add H-3 that the activation calculation does not model. Declare it separately for each component and selected step:
{
"status": "declared",
"source": "retention calculation or measurement reference",
"excludes_activation": true,
"activity_bq": {"2": 120000, "3": 110000}
}
These are additional whole-component activities in Bq. The declaration must
exclude the activation H-3 already in the inventory; ACTINV adds the declared
activity to any calculated H-3 in that component. Use required when an
external contribution is needed but unavailable; the result then reports an
unknown class alongside the calculated-only class. Declare not_applicable
explicitly when there is no external contribution.
Set a class impurity budget
A budget document uses schema: "actinv-waste-budget-1", a base_spec naming
an existing run specification by path or embedding that specification object, a
balance element, fixed matrix constituents and impurities in wt%, and
targets. Add target_class as A, B, or C, the selected rules, component
geometry, waste_type, properties and external-tritium declaration. Budget
constituents are natural-element symbols; the budget-level external-tritium
declaration uses the same status choices and maps each selected step to a
whole-component activity in Bq.
The command solves each element, intersects every applicable table constraint across all target times, and re-solves each usable limit and joint specification margin with the full material. It reports the binding table, column and step. An open mixture boundary has a supremum and an interior verified composition; the supremum is not an attained maximum. Composition bounds, infeasible cases and absence of a positive response are reported explicitly.
actinv waste budget writes its result even when a verification point misses; the verification block shows the
miss and the command exits 3 (verified false). Refused input still exits 1 and writes nothing.
Budgets require fixed rates and coupled mode with reach pruning. Self-shielding, uncertainty, composition-dependent screening and schedule feed are refused. Nominal classification may consume other supported run configurations, but that does not make their composition responses linear.
The reference pack follows 10 CFR 61.55. Single-nuclide equality is accepted where the regulation says “does not exceed”; mixture sums use its strict less-than rule. Separate tables remain separate constraints, and entries with no Class B/C limit retain the rule’s Class B fallback. The selected pack and its interpretation are recorded in each result.
Budgets under nuclear-data uncertainty
actinv waste budget uncertainty SPEC.json [OUT.json] asks how large an impurity can be when the nuclear data are
uncertain. The nominal budget above solves each element once and gives, per impurity, the supremum of its weight
percent for which every table constraint at every target stays inside the target class. Each correlated draw of the
data gives its own element responses and therefore its own supremum. The command draws the sampled channels once per
sample, from the sampling plan of the full budget material, and applies the same factors (cross-section rate scales,
decay-constant scales, yield scales and flux factor) to every element solve of that sample, so the element responses
of one sample come from one data set. It then applies the nominal interval algorithm to each sample’s responses.
An impurity level x keeps the class in a fraction F(x) of data draws. The budget at confidence γ is the k-th smallest per-sample supremum, with k the largest index for which the lower end of the two-sided Clopper-Pearson interval at γ of (n − k + 1)/n is at least γ. Any x below it keeps the class with probability at least γ, at confidence γ, as long as the samples represent the data uncertainty. This is the order-statistic (Wilks) tolerance bound: it is exact for any distribution of the supremum and needs no normality and no first-order expansion. It is reported as an open bound, not an attained maximum. The same k applies to every impurity and to the joint specification scale factor.
Some sample count is needed before any budget exists. With k = 1 the bound is the smallest supremum, which needs
(α/2)^(1/n) ≥ γ: 72 samples at confidence 0.95. A spec with fewer samples is refused, and the refusal names the
minimum (order_statistic.minimum_samples states it for your level).
{
"schema": "actinv-waste-budget-uncertainty-spec-1",
"budget": "class-budget.json",
"confidence_level": 0.95,
"sampling": {
"channels": {"cross_section_mf33": true, "decay_constants": true, "flux_rel_std": 0.05},
"covariance": {"path": "catalog:tendl-2025-neutron-709g-covariance"},
"samples": 200,
"seed": 146001,
"keep_samples": "samples"
}
}
budget is the path of an actinv-waste-budget-1 document, relative to this file, or that document embedded.
sampling is the block of actinv waste uncertainty: samples from 20 to 4096, a seed, the channels and
covariance of study.robustness, and an optional keep_samples folder, relative to this file. The composition
channel is refused, because composition is what the budget solves for. The command also refuses everything
actinv waste budget refuses, and a base spec that enables gas production, declares its own rate, decay or yield
scales, or switches library, projectile or spectrum during the schedule. Every refusal is made before any solve, and
nothing is written.
The actinv-waste-budget-uncertainty-1 result carries:
nominal: the completeactinv waste budgetresult, unchanged.order_statistic:k,nandminimum_samples.quantities: one entry per impurity and one forjoint_scale_factor, with the unit (wt_pctorscale_factor), thestatus, thebudget, thenominal_supremumfor comparison, the per-sample suprema (suprema_by_sample,suprema_sorted),sample_statuscounts (bound,capped,failed,infeasible,no_response) and thebinding_tally: how many samples were bound by each table, column and step. A sample whose solve fails or whose interval is infeasible counts as a supremum of 0, so it can only lower the budget. A supremum limited only by the balance (no constraint binds) iscappedand enters the order statistic at the cap.status:established,not_establishedorunbounded. The order statistic bounds the upper end only. When the nominal budget, or any sample, has a positive lower bound for an impurity (the class needs at least some of it), the budget isnot_establishedwith reasonpositive_lower_boundand the count of such samples; two-sided budgets are not claimed. An impurity with no response in any constraint isunbounded.verification: for each established quantity, the samples at sorted ranks k − 2 to k + 2 are re-solved with the full material, the impurity (alone, the others at specification) or the joint scale factor at 0.99 and 1.01 times that sample’s own supremum and with that sample’s own factors, and classified with the waste evaluator; every sample at rank k or above is re-solved at 0.99 times the reported budget. A row records the classes at the target steps and whether they are all at most the target class.verification_passis true when each 0.99 point is inside the class and each 1.01 point is outside it. The command exits 3, after writing the result, when it is false.failed_samples,coverage(the channels sampled, the inputs they left uncovered and a fixed statement) andnot_claimed.
With keep_samples, each sample writes sample_NNNN.json: its factor block, each element’s solved activities and
class-constraint sums with the factors actually applied to that solve, and the sample’s intervals.
The budgets are conditional on the sampled channels, and each sample assumes the activation response is linear in composition, as the nominal budget does. Composition, geometry and model uncertainty are not sampled. Measured coverage of these channels on the FNS corpus is below nominal (see Data limitations), so a budget can be optimistic. A budget is not a composition tolerance, a procurement specification, a package class or a disposal acceptance.
Classify a package of discrete items
actinv waste package SPEC.json [OUT.json] classifies one disposal container that holds several discrete items, such
as activated steel pieces of different sizes, a sealed source or a cartridge filter, under the NRC Concentration
Averaging and Encapsulation Branch Technical Position (Revision 1, Volume 1, February 2015; ADAMS ML12254B065; “BTP”
below). actinv waste classifies one component on its own concentrations. A container of mixed items cannot simply
be averaged: the BTP limits how concentrated an individual item may be before it has to be taken out of the average,
how small items and sectioned components are grouped, and how much credit encapsulation earns. Homogeneous
(blendable) waste is not covered. The BTP’s Tables 2 and 3 and its thresholds are bundled as
us-nrc-ca-btp-2015-rev1-v1; the Part 61 limits come from the same rule pack as actinv waste. “BTP Table n” and
“CFR Table n” (10 CFR 61.55) are different tables throughout.
An item has an id, a BTP waste type (activated_metal, contaminated_material, design_radioactivity_component,
sealed_source or cartridge_filter), a mass in g and a volume in cm3: the displaced volume (envelope with major voids
removed), or for a cartridge filter the envelope volume (BTP Table 4). Its activity is either taken from an ACTINV run
result (the per-gram activities at each target step times the item mass; a mesh result needs cells as in
actinv waste) or declared as whole-item Bq by nuclide and step, which suits a sealed source or a measurement.
{
"schema": "actinv-waste-package-spec-1",
"rules": "us-nrc-10cfr61.55-v1",
"targets": [2, 3],
"screen": "none",
"nuclide_properties": {
"Nb94": {"z": 41, "half_life_s": 640000000000, "alpha_emitting": false},
"Cs137": {"z": 55, "half_life_s": 951000000, "alpha_emitting": false}
},
"items": [
{"id": "plug-1", "waste_type": "activated_metal", "mass_g": 7800, "displaced_volume_cm3": 1000,
"activity": {"result": "plug-result.json"}},
{"id": "rod-a", "waste_type": "activated_metal", "mass_g": 780, "displaced_volume_cm3": 100,
"section_of": "rod-7", "activity": {"result": "rod-result.json"}},
{"id": "rod-b", "waste_type": "activated_metal", "mass_g": 780, "displaced_volume_cm3": 100,
"section_of": "rod-7", "activity": {"result": "rod-result.json"}},
{"id": "source-1", "waste_type": "sealed_source", "mass_g": 400, "displaced_volume_cm3": 60,
"activity": {"declared_bq": {"2": {"Cs137": 150000000}, "3": {"Cs137": 148000000}}}}
],
"encapsulation": null
}
rules, targets and nuclide_properties are those of actinv waste. btp is optional: the bundled id (the
default) or the path of an actinv-waste-btp-1 file, relative to the spec. screen is none (the default),
activity_37mbq or highest_item. section_of names the original component an item was cut from. The command refuses,
and writes nothing, for another schema, an unknown waste type, a missing or non-positive mass or volume, duplicate ids,
no items, a section_of whose pieces differ in waste type or are alone in the package, an unknown screen, a declared
activity step that is not a target, and the encapsulation inputs described below.
What the command does at each target step
- Items are grouped by waste type (BTP 3.4). Each item alone is evaluated with the nominal Part 61 evaluator, which gives its own class and its concentrations. Within a group the command averages all items over their summed volume and mass, finds the more restrictive of CFR Table 1 and 2 (the one giving the higher class; on a tie the larger sum of fractions) and decides whether the primary gamma emitters Co-60, Nb-94 and Cs-137 are classification-controlling: more than 50 % of that table’s sum of fractions (BTP p.25).
- For each candidate class X from A to C, every item is tested against the limits of X:
- Primary gamma emitters. The item passes if its sum of fractions against BTP Table 2 is at most 1, or if each primary gamma of concern meets the Factor of 2 (controlling) or the Factor of 10 (not controlling) against the class limit of X. Items of 280 cm3 or more use their own sum; items under 280 cm3 share one sum over their summed inventory, and the pool passes or fails as a whole. The result records which limit each item met.
- Other radionuclides of concern. H-3, C-14, Ni-59 and Ni-63 pass BTP Table 3 or the Factor of 10, nuclide by nuclide. The alpha-emitting transuranics with half-life above 5 years (excluding Pu-241 and Cm-242) are one entry per item: their summed activity against BTP Table 3, or their summed concentration against the Factor of 10 of the CFR Table 1 transuranic row. Nuclides outside Tables 2 and 3 use the Factor of 10 only.
- Failing items are removed from the average and classified alone (BTP 3.3.1). The remaining items are classified on their volume- and mass-averaged concentrations; call that class Y. X qualifies when Y is not above X. The class of the group is the lowest qualifying X, reported as X because the items were tested at X’s limits; if none qualifies the group is above Class C. All three candidates are listed in the result.
- Pieces of one sectioned component in the package are treated as that component (BTP 3.3.2.3) when no piece exceeds
BTP Table 3 and no piece under 280 cm3 exceeds BTP Table 2. Pieces that do are separate items, and the result
lists them as
split_out. The test uses the BTP columns of each candidate class X, so the merge can differ between candidates; the step reports the sections of the chosen candidate. Item tests name a merged component by itssection_ofid. - The package class is the highest class of any group and of any item classified alone (BTP 3.4). An item left out of the average therefore still counts.
The two optional screens (BTP 3.3.2.1) replace step 2. With activity_37mbq, a group whose items each have a total
activity below 37 MBq is classified on the average of the whole group; otherwise the item tests run. With
highest_item the group takes the highest class of any one item.
Readings fixed in advance
The BTP is silent or ambiguous in places. The readings below were fixed before the implementation (protocol P147) and are stated in every result. They are choices made here, not statements of what the BTP says.
- The volume limit for encapsulation is 331 ft3 = 9.373 m3, the value common to the BTP text (9.5 m3), Figure 5 and Volume 2 (9.4 m3). A waste loading of at least 14 % qualifies.
- The class limit in the Factors of 2 and 10 is that of the class being tested: 0.1 times the CFR Table 1 value for Class A and B and the Table 1 value for Class C, or the CFR Table 2 column of that class. Where the column has no limit (Co-60, H-3 and the under-5-year group in Classes B and C) the factor test does not apply to that nuclide in that class, and the BTP is not cited for it.
- A radionuclide of concern exceeds 1 % of its class limit for the class being tested.
- The 37 MBq screen uses the total activity of the item, strictly less than 37 MBq.
- An item of exactly 280 cm3 is individual for BTP Table 2.
- A Factor test passes below the factor times the limit (strictly); a BTP Table 2 sum of fractions passes at 1 or less and a BTP Table 3 activity at the table value or less.
- The waste loading is the sum of the encapsulated items’ volumes over the total encapsulated volume, unless the waste volume is declared. The 0.2 m3 cap applies to volume-based limits and the 500 kg cap to mass-based limits.
Encapsulation
Add an encapsulation block to describe one encapsulated container; every item is then encapsulated:
"encapsulation": {"total_volume_cm3": 500000, "encapsulant_mass_g": 900000,
"encapsulant_density_g_cm3": 2.0, "waste_volume_cm3": null}
The item tests of step 2 apply unchanged to the items. The credited volume and mass then follow BTP 3.3.4. With a
loading of at least 14 % and a total volume of at most 331 ft3, the average is taken over the whole encapsulated
volume and over the item mass plus the encapsulant mass. With a lower loading, the credited volume is at most 0.2 m3
and the credited mass at most 500 kg, and never more than the actual volume or mass. A loading of at least 14 % in a
container above 331 ft3 gets no credit (alternative_approach_required, no class). The encapsulant mass is credited at
a density of at most 2.5 g/cm3. Separately, the activity of all items averaged over the waste and the whole encapsulant
must not exceed Class C (exceeds_class_c_cap otherwise). An encapsulated container is one waste form, so its items
form one group whatever their waste types. When they mix activated metal with other types, the group is evaluated,
item tests included, under both the activated-metal and the general rule rows (groups
encapsulated_activated_metal_rules and encapsulated_general_rules) and the higher class is kept. An item that fails
its tests is classified alone, without encapsulation credit. waste_volume_cm3 overrides the summed item volumes. The command refuses a non-positive field,
a waste volume above the total volume (a loading above 1), an encapsulation block together with an item flagged
"encapsulated": false (encapsulated and unencapsulated items do not share a package), and a screen other than none.
Result
The actinv-waste-package-1 result holds the SHA-256 of the spec, the rule pack and the BTP data, and for every
target step: the package class and status, each item (volume, mass, total activity, own class, activities), the
sectioned components, each group’s sums of fractions for both CFR tables, the restrictive table, the primary gamma share
and whether it controls, every candidate with its small-item pool, per-item tests and limit met, removed items,
remainder class, volume and mass, and the encapsulation block (waste volume, loading, credited volume and mass,
status, class and the Class C cap). An item with a nuclide that has no properties makes its group and the package
unknown, and the group lists those items. Alongside are the readings, the implementation choices and the list of what
is not claimed.
The result is consistent with the BTP only under the readings above, and only where the disposal site’s licence adopts the BTP; the site’s licence conditions override it. It is not a classification for shipment or a disposal acceptance, and it does not cover blending of homogeneous wastes (BTP 3.2), alternative approaches (BTP 3.8), 10 CFR 61.58 authorizations or exemptions, structural stability under 10 CFR 61.56, centring procedures, compatibility documentation or the encapsulation topical reports.
Clearance against national tables
actinv clearance certifies the clearance index at one step, per cell or for one run result, against the IAEA 2004
table (RS-G-1.7) unless you choose another. --jurisdiction de, uk or ca evaluates the same statistic, the sum of
activity over limit with its certified probability, against the legal text of Germany, the United Kingdom or Canada.
--jurisdiction iaea is the default. A jurisdiction cannot be combined with --limits. The tables are copies of the
laws, not official versions, and choosing a table, a route and the conditions attached to a clearance decision is yours.
--jurisdiction | Table | Limit used | Routes (--route) |
|---|---|---|---|
de | Strahlenschutzverordnung (StrlSchV 2018), Anlage 4 Tabelle 1, as last amended by Art. 10 G v. 23.10.2024 | Bq/g, with Tabelle 2 for the daughters | unrestricted-clearance (default), rubble-gt-1000-mg-a, soil, landfill-le-100-mg-a, incineration-le-100-mg-a, landfill-le-1000-mg-a, incineration-le-1000-mg-a, scrap-metal-recycling |
uk | Environmental Permitting (England and Wales) Regulations 2016, Schedule 23 Part 3, Table 2 “Concentration of radionuclides” | Bq/g, solid or relevant liquid | table-2-solid-or-relevant-liquid |
ca | Nuclear Substances and Radiation Devices Regulations (SOR/2000-207), Schedule 2 “Unconditional Clearance Levels” | Bq/g | unconditional-clearance |
Germany: column 3 of Tabelle 1 is both the Freigrenze as specific activity and the level for unrestricted clearance of
solid and liquid material. The route columns are the specific clearance of building rubble over 1000 Mg/a (column 6),
soil areas (7), landfill and incineration up to 100 Mg/a (8, 9) and up to 1000 Mg/a (10, 11), and scrap metal for
recycling (14). A blank cell means the table has no value for that nuclide in that column, so the nuclide is reported
in not_listed for that route. The surface columns in Bq/cm2, the total-activity Freigrenze and the HRQ and half-life
columns are not evaluated. The regulation lets nuclides be left out of the sum when they are at most 10 percent of it;
ACTINV does not apply that allowance. A parent marked + includes the daughters of Tabelle 2. Where a nuclide has a plain and a + row, each column uses the smaller value.
United Kingdom: the regulation calls Table 2 the concentration table referred to in paragraphs 5 and 6 of Part 2, not a
clearance table, and its catch-all row (0.01 Bq/g, or a dose-based concentration, for any other artificial radionuclide)
is not applied. A suffix + or sec marks a parent in secular equilibrium with the daughters in Table 3. Where a
nuclide is printed in several forms (Th-232, U-235, U-238, Cf-253; in Germany Zr-97, Pb-212 and Th-232) the form with the
smallest limit is used, so U-235 and U-238 take the sec value of 0.01 Bq/g with their whole Table 3 chain covered. A
progeny is left out of the sum only if the chosen form covers it, and a plain row covers none. The forms and the choice
are recorded per nuclide as form_choice in the sidecar.
Canada: Schedule 2 is the clearance schedule; Schedule 1 holds exemption quantities and is not used. A nuclide that
Schedule 2 does not list has the regulation’s own level of 1 Bq/g up to atomic number 81, which ACTINV applies and marks
"basis": "default_rule". Above 81 the level is 1 Bq/g without alpha emission and 0.1 Bq/g with it; ACTINV does not
decide alpha emission and reports those nuclides in not_listed. A footnote marks parents whose progeny in secular
equilibrium are included.
Each record keeps the fields of the default evaluation: activity_Bq_g, limit_Bq_g and ratio per nuclide, the sum of
fractions as sum_ratio, and the driving nuclide as dominant_ratio. With a jurisdiction it adds:
not_listed: nuclides present above the negligible threshold (--negligible, default 1e-9 Bq/g) that the table does not list for the route, with the activity and the reason. They are not part of the sum and are never treated as zero or dropped.below_negligible_unlisted: the count and total activity of unlisted nuclides below that threshold.covered_by_parent: progeny whose parent is present, which the parent’s value already includes, left out of the sum as in the response tables ofactinv run.basison each nuclide (tableordefault_rule), and in the header ajurisdictionblock with the route, the citation, the table’s SHA-256, the licence and a note on what the regulation allows that ACTINV does not apply.
The same tables are bundled for actinv run as bundled:de-strlschv-2018-anlage-4,
bundled:uk-epr-2016-sch23-pt3-table-2 and bundled:ca-nsrdr-2000-207-schedule-2, with one clearance_index response
per route and the coefficients in Bq/kg.
Sources and licences. Germany: the text of the ordinance is an official work (amtliches Werk) without copyright under
section 5(1) UrhG; it is published by the Bundesministerium der Justiz and is not an official version, which is the
Bundesgesetzblatt. United Kingdom: contains public sector information licensed under the Open Government Licence v3.0
(legislation.gov.uk). Canada: reproduced from the Justice Laws Website under the Reproduction of Federal Law Order
(SI/97-5); not an official version. The converter is scripts/regulatory/convert_national_clearance.py, the archived
source files with their SHA-256 are under controls/fixtures/clearance_sources/, and
controls/check_jurisdiction_tables.py re-reads them with an independent reader and checks every shipped value.
Screen a material’s impurities
Which impurities in an alloy matter, at which cooling times, for which concern, and how much of each can you
tolerate? actinv impurities answers with one command and one input. It solves each element of the alloy once as a
pure material, forms every activity, heat, clearance-index and waste-class table sum of any composition as a weighted
sum of those runs, and reports rankings, limits and worst cases over the impurity ranges you declare. Every number it
reports is then checked by a full solve of the material at that composition.
actinv impurities impurities.json impurities-result.json
actinv impurities impurities.json impurities-result.json --no-verify
The example below is examples/impurities_ra_steel/: a reduced-activation ferritic-martensitic steel in the fusion
first-wall spectrum of examples/optimize_ra_steel, after two full-power years at a total neutron flux of
5e14 n/cm2/s, at 1 d, 1 y, 10 y and 100 y of cooling. Its values are illustrative. They are not a qualified
material specification, a design limit or a regulatory position.
Describe the screen
The document impurities.json uses the schema actinv-impurities-1:
{
"schema": "actinv-impurities-1",
"base_spec": "base_spec.json",
"balance": "Fe",
"matrix": {"Cr": 9.0, "W": 1.1, "Mn": 0.4, "V": 0.2, "Ta": 0.12, "C": 0.11},
"impurities": {
"Co": {"nominal": 0.005, "min": 0.0, "max": 0.01},
"Ni": {"nominal": 0.005, "min": 0.0, "max": 0.05},
"Nb": {"nominal": 0.001, "min": 0.0, "max": 0.005},
"Mo": {"nominal": 0.005, "min": 0.0, "max": 0.02},
"Cu": {"nominal": 0.005, "min": 0.0, "max": 0.02},
"Al": {"nominal": 0.005, "min": 0.0, "max": 0.01},
"N": {"nominal": 0.03, "min": 0.015, "max": 0.045},
"Ag": {"nominal": 0.0001, "min": 0.0, "max": 0.0005}
},
"targets": [2, 3, 4, 5],
"endpoints": [
{"endpoint": "activity.total"},
{"endpoint": "heat.total", "limit": 1.4e-2},
{"endpoint": "dose.contact_proxy"},
{"endpoint": "activity:Nb94", "limit": 100.0},
{"endpoint": "clearance_index"},
{"endpoint": "waste_class", "class": "C"}
],
"waste": {
"rules": "us-nrc-10cfr61.55-v1",
"mass_g": 1000.0,
"density_g_cm3": 7.8,
"waste_type": "activated_metal",
"external_tritium": {"status": "not_applicable"}
}
}
base_specis anactinv-spec-1run (a path relative to this file, or an embedded object). Its flux, schedule and data are used; itsmaterialis replaced. The command forcesmode: coupledandprune: reach, the configuration proven additive, and records that. The example’s schedule is two years of irradiation followed by cooling steps, so result steps 2 to 5 end at 1 d, 1 y, 10 y and 100 y of cooling.balancetakes the remainder to 100 wt%.matrixholds the fixed constituents. Each impurity gives wt% asnominal,minandmax(min≤nominal≤max), or one number for all three.targetsare one-based result step numbers, as inactinv clearance.- Each endpoint is a name or an object with
endpoint, an optionallimitand, forwaste_class, the classA,BorCyou require.activity.totalis in Bq/g,heat.totalin W/g,activity:<nuclide>in Bq/g,dose.contact_proxyin Gy/h,clearance_indexis the IAEA index (limit 1, or your ownlimit; the table can be replaced withlimits, as foractinv budget). A limit onwaste_classis refused: its limits are the Part 61 table sums. wasteis required by awaste_classendpoint: the rule pack, mass, one geometry denominator, waste type and external-tritium declaration, as foractinv waste budget. Nuclide properties are derived from the run’s decay data.dose.contact_proxyneeds the base spec’sphotonsection with a photon response that has attenuation curves for every element in the material.
The command refuses, and writes nothing, when the response would not be linear in composition: self_shielding,
options.screen, a schedule feed, power-driven steps and an uncertainty section in the base spec (first-order
bands do not compose across element runs; nuclear-data uncertainty is the sampling block, supported below). It also
refuses a min above nominal or a nominal above max, an unknown endpoint, dose.contact_proxy without a
photon section and a limit on waste_class.
Read the result
The result actinv-impurities-result-1 holds, for each target step, one entry per endpoint. From the repository
root, with the data installed:
actinv impurities examples/impurities_ra_steel/impurities.json impurities-result.json
Output, the cobalt entry of activity.total at step 2 (1 d of cooling), in Bq/g:
"Co": {
"contribution_at_max": 310378679.26071066,
"contribution_nominal": 155189339.63035533,
"gradient_per_wt_pct": 31037867926.071064,
"max_wt_pct": 0.01,
"min_wt_pct": 0.0,
"nominal_wt_pct": 0.005,
"top_nuclides": [
[
"Co58",
165792519.95582134
],
[
"Co58m1",
17348137.37118505
],
[
"Fe59",
10081400.746684032
]
]
},
Cobalt at its nominal 0.005 wt% adds 1.6e8 Bq/g at one day, mostly Co-58 made by (n,2n) on Co-59.
For a scalar endpoint the entry gives:
matrix_only,nominalandworst_case: the value with the matrix alone, at the nominal composition and at the worst case over the declared ranges.worst_case.cornernames, for each impurity, whether the worst case takesminormax.impurities.<element>: thegradient_per_wt_pctat nominal, thecontribution_nominal(the endpoint at nominal minus the endpoint with that impurity removed and the balance element taking its place), thecontribution_at_max(the impurity at its range maximum against removed, the others at nominal) and thetop_nuclidesbehind the contribution: the three largest per-nuclide shares of the contribution’s sign. For an impurity that lowers the endpoint, they are the balance element’s nuclides it displaces.rankinglists the impurities by contribution at nominal.top_nuclidesisnullforheat.total, which the run does not resolve by nuclide.- With a
limit:limits.alone(the impurity is the only one present),limits.others_at_nominalandlimits.others_at_worst(the others at their worst-case values), each with awt_pctand astatus, andjoint_k, the factor by which every impurity’s nominal weight can be scaled to reach the limit.
actinv impurities examples/impurities_ra_steel/impurities.json impurities-result.json
Output, the cobalt entry of heat.total at step 2, in W/g against the 1.4e-2 W/g limit:
"Co": {
"contribution_at_max": 0.00005761499161947032,
"contribution_nominal": 0.00002880749580973516,
"gradient_per_wt_pct": 0.005761499161947032,
"limits": {
"alone": {
"status": "limit",
"wt_pct": 0.06871907545895065
},
"others_at_nominal": {
"status": "limit",
"wt_pct": 0.06435931557971897
},
"others_at_worst": {
"status": "limit",
"wt_pct": 0.04183787399387127
}
},
"max_wt_pct": 0.01,
"min_wt_pct": 0.0,
"nominal_wt_pct": 0.005,
"top_nuclides": null
},
With the other impurities at nominal, cobalt may rise to 0.064 wt% before the steel’s heat one day after shutdown reaches the limit; with the others at their worst case, to 0.042 wt%.
A status is limit (the number exists), no response (the impurity does not raise the endpoint, or the limit lies
beyond what the balance element can give up) or infeasible (the other constituents alone already reach the limit).
For the contact proxy a status unavailable means the proxy is null there and the entry says why.
The summary gives, for each endpoint, the tightest_limit of each impurity across targets with the step that
binds it, the impurities ranking by their largest contribution across targets, and the worst value or class
across targets.
actinv impurities examples/impurities_ra_steel/impurities.json impurities-result.json
Output, the tightest heat.total limits with the others at nominal, from summary:
"others_at_nominal": {
"Ag": {
"status": "limit",
"step": 2,
"wt_pct": 0.12560332896898269
},
"Al": {
"status": "limit",
"step": 2,
"wt_pct": 0.1378665895018817
},
"Co": {
"status": "limit",
"step": 2,
"wt_pct": 0.06435931557971897
},
"Cu": {
"status": "limit",
"step": 2,
"wt_pct": 2.073400347459034
},
"Mo": {
"status": "limit",
"step": 2,
"wt_pct": 0.8845944427497271
},
"N": {
"status": "no response",
"step": null,
"wt_pct": null
},
"Nb": {
"status": "limit",
"step": 2,
"wt_pct": 0.1891269323069253
},
"Ni": {
"status": "limit",
"step": 2,
"wt_pct": 0.16134111838932721
}
},
Every heat limit binds at one day of cooling, where the iron, chromium and manganese products still dominate. Nitrogen gives no response. In place of iron it lowers the heat up to 10 y, and at 100 y the limit lies beyond what the balance element can give up.
The waste class
A waste_class entry reports nominal_class, and worst_case with the class over the ranges and its binding
table, column and nuclides. Each Part 61 table sum is linear in composition, so each is maximised over the range box
at its own corner and the class is read from the maximised sums. That is a conservative bound, since the class never
decreases when a sum increases. The impurities’ class limits are those actinv waste budget gives, in
summary.<endpoint>.impurity_class_limits; an open boundary is a supremum, not an attained maximum.
actinv impurities examples/impurities_ra_steel/impurities.json impurities-result.json
Output, the start of the waste_class:C entry’s worst_case at step 2:
"worst_case": {
"binding": {
"column": null,
"constraint": "table_1",
"corner": {
"Ag": "max",
"Al": "max",
"Co": "max",
"Cu": "max",
"Mo": "max",
"N": "max",
"Nb": "max",
"Ni": "max"
},
"normalized_sum_max": 0.7039397258233535,
With every impurity at its maximum, the Table 1 sum reaches 0.70 of its Class C limit, so the steel stays Class C
over the declared ranges. The entry’s ranking names the impurities behind it: nitrogen (C-14), then molybdenum and
niobium (Nb-94).
Add nuclear-data uncertainty
Everything above uses the nominal nuclear data. Add a sampling block and every value and limit also gets a bound over
the nuclear-data uncertainty. The worked example examples/impurities_ra_steel/impurities_uncertainty.json is
impurities.json plus two keys:
"confidence_level": 0.95,
"sampling": {
"channels": {"cross_section_mf33": true, "decay_constants": true},
"covariance": {"path": "catalog:tendl-2025-neutron-709g-covariance"},
"samples": 72,
"seed": 158001
}
actinv impurities examples/impurities_ra_steel/impurities_uncertainty.json impurities-uncertainty-result.json
sampling is the block of actinv waste budget uncertainty:
samples from 20 to 4096, a seed, the channels and covariance of study.robustness, and an optional
keep_samples folder, relative to this file. confidence_level runs from 0.5 to 0.999 and defaults to 0.95.
The composition channel is refused, because composition is what the screen varies. So are a base spec that enables gas
production, declares its own rate, decay or yield scales, or switches library, projectile or spectrum during the
schedule, and a confidence_level without sampling. Every refusal is made before any solve, and nothing is written.
Method. At one fixed draw of the data the activation is again linear in composition, so the algorithm above applies
to that draw unchanged. The command draws the factors of every sample once, from the sampling plan of the full alloy at
the plan composition (the matrix, every impurity at its range maximum and the balance element taking the remainder, so
every element the screen can contain is in the plan), and applies the same factors to every element solve of that
sample. It then runs the whole screen on the sample’s element responses: the matrix-only, nominal and worst-case value
of every endpoint at every target, each impurity’s contribution at nominal, the limits and joint_k, and for
waste_class the nominal class, the worst class and the per-impurity class limits. The fields of the nominal screen
are unchanged; the bands are added beside them.
Bounds. With n samples, k is the largest index for which the lower end of the two-sided Clopper-Pearson interval at the confidence level of (n − k + 1)/n is at least the confidence level. A value is reported by its median and its upper bound, the k-th largest per-sample value. A limit is reported by its lower bound, the k-th smallest per-sample limit. These are order-statistic (Wilks) tolerance bounds: exact for any distribution, one-sided, and they need no normality. At least 72 samples are needed at confidence 0.95; a document with fewer is refused, and the refusal names the minimum for your level (528 at 0.99).
Reading the result. Each per-target endpoint entry gains an uncertainty object:
matrix_only,nominalandworst_case, and each impurity’scontribution_nominal: themedian, theupper_boundand itsstatus(bounded, orunboundedwhen a failed sample or an unavailable proxy reaches the rank), with the value of every sample inby_sample.- With a
limit, each impurity’slimits.alone,limits.others_at_nominalandlimits.others_at_worst, andjoint_k: thebound, thestatusand the per-sample limits (by_sample,sorted). A sample whose limit lies beyond the balance element’s reach enters at that cap (capped); a sample that fails or is infeasible enters at 0, so it can only lower the bound. The limit isnot_establishedwhen any sample (or the nominal data) has a positive lower bound, andunboundedwhen the k-th smallest has no response. - For
waste_class, thefrequencyof each class at nominal and over the ranges, andmeets_target: the probability that the target class is met at nominal and at the worst case, with its Clopper-Pearsonlowerbound at the confidence level. Each impurity’s class limit, over all targets, is underuncertainty.impurity_class_limits. ranking: for each impurity the fraction of samples in which it is the largest contributor at nominal.
The top-level uncertainty block gives the confidence_level, the order_statistic (k, n and
minimum_samples), the sampling it ran, the plan composition, the coverage of the sampled channels, the
failed_samples, not_claimed and verification_pass. With keep_samples, each sample writes sample_NNNN.json: its
factor block, the factors each element solve actually carried, the element responses used and the sample’s screen
values, enough to recompute every band.
Verification. Unless --no-verify is given, the nominal checks above still run. For every established limit, the
samples at sorted ranks k − 2 to k + 2 are re-solved with the full alloy and that sample’s own factors at 0.99
and 1.01 times their own limit: the 0.99 point must meet the limit and the 1.01 point must not, unless the limit is
capped. For every upper bound, the sample that holds it is re-solved at the composition the value belongs to (its own
worst-case corner for worst_case) and must agree to 1e-6 relative. Differences smaller than 1e-12 times the
endpoint’s largest value in that sample are ignored. That is round-off, such as a trace nuclide that one solve keeps
at 1e-162 Bq/g and another sets to zero. A point decided this way records rel_dev_before_floor and floor. The
results are in verification.uncertainty, and a miss exits 3 after writing.
The worked example’s 72 samples take about 45 minutes on one laptop core: 15 element solves per sample, 1,080 in all, plus 356 re-solves that verify the bounds. Its heat at step 2 (1 d of cooling) shows what the bounds add. With the nominal data, the worst case, 1.38e-2 W/g, is just under the 1.4e-2 W/g limit. Over the nuclear-data uncertainty, the steel exceeds that limit in 30 of the 72 samples even without its impurities. The 95% upper bound on the worst case is 2.5e-2 W/g, and the cobalt limit’s lower bound is 0: no cobalt share meets the limit at 95% confidence.
actinv impurities examples/impurities_ra_steel/impurities_uncertainty.json impurities-uncertainty-result.json
Output, the end of uncertainty.worst_case in the heat.total entry at step 2, after its 72 per-sample values:
],
"median": 0.013621176480236313,
"order_statistic_rank": 1,
"status": "bounded",
"upper_bound": 0.025141681784584535,
"upper_bound_sample": 68,
"valid_samples": 72
}
What the bands do not claim. They are conditional on the sampled channels and assume, per sample, that the
activation response is linear in composition, as the nominal screen does. Composition, geometry, flux-shape and model
uncertainty are not sampled. Measured coverage of these channels on the FNS corpus is below nominal
(docs/DATA_LIMITATIONS.md), so a bound can be optimistic. The upper bound on a value and the lower bound on a limit
are one-sided order-statistic tolerance bounds. They are not two-sided intervals and not a design margin. The worked
example’s composition and history are illustrative.
In the desktop app and the browser
The Impurities page, under STUDIES, screens the material of the problem that is open. Composition lists
its elements: choose the Balance (the largest at first), keep an element Fixed at its share from Material,
or make it an Impurity with a nominal, minimum and maximum in wt%. Add an impurity the material does not list by
its symbol. When selects the steps to screen; every cooling step after the last irradiation is selected at first.
What matters chooses the endpoints, each with an optional limit, the activity of single nuclides, and the waste
class with the class to meet; the waste class uses the material’s mass and density as the component.
Nuclear-data uncertainty is optional. It adds the sampling block of
Add nuclear-data uncertainty: a confidence of 90, 95 or 99%, the number of samples
(at least the minimum for that confidence), cross sections, decay constants or both, and a seed. The page shows how
many calculations that takes before you start. The page needs a composition in wt%, and it explains on the page what
it refuses, as the command does.
Screen impurities runs the screen in the background, with verification, and shows the result: whether it was
verified, an overview with each endpoint’s worst case, largest contributor and tightest limit over all screened
steps, and for a chosen step, each endpoint’s nominal, impurity-free and worst-case values with every impurity’s
contribution, the nuclides it acts through and its limits. A screen with nuclear-data uncertainty shows each bound in
grey beside its nominal figure: an upper bound on each value and contribution, a lower bound on each limit. A bound
that only restates the nominal figure, such as no limit for an impurity that does not raise the endpoint, is left out.
When the material exceeds a limit without impurities in some samples, the card says so once, instead of a 0 beside
every limit. For the waste class, it shows how many samples meet the target class and the lower bound on that
probability. Save screen… writes the actinv-impurities-1 document with the problem embedded, and Save
result… and Open result… write and read results, including those of actinv impurities. The browser sets up
screens and reads results but does not run them.
What to keep in mind
- Linearity. At fixed flux the coupled activation is linear in the initial composition. That holds without self-shielding, screening or feed; it is a property of the tested neutron spectra and schedules, not a general one. Ranges that move the composition far from the tested mixtures are not covered by that evidence.
- Contact dose is a slab proxy.
dose.contact_proxyis the semi-infinite-slab screening proxy, not a dose for a geometry. It is not linear, because the material’s own attenuation enters it: the command sums the pure elements’ grouped photon sources and evaluates the proxy at the composition’s attenuation exactly as a run would. Its worst case is a corner maximum over the corners of the range box (at most 12 impurities with a range); an interior maximum is not excluded. Its limits are found by bisection to 1e-9 relative in the impurity’s weight fraction and assume the proxy rises with the impurity. Its gradient is a central difference. A proxy the response cannot evaluate is reported asnullwith the reason, never as a number. - Every number is verified. Unless
--no-verifyis given, the nominal composition, every worst-case corner and every reported limit is solved in full and compared with the prediction (verification.points, tolerance 1e-6 relative). The command exits 3, after writing the result, if any point misses. - The Part 61 class is the nominal U.S. classification, not disposal acceptance.
Unfold a neutron spectrum from foils
A set of activation foils irradiated in an unknown field records that field in its activities. actinv unfold
turns the measured activities back into the group fluxes that made them, starting from a prior spectrum you supply,
and tells you how well each energy range is now known.
actinv unfold problem.json measurements.json unfold-result.json
Unfolding codes usually expect activities already reduced to saturated reaction rates, leaving the irradiation
history, decay during irradiation, burn-up and multi-step production to you. actinv unfold models each foil with a
full ACTINV solve over the irradiation and cooling schedule you declare, so those effects are part of the model. Data
you have already reduced can be given as reaction rates instead, and the two kinds can be mixed.
An example
examples/unfold_foils/ holds a nickel and an aluminium foil irradiated for one hour and counted after one hour of
cooling. The prior is the JAEA-FNS iron spectrum of examples/fns_fe_5min.json. The measured values are
illustrative, chosen to be consistent with a spectrum somewhat harder than the prior.
actinv data fetch
actinv unfold examples/unfold_foils/problem.json examples/unfold_foils/measurements.json unfold-result.json
It runs four solves (one per foil, two passes) in about 20 seconds once the data are installed, and prints
chi-square 4.074 on 4. All four measurements respond mostly near the 14 MeV source peak, so the result shows what
foils can and cannot tell you:
| Band | Posterior / prior flux | Standard deviation, prior → posterior |
|---|---|---|
| below 0.5 eV | 1.000 | 18.5% → 18.5% |
| 0.5 eV – 100 keV | 1.003 | 16.3% → 16.3% |
| 0.1 – 1 MeV | 1.047 | 22.7% → 22.6% |
| 1 – 10 MeV | 1.257 | 22.0% → 17.3% |
| above 10 MeV | 1.070 | 29.5% → 1.8% |
Above 10 MeV the flux is now known to 2%. The Co58 and Ni58(n,p) responses start near 5 MeV, which moves and narrows the 1–10 MeV band a little. Below 1 MeV nothing responds, and the result is still the prior.
The problem: prior, foils and history
problem.json is an ordinary actinv-spec-1 neutron problem:
- its spectrum is the prior φ⁰, on the library’s 709 groups (
descendingandtotalare honoured); - its schedule is the foils’ irradiation and cooling history, with flux multipliers as usual;
- its material is the default foil material (each foil may declare its own);
- its library and decay data are used for every foil.
Add an uncertainty block holding a covariance sidecar (and optionally confidence_level) to carry the library’s
MF=33 cross-section covariance into the fit. Nothing else may appear there: unfold sets the responses and channels
itself. Features whose flux is not the spectrum’s (power-driven or wall-loading steps, partitions, step spectra,
feed or removal, rebinning) are refused.
The measurements
measurements.json uses the schema actinv-unfold-input-1. The example’s:
{
"format": "actinv-unfold-input-1",
"prior": {
"relative_uncertainty": 0.3,
"correlation": {"kind": "lethargy_exponential", "length": 1.0}
},
"foils": [
{"id": "ni", "measurements": [
{"nuclide": "Co58", "step": 2, "activity_Bq_per_g": 5450.0, "sigma_Bq_per_g": 164.0},
{"nuclide": "Ni57", "step": 2, "activity_Bq_per_g": 52490.0, "sigma_Bq_per_g": 1575.0}
]},
{"id": "al", "material": {"mass_g": 1.0, "basis": "wt_percent", "composition": {"AL": 100.0}},
"measurements": [
{"nuclide": "Na24", "step": 2, "activity_Bq_per_g": 1112200.0, "sigma_Bq_per_g": 33370.0}
]}
],
"reaction_rates": [
{"id": "ni58-np", "target": "Ni58", "mt": 103,
"rate_per_atom_s": 3.39e-15, "sigma_per_atom_s": 1.0e-16}
]
}
- prior.
relative_uncertaintyis the standard deviation of ln φ_g: one number, or one per group in the spectrum’s order.correlationis{"kind": "diagonal"}or{"kind": "lethargy_exponential", "length": L}, correlating two groups by exp(−|Δu|/L) with u the logarithm of the group energy. Groups with zero prior flux or zero uncertainty are held fixed. - foils. Each foil has an
id, an optionalmaterial, and activities (Bq per gram of foil) at the end of a schedule step, each with its one-standard-deviationsigma_Bq_per_gand an optionalmodel_relative_uncertaintyfor corrections you have not modelled (self-shielding, cover, geometry). A metastable state may be writtenIn115morIn115m1; the result reports the canonicalIn115m1. - reaction_rates. Reactions per target atom per second at the declared spectrum: a
targetnuclide, an ENDFmt, and optionally theproductstate (without it the reaction’s total is used). - Optional:
report_bands_eV(energy edges of the reported bands; default 1e-5, 0.5, 1e5, 1e6 and 1e7 eV and the top of the structure),emit_covariance(write the posterior covariance of ln φ), anditerations.
Every measurement needs a positive value and a positive σ. A measurement the prior spectrum does not produce is refused, since it carries no information the fit can use.
The result
unfold-result.json (actinv-unfold-1) holds:
- groups: prior and posterior flux per group, the standard deviation of ln φ before and after, and the resolution 1 − (posterior variance / prior variance): near 1 where the measurements determine the flux, near 0 where the result is still the prior;
- bands: the flux in each report band with its standard deviation and an interval at the confidence level, and the correlation between bands;
- measurements: each one’s prior and posterior prediction, its pull before and after the fit, its cross-section uncertainty when a sidecar is given, and its response window, the energies below which 5%, 50% and 95% of its response lies;
- consistency: the χ² at the solution with one degree of freedom per measurement. A χ² far above the number of measurements says the measurements and the prior disagree more than their uncertainties allow; look at the pulls. Two foils that respond at the same energies but disagree by more than their σ (say Ni57 low and Na24 high, both from the 14 MeV peak) show up here, not as a confident spectrum.
What it does and does not tell you
Unfolding is under-determined. Outside the energies your foils respond to, the posterior is the prior; the
resolution and response windows say where that is. The intervals are only as right as the prior uncertainty you
declare. Self-shielding and flux perturbation by the foils, covers and counting corrections are inputs (through the
foil material, the problem’s options or the model uncertainty), not something unfold estimates.
Method and evidence
The fit is generalized least squares on ln φ with the prior’s covariance, the measurement uncertainties and, with a sidecar, the cross-section covariance. It is solved by damped Newton with the local model’s exact second derivatives; every activity and its 709 derivatives come from one solve of the foil. The posterior covariance is the usual linearized one at the solution.
Protocol P195 and its Amendment A tested it (P195A-PASS):
actinv unfold estimates a neutron spectrum from foil activities, modelled with a full ACTINV solve of each foil’s irradiation history, and from reaction rates, carrying the library’s cross-section covariance into the fit.
On 40 synthetic spectra drawn from its prior, 94% of the true band fluxes fell inside its 95% intervals and 74% inside one standard deviation, and its band fluxes were closer to the truth than the prior’s (root-mean-square log error 0.124 against 0.208).
On IRDFF-II’s measured spectrum-averaged cross sections in the Cf-252 and U-235 fission fields, predicting each reaction left out of the fit, the median |ln(C/E)| was Cf-252-a prior (the other field): 0.321 → 0.087, UNFOLD CLOSER, p = 3e-08; Cf-252-b prior (a Maxwellian): 0.158 → 0.080, UNFOLD CLOSER, p = 0.00068; U-235-a prior (the other field): 0.246 → 0.044, UNFOLD CLOSER, p = 1.3e-05; U-235-b prior (a Maxwellian): 1.031 → 0.048, UNFOLD CLOSER, p = 2e-09; the Cf-252 reference spectrum used similar measurements in its evaluation.
Evidence: record, verdict, protocol and amendment.
Plan maintenance after shutdown
After a machine shuts down, crews go in to cut pipes, unbolt brackets and change parts. The dose rate at each job’s
place falls as the machine cools, so waiting longer lowers the crew’s dose and lengthens the outage.
actinv maintenance answers, from dose rates you already have:
- when each job may start, with the dose rate at its place under your access limit for the whole job;
- the dose each worker and each crew receives, at each wait after shutdown you ask about;
- the earliest wait at which every job is allowed and every worker stays under your individual limit;
- with a cost per person-sievert and per outage day, the allowed wait that costs least.
actinv maintenance plan.json plan-result.json
The planner does arithmetic on the dose rates it is given. Their accuracy is their source’s, and it never says a plan is safe.
The Maintenance page of the desktop app and the browser does the same from the open result and the files you add; see Plan maintenance after shutdown.
Write a plan
A plan (actinv-maintenance-1) names where its dose rates come from, the limits, the jobs in the order they are done,
and the waits to tabulate. This is examples/maintenance/plan.json:
{
"schema": "actinv-maintenance-1",
"dose_rates": {"runs": [
{"result": "pipe-result.json", "location": "pipe"},
{"result": "bracket-result.json", "location": "bracket"}
]},
"access_limit_Sv_h": 3.0e-3,
"individual_limit_Sv": 2.0e-2,
"jobs": [
{"name": "cut out pipe section", "location": "pipe", "duration_h": 8, "crew": 2},
{"name": "unbolt bracket", "location": "bracket", "duration_h": 6, "crew": 3}
],
"waits_d": [1, 7, 14, 30, 60, 90, 180],
"cost": {"per_person_Sv": 1.0e6, "per_outage_day": 2.0e3}
}
access_limit_Sv_h: a job may run only while the dose rate at its place stays at or under this.individual_limit_Sv(optional): every worker’s dose must stay at or under this.jobs: each with alocation(one of the dose-rate locations),duration_handcrew. Jobs run one after another from the wait, and every crew member is present for the whole job.waits_d: waits after shutdown, in days, to report in full.cost(optional): without it there is no least-cost wait.interpolation_tolerance(optional, default 0.05): see the check.
Paths are relative to the plan.
Where the dose rates come from
dose_rates takes one of three forms.
ACTINV runs (runs): one actinv run result per location, whose problem asks for a point-source dose
(photon.point_source, see the specification). The planner
reads each step’s dose rate at that distance after the end of the last irradiated step. This treats a whole component
as a point at a stated distance: a screen for handling a part, not the field inside a machine.
A facility twin (twin, shutdown_s, sv_per_gy): an actinv twin result’s dose points, whose twin spec gives
them dose_coeff_gy_cm2_per_photon_h. Their times run from the start of the problem, so shutdown_s says when the
machine shut down. They are in Gy/h of air, and sv_per_gy converts them; nothing is converted unless you say how.
Twin dose points are point-kernel estimates with no scatter or buildup.
A table (table): any other dose rates, such as photon transport results, in an actinv-dose-map-1 file:
{
"schema": "actinv-dose-map-1",
"unit": "Sv/h",
"source": "OpenMC shutdown dose, decay steps 1-12",
"locations": [
{"name": "port-3", "times_s": [0, 3600, 86400, 604800], "dose_rate": [2.1e-2, 1.4e-2, 6.0e-3, 2.2e-3]}
]
}
Times are seconds after shutdown and must increase; dose rates are in Sv/h and must not be negative.
What it reports
plan-result.json (actinv-maintenance-result-1) holds:
alone: each job’s earliest start if it were done on its own.waits: for each wait, each job’s start and end, its peak dose rate, the dose of one worker and of its crew, whether it is allowed, the plan’s collective dose, its largest individual dose, whether the whole plan is allowed, and its cost.earliest_wait_d: the earliest allowed wait.best: the allowed wait of least cost, laid out like a row ofwaits.interpolation_check, the inputs with their SHA-256, and notes on the dose-rate source.
Between two tabulated times the dose rate is taken as an exponential, or as a straight line where one end is zero.
That is exact for one decaying nuclide. For several, the interpolated rate is never below the true one, so doses are
not underestimated. Nothing is extrapolated: a plan that needs a dose rate before the first or after the last
tabulated time is refused. Near a flat minimum the least-cost wait can move a long way for a small change in cost; read
the cost of nearby waits from waits before relying on it.
The interpolation check
Every result also solves the plan again with every other tabulated time dropped, keeping the first and the last, and
reports the largest relative change in its answers (largest_relative_change, and at for which answer). If that is
above interpolation_tolerance, coarse is true: add cooling times around the waits and job lengths that matter
and run the dose rates again. The check errs towards flagging, since dropping half the times moves the answers by more
than the full grid’s own error.
The worked example
examples/maintenance/ plans the two jobs above: a copper pipe and a stainless-steel bracket in a port cell after two
years at 3e8 n/cm2/s of D-T neutrons, each as a point source at 1 m. Its README gives the commands, including building
the photon response. The pipe job could start at shutdown; the bracket job only after about 21.5 days, so the plan is
allowed from 21.1 days, and waiting longer saves little dose because the bracket’s dose comes mostly from Co-60 and
Mn-54. Its values are illustrative.
How it was tested
From the registered test P197:
actinv maintenanceplans jobs after shutdown from dose rates tabulated over cooling time: when each job may start, the dose of each crew at each wait, the earliest allowed wait and the wait of least cost.On three dose curves of one, two and three decaying nuclides with exact answers, its doses, start times and least costs on a 201-time grid were within 0.0006 of exact, never below the exact dose or start on any grid, and its interpolation check flagged every grid where an answer was more than 5% off.
On 7 activated components computed by ACTINV (5 of them held out), plans from a 15-time cooling grid were within 0.02 of plans from a 73-time grid wherever the check did not flag the coarser grid (5 flagged).
The five flagged components were also within 2.4%; the check flagged them anyway. P197 tested the planner’s arithmetic, not any dose rate it reads. Dose rates that rise after shutdown, from a daughter growing in, were not in the test; the search for the earliest start can miss an allowed window narrower than its sampling interval.
Certify, optimize and compare designs
Three pages under STUDIES in the desktop app answer design questions by solving many calculations around the open problem:
| Page | Question | Command-line equivalent |
|---|---|---|
| Certify | Does the design meet its limits once the nuclear-data uncertainty is counted, and which measurement would narrow the answer most? | actinv decide |
| Optimize | Which design, within the ranges you give, does best on one quantity while meeting every limit? | actinv optimize |
| Compare | How do materials, spectra or irradiation lengths compare? | actinv study run |
Each page builds the input file the command reads from the open problem, runs the command in the background, and draws its result. Values are per gram of material. In the browser workbench the pages set the study up and download the file instead of solving. The schemas and limits of the commands are in Advanced workflows and the command line.
Set up the material, the irradiation and the source first. The pages that need something from the problem say what is missing and offer a button to the page that sets it.
Certify
Certify checks a list of limits against the uncertainty band of the nuclear data. A design passes a limit only if the edge of the band, not just the nominal value, is on the right side of it.
What it needs. The problem must have Uncertainty switched on under What to compute, with a cross-section covariance file chosen. The flux-only uncertainty mode cannot certify. Until both are set, the page shows a warning and an Open What to compute button. The schedule must also have at least one step.
What to fill in. Under Limits, each limit is a card:
- a name, which must be unique;
- the quantity: Decay heat, Gamma heat, Beta heat, Alpha heat, Activity, or Activity of one nuclide (type the nuclide, such as Co60);
- at most or at least, and the value, in W/g for heats and Bq/g for activities;
- the time, chosen from the schedule’s step ends and named by what they mean, such as “at shutdown” or “1 y after shutdown”;
- the edge it is checked at: Conservative band edge, Normal band edge or Nominal value only.
The conservative edge adds the declared unmodelled share to the band. The normal edge is the band at the problem’s confidence level. Nominal ignores the uncertainty and is offered for comparison. Choose + Limit for more cards, and set how many measurements to suggest per limit (1 to 20, default 5).
Certify solves the problem once with bands, then checks every limit. Progress shows in the status bar.
What the answer shows. The verdict is Certified or Not certified, with a line such as “2 of 3 limits hold at their band edges, with the nuclear-data uncertainty at 95% confidence”. A warning counts limits that pass on the nominal value but fail with the uncertainty, which a calculation without bands would have certified. A second warning appears if the run is incomplete because some reaction or decay data were missing, in which case the band may be too narrow. The table has one row per limit: Name, Quantity and time, Value at the band edge, Limit, Margin (how far under or over the limit) and Without uncertainty. What to measure next ranks the cross sections, half-lives, fission yields or whole reactions whose measurement would narrow each band most, each as a share of the band’s variance that a perfect measurement of that one quantity would remove.
Optimize
Optimize searches within ranges you set for the design that makes one quantity as low or as high as possible while meeting the limits.
What it needs. A material with elements and a schedule with at least one step. Uncertainty is optional: without it, limits and goal are judged on the nominal value, and the page says so.
What to fill in.
-
What the search may change lists up to 6 things, each with a range. Choose + Something to vary to add one.
- Element content: an element’s weight percent, from one value to another. The other elements are scaled so the total stays 100 wt%, so at least one element must be left unvaried. The composition must be in weight percent.
- Flux: the total flux as a multiple of the problem’s, from a lower to a higher positive multiple. The source needs a total flux.
- Step length: one schedule step’s length, from one duration to a longer one, such as 30 d to 2 y.
Each element or step can be varied once.
-
Goal is Lowest or Highest of a quantity (the same list as Certify) at a time in the schedule, and, when the problem has uncertainty, judged at a band edge.
-
Limits are optional and are the same cards as on Certify. A design counts only if it meets every limit.
-
Search sets how many designs to Try spread over the ranges (default 12), and how many more around the best so far (default 8). The total is at most 64 designs; above that the page shows the count in red and Search designs stays disabled. Each design is one solve, or one solve with bands when the problem has uncertainty. The search is seeded, so the same inputs try the same designs.
Search designs runs the search; the status bar counts designs.
What the answer shows. Best design found gives the value of the goal and how many designs were tried. A table lists each varied thing with the Best design value beside The problem now. Use this design puts those values into the open problem; it takes effect like any edit, so run it from Check & run, and use Undo edit to go back. If no design meets every limit, the page says No design meets every limit: widen the ranges, loosen a limit or try more designs. Every design tried lists all designs ranked, and is open by default in that case.
Compare
Compare solves every combination of the materials, spectra and irradiation lengths you choose and ranks the results side by side, each solved as Run solves it.
What to fill in. Three columns:
- Materials: This problem’s material, plus any library materials added with Add a library material. The library is the one on the Material page.
- Spectra: This problem’s spectrum, plus any of the four standard shapes (D-T fusion (14.1 MeV), Fission (Watt), Thermal (Maxwellian), Slowing down (1/E)). The standard shapes take the problem’s total flux.
- Irradiation: This problem’s irradiation, plus further lengths typed after Also irradiate at full flux for, such as
30 d, 5 y. Each irradiation is followed by this problem’s cooling.
“This problem’s” entries are unavailable, with the reason on hover, when they cannot be compared: a composition not in weight percent, an empty material, a spectrum without flux or one that is rebinned or set by wall loading, or an irradiation with power, wall-loading or library-switch steps. Each case is reported at shutdown and at the end of each cooling step. The page shows the number of combinations (materials times spectra times irradiations). Compare needs at least 2 and at most 200 combinations in the app; a study file run with actinv study run takes up to 1024.
What the answer shows. Ranking shows one quantity (Activity or Decay heat) at one time, per gram, lowest first. Only the columns that differ between cases are shown. Each row gives the value, Times the lowest and a bar for scale. A case that did not finish is listed last as “did not finish”.
Compare answers “which is lower” for the combinations you pick. It does not search between them (use Optimize) and does not apply uncertainty bands (use Certify).
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.2.0 installs it under actinv-data/v1.2.0/ with its index, ENDF/B-VIII.0 primary decay data, JEFF-3.3 fallback decay data, and the neutron damage table (see below).
Downloads are checked by size and SHA-256 before installation. Correct existing files are reused, and a file already present under an older version directory (actinv-data/v1.1.0/) with the same SHA-256 is copied and re-verified instead of downloaded again. An incorrect existing file is left in place unless you explicitly request replacement with --force.
Damage table
Every neutron bundle also installs tendl-2025-neutron-damage, a table of damage energy and displacement cross sections on the 709-group structure. Naming it in a problem gives dpa, exact NRT dpa, arc-dpa and He/dpa with no table to build and no displacement energies to list: actinv new writes the damage section for you, and actinv import-fispact uses it for decks that give ALLDISPEN or ATDISPEN. The table covers every TENDL-2025 neutron target that the catalog’s decay data lists as stable or with a half-life of at least one year; shorter-lived products are counted in the run’s covered_atom_fraction and uncovered_targets, not given damage. It is built from the unmodified TENDL-2025 evaluations, with the standard displacement energies of NJOY2016 HEATR. Build your own with build-damage for other energies or targets.
Choose a bundle
| Calculation | Activation bundle | Matching covariance bundle |
|---|---|---|
| Full neutron corpus | tendl-2025-neutron | tendl-2025-neutron-covariance |
| Derived patched neutron subset | tendl-2025-patched-neutron | tendl-2025-patched-neutron-covariance |
| Proton | tendl-2025-proton | None in the shipped catalog |
| Deuteron | tendl-2025-deuteron | None in the shipped catalog |
| Alpha | tendl-2025-alpha | None in the shipped catalog |
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.2.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.2.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.
| Choice | Benefit | Limitation |
|---|---|---|
| Full neutron corpus | Broader target coverage; default for the recorded FNS workflow | Retains known evaluation defects, including a thermal-energy contamination signature |
| Patched neutron subset | Removes that confirmed signature; recommended by the recorded data guidance for thermal/mixed-spectrum cases | Excludes many targets and retains other defect classes |
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.
Deep-decay totals
When a step’s populations have decayed by many orders of magnitude, the CRAM solve’s round-off can be as large as the
activity and heat it reports. Independent high-precision references have shown reported totals far above the true
value at such steps, for example 1.9e-20 Bq/g against 3.6e-36. States below numerical_floor_atoms_per_g are counted
in n_states_below_floor and stay in the totals. Removing or bounding them was tested and not adopted, because the
round-off also sits in states above the floor. Read deep-decay totals near the round-off scale of the largest
population as numerical, not physical.
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 working directory, the data directory and where it came from (ACTINV_DATA_DIR or the default ./actinv-data), the catalog version and the cache directory. Without a problem it reports whether the standard data are installed and, if not, the command that installs them; with one it checks that the problem’s input files are readable. Hash validation supplements those checks; evaluated-data compatibility is checked during a run.
| Symptom | Check and action |
|---|---|
actinv command not found | Confirm pip installed into the active Python environment and its scripts directory is on PATH; reopen the terminal after installing |
| Catalog artifact is not installed | Run actinv data fetch in the working folder, or set ACTINV_DATA_DIR to the installation root |
fetch fails with http status: 403 on a decay file | The IAEA site refuses automated downloads. Upgrade to 1.7.2 or later, which falls back to ACTINV’s copy, or install the two decay files by hand as in Install the nuclear data |
| Cannot open a literal data path | Check the current directory for CLI use, Input folder in the desktop, or the problem’s directory for Problem.from_file |
Cannot open <stem>_index.json | Install the activation library and its matching adjacent index together; covariance needs its own index too |
| SHA-256 mismatch | Verify the selected bundle, data path, and library/index pairing; recover the exact declared input rather than removing its hash constraint |
| Covariance does not match activation data | Use the full/full or patched/patched pairing in Data setup |
| Unknown field or invalid composition | Use the specification reference; check spelling, units, isotope aliases, and natural-element/isotope overlaps |
| Positive total with zero spectrum | Supply a nonzero spectrum shape before setting its total flux |
| Projectile, group, or temperature mismatch | Select a compatible library; standard charged-particle libraries use 162 groups and 0 K |
| Missing optional result | Confirm you requested the output and supplied its required data; absence is not a computed zero |
| Browser will not run or fetch data | Use desktop, CLI, or Python for calculations; the browser edits inputs and displays results |
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, grouped by task. actinv help COMMAND, or --help anywhere after a command, prints that command’s page: what it answers, its usage, an example, where its output goes and its exit codes. The established examples here cover 1.7.2; the waste commands are documented separately in Component waste classes and impurity limits.
The native waste composition workflow is actinv waste composition solve SPEC.json [OUT.json]. It runs the bounded pure-element basis and every
distinct projection witness allowed by the wrapper limits, then emits one
result only after all requested runs and comparisons succeed. Its base-spec
path is relative to the wrapper file; paths inside that base spec retain the
usual current-working-directory/catalog rules. See the waste handbook for its schema and scientific scope.
actinv waste intrusion-screen SPEC.json [OUT.json] keeps nominal Part 61
classification and the explicitly selected February 2026 draft fusion screen
separate. It screens one declared whole container at selected nominal steps.
See the draft-screen format
for caller-supplied WAC/RQ data, coverage and assessment indicators.
actinv waste uncertainty SPEC.json [OUT.json] solves a problem once and again for each correlated draw of the
sampled nuclear-data channels, classifies every solve, and reports class probabilities with Clopper-Pearson intervals
and the class established at a confidence level. The problem path is relative to the spec file. The probabilities are
conditional on the sampled channels; see
Classification under nuclear-data uncertainty.
actinv waste budget uncertainty SPEC.json [OUT.json] draws the sampled nuclear-data channels once per sample, applies
the same factors to every element solve of the class impurity budget, and reports, per impurity and for the joint
specification scale factor, the budget at a confidence level as an order statistic of the per-sample suprema (at least
72 samples at 0.95), with a verification re-solve around it. The budget path is relative to the spec file. See
Budgets under nuclear-data uncertainty.
actinv waste package SPEC.json [OUT.json] classifies one container of discrete items (activated metal pieces,
sealed sources, cartridge filters) under the NRC concentration-averaging and encapsulation BTP: it tests every item
against BTP Tables 2 and 3 and the Factors of 2 and 10, takes failing items out of the average and classifies them
alone, treats sectioned components as one, and applies the encapsulation volume and mass credit and the Class C cap.
Item result paths are relative to the spec file. See
Classify a package of discrete items for the spec, the readings the
result is conditional on and what it does not claim.
Create, check, and solve
actinv new OUT.json [--data-dir DIR]
actinv new OUT.json --material ID --source SHAPE --flux F [--irradiate DURATION] [--data-dir DIR]
actinv new --list
actinv validate SPEC.json [--schema|--files|--hashes]
actinv doctor [SPEC.json]
actinv run SPEC.json [OUT.json]
new refuses to overwrite an existing file. With --material, --source and --flux it writes 1 g of a library material under a standard spectrum shape at total flux F (n/cm²/s), irradiated for DURATION (default 1 y), then cooled to 1 h, 1 d, 30 d, 1 y and 10 y after shutdown. new --list prints the library materials and the shapes (fusion-14mev, fission, thermal, one-over-e), tab-separated. Each library composition is cited and carries a note naming the trace elements it leaves out; it is a starting point, not your material certificate. The shapes are textbook spectra on the 709-group structure, not a facility’s spectrum. Without these options, new writes the iron example. The example it writes names the catalog’s neutron damage table (catalog:tendl-2025-neutron-damage) in a damage section with no displacement energies, so the run reports dpa once the default bundle is installed; the run’s default outputs already include damage. 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. fetch copies a file that an older version directory already holds with the same SHA-256 instead of downloading it again, and reports it as copied; neutron bundles include the shipped damage table.
Query data files
actinv inspect decay DECAY_PATH [NUCLIDE...] [--estimated-spectrum [--group-structure NAME | --group-boundaries-eV E0,E1,...]]
actinv inspect xs LIBRARY.npz [--target NUCLIDE] [--mt MT] [--spectrum SPEC.json]
actinv inspect yields YIELD_PATH... [--parent NUCLIDE] [--energy EV] [--cumulative]
actinv inspect library LIBRARY.npz
actinv inspect groups NAME
inspect reads the same files a run consumes and prints JSON to standard output. Add --out OUT to write the JSON to a file, or --table for a fixed-width table instead. It never modifies data.
decayreports, per nuclide (all of them when none is named), the half-life, each decay mode with its branching ratio and daughter, the mean beta, gamma and alpha energies as stored in the evaluation, and the number of discrete gamma lines with their total energy per decay. Name nuclides as in a material, for exampleCo60orTa182m1. With--estimated-spectrumit instead prints, per nuclide, the spectrum thatphoton.missing_spectra: "estimate"would use (decay-mode class,E_maxbefore and after the Q-value cap, and photons and energy per decay in each photon group), beside the evaluated grouped spectrum when the record has one. The group structure isfispact-24by default, or--group-structure steiner-22, or custom boundaries in eV with--group-boundaries-eV; the JSON schema isactinv-inspect-decay-estimated-spectrum-1, and--tableprints one table per nuclide.xslists a library’s reactions: target, MT, product, group count and energy structure. With--targetit also gives each reaction’s group cross sections;--targettakes a nuclide name or a raw target index (a ZA such as26056is not an index; name the nuclide), and a name needs the*_index.jsonfile beside the library.--mtkeeps one reaction type. With--spectrum, which accepts a spectrum object or a run spec, it also collapses each reaction with the solver’s own flux-weighted average and reports the one-group cross section in barns and the reaction rate per target atom,sigma * total_flux. The spectrum must be on the library’s group structure, checked as a run checks it: a named structure must have the library’s boundaries, custom boundaries must match to1e-12relative. A spectrum withrebinis converted onto its named destination structure first, as a run does, and the destination must be the library’s.yieldsreads one or more fission-yield evaluations and reports independent yields at every tabulated incident energy.--energy EVinterpolates between tabulated energies exactly as a run does and reports each product’s propagated uncertainty.--cumulativeselects the evaluation’s cumulative (MT=459) yields, when present, for inspection only; runs never use them.--parentselects an evaluation by parent nuclide.librarysummarizes a library without decoding its cross sections: targets, reactions (by MT), group structure, energy range, projectile, the scalar fields of the index file and its object fields (such as thespallationsplice provenance, underindex_objects). A library without an index file is named after any of the FISPACT-II structures its boundaries match.groupsprints the boundaries offispact-709,fispact-162, a refinement such asfispact-709x4, or a group JSON file, in ascending energy.
Without --target, xs omits the group values and lists every reaction in the library; narrow it with --target or --mt. With --table and a single reaction, xs prints one row per group.
Render result tables
actinv report RESULT.json [--tables LIST] [--format csv|tsv|markdown|text|html]
[--out DIR] [--step N|all] [--nuclides LIST] [--problem PROBLEM.json]
report turns a result JSON from actinv run into FISPACT-II style tables, ready to plot. It runs no solver and reads no data files; the output depends only on the result. --tables takes a comma-separated list (default: tab1, tab2, tab3, tab4, totals, dominant, elements and timeseries; depletion and regulatory are built only when you name them); --step selects one step by its one-based number (default all); --nuclides Co60,Mn54 keeps only those rows in tab1, tab2 and depletion and adds their atoms and activity columns to timeseries. A nuclide that is in no selected step is an error. Names are written as in the result, for example Co60 or Ta182m1.
--format html writes a report page to read, share or print instead of tables. It shows the headline numbers (activity, decay heat, contact dose and damage) at shutdown and at round cooling times, charts of how they fall, the nuclides that dominate activity and heat, the decay photon spectrum, and the result’s caveats in plain words. --problem PROBLEM.json adds the problem that produced the result, read back as sentences. With --out DIR, the page is written as report.html beside one SVG file per chart; without it, the page goes to standard output. --tables, --step and --nuclides select tables and are refused with html. The desktop and browser Export page writes the same page and charts.
actinv report result.json --format html --problem problem.json --out fe-report
| Table | One row per | Columns |
|---|---|---|
tab1 | step and nuclide, largest population first | step, time_s, nuclide, atoms_per_g, mass_g_per_g, atoms, mass_g |
tab2 | step and nuclide with activity, largest first | step, time_s, nuclide, activity_Bq_per_g, heat_W_per_g, alpha_W_per_g, beta_W_per_g, gamma_W_per_g, half_life_s, activity_Bq, heat_W |
tab3 | step and ingestion or inhalation dose response | step, time_s, response, value, unit, covered_activity_Bq_per_g, missing_activity_Bq_per_g, activity_coverage_fraction, contributing_nuclides, missing_active_nuclides |
tab4 | step and photon energy group | step, time_s, group, low_eV, high_eV, centroid_eV, photons_s_g, power_W_g, photons_s, power_W |
totals | step | total activity and heat per gram; with a summary, also Ci, the alpha, beta and gamma activity, activity by decay mode, activity and heat without H-3, mass, absolute and per-cm³ values |
dominant | step, quantity and rank | the summary.dominant lists with percent, cumulative percent, and the counts to reach 90 % and 99 % |
elements | step and element | the summary.elements table |
timeseries | step | activity_Bq_per_g, heat_total_W_per_g, heat_alpha_W_per_g, heat_beta_W_per_g, heat_gamma_W_per_g, then the photon dose rates (contact_gamma_air_dose_proxy_Gy_h, point_source_gamma_air_dose_Sv_h), one column per radiological response, and NUCLIDE_atoms_per_g, NUCLIDE_activity_Bq_per_g for each --nuclides entry |
depletion | step and initial nuclide | step, time_s, nuclide, model, initial_atoms_per_g, atoms_start_per_g, atoms_end_per_g, depleted_atoms_per_g, depleted_fraction, cumulative_depleted_atoms_per_g, cumulative_depleted_fraction, removal_rate_per_s, removal_rate_relative_standard_uncertainty (only when the result carries one), and channels, the ranked removal channels with their shares (MT102 60.0000%; decay 40.0000%). Needs summary.depletion in the problem |
regulatory | step and radiological response that is not an ingestion or inhalation dose (clearance and waste indices, the A2 transport index, activity limits) | step, time_s, response, value, unit, covered_activity_Bq_per_g, missing_activity_Bq_per_g, activity_coverage_fraction, contributing_nuclides, missing_active_nuclides, unlimited_active_nuclides and covered_by_parent (Y90<-Sr90: a progeny the parent’s value already includes). The dose responses are in tab3. Needs radiological responses in the problem |
Every column name carries its unit. time_s is the time at the end of the step. _per_g quantities are per gram of initial material; atoms, mass_g, activity_Bq and heat_W are those values times material.mass_g, and exist only when the result has a summary. Heat is in watts, where FISPACT-II prints kW. half_life_s is empty for a stable nuclide. A step that lacks a value (for instance a photon dose rate) leaves the cell empty.
--format csv (the default) and tsv print every number in the shortest form that parses back to the same value, for example 3.0000000000000004e-1, with one header row. markdown prints a pipe table under a heading, and text a fixed-width table, both rounded to six significant digits and followed by Note: lines for omitted columns and for rows the summary trimmed (min_atoms, include_stable): tab1 and tab2 say how many entries are missing from summary.nuclides, and a --nuclides name the summary trimmed is named in a note. Without --out, the tables go to standard output; with several tables in csv or tsv, each is introduced by a # name line. --out DIR creates DIR and writes one file per table (tab1.csv, tab4.csv, and so on; .tsv, .md or .txt for the other formats), replacing files of the same name.
Anything the result cannot supply is left out, never estimated. Standard error lists the columns omitted and the tables that are unavailable, each with the reason (for example, no summary section, no radiological responses, no photon_source). The command fails only when no requested table can be built. Add a summary section to the problem for grams, the heat split and the element and dominant tables; an outputs selection that drops inventory, activity_Bq_per_g or heat_W_per_g removes the tables built from them.
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.
Facility twins and optional waste classes
actinv twin TWINSPEC.json [OUT.json] evaluates certified clearance bands for
the existing mesh components. To also classify each component’s nominal
activity, add the optional waste block documented in Component waste
classes. It
requires caller-supplied component mass, displaced volume or density, waste
type, cell-mass mapping, selected steps, nuclide properties, and an explicit
Part 61 rule-pack ID. The component groups already in the twin remain the only
source of cell membership.
The added waste_classification and waste_facility_coverage fields use the
original mesh activity maps. Cell and dose assays affect the existing twin
band results but leave both waste fields unchanged. The class summary counts
components separately; it does not make a facility class or determine disposal
acceptance. Omitting the waste block retains the existing twin result fields.
Plan maintenance after shutdown
actinv maintenance PLAN.json [OUT.json] plans jobs after shutdown from dose
rates tabulated over cooling time: when each job may start under an access
limit, each crew’s dose at each wait, the earliest allowed wait and, with
costs, the wait of least cost. It reads the dose rates from actinv run
results with a point-source dose, from an actinv twin result’s dose points,
or from an actinv-dose-map-1 table. See Plan maintenance after
shutdown.
Convert a FISPACT-II deck
actinv import-fispact DECK.i OUT.json [--fluxes FLUXES] [--files FILES] [--library LIB.npz] [--decay DECAY] [--covariance COV.npz] [--strict]
Writes an actinv-spec-1 problem and an OUT.import.json report that lists every deck keyword as mapped, approximated, noted or unsupported. --strict fails when any keyword is unsupported. Four more options, --fission-yields FILE..., --resonance FILE..., --self-shielding-table FILE and --damage TABLE, supply the data files that the fission, self-shielding and damage keywords need; each is hashed into the spec. --damage is optional: a neutron deck that gives ALLDISPEN or ATDISPEN without it uses the catalog table catalog:tendl-2025-neutron-damage. The table’s own displacement energies (the --damage file’s, or the installed catalog table’s) are compared with ALLDISPEN and ATDISPEN; when the catalog table is not installed at import time, the deck’s energies are written and the run makes the comparison. READGG reads the group bins from the files file’s ggbins entry. See Move a FISPACT-II deck to ACTINV for the keyword table and limits.
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-r2s-joint MESH_RESULT.ndjson MESH_SPEC.json STEP OUT.ndjson
actinv export-r2s-cov MESH_RESULT.ndjson MESH_SPEC.json 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
actinv export-source alara R2S_SOURCE.ndjson OUT_DIR --shutdown-t-s T
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.
export-r2s-joint is export-r2s with the cell-to-cell correlation of the nuclear-data (MF=33) uncertainty carried
jointly (actinv-r2s-joint-1); MESH_SPEC.json is the actinv-mesh-spec-1 document the mesh was run from.
export-source alara writes one ALARA .photonSrc file per cell under OUT_DIR (which must not exist, or exist and be empty) plus a provenance index OUT_DIR/actinv-alara-index.json. --shutdown-t-s T is required; cooling time is step_t_s - T, and every cell must share the same step_t_s. See Advanced workflows and docs/INTERCHANGE_TRANSPORT.md for the full contract.
export-r2s-cov writes the covariance of the decay photon source over (region, photon group) at one step as actinv-r2s-cov-1, in factored form so it stays small. MESH_SPEC.json is the spec the mesh was run from. The mean record is the source S[c][g] in photons/s per region and group. Each shared record is one column L_k[c][g] of the nuclear-data uncertainty that every region sees: the MF=33 cross sections (a pivoted-Cholesky factor of their covariance, so the columns are uncorrelated), the half-lives and the fission yields (one column per parameter). Each independent record holds the columns of one region’s flux-tally noise, which is independent between regions and neutron groups; they factor the region’s photon-group block sum_j M_j M_j^T over the neutron groups j. Then C_S = sum_k L_k L_k^T + blockdiag_c(independent block), and for any dose response R[c][g], Var(D) = R^T C_S R + sum_c S_c^2 sigma_Rc^2. Only the channels the spec lists in uncertainty.channels are propagated; the header’s channels_missing names the rest, and always names photon emission data, which carries no published covariance. The MF=33 factor forms a dense block over the (region, group) pairs with nonzero sensitivity and refuses more than 5000.
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]
build-damage takes --method default|kinematic. The default reads MT=444 from the evaluations. --method kinematic
computes damage energy from MF=3/4/6 and writes an actinv-damage-table-2 file; it also accepts
--displacement-energy EL=eV (repeatable; default the NJOY HEATR standard energy of the element, 25 eV for elements it does not list), --capture-photons evaluated|one-photon|per-photon
(default evaluated), --continuum-recoil kinematic|evaluated (default kinematic) --grid-density X and --continue-on-error true|false (default false; an evaluation whose processing fails is then listed in the table’s failed array instead of aborting the build), and defaults --temperature-K to 0 because it reconstructs resonances at 0 K.
It is implemented for neutron evaluations. See damage observables.
build-shielding takes --profile none|endfb8|tendl (default none), the same tape normalization as
build-library --profile. Use endfb8 for ENDF/B-VIII.1 evaluations and tendl for TENDL; without it an evaluation
the profile would repair (for example an ENDF/B-VIII.1 Breit-Wigner total width below its component sum) is refused.
--workers N (default 1) processes N evaluation files in parallel; the table is byte-identical for any N.
The table does not depend on where the evaluation directory lives: identical input files and options give a byte-identical table, and files lists each input by name and SHA-256.
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 unfold PROBLEM.json MEASUREMENTS.json [OUT.json]
actinv optimize OPTSPEC.json [OUTDIR] [--resume]
actinv decide DECISION.json [OUT.json]
actinv budget BUDGET.json [OUT.json] [--no-verify]
actinv impurities SPEC.json [OUT.json] [--no-verify]
actinv waste WASTE.json [OUT.json]
actinv waste budget BUDGET.json [OUT.json]
actinv waste bounds BOUNDS.json [OUT.json]
actinv waste composition COMPOSITION.json [OUT.json]
actinv waste composition solve NATIVE_COMPOSITION.json [OUT.json]
actinv waste intrusion-screen INTRUSION.json [OUT.json]
actinv waste package PACKAGE.json [OUT.json]
actinv clearance INPUT STEP [--limits PATH] [--confidence T] OUT.ndjson
actinv assimilate --result RUN.json --assay ASSAY.json [--out OUT.json] [--emit-result UPDATED.json]
actinv eval-spread PROBLEM.json [OUT.json]
actinv surrogate fit SURSPEC.json [OUTDIR]
actinv surrogate eval ARTIFACT.json X.json [OUT.json]
actinv clearance certifies that the clearance index is below 1 at one step (one-based), per cell of an actinv mesh
result or for one run result, against the IAEA limits or an actinv-clearance-limits-1 file. --confidence is the
one-sided confidence, between 0.5 and 1 exclusive (default 0.95). actinv assimilate folds an assay
(actinv-assay-1) into a result’s certified bands and reports the gain and a consistency verdict; --emit-result
writes the result with the updated bands for decide, clearance or another assimilate. actinv eval-spread solves
a problem once with each decay evaluation as primary (it needs decay.fallback) and reports how far every quantity
moves. actinv surrogate fits a fast model of a response over a design grid, which optimize can use; responses are
named once each, and the surrogate spec’s base_spec is read relative to the spec’s own folder.
actinv unfold estimates a neutron spectrum from foil activities and reaction rates, starting from the problem’s
spectrum as a prior; see Unfold a neutron spectrum from foils.
actinv impurities screens a material’s impurities over declared composition ranges from one solve per element; see
Screen a material’s impurities. It exits 3, after writing its output, when a verification re-solve
misses; a refused input (nonlinear options, a bad range, an unknown endpoint) exits 1 and writes nothing.
actinv waste budget and actinv waste budget uncertainty likewise exit 3, after writing the full result, when a
verification point misses. actinv study run records a case that fails in study_record.json, whose verdict is then
incomplete, and exits 0; read the verdict.
Each workflow consumes its own document format. Advanced workflows links the schemas, examples, and applicability limits. Every command has its own page: actinv help COMMAND. actinv help exit-codes lists what each exit code means.
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; 1.4.0 adds actinv.budget(budget, *, base_dir=None, verify=True). Their options after the first arguments are keyword-only, for example actinv.decide(decision, base_dir="case") and actinv.optimize(path, outdir="out", resume=True). A failed budget verification is returned in the document rather than raised as an exception. See the Python package reference, Advanced workflows.
Waste classification from Python
The waste commands and the facility twin are available as functions. Each runs the command line’s own code, so the result is the document the CLI would write.
| Python | CLI |
|---|---|
actinv.waste.classify(spec) | actinv waste SPEC |
actinv.waste.budget(spec) | actinv waste budget SPEC |
actinv.waste.bounds(spec) | actinv waste bounds SPEC |
actinv.waste.composition(spec) | actinv waste composition SPEC |
actinv.waste.composition_solve(spec) | actinv waste composition solve SPEC |
actinv.waste.intrusion_screen(spec) | actinv waste intrusion-screen SPEC |
actinv.waste.uncertainty(spec) | actinv waste uncertainty SPEC |
actinv.waste.budget_uncertainty(spec) | actinv waste budget uncertainty SPEC |
actinv.waste.package(spec) | actinv waste package SPEC |
actinv.twin(spec) | actinv twin SPEC |
spec is a path, or a dictionary together with base_dir, the folder its relative paths resolve against (default: the current directory). A path is used as it is, and relative paths inside the file resolve against the file’s folder. A dictionary is written to a temporary file in base_dir for the duration of the call and removed afterwards, also on error. Each call returns the result as a dictionary, or with text=True the exact JSON text the CLI writes to an output file. A refusal raises ValueError with the CLI’s message. Calls print nothing; actinv waste composition also prints an intermediate bounds report to standard output, which actinv.waste.composition leaves out (the result is the same). actinv.waste.budget is actinv waste budget (impurity limits for a requested class); the impurity budget actinv.budget is unchanged.
import json
from pathlib import Path
import actinv
result = actinv.waste.classify("component.json")
for row in actinv.waste.summary(result):
print(row["component"], row["step"], row["class"], row["binding_table"], row["binding_nuclides"])
spec = json.loads(Path("case/bounds.json").read_text(encoding="utf-8"))
bounds = actinv.waste.bounds(spec, base_dir="case")
actinv.waste.summary(result) takes a classification result (also the classification member of an intrusion-screen result, or a twin’s waste_classification) and returns one flat dictionary per component and target step: class, status, coverage, the governing table, column and margin, and the binding nuclides. It reads the result and computes nothing new. The scope is that of Component waste classes: nominal screening, not disposal acceptance or intrusion dose.
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
| field | meaning |
|---|---|
projectile | neutron, proton, deuteron, triton, helion (He-3), alpha or gamma; omission preserves the historical neutron default. |
library.path | ACTINV .npz activation library; the adjacent <stem>_index.json is also required. May be omitted only when every schedule step has zero flux (see Decay-only runs). |
library.sha256 | Optional declared hash. ACTINV always computes the library hash and fails if a declaration differs. The index’s recorded library hash is checked too. |
decay.primary | ENDF-6 radioactive-decay sublibrary. |
decay.fallback | Optional second decay sublibrary; records absent from the primary are taken from it. |
material.composition | Natural element symbols or explicit nuclides (U235, Ba137m1) and nonnegative values interpreted by material.basis. |
spectrum.flux_per_group | Group-integrated fluxes. descending: true reverses the supplied order before use. |
schedule | At least one duration plus exactly one of flux (multiplier), wall_loading_MW_m2 or, with a kerma section, a power target (power_W_cm3 / power_W_per_g; an explicit flux: 0 beside a power target is accepted); optional partition, feed, removal, spectrum, library. Accepted duration units: seconds, minutes, hours, days and years. |
fission_yields | Optional hash-pinned ENDF-6 neutron-induced fission-yield evaluations, and optional spontaneous-fission yields and neutron multiplicities; see below. Empty/omitted preserves the explicit no-yields leakage path. |
uncertainty | Optional neutron-only MF=33 sidecar and response selection; omission reads no covariance file and preserves the ordinary path. |
radiological | Optional hash-pinned clearance, waste, ingestion, or inhalation response table; omission reads no table. |
damage | Optional hash-pinned actinv-damage-table-1 or actinv-damage-table-2 (kinematic) damage-energy table plus per-element displacement energies; required when outputs contains damage. |
kerma | Optional hash-pinned actinv-kerma-table-1 heating table; adds per-step kerma heating and enables power-driven schedule steps (power_W_cm3 / power_W_per_g, with material.density_g_cm3 for the former). |
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.
material.density_g_cm3 is optional (finite and positive); only the step summary’s per-cm³ totals use it.
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, or any other FISPACT-II neutron structure listed under
Group structures with exactly that structure’s group count. Proton, deuteron, triton, helion 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.
Spectrum conversion (spectrum.rebin)
spectrum.rebin converts a spectrum supplied in its own groups onto a library structure inside the run
(FISPACT-II GRPCONVERT, CNVTYPE and LIMGRP). With it, spectrum.structure names the destination structure
(fispact-709, fispact-162 or a refinement such as fispact-709x4; not custom), and boundaries_eV
(strictly ascending, one more than the flux values) plus flux_per_group describe the supplied groups.
| field | meaning | default |
|---|---|---|
convention | equal_lethargy (CNVTYPE 0): flux is spread uniformly in lethargy inside a source group. equal_energy (CNVTYPE 1): uniformly in energy. | equal_lethargy |
emin_eV | LIMGRP lower limit: flux in source groups below it is folded into the first group above it, whose lower edge becomes emin_eV. | none |
emax_eV | LIMGRP upper limit: flux above it is folded into the last group below it, whose upper edge becomes emax_eV. | none |
total rescales the supplied spectrum before conversion. relative_error cannot accompany rebin (it is indexed by
the supplied groups). Flux falling outside the destination structure’s range is not discarded silently: it is
reported. The ledger gains spectrum_conversion (one record per converted spectrum, the base spectrum first, then
any step spectrum) holding convention, cnvtype, destination_structure, source_groups, destination_groups,
emin_eV, emax_eV, limit_flux_moved_from_below, limit_flux_moved_from_above, source_total,
destination_total, outside_destination_below, outside_destination_above, flux_conservation_residual (the
relative closure of source against destination plus outside flux; checked to 1e-12) and exact_grid. A spectrum
without rebin is unchanged and adds nothing to the ledger.
A conversion that leaves no flux in the destination structure (a source wholly below or above its range) is an
error naming the spectrum, because every irradiating step would silently become pure decay; a partial loss is not
refused, so read outside_destination_below and outside_destination_above. emin_eV and emax_eV are checked
when the spec is validated: a limit at or above the whole supplied spectrum (emin_eV) or at or below it
(emax_eV) is an error, while a limit that falls outside the spectrum on the other side leaves that side
unchanged, as the FISPACT-II manual allows. A source group that straddles a limit keeps all of its flux inside the
shortened group (LIMGRP moves its boundary to the limit, it does not split the group), so the part of that group
beyond the limit is redistributed but is not counted in limit_flux_moved_from_below or
limit_flux_moved_from_above, which report only the groups wholly beyond the limit; the total is conserved either
way.
A fragment (group boundaries in eV, flux in n cm^-2 s^-1, merged into a complete problem):
"spectrum": {
"structure": "fispact-709",
"boundaries_eV": [1.0e-3, 1.0, 1.0e3, 1.0e6, 2.0e7],
"flux_per_group": [1.0e9, 4.0e9, 5.0e9, 1.0e9],
"descending": false,
"rebin": {"convention": "equal_lethargy", "emin_eV": 1.0e-2, "emax_eV": 1.5e7}
}
Wall loading (wall_loading_MW_m2)
A schedule step gives exactly one of flux (a multiplier on the spectrum’s total) and wall_loading_MW_m2 (first
wall loading in MW m^-2, FISPACT-II WALL); giving both or neither is an error. FISPACT-II section 4.91 scales the
flux by wall / wall_in_file, the wall loading recorded with the spectrum. ACTINV follows that rule when the
spectrum declares spectrum.wall_loading_MW_m2 (the loading its group fluxes correspond to): the step multiplier is
wall / spectrum.wall_loading_MW_m2. Without a reference, ACTINV uses the manual’s closing statement of section
4.91, “a current C, of 4.44 x 10^13 n cm^-2 s^-1 is equivalent to 1 MW m^-2” (a 14 MeV neutron current), and sets
the step’s total flux to wall x 4.44e13 n cm^-2 s^-1 with the spectrum’s shape; that needs a spectrum with a
positive total. The constant is spec::WALL_CURRENT_PER_MW_M2. A step spectrum uses its own reference. A zero
loading is a cooling step on any spectrum, with or without a reference. The 14 MeV equivalence describes a neutron
current, so without spectrum.wall_loading_MW_m2 a wall step is refused for a proton, deuteron, triton, helion,
alpha or gamma projectile; declare the reference loading instead.
The two bases differ in what they do with flux that rebin places outside the destination structure. With a
reference the multiplier is wall / reference applied to the converted spectrum, so flux lost outside the
destination lowers the step flux. Without one the multiplier is wall x 4.44e13 over the converted spectrum’s sum,
so the step flux is wall x 4.44e13 whatever was lost. Also without a reference, the step flux does not depend on
spectrum.total (only the shape is used), so a scan that scales spectrum.total changes nothing for such steps;
with a reference it scales them. The ledger
gains wall_loading, one record per wall step: step, wall_loading_MW_m2, basis
(spectrum_reference_wall_loading or 14_MeV_current_equivalence), reference_wall_loading_MW_m2,
current_per_MW_m2_cm2_s, flux_multiplier and step_total_flux_cm2_s.
A fragment (the reference loading belongs to the spectrum’s group fluxes):
"spectrum": {"wall_loading_MW_m2": 4.15},
"schedule": [
{"dt": "1 y", "wall_loading_MW_m2": 2.0},
{"dt": "10 y", "flux": 0}
]
Partition (schedule[].partition)
partition is a map from element symbol to the fraction of that element’s atoms kept at the start of the step
(FISPACT-II section 4.54 PARTITION: a value of 0.01 for Ar reduces Ar by a factor of 100). Every nuclide and
isomeric state of the element is scaled; the removed atoms move to the removal sink that removal also uses and are
reported as removed_atoms_per_g. Fractions must lie in [0, 1] and keys must be elements. The split is applied
before the step evolves and also acts on the uncertainty tangents and the comparison solution. An empty
partition: {} is no partition. A composition isotope of the element that has no decay record is not a chain state,
but the partition scales it too (its atoms move to the sink and the step summary shows the kept share).
A partition removes bulk atoms, which the trace formulation cannot represent (it holds the bulk undepleted), so
options.mode: "trace" with a partition is an error, and auto selects coupled. The ledger gains partition:
applied (per step and element: step, element, fraction_kept, removed_atoms_per_g), mode,
mode_forced_coupled (true only when auto would otherwise have chosen trace: burn-up or the decay of a
radioactive bulk nuclide already select coupled), numerical_floor_atoms_per_g_max and removed_atoms_per_g_final.
Partition is not accepted by mesh specs, study specs, reverse solves or the waste-composition solve, and is refused
together with pathways and schedule library overrides.
The coupled formulation carries the bulk material as a state, so its CRAM numerical scale alpha0 x max(N) (see the
numerical floor diagnostic) can sit above trace-level activation products; populations
below it are reported, not removed. A partition that moves an otherwise trace run onto coupled therefore changes
the precision at which trace products are resolved. numerical_floor_atoms_per_g_max is the worst step’s scale in the
ledger’s partition entry; compare it with the products you care about, or set options.mode explicitly.
A fragment:
"schedule": [
{"dt": "1 y", "flux": 1.0},
{"dt": "1 d", "flux": 0, "partition": {"Ar": 0.01, "Fe": 0.5}}
]
Named data overrides (overrides)
overrides is an optional list replacing data for a named nuclide (FISPACT-II section 4.53 OVER). They are
applied while the reaction and decay networks are assembled, and each is listed in the ledger under overrides.
kind | FISPACT-II | fields | effect |
|---|---|---|---|
cross_section | ACROSS | nuclide, mt, value (barns, >= 0) | Sets the reaction’s one-group collapsed cross section for the run’s spectrum. Product branching is kept. |
cross_section_scale | none (ACTINV) | nuclide, mt, value (> 0) | Multiplies the collapsed value. |
half_life | ALAM | nuclide, value, units (default s) | Replaces the half-life; the units are any schedule duration unit. |
cross_section_uncertainty | ADCROSS | nuclide, mt, value | Replaces the relative standard uncertainty of the reaction; needs the cross_section_mf33 channel and a covariance. |
half_life_uncertainty | ADLAM | nuclide, value | Replaces the decay constant’s relative standard uncertainty; needs the decay_constants channel. |
Differences from the manual: FISPACT-II selects an ACROSS reaction by daughter, ACTINV by ENDF reaction number
mt; ADCROSS/ADLAM take a relative standard uncertainty, not an error factor. A cross-section rescale keeps the
correlations of the covariance row. A name that matches no library row or decay record is an error. Cross-section
value overrides cannot be combined with uncertainty (the MF=33 collapse is anchored to the library value), and an
absolute cross_section cannot be combined with self_shielding. Duplicate overrides, and a cross_section and a
cross_section_scale on the same reaction, are rejected. A cross-section override’s ledger entry records the
one-group collapsed value before and after, under the base spectrum only.
An absolute cross_section is one barn value imposed under every spectrum of the schedule: a step with its own
spectrum gets the same number as the base spectrum (the product branching still follows each spectrum). It cannot
set a nonzero value on a reaction that collapses to zero under a spectrum, so the check is made against the base
spectrum when a step uses it and against the spectrum of every step that irradiates; the spectrum of a cooling step
never reads the cross section and is not checked.
A fragment (names are resolved against the library and decay data when the problem is run):
"overrides": [
{"nuclide": "Fe56", "kind": "cross_section_scale", "mt": 16, "value": 0.8},
{"nuclide": "Co60", "kind": "half_life", "value": 5.27, "units": "y"}
]
Decay-only runs
A spec whose every step has zero flux needs no activation library: omit library (or leave library.path empty)
and spectrum. The decay data and the material are read as usual and the schedule is a pure decay/cooling
history. A spec that omits library with any irradiating step is rejected with a message naming the step rule.
Everything that needs a library is rejected for a decay-only spec: uncertainty, self_shielding, damage,
fission_yields files, kerma, options.rate_scale, options.yield_scale, library.sha256 and cross-section
overrides. half_life overrides remain allowed; half_life_uncertainty needs an uncertainty section, which a
decay-only run does not support, so it is refused. A spec that gives a step spectrum but no base spectrum, or a
library but no spectrum, is refused with a message saying that a spectrum is required. The ledger and certificate
carry
decay_only: true and the library and library-index inputs are null. Runs that supply a library are unchanged.
Mesh specs still require a library.
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, and
enter the matrix only when yields is "cumulative" (below). 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.
Rate-weighted energy, parent selection and cumulative yields
Three further options, all opt-in; without them every output is unchanged.
energy: "rate_weighted" forbids fixed_energy_eV and mixes the evaluation’s tabulated yield sets instead of
interpolating at one energy. For each parent and each distinct step spectrum, with tabulated incident energies
E_1 < ... < E_K, library group fission rates r_g = phi_g sigma_f,g (the parent’s MT=18 group cross section
and the spectrum’s group flux) and group energies E_g = sqrt(E_lo E_hi), the weights are
w_k = sum_g r_g h_k(E_g) / sum_g r_g
where h_k are the piecewise-linear hat functions on the E_k (h_1 = 1 at and below E_1, h_K = 1 at and
above E_K; between two tabulated energies the two adjacent hats are 1 - w and w, the weights
effective() uses at one energy). The yield of product i is Y_i = sum_k w_k Y_{k,i} over the tables with
nonzero weight; a product missing from one of them counts as zero yield and zero uncertainty. The standard
uncertainty is sqrt(sum_k w_k^2 sigma_{k,i}^2). A spectrum confined to one group therefore gives the same yields
as "fixed" at that group’s midpoint. A parent with no fission rate in a spectrum (sum r_g = 0) falls back to the
spectrum_average rule, which also finds no fission energy there, so it carries no yields in that spectrum; the
weights record names the fallback. Every distinct step spectrum gets its own weights. The mixing needs the
groupwise library rows, so a spectrum-collapsed cache is not used. It cannot be combined with the
fission_yields uncertainty channel.
parents selects which parents’ fission feeds products:
"fission_yields": {
"files": [
{"path": "/data/endfb-viii.0-nfpy/nfy-092_U_235.endf", "sha256": "64 hexadecimal digits"},
{"path": "/data/endfb-viii.0-nfpy/nfy-094_Pu_239.endf", "sha256": "64 hexadecimal digits"}
],
"parents": {"include": ["U235", "Pu239"]}
}
Give exactly one of include or exclude, a nonempty list of nuclide names (U235, Am242m1). A parent with a
yield file that the selection leaves out keeps its fission reaction and loses nothing from the burn-up diagonal; its
whole fission rate goes to leakage and is booked per parent as fission_unselected_to_leakage. These are refused
before any output: both include and exclude, an empty list, a name that is not a nuclide, a named parent without a
yield file in files, and a named parent with no fission (MT=18) row in the activation library.
yields: "cumulative" (default "independent") reads the MF=8/MT=459 tables in place of MT=454, with the same energy
selection and the same parents filter; an evaluation without MT=459 is refused. Cumulative yields already include
the feeding of each product by its fission-product precursors, and the decay chain feeds the product again, so the
inventory counts that feeding twice. This is an approximation the run reports and does not correct: the ledger’s
fission_cumulative_overlap gives, for each active parent, the summed cumulative yield and the share of it carried
by products that have a direct decay precursor (a chain nuclide with a positive decay edge to the product) that also
has a positive cumulative yield from the same parent.
Spontaneous fission
Without further input, a decay state’s spontaneous-fission branch (RTYP 6) is booked to leakage and counted
in the ledger’s spontaneous_fission_branches_to_leakage. fission_yields.spontaneous routes it to products
instead, and supplies the neutron multiplicity for a spontaneous-fission neutron source. A fission after another
transition (RTYP 2.6, β-delayed fission) is not spontaneous fission of the parent: it is always booked to leakage and
counted in unmodelled_decay_branches_to_leakage. Every input is hash-pinned and optional, but the object must
declare at least one:
"fission_yields": {
"spontaneous": {
"files": [{"path": "/data/sfy/spontaneous-yields.endf", "sha256": "64 hexadecimal digits"}],
"nubar_endf": {"path": "/data/endfb-viii.0-decay/endf-b-viii-0_decay.dat", "sha256": "..."},
"nubar_table": {"path": "nubar.json", "sha256": "..."}
}
}
filesare ENDF-6 MF=8/MT=454 spontaneous-fission yield evaluations (the ENDF/Bsfysublibrary, same record layout as the neutron-induced files). A file may hold one material or the whole sublibrary; each material is one parent. Yields are read at the lowest tabulated incident energy, which is0for spontaneous fission, and the same checks apply (independent yields sum to two fragments within1e-6, no renormalization). A state with a spontaneous-fission branch and a yield evaluation sendsλ · BR_SF · yieldto each fragment, so one decay makes two product atoms and nothing goes to leakage. A fragment absent from the decay library is booked to leakage by name. A state with the branch and no evaluation keeps the branch on leakage and is named underledger.spontaneous_fission.uncovered_to_leakage; no other parent’s yields are borrowed. Only a branch that is the whole decay mode is routed.nubar_endfnames an ENDF file whose MF=1 MT=452 (total, preferred) or MT=456 (prompt) section gives each state’s spontaneous-fission neutron multiplicity. The total includes the delayed neutrons that follow the fission (for Cf-252, 3.7676 total against 3.7590 prompt), so the neutron source is about 0.2 % above the prompt-neutron source at fission time there, and differs by each nuclide’s own delayed fraction elsewhere. The multiplicity is taken atE = 0(a polynomial’s constant term, or the lowest tabulated point, recorded in the ledger). The ENDF/B-VIII.0 decay sublibrary carries these values (Cf-252: 3.7676). Do not name a neutron sublibrary: its MF=1 is the induced-fission multiplicity.nubar_tablenames a JSON document{"source": "<citation>", "nubar": {"Cf252": 3.7676, ...}}. The citation is required and recorded in the certificate; keys are explicit nuclide names. Its entries overridenubar_endffor the same state. ACTINV builds in no multiplicity, and a state with an SF branch and no multiplicity is reported as uncovered, never estimated.
With any nubar_* input every step gains fission.spontaneous_neutron_source (see Read your results).
Fission count and burn-up
options.fission (absent by default) adds a fission.count block to every step:
"options": { "fission": { "energy_per_fission_MeV": 200.0 } }
energy_per_fission_MeV defaults to 200, a conventional round figure and not a nuclide-specific energy; it affects
only the MWd/kg burn-up and must be finite and positive. The option works without fission-yield files: every library
fission (MT=18) row whose target nuclide is a state of the decay chain is counted, whether or not yields exist for it
(a row whose target has no decay record is listed under targets_absent_from_decay_library and is not counted). Both this option and
fission_yields.spontaneous are refused by the native waste composition solve. The count integrates one flux
multiplier per step, so options.fission is refused with power-driven steps (whose multiplier is solved per
sub-interval) and with schedule library overrides (the count reads the base library’s MT=18 rates).
fission_yields.spontaneous reads decay data only and combines with both.
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 (1.4.0) 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. A state-resolved (MF=10) product row takes its reaction’s MF=33 covariance, fully
correlated with the reaction total, so a product such as Co-58 from Ni-58(n,p) is in the band. Its isomer-branching
uncertainty (MF=40) is not. Such a response counts these rows in parameters_from_reaction_total, its
cross_section_mf33 channel says so in note, and its coverage is partial. 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
| Field | Meaning |
|---|---|
isomer | Optional object with top (1–256), reporting isomer-resolved variance and pathway partitions |
design | Optional object with top (1–256), ranking variance removed by a perfect measurement using the covariance model |
unmodeled_relative | Declared finite nonnegative relative term; adds (u * nominal)^2 to variance |
unmodeled_table | Hash-pinned actinv-unmodeled-table-1 file, optional material-family key, and nonnegative fallback |
unmodeled_evalspread | Hash-pinned actinv-eval-spread-1 artifact supplying its suggested relative term |
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, inhalation_dose, a2, or activity_limit. Clearance/waste coefficients are limits in Bq/kg;
ingestion/inhalation coefficients are in Sv/Bq; a2 coefficients are A2 transport values in Bq (the FISPACT-II ATWO
index sum(A_i / A2_i), reported per gram of material); activity_limit coefficients are any other absolute activity
limit in Bq (A1, an exempt consignment or practice total), giving sum(A_i / limit_i) per gram of material. A2 values
are bundled (below), or supply your own table, converting IAEA TBq values to 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.
A response may also carry two optional lists for what a coefficient cannot say. Tables without them are read exactly as before, so existing hash-pinned tables are unaffected.
unlimited: canonical nuclides whose source limit is “Unlimited”. They have no coefficient (listing one that has a coefficient is an error). Their activity counts as covered and contributes zero, because an unlimited A1 or A2 limit adds nothing tosum(A_i / limit_i). The step lists the active ones inunlimited_active_nuclides; they are not inmissing_active_nuclides, sorequire_complete: trueaccepts them.covered_by_parent: a map from a progeny to the parents whose value already includes it. While any listed parent has positive activity, the progeny’s activity counts as covered and contributes zero, even when the progeny has a coefficient of its own, so a decay chain holding both is not counted twice. The step lists these ascovered_by_parentpairs ofnuclideandparent. With no listed parent present the progeny is evaluated like any other nuclide: its own coefficient, or missing. Every parent must itself have a coefficient or beunlimited, a nuclide may not be its own parent, and the map may not contain a cycle.
Both keys are omitted from the step output when nothing in them is active, and the certificate gives
unlimited_count and covered_by_parent_count only for a response that uses them.
{
"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": "a2-example",
"kind": "a2",
"basis": "A2 in Bq",
"coefficients": {"Co60": 4.0e11, "Cs137": 6.0e11},
"unlimited": ["Mn53"],
"covered_by_parent": {"Ba137m1": ["Cs137"]}
}
]
}
See the qualification boundary before using a regulatory table.
A table’s source may also carry the optional strings scope, retrieved, source_file, source_sha256,
converter, licence, and row_provenance. When present they are nonempty and are kept in the certificate.
Bundled regulatory tables
ACTINV ships a few regulatory tables inside the program, converted from public sources by scripts that are kept in
the repository. They are opt-in: set radiological.table.path to bundled:NAME. Nothing is selected for you, there
is no default jurisdiction, and an unknown name is an error that lists the available names.
"radiological": {
"table": {"path": "bundled:us-49cfr173-a2"},
"responses": ["a2-u-medium"]
}
actinv fills a missing sha256 from the bundled table and rejects a different one. Other front ends must declare
the 64-hex-digit SHA-256 of the table, which is recorded in the result like any other table.
| Name | Source and scope | Coefficient | Licence |
|---|---|---|---|
us-49cfr173-a1, us-49cfr173-a2 | 49 CFR 173.435 (eCFR, 2026-10-13), the IAEA SSR-6 Rev.1 (2018) Table 2 A1 and A2 values. United States transport of radioactive material. | A1 or A2 in Bq (from TBq) | US Government work, public domain |
us-49cfr173-exempt-concentration | 49 CFR 173.436, exempt material activity concentration. Transport. | Bq/kg (from Bq/g) | public domain |
us-49cfr173-exempt-consignment | 49 CFR 173.436, exempt consignment activity. Transport. | activity in Bq | public domain |
euratom-2013-59-annex-vii-a | Council Directive 2013/59/Euratom, Annex VII Table A Part 1: exemption and clearance of solid material, artificial radionuclides. European Union (national law may differ). | Bq/kg (from kBq/kg) | EU reuse with attribution |
euratom-2013-59-annex-vii-b-concentration | Annex VII Table B column 2, exemption of moderate amounts. | Bq/kg (from kBq/kg) | EU reuse with attribution |
euratom-2013-59-annex-vii-b-activity | Annex VII Table B column 3, total activity for exemption. | activity in Bq | EU reuse with attribution |
de-strlschv-2018-anlage-4 | Strahlenschutzverordnung 2018, Anlage 4 Tabelle 1: unrestricted clearance (column 3) and the specific clearance routes (columns 6 to 11 and 14), one clearance_index response per route. Germany. Not an official version. | Bq/kg (from Bq/g) | official work, section 5(1) UrhG |
uk-epr-2016-sch23-pt3-table-2 | Environmental Permitting (England and Wales) Regulations 2016, Schedule 23 Part 3 Table 2, concentration of radionuclides in a solid or relevant liquid. United Kingdom (England and Wales). | Bq/kg (from Bq/g) | Open Government Licence v3.0 |
ca-nsrdr-2000-207-schedule-2 | Nuclear Substances and Radiation Devices Regulations (SOR/2000-207), Schedule 2, unconditional clearance levels. Canada. Not an official version. | Bq/kg (from Bq/g) | Reproduction of Federal Law Order (SI/97-5) |
Each table’s source block names the title, edition, URL, retrieval date, SHA-256 of the source file, converter script
(scripts/regulatory/), and licence. The converters read the downloaded file and type no numbers. Tables and the
per-row sidecars are under crates/actinv-core/data/regulatory/; a sidecar (*.rows.json) holds the original row text,
footnote markers, flags, and the reason any source row is not in a table. ACTINV does not read the sidecars.
How to read the tables:
- Limits in Bq, not Bq/kg. The A1, A2, and total-activity tables hold an activity in Bq, with response kind
a2(A2) oractivity_limit(A1, exempt consignment, Directive Table B column 3). The index is the number of limits per gram of material; multiply by the mass in grams to compare a consignment or inventory. - Uranium. The transport tables list uranium by lung-absorption type. Each carries three responses that differ only
in the uranium rows:
...-u-fast,...-u-medium,...-u-slow. An emptyresponseslist returns all three; choose one deliberately. - Unlimited rows. Rows with no finite limit (“Unlimited” in 49 CFR 173.435: Mn-53, Ni-59, Zr-93, I-129, Th-232 and
others) are listed in the response’s
unlimitedlist. Their activity is covered and contributes zero, so an activation inventory that holds them still satisfiesrequire_complete: true. A few uranium rows are unlimited in only one lung-absorption response, as in the source (U-236 in-u-fast). - Element-level rows. Rows such as
U (nat)orRb(nat)cannot be coefficients. They are in the sidecar. ACTINV reports their activity as uncovered and never as zero, sorequire_complete: truerejects a run that needs them. - Parents with progeny. Rows marked as including progeny (footnote (b) in 173.436, (1) or (2) in the Directive) keep
the parent’s value, and the table’s
covered_by_parentmap lists the progeny of each such parent. While the parent has activity, a listed progeny (Ba-137m under Cs-137, Rh-106 under Ru-106, Pa-234m under Th-234) is covered with zero contribution instead of being reported as missing; a progeny that has its own row (Y-90 under Sr-90) is not summed a second time. The inventory does not need editing. If the progeny is present without its parent, it uses its own row or is missing, as for any nuclide. 49 CFR 173.435 footnote (a) only refers to the IAEA SSR-6 list of such parents, which the CFR does not reproduce; for those tables the converter uses the 173.436 footnote (b) progeny lists for the parents that carry footnote (a). Footnote (a) parents that the 173.436 list does not name have nocovered_by_parententry, so their progeny can still appear as missing; the rows sidecar marks themparent_with_progeny_not_in_173_436_list. - Notes kept in the sidecar only. The A2 of Mo-99 in the table is 0.6 TBq; 49 CFR 173.435 footnote (i) gives 0.74 TBq for domestic use. The Directive’s Table B K-40 entry carries the note on potassium salts below 1000 kg. Neither is in the coefficient tables; read the sidecar rows when either applies.
- Source anomalies are recorded rather than corrected: the Directive’s Table B lists U-240 twice (the nuclide-alone row is used), and its parent/progeny marks disagree with its progeny lists for a few nuclides.
- Isomer labels. Three CFR rows use lifetimes (
Eu-150,Np-236,Ta-178). They are mapped to ACTINV isomer states by the decay half-lives in ENDF/B-VIII.0, and flagged in the sidecar.
These tables carry the regulation’s numbers only. Whether a table applies to your material, jurisdiction, and use is your decision.
Building the ICRP 119 dose-coefficient table locally
ICRP Publication 119 (the carrier of the ICRP 72 public ingestion and inhalation coefficients) is copyrighted, so ACTINV does not ship its values. If you have a copy of the PDF, generate a table for your own use:
python3 -I scripts/regulatory/fetch_icrp119.py --pdf P119.pdf --out icrp119.json --fispact-convention
This needs pdftotext (poppler). The script reads Annex F (ingestion, adult) and Annex G (inhalation, 1 um AMAD,
adult, types F/M/S) and writes one response per variant (ingestion-adult-variant1, inhalation-adult-F, …) next
to an icrp119.variants.json that records every choice. With --fispact-convention it adds
ingestion-adult-fispact-max and inhalation-adult-fispact-max, the maximum over the f1 variants and over F/M/S,
which is the convention found in FISPACT-II’s hazards file for its ICRP 72 rows. Keep the output out of version
control and do not redistribute it. --download-url URL --yes-download fetches the PDF first, but only from a URL you
confirm.
scripts/regulatory/compare_fispact.py compares a table with the clearance, A2, or hazards files of a FISPACT-II
2012 data bundle that you hold. It is a QA report, not a feature; the FISPACT files are never copied into ACTINV.
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; with a table-1 file every
covered element must have one, with an actinv-damage-table-2 file an omitted element takes the energy the table
records, 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. For TENDL-2025 neutron targets that are stable or have a half-life of at least one year, the data
catalog (1.2.0) ships a ready table, catalog:tendl-2025-neutron-damage, built with the kinematic method; for other
data, build tables from heatr-processed or equivalent damage-energy evaluations, or build an
actinv-damage-table-2 table with actinv build-damage --method kinematic.
Kinematic damage energy and the table-2 format
--method kinematic computes the damage-energy cross section channel by channel on the 0 K pointwise grid
(resonances included for MT=2 and MT=102). Elastic scattering and the discrete two-body levels use the MF=4 or
MF=6 LAW=2 angular distribution and the MF=3 Q value; single-particle continua (MT=91, 649, 699, 749, 799, 849,
and MT=103-107 when no level MTs exist) use MF=6 LAW=1 Kalbach-Mann or Legendre distributions; capture uses the
incident momentum plus the photon recoil. Recoil energy becomes damage energy through the Lindhard partition in
Robinson’s fit (NJOY HEATR df); a recoil below E_d produces none. E_d defaults per element to the table NJOY2016
HEATR applies when no ed is given (Be 31, C 31, Mg 25, Al 27, Si 25, Ca 40, Ti through Cu 40, Zr 40, Nb 40, Mo 60,
Ag 60, Ta 90, W 90, Au 30, Pb 25 eV; 25 eV for any other element); --displacement-energy EL=eV overrides it. Quadrature is Gauss-Legendre in the emission
cosine, split at the threshold and the NRT breakpoints, and the incident-energy grid is refined until a lin-lin
midpoint agrees within 1e-3. The group collapse is the flat-lethargy weighting of the other builders.
Capture recoil: with --capture-photons evaluated (default) the photon spectra of MF=6 are used where the
evaluation carries them, and the result is flagged evaluated_photon_spectrum: one recoiling nucleus takes the
incident neutron’s momentum and the summed expected photon recoil (the momenta of a cascade emitted before the nucleus
has slowed down add as a single recoil), and its damage energy is partitioned once. With per-photon, NJOY HEATR’s
treatment of MF=6 photon data (tabsq6), each photon’s recoil E_gamma^2 / (2 (A + 1) m_n c^2) is partitioned
separately and averaged over the discrete lines and the continuum, times the photon multiplicity, with no
incident-neutron momentum; the result is flagged per_photon_spectrum. The multiplicity is taken at each record’s
incident energy and the product is interpolated linearly between records, as HEATR does; each continuum panel is
integrated by 8-point Gauss-Legendre after splitting at the photon energies whose recoil reaches the displacement
threshold and the NRT breakpoints (HEATR uses 4-point Gauss-Legendre over the whole panel). Where the evaluation has no
MF=6 photons, per-photon falls back to the one-photon treatment. With one-photon (and the fallbacks), the excitation
energy is emitted as one photon (NJOY HEATR capdam), flagged excitation_energy_one_photon_upper_bound. A cascade of
several photons recoils less than one photon, so the one-photon value is an upper bound; the treatments therefore
differ for capture. The mode is recorded as model.capture_photons and is part of the cache key.
Continuum recoil: with --continuum-recoil kinematic (default) the residual’s recoil in an MF=6 continuum channel
(MT=91, 649, 699, 749, 799, 849 and the lumped MT=103-107) follows from momentum conservation with the emitted
particle’s evaluated energy distribution and, for Kalbach-Mann data without an explicit slope, Kalbach’s systematics;
it is consistent with the ejectile data. With evaluated, where the section carries a residual-nucleus subsection
with an explicit LAW=1 recoil energy distribution (a heavy product under LCT=1 or LCT=3, read as a laboratory
spectrum), the damage comes from that spectrum, as NJOY HEATR does: per incident-energy record the recoil histogram is
passed through the damage function, the record values are interpolated linearly in energy and multiplied by the
multiplicity (each panel is integrated by 8-point Gauss-Legendre after splitting where the response is not smooth;
HEATR uses a trapezoid on the damage function). Channels without such a subsection (including LAW=4 and
centre-of-mass recoil spectra) keep the kinematic recoil. In the TENDL-2025 evaluations of Fe-56, Cr-52 and Ni-58 the
two differ for MT=91, because the recoil spectrum lies partly outside the kinematic window of the neutron data. The
mode is recorded as model.continuum_recoil, each continuum channel note carries recoil (evaluated_recoil_spectrum
or kinematic_no_evaluated_recoil) when evaluated is requested, and channels.evaluated_recoil_channels counts the
channels that used the evaluated spectrum.
Every other non-elastic channel that has a cross section is uncovered: the table records its cross section and an
upper bound on its damage energy from the largest recoil the kinematics allow, D <= T. Ultra-narrow analytic
resonance lines that the pointwise grid does not carry are not added to the damage cross sections.
A table-2 file has the table-1 fields (format actinv-damage-table-2, source, projectile, group_structure,
boundaries_eV, units, targets) and these additions. displacement.displacement_energy_eV maps each element to
the E_d the recoil integrals were built with, and displacement.arc_dpa holds the constants b, c and the fit’s
reference displacement energy for the elements in Table 1 of Nordlund et al., Nat. Commun. 9, 1084 (2018) (Fe, Cu,
Ni, Pd, Pt, W; other elements have no arc-dpa output). The arc-dpa displacement count is evaluated at that reference
energy (Fe 40, Cu 33, Ni 39, Pd 41, Pt 42, W 70 eV), whatever E_d the damage energy and the NRT count use, because
the constants are only defined there; a table built at the reference energy is unchanged by this. Each target row holds damage_energy_barn_eV (the total, equal
to elastic + inelastic + disappearance), the three partials, uncovered_xs_barn, uncovered_damage_upper_barn_eV,
displacement_nrt_barn, displacement_arc_barn (when constants exist) and an informational channels record. The
total feeds the linear dpa exactly as a table-1 file does.
The 0 K resonance reconstruction sets a finite negative cross section to zero, as NJOY RECONR does for a negative
resonance-range value. When that happens for an MT, the target’s channels.zero_k_clipped array gains a record
{mt, points, min_barn, min_energy_eV, low_eV, high_eV} (the number of distinct clipped energies, the most negative
value and its energy, and the energy span of the clipped points); the key is absent for an evaluation with no negative
value. A nonfinite value still fails the build. With --continue-on-error true, an evaluation whose processing fails is
skipped: the top-level failed array lists {file, sha256, error} for each, sorted by file, the file still appears in
files, and the array is absent from a table with no failure.
With a table-2 file each step and each element add dpa_nrt_rate_per_s, dpa_nrt (exact NRT, integrated over the
recoil spectrum), dpa_arc_rate_per_s, dpa_arc (absent unless every covered element has constants),
damage_energy_uncovered_upper_eV_per_g_s, dpa_uncovered_upper_bound_rate_per_s and dpa_uncovered_upper_bound
(damage-energy bound divided by E_d). The step adds he_appm_per_dpa, the cumulative He-3 plus He-4 appm over the
cumulative linear dpa, when gas output is requested. An explicit displacement_energy_eV in the spec must equal the
table’s build value for every covered element; otherwise validation fails and names the rebuild command. A covered
element the spec omits takes the table’s value, and the ledger’s damage.displacement_energy_eV lists the energies
used while damage.displacement_energy_source names each covered element’s source, "spec" or "table". Where an
element’s arc reference energy is below its E_d, dpa_uncovered_upper_bound divides by the lower energy so that it
bounds the arc count as well.
Kerma heating and power-driven steps
kerma is optional. It adds an instantaneous nuclear-heating output to every step and lets a schedule step name a
heating power instead of a flux, as FISPACT-II’s POWER keyword does. Without a kerma section, and without a
step that names a power, the problem, its result and its ledger are byte-for-byte what they were before.
"material": {"composition": {"Fe": 100.0}, "density_g_cm3": 7.874},
"kerma": {
"table": {"path": "/data/kerma/fe_kerma.json", "sha256": "64 hexadecimal digits"},
"power_tolerance": 0.001,
"max_substeps": 64,
"top": 10
},
"schedule": [
{"dt": "1 y", "power_W_cm3": 150.0},
{"dt": "10 y", "flux": 0}
]
kerma.table is a hash-pinned actinv-kerma-table-1 file; the declared SHA-256 is recomputed before the run.
require_complete: true rejects the run when a material nuclide has no heating row (otherwise such nuclides add no
heating and are named in the ledger’s kerma.uncovered_composition_targets). Heating is summed over the decay
chain’s states, so coverage is judged there too: a composition isotope with no decay record is not a chain state and
heats nothing, whichever table row would match it, so it is listed as uncovered (and rejected by require_complete).
A kerma section is refused in a decay-only spec, which has no activation library whose group structure the table
must match. power_tolerance (default 0.001,
open interval (0, 1)), max_substeps (default 64, 1 to 4096) and top (default 10, the number of contributors listed
per step) are described below.
Table format. Strict JSON; unknown fields are an error.
| field | meaning |
|---|---|
format | actinv-kerma-table-1. |
source | citation, edition, url, all nonempty. |
projectile, group_structure, boundaries_eV | The projectile must match the problem; boundaries_eV must equal the activation library’s boundaries exactly. |
units | kerma_barn_eV_per_group. |
targets | Canonical explicit nuclide (Fe56, Ta180m1) or element (Fe) keys, each with one finite barn·eV value per group. A nuclide row wins over its element’s row. |
damage_energy_targets | Optional, same keys; nonnegative barn·eV damage-energy production. Every key must be covered by a targets row (a damage row is read through the heating row of the same state); one without is an error. |
temperature_K, files, uncovered | Optional provenance: the table’s temperature, per-file SHA-256s, and the evaluations that had no kerma section. |
A targets row is the group average of NJOY HEATR’s total heating kerma, ENDF MT=301, in eV·barn per atom; the
optional damage_energy_targets rows are the group-averaged total damage-energy production, MT=444 (NJOY2016
heatr.f90 header: MT=301 total kerma, 444 total damage energy). An atom of nuclide i in group fluxes phi_g
(particles cm⁻² s⁻¹) deposits k_i = sum_g K_ig * phi_g * 1e-24 * 1.602176634e-19 watts. Whether the photon energy
of a capture is counted as heating depends on HEATR’s local flag when the table was made (default 0: gamma rays
are transported and their energy is not deposited at the reaction site); ACTINV reads the table as given and cannot
see that choice, so state it in the table’s source.edition. An element row (Fe) gives every
isotope of that element without a row of its own, and every transmutation product of it, the natural-element
value, and counts them as covered, so covered_atom_fraction is a statement about rows, not about the quality of
their data; an isomer does not fall back to its ground-state row, only to the element row. A negative group value
(energy-balance kerma can go negative where an evaluation’s photon-production data are inconsistent) is accepted and named in the certificate’s
targets_with_negative_group_values; a negative damage-energy value is an error. A table is built from NJOY output
with scripts/build_kerma_table.py (below).
Power-driven steps. A step names power_W_cm3 or power_W_per_g instead of flux; the three are mutually
exclusive (flux: 0 beside a power target is accepted because that is what a result echo carries; any other flux
with a power target is an error). A power must be finite and positive, so cooling stays flux: 0. power_W_cm3
needs material.density_g_cm3 (finite, positive; otherwise unused) and is converted to W per gram with it; the
gram-based inventories need no density. A power-driven step requires a kerma section, uses the step’s own
spectrum when it has one, and may combine with feed/removal. It is refused with uncertainty,
options.screen, options.fission, pathways, schedule library overrides, the reverse and study tools and mesh
specs. It does combine with partition, and in trace mode the first-product pathways table is built from the
multipliers each sub-interval applied.
The flux multiplier on the step’s spectrum is chosen so that the instantaneous heating
sum_i N_i(t) * k_i(spectrum) * multiplier equals the requested power, with N_i the evolving atoms per gram of
every nuclide that has a kerma row (transmutation products with a row contribute). FISPACT-II fixes the flux once
per POWER card from the inventory at the start of the interval, and the user is expected to break a long
irradiation into sub-steps by hand. ACTINV does that automatically: the step is split into equal sub-intervals, the
multiplier is set at the start of each from the composition then reached, and every sub-interval’s end-of-interval
power is compared with the request. If the largest relative departure (the power drift) exceeds power_tolerance
the number of sub-intervals doubles (up to max_substeps) and the step is solved again from its start. A cap of 1
reproduces FISPACT-II’s start-of-step normalization. The achieved multipliers, the total flux in each sub-interval
and the worst drift are reported (see results); a step that hits
max_substeps above the tolerance is reported with converged: false and listed in the ledger, not hidden;
actinv run also prints a warning on stderr naming each such step (the result file is unchanged). The default
tolerance and cap do not converge a strongly burning case (for B-10 under a power target, 64 sub-intervals leave a
drift of about 1.5 % and about 1024 are needed), so check converged. The drift measures the interval end only,
which bounds the interior when power varies monotonically across a sub-interval.
A power step needs heating from the material it starts with. The flux used for pruning, and the first sub-interval’s multiplier, come from the composition at the start of the run, so a power step is refused before the schedule starts when that starting material has no kerma heating under the step’s spectrum, even if an earlier step would breed a nuclide that has a row. Start such a schedule with a flux-driven step on a material that has heating, or add a row for the starting material. A heating that turns negative (a legal negative table row) or non-finite during a step is reported as such, and a heating that vanishes in a refined attempt names the sub-interval and says that a coarser attempt had run.
A fragment (the kerma table pattern above supplies kerma; power_W_per_g needs no density):
"kerma": {
"table": {"path": "/data/kerma/fe_kerma.json", "sha256": "64 hexadecimal digits"},
"max_substeps": 256
},
"schedule": [
{"dt": "30 d", "power_W_per_g": 0.05},
{"dt": "1 d", "flux": 0}
]
Rate pruning and the automatic burnup-mode choice are decided before the schedule is solved, so for a power-driven
step they use the flux amplitude implied by the starting composition (reported per step as
estimated_flux_multiplier). If the achieved multipliers differ greatly from it, set options.prune and
options.mode explicitly.
Kerma output. With a kerma section every step reports its instantaneous heating at the step’s end. Flux-driven
steps use their flux multiplier; a power step uses its final sub-interval’s. See the results guide for the fields.
Build a kerma table
python3 scripts/build_kerma_table.py OUTPUT.json --pendf fe56.pendf \
--boundaries-from damage_table.json --group-structure fispact-709 \
--temperature-K 293.6 --damage-energy
python3 scripts/build_kerma_table.py OUTPUT.json --gendf fe56.gendf --group-structure my-groups
The script reads ENDF-6 tapes written by NJOY2016 and runs no NJOY. --pendf takes a HEATR-processed PENDF: its
pointwise MF=3/MT=301 (and with --damage-energy MT=444) section is collapsed onto the boundaries of
--boundaries-from (any JSON with a boundaries_eV list) with a flat-in-lethargy weight, the weighting
actinv build-damage uses; linear-linear sections only, and zero outside the section’s energy range. --gendf takes
GROUPR output, whose own group averages and EGN boundaries are used; GROUPR must have been run with lord=0,
nsigz=1 and one temperature per tape, and a GENDF names every material as a ground state because it carries no
isomer designation. A material without MT=301 is listed under uncovered, never zero-filled. Several tapes may be
combined into one table; two materials mapping to the same target are an error. The output file’s SHA-256 is printed
for pinning into kerma.table.
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. Instead of a table, a geometry section selects the
resolved-resonance sigmoid-curve model described below; exactly one of the two is required.
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, a
resolved-range segment carries the same moments from a pointwise quadrature of the reconstructed resonance cross
sections, Doppler-broadened (SIGMA1) to each temperature column, 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 damage observables are not shielded and composition dilution uses the
declared material, not evolved inventories.
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.
Monte Carlo sampling statistics
The study.robustness sampling path is the equivalent of FISPACT-II SENSITIVITY/MCSAMPLE. By default
it reports each response’s sample mean, std and sampling error. Declare robustness.statistics (an object,
{} for the defaults) to add a sampling_statistics block per case:
"robustness": {
"samples": 1000, "seed": 17, "responses": ["total_activity_bq_per_g"],
"channels": {"cross_section_mf33": true, "flux_rel_std": 0.05},
"covariance": {"path": "cov.npz", "sha256": "..."},
"statistics": {"percentiles": [2.5, 16, 50, 84, 97.5], "histogram_bins": 20,
"correlation_top": 10, "bootstrap_resamples": 200}
}
Per response and cooling time it gives the distribution (n, mean, std, skewness, min, max,
percentiles, optional histogram), a bootstrap convergence block (standard error of the std and of every
requested percentile), the linear first_order std for the same response when the run computed it (with the
ratio and the gap in bootstrap standard errors), and input_correlations: the Pearson and Spearman
correlation of the response with each sampled input parameter, ranked by |spearman| and cut to
correlation_top, each parameter named by channel and target nuclide, MT, decay-constant or yield edge. A
case-level response_correlation matrix gives the Pearson correlation between all requested responses.
Percentiles are exact order statistics (nearest rank): the smallest sample value x_(k) with
k/n >= p/100, k = max(1, ceil(n p/100)) computed in exact arithmetic on the decimal p; there is no
interpolation. Spearman uses average ranks for ties. One sample has no standard deviation (std is null), and
correlations, the response matrix and the bootstrap need at least three samples; below that they report
{"status": "insufficient_samples"} with the count. The first_order std is compared only when
cross_section_mf33 is the sole enabled channel (the first-order propagation carries that channel only);
otherwise the study’s local_vs_nonlinear has status: "not_comparable" with the enabled channels, and each
first_order says the same.
The sampled input is the natural log of each applied multiplicative factor. Without statistics the
robustness record is unchanged. See the study reference
for every field.
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.
Dilution overrides
self_shielding.dilution_overrides (table mode only) replaces the computed background dilution for chosen
nuclides and groups, the equivalent of FISPACT-II SSFDILUTION:
"dilution_overrides": {"W182": {"300": 100.0, "301": 80.0}, "W184": {"194": 2.5}}
Keys are canonical nuclide names; inner keys are library group indices (0-based, ascending energy, the same
indices as applied_factors); values are positive finite dilution cross sections in barns. For a named group the
supplied sigma0 is used in place of the nuclide’s "composition" or "fixed" value; every other group keeps
the computed one. A nuclide the table does not cover, or a group the table does not carry for that nuclide, is an
error. The ledger and certificate list the applied overrides under dilution_overrides; the reported
sigma0_eff_b remains the computed value.
A fragment with the section it belongs to (the table supplies the covered nuclides and groups):
"self_shielding": {
"table": {"path": "shielding_table.json", "sha256": "..."},
"dilution": "composition",
"dilution_overrides": {"Fe56": {"300": 100.0, "301": 80.0}, "Fe54": {"194": 2.5}}
}
Geometry self-shielding (resolved resonances)
self_shielding.geometry selects FISPACT-II’s SSFGEOMETRY model instead of the Bondarenko table: the
“universal sigmoid curve” of Martinho, Goncalves and Salgado. It is exclusive with table, dilution, sigma0_b
and dilution_overrides, as SSFGEOMETRY and PROBTABLE are exclusive.
"self_shielding": {
"geometry": {
"shape": "foil",
"length_cm": 0.01,
"density_g_cm3": 19.3,
"resonance_files": [{"path": "n_W184.endf", "sha256": "..."}],
"choose": ["W"],
"reactions": "all"
}
}
A fragment that takes the density from the material (the geometry omits density_g_cm3):
"material": {"basis": "wt_percent", "composition": {"FE": 100.0}, "density_g_cm3": 7.874},
"self_shielding": {
"geometry": {
"shape": "wire",
"length_cm": 0.05,
"resonance_files": [{"path": "n_Fe056.endf", "sha256": "..."}]
}
}
shapeis"foil"(length_cm= thickness),"wire"or"sphere"(length_cm= radius), or"cylinder"(length_cm= radius plusheight_cm). Dimensions must be finite and positive;height_cmis required for, and only for, a cylinder. The effective length isy = 1.5 t(foil),2 r(wire),r(sphere),1.65 r h / (r + h)(cylinder). These are the rules of the manual’s Table 25 as quoted; they are not limits of one another (a long thin cylinder tends to1.65 r, the wire is2 r; a wide flat one tends to1.65 h, the foil is1.5 t), so choose the shape that describes the target rather than reading one as the limit of another.density_g_cm3converts the declared material (atoms per gram) to number densities. It may be omitted whenmaterial.density_g_cm3is declared; the geometry then uses that value. When both are given they must agree to1e-9relative, and one of the two is required. FISPACT-II instead takes atoms per unit area or length fromSSFFUEL/SSFMASS; ACTINV uses the run’s own material and a density.resonance_filesare hash-pinned ENDF-6 neutron evaluations, one nuclide each, carrying MF=2/MT=151 resolved resonance parameters (Breit-Wigner, Reich-Moore or R-matrix-limited, LRF=1, 2, 3 or 7). An empty list, an evaluation without MF=2, or one without a resolved range is an error. An LRF=7 feature that cannot be read as the widths below (an unknown channel reference, a KRM other than 3) is an error rather than a dropped resonance. A file may hold several MF=2 isotopes (a natural-element evaluation): each is keyed by its own ZAI, never by the material’s ZA, and an isotope with no usable resolved resonance is listed inresonance_data_unused. Only levels inside the[EL, EH]of the range that lists them count as resonance peaks: R-matrix spin groups carry poles above the resolved range (W-186 lists three near 10.1-10.4 keV withEH= 10 keV) that feed the in-range cross section but are not peaks, so they are dropped and counted per nuclide in the ledger’sshielding.geometry.resonances_outside_range(omitted when none).profile(optional,"none","endfb8"or"tendl", default"none") applies the same tape normalization asbuild-library --profileto each resonance file before it is read. Use"endfb8"for ENDF/B-VIII.1 evaluations (Cu-63, for example, lists a photon exit channel the strict reader refuses without it).chooserestricts the correction to listed nuclides or elements (SSFCHOOSE); every entry must be in the material. A nuclide entry must be supplied by a resonance file (otherwise the run is refused). An element entry shields the isotopes that a file supplies and names the others inshielding_uncovered, as whenchooseis absent (an error underrequire_shielding_complete). Withoutchooseevery material nuclide that a file supplies is shielded; other material nuclides are named inshielding_uncovered.reactionsis"all"(default; FISPACT-II applies the factor to every reaction of the shielded nuclide) or"capture"(MT 102 only).
For each resolved resonance i of a shielded nuclide, z_i = N * sigma_peak,i * y * sqrt(Gamma_gamma/Gamma), with
N the nuclide number density, sigma_peak,i = 4 pi/k^2 * g * Gamma_n/Gamma the Breit-Wigner peak cross section
and g = (2J+1)/(2(2I+1)). The resonance factor is G(z) = (A1 - A2)/(1 + (z/z0)^p) + A2 with A1 = 1.000,
A2 = 0.060, z0 = 2.70, p = 0.82 (FISPACT-II manual Eqs. 43-48). The factor applied in a library group is the
mean of G over the resonances peaking in that group, weighted by w_i = (Gamma_gamma/E^2) * g Gamma_n/Gamma
(Eqs. 49-50); groups without resonance peaks are untouched. The scaled cross sections feed the same per-group fold
as the Bondarenko path, including the MF=33 collapse.
For R-matrix-limited (LRF=7) evaluations, which ENDF/B-VIII and FENDL-3.2c use for many nuclides, the per-resonance
widths come from the spin groups’ channels, classified by their particle pair: the incident-neutron pair (MT=2) gives
the neutron channels, the capture pair (MT=102, including the eliminated photon channel) the capture channels, and
every other channel (fission, charged particles, inelastic) counts only toward the total. Gamma_n, Gamma_gamma
and Gamma are the sums of the channel widths over those three sets. With widths listed (IFG=0) each channel contributes its
magnitude; with reduced-width amplitudes (IFG=1) it contributes 2 P gamma^2, with the penetrability P at the
resonance energy from the same radii, penetrability flags and channel wave numbers as the LRF=7 reconstruction
(P = 1 for the photon channel). Under either, a channel closed at the resonance energy (its pair’s threshold at
or above it) contributes nothing. g uses the spin group’s
|J| and the target spin of the neutron pair, and A is that pair’s mass ratio. Resonances at non-positive energy
or without a positive neutron or capture width are skipped, as for the other formalisms. The single-level sigmoid
model does not use the interference between channels or between resonances that the LRF=7 formalism carries.
The ledger shielding.geometry block and the certificate record, per shielded nuclide, the number density and the
applied factor for each group with its energy range and resonance count, the effective length, and the resonance
file hashes (resonance_files_sha256, certificate inputs.shielding_resonance_files). Limits: the peak cross
section is the single-level Breit-Wigner value (FISPACT-II cites Froehner, JEFF Report 18, for it without
reproducing the formula); only the shielded nuclide’s own peak enters Sigma_tot, the other mixture components are
neglected (the model assumes non-overlapping resonances); the unresolved range, damage and temperature dependence
are not treated; and the sigmoid fit is an approximation to Monte Carlo results for simple shapes, not a
transport calculation.
Mixture self-shielding (pointwise cross sections)
This option is new in 1.7.2. Protocol P178 compared it with OpenMC’s continuous-energy reaction rates; it has not been compared with measurements.
On four fusion materials held out from its development (Eurofer-97, Inconel 718, a W-Ni-Fe heavy alloy and copper), ACTINV’s mixture self-shielding brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same ENDF/B-VIII.1 data, where the unshielded rates differed by up to 32.3%. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by that sentence. Evidence: rates and verdict.
Reconstructing every nuclide’s pointwise cross sections makes a run with a multi-nuclide alloy take minutes rather
than seconds. The reconstruction is done once per nuclide per run, and actinv mesh plans each distinct material
once, so the cost does not grow with the number of cells.
self_shielding.mixture computes per-group resonance self-shielding factors at run time from the material’s own
pointwise cross sections, in place of a precomputed Bondarenko table or the sigmoid curve. It is exclusive with
table and geometry (and with dilution, sigma0_b and dilution_overrides).
"self_shielding": {
"mixture": {
"evaluation_files": [{"path": "n_Cu063.endf", "sha256": "..."}, {"path": "n_Cu065.endf", "sha256": "..."}],
"profile": "endfb8",
"require_complete": false
}
}
evaluation_filesare hash-pinned raw 0 K ENDF-6 neutron evaluations, one nuclide per file (the inputsbuild-libraryreads), each with MF=2/MT=151 resolved resonance parameters and its MF=3 background. The files are verified against their SHA-256 like the geometry’sresonance_files.pointwise_filesreplaceevaluation_files(give one or the other): hash-pinnedactinv-pointwise-1tables, one nuclide each, already at the run temperature (see below).profiledoes not apply to them.profile(optional,"none","endfb8"or"tendl", default"none") applies thebuild-library --profiletape normalization to each file before it is read.require_complete(optional, defaultfalse) refuses the run when a material nuclide above 1e-6 atom fraction has no evaluation file. Without it, such nuclides enter the mixture total through the analytic potential-scattering estimate and are listed in the ledger asbackground_estimated.
For each material nuclide with a file, ACTINV reconstructs the total, elastic, fission and capture cross sections
at the run temperature (resonance contribution plus MF=3 background, Doppler broadened, as build-library does).
The flux is weighted as 1 / Sigma_t(E) per unit lethargy, where Sigma_t is the macroscopic total of the whole
declared mixture. In each library group that overlaps the nuclide’s resolved range, the nuclide’s factor for a channel
is the flux-weighted mean of its cross section over the whole group divided by its plain lethargy mean. The factors
scale the nuclide’s group cross sections as the other modes do (mt 2 elastic, mt 18/19 fission, mt 102 capture, every
other reaction the total factor). Groups that do not overlap a resolved range are unshielded, including the unresolved
range. The method needs a positive run temperature_K. A negative 0 K value (a negative MF=3 background under a
resonance-interference minimum, as in ENDF/B-VIII.1 Fe-54 elastic) is set to zero, as NJOY RECONR does.
With pointwise_files, nothing is reconstructed: each table is used as given, and every library group within its
energy range is shielded, since where the cross sections are smooth the factor is 1. A table is a JSON object with
format "actinv-pointwise-1", nuclide (for example "Cu63"), temperature_K, and energy_eV, total_b,
elastic_b, capture_b and optional fission_b (barns, linear in energy, energies ascending). Its temperature must
be within 1 K of the run’s temperature_K; ACTINV does not re-broaden it. actinv.openmc.export_pointwise writes
these tables from an OpenMC HDF5 library at one of its stored temperatures (OpenMC’s 294 K set serves ACTINV’s
293.6 K default), and ActinvR2SManager uses it for every material by default. A run then takes seconds rather
than minutes. Protocol P190 compared this mode with OpenMC’s continuous-energy rates:
On P178’s four models, ACTINV’s mixture self-shielding with pointwise cross sections exported from OpenMC’s ENDF/B-VIII.1 HDF5 library at 294 K, instead of reconstructed ENDF-6 evaluations, brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same data; each region’s run took at most 73.4 s. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by the sentence above. Evidence: record and verdict.
The ledger shielding.mixture block records the profile, temperature, evaluation files with their hashes, the
covered and background_estimated nuclides, per covered nuclide the number of groups and the smallest applied
scale for each channel, and in zero_k_clips every reaction whose negative 0 K values were set to zero (points,
energy range and the most negative value). With pointwise tables, pointwise_temperatures_K gives each covered
nuclide’s table temperature and the certificate lists the tables as shielding_pointwise_files.
Gas production (H and He isotopes)
This option was added in 1.4.0.
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.
Step summary
summary (optional) adds a complete inventory report, steps[].summary, to every step: a FISPACT-II-style
nuclide table, element table, decay-mode activity totals and dominant-contributor rankings. Without it the result is
unchanged and no summary key is written.
| Field | Default | Meaning |
|---|---|---|
nuclides | true | Emit the per-nuclide table. |
elements | true | Emit the per-element table. |
dominant_top | 10 | Entries kept in each dominant-contributor list; 1 to 256. |
min_atoms | 0 | FISPACT MIND: omit nuclide-table rows whose absolute atoms (atoms × material.mass_g) fall below this. Finite and not negative. |
include_stable | true | false is FISPACT NOSTABLE: omit stable nuclides from the nuclide table. A state with no decay record (a light stand-in, a bulk nuclide missing from the chain, or any state with decay_data: false) is not called stable and stays in the table. |
depletion | false | true is FISPACT DEPLETION: add summary.depletion, the per-step depletion table of every initial-material nuclide. |
min_atoms and include_stable trim the nuclide table only. Totals, the element table and the dominant rankings
always include every state, so a filtered table still reconciles with its totals. The same summary section is
accepted by the mesh specification and applies to every cell.
depletion is opt-in within the summary: without it no depletion key appears in steps[].summary, and the ledger
and certificate carry no depletion entry. It works with trace and coupled mode, with per-step spectra, and with
schedule library switches (each step reports the rates of the library it ran on). With an uncertainty section that
supplies MF=33 covariance, each reaction channel also carries the relative standard uncertainty of its one-group
rate. A schedule step’s removal appears as its own removal channel, and a feed into an initial nuclide as
negative depletion with no channel. The decay channel’s half-life uncertainty is reported whatever
uncertainty.channels lists. Read your results describes the emitted fields.
{
"material": {"mass_g": 10.0, "density_g_cm3": 7.87, "composition": {"Fe": 100}},
"summary": {"dominant_top": 5, "min_atoms": 1e6, "include_stable": false}
}
Read your results describes the emitted fields.
Pathways and routes analysis
The optional pathways object asks for a full source-to-target route analysis (FISPACT-II’s ROUTES and
UNCERTAINTY pathway tables). It is opt-in: without it the result is byte-identical to a run that never heard of
it, and it is independent of the older options.outputs entry pathways, which keeps the trace-mode
first-product table. That table (the result’s pathways array) now also attributes production fed by the decay of
radioactive bulk nuclides (for example Ar-40 from natural K-40), listing the decaying bulk nuclide as from; a
nuclide in the inventory that no listed chain explains makes pathway_closure 1.
"pathways": {
"targets": ["Mn54", "Co60"],
"sources": [],
"max_depth": 10,
"path_floor": 0.005,
"loop_floor": 0.01,
"max_paths": 100
}
| Field | Default | Meaning |
|---|---|---|
targets | [] | Target nuclides. Empty selects the dominant nuclides of the final step automatically. |
rank_by | "activity" | Ranking for automatic targets: "activity" or "heat" at the final step. |
top_targets | 10 | Number of automatic targets. |
sources | [] | Source nuclides. Empty selects every initial nuclide (in trace mode the bulk material’s nuclides, plus feed when the schedule declares one). |
max_depth | 10 | Largest number of edges between a source and a target (1 to 64). |
path_floor | 0.005 | A route is kept when it carries at least this fraction of its target’s inventory. |
loop_floor | 0.01 | A walk that revisits a nuclide is kept when it raises its loop-erased path’s contribution by at least this fraction. |
max_paths | 100 | Routes reported per target; the excess is dropped smallest first and shows up in the residual. |
by_step | false | Also report every route’s atoms at the end of each schedule step. |
fission_parents | [] | Nuclide names. When nonempty, routes may pass through fission edges only from these parents; the inventory is unchanged, and what the other parents’ fission products received is reported as unexplained in each target’s closure residual. Empty places no restriction. |
Nuclide names are explicit nuclides such as Mn54 or Co60m1. A source that is not an initial nuclide, or a target
that is not a tracked state of the run, is named in the result’s notes rather than failing the run.
fission_parents removes only edges that are fission edges of a parent outside the list (a chain product with a
nonzero yield in the parent’s tables). A parent and product pair that also carries a decay or another reaction keeps
its edge, because the matrix entry cannot be split; that fission share stays attributed.
Each route is integrated exactly rather than estimated. For a route x0 -> x1 -> ... -> xk, ACTINV solves the
linear chain with every node’s full removal rate (decay, all reactions and declared removal) on the diagonal and
only the route’s own edge as the source, through every schedule step, using the same per-step rates the main solve
used. The solve is a dense matrix exponential of the small bidiagonal system, so there is no Bateman closed form
and equal rates are harmless. The analysis is linear in the source atoms and works in both trace and coupled
modes. A route is at most max_depth edges long; the search discards a branch as soon as an upper bound on what
it can still deliver falls below the smallest target’s path_floor, so default settings stay fast on large
networks. The search tree is capped at 2,000,000 nodes. If the shared search exceeds that, every target is searched
again on its own floor and the budget is divided evenly among the sources, so one tiny target or one wide source
cannot starve the others; a target whose search still ran out of budget reports search_truncated: true and the
truncated_sources, and the notes name it. At most 8 x max_paths candidate routes per target are integrated, the
largest upper bounds first; the number cut is candidates_dropped_by_cap on the target (and in the notes).
The loop_floor test is applied after, and in addition to, path_floor: a loop walk is dropped when it raises its
loop-erased path by less than loop_floor even if it alone carries more than path_floor of the target. With the
default loop_floor of 0.01 the residual can therefore exceed path_floor; set loop_floor near 0 to account for
every walk above path_floor.
Edge labels name the decay mode or reaction that connects two nuclides. Spontaneous-fission products are labelled
SF, atoms supplied by a schedule feed are feed, and an edge into the removal sink is removal. Labels come from
the decay and reaction tables, not from the run’s rates: a reaction that has a row in the library is named even when
its collapsed rate is zero in this spectrum, and when a decay and a reaction connect the same pair the label joins
them ((n,n')/IT).
The target inventory is the sum over every walk through the graph of that walk’s chain contribution. Walks that
never repeat a nuclide are reported as ordinary routes. A walk that revisits a nuclide (for example a
(n,g) reaction followed by a decay back to the parent) has is_loop: true, names its loop-erased base_path,
and reports loop_gain, its contribution relative to that base path. The floors apply to routes and loop walks
separately, so a route below path_floor alone is not promoted by the loops attached to it.
Combining schedule features
The schedule features were built independently, and some pairs would be half-applied rather than wrong, so they are refused when the spec is validated, with a message naming both features:
| feature | refused together with |
|---|---|
power-driven steps (power_W_cm3 / power_W_per_g) | uncertainty, options.screen, options.fission, pathways, schedule library overrides, wall_loading_MW_m2 on the same step |
schedule partition | pathways, schedule library overrides, options.mode: "trace" |
schedule library overrides | uncertainty, options.gas, self_shielding, damage, fission_yields.files, options.rate_scale, power-driven steps, kerma, partition, options.fission, cross-section overrides, pathways, spectrum.rebin on a step spectrum, decay-only runs |
wall_loading_MW_m2, spectrum.rebin, half-life overrides and fission_yields.spontaneous
combine with all of these. A power step may carry a partition.
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.
| field | meaning | default |
|---|---|---|
group_structure | fispact-24, steiner-22, or custom with group_boundaries_eV. | fispact-24 |
group_boundaries_eV | Finite, nonnegative, strictly increasing photon boundaries. | none |
response | External actinv-photon-response-1 JSON and mandatory SHA-256 declaration. | none |
build_up_factor | Semi-infinite-slab screening factor B. | 2 |
gamma_constant_cutoff_eV | Lower energy cutoff for specific gamma constants. | 20,000 eV |
point_source | Optional point-source dose, the FISPACT-II DOSE 2 analog; see below. | none |
bremsstrahlung | Optional bremsstrahlung component, the FISPACT-II BREMSSTRAHLUNG analog; see below. | none |
missing_spectra | "report" or "estimate": what to do with a nuclide that has a mean EM energy and no photon spectrum, the FISPACT-II SPEK analog; see below. | "report" |
exclude_xrays | Remove the decay records’ X-ray spectra (STYP 9) from the photon source, the FISPACT-II NOXRAY analog; see below. | false |
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.
Photon power in groups whose centroid is below the response’s lowest tabulated energy (1 keV for the shipped NIST
response) does not enter the proxy. It is reported as dose_response_subthreshold_power_W_g. The proxy is still given
when that power is at most 1e-4 of the step’s total photon power; a nuclide’s own proxy follows the same rule with
that nuclide’s power. The limit is fixed. Below 1 keV the air-to-material ratio is not tabulated and can move by up to
about an order of magnitude in light elements, so a 1e-4 share leaves the proxy low by at most about 1e-3. If the
share is larger, the proxy is null; use a response that reaches lower energies or a transport calculation. Groups
above the response’s highest energy, missing elements and power outside the group structure still make the proxy null.
Steiner 22-group structure
group_structure: "steiner-22" selects the 22-group “Steiner” gamma structure that FISPACT-II uses for GROUP 1.
The boundaries are the “22 Group” column of Table 6 of the FISPACT-II User Manual (UKAEA-R(18)001; Table 5 of
UKAEA-CCFE-RE(21)02): 0, 0.01, 0.10, 0.20, 0.40, 1.00, 1.50, then 0.5 MeV steps to 8.00, then 10.00, 12.00 and
14.00 MeV. Unlike the 24-group structure, which extends to 20 MeV here, the table stops at 14 MeV; photons above it are
counted in the overflow diagnostics and, as for any structure that omits source photons, make the contact and
point-source doses null. Combining steiner-22 with group_boundaries_eV is an error.
"photon": {
"group_structure": "steiner-22"
}
Point-source dose (photon.point_source)
Absent by default; when present every step’s photon_source gains point_source_dose. It is the FISPACT-II DOSE 2
analog: manual Eq. (63), D = C sum_i mu_a(E_i) exp(-mu(E_i) r) m_s S(E_i) / (4 pi r^2), where the step’s grouped
photon source is a point source and each group acts at its centroid energy, as in the contact dose. mu_a is the
response’s air mass energy-absorption coefficient, the same curve the contact dose uses. Eq. (63) has no build-up
factor, so build_up_factor plays no part.
| field | meaning | default |
|---|---|---|
distance_m | Source-to-detector distance in metres. Must be at least 0.3. | required |
air_attenuation | Apply the air transmission exp(-mu r) of Eq. (63). | true |
air_density_g_cm3 | Converts the air mass attenuation to a linear coefficient. | 1.20479e-3 (NIST dry air near sea level) |
FISPACT-II raises a dist below 0.3 m to 0.3 m and prints a message; ACTINV rejects it so the configured distance is
the one used. The source mass is material.mass_g, which defaults to 1 g, so the default matches FISPACT-II’s 1 g
convention; for another mass the dose scales linearly and gamma_air_dose_Sv_h_per_g gives the 1 g value. Air
transmission needs an air_mass_attenuation curve (NIST table 4 mu/rho) in the photon response: build it with
scripts/build_photon_response.py --air-attenuation. A response without that curve gives a null dose and an
unavailable_reason when air_attenuation is true; set it false to ask for the unattenuated dose. The dose is
null with a reason under the same conditions as the contact proxy: no response, power above the response’s top
energy or outside the group structure, or a sub-threshold share above 1e-4. It is also null while a nuclide has
decay-record gamma energy but no photon spectrum (unrepresented_gamma_power_W_g above zero in photon_source): that
power never reaches the groups, so the sum would be low by an unknown amount; it is added to excluded_power_W.
photon.missing_spectra: "estimate" places that power in the groups instead. A
dose is never reported for a non-finite or non-positive distance, mass or air density.
point_source, bremsstrahlung, missing_spectra: "estimate" and exclude_xrays need the photon source, which is
built only when options.outputs is absent or contains photons or dose. A specification that sets any of them with
an options.outputs list lacking both is rejected.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"point_source": {"distance_m": 1.0, "air_attenuation": false}
}
Bremsstrahlung (photon.bremsstrahlung)
Absent by default. nuclides lists canonical nuclide names (Cl36, Ar42, K42), as FISPACT-II’s
BREMSSTRAHLUNG keyword does; duplicates, elements and non-canonical spellings are errors. Each listed nuclide with
positive activity at a step is treated as emitting f beta-minus electrons per decay, each at its mean beta energy
E0. Manual Eqs. (65)-(67) then give, per electron and group [E_i, E_i+1] (keV, a = 2.76e-6 per keV), aZ[E0 ln(E_i+1/E_i) - (E_i+1 - E_i)] photons when E0 >= E_i+1, aZ[E0 ln(E0/E_i) - (E0 - E_i)] when E_i < E0 < E_i+1, and none when
E0 <= E_i, carrying the bin-midpoint energy (E_i + E_i+1)/2, all multiplied by f. The same expressions are
applied to the continuous beta spectrum through its mean energy, as the manual does. The result is a separate photon_source.bremsstrahlung
block with its own groups, per-nuclide groups, contact dose (the B/2 mu_a/mu_m slab formula, in Gy/h) and, when
point_source is set, point-source dose. It is never added to the decay-photon groups, powers or dose proxies; add
the two doses yourself if you want the total.
Inputs are never inferred. The decay record’s beta-minus (STYP 1) spectrum gives ER, the average beta-minus energy
per decay of the parent, which already includes the branching ratio. f is the summed branching ratio of the decay
modes whose RTYP carries a beta-minus electron (the digit 1 in its decimal spelling: 1.0, or 1.5 for beta-minus followed
by neutron emission; RTYP 10 does not count), and E0 = ER / f is the mean energy of one electron. Cu-64 (38.5 %
beta-minus) therefore uses 0.385 electrons of 190.7 keV, not one electron of 73.4 keV; a pure beta-minus emitter has
f = 1 and E0 = ER. Each nuclide reports electrons_per_decay and mean_beta_energy_eV. The light-particle mean
energy, which also counts conversion and Auger electrons, is not substituted. Z is the atom-fraction
mean atomic number of the declared material (Eq. 68; the manual says atom fractions even though mass fractions are
used elsewhere), taken from the initial composition. A nuclide that lacks ER or has no beta-minus decay mode (f of
zero), or any nuclide when Z is unavailable
(a material element without natural-isotope data), is listed in missing_inputs with the missing input, contributes
nothing, and sets inputs_complete to false; the totals then cover only the nuclides that were evaluated. Listed
nuclides without activity appear in requested_nuclides_without_activity.
Approximations: this is the manual’s thin approximation, not electron transport. Eq. (66) diverges in a group whose
lower edge is 0 eV, such as the first group of both built-in structures; the manual does not say how FISPACT-II
treats it, so ACTINV leaves that group empty and reports the exact energy the model places there as
zero_lower_edge_group_power_W_g. The block also reports how complete the grouped photons are, against the manual’s
analytic emitted energy a Z E0^2 / 2 per electron (Eq. 65 integrated over energy):
zero_lower_edge_energy_fraction: the share of that energy in the zero-lower-edge group, which the grouped photons lack. For a first edge of 10 keV it is 19 % atE0 = 100 keV, 8 % at 250 keV and 4 % at 500 keV. The contact proxy absorbs some of this, but the point-source dose does not, so treat it as a lower bound when the fraction is large.energy_closure: the energy placed in the groups plus the zero-edge energy, over the same analytic total. Eq. (67) gives every photon of a group the bin-midpoint energy, as FISPACT-II does, and ACTINV keeps that rule. A group holding many low-energy photons is therefore over-credited and the closure is above 1 (about 1.6 forE0 = 120 keVwith 10, 100 and 200 keV edges), while photons beyond the last group edge make it fall below 1. The rule is a documented approximation, not a measurement of the emitted energy.
Both are null when no nuclide was evaluated. FISPACT-II selects candidates by half-life and mean-energy criteria
(appendix C.7.5) for its PRINTLIB 4 listing; ACTINV applies no such filter and evaluates exactly the nuclides you
list.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"bremsstrahlung": {"nuclides": ["Cl36", "K42"]}
}
Nuclides without a photon spectrum (photon.missing_spectra)
"report" is the default. A nuclide whose decay record gives a mean electromagnetic energy E_em but no gamma or
X-ray spectrum (STYP 0 or 9) adds its power to unrepresented_gamma_power_W_g, and the point-source dose stays null.
"estimate" is the FISPACT-II SPEK analog. Each such nuclide gets a photon-number spectrum
n(E) = C exp(-a E / E_max) on (0, E_max], with a = 14 and C set so the spectrum’s energy is E_em. The
spectrum is integrated exactly into every photon group (the closed form of the exponential integral, not a midpoint
rule) and added to the step source. Its power moves from unrepresented_gamma_power_W_g to
estimated_gamma_power_W_g. E_max follows the decay mode with the largest summed branching ratio, using the first
RTYP digit (RTYP 10, unknown origin, is “other”):
| dominant mode | E_max |
|---|---|
| beta-minus (1) | twice the mean light-particle energy per decay (MT=457 index 0); 5 MeV when that is not positive |
| beta-plus or electron capture (2) | 5 MeV |
| isomeric transition (3) | E_em |
| any other mode, or no mode | 5 MeV |
A tie goes to the mode earlier in that table. Beyond the manual’s rule, E_max is also capped by the largest Q-value
among the nuclide’s modes with positive branching, when one is positive, so no estimated photon carries more energy
than the decay releases. Photons above the top of the group structure are counted in the overflow diagnostics, as for
an evaluated spectrum.
The estimate is a model. Each dose ACTINV computes from the grouped source is linear in group power, so a nuclide of
power P contributes between P times the smallest and P times the largest dose per unit power over the energy
intervals of the groups whose lower edge is below the nuclide’s energy cap (its Q-value cap, else the top of the group
structure), each interval clipped to the cap. The dose model places each group’s power at the group’s centroid energy.
Whatever the spectrum inside a group, that centroid lies in the group’s interval, so the model’s dose per unit power is
its value at some energy in the union of the intervals. The bounds are the exact extrema of that value over the union,
not samples: the intervals are split at every knot of the response curves, where the log-log curves are power laws. For
the contact proxy the air-to-material ratio is log-concave on each piece, so the extrema are at the ends or at one
stationary point found by bisection. For the point-source dose the value is A E^q exp(-c E^p), with extrema at the
ends or at E* = (q / (c p))^(1/p). An energy below the response’s lowest tabulated energy gives no dose, as in the
model, so it enters as zero; with such energies in range the lower bound is zero. The bounds hold for any spectrum that
conserves the nuclide’s power below the cap and contain the estimate by construction. If an interval reaches past the
response’s top energy, the range is null. actinv inspect decay --estimated-spectrum lists each nuclide’s intervals
as allowed_intervals_eV.
Each step’s photon_source gains:
estimated_gamma_power_W_g: the power of the estimated nuclides;estimated_spectra:model,exponent_a,contact_gamma_air_dose_proxy_Gy_hand, withpoint_source,point_source_gamma_air_dose_Sv_h, each withrepresented_only(evaluated spectra alone, as"report"gives it),estimate,lower,upper,estimated_shareandunavailable_reason; andby_nuclide, one entry per estimated nuclide withdecay_mode,e_max_manual_eV,e_max_eV,q_cap_eV,e_cap_eV,photons_per_decay,power_W_g, itsgroups, andcontact_gamma_air_dose_proxy_Gy_handpoint_source_gamma_air_dose_Sv_has{estimate, lower, upper, share_of_step_estimate}.
The step’s own contact_gamma_air_dose_proxy_Gy_h stays the value from evaluated spectra; the estimate and bounds are
in estimated_spectra. The step’s groups, source_power_W_g and photon rates include the estimated nuclides.
point_source_dose.gamma_air_dose_Sv_h (and its per-gram value) is defined as the estimate of
estimated_spectra.point_source_gamma_air_dose_Sv_h: the dose of the evaluated nuclides’ groups plus each estimated
nuclide’s own sum over its groups at their centroids. It is not one dose of the combined step groups, where estimated
and evaluated photons would share a group centroid. It is given instead of withheld, and is withheld, with the reason,
when that estimate is null. Its range is in the same block. A range is null for the same reasons as a dose: no response,
power outside the response or the group structure, or a sub-threshold share above 1e-4. The estimates are not
evaluated data: actinv inspect decay DECAY_PATH NUCLIDE --estimated-spectrum prints the estimate beside the
evaluated grouped spectrum.
X-ray exclusion (photon.exclude_xrays)
false by default. With true, the STYP 9 content of every nuclide is removed from the photon source after the
nuclide’s evaluated spectrum has been scaled to its E_em, as FISPACT-II’s NOXRAY does. The scale is the same one
the source uses without the option, so the remaining gamma lines keep their power. The removed power is reported as
excluded_xray_power_W_g in photon_source and, per nuclide, in by_nuclide; it is not part of
source_power_W_g and is not counted as unrepresented. A nuclide whose only photon content is X-rays contributes no
photons. Heat, activity and inventory are not affected.
The fragment below belongs inside a complete problem; it is not a standalone input.
"photon": {
"missing_spectra": "estimate",
"exclude_xrays": true
}
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: reach keeps every
nuclide reachable from the material; rate (the default) also drops nuclides whose proven population bound over the
whole schedule is below bmin_atoms_per_g (default 1e-8), and the ledger’s rate_pruning block bounds what that
can change in total activity and heat. 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 an optional library override (and, when that library is for a different projectile than
the spec’s, the matching projectile). The override is sticky: the step and every later step collapse their reaction
rates from the new library until a step names another library, or names the spec’s own library again to return to
it. The step that switches must carry its own spectrum in the new library’s group structure (fispact-709 for a
neutron library, fispact-162 for any other projectile, or custom with boundaries equal to the library’s); later
steps on that library keep it as their default spectrum, and may replace it for a single step with their own. A
projectile without a library is rejected. Each overriding library is verified like the base library (hashes,
index projectile, group structure, and temperature: a neutron library must match options.temperature_K, any other
projectile’s index must say 0 K), and its path joins the prepared-data fingerprint.
A fragment that irradiates under the base library, then switches to a second neutron library with its own spectrum
(here on custom boundaries equal to that library’s) and cools:
"schedule": [
{"dt": "300 s", "flux": 1.0},
{"dt": "1 h", "flux": 1.0,
"library": {"path": "tendl-2025-neutron-high.npz"},
"spectrum": {"structure": "custom", "boundaries_eV": [1.0e-5, 1.0, 1.0e6, 2.0e7],
"flux_per_group": [1.0e9, 5.0e9, 1.0e9]}},
{"dt": "1 d", "flux": 0.0}
]
A fragment that switches to a proton library, which needs the matching projectile on the switching step:
"schedule": [
{"dt": "300 s", "flux": 1.0},
{"dt": "1 h", "flux": 1.0,
"library": {"path": "tendl-2025-proton-162g.npz"},
"projectile": "proton",
"spectrum": {"structure": "custom", "boundaries_eV": [1.0e5, 1.0e6, 1.0e7, 1.0e8],
"flux_per_group": [1.0e8, 5.0e8, 1.0e8]}},
{"dt": "1 d", "flux": 0.0}
]
All libraries share the one decay chain, so the state vector is the same through a switch: the inventory at the end
of one step is the initial inventory of the next, and only the collapsed rate triplets change. A product that the
decay chain does not know leaks exactly as in a single-library run; each overriding library’s unmapped products,
products without decay data, isomer fallbacks and absent targets are listed under ledger.step_libraries, together
with the steps it served, its fluence and material_nuclides_without_rows (initial-material nuclides with no row in
that library: they do not react on the steps it serves), and the library and index hashes appear under
certificate.inputs.step_libraries. The cumulative fluence_* fields add every step’s own spectrum total whatever
its projectile; the per-library fluence is the one to read across a switch. Pathway attribution covers the base
library only and is suppressed (named in ledger.step_libraries.pathways_suppressed). Overrides cannot be combined
with uncertainty, options.gas, self_shielding, damage, fission_yields or options.rate_scale (each is built
on one library’s rows), nor with power-driven steps, kerma, partition, options.fission, cross-section overrides
or the full pathways analysis (each reads the base library’s rates, groups or per-step matrix), with mesh mode, or
inside a study; the spec is refused rather than half-applied.
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 non-neutron projectiles (proton, deuteron, triton, helion, alpha and gamma), 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 that widens heat.*, activity.total and activity:<nuclide> responses (their band edges, or the nominal value without a band) by the pruning bounds of the rate_pruning ledger block, which include the shortfall of kept nuclides. Other responses are not certified. Inspect that certificate and coverage before relying on a screened calculation.
The optional scale maps support explicit perturbations for sensitivity and sampling workflows:
| Field | Key | Value |
|---|---|---|
options.rate_scale | Activation-library row index as a string | Multiplicative collapsed-reaction-rate factor |
options.decay_scale | Explicit radioactive nuclide, such as Mn56 | Multiplicative decay-constant factor |
options.yield_scale | Explicit parent:product, such as U235:I135 | Multiplicative independent-yield factor |
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, triton, helion, alpha or gamma; --groups accepts any named structure under
Group structures (a neutron build takes fispact-709 or another neutron grid; the
charged-particle and gamma builds take fispact-162) or a custom boundary file. Neutron defaults are 709 groups and 293.6 K; the other projectiles’ defaults are 162
groups and 0 K (gamma, like the other non-neutron projectiles, refuses a nonzero temperature — TENDL does not carry
a Doppler-broadened gamma sublibrary). 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.
Group structures
The named structures are FISPACT-II’s own standard grids. Each is vendored as a JSON file under
crates/actinv-data/data/fispact_<N>_groups.json whose source field names the ebins_<N> file of FISPACT-II’s
ebins.tar.bz2 and that file’s SHA-256; the boundaries are copied verbatim and are checked in the unit tests against
the published first, second, middle, penultimate and last values. Boundaries are stored ascending after loading.
| Name | Groups | Upper edge | Use |
|---|---|---|---|
fispact-66 (WIMS/LANL) | 66 | 25 MeV | neutron |
fispact-69 (WIMS) | 69 | 10 MeV | neutron |
fispact-100 (GAM-II) | 100 | 14.918 MeV | neutron |
fispact-172 (XMAS) | 172 | 19.6403 MeV | neutron |
fispact-175 (VITAMIN-J) | 175 | 19.6403 MeV | neutron |
fispact-211 (VITAMIN-J+) | 211 | 55 MeV | neutron |
fispact-315 (TRIPOLI) | 315 | 19.64 MeV | neutron |
fispact-351 (TRIPOLI+) | 351 | 55 MeV | neutron |
fispact-586 (CASMO) | 586 | 20 MeV | neutron |
fispact-616 (RED/LLNL) | 616 | 20 MeV | neutron |
fispact-709 (CCFE) | 709 | 1 GeV | neutron (default) |
fispact-1102 (UKAEA) | 1102 | 1 GeV | neutron |
fispact-162 (CCFE) | 162 | 1 GeV (5 keV floor) | proton, deuteron, triton, helion, alpha, gamma |
An xN suffix (fispact-1102x2) refines each group log-uniformly into N subgroups, as it does for 709. A spectrum
on any of these structures must supply exactly the structure’s group count, and its library must have been built on
the same named structure: the name, group count and boundary hash are all checked, and a flux on a different grid
must be rebinned to the library first or given as custom boundaries matching the library. Group edges above an evaluation’s
upper energy carry zero cross section, so a 20 MeV grid is the natural pairing for a 20 MeV evaluation and only the
709, 1102 and 162 grids reach the 200 MeV upper limit of the TENDL neutron evaluations and beyond.
High-energy spallation splice
build-library --spallation TABLE.json [--splice-energy-MeV MEV] is the counterpart of FISPACT-II’s
USESPALLATION: above a splice energy (default 200 MeV) the residual-production cross sections of a separate,
user-supplied high-energy library are merged into the activation library. Nothing is fetched or generated; the table
is the only source of the spliced values and ACTINV ships none.
The table is JSON with schema actinv-spallation-residuals-1 (unknown fields are rejected):
{
"schema": "actinv-spallation-residuals-1",
"description": "required free text naming the code, version and run that produced the data",
"projectile": "proton",
"boundaries_eV": [2.0e8, 2.4e8, 2.8e8, "...", 1.0e9],
"targets": [
{"za": 82208, "liso": 0, "channels": [
{"mt": 5,
"loss_barns": [0.9, 0.8, "..."],
"products": [{"zap": 80200, "lfs": 0, "sigma_barns": [0.002, 0.003, "..."]}]}
]}
]
}
boundaries_eVare ascending and must equal the library’s group boundaries from the effective splice energy to the top of the library (to1e-12relative), so each table group is exactly one library group. Everysigma_barnsandloss_barnsarray has one finite, nonnegative value per table group.- The splice energy snaps up to the nearest library boundary, so no group mixes two sources.
splice 200 MeVis exact onfispact-709andfispact-162; on the log-spacedfispact-1102it becomes 208.93 MeV. Both the requested and the effective energy are recorded. A splice at or below the lowest boundary, or leaving no group above it (an EAF-range 20 MeV grid), is an error. - A product is the row
(mt, zap, lfs, MF=10)of its target;loss_barns, if given, is the matching target-depletion row. An existing row with the same key has its spliced groups replaced; a new row is appended after the target’s rows with zero cross section below the splice. Rows the table does not name, and every group below the splice, keep their values bit for bit. Spliced channels leave the other MTs of the same target untouched, so an evaluation that already tabulates overlapping reactions above the splice counts them as well; as in FISPACT-II, the user chooses the splice energy and the table’s content. - Use an MT that carries no gas-production accounting (MT 5 is conventional); a channel whose MT is in the
hydrogen/helium table also receives its ejectile counts under
options.gas. - Table targets absent from the library are skipped and listed. The table’s
projectilemust equal the library’s.
The index gains a spallation block (omitted without the option, leaving the index unchanged) with the table path
and SHA-256, its description, the requested and effective splice energies, the first spliced group, the rows
replaced and added in total and per target, and the skipped targets. Each affected target’s ledger carries a line with
the same counts. Library rows that the table does not replace keep their values even when they are nonzero at or
above the splice (a production row of the library has a different lmf from the table’s MF=10 row, so the table’s row
is appended beside it and the production is counted twice); the block lists them as
untouched_rows_nonzero_in_spliced_groups (a count and the first 50 rows), and build-library warns on standard
error when the count is not zero.
Triton and helion projectiles
--projectile triton and --projectile helion build from ENDF-6 evaluations whose incident-particle record is
NSUB 10030 (triton, projectile ZA (1, 3)) or NSUB 20030 (He-3, ZA (2, 3)), on the same CCFE-162 structure and the
same MF=3/6/8/10 families as the other charged projectiles. The projectile is read from the evaluation, not from a file
name, and AWI must be within 10% of mass number 3. Residual arithmetic is target + projectile − emitted particles
(for example Fe-56 + t gives Co-59 for MT=102, Fe-56 + He-3 gives Ni-59), and the MT=5 residual production of charged
projectiles uses the same MF=6/MF=8/MF=10 path as proton, deuteron and alpha. ACTINV ships no triton or helion
library: the TENDL t and h sublibraries are the intended source, but none is in the standard catalog, so build the
library yourself and check its coverage in the target ledgers.
Gamma (photonuclear) projectile
--projectile gamma builds from the TENDL g sublibrary (public, TENDL-2025): NSUB 0, projectile ZA (0, 0), AWI
required to be exactly 0.0. Residual arithmetic is target + photon − emitted particles on the CCFE-162 group
structure, the same structure and MF=3/6/8/10 families the proton/deuteron/alpha path already uses. Some gamma MTs
(for example 50, 51 and 91 — single-neutron production to the ground state, a discrete level, or the continuum) carry
MF=3/6 cross sections without an MF=8 product declaration; the builder resolves their ground-state residual from the
ENDF MT reaction definition instead of dropping the row, and records every such resolution in the target ledger.
Single-neutron production is counted once. When MT=4 carries its own MF=8 state-resolved declaration
(TENDL-2025 Ta-181 and W-186, for example), MT=4 is used and every MT50–91 detail section is skipped. When MT=4 has no
MF=8 of its own and MT50–91 detail is present, MT=4 is skipped and the detail sections carry the channel. Each skip is
recorded in the target ledger.
Photofission is recognized only as a total cross section: the MF=10 IZAP=−1 total-fission sentinel (TENDL-2025),
or, under a normalization profile such as --profile tendl, the TENDL-2017 encoding of the same quantity as a single
MF=10 IZAP=0 LFS=0 section with no MF=3 MT=18 (P98, recorded in the ledger). An evaluation that declares actual
photofission product yields under MT=18 fails closed, since photofission yields are out of scope for v1. TENDL-2017
gamma files also contain MF=3 tables that start above the reaction threshold while the MF=10 states carry the ramp
from threshold. Under the default profile these fail closed on the emitted-state sum, or, where the state sum
stays within the standard zero-total envelope, are scaled to the zero total with a ledger record, so build TENDL-2017
gamma files with --profile tendl. Under --profile tendl the
builder applies the MF=3 threshold extension (P100): for each such MT it extends the MF=3 table below its first
energy E3 with the summed MF=10 states (ZAP ≥ 0), one point at each energy below E3 that a state tabulates, plus a
joining point at E3 carrying the states’ summed left limit, interpolated lin-lin. The extension applies only when
every state is lin-lin below E3; otherwise the MT is left unchanged and the ledger says why. Each extension writes a
MT<n>: MF=3 threshold extension: … ledger line, and remaining per-group differences are reconciled and recorded as
state_sum_normalized. Without the extension the threshold group’s production would be scaled to the zero MF=3
total and lost. No TENDL-2025 gamma file triggers it.
Pass --decay (and --decay-fallback) when building a gamma library: isomer labels then resolve against the decay
sublibrary the runtime uses. Without decay data the builder falls back to its target catalog and label ranks.
Gamma activation libraries are not yet published through actinv data fetch — that is a separate release decision.
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.
--mf33-from DIR takes the covariances of an input from the file of the same name in DIR, when there is one; the
input itself still binds the target to the activation library by its SHA-256, and nothing but MF=33 is read from the
other file. The index records that file’s SHA-256 as the target’s mf33_source_sha256 and includes it in the source
manifest. A file in DIR without an input of the same name, without MF=33, or with an MF=33 material that is not
the input’s target is refused.
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_EMnormalization factors and represented-power fraction; - specific gamma constants in
Gy m2/(Bq s)andmGy m2/(GBq h)when a response is supplied; contact_gamma_air_dose_proxy_Gy_h, response coverage, and explicit ungrouped/unrepresented power;dose_response_subthreshold_power_W_g, only when non-zero: photon power below the response’s lowest energy, omitted from the proxy.point_source_dose, only withphoton.point_source: distance, mass, dose in Sv/h and per gram, excluded power and the reason a dose isnull; eachby_nuclideentry gainspoint_source_gamma_air_dose_Sv_h;bremsstrahlung, only withphoton.bremsstrahlung: the separate component described above;estimated_gamma_power_W_gandestimated_spectra, only withphoton.missing_spectra: "estimate": the estimated nuclides and the estimate and bounds of each dose, described above;excluded_xray_power_W_g, only withphoton.exclude_xrays; eachby_nuclideentry gains the same key.
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 flux in
n cm^-2 s^-1 (neutron) or particles cm^-2 s^-1 (photon and the other non-neutron projectiles) 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 rectilinearMeshFilterand oneEnergyFilter, in either order, plus an optional single-binParticleFilter(neutronorphoton; more than one particle bin is refused, since a multi-particle tally mixes flux across particle types into one row). A tally with noParticleFilteris legacy behaviour and is accepted only when the mesh spec’s projectile isneutron; a photonParticleFilterwritesparticles cm^-2 s^-1flux and aparticlemetadata field, and a mesh run whose projectile disagrees with the imported flux’s particle units fails before solving. Importing an unfiltered or neutron-filtered tally writes byte-identical output to the pre-P94 importer; - MCNP traditional rectangular XYZ neutron FMESH
meshtalcolumn output with energy rows and optional checked totals; - MCNP energy-binned F4:N
mctalwith 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.
An entry can also be dotted, steps.<field>[.<key>...] (P90), to keep only part of each step instead of the
whole steps array: <field> must be a StepOut field (e.g. heat_W_per_g, photon_source), and further
segments descend through JSON objects — steps.photon_source.groups keeps only photon_source.groups (with
every key of each group entry, since the path ends there), dropping photon_source’s other fields and every
other step field. steps and a steps.<field> entry cannot both appear. A path that reaches an array or a
scalar with segments still to consume is rejected at validation, as is a key that does not exist at that point
in StepOut’s shape — except inside a nuclide- or response-keyed map (activity_Bq_per_g, uncertainty.responses,
damage.elements), which can only be selected whole, not narrowed to one dynamic key. A selected field that is
absent in a given step (e.g. photon_source with no photon output) is left out of that step’s object, exactly as
in the complete record; every emitted step object otherwise holds step plus the selected paths. With any dotted
entry present, the cell text is assembled directly from RunResult/StepOut fields rather than by serializing
and then pruning the whole result, so a large unselected field (e.g. the per-nuclide inventory) is never built.
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.
export-source converts a banded actinv-r2s-source-1 document into the format a transport code or activation-adjacent R2S tool reads directly: OpenMC settings-XML, an MCNP SDEF deck, a Serpent src card block, or — for ALARA-based R2S tools such as nucleide and PyNE — one ALARA .photonSrc file per cell plus a provenance index (export-source alara, requires --shutdown-t-s). See the command reference, docs/INTERCHANGE_TRANSPORT.md for the pinned format contract, and contrib/nucleide_r2s/demo.py for a working round-trip through nucleide’s own ALARA reader.
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.
Since 1.4.0, channels: ["flux"] is available 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.
The self_shielding section selects a hash-pinned neutron table and composition-derived or fixed background dilution. It applies bounded Bondarenko factors over the resolved and unresolved ranges; it does not 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.
For an explicitly selected U.S. Part 61 rule pack, waste reports nominal
component classes and waste budget verifies class-specific impurity limits.
waste bounds classifies user-declared absolute whole-component activity boxes
under the bundled pack and returns a conservative class superset. These boxes
are deterministic enclosures, not probabilities or propagated uncertainty.
waste composition projects caller-declared fixed-rate affine pure-element
responses over bounded natural-element weight percentages that sum to 100%; it
does not generate responses or establish physical linearity. Separate nuclide
projections produce a conservative class superset. See
component waste classes and impurity limits for geometry, inventory
coverage, external-tritium declarations, and both range input schemas.
waste composition solve generates those pure-element responses from one
prepared native ACTINV run per component, checks every distinct projected
extremum composition plus a canonical feasible reference against full native
runs, and retains audit evidence. It verifies selected points and does not
bound solver or nuclear-data error. The fixed-rate affine model remains
qualified only within its declared domain; see the P109 section of the public
waste handbook.
Move a FISPACT-II deck to ACTINV
actinv import-fispact reads a FISPACT-II input deck (.i) and writes an ACTINV problem specification. It converts the problem description: the material, the neutron (or charged-particle) spectrum, the irradiation and cooling schedule, and the few output settings that have an ACTINV counterpart. It does not read FISPACT-II’s nuclear data. The activation library and decay data of the converted problem are ACTINV’s, so results differ from a FISPACT-II run by the difference between the two data sets as well as by the solvers.
actinv import-fispact DECK.i OUT.json [--fluxes FLUXES] [--files FILES]
[--library LIB.npz] [--decay DECAY]
[--covariance COV.npz] [--strict]
The command writes OUT.json (the problem) and OUT.import.json (the import report, below). Four further options supply data that a deck does not name; each file is hashed into the spec, and a deck that does not use an option imports exactly as it would without it:
| Option | Used by | Fills |
|---|---|---|
--fission-yields FILE... | USEFISSION | fission_yields.files: ENDF neutron-induced yield files, one per parent. The parent of each file is read from its own header. |
--resonance FILE... | SSFGEOMETRY | self_shielding.geometry.resonance_files: ENDF evaluations with resolved resonance parameters |
--self-shielding-table FILE | PROBTABLE, SSFDILUTION | self_shielding.table: a Bondarenko table |
--damage TABLE (optional) | ALLDISPEN, ATDISPEN | damage.table: a damage table, for example from actinv build-damage --method kinematic. Without it a neutron deck uses the catalog’s tendl-2025-neutron-damage. A table that records its displacement energies (an actinv-damage-table-2 file) is compared with the deck’s. |
A file that cannot be read stops the import. An option the deck never uses is listed under options_unused in the report. Run and check the converted problem in the usual way:
actinv import-fispact TENDL-2017_1996exp_5min.i fe_5min.json
actinv validate fe_5min.json
actinv run fe_5min.json fe_5min_result.json
The desktop imports a deck from the toolbar (Import FISPACT-II deck…) and shows the same per-keyword report as actinv import-fispact. A deck that irradiates, imported without a fluxes file, gets a flat placeholder spectrum flagged as a required input. Replace it before running, because the result means nothing until you do.
Coming from FISPACT-II
This map is by capability, not by keyword; the keyword translation below says what the importer does with each deck line. Supported means ACTINV has an equivalent that does the same job. Supported differently means the job gets done, but the input, the output or the numerical treatment is not FISPACT-II’s. Not supported means ACTINV has nothing equivalent. Not needed marks a keyword that exists only for FISPACT-II’s own printing, files or solver. A capability can be supported in ACTINV and still be absent from the importer, in which case you add the spec section by hand; the last column says so. “Imported” means the importer maps the deck keywords.
| FISPACT-II capability (keywords) | ACTINV equivalent | Status | Importer and notes |
|---|---|---|---|
Material and irradiation: MASS, FUEL, DENSITY, FLUX, ZERO, TIME, PULSE, PROJECTILE | material, spectrum.total, schedule, projectile; the Material and Irradiation & cooling pages | Supported | Imported. Gamma, triton and helion need --library; triton and helion have not been run on real data |
Wall loading and power: WALL, POWER | step wall_loading_MW_m2, power_W_cm3 or power_W_per_g; a kerma table; the step Drive on Irradiation & cooling | Supported differently | Imported, but a power step needs a kerma table the deck cannot supply. ACTINV holds the power on sub-intervals within a step; max_substeps: 1 reproduces FISPACT-II’s single normalization |
Elemental partition: PARTITION | schedule[].partition | Supported | Imported. Applied at the start of the next step |
Group conversion: GRPCONVERT, CNVTYPE, LIMGRP | spectrum.rebin | Supported | Imported for FISPACT-II standard structures |
Cross-section and half-life changes: OVER with ACROSS, ALAM | overrides | Supported differently | Imported. ADCROSS, ADLAM (error factors) are not imported; overrides are not step-scoped |
Change of library mid-run: GETXS after the first TIME | step library | Supported | Not imported: it needs the second library’s path |
Cooling from decay data alone: GETDECAY without GETXS | decay-only run | Supported | Imported |
Library choice: GETXS, GETDECAY, ARRAY, COLLAPSE | library, decay; actinv data fetch | Supported differently | ACTINV uses its own libraries, not the deck’s. Library-preparation switches (LIBVERSION, COMPRESSXS, FULLXS, SAVELINES) have no counterpart and are noted |
Inventory listing, totals, elements, dominant nuclides: ATOMS, HALF, NOCOMP, NOSORT, SORTDOMINANT, MIND, NOSTABLE | summary section; Step summary on What to compute | Supported | Imported (MIND, NOSTABLE, SORTDOMINANT) |
Tab and plot files: TAB1 to TAB4, GRAPH, NUCGRAPH | actinv report; the Nuclides page | Supported differently | Noted. ACTINV writes one result JSON and renders tables from it afterwards |
Depletion rates: DEPLETION | summary.depletion; actinv report --tables depletion | Supported | Not imported (reported as unsupported); add summary.depletion by hand |
Point-source dose and bremsstrahlung: DOSE 2, BREMSSTRAHLUNG | photon.point_source, photon.bremsstrahlung; Photons & dose | Supported differently | Imported. The dose is an air kerma rate, and bremsstrahlung is a separate block; both need the photon response described below |
Photon groups: GROUP, READGG | photon.group_structure (fispact-24, steiner-22, or custom) | Supported | GROUP is imported. READGG is imported as a custom structure when the files file has a ggbins entry whose file holds the group count and then that many plus one ascending energies in eV, as the FISPACT-II manual describes; a missing, unreadable or malformed ggbins file is reported as unsupported with the reason |
Approximate gamma spectra for nuclides without spectral data: SPEK | photon.missing_spectra: "estimate" | Supported differently | Imported as approximated. ACTINV’s estimate is an exponential shape set by each nuclide’s mean energy per decay mode, not FISPACT-II’s spectrum, and the result carries certified lower and upper dose bounds |
Transport index and hazards: ATWO, HAZARDS, CLEAR | radiological with bundled: tables; actinv report --tables regulatory; Regulatory tables on What to compute | Supported differently | ATWO is imported. HAZARDS and CLEAR are noted: ACTINV chooses no regulation for you. 49 CFR 173.435/173.436 and Euratom 2013/59 Annex VII are bundled; ICRP 119 coefficients are not and come from a local script. These are the regulations’ numbers, not FISPACT-II’s data files |
Geometry self-shielding: SSFGEOMETRY, SSFCHOOSE, SSFFUEL, SSFMASS | self_shielding.geometry | Supported | Not imported (reported as unsupported); the section needs hash-pinned ENDF resonance files the deck does not name |
Dilution override: SSFDILUTION, PROBTABLE | self_shielding.dilution_overrides, self_shielding.table | Supported differently | Not imported. ACTINV needs a hash-pinned Bondarenko table; tables are built from evaluations with actinv build-shielding |
Uncertainty: UNCERTAINTY, NOERROR | uncertainty (MF=33 covariance) | Supported differently | Imported. The default covariance is the TENDL-2025 MF=33 data, not the deck’s library. ACTINV propagates full-covariance bands rather than FISPACT-II’s pathway sums |
Uncertainty controls: COVARIANCE, UNCTYPE, ERROR | uncertainty.covariance, uncertainty.channels, overrides | Supported differently | Not imported |
Monte Carlo sampling and sensitivity: MCSAMPLE, SENSITIVITY | study.robustness.statistics | Supported differently | Not imported (reported as unsupported). The statistics are those of an ACTINV robustness study, not a FISPACT-II sampling run |
Pathways: PATH, ROUTES, LOOKAHEAD, PATHRESET, GENERIC, INDEXPATH, RESULT | pathways; Pathways page | Supported differently | PATH and ROUTES are imported as targets with default thresholds; the others are noted. The result reports a closure for each target |
Fission: READSF, FISYIELD, CUMFYLD, USEFISSION, NOFISS, FISCHOOSE | fission_yields.files, fission_yields.spontaneous, options.fission, actinv inspect yields | Supported differently | Not imported. Which actinides fission is set by the yield files you supply, with no keyword switch |
Displacement damage: ALLDISPEN, ATDISPEN | damage | Supported differently | Imported against --damage TABLE, or against the catalog table tendl-2025-neutron-damage for a neutron deck without it; a per-element ATDISPEN value overrides ALLDISPEN in any order. They are mapped when the table was built at the deck’s energies (or records none, as a table 1 does) and reported as unsupported otherwise, with the actinv build-damage --method kinematic --displacement-energy command that builds a matching table. An element with no energy in the deck takes the table’s energy, else FISPACT-II’s default (25 eV outside its table 8). With --damage and neither keyword the section uses those defaults, as FISPACT-II computes displacement rates by default. With the catalog table installed, the energies are compared at import. If it is not installed, the deck’s energies are written as given, an element the deck omits takes the table’s energy at run time (reported as approximated), and the run refuses a mismatch. A deck for another projectile needs --damage and is unsupported without it, naming the option |
High-energy data: USESPALLATION, USEXSEXTRA | group structures to 1 GeV; build-library splice option | Supported differently | Not imported. You build the library with the splice table |
Library inspection: PRINTLIB, EXTRACTXS | actinv inspect | Supported | Noted. Works without a run |
X-ray switch: NOXRAY | photon.exclude_xrays | Supported | Imported |
Cross-section threshold switch, iron background removal: XSTHRESHOLD, IRON | none | Not supported | XSTHRESHOLD is noted (ACTINV propagates the full covariance); IRON is reported as unsupported |
Run control and print switches: CLOBBER, LOGLEVEL, MONITOR, TOLERANCE, NOT1 to NOT4, CULTAB, SPLIT, JSON | none | Not needed | Noted. ACTINV uses CRAM, which has no solver tolerance, and writes only the files you name |
After the import, edit the JSON problem rather than the deck: ACTINV runs the problem, not the deck. A converted problem does not reproduce FISPACT-II’s numbers by construction, because the data differ. See Understand the competitive benchmark for the recorded FNS comparison on common data.
Import in the desktop
The desktop’s Import FISPACT-II deck… (Ctrl/Cmd+I) runs the same importer and shows the same per-keyword report. It differs from the CLI in one case: a deck that irradiates but comes without a fluxes file converts with a flat placeholder spectrum, flagged as a required input, so you can open the problem and fill in the spectrum. The CLI refuses such a deck. Replace the placeholder before running. See Import a FISPACT-II deck.
What is read
| Input | Used for |
|---|---|
DECK.i | material, flux, schedule, projectile, and the keywords listed below |
--fluxes FLUXES | the group spectrum: a FISPACT-II fluxes file (values highest energy first, first-wall loading, title) |
--files FILES | a FISPACT-II files file. Its fluxes entry names the spectrum when --fluxes is absent. Without --files, DECK_files and then files beside the deck are tried. |
--library, --decay | the ACTINV activation library and decay data for the problem |
--covariance | an MF=33 covariance sidecar paired with --library, used when the deck asks for uncertainties |
The xs_endf, dk_endf and other data entries of a files file are listed in the report for reference and never read. Without --library and --decay the problem uses the catalog references that actinv new uses (catalog:tendl-2025-neutron-709g, catalog:endfb-viii-0-decay with the JEFF-3.3 fallback, and for charged particles the matching 162-group library); install them with actinv data fetch. A gamma-projectile deck needs --library.
The group count of a fluxes file is taken from the file itself. ACTINV reads 709-group neutron spectra and 162-group charged-particle spectra directly; a GETXS 1 N line must agree with the file. A file in another FISPACT-II standard structure (66, 69, 100, 172, 175, 211, 315, 351, 586, 616 or 1102 groups) is imported when the deck says GRPCONVERT: the importer takes the file’s boundaries from that structure and writes a spectrum.rebin section, so ACTINV converts the spectrum to the library’s groups inside the run. A file with any other group count stops the import; convert it to 709 groups first.
How the deck is read
The importer follows the FISPACT-II input rules:
- Keywords are free format and case-insensitive. Only the leading characters matter: a word of three or more characters that begins exactly one keyword is that keyword (
TOL,HAZA,UNCERT,TOLERareTOLERANCE,HAZARDS,UNCERTAINTY,TOLERANCE), and an ambiguous abbreviation is unknown. The deprecated spellingsNOHEAD/NOHEADER,COLLAPSE(GETXS 1),ARRAY(GETDECAY 0) andAINPUT(GETXS 0andGETDECAY 0), and the legacy switchesMCSEED,CONV,DOMINANT,EAFVERSION,ENFA,LEVEL,LINA,LOOPS,NEWFILE,SEQNUMBER,SEQUENTIALandTAPAare known. A word that matches nothing is reported as a separateunsupportedentry (“unknown to this importer”), including when it follows a keyword that takes a list, such asPATHorOVER. - The deck is read as bytes. A UTF-8 byte-order mark is ignored, lines end at
\n,\r\nor a bare\r, and bytes that are not UTF-8 (a Latin-1 micro sign in a comment, for example) are replaced rather than stopping the import; the report recordsdeck.lossy_utf8. << ... >>comments may appear anywhere, including inside a line, and may span lines. A line whose first character is*is text (the title afterFISPACT, and afterEND);<<has no meaning inside it.- The library phase ends at
FISPACT, the initial conditions at the firstTIME, and the deck atEND. Nothing afterENDis read. TIME t [SECS|MINS|HOURS|DAYS|YEARS]sets an interval; the nextATOMS,STEPorSPECTRUMruns it. Each run becomes one step of the ACTINV schedule, at the flux in force when the output keyword is read. A word after the number that is not one of these units is an unknown keyword, and the interval is in seconds. A bare number is seconds (the UKAEA tutorial deck says so).- Assumption. That
TIMEonly sets up an interval and the output keyword runs it is the reading of the UKAEA FISPACT-II tutorial decks, whose comments say thatATOMS“tells FISPACT-II to solve the rate equations”. It is not confirmed against a FISPACT-II output for a deck with twoTIMElines before oneATOMS; the pypact reader treats everyTIMEas a step. The importer therefore keeps the deferral but never hides its cost: aTIMEthat a laterTIMEreplaces, or that no output keyword follows, isunsupported(so--strictstops), and its entry gives the lost interval and flux. Put anATOMSafter eachTIMEto make the intent unambiguous.
- Assumption. That
FLUXsets the flux for the steps that follow. The first positive value becomesspectrum.total, and each step’sfluxmultiplier is its flux divided by that value, so a step atFLUX 0is a cooling step.ZEROalso sets the flux to zero, as in FISPACT-II. The ACTINV schedule carries elapsed time throughZERO; FISPACT-II restarts the elapsed time printed after it (the cooling time restarts at zero, as in the pypact referencetest31.out). The interval durations agree; absolute times in the two outputs differ by the irradiation time. FISPACT-II is documented to allowZEROonce and to refuse irradiation after it; the importer does neither check and simply sets the flux to zero (both statements are unverified here).PULSE n ... ENDPULSEruns its bodyntimes in total (PULSE 3gives three executions, not four), expanded into explicit steps (at most 100000). Loops nest to 64 levels, and a deck whose loops expand to more than two million keyword executions is refused before anything runs. Keywords in the body are reported once, at their first execution. The body ofPULSE 0does not run, but its keywords are still listed (marked as skipped), so an unsupported keyword there is visible to--strict. This reading ofnhas not been checked against the FISPACT-II manual.
Keyword translation
| FISPACT-II | ACTINV |
|---|---|
MASS kg n and ELEMENT percent lines | material with mass_g and basis wt_percent |
FUEL n and NUCLIDE atoms lines | material with basis atoms_per_g and explicit nuclide keys; the mass is taken from mass numbers (the atom counts are exact) |
FLUX, ZERO, TIME, ATOMS, STEP, SPECTRUM, PULSE | spectrum.total and schedule |
PROJECTILE n | projectile (1 neutron, 2 deuteron, 3 proton, 4 alpha, 5 gamma, 6 triton, 7 helion). Gamma, triton and helion have no catalog library: pass --library. |
FISPACT title line | title |
MIND, NOSTABLE, SORTDOMINANT | the summary block: min_atoms, include_stable, dominant_top |
UNCERTAINTY 1 or 2 | uncertainty with an MF=33 covariance (see below) |
UNCTYPE 1, 2, 3 | uncertainty.channels (cross_section_mf33, decay_constants, both); type 2 is approximated |
SENSITIVITY SIGMA | uncertainty.voi, approximated |
ERROR | per-reaction overrides of kind cross_section_uncertainty, approximated |
USEFISSION with --fission-yields | fission_yields.files |
NOFISS, CUMFYLD, FISYIELD | no yield files; fission_yields.yields: "cumulative"; fission_yields.parents |
FISCHOOSE | pathways.fission_parents |
SSFGEOMETRY (and SSFCHOOSE) with --resonance | self_shielding.geometry |
PROBTABLE, SSFDILUTION with --self-shielding-table | self_shielding.table (approximated), self_shielding.dilution_overrides |
NOERROR | no uncertainty block |
GETXS, GETDECAY | the library and decay references; a GETXS 1 N group count is checked against the spectrum |
POWER p n mt… | schedule power_W_cm3, with material.density_g_cm3 from DENSITY (see below) |
WALL w | schedule wall_loading_MW_m2, with spectrum.wall_loading_MW_m2 taken from the fluxes file (see below) |
PARTITION element/fraction pairs | schedule partition on the next step |
OVER nuclide with ACROSS, ALAM | overrides entries of kind cross_section and half_life |
GRPCONVERT, CNVTYPE, LIMGRP | spectrum.rebin with convention, emin_eV, emax_eV |
DOSE 2 distance | photon.point_source |
GROUP 0, GROUP 1 | photon.group_structure fispact-24, steiner-22 |
BREMSSTRAHLUNG nuclides | photon.bremsstrahlung.nuclides |
PATH, ROUTES | a pathways section, the nuclides named as targets |
ATWO | radiological with the bundled us-49cfr173-a2 table |
HALF, HAZARDS, CLEAR, GRAPH, NUCGRAPH, TAB1 to TAB4, NOT1 to NOT4, TOLERANCE, PRINTLIB, MONITOR, CLOBBER and similar | recorded as noted: they select FISPACT-II printing, files or solver controls and do not change the calculated physics. The tables and plot data come from actinv report (below). HAZARDS and CLEAR name a regulation, which ACTINV does not choose for you: add a radiological section with the table you want (see Bundled regulatory tables). |
A deferred setting that appears twice (UNCERTAINTY, GRPCONVERT, CNVTYPE, LIMGRP) takes its last value, and the earlier entries say they were superseded.
UNCERTAINTY needs a covariance sidecar. With --covariance FILE it is hashed and used. With the default neutron library the catalog covariance sidecar is used and the entry is approximated, because its uncertainties are the TENDL-2025 MF=33 data, not those the deck’s FISPACT-II library carried. With another --library and no --covariance the entry is unsupported. Level 3 (pathways only) produces no band.
DENSITY is written to material.density_g_cm3 only when a POWER step needs it. Otherwise it is recorded in the report and left out, since it only adds per-cm3 summary totals and the converted problem stays identical to a hand-written one; add it yourself if you want them. The summary block carries the summary options; a build without them rejects a spec that contains it.
Keywords that need more than the deck
-
POWER.POWER p n mt_1 … mt_ngives a power densitypin W/cc normalized on the kerma of the listed MT numbers (usually1 301). It is written aspower_W_cm3on every step that follows until the nextFLUX,WALL,ZEROorPOWER, and the deck’sDENSITYbecomesmaterial.density_g_cm3. The list is read asnfollowed by exactlynMT numbers; ACTINV normalizes on the kerma table’s total (MT=301), and another list, a missing list or words after the list are named in the entry. A power-driven step needs akermasection with a hash-pinnedactinv-kerma-table-1file, which no deck provides, so the entry isapproximated: the importer writes the spec without it, lists it (and the density, when the deck has noDENSITY) underrequired_additions, and says so in its summary line. The spec does not validate until you add them. Build the table withscripts/build_kerma_table.py. -
WALL. The first-wall loading of the fluxes file becomesspectrum.wall_loading_MW_m2, and a step’s multiplier iswalldivided by it, as in section 4.91 of the FISPACT-II manual. Because the multiplier then applies to the whole file spectrum,spectrum.totalis the sum of the file’s group values and anyFLUXin the same deck is expressed against it. A file that records no positive loading falls back to ACTINV’s 4.44e13 n/cm2/s per MW/m2 equivalence, and the entry isapproximated. -
PARTITION. Element/fraction pairs, with or without a leading pair count, give the fraction of each element’s atoms kept. FISPACT-II applies the split when it reads the keyword, ACTINV at the start of the next step, so aPARTITIONwith no step after it isunsupported. -
OVER. EachACROSS,ALAM,ADCROSSandADLAMis reported under its own name;OVERitself is the worst of them.ACROSS target daughter valuebecomes across_sectionoverride on the ENDF reaction that takes the target to the daughter, found from the change in Z and A: (n,g), (n,2n), (n,3n), (n,p) and (n,a) only, for neutron projectiles. FISPACT-II sets the channel to that daughter; ACTINV sets the whole collapsed reaction and keeps its product branching, so the entry isapproximated. A daughter that is an isomer, a change that two reactions share (for example (n,d) and (n,np)) and a negative value areunsupported.ALAM value [unit]becomes ahalf_lifeoverride.ADCROSSandADLAMareunsupported: ACTINV takes a relative standard uncertainty, FISPACT-II an error factor, and the spec does not define the conversion. Cross-section overrides cannot be combined withuncertainty, so the importer drops theuncertaintyblock and marksUNCERTAINTYasunsupported. -
GRPCONVERT,CNVTYPE,LIMGRP.CNVTYPE 0isequal_lethargy,CNVTYPE 1isequal_energy.LIMGRP low highis read as two energies in eV, so the entry isapproximated. The group counts of the spectrum come from the fluxes file, not from the arguments ofGRPCONVERT. -
DOSE 2,GROUP,BREMSSTRAHLUNG.DOSE 2 distancewritesphoton.point_source; a distance below 0.3 m is raised to 0.3 m, as FISPACT-II does. The dose values arenulluntil you add aphoton.responsewith an air attenuation curve. The shipped photon response has none, so an importedDOSE 2givesnulldoses by default: rebuild a response withscripts/build_photon_response.py --air-attenuationand declare its new SHA-256, or setphoton.point_source.air_attenuationtofalsefor the unattenuated dose. The dose is the air kerma rate (numerically Gy/h), not an ambient dose equivalent, and it needsoptions.outputsto includephotonsordosewhen the deck sets outputs.BREMSSTRAHLUNGisapproximated: ACTINV reports the bremsstrahlung photons and their dose in a separate block and does not add them to the decay-photon dose. The electrons per decay come from each nuclide’s beta-minus decay branching and their energy is the STYP 1 average energy divided by that branching. A deck that lists no nuclides, or an element, isunsupported. -
PATH,ROUTES. The nuclides named becomepathways.targetsand the route-search thresholds keep their defaults; numeric arguments are listed in the entry as not interpreted. ACTINV refusespathwaystogether with power-driven steps orPARTITION; the importer then drops the section and marks the entryunsupported. -
ATWO. The A2 values of 49 CFR 173.435 (the IAEA SSR-6 Rev.1 table) are written asbundled:us-49cfr173-a2, with one response per uranium absorption type. They are not FISPACT-II’s own A2 file, so the entry isapproximated. Nuclides with an unlimited A2 (Mn-53, Ni-59, Zr-93, …) count as covered with zero contribution, sorequire_complete: trueaccepts an activation inventory that holds them. -
Fission.
USEFISSIONneeds--fission-yields; without it the entry isunsupportedand names the option. With itfission_yields.fileslists the files, and the energy setting stays at the spec default.NOFISSforces no yield files, whatever else is given.CUMFYLDsetsfission_yields.yieldstocumulative.FISYIELD nselects the parents: a positive count includes the listed actinides, a negative count excludes them and zero excludes every parent that has a yield file. WithoutFISYIELDthe FISPACT-II default of U-235, U-238 and Pu-239 applies, as an include list cut down to the parents that have a yield file. A named parent with no yield file does not fission in FISPACT-II either, so it is dropped and the entry names it.FISCHOOSErestricts only the pathway analysis, so it becomespathways.fission_parentswhen the deck hasPATHorROUTESand isnotedotherwise. -
Uncertainty.
UNCTYPE 1,2and3set the uncertainty channels. ACTINV propagates the MF=33 covariance whenever a covariance sidecar is given, so type 2 cannot leave the cross-section contribution out: the entry isapproximatedand says the band is wider.SENSITIVITY SIGMAasks for the ranked first-order variance shares (uncertainty.voi) in place of sampled sensitivity coefficients, and adds the uncertainty block when noUNCERTAINTYkeyword did;SENSITIVITY LAMBDAisunsupported.MCSAMPLEandMCSEEDconfigure the sampling that the analytic result replaces: they arenotedbeside a mappedSENSITIVITYandunsupportedwithout one.ERROR nwith parent, daughter and a fractional error becomes across_section_uncertaintyoverride on the reaction that takes the parent to the daughter (Fissionor0is MT 18). The error is read as the relative standard uncertainty of that reaction, which is an interpretation, so the entry isapproximated;-1asks for the library value and isnoted. The override needs the uncertainty block with the cross-section channel, so without one the entry isunsupported.COVARIANCEisnoted: ACTINV has no collapse step. -
Self-shielding.
SSFGEOMETRY type length [height](1 foil, 2 wire, 3 sphere, 4 cylinder, lengths in cm) with--resonancebecomesself_shielding.geometry, with the density fromDENSITY(when the deck has none the density is listed underrequired_additions), andSSFCHOOSEbecomes itschooselist.SSFMASSandSSFFUELgive a composition for the self-shielding calculation, but ACTINV shields the problem’s own material, so they areapproximated.PROBTABLEwith--self-shielding-tablebecomesself_shielding.table; the Bondarenko factors stand in for FISPACT-II’s probability tables, so it isapproximated.SSFDILUTIONwith the table becomesdilution_overrides. FISPACT-II numbers the energy groups from the highest energy (group 1), and ACTINV’s index is 0-based and ascending in energy, so groupgof the 709-group library is index709 - g. FISPACT-II does not allowSSFGEOMETRYbesidePROBTABLE, and neither does ACTINV. -
Noted and corrected.
XSTHRESHOLDandDEPLETIONarenoted: the first is a cost control of FISPACT-II’s pathway-based uncertainty estimate, the second an output request (setsummary.depletionfor the table).RESULTisnoted: a converted deck always defines a material and runs a schedule, whose inventory the pathways use.
A power-driven step is refused beside uncertainty, pathways and step libraries, and the importer follows those refusals instead of writing a spec ACTINV would reject.
The import report
Nothing is dropped silently. OUT.import.json (actinv-fispact-import-report-1) lists every keyword with its line, the section of the deck it appeared in, its arguments, and one status:
| Status | Meaning |
|---|---|
mapped | translated into a spec field |
approximated | translated with a stated caveat, given in detail |
noted | no effect on the calculated physics (printing, files, solver tolerances) |
unsupported | would change the physics and has no ACTINV equivalent, or is unknown to this importer (a misspelling, for instance) |
The report also holds the counts, options_unused (present only when an option was given that no keyword of the deck used), the spectrum source and total, the library chosen, the content of the files file, the SHA-256 of the deck, required_additions (spec sections that the deck implies and no deck can supply, such as kerma for POWER; empty for most decks), and a schedule_map giving, for each ACTINV step, the deck line that defined it, whether it is irradiation or cooling, and the FISPACT-II output keyword that ran it. ACTINV reports every step in full, so the choice between ATOMS, STEP and SPECTRUM does not change what is computed.
Check every approximated and unsupported entry before trusting a converted problem. --strict makes the command fail, after writing the report, when any entry is unsupported.
Not translated
These are reported as unsupported, each with a note saying what to do:
- The self-shielding keywords
PROBTABLE,SSFGEOMETRY,SSFCHOOSE,SSFFUEL,SSFMASSandSSFDILUTION, unless the option that supplies their data is given (--resonanceor--self-shielding-table, above). Each entry then names the missing option. A target type that ACTINV has no shape for, a cylinder without its height andSSFGEOMETRYbesidePROBTABLEstayunsupported. - A
GETXSafter the firstTIME. ACTINV expresses it as a steplibraryoverride, which needs the second library’s path and the spectrum in its group structure. The entry names the schedule step to edit. Step libraries are refused besideuncertainty,kerma, power-driven steps,partition,pathwaysand cross-section overrides. ADCROSS,ADLAM(error factor against relative uncertainty), andACROSSdaughters that are isomers or ambiguous.- Displacement energies that differ from the damage table’s (the entry gives the
build-damagecommand for a matching table), displacement damage in a non-neutron deck without--damage,USEFISSIONwithout--fission-yields,SENSITIVITY LAMBDA,IRON(not a keyword of the 2023 manual),READSF,USESPALLATION,USEXSEXTRAand the other library-selection keywords. - A
GRPCONVERTspectrum whose group count is not a FISPACT-II standard structure stops the import, since its boundaries are not in the deck.
A material defined after the first TIME is not representable.
Behaviour to know about
MASSpercentages. Percentages that do not sum to 100 are written as given and the spec does not renormalize them; the importer says the same reading applies in FISPACT-II, which has not been confirmed from the manual or an output (unverified).MIND. The UKAEA tutorial decks comment that 1e5 atoms is the FISPACT-II default threshold. A deck with noMINDhas that implicit threshold; the importer neither writes nor mentions it, so setsummary.min_atomsif the nuclide lists should match (unverified default).GRPCONVERT a b. The two numbers are not read. The group counts come from the fluxes file and the destination structure is always the library’s, whateverbsays.- Isotopic abundances. A
MASScomposition is resolved through ACTINV’s natural-abundance table. FISPACT-II’s differs slightly, and the report does not list the difference. OVERafter the first step. ACTINV overrides are not step-scoped, so anOVERthat follows a scheduled step applies to the whole run, including the earlier steps. Its entries areapproximatedand say so.DOSE.DOSE 1after aDOSE 2and before any step cancels the point source (theDOSE 2entry is marked superseded). After a step the point source stays for the whole run and theDOSE 1entry isapproximated.--files. Afluxesentry that names a missing file stops the import only when the deck irradiates; a cooling-only deck imports and the report records the unresolved entry (fluxes_file_unresolved).--strict. After a failure the report is written, and anOUT.jsonfrom an earlier run is removed so that it cannot be mistaken for the result.OUTmay not be the deck itself.
Tables and plot data from a result
FISPACT-II writes its tables and graph files while it runs. ACTINV writes one result JSON, and actinv report renders it afterwards, so no tab file is needed and the tables can be regenerated for any step. The report is a pure function of the result file; it runs no solver and reads no data.
actinv report RESULT.json [--tables LIST] [--format csv|tsv|markdown|text]
[--out DIR] [--step N|all] [--nuclides Co60,Mn54]
| FISPACT-II | --tables | Content |
|---|---|---|
TAB1 | tab1 | atoms and grams per nuclide, per step |
TAB2 | tab2 | activity (Bq) and heat (W, where FISPACT-II prints kW) per nuclide, per step; also the alpha, beta and gamma heat split and the half-life |
TAB3 | tab3 | ingestion and inhalation dose responses, per step. These are totals over nuclides: the result holds the response value and its activity coverage, not the per-nuclide coefficients |
TAB4 | tab4 | decay-photon source per energy group, per step (photons_s_g, power_W_g, absolute and per gram) |
GRAPH, NUCGRAPH | timeseries | one row per step: total activity, alpha, beta and gamma heat, the photon dose rates and radiological responses when present, and --nuclides columns (atoms and Bq per gram) |
SORTDOMINANT listings | dominant, elements, totals | the summary dominant lists, the element table and the step totals (see the results page) |
Grams, the heat split, half-lives, absolute (whole-sample) columns, the element table and the dominant lists come from the result’s summary; a deck imported with MIND, NOSTABLE or SORTDOMINANT already has the block. Without it tab1 and tab2 still give atoms and Bq per gram from the base fields, the other tables are reported as unavailable, and standard error names every column that was left out. Nothing is filled in. tab3 is unavailable unless the problem declares radiological with a dose response.
Quantities keep the result’s basis. A _per_g column is per gram of initial material; the unsuffixed atoms, mass_g, activity_Bq and heat_W columns scale by material.mass_g. csv and tsv hold exact values, formatted so they parse back to the same number; text and markdown round to six significant digits. See Command line for the options.
Convert a directory of decks
controls/p132_import_all.py imports every */*.i deck under a directory with the release binary and prints the status counts per keyword:
cargo build --release -p actinv-cli
python3 controls/p132_import_all.py ~/nuclear-data/conderc-fns/fns --out /tmp/p132-imports
It passes the library, decay and covariance files named by ACTINV_LIBRARY, ACTINV_ENDF_DECAY and ACTINV_COVARIANCE, when set, and otherwise lets the importer use the catalog references.
Use ACTINV with OpenMC
OpenMC transports the neutrons and the decay photons; ACTINV activates the material in between. There are two ways to connect them:
- Inside OpenMC’s shutdown-dose workflow. A small adapter replaces the activation step of OpenMC’s own
R2SManager. Your OpenMC script stays an OpenMC script; steps 1 and 3 are OpenMC’s, unmodified. - Through files. Import the flux tally from an OpenMC statepoint, run
actinv mesh, and write the decay-photon source back as OpenMC input. No Python coupling, and the same commands read MCNP tallies.
How it compares
On the steel-cube shutdown-dose problem, with both codes on 2 threads, OpenMC’s flux mode on the same 709 groups, and three ACTINV runs and one to three OpenMC runs per size (protocol P163):
| Mesh cells | ACTINV, model to photon source | OpenMC 0.15.3 flux mode | Worst-case ratio |
|---|---|---|---|
| 8 | 10.7–10.8 s | 99.5–102.0 s | 9.2 |
| 64 | 16.4–16.8 s | 138.4–139.2 s | 8.2 |
| 512 | 64.5–66.4 s | 435.1 s | 6.5 |
ACTINV is at least 6.5x faster than OpenMC 0.15.3 flux mode at every measured size (8, 64, 512 mesh cells).
Against OpenMC 0.15.3 in its default tally mode (per-nuclide reaction-rate tallies, one energy group), one run at 8 mesh cells, ACTINV’s steps 1 and 2 are at least 42x faster; this is not OpenMC’s fastest mode.
The two codes used different data: OpenMC ENDF/B-VIII.1 cross sections with its depletion chain, ACTINV TENDL-2025.
Their shutdown dose rates agreed within 2.1% at every size. ACTINV’s working set was about 1 GiB; OpenMC’s flux mode
needed about 6.4 GiB. Both times include OpenMC’s neutron transport, which the two arms share. The record is
results/p163_speed.json.
On accuracy, the competitive benchmark compares the two activation paths on the same ENDF/B-VIII.1 data against 21 FNS decay-heat experiments (424 measured points): median |ln C/E| 0.131 for ACTINV and 0.181 for OpenMC’s depletion. See Understand the competitive benchmark.
On all 132 FNS experiments (protocol P172): against 2360 measured decay-heat points from 132 JAEA FNS experiments, ACTINV with its shipped TENDL-2025 data has a median |ln C/E| of 0.139; OpenMC 0.15.3 depletion with its published ENDF/B-VIII.1 fast-spectrum depletion chain (chain_endfb81_fast.xml) and ENDF/B-VIII.1 has 0.316. With its R-matrix-limited capture repaired and otherwise the same ENDF/B-VIII.1 cross sections as OpenMC, ACTINV has a median |ln C/E| of 0.234 on 2360 measured decay-heat points from 132 JAEA FNS experiments (P179). See All 132 FNS experiments for OpenMC’s other chains.
Without transport, on the same 132 problems (protocol P180): on the 132 JAEA FNS decay-heat problems of P172, each solved in its own process on the same two CPU cores with the same ENDF/B-VIII.1 cross sections, ACTINV 1.7.1 took a median of 0.61 s per problem from start to finish and OpenMC 0.15.3 depletion 18.1 s; the median per-problem ratio was 29.8. Counting only OpenMC’s depletion step, without its start-up and cross-section collapse, the median per-problem ratio was 9. See Per-problem time.
On a mixed-material mesh (a tungsten sphere in CuCrZr, water and steel, protocol P181 Amendment A, one run per size on an Intel Core i3-N305). Inside the same 10 GiB memory limit and 4-hour limit per run, ACTINV (with an ENDF/B-VIII.1 activation library) completed meshes up to 32,768 elements (36,208 regions) and OpenMC 0.15.3 in flux mode up to 4,096 elements (5,120 regions); at 13,824 elements OpenMC was stopped by its memory limit. On a mixed-material model (a tungsten sphere in CuCrZr, water and steel, 14.1 MeV source) meshed into 4,096 elements (5,120 activation regions), with the same transport and two CPU threads, ACTINV 1.7.1 with an ENDF/B-VIII.1 activation library took 155 s from model to photon source and OpenMC 0.15.3 in flux mode 3,432 s, with peak working memory of 1.4 GiB and 7.2 GiB (one run each). See Larger meshes with several materials for every size and the conditions, including that ACTINV’s runs were redone on ENDF/B-VIII.1 after a first run on TENDL-2025 was seen.
Against OpenMC’s most faithful mode, its R2S with direct reaction-rate tallies (protocol P191): On P181’s tungsten, copper-alloy, water and steel model with 8 mesh elements, ACTINV’s R2S with mixture self-shielding gave a shutdown dose 1.038 ± 0.016 times that of OpenMC 0.15.3’s own R2S with direct reaction-rate tallies, on the same ENDF/B-VIII.1 cross sections; ACTINV’s steps 1 and 2 (model to photon source) took 91 s against 4206 s for OpenMC’s. Without self-shielding ACTINV’s dose was 1.040 ± 0.016 times OpenMC’s; mixture self-shielding changed ACTINV’s distance from OpenMC’s dose by no more than two combined standard deviations (SHIELDING NEUTRAL).
Inside OpenMC’s R2S workflow
You need OpenMC 0.15.3 or newer (the versions that have openmc.deplete.R2SManager), the actinv Python
package (pip install actinv), and the standard data (actinv data fetch). The adapter is the module
actinv.openmc; importing actinv alone never imports OpenMC, and actinv.openmc stops with a clear message if
OpenMC is missing or older than 0.15.3. It is tested on OpenMC 0.15.3 and 0.16.0, and weekly on OpenMC’s
development branch.
import openmc
from actinv.openmc import ActinvR2SManager
r2s = ActinvR2SManager(model, mesh)
r2s.run(timesteps=[3.15e7, 1.0e6], source_rates=[1.0e17, 0.0], photon_time_indices=[2])
run calls the same steps as OpenMC’s own manager: three in OpenMC 0.15.3 (the third is
step3_photon_transport), four from 0.16 (step3_photon_source builds the sources, step4_photon_transport runs
them). A cell-based run also needs bounding_boxes={cell.id: box}, as with OpenMC’s manager.
With no further arguments the manager uses the default data bundle you installed (under ./actinv-data or
$ACTINV_DATA_DIR; it tells you to run actinv data fetch if the files are missing) and the actinv command that
came with the package. To use other files or another build, pass library=, decay_primary=, decay_fallback= or
actinv_bin=.
What changes compared with OpenMC’s own manager:
- Step 1 tallies the flux on the library’s 709 groups, so ACTINV never rebins it, and needs no depletion chain:
it is OpenMC’s step 1 with only the flux tallied, and it writes the same results and files. Pass
micro_kwargs={"chain_file": "chain.xml"}(ornuclides/reactions) to run OpenMC’s own cross-section step instead. - Step 2 writes every region’s flux and material, runs one
actinv meshfor all of them, and hands OpenMC a results object that answersget_decay_photon_energy()for each region. It also saves the region materials asmaterials.xml, sor2s.load_results(path)reopens a finished run without solving again. - The photon sources are ACTINV’s decay-photon spectrum for each region, with strength in photons/s. From
OpenMC 0.16 the manager builds them in place of OpenMC’s
DecaySpectrumsources, which would need nuclide densities and a depletion chain; the regions, boxes and domain constraints are OpenMC’s. Scoring by parent nuclide (by_parent_nuclide=True) is not available, since the spectrum is per region. - Photon transport and everything after it are OpenMC’s own code.
Dose uncertainty
Pass uncertainty={} to get a first-order uncertainty band on every photon tally:
r2s = ActinvR2SManager(model, mesh, uncertainty={})
r2s.run(timesteps=[3.15e7, 1.0e6], source_rates=[1.0e17, 0.0], photon_time_indices=[2])
band = r2s.results["dose_uncertainty"][2][0] # time index 2, first photon tally
band["dose"], band["total_std_dev"], band["std_dev"]["cross_section_mf33"]
The band covers three sources by default: the activation cross sections (the library’s MF=33 covariances, from
the uncertainty/ file that actinv data fetch installs beside the library), decay constants, and the Monte
Carlo noise of the step 1 flux tally. It also includes the photon tally’s own statistics. Add "fission_yields"
to channels for fissile materials, or leave channels out with uncertainty={"channels": [...]}.
How it works:
- Step 2 runs
actinv mesha second time with an uncertainty block. The block covers the activities of the strongest photon emitters, enough to cover all but 10⁻⁵ of each region’s source (at most 60 nuclides). actinv export-r2s-covthen writes, for each step, how each region’s photon source moves with each uncertain input.- The photon run tallies each of your tallies a second time, split by the cell or mesh element where the photon
started. These copies are removed afterwards, so
results["photon_tallies"]andload_resultssee only your tallies. - The split gives the dose per photon born in each region. That, combined with the source covariance, gives the variance.
Each band is a dictionary in the tally’s own shape:
doseis the tally mean times the total photon source.std_devholds one entry per channel.statistical_std_devis the photon tally’s own noise.total_std_devandrelativegive the total.unbanded_fractionandchannels_missingsay what the band leaves out.
Treat the band as a lower bound on the data uncertainty. Nuclides outside the bands, and channels with no
covariance data, contribute nothing to it. The flux channel needs the flux-only step 1, so it cannot be used
together with chain_file.
Current limits:
- one mesh, or a list of cells that are filled with materials directly;
- the photon run must use the same geometry as the neutron run (no separate
photon_model).
Resonance self-shielding
By default the adapter shields each material’s resonance cross sections with its own total
(self_shielding="mixture"). Pass self_shielding=None to turn it off:
r2s = ActinvR2SManager(model, mesh, self_shielding=None)
Step 2 writes each material nuclide’s pointwise cross sections out of your OpenMC library
(openmc.config["cross_sections"]), at the library temperature within 1 K of the run’s (294 K for the default
293.6 K). actinv mesh then applies them as
mixture self-shielding, once per material.
Nuclides with no file in the library enter the mixture total through an analytic estimate. A run temperature with
no stored library temperature within 1 K stops step 2 with an error that names self_shielding=None.
Unshielded 709-group capture rates in steel, copper and tungsten alloys miss OpenMC’s continuous-energy rates. P178 measured them with ACTINV’s ENDF/B-VIII.1 709-group library, the data OpenMC transported with:
On four fusion materials held out from its development (Eurofer-97, Inconel 718, a W-Ni-Fe heavy alloy and copper), ACTINV’s mixture self-shielding brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same ENDF/B-VIII.1 data, where the unshielded rates differed by up to 32.3%. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by that sentence.
P190 repeated it with the pointwise tables the adapter writes:
On P178’s four models, ACTINV’s mixture self-shielding with pointwise cross sections exported from OpenMC’s ENDF/B-VIII.1 HDF5 library at 294 K, instead of reconstructed ENDF-6 evaluations, brought every listed resonance-capture rate within 3.4% of OpenMC’s continuous-energy rate on the same data; each region’s run took at most 73.4 s. 7 of 73 listed capture rows were not scored or did not reach a 0.5% standard error and are not covered by the sentence above.
The planning has since become faster (P190’s slowest region, 34 nuclides, now takes about 5 s), with the same results.
With the default TENDL-2025 library the factors still come from your OpenMC library; that pairing was not part of P190.
contrib/openmc_r2s/demo_steel_cube.py runs the steel-cube problem with both managers and compares the dose. The
adapter’s README lists its limits:
neutron activation only, and one flux spectrum per schedule, scaled by each step’s source rate.
Through files
actinv import-flux openmc statepoint.h5 flux.ndjson --tally 1 --source-rate 1e17
actinv mesh mesh.json result.ndjson
actinv export-openmc-mesh result.ndjson 2 source.py
The tally must be a flux tally on one regular or rectilinear mesh with an energy filter. --source-rate turns the per-source-particle tally into a flux, in
source particles per second. The mesh problem names the flux file, the materials and the schedule; see
Advanced workflows and the
mesh specification.
export-openmc-mesh writes one OpenMC source per cell at one result step, counted from one (here the second). To carry the activation
uncertainty into the photon run, write a banded source with actinv export-r2s and convert it with
actinv export-source openmc; see Export photon sources.
What’s new in 1.7
ACTINV 1.7.0 screens an alloy’s impurities, ships a damage table so that dpa needs no setup, starts a problem from a cited material library, and reorganises the desktop and browser app so that it reaches most of the command line. This page is a tour by task. Versions and releases has the version table, and the 1.7.0 release notes have the full list.
The additions are new commands and opt-in options, except the pathway closure and measurement-design changes collected in Results that may change. The nuclear-data catalog is 1.2.0. The desktop is 0.6.0-preview.1, and the desktop release page describes it.
Screen a material’s impurities
actinv impurities SPEC [OUT] tells you which impurities of an alloy matter, at which cooling times and for which concern, and how much of each you can tolerate. It solves each element once and forms the activity, heat, clearance-index and waste-class table sums of any composition from those runs, then re-solves every reported composition in full. Add a sampling block and every value gets an upper bound and every limit a lower bound over the nuclear-data uncertainty, with the probability of meeting the waste class; see Add nuclear-data uncertainty. In the app, the Impurities page under Studies sets up the same screen from the open problem, runs it on the desktop and shows the result with its bounds. See Screen a material’s impurities.
Get dpa with no setup
The data catalog 1.2.0 includes a neutron damage table. A problem that names it gets dpa, exact NRT dpa, arc-dpa and He/dpa without a table to build. actinv new writes the damage section for you, and actinv import-fispact uses the table for decks that give ALLDISPEN or ATDISPEN. actinv build-damage --method kinematic builds a table from an evaluation for other energies or targets. See Nuclear data.
Import and run more of a FISPACT-II deck
actinv import-fispact takes fission-yield, self-shielding, resonance and damage files and maps the fission, uncertainty, self-shielding, photon and damage keywords. New opt-in options estimate missing photon spectra (photon.missing_spectra: "estimate"), remove X-rays, mix fission yields by each parent’s fission rate and select which parents feed products. See Coming from FISPACT-II.
Start a new problem from a library
actinv new problem.json --material ss316 --source fission --flux 1e13 writes 1 g of a library material under a standard spectrum, irradiated for a year and cooled to 1 h, 1 d, 30 d, 1 y and 10 y; actinv new --list shows the choices. The library has 19 cited compositions of common reactor and fusion materials, each marked as a nominal composition, specification maxima or a measured heat, with its density and a note naming the trace elements it leaves out. The four spectra are D-T fusion, Watt fission, a thermal Maxwellian and 1/E, on the 709-group structure. See Command line.
In the app, New problem on Start opens an empty problem, and three cards fill it in one click each: a library material on Material, a standard spectrum at the flux you type on Source & spectrum, and a standard schedule on Irradiation & cooling. See Start a new problem.
Find your way in the app
The sidebar groups pages as Start, Set up, Results, Studies and Tools; Studies and Tools fold away until opened. Start asks what you want to find out and opens the page that answers it. The five setup steps are ticked as they become ready and end in Check & run, which lists every setting you changed from its default with an Edit button. Validate and Run show their outcome in a chip beside the buttons, and Run reads Running… N s while it works. The nuclear data moved to a Data page under Tools, with Verify the data. Result pages open on Summary, and guided tours cover setup and results. See How the app is organized.
Export a report
The Export page saves a report page you can read, share or print, SVG charts, the tables of actinv report and the result and problem files, into a new folder on the desktop and one zip in the browser. actinv report RESULT.json --format html writes the same report page from the command line. See Export a result and the browser guide.
Run studies from the app
The pages under Studies run the command-line studies from the open problem; the browser sets them up and downloads the input for the command:
- Certify checks limits at the edge of the nuclear-data band and ranks which measurements would narrow the answer (
actinv decide). - Optimize searches up to 6 varied things, within 64 designs, for the best value of one quantity under limits (
actinv optimize). - Compare ranks up to 200 combinations of materials, spectra and irradiation lengths (
actinv study run, which takes up to 1024 from a file). - Mesh & transport takes a transport run’s flux cell by cell: import the tally from OpenMC, MCNP or FISPACT-II, activate every cell (a cancelled run resumes), write the shutdown-dose source for OpenMC, MCNP, Serpent or ALARA, and check which cells clear their limits. See Activate a transport mesh.
- Measurements fits the irradiation flux to measured activities (
actinv reverse, orreverse-qualifiedwith the nuclear-data uncertainty), and Use this flux puts the answer into the schedule. It also narrows the loaded result’s bands with a measured value. See Bring in measurements.
See Certify, optimize and compare designs. Waste class now asks which waste question you have: the class of this result with the draft intrusion screen, the class of a container of several items, every class a component can reach when its activities are ranges, and how sure the class is under nuclear-data uncertainty. See Classify a result as waste. On What to compute, the Uncertainty card gains Unmodeled error, which Estimate from library disagreement fills from actinv eval-spread.
Look at results in the browser
The browser’s Start page opens two results solved ahead of time, so a first visit shows real output without installing anything: the iron example’s result, and an impurity screen of a reduced-activation steel. See Use the browser workbench.
Results that may change
pathway_closure now counts only populations above 1e-12 of the step’s largest. The quick start (examples/fns_fe_5min.json) reported 4.117 because of Mn-58 at 2.7e-28 atoms/g; it now reports 3.9e-15, and no other result field changes. Damage tables you build with build-damage --method kinematic use NJOY2016 HEATR’s per-element displacement energies by default instead of a flat 25 eV; tables built before 1.7.0 are unchanged. In actinv decide, design.top_reactions now computes covariance blocks that are only positive semi-definite, which it used to report as ill_conditioned, and lists computed blocks first; on the iron decision example Fe-56 and Fe-54 now head the list instead of Ca-43 to Ca-47.
What’s new in 1.6
ACTINV 1.6.0 extends the waste commands and gives rate pruning a proven bound. This page is a tour by task. Versions and releases has the version table, and the 1.6.0 release notes have the full list.
The waste additions are new commands; a problem that does not use them computes what it computed before, except for the pruning change collected in Results that may change. Classification from measurement-supported scaling factors and rule packs for jurisdictions other than U.S. 10 CFR 61.55 are not in this release. The nuclear-data catalog stays at 1.1.0. The desktop is 0.5.0-preview.1, and the desktop release page describes it.
Classify waste under nuclear-data uncertainty
actinv waste uncertainty SPEC [OUT] answers “how sure is this class?”. It re-solves the problem for each correlated draw of the spec’s study.robustness channels (MF=33 cross sections, decay constants, fission yields, flux, composition) and classifies every sample with the same evaluator as actinv waste. The result gives the frequency of each class with Clopper-Pearson intervals, the class established at a confidence level (at least 72 samples at 0.95), percentiles of each table sum, and how much of the response the sampled channels cover. See Classification under nuclear-data uncertainty.
Set impurity budgets under uncertainty
actinv waste budget uncertainty SPEC [OUT] turns a class impurity budget into one that holds at a confidence level. Each sample applies the same data factors to every element solve, and the budget is the order-statistic bound of the per-sample suprema, with the constraints that bind and a verification re-solve. Budgets are upper bounds only. See Budgets under nuclear-data uncertainty.
Classify a package of discrete items
actinv waste package SPEC [OUT] classifies one container of activated metal, contaminated material, components, sealed sources and cartridge filters under the NRC concentration-averaging and encapsulation BTP (Revision 1, 2015). It applies the BTP’s item tables and the Factors of 2 and 10, classifies failing items alone, merges sectioned components, and credits encapsulation under the BTP’s loading, volume, mass and Class C rules. The result records the readings of the BTP it relies on. See Classify a package of discrete items.
Use the waste commands from Python
actinv.waste exposes classify, budget, bounds, composition, composition_solve, intrusion_screen, uncertainty, budget_uncertainty and package, and actinv.twin runs a facility twin. Each takes a spec path or a dictionary and returns what the CLI writes; actinv.waste.summary gives one row per component and step. See Waste classification from Python.
Classify a result in the desktop
The desktop’s Waste class page, in the EXPLORE group, builds a waste spec from the loaded result, fills the nuclide properties from the run’s decay data, classifies it with the CLI’s own evaluator, and shows each step’s class, governing table, sum, margin and binding nuclides. The browser workbench opens and edits waste specs and shows waste results but does not classify. See Classify a result as waste.
Results that may change
Rate pruning now drops a nuclide only when a proven bound on its population over the whole schedule is below bmin_atoms_per_g; the previous rule could under-estimate a population. The numerical method describes the bound.
- A few noise-level nuclides are kept or dropped differently. Over the 132 FNS decay-heat experiments at the default threshold, nineteen change heat by more than 1e-6 (at most 1.4 %) and total activity by up to 48 %, only at the end-of-irradiation step. The cause is Be-8 from C-12(n,n’α) in carbon-rich samples: it lives about 1e-16 s, so its population stays below the threshold while its activity equals its production rate. Nothing differs after the first cooling step, and every change is inside the run’s bound. Use
prune: "reach"or a lower threshold where end-of-irradiation activity matters. - The ledger’s
rate_pruningblock replacesremoved_heat_W_per_g_boundwith bounds on dropped and kept activity and heat, their sumsactivity_Bq_per_g_boundandheat_W_per_g_bound, andunbounded_components. Anything that reads the old field, compares ledgers or hashes a normalized result will see the change. See the ledger.
What’s new in 1.5
ACTINV 1.5.0 is mostly about work that used to leave ACTINV for another tool: reading a FISPACT-II deck, printing FISPACT-style tables, estimating dose at a distance, tracing production routes, and checking an inventory against a transport or clearance table. This page is a tour by task. Versions and releases has the version table, and the 1.5.0 release notes have the full list.
Nearly everything below is opt-in. A problem that does not name a new section computes what it computed before; the changes to default results are collected in Results that may change. The nuclear-data catalog stays at 1.1.0. The desktop is 0.4.0-preview.1, and the desktop release page describes it.
Start from a FISPACT-II deck
actinv import-fispact converts a FISPACT-II input deck into an ACTINV problem and writes a report that marks every keyword as mapped, approximated, noted or unsupported:
actinv import-fispact DECK.i OUT.json [--fluxes FLUXES] [--files FILES] [--library LIB.npz] [--decay DECAY] [--covariance COV.npz] [--strict]
All 132 public FNS decks import. POWER, WALL, PARTITION, OVER, GRPCONVERT, DOSE 2, GROUP, BREMSSTRAHLUNG, PATH/ROUTES and ATWO are mapped, and the importer accepts three-letter keyword abbreviations such as TOL. Several keywords still need you to add a section by hand, and a few have no equivalent; Move a FISPACT-II deck to ACTINV has the full keyword map, including the new Coming from FISPACT-II table.
The deck gives ACTINV the problem, not the data. ACTINV uses its own activation and decay libraries, so results differ from a FISPACT-II run by the difference between the data sets as well as by the solvers.
The same importer is in the desktop and the browser workbench as Import FISPACT-II deck (Ctrl/Cmd+I in the desktop).
Reproduce FISPACT-II features
These are the FISPACT-II capabilities added in 1.5. Each is an optional section of the problem specification.
-
Spectrum conversion.
spectrum.rebinconverts a spectrum between group structures inside the run, and every FISPACT-II neutron structure fromfispact-66tofispact-1102(to 1 GeV) is available. See Spectrum conversion and Group structures. -
Schedule controls. Steps can be driven by a wall loading, a power density or a specific power (with a groupwise kerma table), and a step can apply an instantaneous elemental partition. Power is renormalized on sub-intervals within a step;
max_substeps: 1gives FISPACT-II’s single normalization. See Kerma heating and power-driven steps. -
Overrides and decay-only runs. Per-nuclide, per-reaction cross-section, half-life and uncertainty
overrides, and cooling runs from decay data alone. See Named data overrides and Decay-only runs. -
Fission. Spontaneous-fission products, the cumulative fission count, burn-up and the spontaneous-fission neutron source. See Fission count, burn-up and spontaneous-fission neutrons.
-
Projectiles and libraries. Triton and helion projectiles, and switching the activation library between steps. Neither triton nor helion has a library in the standard catalog, and neither has been tried on real data, so treat them as untested beyond synthetic fixtures.
-
Query data without a run.
actinv inspectprints decay data, group and spectrum-collapsed cross sections, fission yields and group boundaries:actinv inspect decay DECAY_PATH [NUCLIDE...] actinv inspect xs LIBRARY.npz [--target NUCLIDE] [--mt MT] [--spectrum SPEC.json]See Query data files.
Get new outputs
Tables and a step summary
The optional summary section adds the full inventory with grams, activity, alpha/beta/gamma heat and half-life per nuclide, step totals (including activity and heat without tritium), an element table, dominant lists with cumulative percentages, and MIND/NOSTABLE-style filters. A summary.depletion table adds, for each initial nuclide, the depleted fraction and the removal rate split between decay and each reaction. See Step summary and Depletion table.
actinv report renders an existing result as FISPACT-style tables (TAB1 to TAB4, step totals, dominant and element tables, a plot-ready time series) in csv, tsv, markdown or text. It runs no solver:
actinv report RESULT.json [--tables LIST] [--format csv|tsv|markdown|text]
[--out DIR] [--step N|all] [--nuclides LIST]
See Render result tables.
Photons and dose
- The 22-group Steiner photon structure alongside the 24-group structure. See Steiner 22-group structure.
photon.point_sourcegives the gamma air-kerma rate at a distance from the sample (at least 0.3 m), like FISPACT-II’sDOSE 2. See Point-source dose.photon.bremsstrahlungreports the bremsstrahlung photons and their dose as a separate block; it is not added to the decay-photon dose. See Bremsstrahlung.
The dose values are null when the photon response has no air attenuation curve or when nuclides have decay-record gamma power with no photon spectrum, rather than a number that looks complete. The shipped response has no air attenuation curve, so a point-source dose needs a rebuilt response or air_attenuation: false; the specification explains both. Approximate gamma spectra for such nuclides (SPEK) are not estimated; the power that has no spectrum is reported instead.
Production pathways and routes
The optional pathways section traces multi-link routes from a source nuclide to a target, including loops, and integrates each route exactly through every schedule step. Each target reports a closure: the total production, the sum over the listed routes, and what the routes leave unexplained. See Read the pathway routes and Pathways and routes analysis.
Regulatory tables
A problem can now compare an inventory with bundled public tables: the A1 and A2 values of 49 CFR 173.435, the exempt values of 49 CFR 173.436, and the clearance and exemption levels of Euratom Directive 2013/59 Annex VII. They are opt-in (radiological.table.path set to bundled:NAME). ACTINV chooses no jurisdiction for you, and whether a table applies to your material and use is your decision.
actinv report has a table for them. It is built only when you name it:
actinv report RESULT.json --tables regulatory
It lists, per step, each clearance, waste or A2 response with its value and the share of the activity the table covers. Some rows have no finite limit, and progeny can be included in a parent’s value; the tables record both, so require_complete can be satisfied by an activation inventory. See Bundled regulatory tables.
ICRP 119 dose coefficients are not bundled because of their copyright. If you hold the publication, scripts/regulatory/fetch_icrp119.py builds a table for your own use; see Building the ICRP 119 dose-coefficient table locally.
Treat self-shielding by geometry
self_shielding.geometry applies a resolved-resonance self-shielding correction for a foil, wire, sphere or cylinder using the universal sigmoid curve, as FISPACT-II’s SSFGEOMETRY does. It reads ENDF resonance files you supply, including R-matrix-limited (LRF=7) evaluations such as ENDF/B-VIII and FENDL-3.2c. self_shielding.dilution_overrides sets the background dilution for chosen groups when you use a Bondarenko table. See Geometry self-shielding and Dilution overrides.
A resonance is used only inside the energy range its evaluation resolves; see Results that may change.
Understand the uncertainty
study.robustness.statisticsadds, for each response, the sample mean, standard deviation, skewness, exact percentiles and a histogram, the input-output Pearson and Spearman correlations by sampled parameter, a response-response correlation matrix, and bootstrap errors next to the first-order standard deviation. It is the counterpart to FISPACT-II’sSENSITIVITYandMCSAMPLEoutput, and it is absent unless you ask for it. See Monte Carlo sampling statistics.- A single sample has no standard deviation, correlations and bootstrap errors need at least three samples, and
first_orderreadsnot_comparablewhen channels beyondcross_section_mf33are sampled. - The removal-rate uncertainty in the depletion table uses the same MF=33 covariance as the rest of the run.
Use the 0.4 interface
Desktop 0.4.0-preview.1 and the browser workbench now have thirteen pages in three groups, with the same look as before. The browser still never runs the solver.
- Outputs (under setup) is one place to enable the step summary and depletion, decay photons and dose, production pathways and routes, regulatory tables, geometry self-shielding, uncertainty with each of its channels (including flux tally statistics) and gas production. A status line on each card gives the solver’s own message when two choices conflict.
- Irradiation & cooling has a Drive for each step (flux multiplier, wall loading, power in W/cm3 or W/g), and Material has an optional density.
- Charts, Tables, Photons & dose, Pathways and Ledger & certificate share one result bar and one chosen step. Tables exports CSV that is byte-identical to
actinv report. - Import FISPACT-II deck converts a deck with the importer’s per-keyword report. Unlike the CLI, the desktop converts a deck that irradiates but has no fluxes file by inserting a flagged placeholder spectrum; replace it before running. The CLI refuses such a deck.
See Use the desktop and Use the browser workbench.
Results that may change
Most 1.5 changes are opt-in. These are not, or they correct a result you may already have.
Defaults that moved
- A fission after another decay transition (beta-delayed fission, RTYP 2.6) was counted as spontaneous fission of the parent. It is now counted in the new ledger key
unmodelled_decay_branches_to_leakage, sospontaneous_fission_branches_to_leakagefalls from 129 to 126 on the shipped data. Inventories do not change. The new key appears only when it is nonzero. - Trace-mode pathway attribution now includes production fed by the decay of a radioactive bulk nuclide, and
pathway_closureis 1 when a nuclide in the inventory has no chain at all. Inventories do not change. In SS316 the leading Ru-100 route is Mo-100 double-beta decay; in tungsten, W-186 alpha decay feeds Hf-182 (the closure of the shipped shielding example falls from 0.98 to 5e-16); and the natural-uranium closure falls from 1.0 to 4e-15. - Trace mode no longer holds radioactive initial material constant.
autonow selects the coupled solver when any initial nuclide decays by 1e-6 or more over the schedule, and an explicit trace request is refused there. Restart or cooling runs from an activated inventory that did not setcoupledshould be rerun. - Trace-mode pathway attribution used to ignore the step’s flux multiplier and spectrum override, and lost production after a cooling gap. It now uses the solve’s own matrices, and
pathway_closureshows the difference.
Opt-in features that were corrected
- Bremsstrahlung used the decay record’s average electron energy per decay of the parent as the energy of one electron per decay. It now uses the beta-minus branching and the matching energy per electron. Partial beta emitters such as Cu-64 change (about 2.6 times more energy); pure beta-minus emitters do not.
- The bundled regulatory tables were regenerated, so their SHA-256 values changed. A spec that declares a bundled table’s hash must use the new one;
actinvfills a missing hash itself. - Geometry self-shielding uses a resolved resonance only inside the range [EL, EH] that its evaluation resolves. TENDL-2025 W-186 is resolved to EH = 4341 eV and loses its factors above that energy; ENDF/B-VIII.1 W-186 loses one group above 10 keV. Whether FISPACT-II clips resonances at the same energy is not verified here, so a W-186 comparison with FISPACT-II may differ for this reason. A
geometry.density_g_cm3that disagrees with the material density is refused.
The changelog lists the remaining fixes (schedule refusals, depletion and sampling statistics, importer robustness).
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.
Rate pruning drops a nuclide only when a proven upper bound on its population over the whole schedule is below the threshold. The bound sums every parent’s contribution, limited both by the parent’s population and by the share of its losses each edge can take, and cycles are handled only where a contraction is certified; otherwise they are kept. The ledger reports bounds on the resulting change in total activity and decay heat, including the shortfall of kept nuclides fed by dropped ones. The bound covers the assembled linear problem, not data, flux, or solver error.
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 Bondarenko factors for the resolved range (a Doppler-broadened pointwise quadrature) and the unresolved range (probability tables). Fixed or composition-derived dilution selects factors on the declared grid, and compatibility is checked against the library. This bounded method does not provide a geometry-dependent transport solution.
The mixture option (new in 1.7.2) computes the resolved-range factors at run time instead, from the pointwise cross sections of every nuclide in the material with a narrow-resonance 1/Σt flux weight, so overlapping resonances of different nuclides shield each other. It is also infinite-medium: no geometry or escape term. See Mixture self-shielding.
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
| Evidence | What it assesses | Practical limit |
|---|---|---|
| Analytic and independent CRAM controls | Time integration, network accounting, and numerical comparisons | Does not establish evaluated-data accuracy |
| IAEA FNS decay-heat experiments | Recorded irradiation/cooling cases across 73 materials and 132 experiments | Results depend on evaluation choice and the benchmark metric |
| IRDFF-II spectrum-averaged cross sections | 120 measured reaction cross sections in the Cf-252 and U-235 fission spectra (IRDFF-II Tables 18–20), with TENDL-2025: median absolute log error 0.014 to 0.024 per table | Tests cross sections in fission spectra, not 14 MeV fields or irradiation histories |
| NPI Řež quasi-monoenergetic fields | 29 measured activation reaction rates in two 7Li(p,n) neutron fields peaking near 10–12.5 MeV, an independent facility from FNS; see the benchmark | Tests activation cross sections folded with a published spectrum, not inventories or decay heat |
| Fission decay-heat experiments | Fission-product heat after thermal fission of U-233, U-235 and Pu-239, measured at five laboratories (Oak Ridge, Los Alamos, IRT, UC Berkeley, CEA Cadarache), from 0.75 s to 1.5 × 10⁵ s; see the benchmark | Tests fission yields and decay data, not activation cross sections; thermal fission only |
| FNG/ITER cell-620 history | Supplied activation history and selected nuclides over recorded times | Does not validate complete shutdown-dose transport |
| Photon and response controls | Reader agreement, source conservation, unit conversions, and screening responses | Limited reference cases; contact dose remains a slab proxy |
| Import and mesh controls | Supported tally subsets, normalization, rebinning, and independent-cell output | Does not qualify the originating transport calculation |
| Covariance and sensitivity controls | Retained uncertainty propagation and coverage reporting | Does not include all uncertainty sources |
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 to November 2026, including ACTINV 1.1.2-era runs, the ACTINV 1.7.0 shutdown-dose timing and the ACTINV 1.7.1 per-problem timing. They are not fresh measurements of every 1.7.1 feature or a ranking for every material, spectrum, and operating regime.
Three different comparison questions
| Comparison | Question it answers | What to check |
|---|---|---|
| Calculated responses against measurements | How well does this code and selected data predict the experiment? | Material, spectrum, history, response, and data versions |
| Codes using common evaluated cross sections | How much do processing, chain representation, and numerical methods differ? | Decay data and represented product states can still differ |
| The same matrix/time step in numerical kernels | How quickly do the implementations solve this numerical workload? | Matrix size, call overhead, threading, hardware, and omitted setup work |
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.
| Metric | Interpretation |
|---|---|
Median abs(ln(C/E)) | Typical multiplicative error across scored points; lower is better |
90th percentile, or p90, abs(ln(C/E)) | Error toward the difficult end of the distribution; lower is better |
| Pooled geometric-mean C/E | Overall multiplicative bias; closer to 1 is better |
| Experiments with all points inside the acceptance band | Entire measured cooling curves meeting the stated threshold; higher is better |
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.
| Metric | ACTINV / TENDL-2017 | FISPACT-II / TENDL-2017 |
|---|---|---|
| Median absolute log error | 0.1030 | 0.1053 |
| p90 absolute log error | 0.6894 | 0.6846 |
| Pooled geometric-mean C/E | 1.0605 | 1.0636 |
| Experiments with all scored points in the band | 71 / 132 | 69 / 132 |
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.
| Metric | ACTINV / ENDF-8 | OpenMC / ENDF-8 |
|---|---|---|
| Median absolute log error | 0.131 | 0.181 |
| p90 absolute log error | 0.970 | 1.640 |
| Pooled geometric-mean C/E | 0.788 | 0.685 |
| Experiments with all scored points in the band | 10 / 21 | 10 / 21 |
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.
All 132 FNS experiments
Protocol P172 repeated the comparison on every FNS experiment, with OpenMC 0.15.3 in its published configuration and ACTINV both with its shipped data and with OpenMC’s cross sections. P179 reran ACTINV’s identical-data arm after the 1.7.1 capture repair.
Against 2360 measured decay-heat points from 132 JAEA FNS experiments, ACTINV with its shipped TENDL-2025 data has a median |ln C/E| of 0.139; OpenMC 0.15.3 depletion with its published ENDF/B-VIII.1 fast-spectrum depletion chain (chain_endfb81_fast.xml) and ENDF/B-VIII.1 has 0.316.
With its R-matrix-limited capture repaired and otherwise the same ENDF/B-VIII.1 cross sections as OpenMC, ACTINV has a median |ln C/E| of 0.234 on 2360 measured decay-heat points from 132 JAEA FNS experiments.
With isomer branching ratios from the ENDF/B-VIII.1 library added to that chain, OpenMC has a median |ln C/E| of 0.252 on the 2360 of those points it covers.
With a chain built from ENDF/B-VIII.0 decay data and TENDL-2025 reaction channels instead (Chain.from_endf, ground-state targets), OpenMC has a median |ln C/E| of 0.311 on the 2358 of those points it covers.
Evidence: P172 scored points and verdict and P179 verdict.
Activation reaction rates: a second facility
The FNS experiments above all come from one facility. Protocol P167 adds an independent one with open data: the 7Li(p,n) quasi-monoenergetic neutron source of the Nuclear Physics Institute of the Czech Academy of Sciences at Řež, where foils were irradiated in fields from 12.4 MeV and 14.4 MeV protons and the spectrum at the foils was measured (Matěj, Košťál, Majerle et al., arXiv:2306.09353). ACTINV computed each reaction rate with its shipped TENDL-2025 library and its own spectrum rebin and collapse (actinv inspect xs).
Against 29 measured reaction rates in two quasi-monoenergetic 7Li(p,n) neutron fields at NPI Řež (12.4 and 14.4 MeV protons; Matěj et al., 2023), ACTINV with its TENDL-2025 library has a median |ln C/E| of 0.038 and a geometric-mean C/E of 1.023.
On the same points the authors’ calculations give a median |ln C/E| of 0.047 with ENDF/B-VIII.0, 0.051 with JEFF-3.3 and 0.057 with JENDL-4, and 0.030 with IRDFF-II on the 27 points it covers.
25 of the 29 ACTINV values are within 2σ of the measurement.
| Field | Points | ACTINV median abs log error | ACTINV within 2σ |
|---|---|---|---|
| 12.4 MeV protons | 13 | 0.039 | 9 |
| 14.4 MeV protons | 16 | 0.035 | 16 |
IRDFF-II is a dosimetry library fitted partly to integral measurements like these, so it is a reference rather than a peer. The largest ACTINV deviation is ⁶⁰Ni(n,p) in the 12.4 MeV field, 18% high, where every library is high by about the same amount. The authors normalized the spectra to ⁵⁸Ni(n,p) and ²⁷Al(n,α), so those two reactions are not counted; ACTINV reproduces them within 1%. This checks activation cross sections between about 1 and 13 MeV; it does not check inventories or decay heat.
Evidence: reaction rates and verdict.
Fission decay heat: five laboratories
Fission-product decay heat tests the fission yields and decay data behind every fission inventory. Protocol P166 scored ACTINV against the measured tables of the IAEA CoNDERC fission compilation (Gauld, 2019): Friesenhahn 1976 and 1979 (IRT), Schrock 1978 (UC Berkeley) and Fiche 1976 (CEA Cadarache), for U-233, U-235 and Pu-239 thermal fission, with irradiations from a 1 s pulse to 35 days. ACTINV used ENDF/B-VIII.0 yields and decay data. The compiler’s ORIGEN calculations, printed in the same tables, used ENDF/B-VII.0 yields and ENDF/B-VII.1 decay data.
Against 692 measured total decay-heat points from 12 fission decay-heat experiments at IRT, UC Berkeley and CEA Cadarache (U-233, U-235 and Pu-239 thermal fission), ACTINV with ENDF/B-VIII.0 yields and decay data has a median |ln C/E| of 0.046 and a geometric-mean C/E of 0.960.
On the same points, ORIGEN with ENDF/B-VII.0 yields and ENDF/B-VII.1 decay data (Gauld, 2019) has a median |ln C/E| of 0.042 and a geometric-mean C/E of 0.962.
| Laboratory | Points | ACTINV median abs log error | ORIGEN median abs log error |
|---|---|---|---|
| IRT (Friesenhahn) | 530 | 0.042 | 0.040 |
| CEA Cadarache (Fiche) | 42 | 0.066 | 0.065 |
| UC Berkeley (Schrock) | 120 | 0.091 | 0.083 |
The two codes track each other closely, so the remaining differences come from the data and the measurements rather than the solver. The UC Berkeley scatter is mostly at cooling times the compiler flags as unreliable; limited to 600–10,000 s, the pooled ACTINV figure is 0.040. ACTINV’s separately measured gamma and beta heat (Friesenhahn) have median |ln C/E| of 0.042 and 0.057. The earlier P9 comparison covers the Oak Ridge (Dickens) and Los Alamos (Yarnell) U-235 measurements, with geometric-mean C/E 1.007 and 0.985.
Evidence: scored points and verdict.
Speed: numerical kernel versus a full calculation
A full shutdown-dose calculation with OpenMC
Protocol P163 timed OpenMC’s shutdown-dose (R2S) workflow on the steel-cube problem from model to photon source, with ACTINV doing the activation step against OpenMC 0.15.3 doing it in flux mode, its fastest documented setting. Both codes used 2 threads, the same seeds, and the same transport settings; OpenMC used ENDF/B-VIII.1, ACTINV TENDL-2025.
| Mesh cells | ACTINV | OpenMC flux mode | Worst-case ratio |
|---|---|---|---|
| 8 | 10.7–10.8 s | 99.5–102.0 s | 9.2 |
| 64 | 16.4–16.8 s | 138.4–139.2 s | 8.2 |
| 512 | 64.5–66.4 s | 435.1 s | 6.5 |
ACTINV is at least 6.5x faster than OpenMC 0.15.3 flux mode at every measured size (8, 64, 512 mesh cells).
Against OpenMC 0.15.3 in its default tally mode (per-nuclide reaction-rate tallies, one energy group), one run at 8 mesh cells, ACTINV’s steps 1 and 2 are at least 42x faster; this is not OpenMC’s fastest mode.
The shutdown dose rates agreed within 2.1% at every size. The ratio falls as the mesh grows because ACTINV’s per-cell activation cost comes to outweigh OpenMC’s fixed start-up cost. Evidence: timing record and verdict. See Use ACTINV with OpenMC to run it.
Larger meshes with several materials
Protocol P181 and its Amendment A timed the same workflow on a model where mesh elements cross material boundaries: a tungsten sphere in CuCrZr, water and steel around a 14.1 MeV source, meshed into 8 to 32,768 elements. OpenMC splits each element by material, so the activation regions outnumber the elements. Each run had its own 10 GiB memory limit and 4-hour limit, two CPU threads, and the same transport; one run per size, on an Intel Core i3-N305.
| Elements (activation regions) | ACTINV, model to photon source | OpenMC 0.15.3 flux mode | Peak working memory, ACTINV / OpenMC |
|---|---|---|---|
| 8 (32) | 11.0 s | 112 s | 1.2 / 6.4 GiB |
| 64 (136) | 13.4 s | 180 s | 1.2 / 6.4 GiB |
| 512 (776) | 31.8 s | 604 s | 1.3 / 6.5 GiB |
| 4,096 (5,120) | 155 s | 3,432 s | 1.4 / 7.2 GiB |
Inside the same 10 GiB memory limit and 4-hour limit per run, ACTINV (with an ENDF/B-VIII.1 activation library) completed meshes up to 32,768 elements (36,208 regions) and OpenMC 0.15.3 in flux mode up to 4,096 elements (5,120 regions); at 13,824 elements OpenMC was stopped by its memory limit.
ACTINV used an ENDF/B-VIII.1 activation library, the evaluation OpenMC used, and its shutdown dose rate agreed with OpenMC’s within 4.4% at every size. The first run used ACTINV’s shipped TENDL-2025 data: its doses were 11–21% below OpenMC’s, a difference between the two evaluations for this steel and tungsten that the protocol’s 10% sanity bound does not allow, and that run is not quoted. The amendment that reran ACTINV on ENDF/B-VIII.1 was written after that result was known, and its ACTINV runs came a few hours after OpenMC’s. With TENDL-2025, ACTINV also completed every size but was slower at large meshes (949 s at 4,096 elements). Evidence: amendment record, verdict and P181’s record.
Per-problem time on the FNS problems
Protocol P180 timed the activation calculation alone, with no transport, on the 132 FNS problems of P172. Each problem ran in its own process, so every time includes start-up and data loading, on a quiet machine (Intel Core i3-N305) limited to two cores.
On the 132 JAEA FNS decay-heat problems of P172, each solved in its own process on the same two CPU cores with the same ENDF/B-VIII.1 cross sections, ACTINV 1.7.1 took a median of 0.61 s per problem from start to finish and OpenMC 0.15.3 depletion 18.1 s; the median per-problem ratio was 29.8.
Counting only OpenMC’s depletion step, without its start-up and cross-section collapse, the median per-problem ratio was 9.
With its shipped TENDL-2025 data, ACTINV took a median of 0.88 s per problem.
Evidence: timings and verdict.
The numerical kernel
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.
| Operator states | Recorded time ratio |
|---|---|
| 32 | 13.8 |
| 256 | 2.64 |
| 1,024 | 1.28 |
| 2,048 | 0.98 |
| 4,096 | 1.83 |
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 2026-09-30 capability scorecard refresh updates the ACTINV column for gas production, the transport-tally flux uncertainty channel, lean mesh output, and impurity budgets; the competitor columns there remain the dated CB1 survey.
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
- A transport calculation or measurement supplies the particle spectrum and its physical normalization.
- The analyst chooses activation, decay, yield, covariance, and response data appropriate to the problem.
- ACTINV calculates inventory evolution and requested responses, reporting coverage and omissions.
- Separate transport or consequence tools use the source terms when spatial or shielding effects matter.
- 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
| Capability | Boundary |
|---|---|
| Neutron, proton, deuteron, triton, helion, alpha, and gamma (photonuclear) activation | Triton and helion (data-limited): the builder, spec and solver accept them through the same charged-particle path as the other projectiles, but no triton or helion library is in the standard catalog, no cross-code comparison has been run for either, and the only tests are synthetic fixtures. Gamma (1.4.0): no photofission product yields, no temperature treatment, and no published library (build from the TENDL g sublibrary); cross-code agreement with FISPACT-II is established below 30 MeV, and above it only against FISPACT-II’s own MT5 processing rule |
| Incident energy range | A library holds cross sections only where its source evaluation tabulates them and only up to the top of its group structure: TENDL neutron evaluations reach 200 MeV, the 709- and 1102-group neutron grids and the 162-group charged-particle grid reach 1 GeV, and the EAF-family grids stop at 20 MeV (55 MeV for 211 and 351). Above an evaluation’s upper energy groups are zero, not extrapolated. The opt-in spallation splice adds user-supplied residual-production data above a chosen energy; ACTINV supplies none and does not qualify the table |
| Schedule-level library switch | A step may switch to another activation library (another projectile or evaluation); verified on a synthetic two-library chain only, not against FISPACT-II’s multi-library runs. Not available with uncertainty, gas, self-shielding, damage, fission yields, mesh or study |
| Single-material and independent-cell inventories | No particle transport, criticality, spatial material exchange, or thermal/flux feedback |
| Photon sources and contact gamma response | Contact response is a semi-infinite-slab screening proxy; ordinary exports use a point at the origin |
| Finite-dilution neutron self-shielding | Explicit Bondarenko table required (resolved and unresolved ranges), with optional per-group dilution overrides; damage is not shielded. The resolved-range factors have unit-test coverage only, with no recorded comparison against a reference code or measurement. The opt-in geometry mode (foil, wire, sphere, cylinder) applies the universal sigmoid curve to resolved Breit-Wigner, Reich-Moore or R-matrix-limited (LRF=7) resonances from user-supplied ENDF files; it neglects other mixture components in the resonance cross section and has unit-test coverage only, with no recorded comparison against FISPACT-II or measurement |
| Mixture self-shielding (new in 1.7.2) | self_shielding.mixture shields the resolved range from the material’s own pointwise cross sections and user-supplied ENDF files; the unresolved range, damage and spatial (geometry) effects are not treated. Compared with OpenMC continuous-energy capture rates on four held-out fusion materials (protocol P178, within 3.4% on 66 of 73 listed capture rows); not compared with measurements |
| Cross-section, half-life, independent-yield, and transport-tally uncertainty | Only requested, retained channels propagate; flux statistics use supplied groupwise errors, not systematic transport errors |
| Hydrogen and helium isotope production (1.4.0) | Neutron-only options.gas; excludes ternary-fission gas and cannot be combined with uncertainty |
| Spontaneous fission, fission count and burn-up | Opt-in. Spontaneous-fission branches reach products only for states with a user-supplied yield evaluation, and the neutron source covers only states with a user-supplied or decay-file multiplicity; the rest stay on leakage or are reported uncovered. The count is the MT=18 rate integral plus spontaneous decays, and burn-up in MWd/kg uses a stated per-fission energy (200 MeV default), not a nuclide-specific value. No ternary-fission products, no delayed-neutron time dependence, and no cross-code qualification of these outputs |
| Radiological responses | Explicit user-selected table required; ACTINV supplies no default regulation, jurisdiction, intake scenario, or margin. Public-domain US transport (49 CFR 173.435/.436) and EU Directive 2013/59/Euratom Annex VII tables are bundled but opt-in by name (bundled:NAME); ICRP 119 dose coefficients are built locally from your own PDF. Bundled tables are faithful conversions, not an assessment that a regulation applies to your case; element-level entries need your attention, and unlimited or progeny-covered entries are counted as covered with zero contribution and reported separately |
| Feed and first-order removal | Schedule-level source/sink model, not a coupled process flowsheet; pathway attribution does not track fed material |
| Reverse calculation | Linear trace-regime normalization estimate, not spectrum unfolding or a general inverse transport model |
| NRT damage | Declared material targets and displacement energies; no recombination, general damage function, or damage covariance |
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. Since 1.4.0 a diagonal transport-tally statistical flux channel is also available; it can run alone without an MF=33 sidecar.
State-resolved (MF=10) productions, such as Co-58 from Ni-58(n,p) or Al-26 from Al-27(n,2n), take their reaction’s MF=33 covariance, fully correlated with the reaction total; their isomer-branching part is not propagated, and their responses report partial coverage.
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.
| Component | Version covered here | Release |
|---|---|---|
| CLI, Python, and Rust workspace | 1.7.2 | v1.7.2 |
| Embedded nuclear-data catalog | 1.2.0 | data-v1.2.0 |
| Desktop preview | 0.6.0-preview.1, using solver 1.7.0 | desktop preview |
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.
New in 1.7.2
Release 1.7.2 makes actinv data fetch work for first-time installs again. The IAEA site now refuses automated
downloads of the two decay files, and fetch now takes ACTINV’s byte-identical copy when that happens. The OpenMC R2S
adapter also ships with the Python package (from actinv.openmc import ActinvR2SManager), with an opt-in uncertainty
band on every photon tally; see Use ACTINV with OpenMC.
It also adds mixture self-shielding (self_shielding.mixture) and faster rate pruning, and fixes the
potential-scattering estimate of dilution: "composition" self-shielding. The
1.7.2 release notes have the
detail.
New in 1.7.1
Release 1.7.1 fixes resonance capture in libraries and self-shielding tables you build from R-matrix-limited evaluations. These include ENDF/B-VIII.1 and FENDL-3.2c tungsten, copper, Fe-54 and Fe-57; from 1.5.0 to 1.7.0 their thermal capture was off by factors up to 9. If you built such a library or table, rebuild it. The TENDL-2025 data that ACTINV downloads is unaffected.
It also fixes the study.robustness cross-section sampler and adds:
- national clearance tables (
actinv clearance --jurisdiction de|uk|ca); - a shutdown-dose source covariance export (
actinv export-r2s-cov); build-shielding --profileand--workers, and aprofilefor geometry self-shielding.
The 1.7.1 release notes list what to re-check.
New in 1.7.0
Release 1.7.0 adds impurity screening for fusion materials (actinv impurities), a damage table in the data catalog
(1.2.0) so that dpa, exact NRT dpa, arc-dpa and He/dpa need no table to build, FISPACT-II parity additions
(estimated photon spectra, fission-yield and uncertainty keywords in actinv import-fispact, and
actinv build-damage --method kinematic), actinv new --material with a cited material library and standard spectra,
and actinv report --format html. The desktop 0.6.0-preview.1 reaches most of the command line: an Export page, and
pages for impurity screens, certification, optimization, comparison, waste questions, transport meshes and
measurements; the browser sets these up and opens two results solved ahead of time. The pathway closure no longer
counts noise-level populations, and actinv decide computes the measurement-design blocks it used to leave null. See What’s new in 1.7, the
1.7.0 release notes and the
desktop 0.6.0-preview.1 notes.
New in 1.6.1
Release 1.6.1 fixes one defect of 1.6.0. A trace-mode run with pathway output, which the default outputs
include, could stop with an index out of bounds error. This happened when a reaction of a bulk nuclide led to a
product with no decay data. Runs that completed in 1.6.0 give the same results in 1.6.1.
New in 1.6.0
Release 1.6.0 adds waste classification under nuclear-data uncertainty (actinv waste uncertainty), impurity budgets
under uncertainty (actinv waste budget uncertainty), classes for packages of discrete items with encapsulation
(actinv waste package), the waste commands in the Python API (actinv.waste, actinv.twin) and a Waste class page
in the desktop. Rate pruning now drops a nuclide only when a proven bound on its population is below the threshold,
and the ledger’s rate_pruning block reports bounds on the change in total activity and heat; see
What’s new in 1.6.
New in 1.5.0
Release 1.5.0 adds FISPACT-II deck import (actinv import-fispact), result tables (actinv report) and library queries (actinv inspect), a step summary and depletion table, photon dose at a distance with a separate bremsstrahlung block, production pathways and routes with closure, bundled regulatory tables (49 CFR 173.435/173.436 and Euratom 2013/59 Annex VII), geometry self-shielding, sampling statistics for robustness studies, wall-loading and power-driven steps, and spontaneous-fission products. The desktop 0.4.0-preview.1 adds the Outputs, Tables, Photons & dose and Pathways pages and deck import. Some defaults changed; see Changes that may affect earlier results. The data catalog stays at 1.1.0. What’s new in 1.5 is a tour of the additions; see also the 1.5.0 release notes and the desktop 0.4.0-preview.1 notes.
New in 1.4.0
Release 1.4.0 adds impurity-budget workflows (actinv budget and the Python budget helper), the OpenMC R2S adapter, hydrogen/helium isotope production through options.gas, transport-tally statistical error propagation through the flux uncertainty channel, lean mesh output through dotted steps.<field> entries in cell_result_fields, and photonuclear (incident-gamma) activation through build-library --projectile gamma. Gamma activation libraries are not published through actinv data fetch; build one from the TENDL g sublibrary. See the 1.4.0 release notes.
Source builds between releases can carry a workspace version that has not moved yet, 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.7.2
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.7.2 release notes change no default result. Rerun calculations that used self_shielding with dilution: "composition" on materials whose main scatterers are light nuclides missing from the table (concrete, water); from 1.1.0 to 1.7.1 they were over-shielded.
The 1.7.1 release notes change no default result. Rebuild any library or self-shielding table you built from R-matrix-limited evaluations (ENDF/B-VIII.1 and FENDL-3.2c tungsten, copper, Fe-54, Fe-57 and others) with 1.5.0 to 1.7.0, and rerun what used it. study.robustness bands from cross_section_mf33 can also differ from 1.7.0.
The 1.7.0 release notes list the two default-result changes: pathway_closure counts only populations above 1e-12 of the step’s largest, so the quick start reports 3.9e-15 instead of 4.117, and actinv decide computes the design.top_reactions blocks it reported as ill_conditioned. Results that may change has the detail.
The 1.6.0 release notes describe the one default-result change: the new rate-pruning rule keeps or drops a few different noise-level nuclides, and the ledger’s rate_pruning fields are renamed and extended. Results that may change gives the measured effect.
The 1.5.0 release notes list the default-result changes: trace mode with radioactive initial material (restart or cooling runs from an activated inventory should be rerun), trace-mode pathway attribution, the spontaneous-fission branch count, and corrections to opt-in photon, regulatory-table and self-shielding outputs. Results that may change summarizes them.
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 that release’s capabilities and their qualification boundaries. The 1.4.0 release notes identify a trace-mode correction that moves results for multi-element materials; review them if your earlier calculations used trace mode. 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.