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.10/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)
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:208, in Library.load(cls, db_id, ontology_graph, directory, name, overwrite, infer_templates, run_shacl_inference)
    206     if not src.exists():
    207         raise Exception(f"Directory {src} does not exist")
--> 208     return cls._load_from_directory(
    209         src,
    210         overwrite=overwrite,
    211         infer_templates=infer_templates,
    212         run_shacl_inference=run_shacl_inference,
    213     )
    214 elif name is not None:
    215     bm = get_building_motif()

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:417, in Library._load_from_directory(cls, directory, overwrite, infer_templates, run_shacl_inference)
    415     lib._read_yml_file(file, template_id_lookup, dependency_cache)
    416 # now that we have all the templates, we can populate the dependencies
--> 417 lib._resolve_template_dependencies(template_id_lookup, dependency_cache)
    418 # load shape collections from all ontology files in the directory
    419 lib._load_shapes_from_directory(directory)

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

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:470, in Library._resolve_dependency(self, template, dep, template_id_lookup)
    468 # if dep is a _template_dependency, turn it into a template
    469 if isinstance(dep, _template_dependency):
--> 470     dependee = dep.to_template(template_id_lookup)
    471     template.add_dependency(dependee, dep.bindings)
    472     return

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

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/dataclasses/library.py:216, in Library.load(cls, db_id, ontology_graph, directory, name, overwrite, infer_templates, run_shacl_inference)
    214 elif name is not None:
    215     bm = get_building_motif()
--> 216     db_library = bm.table_connection.get_db_library_by_name(name)
    217     return cls(_id=db_library.id, _name=db_library.name, _bm=bm)
    218 else:

File ~/work/BuildingMOTIF/BuildingMOTIF/buildingmotif/database/table_connection.py:230, in TableConnection.get_db_library_by_name(self, name)
    222 def get_db_library_by_name(self, name: str) -> DBLibrary:
    223     """Get database library by name.
    224 
    225     :param name: name of DBLibrary
   (...)
    228     :rtype: DBLibrary
    229     """
--> 230     return self.bm.session.query(DBLibrary).filter(DBLibrary.name == name).one()

File /opt/hostedtoolcache/Python/3.11.10/x64/lib/python3.11/site-packages/sqlalchemy/orm/query.py:2870, in Query.one(self)
   2852 def 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.10/x64/lib/python3.11/site-packages/sqlalchemy/engine/result.py:1522, in ScalarResult.one(self)
   1514 def 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.10/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)
    560 if row is None:
    561     if raise_for_none:
--> 562         raise exc.NoResultFound(
    563             "No row was found when one was required"
    564         )
    565     else:
    566         return None

NoResultFound: No row was found when one was required

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/