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. classpcse.engine.CGMSEngine(**kwargs)[source] Engine to mimic CGMS behaviour. The original CGMS did not terminate when the crop cycle 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. classpcse.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_ (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. classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.models.Wofost72_PP(**kwargs)[source] Convenience class for running WOFOST7.2 Potential Production. see pcse.engine.Engine for description of arguments and keywords classpcse.models.Wofost72_Phenology(**kwargs)[source] Convenience class for running WOFOST7.2 phenology only. see pcse.engine.Engine for description of arguments and keywords classpcse.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 classpcse.models.Wofost73_PP(**kwargs)[source] Convenience class for running WOFOST7.3 Potential Production. see pcse.engine.Engine for description of arguments and keywords classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.models.Wofost81_PP(**kwargs)[source] Convenience class for running WOFOST8.1 potential production see pcse.engine.Engine for description of arguments and keywords classpcse.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 classpcse.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. classpcse.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: propertyend_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. propertyndays_in_crop_cycle Returns the number of days of the current cropping cycle. Returns zero if no crop cycle is active. propertystart_date Retrieves the start date of the agromanagement sequence, e.g. the first simulation date Returns : a date object classpcse.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 classpcse.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 classpcse.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 classpcse.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. classpcse.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 classpcse.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 KSUB maximum percolation rate subsoil SSo 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 EVSMX Maximum evaporation rate from a soil surface below the crop canopy Evapotranspiration EVWMX Maximum evaporation rate from a water surface below the crop canopy Evapotranspiration 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). classpcse.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 classpcse.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 classpcse.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). classpcse.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 TMINACCU2 Lower critical minimum temperature for snow accumulation SSi TMINCRIT Critical minimum temperature for snow melt SSi TMAXCRIT Critical maximum temperature for snow melt SSi RMELT Melting rate per day per degree Celcius above the critical minimum temperature. SSi 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 RSNOWSUBLIM Rate of snow sublimation N RSNOWMELT Rate of snow melting N 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. classpcse.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 TRAMX Potential crop transpiration increase Evapotranspiration RNuptake Rate of N uptake by the crop NPK_Demand_Uptake kg ha-1day-1 classpcse.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 1 kg NO3–N ha-1 NH4I Initial amount of NH4-N 1 kg NH4+-N ha-1) WFPS_CRIT Critical water filled pore space fraction m3 water m-3 pore 1 This state variable is defined for each soil layer State variables Name Description Unit AGE Appearant age of amendment (d) 1 d ORGMAT Amount of organic matter (kg ORG ha-1) 1 kg OM m-2 CORG Amount of C in organic matter (kg C ha-1) 1 kg C m-2 NORG Amount of N in organic matter (kg N ha-1) 1 kg N m-2 NH4 Amount of NH4-N (kg N ha-1) 2 kg NH4-N m-2 NO3 Amount of NO3-N (kg N ha-1) 2 kg NO3-N m-2 1 This state variable is defined for each combination of soil layer and amendment 2 This state variable is defined for each soil layer Rate variables Name Description Unit RAGE Rate of change of apparent age 2 d d-1 RAGEAM Initial apparent age 2 d d-1 RAGEAG Rate of ageing of amendment 2 d d-1 RCORG Rate of change of organic C 2 kg C m-2 d-1 RCORGAM Rate pf application organic C 2 kg C m-2 d-1 RCORGDIS Dissimilation rate of organic C 2 kg C m-2 d-1 RNH4 Rate of change amount of NH4+-N 1 kg NH4+-N m-2 d-1 RNH4AM Rate of NH4+-N application 1 kg NH4+-N m-2 d-1 RNH4DEPOS Rate of NH4-N deposition 1 kg NH4+-N m-2 d-1 RNH4IN Rate of NH4+-N inflow from adjacent layer 1 kg NH4+-N m-2 d-1 RNH4MIN Net rate of mineralization 1 kg NH4+-N m-2 d-1 RNH4NITR Rate of nitrification 1 kg NH4+-N m-2 d-1 RNH4OUT Rate of NH4+-N outflow to adjacent layer 1 kg NH4+-N m-2 d-1 RNH4UP Rate of NH4+-N root uptake 1 kg NH4+-N m-2 d-1 RNO3 Rate of change amount of NO3–N 1 kg NO3–N m-2 d-1 RNO3AM Rate of NO3–N application 1 kg NO3–N m-2 d-1 RNO3DENITR Rate of denitrification 1 kg NO3–N m-2 d-1 RNO3DEPOS Rate of NO3–N deposition 1 kg NO3–N m-2 d-1 RNO3IN Rate of NH4+-N inflow from adjacent layer 1 kg NO3+-N m-2 d-1 RNO3NITR Rate of nitrification 1 kg NO3–N m-2 d-1 RNO3OUT Rate of NO3–N outflow to adjacent layer 1 kg NO3–N m-2 d-1 RNO3UP Rate of NO3–N root uptake 1 kg NO3–N m-2 d-1 RNORG Rate of change of organic N 2 kg N m-2 d-1 RNORGAM Rate pf application organic N 2 kg N m-2 d-1 RNORGDIS Dissimilation rate of organic matter 2 kg N m-2 d-1 RORGMAT Rate of change of organic material 2 kg OM m-2 d-1 RORGMATAM Rate of application organic matter 2 kg OM m-2 d-1 RORGMATDIS Dissimilation rate of organic matter 2 kg OM m-2 d-1 1 This state variable is defined for each soil layer 2 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 classpcse.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 day TBASEM Base temperature for emergence SCr TEFFMX Maximum effective temperature for emergence SCr TSUM1 Temperature sum from emergence to anthesis SCr day TSUM2 Temperature sum from anthesis to maturity SCr 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 State variables Name Description Pbl Unit DVS Development stage Y TSUM Temperature sum N day TSUME Temperature sum for emergence N 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 DTSUM Increase in temperature sum for anthesis or maturity N 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’. classpcse.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 classpcse.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 Unit 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 Unit 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’. CO2 Assimilation classpcse.crop.assimilation.WOFOST72_Assimilation(**kwargs)[source] Class implementing a WOFOST/SUCROS style assimilation routine. WOFOST calculates the daily gross CO2 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 CO2 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 CO2 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 CH2O 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 classpcse.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 CO2 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 CO2 assimilation is obtained by integrating the assimilation rates over the leaf layers and over the day. The impact of atmospheric CO2 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 CO2 concentration. Simulation parameters (To be provided in cropdata dictionary): Name Description Type Unit AMAXTB Max. leaf CO2 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 classpcse.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 CO2 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 CO2 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 classpcse.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 CH2O kg-1d-1 RMS Relative maintenance respiration rate for stems SCr kg CH2O kg-1d-1 RML Relative maintenance respiration rate for leaves SCr kg CH2O kg-1d-1 RMO Relative maintenance respiration rate for storage organs SCr kg CH2O 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 CH2O 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 classpcse.crop.evapotranspiration.Evapotranspiration(**kwargs)[source] Calculation of potential evaporation (water and soil) rates and actual crop transpiration rate. Simulation parameters: Name Description Type Unit 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 Unit DVS Crop development stage DVS_Phenology LAI Leaf area index Leaf_dynamics SM Volumetric soil moisture content Waterbalance classpcse.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 Unit DVS Crop development stage DVS_Phenology LAI Leaf area index Leaf_dynamics SM Volumetric soil moisture content Waterbalance classpcse.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 Unit 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 classpcse.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 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 classpcse.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 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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 FROSTOL_H Hardening coefficient SCr FROSTOL_D Dehardening coefficient SCr FROSTOL_S Low temperature stress coefficient SCr 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 LT50I Initial LT50 value of unhardened crop N IDFST Total number of days with frost stress N Rate variables Name Description Pbl Unit RH Rate of hardening N RDH_TEMP Rate of dehardening due to temperature N RDH_RESP Rate of dehardening due to respiration stress N RDH_TSTR Rate of dehardening due to temperature stress N 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 TMIN_CROWN Daily minimum crown temperature derived from calling the crown_temperature module. CrownTemperature 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 classpcse.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): and and and 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 Unit 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 TMIN_CROWN Daily minimum crown temperature N TMAX_CROWN Daily maximum crown temperature N 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 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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 classpcse.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 Pbl 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| classLintul3Rates(**kwargs)[source] classLintul3States(**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. classParameters(**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, ) 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 2 leaf m -2 soil) according to Lambert Beer’s law: where Q is intercepted PAR , Q0 is daily global radiation , 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 classpcse.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 "", line 1, in 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 classpcse.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 "", line 1, in 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. classpcse.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). classpcse.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 "", line 1, in 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 classpcse.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. classpcse.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 with and given 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 classpcse.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=, crop_name=, variety_name=, crop_start_type=, crop_end_type=) 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=, finish_type=, crop_delete=) 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=, N_recovery) 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=, application_depth=, cnratio=, initial_age=, f_NH4N=, f_NO3N=, f_orgmat=) 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=, efficiency=) 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=) 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. classpcse.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. classpcse.input.OpenMeteoWeatherDataProvider(latitude: float, longitude: float, timezone: str = 'UTC', openmeteo_model: str = 'best_match', start_date: str | date | None = None, ETmodel: str = 'PM', forecast: bool = False, force_update: bool = False)[source] A weather provider that uses the Open Meteo weather API. Parameters : latitude – latitude to request weather data for longitude – longitude to request weather data for timezone – timezone for day aggregation (str, default ‘UTC’) openmeteo_model – model to use, default ‘best_match’ start_date – Starting date from which to retrieve data (str, default ‘UTC’) ETmodel – “PM”|”P” for selecting penman-monteith or Penman method for reference evapotranspiration. Defaults to “PM”. forecast – Include a weather forecast, default False force_update – Set to True to force to request fresh data from OpenMeteo website. This object only needs a location (latitude and longitude) at initialization. There are two important parameters when constructing the object: openmeteo_model and forecast. The class variables list possible models to use, either for forecasts or historical data. To utilize a specific model, call it with the appropriate key argument. Be aware that there might be some nuances with using certain models. This hasn’t been tested thoroughly, so there might be some issues with the starting date. Please provide an argument for the start_date parameter if you find any issues. More info for each model is documented here: https://open-meteo.com/en/docs If you don’t specify a model, the Open Meteo API will automatically choose the best model for your chosen location. classpcse.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. classpcse.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. classpcse.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. classpcse.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 DTSMTB: [0.0, 0.0, 30.0, 30.0, 45.0, 30.0] NMINVE: 0.003 CROP_NO: 99 CRPNAM: Winter wheat 102, Ireland, N-U.K., Netherlands, N-Germany NMINSO: 0.011 classpcse.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] () CROP_START_DATE: 2010-05-14 () TSUM2: 900 () cropname: alfalfa () AMAXTB: [ 0. 0.84147098 0.90929743 0.14112001 -0.7568025 -0.95892427 -0.2794155 0.6569866 0.98935825 0.41211849 -0.54402111 -0.99999021] () TSUM1: 1100 () classpcse.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. classpcse.input.YAMLCropDataProvider(model=, 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//WOFOST_crop_parameters//") 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. classpcse.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. classpcse.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. classpcse.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. classpcse.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. classpcse.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 Note The dataproviders for CGMS database were removed from PCSE starting with version 6.0.10 because they were forcing a dependency on PCSE (SQLAlchemy) which was generating problems with other packages. Moreover SQLAlchemy is not required for running PCSE and the DB tools were not broadly used anyway. 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. 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')[source] Provides a convenient interface for starting a WOFOST instance for the internal Demo DB. 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’ example: import pcse wofsim = pcse.start_wofost(grid=31031, crop=1, year=2000, mode='wlp') wofsim 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. classpcse.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 from dump file .