Merge branch 'roof-insulation-rsmeans' of https://github.com/NatLabRockies/openstudio-ee-gem into replace-windows-EC

Author: 1jhu1

lib/measures/IncreaseInsulationRValueForRoofs/README.md

@@ -1,64 +1,73 @@
 
+# IncreaseInsulationRValueForRoofs
 
-###### (Automatically generated documentation)
+This measure upgrades roof insulation to a target R-value, estimates added embodied carbon from EC3 EPD data, and estimates added installed cost using RSMeans (or user-provided custom cost inputs).
 
-# Increase R-value of Insulation for Roofs to a Specific Value
-
-## Description
-
-
-## Modeler Description
-
-
-## Measure Type
-ModelMeasure
-
-## Taxonomy
+## What It Does
 
+- Identifies roof constructions and computes the insulation delta required to hit the target R-value.
+- Applies insulation updates on cloned constructions, leaving the original unchanged.
+- Aggregates added insulation quantities and embodied carbon (GWP) from EC3 EPDs.
+- Runs RSMeans lookup for retrofit materials and stores full match/search diagnostics.
+- Writes standardized outputs into model-level AdditionalProperties buckets.
 
 ## Arguments
 
-
-### Insulation R-value (ft^2*h*R/Btu).
-
-**Name:** r_value,
-**Type:** Double,
-**Units:** ,
-**Required:** true,
-**Model Dependent:** false
-
-### Allow both increase and decrease in R-value to reach requested target?
-
-**Name:** allow_reduction,
-**Type:** Boolean,
-**Units:** ,
-**Required:** true,
-**Model Dependent:** false
-
-### Increase in Material and Installation Costs for Construction per Area Used ($/ft^2).
-
-**Name:** material_cost_increase_ip,
-**Type:** Double,
-**Units:** ,
-**Required:** true,
-**Model Dependent:** false
-
-### One Time Retrofit Cost to Add Insulation to Construction ($/ft^2).
-
-**Name:** one_time_retrofit_cost_ip,
-**Type:** Double,
-**Units:** ,
-**Required:** true,
-**Model Dependent:** false
-
-### Year to Incur One Time Retrofit Cost (whole years).
-
-**Name:** years_until_retrofit_cost,
-**Type:** Integer,
-**Units:** ,
-**Required:** true,
-**Model Dependent:** false
-
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `r_value` | Double | 30.0 | Target R-value (ft²·h·°F/Btu) |
+| `analysis_period` | Integer | 30 | Analysis period for embodied carbon (years) |
+| `gwp_statistic` | Choice | median | Statistic for EPD GWP values (min/max/mean/median) |
+| `api_key` | String | — | EC3 API token |
+| `insulation_material_type` | Choice | Fiberglass Batts | Material for EPD lookup and RSMeans search |
+| `insulation_material_lifetime` | Integer | 30 | Fallback lifetime if EPD has none (years) |
+| `insulation_thermal_conductivity` | Double | 0.0 | 0 = use typical value for selected material (W/m·K) |
+| `insulation_material_density` | Double | 0.0 | 0 = use typical or EPD-derived value (kg/m³) |
+| `calculate_costs` | Boolean | true | Enable cost calculation (RSMeans or custom) |
+| `use_custom_costs` | Boolean | false | Skip RSMeans; use custom cost inputs instead |
+| `use_exact_costline_id` | Boolean | false | Force RSMeans to use the exact `exact_costline_id` |
+| `exact_costline_id` | String | "" | Exact RSMeans unit costline ID |
+| `custom_cost_per_cf` | Double | 0.0 | Custom insulation cost per cubic foot ($/CF) |
+| `labor_cost_multiplier` | Double | 1.0 | Multiplier on custom material cost to derive labor cost |
+| `overhead_profit_percent` | Double | 10.0 | Overhead + profit applied on top of RSMeans cost (%) |
+
+## AdditionalProperties Bucket Map
+
+| OpenStudio Object | Variable | Contents |
+|---|---|---|
+| Building | `basic_input` | Measure name, analysis period, GWP statistic, construction names |
+| Site | `reno_detail` | Target R-value, material type, total renovated area |
+| Facility | `factors` | Mirrored cost totals, cost source, cost basis metadata, GWP factors |
+| SimulationControl | `results` | All cost fields + RSMeans diagnostics JSON payloads |
+| SizingParameters | `mtrl_prop` | Material density, conductivity, lifetime, RSMeans extracted hints |
+
+## Cost Source Modes
+
+- `rsmeans_api` — RSMeans closest-match or exact-ID lookup succeeded.
+- `custom_input` — custom volume-based cost mode used.
+- `none` — costing disabled or unresolved.
+
+Cost basis is persisted as:
+- `roof_insulation_cost_factor_basis` (e.g. `cost_per_volume`, `cost_per_area`, `custom_cost_per_volume`)
+- `roof_insulation_cost_unit_basis` (e.g. `CF`, `SF`)
+
+## Quick Start
+
+```powershell
+cd lib/measures/IncreaseInsulationRValueForRoofs
+./setup_environment.ps1
+python apply_measure.py
+```
+
+Outputs are written to:
+- `tests/output/DOE_small_office_roof_insulation_upgraded.osm`
+- `tests/output/apply_measure_results.json`
+
+## Documentation
+
+- [docs/Increase_Insulation_Roofs.md](docs/Increase_Insulation_Roofs.md) — full measure guide
+- [docs/RSMEANS_SEARCH_STRATEGY.md](docs/RSMEANS_SEARCH_STRATEGY.md) — RSMeans search and scoring details
+- [docs/ENVIRONMENT_SETUP.md](docs/ENVIRONMENT_SETUP.md) — environment setup and troubleshooting
 
 
 

lib/measures/IncreaseInsulationRValueForRoofs/apply_measure.py

@@ -14,35 +14,39 @@
 import json
 import os
 import configparser
-import platform
 
 # ---------------------------------------------------------------------------
 # OpenStudio path setup
 # ---------------------------------------------------------------------------
-# Try to use installed openstudio package first (via pip/conda)
-# Fall back to system installations if needed
+def configure_openstudio_python_path():
+    """Add OpenStudio Python bindings directory to sys.path when needed."""
+    env_path = os.getenv("OPENSTUDIO_PYTHON_PATH")
+    candidates = []
+    if env_path:
+        candidates.append(Path(env_path))
+
+    candidates.extend([
+        Path(r"C:\openstudio-3.11.0\Python"),
+        Path(r"C:\openstudio-3.10.0\Python"),
+        Path(r"C:\openstudio-3.9.0\Python"),
+        Path("/Applications/OpenStudio-3.11.0/Python"),
+        Path("/Applications/OpenStudio-3.10.0/Python"),
+        Path("/Applications/OpenStudio-3.9.0/Python"),
+    ])
+
+    for candidate in candidates:
+        if candidate.exists() and str(candidate) not in sys.path:
+            sys.path.insert(0, str(candidate))
+            os.environ["OPENSTUDIO_PYTHON_PATH"] = str(candidate)
+            print(f"Using OpenStudio Python path: {candidate}")
+            return
+
+
 try:
     import openstudio
     print("Using OpenStudio from installed package")
 except ImportError:
-    OPENSTUDIO_VERSION = "3.9.0"
-    WINDOWS_OPENSTUDIO_PATH = rf"C:\openstudio-{OPENSTUDIO_VERSION}\Python"
-    mac_openstudio_path = f"/Applications/OpenStudio-{OPENSTUDIO_VERSION}/Python"
-
-    openstudio_path = None
-    if platform.system() == "Windows":
-        if Path(WINDOWS_OPENSTUDIO_PATH).exists():
-            openstudio_path = WINDOWS_OPENSTUDIO_PATH
-            sys.path.insert(0, openstudio_path)
-            print(f"Using OpenStudio from: {openstudio_path}")
-    else:
-        if Path(mac_openstudio_path).exists():
-            openstudio_path = mac_openstudio_path
-            sys.path.insert(0, openstudio_path)
-            print(f"Using OpenStudio from: {openstudio_path}")
-
-    if openstudio_path is None:
-        print("Warning: OpenStudio path not found")
+    configure_openstudio_python_path()
 
 import openstudio
 from measure import IncreaseInsulationRValueForRoofs
@@ -210,6 +214,8 @@ def build_cost_response(ap_data):
 
     cost_response = {
         "cost_source": props.get("roof_insulation_cost_source"),
+        "cost_factor_basis": props.get("roof_insulation_cost_factor_basis"),
+        "cost_unit_basis": props.get("roof_insulation_cost_unit_basis"),
         "selection_mode": props.get("roof_insulation_rsmeans_selection_mode"),
         "material_cost": {
             "value": props.get(

lib/measures/IncreaseInsulationRValueForRoofs/docs/ENVIRONMENT_SETUP.md

@@ -1,60 +1,78 @@
-# Environment Setup for Increase Insulation R-Value for Roofs
+# Environment Setup for IncreaseInsulationRValueForRoofs
 
 ## Overview
 
-This measure requires Python 3.8+ and OpenStudio 3.11.0. Use the repository's environment.yml to keep dependencies consistent.
+The roof insulation measure depends on:
 
-## Prerequisites
+- A Python environment where this repository runs.
+- OpenStudio Python bindings.
+- `python-dotenv` (used by RSMeans helper credential loading).
 
-- Conda (Anaconda or Miniconda)
-- Git with the openstudio-ee-gem repository cloned
+## Fastest Setup (PowerShell)
 
-## Quick Setup
+From the measure directory:
 
-### 1. Create the Environment
+```powershell
+cd lib/measures/IncreaseInsulationRValueForRoofs
+./setup_environment.ps1
+```
+
+What this script does:
+
+- Detects `OPENSTUDIO_PYTHON_PATH` or common local OpenStudio Python install paths.
+- Installs/updates `python-dotenv` in the active Python environment.
+- Runs a quick import validation for `openstudio` and `dotenv`.
+
+## Manual Setup
 
-From the repository root:
+1. Create and activate environment from repository root:
 
-```bash
+```powershell
 conda env create -f environment.yml
+conda activate openstudio312
 ```
 
-### 2. Activate the Environment
+2. Ensure OpenStudio bindings are reachable:
 
-```bash
-conda activate openstudio-3.11
+- Preferred: set `OPENSTUDIO_PYTHON_PATH` to your OpenStudio `Python` folder.
+- Or ensure `openstudio` is importable directly in your environment.
+
+3. Install required package:
+
+```powershell
+python -m pip install python-dotenv
 ```
 
-### 3. Verify Installation
+4. Validate imports:
 
-```bash
-python -c "import openstudio; print(openstudio.openStudioVersion())"
+```powershell
+python -c "import openstudio, dotenv; print(openstudio.openStudioVersion())"
 ```
 
 ## Running the Measure
 
-```bash
+```powershell
 cd lib/measures/IncreaseInsulationRValueForRoofs
 python apply_measure.py
 ```
 
 ## Troubleshooting
 
-### "ModuleNotFoundError: No module named 'openstudio'"
+### `ModuleNotFoundError: No module named 'openstudio'`
 
-Ensure the environment is activated and has the openstudio package:
+- Set `OPENSTUDIO_PYTHON_PATH` to the OpenStudio `Python` directory.
+- Re-run `setup_environment.ps1` in the same shell session.
 
-```bash
-conda activate openstudio-3.11
-python -c "import openstudio; print(openstudio.openStudioVersion())"
-```
+### `ModuleNotFoundError: No module named 'dotenv'`
 
-### DLL or Version Errors
+- Run `python -m pip install python-dotenv` in the active environment.
 
-Use the conda environment from environment.yml and avoid mixing system Python with OpenStudio packages.
+### Mixed Python installations
 
-## Additional Resources
+- Confirm interpreter path with:
+
+```powershell
+python -c "import sys; print(sys.executable)"
+```
 
-- [Conda Environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)
-- [Measure Documentation](Increase_Insulation_Roofs.md)
-- [RSMeans Search Strategy](RSMEANS_SEARCH_STRATEGY.md)
+- Ensure that is the same interpreter you used for package install.