opticks.contrast_model.mtf_utils

Shared sanity-check helpers for the MTF model code.

Two patterns are consolidated here:

• reject_unused_params — guards against caller-supplied keyword parameters that the chosen model / kernel / preset does not actually use. Used by validate_*_params functions and preset overrides.

• check_mtf_below_unity / check_mtf_nonneg — atomic output sanity checks composed at call sites. Passive (detector / optics) MTF stages call both; processing-stage MTF (resampling kernels with edge-boost behaviour like Bicubic / Lanczos) calls only the non-negativity primitive.

Each primitive treats non-finite values (NaN, ±Inf) as failures, so silent NaN propagation is not possible.

Functions

check_mtf_below_unity(values, model_name)	Raise ValueError if any MTF value exceeds 1 (or is non-finite).
check_mtf_nonneg(values, model_name)	Raise ValueError if any MTF value is negative (or is non-finite).
reject_unused_params(supplied, required, *, ...)	Raise ValueError if any supplied parameter is not in required.

check_mtf_below_unity(values, model_name)

Raise ValueError if any MTF value exceeds 1 (or is non-finite).

Use for passive MTF stages where MTF > 1 is unphysical (detector, optics). For processing-stage MTF that legitimately exceeds 1 (e.g. Bicubic / Lanczos edge-boost), call only check_mtf_nonneg().

Return type:

None

Parameters:

• values (float | NDArray[np.float64]) – MTF value(s) to check (scalar or array).

• model_name (str) – Identifier of the MTF model, used in the error message.

check_mtf_nonneg(values, model_name)

Raise ValueError if any MTF value is negative (or is non-finite).

Return type:

None

Parameters:

• values (float | NDArray[np.float64]) – MTF value(s) to check (scalar or array).

• model_name (str) – Identifier of the MTF model, used in the error message.

reject_unused_params(supplied, required, *, model_name)

Raise ValueError if any supplied parameter is not in required.

Parameters supplied as None are ignored (treated as “not supplied”).

Return type:

None

Parameters:

• supplied (Mapping[str, object]) – Mapping from parameter name to caller-supplied value.

• required (Iterable[str]) – Names of parameters the chosen model / kernel / preset accepts.

• model_name (str) – Human-readable identifier of the model / kernel / preset, used in the error message (e.g. f"model {model}").