Getting_Started

Getting Started with the BuildSim Cloud

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 a past history of the model or one parametric model. 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