Addition of pyExpandObjects to src and documentation #9073

john-grando · 2021-09-18T01:39:05Z

Pull request overview

pyExpandObjects is a support tool for the EnergyPlus simulation program which pre-processes epJSON files containing HVACTemplate objects.

Much like the existing ExpandObjects program that works with IDF files in EnergyPlus, pyExpandObjects expands HVACTemplate objects from a source file into an expanded file that can be directly run in EnergyPlus, but in this case the processed files are in epJSON format. This pull request adds documentation references as outlined in the associated NFP for this project.

This PR is inserting the app as a subdirectory (src/pyExpandObjects) where users can run the program using that location as the root.

Note, an Energy+.schema.epJSON file exists in this sub-directory (src/resources/). However, this file is also created during the EnergyPlus build process, which should be the object referenced by this program. Given that the relative path to the built file may change based on the final location of this subdirectory, this update has not yet been implemented. Once this subdirectory's final location is set, then the edit will be made.

Pull Request Author

Add to this list or remove from it as applicable. This is a simple templated set of guidelines.

Title of PR should be user-synopsis style (clearly understandable in a standalone changelog context)
Label the PR with at least one of: Defect, Refactoring, NewFeature, Performance, and/or DoNoPublish
If structural output changes, add to output rules file and add OutputChange label
If adding/removing any LaTeX docs or figures, update that document's CMakeLists file dependencies

Reviewer

This will not be exhaustively relevant to every PR.

Perform a Code Review on GitHub
If branch is behind develop, merge develop and build locally to check for side effects of the merge
CI status: all green or justified
Check that performance is not impacted (CI Linux results include performance check)
Run Unit Test(s) locally

…mplate files

Myoldmopar · 2021-09-20T02:00:26Z

Is this expected to go in for the release? It's marked as draft but we are trying to get the release buttoned up. If it's ready to go, switch it to ready to review. If not, please change the milestone.

JasonGlazer · 2021-09-20T20:34:06Z

doc/auxiliary-programs/src/hvactemplateexpansion/pyexpandobjects-introduction.tex

+
+Much like the ExpandObjects program in Section~\ref{ExpandObjects}, the pyExpandObjects expands HVACTemplate objects from an input epJSON file into an expanded file that can be directly run in EnergyPlus.  However, pyExpandObjects does not process GroundHeatTransfer objects or provide support for the Slab or Basement executables.
+
+The pyExpandObjects program works as a preprocessor that maps HVACTemplate objects to regular objects in EnergyPlus.  This processor reads an epJSON file and generates and expanded epJSON file.  No further pre-processing should be required after the conversion has been performed.  Unlike ExpandObjects (Section~\ref{ExpandObjects}), a schema validation does occur when the file is read into the program, and error messages will be shown in the usual EnergyPlus error file.  By default, an invalid epJSON file will stop the program, but this requirement can be removed via command line options.  Please see the documentation (https://epjson-expandobjects.readthedocs.io/) or '--help' command line option for further details.  Additionally, the default settings produce two backup files ("<original-file-name>\_hvac\_templates.epJSON", "<original-file-name>\_base.epJSON") as well as an expanded file with an adjusted name ("<original-file-name>\_expanded.epJSON"). If the '--no-backup' option is used in the command line, then only the expanded file will be output.


The URL does not seem to be an active link in the PDF.

Also, please add the command line documentation from the readthedocs directly into this section.

Change "Please see the documentation" to something more like "Documentation aimed at developers is also available at:"

I added the command line documentation into this section, but it is also located in the InputOutputReference document. Let me know if you feel this is redundant

JasonGlazer · 2021-09-20T20:36:33Z

doc/auxiliary-programs/src/hvactemplateexpansion/pyexpandobjects-introduction.tex

+
+\subsection{Introduction}\label{pyExpandObjects}
+
+Much like the ExpandObjects program in Section~\ref{ExpandObjects}, the pyExpandObjects expands HVACTemplate objects from an input epJSON file into an expanded file that can be directly run in EnergyPlus.  However, pyExpandObjects does not process GroundHeatTransfer objects or provide support for the Slab or Basement executables.


It would probably make sense to say that it is currently not integrated with EP-Launch or from the EnergyPlus command line interface.

JasonGlazer · 2021-09-20T20:41:34Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

 \section{HVACTemplate Processing}\label{hvactemplate-processing}

-\textbf{Unlike other EnergyPlus objects, the HVACTemplate objects are not handled by EnergyPlus directly.} Instead, they are preprocessed by a program called ExpandObjects. If you use EP-Launch or RunEPlus.bat, this preprocessor step is performed automatically using the following sequence:
+\textbf{Unlike other EnergyPlus objects, the HVACTemplate objects are not handled by EnergyPlus directly.} Instead, they are preprocessed by a program called ExpandObjects or pyExpandObjects. If you use EP-Launch or RunEPlus.bat, this preprocessor step is performed automatically using the following sequence:


I don't think just adding pyExpandObjects here works well since most of the next section is about using ExpandObjects with EP-Launch and RunEPlus.bat. You just need to clarify that pyExpandObjects does not use those.

JasonGlazer · 2021-09-20T20:42:34Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

  If there are error messages from EnergyPlus, they will refer to the contents of the expidf file. Specific objects referred to in error messages may exist in the original idf, but they may be objects created by ExpandObjects and only exist in the expidf. Remember that the expidf will be overwritten everytime the original idf is run using EP-Launch or RunEPlus.bat.
 \end{enumerate}

-If you are trying to go beyond the capabilities of the HVACTemplate objects, one strategy you can use is to start your specification using the HVACTemplate objects, run EnergyPlus using EP-Launch and producing an expidf file, rename that file and start making modifications. This approach may help with getting all of the objects needed and the node names set consistently.


Keep this sentence

JasonGlazer · 2021-09-20T20:52:19Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+    Optional - A file with the name "<original-file-name>\_base.epJSON" which has all the HVACTemplate objects removed.
+  \end{enumerate}
+  \item
+    The EnergyPlus simulation proceeds using the expanded file as the input stream.


This needs to be done manually so this sentence is not really accurate right now. Maybe say something about having to specifically run the simulation on the expanded file using the EnergyPlus CLI or EP-Launch 3.

JasonGlazer · 2021-09-20T20:54:42Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+  \item
+    The EnergyPlus simulation proceeds using the expanded file as the input stream.
+  \item
+    If there are error messages from EnergyPlus, they will refer to the contents of the expanded file. Specific objects referred to in error messages may exist in the original epJSON, but they may be objects created by pyExpandObjects and only exist in the expanded file. Remember that the "<original-file-name>\_expanded.epJSON", "<original-file-name>\_hvac\_templates.epJSON", and "<original-file-name>\_base.epJSON" files will be overwritten everytime the original epJSON is run using EP-Launch or RunEPlus.bat.  Also note, the "<original-file-name>\_hvac\_templates.epJSON" and "<original-file-name>\_base.epJSON" files can be merged to recreate the original epJSON file.


change this to running it pyExpandObjects manually and then running EnergyPlus manually.

JasonGlazer · 2021-09-20T20:55:36Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+    If there are error messages from EnergyPlus, they will refer to the contents of the expanded file. Specific objects referred to in error messages may exist in the original epJSON, but they may be objects created by pyExpandObjects and only exist in the expanded file. Remember that the "<original-file-name>\_expanded.epJSON", "<original-file-name>\_hvac\_templates.epJSON", and "<original-file-name>\_base.epJSON" files will be overwritten everytime the original epJSON is run using EP-Launch or RunEPlus.bat.  Also note, the "<original-file-name>\_hvac\_templates.epJSON" and "<original-file-name>\_base.epJSON" files can be merged to recreate the original epJSON file.
+\end{enumerate}
+
+If you are trying to go beyond the capabilities of the HVACTemplate objects, one strategy you can use is to start your specification using the HVACTemplate objects, run EnergyPlus using EP-Launch and producing an expidf or epJSON file, rename that file and start making modifications. This approach may help with getting all of the objects needed and the node names set consistently.


change this to running it pyExpandObjects manually and then running EnergyPlus manually.

JasonGlazer · 2021-09-20T21:10:58Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+
+\begin{itemize}
+\item
+  -x --expandobjects : Run ExpandObjects prior to simulation


Please make it clear these are CLI options for EnergyPlus.

JasonGlazer · 2021-09-20T21:11:24Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+
+\subsubsection*{epJSON Options}\label{pyexpandobjects-cli-epjson-options}
+
+\begin{itemize}


Please make it clear these are pyExpandObjects CLI options. Maybe this belongs in the next section.

JasonGlazer · 2021-09-20T21:13:05Z

doc/input-output-reference/src/hvac-template-objects/hvactemplate-processing.tex

+
+\subsubsection*{epJSON - pyExpandObjects}
+
+The command line options noted above in section~\ref{pyexpandobjects-cli-epjson-options} for epJSON files are available in this tool (e.g. -nb, -ns).  Additionally, the following arugment can be used to specify the file.  Values passed to the program with no arguments will be assumed to be a file name.


I think the pyExpandObjects CLI options belong here.

…rogram

nrel-bot · 2021-10-21T00:18:31Z

@john-grando @lgentile it has been 28 days since this pull request was last updated.

nrel-bot-3 · 2021-12-02T00:21:15Z

@john-grando @lgentile it has been 28 days since this pull request was last updated.

nrel-bot-3 · 2021-12-30T01:09:43Z

@john-grando @lgentile it has been 28 days since this pull request was last updated.

nrel-bot-3 · 2022-01-27T00:26:11Z

@john-grando @lgentile it has been 28 days since this pull request was last updated.

nrel-bot-2 · 2025-04-12T00:22:06Z

@Myoldmopar @john-grando it has been 8 days since this pull request was last updated.

nrel-bot-2 · 2025-04-19T00:28:42Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-05-04T00:42:31Z

@Myoldmopar @john-grando it has been 15 days since this pull request was last updated.

nrel-bot-2 · 2025-05-13T00:40:35Z

@Myoldmopar @john-grando it has been 9 days since this pull request was last updated.

nrel-bot-2 · 2025-05-21T15:02:39Z

@Myoldmopar @john-grando it has been 9 days since this pull request was last updated.

nrel-bot-2 · 2025-05-30T01:51:10Z

@Myoldmopar @john-grando it has been 8 days since this pull request was last updated.

nrel-bot-2c · 2025-06-12T16:09:29Z

@Myoldmopar @john-grando it has been 14 days since this pull request was last updated.

nrel-bot-2c · 2025-06-25T00:33:42Z

@Myoldmopar @john-grando it has been 12 days since this pull request was last updated.

nrel-bot-2c · 2025-07-03T00:59:02Z

@Myoldmopar @john-grando it has been 8 days since this pull request was last updated.

nrel-bot-2 · 2025-07-11T01:14:25Z

@Myoldmopar @john-grando it has been 8 days since this pull request was last updated.

nrel-bot-2c · 2025-07-21T01:12:46Z

@Myoldmopar @john-grando it has been 10 days since this pull request was last updated.

nrel-bot-2c · 2025-08-02T00:50:44Z

@Myoldmopar @john-grando it has been 12 days since this pull request was last updated.

nrel-bot-2 · 2025-09-30T01:09:24Z

@Myoldmopar @john-grando it has been 59 days since this pull request was last updated.

nrel-bot-2c · 2025-10-07T00:53:45Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2025-10-14T00:40:38Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2025-10-21T00:42:42Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2025-10-29T00:59:55Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2025-11-05T01:17:52Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-11-12T00:44:12Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-11-19T01:20:52Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2025-11-26T00:58:10Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-12-03T00:44:39Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-12-10T01:15:28Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-12-17T00:48:37Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-12-24T00:43:37Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2 · 2025-12-31T00:43:04Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2026-01-07T00:47:45Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2026-01-14T00:43:38Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

nrel-bot-2c · 2026-01-21T01:25:16Z

@Myoldmopar @john-grando it has been 7 days since this pull request was last updated.

John Grando and others added 11 commits July 1, 2021 21:43

pyExpandObjects documentation additions

12a189b

renamed chapter headings and reorganized file structure

71bc351

Merge remote-tracking branch 'origin/develop' into pyexpandobjects

aa85ba0

updated covered templates for pyexpandobjects

9672c6d

Merge remote-tracking branch 'origin/develop' into pyexpandobjects

9d74042

documentation update

30ea4a8

pyexpandobjects tweaks

fc5b460

edit url link reference

3956ea5

edited command line argument syntax

11317fb

Merge branch 'NREL:develop' into pyexpandobjects

ccc67a9

updated auxilary programs CMakeLists to be consistent with new hvacte…

2890366

…mplate files

JasonGlazer requested changes Sep 20, 2021

View reviewed changes

John Grando added 5 commits September 20, 2021 20:43

added command line option to pyexpandobjects documentation

d820d03

reformatted documentation to describe pyExpandObjects as standalone p…

9ba9351

…rogram

pyExpandObjects documentation updates responding to comments

3a715d6

separation of pyEO and EO characteristics

feac5e5

added pyExpandObjects to src

6d60510

john-grando changed the title ~~Documentation Update for pyExpandObjects~~ Addition of pyExpandObjects to src and documentation Sep 22, 2021

john-grando requested a review from JasonGlazer September 22, 2021 03:34

brought branch up to date with develop and merge conflicts

b49d388

mjwitte added the NewFeature Includes code to add a new feature to EnergyPlus label Oct 21, 2021

John Grando added 2 commits October 30, 2021 20:48

reduced package size for implementation

aaf113c

removed pyexpandobjects workflows

e3d388d

mjwitte marked this pull request as ready for review November 1, 2021 21:38

mjwitte added this to the EnergyPlus 22.1 milestone Feb 8, 2022

mitchute removed this from the EnergyPlus 24.2 milestone Oct 21, 2025


		Much like the ExpandObjects program in Section~\ref{ExpandObjects}, the pyExpandObjects expands HVACTemplate objects from an input epJSON file into an expanded file that can be directly run in EnergyPlus. However, pyExpandObjects does not process GroundHeatTransfer objects or provide support for the Slab or Basement executables.

		The pyExpandObjects program works as a preprocessor that maps HVACTemplate objects to regular objects in EnergyPlus. This processor reads an epJSON file and generates and expanded epJSON file. No further pre-processing should be required after the conversion has been performed. Unlike ExpandObjects (Section~\ref{ExpandObjects}), a schema validation does occur when the file is read into the program, and error messages will be shown in the usual EnergyPlus error file. By default, an invalid epJSON file will stop the program, but this requirement can be removed via command line options. Please see the documentation (https://epjson-expandobjects.readthedocs.io/) or '--help' command line option for further details. Additionally, the default settings produce two backup files ("<original-file-name>\_hvac\_templates.epJSON", "<original-file-name>\_base.epJSON") as well as an expanded file with an adjusted name ("<original-file-name>\_expanded.epJSON"). If the '--no-backup' option is used in the command line, then only the expanded file will be output. No newline at end of file


		\subsection{Introduction}\label{pyExpandObjects}

		Much like the ExpandObjects program in Section~\ref{ExpandObjects}, the pyExpandObjects expands HVACTemplate objects from an input epJSON file into an expanded file that can be directly run in EnergyPlus. However, pyExpandObjects does not process GroundHeatTransfer objects or provide support for the Slab or Basement executables.


		\subsubsection*{epJSON Options}\label{pyexpandobjects-cli-epjson-options}

		\begin{itemize}


		\subsubsection*{epJSON - pyExpandObjects}

		The command line options noted above in section~\ref{pyexpandobjects-cli-epjson-options} for epJSON files are available in this tool (e.g. -nb, -ns). Additionally, the following arugment can be used to specify the file. Values passed to the program with no arguments will be assumed to be a file name.

Addition of pyExpandObjects to src and documentation #9073

Are you sure you want to change the base?

Addition of pyExpandObjects to src and documentation #9073

Uh oh!

Conversation

john-grando commented Sep 18, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request overview

Pull Request Author

Reviewer

Uh oh!

Myoldmopar commented Sep 20, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nrel-bot commented Oct 21, 2021

Uh oh!

nrel-bot-3 commented Dec 2, 2021

Uh oh!

nrel-bot-3 commented Dec 30, 2021

Uh oh!

nrel-bot-3 commented Jan 27, 2022

Uh oh!

nrel-bot-2 commented Apr 12, 2025

Uh oh!

nrel-bot-2 commented Apr 19, 2025

Uh oh!

nrel-bot-2 commented May 4, 2025

Uh oh!

nrel-bot-2 commented May 13, 2025

Uh oh!

nrel-bot-2 commented May 21, 2025

Uh oh!

nrel-bot-2 commented May 30, 2025

Uh oh!

nrel-bot-2c commented Jun 12, 2025

Uh oh!

nrel-bot-2c commented Jun 25, 2025

Uh oh!

nrel-bot-2c commented Jul 3, 2025

Uh oh!

nrel-bot-2 commented Jul 11, 2025

Uh oh!

nrel-bot-2c commented Jul 21, 2025

Uh oh!

nrel-bot-2c commented Aug 2, 2025

Uh oh!

nrel-bot-2 commented Sep 30, 2025

Uh oh!

nrel-bot-2c commented Oct 7, 2025

Uh oh!

nrel-bot-2c commented Oct 14, 2025

Uh oh!

nrel-bot-2c commented Oct 21, 2025

Uh oh!

nrel-bot-2c commented Oct 29, 2025

Uh oh!

nrel-bot-2c commented Nov 5, 2025

Uh oh!

nrel-bot-2 commented Nov 12, 2025

john-grando commented Sep 18, 2021 •

edited

Loading