Skip to content

#11123 - Document that api_data_fully_ready is probably not need for Construction actuators #11177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
Myoldmopar merged 1 commit into from
Aug 27, 2025
Merged

#11123 - Document that api_data_fully_ready is probably not need for Construction actuators #11177

Myoldmopar merged 1 commit into from
Aug 27, 2025

Conversation

@jmarrec
Copy link
Contributor

@jmarrec jmarrec commented Aug 27, 2025 •
edited
Loading

Pull request overview

Description of the purpose of this PR

This comes after a long investigation. You can find a notebook that demonstrates the investigation at https://github.com/NREL/EnergyPlusDevSupport/blob/master/DefectFiles/11000s/11123/11123_Reproducer.ipynb (Public Gist version here)

I took 5ZoneAirCooled.idf and added another construction => base.idf.

Then I made several variations that use a ConstructionIndexVariable with a Surface "Construction State Actuator", and changes the construction for all windows on BeginTimestepBeforePredictor, like the original defect file.

  • An EMS version
  • An API version
  • A Python Plugin Version
    • And one that sets "Run During Warmup" to false

The python_plugin.py goes somethng like

    def on_begin_timestep_before_predictor(self, state) -> int:
        if not self.api.exchange.api_data_fully_ready(state):
            return 0

        # Get handles if needed

        # actuate

I was getting different total site energy, and could see that the Zone Sizing in eplusout.eio was different.

And then I realized, via a debugger, that the issue was that api.exchange.api_data_fully_ready is set MUCH later, so that Zone Sizing happens with the construction switch for the EMS case but not the PythonPlugin/API Version

EnergyPlus/src/EnergyPlus/SimulationManager.cc

Line 343 in 446b7cf

state.dataPluginManager->fullyReady = true;

The EMS goes:

Initializing Surfaces
Initializing Outdoor environment for Surfaces
Setting up Surface Reporting Variables
Initializing Temperature and Flux Histories
Initializing Window Shading
Computing Interior Absorption Factors
Computing Interior Diffuse Solar Absorption Factors
Initializing Solar Heat Gains
Initializing Internal Heat Gains
Initializing Interior Solar Distribution
Initializing Interior Convection Coefficients
Gathering Information for Predefined Reporting
Completed Initializing Surface Heat Balance
Calculate Outside Surface Heat Balance
Calculate Inside Surface Heat Balance
Calculate Air Heat Balance
Initializing HVAC
Process 1672468 stopped
* thread #1, name = 'energyplus', stop reason = breakpoint 2.1
    frame #0: 0x00007ffff3bac59e libenergyplusapi.so.25.2.0`EnergyPlus::HeatBalanceSurfaceManager::InitEMSControlledConstructions(state=0x00007fffffffa800) at HeatBalanceSurfaceManager.cc:4686:29
   4683	    state.dataGlobal->AnyConstrOverridesInModel = false;
   4684	    for (int SurfNum = 1; SurfNum <= state.dataSurface->TotSurfaces; ++SurfNum) {
   4685	        if (state.dataSurface->SurfEMSConstructionOverrideON(SurfNum)) {
-> 4686	            state.dataGlobal->AnyConstrOverridesInModel = true;
   4687	            break;
   4688	        }
   4689	    }

The PythonPlugin goes

[...]
Initializing HVAC
Warming up
Warming up
Warming up
Warming up
Warming up
Warming up
Performing Zone Sizing Simulation for Load Component Report
...for Sizing Period: #1 CHICAGO_IL_USA ANNUAL HEATING 99% DESIGN CONDITIONS DB
Warming up
Warming up
Warming up
Warming up
Warming up
Warming up
Performing Zone Sizing Simulation for Load Component Report
...for Sizing Period: #2 CHICAGO_IL_USA ANNUAL COOLING 1% DESIGN CONDITIONS DB/MCWB
Re-zeroing zone sizing arrays
Warming up
Warming up
Warming up
Warming up
Warming up
Warming up
Performing Zone Sizing Simulation
...for Sizing Period: #1 CHICAGO_IL_USA ANNUAL HEATING 99% DESIGN CONDITIONS DB
Warming up
Warming up
Warming up
Warming up
Warming up
Warming up
Performing Zone Sizing Simulation
...for Sizing Period: #2 CHICAGO_IL_USA ANNUAL COOLING 1% DESIGN CONDITIONS DB/MCWB
Calculating System sizing
...for Sizing Period: #1 CHICAGO_IL_USA ANNUAL HEATING 99% DESIGN CONDITIONS DB
Calculating System sizing
...for Sizing Period: #2 CHICAGO_IL_USA ANNUAL COOLING 1% DESIGN CONDITIONS DB/MCWB
Adjusting Air System Sizing
Adjusting Standard 62.1 Ventilation Sizing
Initializing Simulation
Reporting Surfaces
Beginning Primary Simulation
Initializing New Environment Parameters
Warming up {1}
['DB-1', 'DF-1', 'WB-1', 'WF-1', 'WL-1', 'WR-1']
actuating
Process 1672717 stopped
* thread #1, name = 'energyplus', stop reason = breakpoint 1.1
    frame #0: 0x00007ffff3bac59e libenergyplusapi.so.25.2.0`EnergyPlus::HeatBalanceSurfaceManager::InitEMSControlledConstructions(state=0x00007fffffffa800) at HeatBalanceSurfaceManager.cc:4686:29
   4683	    state.dataGlobal->AnyConstrOverridesInModel = false;
   4684	    for (int SurfNum = 1; SurfNum <= state.dataSurface->TotSurfaces; ++SurfNum) {
   4685	        if (state.dataSurface->SurfEMSConstructionOverrideON(SurfNum)) {
-> 4686	            state.dataGlobal->AnyConstrOverridesInModel = true;
   4687	            break;
   4688	        }
   4689	    }

Pull Request Author

  • Title of PR should be user-synopsis style (clearly understandable in a standalone changelog context)
  • Label the PR with at least one of: Defect, Refactoring, NewFeature, Performance, and/or DoNoPublish
  • Pull requests that impact EnergyPlus code must also include unit tests to cover enhancement or defect repair
  • Author should provide a "walkthrough" of relevant code changes using a GitHub code review comment process
  • If any diffs are expected, author must demonstrate they are justified using plots and descriptions
  • If changes fix a defect, the fix should be demonstrated in plots and descriptions
  • If any defect files are updated to a more recent version, upload new versions here or on DevSupport
  • If IDD requires transition, transition source, rules, ExpandObjects, and IDFs must be updated, and add IDDChange label
  • If structural output changes, add to output rules file and add OutputChange label
  • If adding/removing any LaTeX docs or figures, update that document's CMakeLists file dependencies

Reviewer

  • Perform a Code Review on GitHub
  • If branch is behind develop, merge develop and build locally to check for side effects of the merge
  • If defect, verify by running develop branch and reproducing defect, then running PR and reproducing fix
  • If feature, test running new feature, try creative ways to break it
  • CI status: all green or justified
  • Check that performance is not impacted (CI Linux results include performance check)
  • Run Unit Test(s) locally
  • Check any new function arguments for performance impacts
  • Verify IDF naming conventions and styles, memos and notes and defaults
  • If new idf included, locally check the err file and other outputs

@jmarrec
#11123 - Document that api_data_fully_ready is probably not need for …
f168af9 
…Construction actuators

This comes after a long investigation.

I took 5ZoneAirCooled.idf and added another construction => base.idf
Then I made several variations that use a ConstructionIndexVariable with a Surface "Construction State Actuator":
* An EMS version
* An API version
* A Python Plugin Version
     * And one that sets "Run During Warmup" to false

And then I realized, via a debugger, that the issue was that api.exchange.api_data_fully_ready is set MUCH later, so that Zone Sizing happens with the construction switch for the EMS case but not the PythonPlugin/API Version
@jmarrec jmarrec requested a review from Myoldmopar August 27, 2025 17:41
@jmarrec jmarrec self-assigned this Aug 27, 2025
@jmarrec jmarrec added the Defect Includes code to repair a defect in EnergyPlus label Aug 27, 2025
@jmarrec
Copy link
Contributor Author

jmarrec commented Aug 27, 2025

doxygen

image

sphinx readthedocs

image

@Myoldmopar
Copy link
Member

Myoldmopar commented Aug 27, 2025

Indeed. Great find. I guess the extra note about construction states/handles could be even more general. There are probably plenty of times where you might need to access things early, but we just can't guarantee everything will be set up. I dunno. No need to add more here, and no need to wait on CI. Merging it, thanks @jmarrec

@Myoldmopar Myoldmopar merged commit 5eba607 into develop Aug 27, 2025
7 checks passed
@Myoldmopar Myoldmopar deleted the 11123_PythonAPI_Discrepancy branch August 27, 2025 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Myoldmopar Myoldmopar Awaiting requested review from Myoldmopar

Assignees

@jmarrec jmarrec

Labels

Defect Includes code to repair a defect in EnergyPlus

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Python API: Discrepancy in Runtime Window Construction Actuation vs. EMS

3 participants

@jmarrec @Myoldmopar