Skip to content

Fix EMS flow diagram: remove BeginNewEnv from Setup Sim box (#11440)#11528

Merged
mitchute merged 2 commits into
developfrom
docs-11440-ems-flowchart-fix
Apr 24, 2026
Merged

Fix EMS flow diagram: remove BeginNewEnv from Setup Sim box (#11440)#11528
mitchute merged 2 commits into
developfrom
docs-11440-ems-flowchart-fix

Conversation

@brianlball
Copy link
Copy Markdown
Contributor

Summary

  • Fixes the "Overall Program Flow and EMS Calling Points" figure (image003.jpg) in the EMS Application Guide.
  • The Setup Simulation box in the figure labeled an "EMS Calling Point: BeginNewEnvironment" annotation inside it. This is incorrect — BeginNewEnvironment never fires during SimulationManager::SetupSimulation. Verified against the code (SimulationManager.cc:431 is the only place this calling point is invoked, inside the main env loop, not inside SetupSimulation).
  • Also verified against the Fortran original NREL/EnergyPlusRelease/SourceCode/SimulationManager.f90: SetupSimulation has never invoked this calling point (back to May 2008, Griffith/Lawrie). Not a conversion regression, just a figure inaccuracy.

Closes #11440 (with docs clarification rather than code change).

What actually happens during Setup Simulation

  • Three reverse-DD kickoff timesteps run per environment.
  • Timestep calling points DO fire during those timesteps (BeginTimestepBeforePredictor, etc.) and user programs on those points run — the existing "(Timestep Calling Points)" annotation is accurate and is kept.
  • BeginNewEnvironment does not fire here. It fires once per environment at SimulationManager.cc:431, AFTER SetupSimulation completes and before warmup.
  • Canonical examples (EMSWindowShadeControl.idf, EMSConstantVolumePurchasedAir.idf) rely on this line-431 firing to initialize their Erl constants before the first reported timestep — they've been passing for years.

Actual EMS calling point flow (for reviewers)

Program Start  (SimulationManager::ManageSimulation)
 │
 ├─ Input parsing (InputProcessor)
 │     [AfterComponentInputReadIn]   enum=ComponentGetInput
 │         └─ DXCoils.cc:6792, Fans.cc:1189, Furnaces.cc:4798, ...
 │
 ├─ Sizing
 │   ├─ [EndOfZoneSizing]    enum=ZoneSizing
 │   │       └─ ZoneEquipmentManager.cc:3336
 │   ├─ [EndOfSystemSizing]  enum=SystemSizing
 │   │       └─ SimAirServingZones.cc:7088
 │   └─ [UnitarySystemSizing]
 │           └─ Furnaces.cc:6031
 │
 ▼ KickOffSimulation = true
 │
 ├─ SetupSimulation (3 kickoff timesteps, no warmup, no reported output)
 │     During each kickoff timestep, Timestep Calling Points fire:
 │         [BeginZoneTimestepBeforeSetCurrentWeather] WeatherManager.cc:150
 │         [BeginZoneTimestepBeforeInitHeatBalance]   HeatBalanceManager.cc:192
 │         [BeginZoneTimestepAfterInitHeatBalance]    HeatBalanceManager.cc:200
 │         [BeginTimestepBeforePredictor]             HVACManager.cc:217
 │         [AfterPredictorBeforeHVACManagers]         HVACManager.cc:844
 │         [AfterPredictorAfterHVACManagers]          HVACManager.cc:854
 │         [InsideHVACSystemIterationLoop]            HVACManager.cc:855, 889
 │         [EndOfSystemTimestepBeforeHVACReporting]   HVACManager.cc:447
 │         [EndOfSystemTimestepAfterHVACReporting]    HVACManager.cc:563
 │         [EndOfZoneTimestepBeforeZoneReporting]     HeatBalanceManager.cc:210
 │         [EndOfZoneTimestepAfterZoneReporting]      HeatBalanceManager.cc:219
 │     NOTE: BeginNewEnvironment does NOT fire here (this PR's fix).
 │
 ▼ (internal) ManageEMS(EMSCallFrom::SetupSimulation) at SimulationManager.cc:337
 │     Parses EMS input, registers programs. Internal-only, NOT a
 │     user-selectable calling point (not in IDD choice list).
 │
 ▼ KickOffSimulation = false
 │
 ├─ Design Periods (DesignDay / SizingPeriod) — per environment:
 │     [BeginNewEnvironment]  SimulationManager.cc:431  ← fires HERE
 │     Warmup timesteps (Timestep Calling Points fire)
 │     [AfterNewEnvironmentWarmUpIsComplete]  enum=BeginNewEnvironmentAfterWarmUp
 │         └─ HeatBalanceManager.cc:231
 │     Reported timesteps (Timestep Calling Points fire)
 │
 ├─ Run Periods (RunPeriod) — same structure as Design Periods.
 │
 └─ Program End

IDD-key / internal-enum name mismatches worth noting

  • AfterComponentInputReadIn ↔ enum ComponentGetInput
  • EndOfZoneSizing ↔ enum ZoneSizing
  • EndOfSystemSizing ↔ enum SystemSizing
  • AfterNewEnvironmentWarmUpIsComplete ↔ enum BeginNewEnvironmentAfterWarmUp
  • AfterPredictorBeforeHVACManagers ↔ enum BeforeHVACManagers
  • AfterPredictorAfterHVACManagers ↔ enum AfterHVACManagers
  • InsideHVACSystemIterationLoop ↔ enum HVACIterationLoop

Files changed

  • doc/readthedocs/sphinx/ems-application-guide/media/image003.jpg — removed the spurious annotation.
  • doc/readthedocs/sphinx/ems-application-guide/media/DrawingFileForEMSCallingPointFigures_LibreOfficeDraw.odg — editable source kept in sync.

No code, test, IDD, or IDF changes.

Test plan

  • Sphinx docs build completes.
  • Updated figure renders correctly in the EMS Application Guide (fig. 77, "Overall Program Flow and EMS Calling Points").
  • No regressions (no code changed).

…box (#11440)

Setup Simulation runs three kickoff timesteps for reverse-DD resolution;
EMS user programs registered on BeginNewEnvironment do not fire during
that phase. They fire in the main env loop (SimulationManager.cc:431).
Timestep calling points do still fire during kickoff, so keep that
annotation.
@brianlball brianlball added Documentation Related primarily on the LaTeX-based EnergyPlus documentation Defect Includes code to repair a defect in EnergyPlus labels Apr 14, 2026
@brianlball
Copy link
Copy Markdown
Contributor Author

updated Setup Simulation block

image003

@brianlball brianlball requested a review from mitchute April 17, 2026 15:41
Copy link
Copy Markdown
Collaborator

@mitchute mitchute left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @brianlball

@mitchute mitchute merged commit c751bf1 into develop Apr 24, 2026
8 checks passed
@mitchute mitchute deleted the docs-11440-ems-flowchart-fix branch April 24, 2026 20:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Defect Includes code to repair a defect in EnergyPlus Documentation Related primarily on the LaTeX-based EnergyPlus documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

EMS calling point BeginNewEnvironment not run during "Setup Simulation"

3 participants