Data Transfer API

class datatransfer.DataExchange(api: <ctypes.LibraryLoader object at 0x7f7529afe110>, running_as_python_plugin: bool = False)[source]

Bases: object

This 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 an 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.api.exchange instance of this class available, and should not attempt to create another one.

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.

class APIDataExchangePoint(_what: str, _name: str, _key: str, _type: str)[source]

Bases: object

A class of string members that describe a single API exchange point. The exchange described in this class could represent output variables, output meters, actuators, and more. The “type” member variable can be used to filter a specific type.

key: str: This represents the unique ID for this exchange point. In the example of the chiller output variable, this could be “Chiller 1”. This is not used for meters

name: str: This represents the name of the entry point, not the name of the specific instance of the entry point. Some examples of this name could be “Chiller Heat Transfer Rate” – which could be available for multiple chillers.

type: str: This represents the “type” of exchange for this exchange point. This is only used for actuators, and represents the control actuation. For a node setpoint actuation, this could be “temperature” or “humidity”, for example.

what: str: This variable will hold the basic type of API data point, in string form. This can be one of the following: “Actuator”, “InternalVariable”, “PluginGlobalVariable”, “PluginTrendVariable”, “OutputMeter”, or “OutputVariable”. Once the full list of data exchange points are returned from a call to get_api_data, this can be used to quickly filter down to a specific type.

actual_date_time(state: c_void_p) → int[source]

Gets a simple sum of the values of the date/time function. Could be used in random seeding.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Integer value of the date/time function.

actual_time(state: c_void_p) → int[source]

Gets a simple sum of the values of the time part of the date/time function. Could be used in random seeding.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Integer value of time portion of the date/time function.

api_data_fully_ready(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Returns a boolean value to indicate whether variables, actuators, and other data are ready for access.

api_error_flag(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Returns true if the error flag was activated during prior calculations.

calendar_year(state: c_void_p) → int[source]

Get the “current” calendar year of the simulation.

Only valid for weather file run periods.

All simulations operate at a real year, either user specified or automatically selected by EnergyPlus based on other data (start day of week + leap year option).

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer year (2020, for example)

current_environment_num(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: The current environment number.

current_sim_time(state: c_void_p) → float[source]

Returns the cumulative simulation time from the start of the environment, in hours

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Value of the simulation time from the start of the environment in fractional hours

current_time(state: c_void_p) → float[source]

Get the current time of day in hours, where current time represents the end time of the current time step.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: A floating point representation of the current time in hours

day_of_month(state: c_void_p) → int[source]

Get the current day of month (1-31)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer day of the month (1-31)

day_of_week(state: c_void_p) → int[source]

Get the current day of the week (1-7)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer day of week (1-7)

day_of_year(state: c_void_p) → int[source]

Get the current day of the year (1-366)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer day of the year (1-366)

daylight_savings_time_indicator(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: A boolean DST indicator for the current time.

get_actuator_handle(state: c_void_p, component_type: str | bytes, control_type: str | bytes, actuator_key: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, actuator_handle: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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_api_data(state: c_void_p) → List[APIDataExchangePoint][source]

Returns a nicely formed list of API data exchange points available in the current simulation.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Returns a Python list of APIDataExchangePoint instances, which can be filtered to inspect exchanges.

get_construction_handle(state: c_void_p, var_name: str | bytes) → int[source]

Get a handle to a constructions in a running 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.

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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
var_name – Name of the construction to look up

Returns:

An integer ID for this construction, or -1 if one could not be found.

get_global_handle(state: c_void_p, var_name: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, handle: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
handle – An integer returned from the get_global_handle function.

Returns:

Floating point representation of the global variable value

get_internal_variable_handle(state: c_void_p, variable_type: str | bytes, variable_key: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, variable_handle: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, meter_name: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, meter_handle: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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_num_nodes_in_cond_fd_surf_layer(state: c_void_p, surface_name: str | bytes, material_name: str | bytes) → None[source]

Get the number of nodes in CondFD surface layer.

Parameters:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
surface_name – The name of the surface as defined in the input file, such as “ZN001:Surf001”.
material_name – The name of the surface material layer as defined in the input file, such as “GypsumBoardLayer”.

Returns:

Nothing

get_object_names(state: c_void_p, object_type_name: str | bytes) → List[str][source]: Gets the instance names for a given object type in the current input file :param state: An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state(). :param object_type_name: The object type name as defined in the schema, such as “Zone” or “Chiller:Electric” :return: A list of strings represented the names of the objects in the input file

get_trend_average(state: c_void_p, trend_handle: int, count: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_handle: int, count: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_var_name: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_handle: int, count: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_handle: int, count: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_handle: int, count: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, trend_handle: int, time_index: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, variable_name: str | bytes, variable_key: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, variable_handle: int) → float[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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p) → int[source]

Gets a flag for the current day holiday type: 0 is no holiday, 1 is holiday type #1, etc.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer indicator for current day holiday type.

hour(state: c_void_p) → int[source]

Get the current hour of the simulation (0-23)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer hour of the day (0-23)

is_raining(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: A boolean indicating whether it is currently raining.

kind_of_sim(state: c_void_p) → int[source]

Gets the current environment number.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Integer value of current environment.

list_available_api_data_csv(state: c_void_p) → bytes[source]

Lists out all API data stuff in an easily parseable CSV form

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: Returns a raw bytes CSV representation of the available API data

minutes(state: c_void_p) → int[source]

Get the current minutes into the hour (1-60)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer number of minutes into the current hour (1-60)

month(state: c_void_p) → int[source]

Get the current month of the simulation (1-12)

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer month (1-12)

num_time_steps_in_hour(state: c_void_p) → int[source]

Returns the number of zone time steps in an hour, which is currently a constant value throughout a simulation.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: An integer representation of the number of time steps in an hour

request_variable(state: c_void_p, variable_name: str | bytes, variable_key: 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
actuator_handle – An integer returned from the get_actuator_handle function.

Returns:

Nothing

reset_api_error_flag(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

set_actuator_value(state: c_void_p, actuator_handle: int, actuator_value: float) → 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:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
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(state: c_void_p, 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.

Parameters:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
handle – An integer returned from the get_global_handle function.
value – Floating point value to assign to the global variable

sun_is_up(state: c_void_p) → 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.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: A boolean indicating whether the sun is currently up.

system_time_step(state: c_void_p) → float[source]

Gets the current system time step value in EnergyPlus. The system time step is variable and fluctuates during the simulation.

Parameters:: state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().
Returns:: The current system time step in fractional hours.

today_weather_albedo_at_time(state: c_void_p, hour: int, time_step_number: int) → float[source]