Python HVAC-Diagram

design/FY2022/NFP-Python-HVAC-Diagram.md

@@ -0,0 +1,85 @@
+# Python HVAC Diagram #
+
+Jason DeGraw, Piljae Im, and Niraj Kunwar
+
+Oak Ridge National Laboratory
+
+Original Date: November 18, 2021
+
+## Justification for New Feature ##
+
+The HVAC-Diagram program is a Fortran utility that can be used to generate
+an SVG representation of the HVAC system in a model based on the BND file
+generated by EnergyPlus. The program has limited flexibility and the SVG
+output is not correctly rendered by all SVG rendering libraries. The SVG format
+[1] is a large and complex format with many capabilities but is somewhat
+overpowered for this application.
+
+## Overview ##
+
+A Python replacement for the utility will be developed to produce output similar
+to the functionality of the original utility. While SVG output will be considered,
+prioirity will be placed on production of output that conveys the same information
+in a more reliable manner.
+
+## Approach ##
+
+The BND output from EnergyPlus will be used to generate several forms of output:
+
+* One or more DOT language [2] files. This format is used by the
+  open source Graphviz package to display and manipulate graphs. Other formats
+  will be considered depending on development team feedback.
+* An HTML-based representation, if possible in a single file. Modern browser
+  capabilities can be leveraged to produce semi-interactive representation of the
+  HVAC loops (e.g. simple controls to turn on/off node names or other ancilliary
+  information). Numerous visualization libraries are available (e.g. D3, p5.js) as
+  well as more traditional techniques (e.g. canvas, imagemaps).
+* [Under consideration] An SVG representation that closely duplicates
+  the output of the original utility.
+
+The functionality will be implemented as a Python class that is initialized with
+input data (e.g. the BND file) and has the capability to produce the output
+described above. The script will be usable as a "packaged" executable and as a
+pure Python script. Dependencies will be kept to a minimum.
+
+## Reference Documentation ##
+
+Appropriate documentation of the script will be provided in the auxiliary
+programs documentation. Online documetation will be provided via the Python 
+`argparse` package. The current command line interface documentation is:
+
+```
+usage: hvac-diagram.py [-h] [-d] [-o file] BND
+
+Generate a diagram of HVAC in an EnergyPlus model
+
+positional arguments:
+  BND                   EnergyPlus BND file to process
+
+options:
+  -h, --help            show this help message and exit
+  -d, --dot             Generate a graphviz DOT graph
+  -o file, --output file
+                        write output to named file
+```
+
+## Input Description ##
+
+The program will initially make use of the BND file as input but may require
+either extension of the BND or information from the epJSON.
+
+## Output Description ##
+
+The outputs of the program are one or more files that enable graphical rendering
+of the HVAC setup of the model. The simple graph description in the DOT language
+will enable users to import that graph into any software that can understand the
+format, but will require additional user effort to understand. The HTML output is
+intended to be a more full-featured representation of the HVAC with interactive
+features (optional display of node names, etc.) with fewer possibilities of bad
+rendering.
+
+## References ##
+
+[1] SVG: Scalable Vector Graphics, https://developer.mozilla.org/en-US/docs/Web/SVG
+
+[2] DOT Language, https://graphviz.org/doc/info/lang.html