Skip to content

feat(package): Add all methods for writing TRACE700 CSVs #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chriswmackey merged 3 commits into from
Apr 22, 2026
Merged

feat(package): Add all methods for writing TRACE700 CSVs #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d4385c6
feat(package): Add all methods for writing TRACE700 CSVs
chriswmackey Apr 21, 2026
57837c0
docs(tests): Add tests for writer methods
chriswmackey Apr 22, 2026
f8c4b41
feat(cli): Add a CLI to translate Dragonfly Models to CSV
chriswmackey Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 157 additions & 0 deletions dragonfly_trace/airflows.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
# coding=utf-8
"""Methods to write room airflows to matrices for Trane TRACE tables."""
from __future__ import division

from ladybug.datatype.volumeflowrate import VolumeFlowRate
from ladybug.datatype.volumeflowrateintensity import VolumeFlowRateIntensity


def airflows_trace700_matrix(rooms, si_units=False):
"""Get a matrix for the "Airflows" table of the TRACE 700 Component Tree.

Args:
rooms: A list of dragonfly Room2Ds and honeybee Rooms for which the
TRACE 700 "Airflows" 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 Airflows
table of the TRACE 700 Component Tree.
"""
# set up things for unit conversion
flow_unit = 'L/s' if si_units else 'cfm'
flow_intensity_unit = 'L/s/sq m' if si_units else 'cfm/sq ft of wall'
flow, fi = VolumeFlowRate(), VolumeFlowRateIntensity()

# set up the names of the rows
row_names = [
'Room Description',
'Adjacent Air Transfer from Room',
'Airflow Template',
'Ventilation Method',
'Ventilation Type',
'Ventilation Cooling',
'Ventilation Cooling Units',
'Ventilation Heating',
'Ventilation Heating Units',
'People-based Rate (Rp)',
'People-based Unit',
'Area-based Rate (Ra)',
'Area-based Unit',
'Ventilation Schedule',
'Std62.1-2004-2010 Clg Ez',
'Std62.1-2004-2010 Clg Ez Pct',
'Std62.1-2004-2010 Htg Ez',
'Std62.1-2004-2010 Htg Ez Pct',
'Std62.1-2004-2010 Er',
'Std62.1-2004-2010 Er Pct',
'DCV Min OA Intake',
'DCV Min OA Intake Unit',
'Infiltration Type',
'Infiltration Cooling',
'Infiltration Cooling Units',
'Infiltration Heating',
'Infiltration Heating Units',
'Infiltration Schedule',
'Main Supply Cooling',
'Main Supply Cooling Units',
'Main Supply Heating',
'Main Supply Heating Units',
'Aux Supply Cooling',
'Aux Supply Cooling Units',
'Aux Supply Heating',
'Aux Supply Heating Units',
'Cooling VAV Min Airflow',
'Cooling VAV Min Airflow Units',
'Heating VAV Max Airflow',
'Heating VAV Max Airflow Units',
'VAV Airflow Schedule',
'VAV Type',
'Room Exhaust',
'Room Exhaust Units',
'Room Exhaust Schedule'
]

# loop through the rooms and add each of the attributes
airflow_mtx = []
for room in rooms:
# calculate the total outdoor air ventilation and infiltration
vent_obj = room.properties.energy.ventilation
vent_flow = vent_obj.room_absolute_flow(room) if vent_obj is not None else 0
inf_obj = room.properties.energy.infiltration
inf_flow = inf_obj.flow_per_exterior_area if inf_obj is not None else 0

# put all attributes into a list
airflow_attr = [
room.display_name,
'<<No adjacent room>>',
'Default',
'Sum of Outdoor Air',
'None',
vent_flow,
flow_unit,
vent_flow,
flow_unit,
'',
'',
'',
'',
'Available (100%)',
'',
'',
'',
'',
'',
'',
'',
'',
'None',
inf_flow,
flow_intensity_unit,
inf_flow,
flow_intensity_unit,
'Available (100%)',
'',
'To be calculated',
'',
'To be calculated',
'',
'To be calculated',
'',
'To be calculated',
'',
'% Clg Airflow',
'',
'% Clg Airflow',
'Available (100%)',
'Default',
'0',
'air changes/hr',
'Available (100%)'
]
airflow_mtx.append(airflow_attr)

# transpose the matrix and convert SI units to IP
airflow_matrix = [list(row) for row in zip(*airflow_mtx)]
if not si_units:
airflow_matrix[5] = list(flow.to_unit(airflow_matrix[5], 'cfm', 'm3/s'))
airflow_matrix[7] = list(flow.to_unit(airflow_matrix[7], 'cfm', 'm3/s'))
airflow_matrix[23] = list(fi.to_unit(airflow_matrix[23], 'cfm/ft2', 'm3/s-m2'))
airflow_matrix[25] = list(fi.to_unit(airflow_matrix[25], 'cfm/ft2', 'm3/s-m2'))
else:
airflow_matrix[5] = list(flow.to_unit(airflow_matrix[5], 'L/s', 'm3/s'))
airflow_matrix[7] = list(flow.to_unit(airflow_matrix[7], 'L/s', 'm3/s'))
airflow_matrix[23] = list(fi.to_unit(airflow_matrix[23], 'L/s-m2', 'm3/s-m2'))
airflow_matrix[25] = list(fi.to_unit(airflow_matrix[25], 'L/s-m2', 'm3/s-m2'))

# round the numbers so that they display nicely
for row_i in (5, 7):
airflow_matrix[row_i] = [round(val, 1) for val in airflow_matrix[row_i]]
for row_i in (23, 25):
airflow_matrix[row_i] = [round(val, 3) for val in airflow_matrix[row_i]]

# insert the column for the row names
for row_name, row in zip(row_names, airflow_matrix):
row.insert(0, row_name)
return airflow_matrix
3 changes: 3 additions & 0 deletions dragonfly_trace/cli/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
import click
from dragonfly.cli import main

from .translate import translate


@click.group(help='dragonfly trace commands.')
@click.version_option()
Expand All @@ -10,6 +12,7 @@ def trace():


# add sub-commands to trace
trace.add_command(translate)

# add trace sub-commands
main.add_command(trace)
149 changes: 149 additions & 0 deletions dragonfly_trace/cli/translate.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
"""dragonfly trace translation commands."""
import click
import sys
import logging

from ladybug.commandutil import process_content_to_output
from dragonfly.model import Model
from dragonfly_trace.writer import model_to_trace700_csv as model_to_csv


_logger = logging.getLogger(__name__)


@click.group(help='Commands for translating URBANopt systems to OSM/IDF.')
def translate():
pass


@translate.command('model-to-trace700-csv')
@click.argument('model-file', type=click.Path(
exists=True, file_okay=True, dir_okay=False, resolve_path=True))
@click.option('--multiplier/--full-geometry', ' /-fg', help='Flag 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=True, show_default=True)
@click.option('--plenum/--separate-plenum', '-p/-sp', help='Flag to indicate whether '
'ceiling/floor plenum depths assigned to Room2Ds should simply be '
'reported as plenum depths in the CSV or they should be used to generate '
'distinct separated plenum rooms in the translation.',
default=True, show_default=True)
@click.option('--merge-method', '-m', help='Text 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. Choose from: None, Zones, PlenumZones, '
'Stories, PlenumStories.', type=str, default='None', show_default=True)
@click.option('--imperial/--metric', '-ip/-si', help='Flag to note whether imperial '
'or metric units should be used for values in the output CSV.',
default=True, show_default=True)
@click.option('--geometry-ids/--geometry-names', ' /-gn', help='Flag to note whether a '
'cleaned version of all geometry display names should be used instead '
'of identifiers when translating the Model.',
default=True, show_default=True)
@click.option('--resource-ids/--resource-names', ' /-rn', help='Flag to note whether a '
'cleaned version of all resource display names should be used instead '
'of identifiers when translating the Model.',
default=True, show_default=True)
@click.option('--output-file', '-f', help='Optional CSV file to output the string '
'of the translation. By default it printed out to stdout.',
type=click.File('w'), default='-', show_default=True)
def model_to_trace700_csv_cli(
model_file, multiplier, plenum, merge_method, imperial,
geometry_ids, resource_ids, output_file
):
"""Translate a Dragonfly Model to a CSV with tables for TRACE 700 attributes.

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.

\b
Args:
model_file: Full path to a Dragonfly Model file (DFJSON or DFpkl).
"""
try:
full_geometry = not multiplier
separate_plenum = not plenum
metric = not imperial
geo_names = not geometry_ids
res_names = not resource_ids
model_to_trace700_csv(
model_file, full_geometry, separate_plenum, merge_method,
metric, geo_names, res_names, output_file
)
except Exception as e:
_logger.exception('System translation failed.\n{}'.format(e))
sys.exit(1)
else:
sys.exit(0)


def model_to_trace700_csv(
model_file, full_geometry=False, separate_plenum=False, merge_method='None',
metric=False, geometry_names=False, resource_names=False, output_file=None,
multiplier=True, plenum=True, imperial=True, geometry_ids=True, resource_ids=True
):
"""Translate a Dragonfly Model to a CSV with tables for TRACE 700 attributes.

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.

Args:
model: A dragonfly Model for which a TRACE 700 CSV matrix will be returned.
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).
separate_plenum: Boolean to indicate whether ceiling/floor plenum depths
assigned to Room2Ds should simply be reported as plenum depths in the
CSV or they should be used to generate distinct separated plenum
rooms in the translation. (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 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

metric: Boolean to note whether the units of the values in the resulting
matrix are in SI (True) instead of IP (False). (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 CSV file to output the CSV string of the translation.
By default this string will be returned from this method.
"""
# load the model and translate it to a CSV
model = Model.from_file(model_file)
exclude_plenums = not separate_plenum
csv_str = model_to_csv(
model, multiplier, exclude_plenums, merge_method,
metric, geometry_names, resource_names
)

return process_content_to_output(csv_str, output_file)
Loading
Loading