Getting_Started

Getting Started with the BuildSim Cloud

Get your BuildSim Cloud account

Before using the API, you need to get a BuildSim Cloud account. You can register the account in the registration page. The registration is free for any level of users.

Onboard process

Once you completed your registration, you will see a default demo project created in your account. You can freely upload your models, view models geometry and do model comparisons - any types of model management and measure implementations can be performed under this project. However, since you have almost no simulation hours, you cannot do cloud simulation and the result analysis - including the most popular dashboard function.

To claim free credits, you need to complete the onboarding process, which consists of three steps.

1. View the baseline model geometry: In the demo project, there is a baseline model to help you start. You can easily find the model, can click the "View Geometry" button at the top of the project page. Complete this action will give you 30 min simulation credit.
2. Run simulation on the baseline model: Next, with the 15 minutes simulation credit, you can run a simulation with the baseline model and get another 30 min credit.
3. Lastly, with a simulated model, you can then proceed to view the design dashboard! Complete this step, you are finally graduated from the onboarding process and acquire another 15 minutes credit!

With the credits, you can start exploring more functions on the BuildSim Cloud. But before that, you need to understand how BuildSim Cloud manages its model system.

Understand BuildSim Cloud model structure

On BuildSim Cloud, the structure is arranged as:

Understand the three levels: Project - Model - Model history / parametric model, is critical to understand the use of this library. Each level can be connected with its unique key:

1. Project API key: This key links to the project, and it is also the required parameter to activate the BuildSimHubAPI object. Example: project_api_key = 'f98aadb3-254f-428d-a321-82a6e4b9424c'
2. Model API key: This key is essential to access a model or a parametric study. Example: model_api_key = '60952acf-bde2-44fa-9883-a0a78bf9eb56'
3. Track token: This key is used to reference specifc commit to the model. A commit can be revision, update or even parametric measures. Example: track_token = '111-111-111'

Project

First of all, we need to create a project on BuildSim Cloud through BuildSimHub platform. There are two ways to retrieve the project API key:

1. In Project page:
2. In Project Landing page:

Model

Once there is a project_api_key, user can either get the list of the models from the Web interface or through API:

import BuildSimHubAPI as bsh_api
import pandas as pd
#example
project_api_key = 'f98aadb3-254f-428d-82a6e4b9424c'
bsh = bsh_api.BuildSimHubAPIClient()

# extract the project list
project_model_list = bsh.project_model_list(project_api_key)
"""
project_model_list = 
[{'branch_name': '5zoneaircooled_uniformloading.epjson', 'branch_id': 146, 'branch_type': 'idf',  
'branch_description': '5zoneaircooled_uniformloading.epjson parametric',  
'api_key': '1471ba46-2af4-e62d64900e35','last_modified_time': '2018-06-20 14:52:24'},  
{'branch_name': 'Python API', 'branch_id': 145, 'branch_type': 'idf',  
'branch_description': 'Python API', 'api_key': '388a62f2-123f-5aa67dd8e154',  
'last_modified_time': '2018-06-20 14:07:07'}]
"""
# use pandas to process the data

df = pd.DataFrame(project_model_list)
print(df[['branch_name','api_key']])
"""
  branch_name             api_key
0 5zoneaircooled.epjson   1471ba46-2af4-e62d64900e35  
1 Python API              388a62f2-123f-5aa67dd8e154  
"""

This is the hello world version of BuildSim Cloud. With this data, you can start fully explore the BuildSim Cloud! One of the key data every user should pay attention to is the api_key. This is the key that points your application to the second-level structure, the Model:

import BuildSimHubAPI as bsh_api
import pandas as pd
#example
project_api_key = 'f98aadb3-254f-428d-82a6e4b9424c'
model_api_key = '1471ba46-2af4-e62d64900e35'
bsh = bsh_api.BuildSimHubAPIClient()
model_list = bsh.model_list(project_api_key, model_api_key)
"""
[{'commit_msg': 'WWR: 0.4, LPD: 0.9, HeatingEff: 0.86', 'commit_date': '2018-06-20', 'commit_id': '1-146-429'},  
{'commit_msg': 'WWR: 0.4, LPD: 0.9, HeatingEff: 0.8', 'commit_date': '2018-06-20', 'commit_id': '1-146-428'}]
"""
df = pd.DataFrame(data_list)  
"""
   commit_msg                            commit_id
0  WWR: 0.4, LPD: 0.9, HeatingEff: 0.86  1-146-429  
1  WWR: 0.4, LPD: 0.9, HeatingEff: 0.8   1-146-428
"""

With the commit_id, we can retrieve data from this specific model hisotry or parametric model. That's it! Now let's explore how to start a simulation