city_retrofit/RetrofitFactory_Documentation.txt

RetrofitFactory Documentation

Overview
RetrofitFactory is a tool designed to apply energy efficiency retrofits to buildings within a city model. It supports multiple retrofit types, including construction improvements, infiltration reduction, and window upgrades.

Usage

Basic Implementation
```python
from hub.imports.retrofit_factory import RetrofitFactory

# Load retrofit data from JSON file
with open('retrofit_scenarios.json', 'r') as f:
    retrofit_data = json.load(f)

# Apply retrofits to a city
retrofit_factory = RetrofitFactory(retrofit_data, city)
retrofit_factory.enrich()
```

Retrofit Data Structure
The retrofit data is stored as a JSON object where building IDs serve as keys and retrofit specifications as values:
```json
{
    "building_id": {
        "retrofit_types": ["construction", "infiltration", "windows"],
        "wall_u_value": 0.3,
        "roof_u_value": 0.2,
        "ground_u_value": 0.25,
        "infiltration_reduction": 30,
        "window_u_value": 1.5,
        "window_g_value": 0.6
    }
}
```

Supported Retrofit Types
RetrofitFactory supports the following types of retrofits:

1. Construction Retrofits
Modifies U-values for walls, roofs, and ground surfaces, but only if the new U-value is lower than the existing one. The retrofit improves thermal resistance of building materials.

Parameters:
- wall_u_value: Target U-value for walls (W/m²K)
- roof_u_value: Target U-value for roofs (W/m²K)
- ground_u_value: Target U-value for ground surfaces (W/m²K)

2. Infiltration Retrofits
Reduces air infiltration rate as a percentage, applied to the ventilation system when off.

Parameters:
- infiltration_reduction: Percentage reduction in infiltration rate (0-100)

3. Window Retrofits
Updates window thermal properties by modifying the U-value and solar heat gain coefficient (g-value).

Parameters:
- window_u_value: Target U-value for windows (W/m²K)
- window_g_value: Target solar heat gain coefficient (0-1)

Implementation Details

Class Structure
```python
class RetrofitFactory:
    def __init__(self, retrofit_data: dict, city: City):
        self._retrofit_data = retrofit_data
        self._city = city
```

Main Methods

1. enrich()
Applies retrofits to all buildings in the city. It iterates over each building, retrieves its corresponding retrofit data, and applies the specified retrofits.

```python
def enrich(self):
    for building in self._city.buildings:
        building_id = str(building.name)
        if building_id in self._retrofit_data:
            building_retrofit_data = self._retrofit_data[building_id]
            retrofit_types = building_retrofit_data.get('retrofit_types', [])
            self._apply_retrofits_to_building(building, retrofit_types, building_retrofit_data)
```

2. _apply_retrofits_to_building()
Handles applying the specified retrofits to an individual building based on its retrofit data.

3. _apply_construction_retrofit_to_building()
Applies construction retrofits by modifying U-values for walls, roofs, and ground surfaces. Only updates if the new U-value is lower than the existing value.

```python
def _apply_construction_retrofit_to_building(self, building: Building, retrofit_params):
    wall_u_value = retrofit_params.get('wall_u_value')
    roof_u_value = retrofit_params.get('roof_u_value')
    ground_u_value = retrofit_params.get('ground_u_value')
```

Thermal resistance is calculated as:
ΔR = (1 / U_new) - (1 / U_old)

```python
def _change_thermal_resistance(self, thermal_boundary, new_u_value):
    old_u_value = thermal_boundary.u_value
    if new_u_value < old_u_value:
        delta_r = (1 / new_u_value) - (1 / old_u_value)
```

4. _reduce_infiltration_rate_by_percentage()
Reduces the infiltration rate by the specified percentage.

```python
def _reduce_infiltration_rate_by_percentage(self, building: Building, retrofit_params):
    percentage = retrofit_params.get('infiltration_reduction')
    if percentage is not None:
        new_rate = old_rate * (1 - percentage / 100)
```

5. _apply_window_retrofit_to_building()
Updates the overall U-value and g-value of windows.

```python
def _apply_window_retrofit_to_building(self, building: Building, retrofit_params):
    overall_u_value = retrofit_params.get('window_u_value')
    g_value = retrofit_params.get('window_g_value')
```

Error Handling
RetrofitFactory includes various error prevention mechanisms:
- Building ID Validation: Logs missing retrofit data for buildings not found in the input.
- U-value Validation: Only applies if the new U-value is lower than the old one.
- Null Checks: Ensures that parameters like infiltration_reduction are not null.
- Type Validation: Checks for required attributes, such as thermal boundaries and openings.

Data Validation

1. Building ID Validation
```python
building_id = str(building.name)
if building_id in self._retrofit_data:
    # Process building
else:
    print(f"No retrofit data for building ID {building_id}")
```

2. U-value and Window Value Validation
```python
if new_u_value < old_u_value:
    # Apply change
else:
    print(f"New U-value {new_u_value} is not less than old U-value {old_u_value}")

if overall_u_value is not None and overall_u_value != 0:
    # Apply change
```

Building Model Integration
RetrofitFactory relies on the city model to access thermal zones, boundaries, and construction properties of buildings. For example:
- Thermal Zone Access:
```python
for thermal_zone in building.thermal_zones_from_internal_zones:
    thermal_archetype = thermal_zone.parent_internal_zone.thermal_archetype
```

- Construction Properties Access:
```python
construction_archetype = thermal_boundary._construction_archetype
construction_archetype.window_overall_u_value = overall_u_value
construction_archetype.window_g_value = g_value
```

Logging and Debugging
RetrofitFactory includes detailed logging for tracking the progress and results of retrofits:
- Logs retrofit application: print(f"Applying retrofits to building ID {building_id}")
- Logs property updates: print(f"Updated wall U-value to {wall_u_value} in building {building.name}")
- Logs missing data: print(f"No retrofit data for building ID {building_id}")

Performance Considerations
- Memory Efficiency: Directly modifies existing objects instead of creating new copies.
- Computational Efficiency: Only processes buildings with available retrofit data and skips unnecessary thermal boundaries.

Integration Requirements
To function correctly, the city model must provide:
- Unique building names convertible to strings.
- Buildings with thermal zones and boundaries that contain layers for construction retrofits.
- Access to thermal zone properties and boundary layers.