honeybee_energy.run module¶

Module for running IDF files through EnergyPlus.

honeybee_energy.run.empty_osm(sim_par=None, epw_file=None, osm_file=None, idf_file=None)[source]¶

Create an empty OSM or IDF file with no building geometry.

This is useful as a starting point for OSMs to which detailed Ironbug systems will be added. Such models with only Ironbug HVAC components can simulate in EnergyPlus if they use the LoadProfile:Plant object to represent the building loads.

Parameters:

sim_par – A SimulationParameter object that describes all of the settings for the simulation. If None, default parameters will be generated.
epw_file – Full path to an EPW file to be associated with the exported OSM. This is typically not necessary but may be used when a sim-par-json is specified that requests a HVAC sizing calculation to be run as part of the translation process but no design days are inside this simulation parameter.
osm_file – Optional path where the OSM will be output.
idf_file – Optional path where the IDF will be output.

Returns:

A tuple of two file paths.

osm – Path to an OpenStudio Model (.osm) file containing the simulation parameters and references to the EPW file. Will be None if no osm_file was input.
idf – Path to an EnergyPlus Input Data File (.idf) containing the simulation parameters. Will be None if no idf_file was input.

honeybee_energy.run.from_gbxml_osw(gbxml_path, model_path=None, osw_directory=None)[source]¶: Deprecated function that is no longer used.

honeybee_energy.run.from_idf_osw(idf_path, model_path=None, osw_directory=None)[source]¶: Deprecated function that is no longer used.

honeybee_energy.run.from_osm_osw(osm_path, model_path=None, osw_directory=None)[source]¶: Deprecated function that is no longer used.

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]¶: Deprecated function that is no longer used.

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.to_empty_osm_osw(osw_directory, sim_par_json_path, epw_file=None)[source]¶: Deprecated function that is no longer used.

honeybee_energy.run.to_gbxml_osw(model_path, output_path=None, osw_directory=None)[source]¶: Deprecated function that is no longer used.

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]¶: Deprecated function that is no longer used.

honeybee_energy.run.to_openstudio_sim_folder(model, directory, epw_file=None, sim_par=None, schedule_directory=None, enforce_rooms=False, use_geometry_names=False, use_resource_names=False, additional_measures=None, base_osw=None, strings_to_inject=None, report_units=None, viz_variables=None, print_progress=False)[source]¶

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

Parameters:

model – The Honeybee Model to be converted into an OpenStudio Model. This can also be the path to an .osm file that is already written into the directory, in which case the process of translating the model will be skipped and this function will only evaluate whether an OSW is needed to run the simulation or a directly-translated IDF is suitable.
directory – The directory into which the output files will be written to.
epw_file – Optional file path to an EPW that should be associated with the output energy model. If None, no EPW file will be assigned to the resulting OpenStudio Model and the OSM will not have everything it needs to be simulate-able in EnergyPlus. (Default: None).
sim_par – Optional SimulationParameter object that describes all of the settings for the simulation. If None, the resulting OSM will not have everything it needs to be simulate-able in EnergyPlus. (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).
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).
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).
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.
print_progress – Set to True to have the progress of the translation printed as it is completed.

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

Returns:

A series of file paths to the simulation input files.

osm – Path to an OpenStudio Model (.osm) file containing the direct translation of the Honeybee Model to OpenStudio. None of the additional_measures will be applied to this OSM if they are specified and any efficiency standards in the simulation parameters won’t be applied until the OSW is run.
osw – Path to an OpenStudio Workflow (.osw) JSON file that can be run with the OpenStudio CLI. Will be None if the OpenStudio CLI is not needed for simulation. This can happen if there is no base_osw, no additional_measures, no report_units or viz_variables, and no efficiency standard specified in the simulation parameters (which requires openstudio-standards).
idf – Path to an EnergyPlus Input Data File (.idf) that is ready to be simulated in EnergyPlus. Will be None if there is an OSW that must be run to create the IDF for simulation.

honeybee_energy.run.to_sdd_osw(model_path, output_path=None, osw_directory=None)[source]¶: Deprecated function that is no longer used.

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]¶: Deprecated function that is no longer used.