kub-bestest

1. Overview

kub-bestest is a command-line tool for generating ASHRAE 140-2020 BESTEST (Building Energy Simulation Test) reference cases for building energy simulation validation.

BESTEST provides standardized test cases to verify that building energy analysis programs produce results within accepted ranges. The generated datasets include:

  • Building geometry (GeoJSON and mesh files)

  • Thermal properties and constructions

  • Weather data

  • HVAC scenario configurations

  • Reference results for validation

2. Installation

The tool is included with the ktirio-ub package:

pip install ktirio-ub
# or with uv
uv pip install -e .

3. Usage

3.1. Synopsis

kub-bestest {generate,list,info} [OPTIONS]

3.2. Commands

3.2.1. generate

Generate a BESTEST dataset for a specific case:

kub-bestest generate --case 600 --output cemdb/locations/bestest_600

Options:

Option Description

--case, -c INT

BESTEST case number (default: 600)

--output, -o PATH

Output directory (required)

--version, -v VERSION

Dataset version (default: 0.1.0)

--year INT

Weather data year (default: 2023)

Example output structure:

cemdb/locations/bestest_600/
└── v0.1.0/
    ├── config.json           # Simulation configuration
    ├── manifest.json         # Dataset manifest
    ├── preprocessing/
    │   ├── enrichment/
    │   │   └── buildings.json
    │   ├── geometry/
    │   │   └── buildings.geojson
    │   └── mesh/
    │       └── bestest.msh
    ├── scenarios/
    │   └── hvac/
    │       └── ideal_heating_cooling.json
    └── weather/
        └── tmy/
            └── golden_co.epw

3.2.2. list

List available BESTEST cases:

kub-bestest list

Example output:

Available BESTEST cases:

  Case 600: Lightweight low-mass building with south-facing windows

3.2.3. info

Show detailed information about a specific BESTEST case:

kub-bestest info 600

Example output:

BESTEST Case 600
========================================
Description: Lightweight low-mass building with south-facing windows

Geometry:
  Dimensions: 8.0m x 6.0m x 2.7m
  Floor area: 48.0 m²
  Volume: 129.6 m³

Climate Control:
  Heating setpoint: 20.0°C
  Cooling setpoint: 27.0°C
  Infiltration: 0.5 ACH
  Internal gains: 200.0 W

Location:
  Weather: Golden, CO, USA
  Coordinates: 39.74°N, 105.18°W
  Elevation: 1829.0 m

Reference Results (ASHRAE 140-2020):
  Annual heating: 1.193 - 1.586 MWh
  Annual cooling: 1.705 - 2.212 MWh
  Peak heating: 3.437 - 4.354 kW
  Peak cooling: 5.965 - 6.827 kW

4. Available Cases

Case Description Mass Level

600

Lightweight low-mass building with south-facing windows

Lightweight

900

Heavyweight high-mass building (planned)

Heavyweight

610

Low-mass with external shading (planned)

Lightweight

620

Low-mass with east/west windows (planned)

Lightweight

4.1. Case 600 Specifications

Case 600 is the base lightweight case from ASHRAE 140-2020:

Geometry: - Dimensions: 8.0m × 6.0m × 2.7m (length × width × height) - Floor area: 48 m² - Volume: 129.6 m³ - Window area: 12 m² (south-facing)

Thermal Properties:

Component Construction U-value

Walls

Plasterboard + Fiberglass insulation + Wood siding

~0.514 W/m²K

Roof

Plasterboard + Fiberglass insulation + Roof deck

~0.318 W/m²K

Floor

Timber floor + High-R insulation

~0.040 W/m²K

Windows

Double glazing (SHGC: 0.787)

3.0 W/m²K

Operating Conditions: - Heating setpoint: 20°C - Cooling setpoint: 27°C - Infiltration: 0.5 ACH - Internal gains: 200 W (40% convective, 60% radiative)

Weather Location: - Golden, Colorado, USA - Latitude: 39.74°N - Longitude: 105.18°W - Elevation: 1829 m

5. Reference Results

ASHRAE 140-2020 provides reference ranges from multiple validated simulation programs. Simulation results should fall within these ranges:

5.1. Case 600 Reference Values

Metric Min Max

Annual heating

1.193 MWh

1.586 MWh

Annual cooling

1.705 MWh

2.212 MWh

Peak heating load

3.437 kW

4.354 kW

Peak cooling load

5.965 kW

6.827 kW

6. Python API

The module can also be used programmatically:

from feelpp.ktirio.ub.dataset.generators.bestest import (
    generate_bestest_dataset,
    generate_config,
    generate_geojson,
    generate_weather,
    generate_scenarios,
    generate_mesh,
    BESTESTCase,
    Case600,
    get_case,
    list_cases,
)

# Generate complete dataset
artifacts = generate_bestest_dataset(
    output_dir="cemdb/locations/bestest_600/v0.1.0",
    case=Case600,
    version="0.1.0",
    year=2023,
)
print(artifacts)
# {'config': Path(...), 'geojson': Path(...), 'mesh': Path(...), ...}

# List available cases
cases = list_cases()
print(cases)  # [600]

# Get case details
case = get_case(600)
print(f"Floor area: {case.floor_area_m2} m²")
print(f"Volume: {case.volume_m3} m³")

# Check reference results
ref = case.reference_results
passed, msg = ref.validate_heating(1.4)  # MWh
print(f"Heating validation: {msg}")

# Generate individual components
geojson = generate_geojson(case, output_dir)
weather = generate_weather(case, output_dir, year=2023)
scenarios = generate_scenarios(case, output_dir)

7. Validation Workflow

  1. Generate dataset:

    kub-bestest generate --case 600 --output cemdb/locations/bestest_600

  2. Run simulation using CEM:

    kub run cemdb/locations/bestest_600/v0.1.0

  3. Compare results against reference values to validate your simulation setup.

8. Exit Codes

Code Description

0

Success

1

Error (invalid case, generation failure, etc.)

9. References

10. See Also