Calliope Studio

Calliope Studio is a web-based user interface for the Calliope energy system modelling framework. It lets you define, edit, validate, run, and analyse Calliope models, all in a single tool. It runs in a browser directly on your computer.

Installation

With uv:

# One-time setup for uv on macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# One-time setup for uv on Windows
#   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv tool install calliope-studio

Then:

calliope-studio my-model      # a model folder containing model.yaml or a solved results .nc
calliope-studio               # no argument opens Calliope Studio with a model picker

To quit Calliope Studio, close its terminal window or press Ctrl+C inside it.

[!IMPORTANT] Calliope needs a solver to actually solve models. You can still use Studio to edit a model or analyse results that somebody else solved, but pressing Run will fail without a solver. Refer to the Calliope documentation for solver installation.

Development builds

To install a development build based on the latest main branch commit:

uv tool install --reinstall --prerelease allow \
  --find-links https://github.com/sjpfenninger/calliope-studio/releases/expanded_assets/dev \
  calliope-studio

The same command updates an existing install to the newest development build. To go back to the stable (released) version:

uv tool install --reinstall calliope-studio

FAQ

• Why does "Run" fail with a solver error? See the note above: you probably have no solver installed.
• Why is the list of models wrong or outdated? The list of models you have opened lives in a small registry file, separate from the models themselves. Its location is reported as registry_path by http://127.0.0.1:8000/api/health while Calliope Studio is running. Deleting it resets the list without actually touching any of your models.
• Where are model results stored? When running a model from inside Calliope Studio, results are saved in a calliope-studio/ folder next to the model.yaml file. This folder is created automatically when running a model for the first time and comes with its own .gitignore file.

Development

Requires pixi.

pixi run serve      # API on port 8000 with auto-reload
pixi run web-dev    # Vite dev server, proxying /api to port 8000

serve opens ./example-model, scaffolding it from Calliope's national_scale template on first use.

Try pixi task list to see all the available development tasks. Some relevant ones:

• pixi run solve-examples solves both Calliope example models into examples/nc_files/. The data tests and the results smoke check read these files, and skip when they are absent.
• pixi run test runs the Python test suite.
• pixi run -e build build produces a wheel and an sdist with the frontend compiled in (the packaging tools live in the build environment).

The frontend tests run from web/:

cd web
pnpm test

Pixi is configured with a gurobi environment to test with Gurobi (needs a license):

pixi run -e gurobi calliope-studio my-model   # Gurobi available as a solver

License

AGPL-3.0-or-later. See LICENSE.