Running the model

There are two basic modes for the model: planning mode and operational mode. The mode is set in the run configuration.

In planning mode, constraints are given as upper and lower boundaries and the model decides on an optimal system configuration.

In operational mode, all capacity constraints are fixed and the system is operated with a receding horizon control algorithm (see Model-wide settings for the settings that control the receding horizon).

In either case, there are three ways to run the model:

  1. With the calliope run command-line tool.
  2. By generating and then executing parallel runs with the calliope generate command-line tool.
  3. By programmatically creating and running a model from within other Python code, or in an interactive Python session.

Single runs with the command-line tool

The included command-line tool calliope run will execute a given run configuration:

$ calliope run my_model/run.yaml

It will generate and solve the model, then save the results to the the output directory given by output.path in the run configuration.

Two output formats are available: CSV files and HDF, and they can be chosen by settings output.format in the run configuration (set to hdf or csv). HDF results in a single compressed file in the high-performance HDF5 data format. The analysis module provides methods to read and analyze these HDF files.

For easier analysis via third-party tools, the CSV option saves a set of CSV files into the given output directory.

Parallel runs


This functionality is currently not Windows-compatible.

Scripts to simplify the creation and execution of a large number of Calliope model runs are generated with the calliope generate command-line tool as follows:

  • Create a run.yaml file with a parallel: section as needed (see Settings for parallel runs).
  • On the command line, run calliope generate path/to/run.yaml.
  • By default, this will create a new subdirectory inside a runs directory in the current working directory. You can optionally specify a different target directory by passing a second path to calliope generate, e.g. calliope generate path/to/run.yaml path/to/my_run_files.
  • Calliope generates several files and directories in the target path. The most important are the Runs subdirectory which hosts the self-contained configuration for the runs and script, which is responsible for executing each run. In order to execute these runs in parallel on a compute cluster, a script is also generated containing job control data, and which can be submitted via a cluster controller (e.g., qsub

The script can simply be called with an integer argument from the sequence (1, number of parallel runs) to execute a given run, e.g. 1, 2, etc. This way the runs can easily be executed irrespective of the parallel computing environment available.


Models generated via calliope generate automatically save results as HDF files inside the parallel run’s Output subdirectory, regardless of whether the output.path or output.format options have been set.

See Settings for parallel runs for details on configuring parallel runs.

Running programmatically from other Python code

The most basic way to run a model programmatically from within a Python interpreter is to create a Model instance with a given run.yaml configuration file, and then call its run() method:

import calliope
model = calliope.Model(config_run='/path/to/run_configuration.yaml')

If config_run is not specified (e.g. model = Model()), the built-in example model is used (see The built-in example model).

config_run can also take an AttrDict object containing the configuration. Furthermore, Model() has an override parameter, which takes an AttrDict with settings that will override the given run settings.

After instantiating the Model object, and before calling the run() method, it is possible to manually inspect and adjust the configuration of the model.

After the model has been solved, a processed set of solution variables and aggregated statistics is accessible under the solution property on the model instance.

If used in an interactive Python session (e.g., a Jupyter Notebook) the model instance can also be queried after running it, e.g.:

# Get a pandas DataFrame of system variables
system_vars = model.get_system_variables()

The API documentation gives an overview of the available methods for programmatic access.

Previous: Run configuration | Next: Analyzing results