Running SIPNET¶

This guide covers how to run SIPNET with command-line options and configuration files.

Quick Start¶

For installation, building, and your first simulation, see Getting Started with SIPNET.

Once SIPNET is built, the basic command is:

./sipnet

This looks for a configuration file named sipnet.in (if present) and uses built-in defaults if not found.

Configuration and Options¶

SIPNET options can be set in two places: 1. Configuration file (sipnet.in or custom file via --input-file) 2. Command-line arguments (passed to ./sipnet on the command line)

When the same option is specified in both places, command-line arguments take precedence and override the configuration file, which overrides built-in defaults. See Option Precedence below for details.

Input/Output Options¶

Option	Short	Argument	Default	Description
`--input-file`	`-i`	`<name>`	`sipnet.in`	Name of input configuration file
`--file-name`	`-f`	`<name>`	`sipnet`	Prefix for climate and parameter input files (looks for `<name>.clim` and `<name>.param`)
`--events-prefix`	`-e`	`<name>`	`events`	Prefix for events input and output files (SIPNET uses `<name>.in` and `<name>.out`)
`--restart-in`		`<path>`	unset	Read a restart checkpoint (schema `1.0`)
`--restart-out`		`<path>`	unset	Write a restart checkpoint at end of run

Model Feature Flags¶

These flags enable or disable optional model processes. Prepend no- to the flag name to disable it (e.g., --no-events).

Flag	Default	Description
`--anaerobic`	OFF (0)	Enable modeling of methane and anaerobic effect on Rh moisture dependency
`--events`	ON (1)	Enable events read from events input file
`--gdd`	ON (1)	Use growing degree days to determine when leaves grow
`--growth-resp`	OFF (0)	Explicitly model growth respiration separately from maintenance respiration
`--leaf-water`	OFF (0)	Calculate a separate leaf water pool and evaporate from it
`--litter-pool`	OFF (0)	Enable a separate litter pool in addition to the soil carbon pool
`--nitrogen-cycle`	OFF (0)	Enable nitrogen cycle modeling (pool and flux tracking)
`--snow`	ON (1)	Track snowpack separately; if disabled, all precipitation is treated as liquid
`--soil-phenol`	OFF (0)	Use soil temperature (instead of growing degree days) to determine leaf growth
`--water-hresp`	ON (1)	Allow soil moisture to affect heterotrophic respiration rates

Model Flag Restrictions¶

The following flag constraints are enforced:

--soil-phenol and --gdd cannot both be enabled
--anaerobic requires --water-hresp
--nitrogen-cycle requires both --litter-pool and --anaerobic

Output Flags¶

These flags control what outputs are generated. Prepend no- to disable (e.g., --no-print-header).

Flag	Default	Description
`--do-main-output`	ON (1)	Write time series of all output variables to `<file-name>.out`
`--do-single-outputs`	OFF (0)	Write selected outputs only (`NEE`, `NEE_cum`, `GPP`, `GPP_cum`) to separate files (e.g., `<file-name>.NEE`)
`--dump-config`	OFF (0)	Write final merged configuration to `<file-name>.config` after running
`--print-header`	ON (1)	Print header row with variable names in output files
`--quiet`	OFF (0)	Suppress informational and warning messages to console

Information Options¶

Option	Short	Description
`--help`	`-h`	Print help message and exit
`--version`	`-v`	Print SIPNET version and exit

Configuration Files¶

SIPNET reads configuration from a file (default: sipnet.in). This file uses a simple key-value format with one setting per line.

Configuration File Format¶

Each line in the configuration file contains a key-value pair separated by whitespace:

KEY VALUE

Keys are case-insensitive and can use hyphens or underscores (e.g., EVENTS, events, EVENTS, events are equivalent).

Configuration File Keys¶

Input/Output Keys¶

Key	Value Type	Description
`INPUT_FILE`	string	Name of configuration file to read
`FILE_NAME`	string	Prefix for climate and parameter input files
`PARAM_FILE`	string	Path to model parameters file (optional; defaults to `<FILE_NAME>.param`)
`CLIM_FILE`	string	Path to climate file (optional; defaults to `<FILE_NAME>.clim`)
`OUT_FILE`	string	Path for main output file (optional; defaults to `<FILE_NAME>.out`)
`OUT_CONFIG_FILE`	string	Path for config dump file (optional; defaults to `<FILE_NAME>.config`)
`EVENTS_PREFIX`	string	Prefix used to derive events input and output filenames
`RESTART_IN`	string	Path to checkpoint to resume from
`RESTART_OUT`	string	Path to checkpoint to write at end of run

Model Feature Keys¶

Key	Value (1/0)	Description
`EVENTS`	0 or 1	Enable/disable event handling
`GDD`	0 or 1	Use growing degree days for leaf growth
`GROWTH_RESP`	0 or 1	Explicitly model growth respiration
`LEAF_WATER`	0 or 1	Track separate leaf water pool
`LITTER_POOL`	0 or 1	Enable separate litter pool
`NITROGEN_CYCLE`	0 or 1	Enable nitrogen cycle modeling
`ANAEROBIC`	0 or 1	Enable methane/anaerobic Rh moisture behavior
`SNOW`	0 or 1	Track snowpack
`SOIL_PHENOL`	0 or 1	Use soil temperature for phenology
`WATER_HRESP`	0 or 1	Allow soil moisture to affect respiration

Output Keys¶

Key	Value (1/0)	Description
`DO_MAIN_OUTPUT`	0 or 1	Write combined output file
`DO_SINGLE_OUTPUTS`	0 or 1	Write selected single-output files (`NEE`, `NEE_cum`, `GPP`, `GPP_cum`)
`DUMP_CONFIG`	0 or 1	Dump final configuration
`PRINT_HEADER`	0 or 1	Include header row in output files
`QUIET`	0 or 1	Suppress console messages

Example Configuration File¶

Here's an example sipnet.in configuration file:

# Input files
FILE_NAME my_site
PARAM_FILE ../inputs/my_site.param
CLIM_FILE  ../inputs/my_site.clim

# Model features
EVENTS 1
GDD 1
SNOW 1
NITROGEN_CYCLE 0

# Output
DO_MAIN_OUTPUT 1
DO_SINGLE_OUTPUTS 0
PRINT_HEADER 1
QUIET 0

Restart Checkpoints (MVP)¶

SIPNET restart support is designed for segmented orchestration (for example, external workflow controllers). SIPNET only handles state checkpointing and resume validation.

RESTART_OUT writes a text restart file (schema 1.0) containing runtime state needed for deterministic resume.

RESTART_IN loads a previously generated restart file and sets SIPNET's state accordingly.

For the checkpoint schema, strict validation order, and implementation details, see Restart Checkpoint Spec.

Option Precedence¶

SIPNET applies configuration in this order (later values override earlier ones):

Built-in Defaults — hardcoded defaults for all options
Configuration File — settings from sipnet.in (or file specified by --input-file)
Command-Line Arguments — options passed to ./sipnet on the command line

Example: Precedence in Action¶

Given this configuration file (sipnet.in):

FILE_NAME base_site
EVENTS 1
LITTER_POOL 0

Running with command-line overrides:

./sipnet --file-name override_site --no-events

Results in:

Option	Source	Value
`file-name`	Command line	`override_site`
`events`	Command line	OFF (0) — `--no-events` overrides config file's `EVENTS 1`
`litter-pool`	Config file	OFF (0) — not overridden

Tutorial: Common Use Cases¶

This section provides practical examples of running SIPNET to compare different configurations and settings.

Use Case 1: Test Phenology Models¶

SIPNET supports two phenology models: GDD-based (growing degree days) and soil-temperature-based. Compare runs using each model.

Create configuration (phenology_test.in):

FILE_NAME my_site
GDD 1
SOIL_PHENOL 0
DO_MAIN_OUTPUT 1

Run with GDD-based phenology:

./sipnet --input-file phenology_test.in

Run with soil-temperature-based phenology:

./sipnet --input-file phenology_test.in --no-gdd --soil-phenol

Compare LAI (leaf area index) timing in the output files to determine which phenology model better captures your site's growing season.

Use Case 2: Explore Parameter Sensitivity¶

To test how model results change with different parameter values, run the same configuration but modify key parameters in sipnet.param.

For low photosynthesis (edit my_site.param, set aMax 50):

./sipnet --file-name my_site

For high photosynthesis (edit my_site.param, set aMax 150):

./sipnet --file-name my_site

Compare GPP and NEE in the output files to understand parameter sensitivity.

Use Case 3: Generate and Compare Model Configurations¶

The --dump-config flag is useful for archiving exactly what settings were used in each run.

Run scenario A:

./sipnet --input-file scenario_a.in --no-events --dump-config

Run scenario B:

./sipnet --input-file scenario_b.in --litter-pool --dump-config

Compare the configurations:

diff scenario_a.config scenario_b.config

This shows exactly which flags and parameters differ between runs.

Output Files¶

SIPNET generates output files based on your configuration:

Main Output File¶

Filename: <file-name>.out (if --do-main-output is enabled, which is default)

This file contains time-series data with one row per time step and one column per output variable. If --print-header is enabled, the first row contains variable names.

Example output (header + first 3 rows, showing first six columns), showing three hour time steps starting Jan 1, 2016:

year day time plantWoodC plantLeafC woodCreation soil ...
2016 1 0.00 1313.61 0.00 0.00 2688.07 ...
2016 1 3.00 1313.59 0.00 0.00 2688.00 ...
2016 1 6.00 1313.56 0.00 0.00 2687.93 ...
...

Per-Variable Output Files¶

Filename pattern: <file-name>.<VARIABLE> (if --do-single-outputs is enabled)

Only these selected outputs are written to separate files: NEE, NEE_cum, GPP, GPP_cum.

Configuration Dump File¶

Filename: <file-name>.config (if --dump-config is enabled)

Shows the final merged configuration after applying all defaults, config file, and command-line options. Useful for: - Reproducing a run exactly - Verifying that settings were applied correctly - Archiving with results for full reproducibility

Example:

EVENTS 1
GDD 1
GROWTH_RESP 0
FILE_NAME my_site
PARAM_FILE my_site.param
CLIM_FILE my_site.clim
...

Input Files Reference¶

For details on the format and contents of input files, see:

Model Parameters: See the parameter reference in Model States and Parameters
Climate Data: See Climate
Model Input Files: See Model Inputs

Troubleshooting¶

"Cannot open file: sipnet.in"¶

This message appears if: - You're using a custom config file that doesn't exist - The config file path is wrong

Solution: Check that the config file exists and the path is correct. If you don't need a config file, just don't provide --input-file; SIPNET will use defaults.

Incompatible Flags Error¶

SIPNET will exit with an error if you try to enable mutually exclusive flags: - --soil-phenol and --gdd together

Solution: Choose one flag from each incompatible pair.

"Growing degree days not calculated for this site"¶

This warning occurs if --gdd is enabled but the climate file lacks necessary temperature data.

Solution: Ensure your climate file includes both air temperature (tair) and soil temperature (tsoil) columns.