dragonfly_energy.cli.translate module

dragonfly energy translation commands.

dragonfly_energy.cli.translate.building_district_loads(scenario_file, loads_to_log=False, log_file=None, loads_to_folder=True)

Set the building loads to be used for DES simulation to district chilled/hot water.

If no district chilled/hot water loads are found in the SQL result file for a given building, the zone sensible cooling/heating load will be used instead and a warning will be returned from this function.

Parameters:

• scenario_csv – The full path to a .csv file for the URBANopt scenario.

• loads_to_log – Boolean to note whether the loads should be updated within the URBANopt project folder (FAlse) or they should instead be included within the log file output from this command (True). The latter is useful when binding building loads to a dragonfly Model.

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

dragonfly_energy.cli.translate.hb_models_to_osm(model_folder, sim_par_json=None, epw_file=None, cpu_count=1, output_folder=None)

Translate a folder of HBJSONs to OSMs in the same folder.

Parameters:

• model_folder – Path to a folder containing HBJSONs to be translated to OSM.

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

• cpu_count – Optional integer to specify the number of processors to be used in converting each HBJSON to an OSM.

• output_folder – Optional path to an output folder where the OSM files will be written. If unspecified, this will be the same as the folder containing HBJSONs.

dragonfly_energy.cli.translate.model_to_gbxml(model_file, ip_units=False, multiplier=False, no_plenum=False, no_ceil_adjacency=False, merge_method='None', triangulate_subfaces=False, permit_non_planar=False, complete_geometry=False, interior_face_type='InteriorFloor', ground_face_type='AutoAssign', reset_geometry_ids=False, reset_resource_ids=False, rect_geo_format='BoundingRectangle', explicit_holes=False, program_name=None, program_version=None, gbxml_schema_version=None, output_file=None, si_units=True, full_geometry=True, plenum=True, ceil_adjacency=True, default_subfaces=True, triangulate_non_planar=True, minimal=True, keep_geometry_ids=True, keep_resource_ids=True, collapsed_holes=True)

Translate a Dragonfly Model to a gbXML file.

Parameters:

• model_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

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

• multiplier – Boolean to note whether the multipliers on each Building story are respected as integers or if full geometry objects for each repeated story should be written for each story in the building. Given that gbXML has no support for assigning multipliers and is a non-manifold geometry schema that relies on all geometry being modeled explicitly,this should almost never be set to True. However, if the destination software supports a means of assigning the multipliers to spaces after importing the gbXML (eg. TRACE 700), it may be useful to set this to True. (Default: False).

• no_plenum – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should not generate distinct 3D Rooms in the translation. (Default: False).

• no_ceil_adjacency – Boolean to indicate whether adjacencies should not be solved between stories. Given that gbXML is fundamentally a non-manifold geometry schema, this parameter should almost never be set to True. However, if the destination software supports simulating each story as a distinct entity, this may be useful. (Default: False).

• merge_method –

  An optional text string to describe how the Room2Ds should be merged into individual Rooms during the translation. Specifying a value here can be an effective way to reduce the number of Room volumes in the resulting Model and, ultimately, yield a faster simulation time with less results to manage. Note that Room2Ds will only be merged if they form a contiguous volume. Otherwise, there will be multiple Rooms per zone or story, each with an integer added at the end of their identifiers. Choose from the following options:

  • None - No merging will occur

  • Zones - Room2Ds in the same zone will be merged

  • PlenumZones - Only plenums in the same zone will be merged

  • Stories - Rooms in the same story will be merged

  • PlenumStories - Only plenums in the same story will be merged

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

• 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

• ground_face_type – Text string for the type to be used for all ground-contact floor faces. If unspecified, the ground types will be left as they are. Choose from: UndergroundSlab, SlabOnGrade, RaisedFloor.

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

• rect_geo_format –

  Text string to note how the rectangular geometry for all Surfaces is written into the gbXML. BoundingRectangle sets the width and height of the rectangular geometry using the bounding rectangle around the geometry, which results in an overestimated area for non-rectangular geo. SimpleArea will set the rectangle width always equal to geometry area and the height always equal to one, ensuring accurate areas and making it easy to check the geometry area in the gbXML. SimpleAreaForNonRectOnly will report the width and height of rectangular Face3D correctly but use simpler areas for non-rectangular geometry. (Default: BoundingRectangle). Choose from the following.

  • BoundingRectangle

  • SimpleArea

  • SimpleAreaForNonRectOnly

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

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

dragonfly_energy.cli.translate.model_to_idf(model_file, sim_par_json=None, full_geometry=False, no_plenum=False, ceil_adjacency=False, merge_method='None', additional_str='', csv_schedules=False, hvac_check=False, geometry_names=False, resource_names=False, output_file=None, multiplier=True, plenum=True, no_ceil_adjacency=True, compact_schedules=True, hvac_to_ideal_air=True, geometry_ids=True, resource_ids=True)

Translate a Dragonfly Model to an IDF using direct-to-idf translators.

The resulting IDF should be simulate-able but not all Model properties might make it into the IDF given that the direct-to-idf translators are used.

Parameters:

• model_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

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

• full_geometry – Boolean to note if the multipliers on each Building story will be passed along to the generated Honeybee Room objects or if full geometry objects should be written for each story in the building. (Default: False).

• no_plenum – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should generate distinct 3D Rooms in the translation. (Default: False).

• ceil_adjacency – Boolean to indicate whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the object-per-model is Story. (Default: False).

• merge_method –

  An optional text string to describe how the Room2Ds should be merged into individual Rooms during the translation. Specifying a value here can be an effective way to reduce the number of Room volumes in the resulting Model and, ultimately, yield a faster simulation time with less results to manage. Note that Room2Ds will only be merged if they form a contiguous volume. Otherwise, there will be multiple Rooms per zone or story, each with an integer added at the end of their identifiers. Choose from the following options:

  • None - No merging will occur

  • Zones - Room2Ds in the same zone will be merged

  • PlenumZones - Only plenums in the same zone will be merged

  • Stories - Rooms in the same story will be merged

  • PlenumStories - Only plenums in the same story will be merged

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

dragonfly_energy.cli.translate.model_to_osm(model_file, sim_par_json=None, epw_file=None, full_geometry=False, no_plenum=False, ceil_adjacency=False, merge_method='None', folder=None, osm_file=None, idf_file=None, epjson_file=None, geometry_names=False, resource_names=False, log_file=None, multiplier=True, plenum=True, no_ceil_adjacency=True, geometry_ids=True, resource_ids=True)

Translate a Dragonfly Model to an OpenStudio Model.

Parameters:

• model_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

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

• full_geometry – Boolean to note if the multipliers on each Building story will be passed along to the generated Honeybee Room objects or if full geometry objects should be written for each story in the building. (Default: False).

• no_plenum – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should generate distinct 3D Rooms in the translation. (Default: False).

• ceil_adjacency – Boolean to indicate whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the object-per-model is Story. (Default: False).

• merge_method –

  An optional text string to describe how the Room2Ds should be merged into individual Rooms during the translation. Specifying a value here can be an effective way to reduce the number of Room volumes in the resulting Model and, ultimately, yield a faster simulation time with less results to manage. Note that Room2Ds will only be merged if they form a contiguous volume. Otherwise, there will be multiple Rooms per zone or story, each with an integer added at the end of their identifiers. Choose from the following options:

  • None - No merging will occur

  • Zones - Room2Ds in the same zone will be merged

  • PlenumZones - Only plenums in the same zone will be merged

  • Stories - Rooms in the same story will be merged

  • PlenumStories - Only plenums in the same story will be merged

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

dragonfly_energy.cli.translate.model_to_sdd(model_file, full_geometry=False, no_plenum=False, ceil_adjacency=False, merge_method='None', geometry_names=False, resource_names=False, output_file=None, multiplier=True, plenum=True, no_ceil_adjacency=True, geometry_ids=True, resource_ids=True)

Translate a Dragonfly Model to a CBECC SDD file.

Parameters:

• model_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

• full_geometry – Boolean to note if the multipliers on each Building story will be passed along to the generated Honeybee Room objects or if full geometry objects should be written for each story in the building. (Default: False).

• no_plenum – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should generate distinct 3D Rooms in the translation. (Default: False).

• ceil_adjacency – Boolean to indicate whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the object-per-model is Story. (Default: False).

• merge_method –

  An optional text string to describe how the Room2Ds should be merged into individual Rooms during the translation. Specifying a value here can be an effective way to reduce the number of Room volumes in the resulting Model and, ultimately, yield a faster simulation time with less results to manage. Note that Room2Ds will only be merged if they form a contiguous volume. Otherwise, there will be multiple Rooms per zone or story, each with an integer added at the end of their identifiers. Choose from the following options:

  • None - No merging will occur

  • Zones - Room2Ds in the same zone will be merged

  • PlenumZones - Only plenums in the same zone will be merged

  • Stories - Rooms in the same story will be merged

  • PlenumStories - Only plenums in the same story will be merged

• 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 SDD file to output the string of the translation. By default it will be returned from this method.

dragonfly_energy.cli.translate.model_to_trace_gbxml(model_file, full_geometry=False, plenum=False, no_ceil_adjacency=False, merge_method='None', detailed_windows=False, rect_sub_distance='0.15m', frame_merge_distance='0.2m', program_name=None, program_version=None, output_file=None, multiplier=True, no_plenum=True, ceil_adjacency=True, single_window=True)

Translate a Dragonfly Model to a gbXML file that is compatible with TRACE.

Parameters:

• model_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

• full_geometry – Boolean to note if the multipliers on each Building story will be passed along to the generated Honeybee Room objects or if full geometry objects should be written for each story in the building. (Default: False).

• plenum – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should generate distinct 3D Rooms in the translation. (Default: False).

• no_ceil_adjacency – Boolean to indicate whether adjacencies should be solved between interior stories when Room2Ds perfectly match one another in their floor plate. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the object-per-model is Story. (Default: False).

• merge_method –

  An optional text string to describe how the Room2Ds should be merged into individual Rooms during the translation. Specifying a value here can be an effective way to reduce the number of Room volumes in the resulting Model and, ultimately, yield a faster simulation time with less results to manage. Note that Room2Ds will only be merged if they form a contiguous volume. Otherwise, there will be multiple Rooms per zone or story, each with an integer added at the end of their identifiers. Choose from the following options:

  • None - No merging will occur

  • Zones - Room2Ds in the same zone will be merged

  • PlenumZones - Only plenums in the same zone will be merged

  • Stories - Rooms in the same story will be merged

  • PlenumStories - Only plenums in the same story will be merged

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