Skip to content

Python Plugin System

5 object types from idfpy.models.python_plugins · EnergyPlus 26.2

Object Summary
PythonPlugin:Instance A single plugin to be executed during the simulation, which can contain multiple calling points for the same …
PythonPlugin:OutputVariable This object sets up an EnergyPlus output variable from a Python Plugin variable
PythonPlugin:SearchPaths Add directories to the search path for Python plugin modules The directory containing the EnergyPlus …
PythonPlugin:TrendVariable This object sets up a Python plugin trend variable from an Python plugin variable A trend variable logs …
PythonPlugin:Variables This object defines name identifiers for custom Python Plugin variable data that should be shared among all …

PythonPlugin:Instance

from idfpy.models import PythonPluginInstance

A single plugin to be executed during the simulation, which can contain multiple calling points for the same class instance by overriding multiple calling point methods.

Field Type Default Details
name
Name required		 string This is the name used to represent this plugin in traditional EMS fields
run_during_warmup_days
Run During Warmup Days		 choice No If this field is enabled, the plugin will be executed during warmup days, otherwise it will only be executed once warmup is completed and the actual run period begins
One of No, Yes
python_module_name
Python Module Name required		 string This is the name of the Python file, without a file extension. For "plugin_b.py", use just "plugin_b". The Python plugin file must be on the plugin system search path to be found during a simulation Additional directories can be added to the search path using the PythonPlugin:SearchPaths object
plugin_class_name
Plugin Class Name required		 string This is the name of the class to be executed as a plugin during a simulation The class must inherit the EnergyPlusPlugin base class
Referenced by 5 object types

AirTerminal:SingleDuct:UserDefined, Coil:UserDefined, PlantComponent:UserDefined, PlantEquipmentOperation:UserDefined, ZoneHVAC:ForcedAir:UserDefined

PythonPlugin:OutputVariable

from idfpy.models import PythonPluginOutputVariable

This object sets up an EnergyPlus output variable from a Python Plugin variable

Field Type Default Details
name
Name required		 string
python_plugin_variable_name
Python Plugin Variable Name required		 string Must be listed in the PythonPlugin:Variables object
type_of_data_in_variable
Type of Data in Variable required		 choice If Metered is selected, the variable is automatically set to a "Summed" type, and the Resource Type, Group Type, and End-Use Subcategory fields on this object are required
One of Averaged, Metered, Summed
update_frequency
Update Frequency required		 choice One of SystemTimestep, ZoneTimestep
units
Units		 string optional but will result in dimensionless units for blank EnergyPlus units are standard SI units
resource_type
Resource Type		 choice This field is optional for regular output variables with "Type of Data in Variable" set to either Averaged or Summed. For Metered variables, this field is required. Choose the type of fuel, water, electricity, pollution or heat rate that should be metered.
One of Coal, CondensateWaterCollected, Diesel, DistrictCooling, DistrictHeatingSteam, DistrictHeatingWater, Electricity, ElectricityProducedOnSite, EnergyTransfer, FuelOilNo1, FuelOilNo2, Gasoline, MainsWaterSupply, NaturalGas, OnSiteWaterProduced, OtherFuel1, OtherFuel2, Propane, RainWaterCollected, SolarAirHeating, SolarWaterHeating, WaterUse, WellWaterDrawn
group_type
Group Type		 choice This field is optional for regular output variables with "Type of Data in Variable" set to either Averaged or Summed. For Metered variables, this field is required. Choose a general classification, building (internal services), HVAC (air systems), or plant (hydronic systems), or system
One of Building, HVAC, Plant, System
end_use_category
End-Use Category		 choice This field is optional for regular output variables with "Type of Data in Variable" set to either Averaged or Summed. For Metered variables, this field is required. Choose how the metered output should be classified for end-use category
One of Baseboard, Boilers, Chillers, Cooling, CoolingCoils, ExteriorEquipment, ExteriorLights, Fans, HeatRecovery, HeatRecoveryForCooling, HeatRecoveryForHeating, HeatRejection, Heating, HeatingCoils, Humidifier, InteriorEquipment, InteriorLights, OnSiteGeneration, Pumps, Refrigeration, WaterSystems
end_use_subcategory
End-Use Subcategory		 string This field is always optional. For regular output variables with "Type of Data in Variable" set to either Averaged or Summed, this field is completely ignored. For Metered variables, this field is optional, but allows custom categorization of the end-uses in the ABUPS End Uses by Subcategory table. Enter a user-defined subcategory for this metered output

PythonPlugin:SearchPaths

from idfpy.models import PythonPluginSearchPaths unique extensible

Add directories to the search path for Python plugin modules The directory containing the EnergyPlus executable file is automatically added so that the Python interpreter can find the packaged up pyenergyplus Python package. By default, the current working directory and input file directory are also added to the search path. However, this object allows modifying this behavior. With this object, searching these directories can be disabled, and users can add supplemental search paths that point to libraries of plugin scripts.

Field Type Default Details
name
Name required		 string
add_current_working_directory_to_search_path
Add Current Working Directory to Search Path		 choice Yes Adding the current working directory allows Python to find plugin scripts in the current directory.
One of No, Yes
add_input_file_directory_to_search_path
Add Input File Directory to Search Path		 choice Yes Enabling this will allow Python to find plugin scripts in the same directory as the running input file, even if that is not the current working directory.
One of No, Yes
add_epin_environment_variable_to_search_path
Add epin Environment Variable to Search Path		 choice Yes The "epin" environment variable is set by some EnergyPlus interfaces in order to let EnergyPlus find external files in special locations. If this is enabled, and that variable is set, the value of the variable will be added to the Python search path.
One of No, Yes
py_search_paths list Each item: search_path

PythonPlugin:TrendVariable

from idfpy.models import PythonPluginTrendVariable

This object sets up a Python plugin trend variable from an Python plugin variable A trend variable logs values across timesteps

Field Type Default Details
name
Name required		 string
name_of_a_python_plugin_variable
Name of a Python Plugin Variable required		 string
number_of_timesteps_to_be_logged
Number of Timesteps to be Logged required		 integer Range: ≥ 1

PythonPlugin:Variables

from idfpy.models import PythonPluginVariables extensible

This object defines name identifiers for custom Python Plugin variable data that should be shared among all running Python Plugins.

Field Type Default Details
name
Name required		 string This object name is purely for reporting and diagnostics
global_py_vars list Each item: variable_name