ECOSYS — Environmental transfer and dose assessment

ECOSYS calculates time-dependent radionuclide concentrations and potential human radiation doses following one or more dated deposition events. The Python implementation builds on ECOSYS-87 by Müller and Pröhl and subsequent extensions in ECOSYS for Excel. It represents seasonal agricultural practices, environmental transfer and age-dependent human exposure.

Scope

For each event, the inputs are a radionuclide identity, calendar date, time-integrated air concentration, wet ground deposition and rainfall depth. Atmospheric transport is prescribed through these local inputs. Regional parameter sets describe plant growth, harvest calendars, animal feed rations and human consumption.

The calculation follows activity through deposition, soil, plants, hay and feed, animal products, food processing and storage. Exposure includes ingestion, cloud and resuspension inhalation, and external irradiation from deposited activity. Cloud external exposure is available as an opt-in effective-dose pathway; skin contamination is evaluated separately as tissue dose.

Results include per-event and superposed concentrations, interval and cumulative per-capita dose in Sv, and collective dose in person-Sv. Doses refer to the specified environmental conditions and food-supply assumptions. Individual nuclides undergo radioactive decay; daughter ingrowth is not calculated.

The model reference specifies the equations, assumptions and numerical methods. The API guide describes the corresponding inputs and result records.

Installation

From a checkout of this repository:

python -m pip install .

Python 3.9 or newer is required. Installation supplies astropy, numpy and xlrd. Physical inputs and outputs carry Astropy units; the engine reads packaged SQLite parameter databases. The original Excel workbooks are needed only when rebuilding or importing parameter data.

Quick start

This example calculates one year of exposure from a Cs-137 event for a single-person adult cohort, using the default valley parameter set and event-anchored integration grid:

from datetime import date

import astropy.units as u
import numpy as np

from ecosys import EcosysEngine
from ecosys.domain.events import DepositionEvent
from ecosys.domain.populations import PopulationCohorts
from ecosys.domain.request import SimulationRequest

event = DepositionEvent(
    nuclide_id="cs_137",
    date=date(2001, 1, 1),
    integrated_air_activity=1 * u.Bq * u.s / u.m**3,
    wet_ground_deposition=1 * u.Bq / u.m**2,
    rainfall=1 * u.mm,
)
population = PopulationCohorts(
    initial_age=np.array([30]) * u.year,
    population=np.array([1]) * u.dimensionless_unscaled,
)
request = SimulationRequest.on_default_grid(
    (event,),
    population,
    output_start_date=date(2001, 1, 1),
    horizon_years=1,
)
result = EcosysEngine().run(request)
print(result.per_capita.cumulative[-1])  # final cumulative dose by cohort, in Sv
print(result.materials.concentration)   # time × material concentrations, in Bq/kg

integrated_air_activity is a time integral in Bq s/m³, not an instantaneous concentration in Bq/m³. Cohort ages are specified at output_start_date and advance with elapsed time. The integration grid is part of the numerical calculation: changing its nodes can change concentrations and doses.

Further examples cover scalar dose, multiple events, time support and reporting, population cohorts, raster inputs and chunked execution.

Parameter data

Three regional parameter sets are packaged, each with a SQLite database exported from its original workbook:

Set	Regional scenario	Workbook	Original-model comparison
valley (default)	Valley areas, normal vegetation	ch1_orig.xls	Three reference runs
mountain	Mountain areas, late vegetation	ch2_orig.xls	No reference runs
ticino_valais	Ticino and Valais, early vegetation	ch3_orig.xls	No reference runs

Select a set when creating the engine, or load its records for inspection:

from ecosys import EcosysEngine
from ecosys.data import load_model_data

engine = EcosysEngine(parameter_set="mountain")
model = load_model_data(parameter_set="mountain", verify=True)

Database loading is read-only. verify=True additionally checks database integrity, foreign keys, numeric value domains and the logical content digest. Simulation results retain dataset and input provenance in result.provenance.

To export the bundled workbooks to a separate directory, or import a custom workbook:

python -m export_excel_data --all --output-dir exported_parameters
python -m export_excel_data --source my.xls --output my.sqlite
python -m export_excel_data --validate my.sqlite

The custom-source example requires an existing workbook at my.xls. Registered-set exports read the bundled workbooks; --source reads exactly the given file. Each output database replaces its destination only after a successful export and validation. Publication with --all is per set.

Import diagnostics identify defaulted, inferred, skipped or omitted values. The bundled workbooks each have one diagnostic: turf (Rasen) is absent from the resuspension/soil-intake range, so these values default to zero. The parameter-set guide and parameter sources describe the data and their provenance.

Verification and validation

The test suite checks source-workbook values, database exports, units, analytic limits, numerical integration, event superposition and spatial execution. Independent calculations check selected integrated dose pathways.

Original-model comparisons use three preserved runs of the Excel-for-ECOSYS-87 1.4D workbook with the valley parameter set and Cs-137. The maintained food-chain regression tests compare grass, hay, milk, meat, root-vegetable and oat concentrations with checkpoint-specific tolerances. The mountain and Ticino/Valais sets have no corresponding reference runs.

These checks establish specified numerical behaviour and agreement within the tested scenarios. They do not constitute validation against environmental measurements or agreement for every radionuclide and regional setting. Validation evidence records the coverage and limits; the scientific decisions and development history explain model choices and differences from the original implementation.

Development and documentation

Install an editable checkout and run the maintained suites:

python -m pip install -e ".[dev]"
python -m pytest -q tests tests_export_excel_data

The user guide is built with MkDocs:

python -m pip install -e ".[docs]"
python -m mkdocs serve

Use python -m mkdocs build --strict to check the documentation build. The LaTeX model reference is maintained separately in docs/model-reference/.

ecosys/
├── domain/           # Input, time, population and result records
├── kernels/          # Numerical transfer and dose calculations
├── data/             # SQLite databases, loader and parameter compilation
├── legacy_workbook/  # Source workbooks and importer
└── engine.py         # Simulation orchestration
export_excel_data/   # Workbook-to-SQLite export and validation
tests/               # Engine, data, packaging and documentation tests
tests_export_excel_data/  # Import and export tests
docs/                # User guide and LaTeX model reference

The earlier workbook-driven implementation is preserved on the legacy branch. The current engine loads SQLite data; ecosys.legacy_workbook is used by the exporter.

References

• Müller, H. and Pröhl, G. (1993). ECOSYS-87: A Dynamic Model for Assessing Radiological Consequences of Nuclear Accidents. Health Physics 64(3), 232–252.
• Müller, H. (2000). Das Rechenmodell ECOSYS für Excel, chapter 3.
• Dose-coefficient sources and parameter provenance are recorded in the model reference and parameter-source guide.