Simplified development workflow for modelers

[VEZY]

Thomas made the remark that it would be more simple for developers to be able to decorate a function they already have with some metadata to build a PlantSimEngine model rather than writing it from scratch as we currently require. It would be simpler because it would be only Julia code first, so simpler to develop, prototype and test. And then when we want to make a model out of it, we decorate the function with some macros to make a PSE model.

Here's an example interface we imagined:

@PSE_model AbstractTestModel function test_model(carbon_offer=-Inf, carbon_demand=-Inf, param1, Ri_Par_f, Δ)
    @meteo Ri_Par_f # This macro helps us identify `Ri_Par_f` as a meteorology variable (i.e. meteo.Ri_Par_f)
    @constant Δ # This macro identifies the constants (taken as constants.Δ)
    @param param1 = 0.5

     var1 = compute_var1(carbon_demand, param1) # This is just a regular function call, not flagged as a hard dependency
    @hard_dependency carbon_offer  = carbon_offer_model(carbon_demand, var1) # this is a hard dependency
    trophic_state = carbon_offer / carbon_demand
    carbon_allocation = minimum(carbon_offer, carbon_demand)

    return @outputs (trophic_state = -Inf carbon_allocation = -Inf)
end

Note that the @PSE_model would automatically identify the inputs from the arguments of the function (and return an error if the inputs have no default value), and the other macros would identify meteo, constant, parameters, and output variables.

The combinations of the macros would write all the code needed for PSE to make a model:

• the model struct, using CamelCase based on the name of the function
• inputs, based on the arguments to the function that are not meteo, constant or parameters
• outputs based on the outputs macro
• meteo. and status. prefix for the meteo and inputs/outputs variables
• replace the hard dependency code by the generic call used in PSE, i.e. get the model associated to the function (it has to be defined before this model to be available) carbon_offer_model, get its process, and replace the line by the generic call PlantSimEngine.run!(models.carbon_offer, models, status, meteo, constants, extra)
• a method for the run! function

This would simplify the development of models, and allow for testing more easily the base functions without coupling, i.e. we can use test_model as is, or use it from PSE using a modelList that would call the run! method.

[VEZY]

Links with #65 and #132 for the inputs / outputs, because we could take this opportunity to declare units in the macro too.
Links with #98 also, as I had in mind to use a macro before the model definition to be able to manipulate the input julia code (the model from the users) and build the composite model as a julia script that users can inspect.

[VEZY]

We had a new discussion about that, this would also allow to provide a simpler API for the unit models that we would expose outside the models. For example, if we want to use the allocation model from XPalm, today we can't really provide a simple API around that. But if we implement our models like this proposition, we could provide this API much more simply.

[VEZY]

I had a discussion with Samuel; and this is not so simple. How can we do this when there is a hard dependency or when we are working in a multi-scale set-up (and so we have variables at different scales, with a method for dep).

This would probably increase the complexity of the package, and providing two ways of doing things is not great, usually. So using one syntax for simple models and another for more complex ones is a no go.

Let's discuss this further before we proceed.

[VEZY]

New discussion with Thomas: in fact, there are two frictions for users and modellers:

1. Modellers may prefer to prototype their functions in standard Julia, and then put it in PSE easily
2. Users may want to call a model like a standard Julia function, not using PSE's way for a first start (testing, plotting...)

For 1., we have three propositions:

1. Either we provide what we put above (a set of macros). Good: Incremental + Functional (i.e. model implemented in standard Julia) and PSE models are always in sync. Bad: can quickly become unreadable.
2. We provide one macro to put before the model and that takes a special struct (or whatever, like a Dict or so) as first argument, that will be used to declare all the informations provided by the other macros from solution 1.: the name of the model, its process, the inputs, outputs, their default values, the constants, the parameters, the meteo variables, the hard dependency and possibly their scale (if multiscale). Like for 1., we would generate the PSE model out of it. Good: Incremental + Great readability + Minimum effort on the modeller + Functional and PSE models always in sync; Bad: More work on our side (but not more than 1.).
3. Do nothing, and ask the user to manually do the work of transforming the model into the format expected by PSE. Good: easy for us; Bad: the two model implementations are not in sync.

For 2., it's the other way around, i.e. from the PSE model to the functional model. This could be done using a macro on the run! method to export the model's code as a string somewhere. Then we could have a function called e.g. generate_model_string that takes the model struct as input, and that would print the model's code, stripped of the PlantSimEngine syntax. This would also help with #98 if we only optionally strip the PSE code (in this case, not stripping).

If we implement 1.1 or 1.2 and 2., we could test that we can retrieve one with the other.

[VEZY]

See e.g. https://github.com/JuliaDebug/CodeTracking.jl for a helper to retrieve code after the functions were created (in the case that the modeler didn't use the macro on the run! Method)

[VEZY]

LLMs basically closed this issue for us. Also, I had another discussion with Thomas, showing him that we can just wrap a model inside a PSE model, by just exposing inputs / outputs to the status.