Skip to content

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

Open
brianlball wants to merge 1 commit intodevelopfrom
docs-11440-ems-flowchart-fix
Open

Fix EMS flow diagram: remove BeginNewEnv from Setup Sim box (#11440)#11528
brianlball wants to merge 1 commit intodevelopfrom
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

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"

2 participants