Code documentation

How to read

The API documentation provides a description of the interface and internals of all SimulationObjects, AncillaryObjects and utility routines available in the PCSE source distribution. All SimulationObjects and AncillaryObjects are described using the same structure:

A short description of the object

The positional parameters and keywords specified in the interface.

A table specifying the simulation parameters needed for the simulation

A table specifying the state variables of the SimulationObject

A table specifying the rate variables of the SimulationObject

Signals sent or received by the SimulationObject

External dependencies on state/rate variables of other SimulationObjects.

The exceptions that are raised under which conditions.

One or more of these sections may be excluded when they are not relevant for the SimulationObject that is described.

The table specifying the simulation parameters has the following columns:

The name of the parameter.

A description of the parameter.

The type of the parameter. This is provided as a three-character code with the following interpretation. The first character indicates of the parameter is a scalar (S) or table (T) parameter. The second and third

The physical unit of the parameter.

The tables specifying state/rate variables have the following columns:

The name of the variable.

A description of the variable.

Whether the variable is published in the kiosk or not: Y|N

The physical unit of the variable.

Finally, all public methods of all objects are described as well.

Engine and models

The PCSE Engine provides the environment where SimulationObjects are ‘living’. The engine takes care of reading the model configuration, initializing model components (e.g. groups of SimulationObjects), driving the simulation forward by calling the SimulationObjects, calling the agromanagement unit, keeping track of time and providing the weather data needed.

Models are treated together with the Engine, because models are simply pre-configured Engines. Any model can be started by starting the Engine with the appropriate configuration file. The only difference is that models can have methods that deal with specific characteristics of a model. This kind of functionality cannot be implemented in the Engine because the model details are not known beforehand.

class pcse.engine.CGMSEngine(**kwargs)[source]

Engine to mimic CGMS behaviour.

The original CGMS did not terminate when the crop cycles was finished but instead continued with its simulation cycle but without altering the crop and soil components. This had the effect that after the crop cycle finished, all state variables were kept at the same value while the day counter increased. This behaviour is useful for two reasons:

CGMS generally produces dekadal output and when a day-of-maturity or day-of-harvest does not coincide with a dekad boundary the final simulation values remain available and are stored at the next dekad.
When aggregating spatial simulations with variability in day-of-maturity or day-of-harvest it ensures that records are available in the database tables. So GroupBy clauses in SQL queries produce the right results when computing spatial averages.

The difference with the Engine are:

Crop rotations are not supported
After a CROP_FINISH signal, the engine will continue, updating the timer but the soil, crop and agromanagement will not execute their simulation cycles. As a consequence, all state variables will retain their value.
TERMINATE signals have no effect.
CROP_FINISH signals will never remove the CROP SimulationObject.
run() and run_till_terminate() are not supported, only run_till() is supported.

run(days=1)[source]: Advances the system state with given number of days

run_till(rday)[source]: Runs the system until rday is reached.

run_till_terminate()[source]: Runs the system until a terminate signal is sent.

class pcse.engine.Engine(**kwargs)[source]

Simulation engine for simulating the combined soil/crop system.

Parameters

parameterprovider – A ParameterProvider object providing model parameters as key/value pairs. The parameterprovider encapsulates the different parameter sets for crop, soil and site parameters.
weatherdataprovider – An instance of a WeatherDataProvider that can return weather data in a WeatherDataContainer for a given date.
agromanagement – AgroManagement data. The data format is described in the section on agronomic management.
config – A string describing the model configuration file to use. By only giving a filename PCSE assumes it to be located in the ‘conf/’ folder in the main PCSE folder. If you want to provide you own configuration file, specify it as an absolute or a relative path (e.g. with a leading ‘.’)
output_vars – the variable names to add/replace for the OUTPUT_VARS configuration variable
summary_vars – the variable names to add/replace for the SUMMARY_OUTPUT_VARS configuration variable
terminal_vars – the variable names to add/replace for the TERMINAL_OUTPUT_VARS configuration variable

Engine handles the actual simulation of the combined soil- crop system. The central part of the Engine is the soil water balance which is continuously simulating during the entire run. In contrast, CropSimulation objects are only initialized after receiving a “CROP_START” signal from the AgroManagement unit. From that point onward, the combined soil-crop is simulated including the interactions between the soil and crop such as root growth and transpiration.

Similarly, the crop simulation is finalized when receiving a “CROP_FINISH” signal. At that moment the finalize() section on the cropsimulation is executed. Moreover, the “CROP_FINISH” signal can specify that the crop simulation object should be deleted from the hierarchy. The latter is useful for further extensions of PCSE for running crop rotations.

Finally, the entire simulation is terminated when a “TERMINATE” signal is received. At that point, the finalize() section on the water balance is executed and the simulation stops.

Signals handled by Engine:

Engine handles the following signals:

CROP_START: Starts an instance of CropSimulation for simulating crop growth. See the _on_CROP_START handler for details.
CROP_FINISH: Runs the finalize() section an instance of CropSimulation and optionally deletes the cropsimulation instance. See the _on_CROP_FINISH handler for details.
TERMINATE: Runs the finalize() section on the waterbalance module and terminates the entire simulation. See the _on_TERMINATE handler for details.
OUTPUT: Preserves a copy of the value of selected state/rate variables during simulation for later use. See the _on_OUTPUT handler for details.
SUMMARY_OUTPUT: Preserves a copy of the value of selected state/rate variables for later use. Summary output is usually requested only at the end of the crop simulation. See the _on_SUMMARY_OUTPUT handler for details.

get_output()[source]

Returns the variables have have been stored during the simulation.

If no output is stored an empty list is returned. Otherwise, the output is returned as a list of dictionaries in chronological order. Each dictionary is a set of stored model variables for a certain date.

get_summary_output()[source]: Returns the summary variables have have been stored during the simulation.

get_terminal_output()[source]: Returns the terminal output variables have have been stored during the simulation.

run(days=1)[source]: Advances the system state with given number of days

run_till(rday)[source]: Runs the system until rday is reached.

run_till_terminate()[source]: Runs the system until a terminate signal is sent.

set_variable(varname, value)[source]

Sets the value of the specified state or rate variable.

Parameters

varname – Name of the variable to be updated (string).
value – Value that it should be updated to (float)

Returns

a dict containing the increments of the variables that were updated (new - old). If the call was unsuccessful in finding the class method (see below) it will return an empty dict.

Note that ‘setting’ a variable (e.g. updating a model state) is much more complex than just getting a variable, because often some other internal variables (checksums, related state variables) must be updated as well. As there is no generic rule to ‘set’ a variable it is up to the model designer to implement the appropriate code to do the update.

The implementation of set_variable() works as follows. First it will recursively search for a class method on the simulationobjects with the name _set_variable_<varname> (case sensitive). If the method is found, it will be called by providing the value as input.

So for updating the crop leaf area index (varname ‘LAI’) to value ‘5.0’, the call will be: set_variable(‘LAI’, 5.0). Internally, this call will search for a class method _set_variable_LAI which will be executed with the value ‘5.0’ as input.

class pcse.models.Alcepas10_PP(**kwargs)[source]

Convenience class for running the ALCEPAS 1.0 onion model for potential production

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.FAO_WRSI10_WLP_CWB(**kwargs)[source]

Convenience class for computing actual crop water use using the Water Requirements Satisfaction Index with a (modified) FAO WRSI approach.

see pcse.engine.Engine for description of arguments and keywords

pcse.models.LINGRA_NWLP_FD: alias of Lingra10_NWLP_CWB_CNB

pcse.models.LINGRA_PP: alias of Lingra10_PP

pcse.models.LINGRA_WLP_FD: alias of Lingra10_WLP_CWB

pcse.models.LINTUL3: alias of Lintul10_NWLP_CWB_CNB

class pcse.models.Lingra10_NWLP_CWB_CNB(**kwargs)[source]

Convenience class for running the LINGRA grassland model for nitrogen and water-limited production.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Lingra10_PP(**kwargs)[source]

Convenience class for running the LINGRA grassland model for potential production.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Lingra10_WLP_CWB(**kwargs)[source]

Convenience class for running the LINGRA grassland model for water-limited production.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Lintul10_NWLP_CWB_CNB(**kwargs)[source]

The LINTUL model (Light INTerception and UtiLisation) is a simple general crop model, which simulates dry matter production as the result of light interception and utilization with a constant light use efficiency.

In literature, this model is known as LINTUL3 and simulates crop growth under water-limited and nitrogen-limited conditions

see pcse.engine.Engine for description of arguments and keywords

pcse.models.Wofost71_PP: alias of Wofost72_PP

pcse.models.Wofost71_WLP_FD: alias of Wofost72_WLP_CWB

class pcse.models.Wofost72_PP(**kwargs)[source]

Convenience class for running WOFOST7.2 Potential Production.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost72_Phenology(**kwargs)[source]

Convenience class for running WOFOST7.2 phenology only.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost72_WLP_CWB(**kwargs)[source]

Convenience class for running WOFOST7.2 water-limited production.

see pcse.engine.Engine for description of arguments and keywords

pcse.models.Wofost72_WLP_FD: alias of Wofost72_WLP_CWB

class pcse.models.Wofost73_PP(**kwargs)[source]

Convenience class for running WOFOST7.3 Potential Production.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost73_WLP_CWB(**kwargs)[source]

Convenience class for running WOFOST7.3 Water=limited Production using the Classic Waterbalance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost73_WLP_MLWB(**kwargs)[source]

Convenience class for running WOFOST7.3 Water=limited Production using the Multi-layer Waterbalance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_NWLP_CWB_CNB(**kwargs)[source]

Convenience class for running WOFOST8.1 nutrient and water-limited production using the classic waterbalance and classic nitrogen balance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_NWLP_MLWB_CNB(**kwargs)[source]

Convenience class for running WOFOST8.1 nutrient and water-limited production using the multi-layer waterbalance and classic nitrogen balance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_NWLP_MLWB_SNOMIN(**kwargs)[source]

Convenience class for running WOFOST8.1 nutrient and water-limited production using the multi-layer waterbalance and the SNOMIN carbon/nitrogen balance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_PP(**kwargs)[source]

Convenience class for running WOFOST8.1 potential production

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_WLP_CWB(**kwargs)[source]

Convenience class for running WOFOST8.1 water-limited production using the classic waterbalance.

see pcse.engine.Engine for description of arguments and keywords

class pcse.models.Wofost81_WLP_MLWB(**kwargs)[source]

Convenience class for running WOFOST8.1 water-limited production using the multi-layer waterbalance.

see pcse.engine.Engine for description of arguments and keywords

Agromanagement modules

The routines below implement the agromanagement system in PCSE including crop calendars, rotations, state and timed events. For reading agromanagement data from a file or a database structure see the sections on the reading file input and the database tools.

class pcse.agromanager.AgroManager(**kwargs)[source]

Class for continuous AgroManagement actions including crop rotations and events.

See also the documentation for the classes CropCalendar, TimedEventDispatcher and StateEventDispatcher.

The AgroManager takes care of executing agromanagent actions that typically occur on agricultural fields including planting and harvesting of the crop, as well as management actions such as fertilizer application, irrigation, mowing and spraying.

The agromanagement during the simulation is implemented as a sequence of campaigns. Campaigns start on a prescribed calendar date and finalize when the next campaign starts. The simulation ends either explicitly by provided a trailing empty campaign or by deriving the end date from the crop calendar and timed events in the last campaign. See also the section below on end_date property.

Each campaign is characterized by zero or one crop calendar, zero or more timed events and zero or more state events. The structure of the data needed as input for AgroManager is most easily understood with the example (in YAML) below. The definition consists of three campaigns, the first starting on 1999-08-01, the second starting on 2000-09-01 and the last campaign starting on 2001-03-01. The first campaign consists of a crop calendar for winter-wheat starting with sowing at the given crop_start_date. During the campaign there are timed events for irrigation at 2000-05-25 and 2000-06-30. Moreover, there are state events for fertilizer application (event_signal: apply_n) given by development stage (DVS) at DVS 0.3, 0.6 and 1.12.

The second campaign has no crop calendar, timed events or state events. This means that this is a period of bare soil with only the water balance running. The third campaign is for fodder maize sown at 2001-04-15 with two series of timed events (one for irrigation and one for N application) and no state events. The end date of the simulation in this case will be 2001-11-01 (2001-04-15 + 200 days).

An example of an agromanagement definition file:

AgroManagement:
- 1999-08-01:
    CropCalendar:
        crop_name: wheat
        variety_name: winter-wheat
        crop_start_date: 1999-09-15
        crop_start_type: sowing
        crop_end_date:
        crop_end_type: maturity
        max_duration: 300
    TimedEvents:
    -   event_signal: irrigate
        name:  Timed irrigation events
        comment: All irrigation amounts in cm
        events_table:
        - 2000-05-25: {irrigation_amount: 3.0}
        - 2000-06-30: {irrigation_amount: 2.5}
    StateEvents:
    -   event_signal: apply_n
        event_state: DVS
        zero_condition: rising
        name: DVS-based N application table
        comment: all fertilizer amounts in kg/ha
        events_table:
        - 0.3: {N_amount : 1, N_recovery: 0.7}
        - 0.6: {N_amount: 11, N_recovery: 0.7}
        - 1.12: {N_amount: 21, N_recovery: 0.7}
- 2000-09-01:
    CropCalendar:
    TimedEvents:
    StateEvents
- 2001-03-01:
    CropCalendar:
        crop_name: maize
        variety_name: fodder-maize
        crop_start_date: 2001-04-15
        crop_start_type: sowing
        crop_end_date:
        crop_end_type: maturity
        max_duration: 200
    TimedEvents:
    -   event_signal: irrigate
        name:  Timed irrigation events
        comment: All irrigation amounts in cm
        events_table:
        - 2001-06-01: {irrigation_amount: 2.0}
        - 2001-07-21: {irrigation_amount: 5.0}
        - 2001-08-18: {irrigation_amount: 3.0}
        - 2001-09-19: {irrigation_amount: 2.5}
    -   event_signal: apply_n
        name:  Timed N application table
        comment: All fertilizer amounts in kg/ha
        events_table:
        - 2001-05-25: {N_amount : 50, N_recovery: 0.7}
        - 2001-07-05: {N_amount : 70, N_recovery: 0.7}
    StateEvents:

property end_date

Retrieves the end date of the agromanagement sequence, e.g. the last simulation date.

Returns: a date object

Getting the last simulation date is more complicated because there are two options.

1. Adding an explicit trailing empty campaign

The first option is to explicitly define the end date of the simulation by adding a ‘trailing empty campaign’ to the agromanagement definition. An example of an agromanagement definition with a ‘trailing empty campaigns’ (YAML format) is given below. This example will run the simulation until 2001-01-01:

Version: 1.0
AgroManagement:
- 1999-08-01:
    CropCalendar:
        crop_name: winter-wheat
        variety_name: winter-wheat
        crop_start_date: 1999-09-15
        crop_start_type: sowing
        crop_end_date:
        crop_end_type: maturity
        max_duration: 300
    TimedEvents:
    StateEvents:
- 2001-01-01:

Note that in configurations where the last campaign contains a definition for state events, a trailing empty campaign must be provided because the end date cannot be determined. The following campaign definition will therefore lead to an error:

Version: 1.0
AgroManagement:
- 2001-01-01:
    CropCalendar:
        crop_name: maize
        variety_name: fodder-maize
        crop_start_date: 2001-04-15
        crop_start_type: sowing
        crop_end_date:
        crop_end_type: maturity
        max_duration: 200
    TimedEvents:
    StateEvents:
    -   event_signal: apply_n
        event_state: DVS
        zero_condition: rising
        name: DVS-based N application table
        comment: all fertilizer amounts in kg/ha
        events_table:
        - 0.3: {N_amount : 1, N_recovery: 0.7}
        - 0.6: {N_amount: 11, N_recovery: 0.7}
        - 1.12: {N_amount: 21, N_recovery: 0.7}

2. Without an explicit trailing campaign

The second option is that there is no trailing empty campaign and in that case the end date of the simulation is retrieved from the crop calendar and/or the timed events that are scheduled. In the example below, the end date will be 2000-08-05 as this is the harvest date and there are no timed events scheduled after this date:

Version: 1.0
AgroManagement:
- 1999-09-01:
    CropCalendar:
        crop_name: wheat
        variety_name: winter-wheat
        crop_start_date: 1999-10-01
        crop_start_type: sowing
        crop_end_date: 2000-08-05
        crop_end_type: harvest
        max_duration: 330
    TimedEvents:
    -   event_signal: irrigate
        name:  Timed irrigation events
        comment: All irrigation amounts in cm
        events_table:
        - 2000-05-01: {irrigation_amount: 2, efficiency: 0.7}
        - 2000-06-21: {irrigation_amount: 5, efficiency: 0.7}
        - 2000-07-18: {irrigation_amount: 3, efficiency: 0.7}
    StateEvents:

In the case that there is no harvest date provided and the crop runs till maturity, the end date from the crop calendar will be estimated as the crop_start_date plus the max_duration.

initialize(kiosk, agromanagement)[source]

Initialize the AgroManager.

Parameters

kiosk – A PCSE variable Kiosk
agromanagement – the agromanagement definition, see the example above in YAML.

property ndays_in_crop_cycle

Returns the number of days of the current cropping cycle.

Returns zero if no crop cycle is active.

property start_date

Retrieves the start date of the agromanagement sequence, e.g. the first simulation date

Returns: a date object

class pcse.agromanager.CropCalendar(**kwargs)[source]

A crop calendar for managing the crop cycle.

A CropCalendar object is responsible for storing, checking, starting and ending the crop cycle. The crop calendar is initialized by providing the parameters needed for defining the crop cycle. At each time step the instance of CropCalendar is called and at dates defined by its parameters it initiates the appropriate actions:

sowing/emergence: A crop_start signal is dispatched including the parameters needed to start the new crop simulation object
maturity/harvest: the crop cycle is ended by dispatching a crop_finish signal with the appropriate parameters.

Parameters

kiosk – The PCSE VariableKiosk instance
crop_name – String identifying the crop
variety_name – String identifying the variety
crop_start_date – Start date of the crop simulation
crop_start_type – Start type of the crop simulation (‘sowing’, ‘emergence’)
crop_end_date – End date of the crop simulation
crop_end_type – End type of the crop simulation (‘harvest’, ‘maturity’, ‘earliest’)
max_duration – Integer describing the maximum duration of the crop cycle

Returns

A CropCalendar Instance

get_end_date()[source]

Return the end date of the crop cycle.

This is either given as the harvest date or calculated as crop_start_date + max_duration

Returns: a date object

get_start_date()[source]

Returns the start date of the cycle. This is always self.crop_start_date

Returns: the start date

validate(campaign_start_date, next_campaign_start_date)[source]

Validate the crop calendar internally and against the interval for the agricultural campaign.

Parameters

campaign_start_date – start date of this campaign
next_campaign_start_date – start date of the next campaign

class pcse.agromanager.TimedEventsDispatcher(**kwargs)[source]

Takes care handling events that are connected to a date.

Events are handled by dispatching a signal (taken from the signals module) and providing the relevant parameters with the signal. TimedEvents can be most easily understood when looking at the definition in the agromanagement file. The following section (in YAML) provides the definition of two instances of TimedEventsDispatchers:

TimedEvents:
-   event_signal: irrigate
    name:  Timed irrigation events
    comment: All irrigation amounts in mm
    events_table:
    - 2000-01-01: {irrigation_amount: 20}
    - 2000-01-21: {irrigation_amount: 50}
    - 2000-03-18: {irrigation_amount: 30}
    - 2000-03-19: {irrigation_amount: 25}
-   event_signal: apply_n
    name:  Timed N application table
    comment: All fertilizer amounts in kg/ha
    events_table:
    - 2000-01-10: {N_amount : 10, N_recovery: 0.7}
    - 2000-01-31: {N_amount : 30, N_recovery: 0.7}
    - 2000-03-25: {N_amount : 50, N_recovery: 0.7}
    - 2000-04-05: {N_amount : 70, N_recovery: 0.7}

Each TimedEventDispatcher is defined by an event_signal, an optional name, an optional comment and the events_table. The events_table is list which provides for each date the parameters that should be dispatched with the given event_signal.

get_end_date()[source]: Returns the last date for which a timed event is given

validate(campaign_start_date, next_campaign_start_date)[source]

Validates the timed events given the campaign window

Parameters

campaign_start_date – Start date of the campaign
next_campaign_start_date – Start date of the next campaign, can be None

class pcse.agromanager.StateEventsDispatcher(**kwargs)[source]

Takes care handling events that are connected to a model state variable.

Events are handled by dispatching a signal (taken from the signals module) and providing the relevant parameters with the signal. StateEvents can be most easily understood when looking at the definition in the agromanagement file. The following section (in YAML) provides the definition of two instances of StateEventsDispatchers:

StateEvents:
-   event_signal: apply_n
    event_state: DVS
    zero_condition: rising
    name: DVS-based N application table
    comment: all fertilizer amounts in kg/ha
    events_table:
    - 0.3: {N_amount : 1, N_recovery: 0.7}
    - 0.6: {N_amount: 11, N_recovery: 0.7}
    - 1.12: {N_amount: 21, N_recovery: 0.7}
-   event_signal: irrigate
    event_state: SM
    zero_condition: falling
    name: Soil moisture driven irrigation scheduling
    comment: all irrigation amounts in cm of water
    events_table:
    - 0.15: {irrigation_amount: 20}

Each StateEventDispatcher is defined by an event_signal, an event_state (e.g. the model state that triggers the event) and a zero condition. Moreover, an optional name and an optional comment can be provided. Finally the events_table specifies at which model state values the event occurs. The events_table is a list which provides for each state the parameters that should be dispatched with the given event_signal.

For finding the time step at which a state event occurs PCSE uses the concept of zero-crossing. This means that a state event is triggered when (model_state - event_state) equals or crosses zero. The zero_condition defines how this crossing should take place. The value of zero_condition can be:

rising: the event is triggered when (model_state - event_state) goes from a negative value towards
zero or a positive value.
falling: the event is triggered when (model_state - event_state) goes from a positive value towards
zero or a negative value.
either: the event is triggered when (model_state - event_state) crosses or reaches zero from any
direction.

The impact of the zero_condition can be illustrated using the example definitions above. The development stage of the crop (DVS) only increases from 0 at emergence to 2 at maturity. A StateEvent set on the DVS (first example) will therefore logically have a zero_condition ‘rising’ although ‘either’ could be used as well. A DVS-based event will not occur with zero_condition set to ‘falling’ as the value of DVS will not decrease.

The soil moisture (SM) however can both increase and decrease. A StateEvent for applying irrigation (second example) will therefore be specified with a zero_condition ‘falling’ because the event must be triggered when the soil moisture level reaches or crosses the minimum level specified by the events_table. Note that if we set the zero_condition to ‘either’ the event would probably occur again the next time-step because the irrigation amount increase the soil moisture and (model_state - event_state) crosses zero again but from the other direction.

The Timer

class pcse.timer.Timer(**kwargs)[source]

This class implements a basic timer for use with the WOFOST crop model.

This object implements a simple timer that increments the current time with a fixed time-step of one day at each call and returns its value. Moreover, it generates OUTPUT signals in daily, dekadal or monthly time-steps that can be caught in order to store the state of the simulation for later use.

Initializing the timer:

timer = Timer(start_date, kiosk, final_date, mconf)
CurrentDate = timer()

Signals sent or handled:

“OUTPUT”: sent when the condition for generating output is True which depends on the output type and interval.

initialize(kiosk, start_date, end_date, mconf)[source]

Parameters

day – Start date of the simulation
kiosk – Variable kiosk of the PCSE instance
end_date – Final date of the simulation. For example, this date represents (START_DATE + MAX_DURATION) for a single cropping season. This date is not the harvest date because signalling harvest is taken care of by the AgroManagement module.
mconf – A ConfigurationLoader object, the timer needs access to the configuration attributes mconf.OUTPUT_INTERVAL, mconf.OUTPUT_VARS and mconf.OUTPUT_INTERVAL_DAYS

Soil process modules

Water balance modules

The PCSE distribution provides several waterbalance modules:

WaterbalancePP which is used for simulation under non-water-limited production
WaterbalanceFD which is used for simulation of water-limited production under conditions of freely draining soils
The SnowMAUS for simulation the build-up and melting of the snow cover.
A multi-layer waterbalance implementing simulations for potential conditions, water-limited free drainage conditions. Currently the model does not support the impact of shallow ground water tables but this will implemented in the future.

class pcse.soil.WaterbalancePP(**kwargs)[source]

Fake waterbalance for simulation under potential production.

Keeps the soil moisture content at field capacity and only accumulates crop transpiration and soil evaporation rates through the course of the simulation

class pcse.soil.WaterbalanceFD(**kwargs)[source]

Waterbalance for freely draining soils under water-limited production.

The purpose of the soil water balance calculations is to estimate the daily value of the soil moisture content. The soil moisture content influences soil moisture uptake and crop transpiration.

The dynamic calculations are carried out in two sections, one for the calculation of rates of change per timestep (= 1 day) and one for the calculation of summation variables and state variables. The water balance is driven by rainfall, possibly buffered as surface storage, and evapotranspiration. The processes considered are infiltration, soil water retention, percolation (here conceived as downward water flow from rooted zone to second layer), and the loss of water beyond the maximum root zone.

The textural profile of the soil is conceived as homogeneous. Initially the soil profile consists of two layers, the actually rooted soil and the soil immediately below the rooted zone until the maximum rooting depth is reached by roots(soil and crop dependent). The extension of the root zone from the initial rooting depth to maximum rooting depth is described in Root_Dynamics class. From the moment that the maximum rooting depth is reached the soil profile may be described as a one layer system depending if the roots are able to penetrate the entire profile. If not a non-rooted part remains at the bottom of the profile.

The class WaterbalanceFD is derived from WATFD.FOR in WOFOST7.1 with the exception that the depth of the soil is now completely determined by the maximum soil depth (RDMSOL) and not by the minimum of soil depth and crop maximum rooting depth (RDMCR).

Simulation parameters:

Name	Description	Type	Unit
SMFCF	Field capacity of the soil	SSo
SM0	Porosity of the soil	SSo
SMW	Wilting point of the soil	SSo
CRAIRC	Soil critical air content (waterlogging)	SSo
SOPE	maximum percolation rate root zone	SSo	$cm day^{-1}$
KSUB	maximum percolation rate subsoil	SSo	$cm day^{-1}$
RDMSOL	Soil rootable depth	SSo	cm
IFUNRN	Indicates whether non-infiltrating fraction of rain is a function of storm size (1) or not (0)	SSi
SSMAX	Maximum surface storage	SSi	cm
SSI	Initial surface storage	SSi	cm
WAV	Initial amount of water in total soil profile	SSi	cm
NOTINF	Maximum fraction of rain not-infiltrating into the soil	SSi
SMLIM	Initial maximum moisture content in initial rooting depth zone.	SSi

State variables:

Name	Description	Pbl	Unit
SM	Volumetric moisture content in root zone	Y
SS	Surface storage (layer of water on surface)	N	cm
SSI	Initial urface storage	N	cm
W	Amount of water in root zone	N	cm
WI	Initial amount of water in the root zone	N	cm
WLOW	Amount of water in the subsoil (between current rooting depth and maximum rootable depth)	N	cm
WLOWI	Initial amount of water in the subsoil		cm
WWLOW	Total amount of water in the soil profile WWLOW = WLOW + W	N	cm
WTRAT	Total water lost as transpiration as calculated by the water balance. This can be different from the CTRAT variable which only counts transpiration for a crop cycle.	N	cm
EVST	Total evaporation from the soil surface	N	cm
EVWT	Total evaporation from a water surface	N	cm
TSR	Total surface runoff	N	cm
RAINT	Total amount of rainfall (eff + non-eff)	N	cm
WDRT	Amount of water added to root zone by increase of root growth	N	cm
TOTINF	Total amount of infiltration	N	cm
TOTIRR	Total amount of effective irrigation	N	cm
PERCT	Total amount of water percolating from rooted zone to subsoil	N	cm
LOSST	Total amount of water lost to deeper soil	N	cm
DSOS	Days since oxygen stress, accumulates the number of consecutive days of oxygen stress	Y
WBALRT	Checksum for root zone waterbalance. Will be calculated within finalize(), abs(WBALRT) > 0.0001 will raise a WaterBalanceError	N	cm
WBALTT	Checksum for total waterbalance. Will be calculated within finalize(), abs(WBALTT) > 0.0001 will raise a WaterBalanceError	N	cm

Rate variables:

External dependencies:

Name	Description	Provided by	Unit
TRA	Crop transpiration rate	Evapotranspiration	$cm day^{-1}$
EVSMX	Maximum evaporation rate from a soil surface below the crop canopy	Evapotranspiration	$cm day^{-1}$
EVWMX	Maximum evaporation rate from a water surface below the crop canopy	Evapotranspiration	$cm day^{-1}$
RD	Rooting depth	Root_dynamics	cm

Exceptions raised:

A WaterbalanceError is raised when the waterbalance is not closing at the end of the simulation cycle (e.g water has “leaked” away).

class pcse.soil.WaterBalanceLayered(**kwargs)[source]

This implements a layered water balance to estimate soil water availability for crop growth and water stress.

The classic free-drainage water-balance had some important limitations such as the inability to take into account differences in soil texture throughout the profile and its impact on soil water flow. Moreover, in the single layer water balance, rainfall or irrigation will become immediately available to the crop. This is incorrect physical behaviour and in many situations it leads to a very quick recovery of the crop after rainfall since all the roots have immediate access to infiltrating water. Therefore, with more detailed soil data becoming available a more realistic soil water balance was deemed necessary to better simulate soil processes and its impact on crop growth.

The multi-layer water balance represents a compromise between computational complexity, realistic simulation of water content and availability of data to calibrate such models. The model still runs on a daily time step but does implement the concept of downward and upward flow based on the concept of hydraulic head and soil water conductivity. The latter are combined in the so-called Matric Flux Potential. The model computes two types of flow of water in the soil:

a “dry flow” from the matric flux potentials (e.g. the suction gradient between layers)

a “wet flow” under the current layer conductivities and downward gravity.

Clearly, only the dry flow may be negative (=upward). The dry flow accounts for the large gradient in water potential under dry conditions (but neglects gravity). The wet flow takes into account gravity only and will dominate under wet conditions. The maximum of the dry and wet flow is taken as the downward flow, which is then further limited in order the prevent (a) oversaturation and (b) water content to decrease below field capacity. Upward flow is just the dry flow when it is negative. In this case the flow is limited to a certain fraction of what is required to get the layers at equal potential, taking into account, however, the contribution of an upward flow from further down.

The configuration of the soil layers is variable but is bound to certain limitations:

The layer thickness cannot be made too small. In practice, the top layer should not be smaller than 10 to 20 cm. Smaller layers would require smaller time steps than one day to simulate realistically, since rain storms will fill up the top layer very quickly leading to surface runoff because the model cannot handle the infiltration of the rainfall in a single timestep (a day).
The crop maximum rootable depth must coincide with a layer boundary. This is to avoid that roots can directly access water below the rooting depth. Of course such water may become available gradually by upward flow of moisture at some point during the simulation.

The current python implementation does not yet implement the impact of shallow groundwater but this will be added in future versions of the model.

For an introduction to the concept of Matric Flux Potential see for example:

Pinheiro, Everton Alves Rodrigues, et al. “A Matric Flux Potential Approach to Assess Plant Water Availability in Two Climate Zones in Brazil.” Vadose Zone Journal, vol. 17, no. 1, Jan. 2018, pp. 1–10. https://doi.org/10.2136/vzj2016.09.0083.

Note: the current implementation of the model (April 2024) is rather ‘Fortran-ish’. This has been done on purpose to allow comparisons with the original code in Fortran90. When we are sure that the implementation performs properly, we can refactor this in to a more functional structure instead of the current code which is too long and full of loops.

Simulation parameters:

Besides the parameters in the table below, the multi-layer waterbalance requires a SoilProfileDescription which provides the properties of the different soil layers. See the SoilProfile and SoilLayer classes for the details.

Name	Description	Unit
NOTINF	Maximum fraction of rain not-infiltrating into the soil
IFUNRN	Indicates whether non-infiltrating fraction of SSi rain is a function of storm size (1) or not (0)
SSI	Initial surface storage	cm
SSMAX	Maximum surface storage	cm
SMLIM	Maximum soil moisture content of top soil layer	cm3/cm3
WAV	Initial amount of water in the soil	cm

State variables:

Name	Description	Unit
WTRAT	Total water lost as transpiration as calculated by the water balance. This can be different from the CTRAT variable which only counts transpiration for a crop cycle.	cm
EVST	Total evaporation from the soil surface	cm
EVWT	Total evaporation from a water surface	cm
TSR	Total surface runoff	cm
RAINT	Total amount of rainfall (eff + non-eff)	cm
WDRT	Amount of water added to root zone by increase of root growth	cm
TOTINF	Total amount of infiltration	cm
TOTIRR	Total amount of effective irrigation	cm
SM	Volumetric moisture content in the different soil layers (array)
WC	Water content in the different soil layers (array)	cm
W	Amount of water in root zone	cm
WLOW	Amount of water in the subsoil (between current rooting depth and maximum rootable depth)	cm
WWLOW	Total amount of water in the soil profile (WWLOW = WLOW + W)	cm
WBOT	Water below maximum rootable depth and unavailable for plant growth.	cm
WAVUPP	Plant available water (above wilting point) in the rooted zone.	cm
WAVLOW	Plant available water (above wilting point) in the potential root zone (below current roots)	cm
WAVBOT	Plant available water (above wilting point) in the zone below the maximum rootable depth	cm
SS	Surface storage (layer of water on surface)	cm
SM_MEAN	Mean water content in rooted zone	cm3/cm3
PERCT	Total amount of water percolating from rooted zone to subsoil	cm
LOSST	Total amount of water lost to deeper soil	cm

Rate variables

Name	Description	Unit
Flow	Rate of flow from one layer to the next	cm/day
RIN	Rate of infiltration at the surface	cm/day
WTRALY	Rate of transpiration from the different soil layers (array)	cm/day
WTRA	Total crop transpiration rate accumulated over soil layers.	cm/day
EVS	Soil evaporation rate	cm/day
EVW	Open water evaporation rate	cm/day
RIRR	Rate of irrigation	cm/day
DWC	Net change in water amount per layer (array)	cm/day
DRAINT	Change in rainfall accumlation	cm/day
DSS	Change in surface storage	cm/day
DTSR	Rate of surface runoff	cm/day
BOTTOMFLOW	Flow of the bottom of the profile	cm/day

class pcse.soil.soil_profile.SoilProfile(parvalues)[source]

A component that represents the soil column as required by the multilayer waterbalance and SNOMIN.

Parameters: parvalues – a ParameterProvider instance that will be used to retrieve the description of the soil profile which is assumed to be available under the key SoilProfileDescription.

This class is basically a container that stores SoilLayer instances with some additional logic mainly related to root growth, root status and root water extraction. For detailed information on the properties of the soil layers have a look at the description of the SoilLayer class.

The description of the soil profile can be defined in YAML format with an example of the structure given below. In this case first three soil physical types are defined under the section SoilLayerTypes. Next, these SoilLayerTypes are used to define an actual soil profile using two upper layers of 10 cm of type TopSoil, three layers of 10, 20 and 30 cm of type MidSoil, a lower layer of 45 cm of type SubSoil and finally a SubSoilType with a thickness of 200 cm. Only the top 3 layers contain a certain amaount of organic carbon (FSOMI).

An example of a data structure for the soil profile:

SoilLayerTypes:
    TopSoil: &TopSoil
        SMfromPF: [-1.0,     0.366,
                    1.0,     0.338,
                    1.3,     0.304,
                    1.7,     0.233,
                    2.0,     0.179,
                    2.3,     0.135,
                    2.4,     0.123,
                    2.7,     0.094,
                    3.0,     0.073,
                    3.3,     0.059,
                    3.7,     0.046,
                    4.0,     0.039,
                    4.17,    0.037,
                    4.2,     0.036,
                    6.0,     0.02]
        CONDfromPF: [-1.0,     1.8451,
                      1.0,     1.02119,
                      1.3,     0.51055,
                      1.7,    -0.52288,
                      2.0,    -1.50864,
                      2.3,    -2.56864,
                      2.4,    -2.92082,
                      2.7,    -4.01773,
                      3.0,    -5.11919,
                      3.3,    -6.22185,
                      3.7,    -7.69897,
                      4.0,    -8.79588,
                      4.17,   -9.4318,
                      4.2,    -9.5376,
                      6.0,   -11.5376]
        CRAIRC:  0.090
        CNRatioSOMI: 9.0
        RHOD: 1.406
        Soil_pH: 7.4
        SoilID: TopSoil
    MidSoil: &MidSoil
        SMfromPF: [-1.0,     0.366,
                    1.0,     0.338,
                    1.3,     0.304,
                    1.7,     0.233,
                    2.0,     0.179,
                    2.3,     0.135,
                    2.4,     0.123,
                    2.7,     0.094,
                    3.0,     0.073,
                    3.3,     0.059,
                    3.7,     0.046,
                    4.0,     0.039,
                    4.17,    0.037,
                    4.2,     0.036,
                    6.0,     0.02]
        CONDfromPF: [-1.0,     1.8451,
                      1.0,     1.02119,
                      1.3,     0.51055,
                      1.7,    -0.52288,
                      2.0,    -1.50864,
                      2.3,    -2.56864,
                      2.4,    -2.92082,
                      2.7,    -4.01773,
                      3.0,    -5.11919,
                      3.3,    -6.22185,
                      3.7,    -7.69897,
                      4.0,    -8.79588,
                      4.17,   -9.4318,
                      4.2,    -9.5376,
                      6.0,   -11.5376]
        CRAIRC:  0.090
        CNRatioSOMI: 9.0
        RHOD: 1.406
        Soil_pH: 7.4
        SoilID: MidSoil_10
    SubSoil: &SubSoil
        SMfromPF: [-1.0,     0.366,
                    1.0,     0.338,
                    1.3,     0.304,
                    1.7,     0.233,
                    2.0,     0.179,
                    2.3,     0.135,
                    2.4,     0.123,
                    2.7,     0.094,
                    3.0,     0.073,
                    3.3,     0.059,
                    3.7,     0.046,
                    4.0,     0.039,
                    4.17,    0.037,
                    4.2,     0.036,
                    6.0,     0.02]
        CONDfromPF: [-1.0,     1.8451,
                      1.0,     1.02119,
                      1.3,     0.51055,
                      1.7,    -0.52288,
                      2.0,    -1.50864,
                      2.3,    -2.56864,
                      2.4,    -2.92082,
                      2.7,    -4.01773,
                      3.0,    -5.11919,
                      3.3,    -6.22185,
                      3.7,    -7.69897,
                      4.0,    -8.79588,
                      4.17,   -9.4318,
                      4.2,    -9.5376,
                      6.0,   -11.5376]
        CRAIRC:  0.090
        CNRatioSOMI: 9.0
        RHOD: 1.406
        Soil_pH: 7.4
        SoilID: SubSoil_10
SoilProfileDescription:
    PFWiltingPoint: 4.2
    PFFieldCapacity: 2.0
    SurfaceConductivity: 70.0 # surface conductivity cm / day
    SoilLayers:
    -   <<: *TopSoil
        Thickness: 10
        FSOMI: 0.02
    -   <<: *TopSoil
        Thickness: 10
        FSOMI: 0.02
    -   <<: *MidSoil
        Thickness: 10
        FSOMI: 0.01
    -   <<: *MidSoil
        Thickness: 20
        FSOMI: 0.00
    -   <<: *MidSoil
        Thickness: 30
        FSOMI: 0.00
    -   <<: *SubSoil
        Thickness: 45
        FSOMI: 0.00
    SubSoilType:
        <<: *SubSoil
        Thickness: 200
    GroundWater: null

class pcse.soil.soil_profile.SoilLayer(**kwargs)[source]

Contains the intrinsic and derived properties for each soil layers as required by the multilayer waterbalance and SNOMIN.

Parameters

layer – a soil layer definition providing parameter values for this layer, see table below.
PFFieldcapacity – the pF value for defining Field Capacity
PFWiltingPoint – the pF value for defining the Wilting Point

The following properties have to be defined for each layer.

Name	Description	Unit
CONDfromPF	Table function of the 10-base logarithm of the unsaturated hydraulic conductivity as a function of pF.	log10(cm water d-1), -
SMfromPF	Table function that describes the soil moisture content as a function of pF	m3 water m-3 soil, -
Thickness	Layer thickness	cm
FSOMI	Initial fraction of soil organic matter in soil	kg OM kg-1 soil
CNRatioSOMI	Initial C:N ratio of soil organic matter	kg C kg-1 N
RHOD	Bulk density of the soil	g soil cm-3 soil
Soil_pH	pH of the soil layer
CRAIRC	Critical air content for aeration for root system	m3 air m-3 soil

Based on the soil layer definition the following properties are derived from the parameters in the table above.

Name	Description	Unit
PFfromSM	Afgen table providing the inverted SMfromPF curve	m3 water m-3 soil, -
MFPfromPF	AfTen table describing the Matric Flux Potential as a function of the hydraulic head (pF).	cm2 d-1
SM0	The volumetric soil moisture content at saturation (pF = -1)	m3 water m-3 soil
SMW	The volumetric soil moisture content at wilting point	m3 water m-3 soil
SMFCF	The volumetric soil moisture content at field capacity	m3 water m-3 soil
WC0	The soil moisture amount (cm) at saturation (pF = -1)	cm water
WCW	The soil moisture amount (cm) at wilting point	cm water
WCFC	The soil moisture amount (cm) at field capacity	cm water
CondFC	Soil hydraulic conductivity at field capacity	cm water d-1
CondK0	Soil hydraulic conductivity at saturation	cm water d-1

Finally rooting_status is initialized to None (not yet known at initialization).

class pcse.soil.SnowMAUS(**kwargs)[source]

Simple snow accumulation model for agrometeorological applications.

This is an implementation of the SnowMAUS model which describes the accumulation and melt of snow due to precipitation, snowmelt and sublimation. The SnowMAUS model is designed to keep track of the thickness of the layer of water that is present as snow on the surface, e.g. the Snow Water Equivalent Depth (state variable SWEDEPTH [cm]). Conversion of the SWEDEPTH to the actual snow depth (state variable SNOWDEPTH [cm]) is done by dividing the SWEDEPTH with the snow density in [cm_water/cm_snow].

Snow density is taken as a fixed value despite the fact that the snow density is known to vary with the type of snowfall, the temperature and the age of the snow pack. However, more complicated algorithms for snow density would not be consistent with the simplicy of SnowMAUS.

A drawback of the current implementation is that there is no link to the water balance yet.

Reference: M. Trnka, E. Kocmánková, J. Balek, J. Eitzinger, F. Ruget, H. Formayer, P. Hlavinka, A. Schaumberger, V. Horáková, M. Možný, Z. Žalud, Simple snow cover model for agrometeorological applications, Agricultural and Forest Meteorology, Volume 150, Issues 7–8, 15 July 2010, Pages 1115-1127, ISSN 0168-1923

http://dx.doi.org/10.1016/j.agrformet.2010.04.012

Simulation parameters: (provide in crop, soil and sitedata dictionary)

Name	Description	Type	Unit
TMINACCU1	Upper critical minimum temperature for snow accumulation.	SSi	$^{\circ}C$
TMINACCU2	Lower critical minimum temperature for snow accumulation	SSi	$^{\circ}C$
TMINCRIT	Critical minimum temperature for snow melt	SSi	$^{\circ}C$
TMAXCRIT	Critical maximum temperature for snow melt	SSi	$^{\circ}C$
RMELT	Melting rate per day per degree Celcius above the critical minimum temperature.	SSi	$cm^{\circ}C^{-1} day^{-1}$
SCTHRESHOLD	Snow water equivalent above which the sublimation is taken into account.	SSi	cm
SNOWDENSITY	Density of snow	SSi	cm/cm
SWEDEPTHI	Initial depth of layer of water present as snow on the soil surface	SSi	cm

State variables:

Name	Description	Pbl	Unit
SWEDEPTH	Depth of layer of water present as snow on the surface	N	cm
SNOWDEPTH	Depth of snow present on the surface.	Y	cm

Rate variables:

Name	Description	Pbl	Unit
RSNOWACCUM	Rate of snow accumulation	N	$cm day^{-1}$
RSNOWSUBLIM	Rate of snow sublimation	N	$cm day^{-1}$
RSNOWMELT	Rate of snow melting	N	$cm day^{-1}$

Nitrogen and Carbon modules

PCSE contains two modules for nitrogen and carbon in the soil:

The simple N_Soil_Dynamics module which only simulates N availability as a pool of available N without any dynamic processes like leach, volatilization, etc.
The SNOMIN module (Soil Nitrogen module for Mineral and Inorganic Nitrogen) which is a layered soil carbon/nitrogen balance that also requires the layered soil water balance. It includes the full N dynamics in the soil as well as the impact of organic matter and organic amendments (manure) on the availability of nitrogen in the soil.

class pcse.soil.N_Soil_Dynamics(**kwargs)[source]

A simple module for soil N dynamics.

This modules represents the soil as a bucket for available N consisting of two components: 1) a native soil supply which consists of an initial amount of N which will become available with a fixed fraction every day and 2) an external supply which is computed as an amount of N supplied and multiplied by a recovery fraction in order to have an effective amount of N that is available for crop growth.

This module does not simulate any soil physiological processes and is only a book-keeping approach for N availability. On the other hand, it requires no detailed soil parameters. Only an initial soil amount, the fertilizer inputs, a recovery fraction and a background supply.

Simulation parameters

Name	Description	Type	Unit
NSOILBASE	Base soil supply of N available through mineralisation	SSi	kg ha^-1
NSOILBASE_FR	Fraction of base soil N that comes available every day	SSi
NAVAILI	Initial N available in the N pool	SSi	kg ha^-1
BG_N_SUPPLY	Background supply of N through atmospheric deposition.	SSi	kg ha^-1day^-1

State variables

Name	Description	Pbl	Unit
NSOIL	total mineral soil N available at start of growth period	N	[kg ha-1]
NAVAIL	Total mineral N from soil and fertiliser	Y	kg ha^-1

Rate variables

Signals send or handled

N_Soil_Dynamics receives the following signals:

APPLY_N: Is received when an external input from N fertilizer is provided. See _on_APPLY_N() for details.

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
TRA	Actual crop transpiration increase	Evapotranspiration	$cm$
TRAMX	Potential crop transpiration increase	Evapotranspiration	$cm$
RNuptake	Rate of N uptake by the crop	NPK_Demand_Uptake	kg ha^-1day^-1

class pcse.soil.SNOMIN(**kwargs)[source]

SNOMIN (Soil Nitrogen module for Mineral and Inorganic Nitrogen) is a layered soil nitrogen balance. A full mathematical description of the model is given by Berghuijs et al (2024).

Berghuijs HNC, Silva JV, Reidsma P, De Wit AJW (2024) Expanding the WOFOST crop model to explore options for sustainable nitrogen management: A study for winter wheat in the Netherlands. European Journal of Agronomy 154 ARTN 127099. https://doi.org/10.1016/j.eja.2024.127099

Simulation parameters:

Name	Description	Unit
A0SOM	Initial age of soil organic material	y
CNRatioBio	C:N ratio of microbial biomass	kg C kg-1 N
FASDIS	Fraction of assimilation to dissimilation
KDENIT_REF	Reference first order denitrification rate constant	d-1
KNIT_REF	Reference first order nitrification rate constant	d-1
KSORP	Sorption coefficient ammonium (m3 water kg-1 soil)	m3 soil kg-1 soil
MRCDIS	Michaelis Menten constant for response factor denitrification to soil respiration	kg C m-2 d-1
NO3ConcR	NO3-N concentration in rain water	mg NO3–N L- water
NH4ConcR	NH4-N concentration in rain water	mg NH4+-N L-1 water
NO3I	Initial amount of NO3-N ¹	kg NO3–N ha-1
NH4I	Initial amount of NH4-N ¹	kg NH4+-N ha-1)
WFPS_CRIT	Critical water filled pore space fraction	m3 water m-3 pore

¹ This state variable is defined for each soil layer

State variables

Name	Description	Unit
AGE	Appearant age of amendment (d) ¹	d
ORGMAT	Amount of organic matter (kg ORG ha-1) ¹	kg OM m-2
CORG	Amount of C in organic matter (kg C ha-1) ¹	kg C m-2
NORG	Amount of N in organic matter (kg N ha-1) ¹	kg N m-2
NH4	Amount of NH4-N (kg N ha-1) ²	kg NH4-N m-2
NO3	Amount of NO3-N (kg N ha-1) ²	kg NO3-N m-2

¹ This state variable is defined for each combination of soil layer and amendment

² This state variable is defined for each soil layer

Rate variables

Name	Description	Unit
RAGE	Rate of change of apparent age ²	d d-1
RAGEAM	Initial apparent age ²	d d-1
RAGEAG	Rate of ageing of amendment ²	d d-1
RCORG	Rate of change of organic C ²	kg C m-2 d-1
RCORGAM	Rate pf application organic C ²	kg C m-2 d-1
RCORGDIS	Dissimilation rate of organic C ²	kg C m-2 d-1
RNH4	Rate of change amount of NH4+-N ¹	kg NH4+-N m-2 d-1
RNH4AM	Rate of NH4+-N application ¹	kg NH4+-N m-2 d-1
RNH4DEPOS	Rate of NH4-N deposition ¹	kg NH4+-N m-2 d-1
RNH4IN	Rate of NH4+-N inflow from adjacent layer ¹	kg NH4+-N m-2 d-1
RNH4MIN	Net rate of mineralization ¹	kg NH4+-N m-2 d-1
RNH4NITR	Rate of nitrification ¹	kg NH4+-N m-2 d-1
RNH4OUT	Rate of NH4+-N outflow to adjacent layer ¹	kg NH4+-N m-2 d-1
RNH4UP	Rate of NH4+-N root uptake ¹	kg NH4+-N m-2 d-1
RNO3	Rate of change amount of NO3–N ¹	kg NO3–N m-2 d-1
RNO3AM	Rate of NO3–N application ¹	kg NO3–N m-2 d-1
RNO3DENITR	Rate of denitrification ¹	kg NO3–N m-2 d-1
RNO3DEPOS	Rate of NO3–N deposition ¹	kg NO3–N m-2 d-1
RNO3IN	Rate of NH4+-N inflow from adjacent layer ¹	kg NO3+-N m-2 d-1
RNO3NITR	Rate of nitrification ¹	kg NO3–N m-2 d-1
RNO3OUT	Rate of NO3–N outflow to adjacent layer ¹	kg NO3–N m-2 d-1
RNO3UP	Rate of NO3–N root uptake ¹	kg NO3–N m-2 d-1
RNORG	Rate of change of organic N ²	kg N m-2 d-1
RNORGAM	Rate pf application organic N ²	kg N m-2 d-1
RNORGDIS	Dissimilation rate of organic matter ²	kg N m-2 d-1
RORGMAT	Rate of change of organic material ²	kg OM m-2 d-1
RORGMATAM	Rate of application organic matter ²	kg OM m-2 d-1
RORGMATDIS	Dissimilation rate of organic matter ²	kg OM m-2 d-1

¹ This state variable is defined for each soil layer

² This state variable is defined for each combination of soil layer and amendment

Signals send or handled

SNOMIN receives the following signals:

APPLY_N_SNOMIN: Is received when an external input from N fertilizer is provided. See _on_APPLY_N_SNOMIN() and signals.apply_n_snomin for details.

Crop simulation processes for WOFOST

Phenology

class pcse.crop.phenology.DVS_Phenology(**kwargs)[source]

Implements the algorithms for phenologic development in WOFOST.

Phenologic development in WOFOST is expresses using a unitless scale which takes the values 0 at emergence, 1 at Anthesis (flowering) and 2 at maturity. This type of phenological development is mainly representative for cereal crops. All other crops that are simulated with WOFOST are forced into this scheme as well, although this may not be appropriate for all crops. For example, for potatoes development stage 1 represents the start of tuber formation rather than flowering.

Phenological development is mainly governed by temperature and can be modified by the effects of day length and vernalization during the period before Anthesis. After Anthesis, only temperature influences the development rate.

Simulation parameters

Name	Description	Type	Unit
TSUMEM	Temperature sum from sowing to emergence	SCr	$^{\circ}C$ day
TBASEM	Base temperature for emergence	SCr	$^{\circ}C$
TEFFMX	Maximum effective temperature for emergence	SCr	$^{\circ}C$
TSUM1	Temperature sum from emergence to anthesis	SCr	$^{\circ}C$ day
TSUM2	Temperature sum from anthesis to maturity	SCr	$^{\circ}C$ day
IDSL	Switch for phenological development options temperature only (IDSL=0), including daylength (IDSL=1) and including vernalization (IDSL>=2)	SCr SCr
DLO	Optimal daylength for phenological development	SCr	hr
DLC	Critical daylength for phenological development	SCr	hr
DVSI	Initial development stage at emergence. Usually this is zero, but it can be higher for crops that are transplanted (e.g. paddy rice)	SCr
DVSEND	Final development stage	SCr
DTSMTB	Daily increase in temperature sum as a function of daily mean temperature.	TCr	$^{\circ}C$

State variables

Name	Description	Pbl	Unit
DVS	Development stage	Y
TSUM	Temperature sum	N	$^{\circ}C$ day
TSUME	Temperature sum for emergence	N	$^{\circ}C$ day
DOS	Day of sowing	N
DOE	Day of emergence	N
DOA	Day of Anthesis	N
DOM	Day of maturity	N
DOH	Day of harvest	N
STAGE	Current phenological stage, can take the folowing values: emerging\|vegetative\|reproductive\|mature	N

Rate variables

Name	Description	Pbl	Unit
DTSUME	Increase in temperature sum for emergence	N	$^{\circ}C$
DTSUM	Increase in temperature sum for anthesis or maturity	N	$^{\circ}C$
DVR	Development rate	Y	day^-1

External dependencies:

None

Signals sent or handled

DVS_Phenology sends the crop_finish signal when maturity is reached and the end_type is ‘maturity’ or ‘earliest’.

class pcse.crop.phenology.Vernalisation(**kwargs)[source]

Modification of phenological development due to vernalisation.

The vernalization approach here is based on the work of Lenny van Bussel (2011), which in turn is based on Wang and Engel (1998). The basic principle is that winter wheat needs a certain number of days with temperatures within an optimum temperature range to complete its vernalisation requirement. Until the vernalisation requirement is fulfilled, the crop development is delayed.

The rate of vernalization (VERNR) is defined by the temperature response function VERNRTB. Within the optimal temperature range 1 day is added to the vernalisation state (VERN). The reduction on the phenological development is calculated from the base and saturated vernalisation requirements (VERNBASE and VERNSAT). The reduction factor (VERNFAC) is scaled linearly between VERNBASE and VERNSAT.

A critical development stage (VERNDVS) is used to stop the effect of vernalisation when this DVS is reached. This is done to improve model stability in order to avoid that Anthesis is never reached due to a somewhat too high VERNSAT. Nevertheless, a warning is written to the log file, if this happens.

Van Bussel, 2011. From field to globe: Upscaling of crop growth modelling. Wageningen PhD thesis. http://edepot.wur.nl/180295
Wang and Engel, 1998. Simulation of phenological development of wheat crops. Agric. Systems 58:1 pp 1-24

Simulation parameters (provide in cropdata dictionary)

Name	Description	Type	Unit
VERNSAT	Saturated vernalisation requirements	SCr	days
VERNBASE	Base vernalisation requirements	SCr	days
VERNRTB	Rate of vernalisation as a function of daily mean temperature.	TCr
VERNDVS	Critical development stage after which the effect of vernalisation is halted	SCr

State variables

Name	Description	Pbl	Unit
VERN	Vernalisation state	N	days
DOV	Day when vernalisation requirements are fulfilled.	N
ISVERNALISED	Flag indicated that vernalisation requirement has been reached	Y

Rate variables

Name	Description	Pbl	Unit
VERNR	Rate of vernalisation	N
VERNFAC	Reduction factor on development rate due to vernalisation effect.	Y

External dependencies:

Name	Description	Provided by	Unit
DVS	Development Stage Used only to determine if the critical development stage for vernalisation (VERNDVS) is reached.	Phenology

Partitioning

class pcse.crop.partitioning.DVS_Partitioning(**kwargs)[source]

Class for assimilate partioning based on development stage (DVS).

DVS_partioning calculates the partitioning of the assimilates to roots, stems, leaves and storage organs using fixed partitioning tables as a function of crop development stage. The available assimilates are first split into below-ground and abovegrond using the values in FRTB. In a second stage they are split into leaves (FLTB), stems (FSTB) and storage organs (FOTB).

Since the partitioning fractions are derived from the state variable DVS they are regarded state variables as well.

Simulation parameters (To be provided in cropdata dictionary):

Name	Description	Type
FRTB	Partitioning to roots as a function of development stage.	TCr
FSTB	Partitioning to stems as a function of development stage.	TCr
FLTB	Partitioning to leaves as a function of development stage.	TCr
FOTB	Partitioning to storage organs as a function of development stage.	TCr

State variables

Name	Description	Pbl
FR	Fraction partitioned to roots.	Y
FS	Fraction partitioned to stems.	Y
FL	Fraction partitioned to leaves.	Y
FO	Fraction partitioned to storage orgains	Y

Rate variables

None

Signals send or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology

Exceptions raised

A PartitioningError is raised if the partitioning coefficients to leaves, stems and storage organs on a given day do not add up to ‘1’.

CO₂ Assimilation

class pcse.crop.assimilation.WOFOST72_Assimilation(**kwargs)[source]

Class implementing a WOFOST/SUCROS style assimilation routine.

WOFOST calculates the daily gross CO₂ assimilation rate of a crop from the absorbed radiation and the photosynthesis-light response curve of individual leaves. This response is dependent on temperature and leaf age. The absorbed radiation is calculated from the total incoming radiation and the leaf area. Daily gross CO₂ assimilation is obtained by integrating the assimilation rates over the leaf layers and over the day.

Simulation parameters

Name	Description	Type	Unit
AMAXTB	Max. leaf CO₂ assim. rate as a function of of DVS	TCr	kg ha^-1hr^-1
EFFTB	Light use effic. single leaf as a function of daily mean temperature	TCr	kg ha^-1hr^-1/(J m^-2sec^-1)
KDIFTB	Extinction coefficient for diffuse visible as function of DVS	TCr
TMPFTB	Reduction factor of AMAX as function of daily mean temperature.	TCr
TMNFTB	Reduction factor of AMAX as function of daily minimum temperature.	TCr

State and rate variables

WOFOST_Assimilation returns the potential gross assimilation rate ‘PGASS’ directly from the __call__() method, but also includes it as a rate variable.

Rate variables:

Name	Description	Pbl	Unit
PGASS	Potential assimilation rate	N	kg CH₂O ha^-1day^-1

Signals sent or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	Leaf_dynamics

class pcse.crop.assimilation.WOFOST73_Assimilation(**kwargs)[source]

Class implementing a WOFOST/SUCROS style assimilation routine including effect of changes in atmospheric CO2 concentration.

WOFOST calculates the daily gross CO₂ assimilation rate of a crop from the absorbed radiation and the photosynthesis-light response curve of individual leaves. This response is dependent on temperature and leaf age. The absorbed radiation is calculated from the total incoming radiation and the leaf area. Daily gross CO₂ assimilation is obtained by integrating the assimilation rates over the leaf layers and over the day.

The impact of atmospheric CO₂ is implemented by applying empirical adjustments to the AMAX at every development stage (parameter CO2AMAXTB) and EFF (parameter CO2EFFTB). The latter two are defined as a function of atmospheric CO₂ concentration.

Simulation parameters (To be provided in cropdata dictionary):

Name	Description	Type	Unit
AMAXTB	Max. leaf CO₂ assim. rate as a function of of DVS	TCr	kg ha^-1hr^-1
EFFTB	Light use effic. single leaf as a function of daily mean temperature	TCr	kg ha^-1hr^-1/(J m^-2sec^-1)
KDIFTB	Extinction coefficient for diffuse visible as function of DVS	TCr
TMPFTB	Reduction factor of AMAX as function of daily mean temperature.	TCr
TMPFTB	Reduction factor of AMAX as function of daily minimum temperature.	TCr
CO2AMAXTB	Correction factor for AMAX given atmos- pheric CO2 concentration.	TCr
CO2EFFTB	Correction factor for EFF given atmos- pheric CO2 concentration.	TCr
CO2	Atmopheric CO2 concentration	SCr	ppm

State and rate variables

WOFOST_Assimilation2 has no state/rate variables, but calculates the rate of assimilation which is returned directly from the __call__() method.

Signals sent or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	Leaf_dynamics

class pcse.crop.assimilation.WOFOST81_Assimilation(**kwargs)[source]

Class implementing a WOFOST/SUCROS style assimilation routine including effect of changes in atmospheric CO2 concentration and impact of leaf nitrogen content on the maximum assimilation rate.

WOFOST calculates the daily gross CO₂ assimilation rate of a crop from the absorbed radiation and the photosynthesis-light response curve of individual leaves. This response is dependent on temperature and leaf age. The absorbed radiation is calculated from the total incoming radiation and the leaf area. Daily gross CO₂ assimilation is obtained by integrating the assimilation rates over the leaf layers and over the day.

Simulation parameters (To be provided in cropdata dictionary):

Name	Description	Type	Unit
AMAX_LNB	Specific leaf nitrogen below which there is no gross photosynthesis	Cr	kg ha^-1
AMAX_REF	Maximum leaf CO2 assim. rate under reference conditions and high specific leaf nitrogen.	TCr	kg ha^-1hr^-1
AMAX_SLP	Slope of linear response of AMAX to specific leaf nitrogen content at reference conditions	Cr Cr	\|kg hr-1 kg-1\|
KN	Extinction coefficient of N in the canopy	Cr
EFFTB	Light use effic. single leaf as a function of daily mean temperature	TCr	kg ha^-1hr^-1/(J m^-2sec^-1)
KDIFTB	Extinction coefficient for diffuse visible as function of DVS	TCr
TMPFTB	Reduction factor of AMAX as function of daily mean temperature.	TCr
TMPFTB	Reduction factor of AMAX as function of daily minimum temperature.	TCr
CO2AMAXTB	Correction factor for AMAX given atmos- pheric CO2 concentration.	TCr
CO2EFFTB	Correction factor for EFF given atmos- pheric CO2 concentration.	TCr
CO2	Atmopheric CO2 concentration	SCr	ppm

State and rate variables

WOFOST_Assimilation has no state/rate variables, but calculates the rate of assimilation which is returned directly from the __call__() method.

Signals sent or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	leaf_dynamics
NLV	Leaf nitrogen amount	n_dynamics	kg ha-1

Maintenance respiration

class pcse.crop.respiration.WOFOST_Maintenance_Respiration(**kwargs)[source]

Maintenance respiration in WOFOST

WOFOST calculates the maintenance respiration as proportional to the dry weights of the plant organs to be maintained, where each plant organ can be assigned a different maintenance coefficient. Multiplying organ weight with the maintenance coeffients yields the relative maintenance respiration (RMRES) which is than corrected for senescence (parameter RFSETB). Finally, the actual maintenance respiration rate is calculated using the daily mean temperature, assuming a relative increase for each 10 degrees increase in temperature as defined by Q10.

Simulation parameters: (To be provided in cropdata dictionary):

Name	Description	Type	Unit
Q10	Relative increase in maintenance repiration rate with each 10 degrees increase in temperature	SCr
RMR	Relative maintenance respiration rate for roots	SCr	kg CH₂O kg^-1d^-1
RMS	Relative maintenance respiration rate for stems	SCr	kg CH₂O kg^-1d^-1
RML	Relative maintenance respiration rate for leaves	SCr	kg CH₂O kg^-1d^-1
RMO	Relative maintenance respiration rate for storage organs	SCr	kg CH₂O kg^-1d^-1

State and rate variables:

WOFOSTMaintenanceRespiration returns the potential maintenance respiration PMRES

directly from the __call__() method, but also includes it as a rate variable within the object.

Rate variables:

Name	Description	Pbl	Unit
PMRES	Potential maintenance respiration rate	N	kg CH₂O ha^-1day^-1

Signals send or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
WRT	Dry weight of living roots	WOFOST_Root_Dynamics	kg ha^-1
WST	Dry weight of living stems	WOFOST_Stem_Dynamics	kg ha^-1
WLV	Dry weight of living leaves	WOFOST_Leaf_Dynamics	kg ha^-1
WSO	Dry weight of living storage organs	WOFOST_Storage_Organ_Dynamics	kg ha^-1

Evapotranspiration

class pcse.crop.evapotranspiration.Evapotranspiration(**kwargs)[source]

Calculation of potential evaporation (water and soil) rates and actual crop transpiration rate.

Simulation parameters:

Name	Description	Type
CFET	Correction factor for potential transpiration rate.	SCr
DEPNR	Dependency number for crop sensitivity to soil moisture stress.	SCr
KDIFTB	Extinction coefficient for diffuse visible as function of DVS.	TCr
IOX	Switch oxygen stress on (1) or off (0)	SCr
IAIRDU	Switch airducts on (1) or off (0)	SCr
CRAIRC	Critical air content for root aeration	SSo
SM0	Soil porosity	SSo
SMW	Volumetric soil moisture content at wilting point	SSo
SMCFC	Volumetric soil moisture content at field capacity	SSo
SM0	Soil porosity	SSo

State variables

Note that these state variables are only assigned after finalize() has been run.

Name	Description	Pbl	Unit
IDWST	Nr of days with water stress.	N
IDOST	Nr of days with oxygen stress.	N

Rate variables

Name	Description	Pbl	Unit
EVWMX	Maximum evaporation rate from an open water surface.	Y	cm day^-1
EVSMX	Maximum evaporation rate from a wet soil surface.	Y	cm day^-1
TRAMX	Maximum transpiration rate from the plant canopy	Y	cm day^-1
TRA	Actual transpiration rate from the plant canopy	Y	cm day^-1
IDOS	Indicates oxygen stress on this day (True\|False)	N
IDWS	Indicates water stress on this day (True\|False)	N
RFWS	Reduction factor for water stress	N
RFOS	Reduction factor for oxygen stress	N
RFTRA	Reduction factor for transpiration (wat & ox)	Y

Signals send or handled

None

External dependencies:

Name	Description	Provided by
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	Leaf_dynamics
SM	Volumetric soil moisture content	Waterbalance

class pcse.crop.evapotranspiration.EvapotranspirationCO2(**kwargs)[source]

Calculation of evaporation (water and soil) and transpiration rates taking into account the CO2 effect on crop transpiration.

Simulation parameters (To be provided in cropdata dictionary):

Name	Description	Type	Unit
CFET	Correction factor for potential transpiration rate.	S
DEPNR	Dependency number for crop sensitivity to soil moisture stress.	S
KDIFTB	Extinction coefficient for diffuse visible as function of DVS.	T
IOX	Switch oxygen stress on (1) or off (0)	S
IAIRDU	Switch airducts on (1) or off (0)	S
CRAIRC	Critical air content for root aeration	S
SM0	Soil porosity	S
SMW	Volumetric soil moisture content at wilting point	S
SMCFC	Volumetric soil moisture content at field capacity	S
SM0	Soil porosity	S
CO2	Atmospheric CO2 concentration	S	ppm
CO2TRATB	Reduction factor for TRAMX as function of atmospheric CO2 concentration	T

State variables

Note that these state variables are only assigned after finalize() has been run.

Name	Description	Pbl	Unit
IDWST	Nr of days with water stress.	N
IDOST	Nr of days with oxygen stress.	N

Rate variables

Name	Description	Pbl	Unit
EVWMX	Maximum evaporation rate from an open water surface.	Y	cm day^-1
EVSMX	Maximum evaporation rate from a wet soil surface.	Y	cm day^-1
TRAMX	Maximum transpiration rate from the plant canopy	Y	cm day^-1
TRA	Actual transpiration rate from the plant canopy	Y	cm day^-1
IDOS	Indicates water stress on this day (True\|False)	N
IDWS	Indicates oxygen stress on this day (True\|False)	N
RFWS	Reducation factor for water stress	Y
RFOS	Reducation factor for oxygen stress	Y
RFTRA	Reduction factor for transpiration (wat & ox)	Y

Signals send or handled

None

External dependencies:

Name	Description	Provided by
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	Leaf_dynamics
SM	Volumetric soil moisture content	Waterbalance

class pcse.crop.evapotranspiration.EvapotranspirationCO2Layered(**kwargs)[source]

Calculation of evaporation (water and soil) and transpiration rates taking into account the CO2 effect on crop transpiration for a layered soil

Simulation parameters (To be provided in cropdata dictionary):

Name	Description	Type	Unit
CFET	Correction factor for potential transpiration rate.	S
DEPNR	Dependency number for crop sensitivity to soil moisture stress.	S
KDIFTB	Extinction coefficient for diffuse visible as function of DVS.	T
IOX	Switch oxygen stress on (1) or off (0)	S
IAIRDU	Switch airducts on (1) or off (0)	S
CRAIRC	Critical air content for root aeration	S
SM0	Soil porosity	S
SMW	Volumetric soil moisture content at wilting point	S
SMCFC	Volumetric soil moisture content at field capacity	S
SM0	Soil porosity	S
CO2	Atmospheric CO2 concentration	S	ppm
CO2TRATB	Reduction factor for TRAMX as function of atmospheric CO2 concentration	T

State variables

Note that these state variables are only assigned after finalize() has been run.

Name	Description	Pbl	Unit
IDWST	Nr of days with water stress.	N
IDOST	Nr of days with oxygen stress.	N

Rate variables

Name	Description	Pbl	Unit
EVWMX	Maximum evaporation rate from an open water surface.	Y	cm day^-1
EVSMX	Maximum evaporation rate from a wet soil surface.	Y	cm day^-1
TRAMX	Maximum transpiration rate from the plant canopy	Y	cm day^-1
TRA	Actual transpiration rate from the plant canopy	Y	cm day^-1
IDOS	Indicates water stress on this day (True\|False)	N
IDWS	Indicates oxygen stress on this day (True\|False)	N
RFWS	Reducation factor for water stress	Y
RFOS	Reducation factor for oxygen stress	Y
RFTRA	Reduction factor for transpiration (wat & ox)	Y

Signals send or handled

None

External dependencies:

Name	Description	Provided by
DVS	Crop development stage	DVS_Phenology
LAI	Leaf area index	Leaf_dynamics
SM	Volumetric soil moisture content	Waterbalance

pcse.crop.evapotranspiration.SWEAF(ET0, DEPNR)[source]

Calculates the Soil Water Easily Available Fraction (SWEAF).

Parameters

ET0 – The evapotranpiration from a reference crop.
DEPNR – The crop dependency number.

The fraction of easily available soil water between field capacity and wilting point is a function of the potential evapotranspiration rate (for a closed canopy) in cm/day, ET0, and the crop group number, DEPNR (from 1 (=drought-sensitive) to 5 (=drought-resistent)). The function SWEAF describes this relationship given in tabular form by Doorenbos & Kassam (1979) and by Van Keulen & Wolf (1986; p.108, table 20) http://edepot.wur.nl/168025.

Leaf dynamics

class pcse.crop.leaf_dynamics.WOFOST_Leaf_Dynamics(**kwargs)[source]

Leaf dynamics for the WOFOST crop model.

Implementation of biomass partitioning to leaves, growth and senenscence of leaves. WOFOST keeps track of the biomass that has been partitioned to the leaves for each day (variable LV), which is called a leaf class). For each leaf class the leaf age (variable ‘LVAGE’) and specific leaf area (variable SLA) are also registered. Total living leaf biomass is calculated by summing the biomass values for all leaf classes. Similarly, leaf area is calculated by summing leaf biomass times specific leaf area (LV * SLA).

Senescense of the leaves can occur as a result of physiological age, drought stress or self-shading.

Simulation parameters (provide in cropdata dictionary)

Name	Description	Type	Unit
RGRLAI	Maximum relative increase in LAI.	SCr	ha ha-1 d-1
SPAN	Life span of leaves growing at 35 Celsius	SCr	day
TBASE	Lower threshold temp. for ageing of leaves	SCr	$^{\circ}C$
PERDL	Max. relative death rate of leaves due to water stress	SCr
TDWI	Initial total crop dry weight	SCr	kg ha^-1
KDIFTB	Extinction coefficient for diffuse visible light as function of DVS	TCr
SLATB	Specific leaf area as a function of DVS	TCr	ha kg^-1

State variables

Name	Description	Pbl	Unit
LV	Leaf biomass per leaf class	N	kg ha^-1
SLA	Specific leaf area per leaf class	N	ha kg^-1
LVAGE	Leaf age per leaf class	N	day
LVSUM	Sum of LV	N	kg ha^-1
LAIEM	LAI at emergence	N
LASUM	Total leaf area as sum of LV*SLA, not including stem and pod area	N N
LAIEXP	LAI value under theoretical exponential growth	N
LAIMAX	Maximum LAI reached during growth cycle	N
LAI	Leaf area index, including stem and pod area	Y
WLV	Dry weight of living leaves	Y	kg ha^-1
DWLV	Dry weight of dead leaves	N	kg ha^-1
TWLV	Dry weight of total leaves (living + dead)	Y	kg ha^-1

Rate variables

Name	Description	Pbl	Unit
GRLV	Growth rate leaves	N	kg ha^-1day^-1
DSLV1	Death rate leaves due to water stress	N	kg ha^-1day^-1
DSLV2	Death rate leaves due to self-shading	N	kg ha^-1day^-1
DSLV3	Death rate leaves due to frost kill	N	kg ha^-1day^-1
DSLV	Maximum of DLSV1, DSLV2, DSLV3	N	kg ha^-1day^-1
DALV	Death rate leaves due to aging.	N	kg ha^-1day^-1
DRLV	Death rate leaves as a combination of DSLV and DALV	N	kg ha^-1day^-1
SLAT	Specific leaf area for current time step, adjusted for source/sink limited leaf expansion rate.	N	ha kg^-1
FYSAGE	Increase in physiological leaf age	N
GLAIEX	Sink-limited leaf expansion rate (exponential curve)	N	ha ha^-1day^-1
GLASOL	Source-limited leaf expansion rate (biomass increase)	N	ha ha^-1day^-1

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
FL	Fraction biomass to leaves	DVS_Partitioning
FR	Fraction biomass to roots	DVS_Partitioning
SAI	Stem area index	WOFOST_Stem_Dynamics
PAI	Pod area index	WOFOST_Storage_Organ_Dynamics
TRA	Transpiration rate	Evapotranspiration	cm day^-1
TRAMX	Maximum transpiration rate	Evapotranspiration	cm day^-1
ADMI	Above-ground dry matter increase	CropSimulation	kg ha^-1day^-1
RF_FROST	Reduction factor frost kill	FROSTOL

class pcse.crop.leaf_dynamics.WOFOST_Leaf_Dynamics_N(**kwargs)[source]

Leaf dynamics for the WOFOST crop model including leaf response to N stress.

# HB 20220405: This function was changed quite a bit and needs redocumentation.

Implementation of biomass partitioning to leaves, growth and senenscence of leaves. WOFOST keeps track of the biomass that has been partitioned to the leaves for each day (variable LV), which is called a leaf class). For each leaf class the leaf age (variable ‘LVAGE’) and specific leaf area are (variable SLA) are also registered. Total living leaf biomass is calculated by summing the biomass values for all leaf classes. Similarly, leaf area is calculated by summing leaf biomass times specific leaf area (LV * SLA).

Senescense of the leaves can occur as a result of physiological age, drought stress, nutrient stress or self-shading.

Finally, leaf expansion (SLA) can be influenced by nutrient stress.

Simulation parameters (provide in cropdata dictionary)

Name	Description	Type	Unit
RGRLAI	Maximum relative increase in LAI.	SCr	ha ha-1 d-1
SPAN	Life span of leaves growing at 35 Celsius	SCr	day
TBASE	Lower threshold temp. for ageing of leaves	SCr	$^{\circ}C$
PERDL	Max. relative death rate of leaves due to water stress	SCr
TDWI	Initial total crop dry weight	SCr	kg ha^-1
KDIFTB	Extinction coefficient for diffuse visible light as function of DVS	TCr
SLATB	Specific leaf area as a function of DVS	TCr	ha kg^-1
RDRNS	max. relative death rate of leaves due to nutrient N stress	TCr
NLAI	coefficient for the reduction due to nutrient N stress of the LAI increase (during juvenile phase).	TCr
NSLA	Coefficient for the effect of nutrient NPK stress on SLA reduction	TCr
RDRNS	Max. relative death rate of leaves due to nutrient N stress	TCr

State variables

Name	Description	Pbl	Unit
LV	Leaf biomass per leaf class	N	kg ha^-1
SLA	Specific leaf area per leaf class	N	ha kg^-1
LVAGE	Leaf age per leaf class	N	day
LVSUM	Sum of LV	N	kg ha^-1
LAIEM	LAI at emergence	N
LASUM	Total leaf area as sum of LV*SLA, not including stem and pod area	N N
LAIEXP	LAI value under theoretical exponential growth	N
LAIMAX	Maximum LAI reached during growth cycle	N
LAI	Leaf area index, including stem and pod area	Y
WLV	Dry weight of living leaves	Y	kg ha^-1
DWLV	Dry weight of dead leaves	N	kg ha^-1
TWLV	Dry weight of total leaves (living + dead)	Y	kg ha^-1

Rate variables

Name	Description	Pbl	Unit
GRLV	Growth rate leaves	N	kg ha^-1day^-1
DSLV1	Death rate leaves due to water stress	N	kg ha^-1day^-1
DSLV2	Death rate leaves due to self-shading	N	kg ha^-1day^-1
DSLV3	Death rate leaves due to frost kill	N	kg ha^-1day^-1
DSLV4	Death rate leaves due to nutrient stress	N	kg ha^-1day^-1
DSLV	Maximum of DLSV1, DSLV2, DSLV3	N	kg ha^-1day^-1
DALV	Death rate leaves due to aging.	N	kg ha^-1day^-1
DRLV	Death rate leaves as a combination of DSLV and DALV	N	kg ha^-1day^-1
SLAT	Specific leaf area for current time step, adjusted for source/sink limited leaf expansion rate.	N	ha kg^-1
FYSAGE	Increase in physiological leaf age	N
GLAIEX	Sink-limited leaf expansion rate (exponential curve)	N	ha ha^-1day^-1
GLASOL	Source-limited leaf expansion rate (biomass increase)	N	ha ha^-1day^-1

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
FL	Fraction biomass to leaves	DVS_Partitioning
FR	Fraction biomass to roots	DVS_Partitioning
SAI	Stem area index	WOFOST_Stem_Dynamics
PAI	Pod area index	WOFOST_Storage_Organ_Dynamics
TRA	Transpiration rate	Evapotranspiration	cm day^-1
TRAMX	Maximum transpiration rate	Evapotranspiration	cm day^-1
ADMI	Above-ground dry matter increase	CropSimulation	kg ha^-1day^-1
RF_FROST	Reduction factor frost kill	FROSTOL

class pcse.crop.leaf_dynamics.CSDM_Leaf_Dynamics(**kwargs)[source]

Leaf dynamics according to the Canopy Structure Dynamic Model.

The only difference is that in the real CSDM the temperature sum is the driving variable, while in this case it is simply the day number since the start of the model.

Reference: Koetz et al. 2005. Use of coupled canopy structure dynamic and radiative transfer models to estimate biophysical canopy characteristics. Remote Sensing of Environment. Volume 95, Issue 1, 15 March 2005, Pages 115-124. http://dx.doi.org/10.1016/j.rse.2004.11.017

For plotting the CSDM model with GNUPLOT the following example code can be used:

td = 150 CSDM_MAX = 5. CSDM_MIN = 0.15 CSDM_A = 0.085 CSDM_B = 0.045 CSDM_T1 = int(td/3.) CSDM_T2 = td

set xrange [0:200] set yrange [-1:8] plot CSDM_MIN + CSDM_MAX*(1./(1. + exp(-CSDM_B*(x - CSDM_T1)))**2 - exp(CSDM_A*(x - CSDM_T2)))

Root dynamics

class pcse.crop.root_dynamics.WOFOST_Root_Dynamics(**kwargs)[source]

Root biomass dynamics and rooting depth.

Root growth and root biomass dynamics in WOFOST are separate processes, with the only exception that root growth stops when no more biomass is sent to the root system.

Root biomass increase results from the assimilates partitioned to the root system. Root death is defined as the current root biomass multiplied by a relative death rate (RDRRTB). The latter as a function of the development stage (DVS).

Increase in root depth is a simple linear expansion over time until the maximum rooting depth (RDM) is reached.

Simulation parameters

Name	Description	Type	Unit
RDI	Initial rooting depth	SCr	cm
RRI	Daily increase in rooting depth	SCr	cm day^-1
RDMCR	Maximum rooting depth of the crop	SCR	cm
RDMSOL	Maximum rooting depth of the soil	SSo	cm
TDWI	Initial total crop dry weight	SCr	kg ha^-1
IAIRDU	Presence of air ducts in the root (1) or not (0)	SCr
RDRRTB	Relative death rate of roots as a function of development stage	TCr

State variables

Name	Description	Pbl	Unit
RD	Current rooting depth	Y	cm
RDM	Maximum attainable rooting depth at the minimum of the soil and crop maximum rooting depth	N	cm
WRT	Weight of living roots	Y	kg ha^-1
DWRT	Weight of dead roots	N	kg ha^-1
TWRT	Total weight of roots	Y	kg ha^-1

Rate variables

Name	Description	Pbl	Unit
RR	Growth rate root depth	N	cm
GRRT	Growth rate root biomass	N	kg ha^-1day^-1
DRRT	Death rate root biomass	N	kg ha^-1day^-1
GWRT	Net change in root biomass	N	kg ha^-1day^-1

Signals send or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
DMI	Total dry matter increase	CropSimulation	kg ha^-1day^-1
FR	Fraction biomass to roots	DVS_Partitioning

Stem dynamics

class pcse.crop.stem_dynamics.WOFOST_Stem_Dynamics(**kwargs)[source]

Implementation of stem biomass dynamics.

Stem biomass increase results from the assimilates partitioned to the stem system. Stem death is defined as the current stem biomass multiplied by a relative death rate (RDRSTB). The latter as a function of the development stage (DVS).

Stems are green elements of the plant canopy and can as such contribute to the total photosynthetic active area. This is expressed as the Stem Area Index which is obtained by multiplying stem biomass with the Specific Stem Area (SSATB), which is a function of DVS.

Simulation parameters:

Name	Description	Type	Unit
TDWI	Initial total crop dry weight	SCr	kg ha^-1
RDRSTB	Relative death rate of stems as a function of development stage	TCr
SSATB	Specific Stem Area as a function of development stage	TCr	ha kg^-1

State variables

Name	Description	Pbl	Unit
SAI	Stem Area Index	Y
WST	Weight of living stems	Y	kg ha^-1
DWST	Weight of dead stems	N	kg ha^-1
TWST	Total weight of stems	Y	kg ha^-1

Rate variables

Name	Description	Pbl	Unit
GRST	Growth rate stem biomass	N	kg ha^-1day^-1
DRST	Death rate stem biomass	N	kg ha^-1day^-1
GWST	Net change in stem biomass	N	kg ha^-1day^-1

Signals send or handled

None

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
ADMI	Above-ground dry matter increase	CropSimulation	kg ha^-1day^-1
FR	Fraction biomass to roots	DVS_Partitioning
FS	Fraction biomass to stems	DVS_Partitioning

Storage organ dynamics

class pcse.crop.storage_organ_dynamics.WOFOST_Storage_Organ_Dynamics(**kwargs)[source]

Implementation of storage organ dynamics.

Storage organs are the most simple component of the plant in WOFOST and consist of a static pool of biomass. Growth of the storage organs is the result of assimilate partitioning. Death of storage organs is not implemented and the corresponding rate variable (DRSO) is always set to zero.

Pods are green elements of the plant canopy and can as such contribute to the total photosynthetic active area. This is expressed as the Pod Area Index which is obtained by multiplying pod biomass with a fixed Specific Pod Area (SPA).

Simulation parameters

Name	Description	Type	Unit
TDWI	Initial total crop dry weight	SCr	kg ha^-1
SPA	Specific Pod Area	SCr	ha kg^-1

State variables

Name	Description	Pbl	Unit
PAI	Pod Area Index	Y
WSO	Weight of living storage organs	Y	kg ha^-1
DWSO	Weight of dead storage organs	N	kg ha^-1
TWSO	Total weight of storage organs	Y	kg ha^-1

Rate variables

Name	Description	Pbl	Unit
GRSO	Growth rate storage organs	N	kg ha^-1day^-1
DRSO	Death rate storage organs	N	kg ha^-1day^-1
GWSO	Net change in storage organ biomass	N	kg ha^-1day^-1

Signals send or handled

None

External dependencies

Name	Description	Provided by	Unit
ADMI	Above-ground dry matter increase	CropSimulation	kg ha^-1day^-1
FO	Fraction biomass to storage organs	DVS_Partitioning
FR	Fraction biomass to roots	DVS_Partitioning

Crop N dynamics

class pcse.crop.n_dynamics.N_Crop_Dynamics(**kwargs)[source]

Implementation of overall N crop dynamics.

NPK_Crop_Dynamics implements the overall logic of N book-keeping within the crop.

Simulation parameters

Name	Description	Unit
NMAXLV_TB	Maximum N concentration in leaves as function of dvs	kg N kg-1 dry biomass
NMAXRT_FR	Maximum N concentration in roots as fraction of maximum N concentration in leaves
NMAXST_FR	Maximum N concentration in stems as fraction of maximum N concentration in leaves
NRESIDLV	Residual N fraction in leaves	kg N kg-1 dry biomass
NRESIDRT	Residual N fraction in roots	kg N kg-1 dry biomass
NRESIDST	Residual N fraction in stems	kg N kg-1 dry biomass

State variables

Name	Description	Unit
NamountLV	Actual N amount in living leaves	kg N ha^-1
NamountST	Actual N amount in living stems	kg N ha^-1
NamountSO	Actual N amount in living storage organs	kg N ha^-1
NamountRT	Actual N amount in living roots	kg N ha^-1
Nuptake_T	total absorbed N amount	kg N ha^-1
Nfix_T	total biological fixated N amount	kg N ha^-1

Rate variables

Name	Description	Unit
RNamountLV	Weight increase (N) in leaves	kg N ha^-1 d^-1
RNamountST	Weight increase (N) in stems	kg N ha^-1 d^-1
RNamountRT	Weight increase (N) in roots	kg N ha^-1 d^-1
RNamountSO	Weight increase (N) in storage organs	kg N ha^-1 d^-1
RNdeathLV	Rate of N loss in leaves	kg N ha^-1 d^-1
RNdeathST	Rate of N loss in roots	kg N ha^-1 d^-1
RNdeathRT	Rate of N loss in stems	kg N ha^-1 d^-1
RNloss	N loss due to senescence	kg N ha^-1 d^-1

Signals send or handled

None

External dependencies

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
WLV	Dry weight of living leaves	WOFOST_Leaf_Dynamics	kg ha^-1
WRT	Dry weight of living roots	WOFOST_Root_Dynamics	kg ha^-1
WST	Dry weight of living stems	WOFOST_Stem_Dynamics	kg ha^-1
DRLV	Death rate of leaves	WOFOST_Leaf_Dynamics	kg ha^-1day^-1
DRRT	Death rate of roots	WOFOST_Root_Dynamics	kg ha^-1day^-1
DRST	Death rate of stems	WOFOST_Stem_Dynamics	kg ha^-1day^-1

class pcse.crop.nutrients.N_Demand_Uptake(**kwargs)[source]

Calculates the crop N demand and its uptake from the soil.

Crop N demand is calculated as the difference between the actual N (kg N per kg biomass) in the vegetative plant organs (leaves, stems and roots) and the maximum N concentration for each organ. N uptake is then estimated as the minimum of supply from the soil and demand from the crop.

Nitrogen fixation (leguminous plants) is calculated by assuming that a fixed fraction of the daily N demand is supplied by nitrogen fixation. The remaining part has to be supplied by the soil.

The N demand of the storage organs is calculated in a somewhat different way because it is assumed that the demand from the storage organs is fulfilled by translocation of N/P/K from the leaves, stems and roots. Therefore the uptake of the storage organs is calculated as the minimum of the daily translocatable N supply and the demand from the storage organs.

Simulation parameters

Name	Description	Unit
NMAXLV_TB	Maximum N concentration in leaves as function of DVS	kg N kg-1 dry biomass
NMAXRT_FR	Maximum N concentration in roots as fraction of maximum N concentration in leaves
NMAXST_FR	Maximum N concentration in stems as fraction of maximum N concentration in leaves
NMAXSO	Maximum N concentration in storage organs	kg N kg-1 dry biomass
NCRIT_FR	Critical N concentration as fraction of maximum N concentration for vegetative plant organs as a whole (leaves + stems)
TCNT	Time coefficient for N translation to storage organs	days
NFIX_FR	fraction of crop nitrogen uptake by	kg N kg-1 dry biomass biological fixation
RNUPTAKEMAX	Maximum rate of N uptake	kg N ha^-1 d^-1

State variables

Rate variables

Name	Description	Pbl	Unit
RNuptakeLV	Rate of N uptake in leaves	Y	kg N ha^-1 d^-1
RNuptakeST	Rate of N uptake in stems	Y	kg N ha^-1 d^-1
RNuptakeRT	Rate of N uptake in roots	Y	kg N ha^-1 d^-1
RNuptakeSO	Rate of N uptake in storage organs	Y	kg N ha^-1 d^-1
RNuptake	Total rate of N uptake	Y	kg N ha^-1 d^-1
RNfixation	Rate of N fixation	Y	kg N ha^-1 d^-1
NdemandLV	N Demand in living leaves	N	kg N ha^-1
NdemandST	N Demand in living stems	N	kg N ha^-1
NdemandRT	N Demand in living roots	N	kg N ha^-1
NdemandSO	N Demand in storage organs	N	kg N ha^-1
Ndemand	Total crop N demand	N	kg N ha^-1 d^-1

Signals send or handled

None

External dependencies

class pcse.crop.nutrients.N_Stress(**kwargs)[source]

Implementation of N stress calculation through [N]nutrition index.

HB 20220405 A lot of changes have been done in this subroutine. It needs to be redocumented.

Name	Description	Unit
NMAXLV_TB	Maximum N concentration in leaves as function of DVS	kg N kg-1 dry matter
NMAXRT_FR	Maximum N concentration in roots as fraction of maximum N concentration in leaves
NMAXSO	Maximum N oconcentration in grains	kg N kg-1 dry matter
NMAXST_FR	Maximum N concentration in stems as fraction of maximum N concentration in leaves
NCRIT_FR	Critical N concentration as fraction of maximum N concentration for vegetative plant organs as a whole (leaves + stems)
NRESIDLV	Residual N fraction in leaves	kg N kg-1 dry matter
NRESIDST	Residual N fraction in stems	kg N kg-1 dry matter
RGRLAI_MIN	Relative growth rate in exponential growth phase at maximum N stress	d-1

Rate variables

The rate variables here are not real rate variables in the sense that they are derived state variables and do not represent a rate. However, as they are directly used in the rate variable calculation it is logical to put them here.

Name	Description	Pbl	Unit
NSLLV	N Stress factor	Y
RFRGRL	Reduction factor relative growth rate in exponential phase	Y

External dependencies:

Abiotic damage

class pcse.crop.abioticdamage.FROSTOL(**kwargs)[source]

Implementation of the FROSTOL model for frost damage in winter-wheat.

Parameters

day – start date of the simulation
kiosk – variable kiosk of this PCSE instance
parvalues – ParameterProvider object providing parameters as key/value pairs

Simulation parameters

Name	Description	Type	Unit
IDSL	Switch for phenological development options temperature only (IDSL=0), including daylength (IDSL=1) and including vernalization (IDSL>=2). FROSTOL requires IDSL>=2	SCr
LT50C	Critical LT50 defined as the lowest LT50 value that the wheat cultivar can obtain	SCr	$^{\circ}C$
FROSTOL_H	Hardening coefficient	SCr	$^{\circ}C^{-1} day^{-1}$
FROSTOL_D	Dehardening coefficient	SCr	$^{\circ}C^{-3} day^{-1}$
FROSTOL_S	Low temperature stress coefficient	SCr	$^{\circ}C^{-1} day^{-1}$
FROSTOL_R	Respiration stress coefficient	SCr	day^-1
FROSTOL_SDBASE	Minimum snow depth for respiration stress	SCr	cm
FROSTOL_SDMAX	Snow depth with maximum respiration stress. Larger snow depth does not increase stress anymore.	SCr	cm
FROSTOL_KILLCF	Steepness coefficient for logistic kill function.	SCr
ISNOWSRC	Use prescribed snow depth from driving variables (0) or modelled snow depth through the kiosk (1)	SSi

State variables

Name	Description	Pbl	Unit
LT50T	Current LT50 value	N	$^{\circ}C$
LT50I	Initial LT50 value of unhardened crop	N	$^{\circ}C$
IDFST	Total number of days with frost stress	N

Rate variables

Name	Description	Pbl	Unit
RH	Rate of hardening	N	$^{\circ}C day^{-1}$
RDH_TEMP	Rate of dehardening due to temperature	N	$^{\circ}C day^{-1}$
RDH_RESP	Rate of dehardening due to respiration stress	N	$^{\circ}C day^{-1}$
RDH_TSTR	Rate of dehardening due to temperature stress	N	$^{\circ}C day^{-1}$
IDFS	Frost stress, yes (1) or no (0). Frost stress is defined as: RF_FROST > 0	N
RF_FROST	Reduction factor on leave biomass as a function of min. crown temperature and LT50T: ranges from 0 (no damage) to 1 (complete kill).	Y
RF_FROST_T	Total frost kill through the growing season is computed as the multiplication of the daily frost kill events, 0 means no damage, 1 means total frost kill.	N

External dependencies:

Name	Description	Provided by	Unit
TEMP_CROWN	Daily average crown temperature derived from calling the crown_temperature module.	CrownTemperature	$^{\circ}C$
TMIN_CROWN	Daily minimum crown temperature derived from calling the crown_temperature module.	CrownTemperature	$^{\circ}C$
ISVERNALISED	Boolean reflecting the vernalisation state of the crop.	Vernalisation i.c.m. with DVS_Phenology module

Reference: Anne Kari Bergjord, Helge Bonesmo, Arne Oddvar Skjelvag, 2008.: Modelling the course of frost tolerance in winter wheat: I. Model development, European Journal of Agronomy, Volume 28, Issue 3, April 2008, Pages 321-330.

http://dx.doi.org/10.1016/j.eja.2007.10.002

class pcse.crop.abioticdamage.CrownTemperature(**kwargs)[source]

Implementation of a simple algorithm for estimating the crown temperature (2cm under the soil surface) under snow.

Is is based on a simple empirical equation which estimates the daily minimum, maximum and mean crown temperature as a function of daily min or max temperature and the relative snow depth (RSD):

$RSD = min(15, SD)/15$

and

$T^{crown}_{min} = T_{min} * (A + B(1 - RSD)^{2})$

and

$T^{crown}_{max} = T_{max} * (A + B(1 - RSD)^{2})$

and

$T^{crown}_{avg} = (T^{crown}_{max} + T^{crown}_{min})/2$

At zero snow depth crown temperature is estimated close the the air temperature. Increasing snow depth acts as a buffer damping the effect of low air temperature on the crown temperature. The maximum value of the snow depth is limited on 15cm. Typical values for A and B are 0.2 and 0.5

Note that the crown temperature is only estimated if drv.TMIN<0, otherwise the TMIN, TMAX and daily average temperature (TEMP) are returned.

Parameters

day – day when model is initialized
kiosk – VariableKiosk of this instance
parvalues – ParameterProvider object providing parameters as key/value pairs

Returns

a tuple containing minimum, maximum and daily average crown temperature.

Simulation parameters

Name	Description	Type
ISNOWSRC	Use prescribed snow depth from driving variables (0) or modelled snow depth through the kiosk (1)	SSi
CROWNTMPA	A parameter in equation for crown temperature	SSi
CROWNTMPB	B parameter in equation for crown temperature	SSi

Rate variables

Name	Description	Pbl	Unit
TEMP_CROWN	Daily average crown temperature	N	$^{\circ}C$
TMIN_CROWN	Daily minimum crown temperature	N	$^{\circ}C$
TMAX_CROWN	Daily maximum crown temperature	N	$^{\circ}C$

Note that the calculated crown temperatures are not real rate variables as they do not pertain to rate of change. In fact they are a derived driving variable. Nevertheless for calculating the frost damage they should become available during the rate calculation step and by treating them as rate variables, they can be found by a get_variable() call and thus be defined in the list of OUTPUT_VARS in the configuration file

External dependencies:

Name	Description	Provided by	Unit
SNOWDEPTH	Depth of snow cover.	Prescibed by driving variables or simulated by snow cover module and taken from kiosk	$cm$

Crop simulation processes for LINGRA

Implementation of the LINGRA grassland simulation model

This module provides an implementation of the LINGRA (LINtul GRAssland) simulation model for grasslands as described by Schapendonk et al. 1998 (https://doi.org/10.1016/S1161-0301(98)00027-6) for use within the Python Crop Simulation Environment.

Overall grassland model

class pcse.crop.lingra.LINGRA(**kwargs)[source]

Top level implementation of LINGRA, integrating all components

This class integrates all components from the LINGRA model and includes the main state variables related to weights of the different biomass pools, the leaf area, tiller number and leaf length. The integrated components include the implementations for source/sink limited growth, soil temperature, evapotranspiration and root dynamics. The latter two are taken from WOFOST in order to avoid duplication of code.

Compared to the original code from Schapendonk et al. (1998) several improvements have been made:

an overall restructuring of the code, removing unneeded variables and renaming the remaining variables to have more readable names.
A clearer implementation of sink/source limited growth including the use of reserves
the potential leaf elongation rate as calculated by the Sink-limited growth module is now corrected for actual growth. Thereby avoiding unlimited leaf growth under water-stressed conditions which led to unrealistic results.

Simulation parameters:

Name	Description	Unit
LAIinit	Initial leaf area index
TillerNumberinit	Initial number of tillers	tillers/m2
WeightREinit	Initial weight of reserves	kg/ha
WeightRTinit	Initial weight of roots	kg/ha
LAIcrit	Critical LAI for death due to self-shading
RDRbase	Background relative death rate for roots	d-1
RDRShading	Max relative death rate of leaves due to self-shading	d-1
RDRdrought	Max relative death rate of leaves due to drought stress	d-1
SLA	Specific leaf area	ha/kg
TempBase	Base temperature for photosynthesis and development	C
PartitioningRootsTB	Partitioning fraction to roots as a function of the reduction factor for transpiration (RFTRA)	-, -
TSUMmax	Temperature sum to max development stage	C.d

Rate variables

Name	Description	Unit
dTSUM	Change in temperature sum for development	C
dLAI	Net change in Leaf Area Index	d-1
dDaysAfterHarvest	Change in Days after Harvest
dCuttingNumber	Change in number of cuttings (harvests)
dWeightLV	Net change in leaf weight	kg/ha/d
dWeightRE	Net change in reserve pool	kg/ha/d
dLeafLengthAct	Change in actual leaf length	cm/d
LVdeath	Leaf death rate	kg/ha/d
LVgrowth	Leaf growth rate	kg/ha/d
dWeightHARV	Change in harvested dry matter	kg/ha/d
dWeightRT	Net change in root weight	kg/ha/d
LVfraction	Fraction partitioned to leaves
RTfraction	Fraction partitioned to roots

State variables

Name	Description	Unit
TSUM	Temperature sum	C d
LAI	Leaf area Index
DaysAfterHarvest	number of days after harvest	d
CuttingNumber	number of cuttings (harvests)
TillerNumber	Tiller number	tillers/m2
WeightLVgreen	Weight of green leaves	kg/ha
WeightLVdead	Weight of dead leaves	kg/ha
WeightHARV	Weight of harvested dry matter	kg/ha
WeightRE	Weight of reserves	kg/ha
WeightRT	Weight of roots	kg/ha
LeafLength	Length of leaves	kg/ha
WeightABG	Total aboveground weight (harvested + current)	kg/ha
SLAINT	Integrated SLA during the season	ha/kg
DVS	Development stage

Signals sent or handled

Mowing of grass will take place when a pcse.signals.mowing event is broadcasted. This will reduce the amount of living leaf weight assuming that a certain amount of biomass will remain on the field (this is a parameter on the MOWING event).

External dependencies:

Name	Description	Provided by
RFTRA	Reduction factor for transpiration	pcse.crop.Evapotranspiration
dLeafLengthPot	Potential growth in leaf length	pcse.crop.lingra.SinkLimitedGrowth
dTillerNumber	Change in tiller number	pcse.crop.lingra.SinkLimitedGrowth

Source/Sink limited growth

class pcse.crop.lingra.SourceLimitedGrowth(**kwargs)[source]

Calculates the source-limited growth rate for grassland based on radiation and temperature as driving variables and possibly limited by soil moisture or leaf nitrogen content.The latter is based on static values for current and maximum N concentrations and is mainly there for connecting an N module in the future.

This routine uses a light use efficiency (LUE) approach where the LUE is adjusted for effects of temperature and radiation level. The former is need as photosynthesis has a clear temperature response. The latter is required as photosynthesis rate flattens off at higher radiation levels which leads to a lower ‘apparent’ light use efficiency. The parameter LUEreductionRadiationTB is a crude empirical correction for this effect.

Note that a reduction in growth rate due to soil moisture is obtained through the reduction factor for transpiration (RFTRA).

This module does not provide any true rate variables, but returns the computed growth rate directly to the calling routine through __call__().

Simulation parameters:

Name	Description	Unit
KDIFTB	Extinction coefficient for diffuse visible as function of DVS.
CO2A	Atmospheric CO2 concentration	ppm
LUEreductionSoilTempTB	Reduction function for light use efficiency as a function of soil temperature.	C, -
LUEreductionRadiationTB	Reduction function for light use efficiency as a function of radiation level.	MJ, -
LUEmax	Maximum light use efficiency.

Rate variables

Name	Description	Unit
RF_RadiationLevel	Reduction factor for light use efficiency due to the radiation level
RF_RadiationLevel	Reduction factor for light use efficiency due to the radiation level
LUEact	The actual light use efficiency	g /(MJ PAR)

Signals send or handled

None

External dependencies:

Name	Description	Provided by
DVS	Crop development stage	pylingra.LINGRA
TemperatureSoil	Soil Temperature	pylingra.SoilTemperature
RFTRA	Reduction factor for transpiration	pcse.crop.Evapotranspiration

class pcse.crop.lingra.SinkLimitedGrowth(**kwargs)[source]

Calculates the sink-limited growth rate for grassland assuming a temperature driven maximum leaf elongation rate multiplied by the number of tillers. The conversion to growth in kg/ha dry matter is done by dividing by the specific leaf area (SLA).

Besides the sink-limited growth rate, this class also computes the change in tiller number taking into account the growth rate, death rate and number of days after defoliation due to harvest.

Simulation parameters:

Name	Description	Unit
TempBase	Base temperature for leaf development and grass phenology	C
LAICrit	Cricical leaf area beyond which leaf death due to self-shading occurs
SiteFillingMax	Maximum site filling for new buds	tiller/leaf-1
SLA	Specific leaf area	ha/kg
TSUMmax	Temperature sum to max development stage	C.d
TillerFormRateA0	A parameter in the equation for tiller formation rate valid up till 7 days after harvest
TillerFormRateB0	B parameter in the equation for tiller formation rate valid up till 7 days after harvest
TillerFormRateA8	A parameter in the equation for tiller formation rate starting from 8 days after harvest
TillerFormRateB8	B parameter in the equation for tiller formation rate starting from 8 days after harvest

Rate variables

Name	Description	Unit
dTillerNumber	Change in tiller number due to the radiation level	tillers/m2/d
dLeafLengthPot	Potential change in leaf length. Later on the actual change in leaf length will be computed taking source limitation into account.	cm/d
LAIGrowthSink	Growth of LAI based on sink-limited growth rate.	d-1

Signals send or handled

None

External dependencies:

Name	Description	Provided by
DVS	Crop development stage	pylingra.LINGRA
LAI	Leaf Area Index	pylingra.LINGRA
TemperatureSoil	Soil Temperature	pylingra.SoilTemperature
RF_Temperature	Reduction factor for LUE based on temperature	pylingra.SourceLimitedGrowth
TillerNumber	Actual number of tillers	pylingra.LINGRA
LVfraction	Fraction of assimilates going to leaves	pylingra.LINGRA
dWeightHARV	Change in harvested weight (indicates that a harvest took place today)	pylingra.LINGRA

Nitrogen dynamics

class pcse.crop.lingra_ndynamics.N_Demand_Uptake(**kwargs)[source]

Calculates the crop N demand and its uptake from the soil.

Crop N demand is calculated as the difference between the actual N concentration (kg N per kg biomass) in the vegetative plant organs (leaves, stems and roots) and the maximum N concentration for each organ. N uptake is then estimated as the minimum of supply from the soil and demand from the crop.

Simulation parameters

Rate variables

Name	Description	Pbl	Unit
RNuptakeLV	Rate of N uptake in leaves	Y	kg N ha^-1 d^-1
RNuptakeRT	Rate of N uptake in roots	Y	kg N ha^-1 d^-1
RNuptake	Total rate of N uptake	Y	kg N ha^-1 d^-1
NdemandLV	Ndemand of leaves based on current growth rate and deficienties from previous time steps	N	kg N ha^-1
NdemandRT	N demand of roots, idem as leaves	N	kg N ha^-1
Ndemand	Total N demand (leaves + roots)	N	kg N ha^-1

Signals send or handled

None

External dependencies

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
NAVAIL	Total available N from soil	NPK_Soil_Dynamics	kg ha^-1

class pcse.crop.lingra_ndynamics.N_Stress(**kwargs)[source]

Implementation of N stress calculation through nitrogen nutrition index.

Stress factors are calculated based on the mass concentrations of N in the vegetative biomass of the plant. For each pool of nutrients, four concentrations are calculated based on the biomass for leaves and stems: - the actual concentration based on the actual amount of nutrients

divided by the vegetative biomass.

The maximum concentration, being the maximum that the plant can absorb into its leaves and stems.
The critical concentration, being the concentration that is needed to maintain growth rates that are not limited by N (regulated by NCRIT_FR). For N, the critical concentration can be lower than the maximum concentration. This concentration is sometimes called ‘optimal concentration’.
The residual concentration which is the amount that is locked into the plant structural biomass and cannot be mobilized anymore.

The stress index (SI) is determined as a simple ratio between those concentrations according to:

$SI = (C_{a) - C_{r})/(C_{c} - C_{r})$

with subscript a, r and c being the actual, residual and critical concentration for the nutrient. This results in the nitrogen nutrition index (NNI). Finally, the reduction factor for assimilation (RFNUTR) is calculated using the reduction factor for light use efficiency (NLUE).

Simulation parameters

Rate variables

The rate variables here are not real rate variables in the sense that they are derived state variables and do not represent a rate. However, as they are directly used in the rate variable calculation it is logical to put them here.

Name	Description	Pbl	Unit
NNI	Nitrogen nutrition index	Y
RFNUTR	Reduction factor for light use efficiency	Y

External dependencies:

Name	Description	Provided by	Unit
DVS	Crop development stage	DVS_Phenology
WST	Dry weight of living stems	WOFOST_Stem_Dynamics	kg ha^-1
WeightLVgreen	Dry weight of living leaves	WOFOST_Leaf_Dynamics	kg ha^-1
NamountLV	Amount of N in leaves	N_Crop_Dynamics	kg ha^-1

class pcse.crop.lingra_ndynamics.N_Crop_Dynamics(**kwargs)[source]

Implementation of overall N crop dynamics.

NPK_Crop_Dynamics implements the overall logic of N book-keeping within the crop.

Simulation parameters

State variables

Name	Description	Pbl	Unit
NamountLV	Actual N amount in living leaves	Y	kg N ha^-1
NamountRT	Actual N amount in living roots	Y	kg N ha^-1
Nuptake_T	total absorbed N amount	N	kg N ha^-1
Nlosses_T	Total N amount lost due to senescence	N	kg N ha^-1

Rate variables

Name	Description	Pbl	Unit
RNamountLV	Weight increase (N) in leaves	N	kg ha^-1day^-1
RNamountRT	Weight increase (N) in roots	N	kg ha^-1day^-1
RNdeathLV	Rate of N loss in leaves	N	kg ha^-1day^-1
RNdeathRT	Rate of N loss in roots	N	kg ha^-1day^-1
RNloss	N loss due to senescence	N	kg ha^-1day^-1

Signals send or handled

None

External dependencies

Crop simulation processes for LINTUL

class pcse.crop.lintul3.Lintul3(**kwargs)[source]

LINTUL3 is a crop model that calculates biomass production based on intercepted photosynthetically active radiation (PAR) and light use efficiency (LUE). It is an adapted version of LINTUL2 (that simulates potential and water-limited crop growth), including nitrogen limitation. Nitrogen stress in the model is defined through the nitrogen nutrition index (NNI): the ratio of actual nitrogen concentration and critical nitrogen concentration in the plant. The effect of nitrogen stress on crop growth is tested in the model either through a reduction in LUE or leaf area (LA) or a combination of these two and further evaluated with independent datasets. However, water limitation is not considered in the present study as the crop is paddy rice. This paper describes the model for the case of rice, test the hypotheses of N stress on crop growth and details of model calibration and testing using independent data sets of nitrogen treatments (with fertilizer rates of 0 - 400 kgNha-1) under varying environmental conditions in Asia. Results of calibration and testing are compared graphically, through Root Mean Square Deviation (RMSD), and by Average Absolute Deviation (AAD). Overall average absolute deviation values for calibration and testing of total aboveground biomass show less than 26% mean deviation from the observations though the values for individual experiments show a higher deviation up to 41%. In general, the model responded well to nitrogen stress in all the treatments without fertilizer application as observed, but between fertilized treatments the response was varying.

Nitrogen demand, uptake and stress

At sub-optimal nitrogen availability in the soil, nitrogen demand of the crop cannot be satisfied, which leads to sub-optimal crop nitrogen concentration. The crop nitrogen concentration below which a crop experiences nitrogen stress is called the critical nitrogen concentration. Nitrogen stress results in reduced rates of biomass production and eventually in reduced yields. Actual N content is the accumulated N above residual (which forms part of the cell structure). The critical N content is the one corresponding to half of the maximum. Nitrogen contents of these three reference points include those of leaves and stems, whereas roots are not considered since N contents of above-ground (green) parts are more important for photosynthesis, because of their chlorophyll content. However, calculation of N demand and N uptake also includes the belowground part.

See: M.E. Shibu, P.A. Leffelaar, H. van Keulena, P.K. Aggarwal (2010). LINTUL3, a simulation model for nitrogen-limited situations: application to rice. Eur. J. Agron. (2010) http://dx.doi.org/10.1016/j.eja.2010.01.003

Parameters

Name	Description	Unit
DVSI	Initial development stage
DVSDR	Development stage above which deathOfLeaves of leaves and roots start
DVSNLT	Development stage after which no nutrients are absorbed
DVSNT	development stage above which N translocation to storage organs does occur
FNTRT	Nitrogen translocation from roots to storage organs as a fraction of total amount of nitrogen translocated from leaves and stem to storage organs
FRNX	Critical N, as a fraction of maximum N concentration
K	Light attenuation coefficient	m²/m²
LAICR	critical LAI above which mutual shading of leaves occurs,	°C/d
LRNR	Maximum N concentration of root as fraction of that of leaves	g/g
LSNR	Maximum N concentration of stem as fraction of that of leaves	g/g
LUE	Light use efficiency	g/MJ
NLAI	Coefficient for the effect of N stress on LAI reduction(during juvenile phase)
NLUE	Coefficient of reduction of LUE under nitrogen stress, epsilon
NMAXSO	Maximum concentration of nitrogen in storage organs	g/g
NPART	Coefficient for the effect of N stress on leaf biomass reduction
NSLA	Coefficient for the effect of N stress on SLA reduction
RDRNS	Relative death rate of leaf weight due to N stress	1/d
RDRRT	Relative death rate of roots	1/d
RDRSHM	and the maximum dead rate of leaves due to shading	1/d
RGRL	Relative growth rate of LAI at the exponential growth phase	°C/d
RNFLV	Residual N concentration in leaves	g/g
RNFRT	Residual N concentration in roots	g/g
RNFST	Residual N concentration in stem	g/g
ROOTDM	Maximum root depth	m
RRDMAX	Maximum rate of increase in rooting depth	m/d
SLAC	Specific leaf area constant	m²/g
TBASE	Base temperature for crop development	°C
TCNT	Time coefficient for N translocation	d
TRANCO	Transpiration constant indicating the level of drought tolerance of the wheat crop	mm/d
TSUMAG	Temperature sum for ageing of leaves	°C.d
WCFC	Water content at field capacity (0.03 MPa)	m³/m³
WCST	Water content at full saturation	m³/m³
WCWET	Critical Water content for oxygen stress	m³/m³
WCWP	Water content at wilting point (1.5 MPa)	m³/m³
WMFAC	water management (False = irrigated up to the field capacity, true= irrigated up to saturation)	(bool)
RNSOIL	Daily amount of N available in the soil through mineralisation of organic matter

Tabular parameters

Name	Description	Unit
FLVTB	Partitioning coefficients
FRTTB	Partitioning coefficients
FSOTB	Partitioning coefficients
FSTTB	Partitioning coefficients
NMXLV	Maximum N concentration in the leaves, from which the values of the stem and roots are derived, as a function of development stage	kg N kg-1 dry biomass
RDRT	Relative death rate of leaves as a function of Developmental stage	1/d
SLACF	Leaf area correction function as a function of development stage, DVS. Reference: Drenth, H., ten Berge, H.F.M. and Riethoven, J.J.M. 1994, p.10. (Complete reference under Observed data.)

initial states *

Name	Description	Unit
ROOTDI	Initial rooting depth	m
NFRLVI	Initial fraction of N in leaves	gN/gDM
NFRRTI	Initial fraction of N in roots	gN/gDM
NFRSTI	Initial fraction of N in stem	gN/gDM
WCI	Initial water content in soil	m³/³
WLVGI	Initial Weight of green leaves	g/m²
WSTI	Initial Weight of stem	g/m²
WRTLI	Initial Weight of roots	g/m²
WSOI	Initial Weight of storage organs	g/m²

State variables:

Name	Description	Unit
ANLV	Actual N content in leaves
ANRT	Actual N content in root
ANSO	Actual N content in storage organs
ANST	Actual N content in stem
CUMPAR	PAR accumulator
LAI	leaf area index	m²/m²
NLOSSL	total N loss by leaves
NLOSSR	total N loss by roots
NUPTT	Total uptake of N over time	gN/m²
ROOTD	Rooting depth	m
TNSOIL	Amount of inorganic N available for crop uptake
WDRT	dead roots (?)	g/m²
WLVD	Weight of dead leaves	g/m²
WLVG	Weight of green leaves	g/m²
WRT	Weight of roots	g/m²
WSO	Weight of storage organs	g/m²
WST	Weight of stem	g/m²
TAGBM	Total aboveground biomass	g/m²
TGROWTH	Total biomass growth (above and below ground)	g/m²

Rate variables:

Name	Description	Pbl	Unit
PEVAP	Potential soil evaporation rate	Y	\|mmday-1\|
PTRAN	Potential crop transpiration rate	Y	\|mmday-1\|
TRAN	Actual crop transpiration rate	N	\|mmday-1\|
TRANRF	Transpiration reduction factor calculated	N
RROOTD	Rate of root growth	Y	\|mday-1\|

class Lintul3Rates(**kwargs)[source]

class Lintul3States(**kwargs)[source]

N_uptakeRates(NDEML, NDEMS, NDEMR, NUPTR, NDEMTO)[source]: Compute the partitioning of the total N uptake rate (NUPTR) over the leaves, stem, and roots.

class Parameters(**kwargs)[source]

deathRateOfLeaves(TSUM, RDRTMP, NNI, SLA)[source]: Compute the relative death rate of leaves due to age, shading amd due to nitrogen stress.

dryMatterPartitioningFractions(NPART, TRANRF, NNI, FRTWET, FLVT, FSTT, FSOT)[source]: Computes the Dry matter partitioning fractions: leaves, stem and storage organs.

initialize(day, kiosk, parvalues)[source]

Parameters

day – start date of the simulation
kiosk – variable kiosk of this PCSE instance
parvalues – ParameterProvider object providing parameters as key/value pairs

relativeGrowthRates(RGROWTH, FLV, FRT, FST, FSO, DLV, DRRT)[source]: Compute the relative total Growth Rate rate of roots, leaves, stem and storage organs.

totalGrowthRate(DTR, TRANRF, NNI)[source]

Compute the total total Growth Rate.

Monteith, (1977), Gallagher and Biscoe, (1978) and Monteith (1990) have shown that biomass formed per unit intercepted light, LUE (Light Use Efficiency, g dry matter MJ-1), is relatively stable. Hence, maximum daily growth rate can be defined as the product of intercepted PAR (photosynthetically active radiation, $MJ m^{-2} day^{-1}$) and LUE.

Intercepted PAR depends on incident solar radiation, the fraction that is photosynthetically active (0.5) (Monteith and Unsworth, 1990; Spitters, 1990), and LAI (m ² leaf m ^-2 soil) according to Lambert Beer’s law:

$Q = 0.5 Q0 (1 - e^{-k LAI})$

where Q is intercepted PAR $MJ m^{-2} day^{-1}$, Q0 is daily global radiation $MJ m^{-2} day^{-1}$, and k is the attenuation coefficient for PAR in the canopy.

translocatable_N()[source]: Compute the translocatable N in the organs.

Base classes

The base classes define much of the functionality which is used “under the hood” in PCSE. Except for the VariableKiosk and the WeatherDataContainer all classes are not to be called directly but should be subclassed instead.

VariableKiosk

class pcse.base.VariableKiosk[source]

VariableKiosk for registering and publishing state variables in PCSE.

No parameters are needed for instantiating the VariableKiosk. All variables that are defined within PCSE will be registered within the VariableKiosk, while usually only a small subset of those will be published with the kiosk. The value of the published variables can be retrieved with the bracket notation as the variableKiosk is essentially a (somewhat fancy) dictionary.

Registering/deregistering rate and state variables goes through the self.register_variable() and self.deregister_variable() methods while the set_variable() method is used to update a value of a published variable. In general, none of these methods need to be called by users directly as the logic within the StatesTemplate and RatesTemplate takes care of this.

Finally, the variable_exists() can be used to check if a variable is registered, while the flush_states() and flush_rates() are used to remove (flush) the values of any published state and rate variables.

example:

>>> import pcse
>>> from pcse.base import VariableKiosk
>>>
>>> v = VariableKiosk()
>>> id0 = 0
>>> v.register_variable(id0, "VAR1", type="S", publish=True)
>>> v.register_variable(id0, "VAR2", type="S", publish=False)
>>>
>>> id1 = 1
>>> v.register_variable(id1, "VAR3", type="R", publish=True)
>>> v.register_variable(id1, "VAR4", type="R", publish=False)
>>>
>>> v.set_variable(id0, "VAR1", 1.35)
>>> v.set_variable(id1, "VAR3", 310.56)
>>>
>>> print v
Contents of VariableKiosk:
 * Registered state variables: 2
 * Published state variables: 1 with values:
  - variable VAR1, value: 1.35
 * Registered rate variables: 2
 * Published rate variables: 1 with values:
  - variable VAR3, value: 310.56

>>> print v["VAR3"]
310.56
>>> v.set_variable(id0, "VAR3", 750.12)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pcse/base.py", line 148, in set_variable
    raise exc.VariableKioskError(msg % varname)
pcse.exceptions.VariableKioskError: Unregistered object tried to set the value of variable 'VAR3': access denied.
>>>
>>> v.flush_rates()
>>> print v
Contents of VariableKiosk:
 * Registered state variables: 2
 * Published state variables: 1 with values:
  - variable VAR1, value: 1.35
 * Registered rate variables: 2
 * Published rate variables: 1 with values:
  - variable VAR3, value: undefined

>>> v.flush_states()
>>> print v
Contents of VariableKiosk:
 * Registered state variables: 2
 * Published state variables: 1 with values:
  - variable VAR1, value: undefined
 * Registered rate variables: 2
 * Published rate variables: 1 with values:
  - variable VAR3, value: undefined

deregister_variable(oid, varname)[source]

Object with id(object) asks to deregister varname from kiosk

Parameters

oid – Object id (from python builtin id() function) of the state/rate object registering this variable.
varname – Name of the variable to be registered, e.g. “DVS”

flush_rates()[source]: flush the values of all published rate variable from the kiosk.

flush_states()[source]: flush the values of all state variable from the kiosk.

register_variable(oid, varname, type, publish=False)[source]

Register a varname from object with id, with given type

Parameters

oid – Object id (from python builtin id() function) of the state/rate object registering this variable.
varname – Name of the variable to be registered, e.g. “DVS”
type – Either “R” (rate) or “S” (state) variable, is handled automatically by the states/rates template class.
publish – True if variable should be published in the kiosk, defaults to False

set_variable(id, varname, value)[source]

Let object with id, set the value of variable varname

Parameters

id – Object id (from python builtin id() function) of the state/rate object registering this variable.
varname – Name of the variable to be updated
value – Value to be assigned to the variable.

variable_exists(varname)[source]

Returns True if the state/rate variable is registered in the kiosk.

Parameters: varname – Name of the variable to be checked for registration.

Base classes for parameters, rates and states

class pcse.base.StatesTemplate(**kwargs)[source]

Takes care of assigning initial values to state variables, registering variables in the kiosk and monitoring assignments to variables that are published.

Parameters

kiosk – Instance of the VariableKiosk class. All state variables will be registered in the kiosk in order to enfore that variable names are unique across the model. Moreover, the value of variables that are published will be available through the VariableKiosk.
publish – Lists the variables whose values need to be published in the VariableKiosk. Can be omitted if no variables need to be published.

Initial values for state variables can be specified as keyword when instantiating a States class.

example:

>>> import pcse
>>> from pcse.base import VariableKiosk, StatesTemplate
>>> from pcse.traitlets import Float, Integer, Instance
>>> from datetime import date
>>>
>>> k = VariableKiosk()
>>> class StateVariables(StatesTemplate):
...     StateA = Float()
...     StateB = Integer()
...     StateC = Instance(date)
...
>>> s1 = StateVariables(k, StateA=0., StateB=78, StateC=date(2003,7,3),
...                     publish="StateC")
>>> print s1.StateA, s1.StateB, s1.StateC
0.0 78 2003-07-03
>>> print k
Contents of VariableKiosk:
 * Registered state variables: 3
 * Published state variables: 1 with values:
  - variable StateC, value: 2003-07-03
 * Registered rate variables: 0
 * Published rate variables: 0 with values:

>>>
>>> s2 = StateVariables(k, StateA=200., StateB=1240)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pcse/base.py", line 396, in __init__
    raise exc.PCSEError(msg)
pcse.exceptions.PCSEError: Initial value for state StateC missing.

touch()[source]: Re-assigns the value of each state variable, thereby updating its value in the variablekiosk if the variable is published.

class pcse.base.RatesTemplate(**kwargs)[source]

Takes care of registering variables in the kiosk and monitoring assignments to variables that are published.

Parameters

kiosk – Instance of the VariableKiosk class. All rate variables will be registered in the kiosk in order to enfore that variable names are unique across the model. Moreover, the value of variables that are published will be available through the VariableKiosk.
publish – Lists the variables whose values need to be published in the VariableKiosk. Can be omitted if no variables need to be published.

For an example see the StatesTemplate. The only difference is that the initial value of rate variables does not need to be specified because the value will be set to zero (Int, Float variables) or False (Boolean variables).

zerofy()[source]: Sets the values of all rate values to zero (Int, Float) or False (Boolean).

class pcse.base.ParamTemplate(**kwargs)[source]

Template for storing parameter values.

This is meant to be subclassed by the actual class where the parameters are defined.

example:

>>> import pcse
>>> from pcse.base import ParamTemplate
>>> from pcse.traitlets import Float
>>>
>>>
>>> class Parameters(ParamTemplate):
...     A = Float()
...     B = Float()
...     C = Float()
...
>>> parvalues = {"A" :1., "B" :-99, "C":2.45}
>>> params = Parameters(parvalues)
>>> params.A
1.0
>>> params.A; params.B; params.C
1.0
-99.0
2.4500000000000002
>>> parvalues = {"A" :1., "B" :-99}
>>> params = Parameters(parvalues)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pcse/base.py", line 205, in __init__
    raise exc.ParameterError(msg)
pcse.exceptions.ParameterError: Value for parameter C missing.

Base and utility classes for weather data

class pcse.base.WeatherDataProvider[source]

Base class for all weather data providers.

Support for weather ensembles in a WeatherDataProvider has to be indicated by setting the class variable supports_ensembles = True

Example:

class MyWeatherDataProviderWithEnsembles(WeatherDataProvider):
    supports_ensembles = True

    def __init__(self):
        WeatherDataProvider.__init__(self)

        # remaining initialization stuff goes here.

check_keydate(key)[source]

Check representations of date for storage/retrieval of weather data.

The following formats are supported:

a date object
a datetime object
a string of the format YYYYMMDD
a string of the format YYYYDDD

Formats 2-4 are all converted into a date object internally.

export()[source]

Exports the contents of the WeatherDataProvider as a list of dictionaries.

The results from export can be directly converted to a Pandas dataframe which is convenient for plotting or analyses.

class pcse.base.WeatherDataContainer(*args, **kwargs)[source]

Class for storing weather data elements.

Weather data elements are provided through keywords that are also the attribute names under which the variables can accessed in the WeatherDataContainer. So the keyword TMAX=15 sets an attribute TMAX with value 15.

The following keywords are compulsory:

Parameters

LAT – Latitude of location (decimal degree)
LON – Longitude of location (decimal degree)
ELEV – Elevation of location (meters)
DAY – the day of observation (python datetime.date)
IRRAD – Incoming global radiaiton (J/m2/day)
TMIN – Daily minimum temperature (Celsius)
TMAX – Daily maximum temperature (Celsius)
VAP – Daily mean vapour pressure (hPa)
RAIN – Daily total rainfall (cm/day)
WIND – Daily mean wind speed at 2m height (m/sec)
E0 – Daily evaporation rate from open water (cm/day)
ES0 – Daily evaporation rate from bare soil (cm/day)
ET0 – Daily evapotranspiration rate from reference crop (cm/day)

There are two optional keywords arguments:

Parameters

TEMP – Daily mean temperature (Celsius), will otherwise be derived from (TMAX+TMIN)/2.
SNOWDEPTH – Depth of snow cover (cm)

add_variable(varname, value, unit)[source]

Adds an attribute <varname> with <value> and given <unit>

Parameters

varname – Name of variable to be set as attribute name (string)
value – value of variable (attribute) to be added.
unit – string representation of the unit of the variable. Is only use for printing the contents of the WeatherDataContainer.

Configuration loading

class pcse.base.ConfigurationLoader(config)[source]

Class for loading the model configuration from a PCSE configuration files

Parameters: config – string given file name containing model configuration

update_output_variable_lists(output_vars=None, summary_vars=None, terminal_vars=None)[source]

Updates the lists of output variables that are defined in the configuration file.

This is useful because sometimes you want the flexibility to get access to an additional model variable which is not in the standard list of variables defined in the model configuration file. The more elegant way is to define your own configuration file, but this adds some flexibility particularly for use in jupyter notebooks and exploratory analysis.

Note that there is a different behaviour given the type of the variable provided. List and string inputs will extend the list of variables, while set/tuple inputs will replace the current list.

Parameters

output_vars – the variable names to add/replace for the OUTPUT_VARS configuration variable
summary_vars – the variable names to add/replace for the SUMMARY_OUTPUT_VARS configuration variable
terminal_vars – the variable names to add/replace for the TERMINAL_OUTPUT_VARS configuration variable

Signals defined

This module defines and describes the signals used by PCSE

Signals are used by PCSE to notify components of events such as sowing, harvest and termination. Events can be send by any SimulationObject through its SimulationObject._send_signal() method. Similarly, any SimulationObject can receive signals by registering a handler through the SimulationObject._connect_signal() method. Variables can be passed to the handler of the signal through positional or keyword arguments. However, it is highly discouraged to use positional arguments when sending signals in order to avoid conflicts between positional and keyword arguments.

An example can help to clarify how signals are used in PCSE but check also the documentation of the PyDispatcher package for more information:

import sys, os
import math
sys.path.append('/home/wit015/Sources/python/pcse/')
import datetime as dt

import pcse
from pcse.base import SimulationObject, VariableKiosk

mysignal = "My first signal"

class MySimObj(SimulationObject):

    def initialize(self, day, kiosk):
        self._connect_signal(self.handle_mysignal, mysignal)

    def handle_mysignal(self, arg1, arg2):
        print "Value of arg1,2: %s, %s" % (arg1, arg2)

    def send_signal_with_exact_arguments(self):
        self._send_signal(signal=mysignal, arg2=math.pi, arg1=None)

    def send_signal_with_more_arguments(self):
        self._send_signal(signal=mysignal, arg2=math.pi, arg1=None, 
                          extra_arg="extra")

    def send_signal_with_missing_arguments(self):
        self._send_signal(signal=mysignal, arg2=math.pi, extra_arg="extra")


# Create an instance of MySimObj
day = dt.date(2000,1,1)
k = VariableKiosk()
mysimobj = MySimObj(day, k)

# This sends exactly the right amount of keyword arguments
mysimobj.send_signal_with_exact_arguments()

# this sends an additional keyword argument 'extra_arg' which is ignored.
mysimobj.send_signal_with_more_arguments()

# this sends the signal with a missing 'arg1' keyword argument which the handler
# expects and thus causes an error, raising a TypeError
try:
    mysimobj.send_signal_with_missing_arguments()
except TypeError, exc:
    print "TypeError occurred: %s" % exc

Saving this code as a file test_signals.py and importing it gives the following output:

>>> import test_signals
Value of arg1,2: None, 3.14159265359
Value of arg1,2: None, 3.14159265359
TypeError occurred: handle_mysignal() takes exactly 3 non-keyword arguments (1 given)

Currently the following signals are used within PCSE with the following keywords.

CROP_START

Indicates that a new crop cycle will start:
self._send_signal(signal=signals.crop_start, day=<date>,
                  crop_name=<string>, variety_name=<string>,
                  crop_start_type=<string>, crop_end_type=<string>)
keyword arguments with signals.crop_start:

day: Current date

crop_name: a string identifying the crop

variety_name: a string identifying the crop variety

crop_start_type: either ‘sowing’ or ‘emergence’

crop_end_type: either ‘maturity’, ‘harvest’ or ‘earliest’

CROP_FINISH

Indicates that the current crop cycle is finished:

self._send_signal(signal=signals.crop_finish, day=<date>,
                  finish_type=<string>, crop_delete=<True|False>)

keyword arguments with signals.crop_finish:

day: Current date

finish_type: string describing the reason for finishing the simulation, e.g. maturity, harvest, all leaves died, maximum duration reached, etc.

crop_delete: Set to True when the CropSimulation object must be deleted from the system, for example for the implementation of crop rotations. Defaults to False.

TERMINATE

Indicates that the entire system should terminate (crop & soil water balance) and that terminal output should be collected:
self._send_signal(signal=signals.terminate)
No keyword arguments are defined for this signal

OUTPUT

Indicates that the model state should be saved for later use:
self._send_signal(signal=signals.output)
No keyword arguments are defined for this signal

SUMMARY_OUTPUT

Indicates that the model state should be saved for later use, SUMMARY_OUTPUT is only generated when a CROP_FINISH signal is received indicating that the crop simulation must finish:
self._send_signal(signal=signals.output)
No keyword arguments are defined for this signal

APPLY_N

Is used for application of N fertilizer:

self._send_signal(signal=signals.apply_n, N_amount=<float>, N_recovery<float>)

Keyword arguments with signals.apply_n:

N_amount: Amount of fertilizer in kg/ha applied on this day.

N_recovery: Recovery fraction for the given type of fertilizer

APPLY_N_SNOMIN

Is used for application of N fertilizer with the SNOMIN module:

self._send_signal(signal=signals.apply_n_snomin,amount=<float>, application_depth=<float>,
                  cnratio=<float>, initial_age=<float>, f_NH4N=<float>, f_NO3N=<float>,
                  f_orgmat=<float>)

Keyword arguments with signals.apply_n_snomin:

amount: Amount of material in amendment (kg material ha-1)

application_depth: Depth over which the amendment is applied in the soil (cm)

cnratio: C:N ratio of organic matter in material (kg C kg-1 N)

initial_age: Initial apparent age of organic matter in material (year)

f_NH4N: Fraction of NH4+-N in material (kg NH4+-N kg-1 material)

f_NO3N: Fraction of NO3–N in material (kg NO3–N kg-1 material)

f_orgmat: Fraction of organic matter in amendment (kg OM kg-1 material)

IRRIGATE

Is used for sending irrigation events:

self._send_signal(signal=signals.irrigate, amount=<float>, efficiency=<float>)

Keyword arguments with signals.irrigate:

amount: Amount of irrigation in cm water applied on this day.

efficiency: efficiency of irrigation, meaning that the total amount of water that is added to the soil reservoir equals amount * efficiency

MOWING

Is used for sending mowing events used by the LINGRA/LINGRA-N models:

self._send_signal(signal=signals.mowing, biomass_remaining=<float>)

Keyword arguments with signals.mowing:

biomass_remaining: The amount of biomass remaining after mowing in kg/ha.

Ancillary code

The ancillary code section deals with tools for reading weather data and parameter values from files or databases.

Data providers

The module pcse.input contains all classes for reading weather files, parameter files and agromanagement files.

class pcse.input.NASAPowerWeatherDataProvider(latitude, longitude, force_update=False, ETmodel='PM')[source]

WeatherDataProvider for using the NASA POWER database with PCSE

Parameters

latitude – latitude to request weather data for
longitude – longitude to request weather data for
force_update – Set to True to force to request fresh data from POWER website.
ETmodel – “PM”|”P” for selecting penman-monteith or Penman method for reference evapotranspiration. Defaults to “PM”.

The NASA POWER database is a global database of daily weather data specifically designed for agrometeorological applications. The spatial resolution of the database is 0.25x0.25 degrees (as of 2018). It is derived from weather station observations in combination with satellite data for parameters like radiation.

The weather data is updated with a delay of about 5 days on realtime (depending on the variable) which makes the database unsuitable for real-time monitoring, nevertheless the POWER database is useful for many other studies and it is a major improvement compared to the monthly weather data that were used with WOFOST in the past.

For more information on the NASA POWER database see the documentation at: https://power.larc.nasa.gov/docs/

The NASAPowerWeatherDataProvider retrieves the weather from the th NASA POWER API and does the necessary conversions to be compatible with PCSE. After the data has been retrieved and stored, the contents are dumped to a binary cache file. If another request is made for the same location, the cache file is loaded instead of a full request to the NASA Power server.

Cache files are used until they are older then 90 days. After 90 days the NASAPowerWeatherDataProvider will make a new request to obtain more recent data from the NASA POWER server. If this request fails it will fall back to the existing cache file. The update of the cache file can be forced by setting force_update=True.

Finally, note that any latitude/longitude within a 0.25x0.25 degrees grid box will yield the same weather data, e.g. there is no difference between lat/lon 5.3/52.1 and lat/lon 5.35/52.2. Nevertheless slight differences in PCSE simulations may occur due to small differences in day length.

class pcse.input.CABOWeatherDataProvider(fname, fpath=None, ETmodel='PM', distance=1)[source]

Reader for CABO weather files.

Parameters

fname – root name of CABO weather files to read
fpath – path where to find files, can be absolute or relative.
ETmodel – “PM”|”P” for selecting penman-monteith or Penman method for reference evapotranspiration. Defaults to “PM”.
distance – maximum interpolation distance for meteorological variables, defaults to 1 day.

Returns

callable like object with meteo records keyed on date.

The Wageningen crop models that are written in FORTRAN or FST often use the CABO weather system (http://edepot.wur.nl/43010) for storing and reading weather data. This class implements a reader for the CABO weather files and also implements additional features like interpolation of weather data in case of missing values, conversion of sunshine duration to global radiation estimates and calculation the reference evapotranspiration values for water, soil and plants (E0, ES0, ET0) using the Penman approach.

A difference with the old CABOWE system is that the python implementation will read and store all files (e.g. years) available for a certain station instead of loading a new file when crossing a year boundary.

Note

some conversions are done by the CABOWeaterDataProvider from the units in the CABO weather file for compatibility with WOFOST:

vapour pressure from kPa to hPa
radiation from kJ/m2/day to J/m2/day
rain from mm/day to cm/day.
all evaporation/transpiration rates are also returned in cm/day.

Example

The file ‘nl1.003’ provides weather data for the year 2003 for the station in Wageningen and can be found in the cabowe/ folder of the WOFOST model distribution. This file can be read using:

>>> weather_data = CABOWeatherDataProvider('nl1', fpath="./meteo/cabowe")
>>> print weather_data(datetime.date(2003,7,26))
Weather data for 2003-07-26 (DAY)
IRRAD:  12701000.00  J/m2/day
 TMIN:        15.90   Celsius
 TMAX:        23.00   Celsius
  VAP:        16.50       hPa
 WIND:         3.00     m/sec
 RAIN:         0.12    cm/day
   E0:         0.36    cm/day
  ES0:         0.32    cm/day
  ET0:         0.31    cm/day
Latitude  (LAT):    51.97 degr.
Longitude (LON):     5.67 degr.
Elevation (ELEV):    7.0 m.

Alternatively the date in the print command above can be specified as string with format YYYYMMDD or YYYYDDD.

class pcse.input.ExcelWeatherDataProvider(xls_fname, missing_snow_depth=None, force_reload=False)[source]

Reading weather data from an excel file (.xlsx only).

Parameters

xls_fname – name of the Excel file to be read
mising_snow_depth – the value that should use for missing SNOW_DEPTH values, the default value is None.
force_reload – bypass the cache file, reload data from the .xlsx file and write a new cache file. Cache files are written under $HOME/.pcse/meteo_cache

For reading weather data from file, initially only the CABOWeatherDataProvider was available that reads its data from a text file in the CABO Weather format. Nevertheless, building CABO weather files is tedious as for each year a new file must constructed. Moreover it is rather error prone and formatting mistakes are easily leading to errors.

To simplify providing weather data to PCSE models, a new data provider was written that reads its data from simple excel files

The ExcelWeatherDataProvider assumes that records are complete and does not make an effort to interpolate data as this can be easily accomplished in Excel itself. Only SNOW_DEPTH is allowed to be missing as this parameter is usually not provided outside the winter season.

class pcse.input.CSVWeatherDataProvider(csv_fname, delimiter=',', dateformat='%Y%m%d', ETmodel='PM', force_reload=False)[source]

Reading weather data from a CSV file.

Parameters

csv_fname – name of the CSV file to be read
delimiter – CSV delimiter
dateformat – date format to be read. Default is ‘%Y%m%d’
ETmodel – “PM”|”P” for selecting Penman-Monteith or Penman method for reference evapotranspiration. Default is ‘PM’.
force_reload – Ignore cache file and reload from the CSV file

The CSV file should have the following structure (sample), missing values should be added as ‘NaN’:

## Site Characteristics
Country     = 'Netherlands'
Station     = 'Wageningen, Haarweg'
Description = 'Observed data from Station Haarweg in Wageningen'
Source      = 'Meteorology and Air Quality Group, Wageningen University'
Contact     = 'Peter Uithol'
Longitude = 5.67; Latitude = 51.97; Elevation = 7; AngstromA = 0.18; AngstromB = 0.55; HasSunshine = False
## Daily weather observations (missing values are NaN)
DAY,IRRAD,TMIN,TMAX,VAP,WIND,RAIN,SNOWDEPTH
20040101,NaN,-0.7,1.1,0.55,3.6,0.5,NaN
20040102,3888,-7.5,0.9,0.44,3.1,0,NaN
20040103,2074,-6.8,-0.5,0.45,1.8,0,NaN
20040104,1814,-3.6,5.9,0.66,3.2,2.5,NaN
20040105,1469,3,5.7,0.78,2.3,1.3,NaN
[...]

with
IRRAD in kJ/m2/day or hours
TMIN and TMAX in Celsius (°C)
VAP in kPa
WIND in m/sec
RAIN in mm
SNOWDEPTH in cm

For reading weather data from a file, initially the CABOWeatherDataProvider was available which read its data from text in the CABO weather format. Nevertheless, building CABO weather files is tedious as for each year a new file must constructed. Moreover it is rather error prone and formatting mistakes are easily leading to errors.

To simplify providing weather data to PCSE models, a new data provider has been derived from the ExcelWeatherDataProvider that reads its data from simple CSV files.

The CSVWeatherDataProvider assumes that records are complete and does not make an effort to interpolate data as this can be easily accomplished in a text editor. Only SNOWDEPTH is allowed to be missing as this parameter is usually not provided outside the winter season.

class pcse.input.CABOFileReader(fname)[source]

Reads CABO files with model parameter definitions.

The parameter definitions of Wageningen crop models are generally written in the CABO format. This class reads the contents, parses the parameter names/values and returns them as a dictionary.

Parameters: fname – parameter file to read and parse
Returns: dictionary like object with parameter key/value pairs.

Note that this class does not yet fully support reading all features of CABO files. For example, the parsing of booleans, date/times and tabular parameters is not supported and will lead to errors.

The header of the CABO file (marked with ** at the first line) is read and can be retrieved by the get_header() method or just by a print on the returned dictionary.

Example

A parameter file ‘parfile.cab’ which looks like this:

** CROP DATA FILE for use with WOFOST Version 5.4, June 1992
**
** WHEAT, WINTER 102
** Regions: Ireland, central en southern UK (R72-R79),
**          Netherlands (not R47), northern Germany (R11-R14)
CRPNAM='Winter wheat 102, Ireland, N-U.K., Netherlands, N-Germany'
CROP_NO=99
TBASEM   = -10.0    ! lower threshold temp. for emergence [cel]
DTSMTB   =   0.00,    0.00,     ! daily increase in temp. sum
            30.00,   30.00,     ! as function of av. temp. [cel; cel d]
            45.00,   30.00
** maximum and minimum concentrations of N, P, and K
** in storage organs        in vegetative organs [kg kg-1]
NMINSO   =   0.0110 ;       NMINVE   =   0.0030

Can be read with the following statements:

>>>fileparameters = CABOFileReader('parfile.cab')
>>>print fileparameters['CROP_NO']
99
>>>print fileparameters
** CROP DATA FILE for use with WOFOST Version 5.4, June 1992
**
** WHEAT, WINTER 102
** Regions: Ireland, central en southern UK (R72-R79),
**          Netherlands (not R47), northern Germany (R11-R14)
------------------------------------
TBASEM: -10.0 <type 'float'>
DTSMTB: [0.0, 0.0, 30.0, 30.0, 45.0, 30.0] <type 'list'>
NMINVE: 0.003 <type 'float'>
CROP_NO: 99 <type 'int'>
CRPNAM: Winter wheat 102, Ireland, N-U.K., Netherlands, N-Germany <type 'str'>
NMINSO: 0.011 <type 'float'>

class pcse.input.PCSEFileReader(fname)[source]

Reader for parameter files in the PCSE format.

This class is a replacement for the CABOFileReader. The latter can be used for reading parameter files in the CABO format, however this format has rather severe limitations: it only supports string, integer, float and array parameters. There is no support for specifying parameters with dates for example (other then specifying them as a string).

The PCSEFileReader is a much more versatile tool for creating parameter files because it leverages the power of the python interpreter for processing parameter files through the execfile functionality in python. This means that anything that can be done in a python script can also be done in a PCSE parameter file.

Parameters: fname – parameter file to read and parse
Returns: dictionary object with parameter key/value pairs.

Example

Below is an example of a parameter file ‘parfile.pcse’. Parameters can be defined the ‘CABO’-way, but also advanced functionality can be used by importing modules, defining parameters as dates or numpy arrays and even applying function on arrays (in this case np.sin):

'''This is the header of my parameter file.

This file is derived from the following sources
* dummy file for demonstrating the PCSEFileReader
* contains examples how to leverage dates, arrays and functions, etc.
'''

import numpy as np
import datetime as dt

TSUM1 = 1100
TSUM2 = 900
DTSMTB = [ 0., 0.,
           5., 5.,
          20., 25.,
          30., 25.]
AMAXTB = np.sin(np.arange(12))
cropname = 'alfalfa'
CROP_START_DATE = dt.date(2010,5,14)

Can be read with the following statements:

>>>fileparameters = PCSEFileReader('parfile.pcse')
>>>print fileparameters['TSUM1']
1100
>>>print fileparameters['CROP_START_DATE']
2010-05-14
>>>print fileparameters
PCSE parameter file contents loaded from:
D:\UserData\pcse_examples\parfile.pw

This is the header of my parameter file.

This file is derived from the following sources
* dummy file for demonstrating the PCSEFileReader
* contains examples how to leverage dates, arrays and functions, etc.
DTSMTB: [0.0, 0.0, 5.0, 5.0, 20.0, 25.0, 30.0, 25.0] (<type 'list'>)
CROP_START_DATE: 2010-05-14 (<type 'datetime.date'>)
TSUM2: 900 (<type 'int'>)
cropname: alfalfa (<type 'str'>)
AMAXTB: [ 0.          0.84147098  0.90929743  0.14112001 -0.7568025
  -0.95892427  -0.2794155   0.6569866   0.98935825  0.41211849
  -0.54402111 -0.99999021] (<type 'numpy.ndarray'>)
TSUM1: 1100 (<type 'int'>)

class pcse.input.YAMLAgroManagementReader(fname)[source]

Reads PCSE agromanagement files in the YAML format.

Parameters: fname – filename of the agromanagement file. If fname is not provided as a absolute or relative path the file is assumed to be in the current working directory.

class pcse.input.YAMLCropDataProvider(model=<class 'pcse.models.Wofost72_PP'>, fpath=None, repository=None, force_reload=False)[source]

A crop data provider for reading crop parameter sets stored in the YAML format.

param model

a model import from pcse.models. This will allow the YAMLCropDataProvider to select the correct branch for each model version. If not provided then pcse.models.Wofost72_PP will be used as default.

param fpath

full path to directory containing YAML files

param repository

URL to repository containg YAML files. This url should be the raw content (e.g. starting with ‘https://raw.githubusercontent.com’)

param force_reload

If set to True, the cache file is ignored and al parameters are reloaded (default False).

This crop data provider can read and store the parameter sets for multiple crops which is different from most other crop data providers that only can hold data for a single crop. This crop data providers is therefore suitable for running crop rotations with different crop types as the data provider can switch the active crop.

The most basic use is to call YAMLCropDataProvider with no parameters. It will than pull the crop parameters for WOFOST 7.2 from my github repository at https://github.com/ajwdewit/WOFOST_crop_parameters/tree/wofost72:

>>> from pcse.input import YAMLCropDataProvider
>>> p = YAMLCropDataProvider()
>>> print(p)
Crop parameters loaded from: https://raw.githubusercontent.com/ajwdewit/WOFOST_crop_parameters/wofost72
YAMLCropDataProvider - crop and variety not set: no activate crop parameter set!

For a specific model and version just pass the model onto the CropDataProvider::

>>> from pcse.models import Wofost81_PP
>>> p = YAMLCropDataProvider(Wofost81_PP)
>>> print(p)
Crop parameters loaded from: https://raw.githubusercontent.com/ajwdewit/WOFOST_crop_parameters/wofost81
Crop and variety not set: no active crop parameter set!

All crops and varieties have been loaded from the YAML file, however no activate crop has been set. Therefore, we need to activate a a particular crop and variety:

>>> p.set_active_crop('wheat', 'Winter_wheat_101')
>>> print(p)
Crop parameters loaded from: https://raw.githubusercontent.com/ajwdewit/WOFOST_crop_parameters/wofost81
YAMLCropDataProvider - current active crop 'wheat' with variety 'Winter_wheat_101'
Available crop parameters:
 {'DTSMTB': [0.0, 0.0, 30.0, 30.0, 45.0, 30.0], 'NLAI_NPK': 1.0, 'NRESIDLV': 0.004,
 'KCRIT_FR': 1.0, 'RDRLV_NPK': 0.05, 'TCPT': 10, 'DEPNR': 4.5, 'KMAXRT_FR': 0.5,
 ...
 ...
 'TSUM2': 1194, 'TSUM1': 543, 'TSUMEM': 120}

Additionally, it is possible to load YAML parameter files from your local file system:

>>> p = YAMLCropDataProvider(fpath=r"D:\UserData\sources\WOFOST_crop_parameters")
>>> print(p)
YAMLCropDataProvider - crop and variety not set: no activate crop parameter set!

Finally, it is possible to pull data from your fork of my github repository by specifying the URL to that repository:

>>> p = YAMLCropDataProvider(repository="https://raw.githubusercontent.com/<your_account>/WOFOST_crop_parameters/<branch>/")

To increase performance of loading parameters, the YAMLCropDataProvider will create a cache file that can be restored much quicker compared to loading the YAML files. When reading YAML files from the local file system, care is taken to ensure that the cache file is re-created when updates to the local YAML are made. However, it should be stressed that this is not possible when parameters are retrieved from a URL and there is a risk that parameters are loaded from an outdated cache file. By default, the cache file will be recreated after 7 days, but in order to force an update use force_reload=True to force loading the parameters from the URL.

class pcse.input.WOFOST72SiteDataProvider(**kwargs)[source]

Site data provider for WOFOST 7.2.

Site specific parameters for WOFOST 7.2 can be provided through this data provider as well as through a normal python dictionary. The sole purpose of implementing this data provider is that the site parameters for WOFOST are documented, checked and that sensible default values are given.

The following site specific parameter values can be set through this data provider:

- IFUNRN    Indicates whether non-infiltrating fraction of rain is a function of storm size (1)
            or not (0). Default 0
- NOTINF    Maximum fraction of rain not-infiltrating into the soil [0-1], default 0.
- SSMAX     Maximum depth of water that can be stored on the soil surface [cm]
- SSI       Initial depth of water stored on the surface [cm]
- WAV       Initial amount of water in total soil profile [cm]
- SMLIM     Initial maximum moisture content in initial rooting depth zone [0-1], default 0.4

Currently only the value for WAV is mandatory to specify.

class pcse.input.WOFOST73SiteDataProvider(**kwargs)[source]

Site data provider for WOFOST 7.3

Site specific parameters for WOFOST 7.3 can be provided through this data provider as well as through a normal python dictionary. The sole purpose of implementing this data provider is that the site parameters for WOFOST are documented, checked and that sensible default values are given.

The following site specific parameter values can be set through this data provider:

- IFUNRN    Indicates whether non-infiltrating fraction of rain is a function of storm size (1)
            or not (0). Default 0
- NOTINF    Maximum fraction of rain not-infiltrating into the soil [0-1], default 0.
- SSMAX     Maximum depth of water that can be stored on the soil surface [cm]
- SSI       Initial depth of water stored on the surface [cm]
- WAV       Initial amount of water in total soil profile [cm]
- SMLIM     Initial maximum moisture content in initial rooting depth zone [0-1], default 0.4
- CO2       Atmospheric CO2 concentration in ppm

Values for WAV and CO2 is mandatory to specify.

class pcse.input.WOFOST81SiteDataProvider_Classic(**kwargs)[source]

Site data provider for WOFOST 8.1 for Classic water and nitrogen balance.

Site specific parameters for WOFOST 8.1 can be provided through this data provider as well as through a normal python dictionary. The sole purpose of implementing this data provider is that the site parameters for WOFOST are documented, checked and that sensible default values are given.

The following site specific parameter values can be set through this data provider:

- IFUNRN        Indicates whether non-infiltrating fraction of rain is a function of
                storm size (1) or not (0). Default 0
- NOTINF        Maximum fraction of rain not-infiltrating into the soil [0-1],
                default 0.
- SSMAX         Maximum depth of water that can be stored on the soil surface [cm]
- SSI           Initial depth of water stored on the surface [cm]
- WAV           Initial amount of water in total soil profile [cm]
- SMLIM         Initial maximum moisture content in initial rooting depth zone [0-1],
                default 0.4
- CO2           Atmospheric CO2 level (ppm), default 360.
- BG_N_SUPPLY   Background N supply through atmospheric deposition in kg/ha/day. Can be
                in the order of 25 kg/ha/year in areas with high N pollution. Default 0.0
- NSOILBASE     Base N amount available in the soil. This is often estimated as the nutrient
                left over from the previous growth cycle (surplus nutrients, crop residues
                or green manure).
- NSOILBASE_FR  Daily fraction of soil N coming available through mineralization
- NAVAILI       Amount of N available in the pool at initialization of the system [kg/ha]

Currently, the parameters for initial water availability (WAV) and initial availability of nutrients (NAVAILI) are mandatory to specify.

class pcse.input.WOFOST81SiteDataProvider_SNOMIN(**kwargs)[source]

Site data provider for WOFOST 8.1 for use with the SNOMIN C/N balance.

The following site specific parameter values can be set through this data provider:

- IFUNRN        Indicates whether non-infiltrating fraction of rain is a function of
                storm size (1) or not (0). Default 0
- NOTINF        Maximum fraction of rain not-infiltrating into the soil [0-1],
                default 0.
- SSMAX         Maximum depth of water that can be stored on the soil surface [cm]
- SSI           Initial depth of water stored on the surface [cm]
- WAV           Initial amount of water in total soil profile [cm]
- SMLIM         Initial maximum moisture content in initial rooting depth zone [0-1],
                default 0.4
- CO2           Atmospheric CO2 level, currently around 400. [ppm]
- A0SOM         Initial age of organic material (24.0)  [year]
- CNRatioBio    C:N ratio of microbial biomass  (9.0) [kg C kg-1 N]
- FASDIS        Assimilation to dissimilation rate ratio (0.5) [-]
- KDENIT_REF    Reference first order rate of denitrification (0.06) [d-1]
- KNIT_REF      Reference first order rate of nitrification (1.0) [d-1]
- KSORP         Sorption coefficient (0.0005) [m3 soil kg-1 soil]
- MRCDIS        Michaelis-Menten constant of relationship organic C-dissimilation rate
                and response factor denitrification rate (0.001) [kg C m-2 d-1]
- NH4ConcR      NH4-N concentration in rain water (0.9095) [mg NH4+-N L-1 water]
- NO3ConcR      NO3-N concentration in rain water (2.1) [mg NO3--N L-1 water]
- NH4I          Initial amount of NH4+ per soil layer  [kg NH4+ ha-1]. This
                should match the number of soil layers specified in the soil
                configuration. The initial value can be highly variable and as
                high as 300-500 kg/ha of NH4/NO3 if the model was started right
                after an N application event.
- NO3I          Initial amount of NO3-N per soil layer [kg NO3-N ha-1]. This
                should match the number of soil layers specified in the soil
                configuration. The initial value can be highly variable and as
                high as 300-500 kg/ha of NH4/NO3 if the model was started right
                after an N application event.
- WFPS_CRIT     Critical fraction water filled soil pores (0.8)  [m3 water m-3 pores]


*important*: Some of the valid ranges of parameters for WOFOST 8.1/SNOMIN are uncertain
and therefore values outside of the specified ranges here may be valid in certain cases.

Simple or dummy data providers

This class of data providers can be used to provide parameter values in cases where separate files or a database is not needed or not practical. An example is the set of soil parameters for simulation of potential production conditions where the value of the parameters does not matter but nevertheless some values must be provided to the model.

class pcse.util.DummySoilDataProvider[source]

This class is to provide some dummy soil parameters for potential production simulation.

Simulation of potential production levels is independent of the soil. Nevertheless, the model does not some parameter values. This data provider provides some hard coded parameter values for this situation.

The database tools

The database tools contain functions and classes for retrieving agromanagement, parameter values and weather variables from database structures implemented for different versions of the European Crop Growth Monitoring System.

Note that the data providers only provide functionality for reading data, there are no tools here writing simulation results to a CGMS database. This was done on purpose as writing data can be a complex matter and it is our experience that this can be done more easily with dedicated database loader tools such as SQLLoader for ORACLE or the load data infile syntax of MySQL.

The CGMS8 database

The CGMS8 tools are for reading data from a database structure that is used by CGMS executable version 9 and 10.

class pcse.db.cgms8.GridWeatherDataProvider(engine, grid_no, start_date=None, end_date=None, recalc_ET=False, use_cache=True)[source]

Retrieves meteodata from the GRID_WEATHER table in a CGMS database.

Parameters

metadata – SqlAlchemy metadata object providing DB access
grid_no – CGMS Grid ID
startdate – Retrieve meteo data starting with startdate (datetime.date object)
enddate – Retrieve meteo data up to and including enddate (datetime.date object)
recalc_ET – Set to True to force calculation of reference ET values. Mostly useful when values have not been calculated in the CGMS database.
use_cache – Set to False to ignore read/writing a cache file.

Note that all meteodata is first retrieved from the DB and stored internally. Therefore, no DB connections are stored within the class instance. This makes that class instances can be pickled.

class pcse.db.cgms8.SoilDataIterator(engine, grid_no)[source]

Soil data iterator for CGMS8.

The only difference is that in CGMS8 the table is called ‘ELEMENTARY_MAPPING_UNIT’ and in CGMS12 it is called ‘EMU’

class pcse.db.cgms8.CropDataProvider(engine, grid_no, crop_no, campaign_year)[source]

Retrieves the crop parameters for the given grid_no, crop_no and year from the tables CROP_CALENDAR, CROP_PARAMETER_VALUE and VARIETY_PARAMETER_VALUE.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Integer grid ID, maps to the GRID_NO column in the table
crop_no – Integer crop ID, maps to the CROP_NO column in the table
campaign_year – Integer campaign year, maps to the YEAR column in the table. The campaign year usually refers to the year of the harvest. Thus for crops crossing calendar years, the start_date can be in the previous year.

class pcse.db.cgms8.STU_Suitability(engine, crop_no)[source]

Returns a set() of suitable STU’s for given crop_no.

Parameters

engine – SqlAlchemy engine object providing DB access
crop_no – Integer crop ID, maps to the CROP_NO column in the table

class pcse.db.cgms8.SiteDataProvider(engine, grid_no, crop_no, campaign_year, stu_no)[source]

Provides the site data from the tables INITIAL_SOIL_WATER and SITE.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Grid number (int)
crop_no – Crop number (int)
campaign_year – Campaign year (int)
stu_no – soil typologic unit number (int)

Note that the parameter SSI (Initial surface storage) is set to zero

Moreover, the start date of the water balance is defined by the column GIVEN_STARTDATE_WATBAL. This value can be accessed as an attribute start_date_waterbalance.

The CGMS12 database

The CGMS12 tools are for reading data from a CGMS12 database structure that is used by CGMS executable version 11 and BioMA 2014.

Tools for reading weather data and timer, soil and site parameters from a CGMS12 compatible database.

class pcse.db.cgms12.WeatherObsGridDataProvider(engine, grid_no, start_date=None, end_date=None, recalc_ET=False, recalc_TEMP=False, use_cache=True)[source]

Retrieves meteodata from the WEATHER_OBS_GRID table in a CGMS12 compatible database.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Grid number (int) to retrieve data for
start_date – Retrieve meteo data starting with start_date (datetime.date object)
end_date – Retrieve meteo data up to and including end_date (datetime.date object)
recalc_ET – Set to True to force calculation of reference ET values. Mostly useful when values have not been calculated in the CGMS database.
recalc_TEMP – Set to True to force calculation of daily average temperature (TEMP) from TMIN and TMAX: TEMP = (TMIN+TMAX)/2.

Note that all meteodata is first retrieved from the DB and stored internally. Therefore, no DB connections are stored within the class instance. This makes that class instances can be pickled.

If start_date and end_date are not provided then the entire time-series for the grid is retrieved.

class pcse.db.cgms12.AgroManagementDataProvider(engine, grid_no, crop_no, campaign_year, campaign_start=None)[source]

Class for providing agromanagement data from the CROP_CALENDAR table in a CGMS12 database.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Integer grid ID, maps to the grid_no column in the table
crop_no – Integer id of crop, maps to the crop_no column in the table
campaign_year – Integer campaign year, maps to the YEAR column in the table. The campaign year usually refers to the year of the harvest. Thus for crops crossing calendar years, the start_date can be in the previous year.
campaign_start –
Optional keyword that can be used to define the start of the campaign. Note that by default the campaign_start_date is set equal to the crop_start_date which means that the simulation starts when the crop starts. This default behaviour can be changed using this keyword. It can have multiple meanings:
- if a date object is passed, the campaign is assumed to start on this date.
- if an int/float is passed, the campaign_start_date is calculated as the crop_start_date minus the number of days provided by campaign_start.

For adjusting the campaign_start_Date, see also the set_campaign_start_date(date) method to update the campaign_start_date on an existing AgroManagementDataProvider.

set_campaign_start_date(start_date)[source]

Updates the value for the campaign_start_date.

This is useful only when the INITIAL_SOIL_WATER table in CGMS12 defines a different campaign_start

class pcse.db.cgms12.SoilDataIterator(engine, grid_no)[source]

Class for iterating over the different soils in a CGMS grid.

Instances of this class behave like a list, allowing to iterate over the soils in a CGMS grid. An example:

>>> soil_iterator = SoilDataIterator(engine, grid_no=15060)
>>> print(soildata)
Soil data for grid_no=15060 derived from oracle+cx_oracle://cgms12eu:***@eurdas.world
  smu_no=9050131, area=625000000, stu_no=9000282 covering 50% of smu.
    Soil parameters {'SMLIM': 0.312, 'SMFCF': 0.312, 'SMW': 0.152, 'CRAIRC': 0.06,
                     'KSUB': 10.0, 'RDMSOL': 10.0, 'K0': 10.0, 'SOPE': 10.0, 'SM0': 0.439}
  smu_no=9050131, area=625000000, stu_no=9000283 covering 50% of smu.
    Soil parameters {'SMLIM': 0.28325, 'SMFCF': 0.28325, 'SMW': 0.12325, 'CRAIRC': 0.06,
                     'KSUB': 10.0, 'RDMSOL': 40.0, 'K0': 10.0, 'SOPE': 10.0, 'SM0': 0.42075}
>>> for smu_no, area, stu_no, percentage, soil_par in soildata:
...     print(smu_no, area, stu_no, percentage)
...
(9050131, 625000000, 9000282, 50)
(9050131, 625000000, 9000283, 50)

class pcse.db.cgms12.CropDataProvider(engine, grid_no, crop_no, campaign_year)[source]

Retrieves the crop parameters for the given grid_no, crop_no and year from the tables CROP_CALENDAR, CROP_PARAMETER_VALUE and VARIETY_PARAMETER_VALUE.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Integer grid ID, maps to the GRID_NO column in the table
crop_no – Integer crop ID, maps to the CROP_NO column in the table
campaign_year – Integer campaign year, maps to the YEAR column in the table. The campaign year usually refers to the year of the harvest. Thus for crops crossing calendar years, the start_date can be in the previous year.

class pcse.db.cgms12.STU_Suitability(engine, crop_no)[source]

Returns a set() of suitable STU’s for given crop_no.

Parameters

engine – SqlAlchemy engine object providing DB access
crop_no – Integer crop ID, maps to the CROP_NO column in the table

class pcse.db.cgms12.SiteDataProvider(engine, grid_no, crop_no, campaign_year, stu_no)[source]

Provides the site data from the tables INITIAL_SOIL_WATER and SITE.

Parameters

engine – SqlAlchemy engine object providing DB access
grid_no – Grid number (int)
crop_no – Crop number (int)
campaign_year – Campaign year (int)
stu_no – soil typologic unit number (int)

Note that the parameter SSI (Initial surface storage) is set to zero

Moreover, the start date of the water balance is defined by the column GIVEN_STARTDATE_WATBAL. This value can be accessed as an attribute start_date_waterbalance.

The CGMS14 database

The CGMS14 database is the database structure that is compatible with the 2015 BioMA implementation of WOFOST. Note that the CGMS14 database structure is considerably different from CGMS8 and CGMS12.

Convenience routines

These routines are there for conveniently starting a WOFOST simulation for the demonstration and tutorials. They can serve as an example to build your own script but have no further relevance.

pcse.start_wofost.start_wofost(grid=31031, crop=1, year=2000, mode='wlp', dsn=None)[source]

Provides a convenient interface for starting a WOFOST instance

If started with no arguments, the routine will connnect to the demo database and initialize WOFOST for winter-wheat (cropno=1) in Spain (grid_no=31031) for the year 2000 in water-limited production (mode=’wlp’)

Parameters

grid – grid number, defaults to 31031
crop – crop number, defaults to 1 (winter-wheat in the demo database)
year – year to start, defaults to 2000
mode – production mode (‘pp’ or ‘wlp’), defaults to ‘wlp’
dsn – PCSE DB as SQLAlchemy data source name defaults to None and in that case a connection to the demo database will be established.

example:

>>> import pcse
>>> wofsim = pcse.start_wofost(grid=31031, crop=1, year=2000, 
...   mode='wlp')
>>> 
>>> wofsim
<pcse.models.Wofost71_WLP_FD at 0x35f2550>
>>> wofsim.run(days=300)
>>> wofsim.get_variable('tagp')
15261.752187075261

Miscelaneous utilities

Many miscelaneous function for a variety of purposes such as the Arbitrary Function Generator (AfGen) for linear interpolation and functions for calculating Penman Penman/Monteith reference evapotranspiration, the Angstrom equation and astronomical calculations such as day length.

pcse.util.reference_ET(DAY, LAT, ELEV, TMIN, TMAX, IRRAD, VAP, WIND, ANGSTA, ANGSTB, ETMODEL='PM', **kwargs)[source]

Calculates reference evapotranspiration values E0, ES0 and ET0.

The open water (E0) and bare soil evapotranspiration (ES0) are calculated with the modified Penman approach, while the references canopy evapotranspiration is calculated with the modified Penman or the Penman-Monteith approach, the latter is the default.

Input variables:

DAY     -  Python datetime.date object                      -
LAT     -  Latitude of the site                          degrees
ELEV    -  Elevation above sea level                        m
TMIN    -  Minimum temperature                              C
TMAX    -  Maximum temperature                              C
IRRAD   -  Daily shortwave radiation                     J m-2 d-1
VAP     -  24-hour average vapour pressure                 hPa
WIND    -  24-hour average windspeed at 2 meter            m/s
ANGSTA  -  Empirical constant in Angstrom formula           -
ANGSTB  -  Empirical constant in Angstrom formula           -
ETMODEL -  Indicates if the canopy reference ET should     PM|P
           be calculated with the Penman-Monteith method
           (PM) or the modified Penman method (P)

Output is a tuple (E0, ES0, ET0):

E0      -  Penman potential evaporation from a free
           water surface [mm/d]
ES0     -  Penman potential evaporation from a moist
           bare soil surface [mm/d]
ET0     -  Penman or Penman-Monteith potential evapotranspiration from a
           crop canopy [mm/d]

Note

The Penman-Monteith algorithm is valid only for a reference canopy, and therefore it is not used to calculate the reference values for bare soil and open water (ES0, E0).

The background is that the Penman-Monteith model is basically a surface energy balance where the net solar radiation is partitioned over latent and sensible heat fluxes (ignoring the soil heat flux). To estimate this partitioning, the PM method makes a connection between the surface temperature and the air temperature. However, the assumptions underlying the PM model are valid only when the surface where this partitioning takes place is the same for the latent and sensible heat fluxes.

For a crop canopy this assumption is valid because the leaves of the canopy form the surface where both latent heat flux (through stomata) and sensible heat flux (through leaf temperature) are partitioned. For a soil, this principle does not work because when the soil is drying the evaporation front will quickly disappear below the surface and therefore the assumption that the partitioning surface is the same does not hold anymore.

For water surfaces, the assumptions underlying PM do not hold because there is no direct relationship between the temperature of the water surface and the net incoming radiation as radiation is absorbed by the water column and the temperature of the water surface is co-determined by other factors (mixing, etc.). Only for a very shallow layer of water (1 cm) the PM methodology could be applied.

For bare soil and open water the Penman model is preferred. Although it partially suffers from the same problems, it is calibrated somewhat better for open water and bare soil based on its empirical wind function.

Finally, in crop simulation models the open water evaporation and bare soil evaporation only play a minor role (pre-sowing conditions and flooded rice at early stages), it is not worth investing much effort in improved estimates of reference value for E0 and ES0.

pcse.util.penman_monteith(DAY, LAT, ELEV, TMIN, TMAX, AVRAD, VAP, WIND2)[source]

Calculates reference ET0 based on the Penman-Monteith model.

This routine calculates the potential evapotranspiration rate from a reference crop canopy (ET0) in mm/d. For these calculations the analysis by FAO is followed as laid down in the FAO publication Guidelines for computing crop water requirements - FAO Irrigation and drainage paper 56

Input variables:

DAY   -  Python datetime.date object                   -
LAT   -  Latitude of the site                        degrees
ELEV  - Elevation above sea level                      m
TMIN  - Minimum temperature                            C
TMAX  - Maximum temperature                            C
AVRAD - Daily shortwave radiation                   J m-2 d-1
VAP   - 24-hour average vapour pressure               hPa
WIND2 - 24-hour average windspeed at 2 meter          m/s

Output is:

ET0 - Penman-Monteith potential transpiration
rate from a crop canopy [mm/d]

pcse.util.penman(DAY, LAT, ELEV, TMIN, TMAX, AVRAD, VAP, WIND2, ANGSTA, ANGSTB)[source]

Calculates E0, ES0, ET0 based on the Penman model.

This routine calculates the potential evapo(transpi)ration rates from a free water surface (E0), a bare soil surface (ES0), and a crop canopy (ET0) in mm/d. For these calculations the analysis by Penman is followed (Frere and Popov, 1979;Penman, 1948, 1956, and 1963). Subroutines and functions called: ASTRO, LIMIT.

Input variables:

DAY     -  Python datetime.date object                                    -
LAT     -  Latitude of the site                        degrees
ELEV    -  Elevation above sea level                      m
TMIN    -  Minimum temperature                            C
TMAX    -  Maximum temperature                            C
AVRAD   -  Daily shortwave radiation                   J m-2 d-1
VAP     -  24-hour average vapour pressure               hPa
WIND2   -  24-hour average windspeed at 2 meter          m/s
ANGSTA  -  Empirical constant in Angstrom formula         -
ANGSTB  -  Empirical constant in Angstrom formula         -

Output is a tuple (E0,ES0,ET0):

E0      -  Penman potential evaporation from a free water surface [mm/d]
ES0     -  Penman potential evaporation from a moist bare soil surface [mm/d]
ET0     -  Penman potential transpiration from a crop canopy [mm/d]

pcse.util.check_angstromAB(xA, xB)[source]

Routine checks validity of Angstrom coefficients.

This is the python version of the FORTRAN routine ‘WSCAB’ in ‘weather.for’.

pcse.util.wind10to2(wind10)[source]: Converts windspeed at 10m to windspeed at 2m using log. wind profile

pcse.util.angstrom(day, latitude, ssd, cA, cB)[source]

Compute global radiation using the Angstrom equation.

Global radiation is derived from sunshine duration using the Angstrom equation: globrad = Angot * (cA + cB * (sunshine / daylength)

Parameters

day – day of observation (date object)
latitude – Latitude of the observation
ssd – Observed sunshine duration
cA – Angstrom A parameter
cB – Angstrom B parameter

Returns

the global radiation in J/m2/day

pcse.util.doy(day)[source]: Converts a date or datetime object to day-of-year (Jan 1st = doy 1)

pcse.util.limit(vmin, vmax, v)[source]: limits the range of v between min and max

pcse.util.daylength(day, latitude, angle=- 4, _cache={})[source]

Calculates the daylength for a given day, altitude and base.

Parameters

day – date/datetime object
latitude – latitude of location
angle – The photoperiodic daylength starts/ends when the sun is angle degrees under the horizon. Default is -4 degrees.

Derived from the WOFOST routine ASTRO.FOR and simplified to include only daylength calculation. Results are being cached for performance

pcse.util.astro(day, latitude, radiation, _cache={})[source]

python version of ASTRO routine by Daniel van Kraalingen.

This subroutine calculates astronomic daylength, diurnal radiation characteristics such as the atmospheric transmission, diffuse radiation etc.

Parameters

day – date/datetime object
latitude – latitude of location
radiation – daily global incoming radiation (J/m2/day)

output is a namedtuple in the following order and tags:

DAYL      Astronomical daylength (base = 0 degrees)     h
DAYLP     Astronomical daylength (base =-4 degrees)     h
SINLD     Seasonal offset of sine of solar height       -
COSLD     Amplitude of sine of solar height             -
DIFPP     Diffuse irradiation perpendicular to
          direction of light                         J m-2 s-1
ATMTR     Daily atmospheric transmission                -
DSINBE    Daily total of effective solar height         s
ANGOT     Angot radiation at top of atmosphere       J m-2 d-1

Authors: Daniel van Kraalingen Date : April 1991

Python version Author : Allard de Wit Date : January 2011

pcse.util.merge_dict(d1, d2, overwrite=False)[source]

Merge contents of d1 and d2 and return the merged dictionary

Note:

The dictionaries d1 and d2 are unaltered.
If overwrite=False (default), a RuntimeError will be raised when duplicate keys exist, else any existing keys in d1 are silently overwritten by d2.

class pcse.util.Afgen(tbl_xy)[source]

Emulates the AFGEN function in WOFOST.

Parameters: tbl_xy – List or array of XY value pairs describing the function the X values should be mononically increasing.

Returns the interpolated value provided with the absicca value at which the interpolation should take place.

example:

>>> tbl_xy = [0,0,1,1,5,10]
>>> f =  Afgen(tbl_xy)
>>> f(0.5)
0.5
>>> f(1.5)
2.125
>>> f(5)
10.0
>>> f(6)
10.0
>>> f(-1)
0.0

pcse.util.is_a_month(day)[source]: Returns True if the date is on the last day of a month.

pcse.util.is_a_dekad(day)[source]: Returns True if the date is on a dekad boundary, i.e. the 10th, the 20th or the last day of each month

pcse.util.is_a_week(day, weekday=0)[source]: Default weekday is Monday. Monday is 0 and Sunday is 6

pcse.util.load_SQLite_dump_file(dump_file_name, SQLite_db_name)[source]: Build an SQLite database <SQLite_db_name> from dump file <dump_file_name>.

Code documentation

How to read

Engine and models

Agromanagement modules

The Timer

Soil process modules

Water balance modules

Nitrogen and Carbon modules

Crop simulation processes for WOFOST

Phenology

Partitioning

CO2 Assimilation

Maintenance respiration

Evapotranspiration

Leaf dynamics

Root dynamics

Stem dynamics

Storage organ dynamics

Crop N dynamics

Abiotic damage

Crop simulation processes for LINGRA

Overall grassland model

Source/Sink limited growth

Nitrogen dynamics

Crop simulation processes for LINTUL

Base classes

VariableKiosk

Base classes for parameters, rates and states

Base and utility classes for weather data

Configuration loading

Signals defined

Ancillary code

Data providers

Simple or dummy data providers

The database tools

The CGMS8 database

The CGMS12 database

The CGMS14 database

Convenience routines

Miscelaneous utilities

CO₂ Assimilation