EnergyPlus C API  0.1
This is the EnergyPlus C API, which allows linking to EnergyPlus and reading and manipluating data during a simulation.
Functions
/eplus/repos/7eplus/src/EnergyPlus/api/runtime.h File Reference

This "runtime" API category provides access to link into a running simulation by providing callback functions. More...

#include <EnergyPlus/api/TypeDefs.h>
#include <EnergyPlus/api/EnergyPlusAPI.h>

Go to the source code of this file.

Functions

void cClearAllStates ()
 Clears the simulation state of EnergyPlus. More...
 
int energyplus (int argc, const char *argv[])
 Runs an EnergyPlus simulation. More...
 
void issueWarning (const char *message)
 Asks EnergyPlus to issue a warning message to the error file. More...
 
void issueSevere (const char *message)
 Asks EnergyPlus to issue a severe message to the error file. More...
 
void issueText (const char *message)
 Asks EnergyPlus to issue a plain text message to the error file. More...
 
void registerProgressCallback (void(*f)(int const))
 Register a callback function to receive updates on simulation progress. More...
 
void registerStdOutCallback (void(*f)(const char *message))
 Register a callback function to receive standard output messages being sent from the simulation. More...
 
void callbackBeginNewEnvironment (void(*f)())
 Register a callback function to be called at the beginning of each new environment. More...
 
void callbackAfterNewEnvironmentWarmupComplete (void(*f)())
 Register a callback function to be called at each new environment once warmup is complete. More...
 
void callbackBeginZoneTimeStepBeforeInitHeatBalance (void(*f)())
 Register a callback function to be called at the beginning of each zone time step before the heat balance is initialized. More...
 
void callbackBeginZoneTimeStepAfterInitHeatBalance (void(*f)())
 Register a callback function to be called at the beginning of each zone time step after the heat balance is initialized. More...
 
void callbackBeginTimeStepBeforePredictor (void(*f)())
 Register a callback function to be called at each zone time step just before the predictor step. More...
 
void callbackAfterPredictorBeforeHVACManagers (void(*f)())
 Register a callback function to be called at each zone time step before HVAC managers are called. More...
 
void callbackAfterPredictorAfterHVACManagers (void(*f)())
 Register a callback function to be called at each zone time step after HVAC managers are called. More...
 
void callbackInsideSystemIterationLoop (void(*f)())
 Register a callback function to be called inside the HVAC system iteration loop. More...
 
void callbackEndOfZoneTimeStepBeforeZoneReporting (void(*f)())
 Register a callback function to be called at the end of each zone time step but before zones have reported data. More...
 
void callbackEndOfZoneTimeStepAfterZoneReporting (void(*f)())
 Register a callback function to be called at the end of each zone time step after zones have reported data. More...
 
void callbackEndOfSystemTimeStepBeforeHVACReporting (void(*f)())
 Register a callback function to be called at the end of each HVAC system time step but before HVAC data has been reported. More...
 
void callbackEndOfSystemTimeStepAfterHVACReporting (void(*f)())
 Register a callback function to be called at the end of each HVAC system time step after HVAC data has been reported. More...
 
void callbackEndOfZoneSizing (void(*f)())
 Register a callback function to be called at the end of the zone sizing process. More...
 
void callbackEndOfSystemSizing (void(*f)())
 Register a callback function to be called at the end of the HVAC system sizing process. More...
 
void callbackEndOfAfterComponentGetInput (void(*f)())
 Register a callback function to be called after some specific components have processed their input. More...
 
void callbackUnitarySystemSizing (void(*f)())
 Register a callback function to be called at unitary system sizing. More...
 

Detailed Description

This "runtime" API category provides access to link into a running simulation by providing callback functions.

While an EnergyPlus simulation is running, registered callback functions are "called back" at user-specified points in the simulation. When a function is called back, it can then leverage other APIs to do program manipulation. For example, it could leverage the functional API to look up a fluid property value, then use the data exchange API to assign a new control property on a component using an actuator. Once the callback functions have been registered, the client should then call the main energyplus function to initiate a new run. If multiple runs are to be performed in series, the cClearAllStates function can be used to "reset" the simulation. There are also methods to allow issuing warnings through internal EnergyPlus methods and to callback with updates on simulation progress and output messages.

See also
energyplus
cClearAllStates

Function Documentation

◆ callbackAfterNewEnvironmentWarmupComplete()

void callbackAfterNewEnvironmentWarmupComplete ( void(*)()  f)

Register a callback function to be called at each new environment once warmup is complete.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackAfterPredictorAfterHVACManagers()

void callbackAfterPredictorAfterHVACManagers ( void(*)()  f)

Register a callback function to be called at each zone time step after HVAC managers are called.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackAfterPredictorBeforeHVACManagers()

void callbackAfterPredictorBeforeHVACManagers ( void(*)()  f)

Register a callback function to be called at each zone time step before HVAC managers are called.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackBeginNewEnvironment()

void callbackBeginNewEnvironment ( void(*)()  f)

Register a callback function to be called at the beginning of each new environment.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackBeginTimeStepBeforePredictor()

void callbackBeginTimeStepBeforePredictor ( void(*)()  f)

Register a callback function to be called at each zone time step just before the predictor step.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackBeginZoneTimeStepAfterInitHeatBalance()

void callbackBeginZoneTimeStepAfterInitHeatBalance ( void(*)()  f)

Register a callback function to be called at the beginning of each zone time step after the heat balance is initialized.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackBeginZoneTimeStepBeforeInitHeatBalance()

void callbackBeginZoneTimeStepBeforeInitHeatBalance ( void(*)()  f)

Register a callback function to be called at the beginning of each zone time step before the heat balance is initialized.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfAfterComponentGetInput()

void callbackEndOfAfterComponentGetInput ( void(*)()  f)

Register a callback function to be called after some specific components have processed their input.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.
Currently this calling point is called after each instance of a DX coil, fan, and unitary system object.

◆ callbackEndOfSystemSizing()

void callbackEndOfSystemSizing ( void(*)()  f)

Register a callback function to be called at the end of the HVAC system sizing process.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfSystemTimeStepAfterHVACReporting()

void callbackEndOfSystemTimeStepAfterHVACReporting ( void(*)()  f)

Register a callback function to be called at the end of each HVAC system time step after HVAC data has been reported.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfSystemTimeStepBeforeHVACReporting()

void callbackEndOfSystemTimeStepBeforeHVACReporting ( void(*)()  f)

Register a callback function to be called at the end of each HVAC system time step but before HVAC data has been reported.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfZoneSizing()

void callbackEndOfZoneSizing ( void(*)()  f)

Register a callback function to be called at the end of the zone sizing process.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfZoneTimeStepAfterZoneReporting()

void callbackEndOfZoneTimeStepAfterZoneReporting ( void(*)()  f)

Register a callback function to be called at the end of each zone time step after zones have reported data.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackEndOfZoneTimeStepBeforeZoneReporting()

void callbackEndOfZoneTimeStepBeforeZoneReporting ( void(*)()  f)

Register a callback function to be called at the end of each zone time step but before zones have reported data.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackInsideSystemIterationLoop()

void callbackInsideSystemIterationLoop ( void(*)()  f)

Register a callback function to be called inside the HVAC system iteration loop.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ callbackUnitarySystemSizing()

void callbackUnitarySystemSizing ( void(*)()  f)

Register a callback function to be called at unitary system sizing.

During an EnergyPlus simulation, a number of predetermined calling points have been established at which any registered callback functions are "called back". This API function allows a client to register a function with no arguments to be called at this specific calling point. From inside this function, the client can leverage other API categories to look up property values or exchange data with the simulation as needed.

Parameters
[in]fThe function to be called back at this specific calling point in the simulation. The function expects no arguments.
Remarks
This function is only allowed during API simulations. For Python Plugin applications, the client will create a custom Python class and override specific functions to be called at equivalent points in the simulation.

◆ cClearAllStates()

void cClearAllStates ( )

Clears the simulation state of EnergyPlus.

After a simulation is complete, if a second is to be run using the same memory space, the simulation state must be cleared, or unexpected errors will occur.

Remarks
This function will also clear any callback functions, so callback functions must be registered again.

◆ energyplus()

int energyplus ( int  argc,
const char *  argv[] 
)

Runs an EnergyPlus simulation.

This function launches an EnergyPlus simulation using the given arguments. The arguments are identical to the command line for EnergyPlus(.exe). Prior to calling this function, it is expected that most workflows will register callback functions to be called back from EnergyPlus at user-specified points in the simulation. If no callbacks are registered, EnergyPlus will proceed as in a regular command line fashion and return when complete. An example usage of this API endpoint is as follows:

void progressCallback(int const i) {
printf("Updated progress: %d", i);
}
int main(int argc, const char * argv[]) {
registerProgressCallback(progressCallback);
energyplus(argc, argv);
}
Remarks
If this function is called multiple times in the same thread, the client must call cClearAllStates in between each run, or unexpected errors will occur.
Prior to calling this function, it is also expected that most workflows will want to use the data exchange API function requestVariable to pre-request Output:Variables to make them accessible in the data exchange functions.
See also
cClearAllStates
requestVariable

◆ issueSevere()

void issueSevere ( const char *  message)

Asks EnergyPlus to issue a severe message to the error file.

During an EnergyPlus simulation, if certain conditions arise, it may be useful to alert the user using this function, which will issue a severe error note in the standard error file and continue the simulation. Severe errors should lead to program termination, so this should be followed with aborting the simulation in one of these ways:

  • If running as a Python Plugin, the function should return 1 to inform EnergyPlus to throw a fatal.
  • If running as an API, the client should abort however is appropriate. If needed, cClearAllStates can be called to reinitialize the program.
Parameters
[in]messageThe severe error message to be issued during the simulation.
Remarks
The usefulness of this function during API applications is questionable, however it is highly valuable during Python Plugin applications. In these applications, the user is still interfacing with EnergyPlus as a black-box program and will rely on output messages primarily through EnergyPlus output files. Using this function to issue a message using standard EnergyPlus techniques will make the process familiar.

◆ issueText()

void issueText ( const char *  message)

Asks EnergyPlus to issue a plain text message to the error file.

During an EnergyPlus simulation, if certain conditions arise, it may be useful to send information to the user with this function, either to provide standard information, or supplemental information to a previously sent warning or error.

Parameters
[in]messageThe text message to be issued during the simulation.
Remarks
The usefulness of this function during API applications is questionable, however it is highly valuable during Python Plugin applications. In these applications, the user is still interfacing with EnergyPlus as a black-box program and will rely on output messages primarily through EnergyPlus output files. Using this function to issue a message using standard EnergyPlus techniques will make the process familiar.

◆ issueWarning()

void issueWarning ( const char *  message)

Asks EnergyPlus to issue a warning message to the error file.

During an EnergyPlus simulation, if certain conditions arise, it may be useful to alert the user using this function, which will issue a warning note in the standard error file and continue the simulation.

Parameters
[in]messageThe warning message to be issued during the simulation.
Remarks
The usefulness of this function during API applications is questionable, however it is highly valuable during Python Plugin applications. In these applications, the user is still interfacing with EnergyPlus as a black-box program and will rely on output messages primarily through EnergyPlus output files. Using this function to issue a message using standard EnergyPlus techniques will make the process familiar.

◆ registerProgressCallback()

void registerProgressCallback ( void(*)(int const)  f)

Register a callback function to receive updates on simulation progress.

During an EnergyPlus simulation, the progress of the simulation will move from zero to one hundred percent. This function can be used to get updates during the simulation that could be used to better provide feedback to the user, perhaps in the form of a progress bar.

Parameters
[in]fThe function to be called back during the simulation. The function should expect one constant integer argument, which will be the percent complete for the current simulation run.
Remarks
This function has limited usefulness in Python Plugin applications, but is highly valuable for being able to report progress during an API workflow simulation.

◆ registerStdOutCallback()

void registerStdOutCallback ( void(*)(const char *message)  f)

Register a callback function to receive standard output messages being sent from the simulation.

During an EnergyPlus simulation, there are a number of output messages being sent to standard output on the command line. This function can be used to get copies of those messages during the simulation which could be captured and better presented to the user during an API workflow.

Parameters
[in]fThe function to be called back during the simulation. The function should expect one constant char * argument, which will be the message being sent to standard output.
Remarks
This function has limited usefulness in Python Plugin applications, but is highly valuable for being able to report messages during an API workflow simulation.