honeybee_energy.run module

Module for running IDF files through EnergyPlus.

honeybee_energy.run.add_gbxml_space_boundaries(base_gbxml, honeybee_model, new_gbxml=None)[source]

Add the SpaceBoundary and ShellGeometry to a base_gbxml of a Honeybee model.

Note that these space boundary geometry definitions are optional within gbXML and are essentially a duplication of the required non-manifold geometry within a valid gbXML. The OpenStudio Forward Translator does not include such duplicated geometries (hence, the reason for this method). However, these closed-volume boundary geometries are used by certain interfaces and gbXML viewers.

Parameters:

  • base_gbxml – A file path to a gbXML file that has been exported from the OpenStudio Forward Translator.

  • honeybee_model – The honeybee Model object that was used to create the exported base_gbxml.

  • new_gbxml – Optional path to where the new gbXML will be written. If None, the original base_gbxml will be overwritten with a version that has the SpaceBoundary included within it.

honeybee_energy.run.from_gbxml_osw(gbxml_path, model_path=None, osw_directory=None)[source]

Create a .osw to translate gbXML to a HBJSON file.

Parameters:

  • gbxml_path – File path to the gbXML to be translated to HBJSON.

  • model_path – File path to where the Model HBJSON will be written. If None, it will be output right next to the input file and given the same name.

  • osw_directory – The directory into which the .osw should be written. If None, it will be written into the a temp folder in the default simulation folder.

honeybee_energy.run.from_idf_osw(idf_path, model_path=None, osw_directory=None)[source]

Create a .osw to translate IDF to a HBJSON file.

Parameters:

  • idf_path – File path to the IDF to be translated to HBJSON.

  • model_path – File path to where the Model HBJSON will be written. If None, it will be output right next to the input file and given the same name.

  • osw_directory – The directory into which the .osw should be written. If None, it will be written into the a temp folder in the default simulation folder.

honeybee_energy.run.from_osm_osw(osm_path, model_path=None, osw_directory=None)[source]

Create a .osw to translate OSM to a HBJSON file.

Parameters:

  • osm_path – File path to the OSM to be translated to HBJSON.

  • model_path – File path to where the Model HBJSON will be written. If None, it will be output right next to the input file and given the same name.

  • osw_directory – The directory into which the .osw should be written. If None, it will be written into the a temp folder in the default simulation folder.

honeybee_energy.run.measure_compatible_model_json(model_file_path, destination_directory=None, simplify_window_cons=False, triangulate_sub_faces=True, triangulate_non_planar_orphaned=False, enforce_rooms=False, use_geometry_names=False, use_resource_names=False)[source]

Convert a Model file to one that is compatible with the honeybee_openstudio_gem.

This includes the re-serialization of the Model to Python, which will automatically ensure that all Apertures and Doors point in the same direction as their parent Face. If the Model tolerance is non-zero and Rooms are closed solids, this will also ensure that all Room Faces point outwards from their parent’s volume. If the Model units are not Meters, the model will be scaled to be in Meters. Geometries with holes will have the vertices re-specified in a manner that they are translated to EnergyPlus as a single list. Lastly, apertures and doors with more than 4 vertices will be triangulated to ensure EnergyPlus accepts them.

Parameters:

  • model_file_path – File path to a Honeybee Model as a HBJSON or HBpkl.

  • destination_directory – The directory into which the Model JSON that is compatible with the honeybee_openstudio_gem should be written. If None, this will be the same location as the input model_json_path. (Default: None).

  • simplify_window_cons – Boolean to note whether window constructions should be simplified during the translation. This is useful when the ultimate destination of the OSM is a format that does not supported layered window constructions (like gbXML). (Default: False).

  • triangulate_sub_faces – Boolean to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices. (Default: True).

  • triangulate_non_planar_orphaned – Boolean to note whether any non-planar orphaned geometry in the model should be triangulated upon export. This can be helpful because OpenStudio simply raises an error when it encounters non-planar geometry, which would hinder the ability to save gbXML files that are to be corrected in other software. (Default: False).

  • enforce_rooms – Boolean to note whether this method should enforce the presence of Rooms in the Model, which is as necessary prerequisite for simulation in EnergyPlus. (Default: False).

  • use_geometry_names – Boolean to note whether a cleaned version of all geometry display names should be used instead of identifiers when translating the Model to OSM and IDF. Using this flag will affect all Rooms, Faces, Apertures, Doors, and Shades. It will generally result in more read-able names in the OSM and IDF but this means that it will not be easy to map the EnergyPlus results back to the input Honeybee Model. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name. (Default: False).

  • use_resource_names – Boolean to note whether a cleaned version of all resource display names should be used instead of identifiers when translating the Model to OSM and IDF. Using this flag will affect all Materials, Constructions, ConstructionSets, Schedules, Loads, and ProgramTypes. It will generally result in more read-able names for the resources in the OSM and IDF. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name. (Default: False).

Returns:

The full file path to the new Model JSON written out by this method.

honeybee_energy.run.output_energyplus_files(directory)[source]

Get the paths to the EnergyPlus simulation output files given the idf directory.

Parameters:

directory – The path to where the IDF was run.

Returns:

A tuple with four elements

  • sql – Path to a .sqlite file containing all simulation results. Will be None if no file exists.

  • zsz – Path to a .csv file containing detailed zone load information recorded over the course of the design days. Will be None if no file exists.

  • rdd – Path to a .rdd file containing all possible outputs that can be requested from the simulation. Will be None if no file exists.

  • html – Path to a .html file containing all summary reports. Will be None if no file exists.

  • err – Path to a .err file containing all errors and warnings from the simulation. Will be None if no file exists.

honeybee_energy.run.prepare_idf_for_simulation(idf_file_path, epw_file_path=None)[source]

Prepare an IDF file to be run through EnergyPlus.

This includes checking that the EPW file and IDF file exist and renaming the IDF to in.idf (if it is not already named so). A check is also performed to be sure that a valid EnergyPlus installation was found.

Parameters:

  • idf_file_path – The full path to an IDF file.

  • epw_file_path – The full path to an EPW file. Note that inputting None here is only appropriate when the simulation is just for design days and has no weather file run period. (Default: None).

Returns:

directory – The folder in which the IDF exists and out of which the EnergyPlus simulation will be run.

honeybee_energy.run.run_idf(idf_file_path, epw_file_path=None, expand_objects=True, silent=False)[source]

Run an IDF file through energyplus on any operating system.

Parameters:

  • idf_file_path – The full path to an IDF file.

  • epw_file_path – The full path to an EPW file. Note that inputting None here is only appropriate when the simulation is just for design days and has no weather file run period. (Default: None).

  • expand_objects – If True, the IDF run will include the expansion of any HVAC Template objects in the file before beginning the simulation. This is a necessary step whenever there are HVAC Template objects in the IDF but it is unnecessary extra time when they are not present. (Default: True).

  • silent – Boolean to note whether the simulation should be run silently. This only has an effect on Windows simulations since Unix-based simulations always use shell and are always silent (Default: False).

Returns:

A series of file paths to the simulation output files

  • sql – Path to a .sqlite file containing all simulation results. Will be None if no file exists.

  • zsz – Path to a .csv file containing detailed zone load information recorded over the course of the design days. Will be None if no file exists.

  • rdd – Path to a .rdd file containing all possible outputs that can be requested from the simulation. Will be None if no file exists.

  • html – Path to a .html file containing all summary reports. Will be None if no file exists.

  • err – Path to a .err file containing all errors and warnings from the simulation. Will be None if no file exists.

honeybee_energy.run.run_osw(osw_json, measures_only=True, silent=False)[source]

Run a .osw file using the OpenStudio CLI on any operating system.

Parameters:

  • osw_json – File path to a OSW file to be run using OpenStudio CLI.

  • measures_only – Boolean to note whether only the measures should be applied in the running of the OSW (True) or the resulting model should be run through EnergyPlus after the measures are applied to it (False). (Default: True).

  • silent – Boolean to note whether the OSW should be run silently. This only has an effect on Windows simulations since Unix-based simulations always use shell and are always silent (Default: False).

Returns:

The following files output from the CLI run

  • osm – Path to a .osm file representing the output model. Will be None if no file exists.

  • idf – Path to a .idf file representing the model. Will be None if no file exists.

honeybee_energy.run.set_gbxml_floor_types(base_gbxml, interior_type=None, ground_type=None, new_gbxml=None)[source]

Set certain Floor Faces of a base_gbxml to a single type.

This method helps account for the fact that the gbXML schema has several different types of floors that mean effectively the same thing in energy simulation but not all destination software interfaces are equipped to treat them as such.

Parameters:

  • base_gbxml – A file path to a gbXML file that has been exported from the OpenStudio Forward Translator.

  • interior_type –

    Text for the type to be used for all interior floor faces. If None, the interior types will be left as they are. (Default: None). Choose from the following.

    • InteriorFloor

    • Ceiling

  • ground_type –

    Text for the type to be used for all ground-contact floor faces. If None, the ground floor types will be left as they are. (Default: None). Choose from the following.

    • UndergroundSlab

    • SlabOnGrade

    • RaisedFloor

  • new_gbxml – Optional path to where the new gbXML will be written. If None, the original base_gbxml will be overwritten with a version that has the floor types overridden. (Default: None).

honeybee_energy.run.to_empty_osm_osw(osw_directory, sim_par_json_path, epw_file=None)[source]

Create a .osw to produce an empty .osm file with no building geometry.

This is useful for creating OpenStudio models to which a detailed Ironbug system will be added. Such models with only Ironbug components can simulate in EnergyPlus if they use the LoadProfile:Plant object to represent the building loads. They are useful for evaluating the performance of such heating and cooling plants and, by setting the simulation parameters and EPW file with the inputs to this method, any sizing criteria for the plant components can be set.

Parameters:

  • osw_directory – The directory into which the .osw should be written and the .osm will eventually be written into.

  • sim_par_json_path – File path to a SimulationParameter JSON.

  • epw_file – Optional file path to an EPW that should be associated with the output energy model. If None, no EPW file will be written into the OSW. (Default: None).

Returns:

The file path to the .osw written out by this method.

honeybee_energy.run.to_gbxml_osw(model_path, output_path=None, osw_directory=None)[source]

Create a .osw to translate HBJSON to a gbXML file.

Parameters:

  • model_path – File path to Honeybee Model (HBJSON).

  • output_path – File path to where the gbXML will be written. If None, it will be output right next to the input file and given the same name.

  • osw_directory – The directory into which the .osw should be written. If None, it will be written into the a temp folder in the default simulation folder.

honeybee_energy.run.to_openstudio_osw(osw_directory, model_path, sim_par_json_path=None, additional_measures=None, base_osw=None, epw_file=None, schedule_directory=None, strings_to_inject=None, report_units=None, viz_variables=None)[source]

Create a .osw to translate honeybee JSONs to an .osm file.

Parameters:

  • osw_directory – The directory into which the .osw should be written and the .osm will eventually be written into.

  • model_path – File path to the Model as either a HBJSON or an OSM.

  • sim_par_json_path – Optional file path to the SimulationParameter JSON. If None, the resulting OSM will not have everything it needs to be simulate-able in EnergyPlus. (Default: None).

  • additional_measures – An optional array of honeybee-energy Measure objects to be included in the output osw. These Measure objects must have values for all required input arguments or an exception will be raised while running this function. (Default: None).

  • base_osw – Optional file path to an existing OSW JSON be used as the base for the output .osw. This is another way that outside measures can be incorporated into the workflow. (Default: None).

  • epw_file – Optional file path to an EPW that should be associated with the output energy model. If None, no EPW file will be written into the OSW. (Default: None).

  • schedule_directory – An optional file directory to which all file-based schedules should be written to. If None, all ScheduleFixedIntervals will be translated to Schedule:Compact and written fully into the IDF string instead of to Schedule:File. (Default: None).

  • strings_to_inject – An additional text string to get appended to the IDF before simulation. The input should include complete EnergyPlus objects as a single string following the IDF format.

  • report_units –

    A text value to set the units of the OpenStudio Results report that can optionally be included in the OSW. If set to None, no report will be produced. (Default: None). Choose from the following.

    • si - all units will be in SI

    • ip - all units will be in IP

  • viz_variables – An optional list of EnergyPlus output variable names to be visualized on the geometry in an output view_data HTML report. If None or an empty list, no view_data report is produced. See below for an example.

viz_variables = [
    "Zone Air System Sensible Heating Rate",
    "Zone Air System Sensible Cooling Rate"
]
Returns:

The file path to the .osw written out by this method.

honeybee_energy.run.to_sdd_osw(model_path, output_path=None, osw_directory=None)[source]

Create a .osw to translate HBJSON to a SDD file.

Parameters:

  • model_path – File path to Honeybee Model (HBJSON).

  • output_path – File path to where the SDD will be written. If None, it will be output right next to the input file and given the same name.

  • osw_directory – The directory into which the .osw should be written. If None, it will be written into the a temp folder in the default simulation folder.

honeybee_energy.run.trace_compatible_model_json(model_file_path, destination_directory=None, single_window=True, rect_sub_distance='0.15m', frame_merge_distance='0.2m')[source]

Convert a Model to one that is compatible with exporting to TRANE TRACE 3D Plus.

The resulting HBJSON is intended to be serialized to gbXML for import into TRACE 3D Plus. To handle TRACE’s limitations, all rooms in the model will be converted to extrusions with flat roofs and all Apertures will be converted to simple rectangles. In this process, priority is given to preserving the volume of the original detailed geometry and the original window area.

Parameters:

  • model_file_path – File path to a Honeybee Model as a HBJSON or HBpkl.

  • destination_directory – The directory into which the Model JSON that is compatible with the honeybee_openstudio_gem should be written. If None, this will be the same location as the input model_json_path. (Default: None).

  • single_window – A boolean for whether all windows within walls should be converted to a single window with an area that matches the original geometry. (Default: True).

  • rect_sub_distance – Text string of a number for the resolution at which non-rectangular Apertures will be subdivided into smaller rectangular units. This is required as TRACE 3D plus cannot model non-rectangular geometries. This can include the units of the distance (eg. 0.5ft) or, if no units are provided, the value will be interpreted in the honeybee model units. (Default: 0.15m).

  • frame_merge_distance – Text string of a number for the maximum distance between non-rectangular Apertures at which point the Apertures will be merged into a single rectangular geometry. This is often helpful when there are several triangular Apertures that together make a rectangle when they are merged across their frames. This can include the units of the distance (eg. 0.5ft) or, if no units are provided, the value will be interpreted in the honeybee model units. (Default: 0.2m).

Returns:

The full file path to the new Model JSON written out by this method.