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:

```python
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.