Skip to content

Creating a model

A Calliope model is a collection of interconnected technologies, nodes and carriers describing a real world system of flows. Usually, we consider those to be energy flows, and most of what you will read in this documentation concerns energy systems. However, it is just as applicable to other types of flows, such as water!

Carriers are commodities whose flows we track, e.g., electricity, heat, hydrogen, water, CO2.

Technologies supply, consume, convert, store or transmit carriers, e.g., transmission lines/pipes, batteries, power plants, wind turbines, or home appliances.

Nodes contain groups of technologies and are usually geographic, e.g., a country, municipality or a single house.

Flows can enter the system from sources, e.g., energy from the sun to power a solar panel, and can exit it into sinks, e.g., electricity consumed by household appliances. Unlike carriers, we do not explicitly track the type of commodity described by sources and sinks.

Putting all of these possibilities together allows a modeller to create a model that is as simple or complex as necessary to answer a given research question. Calliope's syntax ensures these models are intuitive, and easy to understand and share.

Visual description of the Calliope terminology.

Example

Refer to the examples and tutorials section for a more practical look at how to build a Calliope model.

Model configuration and model definition

Calliope models are defined through YAML files (a format that is both human and computer-readable), and CSV files (a simple tabular format). In the pages in this section we will take you through each part of setting up your model.

We distinguish between:

  • the model configuration (the options provided to Calliope to do its work) and
  • the model definition (your representation of a physical system in YAML).

Model configuration is everything under the top-level YAML key config. Model definition is everything else, under the top-level YAML keys parameters, techs, nodes, templates, and data_tables.

It is possible to define alternatives to the model configuration/definition that you can refer to when you initialise your model. These are defined under the top-level YAML keys scenarios and overrides.

We dive into each of these top-level keys in the pages you'll find in the left-hand navigation.

Structuring your model directory

It makes sense to collect all files belonging to a model inside a single model directory. The layout of that directory typically looks roughly like this (+ denotes directories, - files):

+ example_model
    + model_definition
        - nodes.yaml
        - techs.yaml
    + data_tables
        - solar_resource.csv
        - electricity_demand.csv
    - model.yaml
    - scenarios.yaml

In the above example, the files model.yaml, nodes.yaml and techs.yaml together are the model definition. This definition could be in one file, but it is more readable when split into multiple. We use the above layout in the example models.

Inside the data_tables directory, tabular data are stored as CSV files.

Note

The easiest way to create a new model is to use the calliope new command, which makes a copy of one of the built-in examples models:

$ calliope new my_new_model

This creates a new directory, my_new_model, in the current working directory.

By default, calliope new uses the national-scale example model as a template. To use a different template, you can specify the example model to use, e.g.: --template=urban_scale.

Next steps to setting up your model

The rest of this section discusses everything you need to know to set up a model: