Developing a new modeling capability in OpenStudio‐HPXML

Follow these general steps to develop and add new modeling capability to OpenStudio-HPXML. Not all steps will apply to every situation.

Before you begin, make sure to clone the latest version of the OpenStudio-HPXML repository on your local machine and create a new branch. You do not need any additional development tools other than installing the correct version of OpenStudio. You may also find it useful to add the openstudio executable to your PATH.

1. Open a pull request (PR)

• Create a new branch for your development and open a (draft) GitHub Pull Request once you have started committing/pushing your source code changes. This lets other developers know what you are working on, and makes it easy to see commits, diffs, etc.

2. Update HPXML Schema

• Look for existing inputs in the HPXML.xsd Schema to describe the modeling capability. You can refer to the HPXML Data Dictionary to check what is already available in HPXML or you can view the Schema in an application like Oxygen XML or XMLSpy.
• If new inputs are needed and the inputs are not widely useful to other software tools, they can be new inputs under an extension element, in which case HPXML schema changes are not needed. If the inputs would be more widely useful to other software tools, propose a change to the HPXML schema.

3. Update Schematron Validator

• The EPValidator.xml Schematron document describes what HPXML required/optional inputs are accepted by OS-HPXML.
• It is important to consider whether the new HPXML input should be required or optional. If optional, users of OS-HPXML will not need to make changes to their software, so the new addition would not be a breaking change. However, this requires you to determine an appropriate default value if not provided in an HPXML file. For inputs that have a strong impact on simulation results (e.g., wall assembly R-value, air conditioner SEER, etc.), it is usually best to make them required. Optional inputs should usually be reserved for those that have secondary effects on simulation results or are features not easily/commonly collected (e.g., wall solar absorptance).
• Search through EPValidator.xml to look for similar/related inputs (if any), which may lead to a parent element where the new input 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 following line must specify the x-path for the HPXML schema element to which one or more rule checks will apply. This line is specified as <sch:rule context='/x-path/'.
• The remaining lines specify the rule checks that govern whether a given submitted HPXML file will be considered valid or will produce error/warning messages.
• The schematron document sometimes points to another location within EPvalidator.xml 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 additional checks on the newly defined sub-child element.

4. Update HPXML class

• The HPXML ruby class allows 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. Update the methods that involve reading/writing the HPXML file.

5. Create sample file(s)

• 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.
• Create the new sample files by running the command: openstudio tasks.rb update_hpxmls.
• In a command line terminal, run the newly created OpenStudio-HPXML sample file using the command: openstudio workflow/run_simulation.rb -x my_sample_file.xml --<options>. Try introducing some invalid inputs and verify that you get appropriate error messages per EPvalidator.xml.

6. Update documentation

• In OpenStudio-HPXML, the documentation is written in a restructured text (.rst) file.
• Follow formatting closely to the existing documentation.
• Describe the new inputs and its data type, constraints, etc. in the workflow inputs
• Make sure to use the correct order of elements per the HPXML Schema.

7. Update model translation

• The HPXML to OpenStudio measure dictates how HPXML inputs are translated to the OpenStudio/EnergyPlus model.
• 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.
• Update the code that creates the OpenStudio model. Refer to the OpenStudio SDK documentation when interacting with OpenStudio model objects.
• Run the command openstudio tasks.rb update_measures, which will 1) use RuboCop to automatically reformat the ruby code to use a consistent style and/or provide warnings or syntax errors, and 2) update the OpenStudio measure.xml files.
• Run a simulation using your sample file and verify that the EnergyPlus IDF input file appropriately reflects your changes.

8. Add tests [TODO]

9. Update PR for code review

• Pull the base branch into your branch so that it is up to date; CI tests will not run unless your branch is up to date. When doing so, there may be source code conflicts that have to be resolved. For certain files (measure.xml or results_*.csv), you can arbitrarily resolve conflicts because the files are automatically generated. For all other files, you will have to carefully resolve the conflicts by incorporating changes to the same lines of code that occurred in both your branch and the base branch.
• Double-check you don't have any temporary debug code (like print statements).
• Go through the PR checklist and make sure all relevant items are completed and checked. For example, make sure openstudio tasks.rb update_measures has been run, review changes to sample file simulation results, etc.

10. Request code review

• Mark your pull request as ready for review (no longer draft) and request review from another developer.

11. Merge

• Once the reviewer has approved the pull request and all CI tests are passing, the PR can be merged.