Scientific Decisions
This register records approved decisions and unresolved scientific choices for the engine. An entry is decided only where an explicit approval is recorded; unresolved choices remain open until evidence is reviewed and the maintainer approves a specific option.
SD-01: Integrated Air Activity And Cloud Coefficients
Status: decided
Question: What physical quantity does integrated air activity represent, and what is the dimensional basis of cloud external dose coefficients?
Evidence: The canonical input documentation describes integrated air
activity as activity multiplied by time per volume. The legacy public field is
labelled Bq h/m3, but the legacy calculation multiplies its numeric value by
the number of seconds in a day. For the TestCs137 scenario this is consistent
with a constant concentration of 300 Bq/m3 during one day, giving
300 Bq/m3 * 1 day = 25,920,000 Bq s/m3. An actual physical input of
300 Bq h/m3 would instead be 1,080,000 Bq s/m3. The cloud external
coefficient has an unresolved legacy air-activity basis.
Options: Define integrated air activity as a physical Bq s/m3 quantity
and convert Bq s/m3, Bq h/m3, and equivalent units dimensionally; defer
cloud external dose until its coefficient basis is resolved; retain a legacy
coefficient only outside clean production computation.
Decision: Approved: represent integrated air activity as a physical
Bq s/m3 quantity. Accept equivalent inputs such as Bq h/m3 through
Astropy dimensional conversion, and never apply the legacy 86400 multiplier.
Cloud external and skin pathways remain deferred pending their separate
scientific decisions (see the later SD-11 worksheet-unit update for skin).
Rationale: The old numeric multiplier encodes an implicit one-day exposure
scenario, not conversion of an actual Bq h/m3 quantity. The clean boundary
must make both concentration and duration explicit when reproducing that
scenario; a supplied integrated quantity retains its true Astropy units.
Test consequences: Dry deposition must produce activity per area from
the dimensional source and velocity, wet deposition remains activity per
area, and cloud inhalation must combine the source with inhalation volume per
time without an implicit multiplier. Cloud external dose and skin deposition
remain unavailable until their pathway decisions are approved. Add
unit-equivalence tests for Bq s/m3, Bq h/m3, and
other compatible representations.
Later source-unit revision (2026-09-28): The nuclide sheets explicitly
label cloud-submersion factors Sv/s pro Bq/m³. The independently unit-labelled
Cs-137 annual-rate coefficient is consistent within about 5% when converted
to seconds; the difference between historic coefficient sets does not change
the unit. The cloud coefficient is resolved as Sv s-1 per Bq m-3 and used
with physical integrated air activity and short-term cloud shielding. The
legacy 86400 multiplier is not part of the clean computation. Cloud external
dose can be requested explicitly without changing existing default pathways.
The preserved VM report-table exports (tests/artifacts_ecosys_for_excel/run1.XLS–run3.XLS) confirm
all 66 cloud-submersion checkpoint values across default and refined supports
within 3e-8 relative error using the artifact's physical integrated-air input.
SD-02: Canonical Year Definition
Status: decided
Question: Which year definition applies to physical decay, biological half-lives, and age progression?
Evidence: Canonical half-lives are stored in years, and the conventions
document records an Astropy year conversion. The legacy implementation uses
365 day for the radioactive-decay compatibility constant, while
timegrid.py also uses Astropy's year length and Gregorian anniversary
helpers. These are different physical-duration and calendar behaviors.
Options: Use Astropy year conversion for physical and biological durations; use a fixed-day scientific year; define separate approved rules for physical durations, biological durations, and calendar anniversaries.
Decision: Approved: use Astropy's year conversion for physical and biological durations, including radioactive decay, soil rates, retention, and other half-life calculations.
Rationale: Canonical half-lives are stored in years and Astropy provides a single explicit conversion. This replaces the legacy fixed-365-day decay compatibility constant for engine physical calculations.
Test consequences: The selected rule controls half-life equivalence, radioactive decay, soil rates, retention, and age progression. Tests must also prove that calendar anniversary calculations are not silently used as physical decay durations.
SD-03: Seasonal Calendar And Leap Days
Status: decided
Question: How do recurring seasonal schedules map to Gregorian dates, especially on February 29 and in leap years?
Evidence: Canonical day-of-year coordinates are explicit, while the architecture plan requires actual dates and a documented leap-day policy.
Options: Use month/day recurrence; use canonical non-leap day coordinates with an explicit leap-day rule; use a day-of-year policy with a defined post-February-29 shift.
Decision: Approved: calculate event-to-output elapsed durations from actual Gregorian dates, so leap days are counted normally. For canonical 365-coordinate seasonal curves, use the March 1 seasonal value on February 29 and retain normal month/day mapping for other dates.
Rationale: Elapsed time and seasonal lookup are separate concepts. Actual dates provide correct event-to-date durations, while the explicit March 1 mapping resolves the missing leap-day coordinate without shifting all later month/day values.
Test consequences: Add elapsed-date tests across leap years and schedule boundary tests for ordinary years, leap years, February 28, February 29, and March 1. February 29 must equal the March 1 seasonal value.
SD-04: Soil Enrichment In Resuspension
Status: decided
Question: Does the canonical soil enrichment factor apply to every resuspension pathway, and where does it enter the equation?
Evidence: The parameter inventory identifies enrichment as an element
factor. ecosys/soil.py requires a positive enrichment factor and computes
total_ground_deposition * KR * enrichment_factor, producing air
concentration. The production resuspension inhalation path in
ecosys/dose.py computes total_ground_dep * KR and omits enrichment.
Options: Apply enrichment to all resuspension pathways using
C_air = ground_deposition * KR * enrichment; apply it only to the
scientifically supported resuspension pathway; omit it from resuspension and
retain it only in approved soil-to-plant terms.
Decision: Approved: apply the element enrichment factor to resuspension
air concentration and downstream resuspension inhalation. Use
C_air = total_ground_deposition * KR(t) * enrichment_factor.
Rationale: The canonical enrichment factor is an element-specific soil property, and the approved equation matches the explicit standalone physical helper. The engine will correct the production-path omission rather than preserve it as compatibility behavior.
Test consequences: The selected placement controls independent resuspension unit, asymptotic-limit, zero-source, and linearity tests. The clean implementation must not silently reproduce the disagreement.
Later manual evidence: ECOSYS/Manual/KAP3.DOC, §3.2 distinguishes
enrichment of resuspended soil adhering to plants from unenriched soil eaten
by grazing animals. This supports the separate plant-enrichment term in the
Excel-model formulation; it does not establish the derivation of the paper's
effective 0.001 coefficient. See the Excel-manual evidence in the development history (§3).
SD-05: Animal Product Transfer-Factor Units
Status: decided
Question: What is the dimensional meaning of an animal product transfer factor and how does it relate to constant daily intake?
Evidence: The canonical inventory describes the factor as an effective concentration per daily intake, while the data table stores a dimensionless factor. The legacy animal recurrence is identified as requiring review.
Options: Treat the factor as a dimensioned intake-to-product coefficient; treat it as a dimensionless equilibrium ratio with an explicit intake term; define separate units for each product class if required by evidence.
Decision: Approved: treat each stored numeric transfer factor as a contextual
coefficient with effective day/kg meaning, converting the animal biological
activity-intake state to fresh-product concentration in Bq/kg. The canonical
numeric representation remains unchanged, but the clean equation must expose
the contextual unit rather than treating the factor as dimensionless.
Rationale: The stored representation does not by itself settle the physical equation.
Test consequences: Add dimensional constant-intake and impulse-response tests for milk, meat, and eggs.
SD-06: Grass Contamination Components
Status: decided; monthly growth integration retained, finite Excel-manual foliar horizon reinstated after manual review (2026-09-27).
Question: What physical processes do the two pasture-grass terms represent, and are their fractions independent?
Evidence: ECOSYS-87 Eq. (9) gives
C_g,l(t) = A_g/Y_g * [(1-a)*exp(-(lambda_b+lambda_w+lambda_r)*t) + a*exp(-(lambda_t+lambda_r)*t)].
The paper defines a as the fraction translocated to the root zone, lambda_b
as growth dilution, lambda_w as weathering, lambda_r as radioactive decay,
and lambda_t as the effective decrease rate for the root-zone
translocation/remobilization term. Its text gives a long-term fraction a=0.05
and a 60-day half-life; the uncertainty table independently labels these
parameters as root-zone translocation fraction and half-life. The canonical
records with a=0.05 use that same 60-day half-life.
All 13 canonical ElementGrassParameter records have component fractions
within [0, 1] summing to one; the three canonical grass PlantData fallback
records do as well. Their component-2 fractions are the independent a values
(Cs, I, Mn, Mo, Te, and Zn use 0.05; Ba, Ce, Nb, Pu, Ru, Sr, and Zr use 0).
The stored component-1 fractions equal 1-a.
Options: Treat both stored fractions as independent weights; derive the main foliar weight as the complement of the root-zone translocation fraction; replace the published two-term expression with a new compartment model.
Decision: Use a = component2_fraction and 1-a for the main foliar
component. Validate the stored component-1 value as a consistency field, then
derive the compiled component-1 weight from 1-a; do not treat it as an
independent scientific parameter. In the no-weathering/growth/physical-loss
limit at t=0, the two terms sum to A_g/Y_g; setting a=0 isolates the main
foliar term and a=1 isolates the root-zone translocation/remobilization
term. At later times the slower effective exponent dominates while both terms
are active.
Rationale: Eq. (9), its definitions, the uncertainty table, and the complementary canonical data establish the split. Both terms begin with activity initially deposited on grass; “direct component” would incorrectly imply a separate source.
Paper-alignment revision: Eq. (9) itself contains no 730-day cutoff. For
monthly time-dependent growth rates, use
exp(-integral(lambda_b(s), s=0..t)), integrating actual Gregorian month
overlaps, rather than applying the output month's rate to all elapsed time.
This prevents activity from reappearing at a transition to a dormant month.
The packaged monthly parameter values remain the workbook calibration; they
are not replaced by Table 6 defaults in this revision.
Excel-manual revision: §3.2 of ECOSYS/Manual/KAP3.DOC explicitly states
that direct atmospheric grass contamination is dropped after a configured
period. The legacy solver uses the 730-day horizon; retain this finite horizon
for both grass foliar components, while preserving the exact accumulated
monthly growth-loss calculation within that horizon. This is a declared
later-model extension, not a term in the 1993 Eq. (9).
Test consequences: Verify canonical complementarity and rejection of
inconsistent fractions; check the t=0, a=0, and a=1 limits and the
long-time dominant term while within the active horizon.
SD-07: Root-Uptake Ramp And Long-Term Plant Behavior
Status: decided
Question: What root-uptake ramp applies after deposition, and what is the plant behavior beyond the parameterized seasonal horizon?
Evidence: The architecture plan identifies a 50-day legacy ramp and long-term behavior as decisions. Soil-to-plant transfer and plant growth curves are present in canonical data.
Options: Retain the observed ramp and define a repeating seasonal model; derive a continuous uptake transition; explicitly end or defer the model outside the supported horizon.
Decision: Approved: use the documented 50-day linear root-uptake ramp except for leafy vegetables as revised below, end non-grass direct-leaf contribution after 730 elapsed days, and continue explicit soil/root and physical-decay behavior beyond the parameterized seasonal horizon without report-grid state.
Rationale: This preserves the approved modeled transition while making the cutoff and post-horizon behavior explicit, vectorizable, and independent of legacy report points.
Paper-alignment history (2026-09-27): The first revision removed the grass cutoff and used additive leafy contributions. Subsequent examination of the later Excel manual changes the selected model version: grass now follows the documented finite horizon (SD-06), and leafy vegetables follow the type-3 crop-replacement convention (SD-08). For leafy vegetables, the root contribution is not first multiplied by the separate 50-day ramp. Other plant categories retain the legacy-derived 50-day rule pending review.
Test consequences: Add ramp boundary, seasonal recurrence, horizon, and long-term asymptotic tests.
SD-08: Harvest Carry-Forward And Translocation Horizon
Status: decided
Question: How is harvested concentration carried between seasons, and what coordinate range and out-of-range behavior apply to translocation data?
Evidence: The canonical translocation table uses element, plant, and day offset dimensions. The architecture plan identifies harvest carry-forward and translocation horizon as unresolved.
Options: Reset harvested state at each season; carry a defined residual state; use only the canonical translocation range; extrapolate or clamp after the range; mark out-of-range requests unavailable.
Decision: Approved: carry residual contamination state between seasons. Harvest removes harvested biomass, but does not erase contamination remaining in soil, roots, stubble, or other explicitly modeled state variables. Use the canonical translocation coordinate as elapsed days from its approved reference, interpolate within the canonical range, and return zero outside the supported 0..200-day range.
Rationale: Harvest is a biomass removal operation, not an instantaneous reset of environmental or residual plant state. The finite canonical translocation table must not be extrapolated without evidence.
Test consequences: Add harvest-boundary, interpolation, out-of-range, and multi-season state tests.
Paper-alignment history (2026-09-27): The first revision anchored both leafy and silage/beet-leaf concentrations at the harvest endpoint. The later Excel manual §3.2 supplies plant-type-specific rules instead: type 2 (silage maize/beet leaves) and type 4 products are stored at the end-of-window concentration, type 5 products at the harvest-window mean; storage loses only radioactive activity. Type 3 leafy vegetables are also harvested in winter, not stored as one annual October crop. Accordingly, retain type-2 endpoint anchors but evaluate type-3 winter produce from the time-dependent fresh-soil term. The type-3 first-season crop-replacement blend, initially implemented in legacy VBA, fades foliage while new root-fed crops take over during the configured growth interval; this specific interpolation is supported by workbook/VBA behavior rather than a published equation in the manual. Canonical type IDs are read from the workbook, so the scenario's fruiting vegetables (type 4) and orchard fruit (type 5) override the manual's generic species examples. See the Excel-manual evidence in the development history (§3).
Coordinate/eligibility correction (2026-09-27): The workbook's growth and harvest fields are one-based seasonal days, unlike the zero-based LAI and biomass curves. Evaluate harvest windows and hay preparation on their one-based dates; keep physical elapsed time Gregorian. ECOSYS's type-4/5 branches only translocate activity deposited on foliage after growth begins; overwintered cereals remain eligible when growth starts in the previous year. This correction eliminates the TestCs137 oats one-day translocation cliff and the pre-growth root-vegetable food spike (see §4.1 of the development history).
In-season harvest follow-up: The independent tests/artifacts_ecosys_for_excel/run3.XLS
time series exposed an event inside the oat harvest window (14 August).
The first harvest is already active at deposition, not the next year's
harvest start. Stored first-season activity ends at the actual start of the
next harvest season; the previous modulo-365 rule incorrectly zeroed oat
activity on days 0--1 and kept old stock through the following harvest.
This is a boundary correction, not a new plant parameter.
Open implementation gap from the same VM series: The first season's stored stock is anchored, but the clean type-4 crop does not yet carry its second harvested stock to the third harvest. VM raw oats on day 715 equal the day-365 harvest concentration propagated by physical decay alone; the clean result follows continuously changing root-zone soil instead. Both rejoin at the next harvest. See §4.2 of the development history.
Implementation revision (VM phase A): The preceding first-season-only gap is superseded. Types 2/4 establish end-of-harvest stocks and type 5 an arithmetic mean of daily fresh concentrations from the event (or harvest start, whichever is later) through harvest end. As in the VBA sample mean, these samples retain their own radioactive survival; the resulting mean is assigned to harvest end without decaying samples a second time. Subsequent storage loses only physical activity, up to the next Gregorian harvest start. Pre-event harvests provide zero stock; fresh type-3 winter produce is separate. This deterministic daily averaging avoids report-grid-dependent harvest means. The manual describes a long-term annual-mean transition and the recovered VBA stops resolving harvest periods after its second post-event season. The clean engine currently retains explicit seasonal stocks over the full requested horizon; long-term annualization remains an independently measurable model discrepancy, not a choice made by support-node spacing. On run 3, oat day 715 changes from ~3.153351 to 3.416711 Bq/kg (VM 3.417392); day 720 is 3.148736 (VM 3.148639). The ~0.02% stock difference is not a feed factor.
SD-09: Hay Drying And Preparation Averaging
Status: decided
Question: Which averaging interval, weighting, drying factor, storage timing, and mass basis define hay concentration?
Evidence: ECOSYS-87 describes hay/silage concentration as a weighted mean of grass harvested from 15 May through 15 September: the mean from the first half of the preparation period receives weight 0.70 and the second-half mean receives weight 0.30. Canonical scenario data supplies the preparation start, first-half split, end, and drying factor. Its legacy first-interval multiplier is 2.0, which represents a 2:1 weight (about 67/33 for equal-duration halves), not the paper's 70/30.
Options: Use the paper's fixed 70/30 split weights; use the legacy scenario's first-interval multiplier; derive another interval-weighted transformation from grass.
Decision: Use the canonical preparation start, split, and end dates.
The original paper-alignment decision used 0.70*first_mean+0.30*second_mean.
After review of the Excel manual §3.2, the selected Excel-model calculation
uses the configured first-to-second production multiplier w, with
(w*first_mean+second_mean)/(w+1). The packaged w=2 therefore means
2/3 and 1/3, not 70/30. Apply the canonical drying factor of 5, store hay
after preparation, and report on the dry-mass basis. The reusable kernel
retains paper 70/30 as its explicit default when no multiplier is provided;
the engine supplies the scenario value.
Rationale: The manual explicitly explains the 2:1 production-share parameter and describes hay drying by water loss. This is a documented Excel-model agricultural assumption rather than an unexplained numerical substitute for the 1993 paper's 70/30 shares. Each subinterval is averaged over its own duration before production shares are applied.
Test consequences: Verify a hand-calculated piecewise hay curve, both weighted windows, the canonical split date, drying, post-preparation storage decay, and dry-mass units.
Open production/stock timing gap: tests/artifacts_ecosys_for_excel/run1.XLS and run2.XLS
show contaminated feed hay first appearing exactly 90 days after the May 15
preparation start, from running hay production. The clean feed graph treats
hay as a terminal completed-season stock and does not evaluate the configured
90-day feed delay against an in-progress hay production series. The approved
2:1 shares and drying factor do not settle this availability question;
see §4.2 of the development history.
Implementation revision (VM phase B): The preceding timing gap is
superseded. Prepared hay at time q within a season is the dry-mass multiple
of (w*integral(start..min(q,split)) C_grass(s) ds +
integral(split..min(q,end)) C_grass(s) ds) /
(w*(min(q,split)-start) + max(0,min(q,end)-split)).
At the exact start it is the grass concentration there. Pre-event preparation
has zero activity and still counts in the duration. Daily deterministic
piecewise-linear quadrature uses no future production; after end, completed
stock decays physically. The feed graph's representational hay self-edge
applies the configured 90-day storage and its radioactive survival once,
with factor 1; the hay source already contains the fivefold dry conversion.
Unlike fixed 2:1 shares of two full-season means, partial and unequal windows
weight actual elapsed production. VM uses width-weighted samples on its sparse
grid, so early residuals can reflect quadrature: run 1 intensive day 106 is
49,427.869 versus VM 49,173.051 Bq/kg, day 108 46,734.997 versus 46,053.324;
run 2 day 103 is 56,488.689 versus 56,488.434. Both first observed onsets
are the May 15 production start plus the 90-day feed delay.
SD-10: Animal Equilibrium After Mast
Status: decided, revised for a population-level herd model
Question: Does mast_duration describe one animal's lifetime before
slaughter, or the turnover window of a continuously replenished product herd?
How is product output represented after the early transient?
Evidence: Canonical mast durations match the legacy workbook values. The legacy animal solver feeds a rolling mast-duration window during its transient and uses an equilibrium production approximation after the second post-event calendar year. The engine cannot resolve individual births, deaths, and slaughter from its available inputs.
Options: Track a single finite animal through mast and post-mast retention; represent a continuously replenished production herd with a rolling turnover window; or add explicit animal cohorts and slaughter dates.
Decision: Approved: represent animal products as a population-level
production stream, not a single finite animal. mast_duration is the rolling
herd-turnover window: ration-fed inputs continue under the requested forcing,
while contamination older than the window leaves the product stream. The
deposition-day inhalation impulse contributes only while it remains within that
window. Propagate biological and physical loss exactly within the window.
Beginning on January 1 of the third calendar year after deposition, use the
legacy-style equilibrium output factor evaluated from current support-node
feed intake. Products are evaluated only on supplied support nodes.
Rationale: The user clarified that the outputs represent a population, not an individually tracked animal. A finite-animal cutoff caused several orders of magnitude of year-one differences for short-mast products (broiler, calf, and lamb), even though the legacy and canonical mast durations agree.
Ration forcing: Retain the left-held ration forcing of the time-support grid (SD-18). On the TestCs137 70-year default support, sampling the legacy linear ration interpolation at the same support nodes changed one-year cumulative ingestion by about 3.1% and total dose by about 2.9%; this is within the user's accepted few-percent range. The experiment is summarized in the development history (§2).
Revision (VM phases C/D): The preceding stepwise schedule choice and the following provisional caution are superseded by three-artifact comparisons. Interpolate each feed's kg/day amount by canonical material ID between adjacent one-based seasonal change days; missing material at an endpoint has zero amount. Before the first breakpoint hold the first ration; after the last hold the last, resetting to the first at the next calendar-year boundary (no unrecorded December-to-January extrapolation). February 29 uses March 1 per SD-03. Within each transient support interval, hold both this interpolated schedule and the same material's feed concentration from the left node. The analytic retention propagation, rolling mast policy and January 1 year-three switch remain unchanged. Equilibrium uses separately gathered current-node ration and feed; its existing factor and activation date are unchanged. On VM run 2 day 7, cow/sheep/goat/lamb/deer are 3484.815/5950.646/8099.825/12061.820/ 5833.202 Bq/kg against 3485.140/5951.329/8100.433/12062.109/5833.696. Deposition-day VM output is zero while clean impulse output remains positive: SD-17 impulse ownership has not been changed by the feed forcing revision.
Revision (2026-09-28, approved by the maintainer): Equilibrium output at a
node now uses the ration averaged over the calendar days of its interval
(average_rations, daily evaluation plus cumulative sums, ~13 ms for 70
years), with the feed concentrations still taken at the node. Before, the
node-date ration alone stood for the whole interval: late default nodes all
fall on the deposition anniversary, so sheep milk was +13.8% (April event,
spring ration with hay) or −8.2% (August event, grass only) against the VMs.
The VBA uses a constant first-year mean ration. Now all three runs agree with
each other (sheep milk +4.8/+5.0/+2.1%), and the remaining offset is the
documented hay-stock difference (inventory E17). This did not change the
default-versus-refined 70-year ingestion difference (+4.4 → +4.6% for run 1),
so it is not the cause of the SD-18 support dependence.
New time-series evidence requiring reconsideration: On the VM's daily April/May support, left-held ration forcing yields almost no early sheep, goat, lamb, or deer contamination while linear interpolation produces nearby values. Sampling feed at the preceding rather than right support node additionally brings short-term animal values close to the VM, but a naive global previous-node swap over sparse decades significantly overestimates 70-year ingestion. This does not revise the left-held forcing (SD-18) until a supported between-node intake reconstruction and grid-convergence policy are selected. See §4.2 of the development history.
Test consequences: Add rolling-window steady-input, turnover boundary, inhalation-impulse expiration, year-three equilibrium, staged products, and batch/chunk tests. Compare animal/food checkpoints with the legacy herd output without importing legacy code into production.
SD-17: Animal Inhalation Timing
Status: decided
Question: What source interval and retention path apply to animal inhalation?
Decision: Approved: use the air concentration and inhalation rate at the deposition-day impulse, inject that activity intake into the same biological retention compartments as feed intake, and apply the approved product transfer and physical decay terms.
Rationale: This preserves the documented deposition-day animal branch while using one retention equation for all animal activity inputs.
Test consequences: Add deposition-day impulse, zero-after-impulse, retention, units, and batch-shape tests.
Revision (2026-09-28, approved by the maintainer): The instantaneous t=0
impulse is superseded. The deposition-day inhaled activity enters the same
retention compartments at a constant rate over the deposition day
[0, 1 d]. This is the VBA semantics: AktZufuhrTierBerechnen places the
inhalation in the day-0 intake, and the recurrence
S(t)=S(t-1)exp(-λΔt)+A(t-1)(1-exp(-λΔt)) (Akti-Modul.bas:729) holds
that intake over the following day. It is also the physical reading of the
reference scenario (constant air concentration for one day). Consequences:
product output is zero at day 0, and after the first day the product equals
the former impulse result times (e^{kD}-1)/(kD). The kernel carries the
inhaled term in closed form, including exact rolling mast windows, and treats
inhalation_duration=0 as the former impulse. Evidence
(divergence E4 in §4.3 of the development history): VM/impulse ratios for eggs,
chicken, pork and fattened beef were exactly λ/(e^λ−1) (0.88892, 0.98277,
0.99013, 0.99308). After the revision these products agree with all three
VMs within 0.0034% during the first month, the eight zero-reference food cells
disappear, and run-2 day-1/day-7 milk and meat agree within 0.0034%.
SD-11: Skin-Dose Coefficient Basis
Status: decided
Question: What physical basis applies to the skin coefficient, and is the fallback skin pathway supported in the engine?
Evidence: The nuclide worksheets explicitly distinguish organ doses under
Sv/s pro Bq (gamma dose to organs other than skin from 1 Bq distributed on
skin or clothing) from the small skin-dose table under Sv/s pro Bq/cm**2
(alpha/beta/gamma). The footnoted Haut * row points to the small table.
These are now exported as separate units and source-provenanced rows.
Options: Approve the retained skin-organ equation; approve the radiation factor fallback equation; defer skin dose and expose an explicit unsupported pathway error.
Decision: The worksheet coefficient units are identified, but the clean skin pathway remains deferred pending approval of how the two different skin/clothing exposure branches and the footnoted skin row enter the equation. Expose explicit pathway unavailability rather than introducing a numerical fallback.
Rationale: Resolving the tabulated units does not by itself approve the retained organ-dose equation or substitution of the radiation-specific skin factors. No numerical placeholder may be introduced for an unapproved branch.
Test consequences: Add dimensional skin tests or a tested explicit deferral, including pathway applicability behavior.
Later VBA verification (2026-09-28): Dosis-Modul.bas:544-553 selects the
small alpha/beta/gamma table only for IndexOrgan=10 (skin tissue); other
selected organs use their respective organ table. Clothing receives only the
gamma component, while uncovered skin also receives alpha and beta. The
time-integrated surface-activity dose is exposed separately as skin-tissue
dose, not added to the clean effective-dose total. The effective-dose skin
organ pathway remains deferred pending its distinct clean calculation and
handling of blank source cells.
The preserved VM artifacts all select Effektivdosis, so their
Haut/Kleidung rows cannot validate skin-tissue dose; only a VM run with
IndexOrgan=10 would provide an independent tissue-dose checkpoint.
SD-12: Ground Decay And Soil Migration
Status: decided
Question: Are root-zone migration/fixation and ground-external gamma shielding one soil-loss process, or separate effective models?
Evidence: ECOSYS-87 Eq. 12 gives root-zone soil activity as initial soil
deposition divided by root-zone soil mass per area and attenuated by physical
decay, migration out of the root zone, and fixation. With no desorption, the
current availability fraction is
exp(-(lambda_migration + lambda_fixation)*t); after physical survival and
division by canonical soil mass per area, it gives the Eq. 12 root-zone
concentration used by Eq. 11. The canonical process is named migration in
the clean data and was called lambda_leach in legacy code.
For external ground exposure, ECOSYS-87 Eqs. 22-23 instead define a separate
shielding correction
y(t) = sum_j a_j * exp(-lambda_j*t) for migration into deeper layers. The
paper gives a = (0.36, 0.64) and half-lives (1.3, 49.0) years. The clean
GroundDecayComponent records for Cs-137 contain those values. The exposure
kernel integrates each component with physical decay at rate
lambda_physical + lambda_j, and the engine applies its environment/location
reduction. It does not use CompiledSoil.migration. The legacy ground-dose
path also uses this correction and obtains its initial activity from the
grass-surface deposition helper.
Options: Reuse root-zone soil migration for ground gamma attenuation; derive a shared conserved-soil model; or retain the paper's independent root-zone and ground-shielding formulations.
Decision: Retain separate formulations. Root uptake uses the canonical
root-zone migration and fixation terms (plus the current desorption extension
when configured). Ground external exposure uses the independent empirical
two-component y(t) correction and must not reuse the root-zone migration
rate. SoilInventory.total remains the code's separately calculated surface
activity series routed to resuspension; ECOSYS-87 does not define it as a
universal conserved total from which plant_available must be a strict subset.
Rationale: The paper gives distinct equations and parameters for root-zone loss and ground gamma shielding. The matching Cs-137 ground components and closed-form integration tests support the separate ground-exposure model.
Implementation caveats requiring separate review: The paper's Eq. 12 does
not include desorption. The later Excel manual §3.2 attributes its two-term
fixation/desorption extension to Fesenko (1998), with zero desorption reducing
to the older equation. This provides manual provenance, though the embedded
equation should be checked against the original source before asserting exact
algebraic equivalence. Also, Eq. 22 defines its initial grassland activity from soil
dry deposition + grass dry deposition + wet deposition (Eq. 6), while the
current engine supplies the ground target alone to ground-exposure
integration. That source-composition difference remains open and is not changed
by this decision. (Superseded 2026-09-28, see below.) The engine also samples the age-dependent ground dose factor
at each interval's right support node; continuous variation within intervals
remains covered by the open support/quadrature question in SD-18. The legacy
ground-dose routine also samples that factor at grid nodes, so resolving this
point requires deciding how the paper's g_g(t) should be interpreted, not
replacing a clean-only numerical behavior.
Ground-shine source (2026-09-28, approved by the maintainer): The
ground-external source is ground deposition (wet + dry) plus dry deposition on
the lawn (turf) target, i.e. Eq. 6's grassland total and the VBA
GesDepRasen = GesDepBoden + TrockDepPfl(Rasen) (Depo-Modul.bas:78).
Lawn and intensive grass have identical deposition for spring events, but not
in tests/artifacts_ecosys_for_excel/run3.XLS (14 August), where only the lawn value reproduces the
VM. Clean/VM ground dose was 0.512/0.505/0.556 for runs 1–3, equal to
ground/(ground+lawn dry) to four digits. It is now 1.000 ± 0.0004 from 5 to 70
years. Early values remain low by exactly t/(t+1) because of the VBA 24:00
row convention (divergence E2 in §4.3 of the development history).
Implementation correction (2026-09-28): Root-uptake migration, fixation
and desorption rates were taken from the request landscape's soil type for
every plant, while the soil mass already came from each plant's own soil type.
Both now follow the plant's canonical soil type, like VBA BodenArt (pasture
for grass, arable for crops). The landscape soil type still drives the
surface inventory routed to resuspension. With an arable landscape, grass had
been losing root-zone activity at the arable rate (migration T½ 100 y instead
of 40 y); grass-fed products were +107% against the VMs at 70 years, and are
now within 0.1%. Whether a GIS landscape soil type should ever override a
plant's own soil type is not decided here.
Test consequences: Keep one- and two-component analytical ground integrals, including the published Cs-137 fractions/half-lives and nonzero interval start; verify that changing root-zone migration does not change ground-external dose; verify that compiled ground fractions sum to one and environment/location weighting is applied; and verify root uptake against Eqs. 11-12 in the no-desorption limit.
SD-13: Combined Nuclides And Decay Chains
Status: open
Question: Are combined nuclide identities sufficient, or must parent- daughter decay chains be represented explicitly?
Evidence: Canonical identities include combined nuclides such as
te_132_i_132. The architecture plan identifies combined identities versus
explicit chains as unresolved.
Options: Treat combined identities as independent canonical parameter sets; add explicit parent-daughter chain records; support combined identities now and defer chain dynamics.
Decision: Open.
Rationale: The current database identity does not establish chain semantics.
Test consequences: Add identity, half-life, superposition, and chain behavior tests for the approved representation.
SD-14: Annual Dose Semantics
Status: open
Question: Does annual dose mean an interval integral, an annualized endpoint rate, or both as separate outputs?
Evidence: The architecture plan notes that historical reports mix interval dose and point-rate approximations and requires these meanings to be distinct.
Options: Return interval integrals only; return annualized endpoint rates only; return both as separately named, unit-bearing quantities.
Decision: Open.
Rationale: Report labels cannot define physical result semantics.
Test consequences: Add irregular-time interval integration and explicit annualization tests, with separate result axes or fields as approved.
SD-15: Pathway Applicability
Status: open
Question: Which pathways apply to each nuclide or element, and does that applicability belong in canonical data or compiled model policy?
Evidence: Canonical dose and environmental tables have explicit pathway dimensions, while the architecture plan requires stable result shapes and distinguishes inapplicability from unsupported science.
Options: Encode applicability exclusively in canonical relationships; compile it from existing canonical dimensions; maintain a separately approved scientific applicability policy.
Decision: Open.
Rationale: Stable zero results and explicit unsupported errors require a single authoritative source.
Test consequences: Add complete pathway-axis, inapplicable-zero, missing
SD-16: Cohort Aging And Consumption Profiles
Status: decided (approved text below)
Question: How do cohorts age over elapsed time, and when do they transition between consumption and activity profiles?
Evidence: Canonical age groups are explicit at 1, 5, 10, 15, and 20 years. The design separates physical duration, age progression, and calendar anniversaries.
Options: Interpolate continuously by physical age; transition only at calendar anniversaries; use explicit profile transition dates supplied by the request; keep profiles fixed for a simulation.
Decision: Approved: advance cohort age by physical elapsed duration. Consumption and activity profile transitions must be defined from that quantity rather than from array positions or legacy report years.
Rationale: Cohort age is a physical duration, so elapsed-time progression keeps it independent of reporting grids and calendar labels.
Clarification (audit A01, 2026-09-29): initial_age is the age at
output_start_date. Cohort age at an absolute instant is initial_age plus
the physical duration from the output origin to that instant. Event-relative
time drives decay and transfer only; it never restarts cohort age at a later
event.
Test consequences: Add exact-age, between-age, anniversary, profile
transition, and cohort-axis shape tests. Origin-shift equivalence and
delayed-event tests: tests/integration/test_cohort_aging.py.
SD-18: Numerical Support Grid And Report Selection
Status: decided, with numerical-method questions remaining open
Question: Is the supplied time axis only a set of report queries, or is it the numerical support used to advance model states and accumulate interval doses? How may convenience defaults and reports select times?
Decision: Approved: the low-level request's explicit, unit-bearing time axis is the numerical support for concentrations, animal states, and interval doses. Adding support points may change numerical answers. The high-level convenience path constructs a deterministic Gregorian, event-date-anchored support schedule modeled on VBA's time-grid schedule; this approves only the schedule's role as support, not legacy numeric-unit shortcuts, fixed-day years, or VBA's ration interpolation.
Consecutive support nodes define right-owned intervals
(t[i-1], t[i]]. The interval at t[0] == 0 is zero except for an explicit
deposition-day cloud-inhalation impulse. An impulse at a later event node is
owned by the interval ending at that node. Cumulative dose is the sum of
interval doses through the node, not an endpoint rate or an annualized value.
For custom support, an event before the output origin is rejected until an
explicit prehistory contract exists. Every event instant within the finite
simulation window must be an exact support node; the engine must not round it,
insert an implicit node, or discard its impulse. An event after the finite
horizon is outside that run's simulated window. Report selection operates only
on a completed result: exact is the default and requires an existing node;
at_or_after, nearest, and vba_activity are explicit selection modes and
must not change integration support or recalculate dose.
Ingestion quadrature (2026-09-28, approved by the maintainer): Each ingestion
interval uses the logarithmic mean of its endpoint food concentrations,
(a − b) / ln(a / b) (interval_mean_concentration), which is exact for
exponential change between nodes; it falls back to the arithmetic mean when an
endpoint is zero or both are equal. Consumption, dose factor and the
interval-averaged seasonal factor are unchanged. The former right-endpoint
rule (also the VBA's) underestimated long, declining late intervals: 70-year
ingestion differed by −4.4/−3.9/−2.0% between the default (~290 nodes) and a
daily/monthly support (~1550 nodes) for the three VM scenarios; it now differs
by +0.36/+0.37/+0.05%, and by ≤0.12% at one year. The default support
therefore no longer reproduces the VM's own endpoint quadrature (run 1,
70 years: 3.264 vs VM 3.108 mSv).
Supply onset of stored plant foods (2026-09-28, approved by the maintainer):
A food made from a plant through storage (leafy vegetables 1 d, potatoes 7 d,
grains 548–576 d, ...) is zero until its cumulative storage delay after the
event and then steps to factor · survival(delay) · plant(0). The ingestion
interval containing that onset counts only the part after it,
clip((t1 − onset)/(t1 − t0), 0, 1) · logmean(post-step value, end), instead
of a linear rise from zero. The onset and post-step value come from the food
graph and the plant value at the event node (_food_availability_onsets).
Foods from animal products rise continuously from zero and get no onset;
externally supplied concentrations without plants get none either. The
expression is branch-free in the values and continuous in the onset time
(including across nodes), keeping it usable for gradient-based sensitivity
studies. On a daily support the first week is now within 0.3–0.4% of a
1/8-day support (was +6% with the zero-start fallback, +15% with the former
endpoint rule).
Rationale: Time points used to advance state and integrate dose are scientific inputs because changing them may change the numerical result. A separate report projection makes that dependency inspectable and prevents a report label from silently changing the simulation.
Open questions: This decision does not select new quadrature for varying food concentration, age-dependent coefficients, or resuspension concentration between support nodes. Preserve the currently tested integration rules until those questions receive separate scientific decisions. Cloud external and skin coefficients remain deferred under SD-01 and SD-11.
Test consequences: Verify grid sensitivity as documented behavior; exact support preservation; explicit event-node and prehistory errors; interval ownership and cumulative conservation including cloud impulses; and pure report selection with exact-default errors and named alternative modes. The quarantined legacy comparison may verify the schedule but cannot establish physical dose equivalence.
VM phase D numerical convention: The approved support contract now also specifies left-node, material-matched feed and ration for the transient, with current-node forcing passed independently to equilibrium. The low-level axis is still used exactly as supplied; neither feed switches nor report queries insert implicit solver nodes. Long intervals hold potentially stale transient feed, so compare deterministic refinements at common checkpoints before interpreting late peaks or cumulative dose. The old wording above excluding VBA ration interpolation from the approved schedule is superseded only as to ration evaluation, not the support schedule or numeric unit conventions.