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