nrcan-iets-ce-o-hbc / htap

NRCan's Ruby scripts for batch analysis and optimization with HOT2000

Housing Technology Assessment Platform (HTAP)

HTAP is a collection of data and tools that automate and extend the HOT2000 residential energy simulation tool. The HOT2000 software suite can be obtained directly from Natural ResourcesCanada.

HTAP has been used to:

• Optimize the design of Net-Zero Energy and Net-Zero-Ready Housing, and deep energy retrofits
• Investigate the impact potential of different heating technologies in the Canadian housing stock
• Estimate costs and benefits associated with changes in the building code

Natural Resources Canada (NRCan) developed HTAP to support research and program development. While HTAP is published in the hope others will find it useful, NRCan provides no warranty or support for the software or its users.

Requirements & Installation

HTAP requires the following components be installed on your computer:

• Ruby (http://rubyinstaller.org/)
• Git (https://git-scm.com/downloads)
• The HOT2000 command-line client, installed into C:\H2K-cli-min\

In addition to these, you may find the following tools useful:

• A text file editor, such as notepad++
• A data analysis program, such as Matlab, tableau or excel.

To install HTAP, check out the files from Git-hub:

C:\> git clone https://github.com/NRCan-IETS-CE-O-HBC/HTAP.git

Before you can run HTAP simulations, you must first copy the archetype files to the C:\H2K-CLI-Min\User\ directory. HTAP includes a ruby script to do this for you:

PS C:\> cd .\HTAP\Archetypes
PS C:\HTAP\Archetypes> ruby .\CopyToH2K.rb

Versions

The master branch contains the most stable version of HTAP. New features are regularly integrated into the general-dev branch. Other branches include new features under development for future versions of HTAP.

Documentation

• Introduction to HTAP: a summary of HTAP features and use
• HTAP-input-and-output.md: Documentation for HTAP input & output

Contributors

HTAP is developed and maintained by CanmetENERGY-Ottawa, a division of Natural Resources Canada. HTAP's current capabilities reflect contributions from the National Research Council and other third-party contributors.

Natural Resources Canada / CanmetENERGY Ottawa

• Alex Ferguson
• Jeff Blake
• Julia Purdy
• Rasoul Asaee

National Research Council

• Adam Wills

StepWin

• Arman Mottaghi

Contact

Direct inquiries about HTAP and related projects to [email protected]

htap's Issues

Document changes made in recent commits for Ceilings, Doors and Foundations

Supplement Julia's Git documentation file "HTAP-input-and-output.md" with descriptions of the new features added for recently closed tickets #3, #5, #17 and #30.

Clean junk out of HOT2000.options file(s)

• Get rid of old ESP-r/dakota info
• Eliminate tags that do nothing
• Remove redundant definitions ( and possibly set up aliases )

Add auto-testing capabilities to HTAP

HTAP needs automated testing via continuious integration, or something like ESP-r's old tester.pl script.

Costing database : automated costing for future database

We need a way to dynamically compute costs for arbitrary archetypes

Add CI

Follow BTAP's lead on continuious integration.

Rotation of models and output averaging

Walls do not necessarily have a facing, but windows do and their orientation has an impact on annual energy calculations. It's seems like HTAP had the capability to rotate and average results in the ESP-r days, and it would be very beneficial to have this capability established for the HOT2000 version.

Key energy savings opportunities: Findings from LEEP

NRCan to examine key findings from LEEP reports, optimization work, and consider priority report on ECM measures.

Heated Floor Area

getHeatedFloorArea function estimates the heated floor area and compare that with the user-input data.

A few concerns about area calculations using ceiling area as a reference:
(Heated floor area = Ceiling area * No of Storeys + Slab area)

1. The cathedral ceiling area is the actual area, not the horizontal projection of the ceiling area.
2. It is possible that the user-input ceiling area is not consistent with the building geometry (too small or too large)
3. Does the slab attribute accounts for the slab area in basement/heated crawl space?
4. xml format has slightly changed in v11.5b8.

Substitute-h2k.rb: Add ability to set run mode of input file

HTAP currently allows user to specify the output data set to report on after a run but does not ensure that the H2K program mode coincides with the output set specified. Combine both of these capabilities in one option file entry.

Map of all blowerdoor tests

NRCan to determine if SO service areas can be mapped via blower-door testing db, 6-digit postal codes

• Rasoul: examine preliminary map
• Iain, Adam: Provide feedback on usefulness, relevance

Test 9.36 workaround hook and verify usefulness with NRC

getHeatedFloorArea in substitute-h2k.rb does not correctly calculate the heated floor area

Bug reported by Adam W. on Gen-Dev:

The method getHeatedFloorArea in substitute-h2k.rb does not correctly calculate the heated floor area of archetypes:

numStoreysInput = elements["HouseFile/House/Specifications/Storeys"].attributes["code"].to_f

• For a one storey dwelling this code is equal to 1
• For a two storey however, this code is equal to 3

For NRCan archetype 7 (two storey slab-on-grade), for example, the calculated floor area is 399 m2 and reported is 194 m2

Teach us how BTAP uses Continuous Integration (CI)

Provide team with overview on how BTAP uses CircleCI or, if it's not appropriate for HTAP, then some other continuous integration (CI) off-the-shelf program or custom produced approach.

Git Project Management strategies:

Adam, Alex, Rasoul to try project management features in git; report on usefulness.

Refactor HTAP (.options, .choices, substitute-h2k.rb)

Dream up a better way to organize this data, including:

• How we track and compare multiple .options files for different projects.
• Do we need options files as they exist now or is a new format better
• Some of the options only require a single input and, perhaps, can be specified only in a choice file

Bug in NBC rulesets for crawl-spaces

Bug reported by Adam W on Gen-Dev:

Method NBC_936_2010_RuleSet in substitute-h2k.rb does not update crawlspace walls if crawlspace is heated, or updates floor above crawlspace if it is unheated.

Verify pros/cons of wiki vs markdown format; recommend documentation approach for HTAP

Archetypes documentation

• Adam: provide feedback on gaps, improvements in draft archetype documentation
• Rasoul: update documentation as 2+ page overview for committee.

NBC ruleset doesn't update doors, or windows in doors

Bug reported by Adam W on Gen-Dev:

Method NBC_936_2010_RuleSet in substitute-h2k.rb does not update doors, or windows in doors.

htap-prm.rb returns "Fatal Error! HOT2000 message box or couldn't load file!" but the generated .h2k files seem to work.

I have had this problem with the master branch, using H2K-CLI-Min 11.3b90.

This is the Command Line (input files are attached below) :

λ htap-prm.rb -r test.run -v -o HOT2000.options

 ======================================================
 HTAP-prm.rb ( a simple parallel run manager for HTAP )
 ======================================================

 - Creating working directories (HTAP_work-0 ... HTAP_work-2)

 - Deleting prior HTAP-sim directories

 - Reading HTAP run definition from test.run...  done.

 - Creating mesh run combinations from run definitions...  done. (created 3 .choice files)

 - Preparing to process 3 generated '.choice' files using 3 threads

 - HTAP-prm: begin runs ----------------------------

   + Batch 1 ( 0/3 files processed so far...)
     - Starting thread : 1/3 for file ./gen-choice-files/sim-1.choices (PID 14204)... done.
     - Starting thread : 2/3 for file ./gen-choice-files/sim-2.choices (PID 20256)... done.
     - Starting thread : 3/3 for file ./gen-choice-files/sim-3.choices (PID 4832)... done.
     - Waiting on PID: 14204 (1/3)... done.
     - Waiting on PID: 20256 (2/3)... done.
     - Waiting on PID: 4832 (3/3)... done.
     - Post-processing results from PID: 14204 (1/3 ./gen-choice-files/sim-1.choices )... RUN FAILED! (see dir: HTAP-sim-1)
     - Post-processing results from PID: 20256 (2/3 ./gen-choice-files/sim-2.choices )... RUN FAILED! (see dir: HTAP-sim-2)
     - Post-processing results from PID: 4832 (3/3 ./gen-choice-files/sim-3.choices )... RUN FAILED! (see dir: HTAP-sim-3)
     - Writing results to disk...  done.

 - HTAP-prm: runs finished -------------------------

 - Deleting working directories

 - HTAP-prm: Run complete -----------------------
   + 0 files were evaluated successfully.

   + 3 files failed to run
   ! The following files failed to run !
     + ./gen-choice-files/sim-1.choices (dir: HTAP-sim-1)
     + ./gen-choice-files/sim-2.choices (dir: HTAP-sim-2)
     + ./gen-choice-files/sim-3.choices (dir: HTAP-sim-3)

When I look in in each of those HTAP-sim-* directories, the end of Substitute-PL.log is:

... 

Overwriting: C:\HTAP\HTAP-work-0\NRCan-A9_3000sf_2stry_walkOut.h2k 

 Changed path to path: C:/HTAP/HTAP-work-0/H2K for simulation.

 Invoking HOT2000 (PID 20108)... Hot2000 (PID: 20108) finished with exit status  

substitute-h2k.rb -> Fatal error: 
 Fatal Error! HOT2000 message box or couldn't load file!

There is no HOT2000 error popping up on my screen, and the .h2k file in each directory is ok (attached below): The XML contains <AllResults> and I have opened and ran them in GUI version of HOT2000.

My understanding is that the problem stems from HOT2000 closing without an exit code. What would be the reason for that?

Attachments

Implement time-out configuration

Problem: Substitute-h2k.rb's definitions of $maxRunTime and $maxTries are arbitrary; may cause issues especially when running in ERS mode.

Solution: Add support for configuring them via command line, or perhaps via the .run file

substitute-h2k.rb: Add support for skylights, windows in doors

Add the following window elements into HTAP:

• Windows in ceilings (i.e., skylights). Determine if also need to use the "Skylight" window type.
• Windows in doors
• The only other window element allowed in H2K is windows in closed crawlspaces and it may make sense to also add this

Create branch point from stable code for codes development

Allow for 9.36 rule sets in current htap-prm runs

Use a variation of Julia's PERL script code to allow for the generation of an appropriate archetype that can be used to run upgrades as specified in a ".run" file. The "RunScope" section of this file describes everything that's required to generate an archetype file for further analysis.

Review 9.36 use case with Adam, NRC

Substitute-h2k.rb: Add support for different types of ceilings

Provide support for changing the insulation in ceilings of a specific construction type rather than changing all ceilings to one insulation level. There are five (5) ceiling construction types in HOT2000:

Attic/gable, Attic/hip, Cathedral, Flat and Scissor.

Attic/gable and Attic/hip should be grouped together as they will have similar insulation levels.

Missing <AddedToSlab>

Inputs

• Archetypes: Slab On Grade or Crawl Space without insulation.

• Opt-H2KFoundation: Any slab option with added insulation such as STEP_SLAB_R15_under

Problem

Results in corrupted H2K files. The <Slab> is missing a <AddedToSlab> tag.

Wrong Schema

<Floor>
    <Construction hasIntegralFooting='false' heatedFloor='false' isBelowFrostline='false'>
        <FloorsAbove idref='Code 3' nominalInsulation='0' rValue='0.4684'>4200000000</FloorsAbove>
    </Construction>
    <Measurements area='102.19' isRectangular='false' perimeter='46.634'/>
</Floor>

Correct Schema

<Floor>
   <Construction isBelowFrostline="false" hasIntegralFooting="false" heatedFloor="false">
        <AddedToSlab rValue="1.9601" nominalInsulation="1.9601">User specified</AddedToSlab>
        <FloorsAbove idref="Code 3" rValue="0.4684" nominalInsulation="0">4200000000</FloorsAbove>
    </Construction>
    <Measurements isRectangular="false" area="102.1933" perimeter="46.6344" />
</Floor>

Electrical energy is not zero when PV creates sufficient electricity

@julia-purdy reported this problem when two almost identical house files were run but one of them (2nd in list below) showed a non-zero electrical energy value (EnergyEleckWh) in the results file (SubstitutePL-output.txt).

1) Mattamy-Lot2-10-8700RN02760005_FinalDesign_v11.3.h2k --> EnergyEleckWh is 0 as expected
2) Mattamy-Lot2-11-8700RN02760004_FinalDesign_v11.3.h2k --> EnergyEleckWh is 12953!

(Note that these files are located in the Archetypes/NZE EQ lessons learned folder.

Doc: HTAP-input-and-output.md needs update for .json schema

HTAP-input-and-output.md has only been partially updated to reflect the HTAP-options.json conventions.

• Convert remainder of file to new .json convention
• Rethink legacy file section (with info on HOT2000.options)

Add support for reporting ERS, Ref-house ERS from the tsv file.

StepWin needs access to ERSRating ERSRefHouseRating values from the <programs> / <tsv> section. Likely will be useful in the NBC analsys when someone asks, "How will this compare to the reference house ?"

To do:

• Figure out if other parameters should also be added to substitute-h2k.rb output
• Add them
• Verify that the numbers are correctly reported as part of htap-output.json

Consider breaking up HRV spec into more granular info

Could add more flexibility by separating the following into separate inputs

• ventilation requirements
• air-distribution type
• Operating hours
• L/s rates

getArchGeomData.rb no longer retrieves number of storeys data

Oil consumption problem

From @julia-purdy : Question about the oil consumption. When i look at the HOT2000 calculation (on screen) it's in the order of 3000 L, HTAP output is in the order of 10 000L. i think the oil (L) is pulling
Furnace/Boiler Annual Energy Consumption: 124760 MJ instead of:

ESTIMATED ANNUAL FUEL CONSUMPTION SUMMARY

Fuel Space Heating Space Cooling DHW Heating Baseloads Ventilation Total
Oil (Litres) 3238.5 0.0 0.0 0.0 0.0 3238.5
Electricity (kWh) 535.0 0.0 4402.5 8760.0 0.0 13697.5

substitute-h2k.rb: add data to indicate presence of permafrost by climate location, allow below grade insulation configurations to be picked based on permafrost data

Jeff confirms that permafrost calculations have a huge impact on results.

Review HP rating temperature

HTAP hard-codes the HP rating temperature to -5ºC; which is fine as long as users have provided the corresponding COP. Many may assume that this actually means 8.3ºC - If they provide a higher-than-expected COP, the heat pump model will overpredict performance and underpredict energy use.

To Do:

• Decide what default rating temperature makes most sense
• Review current COP data and determine what values are supposed to be used
• Incorporate MaRS/ICF study changes.

Develop hook for NRC 9.36 ruleset workaround

Adding HRV to homes without basement generates precheck

Error is You have specified a basement flow rate (in Ventilation/Room Inputs) when there is no basement in the house. Set it to "Not Applicable".

Possible fix - test for basement type in substitute-h2k.rb, and set ventilation data accordingly.

Update documentation

• Provide instructions on using htap-prm.rb
• document structure of the .run file
• depreciate gen opt

Add additional reporting parameters required for NBC

From Adam Wills

Not yet supported (add)
• Annual heat loss by envelope component
• Annual DHW heating load [GJ] -- heating load (or demand) on DHW system (before eff applied)

Confirm already supported by HTAP

• Annual space heating fuel consumption (Not available by fuel type -- see comment)
• Annual DHW fuel consumption (Not available by fuel type -- see comment)
• Site electrical consumption
• Site natural gas consumption
• Site oil consumption
• Space heating load (Not provided in .h2k XML file - see comment)
• TEDI (Needs to be improved - see comment)

Add all new outputs to the screen dump and the output file (SubstitutePL-output.txt). Add a new command line switch (something like -e1,--extended-output1) so we don't screw up existing tableau workbooks with these new outputs.

`Opt-HVAC` is misleading

• opt-hvac Should be Opt-Heating or maybe Opt-HeatingCooling
• Opt-Casement Windows should be Opt-Windows

Ideally we could add a new mapping for this option while also maintaining support for the older convention.

Substitute-h2k.rb: Improve foundation upgrades

The current foundation upgrade option allows for:

1. Changing the insulation configuration specification within a foundation type (e.g., BCIN_1 to BCEA_3) but not allowing the type to be changed (i.e., the "B" in this case)
2. Changing the wall and/or slab insulation of foundations that match the foundation type (i.e., B, W, C or S).

Note that the tag 1 code in "Opt-H2KFoundation" is a concatenation of the configuration type (e.g., BCIN_1) and one of the following suffixes:

• _ALL: Change insulation in all foundation types (Basement, Walkout, Crawlspace & Slab-On-Grade)
• _B: Change insulation in all Full Basements only
• _W: Change insulation in all Walkouts only
• _C: Change insulation in all Crawlspaces only
• _S: Change insulation in all Slab-On-Grade foundations only

Example: BCIN_1_B
This is documented in tag "Opt-H2KFoundation" of the HOT2000.options file and in HTAP/doc/HTAP-input-and-output.md.

It does NOT:

1. Change the insulation configuration of both Basement and Slab foundations in a file
   (e.g., change insulation in Basements to BCIN_1 and Slabs to SCN_1).
2. Change the insulation in a specific (single) foundation entry
3. Change the basic foundation type (e.g., Basement to a Slab).

This issue is primarily concerned with resolving the first restriction.

Substitute-h2k.rb: Add support for insulating doors

HTAP currently does not provide an option/choice input for door insulation and the associated Ruby script.

Procedures for testing, reviewing, completing pull requests

• Alex: review Iain's BTAP procedures, convert to HTAP wiki
• Adam: pilot testing script on current PRs; report on effectiveness.

Substitute-h2k.rb: Add treatment for ventilation minimum requirements

based on 9.32 & # of bedrooms. Snippit from Adam's 9.36 ruleset

<!-- Minumum ventilation rates (L/s) from NBC Table 9.32.3.3 as a function of number of bedrooms--> <Ventilation _1="16" _2="18" _3="22" _4="26" _5="30" power="2.32"/>

General mode run with 9.36 Boundary conditions

Request from A. Wills

Option to set model boundary conditions to NBC Section 9.36 requirements, and enforce General run mode.
a. Also use inputs recommended by NRCan Section 9.36 modelling guide

Set ventilation / baseloads / setpoints programatically in general mode

ERS mode takes too long to run !

Create a way to deal with heel height R-value (for EStar BOPs)

The Energy Star Builder Option Packages include ceiling options that also specify the heel height R-value.
For example, "R 42 (nominal) at heel". Brian has suggested a method for estimating the heel nominal R-value for a given attic overall nominal R-value and the attic heel height. The data for this should be available in the HOT2000 diagnostics file.

substitute-h2k.rb: Verify treatment of vented & unvented crawl spaces

Move getArchGeomData.rb methods to H2KUtils module

Description

Moving methods from getArchGeomData.rb to the H2KUils module to allow for standardization of HTAP methods and greater code re-usability.

The getArchGeomData.rb currently contains hard-coded procedures to extract geometry data from h2k files. It makes sense to encapsulate these procedures into modules, making them available to all scripts in HTAP and limit duplication of code

Approach

Copy/paste and refactor of getArchGeomData.rb procedures into logical methods in the H2KUils module.

Testing Plan

TBD

Waiting On

None.

Repositories Involved

https://github.com/NRCan-IETS-CE-O-HBC/HTAP/tree/arch_geo_script

Get NRC familiar with AWS use