Documentation Issue 2019b

mjwitte commented 5 years ago

Issue overview

A collection of minor documentation issues. See comments below for additional items.

[x] I/O Ref "Zone Equipment Input Syntax Map" figure is missing.
[x] I/O Ref "Representative Zone Equipment" figure is missing (next the previous one)

Details

Some additional details for this issue (if relevant):

Platform (Operating system, version)
Version of EnergyPlus (if using an intermediate build, include SHA)
Unmethours link or helpdesk ticket number

Checklist

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

[x] Defect file added (list location of defect file here): N/A
[x] Ticket added to Pivotal for defect (development team task)
[ ] Pull request created (the pull request will have additional tasks related to reviewing changes that fix this defect)

Nigusse commented 5 years ago

[x] Fan:SystemModel is missing as a valid fan type in FanPerformance:NightVentilation object in I/O reference documentation here.

mldichter commented 5 years ago

[x] Broken link on page 2639 https://www.energy.ca.gov/title24/2005standards/archive/rulemaking/documents/tdv/index.html

mldichter commented 5 years ago

[x] Typo "crwon" in IO Ref 9.1

Typographical errors are common and many of them can be fixed with a simple spellchecker.

crwon

shorowit commented 5 years ago

[x] There are a bunch of old EnergyPlus links in the Tips & Tricks documentation, perhaps others. Here's an example:

mitchute commented 5 years ago

[x] IORef Figure 1.111 is missing a caption.

Also:

[ ] the X in the legend for "X - requires separate refrigeration system" should be red in this chart.
[ ] the Fan:SystemModel is not included in the multiple occurrences of this chart

Original Word file with charts (needs updating): FillGaps_HVACComponents_ParentChildMatrix_ExistingCapabilities.docx

mitchute commented 5 years ago

[x] Some figures do not appear in the docs (on mac, at least). For example, Figure 1.110.

This happens for docs downloaded from GitHub and when built locally.

shorowit commented 5 years ago

[x] The example IDF object for Output:Table:Annual has an extra field "Report Group Name" that isn't in the IDD.

Documentation:

Output:Table:Annual,
  Custom Annual Window Report,  !- Name
  , !- Report Group Name                        <---- ???
  , !- Filter
  , !- Schedule Name
........

IDD:

Output:Table:Annual,
       \memo Provides a generic method of setting up tables of annual results with one row per object.
       \memo The report has multiple columns that are each defined using a repeated group of fields
       \memo for any number of columns. A single Output:Table:Annual produces a single table in the
       \memo output.
       \extensible:3
   A1, \field Name
       \required-field
       \type alpha
   A2, \field Filter
       \type alpha
       \note An optional text string that is compared to the names of the objects referenced by the
       \note variables and if they match are included in the table. A footnote will appear that indicates
       \note that the objects shown may not be all the objects that of that type that occur in the file.
   A3, \field Schedule Name
       \type object-list
       \object-list ScheduleNames
       \note Optional schedule name. If left blank, aggregation is performed for all hours simulated. If
       \note a schedule is specified, aggregation is performed for non-zero hours in the schedule.
........

mjwitte commented 4 years ago

[x] Input Output Reference for CoolingTower:VariableSpeed:Merkel does not mention these input fields but they are in the idd file:

N17, \field Design Inlet Air Dry-Bulb Temperature N18, \field Design Inlet Air Wet-Bulb Temperature N19, \field Design Approach Temperature N20, \field Design Range Temperature

energysims commented 4 years ago

[x] Input Output Reference is also missing descriptions of these input fields in the single and two speed cooling towers.

CoolingTower:SingleSpeed, N13, \field Design Inlet Air Dry-Bulb Temperature N14, \field Design Inlet Air Wet-Bulb Temperature N15, \field Design Approach Temperature N16, \field Design Range Temperature

CoolingTower:TwoSpeed, N21, \field Design Inlet Air Dry-Bulb Temperature N22, \field Design Inlet Air Wet-Bulb Temperature N23, \field Design Approach Temperature N24, \field Design Range Temperature

energysims commented 4 years ago

[x] Input Output Reference discussion of CoolingTower:VariableSpeed:Merkel is missing value inside quotes in discussion of 1.24.4.1.4 Field: Performance Input Method. “” should be replaced with “UFactorTimesAreaAndDesignWaterFlowRate” in the second sentence below.

This alpha field contains the method by which the user will specify tower performance: “UFactorTimesAreaAndDesignWaterFlowRate” or “NominalCapacity”. If this field is left blank in the input data file, the default input method is assumed to be “NominalCapacity”. If the method “” is selected, then the user must enter design UA values, design water flow rates and air flow rates as described for the previous input fields.

eringold commented 4 years ago

[x] I/O reference groups all 'Outputs' at the bottom of the 'Group - Room Air Models' section, not after the relevant object input fields.

For example, "1.12.10 RoomAirSettings:ThreeNodeDisplacementVentilation" lists the inputs, then is followed immediately by "1.12.11 RoomAirSettings:CrossVentilation". The outputs for the three node object don't appear until 1.12.19.5, fourteen pages later. As a user, I expect to find all object-specific outputs described immediately after the object input description.

shorowit commented 4 years ago

[ ] The Field: Solar Distribution says for FullExterior: "... transmitted diffuse radiation, which is assumed to be uniformly distributed on all interior surfaces." However, the Surface Inside Face Initial Transmitted Diffuse Absorbed Solar Radiation Rate output suggests this is no longer correct as it states: "As of Version 2.1, diffuse solar transmitted through exterior and interior windows is no longer uniformly distributed. Instead, it is distributed according to the approximate view factors between the transmitting window and all other heat transfer surfaces in the zone."

JasonGlazer commented 4 years ago

[x] The headings of this table seem messed up in the IOref 9.2

mldichter commented 4 years ago

[x] In the Controller:MechanicalVentilation object documentation and ~IDF Editor~ IDD, change field Zone <x> Name to Zone or ZoneList <x> Name as this field does accept a ZoneList object.

jmarrec commented 4 years ago

@mitchute wrote:

* [ ]  Some figures do not appear in the docs (on mac, at least). For example, [Figure 1.110](https://github.com/NREL/EnergyPlus/blob/fd07e7599f8b921178db9ced3f96aba53c39d582/doc/input-output-reference/src/overview/group-air-distribution.tex#L555).

It seems all of these png that do not display correctly in the PDF are RGB Color 16-bit gamma integer, while others that work fine are 8-bit. If I open the 16bit png in GIMP, and change the precision from 16-bit to 8-bit, suddenly it works.

Unix: file *.png | /bin/grep "16-bit"

jmarrec commented 4 years ago

@shorowit re https://github.com/NREL/EnergyPlus/issues/7451#issuecomment-552662680.

The Field: Solar Distribution says for FullExterior:

Beam solar radiation entering the zone is treated as for MinimalShadowing – All beam solar radiation entering the zone is assumed to fall on the floor, where it is absorbed according to the floor’s solar absorptance. Any reflected by the floor is added to the transmitted diffuse radiation, which is assumed to be uniformly distributed on all interior surface

Now if you look at Surface Inside Face Initial Transmitted Diffuse Absorbed Solar Radiation Rate, and keep reading on:

As of Version 2.1, diffuse solar transmitted through exterior and interior windows is no longer uniformly distributed. Instead, it is distributed according to the approximate view factors between the transmitting window and all other heat transfer surfaces in the zone. This variable is the amount of transmitted diffuse solar that is initially absorbed on the inside of each heat transfer surface. The portion of this diffuse solar that is reflected by all surfaces in the zone is subsequently redistributed uniformly to all heat transfer surfaces in the zone, along with interior reflected beam solar and shortwave radiation from lights. The total absorbed shortwave radiation is given by the next variable

I think there isn't an actual problem here. Thoughts anyone?

mjwitte commented 4 years ago

@jmarrec @shorowit There is some confusion here between initial transmitted diffuse and reflected diffuse. The description for Surface Inside Face Initial Transmitted Diffuse Absorbed Solar Radiation Rate properly distinguishes between the two. The descriptions for Solar Distribution don't seem to make that distinction very clear. I did a quick check of the code to confirm how reflected diffuse is used (and the equations are laid out in the Engineering Reference under Interior Diffuse Radiation.

So in the Building Solar Distribution options, "Any reflected by the floor is added to the transmitted diffuse radiation" should read "... added to the reflected diffuse radiation ...".

And the overall Solar Distribution description could use a few sentences explaining how diffuse is treated - using the laguage from the output variable description, something like this:

"Diffuse solar transmitted through exterior and interior windows is distributed according to the approximate view factors between the transmitting window and all other heat transfer surfaces in the zone. The portion of this diffuse solar that is reflected by all surfaces in the zone is subsequently redistributed uniformly (weighted by area and solar absorptance) to all heat transfer surfaces in the zone, along with interior reflected beam solar and shortwave radiation from lights."

rraustad commented 4 years ago

"(weighted by area and solar absorptance)" Since the description is talking about the "portion of diffuse solar that is reflected and redistributed", weighted by surface solar absorptance doesn't sound right, but I didn't check the equations.

mjwitte commented 4 years ago

@rraustad Yeah, the solar absorptance comes into play twice (or more). It governs how much initial solar (beam and diffuse) gets reflected (all as diffuse) and then it governs how much of the total reflected diffuse it absorbs. So, if there are two surfaces in the same zone with different solar absorptance, the one with higher solar absorptance will keep more of the reflected diffuse.

mldichter commented 4 years ago

The IO Ref and IDD disagree on the inputs to a AirflowNetwork:Distribution:Linkage object.

Capture3 Capture4

The IDD appears to be the correct one. The Node 1 Name and Node 2 Name fields can accept the name of a Zone object.

NREL / EnergyPlus