The Calliope model and backend objects¶

In this tutorial, we use the urban scale example model to go into a bit more detail on the public and non-public properties of the calliope.Model and calliope.Model.backend objects.

In [1]:

Copied!

from pathlib import Path

import calliope

calliope.set_log_verbosity("INFO", include_solver_output=False)
from pathlib import Path

import calliope

calliope.set_log_verbosity("INFO", include_solver_output=False)

Model input¶

In [2]:

Copied!

# Initialise the model with the Urban Scale example model
m = calliope.examples.urban_scale()
# Initialise the model with the Urban Scale example model
m = calliope.examples.urban_scale()

[2026-09-01 19:54:08] INFO     Math init | loading pre-defined math.

[2026-09-01 19:54:08] INFO     Math init | loading math files {'additional_math', 'milp', 'spores', 'storage_inter_cluster', 'operate', 'base'}.

[2026-09-01 19:54:08] INFO     Model: preprocessing data

[2026-09-01 19:54:08] INFO     Math build | building applied math with ['base', 'additional_math'].

[2026-09-01 19:54:09] INFO     input data `name` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     input data `color` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     input data `name` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     input data `color` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     input data `name` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     input data `color` not defined in model math; it will not be available in the optimisation problem.

[2026-09-01 19:54:09] INFO     Model: initialisation complete

In [3]:

Copied!

# Get information on the model
print(m.info())
# Get information on the model
print(m.info())

[2026-09-01 19:54:09] WARNING  /home/docs/checkouts/readthedocs.org/user_builds/calliope/checkouts/latest/src/calliope/model.py:443: FutureWarning: The return type of `Dataset.dims` will be changed to return a set of dimension names in future, in order to be more consistent with `DataArray.dims`. To access a mapping from dimension names to lengths, please use `Dataset.sizes`.
  msize = dict(self.inputs.dims)

Model name:   Urban-scale example model
Model size:   {'costs': 1, 'nodes': 4, 'techs': 12, 'carriers': 3, 'timesteps': 48} (26 valid node:tech:carrier combinations)

Model data¶

m.inputs and m.results are xarray Datasets.

Until we solve the model, results is empty.

In [5]:

Copied!

m.results
m.results

Out[5]:

<xarray.Dataset> Size: 0B
Dimensions:  ()
Data variables:
    *empty*

Building and checking the optimisation problem¶

Calling m.build allows us to build the optimisation problem, which creates arrays of Python objects from the YAML math formulation.

In [6]:

Copied!

m.build()
m.build()

[2026-09-01 19:54:10] INFO     Model: backend build starting

[2026-09-01 19:54:10] INFO     Optimisation Model | parameters/lookups | Generated.

[2026-09-01 19:54:10] INFO     Optimisation Model | variables | Generated.

[2026-09-01 19:54:11] INFO     Optimisation Model | global_expressions | Generated.

[2026-09-01 19:54:13] INFO     Optimisation Model | constraints | Generated.

[2026-09-01 19:54:13] INFO     Optimisation Model | piecewise_constraints | Generated.

[2026-09-01 19:54:13] INFO     Optimisation Model | objectives | Generated.

[2026-09-01 19:54:13] INFO     Model: backend build complete

As with the calliope Model, the backend has its own dataset containing all the arrays of backend objects

There is then a public API to access filtered views on this dataset, e.g. input parameters...

... or constraints

You can also access backend arrays in text format, to debug the problem:

In [10]:

Copied!

m.backend.get_constraint(
    "area_use_capacity_per_loc", as_backend_objs=False
).to_pandas().dropna(how="all", axis=0)
m.backend.get_constraint(
    "area_use_capacity_per_loc", as_backend_objs=False
).to_pandas().dropna(how="all", axis=0)

Out[10]:

	lb	body	ub
nodes
X1	NaN	variables[area_use][0]	500.0
X2	NaN	variables[area_use][1]	1300.0
X3	NaN	variables[area_use][2]	900.0

We can increase the verbosity of the constraint/global expression "body" by calling the backend method verbose_strings. We do not do this automatically as it entails a memory/time overhead on building the model and is only necessary for debugging your optimisation problem.

In [11]:

Copied!





m.backend.verbose_strings()
m.backend.get_constraint(
    "area_use_capacity_per_loc", as_backend_objs=False
).to_pandas().dropna(how="all", axis=0)
m.backend.verbose_strings()
m.backend.get_constraint(
    "area_use_capacity_per_loc", as_backend_objs=False
).to_pandas().dropna(how="all", axis=0)

Out[11]:

	lb	body	ub
nodes
X1	NaN	variables[area_use][X1, pv]	500.0
X2	NaN	variables[area_use][X2, pv]	1300.0
X3	NaN	variables[area_use][X3, pv]	900.0

Updating the optimisation problem in-place¶

If we want to update a model input or fix a decision variable, we can do so now that we have built the optimisation problem

In [12]:

Copied!





m.backend.update_input("flow_cap_max", m.inputs.flow_cap_max * 2)
m.backend.get_parameter("flow_cap_max", as_backend_objs=False).sel(
    techs="pv"
).to_series().dropna()
m.backend.update_input("flow_cap_max", m.inputs.flow_cap_max * 2)
m.backend.get_parameter("flow_cap_max", as_backend_objs=False).sel(
    techs="pv"
).to_series().dropna()

Out[12]:

carriers     nodes
electricity  X1       500.0
             X2       500.0
             X3       100.0
Name: flow_cap_max, dtype: float64

Solve the optimisation problem¶

Once we have all of our optimisation problem components set up as we desire, we can solve the problem.

In [13]:

Copied!

m.solve()
m.solve()

[2026-09-01 19:54:14] INFO     Optimisation model | starting model in base mode.

[2026-09-01 19:54:14] INFO     Postprocessing: applied zero threshold 1e-10 to model results.

[2026-09-01 19:54:14] INFO     Optimisation Model | postprocess | Generated.

[2026-09-01 19:54:14] INFO     Backend: solver finished running. Time since start of solving optimisation problem: 0:00:00.773980

[2026-09-01 19:54:14] INFO     Postprocessing: ended. Time since start of solving optimisation problem: 0:00:00.784253

[2026-09-01 19:54:14] INFO     Backend: model solve completed. Time since start of solving optimisation problem: 0:00:00.784806

The results can now be accessed by the public property m.results

We can also view the data within the backend directly

In [15]:

Copied!

m.backend.get_variable("flow_cap", as_backend_objs=False).to_series().dropna()
m.backend.get_variable("flow_cap", as_backend_objs=False).to_series().dropna()

Out[15]:

nodes  techs               carriers   
N1     N1_to_X2            heat           189.87211
       N1_to_X3            heat           10.382599
       X1_to_N1            heat           567.70227
X1     X1_to_N1            heat           567.70227
       X1_to_X2            electricity    274.76645
       X1_to_X3            electricity    47.452088
       chp                 electricity    260.44701
                           gas            643.07904
                           heat           208.35761
       demand_electricity  electricity     1.307938
       demand_heat         heat            1.719711
       pv                  electricity          0.0
       supply_gas          gas            643.07904
       supply_grid_power   electricity    34.114372
X2     N1_to_X2            heat           189.87211
       X1_to_X2            electricity    274.76645
       boiler              gas            227.26339
                           heat           193.17388
       demand_electricity  electricity    269.34435
       demand_heat         heat           365.13767
       pv                  electricity    14.358886
       supply_gas          gas            227.26339
X3     N1_to_X3            heat           10.382599
       X1_to_X3            electricity    47.452088
       boiler              gas             0.018353
                           heat              0.0156
       demand_electricity  electricity    64.927357
       demand_heat         heat            9.398229
       pv                  electricity        100.0
       supply_gas          gas             0.018353
Name: flow_cap, dtype: object

Save¶

In [16]:

Copied!





# We can save at any point, which will dump the entire model to file.
# NetCDF is recommended, as it retains the model data _and_ attributes and can be reloaded into a Calliope model at a later date.


output_path = Path(".") / "outputs" / "4_calliope_model_object"
output_path.mkdir(parents=True, exist_ok=True)

m.to_netcdf(
    output_path / "example.nc"
)  # Saves a single file with two groups: `inputs` and `results`
m.to_csv(
    output_path / "csv_files", allow_overwrite=True
)  # Saves a file for each xarray DataArray
# We can save at any point, which will dump the entire model to file.
# NetCDF is recommended, as it retains the model data _and_ attributes and can be reloaded into a Calliope model at a later date.


output_path = Path(".") / "outputs" / "4_calliope_model_object"
output_path.mkdir(parents=True, exist_ok=True)

m.to_netcdf(
    output_path / "example.nc"
)  # Saves a single file with two groups: `inputs` and `results`
m.to_csv(
    output_path / "csv_files", allow_overwrite=True
)  # Saves a file for each xarray DataArray