Installation

This guide covers all the ways to set up CESM for use, development, and documentation generation.

Prerequisites

Python 3.11 or newer
git
Docker (optional, only needed for the devcontainer workflow)

Basic installation

Clone the repository, create a virtual environment, and install CESM in editable mode:

git clone <repository-url>
cd CommonEnergySystemModel
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install -e .

Always use a virtual environment. Installing CESM and its dependencies into your global Python is not recommended — it can cause version conflicts with other projects.

This installs the core dependencies defined in pyproject.toml:

linkml-runtime — LinkML schema runtime
pyyaml — YAML parsing
pandas — DataFrame operations
duckdb — embedded analytical database

Optional extras

The project defines optional dependency groups in pyproject.toml. Install them by appending the group name in brackets:

Development tools (pytest, ruff)

pip install -e ".[dev]"

Spine Toolbox workflows (includes Spine Toolbox and spinedb_api)

pip install -e ".[spine]"

Documentation tooling (linkml)

pip install -e ".[docs]"

You can combine extras: pip install -e ".[dev,spine]".

Generating Pydantic classes from the schema (optional)

This step is only needed if you want to import CESM data from YAML files (via from_yaml.py) or validate data against the schema. Regular transformation workflows (DuckDB, FlexTool, GridDB, Spine DB) do not require it.

pip install linkml
gen-pydantic model/cesm_v0.1.0.yaml > src/generated/cesm_pydantic.py

The generated file is not tracked in version control, so you need to run this command after every fresh clone and after any change to model/cesm_v0.1.0.yaml.

Devcontainer setup

The repository includes a devcontainer configuration that provides a ready-to-use development environment with Python 3.x, LinkML tools, all required dependencies, and editor extensions for AsciiDoc and Drawio.

VS Code

Install the Dev Containers extension.
Open the repository folder in VS Code.
When prompted, select Reopen in Container (or run the command Dev Containers: Reopen in Container from the command palette).

VSCodium

VS Code’s Dev Containers extension is not available in VSCodium. Use DevPod instead to open the devcontainer.

After opening the container

Once inside the container, create a virtual environment and install CESM:

python -m venv .venv
source .venv/bin/activate
pip install -e .            # or: pip install -e ".[dev]"

Documentation generation (optional)

Building the project documentation is a multi-step process that generates schema reference pages from the LinkML model and then assembles everything into an HTML site with Antora.

Step 1: Install the AsciiDoc generator

The schema documentation generator is installed from source:

pip install -e git+https://github.com/Netbeheer-Nederland/linkml-asciidoc-generator.git#egg=linkml-asciidoc-generator

Step 2: Generate schema reference pages

python -m linkml_asciidoc_generator.main "model/cesm_v0.1.0.yaml" -o "artifacts/documentation/modules/schema"

This produces AsciiDoc pages describing every class, slot, and enum in the CESM schema.

Step 3: Build the HTML site with Antora

You need Node.js and npm installed for this step.

npx antora antora-playbook.yml

The generated site is written to the output directory configured in antora-playbook.yml.

Verification

To verify that the installation works, load the included sample dataset into a DuckDB database:

python src/readers/from_yaml.py data/samples/cesm-sample.yaml artifacts/cesm.duckdb

If this completes without errors, the core installation is working correctly. See the Quickstart guide for more ways to exercise the toolchain.

Spine Toolbox setup

The repository includes a Spine Toolbox project with GUI-based workflows for data transformations.

Install

pip install -e ".[spine]"

This installs Spine Toolbox and all its dependencies (including spinedb_api).

Launch and open the project

spinetoolbox

In Spine Toolbox, go to File > Open project… and select the repository root directory (the folder containing .spinetoolbox/project.json). The workflows for YAML to CESM, CESM to FlexTool, CESM to GridDB, and other transformations will be available.

The FlexTool3 tool specification in the project file references an external path that must be updated to match your local FlexTool3 installation. FlexTool3 itself is optional — the core CESM transformation tools work without it.

For more details, see the Spine Toolbox Guide.