Overview

This repo contains a collection of example BuildingSync files and tools for writing and validating BuildingSync use cases as schematron files.

Command line validation

Setup

Python 3 must be installed before continuing. Check your version with python --version.

# Copy repo
git clone https://github.com/BuildingSync/TestSuite.git

# Install dependencies
cd TestSuite
python -m pip install -r requirements.txt

# Test that it works, you should see a message describing the usage
./buildingsch.py

Development

Generate Schematron

First create a CSV file that meets the required structure:

phase title,phase see,pattern title,pattern see,rule title,rule context,assert test,assert description,assert severity,notes

See the CSV files in this repo for examples.

Hierarchy is implied by the lack of text in a column. If no phase data is added to a row, it's considered to be the same phase as the row above. If no pattern data is present, it's assumed to be the same pattern as above. If no rule context is given, it's assumed to be the same as the one above.

The generator expects a "exemplary" xml file which should pass the validation. This is used to make sure all rules are applied (schematron will skip rules if the rule context doesn't match or if it only matches nodes that have already been matched within that pattern). If no exemplary file is provided no rule context checks will be made.

./buildingsch.py generate path_to_csv [path_to_exemplary_xml]

Generate all schematron files by using the following command

./buildingsch.py generate_all

Testing

tox

Ruby tests and validation

We are currently migrating from Ruby to Python, so there is still some remaining Ruby code.

System Requirements

In order to run the OpenStudio simulation tests you must have a stable version of the following:

• OpenStudio>2.0
• Ruby v2.2.4 via an rbenv environment
• Bundler v1.17.2

Setup

Place a file called openstudio.rb into the the directory of your Ruby2.2.4 installation /foo/bar/.rbenv/versions/2.2.4/lib/ruby/2.2.4

The openstudio.rb file should contain one line referencing the location of the Ruby folder of your OpenStudio installation:

require '/Applications/OpenStudio-2.9.1/Ruby/openstudio.rb'

Note - your version of OpenStudio may be different

Due to dependency issues, there are currently two Gemfiles available in the repo. Refer to the linked sections for specifics on how to use.

1. Gemfile - Use this for running Rake tasks for running simulation tests
2. Gemfile-sch - Use this for running Rake tasks for schematron tests

Note - there is no need to rm -rf .bundle/ when switching between the above two scenarios. Just run the below commands and then proceed as described in the linked sections

$ bundle install --gemfile Gemfile --path .bundle/install
$ bundle install --gemfile Gemfile-sch --path .bundle/install

Use Cases, Model View Definitions, and Modeling Level of Detail Definitions

As BuildingSync has grown in its ability to represent information about buildings, it is able to define aspects of buildings at varying levels of abstraction. Additionally, while originally designed to capture energy audit data, data stored in BuildingSync can be used for other purposes as well. Working with data for different purposes and at varying levels of abstraction in a schema is not something new to BuildingSync. This is a similar problem faced by the building information modeling (BIM) community, where different informational requirements are necessary at different project stages and many different stakeholders are involved in projects. BIM uses the Industry Foundation Classes (IFC) schema for transferring data between applications. The BuildingSync team utilizes two concepts introduced by the BIM world for refining data expectations needed by different users of the schema: Level of Development (LOD) and Model View Definitions (MVD).

The LOD spec is a comprehensive guide developed by the AIA and BIMForm to help BIM authors describe the depth of their models based on phases of design reference. MVDs are developed by a variety of users in the BIM community to define a subset of the overall schema necessary for a specific use case or workflow reference. We utilize these concepts in BuildingSync and define them as follows:

MVD

A MVD in BuildingSync is intended to provide a narrower focus for which the data stored in a BuildingSync document is intended. It is analogous to the MVD introduced above. The two primary MVDs developed so far are: - Audit – To ensure alignment of data contained in the BuildingSync document with portions of the ASHRAE 211 Standard - OpenStudio Simulation – To ensure alignment of data contained in the BuildingSync document with requirements necessary to utilize the BuildingSync-gem for automatically generating and simulating an energy model using OpenStudio.

MLOD definitions

The MLOD definitions are intended to provide expectations of informational requirements at differing levels of abstraction. For example, in BuildingSync, a Building element can be defined to capture high-level information, but narrower levels of abstraction regarding architectural and mechanical space configurations (Section, ThermalZone, or Space elements) can be defined as child elements of the Building to provide more specific information. This is analogous to the LOD spec introduced above.

Use case

A use case is a combination of an MVD and a MLOD. Together, these provide formalized definitions for BuildingSync data expectations.

The formal definitions for each use case is defined using Schematron files, which are located in spec/use_cases/[schema_version]/[MLOD]_[MVD].sch. Six MLODs have been defined in BuildingSync, the first four being in alignment with ASHRAE Standard 211:

The lib directory provides a library of general purpose Schematron functions used within the individual Schematron documents. These functions are designed to be used by others with use cases outside of the Levels defined above. Narrative overviews for the different levels can be found in docs.

Rakefile

Rake tasks are currently used for two purposes:

1. Tests
2. Running Simulations

Schematron Tests

RSpec is used for running tests. The tests are written around the following:

1. Testing individual Schematron functions within lib/ are working correctly. In Progress.
2. Testing that Schematron is working against Level Definition files. In Progress.

$ bundle install --gemfile Gemfile-sch --path .bundle/install # if not previously run
$ BUNDLE_GEMFILE=Gemfile-sch bundle exec rake spec
$ BUNDLE_GEMFILE=Gemfile-sch bundle exec rake spec SPEC=spec/lib/scenario_elements_spec.rb # run tests in single file

More information on developing Schematron functions (and the required tests!) can be found in the docs/Contributions and Schematron.md document.

Running Simulation Tests

Tests are also written for OpenStudio Simulation files. Examples for how to use the BuildingSync-gem and the Translator class to run OpenStudio simulations using a BuildingSync XML file can be found in the spec/simulations/**_spec.rb files. Since running all of the files through a simulation can be computationally expensive, tests are separated into two scenarios:

1. Translation of BuildingSync XML file into the OSM / OSW.
2. Simulation of the OSW.

By default, all of the files are removed after the translation/simulation occurs. This can be overriden by passing the REMOVE_FILES=false environment variable. Tests can be run as follows:

Test that simulation files are translated (files will be removed after test)

$ BUNDLE_GEMFILE=Gemfile bundle exec rake translate

Test that simulation files can be simulated (files will remain after test)

$ BUNDLE_GEMFILE=Gemfile bundle exec rake simulate REMOVE_FILES=false

Outputs

Output directories will be created after running either the translation or simulation tests and are located in spec/simulations/[schema-version]/[sim-file]/.

Examples

HVAC System Examples

Where the System Type specified below does not exactly match the enumeration in the BSync XML file, check the mapping defined by map_primary_hvac_system_type_to_cbecs_system_type. Additionally, see the examples/HVACSystems directory for a tutorial and example files.

Lighting System Examples

Premise Examples

Contributing

See Contributions and Schematron