Staley 2017 numerical engine contract
Status: accepted, 2026-09-09 UTC. The owner explicitly approved N01–N04 and this contract in the execution conversation. ADR-0056 records provenance.
Scope and interfaces
An in-memory scalar Python library consumes prepared watershed predictors. It performs no raster processing, I/O, model selection, or missing-data fallback. Signatures:
probability(model, duration_minutes, *, T, F, S, rainfall_mm) -> float
rainfall_threshold(model, duration_minutes, *, T, F, S, target_probability) -> ThresholdResult
Model is exactly M1 or M3; duration is 15, 30 or 60 minutes. Numeric inputs
are Python numbers.Real scalars convertible to finite binary64 values. Reject booleans,
strings, complex numbers, containers and arrays; no broadcasting is supported.
Caller type errors raise TypeError; invalid ranges, model/duration values,
or nonfinite numeric inputs raise ValueError, identifying the argument.
M1 T and M3 F are fractions in [0,1]. M3 T and both S values are nonnegative, with no invented upper calibration bound. M1 F may be any finite value, including negative normalized dNBR. M1 F is already scaled: do not divide by 1000 again. M1 S is supplied in the calibrated K convention; M3 S is supplied as thickness in cm divided by 254. These checks do not establish calibration validity. Rainfall is nonnegative accumulation in mm for the chosen duration.
Forward calculation
Use the six coefficient rows in the specification, independently checked in
the publication audit.
Set q = Ct*T + Cf*F + Cs*S, x = B + rainfall_mm*q and evaluate sigmoid(x)
with a sign-stable exponential branch. Finite extreme logits may round to 0
or 1. Nonfinite intermediate arithmetic raises OverflowError explicitly;
it is not converted into a saturated probability. No response clamping or
override at zero rainfall is applied: the equation returns sigmoid(B) there.
This is mathematical model behavior, not a claim of rainless debris flows.
Inverse equality and numerical policies
The caller supplies a finite target strictly between 0 and 1. There is no
engine default target. A threshold means a nonnegative rainfall solution to
p(R) = target, not minimum rainfall to reach or exceed that target.
Immutable ThresholdResult contains status, reason, rainfall_mm
and intensity_mm_per_hour. Status is available, unavailable, or
nonunique. Available results have reason None and finite nonnegative
numeric values. Other results have both numeric values None.
For exact q == 0, compare the target exactly with the forward implementation's
sigmoid(B). A match returns nonunique / constant_probability; otherwise
return unavailable / constant_probability_mismatch. This binary64 equality
rule avoids an invented tolerance and avoids using a logit round-trip to
recognize the representable intercept probability.
For nonzero q, a target exactly equal to sigmoid(B) returns zero rainfall.
First reject targets below the representable intercept for positive q, or
above it for negative q, as negative_rainfall. This exact comparison prevents
cancellation in logit subtraction from manufacturing a reachable threshold.
For reachable targets, divide the stable log-odds difference by q. Normally
use log(target) - log1p(-target) - B. When abs(target-baseline) <= baseline/2,
use log1p(delta/baseline) - log1p(-delta/(1-baseline)), where baseline is
sigmoid(B) and delta is target minus baseline. This numerical evaluation branch
centers on the accepted representable intercept and keeps both log1p arguments
away from -1; it does not classify a nonzero response as zero. A negative solution
returns unavailable / negative_rainfall. A finite nonnegative solution is
available, with intensity obtained by dividing rainfall by duration in hours.
A nonzero mathematical rainfall solution that rounds to zero returns
unavailable / arithmetic_underflow; zero is reserved for exact baseline
targets. A nonfinite inverse or intensity returns unavailable / arithmetic_overflow.
Overflow while constructing q remains OverflowError, as in the forward API.
No tolerance-based zero tests or negative-result clipping are used.
Negative q is possible with M1 dNBR. The inverse may then have a nonnegative equality solution on a decreasing curve. That extension is algebraic, outside the publication's positive-contribution discussion, and is not a scientifically validated rainfall-trigger threshold. Tiny q can lead to unrepresentable solutions; unavailable values must never be replaced by zero or infinity.
Validation requirements
Independent numerical tests must cover six coefficient rows, negative/zero q, zero rainfall, finite extremes, overflow, invalid types/ranges and inverse reconstruction. Synthetic generated examples are numerical evidence only.
At targets adjacent to the intercept probability, adding the solved rainfall term to B in the forward function may round back to B. Reconstruction is subject to binary64 rounding; an available equality is not a promise of bitwise target reconstruction. Exact side-of-baseline reachability is preserved.
Scientific integration amendment — 2026-09-14
For new production execution, the runtime integration contract and accepted ADR-0067 govern model-specific common support, recorded-depth soil policy, version-2 predictors and mask publication. Existing local/offline v1 semantics below remain reproducible. Runtime implementation conformance is pending; the amendment does not authorize source acquisition or production deployment.