def set_global_value(self, handle: int, value: float) -> None:
"""
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.
:param handle: An integer returned from the `get_global_handle` function.
:param value: Floating point value to assign to the global variable
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"set_global_handle is only available as part of a Python Plugin workflow"
)
self.api.setPluginGlobalVariableValue(handle, value)
def get_trend_handle(self, trend_var_name: Union[str, bytes]) -> int:
"""
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.
:param trend_var_name: The name of the global variable to retrieve, this name must match the name of a
`PythonPlugin:TrendVariable` IDF object.
:return: An integer ID for this trend variable, or -1 if one could not be found.
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_trend_handle is only available as part of a Python Plugin workflow"
)
if isinstance(trend_var_name, str):
trend_var_name = trend_var_name.encode('utf-8')
return self.api.getPluginTrendVariableHandle(trend_var_name)
def get_global_handle(self, var_name: Union[str, bytes]) -> int:
"""
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.
:param var_name: The name of the global variable to retrieve, this name must be listed in the IDF object:
`PythonPlugin:GlobalVariables`
:return: An integer ID for this global variable, or -1 if one could not be found.
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_global_handle is only available as part of a Python Plugin workflow"
)
if isinstance(var_name, str):
var_name = var_name.encode('utf-8')
return self.api.getPluginGlobalVariableHandle(var_name)
def get_trend_value(self, trend_handle: int, time_index: int) -> RealEP:
"""
:param trend_handle:
:param time_index:
:return:
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_trend_value is only available as part of a Python Plugin workflow"
)
return self.api.getPluginTrendVariableValue(trend_handle, time_index)
def get_trend_handle(self, trend_var_name: Union[str, bytes]) -> int:
"""
:param trend_var_name:
:return:
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_trend_handle is only available as part of a Python Plugin workflow"
)
if isinstance(trend_var_name, str):
trend_var_name = trend_var_name.encode('utf-8')
return self.api.getPluginTrendVariableHandle(trend_var_name)
def get_trend_sum(self, trend_handle: int, count: int) -> RealEP:
"""
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.
:param trend_handle: An integer returned from the `get_trend_handle` function.
:param count: The number of time steps to search back in history to evaluate this function.
:return: Floating point value representation of the specific evaluation.
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_trend_sum is only available as part of a Python Plugin workflow"
)
return self.api.getPluginTrendVariableSum(trend_handle, count)
def get_construction_handle(self, var_name: Union[str, bytes]) -> int:
"""
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.
:return: An integer ID for this construction, or -1 if one could not be found.
"""
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_construction_handle is only available as part of a Python Plugin workflow"
)
if isinstance(var_name, str):
var_name = var_name.encode('utf-8')
return self.api.getConstructionHandle(var_name)
def get_trend_direction(self, trend_handle: int, count: int) -> RealEP:
if not self.running_as_python_plugin:
raise EnergyPlusException(
"get_trend_direction is only available as part of a Python Plugin workflow"
)
return self.api.getPluginTrendVariableDirection(trend_handle, count)