Reworking HPXML's Enclosure

[shorowit]

(This PR replaces #105, #176, #179, #178, #166, and #113, which are all changes to the Enclosure element.)

This PR is a second attempt to update HPXML's Enclosure element to address several fundamental issues:

1. Difficulty describing attics, both in terms of attached surfaces (e.g., roofs, floors, knee walls, gable walls) as well as the inability to specify multiple floor/roof elements for a given attic. See Discuss knee walls as Attic section rather than Walls #102 and Allow multiple Attic Floor Insulation and Attic Roof Insulation nodes #28.
2. Inability to easily describe some building surfaces, such as knee walls between conditioned/unconditioned attic, bonus room floors over garages, above-grade wood frame walls attached to foundations for split-level homes, etc.
3. Confusion over where certain surfaces should be defined. For example, should a foundation wall between conditioned and unconditioned basements be part of the conditioned basement Foundation or unconditioned basement Foundation (or duplicated in both)?

The proposal attempts to minimize the breaking changes relative to HPXML v2.3.

Breaking changes:

• Replaces AtticsAndRoofs with Attics/Attic elements, structured similarly to Foundations/Foundation.
• Moves all surfaces to the Enclosure level. These surfaces can be (optionally) referenced from Foundation, Attic, or Garage elements through, e.g., Attic/AttachedToWall elements (or similar) with an IDREF. Thus, a surface can be defined once and referenced from two different Foundation or Attic elements if needed.
• All surfaces have InteriorAdjacentTo and ExteriorAdjacentTo fields, except for Roof/Slab elements that do not have ExteriorAdjacentTo. Roofs are always assumed to be exterior adjacent to outside and Slabs are always assumed to be exterior adjacent to ground.
• Replaces the optional AtticType enumeration with a required AtticType element w/ sub-elements, consistent with FoundationType. All existing attic type enumerations can be mapped to the new elements.

New features:

• The FrameFloor element can now be used for all floors/ceilings (e.g., attic floors, floors above foundations, floors of bonus rooms, etc.). Added "none" as a FloorCovering enumeration to describe attic floors.
• Creates a Garages/Garage element, structured similarly to Foundations/Foundation.
• Adds DistanceToTopOfInsulation and DistanceToBottomOfInsulation elements for FoundationWalls. Allows describing, e.g., 4ft high insulation in an 8ft basement.
• Adds an UnderSlabInsulationSpansEntireSlab element for the Slab to specify that the under slab insulation spans the entire slab.
• Allows specifying an Attic/VentilationRate and Foundation/VentilationRate for vented attics/crawlspaces. Units can be "ACHnatural", "SLA", or "CFM per sq.ft.".
• Extends SolarAbsorptance and Emittance elements to RimJoists.

Since a picture is worth a thousand words, here's how the Enclosure looks. Note that some elements were hidden to keep the layout simple to understand. (Or you can view it live on the HPXML Toolbox website.)

[shorowit]

A few discussion items:

• Should HPXML provide guidance for InteriorAdjacentTo and ExteriorAdjacentTo for surfaces between spaces where there's not really a "correct" approach (e.g., knee walls, floors between attic/living, floors between foundation/living, floors under bonus room, walls between living/garage, walls between foundation spaces, etc.)? For example, should a knee wall use:
  • InteriorAdjacentTo="attic - conditioned" and ExteriorAdjacentTo="attic - unconditioned", or
  • InteriorAdjacentTo="attic - unconditioned" and ExteriorAdjacentTo="attic - conditioned"?
• Is it sufficient to simply have Floor elements (and not need Ceiling elements)?
• Are the correct AttachedtoFoo elements available for Attic/Garage/Foundation elements?
• Is there ever a situation where a Roof/Slab element needs an ExteriorAdjacentTo because it's not outdoors/ground?

[nmerket]

@shorowit, thank you for the detailed pull request and explanations of what you've done here. This goes a long way to address some of the inconsistencies and pain points we've experienced and that I've heard from users.

Some Questions/Comments:

• What is the difference between FloorTrusses and FloorJoists in Floor? I think I understand joists, but not trusses.
• Is there a reason GarageType is not required the way AtticType and FoundationType are?
• In Foundation and Garage there is a AttachedToFloor element referencing a floor. I think these are intended to be floors above the foundation or garage, respectively. If that's the case that should be made clear because the terminology is somewhat confusing. At the very least, it should be mentioned in an annotation on AttachedToFloor. We could also consider making it explicit in the element name, i.e. AttachedToFloorAbove. I suppose the same thing goes for attics and "below." I'll have to think on that. Leaning towards an annotation to explain the convention.
• An AttachedToRimJoists would be useful on the Foundation element.
• Here's a crazy idea for interior surfaces: What if we had ExteriorAdjacentTo stay as it is and allow 0 or 1 of them, and allowed 0 to 2 InteriorAdjacentTo elements? That way if we had say an attic knee wall, it would use two InteriorAdjacentTo elements and no ExteriorAdjacentTo elements.

[shorowit]

Good comments, @nmerket. Thanks for reviewing.

* What is the difference between `FloorTrusses` and `FloorJoists` in `Floor`? I think I understand joists, but not trusses.

I also don't understand why trusses are available. But both joists and trusses are available in HPXML v2.3, so I retained it.

* Is there a reason `GarageType` is not required the way `AtticType` and `FoundationType` are?

Just an oversight. I've changed it to be required.

* In `Foundation` and `Garage` there is a `AttachedToFloor` element referencing a floor. I think these are intended to be floors _above_ the foundation or garage, respectively. If that's the case that should be made clear because the terminology is somewhat confusing. At the very least, it should be mentioned in an annotation on `AttachedToFloor`. We could also consider making it explicit in the element name, i.e. `AttachedToFloorAbove`. I suppose the same thing goes for attics and "below." I'll have to think on that. Leaning towards an annotation to explain the convention.

A third possibility would be to revert the name to Floor to FrameFloor, as that helps distinguish it from Slab. That's how it was in HPXML v2.3 of course, with a Foundation having a FrameFloor and Slab. I don't have a strong opinion. I did document the Floor element though.

* An `AttachedToRimJoists` would be useful on the `Foundation` element.

Ok, it's been added.

* Here's a crazy idea for interior surfaces: What if we had `ExteriorAdjacentTo` stay as it is and allow 0 or 1 of them, and allowed 0 to 2 `InteriorAdjacentTo` elements? That way if we had say an attic knee wall, it would use two `InteriorAdjacentTo` elements and no `ExteriorAdjacentTo` elements.

Crazy indeed. I see where you're coming from and it has some appeal. That said, I think it would add more effort to any HPXML import code. I'm open to the idea, but probably lean towards not doing this.

[nmerket]

Notes from phone call

• @GamalielL: How does this work for a variety of measures?
  • @nmerket: We should work through several examples of measures. Can people provide some example measures in HPXML?
• @GamalielL: How would this affect the existing use cases?
  • @nmerket: Since there is a mapping from HPXML 2.3 to this for every element, we'd keep the same elements in the use cases. ERI would probably not use the "spaces" much as most of that software is using a surface-based approach.
• @lirainer: Has concerns about the potential for inconsistencies between (Interior|Exterior)AdjacentTo and the idrefs.
• @GamalielL: Add "none" to floor covering for unfinished attics without flooring.
• Stick with FrameFloor instead of Floor.
• How to handle Interior and Exterior Adjacent To for surfaces in between to interior spaces?
  • @shorowit: For lack of a strong preference in the group, we'll allow the interior and exterior adjacent to be arbitrary in this case.
• InsulationHeight is that from the top or the bottom? We may need a new element measuring the distance to top of insulation and bottom.
• @GamalielL and Brian: Attic ventilation rate. This should be on the Attic element instead of the building summary because a house can have more than one attic with different ventilation rates.
• @lirainer: Add the enumeration "CFM per sq.ft." to AtticVentilationRate/UnitofMeasure.
• FloorTrusses could be replaced with an enumeration in FloorJoists/Material.

[shorowit]

I've updated the PR description to reflect the following changes that I made based on feedback:

• Reverted Floor to FrameFloor.
• Added "none" to FloorCovering for unfinished attics without flooring.
• Changed FoundationWall/InsulationHeight to DistanceToTopOfInsulation and DistanceToBottomOfInsulation.
• Moved ventilation specifications to the Attic/Foundation level. Added the enumeration "CFM per sq.ft." to VentilationRate/UnitofMeasure.

[nmerket]

Fixes #28