Overview

Builelib is a Python library for calculating the annual energy consumption of non-residential buildings. It implements the calculation methods used by Japan's Building Energy Conservation Standard program for non-residential buildings (WEBPRO).

Builelib provides an Excel-based CLI, a Python API, a JSON-based FastAPI application, and a Docker configuration.

Parse an input sheet in memory

from builelib.input import parse_input_sheet

result = parse_input_sheet("input.xlsx")
print(result.data)
print(result.errors, result.warnings)

This API supports .xlsx and .xlsm WEBPRO input sheets and does not create an intermediate JSON file. Envelope consumers can also import calculate_wall_u_value and calculate_window_performance from builelib.input.

Requirements

• Python 3.12 or later
• uv
• Git
• Docker, only when running the containerized API

Setup

1. Install uv

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

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

2. Clone the repository and install dependencies

git clone https://github.com/MasatoMiyata/builelib.git
cd builelib
uv sync --locked

uv sync creates the .venv virtual environment and installs the dependencies. --locked uses the committed uv.lock without changing it.

Run from the CLI

Run a calculation

uv run builelib <inputfile>

Replace <inputfile> with the path to an actual .xlsx or .xlsm file. Do not type the angle brackets themselves.

Example using the included sample file:

uv run builelib ./examples/Builelib_inputSheet_sample_001.xlsx

Quote paths that contain spaces.

uv run builelib "C:\path with spaces\input.xlsx"

Validate input without calculating

Pass False as the second argument to parse and validate the Excel input without running the energy calculations.

uv run builelib <inputfile> False

Validation-only mode still writes the converted input, validation results, per-system result files, and a ZIP archive.

Output files

Output files are written next to the input Excel file. Existing files with the same names are overwritten.

Run from Python

Calculate from an Excel or JSON file

from builelib.runner import calculate

calculate("./examples/Builelib_inputSheet_sample_001.xlsx")

calculate() accepts a file path and reads Excel (.xlsx, .xlsm) or JSON (.json) according to its extension. It writes JSON, CSV, and ZIP files next to the input file instead of returning the results. For a JSON file, use calculate("input.json"). Pass False as the second argument to skip equipment calculations and validate the input.

calculate("./examples/Builelib_inputSheet_sample_001.xlsx", False)

Calculate from JSON data in memory

calculate_from_json() accepts a dictionary that conforms to webproJsonSchema and returns a result dictionary without creating files.

from builelib.runner import calculate_from_json

output = calculate_from_json(input_data)
print(output["result"])
print(output["errors"])

Run the Web API

Start the local development server:

uv run uvicorn main:app --reload --host 127.0.0.1 --port 8000

After the server starts, open the interactive API documentation:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Main endpoints:

Run with Docker

compose.yaml uses an external volume and an external network. Create them once before the first start.

docker volume create builelib_data
docker network create mynetwork

Build and start the service:

docker compose up --build -d

The API documentation is available at http://localhost:8081/docs.

Stop the service with:

docker compose down

The external builelib_data volume is not removed by docker compose down.

Create input data

Enter the building specifications in a WEBPRO input sheet, using the same input procedure as WEBPRO.

Add the Builelib-specific SP sheet (Form SP) to the WEBPRO input sheet to specify detailed calculation conditions. Sample files are available in examples.

See the manual for details.

Tests

uv run python -m pytest tests

Example that runs a specific test file:

uv run python -m pytest tests/test_api.py -v

Remove the development environment

Builelib is installed in the repository-local .venv. To remove the development environment, move to the repository's parent directory and delete the builelib directory.

Windows PowerShell:

cd ..
Remove-Item -Recurse -Force .\builelib

macOS / Linux:

cd ..
rm -rf ./builelib

References

• WEBPRO for non-residential buildings
• Engineering reference
• Engineering reference source

License

MIT License

© Masato Miyata