Model Correction

Important

This tutorial assumes that BuildingMOTIF has already been installed in the local environment.

The purpose of this tutorial is to learn how to fix a model that fails validation using BuildingMOTIF Templates to automate the correction process.

Setup

Like the previous tutorial, we’ll create an in-memory BuildingMOTIF instance, load the model, and load some libraries. We’ll also load the manifest from the previous tutorial.

Warning

Currently, libraries in ../../buildingmotif/libraries/ are included and libraries in ../../libraries/ are excluded from the BuildingMOTIF Python package (available by cloning, downloading, or forking the repository). See NREL/BuildingMOTIF#133.

from rdflib import Namespace, URIRef
from buildingmotif import BuildingMOTIF
from buildingmotif.dataclasses import Model, Library, Template
from buildingmotif.namespaces import BRICK, RDF # import this to make writing URIs easier

# in-memory instance
bm = BuildingMOTIF("sqlite://")

# create the namespace for the building
BLDG = Namespace('urn:bldg/')

# create the building model
model = Model.create(BLDG, description="This is a test model for a simple building")

# load libraries included with the python package
constraints = Library.load(ontology_graph="constraints/constraints.ttl")

# load libraries excluded from the python package (available from the repository)
brick = Library.load(ontology_graph="../../libraries/brick/Brick-subset.ttl")
g36 = Library.load(directory="../../libraries/ashrae/guideline36")


# load tutorial 2 model and manifest
model.graph.parse("tutorial2_model.ttl", format="ttl")
manifest = Library.load(ontology_graph="tutorial2_manifest.ttl")

# assign the manifest to our model
model.update_manifest(manifest.get_shape_collection())

/opt/hostedtoolcache/Python/3.11.9/x64/lib/python3.11/site-packages/pyshacl/extras/__init__.py:46: Warning: Extra "js" is not satisfied because requirement pyduktape2 is not installed.
  warn(Warning(f"Extra \"{extra_name}\" is not satisfied because requirement {req} is not installed."))

---------------------------------------------------------------------------
NoResultFound                             Traceback (most recent call last)
File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/database/table_connection.py:316, in TableConnection.get_db_template_by_name(self, name)
    314 try:
    315     db_template = (
--> 316         self.bm.session.query(DBTemplate).filter(DBTemplate.name == name).one()
    317     )
    318 except NoResultFound:

File /opt/hostedtoolcache/Python/3.11.9/x64/lib/python3.11/site-packages/sqlalchemy/orm/query.py:2870, in Query.one(self)
   2853 """Return exactly one result or raise an exception.
   2854 
   2855 Raises ``sqlalchemy.orm.exc.NoResultFound`` if the query selects
   (...)
   2868 
   2869 """
-> 2870 return self._iter().one()

File /opt/hostedtoolcache/Python/3.11.9/x64/lib/python3.11/site-packages/sqlalchemy/engine/result.py:1522, in ScalarResult.one(self)
   1515 """Return exactly one object or raise an exception.
   1516 
   1517 Equivalent to :meth:`_engine.Result.one` except that
   (...)
   1520 
   1521 """
-> 1522 return self._only_one_row(
   1523     raise_for_second_row=True, raise_for_none=True, scalar=False
   1524 )

File /opt/hostedtoolcache/Python/3.11.9/x64/lib/python3.11/site-packages/sqlalchemy/engine/result.py:562, in ResultInternal._only_one_row(self, raise_for_second_row, raise_for_none, scalar)
    561 if raise_for_none:
--> 562     raise exc.NoResultFound(
    563         "No row was found when one was required"
    564     )
    565 else:

NoResultFound: No row was found when one was required

During handling of the above exception, another exception occurred:

NoResultFound                             Traceback (most recent call last)
Cell In[1], line 20
     18 # load libraries excluded from the python package (available from the repository)
     19 brick = Library.load(ontology_graph="../../libraries/brick/Brick-subset.ttl")
---> 20 g36 = Library.load(directory="../../libraries/ashrae/guideline36")
     23 # load tutorial 2 model and manifest
     24 model.graph.parse("tutorial2_model.ttl", format="ttl")

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:194, in Library.load(cls, db_id, ontology_graph, directory, name, overwrite)
    192     if not src.exists():
    193         raise Exception(f"Directory {src} does not exist")
--> 194     return cls._load_from_directory(src, overwrite=overwrite)
    195 elif name is not None:
    196     bm = get_building_motif()

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:345, in Library._load_from_directory(cls, directory, overwrite)
    343     lib._read_yml_file(file, template_id_lookup, dependency_cache)
    344 # now that we have all the templates, we can populate the dependencies
--> 345 lib._resolve_template_dependencies(template_id_lookup, dependency_cache)
    346 # load shape collections from all ontology files in the directory
    347 lib._load_shapes_from_directory(directory)

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:447, in Library._resolve_template_dependencies(self, template_id_lookup, dependency_cache)
    445         continue
    446     for dep in dependency_cache[template.id]:
--> 447         self._resolve_dependency(template, dep, template_id_lookup)
    448 # check that all dependencies are valid (use parameters that exist, etc)
    449 for template in self.get_templates():

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:398, in Library._resolve_dependency(self, template, dep, template_id_lookup)
    396 # if dep is a _template_dependency, turn it into a template
    397 if isinstance(dep, _template_dependency):
--> 398     dependee = dep.to_template(template_id_lookup)
    399     template.add_dependency(dependee, dep.bindings)
    400     return

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:87, in _template_dependency.to_template(self, id_lookup)
     84 # if not in the local cache, then search the database for the template
     85 # within the given library
     86 library = Library.load(name=self.library)
---> 87 return library.get_template_by_name(self.template_name)

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:578, in Library.get_template_by_name(self, name)
    569 def get_template_by_name(self, name: str) -> Template:
    570     """Get template by name from library.
    571 
    572     :param name: template name
   (...)
    576     :rtype: Template
    577     """
--> 578     dbt = self._bm.table_connection.get_db_template_by_name(name)
    579     if dbt.library_id != self._id:
    580         raise ValueError(f"Template {name} not in library {self._name}")

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/database/table_connection.py:319, in TableConnection.get_db_template_by_name(self, name)
    315     db_template = (
    316         self.bm.session.query(DBTemplate).filter(DBTemplate.name == name).one()
    317     )
    318 except NoResultFound:
--> 319     raise NoResultFound(f"No template found with name {name}")
    320 return db_template

NoResultFound: No template found with name https://brickschema.org/schema/Brick#Leaving_Chilled_Water_Flow_Sensor

Model Validation

Let’s validate the model again to see what’s causing the failure.

validation_result = model.validate()
print(f"Model is valid? {validation_result.valid}")

# print reasons
for uri, diffset in validation_result.diffset.items():
    for diff in diffset:
        print(f" - {diff.reason()}")

We can get this information in a few different ways, too. For example, asking for all the entities which have failed validation:

for e in validation_result.get_broken_entities():
    print(e)

We can also get all reasons a particular entity has failed validation:

for diff in validation_result.get_diffs_for_entity(BLDG["Core_ZN-PSC_AC"]):
    print(diff.reason())

Model Correction with Templates

The model is failing because the AHU doesn’t have the minimum number of supply fans associated with it. We could add the fan explicitly by adding those triples to the model like we’ve done previously, but we can also ask BuildingMOTIF to generate new templates that explicitly prompt us for the missing information. We can also take a closer look at the first autogenerated template

# create a new library to hold these generated templates
generated_templates = Library.create("my-autogenerated-templates")

# loop through all results for the AHU
for diff in validation_result.get_diffs_for_entity(BLDG["Core_ZN-PSC_AC"]):
    diff.resolve(generated_templates)

# print some of the autogenerated template
for templ in generated_templates.get_templates():
    templ = templ.inline_dependencies()
    print(f"Name (autogenerated): {templ.name}")
    print(f"Parameters (autogenerated): {templ.parameters}")
    print("Template body (autogenerated):")
    print(templ.body.serialize())
    print('-' * 79)

In this case, the generated templates are fairly simple. They require an input for the name of the supply fan and the names of several missing points. We can loop through each of these generated templates and create the names. Here, we are creating arbitrary names for the points but in a real setting you would likely pull the equipment or point names from an external source like a Building Information Model or BACnet network[1] (see future tutorials for how to do this!) Another challenge is the fact that we already have a supply fan in the model. Here, we can take advantage of the fact that the name of the fan in the existing model are just the name of the AHU wtih the -Fan postfix. The name of the AHU is in the generated templates (see above) so we can just pull out the name of the AHU, add the postfix, and use that as the value for the name parameter.

If we just add the generated templates to the building model, we will probably pass validation but the entity names will have no significance to the building. It is highly recommended to use the template evaluation features (demonstrated below) to fill in the parameters with the “real” names of the entities as they appear in the building and/or building management system.

# use the name of the AHU from above as the base of our template names
ahu_name = "Core_ZN-PSC_AC"

# lookup for the name of the template to the name of the point or part
points_and_parts = {
    "resolve_Core_ZN-PSC_ACMixed_Air_Temperature_Sensor": "-MAT",
    "resolve_Core_ZN-PSC_ACFilter_Differential_Pressure_Sensor": "-FilterDPS",
    "resolve_Core_ZN-PSC_ACCooling_Command": "-CCmd",
    "resolve_Core_ZN-PSC_ACHeating_Command": "-HCmd",
    "resolve_Core_ZN-PSC_ACOutside_Air_Temperature_Sensor": "-OAT",
    "resolve_Core_ZN-PSC_ACSupply_Air_Temperature_Sensor": "-SAT",
    "resolve_Core_ZN-PSC_ACReturn_Air_Temperature_Sensor": "-RAT",
    "resolveCore_ZN-PSC_ACsa-fan": "-Fan", # this is an existing fan in the model!
}

for templ in generated_templates.get_templates():
    templ = templ.inline_dependencies()

    suffix = points_and_parts[templ.name]

    # we know from the exploration above that each template has
    # 1 parameter which is the name of the missing item
    param = list(templ.parameters)[0]
    bindings = {
        param: BLDG[ahu_name + suffix],
    }
    thing = templ.evaluate(bindings)
    if isinstance(thing, Template):
        # there might be other parameters on a template. Invent names for them
        _, thing = thing.fill(BLDG)
    model.add_graph(thing)

We use the same code as before to ask BuildingMOTIF if the model is now valid:

validation_result = model.validate()
print(f"Model is valid? {validation_result.valid}")
# print reasons
for uri, diffset in validation_result.diffset.items():
    for diff in diffset:
        print(f" - {diff.reason()}")

We are still not finished. The sa-fan shape has its own requirements for necessary points. Let’s use the same process above to get templates we can fill out to repair the model

generated_templates_sf = Library.create("my-autogenerated-templates-sf")
for diff in validation_result.get_diffs_for_entity(BLDG["Core_ZN-PSC_AC-Fan"]):
    diff.resolve(generated_templates_sf)

# print some of the autogenerated template
for templ in generated_templates_sf.get_templates():
    templ = templ.inline_dependencies()
    print(f"Name (autogenerated): {templ.name}")
    print(f"Parameters (autogenerated): {templ.parameters}")
    print("Template body (autogenerated):")
    print(templ.body.serialize())
    print('-' * 79)

Use the names of these templates to build a lookup table for the point and part names.

sf_name = "Core_ZN-PSC_AC-Fan"

# lookup for the name of the template to the name of the point or part
points_and_parts = {
    "resolve_Core_ZN-PSC_AC-FanFrequency_Command": "-Freq",
    "resolve_Core_ZN-PSC_AC-FanStart_Stop_Command": "-StartStop",
    "resolve_Core_ZN-PSC_AC-FanFan_Status": "-Sts",
}
for templ in generated_templates_sf.get_templates():
    templ = templ.inline_dependencies()

    suffix = points_and_parts[templ.name]

    param = list(templ.parameters)[0]
    bindings = {
        param: BLDG[sf_name + suffix],
    }
    thing = templ.evaluate(bindings)
    model.add_graph(thing)

We can re-check the validation of the model now:

validation_result = model.validate()
print(f"Model is valid? {validation_result.valid}")
print(validation_result.report.serialize())

# print reasons
for uri, diffset in validation_result.diffset.items():
    for diff in diffset:
        print(f" - {diff.reason()}")

Success! The model is valid with respect to the targeted use case, i.e. the model can support the high-performance sequences of operation for single zone VAV AHUs from ASHRAE Guideline 36. Let’s take a look at the validated model and save it for use in future tutorials.

# print model
print(model.graph.serialize())

#save model
model.graph.serialize(destination="tutorial3_model.ttl")

---

[1]

https://bacnet.org/