Chunked Execution

Simulation results

EcosysEngine.iter_chunks evaluates a request in pieces along its leading batch dimensions. Raster cells are flattened in C order; time, cohort, plant, animal and pathway axes remain intact. Each yielded slice identifies the corresponding cells in the flattened input.

from datetime import date

import astropy.units as u
import numpy as np

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

event = DepositionEvent(
    nuclide_id="cs_137",
    date=date(2001, 1, 1),
    integrated_air_activity=np.ones((2, 3)) * 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.ones((2, 3, 1)) * u.dimensionless_unscaled,
)
request = SimulationRequest.on_default_grid(
    (event,), population, output_start_date=event.date, horizon_years=1,
)
for batch_slice, result in EcosysEngine().iter_chunks(request, chunk_size=2):
    final_dose = result.per_capita.cumulative[:, -1, :]
    print(batch_slice, final_dose)  # two cells × one cohort, in Sv
    # Write this chunk to the destination before requesting the next one.

The iterator does not assemble a full raster result. Consume or persist each chunk as it arrives to keep memory bounded. Coordinate metadata and GIS file output remain the caller's responsibility.

Quantity arrays

For a calculation on a quantity array, execute_in_chunks splits its first axis and concatenates the returned arrays while preserving units:

import astropy.units as u
import numpy as np

from ecosys.batching import execute_in_chunks

batch = np.ones((1000, 3)) * u.Bq / u.kg
chunked = execute_in_chunks(batch, lambda chunk: chunk * 2.0, 100)
assert chunked.shape == (1000, 3)
assert chunked.unit == u.Bq / u.kg

Unlike the engine iterator, this helper retains the complete concatenated output. The performance tests check that chunked engine results reproduce unchunked per-capita doses and material concentrations.