Skip to content

API reference

All public classes and functions are accessible from the top-level rad_point_kernel module.

import rad_point_kernel as rpk

Source

Source(particle, energy)

Defines a radiation source by particle type and energy.

  • particle - "neutron" or "photon".
  • energy - energy in eV as a single float, or a list of (energy_eV, weight) tuples for multi-line spectra.

Examples:

# Monoenergetic Cs-137 photon source
source = rpk.Source(particle="photon", energy=662e3)

# Co-60 two-line photon source
source = rpk.Source(particle="photon", energy=[(1173e3, 1.0), (1333e3, 1.0)])

# D-T fusion neutron source
source = rpk.Source(particle="neutron", energy=14.1e6)

Materials

Material(composition, density, fraction="mass")

A material defined by composition and density.

  • composition - dict of component names to fractions. Keys can be element symbols ("Fe"), chemical formulas ("H2O"), or nuclide names ("Li6").
  • density - density in g/cm3.
  • fraction - "mass" (default) or "atom".

Properties: density, composition, fraction.

Methods:

  • nuclide_mass_fractions() - returns a dict of resolved nuclide-level mass fractions.

Material.volume_mix(mat_a, frac_a, mat_b, frac_b)

Static method. Mix two materials by volume fraction. Returns a new Material with volume-weighted density and composition.

Geometry

Layer(thickness, material=None)

A spherical shell layer with thickness in cm and optional material.

  • thickness - layer thickness in cm.
  • material - a Material, or omit for void (empty space).

Properties: thickness, has_material, material.

Calculation functions

All calculation functions take a Source object that specifies the particle type and energy. They return a result normalised per source particle. Apply an absolute strength via result.scale(strength=...) to land in the unit you want: a strength in particles/sec gives Sv/s and particles/cm^2/s; in particles/hr gives Sv/hr; in particles/shot gives Sv/shot. Re-scaling is a numeric post-process - it never re-runs the simulation.

Transmission fraction

calculate_transmission(layers, source)

Returns a float in [0, 1]: the pure material attenuation exp(-Sum(Sigma_r * t)) without geometric spreading.

  • layers - list of Layer objects.
  • source - a Source object.

Uncollided flux

calculate_flux(layers, source, buildup=None)

Returns a CalcResult with flux per source particle. Computes 1 / (4piR^2) * exp(-Sigma*t) * B.

  • layers - list of Layer objects.
  • source - a Source object.
  • buildup - optional BuildupModel, BuildupResult, or InterpolationResult.

Dose rate

calculate_dose(layers, source, geometry, buildup=None)

Returns a CalcResult with dose per source particle (Sv/particle). Multiplies the per-particle uncollided flux by the ICRP-116 fluence-to-dose conversion coefficient.

  • layers - list of Layer objects.
  • source - a Source object.
  • geometry - one of "AP", "PA", "RLAT", "LLAT", "ROT", "ISO".
  • buildup - optional BuildupModel, BuildupResult, or InterpolationResult.

Secondary photon dose rate

calculate_secondary_photon_dose(layers, source, geometry, neutron_buildup=None)

Returns a SecondaryGammaResult with dose per source particle. Analytical estimate of the secondary photon dose from neutron capture gammas in each material, plus the neutron dose. For more accurate results, prefer a coupled neutron-photon compute_buildup run.

  • layers - list of Layer objects.
  • source - a monoenergetic neutron Source object.
  • geometry - one of "AP", "PA", "RLAT", "LLAT", "ROT", "ISO".
  • neutron_buildup - optional build-up applied to the neutron component.

Result types

CalcResult

Returned by flux and dose calculations. Numeric fields are normalised per source particle; multiply through with .scale(strength=...) to apply an absolute source strength.

Properties:

  • flux - flux at the outer surface (per source particle until scaled).
  • dose - effective dose (Sv per source particle until scaled). Present for dose calculations only.
  • transmission_fraction - exp(-Sigma*t).
  • optical_thickness - Sum(Sigma_r,i * t_i).
  • buildup_factor - applied build-up factor (1.0 if none).
  • total_distance_cm - total distance from source to detector (cm).
  • source_strength - strength baked into flux and dose (1.0 = unscaled).

Methods:

  • scale(strength) - returns a new CalcResult with flux and dose multiplied to reflect the given absolute strength. Re-scaling replaces the previous strength rather than compounding. Strength must be > 0.

SecondaryGammaResult

Returned by calculate_secondary_photon_dose. Dose fields are per source particle until scaled.

Properties:

  • neutron_dose - neutron dose (per source particle until scaled).
  • secondary_photon_dose - secondary photon dose (per source particle until scaled).
  • total_dose - sum of neutron + secondary photon dose.
  • source_strength - strength baked into the dose fields (1.0 = unscaled).

Methods:

  • scale(strength) - returns a new result with the dose fields multiplied. Same semantics as CalcResult.scale.

Build-up

BuildupModel

Analytical build-up factor models. Created via static methods:

  • BuildupModel.none() - no correction (B = 1).
  • BuildupModel.constant(value) - fixed scalar B.
  • BuildupModel.linear(a) - B = 1 + a * mu_t.
  • BuildupModel.polynomial(coeffs) - B = 1 + a1(mu_t) + a2(mu_t)^2 + ...
  • BuildupModel.taylor(a, alpha1, alpha2) - B = Aexp(-alpha1mu_t) + (1-A)exp(-alpha2mu_t).

BuildupResult

Result of a single Monte Carlo build-up computation from compute_buildup. The mc, mc_std_dev, and pk values are stored per source particle until scaled.

Attributes (dicts keyed by quantity string):

  • mc - Monte Carlo tally value (per source particle until scaled).
  • mc_std_dev - Monte Carlo standard deviation.
  • pk - point-kernel reference value.
  • buildup - build-up factor (mc / pk; dimensionless ratio, never affected by scaling).
  • optical_thickness - total optical thickness (float).
  • source_strength - strength baked into mc, mc_std_dev, pk (1.0 = unscaled).

Can be passed directly to any calculation function as the buildup argument.

Methods:

  • scale(strength) - returns a new BuildupResult with mc, mc_std_dev, and pk multiplied to reflect the given absolute strength. Re-scaling replaces the previous strength.
  • to_dict() / from_dict(d) - serialize to/from plain dict (the source_strength round-trips).
  • BuildupResult.save(results, path) - save a list of results to JSON.
  • BuildupResult.load(path) - load a list of results from JSON.

BuildupFit(points, results)

Analytical-form fit of build-up factor across a set of MC points. 1D inputs are fit with a Shin-Ishii / Taylor double-exponential (B(μt) = A·exp(-α₁·μt) + (1-A)·exp(-α₂·μt), B(0)=1 by construction); multi-D inputs use a thin-plate-spline RBF with degree-1 polynomial augmentation.

  • points - list of dicts defining parameter values (e.g. [{"thickness": 5}, {"thickness": 10}]).
  • results - list of BuildupResult, one per point.

Properties: axis_names, available_quantities, axis_ranges.

Methods:

  • interpolate(quantity=None, warn=True, **kwargs) - returns an InterpolationResult at the given parameter values. If the fit has more than one available quantity (e.g. both dose-AP-neutron and dose-AP-total), quantity= is required to disambiguate; otherwise it defaults to the only one.

InterpolationResult

Result of a BuildupFit.interpolate() query.

Attributes:

  • value - predicted build-up factor.
  • sigma - predictive uncertainty. Not exposed for BuildupFit (always NaN); see roadmap.
  • is_extrapolated - True if the query is outside the range of Monte Carlo data.
  • extrapolated_axes - dict of {axis: (value, min, max)} for extrapolated axes.

Can be passed directly to any calculation function as the buildup argument.

compute_buildup(geometries, source, quantities, ...)

Run OpenMC Monte Carlo simulations and compute build-up factors. Requires OpenMC; see Installation.

Parameters:

  • geometries - list of layer lists, each defining a shield geometry.
  • source - a Source object specifying the particle type and energy.
  • quantities - required. List of quantity strings. The particle is part of the name (e.g. ["flux-neutron", "dose-AP-neutron"] for a neutron source, or ["flux-photon", "dose-AP-photon"] for a photon source). "dose-{geo}-coupled-photon" is the secondary-photon dose from a neutron source. "dose-{geo}-total" is accepted as a shorthand for ["dose-{geo}-neutron", "dose-{geo}-coupled-photon"] (requires a neutron source); the result still carries all three keys so the components are recoverable. When both halves are present, a synthetic "dose-{geo}-total" is added to each result with MC value equal to the neutron + secondary-photon dose; its buildup factor uses the neutron PK as reference. Geometries: AP, PA, RLAT, LLAT, ROT, ISO.
  • particles_per_batch - particles per batch (default 10,000).
  • max_batches - maximum batches (default 100).
  • trigger_rel_err - target relative error (default 0.05).
  • cross_sections - path to cross_sections.xml or directory (default: uses OPENMC_CROSS_SECTIONS env var).

Returns: list of BuildupResult, one per geometry. MC and PK values are stored per source particle. Apply absolute scaling with result.scale(strength=...) to land in your chosen unit.