Simulation_Results

Simulation Results

• Result Class
• Functions
  • Basic Info
  • Bldg Level Simulation Results
  • Bldg Level Derived Results
  • Zone Load
  • Hourly Data
  • HTML Table
  • Other Functions

After a successful simulation, we then are facing to many different simulation results files: .err, .eso, .html and .rdd, etc.

How to quickly identify key results from so many files? That is the goal of Simulation Results class.

Result class

Result class is the gateway to connect with a model's information and simulation results. There are two methods to get a model's result class:

1. Return from the simulation method

import BuildSimHubAPI as bsh_api

project_api_key = "7e140eec-b37f-4213-88b5f96c0065"
file_dir = "/Users/weilixu/Desktop/5ZoneAirCooled.epJSON"
wea_dir = "/Users/weilixu/Desktop/data/jsontest/in.epw"

# initialize the client
bsh = bsh_api.BuildSimHubAPIClient()
new_sj_run = bsh.new_simulation_job(project_api_key)
results = new_sj_run.run(file_dir, wea_dir, track=True)
if results:
    print(str(results.net_site_eui()) + " " + results.last_parameter_unit)

"""Output
32.1 kBtu/ft2
"""

2. Retrieve a model results

import BuildSimHubAPI as bsh_api

project_api_key = "7e140eec-b37f-4213-8640-88b5f96c0065"
model_api_key = "96d21c84-d17f-41a2-1d09ca43736e"

# initialize the client
bsh = bsh_api.BuildSimHubAPIClient()
results = bsh.model_results(project_api_key, model_api_key)
if results:
    print(str(results.net_site_eui()) + " " + results.last_parameter_unit)

"""Output
32.1 kBtu/ft2
"""

Functions

Building Basic Information

---

This group of functions extract information directly from the energy model. Therefore, no simulation is required.

- bldg_geo()

This function opens local default browser to view the model's 3D geometry.

# if success the 3D viewer will be opened in the default web browser
results.bldg_geo()

- bldg_orientation()

print(str(results.bldg_orientation()))
# Output: 30

- num_above_ground_floor()

Number of floors above the ground. This function extract floor information based on the floor height.

print(str(results.num_above_ground_floor()))
# Output: 3

- num_total_floor()

Number of total floors, including basements and above ground floors.

print(str(results.num_total_floor()))
# Output: 4

- num_zones()

Number of zones, including conditioned, semi-conditioned and unconditioned zones.

print(str(results.num_zones()))
# Output: 12

- num_condition_zones()

Number of conditioned zones, including conditioned, semi-conditioned zones.

print(str(results.num_condition_zones()))
# Output: 15

- condition_floor_area(unit)

The total floor area for conditioned zones.

print(str(results.condition_floor_area('si')) + results.last_parameter_unit)
# Output: 143.2 m2
print(str(results.condition_floor_area('ip')) + results.last_parameter_unit)
# Output: 1541.4 ft2

- gross_floor_area(unit)

The total floor area

print(str(results.gross_floor_area('si')) + results.last_parameter_unit)
# Output: 143.2 m2
print(str(results.gross_floor_area('ip')) + results.last_parameter_unit)
# Output: 1541.4 ft2

- window_wall_ratio()

The overall window to wall ratio.

print(str(results.window_wall_ratio()))
# Output: 0.23

Bldg Level Simulation Results

---

This group of functions extract building level simulation results for quick reviews. A sucessful simulation is required to use all the functions.

- net_site_eui()

Net site energy use intensity - the unit follows the simulation unit setting.

print(str(results.net_site_eui()))
print(results.last_parameter_unit)
#Output: 32.1
# kBtu/ft2

- total_site_eui()

print(str(results.total_site_eui()))
print(results.last_parameter_unit)
#Output: 32.1
# kBtu/ft2

- not_met_hour_cooling()

print(str(results.not_met_hour_cooling()) + " " + results.last_parameter_unit)
#Output: 22 hr

- not_met_hour_heating()

print(str(results.not_met_hour_heating()) + " " + results.last_parameter_unit)
#Output: 0 hr

- total_end_use_electricity()

print(str(results.total_end_use_electricity()) + " " + results.last_parameter_unit)
#Output: 1725.33 GJ

- total_end_use_naturalgas()

print(str(results.total_end_use_naturalgas()) + " " + results.last_parameter_unit)
#Output: 338.05 GJ

- cooling_electricity()

print(str(results.cooling_electricity()) + " " + results.last_parameter_unit)
#Output: 236.73 GJ

- cooling_naturalgas()

print(str(results.cooling_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- domestic_hotwater_electricity()

print(str(results.domestic_hotwater_electricity()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- domestic_hotwater_naturalgas()

print(str(results.domestic_hotwater_naturalgas()) + " " + results.last_parameter_unit)
#Output: 79.87 GJ

- exterior_equipment_electricity()

print(str(results.exterior_equipment_electricity()) + " " + results.last_parameter_unit)
#Output: 18.87 GJ

- exterior_equipment_naturalgas()

print(str(results.exterior_equipment_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- exterior_lighting_electricity()

print(str(results.exterior_lighting_electricity()) + " " + results.last_parameter_unit)
#Output: 103.91 GJ

- exterior_lighting_naturalgas()

print(str(results.exterior_lighting_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- fan_electricity()

print(str(results.fan_electricity()) + " " + results.last_parameter_unit)
#Output: 83.51 GJ

- fan_naturalgas()

print(str(results.fan_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- heating_electricity()

print(str(results.heating_electricity()) + " " + results.last_parameter_unit)
#Output: 144.46 GJ

- heating_naturalgas()

print(str(results.heating_naturalgas()) + " " + results.last_parameter_unit)
#Output: 258.18 GJ

- heat_rejection_electricity()

print(str(results.heat_rejection_electricity()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- heat_rejection_naturalgas()

print(str(results.heat_rejection_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- interior_equipment_electricity()

print(str(results.interior_equipment_electricity()) + " " + results.last_parameter_unit)
#Output: 806.67 GJ

- interior_equipment_naturalgas()

print(str(results.interior_equipment_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- interior_lighting_electricity()

print(str(results.interior_lighting_electricity()) + " " + results.last_parameter_unit)
#Output: 331.16 GJ

- interior_lighting_naturalgas()

print(str(results.interior_lighting_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

- pumps_electricity()

print(str(results.pumps_electricity()) + " " + results.last_parameter_unit)
#Output: 0.02 GJ

- pumps_naturalgas()

print(str(results.pumps_naturalgas()) + " " + results.last_parameter_unit)
#Output: 0.0 GJ

Bldg Level Derived Results

---

This group of functions derives the building level result data from the simulation results and energy model

- bldg_lpd()

Building lighting power density is extracted from Zone Summary table in the HTML.

print(str(results.bldg_lpd()) + " " + results.last_parameter_unit)
#Output: 6.7 W/m2

- bldg_epd()

Building equipment power density is extracted from Zone Summary table in the HTML.

print(str(results.bldg_epd()) + " " + results.last_parameter_unit)
#Output: 10.7 W/m2

- bldg_ppl()

Building people is extracted from Zone Summary table in the HTML.

print(str(results.bldg_lpd()) + " " + results.last_parameter_unit)
#Output: 18.58 m2 per person

- wall_rvalue()

Average wall R value

print(str(results.wall_rvalue()) + " " + results.last_parameter_unit)
#Output: 2.3 m2/W-K

- roof_rvalue()

Average roof R value

print(str(results.roof_rvalue()) + " " + results.last_parameter_unit)
#Output: 4.3 m2/W-K

- window_uvalue()

Average window u value

print(str(results.window_uvalue()) + " " + results.last_parameter_unit)
#Output: 1.76 W/m2-K

- window_shgc()

Average window SHGC value

print(str(results.window_uvalue()) + " " + results.last_parameter_unit)
#Output: 0.38

- roof_absorption()

Average roof absorption value

print(str(results.roof_absorption()))
#Output: 0.3

- bldg_infiltration()

Design building infiltration - this method can only extract the value from DesignFlowRate object.

print(str(results.bldg_infiltration()) + " " + results.last_parameter_unit)
#Output: 0.0005351577070933334 m3/s-m2

- bldg_water_heater_efficiency()

Average water heater efficiency.

print(str(results.bldg_infiltration()))
#Output: 0.88

- bldg_dx_cooling_efficiency()

Average cooling DX coil efficiency

print(str(results.bldg_dx_cooling_efficiency()))
#Output: 3.2

- bldg_chiller_efficiency()

Average chiller efficiency

print(str(results.bldg_chiller_efficiency()))
#Output: 5.0

- bldg_electric_boiler_efficiency()

Average electric boilers efficiency

print(str(results.bldg_electric_boiler_efficiency()))
#Output: 0.98

- bldg_fuel_boiler_efficiency()

Average natural gas boilers efficiency

print(str(results.bldg_fuel_boiler_efficiency()))
#Output: 0.88

- bldg_dx_heating_efficiency()

Average heaing DX coils efficiency

print(str(results.bldg_dx_heating_efficiency()))
#Output: 3.6

Zone Load

---

Zone load is one of the complex data type which is difficult to be extracted as a single value. First, let's extract zone level load data:

zone_load_data = results.zone_load()
print(zone_load_data)
"""Output: [{'zone_name': 'Perimeter_mid_ZN_1', 
'heating_unit': 'W', 'cooling_unit': 'W', 
'heating_load': -12441.170000000002, 
'cooling_load': 26048.420000000002, 
'heating_load_density': -60.00371370695477,
'cooling_load_density': 125.63142664223017,
'heating_load_density_unit': 'W/m2',
'cooling_load_density_unit': 'W/m2',
'cooling_peak_load_time': '7/21 13:30:00',
'heating_peak_load_time': '1/21 09:00:00'},...]"""

This returned zone load data is arranged in list > dict structure. This structure can be directly imported into pandas:

import pandas as pd
df = pd.DataFrame(zone_load_data)
print(df)
"""Output:
   cooling_load         ...                   zone_name
0       26048.42         ...          Perimeter_mid_ZN_1
1       71485.30         ...                 Core_bottom
2       51590.58         ...                    Core_mid
"""

Zone load components

Zone load components can be extracted use the same function

zone_load_data = results.zone_load('Core_mid')
print(zone_load_data)
"""Output: [{'zone_name': 'CORE_TOP', 'floor_area': 983.54, 'floor_area_unit': 'm2', 'data': {'cooling_unit': 'W', 'cooling': [{'load_component': 'People', 'Sensible - Instant': 2577.0, 'Sensible - Delayed': 4715.54, 'Sensible - Return Air': 0.0, 'Latent': 2671.21, 'Total': 9963.75, '%Grand Total': 27.61, 'Related Area': 983.54, 'Total per Area': 10.13},..."""

The returned data is more complicated than the regular data format. However, there is a post processing package inside the API library that helps to process this data:

import BuildSimHubAPI.postprocess as pp

one_zone_load = pp.OneZoneLoad(zone_load_data)
print(one_zone_load.heating_load_component_detail())
"""Output:
         Latent          ...            Sensible - Return Air
People    0.0             ...            0.0
Lights    0.0             ...            0.0
Equipment 0.0          ...               0.0
Refrigeration 0.0          ...           0.0
...
"""
print(one_zone_load.cooling_load_component_detial())
"""Output:
         Latent          ...            Sensible - Return Air
People    2671.21             ...        0.0
Lights    0.0             ...            0.0
Equipment 0.0          ...               0.0
Refrigeration 0.0          ...           0.0
...
"""

More information about the post-process module can refer to BuildSim Plot project.

Hourly Data

---

BuildSim Cloud also allows hourly data extraction. However, user has to define Output:variable and Output:meter classes in the energy model to make this function available.

hourly_data()

This function can be used to extract the list of hourly data:

# get the list of hourly variables  
variable_list = results.hourly_data()  
print(variable_list)
"""Output
['Heating Coil Heating Rate:SPACE1-1 ZONE COIL', 
'Pump Mass Flow Rate:HW CIRC PUMP', 
'Cooling Coil Total Cooling Rate:MAIN COOLING COIL 1', 
'Heating Coil Heating Rate:SPACE2-1 ZONE COIL', 
'Zone Air Temperature:SPACE1-1', 
'Zone Air System Sensible Cooling Rate:PLENUM-1', 
'Cooling Coil Sensible Cooling Rate:MAIN COOLING COIL 1', 
'Heating Coil Heating Rate:MAIN HEATING COIL 1',..]
"""

Use the element inside the variable_list to retrieve the detail hourly data:

variable_data = results.hourly_data('Heating Coil Heating Rate:SPACE1-1 ZONE COIL')
print(variable_data)
"""Output
{'resolution': 'Hourly', 'category': 'Value', 'unit': 'W', 
'data': [{'timestamp': '1/1/2018 01:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 02:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 03:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 04:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 05:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 06:00:00', 'value': '0.0'}, 
{'timestamp': '1/1/2018 07:00:00', 'value': '6082.601062715245'},... 
"""

This gives the detail hourly data in JSON format. However, there is a post processing package inside the API library that helps to process this data:

import BuildSimHubAPI.postprocess as pp
hourly_plot = pp.HourlyPlot(variable_data, 
'Heating Coil Heating Rate:SPACE1-1 ZONE COIL')
"""Output:
      Heating Coil Heating Rate:SPACE1-1 ZONE COIL timestamp
0                                         0.000000 2018-01-01 00:00:00
1                                         0.000000 2018-01-01 01:00:00
2                                         0.000000 2018-01-01 02:00:00
3                                         0.000000 2018-01-01 03:00:00
4                                         0.000000 2018-01-01 04:00:00
5                                         0.000000 2018-01-01 05:00:00
6                                      6082.601063 2018-01-01 06:00:00
7                                      4182.091393 2018-01-01 07:00:00
8                                      2163.459871 2018-01-01 08:00:00
9                                       948.128469 2018-01-01 09:00:00
"""

More information about the post-process module can refer to BuildSim Plot project.

HTML Table

Any HTML Tables can be extracted from the BuildSim Cloud through API function.

html_table(report, table, report_for='EntireFacility')

The function takes in three parameters

1. report: The report name - e.g.: Annual Building Utility Performance Summary
2. table: The table name -e.g.: Site and Source Energy
3. report_for: This is an optional parameter. Most of the report is for the Entire Facility.

table_data = results.html_table('Annual Building Utility Performance Summary', 'End Uses')
print(table_data)
"""Output
{'data': {'array': [{'unit': 'GJ', 'col': 'Electricity', 
'row': 'Heating', 'value': '144.46'}, 
{'unit': 'GJ', 'col': 'Electricity', 
'row': 'Cooling', 'value': '236.73'},...
"""

The returned data is in JSON format. There is a post-process function available to convert this data into pandas dataframe:

table_data = results.html_table('Annual Building Utility Performance Summary', 'End Uses')

import pandas as pd
data = pp.HTMLTable(table_data)  
df = data.pandas_df()
"""Output
                         Electricity  Natural Gas   ...    District Heating   Water
Cooling                  236.73         0.00   ...                 0.0    0.00
Exterior Equipment        18.87         0.00   ...                 0.0    0.00
Exterior Lighting        103.91         0.00   ...                 0.0    0.00
Fans                      83.51         0.00   ...                 0.0    0.00
Generators                 0.00         0.00   ...                 0.0    0.00
"""

More information about the post-process module can refer to BuildSim Plot project.

Other Functions

---

- get_simulation_results(result_type="html", accept='file')

This function allows user to extract result files including .html, .err, .eso,.eio, .rdd.

html = results.get_simulation_results('html')
print(html)

- download_model()

This function helps user to download the .idf, osm files.

idf = results.download_model()
print(idf)