# Constructing building model

This section of the walkthrough covers the development of a BRICK model for your buildings/sites. We will be using the DCH Model Generation Tool (mgtool) which requires a set of CSVs, so reading[ that section of the documentation](/dch-2.0-documentation/si-docs/dch-onboarding-brick-model-construction/overview.md) before proceeding is encouraged.

It is assumed: 

1. That you have already read our [Model Scope and Requirements](/dch-2.0-documentation/si-docs/dch-onboarding-timeseries-data/selecting-the-points.md) document and have a scope of onboarding. This walkthrough is for a full level 3 model.
2. You have collated all technical information about your onboarding scope. Documents like BMS screenshots, Single Line Diagrams (SLDs), plant blueprints etc.

{% hint style="warning" %}
This is NOT a real model, it is an imaginary building. The points for the equipment may not be complete compared to the real world (e.g. FCUs in this model do not have air flow sensor). This is strictly to outline the general process of modelling a building.
{% endhint %}

Although we recommend you follow these steps in order, you may also take a different approach to developing your model CSVs. Our approach is a top-down method which starts with the high-level entities and their relationships (i.e. skeleton and object CSVs first) before dealing with the points.

{% hint style="danger" %}
To ensure compatibility with DCH applications, building models MUST abide by our norms as detailed in:

* [Electrical Norms](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-modelling-norms/electrical-modelling-norms.md)
* [PV Norms](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-modelling-norms/pv-modelling-norms.md)
* [Mechanical and Misc. Norms](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-modelling-norms/mechanical-and-misc.-modelling-norms.md)
  {% endhint %}

## Step 1: skeleton CSV

This CSV declares:

1. What Equipment, Locations, Zones and Collections (entities) are in the building
2. How these entities related to each other

We also require a prefix to be used for URI mapping. For this model we will use **bldA** as the prefix.

For this walkthrough we are modelling a building with the following technical documentation available. We will fill-in our skeleton CSV as we go on. 

<figure><img src="/files/gT5VRfzdjknoPQb8iPX9" alt=""><figcaption><p>Floorplans, HVAC zones/locations and IoT sensors</p></figcaption></figure>

**Things we take away:**

* The building has 2 wings
* Each wing has 2 floors
* Each floor has 2 rooms
* HVAC
  * All VAVs except VAV7 feed a specific room (VAV7 feeds a zone containing 2 rooms) \[7 VAVs]
  * FCUs are serving 2 rooms each \[4 FCUs]
* There are Temperature and Humidity (TH) IoT sensors installed that are not integrated with the HVAC systems

Based on these notes, we can start populating our skeleton CSV:

<table data-full-width="true"><thead><tr><th width="177">0</th><th width="221">1</th><th width="203">2</th><th width="268">3</th><th width="185">4</th><th width="143">5</th><th width="119">6</th><th>7</th></tr></thead><tbody><tr><td>['hasPart',1]</td><td>['isPartOf',0]</td><td>['isPartOf,1]</td><td>['isPartOf',2]</td><td>['hasPart',3]</td><td>['feeds',3]</td><td>['feeds',4]</td><td>['feeds',2]</td></tr><tr><td>bldA|Building_A</td><td>bldA|Eastern_Wing</td><td>bldA|Eastern_Floor_1</td><td>bldA|Eastern_Floor_1_Room_1</td><td></td><td>bldA|VAV5</td><td></td><td>bldA|FCU3</td></tr><tr><td>bldA|Building_A</td><td>bldA|Eastern_Wing</td><td>bldA|Eastern_Floor_1</td><td>bldA|Eastern_Floor_1_Room_2</td><td></td><td>bldA|VAV6</td><td></td><td></td></tr><tr><td>bldA|Building_A</td><td>bldA|Eastern_Wing</td><td>bldA|Eastern_Floor_2</td><td>bldA|Eastern_Floor_2_Room_1</td><td>bldA|HVAC_Zone_A</td><td></td><td>bldA|VAV7</td><td>bldA|FCU4</td></tr><tr><td>bldA|Building_A</td><td>bldA|Eastern_Wing</td><td>bldA|Eastern_Floor_2</td><td>bldA|Eastern_Floor_2_Room_2</td><td>bldA|HVAC_Zone_A</td><td></td><td></td><td></td></tr><tr><td>bldA|Building_A</td><td>bldA|Western_Wing</td><td>bldA|Western_Floor_1</td><td>bldA|Western_Floor_1_Room_1</td><td></td><td>bldA|VAV1</td><td></td><td>bldA|FCU1</td></tr><tr><td>bldA|Building_A</td><td>bldA|Western_Wing</td><td>bldA|Western_Floor_1</td><td>bldA|Western_Floor_1_Room_2</td><td></td><td>bldA|VAV2</td><td></td><td></td></tr><tr><td>bldA|Building_A</td><td>bldA|Western_Wing</td><td>bldA|Western_Floor_2</td><td>bldA|Western_Floor_2_Room_1</td><td></td><td>bldA|VAV3</td><td></td><td>bldA|FCU2</td></tr><tr><td>bldA|Building_A</td><td>bldA|Western_Wing</td><td>bldA|Western_Floor_2</td><td>bldA|Western_Floor_2_Room_2</td><td></td><td>bldA|VAV4</td><td></td><td></td></tr></tbody></table>

<figure><img src="/files/kVAJ83LC1pPEnpHgfhkh" alt=""><figcaption><p>FCU BMS screens</p></figcaption></figure>

**Things we take away:**

* FCUs in this building have the following sub-equipment:
  * Filter
  * CHW Valve
  * CHW Coil
  * HW Valve
  * HW Coil
  * Supply Fan

Now we can declare these sub-equipment in the skeleton CSV picking up from column 7 where we declared our FCUs and where they are feeding. Note that we have moved many rows down to make our job easier and we are no longer operating in the same rows as last time.

<table data-full-width="true"><thead><tr><th>7</th><th>8</th></tr></thead><tbody><tr><td>['feeds',2]</td><td>['isPartOf',7]</td></tr><tr><td>bldA|FCU3</td><td></td></tr><tr><td></td><td></td></tr><tr><td>bldA|FCU4</td><td></td></tr><tr><td></td><td></td></tr><tr><td>bldA|FCU1</td><td></td></tr><tr><td></td><td></td></tr><tr><td>bldA|FCU2</td><td></td></tr><tr><td></td><td></td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_Filter</td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_CHWValve</td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_CHWCoil</td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_HWValve</td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_HWCoil</td></tr><tr><td>bldA|FCU1</td><td>bldA|FCU1_SupplyFan</td></tr></tbody></table>

We repeat this for all FCUs. The skeleton CSV at the end of this step looks like this:

{% file src="/files/ouLPUcdpne1m8yuOIJ8R" %}

<figure><img src="/files/n4TxWrrYGQkYCQVjZ5wZ" alt=""><figcaption><p>VAV BMS screens</p></figcaption></figure>

**Things we take away:**

* VAVs in this building have the following sub-equipment:
  * HW Valve
  * HW Coil

We repeat the same process as we did with FCUs to declare these sub-equipment.

{% file src="/files/7HPZOFMa1xNujFc9VRoS" %}

<figure><img src="/files/e20fnirFOZbNICEwkvm9" alt=""><figcaption><p>AHU BMS screen</p></figcaption></figure>

**Things we take away:**

* 1 AHU only in this building which feeds the VAVs
* The AHU has the following sub-equipment:
  * OA Damper
  * RA Damper
  * Filter
  * CHW Valve
  * CHW Coil
  * HW Valve
  * HW Coil
  * Return Fan
  * Return Fan VSD
  * Supply Fan
  * Supply Fan VSD

With the AHU there are a couple of things we need to add:

* Add the sub-equipment listed above.
* Note that based on our [VSD norms](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-modelling-norms/mechanical-and-misc.-modelling-norms.md#vsds), we MUST model the VSD as feeding their respective sub-equipment and it does not take on the isPartOf relationship with the AHU.
* Add the relationship between the AHU and the VAVs.

This brings our CSV to this state:

{% file src="/files/QPq9e10oCbEFvQhLNnbS" %}

<figure><img src="/files/7zsJgAcE4QfTOyO5M5F4" alt=""><figcaption><p>Chilled Water Plant BMS screen</p></figcaption></figure>

**Things we take away:**

* The Chilled Water Plant contains:
  * A Chiller
  * A Chilled Water Pump

To close the chilled water loop, we model from our chilled water coils to the chiller (CHWP) and then to the chilled water pump:

{% file src="/files/hT6moG8UoMcgNTMsWp5W" %}

<figure><img src="/files/RVK3aFSxt2UU7QJnF7yE" alt=""><figcaption><p>Hot Water Plant BMS Screen</p></figcaption></figure>

**Things we take away:**

* The Chilled Water Plant contains:
  * A Boiler
  * A Hot Water Pump

We repeat closing the loop, this time for our hot water plant. The result is a full plant skeleton CSV:

{% file src="/files/3kjMn1EBwzRcTaChcP8j" %}

<figure><img src="/files/eid0rAHWjL0UDE1KRFYc" alt=""><figcaption><p>Electrical</p></figcaption></figure>

**Things we take away:**

* There are 4 total electrical meters in the building.
  * Main building supply (point of connection with grid) is metered by MSSB.
  * Building has a submeter for the Chiller as measured by M1.
  * Building has a submeter for the Boiler as measured by M2.
  * Building has solar generation as measured by both the inverter and M3.

Starting from the bottom of the electrical tree, we establish the lower level meters and work our way up. In this scenario, M1, M2 and M3 are submeters of MSSB while they all meter their respective equipment (Chiller, Boiler and Inverter respectively). Additionally, we link the solar array with the inverter as described in our norms. This results in our final skeleton CSV:

{% file src="/files/CF5por4BKQlmtWC5I5kw" %}

## Step 2: objects CSV

This step is relatively easy, all we have to do is list all entity instances we used in the skeleton and assign a[ BRICK class](https://brickschema.org/ontology/1.3) to them. You can also use our [BRICK patch classes](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-extensions.md). For this model, the objects CSV would look like:

<table data-full-width="true"><thead><tr><th>Model_ID|Entity_Name</th><th>Class</th></tr></thead><tbody><tr><td>bldA|AHU</td><td>AHU</td></tr><tr><td>bldA|Boiler</td><td>Boiler</td></tr><tr><td>bldA|Building_A</td><td>Building</td></tr><tr><td>bldA|MSSB_Primary</td><td>Building_Electrical_Meter</td></tr><tr><td>bldA|AHU_CHWCoil</td><td>Chilled_Water_Coil</td></tr><tr><td>...</td><td>...</td></tr></tbody></table>

{% file src="/files/Yyqmhv11xgoip0T29U9z" %}

## Step 3: point\_list and point\_linkage CSVs

This step is where we will link the entities created in the last steps to their points. For this step we require our points list:

1. On the sidebar, go to Data and select Data Sources

   <figure><img src="/files/mgwPYLS0AiYKPYK5qjmq" alt=""><figcaption></figcaption></figure>

2. Find your data source from the list and select it

   <figure><img src="/files/Y1kOIZt8yr8yoXuG45c7" alt=""><figcaption></figcaption></figure>

3. Click on **Download Points List**

   <figure><img src="/files/eZ86k5QX3jQlcWufHRcn" alt=""><figcaption></figcaption></figure>

For our mock model, we have the following points list:

{% file src="/files/kVV27NMBPVbNpOuog1Pk" %}

The points\_list CSV file requires the full URI path of the points, so we copy the **uri** field into a new CSV and save it as **points\_list.csv** (No header required). The Data Pool URI can also be found in the Data Source page.

<figure><img src="/files/SUOAtUaBct1ZpCF4pdjj" alt=""><figcaption><p>points_list.csv</p></figcaption></figure>

Now we have to use this list for out point\_linkage CSV. This operation requires a string pattern match as detailed [here](/dch-2.0-documentation/si-docs/dch-onboarding-brick-model-construction/point_create_link_pattern_match-operation.md). This pattern match looks for the declared expression anywhere in the point name. For example, for the point:

dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/datapool/managed\_datapool\_walkthrough\_datasource\_a710d406-9eb4-4070-b2fe-45c4a0bc8782#walkthrough\_site.walkthrough\_buildin&#x67;**.AHU.**&#x45;nable

The expression is **.AHU.** to link the point to the **bld|AHU** entity we created in our skeleton and object CSVs.

However, for points such as:

dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/datapool/managed\_datapool\_walkthrough\_datasource\_a710d406-9eb4-4070-b2fe-45c4a0bc8782#walkthrough\_site.walkthrough\_building.**TH3**.Air\_Temp

dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/datapool/managed\_datapool\_walkthrough\_datasource\_a710d406-9eb4-4070-b2fe-45c4a0bc8782#walkthrough\_site.walkthrough\_building.**TH3**.Air\_Hum

Since IoT equipment is not directly modelled, we have to link these points to their respective location/zone. In the case of **TH3**, since the sensor platform is installed in room **bldA|Western\_Floor\_2\_Room\_1** then the expression for this room would be **TH3**. This links both points to the room.

The final point\_linkage CSV looks like this:

<table data-full-width="true"><thead><tr><th>Model_ID|Entity_Name</th><th>Point_Expressions</th></tr></thead><tbody><tr><td>bld|AHU</td><td>.AHU.</td></tr><tr><td>bldA|Western_Floor_2_Room_1</td><td>.TH3.</td></tr><tr><td>...</td><td>...</td></tr></tbody></table>

{% hint style="info" %}
A good way of populating the point\_linkage CSV is to copy the **Model\_ID|Entity\_Name** column from objects CSV to ensure you have all of your entities covered. Next start linking points until you are out of points to link.
{% endhint %}

{% hint style="danger" %}
Be aware that if you use the expression **AHU** (without the dots) for the entity AHU, all points with **AHU** in them are then linked and you can no longer link the points for the AHU's sub-equipment (e.g. AHU\_CHWCoil is then pointless). You can overcome this by either reorganising the order of your pattern match or to change the pattern altogether. In this case we included the dots before and after the **AHU** to avoid this pitfall.&#x20;
{% endhint %}

{% file src="/files/Xw3mKPzXQYDrFBiDOMsM" %}

## **Step 4: manifest.json**

Now that we are done with our CSVs, we need to write a manifest file. You need the following information before you get started:

* Organisation ID (in this case I am using my sandbox organisation **sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62**)
* Site ID: exactly as created on DCH (for this example it is **walkthrough\_site**)
* Building ID: exactly as created on DCH (for this example it is **walkthrough\_building**)
* Data pool ID: you can get this by refering to your point\_list.csv. You can see the point URI names follow the pattern of \<dch:org/YOUR\_ORG/datapool/YOUR\_DATAPOOL\_ID#> (in our case, the data pool ID is **managed\_datapool\_walkthrough\_datasource\_390c330e-8335-4084-abf0-00d6daf87c5a#**.

First, we set the manifest version. We are currently at version 1.0.0:

```json
{
    "manifest_version":"1.0.0",
}
```

Next, we add our URI mappings based on the info above:

```json
{
    "manifest_version":"1.0.0",
  "id_mapping": {
    "bldA": "dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/site/walkthrough_site/building/walkthrough_building#",
    "WALKTHROUGH_DATA": "dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/datapool/managed_datapool_walkthrough_datasource_390c330e-8335-4084-abf0-00d6daf87c5a#"
  }
}
```

Note how we assigned the URI prefix **bldA** to the actual building in DCH. The URI path to your data pool can be called whatever you want, that is added to reduce the size of the final model file by replacing the path with **WALKTHROUGH\_DATA**.

Finally, we tell the tool what operations we are using and what the CSVs are called:

```json
{
  "manifest_version": "1.0.0",
  "id_mapping": {
    "bldA": "dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/site/walkthrough_site/building/walkthrough_building#",
    "WALKTHROUGH_DATA": "dch:org/sandbox-eddf8c4b-a3a7-49a1-82d4-1e4821baca62/datapool/managed_datapool_walkthrough_datasource_390c330e-8335-4084-abf0-00d6daf87c5a#"
  },
  "operations": [{
      "operation_type": "CREATE",
      "config": {
        "object_file": "objects.csv"
      }
    }, {
      "operation_type": "RELATE",
      "config": {
        "skeleton_file": "skeleton_FINAL.csv"
      }
    }, {
      "operation_type": "POINT_CREATE_LINK_PATTERN_MATCH",
      "config": {
        "point_linkage_file": "point_linkage.csv",
        "point_list_files": ["points_list.csv"]
      }
    }]
}
```

Save this file and call it **manifest.json**.

{% hint style="warning" %}
Couple of warnings:

* The tool reads these fields in order, so if you put RELATE before CREATE the tool will fail thinking there are no objects created.
* In POINT\_CREATE\_LINK\_PATTERN\_MATCH operation, point\_list\_files MUST be set as a list with square brackets.
  {% endhint %}

## **Step 5: generating a TTL**

Now that we have all of our CSVs and manifest, we can use the mgtool to generate our model.

1. Make a folder and call it whatever you wish (we will call it **walkthrough\_model**).
2. Place your manifest in that folder.
3. Place all of your CSVs in a folder called **input\_csvs** in the root folder.

   <figure><img src="/files/dQmLmNBQtn5AkYht8Nfs" alt=""><figcaption></figcaption></figure>
4. Place the **manifest** and the **input\_csvs** folder in a ZIP file.
5. In the DCH sidebar, go to **Tools** and select **Generate Model(s).**

   <figure><img src="/files/NEFZxBuOLUomjnxBt6eN" alt=""><figcaption></figcaption></figure>
6. Drag and drop the zip file in the box and press **Generate Model**.
7. After the model generation is done, a ZIP file will be downloaded by your browser with the full report and the generated TTL file.
8. Check the **mgtool.log** for any warnings or errors.

{% file src="/files/qK8XCOsNmgaf88c1FFx2" %}

{% file src="/files/3ftBbpXMkmTAqcPydip6" %}

## Step 6: upload your model

Now we can upload our model TTL to DCH. Navigate to your building page by clicking on it.

<figure><img src="/files/ypRFXiCmCTJfK34FjP6L" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/0Us7cgmcghJhpXhLEMzP" alt=""><figcaption></figcaption></figure>

Press **Upload Model File** and select your TTL file.

<figure><img src="/files/efRtmTAnGUg5GHrcLmSt" alt=""><figcaption></figcaption></figure>

Press **Upload & Overwrite**. If everything is alright with your model, you should get this message:

<figure><img src="/files/TnB7jDCVaQ5NC5HiTc3K" alt=""><figcaption></figcaption></figure>

Your building page should now have **Site Published**.

<figure><img src="/files/YWvfdcIMHAMOpkxW2Yn3" alt=""><figcaption></figcaption></figure>

## **Step 7: point classification**

Last step is to use the [**Point Classifier**](/dch-2.0-documentation/si-docs/dch-onboarding-brick-model-construction/point-classifier-ui.md) tool to assign BRICK classes to our points.

From the sidebar, go to **Tools** and select **Point Classifier**.

<figure><img src="/files/vRjFEzKSAdRxZ8eAdniJ" alt=""><figcaption></figcaption></figure>

Select **Create New** and enter a name for this classifier set. Then select your data pool from the list.

<figure><img src="/files/E9RMdJ75lmTbVhqPxAsK" alt=""><figcaption></figcaption></figure>

Press on the **+** sign on the top right to create a new rule to this set. We will be focusing on the **ID** field which represent the point IDs as shown in the point\_list CSV. It is a good idea to have your point\_list CSV open on the side.

As the first rule, we will target all points ending with "**.Enable"**. Type **\*Enable** on the left field and select **Enable Command** on the right **Class** field. This classifies all points ending with **.Ending** as **Enable Command**.

<figure><img src="/files/fMtefVYvkOMPDrxPLsTj" alt=""><figcaption></figcaption></figure>

We repeat this for all other point types. For all of our KWH points, we have to set Entity Properties to abide by our [Electrical Modelling Norms](/dch-2.0-documentation/dch-and-the-brick-schema-ontology/dch-brick-modelling-norms/electrical-modelling-norms.md). To do this, enable the **Properties** field and start adding the values to their properties. You may also add Units of Measure in the right **UoM** fields.

<figure><img src="/files/jNyKZcs8RsgdZvWsLima" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2F1r12vbQkxKxvO6cf3f" alt=""><figcaption></figcaption></figure>

When you are done, press **Generate Rules.** A new section opens on the same page with the changes mapped out for your approval. If everything looks good and you wish to proceed, press **Apply Changes** at the bottom of the page. Your points are now classified and your model is DONE!

<figure><img src="/files/kDCRdH6mhSi1oL1PG3wR" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dataclearinghouse.org/dch-2.0-documentation/walkthroughs/constructing-building-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.