API reference

This page documents the public objects exported by openmc_feedbacks. The package does not create reactor geometry, materials, or nuclear data. Supply a prepared OpenMC model, depletion chain, cross-section configuration, power, and time schedule.

`run_depletion`

run_depletion(model, timesteps, power, chain_file, *, timestep_units='d', integrator='predictor', control=None, output_dir='.')

Run an OpenMC transport-coupled depletion calculation and return the integrator object after the calculation completes.

Parameters

model

Either an openmc.Model object or a path to a directory containing the OpenMC XML inputs. For a path, the function calls openmc.Model.from_xml(directory=...). Pass the directory, not a path to an individual XML file. Typical inputs include geometry.xml, materials.xml, and settings.xml.

timesteps

Sequence of positive step durations. Values are durations, not cumulative times. All values use timestep_units.

power

Reactor power in watts. A single value is applied to all steps by the selected OpenMC integrator.

chain_file

Path to an existing OpenMC depletion chain XML file. The chain must provide the decay and transmutation data needed by the depletable materials and reactions in the model.

timestep_units

Time unit for the values in timesteps. Defaults to "d" (days). Units supported by OpenMC include seconds, minutes, hours, and days.

integrator

Depletion time-integration method. Supported values are:

"predictor": first-order predictor method; default.
"cecm": constant extrapolation/constant midpoint method.
"epc-rk4": extended predictor-corrector Runge-Kutta method.

End-of-step feedback compensation (control.target_mode="end") is currently supported only with "predictor".

control

Optional FeedbackControl object. If omitted, the depletion calculation runs without soluble-species feedback.

output_dir

Directory for OpenMC depletion output and feedback history. Created if it does not already exist. Defaults to the current directory.

Model requirements

Every material marked depletable must have a positive volume. The model’s cross-section configuration must be available to OpenMC. chain_file must exist. The caller is responsible for choosing consistent units, materials, volumes, power, and nuclear data.

The function raises:

FileNotFoundError if the depletion chain path does not exist.
ValueError if a depletable material has no positive volume, the integrator name is unsupported, or end-of-step feedback is requested with an integrator other than predictor.
OpenMC exceptions for invalid models, missing data, transport failures, or depletion failures.

`FeedbackControl`

class FeedbackControl(material_name, nuclides, reference_concentration, minimum, maximum, target_keff, ...)

Configure bounded feedback that scales selected nuclide atom densities in one material to move transport k_eff toward a target. The material must exist in the model, and each requested nuclide or element must match one or more nuclides in that material.

Required parameters

material_name: Exact material name used to find the control material in the OpenMC model.
nuclides: Tuple of isotope names or element symbols. An isotope name such as "B10" selects that isotope. An element symbol such as "B" selects all isotopes of that element already in the material. Multiple isotope names and element symbols can be combined.
reference_concentration: Concentration represented by the selected nuclide densities currently defined in the input material. The density at a requested concentration is the reference density multiplied by requested_concentration / reference_concentration. Concentration units are user-defined but must be consistent across all concentration fields.
minimum and maximum: Lower and upper search bounds. The current implementation requires 0 <= minimum < maximum <= reference_concentration.
target_keff: Desired transport eigenvalue. Its interpretation depends on target_mode below.

Feedback and target parameters

target_mode="beginning": Default. Treat target_keff as the target at the start of each depletion step. The controller searches for the concentration at each operator evaluation.
target_mode="end": Treat target_keff as the desired end-of-step value. The beginning-of- step target is adjusted using a filtered estimate of the expected keff loss. This mode requires the predictor integrator.
expected_step_keff_loss=0.01: Initial estimate of the keff decrease over one timestep. Used only when target_mode="end". Calibrate this value for the reactor, power, and timestep schedule.
loss_filter_alpha=0.3: Weight applied to each newly measured step loss in the exponential filter. Must be between zero and one. A higher value follows new measurements faster; a lower value smooths them more strongly.
minimum_step_keff_loss=-0.01 and maximum_step_keff_loss=0.02: Bounds applied to a measured step loss before it updates the filtered estimate. Used only in end-target mode.

Search parameters

search_particles=None: Particle count for concentration trial solves at refinement level zero. None uses the particle count in the OpenMC model. Refinement levels multiply the current base particle count by refinement_factor.
search_batches=None: Batch count for trial solves at refinement level zero. None uses the model’s batch count. Refinement levels multiply the base batch count by refinement_factor.
search_inactive=None: Inactive batches for search solves. None uses the model setting. The number of inactive batches is not multiplied during refinement.
tolerance=0.001: Concentration interval width at which the bounded search may stop, in the same user-defined units as minimum and maximum.
keff_tolerance=0.0005: Maximum absolute keff error. A target is reported as met only when abs(keff - target_keff) + confidence_z * keff_std_dev is no greater than this tolerance.
max_iterations=12: Maximum number of secant/bisection search iterations per operator call.
max_search_refinements=2: Maximum number of higher-statistics reruns for a candidate whose nominal keff is near the target but whose reported uncertainty is too large.
refinement_factor=2.0: Multiplier applied to trial particle and batch counts at each refinement level. Must be greater than one.
confidence_z=2.0: Number of reported standard deviations included in the conservative keff acceptance criterion. For example, 2.0 uses an approximately two- standard-deviation margin when the estimate is approximately normal.
warm_start_width=100.0: Half-width of the initial concentration interval around the previous selected concentration, in the configured concentration units. The first search uses the full configured interval.
warm_start_expansion=2.0: Factor by which the local interval half-width grows when it does not bracket the target. Expansion continues up to the full configured range.
use_secant=True: Use a secant estimate when it lies safely inside the current bracket. Set to False to use midpoint bisection for every iteration.
history_file="feedback_history.csv": CSV filename for feedback diagnostics. Relative paths are placed under output_dir; absolute paths are used as supplied.

Search behavior and outputs

On the first feedback call, the full concentration interval is evaluated. Later calls start near the previous selected concentration and expand the bracket if necessary. Within a bracket, the search uses safeguarded secant proposals with bisection fallback. If the target is outside the configured range, the closer endpoint is used.

The selected concentration is evaluated again using the model’s original particle, batch, and inactive settings. Only this final transport result is passed to the depletion integrator. Trial concentrations do not run trial depletion calculations.

The history CSV contains one row for every endpoint, search, refinement, loss-measurement, and final selected transport evaluation. Columns include step and trial numbers, phase, concentration, keff estimate and reported standard deviation, target, current bracket, search level and statistics, selection flag, absolute keff error, status, and stopping reason. target_met means the final selected result met the uncertainty-aware keff criterion; target_unmet means it did not. Bound, concentration-width, iteration, and uncertainty limits are distinguished in stopping_reason.

The controller assumes the keff response is monotonic over the configured concentration range. Monte Carlo uncertainties describe sampling variation; they do not include nuclear-data uncertainty or model bias.