Tas + OpenStudio/EnergyPlus from SAM_UI on one frozen model: validation first, then parallel jobs and SAM MCP (tracking) #227

Goal

Run Tas and OpenStudio/EnergyPlus from SAM_UI on the same frozen SAM AnalyticalModel, so that we can line up inputs, compare outputs and build confidence in both simulation workflows. Only once that is validated do we add parallel execution and then a SAM MCP server.

NatLabRockies/openstudio-mcp is treated as an optional companion for AI agents (OSM editing and measures on files SAM exports). It is not SAM's engine.

Current state (Q4 sow/2026-Q4)

• SAM_UI:
  • Tas runs inside the app: WPF/SAM.Analytical.UI.WPF/Modify/Simulate.cs:769 → Modify/RunWorkflow.cs:49.
  • There is no OpenStudio path. SAM_OpenStudio is not referenced in any csproj or in build.yml.
• SAM_OpenStudio:
  • Entry points: AnalyticalModel.ToOpenStudio/ToOpenStudioAsync(epw, outDir, convOpts, runOpts, run, IProgress, CancellationToken).
  • EnergyPlus runs out of process through openstudio.exe under a Job Object, with a unique run folder per run. Results are read from SQL into SAM result classes.
  • benchmark-openstudio writes a B1a document.
  • There is no input/translation report.
• SAM_Validation:
  • B1a schema v1 (provenance hashes, model and space metrics with units, available:false for missing values).
  • benchmark-compare with Match/Warn/Fail bands and a provenance gate.
  • Only synthetic fixtures so far. B4 (corpus) and B6 (first validated report) are pending.
• SAM_Tas:
  • benchmark-tas runs on an STA thread and writes B1a. It needs .NET Framework MSBuild because of the COM references.
  • One live run is recorded. SingleBox is illegal in Tas.
  • No real Tas-vs-OpenStudio comparison has been done.
• SAM_Multitasker:
  • A Roslyn script runner with no STA/COM handling, cancellation, progress or isolation, plus known defects.
  • SAM_UI's Multitasker Grasshopper component does not use it.

Architecture (Phase 1)

1. Snapshot: serialise the model to JSON once and compute canonicalModelHash. Both engines read this file, and any engine-specific preparation works on a copy.
2. Weather: one EPW, hashed once, and the same design-day source for both engines.
3. Run order: engines run one after the other. The Tas path is unchanged. OpenStudio runs through ToOpenStudioAsync on a background thread; EnergyPlus is already a separate process.
4. Results: each engine writes results into its own copy (<name>_TAS.json, <name>_OpenStudio.json). Existing Tas results are never overwritten.
5. Evidence: a B1a document per engine, benchmark-compare for outputs, and an input manifest per engine. Together these make one comparison report.

Phases, issues and gates

Child issues are listed below as sub-issues. Gates use PASS / FAIL / NOT RUN / BLOCKED and keep GitHub CI separate from local runs on a machine with a Tas licence and OpenStudio 3.10 installed. No engine output has to agree within an arbitrary percentage: a difference is acceptable when it is classified and explained.

Phase 1 (working simulations and validation): highest priority

• Tas baseline → G0
• Minimal OpenStudio/EnergyPlus run from SAM_UI → G1 (first PR)
• Input manifest: what EnergyPlus received (SAM_OpenStudio)
• Input manifest: what Tas received
• Engine comparison run on one frozen snapshot plus comparison report → G2
• Benchmark cases and acceptance criteria
• Investigate and classify differences → G3

Phase 2 (parallel execution): opens after G3

• SAM_Multitasker assessment and job-runner design (Tas COM/STA and licence limits preserved)
• Parallel Tas + OpenStudio runs from the UI → G4

Phase 3 (SAM MCP): opens after G4

• SAM MCP server on the validated workflows and the job layer, built so other SAM engineering functions can be added
• openstudio-mcp companion guide (SAM_OpenStudio, docs only)

Difference classes used throughout: model/export defect, input or schedule mismatch, engine methodology difference, result extraction or unit-conversion defect.

Policy

Each child is delivered through a focused PR into sow/2026-Q4 with a PR record document. PROJECT_PROGRESS.md gets a closeout entry only after the merge, as AGENTS.md requires. Dependencies in SAM_Validation and SAM_Tas are referenced here; if a change is needed in either, it gets its own issue in that repository.