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

Author: 1jhu1

lib/measures/door_enhancement/README.md

@@ -1,30 +1,86 @@
-# Door Enhancement Measure
-
-## Summary
-The Door Enhancement measure improves door-related performance in OpenStudio models by:
-- reducing infiltration in spaces containing doors,
-- optionally replacing doors and adding seals,
-- calculating embodied carbon from EC3 EPD data,
-- estimating costs through RSMeans or custom cost inputs.
-
-## Cost Modes
-- RSMeans mode (`use_custom_costs = False`): derives a door search term from model size/material context, runs multi-catalog lookup (`bc-mf`, `gb-mf`, `rp-mf`), applies 10% overhead/profit, and stores summary + hit details in AdditionalProperties.
-- Custom mode (`use_custom_costs = True`): bypasses RSMeans API and uses user-provided cost inputs directly.
-
-## RSMeans Fallback Behavior
-When direct RSMeans search has no match, the helper can use door-specific fallback unit cost line IDs for known materials (for example weatherstrips, automatic door bottom, and core steel door variants). The measure logs fallback warnings and fallback counts when this path is used.
-
-## Credentials
-- EC3: API token read from `config.ini` (`[EC3_API_TOKEN] API_TOKEN=...`) or environment.
-- RSMeans: `client_id` and `client_secret` environment variables (or `.env`).
-
-## Primary Files
-- `measure.py` - main measure logic
-- `resources/call_rsmeans_api.py` - RSMeans lookup client/helper
-- `resources/EC3_lookup.py` - EC3 data retrieval and processing
-- `apply_measure.py` - local integration harness
-
-## Additional Docs
-- `docs/USAGE_GUIDE.md` - user workflow and examples
-- `docs/QUICK_REFERENCE.md` - concise operational reference
-- `docs/TECHNICAL.md` - architecture, data flow, and algorithms
+# DoorEnhancement
+
+This measure improves door performance in OpenStudio models by adding sealing products (weatherstrip, automatic door bottom, silicone smoke gasket) and optionally replacing existing doors with more thermally efficient alternatives. It estimates added embodied carbon from EC3 EPD data and estimates installed cost using RSMeans (or user-provided custom cost inputs).
+
+## What It Does
+
+- Reduces space infiltration rates by a user-specified percentage to simulate improved air sealing from weatherstripping.
+- Fetches EC3 EPD data for the selected bottom seal, top/side seal, and door replacement materials; calculates life-cycle embodied carbon (kg CO₂ eq) over the analysis period.
+- When replacing doors, updates door construction R-values from material properties (thickness, conductivity, density).
+- Runs RSMeans lookup for door components (door unit, bottom seal, top/side seal) and stores full match/search diagnostics.
+- Writes standardized outputs into the five standard AdditionalProperties buckets.
+
+## Arguments
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `space_type` | Choice | *Entire Building* | Space type to apply infiltration reduction |
+| `space_infiltration_reduction_percent` | Double | 30.0 | Infiltration reduction (%) |
+| `alter_coef` | Boolean | false | Alter temperature/wind coefficients (disabled; always preserved) |
+| `door_area_per_unit` | Double | 1.95 | Door leaf area per unit (m²) per PCR declared unit |
+| `analysis_period` | Integer | 30 | Analysis period for embodied carbon (years) |
+| `door_bottom_seal_option` | Choice | automatic door bottom | Bottom seal product (none/brush weatherstrip/automatic door bottom/silicone adhesive smoke gasket) |
+| `door_top_side_seal_option` | Choice | jamb weatherstrip | Top and side seal product (none/silicone adhesive smoke gasket/jamb weatherstrip) |
+| `door_option` | Choice | wooden door | Door replacement type (none or any steel/glass/wood/garage option) |
+| `strip_lifetime` | Integer | 15 | Service life of sealing strip (years) |
+| `door_lifetime` | Integer | 30 | Service life of door (years) |
+| `gwp_statistic` | Choice | median | GWP statistic for EPD values (minimum/maximum/mean/median) |
+| `api_key` | String | — | EC3 API token |
+| `length_per_unit_bottom_side` | Double | 0.9144 | Length per unit of bottom seal (m); 0.0 = use product default |
+| `length_per_unit_other_sides` | Double | 5.1816 | Length per unit of top/side seal (m); 0.0 = use product default |
+| `door_thermal_conductivity` | Double | 0.0 | Door conductivity (W/m·K); 0.0 = use material default |
+| `door_density` | Double | 0.0 | Door density (kg/m³); 0.0 = use material default |
+| `door_thickness` | Double | 0.0 | Door thickness (m); 0.0 = use material default |
+| `use_custom_costs` | Boolean | false | Skip RSMeans; use custom cost inputs |
+| `custom_door_cost_per_unit` | Double | 0.0 | Custom door cost ($/m²) |
+| `custom_bottom_seal_cost` | Double | 0.0 | Custom bottom seal cost ($/m) |
+| `custom_top_side_seal_cost` | Double | 0.0 | Custom top/side seal cost ($/m) |
+| `rsmeans_unit_costline_id` | String | "" | Optional exact RSMeans unit cost line ID |
+
+## AdditionalProperties Bucket Map
+
+| OpenStudio Object | Variable | Contents |
+|---|---|---|
+| Building | `basic_input` | Measure name, analysis period, GWP statistic, construction names |
+| Site | `reno_detail` | Door/seal options, total door area, sealing lengths, door count |
+| Facility | `factors` | Cost totals, cost_source, cost_factor_basis, cost_unit_basis, GWP factors |
+| SimulationControl | `results` | Mirrored cost scalars + three RSMeans diagnostic JSON payloads |
+| SizingParameters | `mtrl_prop` | Door material properties, seal lengths, RSMeans-extracted hints |
+
+## Cost Source Modes
+
+- `rsmeans_api` — RSMeans search or exact-ID lookup succeeded.
+- `custom_input` — custom cost mode used.
+- `none` — costing disabled or unresolved.
+
+Cost basis is persisted as:
+- `door_enhancement_cost_factor_basis` (e.g. `cost_per_unit`, `cost_per_length`, `mixed`, `custom_cost_per_unit`)
+- `door_enhancement_cost_unit_basis` (e.g. `EA`, `LF`, `EA, LF`)
+
+## RSMeans Search Strategy
+
+When `use_custom_costs = False`, the measure builds search materials for:
+- The door (unit: `ea`, division `08`)
+- Bottom seal (unit: `lf`, division `08`)
+- Top/side seal (unit: `lf`, division `08`)
+
+These are searched across three catalogs (`bc-mf`, `gb-mf`, `rp-mf`). If no search result scores ≥ 50.0 (the minimum acceptable match score), the helper falls back to hard-coded costline IDs in `DOOR_FALLBACK_RSMEANS_IDS`. Full search diagnostics are stored in three JSON fields on `SimulationControl`.
+
+## Quick Start
+
+```powershell
+cd lib/measures/door_enhancement
+./setup_environment.ps1
+python apply_measure.py
+```
+
+Outputs are written to:
+- `tests/output/DOE_small_office_door_enhanced.osm`
+- `tests/output/apply_measure_results.json`
+
+## Documentation
+
+- [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md) — user workflow and examples
+- [docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md) — concise operational reference
+- [docs/TECHNICAL.md](docs/TECHNICAL.md) — architecture, data flow, and algorithms
+- [docs/CUSTOM_COSTS_IMPLEMENTATION.md](docs/CUSTOM_COSTS_IMPLEMENTATION.md) — custom cost mode details

lib/measures/door_enhancement/apply_measure.py

@@ -5,7 +5,9 @@
 1. Loads a test OSM file from the tests/ folder
 2. Runs the ModelMeasure with a set of configurable arguments
 3. Saves the modified model to tests/output/
-4. Verifies that AdditionalProperties were attached to modified door subsurfaces
+4. Verifies that AdditionalProperties were attached to the standard
+   5-bucket objects (Building, Site, Facility, SimulationControl,
+   SizingParameters)
 """
 
 from pathlib import Path
@@ -16,15 +18,37 @@
 # ---------------------------------------------------------------------------
 # OpenStudio path setup
 # ---------------------------------------------------------------------------
-OPENSTUDIO_VERSION = "3.11.0"
-openstudio_path = f"/Applications/OpenStudio-{OPENSTUDIO_VERSION}/Python"
 
-if Path(openstudio_path).exists():
-    sys.path.insert(0, openstudio_path)
-    print(f"Using OpenStudio from: {openstudio_path}")
-else:
-    print(f"Warning: OpenStudio path not found at {openstudio_path}")
-    print("Will attempt to use system OpenStudio installation")
+def configure_openstudio_python_path():
+    """Locate and add an OpenStudio Python directory to sys.path.
+
+    Checks (in order):
+    1. OPENSTUDIO_PYTHON_PATH environment variable.
+    2. Standard Windows install paths for versions 3.11, 3.10, 3.9.
+    3. Standard macOS install paths for the same versions.
+    4. Assumes the openstudio package is already importable (installed).
+    """
+    import os
+    explicit = os.environ.get("OPENSTUDIO_PYTHON_PATH", "").strip()
+    if explicit and Path(explicit).exists():
+        sys.path.insert(0, explicit)
+        print(f"Using OpenStudio from OPENSTUDIO_PYTHON_PATH: {explicit}")
+        return
+
+    candidates = []
+    for ver in ("3.11.0", "3.10.0", "3.9.0"):
+        candidates.append(Path(f"C:/openstudio-{ver}/Python"))
+        candidates.append(Path(f"/Applications/OpenStudio-{ver}/Python"))
+    for candidate in candidates:
+        if candidate.exists():
+            sys.path.insert(0, str(candidate))
+            print(f"Using OpenStudio from: {candidate}")
+            return
+
+    print("Using OpenStudio from installed package")
+
+
+configure_openstudio_python_path()
 
 import openstudio
 from measure import DoorEnhancement
@@ -175,20 +199,27 @@ def print_runner_output(runner):
 
 def verify_additional_properties(model):
     """
-    Check the new separate Facility AdditionalProperties (summary block).
-    Returns a list of (object_name, prop_name, value) tuples.
+    Check all five standard AdditionalProperties buckets and return a list of
+    (bucket_label, property_name, value) tuples.
     """
     found = []
-    facility = model.getFacility()
-    ap = facility.additionalProperties()
-    for feature_name in ap.featureNames():
-        val_opt = ap.getFeatureAsDouble(feature_name)
-        if val_opt.is_initialized():
-            found.append(("Facility", feature_name, val_opt.get()))
-        else:
-            val_str = ap.getFeatureAsString(feature_name)
-            if val_str.is_initialized():
-                found.append(("Facility", feature_name, val_str.get()))
+
+    def _collect_props(label, ap):
+        for feature_name in ap.featureNames():
+            val_opt = ap.getFeatureAsDouble(feature_name)
+            if val_opt.is_initialized():
+                found.append((label, feature_name, val_opt.get()))
+            else:
+                val_str = ap.getFeatureAsString(feature_name)
+                if val_str.is_initialized():
+                    found.append((label, feature_name, val_str.get()))
+
+    _collect_props("Building",         model.getBuilding().additionalProperties())
+    _collect_props("Site",             model.getSite().additionalProperties())
+    _collect_props("Facility",         model.getFacility().additionalProperties())
+    _collect_props("SimulationControl", model.getSimulationControl().additionalProperties())
+    _collect_props("SizingParameters", model.getSizingParameters().additionalProperties())
+
     return found
 
 
@@ -265,16 +296,27 @@ def _sv_value(sv):
 
     # Verify AdditionalProperties on Building
     print("\n" + "=" * 80)
-    print("VERIFYING SEPARATE FACILITY ADDITIONAL PROPERTIES")
+    print("VERIFYING SEPARATE ADDITIONAL PROPERTIES")
     print("=" * 80)
 
     ap_data = verify_additional_properties(model)
     if ap_data:
-        print(f"Found {len(ap_data)} properties in separate Facility AdditionalProperties:")
+        print(f"Found {len(ap_data)} properties in separate AdditionalProperties:")
         for obj_name, prop_name, value in ap_data:
             print(f"  [{obj_name}] {prop_name}: {value}")
     else:
-        print("  No properties found on Facility.")
+        print("  No properties found on standard buckets.")
+
+    # Gather cost_factor_basis and cost_unit_basis for summary
+    cost_factor_basis = next(
+        (v for lbl, k, v in ap_data if k == "door_enhancement_cost_factor_basis"), "not_found"
+    )
+    cost_unit_basis = next(
+        (v for lbl, k, v in ap_data if k == "door_enhancement_cost_unit_basis"), ""
+    )
+    cost_source = next(
+        (v for lbl, k, v in ap_data if k == "door_enhancement_cost_source"), "not_found"
+    )
 
     # Save modified model
     print("\n" + "=" * 80)
@@ -288,12 +330,15 @@ def _sv_value(sv):
     results = {
         "measure": "DoorEnhancement",
         "success": success,
+        "cost_source": cost_source,
+        "cost_factor_basis": cost_factor_basis,
+        "cost_unit_basis": cost_unit_basis,
         "step_values": step_values,
         "doors_in_model": len(doors),
         "additional_properties_count": len(ap_data),
         "additional_properties_sample": [
-            {"subsurface": s, "property": p, "value": v}
-            for s, p, v in ap_data[:10]
+            {"bucket": s, "property": p, "value": v}
+            for s, p, v in ap_data[:15]
         ]
     }
     with open(results_json_path, "w") as f: