PModel API for 2.0.0

[davidorme]

Given we have breaking changes in the API, we might as well think big. Here are some proposals:

PModelEnvironment

• At the moment this doesn't include fapar and ppfd. However if we drop PModel.estimate_productivity to align the signatures and usage of PModel and SubdailyPModel then providing these via PModelEnvironment is more natural and makes it easier to swap model settings. PModelEnvironment then provides all the forcing data. We can allow ppfd and fapar to default to unity.

• We have a bunch of "optional" variables, required by some downstream methods. At the moment this is really inflexible, because each has to be written into PModelEnvironment. The whole point in using registries for the methods is that people can define new ones, but if they require new forcing data variables, they can't work without changing the PModelEnvironment definition. So, we should just **kwargs and then check all kwargs are appropriately sized numpy arrays. The only thing we lose is bounds checking on the alternate variables but I think the flexibility makes sense. We can then use setattr to expose arbitrary variables to downstream methods.

• The PModelEnvironment should provide tk and tk_ref. A large number of functions use this and are currently calculating it internally - we should change them all to assuming tk and then calculate it once.

class PModelEnvironment:
    def __init__(
        self,
        tc: NDArray[np.float64],
        vpd: NDArray[np.float64],
        co2: NDArray[np.float64],
        patm: NDArray[np.float64],
        fapar: NDArray[np.float64] | None,
        ppfd: NDArray[np.float64] | None,
        pmodel_const: PModelConst = PModelConst(),
        core_const: CoreConst = CoreConst(),
       **kwargs: Any,
    ):

FastSlowScaler

In a similar vein, there are a lot of arguments to SubdailyPModel that are to do with the acclimation model to be used. I think we get rid of FastSlowScaler and build the same functionality into a broader AcclimationModel class. That again makes it easier to swap in alternative settings to the SubdailyPModel and bundles related functionality better.

Something like:

class AcclimationModel:

    def __init__(
        self,
        datetimes: NDArray[np.datetime64],
        alpha: float = 1 / 15,
        allow_holdover: bool = False,
        allow_partial_data: bool = False,
        fill_kind: str = "previous",
        previous_realised: tuple[NDArray, NDArray, NDArray] | None = None,
    )

PModel and SubdailyPModel

• We need to align the attribute names - this might use a base class, or could just simply be better organised? I'd lean towards a base class to be DRY on the docstrings etc.
• We should use functools.cached_property to support properties that aren't required as part of the model calculation, rather than the current self._var and @property setup. This is very much simplified in PModel if we drop estimate_productivity and provide fapar and ppfd in the env, because then we don't need to test for that having been run.

With these changes, the signatures will end up like:

class PModel:
    # Largely unchanged
    def __init__(
        self,
        env: PModelEnvironment,
        method_kphio: str = "temperature",
        method_optchi: str = "prentice14",
        method_jmaxlim: str = "wang17",
        method_arrhenius: str = "simple",
        reference_kphio: float | NDArray | None = None,
    ):

class SubdailyPModel:
    def __init__(
        self,
        env: PModelEnvironment,
        acclim: AcclimationModel,
        method_optchi: str = "prentice14",
        method_jmaxlim: str = "wang17",
        method_kphio: str = "temperature",
        method_arrhenius: str = "simple",
        reference_kphio: float | NDArray | None = None,
    ) -> None:

Workflow

This would give the following workflow sketch:

data = xarray.load_dataset("convenient/file/with/all/data.nc")
env = PModelEnvironment(
        tc: data["tc"].to_numpy(),
        vpd: data["vpd"].to_numpy(),
        co2: data["co2"].to_numpy(),
        patm: data["patm"].to_numpy(),
        fapar: data["fapar"].to_numpy(),
        ppfd: data["ppfd"].to_numpy(),
        growth_temp: data["growth_temp"].to_numpy()
)

# Default PModel
pmod = PModel(env=env)
pmod.gpp.mean()

# Create the acclimation settings
acclim = AcclimationModel(
        datetimes=data["time"].to_numpy()
        alpha=1/8,
)
acclim.set_window(window_center: np.timedelta(1, "H"), half_width: np.timedelta(1, "H"))

# Default SubdailyPModel
pmod = SubdailyPModel(env=env, acclim=acclim)
pmod.gpp.mean()

I think this is all a lot more logical and clean for users, but they are bigger changes.

[davidorme]

@Shirleycwj

I'd really appreciate a user perspective on this - it is going to break older code, but we're already going to need to do that to fix existing issues. This seems much more logical to me.

[Shirleycwj]

@davidorme I think the final workflow looks much clearer than previous version! Just checking on one thing: the soil moisture function, as some of the soil moisture function (and perfaps in the future) is wrapped into PModel that modifies beta for example, and I wonder how these would fit into PModelEnvironment?

[davidorme]

So we have two basic approaches to soil moisture.

1. Beni and Giulia's post hoc empirical corrections. These stay as is, although I think we should make the default $\phi_0$ to be 1/8 and then explicitly say that Beni's correction is calibrated on a different setting for that. Otherwise we get back silly results when the correction isn't applied post hoc. This was less of an issue for rpmodel because that correction was baked in, but PModel has more options and it is much easier to be clearer on the specific function docs than to have spaghetti code trying to guess use cases.

   We could make the penalty functions into something that explicitly checks the settings are appropriate? That is Beni's function is the standard PModel with adjusted $\phi_0=0.05625$ (or the alternative value with no temperature correction of $\phi_0$) , or Giulia's with the Subdaily and standard $\phi_0=1/8$. I think that's fussy though.

2. Internal methods that account for soil moisture. We have a few of these already - Alienor's optimal $\chi$ methods, David's $\phi_0$ method. These are all supported by the class frameworks we use for those four key method options: each method is implemented as a separate class, and each class can require that PModelEnvironment provides additional data, which is checked when the model is fitted. We'd be able to add on new methods that allow additional data to inform all of those methods.