Model Inputs¶
There are three main types of input files needed to run SIPNET:
1. sipnet.param: Model parameter file.
2. <sitename>.clim: Climate file, provides weather data for each time step of the simulation period.
3. events.in: (Optional) Agronomic events.
4. Run time options (command line arguments or config file sipnet.in)
Parameters and Initial Conditions¶
Both initial conditions and parameters are specified in a file named sipnet.param.
The SIPNET parameter file (sipnet.param) specifies model parameters and their properties for each simulation.
Each line in the file corresponds to a single parameter and contains five or six space-separated values.
| Column | Description |
|---|---|
| Parameter Name | Name of the parameter |
| Value | Value of the parameter to use in the model |
Example sipnet.param file¶
Column names are not used, but are:
param_name value
The first lines in sipnet.param could be:
plantWoodInit 110
laiInit 0
litterInit 200
soilInit 7000
litterWFracInit 0.5
soilWFracInit 0.6
snowInit 1
microbeInit 0.5
fineRootFrac 0.2
coarseRootFrac 0.2
aMax 95
aMaxFrac 0.85
...
Climate¶
For each step of the model, the following inputs are needed. These are provided in a file named <sitename>.clim with the following columns:
| col | parameter | description | units | notes |
|---|---|---|---|---|
| 1 | year | year of start of this timestep | integer, e.g. 2010 | |
| 2 | day | day of start of this timestep | Day of year | 1 = Jan 1 |
| 3 | time | time of start of this timestep | hours after midnight | e.g. noon = 12.0, midnight = 0.0, can be a fraction |
| 4 | length | length of this timestep | days | variable-length timesteps allowed, typically not used |
| 5 | tair | avg. air temp for this time step | degrees Celsius | |
| 6 | tsoil | average soil temperature for this time step | degrees Celsius | can be estimated from Tair |
| 7 | par | average photosynthetically active radiation (PAR) for this time step | \(\text{Einsteins} \cdot m^{-2} \text{ground area} \cdot \text{time step}^{-1}\) | input is in Einsteins * m^-2 ground area, summed over entire time step |
| 8 | precip | total precip. for this time step | cm | input is in mm; water equivilant - either rain or snow |
| 9 | vpd | average vapor pressure deficit | kPa | input is in Pa, can be calculated from air temperature and relative humidity. |
| 10 | vpdSoil | average vapor pressure deficit between soil and air | kPa | input is in Pa ; differs from vpd in that saturation vapor pressure is calculated using Tsoil rather than Tair |
| 11 | vPress | average vapor pressure in canopy airspace | kPa | input is in Pa |
| 12 | wspd | avg. wind speed | m/s |
Note: An older format for this file included location as the first column and soilWetness as the last column. Files with this older format can still be read by sipnet: * SIPNET will print a warning indicating that it is ignoring the obsolete columns * If there is more than one location specified in the file, SIPNET will error and halt
Example sipnet.clim file:¶
Column names are not used, but are:
loc year day time length tair tsoil par precip vpd vpdSoil vPress wspd
Half-hour time step
0 1998 305 0.00 -1800 1.9000 1.2719 0.0000 0.0000 109.5364 77.5454 726.6196 1.6300
0 1998 305 0.50 -1800 1.9000 1.1832 0.0000 0.0000 109.5364 73.1254 726.6196 1.6300
0 1998 305 1.00 -1800 2.0300 1.1171 0.0000 0.0000 110.4243 63.9567 732.5092 0.6800
0 1998 305 1.50 -1800 2.0300 1.0439 0.0000 0.0000 110.4243 60.3450 732.5092 0.6800
Variable time step
0 1998 305 0.00 0.292 1.5 0.8 0.0000 0.0000 105.8 70.1 711.6 0.9200
0 1998 305 7.00 0.417 3.6 1.8 5.6016 0.0000 125.7 23.5 809.4 1.1270
0 1998 305 17.00 0.583 1.9 1.3 0.0000 0.0000 108.1 75.9 732.7 1.1350
0 1998 306 7.00 0.417 2.2 1.4 2.7104 1.0000 114.1 71.6 741.8 0.9690
Agronomic Events¶
Agronomic (management) events are read from an events.in file. This file specifies one event per line:
| col | parameter | description | units | notes |
|---|---|---|---|---|
| 1 | year | Year of the event | e.g. 2025 | |
| 2 | day | Day of year of the event | DOY | 1 = Jan 1 |
| 3 | event_type | Event type code | one of: plant, harv, till, fert, irrig |
|
| 4…n | event_param | Type‑specific parameters (see below) | varies | Order depends on event type |
Rules:
- File must be in chronological order. Ties (same day multiple events) are allowed and processed in file order.
- Events are specified at day resolution (no sub‑daily timestamp).
- Every (year, day) appearing in
events.inmust have at least one corresponding climate record; otherwise SIPNET errors. - Values in
events.inare instantaneous amounts (cm or mass/area) applied on the date and time of the first climate record matching that event's year and day.
See subsections below for details and parameter definitions for each event type.
Irrigation¶
| parameter | col | req? | description |
|---|---|---|---|
| amount | 5 | Y | Amount added (cm) |
| method | 6 | Y | 0=canopy 1=soil 2=flood (placeholder) |
Model representation: An irrigation event increases soil moisture. A fraction of canopy irrigation is immediately evaporated.
Specifically:
- For
method=soil, this amount of water is added directly to thesoilWaterstate variable - For
method=canopy, a fraction of the irrigation water (determined by input paramimmedEvapFrac) is added to the flux state variableimmedEvap, with the remainder going tosoilWater. - Initial implementation assumes that LITTER_WATER is not on. This might be revisited at a later date.
Fertilization¶
| parameter | col | req? | description |
|---|---|---|---|
| org-N | 5 | Y | g N / m2 |
| org-C | 6 | Y | g C / m2 |
| min-N | 7 | Y | g N / m2 |
- Model representation: increases size of mineral N and litter C and N. Urea-N is assumed to be mineral N.
- The code that generates
events.inwill handle conversion from fertilizer amount and type to mass of N and C allocated to different pools. In PEcAn this is done by thePEcAn.SIPNET::write.configs.SIPNET()function.
Tillage¶
| parameter | col | req? | description |
|---|---|---|---|
| tillageEff \((f_{\textrm{till}})\) | 5 | Y | Adjustment to \(R_H\) |
- Model representation:
- Transient increase in decomposition rate by \(f_{\text{,tillage}}\) that exponentially decays over time.
- Multiple tillage events are additive.
Planting¶
| parameter | col | req? | description |
|---|---|---|---|
| leaf-C | 5 | Y | C added to leaf pool (g C / m2) |
| wood-C | 6 | Y | C added to above-ground wood pool (g C / m2) |
| fine-root-C | 7 | Y | C added to fine root pool (g C / m2) |
| coarse-root-C | 8 | Y | C added to coarse root pool (g C / m2) |
- Model representation:
- Date of event is the date of emergence, not the date of actual planting
- Increases size of carbon pools by the amount of each respective parameter
- \(N\) pools are calculated from \(CN\) stoichiometric ratios.
- notes: PFT (crop type) is not an input parameter for a planting event because SIPNET only represents a single PFT.
Harvest¶
| parameter | col | req? | description |
|---|---|---|---|
| fraction of aboveground biomass removed | 5 | Y | |
| fraction of belowground biomass removed | 6 | N | default = 0 |
| fraction of aboveground biomass transferred to litter pool | 7 | N | default = 1 - removed |
| fraction of belowground biomass transferred to litter pool | 8 | N | default = 1 - removed |
- model representation:
- biomass C and N pools are either removed or added to litter
- for annuals or plants terminated, no biomass remains (col 5 + col 7 = 1 and col 6 + col 8 = 1).
- for perennials, some biomass may remain (col 5 + col 7 <= 1 and col 6 + col 8 <= 1; remainder is living).
- root biomass is only removed for root crops
Example of events.in file:¶
2022 35 till 0.2 # tilled on day 35, f_till = 0.2 (20% boost to rate term)
2022 40 till 0.1 # tilled on day 40, adds 0.1 to f_till
2022 40 irrig 5 1 # 5cm canopy irrigation on day 40 applied to soil
2022 40 fert 0 0 10 # fertilized with 10 g / m2 N_min on day 40 of 2022
2022 50 plant 10 3 2 5 # plant emergence on day 50 with 10/3/2/4 g C / m2, respectively, added to the leaf/wood/fine root/coarse root pools
2022 250 harv 0.1 # harvest 10% of aboveground plant biomass on day 250
Run-time Options¶
Configuration settings are applied in the following order of precedence:
- Default values built into SIPNET
- Values from the configuration file
- Command-line arguments
Thus, command-line arguments override settings in the configuration file, and configuration file settings override default values.
Input / Output Options¶
| Option | Default | Description |
|---|---|---|
input-file |
sipnet.in | Name of input config file |
file-name |
sipnet | Prefix of climate and parameter files |
Output Flags¶
| Option | Default | Description |
|---|---|---|
do-main-output |
on | Print time series of all output variables to <file-name>.out |
do-single-outputs |
off | Print outputs one variable per file (e.g. <file-name>.NEE) |
dump-config |
on | Print final config to <file-name>.config |
print-header |
on | Whether to print header row in output files |
quiet |
off | Suppress info and warning message |
Model Flags¶
| Option | Default | Description |
|---|---|---|
events |
on | Enable event handling. |
gdd |
on | Use growing degree days to determine leaf growth. |
growth-resp |
off | Explicitly model growth respiration, rather than including with maintenance respiration. |
leaf-water |
off | Calculate leaf pool and evaporate from that pool. |
litter-pool |
off | Enable litter pool in addition to single soil carbon pool. |
microbes |
off | Enable microbe modeling. |
snow |
on | Keep track of snowpack, rather than assuming all precipitation is liquid. |
soil-phenol |
off | Use soil temperature to determine leaf growth. |
water-hresp |
on | Whether soil moisture affects heterotrophic respiration. |
Note the following restrictions on these options:
- soil-phenol and gdd may not both be turned on
Command Line Arguments¶
Command-line arguments can be used to specify run-time options when starting SIPNET. The syntax is as follows:
sipnet [options]
Where [options] can include any of the run-time options listed above.
Flags use the syntax --flag to turn them on, or --no-flag to turn them off. Other options are specified by --option value.
See sipnet --help for a full list of available command-line options.
Configuration File Format¶
SIPNET reads a configuration file that specifies run-time options without using command-line arguments. By default, SIPNET looks for a file named sipnet.in in the current directory. These will be overwritten by command-line arguments if specified.
The configuration file uses a simple key-value format, option = value,
with one option per line; comments follow #. Flags are specified as 0 for off and 1 for on.
Example Configuration File¶
Note that case is ignored for parameter names, as well as dashes and underscores.
# Base filename (used for derived filenames)
FILE_NAME = mysite
# Output options
DO_MAIN_OUTPUT = 1
DO_SINGLE_OUTPUTS = 0
DUMP_CONFIG = 1
PRINT_HEADER = 1
QUIET = 0
# Model options
EVENTS = 1
GDD = 1
GROWTH_RESP = 0
LEAF_WATER = 0
LITTER_POOL = 0
MICROBES = 0
SNOW = 1
SOIL_PHENOL = 0
WATER_HRESP = 1
When DUMP_CONFIG is on, SIPNET will output the final configuration (after applying all settings from defaults, configuration file, and command line) to a file named <file-name>.config.