OpenStudio Advanced - Gelişmiş Metodolojiler 22 Aralık 2021

8. OpenStudio: Uploads to BCL

​

Transcript:

Today we are going to discuss the Building Component Library (BCL) and how to upload components to the BCL.
What is it? We have already discussed this in previous videos...
The National Renewable Energy Laboratory (NREL) created the Building Component Library a number of years ago.
It allows researchers and engineers to share various aspects of their energy modeling with each other on a public forum.
It is not unlike other public repositories for instance: components for sketchup or for revit or any other number of modeling or design programs.
You can go up to the resources and browse the BCL based on the type of information that you are looking for.
The library contains measures; these are all snippets of program that can transform your energy model.
It can automatically change things such as electric lighting controls.
Or it might go through and model your building and then it would change the windows to a different type of window to see what the energy difference is.
There are many different kinds of programs.
Also, there is components, which are simply constructions. Mostly constructions. Components could also be different types of equipment.
You can search for different types of windows or doors to plug into your energy model. You can find those here.
Today, we are going to show how to upload that information to share it on the Building Component Library (BCL).
Then, everybody else in the public can also access that information.
It creates a collaborative effort with everybody in the energy modeling community sharing this information. It makes energy modeling easier for everyone.
Let us go back to the home page and go down to this bottom right. It says contribute (to add content to the BCL).
There are four steps in this process. We are going to discuss each step. Step by step.
Let us go to step one. It says organize your data...
One thing to note...in the past, NREL was hosting the BCL on its website.
There was no tracking on the different versions of data that were being input to the library.
They ended up switching over to Github as a version tracker. It tracks the different versions of programs and components that are being uploaded to the library.
You have to get a Github account. Go to Github.com and sign up for an account. It is free.
I have already got an account, so I will just sign in.
It takes you to the home page here when you are already have an account.
I believe when you first set up your account it is going to take you to a profile page. Like this...
That is the first step; create a Github account.
The next step is to create a repository. A repository is like a a big folder where you keep all of your measures or components or programs.
Github is a lot larger than than just the building component library. Github is used for tracking all sorts of different programming code throughout the world.
It is also a collaborative website where programmers can get together and merge their programs with each other to create a much larger program.
Github tracks all kinds of different things such as conflicts between two different programmers or conflicts of programming code with the main code and and that sort of thing.
For our purposes, we just need to create a repository. The appropriate structure for the repository is going to be this right here.
Let us go back to our Github page. Go to the top here, where it says "Repositories" and click it.
We need to create a new repository. I already have one set up, so I am just going to copy the name of this.
We will click "new" to create a new repository. You will only have to create a repository twice.
You will create a repository for measures and you will create a repository for components.
After you are done creating those two repositories, everything is greatly simplified. We will get into that a little bit later...
We will name this as a dash 2. You want to give it a description...Helix Energy Partners BCL components...
We will create a components repository for now and then we will have to create a a measures repository later. Those are the two repositories that you will have to create.
After you are done you do not have to create any more.
We will make this public. You want to add a readme file. This file is so anyone can see the description of this repository.
You can just type in a simple read me about that.
Add git ignore. This is for programmers. This is so that Github can ignore certain file types.
So Github does not have to track everything that is in the program folders.
There are certain file types associated with programming code that are not not necessary for tracking. They might be library files or something that the programming language uses.
All of the OpenStudio measures are programmed using ruby, so we are going to select ruby here.
Then, choose a license. We will select a simple BSD 2 simplified license. Public license. Click "Create Repository".
Now we have our repository created. You can see there is a "readme" here. You can just edit it.
This is where we keep our components that have been uploaded to the BCL.
That is how you edit the readme file.
You can add any additional notes for committing these changes but we will just click "Commit changes".
Let us go back to our main repository folder. From here, we need to add a file.
Specifically, we need to create an xml file and the specified file structure. Go up here to add file, create new file.
To add folders...like I said, we wanted to create this structure here...
To add folders, we will type in "lib". This will be the first folder. Then, you type in a slash to create that folder.
Then "components". Then slash. Then, we are going to call this Australian underscore 9b underscore spaces.
This folder name, according to this, needs to be unique across the whole repository.
So, for each of your components that you are uploading, this folder name and all folders below it should be unique across the whole repository.
So, we have created that folder. Now we need to create a component.xml file.
Going back to the BCL steps to create this...
The the xml file is a directory for each of the the measures and components located in the library.
Let us open this, I am just going to go back to here real quick...
Go to components. We will just select windows...
The xml file has this information in it. The name, the type, the description. It also has a tag on there.
For example windows; that allows the Building Component Library to filter and search for components and measures.
The Building Component Library reads the meta data in the xml file so that it can return relative search results for anyone that is looking for very specific information.
...we have created this component.xml. If you go back to the instructions steps, they allow you to download an example component right here.
Otherwise, you can just browse the BCL and download any one of these components as an example.
We will just download this example component here.
We will open it up...open...you can edit this with any sort of text editor.
We will just copy all of this information in this example xml file and we will go back to our Github component xml file and then just paste it in here.
Then, you want to add the name of this component. We did Australia_9b_Spaces so that is the name of our component.
You want to make sure that every one of these that this snippets of data is nested within a beginning tag and an end tag.
You also have to create a unique identification code for the uid and the version id.
You can just search the web for uuid generator and any one of these...You can just copy the uuid and paste it in here.
We also need to create one for the version, so we will just refresh the page. Copy that uuid and paste this in here for the version.
The display name is going to be this right here, when you are searching the BCL.
For our display name we are going to name it this right here: Australian NCC 2019 Class 9b School-Space types.
The description is going to be this right here. When you are searching the Building Component Library.
We are going to call this...and you want to make sure it is in between those tags...Australian National Construction Code Standard Reference Space Types for K-12 Schools.
...we will just add in "2019" for the year of the code...
Then, a modeler description; any additional information to the energy modeler.
We do not have any very specific information, so we can just put in that same information there.
Tags: this is going to be a whole building. The space types we are going to upload are applicable to a whole building.
When you're searching the BCL, the tags are located over here.
It says "Component Tag". You can search any one of these.
For instance, if you are going to upload a weather file or a type of exterior wall construction.
That is the tag you want to use.
Our example is using "whole building" so we will just leave this whole building tag as it is.
Attributes:...this one is going to be a k-12 school. Some of these attributes are...
Actually all of these attributes are for the legacy version of OpenStudio. They are used for sorting.
I think, nowadays, it is mostly just tags that are used.
But, if you want, you can add some some of these attributes in. They can be useful later if you are going to be doing some programming.
We will just add a few of these in here. Make sure that you insert it in between these. We are just going to copy this here and paste. 
The first attribute we are going to do is country. To see a list of attributes...Let us see...
You can go to the attributes page and do a filter to search by attributes. We will do country.
You can see that the attribute name is country. We put in country here.
Legacy API query string; this is used for programming. The data type is a string.
So, our string is going to be "Australia".
We will add in another attribute: climate zone.
Again search for attributes, just to tag this. It is supposed to make your measures and components a little bit easier to search for on the BCL.
We will use "Climate Zone". It will be used for "All" climate zones in Australia. That is good enough.
Our building type is going to be K-12...oh sorry...we already have climate zone down here...okay. All right.
Finally, files.
The file extension that we are uploading is going to be OpenStudio (.osm). The version identifier of the program is going to be...
Let us open up this our .osm file with a text editor. You can see at the very top; version identifier of the program is going to be this 3.2.1. So, "3.2.1".
The file name is going to be the name of our .osm file. Paste this in here....school space types.osm.
The file type is a .osm file. That concludes our .xml file for this component.
We will just commit the new file. If you want to add additional description in here you can do that. Okay, we have created the .xml file.
The next step is to create a nested folder in here under your component folder called files. 
These are all files attachments that the component.xml references.
Go to "add file" to create a new file. We will create "files"...I believe...
Yeah, so this is the example component we have. The component.xml and then inside that component folder there is another folder called "files".
That is where we are going to place our .osm file. Put a slash to create that folder.
Then, we are going to create our .osm file. We will copy the file name and then type ".osm" to create the .osm file.
Next, go back to the text editor where we opened up the .osm file. Select all. Copy. Paste.
Then just click the "Commit new file" button.
If you want, if you are an advanced programmer, you can create additional branches off of this for doing some program editing and then later on you can merge those branches to this main branch.
We will just create the main branch. Commit new file. That is basically step one for creating your Github repository.
The next step is step two; register your repo with the BCL.
We will expand this. This step is accomplished via the BCL manifest.
It shows a link right here. Open up this link. This takes you to the building component library "BCL manifest" repository.
Number one says to fork this repository. You would go up here to fork...um...if I click it I already have it forked right here...you can see it is already forked.
Just to give you a quick demonstration on what forking is...we will just fork any...we can fork this one.
For example I do not have this one forked yet. Just click "fork" here. It says it is forking that repository.
You can see that it is forked from the building components library and it has created your own repository under your account.
It brought in all of the the information from that that forked repository. That is how you fork a repository.
Let us just delete this...okay.
Go back to our forked repository. The next step is to, in the forked repo, add a section of in the .json file with basic information about your repository. Name, organization type, and url.
Once you have the repository forked it, should bring in this .json file.
Click on it. We need to edit it. Scroll all the way down to the bottom.
You can see that I already have my repository in there, the original one I created.
We will have to add the new one that we just created.
To add your components repository to that manifest, you need to copy the one above.
Make sure you cut/copy from the bottom. In between these two brackets. Up to this comma.
Click in between the brackets and paste. The name of our repository that we just created was this right here. That is the name of the repository.
The organization is your Github account name. We are creating a component repository.
If you are creating a measure repository you would just type in measure there.
The url for that repository is going to be this, right here.
You can commit the changes and add any specific information about what you are changing. We are just updating it, adding our component repository to the BCL manifest.
Click "Commit changes". That changes the BCL manifest on our repository.
In order to change the BCL manifest on the NREL repository, you have to create a "pull request".
Go up to pull requests. Click the "New pull request" button.
It is saying that there are conflicts. The manifest .json file at NREL is different from the one at our repository.
If you scroll down, you can see the changes that we made to that. We added our repository to the manifest.
Click "Create pull request". Title: "an example of how to create a pull request". 
Requestiing to add our repository to the main BCL manifest.
Click "Create pull request".
You will notice that there is a review required. The folks over at BCL will review those changes and then either approve or deny those changes.
So, now we have created a pull request against the original BCL manifest.
The BCL folks will review your your change to the .json file. If acceptable they will merge your request to the main branch.
That is step two.
Let us go to step three. Configure your repo to automatically add new releases to the BCL.
Once your repo has been approved and registered with the BCL manifest, you need to set up web hooks so that the BCL can be automatically notified if you add new content to your repo. 
New components or measures, update those existing components or measures.
If you do some editing on your programs, all of those updates can be automatically added to the Building Component Library.
The instructions say to select web hooks from the left navigation menu on your repo's setting page...
Let us go back to our repository. I have just deleted our example that we did.
I am going to use my original repository as an example from now on.
Go to the repository that we created. This is our components repository. Go up to settings here.
Click "Webhooks". Click the "Add webhook" button. The guide says enter the payload url.
...this BCL2 will need to be updated when the BCL moves...so the BCL is finally moved to its final url. We need to use this one right here.
Click there and paste it in. The content type will be application.json...enable ssl...we need to select individual events.
Let us get rid of "pushes". We will select "releases". Make sure that is set as "active".
Click the "Add webhook" button at the bottom. Okay. We have added our webhook.
The final step...step four; create a release of your repository.
Let us go back here. Click our repository. It will take us back to the code page. Over on the right, you will see a "Create new release" link, here. Click that.
We need to choose a title, tag version, name, and description.
We will do version one. Create a new tag, click that. We will call this "Initial Release". Initial release of the HEPLLC components repository.
If you are doing testing or something, you can do a pre-release but this says that you do not want to check this pre-release box.
If you do check it, then the release will not be added to the BCL. So, we will leave this unchecked.
Click "Publish release" button at the bottom. There you go. We created a release of our repository.
Then, it says the BCL will index your new content. To see the status of your repo, including indexing errors, you can visit the BCL dashboard and click on your repo page.
We can open up this here. We can search for our repository. Here. Right here.
Okay. This is our repository. Content type is "component". We have one release. The latest release version is this.
You can find the link to our repository here. It says our repository is active...it says that the release was successful...
However, it says no content was added in this release. It looks like we have an error on our .xml file. "mismatched tagline 30"
Let us go back to our repository. Let us look at the .xml file.
Line 30, right here. Sometimes it is easier to edit these files in a in a programming editor. Or even something like notepad++.
We will copy the contents of this file and paste into notepad++. Save the file as an .xml file. That way notepad knows what type of file it is. Okay.
Notepad++ is handy because it it can highlight the beginning and ending of snippets of program. You can see that this is the main header; attributes.
This is the first attribute, second attribute, third attribute. It looks like we have some extra data in here. It needs to be deleted.
Let us go back to Github. We will just quickly edit this file.
We see that there is two here. We only need the beginning and ending of that.
We will commit the changes. That edits the file. Now we have to do another release of this repository.
Go to releases. Draft a new release...we want version two; create a new version. Edit AU spaces xml. Fix AU spaces xml. Publish the release here.
Then, we can go back to the Building Component Library repo details.
Let us just refresh this. You can see version 2 was released. It was successful and it was added with one components to the BCL.
So, let us browse the BCL. We will see if it was added in there.
We added a component. The component was a whole building...um well... let us see...we can browse by repo. Here it is.
We have one component added to the BCL. Click it. You can see: there is our component.
Anyone in the world can search for this component on the BCL and they can download it with the download button. They can use it for their energy modeling.
Now that we have our repository set up and it is hooked into the BCL, it is really easy to add additional components to the repository.
And do new releases that get uploaded to the BCL.
Let us go back to our components repository. Go to code. Click add file. Create new file.
You want to place the file in the same location as the other components so...lib/components.
Then, we will create the new folder. For example we are going to create a new window. "new window" folder.
Then, component.xml. Then you would add in all of the metadata just like we did before. Commit new file.
If you want you know the structure for that .xml you can just download this as a sample .xml component.
Then, we need to add our file. Create new file again. Create the files folder. Then "new window.osm".
If you create a new window...for example...we will just create a new OpenStudio file.
Go to constructions, materials. Add glazing window materials...add clear three millimeter.
Construction, let us call it "new window". Let us drag in this clear three millimeter. Save this as our new window file.
Then let us go to the desktop and open the .osm file. Paste it in here. That is our new window file. Commit new file.
Now we have in our components folder Australian spaces and we have created this new window.
It contains the .xml and the supporting files for that .xml is the .osm file.
Finally, you do a new release. Go to releases. Draft a new release. Same thing. Version zero zero...3. Create a new tag. "Add new window"..."added a new window".
Then, you would just publish the release.
So, that is how you set up your repo. Afterwards, it is really easy to just add additional components and measures to the BCL.
Thank you! Please like and subscribe!