softcpsrecsimulator 0.1.0

An open source Farama Foundation Gymnasium environment for benchmarking distributed energy resource control algorithms to provide energy flexibility in a district of buildings.

CityLearn

CityLearn is an open source Farama Foundation Gymnasium environment for the implementation of Multi-Agent Reinforcement Learning (RL) for building energy coordination and demand response in cities. A major challenge for RL in demand response is the ability to compare algorithm performance. Thus, CityLearn facilitates and standardizes the evaluation of RL agents such that different algorithms can be easily compared with each other.

Environment Overview

CityLearn includes energy models of buildings and distributed energy resources (DER) including air-to-water heat pumps, electric heaters and batteries. A collection of building energy models makes up a virtual district (a.k.a neighborhood or community). In each building, space cooling, space heating and domestic hot water end-use loads may be independently satisfied through air-to-water heat pumps. Alternatively, space heating and domestic hot water loads can be satisfied through electric heaters.

Installation

Install latest release in PyPi with pip:

pip install softcpsrecsimulator

Python import path remains:

from citylearn.citylearn import CityLearnEnv

Developer Commands

Use the repository virtual environment when available:

.venv/bin/pytest -q

Critical lint checks used in CI:

.venv/bin/python -m ruff check citylearn tests scripts/manual scripts/ci --select E9,F821

Manual utility scripts live in scripts/manual and are excluded from default pytest collection:

python scripts/manual/demo_ev_rbc.py
python scripts/manual/demo_ev_rbc_export_end.py

Runtime benchmark (main training resolutions 5s/60s):

python scripts/manual/bench_runtime.py --seconds 5 60 --render-modes none end --episode-steps 1200

CI performance smoke check command:

python scripts/ci/perf_smoke.py --episode-steps 600 --seconds 60 --baseline-file scripts/ci/perf_baseline.json

Publish This Fork to PyPI

This fork is configured to publish the distribution name softcpsrecsimulator.

1. Create the package on PyPI (project name: softcpsrecsimulator).
2. In GitHub repo settings, add secret PYPI_API_TOKEN with a PyPI token that can publish this project.
3. Bump citylearn/__init__.py version.
4. Push commit and create a GitHub Release (or run Publish Python Package workflow manually).
5. Workflow .github/workflows/pypi_deploy.yml builds dist/* and uploads to PyPI.

Optional local build check:

python -m pip install --upgrade pip build twine
python -m build
python -m twine check dist/*

Internal Architecture

Public APIs remain in CityLearnEnv and Building, while internal orchestration is split into service modules under citylearn/internal:

• loading.py: schema-driven loading/build assembly (_load*, metadata processing).
• runtime.py: episode runtime orchestration (step, action parsing, time progression, EV/charger association).
• building_ops.py: building observation/action orchestration.
• kpi.py: KPI/evaluation pipeline.

Export and Render Modes

CityLearnEnv keeps export off by default:

• render_mode='none': no CSV export and minimal runtime overhead.
• render_mode='during': writes CSV rows at each environment step.
• render_mode='end': keeps the rollout fast and writes full episode CSVs when the episode ends.

Optional location controls:

• render_directory: base folder for exports.
• render_session_name: session subfolder name under render_directory (or render_directory_name).
• render_directory_name: legacy fallback folder under project root when render_directory is not set.
• render: legacy boolean flag; still supported for compatibility.

Examples:

from citylearn.citylearn import CityLearnEnv

# Fast training/no export
env = CityLearnEnv(schema, render_mode='none')

# Stream CSVs every step
env = CityLearnEnv(
    schema,
    render_mode='during',
    render_directory='outputs',
    render_session_name='run_during'
)

# Export once at episode end
env = CityLearnEnv(
    schema,
    render_mode='end',
    render_directory='outputs',
    render_session_name='run_end'
)

Documentation

Refer to the docs.

CityLearn UI

CityLearn UI is a visual dashboard for exploring simulation data generated by the CityLearn framework. It was developed to simplify the analysis of results from smart energy communities, district energy coordination, demand response (among other applications), allowing users to visually inspect building-level components, compare simulation KPIs, and create simulation schemas with ease.

The interface is available in two options:

• Web app: https://citylearnui.netlify.app/ (free hosted version — not recommended for sensitive/personal data)
• Open-source code: https://github.com/Soft-CPS-Research-Group/citylearn-ui

You can check a tutorial at the official CityLearn website, in the CityLearn UI repository README, or at the help tooltip of the oficial webapp.

Compatibility: This version of the UI currently supports CityLearn v2.5.0 simulation data.

Developed by: José, a member of the SoftCPS, Software for Cyber-Physical Systems research group (ISEP, Portugal) in collaboration with the Intelligent Environments Lab, University of Texas at Austin.