Merge pull request #34 from NatLabRockies/optimize

AI-assisted measure authoring + CooledBeam terminals + zone equipment priority

Author: brianlball

.claude/skills/measure-authoring/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: measure-authoring
+description: Create, test, and apply custom OpenStudio measures. Use when user asks to "write a measure", "create a custom measure", "modify the model with Ruby/Python code", or needs logic beyond what existing tools provide.
+disable-model-invocation: true
+---
+
+# Measure Authoring
+
+Create custom OpenStudio ModelMeasures with user-provided logic, test them, and apply them to models.
+
+## When to Use
+
+Use measure authoring when:
+- No existing MCP tool does what the user needs
+- User explicitly asks for a "custom measure" or "Ruby/Python measure"
+- Complex model modifications requiring iteration over many objects
+- User wants reusable, repeatable model transformations
+
+Do NOT use when an existing tool already does the job (e.g., `replace_air_terminals` for terminal swaps, `adjust_thermostat_setpoints` for thermostat changes).
+
+## Workflow
+
+### 1. Create the Measure
+```
+create_measure(
+    name="set_lights_8w",
+    description="Set all lights to 8 W/m2",
+    language="Ruby",
+    run_body="    model.getLightsDefinitions.each { |ld| ld.setWattsperSpaceFloorArea(8.0) }\n    runner.registerFinalCondition('Done')"
+)
+```
+
+### 2. Test It
+```
+test_measure(measure_dir="/runs/custom_measures/set_lights_8w")
+```
+
+### 3. Apply to Model
+```
+apply_measure(measure_dir="/runs/custom_measures/set_lights_8w")
+```
+
+### 4. Verify Results (Before/After Comparison)
+For rigorous validation, run a baseline simulation BEFORE applying the measure:
+```
+save_osm_model(save_path="/runs/baseline.osm")
+run_simulation(osm_path="/runs/baseline.osm", epw_path="<epw>")
+extract_summary_metrics(run_id=<baseline_id>)   # record baseline EUI
+
+# reload, apply measure, re-simulate
+load_osm_model(osm_path="<original>")
+apply_measure(measure_dir="/runs/custom_measures/set_lights_8w")
+save_osm_model(save_path="/runs/retrofit.osm")
+run_simulation(osm_path="/runs/retrofit.osm", epw_path="<epw>")
+extract_summary_metrics(run_id=<retrofit_id>)   # compare to baseline
+```
+
+## Language Choice
+
+- **Ruby**: Preferred for most measures. Matches OpenStudio SDK documentation and existing measure libraries.
+- **Python**: Works but less common. Use when user prefers Python.
+
+## Common run_body Patterns (Ruby)
+
+### Envelope
+```ruby
+    model.getLightsDefinitions.each { |ld| ld.setWattsperSpaceFloorArea(8.0) }
+    model.getSpaceInfiltrationDesignFlowRates.each { |inf| inf.setFlowperExteriorSurfaceArea(0.0003) }
+    model.getSurfaces.each { |s| next unless s.outsideBoundaryCondition == 'Outdoors'; ... }
+```
+
+### HVAC
+```ruby
+    model.getAirLoopHVACs.each do |loop|
+      loop.thermalZones.each do |zone|
+        loop.removeBranchForZone(zone)
+        # create new terminal...
+        loop.addBranchForZone(zone, terminal.to_StraightComponent.get)
+      end
+    end
+```
+
+### Zone Equipment
+```ruby
+    model.getThermalZones.each do |zone|
+      bb = OpenStudio::Model::ZoneHVACBaseboardConvectiveElectric.new(model)
+      bb.setName("#{zone.name} Baseboard")
+      bb.addToThermalZone(zone)
+    end
+```
+
+### Air Terminals (beams)
+```ruby
+    # CooledBeam (2-pipe, cooling only)
+    coil = OpenStudio::Model::CoilCoolingCooledBeam.new(model)
+    terminal = OpenStudio::Model::AirTerminalSingleDuctConstantVolumeCooledBeam.new(model, sch, coil)
+
+    # FourPipeBeam (4-pipe, heating + cooling)
+    cc = OpenStudio::Model::CoilCoolingFourPipeBeam.new(model)
+    hc = OpenStudio::Model::CoilHeatingFourPipeBeam.new(model)
+    terminal = OpenStudio::Model::AirTerminalSingleDuctConstantVolumeFourPipeBeam.new(model, cc, hc)
+```
+
+WARNING: Beams are AIR TERMINALS (connect via `air_loop.addBranchForZone`), NOT zone equipment (`addToThermalZone`).
+
+## Notes
+
+- `run_body` indentation matters: Ruby = 4 spaces, Python = 8 spaces
+- Always call `runner.registerFinalCondition("msg")` at end of run body
+- `create_measure` is idempotent (overwrites existing measure with same name)
+- Use `edit_measure` to modify an existing measure without recreating from scratch
+- Use `list_custom_measures` to see all created measures

.claude/skills/retrofit/SKILL.md

@@ -75,3 +75,4 @@ Present side-by-side comparison:
 - Always save to a new path before re-simulating to preserve the baseline
 - Multiple ECMs can be stacked before re-simulating
 - Some measures modify the model in-memory (thermostat, window); others run as OpenStudio measures
+- For custom ECMs not covered by existing tools, use `create_measure` to write a custom measure (see `measure-authoring` skill)

.claude/skills/tool-workflows/SKILL.md

@@ -93,6 +93,33 @@ apply_measure(measure_dir="/inputs/measures/my_measure",
 
 Note: All measure arguments are strings. Booleans → `"true"` / `"false"`. Numbers → `"42"`.
 
+## Write and Apply a Custom Measure
+
+Full chain: create → test → apply → simulate → compare results.
+
+```
+# 1. Baseline simulation
+save_osm_model(save_path="/runs/baseline.osm")
+run_simulation(osm_path="/runs/baseline.osm", epw_path="<epw>")
+extract_summary_metrics(run_id=<baseline_id>)
+
+# 2. Create custom measure
+create_measure(name="my_measure", description="...",
+    language="Ruby", run_body="    model.get...each { |x| ... }")
+test_measure(measure_dir="/runs/custom_measures/my_measure")
+
+# 3. Reload original model, apply measure, re-simulate
+load_osm_model(osm_path="<original>")
+apply_measure(measure_dir="/runs/custom_measures/my_measure")
+save_osm_model(save_path="/runs/retrofit.osm")
+run_simulation(osm_path="/runs/retrofit.osm", epw_path="<epw>")
+extract_summary_metrics(run_id=<retrofit_id>)
+
+# 4. Compare baseline vs retrofit EUI
+```
+
+See the `measure-authoring` skill for run_body patterns and language guidance.
+
 ## Object Cleanup
 
 ```

.github/workflows/ci.yml

@@ -61,23 +61,23 @@ jobs:
           mkdir -p runs
           case ${{ matrix.shard }} in
             1)
-              # sim test + component/weather + loop ops + skill_simulate + skill_retrofit
-              FILES="tests/test_example_workflows.py tests/test_component_properties.py tests/test_comstock.py tests/test_weather.py tests/test_mcp_seb4.py tests/test_create_constructions.py tests/test_loop_operations.py tests/test_plant_loop_demand.py tests/test_sizing_properties.py tests/test_skill_simulate.py tests/test_skill_retrofit.py tests/test_integration.py"
+              # sim test + component/weather + loop ops + skill_retrofit
+              FILES="tests/test_example_workflows.py tests/test_component_properties.py tests/test_comstock.py tests/test_weather.py tests/test_mcp_seb4.py tests/test_create_constructions.py tests/test_loop_operations.py tests/test_plant_loop_demand.py tests/test_sizing_properties.py tests/test_skill_retrofit.py tests/test_integration.py"
               EXTRA_ENV="-e MCP_OSW_PATH=tests/assets/SEB_model/SEB4_baseboard/workflow.osw -e EXPECTED_EUI=1.8750760248144998 -e EXPECTED_EUI_RTOL=0.02 -e EXPECTED_EUI_ATOL=0.0"
               ;;
             2)
-              # common_measures (20 tests), hvac_systems, geometry, zone terminal, skill_energy_report, skill_new_building, validation sys1-4 + sys7-8
-              FILES="tests/test_common_measures.py tests/test_hvac_systems.py tests/test_replace_zone_terminal.py tests/test_geometry.py tests/test_bar_building.py tests/test_skill_energy_report.py tests/test_skill_new_building.py tests/test_hvac_validation_sys1_4.py tests/test_hvac_validation_sys7_8.py"
+              # common_measures, hvac_systems, geometry, zone terminal, skill_energy_report, hvac_validation (consolidated)
+              FILES="tests/test_common_measures.py tests/test_hvac_systems.py tests/test_replace_zone_terminal.py tests/test_geometry.py tests/test_bar_building.py tests/test_skill_energy_report.py tests/test_hvac_validation.py"
               EXTRA_ENV=""
               ;;
             3)
-              # controls, object mgmt, loads, building, doas, hvac, measures, skill_qaqc, skill_add_hvac, validation sys5-6
-              FILES="tests/test_component_controls.py tests/test_object_management.py tests/test_generic_access.py tests/test_create_loads.py tests/test_building.py tests/test_doas_system.py tests/test_hvac.py tests/test_measures.py tests/test_skill_qaqc.py tests/test_skill_add_hvac.py tests/test_hvac_validation_sys5_6.py tests/test_hvac_supply_wiring.py"
+              # controls, object mgmt, loads, building, doas, hvac, measures, measure_authoring, skill_qaqc, hvac_supply_wiring
+              FILES="tests/test_component_controls.py tests/test_object_management.py tests/test_generic_access.py tests/test_create_loads.py tests/test_building.py tests/test_doas_system.py tests/test_hvac.py tests/test_measures.py tests/test_measure_authoring.py tests/test_skill_qaqc.py tests/test_hvac_supply_wiring.py"
               EXTRA_ENV=""
               ;;
             4)
-              # vrf, radiant, query skills, creation, air terminals, results extraction, validation sys9-10
-              FILES="tests/test_vrf_system.py tests/test_radiant_system.py tests/test_loads.py tests/test_spaces.py tests/test_space_types.py tests/test_schedules.py tests/test_constructions.py tests/test_create_space.py tests/test_create_thermal_zone.py tests/test_add_air_loop.py tests/test_create_schedule_ruleset.py tests/test_add_output_variable.py tests/test_add_output_meter.py tests/test_load_save_model.py tests/test_versions.py tests/test_create_example_osm.py tests/test_inspect_osm_summary.py tests/test_copy_file.py tests/test_replace_air_terminals.py tests/test_results_extraction.py tests/test_swig_memleak_cleanup.py tests/test_skill_view.py tests/test_skill_tools_integration.py tests/test_hvac_validation_sys9_10.py tests/test_stdio_smoke.py tests/test_response_sizes.py"
+              # vrf, radiant, query skills, creation, air terminals, results extraction
+              FILES="tests/test_vrf_system.py tests/test_radiant_system.py tests/test_loads.py tests/test_spaces.py tests/test_space_types.py tests/test_schedules.py tests/test_constructions.py tests/test_create_space.py tests/test_create_thermal_zone.py tests/test_add_air_loop.py tests/test_create_schedule_ruleset.py tests/test_add_output_variable.py tests/test_add_output_meter.py tests/test_load_save_model.py tests/test_versions.py tests/test_create_example_osm.py tests/test_inspect_osm_summary.py tests/test_copy_file.py tests/test_replace_air_terminals.py tests/test_results_extraction.py tests/test_swig_memleak_cleanup.py tests/test_skill_tools_integration.py tests/test_stdio_smoke.py tests/test_response_sizes.py"
               EXTRA_ENV=""
               ;;
             5)

CLAUDE.md

@@ -1,12 +1,19 @@
 # CLAUDE.md — Instructions for Claude Code
 
 ## Project: openstudio-mcp
-Building energy simulation MCP server using OpenStudio SDK Python bindings and Measures.
+MCP server that gives AI agents full control of building energy modeling —
+create buildings, configure HVAC, run EnergyPlus simulations, and extract
+results — all through 134 MCP tools backed by the OpenStudio SDK.
 
-**Template project:** This codebase is designed as a reference implementation
-that other building energy simulation engines (EnergyPlus, TRNSYS, DOE-2, etc.)
-can use as a template. Code must be explicit, well-commented, and easy for
-contributors unfamiliar with OpenStudio to understand and adapt.
+**Who it's for:** Building energy modelers who want to use AI assistants
+(Claude, GPT, etc.) to do real modeling work — not just chat about it.
+The MCP tools replace manual GUI workflows in the OpenStudio Application
+with tool calls an LLM can chain together autonomously.
+
+**Template project:** Designed as a reference implementation that other
+building energy simulation engines (EnergyPlus, TRNSYS, DOE-2, etc.)
+can fork and adapt. Code is explicit, well-commented, and accessible
+to contributors unfamiliar with OpenStudio.
 
 ## Critical: Use MCP Tools — Do Not Reinvent
 Always use openstudio-mcp tools for BEM tasks:
@@ -41,6 +48,7 @@ Always use openstudio-mcp tools for BEM tasks:
 | Phase 6 | ✅ COMPLETE | Loads, object management, weather & measures (3 skills, 13 tools) |
 | Phase 7 | 📋 FUTURE | Advanced creation (geometry, space type wizard) |
 | Phase 8 | ✅ COMPLETE | Bundle common-measures-gem (20 measures, 11 tools: reporting, thermostat, envelope, PV, visualization) |
+| Phase 9 | ✅ COMPLETE | AI-assisted measure authoring (3 tools: create, test, edit custom measures) |
 
 ## Current Skills
 | Skill | Tools | Phase |
@@ -60,15 +68,16 @@ Always use openstudio-mcp tools for BEM tasks:
 | `simulation_outputs` | `add_output_variable`, `add_output_meter` | Phase 3 |
 | `hvac_systems` | `add_baseline_system`, `list_baseline_systems`, `get_baseline_system_info`, `replace_air_terminals`, `replace_zone_terminal`, `add_doas_system`, `add_vrf_system`, `add_radiant_system` | Phase 4 |
 | `component_properties` | `get_component_properties`, `set_component_properties`, `set_economizer_properties`, `set_sizing_properties`, `set_sizing_system_properties`, `get_sizing_system_properties`, `set_sizing_zone_properties`, `get_sizing_zone_properties`, `get_setpoint_manager_properties`, `set_setpoint_manager_properties` | Phase 5 |
-| `loop_operations` | `create_plant_loop`, `add_supply_equipment`, `remove_supply_equipment`, `add_demand_component`, `remove_demand_component`, `add_zone_equipment`, `remove_zone_equipment`, `remove_all_zone_equipment` | Phase 5 |
+| `loop_operations` | `create_plant_loop`, `add_supply_equipment`, `remove_supply_equipment`, `add_demand_component`, `remove_demand_component`, `add_zone_equipment`, `remove_zone_equipment`, `remove_all_zone_equipment`, `set_zone_equipment_priority` | Phase 5 |
 | `object_management` | `delete_object`, `rename_object`, `list_model_objects`, `get_object_fields`, `set_object_property` | Phase 6B |
 | `weather` | `get_weather_info`, `add_design_day`, `get_simulation_control`, `set_simulation_control`, `get_run_period`, `set_run_period` | Phase 6C |
 | `measures` | `list_measure_arguments`, `apply_measure` | Phase 6D |
 | `comstock` | `list_comstock_measures`, `create_bar_building`, `create_typical_building`, `create_new_building` | ComStock |
 | `common_measures` | `list_common_measures`, `view_model`, `view_simulation_data`, `generate_results_report`, `run_qaqc_checks`, `adjust_thermostat_setpoints`, `replace_window_constructions`, `enable_ideal_air_loads`, `clean_unused_objects`, `change_building_location`, `set_thermostat_schedules`, `replace_thermostat_schedules`, `shift_schedule_time`, `add_rooftop_pv`, `add_pv_to_shading`, `add_ev_load`, `add_zone_ventilation`, `set_lifecycle_cost_params`, `add_cost_per_floor_area`, `set_adiabatic_boundaries` | Phase 8 |
+| `measure_authoring` | `list_custom_measures`, `create_measure`, `test_measure`, `edit_measure` | Phase 9 |
 | `skill_discovery` | `list_skills`, `get_skill` | — |
 
-**Total: 22 skills, 131 MCP tools, ~310 integration tests**
+**Total: 23 skills, 134 MCP tools, ~390 integration tests**
 
 ## Model Query Pattern
 ```python
@@ -186,11 +195,6 @@ To add a new SPM type to `set_setpoint_manager_properties`:
 3. Add an entry to `SPM_TYPES` registry with getter method name and get/set functions.
 4. Add a test in `tests/test_component_controls.py`.
 
-## Active Fix Plan
-See `docs/debug/fix-plan.md` for current work items (11 items from Claude Desktop
-debug sessions). Key changes: remove inject_idf, rename read_run_artifact→read_file,
-list_files redesign, sizing system/zone tools, 6 new SPM types.
-
 ## Rules
 1. Keep files small where practical — aim for under 250 lines, but don't split artificially just to hit a number
 2. Every MCP tool must have a test in `tests/skills/` (Phase 2+) or `tests/` (existing)