Skip to content

Installation

This repository is a Python workspace with a JavaScript dashboard for Gridalyn: the core digital-twin SDK, governed project workflows, semantic graph exports, canonical reports, and the dashboard. Use the gridalyn CLI for all local workflows.

Prerequisites

Recommended local tools:

  • Python 3.12 or newer;
  • uv for Python dependency management;
  • Node.js 20 or newer for the dashboard;
  • Docker and Docker Compose for local dashboard deployment;
  • Git.

Install uv if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Python Environment

From the repository root:

uv sync --extra dev

Use plain uv sync when you only need the installable SDK and CLI. These are the heavier capability groups:

uv sync --extra geo        # geospatial preprocessing and OSM tooling
uv sync --extra sim        # pandapower and LightSim2Grid helpers
uv sync --extra ops        # optimization and operational analytics
uv sync --extra dashboard  # dashboard and visualization helpers
uv sync --extra all        # full runtime capability set

The complete set is all, cim, dashboard, dev, docs, geo, ops, sim, test and typing. There is no semantic extra — it was removed on 2026-08-07 together with the dead RDF/XML exporter and rdflib. The semantic graph needs no extra at all: it is Parquet and pandas, both base dependencies, so plain uv sync is enough to build and validate it.

uv sync synchronises the environment exactly: each command above replaces the installed set rather than adding to it, so running uv sync --extra geo after uv sync --extra dev uninstalls the dev toolchain (measured: 121 packages removed, including pytest). Note also that --extra all is the full runtime set and does not include the test and documentation tooling. To keep several groups at once, pass them in one command, as in uv sync --extra dev --extra geo.

The dev extra installs the full runtime plus test and documentation tooling for the repository workflow.

Run the test suite:

uv run --with pytest python -m pytest -q

Run a focused test module:

uv run --with pytest python -m pytest tests/test_project_hygiene.py -q

Dashboard Environment

Install frontend dependencies:

npm install --prefix dashboard

Run checks:

npm --prefix dashboard run lint
npm --prefix dashboard run build

Deploy locally with compose:

docker compose -f dashboard/docker-compose.yml up -d --build dashboard

The dashboard is typically available at:

http://localhost:8081/

Documentation Environment

Build the documentation:

uv run --extra docs mkdocs build --strict -f docs/mkdocs.yml

MkDocs writes generated HTML to the root site/ directory, which is ignored by Git. The source documentation lives under the domain folders in docs/.

Repository Layout

The main source directories are:

configs/                 reusable grid and geography configuration
gridalyn/                canonical Python SDK package and namespace
projects/                governed reproducible workflows
instances/default/       default local digital-twin instance
dashboard/               browser application source
docs/                    MkDocs source
examples/                tutorials and data-acquisition examples

Generated simulations can update many figures, Parquet files, and JSON reports. Review git status --short before committing so generated project outputs do not get mixed with source-only changes.

Next Step

Continue with the Quickstart to run a real study end to end. Come back to the Reproducibility Guide once you need byte-stable results across machines.