Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

  • decay reports, 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 example Co60 or Ta182m1. With --estimated-spectrum it instead prints, per nuclide, the spectrum that photon.missing_spectra: "estimate" would use (decay-mode class, E_max before 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 is fispact-24 by default, or --group-structure steiner-22, or custom boundaries in eV with --group-boundaries-eV; the JSON schema is actinv-inspect-decay-estimated-spectrum-1, and --table prints one table per nuclide.
  • xs lists a library’s reactions: target, MT, product, group count and energy structure. With --target it also gives each reaction’s group cross sections; --target takes a nuclide name or a raw target index (a ZA such as 26056 is not an index; name the nuclide), and a name needs the *_index.json file beside the library. --mt keeps 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 to 1e-12 relative. A spectrum with rebin is converted onto its named destination structure first, as a run does, and the destination must be the library’s.
  • yields reads one or more fission-yield evaluations and reports independent yields at every tabulated incident energy. --energy EV interpolates between tabulated energies exactly as a run does and reports each product’s propagated uncertainty. --cumulative selects the evaluation’s cumulative (MT=459) yields, when present, for inspection only; runs never use them. --parent selects an evaluation by parent nuclide.
  • library summarizes 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 the spallation splice provenance, under index_objects). A library without an index file is named after any of the FISPACT-II structures its boundaries match.
  • groups prints the boundaries of fispact-709, fispact-162, a refinement such as fispact-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
TableOne row perColumns
tab1step and nuclide, largest population firststep, time_s, nuclide, atoms_per_g, mass_g_per_g, atoms, mass_g
tab2step and nuclide with activity, largest firststep, 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
tab3step and ingestion or inhalation dose responsestep, time_s, response, value, unit, covered_activity_Bq_per_g, missing_activity_Bq_per_g, activity_coverage_fraction, contributing_nuclides, missing_active_nuclides
tab4step and photon energy groupstep, time_s, group, low_eV, high_eV, centroid_eV, photons_s_g, power_W_g, photons_s, power_W
totalssteptotal 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
dominantstep, quantity and rankthe summary.dominant lists with percent, cumulative percent, and the counts to reach 90 % and 99 %
elementsstep and elementthe summary.elements table
timeseriesstepactivity_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
depletionstep and initial nuclidestep, 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
regulatorystep 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.