Long term scenarios

This submodule contains infrastructure to compute steady-state long-term dose given constant yearly activity emission.

Optional Photon Comparison

Using PKI

Pass pki_nuclides to add photon point-kernel comparison doses at the existing chimney-group observers. Long-term observers are already supplied by the exposed-group coordinates, so no hotspot-radius arguments are required. For direct evaluation at any 3-D coordinates, see the arbitrary-coordinate example.

The long-term PKI path is an advanced, photon-only, non-regulatory comparison and is disabled unless pki_nuclides is supplied. ENSI-G14 remains the reference model and default totals exclude PKI records.

from ensi_g14_calculator.dose import PointKernelConfig

evaluator.run(
    chimneys,
    exposed_groups,
    weather_3_parameter,
    weather_4_parameter,
    emissions,
    summer_total_precipitation=0.3 * m,
    pki_nuclides=["Cs-137"],
    pki_config=PointKernelConfig(
        radial_order=12,
        polar_order=12,
        azimuthal_order=16,
    ),
)

The packaged spectrum includes Cs-137 at 0.6617 MeV with yield 0.8510, as well as the additional photon lines listed in the packaged resource. The PKI coefficient is evaluated at each chimney-group observer, whose height defaults to local terrain, before worker transport context is discarded. Results are stored as model="pki_photon" and is_reference=False; use the database query option for explicit comparison.

The input Q is integrated released activity in Bq and the output is integrated Sv. Parent transport decay and shielding are included. Daughter ingrowth and kSPE are omitted. The model uses packaged attenuation, buildup, and ISO fluence-to-effective-dose data, masks plume values below terrain, does not block terrain-intersecting photon rays, evaluates plume values directly at quadrature points, and truncates the integration at the configured mean free path limit.

`ensi_g14_calculator.long_term_scenarios`

Classes

Modules

`runner`

This file implements a high level class for running long term estimates. It handles the calculation of nested loops of dose calculation:

for each chimney in a site emitting activity
for each geographically situated exposed group (position)
for each nuclide in the emitted vector
for each exposed age group

and inserts the result in an sqlite3 database, which can be visualised with the dashboards in the ensi_g14_dashboard directory.

You can find examples in the main documentation.

Classes

`LongTermEvaluator`

Functions

__init__(db_path, topography_asc, buildings=None, near_field=None)

Class handling the evaluation of long term dose given weather statistics, yearly release of activity by nuclide, characteristics and position of chimneys, position of exposed groups.

Parameters:

Name	Type	Description	Default
`db_path`	`str`	string, path, where do we place the database that will contain our results?	required
`topography_asc`	`str \| None`	string, path, where do we read the topography from? if None or empty string, uses a flat orography instead.	required
`buildings`		optional sequence of orography.BuildingFootprint (centres given by latitude/longitude), added on top of the terrain for every chimney (outside G-14).	`None`
`near_field`	`NearFieldConfig \| dict[str, NearFieldConfig] \| None`	optional near_field.NearFieldConfig, building-wake dispersion for short stacks (outside G-14, see prototyping/near_field_dispersion.tex): one config for every chimney, or a dict {chimney name: config} (chimneys not in the dict use plain G-14). None: plain G-14.	`None`

run(chimneys_data, groups_data, weather_data_3_params, weather_data_4_params, emission_data, summer_total_precipitation=None, pki_nuclides=None, pki_config=None)

Method for running a dose assessment over a set of chimneys, receptor groups, and nuclide emissions. Assumes steady-state, 100-year horizon (long term G14)

Loads and validates all required input data, then computes dispersion and dose contributions for each chimney-group pair across all provided weather scenarios and nuclides. Stores the result in the database at the path you provided when instantiating this object.

You can request point-kernel-integral submersion dose evaluations for some nuclides with the pki_nuclides argument. Beware that this is more expensive.

Parameters:

Name	Type	Description	Default
`chimneys_data`	`DataFrame \| str`	DataFrame or path to CSV file with chimney geometrical and positional data. Required columns: 'name', 'D_i', 'D_e', 'W', 'h', 'h_building', 'lat', 'long'.	required
`groups_data`	`DataFrame \| str`	DataFrame or path to CSV file with receptor group locations. Required columns: 'name', 'lat', 'long'. Optional: 'height', observer height above local ground in m (outside G-14) for inhalation and submersion; deposition and ingestion stay at ground level. Not supported with the PKI surrogate.	required
`weather_data_3_params`	`DataFrame \| str`	DataFrame or path to CSV file with 3-parameter weather statistics (no rainfall). Required columns: 'weather_category', 'wind_speed', 'wind_direction', 'probability'.	required
`weather_data_4_params`	`DataFrame \| str`	DataFrame or path to CSV file with 4-parameter weather statistics (with rainfall). Required columns: 'weather_category', 'rainfall_intensity', 'wind_speed', 'wind_direction', 'probability'.	required
`emission_data`	`DataFrame \| str`	DataFrame or path to file with nuclide emission rates per chimney. Required columns: 'nuclide' (used as index); remaining columns correspond to chimney names and must match entries in `chimneys_data`.	required
`summer_total_precipitation`	`None \| Quantity`	scalar, astropy unit (length), optional. Total summer precipitation, relevant only for tritium dose calculations. Defaults to None.	`None`
`pki_nuclides`		optional iterable of nuclides for photon point-kernel comparison doses. For near-field chimneys it must contain every nuclide they emit: their submersion dose is the exact PKI, as the G-14 submersion (chi_K,S) is not defined below 200 m.	`None`
`pki_config`		optional PointKernelConfig or mapping of its settings.	`None`

Returns:

Type	Description
	None

plot_dispersion(chimney_name, resolution=101, distance_unit='m', savepath=None)

Generates a 4-panel diagnostic plot: dispersion (real and submersion), topography, centred on a chimney, plus the wind rose.

Parameters:

Name	Type	Description	Default
`chimney_name`	`str`	string, the name of the chimney of interest (as given in the input data)	required
`resolution`	`int`	int, dimension of the grid (default 101: 101 x 101 grid).	`101`
`distance_unit`	`str`	string, default 'm', the distance unit to use in the plot.	`'m'`
`savepath`	`str`	path were to save the plot if given, default None	`None`

Returns:

Type	Description
	None

plot_deposition(chimney_name, nuclide, resolution=101, distance_unit='m')

Generates a 4-panel diagnostic plot for deposition factors: Washout (W), Fallout (F), Total Deposition Factor (xi), and topography.

Parameters:

Name	Type	Description	Default
`chimney_name`	`str`	string, name of the chimney	required
`nuclide`	`str`	string, e.g., 'I-131' or 'Cs-137'	required
`resolution`	`int`	int, grid dimension	`101`
`distance_unit`	`str`	string, units for axes	`'m'`

Functions

Extensions recorded in the database

Every dose row has an extensions column listing the deviations from ENSI-G14 in effect when it was computed, as sorted comma-separated tags: decay_in_plume, near_field, building_footprints, observer_height. An empty string means strict G-14; NULL marks rows written by older versions, which did not record it. A tag says the setting was on for that chimney and group, not that every pathway changed (observer heights do not affect deposition, for example). The parameters themselves are in the chimneys table (wind measurement height, decay in the plume, number of building footprints, near-field building and options) and in exposed_groups.observer_height_m. For example, strict G-14 doses only:

SELECT * FROM doses WHERE is_reference = 1 AND extensions = '';