| """ | |
| 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 | |