bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task package

Submodules

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.create_result_df module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.create_result_df.CreateResultDF(playground)

Bases: ITask

This ITask creates a result dataframe for EnergyPlus BEPS simulations

See detailed explanation in the run function below.

format_dataframe(df_original: DataFrame, zone_dict: dict, space_bound_dict: dict) → DataFrame

Formats the dataframe to generic bim2sim output structure.

This function:

• adds the space GUIDs to the results

• selects only the selected simulation outputs from the result

Args:

df_original: original dataframe directly taken from simulation zone_dict: dictionary with all zones, in format {GUID : Zone Usage} space_bound_dict: dictionary with space_guid and a list of space

boundary guids of this space.

Returns:

df_final: converted dataframe in bim2sim result structure

static map_zonal_results(bim2sim_energyplus_mapping_base, zone_dict, space_bound_dict=None, plot_single_zone_guid=None)

Add zone/space guids/names to mapping dict.

EnergyPlus outputs the results referencing to the IFC-GlobalId. This function adds the real zone/space guids or aggregation names to the dict for easy readable results. Rooms are mapped with their space GUID, aggregated zones are mapped with their zone name. The mapping between zones and rooms can be taken from tz_mapping.json file with can be found in export directory.

Args:

bim2sim_energyplus_mapping_base: Holds the mapping between

simulation outputs and generic bim2sim output names.

zone_dict: dictionary with all zones, in format {GUID : Zone Usage} space_bound_dict: dictionary mapping space guids and their bounds plot_single_zone_guid: guid of single space that should be analyzed

Returns:

dict: A mapping between simulation results and space guids, with

appropriate adjustments for aggregated zones.

reads: Tuple[str] = ('idf', 'sim_results_path', 'elements')

run(idf: IDF, sim_results_path: Path, elements: dict) → dict[slice(<class 'str'>, <class 'pandas.core.frame.DataFrame'>, None)]

Create a result DataFrame for EnergyPlus BEPS results.

This function transforms the EnergyPlus simulation results to the general result data format used in this bim2sim project. The simulation results stored in the EnergyPlus result file ( “eplusout.csv”) are shifted by one hour to match the simulation results of the modelica simulation. Afterwards, the simulation results are formatted to match the bim2sim dataframe format.

Args:

idf (IDF): eppy idf sim_results_path (Path): path to the simulation results from

EnergyPlus

elements (dict): dictionary in the format dict[guid: element],

holds preprocessed elements including space boundaries.

Returns:

df_finals (dict): dictionary in the format dict[str(project name): pd.DataFrame], final dataframe that holds only relevant data, with generic bim2sim names and index in form of MM/DD-hh:mm:ss

select_wanted_results()

Selected only the wanted outputs based on sim_setting sim_results

touches: Tuple[str] = ('df_finals',)

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.CreateIdf(playground)

Bases: ITask

Create an EnergyPlus Input file.

Task to create an EnergyPlus Input file based on the for EnergyPlus preprocessed space boundary geometries. See detailed explanation in the run function below.

add_shading_control(shading_type, elements, idf, outdoor_temp=22, solar=40)

Add a default shading control to IDF. Two criteria must be met such that the window shades are set: the outdoor temperature must exceed a certain temperature and the solar radiation [W/m²] must be greater than a certain heat flow. Args:

shading_type: shading type, ‘Interior’ or ‘Exterior’ elements: elements idf: idf outdoor_temp: outdoor temperature [°C] solar: solar radiation on window surface [W/m²]

static add_shadings(elements: dict, idf: IDF)

Add shading boundaries to idf.

Args:

elements: dict[guid: element] idf: idf file object

static check_preprocessed_materials_and_constructions(rel_elem, layers)

Check if preprocessed materials and constructions are valid.

static export_geom_to_idf(sim_settings: EnergyPlusSimSettings, elements: dict, idf: IDF)

Write space boundary geometry to idf.

This function converts the space boundary bound_shape from OpenCascade to idf geometry.

Args:

elements: dict[guid: element] idf: idf file object

get_preprocessed_materials_and_constructions(sim_settings: EnergyPlusSimSettings, elements: dict, idf: IDF)

Get preprocessed materials and constructions.

This function sets preprocessed construction and material for building surfaces and fenestration. For virtual bounds, an air boundary construction is set.

Args:

sim_settings: BIM2SIM simulation settings elements: dict[guid: element] idf: idf file object

static idf_validity_check(idf)

Perform idf validity check and simple fixes.

This function performs a basic validity check of the resulting idf. It removes openings from adiabatic surfaces and very small surfaces.

Args:

idf: idf file object

static init_idf(sim_settings: EnergyPlusSimSettings, paths: FolderStructure, weather_file: PosixPath, ifc_name: str) → IDF

Initialize the EnergyPlus input file.

Initialize the EnergyPlus input file (idf) with general idf settings and set default weather data.

Args:

sim_settings: EnergyPlusSimSettings paths: BIM2SIM FolderStructure weather_file: PosixPath to *.epw weather file ifc_name: str of name of ifc

Returns:

idf file of type IDF

init_zone(sim_settings: EnergyPlusSimSettings, elements: dict, idf: IDF)

Initialize zone settings.

Creates one idf zone per space and sets heating and cooling templates, infiltration and internal loads (occupancy (people), equipment, lighting).

Args:

sim_settings: BIM2SIM simulation settings elements: dict[guid: element] idf: idf file object

init_zonegroups(elements: dict, idf: IDF)

Assign one zonegroup per storey.

Args:

elements: dict[guid: element] idf: idf file object

static init_zonelist(idf: IDF, name: str = None, zones_in_list: list[str] = None)

Initialize zone lists.

Inits a list of zones in the idf. If the zones_in_list is not set, all zones are assigned to a general zone, unless the number of total zones is greater than 20 (max. allowed number of zones in a zonelist in an idf).

Args:

idf: idf file object name: str with name of zone list zones_in_list: list with the guids of the zones to be included in

the list

reads: Tuple[str] = ('elements', 'weather_file')

run(elements: dict, weather_file: Path) → tuple[geomeppy.idf.IDF, pathlib.Path]

Execute all methods to export an IDF from BIM2SIM.

This task includes all functions for exporting EnergyPlus Input files (idf) based on the previously preprocessed SpaceBoundary geometry from the ep_geom_preprocessing task. Geometric preprocessing (includes EnergyPlus-specific space boundary enrichment) must be executed before this task. In this task, first, the IDF itself is initialized. Then, the zones, materials and constructions, shadings and control parameters are set in the idf. Within the export of the idf, the final mapping of the bim2sim elements and the idf components is executed. Shading control is added if required, and the ground temperature of the building surrounding ground is set, as well as the output variables of the simulation. Finally, the generated idf is validated, and minor corrections are performed, e.g., tiny surfaces are deleted that would cause errors during the EnergyPlus Simulation run.

Args:

elements (dict): dictionary in the format dict[guid: element],

holds preprocessed elements including space boundaries.

weather_file (Path): path to weather file in .epw data format

Returns:

idf (IDF): EnergyPlus input file sim_results_path (Path): path to the simulation results.

set_day_hvac_template(idf: IDF, space: ThermalZone, name: str)

Set 24 hour hvac template.

This function sets idf schedules with 24hour schedules for heating and cooling.

Args:

idf: idf file object space: ThermalZone name: IDF Thermostat Name

static set_day_week_year_schedule(idf: IDF, schedule: list[float], profile_name: str, schedule_name: str)

Set day, week and year schedule (hourly).

This function sets an hourly day, week and year schedule.

Args:

idf: idf file object schedule: list of float values for the schedule (e.g.,

temperatures, loads)

profile_name: string schedule_name: str

set_equipment(sim_settings: EnergyPlusSimSettings, idf: IDF, name: str, zone_name: str, space: ThermalZone)

Set internal loads from equipment.

This function sets schedules and internal loads from equipment based on the BIM2SIM Preprocessing, i.e. based on IFC data if available or on templates.

Args:

sim_settings: BIM2SIM simulation settings idf: idf file object name: name of the new people idf object zone_name: name of zone or zone_list space: ThermalZone instance

static set_ground_temperature(idf: IDF, t_ground: Quantity)

Set the ground temperature in the idf.

Args:

idf: idf file object t_ground: ground temperature as ureg.Quantity

set_heating_and_cooling(idf: IDF, zone_name: str, space: ThermalZone)

Set heating and cooling parameters.

This function sets heating and cooling parameters based on the data available from BIM2SIM Preprocessing (either IFC-based or Template-based).

Args:

idf: idf file object zone_name: str space: ThermalZone instance

set_hvac_template(idf: IDF, name: str, heating_sp: int | float, cooling_sp: int | float, mode='setback')

Set heating and cooling templates (manually).

This function manually sets heating and cooling templates.

Args:

idf: idf file object heating_sp: float or int for heating set point cooling_sp: float or int for cooling set point name: IDF Thermostat Name

static set_infiltration(idf: IDF, name: str, zone_name: str, space: ThermalZone, ep_version: str)

Set infiltration rate.

This function sets the infiltration rate per space based on the BIM2SIM preprocessing values (IFC-based if available or template-based).

Args:

idf: idf file object name: name of the new people idf object zone_name: name of zone or zone_list space: ThermalZone instance ep_version: Used version of EnergyPlus

set_lights(sim_settings: EnergyPlusSimSettings, idf: IDF, name: str, zone_name: str, space: ThermalZone)

Set internal loads from lighting.

This function sets schedules and lighting based on the BIM2SIM Preprocessing, i.e. based on IFC data if available or on templates.

Args:

sim_settings: BIM2SIM simulation settings idf: idf file object name: name of the new people idf object zone_name: name of zone or zone_list space: ThermalZone instance

static set_natural_ventilation(idf: IDF, name: str, zone_name: str, space: ThermalZone, ep_version)

Set natural ventilation.

This function sets the natural ventilation per space based on the BIM2SIM preprocessing values (IFC-based if available or template-based). Natural ventilation is defined for winter, summer and overheating cases, setting the air change per hours and minimum and maximum outdoor temperature if applicable.

Args:

idf: idf file object name: name of the new people idf object zone_name: name of zone or zone_list space: ThermalZone instance ep_version: Used version of EnergyPlus

static set_output_variables(idf: IDF, sim_settings: EnergyPlusSimSettings)

Set user defined output variables in the idf file.

Args:

idf: idf file object sim_settings: BIM2SIM simulation settings

set_people(sim_settings: EnergyPlusSimSettings, idf: IDF, name: str, zone_name: str, space: ThermalZone)

Set occupancy schedules.

This function sets schedules and internal loads from people (occupancy) based on the BIM2SIM Preprocessing, i.e. based on IFC data if available or on templates.

Args:

sim_settings: BIM2SIM simulation settings idf: idf file object name: name of the new people idf object zone_name: name of zone or zone_list space: ThermalZone instance

static set_preprocessed_construction_elem(rel_elem: IFCBased, layers: list[bim2sim.elements.bps_elements.Layer], idf: IDF)

Write preprocessed constructions to idf.

This function uses preprocessed data to define idf construction elements.

Args:

rel_elem: any subclass of IFCBased (e.g., Wall) layers: list of Layer idf: idf file object

static set_preprocessed_material_elem(layer: Layer, idf: IDF)

Set a preprocessed material element.

Args:

layer: Layer Instance idf: idf file object

static set_preprocessed_window_material_elem(rel_elem: Window, idf: IDF, add_window_shading: False)

Set preprocessed window material.

This function constructs windows with a WindowMaterial:SimpleGlazingSystem consisting of the outermost layer of the providing related element. This is a simplification, needs to be extended to hold multilayer window constructions.

Args:

rel_elem: Window instance idf: idf file object add_window_shading: Add window shading (options: ‘None’, ‘Interior’, ‘Exterior’)

static set_simulation_control(sim_settings: EnergyPlusSimSettings, idf)

Set simulation control parameters.

This function sets general simulation control parameters. These can be easily overwritten in the exported idf. Args:

sim_settings: EnergyPlusSimSettings idf: idf file object

touches: Tuple[str] = ('idf', 'sim_results_path')

static write_schedule(idf: IDF, sched_name: str, sched_part_list: list)

Write schedules to idf.

This function writes a schedule to the idf. Only used for manual setup of schedules (combined with set_hvac_template).

Args:

idf: idf file object sched_name: str with name of the schedule sched_part_list: list of schedule parts (cf. function

_define_schedule_part)

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_create_idf.IdfObject(sim_settings, inst_obj, idf)

Bases: object

Create idf elements for surfaces.

This class holds all data required for the idf setup of BUILDINGSURFACE:DETAILED and FENESTRATIONSURFACE:DETAILED. This includes further methods for processing the preprocessed information from the BIM2SIM process for the use in idf (e.g., surface type mapping).

static get_circular_shape(obj_pnts: list[tuple]) → bool

Check if a shape is circular.

This function checks if a SpaceBoundary has a circular shape.

Args:

obj_pnts: SpaceBoundary vertices (list of coordinate tuples)

Returns:

True if shape is circular

map_boundary_conditions(inst_obj: SpaceBoundary | SpaceBoundary2B)

Map boundary conditions.

This function maps the boundary conditions of a SpaceBoundary instance to the idf space boundary conditions.

Args:

inst_obj: SpaceBoundary instance

map_surface_types(inst_obj: SpaceBoundary | SpaceBoundary2B)

Map surface types.

This function maps the attributes of a SpaceBoundary instance to idf surface type.

Args:

inst_obj: SpaceBoundary instance

static process_circular_shapes(idf: IDF, obj_coords: list[tuple], obj, inst_obj: SpaceBoundary | SpaceBoundary2B)

Simplify circular space boundaries.

This function processes circular boundary shapes. It converts circular shapes to triangular shapes.

Args:

idf: idf file object obj_coords: coordinates of an idf object obj: idf object inst_obj: SpaceBoundary instance

static process_other_shapes(inst_obj: SpaceBoundary | SpaceBoundary2B, obj)

Simplify non-circular shapes.

This function processes non-circular shapes with too many vertices by approximation of the shape utilizing the UV-Bounds from OCC (more than 120 vertices for BUILDINGSURFACE:DETAILED and more than 4 vertices for FENESTRATIONSURFACE:DETAILED)

Args:

inst_obj: SpaceBoundary Instance obj: idf object

set_construction_name()

Set default construction names.

This function sets default constructions for all idf surface types. Should only be used if no construction is available for the current object.

set_idfobject_attributes(idf: IDF)

Writes precomputed surface attributes to idf.

Args:

idf: the idf file

set_idfobject_coordinates(obj, idf: IDF, inst_obj: SpaceBoundary | SpaceBoundary2B)

Export surface coordinates.

This function exports the surface coordinates from the BIM2SIM Space Boundary instance to idf. Circular shapes and shapes with more than 120 vertices (BuildingSurfaces) or more than 4 vertices (fenestration) are simplified.

Args:

obj: idf-surface object (buildingSurface:Detailed or fenestration) idf: idf file object inst_obj: SpaceBoundary instance

set_preprocessed_construction_name()

Set preprocessed constructions.

This function sets constructions of idf surfaces to preprocessed constructions. Virtual space boundaries are set to be an air wall (not defined in preprocessing).

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_idf_cfd_export module

Module to export space boundaries as .stl for use in CFD.

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_idf_cfd_export.ExportIdfForCfd(playground)

Bases: ITask

Export Idf shapes as .stl for use in CFD applications.

See detailed explanation in the run function below.

static combine_space_stl_files(stl_name: str, space_name: str, paths: str)

Combine the stl file of spaces.

Args:

stl_name: name of the stl file space_name: name of the space paths: BIM2SIM paths

static combine_stl_files(stl_name: str, paths: str)

Combine stl files.

Args:

stl_name: name of the stl file paths: BIM2SIM paths

static combined_space_stl(stl_name: str, paths)

Combine the stl files per space in stl files.

Args:

stl_name: name of the stl file. paths: BIM2SIM paths

export_2b_bounds_to_stl(elements: dict, stl_name: str, stl_dir: str)

Export generated 2b space boundaries to stl for CFD purposes.

Args:

stl_dir: directory of exported stl files elements: dict[guid: element] stl_name: name of the stl file.

export_bounds_per_space_to_stl(elements: dict, stl_name: str, base_stl_dir: str)

Export stl bounds per space in individual directories.

Args:

elements: dict[guid: element] stl_name: name of the stl file. base_stl_dir: directory of exported stl files

export_bounds_to_stl(elements: dict, stl_name: str, stl_dir: str)

Export space boundaries to stl file.

This function exports space boundary geometry to an stl file as triangulated surfaces. Only physical (i.e., non-virtual) space boundaries are considered here. The geometry of opening space boundaries is removed from their underlying parent surfaces (e.g., Wall) before exporting to stl, so boundaries do not overlap.

Args:

stl_dir: directory of exported stl files elements: dict[guid: element] stl_name: name of the stl file.

export_single_bound_to_stl(bound: SpaceBoundary, stl_dir: str, stl_name: str)

Export a single bound to stl.

Args:

bound: SpaceBoundary instance stl_dir: directory of exported stl files stl_name: name of the stl file.

static export_space_bound_list(elements: dict, paths: str)

Exports a list of spaces and space boundaries.

Args:

elements: dict[guid: element] paths: BIM2SIM paths

reads: Tuple[str] = ('elements', 'idf')

run(elements, idf)

Run CFD export depending on settings.

This task exports space boundaries as .stl for use as geometric input files in CFD simulations. This task exports the space boundary geometry in two different ways: (1) all space boundaries are exported as stl files independent of their corresponding space and combined in a single stl file, and (2) the space boundaries are and labelled within the resulting and combined stl files for a more distinct usage in the CFD application.

Args:

elements (dict): dictionary in the format dict[guid: element],

holds preprocessed elements including space boundaries.

idf (IDF): eppy idf, EnergyPlus input file.

static write_triang_face(shape: TopoDS_Shape, name)

Write triangulated face to stl file.

Args:

shape: TopoDS_Shape name: path and name of the stl

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_idf_postprocessing module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_idf_postprocessing.IdfPostprocessing(playground)

Bases: ITask

Idf Postprocessin task.

See run function for further details.

reads: Tuple[str] = ('elements', 'idf', 'ifc_files', 'sim_results_path')

run(elements: dict, idf: IDF, ifc_files: list, sim_results_path: Path)

EnergyPlus postprocessing for further evaluation and debugging.

This task holds export functions for further evaluation and debugging. Information on spaces and space boundaries are exported and the zone names are exported in json format.

Args:

elements (dict): dictionary in the format dict[guid: element],

holds preprocessed elements including space boundaries.

idf (IDF): eppy idf, EnergyPlus input file. ifc_files (list): list of ifc files used in this project sim_results_path (Path): path to simulation results.

static write_zone_names(idf, elements, exportpath: Path)

Write a dictionary of the bim2sim ThermalZone names and usages.

This method creates a dict and exports it to a json file ( zone_dict.json) to the path defined in exportpath. This dict includes the zone name and the selected usage within bim2sim. All zones are considered that are created within the bim2sim elements.

Args:

idf: eppy idf elements: bim2sim elements exportpath: base path to place the resulting zone_dict.json

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_ifc_validation module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_ifc_validation.IfcValidation(playground)

Bases: ITask

Validate IFC file, focussing on energy modeling (use of space boundaries).

See run method for further details.

reads: Tuple[str] = ('ifc_files',)

run(ifc_files)

IFC file validation for EnergyPlus. No longer maintained.

This function holds an IFC file validation for EnergyPlus, but is no longer used. This task is replaced by the CheckIFC class in the common task section. For building performance simulation workflows like EnergyPlus, the common CheckIfc class executes the BEPS specific CheckIfcBPS methods.

Args:

ifc_files: input ifc files.

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_ifc_validation.SpaceBoundaryValidation(bound, id_list)

Bases: object

Validate IFC Space Boundaries for use in EnergyPlus

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_run_simulation module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_run_simulation.RunEnergyPlusSimulation(playground)

Bases: ITask

Run EnergyPlus simulation.

See run function for more details.

reads: Tuple[str] = ('idf', 'sim_results_path')

run(idf: IDF, sim_results_path: Path)

Run EneryPlus simulation.

This function is used to run EnergyPlus. The simulation is performed according to the selected simulation settings. The simulation results can be found under the simulation result path in the project name directory.

Args:

idf (IDF): eppy idf, EnergyPlus input file sim_results_path (Path): Path to simulation results.

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_visualize_results module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.ep_visualize_results.VisualizeResults(playground)

Bases: ITask

Visualize results of the EnergyPlus simulation.

See run function for more details.

reads: Tuple[str] = ('elements', 'sim_results_path')

run(elements, sim_results_path)

Run EnergyPlus specific visualization.

This function is no longer maintained, please use the plot scripts based on the df_finals dataframe instead. This function creates images of a floor plan visualization and saves them as a .png file.

Args:

elements (dict): dictionary in the format dict[guid: element],

holds preprocessed elements including space boundaries.

sim_results_path (Path): Path to simulation results.

:

bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.load_energyplus_results module

class bim2sim.plugins.PluginEnergyPlus.bim2sim_energyplus.task.load_energyplus_results.LoadEnergyPlusResults(playground)

Bases: ITask

Load existing results, run() method holds detailed information.

run()

Loads existing EnergyPlus results from a previous simulation.

The idf file from a previous simulation is loaded and stored in the playground state. The intended behaviour is that for the following tasks with post-processing and plotting there should be no difference if a total bim2sim plugin run is performed or the existing results are loaded.

Returns:

sim_results_path: path where to store the plots idf: loaded EnergyPlus input file

touches: Tuple[str] = ('sim_results_path', 'idf')