docs/user_guide.md

""" User documentation for the Enhanced HVAC Load Calculator. This document provides detailed instructions for using the calculator. """

Enhanced HVAC Load Calculator - User Guide

Table of Contents

1. Introduction
2. Getting Started
3. Building Information
4. Internal Loads
5. Calculation Results
6. Building Manager
7. Import/Export
8. Troubleshooting
9. Glossary

1. Introduction

The Enhanced HVAC Load Calculator is a comprehensive tool for calculating cooling loads in buildings based on ASHRAE methods. This calculator helps HVAC engineers, architects, and building designers determine the appropriate cooling system size for a building by calculating the peak cooling load and monthly energy consumption.

Key Features

• Accurate cooling load calculations based on ASHRAE methods
• Support for different activity levels, lighting types, and equipment types
• Monthly breakdown of cooling loads and energy consumption
• Interactive visualizations with multiple chart options
• Multiple building comparison capabilities
• Data import/export in various formats

2. Getting Started

Navigation

The application has five main pages, accessible from the sidebar:

• Building Information: Enter building properties and components
• Internal Loads: Configure people, lighting, and equipment loads
• Results: View calculation results with interactive visualizations
• Building Manager: Manage multiple buildings and compare them
• Import/Export: Save and load building data and results

Creating a New Building

1. Click "Create New Building" in the sidebar
2. Navigate to the "Building Information" page
3. Enter building details and components

Loading an Existing Building

1. Click "Load Selected Building" in the sidebar
2. Select a building from the dropdown menu
3. The building will be loaded and ready for viewing or editing

3. Building Information

The Building Information page allows you to enter the basic properties of your building and its components.

Building Settings

• Name: Enter a descriptive name for the building
• Floor Area: Enter the total floor area in square meters
• Ceiling Height: Enter the ceiling height in meters
• Indoor Temperature: Set the indoor design temperature in °C
• Indoor Humidity: Set the indoor design relative humidity in %

Location

• City: Select the city where the building is located
• Latitude/Longitude: These will be automatically filled based on the city, but can be adjusted if needed

Walls

Add walls for each orientation (North, South, East, West):

1. Click "Add Wall"
2. Enter the width and height in meters
3. Set the U-value (thermal transmittance) in W/m²·K
4. Select the construction type (Light, Medium, Heavy)
5. Click "Save Wall"

Roof

• Area: Enter the roof area in square meters
• U-value: Set the U-value in W/m²·K
• Construction Type: Select the roof construction type

Glass

Add glass (windows) for each orientation:

1. Click "Add Glass"
2. Enter the width and height in meters
3. Set the U-value in W/m²·K
4. Set the SHGC (Solar Heat Gain Coefficient)
5. Select the shading type
6. Click "Save Glass"

4. Internal Loads

The Internal Loads page allows you to configure the internal heat sources in the building.

People

• Count: Enter the number of occupants
• Activity Level: Select the activity level from the dropdown menu
  • Different activity levels have different heat gain values
  • The heat gain per person will be displayed based on the selected activity

Lighting

• Power: Enter the total lighting power in watts
• Lighting Type: Select the lighting type from the dropdown menu
  • Different lighting types have different heat emission factors
  • The heat emission factor will be displayed based on the selected type

Equipment

• Power: Enter the total equipment power in watts
• Equipment Type: Select the equipment type from the dropdown menu
  • Different equipment types have different sensible and latent heat factors
  • The heat factors will be displayed based on the selected type

5. Calculation Results

The Results page displays the cooling load calculation results with interactive visualizations.

Calculating Cooling Load

1. Navigate to the Results page
2. Click "Calculate Cooling Load"
3. The calculation will run and display the results

Peak Cooling Load

The peak cooling load section shows:

• Sensible Load (W)
• Latent Load (W)
• Total Load (W)
• Peak Hour
• Sensible Heat Ratio (SHR)

Load Breakdown

The load breakdown section provides multiple visualization options:

• Pie Charts: Shows the distribution of external and internal loads
• Stacked Bar: Displays the composition of cooling load components
• Treemap: Provides a hierarchical view of all load components
• Detailed Breakdown: Shows detailed tables of all load components

Monthly Breakdown

The monthly breakdown section shows:

• Monthly peak cooling loads
• Monthly average cooling loads
• Monthly energy consumption
• Correlation with outdoor temperature

Hourly Load Profile

The hourly load profile shows the cooling load variation throughout the day for the peak month.

Energy Efficiency Recommendations

Based on the calculation results, the system provides recommendations for improving energy efficiency.

6. Building Manager

The Building Manager page allows you to manage multiple buildings and compare them.

Building List

The building list shows all saved buildings with key metrics:

• Building name
• Location
• Floor area
• Peak cooling load
• Annual energy consumption

Building Actions

• Rename Building: Change the name of a building
• Remove Building: Delete a building from the manager
• Duplicate Building: Create a copy of a building with a new name
• Calculate Building: Calculate cooling load for a building
• Compare Buildings: Compare multiple buildings side by side

Building Comparison

The building comparison page provides multiple visualization options:

• Overview: Shows key metrics for all buildings
• Peak Loads: Compares peak cooling loads and their components
• Monthly Comparison: Shows monthly cooling load patterns
• Energy Consumption: Compares annual and monthly energy consumption
• Detailed Comparison: Provides a detailed side-by-side comparison of building properties

7. Import/Export

The Import/Export page allows you to save and load building data and results.

Export Options

• Building Data: Export building data to JSON format
• Results: Export calculation results to JSON format
• Monthly Data: Export monthly breakdown data to CSV format
• Complete Project: Export all data as a ZIP archive

Import Options

• Building Data: Import building data from JSON file
• Complete Project: Import a complete project from ZIP archive

8. Troubleshooting

Common Issues

• Calculation errors: Ensure all required fields are filled correctly
• Missing results: Make sure you have calculated the cooling load before viewing results
• Import errors: Check that the file format is correct and contains valid data

Getting Help

If you encounter any issues, please:

1. Check the documentation for guidance
2. Run the debug script to identify and fix issues:

   python tests/debug.py
   

3. Contact support with details of the problem

9. Glossary

• ASHRAE: American Society of Heating, Refrigerating and Air-Conditioning Engineers
• CLTD: Cooling Load Temperature Difference
• CLF: Cooling Load Factor
• SHGC: Solar Heat Gain Coefficient
• U-value: Thermal transmittance (W/m²·K)
• SHR: Sensible Heat Ratio
• CDD: Cooling Degree Days