7/8 Add UrbanVPRM model and reference-EVI preprocessing

[Timothy-W-Hilton]

Add UrbanVPRM model and reference-EVI preprocessing

Summary

Add an initial UrbanVPRM extension of the standard VPRM model. It applies the impervious-surface-area (ISA), reference-EVI respiration treatment, and UHI-adjusted temperature drivers from Hardiman et al. (2017), while preserving ordinary VPRM calculations for every non-urban class.

Design

Base-model extension points

The base model now exposes protected GPP and respiration calculation hooks. The existing classwise loop and output assembly remain in the base model. This lets an extension override only the class-specific flux calculation it needs, without duplicating the VPRM prediction workflow.

Urban preprocessing

urban_vprm_preprocessor(vprm_preprocessor) builds a static reference EVI lookup for each satellite-grid cell:

• eligible reference cells are ISA-zero cells with fractional coverage of a caller-selected vegetated VPRM class;
• water and non-vegetated classes can therefore be excluded explicitly;
• the lookup stores nearest-reference row/column indices, distance, the eligibility mask, and available annual EVI extrema.

ISA itself is supplied on the satellite grid by a compatible preprocessing step. The separate GISA-new PR #41 provides one such workflow; this PR does not tie UrbanVPRM to a particular ISA product.

Urban flux model

vprm_urban_model(vprm_base_model):

• applies UrbanVPRM only to explicitly configured urban classes (default 10 and 11);
• retains unmodified base-VPRM GPP and respiration for all other classes;
• accepts a caller-supplied UHI temperature-adjustment callable, rather than embedding region-specific UHI coefficients;
• implements Hardiman et al. (2017) Appendix A Supplement SI Eqs. 6--8 for urban respiration;
• converts ISA percentages to a validated 0--1 fraction, allowing only tiny conservative-regridding roundoff beyond the 0--100 percent bounds.

By default, dynamic EVI reference selection finds the nearest eligible cell with finite positive EVI for the current satellite image. The result is cached until the image changes. This avoids using an ISA-zero reference whose EVI is currently cloud-masked or zero while avoiding repeated work for every modelled hour in the same satellite image.

Example

urban_pre = urban_vprm_preprocessor(...)
# Attach ISA using a compatible preprocessing workflow.
urban_pre.add_urban_reference_evi_lookup(
    vegetated_vprm_classes=[3, 4, 6, 7, 9],
)

model = vprm_urban_model(
    vprm_pre=urban_pre,
    met=meteorology,
    fit_params_dict=parameters,
    urban_vprm_classes=(10, 11),
    uhi_temperature_adjustment=lambda temperature, isa, when: temperature,
)

The identity callable in this example represents an explicit zero-UHI assumption; applications should provide a suitable local parameterization when one is available.

Validation

• Tests confirm the extracted base-model hooks reproduce the former VPRM GPP and respiration equations.
• UrbanVPRM tests cover the Hardiman ISA/reference-EVI respiration equations, ISA percentage validation, static lookup indexing, dynamic positive-EVI reference selection and cache refresh, and preservation of base behavior for non-urban classes.
• Focused test suite on this branch: 5 passed.