docs/developer_guide.md

""" Developer documentation for the Enhanced HVAC Load Calculator. This document provides technical details for developers who want to extend or modify the calculator. """

Enhanced HVAC Load Calculator - Developer Guide

Table of Contents

1. Architecture Overview
2. Directory Structure
3. Module Descriptions
4. Data Models
5. Calculation Methods
6. UI Components
7. Testing
8. Extension Points
9. Best Practices

1. Architecture Overview

The Enhanced HVAC Load Calculator follows a Model-View-Controller (MVC) architecture:

• Models: Data structures for building components and calculation results
• Views: UI components for user interaction and visualization
• Controllers: Business logic and calculation methods

The application uses Streamlit for the web interface, which provides reactive components that update automatically when the underlying data changes.

Key Components

• Building data models
• ASHRAE tables and reference data
• Cooling load calculation engine
• Monthly breakdown calculator
• Visualization components
• Data import/export utilities
• Building management system

Data Flow

1. User inputs building information through the UI
2. Data is stored in Building model instances
3. Calculation controllers process the data using ASHRAE methods
4. Results are stored in CoolingLoadResult instances
5. View components display the results with visualizations
6. Data can be exported to various formats or imported from files

2. Directory Structure

hvac_improved/
├── app/
│   └── main.py                 # Main application entry point
├── models/
│   └── building.py             # Building data models
├── controllers/
│   ├── cooling_load_calculator.py      # Cooling load calculation
│   ├── enhanced_cooling_load_calculator.py  # Enhanced calculation methods
│   ├── monthly_breakdown.py    # Monthly breakdown calculation
│   └── building_manager.py     # Multiple building management
├── views/
│   ├── building_info_form.py   # Building information input
│   ├── internal_loads_form.py  # Internal loads configuration
│   ├── enhanced_results_display.py  # Results visualization
│   └── building_comparison.py  # Building comparison visualization
├── utils/
│   ├── data_io.py              # Data import/export utilities
│   ├── psychrometrics.py       # Psychrometric calculations
│   └── ashrae_integration.py   # ASHRAE tables integration
├── data/
│   ├── ashrae_tables.py        # ASHRAE tables and reference data
│   └── weather_data.py         # Weather data for different locations
├── tests/
│   ├── test_calculator.py      # Unit tests
│   ├── test_integration.py     # Integration tests
│   └── debug.py                # Debug script
└── docs/
    ├── user_guide.md           # User documentation
    └── developer_guide.md      # Developer documentation

3. Module Descriptions

app/main.py

The main application entry point that integrates all components and provides the Streamlit interface. It handles navigation, session state management, and component integration.

models/building.py

Contains data classes for building components, including:

• Building settings
• Location
• Walls, roof, and glass
• People, lighting, and equipment
• Cooling load results

controllers/cooling_load_calculator.py

Implements the core cooling load calculation methods based on ASHRAE procedures. It calculates external loads (walls, roof, glass) and internal loads (people, lighting, equipment).

controllers/enhanced_cooling_load_calculator.py

Extends the core calculator with improved methods, correction factors, and more accurate calculations. It integrates with ASHRAE tables for precise results.

controllers/monthly_breakdown.py

Calculates monthly cooling loads and energy consumption based on weather data and building characteristics. It provides detailed monthly reports and energy efficiency recommendations.

controllers/building_manager.py

Manages multiple buildings, including adding, updating, removing, renaming, and duplicating buildings. It also handles building comparison and calculation management.

views/building_info_form.py

Provides UI components for entering building information, including settings, location, walls, roof, and glass. It validates input and updates the building model.

views/internal_loads_form.py

Provides UI components for configuring internal loads, including people, lighting, and equipment. It supports different activity levels, lighting types, and equipment types.

views/enhanced_results_display.py

Displays calculation results with interactive visualizations, including pie charts, stacked bars, treemaps, and detailed breakdowns. It also shows monthly and hourly profiles.

views/building_comparison.py

Provides visualization components for comparing multiple buildings, including overview, peak loads, monthly comparison, and energy consumption.

utils/data_io.py

Implements data import/export utilities for various formats, including JSON, CSV, PDF, and ZIP. It handles serialization and deserialization of building models and results.

utils/psychrometrics.py

Implements psychrometric calculations for air properties, including humidity ratio, wet bulb temperature, dew point, and enthalpy. It supports cooling coil load calculations.

utils/ashrae_integration.py

Provides integration with ASHRAE tables and methods, including correction factors, adjustment methods, and lookup functions.

data/ashrae_tables.py

Contains ASHRAE tables and reference data extracted from the PDF files, including CLTD, CLF, and other factors. It provides structured access to the tables.

data/weather_data.py

Provides weather data for different locations, including design conditions, monthly averages, and hourly profiles. It supports cooling degree day calculations.

4. Data Models

Building

The main data model that represents a building with all its components. It includes:

• Settings (name, floor area, ceiling height, indoor conditions)
• Location (city, latitude, longitude)
• Walls (list of Wall objects with orientation, area, U-value, construction type)
• Roof (area, U-value, construction type)
• Glass (list of Glass objects with orientation, area, U-value, SHGC, shading)
• People (count, activity level)
• Lighting (power, type)
• Equipment (power, type)

CoolingLoadResult

Represents the result of a cooling load calculation. It includes:

• Building name
• Peak sensible load
• Peak latent load
• Peak total load
• Peak hour
• External loads (roof, walls, glass conduction, glass solar)
• Internal loads (people, lighting, equipment)
• Hourly loads (24-hour profile)

5. Calculation Methods

Cooling Load Calculation

The cooling load calculation follows ASHRAE procedures:

1. Calculate external loads:

   • Roof load = Area × U-value × CLTD (corrected)
   • Wall load = Area × U-value × CLTD (corrected)
   • Glass conduction load = Area × U-value × CLTD (corrected)
   • Glass solar load = Area × SHGC × SC × CLF

2. Calculate internal loads:

   • People sensible load = Count × Sensible heat gain × CLF
   • People latent load = Count × Latent heat gain
   • Lighting load = Power × Usage factor × CLF × Heat emission factor
   • Equipment sensible load = Power × Usage factor × Sensible heat factor
   • Equipment latent load = Power × Usage factor × Latent heat factor

3. Calculate total loads:

   • Sensible load = Sum of all sensible components
   • Latent load = Sum of all latent components
   • Total load = Sensible load + Latent load

Monthly Breakdown Calculation

The monthly breakdown calculation:

1. Uses monthly weather data for each location
2. Calculates cooling degree days for each month
3. Estimates monthly energy consumption based on peak load and usage patterns
4. Provides monthly peak and average loads

6. UI Components

Building Information Form

• Text inputs for building settings
• Location selector with city database
• Wall editor with add/edit/remove functionality
• Roof properties editor
• Glass editor with add/edit/remove functionality

Internal Loads Form

• People count input and activity level selector
• Lighting power input and type selector
• Equipment power input and type selector
• Information displays for heat gain factors

Results Display

• Summary cards for peak loads
• Interactive charts with Plotly
• Tabbed interface for different visualization types
• Detailed breakdown tables
• Monthly and hourly profile charts
• Energy efficiency recommendations

Building Manager

• Building list with key metrics
• Building action buttons
• Building comparison visualizations
• Multiple chart types for different comparison aspects

Import/Export

• Export options for different formats
• Import options with file upload
• Progress indicators for long operations

7. Testing

Unit Tests

Unit tests verify individual components:

• Building model creation and serialization
• Cooling load calculation accuracy
• Monthly breakdown calculation
• Data import/export functionality

Integration Tests

Integration tests verify end-to-end workflows:

• Building manager operations
• Complete calculation process
• Data persistence and retrieval
• Building comparison functionality

Debug Script

The debug script automates testing and issue resolution:

1. Runs all tests
2. Identifies failures
3. Attempts to fix common issues
4. Verifies fixes with additional test runs

8. Extension Points

Adding New Building Components

To add new building components:

1. Extend the Building model in models/building.py
2. Update the building information form in views/building_info_form.py
3. Add calculation methods in controllers/enhanced_cooling_load_calculator.py
4. Update the results display in views/enhanced_results_display.py

Adding New Calculation Methods

To add new calculation methods:

1. Create new functions in controllers/enhanced_cooling_load_calculator.py
2. Update the CoolingLoadResult model if needed
3. Add visualization components in views/enhanced_results_display.py

Adding New Visualization Types

To add new visualization types:

1. Create new visualization functions in views/enhanced_results_display.py
2. Add new tabs or sections to the results display
3. Update the building comparison visualization if needed

Adding New Import/Export Formats

To add new import/export formats:

1. Add new functions in utils/data_io.py
2. Update the import/export UI components
3. Add appropriate file handling and error checking

9. Best Practices

Code Organization

• Follow the MVC pattern
• Keep related functionality in the same module
• Use descriptive names for functions and variables
• Add docstrings to all functions and classes

Performance Optimization

• Cache expensive calculations
• Use vectorized operations with NumPy when possible
• Optimize database queries and data processing
• Use Streamlit's caching mechanisms

UI Design

• Keep the interface clean and intuitive
• Provide informative tooltips and help text
• Use consistent styling and layout
• Ensure responsive design for different screen sizes

Testing

• Write tests for all new functionality
• Run tests regularly during development
• Use test-driven development when appropriate
• Maintain high test coverage

Documentation

• Keep documentation up to date
• Document all public APIs
• Include examples and use cases
• Provide both user and developer documentation