KUB Course - Building Energy Simulation

Educational Python library for building energy simulation using FMU (Functional Mock-up Units). Designed for training courses on thermal building physics and energy performance analysis.

Features

• 🏗️ FMU Simulation: High-level wrapper for FMPy to run building energy simulations
• 📊 Visualization: Interactive Plotly-based plotting for temperature, heat flux, and energy analysis
• 📚 Material Database: Comprehensive thermal properties of construction and insulation materials
• 📓 Training Notebooks: Hands-on exercises covering:
  • Heat conduction and thermal resistance
  • Infrared and solar radiation
  • Building loss assessment
  • Weather data analysis
  • Case studies with optimization

Quick Start

Installation

Option 1: Using Dev Container (Recommended)

Open this repository in VS Code and click "Reopen in Container". Everything will be set up automatically.

Option 2: Using UV (Fast)

uv venv --system-site-packages
source .venv/bin/activate
uv pip install -e '.[dev,test]'

Option 3: Using pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e '.[dev,test]'

Basic Usage

from kub.course.simlib import FMUSimulation
from kub.course.plotlib import SimulationPlotFactory
from pathlib import Path

# Load and run an FMU simulation
fmu_path = Path("database/day1/FMUs/Exercises_Conduction_SteStaWalResCon_01.fmu")
sim = FMUSimulation(fmu_path)

# Configure simulation
sim.initialize(startTime=0.0, stopTime=3600.0, timeStep=1.0)
sim.initParameters({"Wall_Resistor.R": 1.5, "Wall_Conductor.G": 0.75})
sim.exitInitialization()

# Run and collect results
data = sim.run(["Wall_Resistor.port_b.T", "Wall_Conductor.port_b.Q_flow"])
sim.terminate()

# Visualize results
factory = SimulationPlotFactory()
factory.plot_subplots(
    time=data["time"],
    data_type="temperature",
    data_dict={"Temperature": data["Wall_Resistor.port_b.T"]},
    title="Wall Temperature Over Time"
)

Material Database

from kub.course.simlib.materials import insulation_materials, structural_materials

# Access thermal properties
glass_wool = insulation_materials["glass_wool"]
print(f"Lambda: {glass_wool['lambda']} W/(m·K)")
print(f"Density: {glass_wool['rho']} kg/m³")
print(f"Specific heat: {glass_wool['Cp']} J/(kg·K)")

Project Structure

course.kub/
├── .devcontainer/          # Development container configuration
├── .github/workflows/      # CI/CD pipelines
├── .vscode/                # VS Code settings
├── database/               # FMU files and data
│   ├── day1/              # Day 1 exercises (conduction, radiation)
│   └── day2/              # Day 2 exercises (optimization, weather)
├── notebooks/              # Jupyter training notebooks
│   ├── trainingDay1/      # Basic physics exercises
│   └── trainingDay2/      # Advanced case studies
├── src/python/kub/course/ # Main package
│   ├── plotlib/           # Visualization utilities
│   └── simlib/            # Simulation and materials
└── tests/                  # Unit tests (coming soon)

Development

Running Tests

pytest                                    # Run all tests
pytest --cov=kub --cov-report=html       # With coverage report

Code Quality

ruff check .                             # Lint code
ruff format .                            # Format code
ruff check --fix .                       # Auto-fix issues

Building the Package

python -m build
pip install dist/*.whl

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Authors

• Philippe Pinçon - [email protected]
• Gwennolé Chappron - [email protected]
• Christophe Prud'homme - [email protected]

Acknowledgments

• Part of the Ktirio Urban Building (KUB) project
• Uses FMPy for FMU simulation
• Built with Plotly for interactive visualization