This "data exchange" API category provides access to read and write real-time data within a running simulation. More...

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

Functions
char *	listAllAPIDataCSV ()
	Gets available API data for the current simulation. More...

int	apiDataFullyReady ()
	Provides a user-facing check for whether API data is ready to be accessed. More...

int	apiErrorFlag ()
	Provides a user-facing check on the API error flag. More...

void	resetErrorFlag ()
	Reset the API Error flag. More...

void	requestVariable (const char type, const char key)
	Marks a variable as requested in a simulation. More...

int	getVariableHandle (const char type, const char key)
	Gets a handle to a variable. More...

Real64	getVariableValue (int handle)
	Gets the current value of a variable. More...

int	getMeterHandle (const char *meterName)
	Gets a handle to a meter. More...

Real64	getMeterValue (int handle)
	Gets the current value of a meter. More...

int	getActuatorHandle (const char componentType, const char controlType, const char *uniqueKey)
	Gets a handle to an actuator. More...

void	resetActuator (int handle)
	Resets an actuator so EnergyPlus will calculate the value as normal. More...

void	setActuatorValue (int handle, Real64 value)
	Sets the value of an actuator in EnergyPlus. More...

Real64	getActuatorValue (int handle)
	Gets the value of an actuator in EnergyPlus. More...

int	getInternalVariableHandle (const char type, const char key)
	Gets a handle to an internal variable. More...

Real64	getInternalVariableValue (int handle)
	Gets the current value of an internal variable. More...

int	getPluginGlobalVariableHandle (const char *name)
	Gets a handle to a Python Plugin "Global" variable. More...

Real64	getPluginGlobalVariableValue (int handle)
	Gets the current value of a Python Plugin "Global" variable. More...

void	setPluginGlobalVariableValue (int handle, Real64 value)
	Sets the value of a Python Plugin "Global" variable. More...

int	getPluginTrendVariableHandle (const char *name)
	Gets a handle to a Python Plugin "Trend" variable. More...

Real64	getPluginTrendVariableValue (int handle, int timeIndex)
	Gets the current value of a Python Plugin "Trend" variable at a specific history point. More...

Real64	getPluginTrendVariableAverage (int handle, int count)
	Gets the average value of a Python Plugin "Trend" variable over a given number of history points. More...

Real64	getPluginTrendVariableMin (int handle, int count)
	Gets the minimum value of a Python Plugin "Trend" variable over a given number of history points. More...

Real64	getPluginTrendVariableMax (int handle, int count)
	Gets the maximum value of a Python Plugin "Trend" variable over a given number of history points. More...

Real64	getPluginTrendVariableSum (int handle, int count)
	Gets the summation of a Python Plugin "Trend" variable over a given number of history points. More...

Real64	getPluginTrendVariableDirection (int handle, int count)
	Gets the average trajectory of a Python Plugin "Trend" variable over a given number of history points. More...

int	year ()
	Returns the current year of the simulation. More...

int	month ()
	Returns the current month of the simulation, from 1 for January to 12 for December. More...

int	dayOfMonth ()
	Returns the current day of month of the simulation, from 1 to 28, 29, 30, or 31, based on the month. More...

int	dayOfWeek ()
	Returns the current day of week of the simulation, from 1 for Sunday to 7 on Saturday. More...

int	dayOfYear ()
	Returns the current day of year of the simulation, from 1 for January 1 to 365 (or 366 for a leap year) for December 31. More...

int	daylightSavingsTimeIndicator ()
	Returns the current daylight savings time status, which is 0 (zero) if DST is off, or 1 (one) if DST is on. More...

int	hour ()
	Returns the current hour of the day in 0-23 form. More...

Real64	currentTime ()
	Returns the current time of the simulation. More...

int	minutes ()
	Returns the minutes into the hour from 1 to 60. More...

Real64	zoneTimeStep ()
	Returns the duration of the current zone simulation time step, in fractional hours. More...

Real64	systemTimeStep ()
	Returns the duration of the current HVAC system simulation time step, in fractional hours. More...

int	holidayIndex ()
	Returns the holiday index for the current day of the simulation. More...

int	sunIsUp ()
	Returns 0 if the sun is down, or 1 if the sun is up. More...

int	isRaining ()
	Returns 0 if it is not currently raining, or 1 if it is currently raining. More...

int	warmupFlag ()
	Returns the current warmup flag status, 0 if not warming up, 1 if warming up. More...

int	kindOfSim ()
	Returns an integer indicator for the current simulation environment type. More...

int	currentEnvironmentNum ()
	Returns the current environment number for a specific siulation. More...

int	getConstructionHandle (const char *constructionName)
	Returns an index to a construction in the simulation. More...

int	actualTime ()
	Returns a simple sum of the time part of the date/time function. More...

int	actualDateTime ()
	Returns a simple sum of the date/time function. More...

Detailed Description

This "data exchange" API category provides access to read and write real-time data within a running simulation.

While an EnergyPlus simulation is running, simulation state is constantly being calculated and updated. EMS was implemented in EnergyPlus to allow user scripts to read variable data and write actuator data in custom ways. This builds on top of that implementation by allowing the user to write C code that can read/write simulation data. This file includes methods that are specific to PythonPlugin workflows, including PythonPlugin "Trend" and "Global" variables. These mechanisms are only available in Plugin workflows and will cause a program error if they are accessed in an "EnergyPlus-as-a-library" workflow. However, there are many functions in this file that are available for all API usages, including getting access to variables and meters, writing actuator values, and accessing simulation state such as the day of week, hour of day, etc.

Function Documentation

◆ actualDateTime()

int actualDateTime ( )

Returns a simple sum of the date/time function.

Could be used in random seeding.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady; kindOfSim

◆ actualTime()

int actualTime ( )

Returns a simple sum of the time part of the date/time function.

Could be used in random seeding.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady; kindOfSim

◆ apiDataFullyReady()

int apiDataFullyReady ( )

Provides a user-facing check for whether API data is ready to be accessed.

Many parts of a simulation need to be set up to complete a run. At the early stages of a simulation, most data has not been allocated and set up. Calling to retrieve variable, meter, or actuator values prior to this point can cause problems. This function allows a user to call the simulation to check whether data is ready for access. Do not call for variable, meter, actuator, or any other internal exchange data prior to this returning true.

Returns: Returns 0 (success) once the data is ready, otherwise returns 1.

◆ apiErrorFlag()

int apiErrorFlag ( )

Provides a user-facing check on the API error flag.

Some API functions return a value of 0, which could potentially indicate an error, or an actual 0 value. This function provides a way to disambiguate the response value.

Returns: Returns 0 (success) if the error flag is not activated, or 1 if the error flag is true.

◆ currentEnvironmentNum()

int currentEnvironmentNum ( )

Returns the current environment number for a specific siulation.

As EnergyPlus simulates, it runs through multiple phases that often include multiple design days followed by a run period. This function returns the current index which is just incremented for each new phase. This has limited value in a general sense, but for some very tightly defined workflows, this could give some information. It is more advised to check the result of the kindOfSim function to get a reliable environment type.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady; kindOfSim

◆ currentTime()

Real64 currentTime ( )

Returns the current time of the simulation.

For this function, the current time represents the end time of the current time step. The time is returned as floating point fractional hours of the day, and since it represents the end of the current time step, the value will go from just over zero at the beginning of a day to 24.0 at the last time step of the day.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ daylightSavingsTimeIndicator()

int daylightSavingsTimeIndicator ( )

Returns the current daylight savings time status, which is 0 (zero) if DST is off, or 1 (one) if DST is on.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ dayOfMonth()

int dayOfMonth ( )

Returns the current day of month of the simulation, from 1 to 28, 29, 30, or 31, based on the month.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ dayOfWeek()

int dayOfWeek ( )

Returns the current day of week of the simulation, from 1 for Sunday to 7 on Saturday.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ dayOfYear()

int dayOfYear ( )

Returns the current day of year of the simulation, from 1 for January 1 to 365 (or 366 for a leap year) for December 31.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ getActuatorHandle()

int getActuatorHandle	(	const char *	componentType,
		const char *	controlType,
		const char *	uniqueKey
	)

Gets a handle to an actuator.

Looks up a handle to an actuator within a running simulation. Actuators are identified by three parameters: key, type, and control type

Parameters

[in]	componentType	The component type for the actuator, such as "Weather Data"
[in]	controlType	The specific control type for the actuator, such as "Outdoor Dew Point"
[in]	uniqueKey	The unique key for this actuator, such as "Environment"

Returns: The integer handle to an actuator, or -1 if the actuator was not found

Remarks: Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady

◆ getActuatorValue()

Real64 getActuatorValue ( int handle )

Gets the value of an actuator in EnergyPlus.

Actuators are variables in the simulation which can be overridden. This function allows a client to get the last value assigned to the actuator. Although in most applications, the client can just track the last value it assigned to the actuator, there are some occasions (Python Plugins) where multiple scripts could read/write from/to the actuator. In this case, being able to grab the last value that was assigned with setActuatorValue is reasonable.

Parameters

[in] handle The integer handle to the actuator, which can be retrieved using the getActuatorHandle function

Returns: The floating point value last assigned to the actuator in the program, or zero if a handle problem is encountered. If a zero is returned, use the apiErrorFlag function to disambiguate the return value.

Remarks: Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady; getActuatorHandle; setActuatorValue

◆ getConstructionHandle()

int getConstructionHandle ( const char * constructionName )

Returns an index to a construction in the simulation.

Some actuators allow specifying different constructions to allow switchable construction control. This function returns an index that can be used in those functions. The construction is specified by name.

Parameters

[in] constructionName The name of the construction to be looked up.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady; kindOfSim

◆ getInternalVariableHandle()

int getInternalVariableHandle	(	const char *	type,
		const char *	key
	)

Gets a handle to an internal variable.

Internal variables are essentially "static" data – think zone volume or component sizing. Internal variables are identified by a key and type.

Parameters

[in]	type	Internal Variable Type, such as "Zone Floor Area"
[in]	key	Internal Variable Key, such as "Zone 1"

Returns: The integer handle to an independent variable, or -1 if the variable was not found

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady

◆ getInternalVariableValue()

Real64 getInternalVariableValue ( int handle )

Gets the current value of an internal variable.

This function uses the integer handle of a variable and retrieves the static value of the variable.

Parameters

[in] handle The handle id to a variable which can be retrieved using the getInternalVariableHandle function.

Returns: The current value of the variable, in floating point form, or zero if a handle problem is encountered. If a zero is returned, use the apiErrorFlag function to disambiguate the return value.

See also: getInternalVariableHandle

◆ getMeterHandle()

int getMeterHandle ( const char * meterName )

Gets a handle to a meter.

Looks up a handle to a meter within a running simulation. Meters are identified by a single name string.

Parameters

[in] meterName The name of the meter to which a reference is retrieved

Returns: The integer handle to a meter, or -1 if the meter was not found

Remarks: Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady

◆ getMeterValue()

Real64 getMeterValue ( int handle )

Gets the current value of a meter.

Looks up the value of an existing meter within a running simulation. Caution: This function currently returns the instantaneous value of a meter, not the cumulative value. This will change in a future version of the API.

Parameters

[in] handle The handle id of the meter, which can be retrieved using the getMeterHandle function

Returns: The floating point value of a meter at the current time, or zero if a handle problem is encountered. If a zero is returned, use the apiErrorFlag function to disambiguate the return value.

Remarks: Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady; getMeterHandle

◆ getPluginGlobalVariableHandle()

int getPluginGlobalVariableHandle ( const char * name )

Gets a handle to a Python Plugin "Global" variable.

When using Python Plugins, it is sometimes necessary to share data between plugins. These global variables are declared in the input file first, and then can be read/write by any number of plugins. Plugin global variables are identified by name only. This function returns -1 if a match is not found.

Parameters

[in] name The name of the plugin global variable, which is declared in the EnergyPlus input file

Returns: The integer handle to a plugin global variable, or -1 if a match is not found.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.

See also: apiDataFullyReady

◆ getPluginGlobalVariableValue()

Real64 getPluginGlobalVariableValue ( int handle )

Gets the current value of a Python Plugin "Global" variable.

When using Python Plugins, the value of the shared "global" variables can change at any time. This function returns the current value of the variable.

Parameters

[in] handle The handle id to a Python Plugin "Global" variable, which can be retrieved using the getPluginGlobalVariableHandle function.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.

Returns: The current value of the variable, in floating point form, or zero if a handle problem is encountered. If a zero is returned, use the apiErrorFlag function to disambiguate the return value.

See also: apiDataFullyReady; getPluginGlobalVariableHandle

◆ getPluginTrendVariableAverage()

Real64 getPluginTrendVariableAverage	(	int	handle,
		int	count
	)

Gets the average value of a Python Plugin "Trend" variable over a given number of history points.

When using Python Plugins, the average value of the "trend" variable over a number of previous timesteps can be retrieved, up to the number of history terms defined in the input file.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	count	The number of timesteps backward to traverse the trend when returning this value.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getPluginTrendVariableDirection()

Real64 getPluginTrendVariableDirection	(	int	handle,
		int	count
	)

Gets the average trajectory of a Python Plugin "Trend" variable over a given number of history points.

For many control applications, it is useful to know the average trajectory of a trend variable over time. To calculate this, the program will sample the history of the trend over the user-specified number of time history terms, perform a regression, and return the slope of this regression line. If positive, the trend is, on average, increasing, and decreasing if negative.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	count	The number of timesteps backward to traverse the trend when calculate this average direction.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getPluginTrendVariableHandle()

int getPluginTrendVariableHandle ( const char * name )

Gets a handle to a Python Plugin "Trend" variable.

When using Python Plugins, variable history can be stored/accessed using "trend" variables. These trend variables are declared in the input file first, and then can be read/write by any number of plugins. Plugin trend variables are identified by name only. If a trend is not found, this function will return -1.

Parameters

[in] name The name of the plugin trend variable, which is declared in the EnergyPlus input file

Returns: The integer handle to a plugin trend variable, or -1 if a match is not found.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.

See also: apiDataFullyReady

◆ getPluginTrendVariableMax()

Real64 getPluginTrendVariableMax	(	int	handle,
		int	count
	)

Gets the maximum value of a Python Plugin "Trend" variable over a given number of history points.

When using Python Plugins, the maximum value of the "trend" variable over a number of previous timesteps can be retrieved, up to the number of history terms defined in the input file.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	count	The number of timesteps backward to traverse the trend when returning this value.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getPluginTrendVariableMin()

Real64 getPluginTrendVariableMin	(	int	handle,
		int	count
	)

Gets the minimum value of a Python Plugin "Trend" variable over a given number of history points.

When using Python Plugins, the minimum value of the "trend" variable over a number of previous timesteps can be retrieved, up to the number of history terms defined in the input file.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	count	The number of timesteps backward to traverse the trend when returning this value.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getPluginTrendVariableSum()

Real64 getPluginTrendVariableSum	(	int	handle,
		int	count
	)

Gets the summation of a Python Plugin "Trend" variable over a given number of history points.

When using Python Plugins, the summation of the "trend" variable over a number of previous timesteps can be retrieved, up to the number of history terms defined in the input file.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	count	The number of timesteps backward to traverse the trend when returning this value.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getPluginTrendVariableValue()

Real64 getPluginTrendVariableValue	(	int	handle,
		int	timeIndex
	)

Gets the current value of a Python Plugin "Trend" variable at a specific history point.

When using Python Plugins, the value of the "trend" variable can be retrieved from previous timesteps, up to the number of history terms defined in the input file.

Parameters

[in]	handle	The handle id to a Python Plugin "Trend" variable, which can be retrieved using the `getPluginTrendVariableHandle` function.
[in]	timeIndex	The number of timesteps backward to traverse the trend when returning this value.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginTrendVariableHandle

◆ getVariableHandle()

int getVariableHandle	(	const char *	type,
		const char *	key
	)

Gets a handle to a variable.

Looks up a handle to a variable within a running simulation. Variables are identified by a key and type. Variables are only available if they are explicitly listed as Output:Variable objects in the input file, or if API calls to requestVariable to mark this variable as requested prior to a simulation run. This function will return a handle of -1 if a match is not found for this type/key combination.

Parameters

[in]	type	Variable Type, such as "System Node Mass Flow Rate", or "Site Outdoor Air DryBulb Temperature"
[in]	key	Variable Key, such as "Node 32", or "Environment"

Returns: The integer handle to a variable, or -1 if the variable was not found

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady; requestVariable

◆ getVariableValue()

Real64 getVariableValue ( int handle )

Gets the current value of a variable.

This function uses the integer handle of a variable and retrieves the current value of the variable.

Parameters

[in] handle The handle id to a variable which can be retrieved using the getVariableHandle function.

Returns: The current value of the variable, in floating point form, or zero if a handle problem is encountered. If a zero is returned, use the apiErrorFlag function to disambiguate the return value.

See also: getVariableHandle

◆ holidayIndex()

int holidayIndex ( )

Returns the holiday index for the current day of the simulation.

Days in the simulation year can be regular days, in which case this returns zero, or integers 1-N based on holiday definitions in the input.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ hour()

int hour ( )

Returns the current hour of the day in 0-23 form.

The hour within the simulation ranges from 0 for timesteps from 12:00am to 12:59am up to 23 for timesteps from 11:00pm to 11:59pm

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ isRaining()

int isRaining ( )

Returns 0 if it is not currently raining, or 1 if it is currently raining.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ kindOfSim()

int kindOfSim ( )

Returns an integer indicator for the current simulation environment type.

During an EnergyPlus simulation, there are often multiple stages of the simulation run. These include design days followed by a run period most commonly, but there are also sizing simulation environments. The full list of values is:

Design (Sizing) Day = 1
Design (Sizing) RunPeriod = 2
Weather File Run Period = 3
HVAC-Sizing Design Day = 4
HVAC-Sizing Run Period = 5
Weather Data Processing Environment = 6

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ listAllAPIDataCSV()

char* listAllAPIDataCSV ( )

Gets available API data for the current simulation.

This function returns a char * which points to API data in CSV form for the current simulation The data can be easily parsed and then used in subsequent API code.

Remarks: A future version of this will more intelligently return available data in a structured format in memory.

Returns: A char * pointing to a CSV formatted string. This allocates a new char *, and calling clients must free this when done with it!

◆ minutes()

int minutes ( )

Returns the minutes into the hour from 1 to 60.

The minutes into the simulation will return the value for the end of the current system time step. This function returns an integer value, but because the HVAC system time step is constantly adjusted, the end of the system time step may actually occur at a fractional part of a minute. This function truncates the seconds portion during integerization.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ month()

int month ( )

Returns the current month of the simulation, from 1 for January to 12 for December.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ requestVariable()

void requestVariable	(	const char *	type,
		const char *	key
	)

Marks a variable as requested in a simulation.

To optimize memory and cpu usage, the simulation ignores variables not requested in the IDF. This function allows marking variables as used even if they are not in the input file.

Parameters

[in]	type	Variable Type, such as "System Node Mass Flow Rate", or "Site Outdoor Air DryBulb Temperature"
[in]	key	Variable Key, such as "Node 32", or "Environment"

Remarks: This function should be called prior to executing each simulation, as the internal array is cleared when clearing the state of each run.

◆ resetActuator()

void resetActuator ( int handle )

Resets an actuator so EnergyPlus will calculate the value as normal.

When an actuator value is set using setActuatorValue, a flag is set so the actuated value will not be overridden. If the user desires to revert back and let EnergyPlus calculate the actuated value, this function will reset the flag. The user can always set the actuated value again anytime.

Parameters

[in] handle The integer handle to the actuator, which can be retrieved using the getActuatorHandle function

Remarks: When calling this function, a handle index or other problem will cause the function to return 0 but set an error flag. In Plugin work flows, EnergyPlus will abort after returning, in other applications use the apiErrorFlag function to check the error status.; Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady; getActuatorHandle; setActuatorValue

◆ resetErrorFlag()

void resetErrorFlag ( )

Reset the API Error flag.

In most cases, upon an error, the client will want to just abort the calculation. However, in cases where an invalid condition allows a calculation to continue, this function can reset the flag.

◆ setActuatorValue()

void setActuatorValue	(	int	handle,
		Real64	value
	)

Sets the value of an actuator in EnergyPlus.

Actuators are variables in the simulation which can be overridden. Calculations made outside of EnergyPlus are performed and used to update values inside EnergyPlus via actuators. Internally, actuators can alter floating point, integer, and boolean operational values. The API only exposes this set function with a floating point argument. For floating point types, the value is assigned directly. For integer types, the value is rounded using std::lround, which will round to the nearest integer, with the halfway point rounded away from zero (2.5 becomes 3), then cast to a plain integer. For logical values, the original EMS convention is kept, where a value of 1.0 means TRUE, and a value of 0.0 means FALSE – and any other value defaults to FALSE. A small tolerance is applied internally to allow for small floating point roundoff. A value very close to 1.0 will still evaluate to TRUE.

Parameters

[in]	handle	The integer handle to the actuator, which can be retrieved using the `getActuatorHandle` function
[in]	value	The floating point value to be assigned to the actuator in the simulation

Remarks: When calling this function, a handle index or other problem will cause the function to return 0 but set an error flag. In Plugin work flows, EnergyPlus will abort after returning, in other applications use the apiErrorFlag function to check the error status.; Note the behavior of this function is not well-defined until the apiDataFullyReady function returns true

See also: apiDataFullyReady; getActuatorHandle; setActuatorValue

◆ setPluginGlobalVariableValue()

void setPluginGlobalVariableValue	(	int	handle,
		Real64	value
	)

Sets the value of a Python Plugin "Global" variable.

When using Python Plugins, the value of the shared "global" variables can change at any time. This function sets the variable to a new value.

Parameters

[in]	handle	The handle id to a Python Plugin "Global" variable, which can be retrieved using the `getPluginGlobalVariableHandle` function.
[in]	value	The floating point value to be assigned to the global variable

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.; This function only has meaning in the context of Python Plugin workflows, not in regular API workflows.; A handle index or other problem will return 0 and set a flag to cause EnergyPlus to terminate once Python completes.

See also: apiDataFullyReady; getPluginGlobalVariableHandle

◆ sunIsUp()

int sunIsUp ( )

Returns 0 if the sun is down, or 1 if the sun is up.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ systemTimeStep()

Real64 systemTimeStep ( )

Returns the duration of the current HVAC system simulation time step, in fractional hours.

The HVAC time step will vary throughout the simulation as needed to maintain convergence while being cautious about program runtime. This function returns the current value of the time step

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ warmupFlag()

int warmupFlag ( )

Returns the current warmup flag status, 0 if not warming up, 1 if warming up.

During an EnergyPlus simulation, at the beginning of each run period or design day, the first day is repeated until the simulation achieves convergence. This eliminates the dependence on guesses to initial values used when initializing the entire simulation state. It can be useful to ignore operations during warmup, and this flag allows checking that status.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ year()

int year ( )

Returns the current year of the simulation.

A simulation can span multiple years and will always have a "meaningful" year that is either user-defined explicitly, determined based on other inputs in the input file, or chosen as the current year.

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

◆ zoneTimeStep()

Real64 zoneTimeStep ( )

Returns the duration of the current zone simulation time step, in fractional hours.

The zone time step will vary throughout the simulation as needed to maintain convergence while being cautious about program runtime. This function returns the current value of the time step

Remarks: The behavior of this function is not well-defined until the apiDataFullyReady function returns true.

See also: apiDataFullyReady

Functions

Detailed Description

Function Documentation

◆ actualDateTime()

◆ actualTime()

◆ apiDataFullyReady()

◆ apiErrorFlag()

◆ currentEnvironmentNum()

◆ currentTime()

◆ daylightSavingsTimeIndicator()

◆ dayOfMonth()

◆ dayOfWeek()

◆ dayOfYear()

◆ getActuatorHandle()

◆ getActuatorValue()

◆ getConstructionHandle()

◆ getInternalVariableHandle()

◆ getInternalVariableValue()

◆ getMeterHandle()

◆ getMeterValue()

◆ getPluginGlobalVariableHandle()

◆ getPluginGlobalVariableValue()

◆ getPluginTrendVariableAverage()

◆ getPluginTrendVariableDirection()

◆ getPluginTrendVariableHandle()

◆ getPluginTrendVariableMax()

◆ getPluginTrendVariableMin()

◆ getPluginTrendVariableSum()

◆ getPluginTrendVariableValue()

◆ getVariableHandle()

◆ getVariableValue()

◆ holidayIndex()

◆ hour()

◆ isRaining()

◆ kindOfSim()

◆ listAllAPIDataCSV()

◆ minutes()

◆ month()

◆ requestVariable()

◆ resetActuator()

◆ resetErrorFlag()

◆ setActuatorValue()

◆ setPluginGlobalVariableValue()

◆ sunIsUp()

◆ systemTimeStep()

◆ warmupFlag()

◆ year()

◆ zoneTimeStep()