Documentation 2021c

[jmarrec]

Issue overview

A place to collect requested documentation fixes. Add a new comment to the issue with new doc-change-only issues. Someone will eventually fix them all up at the same time once critical mass has been reached.

[jmarrec]

• [x] Space Name isn't documented in I/O ref for BuildingSurface:Detailed, Floor:Detailed, etc

  • https://github.com/NREL/EnergyPlus/blob/2ad67318cfe34c038d73081846e141c43440678b/doc/input-output-reference/src/overview/group-thermal-zone-description-geometry.tex#L2143-L2149 missing the 'Space Name' in between 'Zone Name' and 'Outside Boundary Condition'
    • [x] Space or SpaceList Name is not documented in InternalMass either
      • Incidentally since Space or SpaceList Name is not used if 'Zone or ZoneList' field is used, I find it weird that that this wouldn't be a single field like Zone or ZoneList or Space or SpaceList Name like it's done on many object**

• [ ] Be explicit about the need for Zone, Space, ZoneList, and SpaceList names to be unique among the four groups.

[shorowit]

• [x] Incorrect output variables for some Coil:WaterHeating objects; see https://github.com/NREL/EnergyPlus/issues/9124#issuecomment-940121827

[mitchute]

• [ ] DHW Documentation Issues. See #9143 and resolve any doc-change issues.

[mjwitte]

• [x] In the I/O Ref, for ZoneHVAC:EquipmentConnections, the overview and the field description for "Zone Return Air Node or NodeList Name" still say that Return Node is required. The idd does not tag this as required. I'm 99% certain it is no longer required. Should probably test this before changing the docs.

[shorowit]

• [x] "generatros" appears twice instead of "generators" in https://bigladdersoftware.com/epx/docs/9-6/input-output-reference/group-electric-load-center-generator.html

[shorowit]

• [x] The zone name field for the Li-ion battery only describes how the zone is used with respect to heat gains. It should also include language stating that the zone temperature is used by the battery (or if no zone is provided, outside temperatures are used). See the code.

[shorowit]

• [x] The Output:JSON object added in https://github.com/NREL/EnergyPlus/pull/6192 cannot be found anywhere in the I/O Ref or the OutputDetailsAndExamples documentation.

[michaldengusiak]

• [x] In the Engineering Reference, under Heat Gain From Lights, the units for Cp are incorrect.,

please refer to https://unmethours.com/question/65109/value-for-cp-specific-heat-of-air/

(J/kg should be J/kg−K) in the EnergyPlus documentation

• [x] In the Engineering Reference, for Fanger Comfort Model, abbrevation and order

https://bigladdersoftware.com/epx/docs/8-7/engineering-reference/occupant-thermal-comfort.html#fanger-comfort-model

• [x] abrevation and order

[JasonGlazer]

• [x] UtilityCost:Computation EXCEEDS has operands reversed according to this comment on unmethours. The IOref should say: "Returns the difference between the first and second variable if the second variable is greater than the first. If the first variable is greater or equal to the second variable returns a zero."

[eringold]

• [x] Multiple objects in Energy+.idd have the following \memo lines;

  \memo a list of meters that can be reported are available after a run on
  \memo the meter dictionary file (.mdd) if the Output:VariableDictionary has been requested.

  Objects are:

  DemandManagerAssignmentList,
  ElectricLoadCenter:Transformer,
  ElectricLoadCenter:Distribution,
  Output:Meter:MeterFileOnly,
  Output:Meter:Cumulative,
  Output:Meter:Cumulative:MeterFileOnly,

  Seems appropriate for Output:Meter types, but not DemandManager or ElectricLoadCenter.

[mjwitte]

Seems appropriate for Output:Meter types, but not DemandManager or ElectricLoadCenter.

Those memos should be expanded to describe the object (that's what memos are for), but referencing the mdd is appropriate, because these objects have input fields which are meter names. Perhaps these line should be \notes at the first meter name field.

[lymereJ]

• [x] Small typo in the description of High/Low System Node Setpoint Temperature: "upper" is used to describe both outputs.

[jmarrec]

• [ ] Coil:WaterHeating:AirToWaterHeatPump:VariableSpeed: Output variables look weird as they mention "Cooling Coil" when really this is a heating one. The :Wrapped and :Pumped ones correctly mention "Heating Coil XXX".
  • https://bigladdersoftware.com/epx/docs/9-6/input-output-reference/group-heating-and-cooling-coils.html#vshpwhheating-outputs
  • https://github.com/NREL/EnergyPlus/blob/2f3618a629077d45308382a808b82c81e87a697b/doc/input-output-reference/src/overview/group-heating-and-cooling-coils.tex#L6613-L6668

[shorowit]

@jmarrec That is apparently intentional. Note where the documentation says: “This coil draws heating energy from air to the heater. Thus it is regarded as a cooling coil, as shown in the output variable names.”

[jmarrec]

@shorowit I understand the rationale, but the discrepancy with the Pumped and Wrapped coils bothers me.

[shorowit]

@jmarrec Ah! I just remembered that this has been brought up before and, actually, the Pumped and Wrapped coils are incorrectly documented. This issue is captured above in this issue here and you can see the discussion on it here.

[eringold]

• [x] I/O ref for ElectricLoadCenter:Distribution lists old '... Electric Demand Power' outputs: https://github.com/NREL/EnergyPlus/blob/c17e07c8ba6f2c31403f2f7bf14ee2b51ebbada8/doc/input-output-reference/src/overview/group-electric-load-center-generator.tex#L432-L436 Which should be "...Electricity Demand Rate": https://github.com/NREL/EnergyPlus/blob/2f8b2517baa1e6e553fe766f4587a0926b4f5032/src/Transition/SupportFiles/Report%20Variables%209-3-0%20to%209-4-0.csv#L171-L173

[RKStrand]

• [x] In the documentation for the recently split up input for variable and constant flow radiant systems (into design and system specific data), the "design data" has been added as a subsection under the sections for these objects. However, there is no text that really describes the fact that the user will need both the design and system specific data and the design data is somewhat lost in that it is subsection "2" while subsection "1" is labeled "input". This could be confusing and should be addressed. In addition, in the constant flow section, the temperature control schedules mention a temperature control type "above", but that information was moved to the design data which actually comes after this. So, this needs to be cleaned up and maybe a quick double check of similar issues in the other radiant system models need to be made while we are at it. Example:

[aaron-boranian]

• [ ] Make-up Water Supply Schedule Name input field of SwimmingPool:Indoor object claims that field can be left blank to use same calculations as site's water mains temperature, but leaving blank results in severe error that stops the simulation. The IDD also lists this input field as required, so "if blank" references in bold below should be removed.

I/O Ref:

The scheduled named by this field establishes a cold water temperature [C] for the water that replaces the water which is lost from the pool due to evaporation. If blank, water temperatures are calculated by the Site:WaterMainsTemperature object. This field (even if blank) overrides the Cold Water Supply Temperature Schedule in all of the listed WaterUse:Equipment objects.

Also, is last sentence true (this field overrides cold water supply temperature for ALL water use equipments?

Severe Error: Severe [SwimmingPool:Indoor][Indoor Pool] - Missing required property 'make_up_water_supply_schedule_name'. Fatal Errors occurred on processing input file. Preceding condition(s) cause termination.

[mjwitte]

• [ ] Make-up Water Supply Schedule Name input field of SwimmingPool:Indoor object claims that field can be left blank to use same calculations as site's water mains temperature, but leaving blank results in severe error that stops the simulation. The IDD also lists this input field as required, so "if blank" references in bold below should be removed.

I/O Ref:

The scheduled named by this field establishes a cold water temperature [C] for the water that replaces the water which is lost from the pool due to evaporation. If blank, water temperatures are calculated by the Site:WaterMainsTemperature object. This field (even if blank) overrides the Cold Water Supply Temperature Schedule in all of the listed WaterUse:Equipment objects.

Also, is last sentence true (this field overrides cold water supply temperature for ALL water use equipments?

@aaron-boranian Probably not. Looks like this is a pasteo from another object. Code inspection or a quick test run should answer for sure.

Severe Error: Severe [SwimmingPool:Indoor][Indoor Pool] - Missing required property 'make_up_water_supply_schedule_name'. Fatal Errors occurred on processing input file. Preceding condition(s) cause termination.

Sounds like this is just an idd error, but you'll need to check the code and test with the required tag removed to see if it all works as exepected.

[jcyuan2020]

• [x] Incorrect equation for convective coefficient definition in Engineering Ref:

[jcyuan2020]

• [x] The IDD entry does not agrees with this:

[jcyuan2020]

• [x] The field name does not have "External" and also the choice name should be "Imported":

[jcyuan2020]

• [x] The separation line after the first row in the table is not needed:

[jcyuan2020]

• [x] UtilityCost:Computation EXCEEDS has operands reversed according to this comment on unmethours. The IOref should say: "Returns the difference between the first and second variable if the second variable is greater than the first. If the first variable is greater or equal to the second variable returns a zero."

This change is now completed in the IORef. However, the "correct" definition actually seems to be very counter-intuitive.

[jcyuan2020]

@jmarrec Ah! I just remembered that this has been brought up before and, actually, the Pumped and Wrapped coils are incorrectly documented. This issue is captured above in this issue here and you can see the discussion on it here.

The output variables' naming for the pumped and wrapped Coil:WaterHeating:AirToWaterHeatPump are now changed according to the discussion.

[jcyuan2020]

• [x] In the documentation for the recently split up input for variable and constant flow radiant systems (into design and system specific data), the "design data" has been added as a subsection under the sections for these objects. However, there is no text that really describes the fact that the user will need both the design and system specific data and the design data is somewhat lost in that it is subsection "2" while subsection "1" is labeled "input". This could be confusing and should be addressed. In addition, in the constant flow section, the temperature control schedules mention a temperature control type "above", but that information was moved to the design data which actually comes after this. So, this needs to be cleaned up and maybe a quick double check of similar issues in the other radiant system models need to be made while we are at it. Example:

The following changes are applied now:

1. The section headings for "ZoneHVAC:LowTemperatureRadiant:ConstantFlow:Design" and "ZoneHVAC:LowTemperatureRadiant:VariableFlow:Design" are now pumped one level up to be in the same level as the two parent objects. Each is placed right after the parent object.
2. Added hyperref to the parent objects "Design Object" input field description to point to their own "xxx:Design" section.
3. According to the IDD, it is not so clear if a "Design Object" is absolutely required, since this is not marked as a required field there. So probably will leave this to later determinations about if a design object should always be required. Currently using the added hyperref in item 2 to slightly emphasize the linkage.
4. Addressed the pointing issue in the "temperature control type" descriptions in each of the objects.
5. Some typo corrections across a few different sections.

[jcyuan2020]

• [ ] Make-up Water Supply Schedule Name input field of SwimmingPool:Indoor object claims that field can be left blank to use same calculations as site's water mains temperature, but leaving blank results in severe error that stops the simulation. The IDD also lists this input field as required, so "if blank" references in bold below should be removed.

I/O Ref: The scheduled named by this field establishes a cold water temperature [C] for the water that replaces the water which is lost from the pool due to evaporation. If blank, water temperatures are calculated by the Site:WaterMainsTemperature object. This field (even if blank) overrides the Cold Water Supply Temperature Schedule in all of the listed WaterUse:Equipment objects. Also, is last sentence true (this field overrides cold water supply temperature for ALL water use equipments?

@aaron-boranian Probably not. Looks like this is a pasteo from another object. Code inspection or a quick test run should answer for sure.

Severe Error: Severe [SwimmingPool:Indoor][Indoor Pool] - Missing required property 'make_up_water_supply_schedule_name'. Fatal Errors occurred on processing input file. Preceding condition(s) cause termination.

Sounds like this is just an idd error, but you'll need to check the code and test with the required tag removed to see if it all works as exepected.

The original text seems to be an accurate description of what's happening in the two code blocks below): 1). if left blank->will override with environment water mains temperature; 2). if not left blank but not a schedule match->will have `ErrorsFound = true' which is equivalent to a fatal-out; 3). for all other scenarios, it will take the schedule value. So here left blank and code running ok (only occurs in 1) is equivalent to having the value is overridden by water main temperature anyway.

Based on:

        if ((state.dataSwimmingPools->Pool(Item).MakeupWaterSupplySchedPtr == 0) && (!lAlphaBlanks(4))) {
            ShowSevereError(state, cAlphaFields(4) + " not found: " + Alphas(4));
            ShowContinueError(state, "Occurs in " + CurrentModuleObject + " = " + Alphas(1));
            ErrorsFound = true;
        }

and

    if (this->MakeupWaterSupplySchedPtr > 0) {
        this->CurMakeupWaterTemp = ScheduleManager::GetCurrentScheduleValue(state, this->MakeupWaterSupplySchedPtr);
    } else {
        // use water main temperaure if no schedule present in input
        this->CurMakeupWaterTemp = state.dataEnvrn->WaterMainsTemp;
    }

So looks like an idd change to allow blank input is what's needed here.

[jcyuan2020]

• [x] Duplicated or redundant Zone Thermal Output section: Section 1.10.5:

Section 1.10.67:

It looks the latter may be some kind of residual from previous versions?

[eringold]

However the actual table displays these units to be [J/(kg*K)]: And is located in the 'Coils' table of the Coil Sizing Report.

[RKStrand]

• [x] In the constant flow radiant system documentation in the IO Ref, the underlined terms should say "Zone Radiant HVAC" not "Constant Flow".

The sections that provide detail on these output variables after this got it right.