EnergyPlus

frads.EnergyPlusSetup

EnergyPlusSetup(epmodel, weather_file=None, enable_radiance=False)

EnergyPlus Simulation Setup.

Attributes:

Name	Type	Description
api		EnergyPlusAPI object
epw		Weather file path
actuator_handles		Actuator Handles
variable_handles		Variable handles
construction_handles		Construction Handles
actuators		List of actuators available
model		EnergyPlusModel object
state		EnergyPlusState object
handles		Handles object

Class for setting up and running EnergyPlus simulations.

Parameters:

Name	Type	Description	Default
epmodel	EnergyPlusModel	EnergyPlusModel object	required
weather_file	Optional[str]	Weather file path. (default: None)	None
enable_radiance	bool	If True, enable Radiance for Three-Phase Method. (default: False)	False

Examples:

>>> epsetup = EnergyPlusSetup(epmodel, weather_file="USA_CA_Oakland.Intl.AP.724930_TMY3.epw")

actuate

actuate(component_type, name, key, value)

Set or update the operating value of an actuator in the EnergyPlus model.

If actuator has not been requested previously, it will be requested. Set the actuator value to the value specified.

Parameters:

Name	Type	Description	Default
component_type	str	The actuator category, e.g. "Weather Data"	required
name	str	The name of the actuator to retrieve, e.g. "Outdoor Dew Point"	required
key	str	The instance of the variable to retrieve, e.g. "Environment"	required
value	float	The value to set the actuator to	required

Raises:

Type	Description
ValueError	If the actuator is not found

Examples:

>>> epsetup.actuate("Weather Data", "Outdoor Dew Point", "Environment", 10)

actuate_cfs_state

actuate_cfs_state(window, cfs_state)

Set construction state for a surface.

Parameters:

Name	Type	Description	Default
window	str	The name of the surface to set the cfs state for.	required
cfs_state	str	The name of the complex fenestration system (CFS) state to set the surface to.	required

Examples:

>>> epsetup.actuate_construction_state("window1", "cfs1")

actuate_cooling_setpoint

actuate_cooling_setpoint(zone, value)

Set cooling setpoint for a zone.

Parameters:

Name	Type	Description	Default
zone	str	The name of the zone to set the cooling setpoint for.	required
value	float	The value to set the cooling setpoint to.	required

Examples:

>>> epsetup.actuate_cooling_setpoint("zone1", 24)

actuate_heating_setpoint

actuate_heating_setpoint(zone, value)

Set heating setpoint for a zone.

Parameters:

Name	Type	Description	Default
zone	str	The name of the zone to set the heating setpoint for.	required
value	float	The value to set the heating setpoint to.	required

Example

epsetup.actuate_cooling_setpoint("zone1", 20)

actuate_lighting_power

actuate_lighting_power(light, value)

Set lighting power for a zone.

Parameters:

Name	Type	Description	Default
light	str	The name of the lighting object to set the lighting power for.	required
value	float	The value to set the lighting power to.	required

Examples:

>>> epsetup.actuate_lighting_power("zone1", 1000)

calculate_edgps

calculate_edgps(zone, cfs_name)

Calculate enhanced simplified daylight glare probability in a zone. The view is positioned at the center of the zone with direction facing the windows, weighted by the window area.

Parameters:

Name	Type	Description	Default
zone	str	Name of the zone.	required
cfs_name	Dict[str, str]	Dictionary of windows and their complex fenestration state.	required

Returns:

Type	Description
tuple[float, float]	Enhanced simplified daylight glare probability.

Raises:

Type	Description
KeyError	If zone not found in model.

Examples:

>>> epsetup.calculate_edgps("Zone1", "CFS1")

calculate_wpi

calculate_wpi(zone, cfs_name)

Calculate workplane illuminance in a zone.

Parameters:

Name	Type	Description	Default
zone	str	Name of the zone.	required
cfs_name	Dict[str, str]	Name of the complex fenestration state.	required

Returns:

Type	Description
ndarray	Workplane illuminance in lux.

Raises:

Type	Description
ValueError	If zone not found in model.

Examples:

>>> epsetup.calculate_wpi("Zone1", "CFS1")

get_cfs_state

get_cfs_state(window)

Return the current complex fenestration state with input window name

Parameters:

Name	Type	Description	Default
window	str	name of the window	required

Returns:

Type	Description
str	name of the cfs state

get_datetime

get_datetime()

Get the current date and time from EnergyPlus Run time datatime format with iso_8601_format = yes. hour 0-23, minute 10 - 60 v23.2.0

Returns:

Type	Description
datetime	datetime object

get_diffuse_horizontal_irradiance

get_diffuse_horizontal_irradiance()

Get diffuse horizontal irradiance.

Returns:

Type	Description
float	Diffuse horizontal irradiance in W/m2.

Example

epsetup.get_diffuse_horizontal_irradiance()

get_direct_normal_irradiance

get_direct_normal_irradiance()

Get direct normal irradiance.

Returns:

Type	Description
float	Direct normal irradiance in W/m2.

Examples:

>>> epsetup.get_direct_normal_irradiance()

get_variable_value

get_variable_value(name, key)

Get the value of a variable in the EnergyPlus model during runtime. The variable must be requested before it can be retrieved. If this method is called in a callback function, the variable will be requested automatically. So avoid having other methods called get_variable_value in the callback function.

Parameters:

Name	Type	Description	Default
name	str	The name of the variable to retrieve, e.g. "Outdoor Dew Point"	required
key	str	The instance of the variable to retrieve, e.g. "Environment"	required

Returns:

Type	Description
float	The value of the variable

Raises:

Type	Description
KeyError	If the key is not found
ValueError	If the variable is not found

Examples:

>>> epsetup.get_variable_value("Outdoor Dew Point", "Environment")

request_variable

request_variable(name, key)

Request a variable from the EnergyPlus model for access during runtime.

Parameters:

Name	Type	Description	Default
name	str	The name of the variable to retrieve, e.g. "Outdoor Dew Point"	required
key	str	The instance of the variable to retrieve, e.g. "Environment"	required

Returns:

Type	Description
None	None

Examples:

>>> epsetup.request_variable("Outdoor Dew Point", "Environment")

run

run(output_directory='./', output_prefix='eplus', output_suffix='L', silent=False, annual=False, design_day=False)

Run EnergyPlus simulation.

Parameters:

Name	Type	Description	Default
output_directory	Optional[str]	Output directory path. (default: current directory)	'./'
output_prefix	Optional[str]	Prefix for output files. (default: eplus)	'eplus'
output_suffix	Optional[str]	Suffix style for output files. (default: L) L: Legacy (e.g., eplustbl.csv) C: Capital (e.g., eplusTable.csv) D: Dash (e.g., eplus-table.csv)	'L'
silent	bool	If True, do not print EnergyPlus output to console. (default: False)	False
annual	bool	If True, force run annual simulation. (default: False)	False
design_day	bool	If True, force run design-day-only simulation. (default: False)	False

Examples:

>>> epsetup.run(output_prefix="test1", silent=True)

set_callback

set_callback(method_name, func)

Set callback function for EnergyPlus runtime API.

Parameters:

Name	Type	Description	Default
method_name	str	Name of the method to set callback for.	required
func	Callable	Callback function.	required

Raises:

Type	Description
AttributeError	If method_name is not found in EnergyPlus runtime API.

Examples:

>>> epsetup.set_callback("callback_begin_system_timestep_before_predictor", func)

frads.EnergyPlusModel

Bases: EnergyPlusModel

EnergyPlus Model object

Attributes:

Name	Type	Description
walls_window		list of walls with windows
floors		list of floors
lighting_zone		list of lighting zones
zones		list of zones

floors property

floors

Get all of the floor names.

window_walls property

window_walls

Get list of walls with windows.

add_glazing_system

add_glazing_system(glzsys)

Add glazing system to EnergyPlusModel's epjs dictionary.

Parameters:

Name	Type	Description	Default
glzsys	GlazingSystem	GlazingSystem object	required

Raises:

Type	Description
ValueError	If solar and photopic results are not computed.

Examples:

>>> model = load_energyplus_model(Path("model.idf"))
>>> model.add_glazing_system(glazing_system1)

add_lighting

add_lighting(zone, lighting_level, replace=False)

Add lighting object to EnergyPlusModel's epjs dictionary.

Parameters:

Name	Type	Description	Default
zone	str	Zone name to add lighting to.	required
lighting_level	float	Lighting level in Watts.	required
replace	bool	If True, replace existing lighting object in zone.	False

Raises:

Type	Description
ValueError	If zone not found in model.
ValueError	If lighting already exists in zone and replace is False.

Examples:

>>> model.add_lighting("Zone1", 10)

add_output

add_output(output_type, output_name, reporting_frequency='Timestep')

Add an output variable or meter to the epjs dictionary.

Parameters:

Name	Type	Description	Default
output_type	str	Type of the output. "variable" or "meter".	required
output_name	str	Name of the output variable or meter.	required
reporting_frequency	str	Reporting frequency of the output variable or meter.	'Timestep'

Raises:

Type	Description
ValueError	If output_type is not "variable" or "meter".

Examples:

>>> model.add_output("Zone Mean Air Temperature", "variable")
>>> model.add_output("Cooling:Electricity", "meter")

frads.epmodel_to_radmodel

epmodel_to_radmodel(ep_model, epw_file=None, add_views=True)

Convert EnergyPlus model to Radiance models where each zone is a separate model.

Parameters:

Name	Type	Description	Default
ep_model	EnergyPlusModel	EnergyPlus model.	required
epw_file	Optional[str]	EnergyPlus weather file path. Defaults to None.	None
add_views	bool	Add views to the model. Such views will be positioned at the center of the zone facing windows weighted by window area. Defaults to True.	True

Returns:

Name	Type	Description
dict	dict	Radiance models.

Examples:

>>> radmodels = epmodel_to_radmodel(ep_model, epw_file)

frads.load_energyplus_model

load_energyplus_model(fpath)

Load EnergyPlus model from JSON file.

Parameters:

Name	Type	Description	Default
fpath	Union[str, Path]	Path to JSON file.	required

Returns:

Type	Description
EnergyPlusModel	EnergyPlusModel object.

Raises:

Type	Description
ValueError	If file is not an IDF or epJSON file.

Examples:

>>> model = load_energyplus_model("model.json")