| # 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. | |