diff --git a/design/FY2022/NFP-Python-HVAC-Diagram.md b/design/FY2022/NFP-Python-HVAC-Diagram.md new file mode 100644 index 00000000000..451ce37ecd4 --- /dev/null +++ b/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