This library allows you to quickly and easily use the BuildSimHub Web API v1 via Ruby. This library represents the beginning of the Cloud Simulation function on BuildSimHub. Please browse the rest of this README for further detail. We appreciate your continued support, thank you!
- The BuildSimHub service, starting at the free level
- Ruby version >= 2.2
Simply clone this repository and place in any folder you wish to build your application on. Examples:
After you downloaded the whole package, the first you need to do is to reconfigure your user API in the info.config file. You can find the API key associate with your account under the profile page:
Simple edit the info.config
user_api_key:[YOUR_API_KEY]
The following is the minimum needed code to initiate a regular simulation with the helpers/simulationJob
require_relative 'BuildSimHubAPI/BuildSimHubAPI'
api = BuildSimHubAPI.new
#this key can be found under your project folder
folder_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
newSj = api.newSimulationJob(folder_key)
response = newSj.createModel(file_dir)
#print success means the simulation job has successfully
#started a simulation, if there is an error, then
#you will receive the correspondent error message
print responseThe BuildSimHubAPIClient creates a portal object that manages simulation workflow.
From this object, you can initiate a simulationJob to conduct a cloud simulation. Call createModel() method with parameters can start the cloud simulation.
require_relative 'BuildSimHubAPI/BuildSimHubAPI'
api = BuildSimHubAPI.new
#this key can be found under your project folder
folder_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
newSj = api.newSimulationJob(folder_key)
response = newSj.createModel(file_dir)
######BELOW ARE THE CODE TO TRACK SIMULATION#########
if(response == 'success')
while newSj.trackSimulation do
print newSj.getTrackStatus
sleep 10
end
endAs mentioned previously, BuildSimHubAPIClient manages the entire workflow of the simulation. So once a cloud simulation is successfully started by the SimulationJob class, you can simply call trackSimulation() function to receive the simulation progress.
require_relative 'BuildSimHubAPI/BuildSimHubAPI'
api = BuildSimHubAPI.new
#this key can be found under your project folder
folder_key="0ade3a46-4d07-4b99-907f-0cfeece321072"
#absolute directory to the energyplus model
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.idf"
newSj = api.newSimulationJob(folder_key)
response = newSj.createModel(file_dir)
######BELOW ARE THE CODE TO TRACK SIMULATION#########
if(response == 'success')
while newSj.trackSimulation do
print newSj.getTrackStatus
sleep 10
end
response = newSj.getSimulationResult("err")
else
print response
endIf the Job is completed, you can get results by calling getSimulationResults(type) function.
#Object and Functions
The easiest way to generate a SimulationJob class is calling the newSimulationJob() method in the BuildSimHubAPIClient.
Nevertheless, you have to provide a folder_key in order to create a new SimulationJob instance.
The folder_key can be found under each folder of your project
SimulationType class helps you configure the cloud simulation. There are two simulation types: regular and fast. Also, ou can increase the number of agent by calling the increaseAgents() function.
simulationType = bsh.getSimulationType
numOfAgents = simulationType.increaseAgents;
print numOfAgentsIt should be noted that the maximum number of agents working on one simulation job is limited to 12, and the more agents you assigned to one simulation job, the faster your simulation can be. You can also call resetAgent() function to reset the number of agent to 2.
A simulation job manages one type of cloud simulation. It contains three main functions which are listed below:
The createModel() function has in total 4 parameters.
file_dir(required): the absolute local directory of your EnergyPlus / OpenStudio model (e.g., "/Users/weilixu/Desktop/5ZoneAirCooled.idf")comment(optional): The description of the model version that will be uploaded to your folder. The default message isUpload through Ruby APIsimulationType(optional): The simulation Type should be generated from SimulationType class. This class manages the simulation type as well as how many agents you want to assign to this simulation job. Default isregularsimulation which uses 1 agent to do the cloud simulation.agent(optional): The agent number is a property of SimulationType class. If fast simulation is selected, then the default of agent will be 2.
This method returns two types of information:
If sucess: success
or error message states what was wrong in your request.
The trackSimulation() function does not require any parameters. However, it is required that a successful cloud simulation is created and running on the cloud. Otherwise, you will receive this message by calling this function:
No simulation is running or completed in this Job - please start simulation using createModel method.
If there is a simulation running on the cloud for this simulationJob, then, this function will return true and you can retrieve the simulation status by get the class parameter trackStatus. Example code is below:
if(newSimulationJob.trackSimulation):
print newSimulationJob.trackStatusThe getSimulationResults(type) function requires 1 parameter, the result type. Currently, you can retrieve three types of results: the error file (err), eso file (eso) and html file (html), generated from EnergyPlus simulation.
response = newSimulationJob.getSimulationResults('err')
print response- Certainly, the first thing is to get the project into GEM.
- We are also working on an HTML compiler, which let users to retrieve any values from the html output
- If you are interested in the future direction of this project, please take a look at our open issues and pull requests. We would love to hear your feedback.
buildsimhub-ruby is guided and supported by the BuildSimHub Developer Experience Team.
buildsimhub-ruby is maintained and funded by the BuildSimHub, Inc. The names and logos for buildsimhub-ruby are trademarks of BuildSimHub, Inc.