Data Transfer API¶
-
class
datatransfer.DataExchange(api: <ctypes.LibraryLoader object at 0x7fdff3d3bb70>, running_as_python_plugin: bool = False)[source]¶ Bases:
objectThis API class enables data transfer between EnergyPlus and a client. Output variables and meters are treated as “sensor” data. A client should get a handle (integer) using one of the worker methods then make calls to get data using that handle. Some specific variables in EnergyPlus are controllable as actuators. These work the same way, in that a client should get an integer handle to an actuator and then use the workers to set the value on the actuator. There are also some static data members in EnergyPlus that are exposed as “internal” variables. These variables hold static data such as zone floor area and volume, so they do not change during a simulation, but are constant once they are assigned. Even with this difference, the variables are still handled the same way, by getting an integer handle and then accessing the data using that handle.
This data transfer class is used in one of two workflows:
When a outside tool is already running EnergyPlus using the Runtime API, and data transfer is to be made during callback functions. In this case, the script should create a DataTransfer API class by calling the data_transfer method on the main API class, never trying to create this class directly.
When a Python script is used in the EnergyPlus Python Plugin System, and the user runs the EnergyPlus binary. In this case, the plugin may need access to state data to make control decisions, and this class enables that. The plugin base class automatically creates an instance of this class, so client plugins that inherit that class will have a self.transfer instance of this class available, and should not attempt to create another one.
In the Python Plugin case, the client Python code may make use of the methods to get/set plugin global variables, but only in the Python Plugin cases. For the outside tool API usage, plugin global variables are not available, and data should be shared in the outside calling code.
-
actual_date_time() → int[source]¶ Gets a simple sum of the values of the date/time function. Could be used in random seeding.
- Returns
Integer value of the date/time function.
-
actual_time() → int[source]¶ Gets a simple sum of the values of the time part of the date/time function. Could be used in random seeding.
- Returns
Integer value of time portion of the date/time function.
-
api_data_fully_ready() → bool[source]¶ Check whether the data exchange API is ready. Handles to variables, actuators, and other data are not reliably defined prior to this being true.
- Returns
Returns a boolean value to indicate whether variables, actuators, and other data are ready for access.
-
api_error_flag() → bool[source]¶ Check whether the error flag has been activated. A number of functions will return 0 in erroneous situations, and this function allows for disambiguation between valid zero return values and the error condition.
- Returns
Returns true if the error flag was activated during prior calculations.
-
current_environment_num() → int[source]¶ Gets the current environment index. EnergyPlus environments are design days, run periods, etc. This function is only expected to be useful in very specialized applications where you control the environment order carefully.
- Returns
The current environment number.
-
current_time() → ctypes.c_double[source]¶ Get the current time of day in hours, where current time represents the end time of the current time step.
- Returns
A floating point representation of the current time in hours
-
day_of_month() → int[source]¶ Get the current day of month (1-31)
- Returns
An integer day of the month (1-31)
-
day_of_week() → int[source]¶ Get the current day of the week (1-7)
- Returns
An integer day of week (1-7)
-
day_of_year() → int[source]¶ Get the current day of the year (1-366)
- Returns
An integer day of the year (1-366)
-
daylight_savings_time_indicator() → bool[source]¶ Get the current daylight savings time indicator as a logical value. The C API returns an integer where 1 is yes and 0 is no, this simply wraps that with a bool conversion.
- Returns
A boolean DST indicator for the current time.
-
get_actuator_handle(component_type: Union[str, bytes], control_type: Union[str, bytes], actuator_key: Union[str, bytes]) → int[source]¶ Get a handle to an available actuator in a running simulation.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
component_type – The actuator category, e.g. “Weather Data”
control_type – The name of the actuator to retrieve, e.g. “Outdoor Dew Point”
actuator_key – The instance of the variable to retrieve, e.g. “Environment”
- Returns
An integer ID for this output variable, or -1 if one could not be found.
-
get_actuator_value(actuator_handle: int) → ctypes.c_double[source]¶ Gets the most recent value of an actuator. In some applications, actuators are altered by multiple scripts, and this allows getting the most recent value.
- Parameters
actuator_handle – An integer returned from the get_actuator_handle function.
- Returns
A floating point of the actuator value. For boolean actuators returns 1.0 for true and 0.0 for false. Returns zero if the handle is invalid. Use the api_error_flag function to disambiguate between valid zero returns and error states.
-
get_construction_handle(var_name: Union[str, bytes]) → int[source]¶ Get a handle to a constructions in a running simulation. This is only used for Python Plugin applications!
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.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Returns
An integer ID for this construction, or -1 if one could not be found.
-
get_global_handle(var_name: Union[str, bytes]) → int[source]¶ Get a handle to a global variable in a running simulation. This is only used for Python Plugin applications!
Global variables are used as a way to share data between running Python Plugins. First a global variable must be declared in the input file using the PythonPlugin:GlobalVariables object. Once a name has been declared, it can be accessed in the Plugin by getting a handle to the variable using this get_global_handle function, then using the get_global_value and set_global_value functions as needed. Note all global variables are floating point values.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
var_name – The name of the global variable to retrieve, this name must be listed in the IDF object: PythonPlugin:GlobalVariables
- Returns
An integer ID for this global variable, or -1 if one could not be found.
-
get_global_value(handle: int) → ctypes.c_double[source]¶ Get the current value of a plugin global variable in a running simulation. This is only used for Python Plugin applications!
Global variables are used as a way to share data between running Python Plugins. First a global variable must be declared in the input file using the PythonPlugin:GlobalVariables object. Once a name has been declared, it can be accessed in the Plugin by getting a handle to the variable using the get_global_handle function, then using this get_global_value and the set_global_value functions as needed. Note all global variables are floating point values.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
handle – An integer returned from the get_global_handle function.
- Returns
Floating point representation of the global variable value
-
get_internal_variable_handle(variable_type: Union[str, bytes], variable_key: Union[str, bytes]) → int[source]¶ Get a handle to an internal variable in a running simulation.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
variable_type – The name of the variable to retrieve, e.g. “Zone Air Volume”, or “Zone Floor Area”
variable_key – The instance of the variable to retrieve, e.g. “Zone 1”
- Returns
An integer ID for this output variable, or -1 if one could not be found.
-
get_internal_variable_value(variable_handle: int) → ctypes.c_double[source]¶ Get the value of an internal variable in a running simulation. The get_internal_variable_handle function is first used to get a handle to the variable by name. Then once the handle is retrieved, it is passed into this function to then get the value of the variable.
- Parameters
variable_handle – An integer returned from the get_internal_variable_handle function.
- Returns
Floating point representation of the internal variable value. Returns zero if the handle is invalid. Use the api_error_flag function to disambiguate between valid zero returns and error states.
-
get_meter_handle(meter_name: Union[str, bytes]) → int[source]¶ Get a handle to a meter in a running simulation.
The meter name passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the meter name passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
meter_name – The name of the variable to retrieve, e.g. “Electricity:Facility”, or “Fans:Electricity”
- Returns
An integer ID for this meter, or -1 if one could not be found.
-
get_meter_value(meter_handle: int) → ctypes.c_double[source]¶ Get the current value of a meter in a running simulation. The get_meter_handle function is first used to get a handle to the meter by name. Then once the handle is retrieved, it is passed into this function to then get the value of the meter.
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
meter_handle – An integer returned from the get_meter_handle function.
- Returns
Floating point representation of the current meter value. Returns zero if the handle is invalid. Use the api_error_flag function to disambiguate between valid zero returns and error states.
-
get_trend_average(trend_handle: int, count: int) → ctypes.c_double[source]¶ Get the average of a plugin trend variable over a specific history set. The count argument specifies how many time steps to go back in the trend history. A value of 1 indicates averaging just the most recent value. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
count – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_trend_direction(trend_handle: int, count: int) → ctypes.c_double[source]¶ Get the trajectory of a plugin trend variable over a specific history set. The count argument specifies how many time steps to go back in the trend history. A value of 1 indicates sweeping just the most recent value. A linear regression is performed over the swept values and the slope of the regression line is returned as a representation of the average trajectory over this range. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
count – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_trend_handle(trend_var_name: Union[str, bytes]) → int[source]¶ Get a handle to a trend variable in a running simulation. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using this get_trend_handle function, then using the other trend variable worker functions as needed.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
trend_var_name – The name of the global variable to retrieve, this name must match the name of a PythonPlugin:TrendVariable IDF object.
- Returns
An integer ID for this trend variable, or -1 if one could not be found.
-
get_trend_max(trend_handle: int, count: int) → ctypes.c_double[source]¶ Get the maximum of a plugin trend variable over a specific history set. The count argument specifies how many time steps to go back in the trend history. A value of 1 indicates sweeping just the most recent value. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
count – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_trend_min(trend_handle: int, count: int) → ctypes.c_double[source]¶ Get the minimum of a plugin trend variable over a specific history set. The count argument specifies how many time steps to go back in the trend history. A value of 1 indicates sweeping just the most recent value. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
count – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_trend_sum(trend_handle: int, count: int) → ctypes.c_double[source]¶ Get the summation of a plugin trend variable over a specific history set. The count argument specifies how many time steps to go back in the trend history. A value of 1 indicates sweeping just the most recent value. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
count – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_trend_value(trend_handle: int, time_index: int) → ctypes.c_double[source]¶ Get the value of a plugin trend variable at a specific history point. The time_index argument specifies how many time steps to go back in the trend history. A value of 1 indicates taking the most recent value. The value of time_index must be less than or equal to the number of history terms specified in the matching PythonPlugin:TrendVariable object declaration in the input file. This is only used for Python Plugin applications!
Trend variables are used as a way to track history of a PythonPlugin:Variable over time. First a trend variable must be declared in the input file using the PythonPlugin:TrendVariable object. Once a variable has been declared there, it can be accessed in the Plugin by getting a handle to the variable using the get_trend_handle function, then using the other trend variable worker functions as needed.
- Parameters
trend_handle – An integer returned from the get_trend_handle function.
time_index – The number of time steps to search back in history to evaluate this function.
- Returns
Floating point value representation of the specific evaluation.
-
get_variable_handle(variable_name: Union[str, bytes], variable_key: Union[str, bytes]) → int[source]¶ Get a handle to an output variable in a running simulation.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
variable_name – The name of the variable to retrieve, e.g. “Site Outdoor Air DryBulb Temperature”, or “Fan Air Mass Flow Rate”
variable_key – The instance of the variable to retrieve, e.g. “Environment”, or “Main System Fan”
- Returns
An integer ID for this output variable, or -1 if one could not be found.
-
get_variable_value(variable_handle: int) → ctypes.c_double[source]¶ Get the current value of a variable in a running simulation. The get_variable_handle function is first used to get a handle to the variable by name. Then once the handle is retrieved, it is passed into this function to then get the value of the variable.
- Parameters
variable_handle – An integer returned from the get_variable_handle function.
- Returns
Floating point representation of the current variable value. Returns zero if the handle is invalid. Use the api_error_flag function to disambiguate between valid zero returns and error states.
-
holiday_index() → int[source]¶ Gets a flag for the current day holiday type: 0 is no holiday, 1 is holiday type #1, etc.
- Returns
An integer indicator for current day holiday type.
-
hour() → int[source]¶ Get the current hour of the simulation (0-23)
- Returns
An integer hour of the day (0-23)
-
is_raining() → bool[source]¶ Gets a flag for whether the it is currently raining. The C API returns an integer where 1 is yes and 0 is no, this simply wraps that with a bool conversion.
- Returns
A boolean indicating whether it is currently raining.
-
list_available_api_data_csv() → bytes[source]¶ Lists out all API data stuff in an easily parseable CSV form
- Returns
Returns a raw bytes CSV representation of the available API data
-
minutes() → int[source]¶ Get the current minutes into the hour (1-60)
- Returns
An integer number of minutes into the current hour (1-60)
-
month() → int[source]¶ Get the current month of the simulation (1-12)
- Returns
An integer month (1-12)
-
request_variable(variable_name: Union[str, bytes], variable_key: Union[str, bytes]) → None[source]¶ Request output variables so they can be accessed during a simulation.
In EnergyPlus, not all variables are available by default. If they were all available, there would be a terrible memory impact. Instead, only requested and necessary variables are kept in memory. When running EnergyPlus as a program, including when using Python Plugins, variables are requested through input objects. When running EnergyPlus as a library, variables can also be requested through this function call. This function has the same signature as the get_variable_handle function, which is used to then request the ID of a variable once the simulation has begun. NOTE: Variables should be requested before each run of EnergyPlus, as the internal array is cleared when clearing the state of each run.
- Parameters
variable_name – The name of the variable to retrieve, e.g. “Site Outdoor Air DryBulb Temperature”, or “Fan Air Mass Flow Rate”
variable_key – The instance of the variable to retrieve, e.g. “Environment”, or “Main System Fan”
- Returns
Nothing
-
reset_actuator(actuator_handle: int) → None[source]¶ Resets the actuator internally to EnergyPlus. This allows subsequent calculations to be used for the actuator instead of the externally set actuator value.
- Parameters
actuator_handle – An integer returned from the get_actuator_handle function.
- Returns
Nothing
-
reset_api_error_flag() → None[source]¶ Resets the error flag for API calls. A number of functions will return 0 in erroneous situations, but activate an error flag. In certain work flows, it may be useful to reset this error flag (unit testing, etc.). This function allows resetting it to false.
-
set_actuator_value(actuator_handle: int, actuator_value: ctypes.c_double) → None[source]¶ Sets the value of an actuator in a running simulation. The get_actuator_handle function is first used to get a handle to the actuator by name. Then once the handle is retrieved, it is passed into this function, along with the value to assign, to then set the value of the actuator. 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 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 round-off. A value very close to 1.0 will still evaluate to TRUE.
- Parameters
actuator_handle – An integer returned from the get_actuator_handle function.
actuator_value – The floating point value to assign to the actuator
- Returns
Nothing
-
set_global_value(handle: int, value: float) → None[source]¶ Set the current value of a plugin global variable in a running simulation. This is only used for Python Plugin applications!
Global variables are used as a way to share data between running Python Plugins. First a global variable must be declared in the input file using the PythonPlugin:GlobalVariables object. Once a name has been declared, it can be accessed in the Plugin by getting a handle to the variable using the get_global_handle function, then using the get_global_value and this set_global_value functions as needed. Note all global variables are floating point values.
The arguments passed into this function do not need to be a particular case, as the EnergyPlus API automatically converts values to upper-case when finding matches to internal variables in the simulation.
Note also that the arguments passed in here can be either strings or bytes, as this wrapper handles conversion as needed.
- Parameters
handle – An integer returned from the get_global_handle function.
value – Floating point value to assign to the global variable
-
sun_is_up() → bool[source]¶ Gets a flag for whether the sun is currently up. The C API returns an integer where 1 is yes and 0 is no, this simply wraps that with a bool conversion.
- Returns
A boolean indicating whether the sun is currently up.
-
system_time_step() → ctypes.c_double[source]¶ Gets the current system time step value in EnergyPlus. The system time step is variable and fluctuates during the simulation.
- Returns
The current system time step in fractional hours.
-
warmup_flag() → bool[source]¶ Gets a flag for whether the warmup flag is currently on, signaling that EnergyPlus is still in the process of converging on warmup days. The C API returns an integer where 1 is yes and 0 is no, this simply wraps that with a bool conversion.
- Returns
A boolean indicating whether the warmup flag is on.