Energy Modeling Decisions

A structured catalog of typical problems, tools, use cases, and challenges in using energy modeling tools for buildings.

Current State

Category	Count	IDs
Problems	8	prob_001 – prob_008
Tools	9	tool_001 – tool_009
Use Cases	21	uc_001 – uc_021
Challenges	9	chal_001 – chal_009

Implementation Summary

This folder uses a matrix-based workflow driven by data.yaml.

Data model

• Problems: 8 (prob_001 to prob_008)
• Tools: 9 (tool_001 to tool_009)
• Use cases: 21 (uc_001 to uc_021)
• Challenges: 9 (chal_001 to chal_009)

The use_cases section is the source of truth for problem-tool combinations.

Active scripts

• generate_interface_matrix.py

  • Generates index.html from data.yaml
  • Includes the matrix UI, problem/tool/use-case modals, and challenges list
  • Persists current page header and matrix header layout

• _reconcile_connections.py

  • Rebuilds tools[].use_cases from use_cases
  • Rebuilds tools[].problems_addressed from use_cases
  • Validates references across problems/tools/use_cases/challenges

Standard edit workflow

1. Edit data.yaml
2. Run reconciliation
3. Regenerate HTML

python _reconcile_connections.py
python generate_interface_matrix.py

Notes

• Manual edits to index.html can be overwritten by regeneration.
• If a UI text change should persist, update generate_interface_matrix.py and regenerate.

Files

File	Purpose
data.yaml	All data — edit this to add entries
index.html	🌐 Interactive web explorer — problems, tools, use cases, challenges with cross-references
generate_interface_matrix.py	🔧 Generates the matrix-style index.html from data.yaml
_reconcile_connections.py	✅ Rebuilds and validates cross-references from use_cases

Using the Interactive Interface

Open index.html in your web browser to explore the interactive matrix:

• Click on a Problem (left column) → See details, relevant users, and applicable tools
• Click on a Tool (column header) → See details, all problems it addresses, key attributes
• Click on a Matrix Cell (✓) → See the full use case with pros/cons and challenges

The matrix displays all 21 use cases across 8 problems and 9 tools. Hover for visual feedback.

Regenerating the interface

After editing data.yaml, regenerate the HTML interface:

python _reconcile_connections.py
python generate_interface_matrix.py

Maintaining Cross-Reference Integrity

The use_cases section is the matrix source of truth for problem-tool connections. After any edit, re-sync and validate cross-references before regenerating outputs:

python _reconcile_connections.py
python generate_interface_matrix.py

This guarantees that each tool's use_cases and problems_addressed are rebuilt from the matrix and all references across problems/tools/use_cases/challenges are valid.

---

Schema reference

All data lives in data.yaml in four top-level sections. Every entry has a unique ID used to cross-reference other sections.

problems

Things that need to be solved.

Field	Type	Description
id	prob_NNN	Unique identifier
name	string	Short label
description	string	One-paragraph description
tags	list of strings	Free-form keywords
users	list of strings	Who faces this problem (e.g., "Building Designers", "Policy Makers")

tools

Software or methods used to address problems.

Field	Type	Description
id	tool_NNN	Unique identifier
name	string	Tool name
description	string	One-paragraph description
url	string (optional)	Homepage or repo
problems_addressed	list of prob_NNN	Which problems this tool handles
use_cases	list of uc_NNN	Use cases where this tool is applied
ease_of_use	high|med|low	Learning curve & operational complexity
time_required	high|med|low	Analysis time per building (high=days, med=hours, low=min/sec)
expense	high|med|low	Total cost including labor
challenges	list of chal_NNN	Challenges this tool faces
attributes	dict	Named characteristics for comparison (e.g., accuracy, data_requirements)

use_cases

Specific scenarios combining a problem and a tool.

Field	Type	Description
id	uc_NNN	Unique identifier
name	string	Short label
description	string	One-paragraph description
problem	prob_NNN	Problem this use case addresses
tool	tool_NNN	Tool used in this use case
users	list of strings	Relevant user roles (e.g., "Building Owners", "Policy Makers")
challenges	list of chal_NNN	Challenges relevant to this use case
pros	list of strings	Advantages of this approach
cons	list of strings	Disadvantages/limitations

challenges

Cross-cutting difficulties that affect multiple problems and tools.

Field	Type	Description
id	chal_NNN	Unique identifier
name	string	Short label
description	string	One-paragraph description
problems	list of prob_NNN	Problems this challenge complicates
tools	list of tool_NNN	Tools most affected

---

How to add a use case

1. Append to the use_cases list with the next uc_NNN id.
2. Specify the relevant problem (single ID) and tool (single ID).
3. Fill in name and description.
4. Add users (list of user roles) and challenges (list of chal_NNN IDs).
5. List pros and cons (advantages and disadvantages of this combination).
6. Run:

python _reconcile_connections.py
python generate_interface_matrix.py

How to add a problem

1. Append to the problems list with the next prob_NNN id.
2. Fill in name, description, and tags.
3. Add users (list of user roles who face this problem).
4. Update relevant tools' problems_addressed lists.
5. Create corresponding use cases.
6. Run:

python _reconcile_connections.py
python generate_interface_matrix.py