From 8f332baad6d78c16d333ca5045f9f203d6e08ca3 Mon Sep 17 00:00:00 2001 From: majidrezaei93 Date: Tue, 19 Nov 2024 11:25:01 -0500 Subject: [PATCH] feat: add README.md file --- README.md | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..8a0bd1f9 --- /dev/null +++ b/README.md @@ -0,0 +1,169 @@ +## 1. Creating the City Model from a GeoJSON File + +Start by using the `GeometryFactory` class to create a city model from a GeoJSON file. This class reads building geometries and attributes from the file and constructs a city model. + +```python +city = GeometryFactory( + "geojson", + input_file, + height_field="height", + year_of_construction_field="contr_year", + function_field="function_c", + adjacency_field="adjacency", + function_to_hub=Dictionaries().montreal_function_to_hub_function +).city +``` + +- `"geojson"`: Specifies the format of the input file. +- `input_file`: The path to your GeoJSON file. +- `height_field="height"`: The attribute in the GeoJSON file that contains the building height. +- `year_of_construction_field="contr_year"`: The attribute for the building's year of construction. +- `function_field="function_c"`: The attribute for the building's function or usage. +- `adjacency_field="adjacency"`: The attribute indicating whether the building is attached or detached. +- `function_to_hub`: A dictionary that maps the building functions to standardized functions used by HUB. + +The `city` object now contains all the buildings from the GeoJSON file with their associated attributes. + +--- + +## 2. Enriching the City with Construction Details + +Use the `ConstructionFactory` to enrich the city model with construction details and calculation of the thermal zones and total floor area. + +```python +ConstructionFactory('nrcan', city).enrich() +``` + +- `'nrcan'`: Specifies the source of construction data, in this case, NRCan. +- `city`: The city model created in the previous step. +--- +## 3. Assigning Energy Demands Using Archetypes + +Finally, we assign energy demands to each building using the `ResultFactory` class and an archetype-based demand model. This basically maps buildings to predefined archetypes and assigning corresponding energy demand profiles. + +```python +ResultFactory('archetypes', city, demand_file).enrich() +``` +- `'archetypes'`: Specifies the handler we are using which in this case is archetype-based demand model. +- `city`: The city. +- `demand_file`: The path to the CSV file containing the archetype demand profiles. +--- + +## 4. Rules for Finding Archetypes and Assigning Demands + +This mapping is based on the following building attributes: + +- **Function** +- **Height** +- **Adjacency**: Whether the building is attached or is detached. +- **Year of Construction** + +### **Mapping Rules**: + +Based on the building's function, height, and adjacency: + +- **Residential Buildings** ('residential', 'multifamily house', 'single family house'): + - **Single Family House**: + - Height less than 6 meters. + - Adjacency: 'detached'. + - `usage = 'Single Family'`. + - **Row House**: + - Height less than 6 meters. + - Adjacency: 'attached'. + - `usage = 'Row house'`. + - **Duplex/Triplex**: + - Height between 6 and 10 meters. + - Adjacency: 'detached'. + - `usage = 'Duplex/triplex'`. + - **Small MURBs** (Multi-Unit Residential Buildings): + - Height between 6 and 10 meters. + - Adjacency: 'attached'. + - `usage = 'Small MURBs'`. + - **Medium MURBs**: + - Height between 10 and 15 meters. + - `usage = 'Medium MURBs'`. + - **Large MURBs**: + - Height greater than 15 meters. + - `usage = 'Large MURBs'`. + +- **Office Buildings** ('office', 'office and administration'): + - `usage = 'Office'`. + +- **Commercial Buildings** ('commercial', 'retail shop without refrigerated food', 'retail shop with refrigerated food', 'stand alone retail', 'strip mall'): + - If adjacency is 'attached': + - `usage = 'Commercial attached'`. + - Else: + - `usage = 'Commercial detached'`. + +#### Determine Building Vintage (`vintage`): + +Based on the building's year of construction: + +- **Pre-1947**: + - `year <= 1947`. + - `vintage = 'Pre 1947'`. +- **1947-1983**: + - `1947 < year <= 1983`. + - `vintage = '1947-1983'`. +- **1984-2010**: + - `1983 < year <= 2010`. + - `vintage = '1984-2010'`. +- **Post-2010**: + - `year > 2010`. + - `vintage = 'Post 2010'`. + +Combine usage and vintage to create the key: + +```python +archetype_key = f"{usage} {vintage}" +``` + +This key is used to look up the corresponding demand profiles in the archetype demand file. + +--- + +### Assigning Demands: + +1. **Lookup Demand Profiles**: + + Using the `archetype_key`, retrieve the hourly demand profiles from the `demand_file`. Each archetype has associated hourly demands for different energy uses. + +2. **Scale Demands by Floor Area**: + + Multiply the demand values by the building's total floor area. + +3. **Assign Demands to Building**: + + Set the building's demand attributes: + + ```python + building.heating_demand = [value * area for value in demand['Heating']] + building.cooling_demand = [value * area for value in demand['Cooling']] + building.domestic_hot_water_heat_demand = [value * area for value in demand['DHW']] + building.appliances_electrical_demand = [value * area for value in demand['Equipment']] + building.lighting_electrical_demand = [value * area for value in demand['Lighting']] + ``` + +--- + +### Example: + +For a residential building with the following attributes: +- **Function**: 'residential' +- **Height**: 9 meters +- **Adjacency**: 'attached' +- **Year of Construction**: 1986 + +#### **Mapping Steps**: + +1. **Usage**: + - Height is between 6 and 10 meters. + - Adjacency is 'attached'. + - Therefore, `usage = 'Small MURBs'`. + +2. **Vintage**: + - Year is 1986, which falls in 1984-2010. + - Therefore, `vintage = '1984-2010'`. + +3. **Archetype Key**: + - `archetype_key = 'Small MURBs 1984-2010'`. \ No newline at end of file