py4design.py2energyplus package

Module contents

class py4design.py2energyplus.Idf

Bases: object

An object that contains all the neccessary information for running a Energyplus simulation.

Attributes

zones ( list of IdfZone class instances) The list of zones to be simulated by Energyplus.
runperiods ( list of RunPeriod class instances) The list of runperiods to be simulated by Energyplus.
outputvars (list of OutputVariables class instances) The variables that will be outputted after the simulation.
outputmeter (list of OutputMeter class instances) The meters that will be outputted after the simulation.
buildingshades (list of IdfBuildingShade class instances) List of building shades geometries for the simulation.
version (str) The version of the Energyplus application.
time_step ( str) The time step of the simulation in minutes.
shadow_calc (tuple of two str) The first element of the tuple is the calculation frequency and the second element is the max figures. e.g.(“20”, “100000”)
building_data ( str) The IDF string of the building to be simulated.
result_file_path ( str) The file path of the output.csv file.
north ( str) The north direction in degrees. If “0” it means the y-direction is north, if “90” x-direction is north.
terrain ( str) The terrain of the simulation environment. e.g. “Urban”, “Suburbs”, “Country”, “City”, “Ocean”.
solar_dist ( str) The solar distribuition setting. e.g. “FullExterior”, “MinimalShadowing”, “FullInteriorAndExterior”, “FullExteriorWithReflections”, “FullInteriorAndExteriorWithReflections”.
max_warmup_days ( str) The maximum number of warmup days. At least “25”.
ground_temp ( list of str) The the ground temperature for each month.
output_control_table_style (tuple of two str) The first element of the tuple specifies the style of the table, e.g. “HTML”. The second element of the tuple specifies the unit conversion, e.g. JtoKWH.
output_surfaces_drawings (list of str) The 3D model formats to output after the simulation, e.g. [“DXF”].
output_table_summary_reports ( list of str) The reports to be outputted after the simulation, e.g. [“AllSummary”].
set_version(version)

This function sets the energyplus version that is used.

Parameters:

version: str

The version of the Energyplus application.
set_time_step(time_step)

This function sets the time step of the energyplus simulation.

Parameters:

time_step : str

The time step of the simulation in minutes.
set_shadow_calc(calc_frequency, max_figures)

This function sets the shadow calculation parameters of the energyplus simulation.

Parameters:

shadow_calc : tuple of two str

The first element of the tuple is the calculation frequency and the second element is the max figures. e.g.(“20”, “100000”)
set_north(north)

This function sets the north direction of the energyplus simulation.

Parameters:

north : str

The north direction in degrees. If “0” it means the y-direction is north, if “90” x-direction is north.
set_terrain(terrain)

This function sets the terrain of the energyplus simulation.

Parameters:

terrain : str

The terrain of the simulation environment. e.g. “Urban”, “Suburbs”, “Country”, “City”, “Ocean”.
set_solar_dist(solar_dist)

This function sets the solar distribuition of the energyplus simulation.

Parameters:

solar_dist : str

The solar distribuition setting. e.g. “FullExterior”, “MinimalShadowing”, “FullInteriorAndExterior”, “FullExteriorWithReflections”, “FullInteriorAndExteriorWithReflections”.
set_max_warmup_days(max_warmup_days)

This function sets the maximum warmup days of the energyplus simulation.

Parameters:

max_warmup_days : str

The maximum number of warmup days. At least “25”.
set_ground_temp(ground_temp)

This function sets the ground temperatures of the energyplus simulation.

Parameters:

ground_temp : list of str

The the ground temperature for each month. e.g. [“20”, “20”, “20”, “20”, “20”, “20”,”20”, “20”, “20”, “20”, “20”, “20”]
set_output_control_table_style(column_sep, unit_conversion)

This function sets the output control table style of the energyplus simulation.

Parameters:

column_sep : str

The style of the table, e.g. “HTML”.

unit_conversion : str

The unit conversion, e.g. JtoKWH.
add_output_surfaces_drawing(drawing_type)

This function sets the 3D geometry format to output after the simulation.

Parameters:

drawing_type : str

The 3D model of the simulated building, e.g. “DXF”.
add_output_table_summary_report(report_type)

This function sets the report type to output after the simulation.

Parameters:

report_type : str

The reports to be outputted after the simulation, e.g. “AllSummary”.
execute_idf(base_file_path, weather_file_path, data_folder_path)

This function executes the energyplus application.

Parameters:

base_file_path : str

The file path of the base.idf file. The base.idf file documents all the basic information of the simulation e.g. materials, constructions … It is distributed together with py2energyplus.

weather_file_path: str

The file path of the weather file.

data_folder_path : str

The directory to write all the results file to.
read_results_file()

This function reads the output.csv file and save a list of results after the simulation into self.content.

get_results(result_category, display)

This function reads the self.content and filter the results. read_result_file function must be executed prior.

Parameters:

result_category : str

The result to filter. Options: “energytransfer”, “z_sys_sensible_cooling”, “z_sys_sensible_cooling_peak”, “z_sys_sensible_heating”, “z_sys_sensible_heating_peak”, “sol_incident”, “sol_beam”, “sol_sky_diff”, “sol_refl_obs”.

display: str

If display is “daily”, shows the results/day.
Returns:

filtered results : dictionary

A dicitonary with the output variable names as keywords and a list of results values.
class py4design.py2energyplus.RunPeriod(start_month, start_day, end_month, end_day, idf)

Bases: object

An object that contains all the run period information for running a Energyplus simulation.

Parameters:

start_month : str

The starting month of the energyplus simulation.

start_day : str

The starting day of the starting month of the energyplus simulation.

end_month : str

The end month of the energyplus simulation.

end_day : str

The end day of the end month of the energyplus simulation.

idf : Idf class instance

The idf class instance to append to.

Attributes

see Parameters  
idf()

This function writes all the run period information into energyplus readable string

Returns:

run period : str

The idf string of the run period.
class py4design.py2energyplus.OutputMeter(variable_name, report_frequency, idf)

Bases: object

An object that contains all the output meter information for running a Energyplus simulation.

Parameters:

variable_name : str

The name of the variable of the output meter.

report_frequency : str

The report frequency of the variable, e.g. “Hourly”, “Monthly”, “Daily”.

idf : Idf class instance

The idf class instance to append to.

Attributes

see Parameters  
idf()

This function writes all the output meter information into energyplus readable string

Returns:

output meter : str

The idf string of the output meter.
class py4design.py2energyplus.OutputVariables(variable_name, report_frequency, idf)

Bases: object

An object that contains all the output variable information for running a Energyplus simulation.

Parameters:

variable_name : str

The name of the variable.

report_frequency : str

The report frequency of the variable, e.g. “Hourly”, “Monthly”, “Daily”.

idf : Idf class instance

The idf class instance to append to.

Attributes

see Parameters  
idf()

This function writes all the output variable information into energyplus readable string.

Returns:

output variable : str

The idf string of the output variable.
class py4design.py2energyplus.IdfZone(name, idf)

Bases: object

An object that contains all the zone information for running a Energyplus simulation.

Parameters:

name : str

The name of the zone.

idf : Idf class instance

The idf class instance to append to.

Attributes

name (str) The name of the zone.
surfaces (list of IdfZoneSurface class instance) The surfaces that belongs to this zone.
cstart (str) The starting time of the cooling schedule, e.g. “09:00”
cend (str) The ending time of the cooling schedule, e.g. “17:00”
ctemp (str) The set point temperature of the cooling, e.g. “25”
hstart (str) The starting time of the heating schedule, e.g. “09:00”
hend (str) The ending time of the heating schedule, e.g. “17:00”
htemp (str) The set point temperature of the heating, e.g. “18”
l_start (str) The starting time of the lighting schedule, e.g. “09:00”
l_end (str) The ending time of the lighting schedule, e.g. “17:00”
l_watts (str) The Watts per m2 of the lighting, e.g. “10”
p_start (str) The starting time of the occupancy schedule, e.g. “09:00”
p_end (str) The ending time of the occupancy schedule, e.g. “17:00”
p_num (str) The m2 per person of the occupancy, e.g. “10”
ig_start (str) The starting time of the internal gain other equipment schedule, e.g. “09:00”
ig_end (str) The ending time of the internal gain other equipment schedule, e.g. “17:00”
ig_watts (str) The Watts per m2 of the equipment, e.g. “20”
add_surface(surface)

This function adds surface to the zone.

Parameters:

surface : IdfZoneSurface class instance

Add the surface into the zone.
set_cool_schedule(start, end, temp)

This function sets the cooling schedule for the zone.

Parameters:

start : str

The starting time of the cooling schedule, e.g. “09:00”

end : str

The ending time of the cooling schedule, e.g. “17:00”

temp : str

The set point temperature of the cooling, e.g. “25”
set_heat_schedule(start, end, temp)

This function sets the heating schedule for the zone.

Parameters:

start : str

The starting time of the heating schedule, e.g. “09:00”

end : str

The ending time of the heating schedule, e.g. “17:00”

temp : str

The set point temperature of the heating, e.g. “18”
set_light_schedule(start, end, watts)

This function sets the lighting schedule for the zone.

Parameters:

start : str

The starting time of the lighting schedule, e.g. “09:00”

end : str

The ending time of the lighting schedule, e.g. “17:00”

watts : str

The Watts per m2 of the lighting, e.g. “10”
set_internal_gains_schedule(start, end, watts)

This function sets the internal gain schedule for the zone.

Parameters:

start : str

The starting time of the internal gain other equipment schedule, e.g. “09:00”

end : str

The ending time of the internal gain other equipment schedule, e.g. “17:00”

watts : str

The Watts per m2 of the equipment, e.g. “20”
idf()

This function writes all the information into energyplus readable string

Returns:

zone data : str

The idf string of the zone data.
class py4design.py2energyplus.IdfSurface(name, points, construction)

Bases: object

An object that contains all the surface information for running a Energyplus simulation.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

construction : str

The name of the construction. The construction must be in the base.idf file. e.g. “Medium Roof/Ceiling”

Attributes

see Parameters.  
class py4design.py2energyplus.IdfZoneSurface(name, points, construction, type, boundary_srf_name)

Bases: py4design.py2energyplus.IdfSurface

An object that contains all the zone surface information for running a Energyplus simulation.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

construction : str

The name of the construction. The construction must be in the base.idf file. e.g. “Medium Roof/Ceiling”

type : str

The type of the surface, options: “Floor”, “Wall”, “Ceiling”, “Roof” .

boundary_srf_name : str

The boundary of the surface, options: “Outdoors”, “Adiabatic”, “Ground” or the name of the surface it is adjacent to.

Attributes

zone (str) The name of the zone.
type (str) The type of the surface, options: “Floor”, “Wall”, “Ceiling”, “Roof” .
subsurfaces (list of IdfSubSurface class instances) The list of subsurfaces (windows & shades) that belongs to this surface.
boundary (str) The boundary condition of the surface, options: “Outdoors”, “Adiabatic”, “Ground” or the name of the surface it is adjacent to.
boundary_obj (str) The object the surface is adjacent to. If boundary is “Outdoors” or “Ground” returns an empty string, if “Adiabatic” return its own name, else return the name of the surface it is adjacent to.
sun_exp (str) Describes if the surface is exposed to sun. Returns either “SunExposed” or “NoSun”.
win_exp (str) Describes if the surface is exposed to wind. Returns either “WindExposed” or “NoWind”.
add_window(window)

This function adds a window subsurface.

Parameters:

window : IdfWindow class instance

The window that belongs to this surface.
add_shade(shade)

This function adds a shade subsurface.

Parameters:

shade : IdfShade class instance

The shade that belongs to this surface.
idf()

This function writes all the information into energyplus readable string

Returns:

surface data : str

The idf string of the surface data.
class py4design.py2energyplus.IdfSubSurface(name, points, construction, host_srf)

Bases: py4design.py2energyplus.IdfSurface

An object that contains all the zone subsurface information for running a Energyplus simulation.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

construction : str

The name of the construction. The construction must be in the base.idf file. e.g. “Medium Roof/Ceiling”

host_srf : str

The name of the host surface. e.g. “wall1”.

Attributes

host_srf (str) See Parameters.
transmittance (str) The transmittance value of the subsurface, only used for shading surfaces. If not provided energyplus will default to 0, means a totally opaque surface.
class py4design.py2energyplus.IdfWindow(name, points, construction, host_srf)

Bases: py4design.py2energyplus.IdfSubSurface

An object that contains all the zone subsurface information for running a Energyplus simulation.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

construction : str

The name of the construction. The construction must be in the base.idf file. e.g. “Medium Roof/Ceiling”

host_srf : str

The name of the host surface. e.g. “wall1”.

Attributes

host_srf (str) See Parameters.
transmittance (str) The transmittance value of the subsurface, only used for shading surfaces.
idf()

This function writes all the information into energyplus readable string

Returns:

window data : str

The idf string of the window data.
class py4design.py2energyplus.IdfShade(name, points, construction, host_srf)

Bases: py4design.py2energyplus.IdfSubSurface

An object that contains all the zone subsurface information for running a Energyplus simulation.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

construction : str

The name of the construction. The construction must be in the base.idf file. e.g. “Medium Roof/Ceiling”

host_srf : str

The name of the host surface. e.g. “wall1”.

Attributes

host_srf (str) See Parameters.
transmittance (str) The transmittance value of the subsurface, only used for shading surfaces.
idf()

This function writes all the information into energyplus readable string

Returns:

shade data : str

The idf string of the shade data.
class py4design.py2energyplus.IdfBuildingShade(name, points, idf)

Bases: object

An object that contains all the surfaces of the surrounding context, e.g. shadings that are not attached to the buildings which includes trees and surrounding site.

Parameters:

name : str

The name of the surface.

points : pyptlist

List of points that defines the surface. Pyptlist is a list of tuples of floats. A pypt is a tuple that documents the xyz coordinates of a pt e.g. (x,y,z), thus a pyptlist is a list of tuples e.g. [(x1,y1,z1), (x2,y2,z2), …]

idf : Idf class instance

The idf class instance to append to.

Attributes

See Parameters.  
idf()

This function writes all the information into energyplus readable string

Returns:

building shade data : str

The idf string of the building shade data.