Developing a new modeling capability in OpenStudio‐HPXML

General steps:

Follow these general steps to develop and add new modeling capability to OpenStudio-HPXML. Before you begin, make sure to clone the latest version of the OpenStudio-HPXML repository on your local machine and create a new branch.

Step 1. Update HPXML Schema if needed.

• Look for an already existing model that you could build on top of (in which case HPXML Schema modification is not necessary), or make a determination if a completely new model is required (in which case the HPXML schema modification is necessary).
• Look through the HPXML Data Dictionary to check what is already available in HPXML and the required HPXML Schema ordering of elements in an HPXML file.
• Note that in an HPXML file, the order of elements matters (elements must occur in a certain order going from top to down, agreeing with the order specified in the HPXML Schema).

Step 2. Update the EPValidator.xml schematron document to describe what new HPXML required/optional inputs are accepted.

• Search through the EPValidator.xml (schematron) with a keyword to check for an existing model (if any), which may lead to a base (parent) element where the new model might be integrated. For example, To add a new child element model to a parent element 'Roof', you would search for the parent element 'Roof' if it already exist or create a new one if it does not exist yet.

• The parent element must have a name specified on the line <sch:title>parent_element_name</sch:title>.

• The line following the parent element name line must specify the x-path for the parent element that the HPXML schema will search through the HPXML file being simulated on EnergyPlus. This line is specified as <sch:rule context='/x-path/'.

• The lines below the x-path line specifies each unique child element associated with the parent element.

• For checking the attributes related to each sub-child element within each child element, the schematron points to another location within the EPvalidator.xml file where conditional checks are performed on each sub-child element (indicated by a <!-- See [child_element_name] --> syntax at the end of the line). The location of the conditional checks is where a developer can add attribute checks on the newly defined sub-child element.

• Each element must be created such that the schema will first search for the number of elements specified in the HPXML file and compare it against a pre-determined number. If the number of elements does not meet this criteria, the user should get an error message.

• If the number of elements specified in the HPXML file meets the criteria, the schematron directs the schema to then check that the option selected for that particular element belongs to a set of pre-determined options. If not, the user should get an error message. The developer should correlate the entry of the option here with what data type the HPXML schema allows for those options.

• It is important to consider whether to make the specific element being added to the parent element should be an optional input by the user. Often times, keeping the new addition as optional helps the use of current and older versions of OpenStudio-HPXML to run without errors, so that the new addition does not become a breaking change. If the parent element is already an optional input, the child element of the parent element has to be optional as well.

Step 3. Update the HPXML ruby class to allow reading the new inputs from and writing the new inputs to an HPXML file.

• It is important to remember that in an HPXML file, the order of elements must follow the order specified in the HPXML Schema.
• Within the HPXML ruby class, search for (or create a new) class with associated attributes. T

Step 4. Create (or update) a test/sample HPXML file that exercises the new feature.

• If the modeling feature is commonly used, add new arguments to the BuildResidentialHPXML measure.
• (If the modeling feature is not commonly used, ... [TODO about modifying tasks.rb directly]
• Update hpxml_inputs.json to add new sample files with their appropriate measure arguments. The new sample file can be based on a "parent_hpxml" sample file.
• In a command line terminal, run the newly created OpenStudio-HPXML sample file using the command: C./openstudio-<version_number>/bin/openstudio.exe <path_to_your_local_OpenStudio-HPXML_repository/workflow/run_simulation.rb -x <path_to_your_newly_created_HPXML_sample_file> --<options> (If you have openstudio already added to your PATH environment variable, you may replace the C./openstudio-<version_number>/bin/openstudio.exe simply with openstudio). You may get errors and warnings which need to be resolved. Try introducing some invalid inputs and verify that you get corresponding errors.

Step 5. Update the workflow inputs documentation to describe the new inputs and its data type, constraints, etc.

• In OpenStudio-HPXML, the documentation is written in a restructured text (.rst) file.
• Follow formatting closely to the existing documentation.
• Make sure to follow the required HPXML Schema order in the documentation.

Step 6. Update the HPXML to OpenStudio model translation.

• Update the HPXMLtoOpenStudio measure.
  • If the new HPXML input(s) are optional, update hpxml_defaults.rb to look for a missing value and fill in the default. Run a sample file where the optional input is not provided and verify that the in.xml (HPXML w/ default values) shows the correct default value for that input and has the dataSource='software' attribute.

Step 7. Add tests [TODO]

Step XX. Open a pull request, commit and push your changes and request for review.