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

design/FY2023/ImprovedErrorHandling.md

@@ -0,0 +1,89 @@
+# Modern Error Reporting
+
+One feature request pretty much summarizes the issue and solution for our error reporting:
+
+> "The current solution of writing out the error file to a text file without establishing a standard procedure makes it difficult for third-party vendors to translate the content.
+  We would prefer to start establishing a standard template for warnings/error records with unique IDs being written to the JSON files. "
+
+OK, so the big picture is we want an error file in JSON format with some form of ID associated with the error messages.
+A nice side benefit of this would be that we could generate a bit of documentation that cross references the ID.
+The documentation could be built up over time with additions like typical causes, tips and tricks for fixing or working around, etc.
+
+## Detailed task list
+
+To meet this need, I think development would follow something like this:
+
+- Analyze existing structure, figuring out a feasible plan for refactoring error message calls
+- Create a new error manager in EnergyPlus that tracks errors in a nice structure
+- Refactor calls to error message routines to use a vector of strings rather than individual calls to *Continue*
+- Refactor the error message routines to not just emit to the err file but also add them to the new error manager
+  - (at this point I should be able to get no diffs)
+- Try to find "nearly" identical error messages and bring them together
+  - I would expect this to cause valid diffs in the err file as minor wording changes are collected together 
+- Create a set of ID categories, and modify the error emission to report the error ID
+- Use the error manager to generate the JSON error file
+- Create an auto-generated document for the different error message IDs
+
+## Error File Contents
+
+I would start creating the error file with something like this, but am totally open to feedback, and it also may naturally change as development commences:
+
+```json
+{
+  "summary": {
+    "outcome": "fatal",
+    "num_severe": 2,
+    "num_warnings": 1,
+    "runtime": 210.2,
+    "timestamp": "2023-04-24T13:05:30Z"
+  },
+  "fatal": {
+    "id": "F1000",
+    "summary": "EnergyPlus failed because of a Meta-reason",
+  },
+  "severe": [
+    {
+      "id": "S1021",
+      "synopsis": "Flow controller did not converge",
+      "extra_info": "Air loop 'AirLoop' diverged with oscillating flow rate.  Flow controller 'ControlStrategy' is set to 'InverseMobiusStrip', which only exists in hyper dimensional systems.  Choose a more appropriate option."
+    },
+    {
+      "id": "S3001",
+      "synopsis": "Encountered meta-building in the input file",
+      "extra_info": "Building 'MetaBuilding' was declared with meta-latitude '\\342\\200\\234' and meta-longitude '\\742\\234\\876', which are not supported in this version of EnergyPlus"
+    }
+  ],
+  "warnings": [
+    {
+      "id": "W4040",
+      "synopsis": "Timestep is set to 3600 seconds, which is incompatible with some cool short time step model, suggest setting it to 3599 or less.",
+      "extra_info": ""
+    }
+  ],
+  "information": [
+    "Testing Individual Branch Integrity",
+    "All Branches passed integrity testing",
+    "Testing Individual Supply Air Path Integrity",
+    "All Supply Air Paths passed integrity testing",
+    "Testing Individual Return Air Path Integrity",
+    "All Return Air Paths passed integrity testing",
+    "No node connection errors were found.",
+    "Beginning Simulation",
+    "EnergyPlus Completed Successfully"
+  ]
+}
+```
+
+We'll need to keep in mind how new errors can be introduced into the category system to future proof it.
+Many tools do something like: A001, A002, B001, B002, so I would probably start by doing something similar.
+
+Things I still need to solve:
+- Should I include timestamp info for every single warning?
+- Add structure for recurring
+- Add extra flag for whether warmup, sizing, or kickoff were true
+
+## Current questions for dev team
+
+- What should we name this JSON based error file?
+- Do we just keep a list of message string templates in a single dedicated file, and use these in calls to errors?
+- Anyone have strong feelings on the ID or JSON form?

design/FY2024/NFP-Space Sizing and HVAC-Part4.md

@@ -0,0 +1,214 @@
+Extend Spaces to Sizing and HVAC - Part 4
+================
+
+**Michael J. Witte, GARD Analytics, Inc.**
+
+ - Original June 17, 2024
+ - Revised, August 2, 2024
+
+## Table of Contents ##
+
+[E-mail and Conference Call Conclusions](#e-mail-and-conference-call-conclusions)
+
+[Background and Overiew](#background-and-overview)
+
+[Approach](#approach)
+
+[Testing/Validation/Data Sources](#testingvalidationdata-sources)
+
+[Input Description](#input-description)
+
+[Outputs Description](#outputs-description)
+
+[Engineering Reference](#engineering-reference)
+
+[Example File and Transition Changes](#example-file-and-transition-changes)
+
+[Design](#design)
+
+## E-mail and Conference Call Conclusions ##
+June 17-20, Q&A in the pull request with rraustad. Made some minor updates to the NFP to clarify the sizing methods and to mention that an spsz output file will be created, similar to the existing zsz output.
+
+
+## Background and Overview ##
+
+Space was added as a new concept in v9.6. Each EnergyPlus Zone contains one or more Spaces which are used for:
+
+  * assigning and allocating internal gains
+  * specifying enclosure boundaries,
+  * reporting inputs grouped by space types, and 
+  * reporting select output grouped by space types.
+
+For the zone heat balance each thermal Zone is composed of one or more Spaces controlled by a single thermostat or HVAC system control point such as a VAV terminal unit.
+
+In version 23.1 options were added to perform the air heat balance for each Space or each Zone, and space-level heat balance output variables were added.
+
+In version 23.2, the following capabilities were added:
+
+  * When ZoneAirHeatBalanceAlgorithm "Do Space Heat Balance for Sizing" = Yes, zone sizing is also done for all spaces. The HVAC Sizing Summary table report will include subtables for Space Sensible Cooling and Heating as well as for Zone Sensible Cooling and Heating. Space Sizing will also be reported to the eio output. The space sizing results are reported, but not used.
+
+  * Three new objects, SpaceHVAC:EquipmentConnections, SpaceHVAC:ZoneEquipmentSplitter, and SpaceHVAC:ZoneEquipmentMixer allow one or more zones to be simulated at the space level for HVAC, leading to independent air temperature and humidity in each space.
+
+  * For zone equipment serving multiple spaces, three thermostat control options (SingleSpace, Ideal, and Maximum).
+
+This NFP proposes additional optional capabilities:
+
+  * Use the Space-level (room-by-room) sizing results to size Zone-level equipment to either the coincident or non-coincident peak across the Spaces (rooms).
+
+  * Refine existing Space-level HVAC simulation.
+
+  * Extend space HVAC to support more special objects (e.g. ZoneThermalChimney, if budget allows).
+
+
+
+## Approach ##
+### Sizing
+A new input will be added to Sizing:Zone to allow zone sizing using the non-coincident space peaks or the coincident peak. 
+
+Space sizing is an actual heat balance on each space. Currently zone sizing is an actual heat balance on each zone (as a whole) although some of the components for the zone heat balance are sums across the spaces (even when space heat balance is off). e.g. internal gains. The current zone sizing calculations will be used to calculate the coincident zone sizing using the combined spaces. 
+
+For the non-coincident zone sizing, the individual space peaks will be summed and other values (such as outdoor temperature) will be averaged.
+
+When space sizing is active, sizing results are reported in the table output for both spaces and zones. There will be no change here.
+
+When space sizing is active, a new spssz output file will be generated, similar to the existing zsz output. This will require a new field in the OutputControl:Files object.
+
+
+### HVAC
+* Calculate return flows at the Space level. Currently, space return nodes can be specified, but there is no flow assigned to them. All return flow is lumped at the zone level.
+
+
+![SpaceHVACSchematic](SpaceHVACSchematic.png)
+
+
+
+## Testing/Validation/Data Sources ##
+
+Compare Space vs Zone-level results.
+
+## Input Description ##
+Some new objects and some changes to existing objects are proposed.
+
+### Sizing:Zone
+* *New field at the end:"*
+```
+  A15; \field Type of Space Sum to Use
+      \type choice
+      \key Coincident
+      \key NonCoincident
+      \default Coincident
+```
+
+### OutputControl:Files
+* *New field in the middle:"*
+```
+  A9 , \field Output Space Sizing
+       \type choice
+       \key Yes
+       \key No
+       \default Yes
+```
+
+### ZoneRefrigerationDoorMixing
+(If budget allows, otherwise limit these to single-space zones.)
+* *Change field "Zone 1 Name" to "Zone or Space Name 1."*
+
+* *Change field "Zone 2 Name" to "Zone or Space Name 2."*
+
+### ZoneCoolTower:Shower
+(If budget allows, otherwise limit these to single-space zones.)
+* *Change field "Zone Name" to "Zone or Space Name."*
+
+### ZoneThermalChimney
+(If budget allows, otherwise limit these to single-space zones.)
+* *Change field "Zone N Name" to "Inlet Zone or Space Name N."*
+
+### idf Example
+
+
+## Outputs Description ##
+A new Spsz output file will be created when space sizing is active.
+
+
+## Engineering Reference ##
+
+
+## Example File and Transition Changes ##
+
+* Transition will be required for idf OutputControl:Files.
+
+* Field name changes may be required for epJSON inputs for ZoneRefrigerationDoorMixing, ZoneCoolTower:Shower, and/or ZoneThermalChimney.
+
+* The existing example file 5ZoneAirCooledWithSpaces will be copied to a new example file that uses the new Sizing:Zone Coincident Space sum option.
+
+
+## Design ##
+
+### Sizing ###
+
+When Space sizing is requested, the following arrays are created for Spaces.
+
+```
+    Array2D<DataSizing::ZoneSizingData> SpaceSizing;                      // Data for space sizing (all data, all design)
+    EPVector<DataSizing::ZoneSizingData> FinalSpaceSizing;                // Final data for space sizing including effects
+    Array2D<DataSizing::ZoneSizingData> CalcSpaceSizing;                  // Data for space sizing (all data)
+    EPVector<DataSizing::ZoneSizingData> CalcFinalSpaceSizing;            // Final data for space sizing (calculated only)
+```
+
+The main calculation flow for Zone sizing is:
+
+* `SizingManager::ManageSizing`
+    * Get sizing inputs (`GetOARequirements . . . GetPlantSizingInput`).
+    * Loop over sizing environments and days
+        ```
+          UpdateZoneSizing(state, Constant::CallIndicator::BeginDay);
+          Loop over hours and timesteps
+            ManageWeather(state);
+            UpdateSysSizing(state, Constant::CallIndicator::DuringDay);
+            ManageHeatBalance(state);
+          UpdateZoneSizing(state, Constant::CallIndicator::EndDay);
+        UpdateZoneSizing(state, Constant::CallIndicator::EndZoneSizingCalc);
+        ```
+        * Repeat (with a pulse) if zone component loads report is requested.
+ * `ZoneEquipmentManager::UpdateZoneSizing` (where all the work is done.)
+     * `case Constant::CallIndicator::BeginDay:`
+         * Do some initializations on `CalcZoneSizing`
+     * `case Constant::CallIndicator::DuringDay:`
+         * Called from `HVACManager`
+         * save the results of the ideal zone component calculation in the CalcZoneSizing sequence variables
+         * Works on `ZoneSizing` and `CalcZoneSizing`
+     * `case Constant::CallIndicator::EndDay:`
+         * Compute moving averages
+         * Save values at peak heating and cooling
+         * Works on `CalcZoneSizing` and `CalcFinalZoneSizing`
+         * *In this function add the zone sizing coincident/non-coincident option and calculations.*
+
+     * `case Constant::CallIndicator::EndZoneSizingCalc:`
+         * Apply EMS overrides
+         * Output sizing results from `CalcFinalZoneSizing`
+         * Move sizing data into final sizing array according to sizing method
+         * Works on `CalcZoneSizing`, `CalcFinalZoneSizing`, `ZoneSizing`, and `FinalZoneSizing`
+         * Lots going on in here.
+         
+### HVAC ###
+
+The main calculation flow for Zone and Space HVAC in `HVACManager:ManageHVAC` is as follows, with notes about changes required for Space-HVAC.
+
+* `ZoneTempPredictorCorrector::ManageZoneAirUpdates(... GetZoneSetPoints)`
+    * `CalcZoneAirTempSetPoints`
+* `ZoneTempPredictorCorrector::ManageZoneAirUpdates(... PredictStep)`
+    * `PredictSystemLoads`
+* `SimHVAC`
+    * `SetPointManager::ManageSetPoints(state);`
+    * `SimSelectedEquipment`
+        * `SimAirServingZones::ManageAirLoops`
+        * `ZoneEquipmentManager::ManageZoneEquipment`
+            * `CalcZoneReturnFlows`*
+                * *Add space return flow calculations here.*
+                * *Likely refactor this function to be callable for either zone or space.*
+        * `PlantManager::ManagePlantLoops`
+* `ZoneTempPredictorCorrector::ManageZoneAirUpdates(... CorrectStep)`
+    * `correctZoneAirTemps`
+
+
+

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

@@ -1518,21 +1518,21 @@ \subsection{ZoneRefrigerationDoorMixing}\label{zonerefrigerationdoormixing}
 
 ZoneRefrigerationDoorMixing is ideally suited for two zones, at least one of which is refrigerated, that exchange an equal amount of dry air. As with \hyperref[zonemixing]{ZoneMixing}, this is a simplified interzone airflow in EnergyPlus. The ZoneRefrigerationDoorMixing approach shares some features of both \hyperref[zonemixing]{ZoneMixing} and \hyperref[zonecrossmixing]{ZoneCrossMixing}. Like \hyperref[zonecrossmixing]{ZoneCrossMixing}, ZoneRefrigerationDoorMixing has an energy effect on both the source and the receiving zone, thus maintaining both the air mass and energy balances in the two zones. Unlike the other two mixing objects, ZoneRefrigerationDoorMixing always calculates the air exchange rate based on the zone temperature and relative humidity. That is, the user does not specify the air flow rate. The user can moderate the flow through a door-opening schedule.
 
-ZoneRefrigerationDoorMixing can only be entered once for any unique pair of zones. It doesn't matter which zone is listed first and the zones will automatically switch back and forth between source and receiving zones depending upon which zone is colder.
+ZoneRefrigerationDoorMixing can only be entered once for any unique pair of zones. It doesn't matter which zone is listed first and the zones will automatically switch back and forth between source and receiving zones depending upon which zone is colder. If space heat balance is active and a space name is specified for Zone or Space Name 1 or 2, then the space conditions will be used and the exchange will be with that space only. If space heat balance is active and a zone name is specified, then the aveerage zone conditions will be used, and the exchange will be proportioned to all spaces in the zone by space volume.
 
 \subsubsection{Inputs}\label{inputs-7-003}
 
 \paragraph{Field: Name}\label{field-name-7-002}
 
 The name of the ZoneRefrigerationDoorMixing object.
 
-\paragraph{Field: Zone 1~ Name}\label{field-zone-1-name}
+\paragraph{Field: Zone or Space Name 1}\label{field-zone-1-name}
 
-This field is the name of one of the two zones (ref: Zone) exchanging air and attaches a particular refrigeration door~ mixing statement to both thermal zones in the building.
+This field is the name of one of the two zones (ref: Zone) or spaces exchanging air and attaches a particular refrigeration door~ mixing statement to both thermal zones or spaces in the building. If a space name is used, it must belong to a different zone than Zone or Space Name 2.
 
-\paragraph{Field: Zone 2~ Name}\label{field-zone-2-name}
+\paragraph{Field: Zone or Space Name 2}\label{field-zone-2-name}
 
-This field is the name of the other zone (ref: Zone) exchanging air and attaches a particular refrigeration door~ mixing statement to both thermal zones in the building.
+This field is the name of the other zone (ref: Zone) or space exchanging air and attaches a particular refrigeration door~ mixing statement to both thermal zones or spaces in the building. If a space name is used, it must belong to a different zone than Zone or Space Name 1.
 
 \paragraph{Field: Schedule Name}\label{field-schedule-name-5}
 
@@ -1965,9 +1965,9 @@ \subsubsection{Inputs}\label{inputs-8-002}
 
 This field is the name of the schedule that denotes whether the cooltower can run during a given time period. A schedule value greater than 0 (usually 1 is used) indicates that the cooltower is available and can be on during the time period. A value less than or equal to 0 (usually 0 is used) denotes that the cooltower is not available and must be off for the time period. If this field is blank, the schedule has values of 1 for all time periods.
 
-\paragraph{Field: Zone Name}\label{field-zone-name-6}
+\paragraph{Field: Zone or Space Name}\label{field-zone-name-6}
 
-This field is the name of the zone (ref: Zone) and attaches a particular cooltower statement to a thermal zone in the building.
+This field is the name of the zone (ref: Zone) or space the cooltower is attached to.
 
 \paragraph{Field: Water Supply Storage Tank Name}\label{field-water-supply-storage-tank-name}
 
@@ -2185,9 +2185,9 @@ \subsubsection{Inputs}
 
 This dimensionless number is the discharge coefficient of the thermal chimney. The ventilation rate enhanced by the thermal chimney is also dependent on the discharge coefficient.
 
-\paragraph{Field: Zone \textless{}\#\textgreater{} Name}\label{field-zone-name-8}
+\paragraph{Field: Zone or Space Name \textless{}\#\textgreater{}}\label{field-zone-name-8}
 
-This field is the name of the zone (ref: Zone) to which the thermal chimney is attached. It is used in conjunction with the next three fields. Note that up to 20 sets of zone name, distance from the top of the thermal chimney to each inlet, relative ratios of air flow rates passing through each zone and cross sectional areas of each air channel inlet may be entered for a single thermal chimney if multiple zones share the common thermal chimney.
+This field is the name of the zone (ref: Zone) or space to which the thermal chimney is attached. It is used in conjunction with the next three fields. Note that up to 20 sets of zone or space name, distance from the top of the thermal chimney to each inlet, relative ratios of air flow rates passing through each zone and cross sectional areas of each air channel inlet may be entered for a single thermal chimney if multiple zones or spaces share the common thermal chimney.  If space heat balance is active and a space name is specified for Zone or Space Name, then the space conditions will be used and the exchange will be with that space only. If space heat balance is active and a zone name is specified, then the aveerage zone conditions will be used, and the exchange will be proportioned to all spaces in the zone by space volume.
 
 \paragraph{Field: Distance from Top of Thermal Chimney to Inlet \textless{}\#\textgreater{}}\label{field-distance-from-top-of-thermal-chimney-to-inlet}