team-8/hydroshoot/doc/usage.rst
francesco-bufalini 0ba7189bfc Commit last-minute
2025-08-02 13:46:28 +02:00

152 lines
5.6 KiB
ReStructuredText

=====
Usage
=====
.. figure:: figs/usage_fig_1.png
:align: center
Illustration of inputs and outputs of HydroShoot.
Three input files are required in order to run HydroShoot. The first contains all model parameters, the second
meteorological data, and the third (optional) soil predawn water potential data. The model returns an undetermined
number of files (:math:`\geq 3`) of two types of outputs.
Set the required files up
-------------------------
1. Model parameters
Almost all model parameters are setup in the **params.json** file.
*params.json* is a *JavaScript Object Notation (JSON)* file that contains the following sections:
* "simulation"
* "planting"
* "phenology"
* "mtg_api"
* "numerical_resolution"
* "irradiance"
* "energy"
* "hydraulic"
* "exchange"
* "soil"
Each of the above sections refers to its homonym process. An exhaustive and thoroughly detailed description
of all the parameters inside each section, their units and their expected values, are given in the
`params_schema.json` file (src/hydroshoot/). The reader is encouraged to refer to this file to know how exactly
to fill up the *params.json* file.
2. Meteorological data (time series)
Meteorological data must be provided using a .csv file whose name must be given in the
`params.json` file ("meteo" parameters).
This file must contain the following columns:
* `time`: a `datetime` string having the format YYYY-MM-DD HH:MM:SS
* `Tac`: air temperature :math:`[^\circ C]`
* `hs`: relative humidity (%)
* `u`: wind speed :math:`[m \ s^{-1}]`
* `Rg`: solar radiation (shortwave irradiance) given even in :math:`[W_{global} \ m_{ground}^{-2}]`,
:math:`[W_{PAR} \ m_{ground}^{-2}]` or :math:`[{\mu mol}_{PPFD} \ m_{ground}^{-2} \ s^{-1}]`.
The user must provide the unit of `Rg` in the `params.json` file ("E_type" parameter).
3. Soil predawn water potential data (time series)
There are two ways to supply predawn soil water potential (:math:`\Psi_{soil}`) to the model:
a. using an external file that must be named "psi_soil.input" (the user will be able to give other names to the file
in the future).
b. using the keyword argument "psi_soil" when calling the simulator:
.. code-block:: python
from hydroshoot import model
model.run(g, working_directory, psi_soil=-0.5)
In this case, the value given in the 'psi_soil' keyword overrides **all values** given in 'psi_soil.input' file.
HydroShoot will force soil water potential value **at each time step** to that given by the keyword 'psi_soil'.
Outputs
-------
The first output file is a *comma-separated values* (csv) file named "time_series.output" (only one file is returned)
that contains the following time-dependent outputs:
* **time**: datetime string (YYYY-MM-DD HH:MM:SS)
* **An**: net carbon assimilation flux of the whole plant :math:`[\mu mol \ s^{-1}]`
* **E**: tranpiration flux of the whole plant :math:`[g \ h^{-1}]`
* **Rg**: absorbed shortwave irradiance by the whole plant :math:`[W \ m_{ground}^{-2}]`
* **Tleaf**: median leaf temperature :math:`[^\circ C]`
The second type of outputs is a pickle (pckl) file in which is stored mtg data **for each simulated time step**. Note
that **pckl files do not contain geometry data**. Geometry is not currently stored as an output since the model expects
it as an input.
Run the model
-------------
Let's take the simple example provided in '~/example/potted_grapevine/'. We will use for this example **architecture**
and **display** modules provided with HydroShoot package (these packages may be removed in the future).
This example runs HydroShoot on a small potted grapevine canopy having two primary shoots.
Let's build the mock-up using the digitalization data provided in "grapevine_pot.csv" file:
.. code-block:: python
from os import getcwd
from openalea.mtg import traversal
from openalea.plantgl.all import Scene
from hydroshoot import architecture, display, model
# Path for plant digitalization data.
g = architecture.vine_mtg('grapevine_pot.csv')
for v in traversal.iter_mtg2(grapevine_mtg, grapevine_mtg.root):
architecture.vine_phyto_modular(grapevine_mtg, v)
architecture.vine_mtg_properties(grapevine_mtg, v)
architecture.vine_mtg_geometry(grapevine_mtg, v)
architecture.vine_transform(grapevine_mtg, v)
Display now the scene using **display** module, you should be having something like :numref:`fig_mockup`:
.. code-block:: python
scene = display.visu(g, def_elmnt_color_dict=True, scene=Scene(),
view_result=True)
.. _fig_mockup:
.. figure:: figs/usage_fig_2.png
Screen shot of the mock-up produced by the "potted_grapevine" example.
You're now ready to run the model using the meteorological data provided in "meteo.input", and forcing soil water
potential to a fixed value of -0.5 :math:`MPa`. Ensure first that the model will run over one hour only by setting
start and end dates of the simulation in the "params.json" file ("sdate": "2012-08-01 11:00:00",
"edate": "2012-08-01 11:00:00").
.. code-block:: python
model.run(g, str(getcwd()) + '/', scene, psi_soil=-0.2, gdd_since_budbreak=100.)
You should now have created the '/output/' folder where output files ("time_series.ouput", "mtg20120801110000.pckl")
are stored. "time_series.ouput" file should contain close values to those below:
.. code-block:: none
time;Rg;An;E;Tleaf
2012-08-01 11:00:00;69.83;7.99;179.17;26.05
.. figure:: figs/usage_fig_3.png
:align: center