Skip to content

Core Classes

frads.EnergyPlusSetup 

EnergyPlusSetup(epmodel, weather_file=None, enable_radiance=False, nproc=1, initialize_radiance=True, output_directory='./')

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 None | 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_cfs_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 by default, with direction facing the windows weighted by window area. Users can modify the view position and direction through rconfig before calling initialize_radiance().

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]

Tuple of (enhanced simplified DGP, simplified DGP).

Raises:

Type Description
KeyError

If zone not found in model.

Examples:

>>> edgp, sdgp = epsetup.calculate_edgps("Zone1", {"window1": "state1"})

calculate_mev 

calculate_mev(zone, cfs_name)

Calculate menalonpic illuminance.

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
float

Menalonpic vertical illuminance.

Raises:

Type Description
KeyError

If zone not found in model.

Examples:

>>> epsetup.calculate_mev("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_illuminance 

get_diffuse_horizontal_illuminance()

Get diffuse horizontal illuminance.

Returns:

Type Description
float

Diffuse horizontal illuminance in lux.
Example

epsetup.get_diffuse_horizontal_illuminance()

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_illuminance 

get_direct_normal_illuminance()

Get direct normal illuminance.

Returns:

Type Description
float

Direct normal illuminance in lux.

Examples:

>>> epsetup.get_direct_normal_illuminance()

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_total_sky_cover 

get_total_sky_cover()

Get total sky cover.

Returns:

Type Description
float

Total sky cover in fraction.
Example

epsetup.get_total_sky_cover()

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")

initialize_radiance 

initialize_radiance(zones=None, nproc=1)

Initialize Radiance for Three-Phase Method.

Parameters:

Name Type Description Default
zones None | list[str]

List of zones to initialize. If None, initialize all zones.

 None
nproc int

Number of processors to use for generating matrices.

 1

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 None | str

Output directory path. (default: current directory)

 './'
output_prefix None | str

Prefix for output files. (default: eplus)

 'eplus'
output_suffix None | 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")

Model Loading and Conversion

frads.load_energyplus_model 

load_energyplus_model(fpath)

Load EnergyPlus model from IDF or epJSON file.

Supports loading EnergyPlus models from both IDF (Input Data File) and epJSON (EnergyPlus JSON) formats. IDF files are automatically converted to epJSON format during loading.

Parameters:

Name Type Description Default
fpath str | Path

Path to the EnergyPlus model file (.idf or .epJSON/.json).

 required

Returns:

Type Description
EnergyPlusModel

EnergyPlusModel object containing the parsed building model data.

Raises:

Type Description
ValueError

If file extension is not .idf, .epJSON, or .json.
FileNotFoundError

If the specified file does not exist.

Examples:

>>> # Load from IDF file
>>> model = load_energyplus_model("building.idf")
>>> # Load from epJSON file
>>> model = load_energyplus_model("building.epJSON")
>>> print(f"Building has {len(model.zones)} zones")

frads.epmodel_to_radmodel 

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

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 None | 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)

Utility Functions

frads.ep_datetime_parser 

ep_datetime_parser(inp)

Parse date and time from EnergyPlus output format.

EnergyPlus outputs dates and times in "MM/DD HH:MM:SS" format. This function handles the special case where EnergyPlus uses "24:00:00" to represent midnight of the next day.

Parameters:

Name Type Description Default
inp str

Date and time string from EnergyPlus output (e.g., "01/15 14:30:00").

 required

Returns:

Type Description
datetime

A datetime object representing the parsed date and time.

Examples:

>>> ep_datetime_parser("01/15 14:30:00")
datetime.datetime(1900, 1, 15, 14, 30)
>>> ep_datetime_parser("12/31 24:00:00")  # Midnight of next day
datetime.datetime(1901, 1, 1, 0, 0)