honeybee_energy.cli.translate module

honeybee energy translation commands.

honeybee_energy.cli.translate.empty_osm(sim_par_json=None, epw_file=None, osm_file=None, idf_file=None, log_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_json – Full path to a honeybee energy SimulationParameter JSON 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.

  • log_file – Optional log file to output the paths to the generated OSM and] IDF files if they were successfully created. By default this string will be returned from this method.

honeybee_energy.cli.translate.model_from_gbxml(gbxml_file, reset_properties=False, osw_folder=None, output_file=None, keep_properties=True)[source]

Translate a gbXML to a Honeybee Model (HBJSON).

Parameters:

  • gbxml_file – Path to a gbXML file.

  • reset_properties – Boolean to note whether all energy properties should be reset to defaults upon import, meaning that only the geometry and boundary conditions are imported from the gbXML Model. (Default: False).

  • osw_folder – Deprecated input that is no longer used.

  • output_file – Optional HBJSON file to output the string of the translation. If None, it will be returned from this method. (Default: None).

honeybee_energy.cli.translate.model_from_idf(idf_file, reset_properties=False, osw_folder=None, output_file=None, keep_properties=True)[source]

Translate an EnergyPlus Model (IDF) to a Honeybee Model (HBJSON).

Parameters:

  • idf_file – Path to an EnergyPlus Model (IDF) file.

  • reset_properties – Boolean to note whether all energy properties should be reset to defaults upon import, meaning that only the geometry and boundary conditions are imported from the EnergyPlus Model. (Default: False).

  • osw_folder – Deprecated input that is no longer used.

  • output_file – Optional HBJSON file to output the string of the translation. If None, it will be returned from this method. (Default: None).

honeybee_energy.cli.translate.model_from_osm(osm_file, reset_properties=False, osw_folder=None, output_file=None, keep_properties=True)[source]

Translate a OpenStudio Model (OSM) to a Honeybee Model (HBJSON).

Parameters:

  • osm_file – Path to a OpenStudio Model (OSM) file.

  • reset_properties – Boolean to note whether all energy properties should be reset to defaults upon import, meaning that only the geometry and boundary conditions are imported from the Openstudio Model. (Default: False).

  • osw_folder – Deprecated input that is no longer used.

  • output_file – Optional HBJSON file to output the string of the translation. If None, it will be returned from this method. (Default: None).

honeybee_energy.cli.translate.model_to_gbxml(model_file, ip_units=False, full_geometry=False, include_shell_geometry=False, include_space_boundaries=False, interior_face_type='InteriorFloor', ground_face_type='AutoAssign', face_rename_format=None, subface_rename_format=None, reset_geometry_ids=False, reset_resource_ids=False, triangulate_subfaces=False, permit_non_planar=False, simple_rect_areas=False, explicit_holes=False, ventilation_components=False, program_name='Ladybug Tools CLI', program_version=None, gbxml_schema_version=None, output_file=None, si_units=True, minimal=True, exclude_shell_geometry=True, exclude_space_boundaries=True, keep_geometry_ids=True, keep_resource_ids=True, default_subfaces=True, triangulate_non_planar=True, bounding_rectangles=True, collapsed_holes=True, total_ventilation=True)[source]

Translate a Honeybee Model file to a gbXML file.

Parameters:

  • model_file – Full path to a Honeybee Model file (HBJSON or HBpkl).

  • ip_units – A boolean to note whether the geometry, space loads, and construction properties are reported in IP units (True) or SI units (False). (Default: False).

  • full_geometry – Boolean to note whether space boundaries and shell geometry should be included in the exported gbXML vs. just the minimal required non-manifold geometry. Specifying True here will override the individual include_shell_geometry and include_space_boundaries options. (Default: False).

  • include_shell_geometry – Boolean for whether shell geometry should be included vs. just the minimal required non-manifold geometry. (Default: False).

  • include_space_boundaries – Boolean for whether space boundaries should be included vs. just the minimal required non-manifold geometry. (Default: False).

  • interior_face_type –

    Text string for the type to be used for all interior floor/ceiling faces. (Default: InteriorFloor). Choose from the following.

    • InteriorFloor

    • Ceiling

  • ground_face_type –

    Text string for the type to be used for all ground-contact floor faces. If AutoAssign, the ground types will be SlabOnGrade for floors belonging to rooms with any above-ground walls and UndergroundSlab for floors in rooms with all underground walls. Choose from the following.

    • AutoAssign

    • UndergroundSlab

    • SlabOnGrade

    • RaisedFloor

  • face_rename_format – An optional text string for the pattern with which faces will be renamed. Any property on the honeybee Face class may be used (eg. gbxml_str) and each property should be put in curly brackets. Nested properties can be specified by using “.” to denote nesting levels (eg. properties.energy.construction.display_name). Functions that return string outputs can also be passed here as long as these functions defaults specified for all arguments.

  • subface_rename_format – An optional text string for the pattern with which apertures and doors will be renamed. Any property that exists on both the honeybee Aperture and honeybee Door class may be used (eg. gbxml_str) and each property should be put in curly brackets. Nested properties can be specified by using “.” to denote nesting levels (eg. properties.energy.construction.display_name). Functions that return string outputs can also be passed here as long as these functions defaults specified for all arguments.

  • reset_geometry_ids – Boolean to note whether a cleaned version of geometry display names should be used for the IDs that appear within the gbXML file. Using this flag will affect all Rooms, Faces, Apertures, Doors, and Shades. It will generally result in more read-able IDs in the gbXML file but this means that it will not be easy to map results back to the input 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).

  • reset_resource_ids – Boolean to note whether a cleaned version of all resource display names should be used for the IDs that appear within the gbXML file. 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 gbXML file. 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).

  • triangulate_subfaces – 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: False).

  • permit_non_planar – 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).

  • simple_rect_areas – Boolean to note whether the width and height of all RectangularGeometry is set based on the bounding rectangle around the geometry (False) or is set in a simplified manner with the width always equal to geometry area and the height always equal to one (True). Setting to True can ensure correct overall area of the geometry in the destination software, particularly in cases where the geometry is not rectangular. However, if the destination software has a means of representing the 2D rectangular geometry in 3D, setting this to True may not look correct. (Default: False).

  • explicit_holes – Boolean to note whether holes in Surfaces should be represented explicitly with their own PolyLoop or the hole and boundary should be collapsed into a single PolyLoop that winds inwards to cut out the holes. (Default: False).

  • ventilation_components – Boolean to note whether outdoor air ventilation values in the gbXML are written as a single total OAFlowPerZone (True) or ventilation criteria are written as separate criteria (False). That is, separate specifications for OAFlowPerPerson, OAFlowPerArea, etc. Note that the total ventilation accounts for the ventilation effectiveness while the individual flows do not. (Default: True).

  • program_name – Optional text to set the name of the software that will appear under the programId and ProductName tags of the DocumentHistory section. This can be set things like “Ladybug Tools” or “Pollination” or some other software in which this gbXML export capability is being run. If None, the “OpenStudio” will be used. (Default: None).

  • program_version – Optional text to set the version of the software that will appear under the DocumentHistory section. If None, and the program_name is also unspecified, only the version of OpenStudio will appear. Otherwise, this will default to “0.0.0” given that the version field is required. (Default: None).

  • gbxml_schema_version – Optional text to set the version of the gbXML schema that is specified in the XML header (eg. “5.00”). If None, this will default to the latest version.

  • output_file – Optional gbXML file to output the string of the translation. By default it will be returned from this method.

honeybee_energy.cli.translate.model_to_idf(model_file, sim_par_json=None, additional_str='', csv_schedules=False, hvac_check=False, geometry_names=False, resource_names=False, output_file=None, compact_schedules=True, hvac_to_ideal_air=True, geometry_ids=True, resource_ids=True)[source]

Translate a Honeybee Model file to a simplified IDF using direct-to-idf methods.

The direct-to-idf methods are faster than those that translate the model to OSM but certain features like detailed HVAC systems and the Airflow Network are not supported.

Parameters:

  • model_file – Full path to a Honeybee Model file (HBJSON or HBpkl).

  • sim_par_json – Full path to a honeybee energy SimulationParameter JSON that describes all of the settings for the simulation. If None, default parameters will be generated.

  • additional_str – Text string for additional lines that should be added to the IDF.

  • csv_schedules – Boolean to note whether any ScheduleFixedIntervals in the model should be included in the IDF string as a Schedule:Compact or they should be written as CSV Schedule:File and placed in a directory next to the output_file. (Default: False).

  • hvac_check – Boolean to note whether any detailed HVAC system templates should be converted to an equivalent IdealAirSystem upon export. If hvac-check is used and the Model contains detailed systems, a ValueError will be raised. (Default: False).

  • 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 original 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).

  • 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).

  • output_file – Optional IDF file to output the IDF string of the translation. By default this string will be returned from this method.

honeybee_energy.cli.translate.model_to_osm(model_file, sim_par_json=None, epw_file=None, folder=None, osm_file=None, idf_file=None, epjson_file=None, geometry_names=False, resource_names=False, log_file=None, geometry_ids=True, resource_ids=True)[source]

Translate a Honeybee Model file into an OpenStudio Model and corresponding IDF.

Parameters:

  • model_file – Full path to a Honeybee Model file (HBJSON or HBpkl).

  • sim_par_json – Full path to a honeybee energy SimulationParameter JSON 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.

  • folder – Deprecated input that is no longer used.

  • osm_file – Optional path where the OSM will be output.

  • idf_file – Optional path where the IDF will be output.

  • epjson_file – Optional path where the epJSON will be output.

  • 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 original 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).

  • 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).

  • log_file – Optional log file to output the paths to the generated OSM and] IDF files if they were successfully created. By default this string will be returned from this method.

honeybee_energy.cli.translate.model_to_sdd(model_file, geometry_names=False, resource_names=False, osw_folder=None, output_file=None, geometry_ids=True, resource_ids=True)[source]

Translate a Honeybee Model file to a SDD file.

Parameters:

  • model_file – Full path to a Honeybee Model file (HBJSON or HBpkl).

  • 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 original 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).

  • 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).

  • osw_folder – Deprecated input that is no longer used.

  • output_file – Optional SDD file to output the string of the translation. By default it will be returned from this method.

honeybee_energy.cli.translate.model_to_trace_gbxml(model_file, detailed_windows=False, rect_sub_distance='0.15m', frame_merge_distance='0.2m', program_name=None, program_version=None, output_file=None, single_window=True)[source]

Translate a Honeybee Model to a gbXML file that is compatible with TRACE 3D Plus.

Parameters:

  • model_file – Full path to a Honeybee Model file (HBJSON or HBpkl).

  • detailed_windows – A boolean for whether all windows within walls should be left as they are (True) or converted to a single window with an area that matches the original geometry (False). (Default: False).

  • rect_sub_distance – 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 – 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).

  • program_name – Optional text to set the name of the software that will appear under the programId and ProductName tags of the DocumentHistory section. This can be set things like “Ladybug Tools” or “Pollination” or some other software in which this gbXML export capability is being run. If None, the “OpenStudio” will be used. (Default: None).

  • program_version – Optional text to set the version of the software that will appear under the DocumentHistory section. If None, and the program_name is also unspecified, only the version of OpenStudio will appear. Otherwise, this will default to “0.0.0” given that the version field is required. (Default: None).

  • output_file – Optional gbXML file to output the string of the translation. By default it will be returned from this method.