dragonfly_trace.writer module

Methods to write Dragonfly Models to Trane TRACE.

dragonfly_trace.writer.model_to_exp(model, si_units=False, ventilation_method='Sum of Outdoor Air')

Get a single combined EXP string for all unique ProgramTypes and ConstructionSets in a Dragonfly Model.

Parameters:

• model – A Dragonfly Model object.

• si_units – Boolean to note whether the units of the values in the resulting matrix are in SI (True) instead of IP (False). (Default: False).

• ventilation_method –

  Optional text for the ventilation method to be used in the resulting matrix. Choose from the following.

  • Sum of Outdoor Air

  • ASHRAE 62.1

Returns:

Text string of EXP file contents for TRACE 700.

dragonfly_trace.writer.model_to_trace700_csv(model, si_units=False, ventilation_method='Sum of Outdoor Air', use_multiplier=True, exclude_plenums=True, merge_method=None, geometry_names=False)

Generate a CSV string with TRACE 700 load simulation attributes of a Model.

The resulting CSV tables can be copied into the tables that appear in the Component Tree view of TRACE 700. The order and organization of rooms in the resulting matrix should match that of the gbXML produced from the same model.

Parameters:

• model – A dragonfly Model for which a TRACE 700 CSV matrix will be returned.

• si_units – Boolean to note whether the units of the values in the resulting matrix are in SI (True) instead of IP (False). (Default: False).

• ventilation_method –

  Optional text for the ventilation method to be used in the resulting matrix. Choose from the following.

  • Sum of Outdoor Air

  • ASHRAE 62.1

• use_multiplier – If True, the multipliers on this Model’s Stories will be passed along to the CSV. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all resulting multipliers will be 1. (Default: True).

• exclude_plenums – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor_to_ceiling_height instead of a base Room with (a) plenum Room(s). (Default: True).

• 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 in the destination engine with fewer results to manage. Note that Room2Ds will only be merged if they form a continuous 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 of Room2Ds 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).

Returns:

Text string of content to be written into a CSV file containing all tables needed to specify room loads in TRACE 700.

dragonfly_trace.writer.model_to_trace700_gbxml(model, si_units=False, opening_simplification='MergeAdjWindows', program_name=None, program_version=None)

Generate a gbXML of a model, which can be imported to TRACE 700.

Parameters:

• model – A dragonfly Model for which a TRACE 700 gbXML will be returned.

• si_units – Boolean to note whether the units of the values in the resulting gbXML are in SI (True) instead of IP (False). (Default: False).

• opening_simplification –

  Optional text to note the method by which openings are simplified as part of the translation to gbXML. (Default: MergeAdjWindows). Choose from the following options.

  • None - No sub-face simplification will occur

  • MergeAdjWindows - Adjacent windows are merged; doors are left as is

  • SingleWindow - All doors removed; windows are merged into one per wall

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

Returns:

A gbXML text string that can be written to a file and imported to TRACE 700.

dragonfly_trace.writer.model_to_trace700_matrix(model, si_units=False, ventilation_method='Sum of Outdoor Air', use_multiplier=True, exclude_plenums=True, merge_method=None, geometry_names=False)

Get matrices with TRACE 700 simulation attributes of a Model.

The resulting matrices can be written to a CSV and then copied into the tables that appear in the Component Tree view of TRACE 700. The order and organization of rooms in the resulting matrix matches that of the gbXML produced from the same model.

Parameters:

• model – A dragonfly Model for which a TRACE 700 CSV matrix will be returned.

• si_units – Boolean to note whether the units of the values in the resulting matrix are in SI (True) instead of IP (False). (Default: False).

• ventilation_method –

  Optional text for the ventilation method to be used in the resulting matrix. Choose from the following.

  • Sum of Outdoor Air

  • ASHRAE 62.1

• use_multiplier – If True, the multipliers on this Model’s Stories will be passed along to the CSV. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all resulting multipliers will be 1. (Default: True).

• exclude_plenums – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor_to_ceiling_height instead of a base Room with (a) plenum Room(s). (Default: True).

• 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 in the destination engine with fewer results to manage. Note that Room2Ds will only be merged if they form a continuous 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 of Room2Ds 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).

Returns:

A tuple with four items.

room_matrix – A list of list where each sublist represents a row of the

Rooms table of the TRACE 700 Component Tree.

airflows_matrix – A list of list where each sublist represents a row of the

Airflows table of the TRACE 700 Component Tree.

people_and_lights_matrix – A list of list where each sublist represents

a row of the People & Lighting table of the TRACE 700 Component Tree.

misc_loads_matrix – A list of list where each sublist represents a row of

the Miscellaneous Loads table of the TRACE 700 Component Tree.

oa_calc_matrix – A list of list where each sublist represents a row of a

table that illustrates how the outdoor airflow rates appearing in the airflows_matrix were calculated.

dragonfly_trace.writer.model_to_trace700_workbook(model, si_units=False, ventilation_method='Sum of Outdoor Air', use_multiplier=True, exclude_plenums=True, merge_method=None, geometry_names=False)

Generate an Excel Workbook (openpyxl) with TRACE 700 attributes of a Model.

The resulting openpyxl Workbook can be saved and opened in Excel. The data in the tables can then be copied into the tables that appear in the Component Tree view of TRACE 700. The order and organization of rooms in the resulting matrix should match that of the gbXML produced from the same model.

Parameters:

• model – A dragonfly Model for which a TRACE 700 Excel Workbook will be returned.

• si_units – Boolean to note whether the units of the values in the resulting matrix are in SI (True) instead of IP (False). (Default: False).

• ventilation_method –

  Optional text for the ventilation method to be used in the resulting matrix. Choose from the following.

  • Sum of Outdoor Air

  • ASHRAE 62.1

• use_multiplier – If True, the multipliers on this Model’s Stories will be passed along to the Workbook. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all resulting multipliers will be 1. (Default: True).

• exclude_plenums – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor_to_ceiling_height instead of a base Room with (a) plenum Room(s). (Default: True).

• 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 in the destination engine with fewer results to manage. Note that Room2Ds will only be merged if they form a continuous 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 of Room2Ds 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. (Default: False).

Returns:

An Excel Workbook (openpyxl) with TRACE 700 attributes of the input Model.

dragonfly_trace.writer.model_to_trace700_zip_bytes(model, si_units=False, opening_simplification='MergeAdjWindows', ventilation_method='Sum of Outdoor Air', program_name=None, program_version=None)

Get the bytes of a .zip file containing files for import to TRACE 700.

The .zip file will include three files within it - a gbXML that should be imported to TRACE 700 first to set up the geometry, an XLSX with all of the room properties to be pasted into the “Component View” tables of TRACE 700, and an optional EXP file that contains the dragonfly model’s ProgramTypes exported to TRACE 700 room templates.

Parameters:

• model – A dragonfly Model for which a TRACE 700 gbXML will be returned.

• si_units – Boolean to note whether the units of the values in the resulting file are in SI (True) instead of IP (False). (Default: False).

• opening_simplification –

  Optional text to note the method by which openings are simplified as part of the translation to gbXML. (Default: MergeAdjWindows). Choose from the following options.

  • None - No sub-face simplification will occur

  • MergeAdjWindows - Adjacent windows are merged; doors are left as is

  • SingleWindow - All doors removed; windows are merged into one per wall

• ventilation_method –

  Optional text for the ventilation method to be used in the resulting matrix. Choose from the following.

  • Sum of Outdoor Air

  • ASHRAE 62.1

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

Returns:

ZIP file bytes that can be written to a file and unzipped to yield everything needed to recreate the dragonfly model in TRACE 700.

dragonfly_trace.writer.rooms_to_trace700_matrix(rooms, si_units=False)

Get a matrix for the “Rooms” table of the TRACE 700 Component Tree.

Parameters:

• rooms – A list of dragonfly Room2Ds and honeybee Rooms for which the TRACE 700 “Rooms” matrix will be returned.

• si_units – Boolean to note whether the units of the values in the resulting matrix are in SI (True) instead of IP (False). (Default: False).

Returns:

A list of list where each sublist represents a row of the Rooms table of the TRACE 700 Component Tree.