documentation/enhancements.md

Enhancement Documentation

Window Shading Calculation Fix

Issue

The original calculator had an error when using certain window shading options, particularly the 'external_awning' option. This caused the following error:

ValueError: could not convert string to float: 'external_awning'
Traceback: File "/usr/local/lib/python3.10/site-packages/streamlit/runtime/scriptrunner/script_runner.py", line 542, in _run_script exec(code, module.__dict__) 
File "/home/user/app/app.py", line 160, in <module> main() 
File "/home/user/app/app.py", line 69, in main cooling_calculator() 
File "/home/user/app/pages/cooling_calculator.py", line 1785, in cooling_calculator ventilation_form(ref_data) 
File "/home/user/app/pages/cooling_calculator.py", line 1169, in ventilation_form calculate_cooling_load() 
File "/home/user/app/pages/cooling_calculator.py", line 1260, in calculate_cooling_load results = calculator.calculate_total_cooling_load( 
File "/home/user/app/cooling_load.py", line 246, in calculate_total_cooling_load shade_factor = 1.0 - float(shading_value)

Solution

The issue was in the calculate_total_cooling_load method of the CoolingLoadCalculator class. The code was attempting to convert the shading value string directly to a float, but shading values like 'external_awning' are string identifiers, not numeric values.

The fix involves properly retrieving the numeric factor value from the reference data instead of trying to convert the string identifier directly:

# Original problematic code
shading_value = window.get('shading', 0.0)
if shading_value == 'none' or shading_value == '':
    shading_value = 0.0
shade_factor = 1.0 - float(shading_value)  # This line caused the error

# Fixed code
shading_id = window.get('shading', 'none')
shade_factor = 1.0  # Default: no shading (full solar gain)
            
# Get shading factor from reference data
shading_data = self.ref_data.get_shading_factor(shading_id)
if shading_data and 'factor' in shading_data:
    # Use the factor value from the reference data
    # The factor represents how much solar gain is reduced (e.g., 0.4 means 40% reduction)
    shade_factor = 1.0 - shading_data['factor']

This fix ensures that the calculator properly handles all shading types, including 'external_awning', by looking up the appropriate shading factor in the reference data.

Scenario Comparison Functionality

Feature Description

The scenario comparison functionality allows users to:

1. Save calculation results as named scenarios with descriptions
2. View a list of saved scenarios
3. Select multiple scenarios to compare
4. Visualize differences between scenarios with charts and tables
5. Export comparison data as CSV

Implementation

This feature is implemented through several components:

1. ScenarioManager Class (utils/scenario_manager.py)

   • Handles saving, loading, and comparing scenarios
   • Generates visualization charts for comparisons
   • Provides Streamlit UI integration

2. Scenario Integration Module (utils/scenario_integration.py)

   • Integrates scenario functionality into the main application
   • Adds UI components to calculators for saving scenarios
   • Adds a dedicated scenario comparison page

3. Directory Structure

   • Creates a scenarios directory with subdirectories for cooling and heating scenarios
   • Stores scenarios as JSON files with timestamps

Usage

Users can save scenarios after completing calculations, then navigate to the Scenario Comparison page to select and compare multiple scenarios. The comparison shows total loads, load breakdowns, and percentage differences between scenarios.

Attribution and Purpose Information

Attribution information has been added to the application, crediting Dr. Majed Abuseif as the creator and explaining the tool's purpose:

This tool was created to facilitate HVAC calculation and understanding for Deakin University students, but has been enhanced to cover wider aspects to allow professionals and energy and HVAC enthusiasts to use it.

This information appears in the sidebar of the application and is also included in the README and documentation.

Testing

All enhancements have been thoroughly tested:

1. Window Shading Fix Tests

   • Tests for different shading types (none, internal blinds, external awning)
   • Verifies correct calculation of shade factors

2. Scenario Manager Tests

   • Tests for saving scenarios
   • Tests for loading scenarios
   • Tests for comparing multiple scenarios

All tests pass successfully, confirming that the enhancements work as expected.