# wayne-turner/heat_loss architecture

> Architecture diagram of the GitHub repository wayne-turner/heat_loss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wayne-turner/heat_loss
- Repository: https://github.com/wayne-turner/heat_loss

## Overview

##### Project type and purpose
- This is a lightweight, educational Python toolkit (“heat_loss”) for calculating and analyzing heat loss in buildings.
- It’s delivered as a library/script (heat_loss_simulation.py) rather than a multi‐tier web application. It targets educators, students, DIY homeowners, contractors, and energy analysts.

##### File structure
- Top level:
- README.md         ← project description, usage, features
- heat_loss_simulation.py ← core implementation
- requirements.txt  ← external dependencies (Pandas, Matplotlib/Seaborn)
- No separate “frontend” or “backend” directories. All logic resides in a single module.
- No build scripts or deployment manifests—this is a script‐based library.

##### README for additional insights
- Core functions:
- compute_specific_heat_loss(...)
- heat_loss_scenarios(...)
- Data flows into Pandas DataFrames, optional plotting with Matplotlib/Seaborn.
- Emphasis on scenario generation (ROI ranking) and parameter reference.

a. Main components
1. User Interface (CLI or Notebook)
2. heat_loss_simulation.py module
– Input Parser
– Calculation Engine
∙ Roof heat loss
∙ Wall heat loss
∙ Window heat loss
∙ Ventilation (ACH) loss
– Scenario Generator
– Data Model (Pandas DataFrame)
– Output Formatter (tabular output, plot)
3. External Libraries (Pandas, Matplotlib/Seaborn)
4. (Optional) User’s script or notebook orchestrating calls
b. Relationships and interactions
- User invokes functions → Input Parser accepts parameters → Calculation Engine computes losses → Results aggregated in DataFrame → Output Formatter renders results (console/plot) → User interprets results.
- heat_loss_scenarios calls compute-specific internally in loop, aggregates scenarios.
- Pandas provides data structures; Matplotlib/Seaborn provides visualization interfaces.
c. Architectural patterns/design principles
- Modular single‐module design: separation of parsing, calculation, aggregation, and presentation.
- Functional decomposition: each physical loss type calculated by a dedicated routine.
- Data‐driven scenario generation: use of DataFrame to abstract scenario combinations.
- Extensibility point: new material types or loss mechanisms can be added to the calculation engine.
d. Key technologies, frameworks, libraries
- Python 3.6+
- Pandas for data structures and scenario tables
- Matplotlib or Seaborn for optional plotting
- Standard library modules (math, itertools, typing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing
    User["User Script / Notebook"]:::user
    README_doc["README Documentation"]:::user

    %% Core Module
    subgraph "heat_loss_simulation.py Module"
        CoreModule["heat_loss_simulation.py"]:::core
        Parser["Input Parser"]:::core
        CE["Calculation Engine"]:::core
        subgraph "Calculation Engine Details"
            Roof["Roof Heat Loss"]:::core
            Wall["Wall Heat Loss"]:::core
            Window["Window Heat Loss"]:::core
            Ventilation["Ventilation (ACH) Loss"]:::core
        end
        Scenario["Scenario Generator"]:::core
        DataModel["Data Model (Pandas DataFrame)"]:::core
        Formatter["Output Formatter (Tabular/Plot)"]:::core
    end

    %% External Dependencies
    subgraph "External Libraries"
        ExternalDeps["requirements.txt"]:::third
        Pandas["Pandas"]:::third
        Plotter["Plotter (Matplotlib/Seaborn)"]:::third
    end

    %% Data Flow
    User -->|"invoke functions"| Parser
    Parser -->|"parses params"| CE
    CE -->|"compute losses"| DataModel
    DataModel -->|"structure results"| Formatter
    Formatter -->|"output to user"| User

    Scenario -->|loops and aggregates| CE
    Scenario -->|writes scenarios| DataModel

    DataModel -->|"uses"| Pandas
    Formatter -->|"uses"| Plotter

    README_doc -->|"guides usage"| User

    %% Click Events
    click README_doc "https://github.com/wayne-turner/heat_loss/blob/main/README.md"
    click CoreModule "https://github.com/wayne-turner/heat_loss/blob/main/heat_loss_simulation.py"
    click ExternalDeps "https://github.com/wayne-turner/heat_loss/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#e0f7e9,stroke:#2d7,stroke-width:1px
    classDef core fill:#e8f1fb,stroke:#1f4,stroke-width:1px
    classDef third fill:#ffe5b5,stroke:#e67e22,stroke-width:1px
```
