# 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.

![Demand-response](https://github.com/intelligent-environments-lab/CityLearn/blob/master/assets/images/dr.jpg)

## 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.

![Citylearn](https://github.com/intelligent-environments-lab/CityLearn/blob/master/assets/images/environment.jpg)

## Installation
Install latest release in PyPi with `pip`:
```console
pip install softcpsrecsimulator
```

Optional dependency for PV autosizing (`PySAM`):
```console
pip install "softcpsrecsimulator[pysam]"
```

Python import path remains:
```python
from citylearn.citylearn import CityLearnEnv
```

## Developer Commands
Use the repository virtual environment when available:

```console
.venv/bin/pytest -q
```

Critical lint checks used in CI:

```console
.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:

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

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

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

CI performance smoke check command:

```console
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:
```console
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:

```python
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](https://intelligent-environments-lab.github.io/CityLearn/).

## 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](https://intelligent-environments-lab.github.io/CityLearn/ui.html), in the CityLearn UI repository [README](https://github.com/Soft-CPS-Research-Group/citylearn-ui), or at the help [tooltip of the oficial webapp](https://citylearn-ui.netlify.app/admin/help).

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

**Developed by:** José, a member of the [SoftCPS](https://www2.isep.ipp.pt/softcps/), Software for Cyber-Physical Systems research group (ISEP, Portugal) in collaboration with the Intelligent Environments Lab, University of Texas at Austin.
