Step-by-step Passive Retrofit

Python framework for evaluating step-by-step building retrofit strategies using EnergyPlus.

The repository supports lifecycle analysis of retrofit scenarios by combining building energy simulation with thermal comfort, economic, and emissions assessment. It was developed from research on staged renovation strategies and preserves the validated computational logic used in the original PhD study.

The framework includes 18,421 lifecycle retrofit scenarios and 326 unique EnergyPlus simulation cases covering combinations of wall, window, roof, floor, and shading measures over a 30-year analysis period.

Requirements

• Python 3.10 or newer
• EnergyPlus 24.2
• The original base epJSON model
• The Trondheim-Voll EPW weather file

Install the package:

python -m pip install -e .

Configure external inputs:

$env:ENERGYPLUS_HOME = "C:\EnergyPlusV24-2-0"
$env:PASSIVE_BASE_MODEL = "C:\sample\NordreSizedShadingJuly2.epJSON"
$env:PASSIVE_WEATHER = "C:\sample\NOR_TD_Trondheim-Voll.012570_TMYx.2009-2023.epw"

Run the baseline:

python experiments/run_baseline.py

Run the three regression cases:

python experiments/run_representative_cases.py --parallel

Preview the full simulation set without running it:

python experiments/run_all_scenarios.py

Bulk execution requires an explicit safety flag:

python experiments/run_all_scenarios.py --confirm-simulations --skip-existing

Generated files default to outputs/energyplus/ and are ignored by Git. Override this location with PASSIVE_OUTPUT_DIR or --output-dir.

Reproducible pipeline

The pipeline connects scenario generation, EnergyPlus, extraction, lifecycle analysis, aggregation, and output generation while reusing the scientific modules listed below.

environment/configuration
          |
          v
18,421-scenario catalogue -> selected lifecycle scenarios
          |
          v
unique EnergyPlus cases -> simulate missing cases or reuse existing outputs
          |
          v
HTML + hourly CSV + EIO extraction
          |
          v
energy + comfort + economics + emissions
          |
          v
scenario aggregation
          |
          v
CSV/XLSX tables + SVG emissions figure

Required inputs

• EnergyPlus 24.2 installation
• Baseline epJSON building model
• Trondheim-Voll EPW weather file
• The environment variables shown in the Requirements section

The default pipeline selection is lifecycle scenario index 0. Its six five-year checkpoint cases form a small reproducible validation run while retaining the notebook's global baseline convention.

Run the pipeline:

python scripts/run_pipeline.py

Process selected scenarios:

python scripts/run_pipeline.py --scenario-indices 0 1 2688

Reuse existing EnergyPlus outputs and fail clearly if any required case is missing:

python scripts/run_pipeline.py --scenario-indices 0 --skip-simulations

By default, existing complete case directories are reused and only missing cases are simulated. Use --rerun-existing only when deliberate regeneration is required.

Generated files:

outputs/
├── energyplus/<case identifier>/   # generated models and EnergyPlus outputs
└── pipeline/
    ├── tables/
    │   ├── scenario_results.csv
    │   └── scenario_results.xlsx
    └── figures/
        └── emissions_profile.svg

Everything under outputs/ is excluded from Git. Use --output-dir to choose a different pipeline-results directory and PASSIVE_OUTPUT_DIR to choose the EnergyPlus case directory.

Tests

The core tests use unittest and do not require plotting dependencies:

$env:PYTHONPATH = "src"
python -m unittest discover -s tests -v

To include EnergyPlus regression outputs:

$env:PASSIVE_REGRESSION_OUTPUT = "outputs\energyplus"
python -m unittest discover -s tests -v

Architecture

Notebook responsibility	Project implementation
Paths and runtime configuration	config.ProjectConfig
Retrofit properties and deterioration	measures.RetrofitCatalog
Scenario generation and timelines	scenarios
epJSON modification and EnergyPlus	energyplus
HTML, CSV, and EIO extraction	results
Energy calculations	energy
Comfort calculations	comfort
Discounting and investment costs	economics
Embodied and operational emissions	emissions
Final scenario table	aggregation
Figures	plotting
End-to-end case execution	experiment.ExperimentRunner
Reproducible lifecycle workflow	pipeline.RetrofitPipeline

The validated notebook remains the reference implementation and is not required at runtime.