Correction of Various Documentation Issues #8826

RKStrand · 2021-06-16T21:48:21Z

Pull request overview

Fixes Documentation Issues 2021a #8277
The purpose of this pull request is the implementation of a host of documentation fixes in various EnergyPlus documents. Most of the changes were in the Input Output Reference, but there were changes in several other documents as well. The issues dealt with are too numerous to repeat here. Consult Documentation Issues 2021a #8277 for a full checklist of what was resolved in this work. A few typos were also corrected in the code (comment lines) and the IDD. No changes were made to any logic.
Fixes EMS actuator key names in the documentation and in the source code may not match #6974
Fixes I/O Ref should indicate which output variables are only available for interior or exterior windows #4306

Diffs expected for 1ZoneUncontrolledWithHysteresisPCM due to input file change.

Pull Request Author

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

Reviewer

This will not be exhaustively relevant to every PR.

A good portion, but not all, of the changes requested as part of 8277 (or referred to 8277). These are mostly documentation fixes. The few code or IDD fixes are simply correcting typos.

Update to variables that can be output for interior windows and other minor edits.

Last changes required to IO Reference to address issues related to extensible IDD and many other edits.

mjwitte

@RKStrand Some initial comments. If you scroll through the changes page on the PR, you'll see some warnings in yellow and at the end there are some errors reported (which you did not introduce, I think I actually did those). If you can clean those up here, that would be good.

mjwitte · 2021-06-17T22:31:23Z

idd/Energy+.idd.in

@@ -5,6 +5,14 @@
 ! The IDD defines the syntax and data model for each type of input "Object."
 ! Lines in EnergyPlus input files (and IDD) are limited to 500 characters.
 !
+!
+! Note on IDD Processing/Usage


This entire block of comments also appear in the I/O Reference. I would just copy from the IDD to update the entire block (which may be out of date in other ways0.

Fixed--see next commit.

mjwitte · 2021-06-17T22:36:12Z

doc/input-output-reference/src/overview/group-advanced-surface-concepts.tex

@@ -2294,7 +2292,7 @@ \subsubsection{Inputs}\label{inputs-13}

 \paragraph{Field(s): Surface \textless{}1 thru x\textgreater{} Name}\label{fields-surface-1-thru-x-name}

-The remaining fields are used to name the \textbf{\hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed}} objects that are associated with the exterior naturally vented cavity. These are the underlying heat transfer surfaces and are defined elsewhere in the input file. These surfaces should all specify OtherSideConditionsModel as their exterior environment. The input object can currently accommodate up to ten surfaces, but it is extensible by modifying the Energy+.idd entry.
+The remaining fields are used to name the \textbf{\hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed}} objects that are associated with the exterior naturally vented cavity. These are the underlying heat transfer surfaces and are defined elsewhere in the input file. These surfaces should all specify OtherSideConditionsModel as their exterior environment. The input object can currently accommodate up to ten surfaces.


This object is extensible, not limited to 10 surfaces. Also, the introductory paragraph for this object, SurfaceProperty:ExteriorNaturalVentedCavity, needs editing, it still says "(although if you need to use more than 10 surfaces, then the IDD will need to be extended)."

Wow--good catch. I thought I got all of those but clearly missed this one. Will be fixed in the next commit.

mjwitte · 2021-06-17T22:43:42Z

doc/input-output-reference/src/overview/group-electric-load-center-generator.tex

@@ -524,7 +524,7 @@ \subsubsection{Outputs}\label{outputs-1-008}

 \subsection{ElectricLoadCenter:Generators}\label{electricloadcentergenerators}

-The ElectricLoadCenter:Generators object is used to provide a list of the generators to include in the simulation. The list includes the names and types of all the generators along with separate availability schedules, the rated power output, and thermal-to-electrical power ratio for each. Sets of five input fields are repeated for each generator. If more than 30 generators are needed, EnergyPlus will auto-extend to suit the needs but other interfaces (such as the IDF Editor may not). The user can always modify the Energy+.idd file to accommodate the extra fields necessary, but it is likely the next release of EnergyPlus will overwrite any user modifications.
+The ElectricLoadCenter:Generators object is used to provide a list of the generators to include in the simulation. The list includes the names and types of all the generators along with separate availability schedules, the rated power output, and thermal-to-electrical power ratio for each. Sets of five input fields are repeated for each generator. If more than 30 generators are needed, EnergyPlus will auto-extend to suit the needs but other interfaces (such as the IDF Editor) may not. The user can always modify the Energy+.idd file to accommodate the extra fields necessary, but it is likely the next release of EnergyPlus will overwrite any user modifications.


"If more than 30 generators are needed, EnergyPlus will auto-extend to suit the needs but other interfaces (such as the IDF Editor) may not. The user can always modify the Energy+.idd file to accommodate the extra fields necessary, but it is likely the next release of EnergyPlus will overwrite any user modifications." I would replace this with the standard This object is extensible sentence.

Good call--will be fixed in the next commit.

mjwitte · 2021-06-17T22:50:30Z

doc/input-output-reference/src/overview/group-refrigeration.tex

@@ -1055,7 +1055,7 @@ \subsubsection{Field: Insulated Floor U-Value}\label{field-insulated-floor-u-val

 The floor themal transmittance (in W/m\(^{2}\)-K). This value has a default value of 0.3154. (This corresponds to R18 in Archaic American Insulation Units.~ To convert other R-values to thermal transmittance, divide 5.678 by the R-value.~ For example, R15 is 0.3785 W/m\(^{2}\)-K and R5 is 1.136 W/m\(^{2}\)-K.)

-\textbf{\emph{THE REMAINING 12 FIELDS FOR THE WALK-IN COOLER MUST BE REPEATED FOR EACH ZONE WHICH IS IN CONTACT WITH A WALK-IN WALL, CEILING, OR DOOR. The IDD includes fields for 3 zones, but can be extended by repeating the last 12 values in the object.}}
+\textbf{\emph{THE REMAINING 12 FIELDS FOR THE WALK-IN COOLER MUST BE REPEATED FOR EACH ZONE WHICH IS IN CONTACT WITH A WALK-IN WALL, CEILING, OR DOOR.  This field is extensible, so additional fields of this type can be added to the end of this object by repeating the last 12 values in the object.}}


This object is extensible.
Actually, most of the places that say "This field is extensible..." probably should say "This object is extensible" I guess saying "this field" is ok for places where it's just a single extensible field.

Generally my pattern was if it was a single field I used the term field. If it was a group of fields that were repeated, I adjusted the language to say that. Are you ok with that? If not, I'll go through and change them.

I'm in the process of changing everything to "This object is extensible..." and cleaning up how these some of these show up in the docs. So ignore the question from the above comment.

mjwitte · 2021-06-17T22:54:00Z

doc/input-output-reference/src/overview/group-demand-limiting-controls.tex


 The name of a DemandManager object defined elsewhere in the input file.

-DemandManagers are listed by pairs of data items: \emph{Demand Manager Type} and \emph{Demand Manager Name}. Ten managers are accommodated in the list by default. The IDD specification, however, is extensible and additional pairs may be added by directly editing the IDD.
+DemandManagers are listed by pairs of data items: \emph{Demand Manager Type} and \emph{Demand Manager Name}. These two fields are extensible, so up to 10 additional pairs of these fields can be added to the end of this object.


This object is extensible, so ~~up to 10~~ additional pairs of these fields ....

Got it--fixed in the next commit.

mjwitte · 2021-06-17T22:55:44Z

doc/input-output-reference/src/overview/group-solar-collectors.tex

@@ -666,7 +666,7 @@ \subsection{SolarCollector:UnglazedTranspired}\label{solarcollectorunglazedtrans

 This object is used to model unglazed transpired solar collectors (UTSC) used to condition outdoor air. These collectors are generally used to heat air drawn through perforated absorbers that are heated by the sun and also recover heat conducted out through the underlying wall. The SolarCollector:UnglazedTranspired object represents a single collector attached to one or more \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects and to one or more outdoor air systems. Therefore the transpired collector is part of both the thermal envelope and the HVAC system. An example file is provided called TranspiredCollectors.idf.

-The area and orientation of the collector is obtained from \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects, which are referenced by name. Although the collector surface itself is slightly detached from the underlying building wall (or roof), no additional surface object is needed to represent the collector itself. When modeling transpired collectors, it is important to consider the size of the collector when developing the building model's \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects because the underlying surfaces must match the collector. For example, if the collector covers only part of the wall, then that wall should be split into separate surfaces where one matches the size of the collector. A single collector can be associated with as many \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects as desired (although if you need to use more than 10 surfaces, then the IDD will need to be extended). The collector can be arranged at any tilt angle by describing the surfaces appropriately. The surfaces need not be contiguous nor have the same orientation, but the program will issue warnings if surfaces have widely ranging tilts and azimuths.
+The area and orientation of the collector is obtained from \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects, which are referenced by name. Although the collector surface itself is slightly detached from the underlying building wall (or roof), no additional surface object is needed to represent the collector itself. When modeling transpired collectors, it is important to consider the size of the collector when developing the building model's \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects because the underlying surfaces must match the collector. For example, if the collector covers only part of the wall, then that wall should be split into separate surfaces where one matches the size of the collector. A single collector can be associated with as many \hyperref[buildingsurfacedetailed]{BuildingSurface:Detailed} objects as desired since this field is extensible. The collector can be arranged at any tilt angle by describing the surfaces appropriately. The surfaces need not be contiguous nor have the same orientation, but the program will issue warnings if surfaces have widely ranging tilts and azimuths.


For this object, the Surface <#> Name field still says "can currently accommodate up to ten surfaces, but it is extensible." I would change that to your standard extensible sentence.

Fixed in next commit

mjwitte

@RKStrand Lots of good stuff here. A few more comments to complete the initial review.

mjwitte · 2021-06-18T01:46:41Z

doc/input-output-reference/src/overview/group-pumps.tex

-For VFD Control Type = PressureSetPointControl, this field defines the minimum allowable RPM, or the lower bound of pump speed to use when determining the required pump speed. For VFD Control Type = ManualControl, this field is not interpreted. The value of the schedule is RPM.
+For VFD Control Type = ManualControl, this field defines the minimum allowable RPM, or
+the lower bound of pump speed to use when determining the required pump speed. For VFD Control Type = PressureSetPointControl, this field is not interpreted. The value of the schedule is RPM.

 \paragraph{Field: Maximum RPM Schedule}\label{field-maximum-rpm-schedule}

-For VFD Control Type = PressureSetPointControl, this field defines the maximum allowable RPM, or the upper bound of pump speed to use when determining the required pump speed. For VFD Control Type = ManualControl, this field is not interpreted. The value of the schedule is RPM.
+For VFD Control Type = ManualControl, this field defines the maximum allowable RPM, or
+the upper bound of pump speed to use when determining the required pump speed. For VFD Control Type = PressureSetPointControl, this field is not interpreted. The value of the schedule is RPM.


Revert these. It was correct before. See comment here.

Reverted in next commit.

mjwitte · 2021-06-18T01:51:33Z

doc/ems-application-guide/src/user-defined-component-models/plant-component.tex

@@ -119,7 +123,7 @@ \subsection{Ambient Zone}\label{ambient-zone-001}
 \item
 An actuator called ``Component Zone Internal Gain'' with the control type ``Sensible Heat Gain Rate,'' in {[}W{]}, is available.~ This can be used for purely convective sensible heat gains (or losses) to a zone.
 \item
- An actuator called ``Component Zone Internal Gain'' with the control type ``Return Air Heat Gain Rate,'' in {[}W{]}, is available.~ This can be used for purely convective sensible heat gains (or losses) to the return air duct for a zone.
+ An actuator called ``Component Zone Internal Gain'' with the control type ``Return Air Heat Sensible Gain Rate,'' in {[}W{]}, is available.~ This can be used for purely convective sensible heat gains (or losses) to the return air duct for a zone.


Thanks for the thorough review and updates on the EMS actuators!

Thanks--this one would have been easy to overlook!

mitchute

Lot's of good stuff here. There's too much in the original issue to go line by line checking this, but I'm OK with the changes. I think there may be a few other comments left so we can get this in once that's all wrapped up.

mitchute · 2021-06-18T15:50:01Z

doc/input-output-reference/src/overview/group-surface-construction-elements.tex

+
+The \hyperref[materialpropertyphasechangehysteresis]{MaterialProperty:PhaseChangeHysteresis} object also includes the following outputs. The Conduction Finite Difference solution algorithm uses a finite difference solution technique where the surfaces are divided into a nodal arrangement. These outputs are specific to Conduction Finite Difference solution.
+
+The following output variables are applicable to all opaque heat transfer surfaces when using Solution Algorithms ConductionFiniteDifference. Note that the "X" in the list and descriptions below must be replaced by a number that indicates the node at which the variables are being reported. So, for example, to report the surface temperature for node 7, one would use "CondFD Surface Temperature Node 7".


If you're already making changes, change the " to "``" (two backticks for the left side) and "''" (two apostrophes for the right side).

Got it--actually ``them'' because there were two copies of this in this file. Should be fixed in the next commit.

mitchute · 2021-06-18T16:02:35Z

doc/input-output-reference/src/overview/group-zone-forced-air-units.tex

@@ -2938,9 +2938,9 @@ \subsubsection{Inputs}\label{inputs-10-024}

 The name of the third air chiller that will be used to meet the zone cooling load.


It doesn't look like you caused this, but can you address this warning? Are there plans elsewhere to fix the other LaTeX build issues that have surface recently?

If this is in reference to the build warnings that pop up at the bottom of the Files Changed tab on all the PRs, those are now addressed in develop.

Myoldmopar · 2021-06-22T18:18:05Z

With the PR I just merged about the IORef (#8836) in develop now, this branch should have develop pulled up before merging. @RKStrand do you have any additional work to make on this? If not I'll merge develop and push it up.

@mjwitte @mitchute do you have any additional reviewing to do on this or is it ready if CI comes back clean?

RKStrand · 2021-06-22T18:22:07Z

@Myoldmopar I'm still working through the review comments. Might be done and ready for the next review later today, but I'm not really sure.

Additional changes were made based on review comments received from other development team members. Should be ready for the next review now.

RKStrand · 2021-06-22T19:25:52Z

@Myoldmopar @mjwitte @mitchute Ok, I think I have addressed all of the comments above and brought develop into this branch as well. Hopefully everything comes back clean now. Let me know if there is anything else that needs to be done here. Thanks!

mjwitte

@RKStrand Changes to address comments look good.

RKStrand added 4 commits June 14, 2021 10:08

Some of the changes for 8277

2327efd

A good portion, but not all, of the changes requested as part of 8277 (or referred to 8277). These are mostly documentation fixes. The few code or IDD fixes are simply correcting typos.

Merge branch 'develop' into 8277DocumentationIssues2021a

0c9acac

Update to Interior Window Output

2612620

Update to variables that can be output for interior windows and other minor edits.

Remaining changes to IORef

22171a9

Last changes required to IO Reference to address issues related to extensible IDD and many other edits.

RKStrand added Defect Includes code to repair a defect in EnergyPlus Documentation Related primarily on the LaTeX-based EnergyPlus documentation labels Jun 16, 2021

RKStrand requested review from Myoldmopar, mitchute and mjwitte June 16, 2021 21:48

RKStrand self-assigned this Jun 16, 2021

mjwitte removed request for Myoldmopar and mitchute June 17, 2021 22:04

mjwitte reviewed Jun 17, 2021

View reviewed changes

mjwitte reviewed Jun 18, 2021

View reviewed changes

mitchute reviewed Jun 18, 2021

View reviewed changes

RKStrand added 2 commits June 22, 2021 14:24

Resolution of Review Comments

02fa74a

Additional changes were made based on review comments received from other development team members. Should be ready for the next review now.

Merge branch 'develop' into 8277DocumentationIssues2021a

f53cb64

mjwitte approved these changes Jun 22, 2021

View reviewed changes

mjwitte merged commit 7415d82 into develop Jun 22, 2021

mjwitte deleted the 8277DocumentationIssues2021a branch June 22, 2021 22:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Correction of Various Documentation Issues #8826

Correction of Various Documentation Issues #8826

RKStrand commented Jun 16, 2021 •

edited by mjwitte

Loading

mjwitte left a comment

mjwitte Jun 17, 2021

RKStrand Jun 18, 2021

mjwitte Jun 17, 2021

RKStrand Jun 18, 2021

mjwitte Jun 17, 2021

RKStrand Jun 18, 2021

mjwitte Jun 17, 2021

RKStrand Jun 18, 2021

RKStrand Jun 22, 2021

mjwitte Jun 17, 2021

RKStrand Jun 18, 2021

mjwitte Jun 17, 2021

RKStrand Jun 22, 2021

mjwitte left a comment

mjwitte Jun 18, 2021

RKStrand Jun 22, 2021

mjwitte Jun 18, 2021

RKStrand Jun 22, 2021

mitchute left a comment

mitchute Jun 18, 2021

RKStrand Jun 22, 2021

mitchute Jun 18, 2021

Myoldmopar Jun 22, 2021

Myoldmopar commented Jun 22, 2021

RKStrand commented Jun 22, 2021

RKStrand commented Jun 22, 2021

mjwitte left a comment


		The \hyperref[materialpropertyphasechangehysteresis]{MaterialProperty:PhaseChangeHysteresis} object also includes the following outputs. The Conduction Finite Difference solution algorithm uses a finite difference solution technique where the surfaces are divided into a nodal arrangement. These outputs are specific to Conduction Finite Difference solution.

		The following output variables are applicable to all opaque heat transfer surfaces when using Solution Algorithms ConductionFiniteDifference. Note that the "X" in the list and descriptions below must be replaced by a number that indicates the node at which the variables are being reported. So, for example, to report the surface temperature for node 7, one would use "CondFD Surface Temperature Node 7".

		@@ -2938,9 +2938,9 @@ \subsubsection{Inputs}\label{inputs-10-024}

		The name of the third air chiller that will be used to meet the zone cooling load.

Correction of Various Documentation Issues #8826

Correction of Various Documentation Issues #8826

Conversation

RKStrand commented Jun 16, 2021 • edited by mjwitte Loading

Pull request overview

Pull Request Author

Reviewer

mjwitte left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjwitte left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mitchute left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Myoldmopar commented Jun 22, 2021

RKStrand commented Jun 22, 2021

RKStrand commented Jun 22, 2021

mjwitte left a comment

Choose a reason for hiding this comment

RKStrand commented Jun 16, 2021 •

edited by mjwitte

Loading