Command Line Interface¶

simulatr ships with a command line interface for configuring the package, installing simulators, creating model input files, and running simulations. The commands below all use the simulatr.cli module.

Invoking the CLI ¶

If simulatr is installed into your environment, the simulatr console script is available on your PATH:

$ simulatr --help

The same interface can be invoked as a module, which works without a console script:

$ python -m simulatr --help

Both forms accept the same subcommands:

usage: simulatr [-h] {config,install,create,run} ...

Overview ¶

Command	Description
`simulatr config`	Set a configuration option in a configuration file.
`simulatr install`	Install or register a simulator (e.g. ApsimX).
`simulatr create`	Create a simulator model input file.
`simulatr run`	Run a simulation.

Configuration ¶

simulatr config <section> <name> <value> writes a single option to a configuration file. Options for the directories and files sections are converted to absolute paths automatically.

Configuration files live in .simulatr.ini files that are read from (and written to) several locations:

$ simulatr config directories apsimx /Users/me/ApsimX
Set apsimx in the "directories" section of
"/Users/me/my-project/.simulatr.ini" to "/Users/me/ApsimX"

By default the option is written to the most local configuration file (the current working directory). The --level flag selects a different location:

$ simulatr config directories apsimx /Users/me/ApsimX --level local
$ simulatr config directories apsimx /Users/me/ApsimX --level user
$ simulatr config directories apsimx /Users/me/ApsimX --level env

The directories section supports the following options:

output – Directory for simulation output.
models – Base directory where simulator models are installed.
apsimx – Directory containing the ApsimX installation.
nasa_power_weather_data – Cache directory for downloaded NASA POWER weather data.

Installing a simulator ¶

simulatr install apsimx installs ApsimX into the directory given by the apsimx configuration option (by default ./models/apsimx), prompting for confirmation:

$ simulatr install apsimx
Install the apsimx model into ".../models/apsimx"? [Y/n]

Use --directory to install into a different location and record it in the configuration at the same time:

$ simulatr install apsimx --directory /Users/me/ApsimX

If a valid installation already exists at the configured location, the command simply registers it and returns.

Creating model input files ¶

simulatr create apsimx <crop> generates an ApsimX .apsimx model input file for the requested crop. The crop name is case-insensitive.

$ simulatr create apsimx wheat
Created input file "Wheat-Generated-Interactive.apsimx"

The generated file supports interactive interventions such as sowing, harvesting, irrigation, and fertilization.

Choosing the output path ¶

$ simulatr create apsimx wheat --dst ./wheat.apsimx
Created input file "./wheat.apsimx"

Note

Pass a path that includes a directory component (for example ./wheat.apsimx). A bare filename such as --dst wheat.apsimx is resolved relative to the Examples subdirectory and will fail unless that directory exists.

Selecting the available actions ¶

The --actions option restricts which interventions are included in the interactive file:

$ simulatr create apsimx wheat \
    --actions sow harvest nitrogen \
    --dst ./wheat.apsimx

Copying an example ¶

# Copy the bundled Wheat example
$ simulatr create apsimx wheat --from-example

# Copy a specific example file
$ simulatr create apsimx wheat --from-example /path/to/example.apsimx

When no example is requested the file is generated from a crop template instead.

Overwriting existing files ¶

$ simulatr create apsimx wheat --dst ./wheat.apsimx
$ simulatr create apsimx wheat --dst ./wheat.apsimx
RuntimeError: Model file already exists: "./wheat.apsimx"
$ simulatr create apsimx wheat --dst ./wheat.apsimx --overwrite
Created input file "./wheat.apsimx"

Note

The --interactive flag is accepted for compatibility but is currently a no-op: files generated by create are always interactive.

Running a simulation ¶

simulatr run apsimx starts the ApsimX ZMQ server and runs a simulation. A working ApsimX installation is required (see the install command and the README).

Run a simulation from a crop name:

$ simulatr run apsimx --crop-name wheat

Or from an existing model input file:

$ simulatr run apsimx --model-file ./wheat.apsimx

Setting the action timestep ¶

By default the simulation runs continuously to completion (--timestep 0). A positive --timestep runs the simulation in daily steps and pauses for an action between steps:

$ simulatr run apsimx --crop-name wheat --timestep 7

Recording state variables ¶

Use --state-variables to log the value of a set of simulation state variables at each step:

$ simulatr run apsimx --crop-name wheat \
    --state-variables \
        "[Clock].Today" \
        "[CROP].Phenology.CurrentStageName" \
        "[CROP].Total.Wt" \
        "[Weather].Rain" \
        "[Soil].Water.PAW"

The retrieved values are written to the engine’s output file.

Allowing actions ¶

$ simulatr run apsimx --crop-name wheat \
    --actions sow harvest nitrogen

Logging ¶

The --log-level option controls the verbosity of logging and --log-file redirects log messages to a file. With no argument, --log-file writes to <simulator>.log in the current directory:

$ simulatr run apsimx --crop-name wheat --log-file
Log being written to "apsimx_wheat.log"

$ simulatr run apsimx --crop-name wheat \
    --log-file ./run.log --log-level DEBUG