Setup & Prerequisites

This page lists all software requirements needed to work with BuEM. Requirements are separated by role: Users interact with BuEM through its API (typically via Docker), while Developers work directly with the source code and contribute to the project.

Software Requirements

The table below summarises every piece of software you may need. Items marked compulsory must be installed before you can run BuEM.

Requirement	Version	Compulsory / Optional	Use / Notes	Download Link
Python	>= 3.13	Compulsory	Runtime for BuEM. The conda environment pins 3.13 exactly.	python.org
Conda (Miniconda or Anaconda)	latest	Compulsory (developers)	Environment & dependency management. Miniconda is sufficient.	Miniconda
Docker Desktop	>= 4.6	Compulsory (users)	Runs the BuEM container. Includes Docker Engine >= 29 and Compose v2.	Docker Desktop
Git	latest	Compulsory	Source code access and version control.	git-scm.com
PostgreSQL	>= 17	Compulsory	Database back-end for building data.	PostgreSQL
PgAdmin	>= 8	Optional	GUI for inspecting and managing the PostgreSQL database.	PgAdmin
City2TABULA	v0.5.0	Compulsory	Populates the building database that BuEM reads. See City2TABULA below.	City2TABULA setup
IDE (VS Code / PyCharm)	latest	Optional	Recommended editor for development. VS Code with the Python extension works well.	VS Code / PyCharm

Note

Docker Desktop >= 4.6 ships with Docker Engine >= 29 and Docker Compose v2. You do not need to install Docker Engine or Compose separately when using Docker Desktop.

For Users

If you only need to run BuEM simulations via its API, install the following and skip the developer section:

1. Docker Desktop – provides the container runtime.

2. Git – to clone the repository and access docker-compose.yml.

3. PostgreSQL – database for building parameters.

4. City2TABULA – populates the database with building archetypes.

Quick verification:

docker --version        # Docker version 29.x or higher
docker compose version  # Docker Compose v2.x
git --version
pg_config --version     # PostgreSQL 17.x or higher

Tip

pg_config is used instead of psql because many PostgreSQL installations (especially GUI-based installers on Windows) do not add psql to the system PATH. pg_config ships with the core PostgreSQL libraries on all platforms. If the command is not found, ensure the PostgreSQL installation directory (e.g. C:\Program Files\PostgreSQL\17\bin on Windows, or /usr/bin on Linux) is on your PATH.

Once the prerequisites are in place, proceed to Docker Installation to start the BuEM container.

For Developers

Developers need everything listed for users plus the local Python environment:

1. Python 3.13 and Conda – managed via environment.yml.

2. IDE – VS Code or PyCharm recommended.

3. PgAdmin – optional, helpful for database inspection.

Quick verification:

python --version        # Python 3.13.x
conda --version
docker --version        # Docker version 29.x or higher
git --version
pg_config --version     # PostgreSQL 17.x or higher

See the tip in the Users section above if pg_config is not found.

Proceed to Conda Setup to create the development environment, then see Development Setup for code-quality tools and testing.

City2TABULA

City2TABULA generates the building-archetype database that BuEM consumes. Follow the City2TABULA setup guide to install version v0.5.0 and populate your PostgreSQL database before running BuEM.

Key steps (summary):

1. Clone the City2TABULA repository.

2. Install its conda environment.

3. Configure the PostgreSQL connection.

4. Run the database population script.

Refer to the City2TABULA documentation for the full procedure.

System Requirements

Resource	Minimum
Operating System	Windows 10+, macOS 12+, or Linux (Ubuntu 22.04+ recommended)
Memory	4 GB (8 GB recommended for large datasets)
Disk Space	2 GB (additional space for weather data and results)
Network	Internet access for pulling Docker images and downloading dependencies

Next Steps

Role	Next Page
Users (API / Docker)	Docker Installation
Developers	Conda Setup