openstudio-ee 0.12.3 → 0.12.5

data/lib/measures/window_enhancement/measure.xml

@@ -0,0 +1,271 @@
+<?xml version="1.0"?>
+<measure>
+  <schema_version>3.1</schema_version>
+  <name>window_enhancement</name>
+  <uid>0ad8e761-8624-4d9d-a7d6-ebf30cce243b</uid>
+  <version_id>6e806249-5eab-444e-b724-f00dd42c13fb</version_id>
+  <version_modified>2025-09-25T04:50:20Z</version_modified>
+  <xml_checksum>7DADF7C5</xml_checksum>
+  <class_name>WindowEnhancement</class_name>
+  <display_name>Window Enhancement</display_name>
+  <description>Make existing window better by adding film, storm window, or something else.</description>
+  <modeler_description>Using layered construction and not simple glazing to do this. We have to think about how to address simple glazing with this.</modeler_description>
+  <arguments>
+    <argument>
+      <name>analysis_period</name>
+      <display_name>Analysis Period</display_name>
+      <description>Analysis period of embodied carbon of building/building assembly</description>
+      <type>Integer</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>30</default_value>
+    </argument>
+    <argument>
+      <name>igu_option</name>
+      <display_name>IGU Option</display_name>
+      <description>Type of insulating glazing unit</description>
+      <type>Choice</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <choices>
+        <choice>
+          <value>electrochromic</value>
+          <display_name>electrochromic</display_name>
+        </choice>
+        <choice>
+          <value>fire_resistant</value>
+          <display_name>fire_resistant</display_name>
+        </choice>
+        <choice>
+          <value>laminated</value>
+          <display_name>laminated</display_name>
+        </choice>
+        <choice>
+          <value>low_emissivity</value>
+          <display_name>low_emissivity</display_name>
+        </choice>
+        <choice>
+          <value>tempered</value>
+          <display_name>tempered</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>igu_lifetime</name>
+      <display_name>IGU Lifetime</display_name>
+      <description>Lifetime of the insulating glazing unit</description>
+      <type>Integer</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>15</default_value>
+    </argument>
+    <argument>
+      <name>wf_lifetime</name>
+      <display_name>Product Lifetime of Window Frame</display_name>
+      <description>Life expectancy of window frame</description>
+      <type>Integer</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>15</default_value>
+    </argument>
+    <argument>
+      <name>wf_option</name>
+      <display_name>Window frame option</display_name>
+      <description>Type of aluminum extrusion</description>
+      <type>Choice</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <choices>
+        <choice>
+          <value>anodized</value>
+          <display_name>anodized</display_name>
+        </choice>
+        <choice>
+          <value>painted</value>
+          <display_name>painted</display_name>
+        </choice>
+        <choice>
+          <value>thermally_improved</value>
+          <display_name>thermally_improved</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>frame_cross_section_area</name>
+      <display_name>Frame Cross Section Area (m²)</display_name>
+      <description>Cross-sectional area of the IGU frame in square meters.</description>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0.0025</default_value>
+    </argument>
+    <argument>
+      <name>epd_type</name>
+      <display_name>EPD Type</display_name>
+      <description>Type of EPD for searching GWP values, Product EPDs refer to specific products from a manufacturer, while industrial EPDs represent average data across an entire industry sector.</description>
+      <type>Choice</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <choices>
+        <choice>
+          <value>Product</value>
+          <display_name>Product</display_name>
+        </choice>
+        <choice>
+          <value>Industry</value>
+          <display_name>Industry</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>gwp_statistic</name>
+      <display_name>GWP Statistic</display_name>
+      <description>Type of GWP statistic for searching GWP values, Product GWP statistics refer to specific products from a manufacturer, while industrial GWP statistics represent average data across an entire industry sector.</description>
+      <type>Choice</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <choices>
+        <choice>
+          <value>minimum</value>
+          <display_name>minimum</display_name>
+        </choice>
+        <choice>
+          <value>maximum</value>
+          <display_name>maximum</display_name>
+        </choice>
+        <choice>
+          <value>mean</value>
+          <display_name>mean</display_name>
+        </choice>
+        <choice>
+          <value>median</value>
+          <display_name>median</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>total_embodied_carbon</name>
+      <display_name>Total Embodied Carbon (kgCO2e)</display_name>
+      <description>Total embodied carbon of the window frame in kilograms of CO2 equivalent.</description>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0.0</default_value>
+    </argument>
+    <argument>
+      <name>total_embodied_carbon</name>
+      <display_name>Total Embodied Carbon (kgCO2e)</display_name>
+      <description>Total embodied carbon of the window frame in kilograms of CO2 equivalent.</description>
+      <type>Double</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+      <default_value>0.0</default_value>
+    </argument>
+    <argument>
+      <name>api_key</name>
+      <display_name>API Key</display_name>
+      <description>API key for accessing external services.</description>
+      <type>String</type>
+      <required>true</required>
+      <model_dependent>false</model_dependent>
+    </argument>
+  </arguments>
+  <outputs />
+  <provenances />
+  <tags>
+    <tag>Envelope.Fenestration</tag>
+  </tags>
+  <attributes>
+    <attribute>
+      <name>Measure Type</name>
+      <value>ModelMeasure</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Measure Language</name>
+      <value>Python</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Intended Software Tool</name>
+      <value>Apply Measure Now</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Intended Software Tool</name>
+      <value>OpenStudio Application</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Intended Software Tool</name>
+      <value>Parametric Analysis Tool</value>
+      <datatype>string</datatype>
+    </attribute>
+    <attribute>
+      <name>Intended Use Case</name>
+      <value>Retrofit EE</value>
+      <datatype>string</datatype>
+    </attribute>
+  </attributes>
+  <files>
+    <file>
+      <filename>LICENSE.md</filename>
+      <filetype>md</filetype>
+      <usage_type>license</usage_type>
+      <checksum>FFCBFF29</checksum>
+    </file>
+    <file>
+      <filename>README.md</filename>
+      <filetype>md</filetype>
+      <usage_type>readme</usage_type>
+      <checksum>DE9B0464</checksum>
+    </file>
+    <file>
+      <version>
+        <software_program>OpenStudio</software_program>
+        <identifier>3.8.0</identifier>
+        <min_compatible>3.8.0</min_compatible>
+      </version>
+      <filename>measure.py</filename>
+      <filetype>py</filetype>
+      <usage_type>script</usage_type>
+      <checksum>3D0A891D</checksum>
+    </file>
+    <file>
+      <filename>EC3_lookup.py</filename>
+      <filetype>py</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>2832F008</checksum>
+    </file>
+    <file>
+      <filename>Test_API.py</filename>
+      <filetype>py</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>26458C20</checksum>
+    </file>
+    <file>
+      <filename>calculate_perimeter.py</filename>
+      <filetype>py</filetype>
+      <usage_type>resource</usage_type>
+      <checksum>D7980CA8</checksum>
+    </file>
+    <file>
+      <filename>example_model.osm</filename>
+      <filetype>osm</filetype>
+      <usage_type>test</usage_type>
+      <checksum>E08CA027</checksum>
+    </file>
+    <file>
+      <filename>example_model_2.osm</filename>
+      <filetype>osm</filetype>
+      <usage_type>test</usage_type>
+      <checksum>E01ECAD1</checksum>
+    </file>
+    <file>
+      <filename>test_window_enhancement.py</filename>
+      <filetype>py</filetype>
+      <usage_type>test</usage_type>
+      <checksum>061487A7</checksum>
+    </file>
+  </files>
+</measure>

data/lib/measures/window_enhancement/resources/EC3_lookup.py

@@ -0,0 +1,321 @@
+# EC3 API Lookup Script
+import json
+import re
+from typing import Dict, Any, List
+from pathlib import Path
+import configparser
+from datetime import datetime
+import numpy as np
+import os
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+repo_root = os.path.abspath(os.path.join(script_dir, "../../../.."))
+config_path = os.path.join(repo_root, "config.ini")
+
+# this measure doesn't function without EC3 token and required Python libraries installed
+if not os.path.exists(config_path):
+    raise FileNotFoundError(f"Config file not found: {config_path}. Please setup your EC3 token before attempting to run this measure.")
+
+# load custom libraries after confirming if config.ini 
+import requests
+
+config = configparser.ConfigParser()
+config.read(config_path)
+API_TOKEN= config["EC3_API_TOKEN"]["API_TOKEN"]
+
+# #find material_name by category
+# material_category = {"concrete":{"ReadyMix","PrecastConcrete","CementGrout","FlowableFill"},
+#                      "masonry":{"Brick", "CMU"},
+#                      "steel":{"RebarSteel","WireMeshSteel","ColdFormedSteel","StructuralSteel"},
+#                      "aluminum":{"AluminiumExtrusions"},
+#                      "wood":{"PrefabricatedWood","DimensionLumbe","SheathingPanels","CompositeLumber","MassTimber","NonStructuralWood"},
+#                      "sheathing":{"GypsumSheathingBoard","CementitiousSheathingBoard"},
+#                      "thermal_moisture_protection":{"Insulation","MembraneRoofing"},
+#                      "cladding":{"RoofPanels","InsulatedRoofPanels","WallPanels","InsulatedWallPanels"},
+#                      "openings":{"glazing":["InsulatingGlazingUnits","FlatGlassPanes","ProcessedNonInsulatingGlassPanes"],
+#                                  "extrusions":["AluminiumExtrusions"]},
+#                      "finishes":{"CementBoard","Gypsum","Tiling","CeilingPanel","Flooring","PaintingAndCoating"}
+#                      }
+# for testing use, do not delete
+material_category = {
+                     "test":["InsulatingGlazingUnits"]
+                     }
+
+def generate_url(material_name, endpoint ="materials", page_number=1, page_size=250, jurisdiction="021", date=None, option=None, boolean="yes",
+                  glass_panes=None, epd_type="Product"):
+    '''
+    jurisdiction = "021" means Northern America region
+    '''
+    if date is None:
+        date = datetime.today().strftime("%Y-%m-%d")  # use today's date as default
+    url = (
+        f"https://api.buildingtransparency.org/api/{endpoint}"
+        f"?page_number={page_number}&page_size={page_size}"
+        f"&mf=!EC3%20search(%22{material_name}%22)%20WHERE%20"
+        f"%0A%20%20jurisdiction%3A%20IN(%22{jurisdiction}%22)%20AND%0A%20%20"
+        f"epd__date_validity_ends%3A%20%3E%20%22{date}%22%20AND%0A%20%20"
+        f"epd_types%3A%20IN(%22{epd_type}%20EPDs%22)%20"
+    )
+    conditions = []
+    if option and boolean:
+        conditions.append(f"{option}%3A%20{boolean}")
+
+    if glass_panes:
+        conditions.append(f"glass_panes%3A%20%3E~%20{glass_panes}")
+
+    if conditions:
+        url += "AND%0A%20%20" + "%20AND%0A%20%20".join(conditions) + "%20%0A"
+
+    url += "!pragma%20eMF(%222.0%2F1%22)%2C%20lcia(%22TRACI%202.1%22)"
+    
+    return url
+
+def fetch_epd_data(url,api_token):
+    """
+    input url address generted by generate_url()
+    Fetch EPD data from the EC3 API.
+    return: Parsed JSON response or empty list on failure.
+    """
+    try: 
+        print(f"Fetching data from URL: {url}")  # Log the URL being fetched
+        # API configuration
+        HEADERS = {"Accept": "application/json", "Authorization": "Bearer " + api_token}
+        response = requests.get(url, headers=HEADERS, verify=False)
+        response.raise_for_status() # HTTPError if failure 
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching data from {url}: {e}")
+        if 'response' in locals():  # Check if response was defined
+            print(f"Response content: {response.text}")
+        else:
+            print("No response content available.")
+        return []
+
+def parse_product_epd(epd: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Parse GWP data for a given EPD.
+    :param epd: EPD dictionary
+    :return: Parsed GWP data
+    """
+    # initialize parameters and dictionary
+    parsed_data = {}
+    gwp_per_m3 = 0.0
+    gwp_per_m2 = 0.0
+    gwp_per_kg = 0.0
+
+    # extract information from EPD's json repsonse
+    declared_unit = epd.get("declared_unit")
+    thickness = epd.get("thickness")
+    gwp_per_declared_unit = epd.get("gwp")
+    mass_per_declared_unit = epd.get("mass_per_declared_unit")
+    density = epd.get("density")
+    gwp_per_kg = epd.get("gwp_per_kg")
+    epd_name = epd.get('name')
+    description = epd.get('description')
+    original_ec3_link = epd['manufacturer']['original_ec3_link']
+
+    # Per mass
+    if gwp_per_kg != None:
+        gwp_per_kg = extract_numeric_value(gwp_per_kg)
+
+    elif gwp_per_kg == None and "t" in declared_unit:
+        gwp_per_kg = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_kg = gwp_per_kg/1000 # convert from t to kg
+
+    elif gwp_per_kg == None and "kg" in declared_unit:
+        gwp_per_kg = divide(gwp_per_declared_unit, declared_unit)
+
+    elif mass_per_declared_unit != None and gwp_per_kg == None and not any(unit in declared_unit for unit in ["kg", "t"]):
+        gwp_per_kg = divide(gwp_per_declared_unit, mass_per_declared_unit)
+
+    # Per volume
+    if "m3" in declared_unit:
+        gwp_per_m3 = divide(gwp_per_declared_unit, declared_unit)
+
+    elif "cf" in declared_unit:
+        gwp_per_m3 = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_m3 = gwp_per_m3 * 35.3147 # convert from cubic feet to m3
+
+    elif "m2" in declared_unit and thickness and "mm" in thickness:
+        gwp_per_m2 = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_m3 = gwp_per_m2/(extract_numeric_value(thickness)/1000)
+
+    elif density and "kg / m3" in density and gwp_per_kg:
+        gwp_per_m3 = multiply(gwp_per_kg, density)
+
+    # Per area
+    if "m2" in declared_unit:
+        gwp_per_m2 = divide(gwp_per_declared_unit, declared_unit)
+
+    elif "sf" in declared_unit:
+        gwp_per_m2 = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_m2 = gwp_per_m2 * 10.7639 # convert from square feet to m2
+
+    elif "m3" in declared_unit and thickness and "mm" in thickness:
+        gwp_per_m3 = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_m2 = gwp_per_m3 * (extract_numeric_value(thickness)/1000)
+    
+    parsed_data["epd_name"] = epd_name
+    parsed_data["declared_unit"] = declared_unit
+    parsed_data["gwp_per_declared_unit"] = gwp_per_declared_unit
+    parsed_data["mass_per_declared_unit"] = mass_per_declared_unit
+    parsed_data["thickness"] = thickness
+    parsed_data["density"] = density
+    parsed_data["gwp_per_m3 (kg CO2 eq/m3)"] = gwp_per_m3
+    parsed_data["gwp_per_m2 (kg CO2 eq/m2)"] = gwp_per_m2
+    parsed_data["gwp_per_kg (kg CO2 eq/kg)"] = gwp_per_kg 
+    parsed_data["original_ec3_link"] = original_ec3_link
+    parsed_data["description"] = description
+
+    return parsed_data
+
+def parse_industrial_epd(epd: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Parse GWP data for a given EPD.
+    :param epd: EPD dictionary
+    :return: Parsed GWP data
+    """
+
+    parsed_data = {}
+    gwp_per_m3 = 0.0
+    gwp_per_m2 = 0.0
+    gwp_per_kg = 0.0
+
+    declared_unit = epd.get("declared_unit")
+    gwp_per_kg = epd.get("gwp_per_kg")
+    gwp_per_declared_unit = epd.get("gwp")
+    epd_name = epd.get('name')
+    original_ec3_link = epd.get('original_ec3_link')
+    description = epd.get('description')
+    density_min = epd.get('density_min')
+    density_max = epd.get('density_max')
+    area = epd.get('area')
+
+    if density_min is not None and density_max is not None:
+        density_avg = (extract_numeric_value(density_max) + extract_numeric_value(density_min))/2
+    elif density_min is not None:
+        density_avg = extract_numeric_value(density_min)
+    elif density_max is not None:
+        density_avg = extract_numeric_value(density_max)
+    else:
+        density_avg = None
+
+    # Per area (stop using this becasue the area value is not sensible)
+    # if "m^2" in area:
+    #     gwp_per_m2 = extract_numeric_value(gwp_per_declared_unit)/extract_numeric_value(area)
+
+    # Per mass
+    if "t" in declared_unit:
+        gwp_per_kg = divide(gwp_per_declared_unit, declared_unit)
+        gwp_per_kg = gwp_per_kg / 1000 # convert to kg
+    elif "kg" in declared_unit:
+        gwp_per_kg = divide(gwp_per_declared_unit, declared_unit)
+
+    # Per volume
+    if gwp_per_kg != None and density_avg != None:
+        gwp_per_m3 = gwp_per_kg * density_avg
+        
+    parsed_data["epd_name"] = epd_name
+    parsed_data["declared_unit"] = declared_unit
+    parsed_data["gwp_per_declared_unit"] = gwp_per_declared_unit
+    parsed_data["density_min"] = density_min
+    parsed_data["density_max"] = density_max
+    parsed_data["area"] = area
+    parsed_data["gwp_per_m3 (kg CO2 eq/m3)"] = gwp_per_m3
+    parsed_data["gwp_per_m2 (kg CO2 eq/m2)"] = gwp_per_m2
+    parsed_data["gwp_per_kg (kg CO2 eq/kg)"] = gwp_per_kg 
+    parsed_data["original_ec3_link"] = original_ec3_link
+    parsed_data["description"] = description
+
+    return parsed_data
+
+def extract_numeric_value(value: Any) -> float:
+    """
+    Extract numeric value from a string or number.
+    :param value: Value to process
+    :return: Extracted numeric value
+    """
+    match = re.search(r"[-+]?\d*\.?\d+", str(value))
+    return float(match.group()) if match else 0.0
+
+# extract numeric values then divide
+def divide(member: Any, denominator: Any) -> float:
+    try:
+        member_value = extract_numeric_value(member)
+        denominator_value = extract_numeric_value(denominator)
+        return round(member_value/denominator_value, 2)
+    except ZeroDivisionError:
+        return 0.0
+
+# extract numeric values then multiply
+def multiply(multiplicand: Any, multiplier: Any) -> float:
+
+    multiplicand_value = extract_numeric_value(multiplicand)
+    multiplier_value = extract_numeric_value(multiplier)
+    return round(multiplicand_value * multiplier_value, 2)
+
+def calculate_geometry(self, sub_surface):
+    """
+    Calculate the length, width, perimeter, and area of the window from its vertices.
+    Assumes the window is a quadrilateral (typically a rectangle).
+    """
+    vertices = sub_surface.vertices()
+    if len(vertices) != 4:
+        return {
+            "length": 0.0,
+            "width": 0.0,
+            "perimeter": 0.0,
+            "area": 0.0
+        }
+
+    # Calculate all edge lengths
+    edge_lengths = []
+    perimeter = 0.0
+    for i in range(4):
+        v1 = vertices[i]
+        v2 = vertices[(i + 1) % 4]
+        edge = v2 - v1
+        length = edge.length()
+        edge_lengths.append(length)
+        perimeter += length
+
+    # Assume opposite edges are equal, so we can group into two unique lengths
+    length = max(edge_lengths)
+    width = min(edge_lengths)
+
+    # Area = length × width
+    area = length * width
+
+    return {
+        "length": length,
+        "width": width,
+        "perimeter": perimeter,
+        "area": area
+    }
+
+def main():
+    """
+    Main function to execute the script.
+    """
+    print("Fetching EC3 EPD data...")
+
+    for category, list in material_category.items():
+        print(material_category[category])
+        for name in list:
+            print(name)
+            product_url = generate_url(name, endpoint="materials", epd_type="Product")
+            industry_url = generate_url(name, endpoint="industry_epds", epd_type="Industry")
+
+            product_epd_data = fetch_epd_data(product_url,API_TOKEN) 
+            industrial_epd_data = fetch_epd_data(industry_url,API_TOKEN)
+            print(f"Number of  product EPDs for {name}: {len(product_epd_data)}")
+            print(f"Number of  industrial EPDs for {name}: {len(industrial_epd_data)}")
+            for idx, epd in enumerate(product_epd_data, start=1):
+                parsed_data = parse_product_epd(epd)
+                print(f"Product EPD #{idx}: {json.dumps(parsed_data, indent=4)}")
+            for idx, epd in enumerate(industrial_epd_data, start=1):
+                parsed_data = parse_industrial_epd(epd)
+                print(f"Industrial EPD #{idx}: {json.dumps(parsed_data, indent=4)}")
+
+if __name__ == "__main__":
+    main()

data/lib/measures/window_enhancement/resources/Test_API.py

@@ -0,0 +1,32 @@
+# Test EC3 API Call
+import requests
+import pprint
+import os
+import configparser
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+repo_root = os.path.abspath(os.path.join(script_dir, "../../../.."))
+config_path = os.path.join(repo_root, "config.ini")
+
+if not os.path.exists(config_path):
+    raise FileNotFoundError(f"Config file not found: {config_path}")
+
+config = configparser.ConfigParser()
+config.read(config_path)
+API_TOKEN= config["EC3_API_TOKEN"]["API_TOKEN"]
+
+test_url = ("https://api.buildingtransparency.org/api/materials?page_number=1&page_size=25&mf=!EC3%20search(%22InsulatingGlazingUnits%22)%20WHERE%20%0A%20%20jurisdiction%3A%20IN(%22021%22)%20AND%0A%20%20epd__date_validity_ends%3A%20%3E%20%222025-04-18%22%20AND%0A%20%20epd_types%3A%20IN(%22Product%20EPDs%22)%20%0A!pragma%20eMF(%222.0%2F1%22)%2C%20lcia(%22TRACI%202.1%22)")
+# Headers for the request
+headers = {
+    "Accept": "application/json",
+    "Authorization": "Bearer "+ API_TOKEN
+}
+
+# Execute the GET request
+test_response = requests.get(test_url, headers=headers, verify=False)
+
+# Parse the JSON response
+test_response = test_response.json()
+pprint.pp(test_response)
+# Print the response and the number of EPDs
+print(f"Number of EPDs: {len(test_response)}")