docs/technical_documentation.md

HVAC Calculator Technical Documentation

System Architecture

The HVAC Calculator is built using a modular architecture with the following components:

1. User Interface Layer: Streamlit-based web interface
2. Application Layer: Core calculation and processing logic
3. Data Layer: Data models, reference data, and persistence

Component Diagram

+----------------------------------+
|           User Interface         |
|  +----------------------------+  |
|  |     Streamlit Web App      |  |
|  +----------------------------+  |
+----------------------------------+
                |
                v
+----------------------------------+
|         Application Layer        |
|  +------------+  +------------+  |
|  | Calculation |  |    Data    |  |
|  |   Engine    |  | Processing |  |
|  +------------+  +------------+  |
|  +------------+  +------------+  |
|  |Visualization|  |    Data    |  |
|  |  Components |  | Validation |  |
|  +------------+  +------------+  |
+----------------------------------+
                |
                v
+----------------------------------+
|            Data Layer            |
|  +------------+  +------------+  |
|  |   Models   |  | Reference  |  |
|  |            |  |    Data    |  |
|  +------------+  +------------+  |
|  +------------+  +------------+  |
|  |  Climate   |  |    Data    |  |
|  |    Data    |  | Persistence|  |
|  +------------+  +------------+  |
+----------------------------------+

Technology Stack

• Frontend: Streamlit (Python-based web framework)
• Backend: Python 3.10+
• Data Processing: Pandas, NumPy
• Visualization: Plotly, Matplotlib
• Data Export: OpenPyXL, XlsxWriter
• Testing: Python unittest framework

Module Descriptions

App Module

The app module contains the Streamlit application components:

• main.py: Main application entry point and navigation
• building_info_form.py: Building information input form
• component_selection.py: Component selection interface
• results_display.py: Results display module
• data_validation.py: Data validation module
• data_persistence.py: Data persistence module
• data_export.py: Data export module

Data Module

The data module contains data models and reference data:

• building_components.py: Building component data models
• reference_data.py: Reference data for materials and construction types
• climate_data.py: ASHRAE 169 climate data module
• ashrae_tables.py: ASHRAE tables implementation (CLTD, SCL, CLF)

Utils Module

The utils module contains utility functions and calculation engines:

• component_library.py: Component library with preset and custom components
• u_value_calculator.py: U-value calculator for material assemblies
• shading_system.py: Shading system for windows
• area_calculation_system.py: Area calculation and validation system
• psychrometrics.py: Psychrometric calculations for air properties
• heat_transfer.py: Shared heat transfer calculation functions
• cooling_load.py: Cooling load calculations (CLTD/CLF method)
• heating_load.py: Heating load calculations (steady-state method)
• component_visualization.py: Hierarchical component visualization
• scenario_comparison.py: Scenario comparison visualization
• psychrometric_visualization.py: Psychrometric visualization
• time_based_visualization.py: Time-based visualization

Tests Module

The tests module contains test cases:

• test_calculator.py: Comprehensive tests for calculator components

Data Flow

1. User Input: User enters building information, climate data, and component details
2. Data Validation: Input data is validated for completeness and correctness
3. Calculation: Cooling and heating loads are calculated using ASHRAE methods
4. Visualization: Results are visualized using various charts and tables
5. Export: Results can be exported in various formats (CSV, Excel, JSON)

Calculation Methods

Cooling Load Calculation

The cooling load calculation uses the CLTD/CLF method from ASHRAE:

1. Walls and Roofs: Uses Cooling Load Temperature Difference (CLTD) method

   • Q = U × A × CLTD
   • CLTD values are adjusted for latitude, month, and time of day

2. Windows: Uses Solar Cooling Load (SCL) method

   • Q = U × A × CLTD + A × SC × SCL
   • SCL values are adjusted for latitude, month, and time of day

3. Internal Gains: Uses Cooling Load Factor (CLF) method

   • Q = q × CLF
   • CLF values are adjusted for zone type and hours of operation

4. Infiltration and Ventilation: Uses sensible and latent heat equations

   • Q_sensible = ρ × Q × cp × ΔT
   • Q_latent = ρ × Q × hfg × Δw

Heating Load Calculation

The heating load calculation uses the steady-state method:

1. Building Envelope: Uses steady-state conduction

   • Q = U × A × ΔT
   • ΔT is the difference between indoor and outdoor design temperatures

2. Infiltration and Ventilation: Uses sensible heat equation

   • Q = ρ × Q × cp × ΔT

3. Internal Gains: Considered as heat sources that offset heating load

   • Q_heating = Q_envelope - Q_internal

Data Models

Building Component Models

All building components inherit from a base Component class:

class Component:
    id: str
    name: str
    component_type: ComponentType
    u_value: float
    area: float

Specific component types extend this base class:

• Wall: Adds orientation, wall_type, and wall_group
• Roof: Adds orientation, roof_type, and roof_group
• Floor: Adds floor_type
• Window: Adds orientation, shgc, vt, window_type, glazing_layers, gas_fill, and low_e_coating
• Door: Adds orientation and door_type

Climate Data Model

The climate data model includes:

• Climate zones
• Design conditions (summer and winter)
• Monthly temperature data
• Solar radiation data

Reference Data

Reference data includes:

• Wall types and properties
• Roof types and properties
• Floor types and properties
• Window types and properties
• Door types and properties
• Material properties (conductivity, density, specific heat)

Persistence and Export

Data Persistence

• Projects are saved in JSON format with a .hvac extension
• All component data is properly serialized, including enums and complex objects
• Project history is maintained in the session state for quick access to previous work

Data Export

• CSV export provides individual tables for different components and results
• Excel export creates a comprehensive report with multiple sheets
• JSON scenario export preserves all calculation results and input data
• Batch export creates a ZIP file containing all scenarios

Deployment

Local Deployment

To run the application locally:

1. Install the required dependencies:

pip install streamlit pandas numpy plotly matplotlib openpyxl xlsxwriter

2. Run the Streamlit application:

cd hvac_calculator
streamlit run app/main.py

Hugging Face Space Deployment

To deploy to Hugging Face Space:

1. Create a new Space on Hugging Face
2. Select Streamlit as the Space SDK
3. Upload the application files
4. Configure the requirements.txt file
5. Set the app file to app/main.py

Performance Considerations

• The application is designed to run efficiently in a web browser
• Calculation methods are optimized for speed and accuracy
• Large datasets (e.g., ASHRAE tables) are loaded only when needed
• Visualizations use efficient rendering techniques

Security Considerations

• All data processing is done client-side
• No sensitive data is transmitted to external servers
• Project files are stored locally on the user's computer
• No authentication is required for basic usage

Future Enhancements

• Additional calculation methods (e.g., Heat Balance Method)
• Support for more complex building geometries
• Integration with BIM software
• Enhanced 3D visualization
• Cloud-based project storage
• Collaborative editing features

Conclusion

This technical documentation provides an overview of the HVAC Calculator's architecture, components, and implementation details. For more information, please refer to the code documentation and user guide.