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 too many different simulation result files: .err, .eso, .html and .rdd, etc.

How to quickly identify key results from so many files? That is the goal of the 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. You do not need a successful simulation to use this function.

idf = results.download_model()
print(idf)

- class_template(class_label)

This function extracts the class template from the IDD for reference when modifying a model. The class_label is the EnergyPlus class name such as Lights or buildingsurface:detailed. This field is case insensitive. You do not need a successful simulation to use this function.

field_list = results.class_template('Lights')
for field in field_list:
    print(field)

"""Output
{'field_name': 'Name', 'field_type': 'alpha'}
{'field_name': 'Zone or ZoneList Name', 'field_type': 'object-list', 'field_link': ['thermal zone 43', 'thermal zone 44', 'thermal zone 41', ...]}
{'field_name': 'Schedule Name', 'field_type': 'object-list', 'field_link': ['always 1_bas', 'large office activity', 'large office bldg occ', 'on_bas', 'large office infil quarter on', 'large office bldg light', 'large office clgsetp', 'small office bldg occ', 'office infil quarter on', 'small office infil quarter on', 'small office clgsetp', 'always on discrete', 'large office bldg equip', 'office work occ', 'office activity', 'office misc occ', 'off_bas', 'medium office bldg occ', 'medium office clgsetp', 'small office bldg equip', 'small office activity', 'always on continuous', 'large office htgsetp', 'office bldg light', 'medium office htgsetp', 'office bldg equip', 'always off discrete', 'medium office infil quarter on', 'small office htgsetp', 'medium office activity', 'medium office bldg equip']}
...
"""

- get_design_day_condition()

This function is used to check the design day condition set for the model. You do not need a successful simulation to use this function

date = results.get_design_day_condition()
print(date['cooling'])
"""Output
!- Generated by BuildSimHub
SizingPeriod:DesignDay,
    ALLEGHENY CO 1%,
    7,
    21,
    SummerDesignDay,
    30.8,
    9.8,
    DefaultMultipliers,
    ,
    Wetbulb,
    21.8,
    ,
    ,
    ,
    ,
    96750.0,
    4.3,
    240,
    No,
    No,
    No,
    ASHRAETau,
    ,
    ,
    0.44,
    2.116,
    0.00;
"""

- zone_list()

This function extracts the list of zones and their info. This function does not require a successful simulation.

model = bsh.model_results(project_api_key, model_api_key)
data = model.zone_list()
print(pd.DataFrame(data).to_string())

"""Output
   conditioned  floor     zone_cool zone_exhaust     zone_heat           zone_name     zone_vent
0          Yes      1  PACU_VAV_bot               PACU_VAV_bot         Core_bottom  PACU_VAV_bot
1          Yes      1  PACU_VAV_bot               PACU_VAV_bot  Perimeter_bot_ZN_4  PACU_VAV_bot
2          Yes      1  PACU_VAV_bot               PACU_VAV_bot  Perimeter_bot_ZN_3  PACU_VAV_bot
3          Yes      1  PACU_VAV_bot               PACU_VAV_bot  Perimeter_bot_ZN_2  PACU_VAV_bot
4          Yes      1  PACU_VAV_bot               PACU_VAV_bot  Perimeter_bot_ZN_1  PACU_VAV_bot
...
"""

zone_info(zone_name)

This function extracts detail information about a zone. This function requires to use when a simulation completed.

model = bsh.model_results(project_api_key, model_api_key)
data = model.zone_info('Core_bottom')
print(data)

"""Output
{'zone_name': 'Core_bottom', 'zone_area': '983.5365718200003', 'zone_ppl': '52.938665381982624', 'zone_lpd': '590.1219430920002', 'zone_epd': '40370.84590989011', 'zone_heat': 'PACU_VAV_bot', 'zone_cool': 'PACU_VAV_bot', 'zone_vent': 'PACU_VAV_bot', 'zone_exhaust': ''}
"""

get_class(class_label, class_name=None)

This method allows the user to retrieve the data under a class in EnergyPlus file. Specify the class_label to identify the class in the model. If the class name is specified, then correspondent class will be retrieved. This function does not require a successful simulation is completed.

model = bsh.model_results(project_api_key, model_api_key)
data = model.get_class('Lights','Core_bottom_Lights')
print(data)
"""Output
[{'label': 'Lights', 'Name': 'Core_bottom_Lights', 'Zone or ZoneList Name': 'Core_bottom', 'Schedule Name': 'BLDG_LIGHT_SCH', 'Design Level Calculation Method': 'Watts/Area', 'Lighting Level': '', 'Watts per Zone Floor Area': '0.6', 'Watts per Person': '', 'Return Air Fraction': '0.0000', 'Fraction Radiant': '0.7000', 'Fraction Visible': '0.2000', 'Fraction Replaceable': '1.0000', 'End-Use Subcategory': 'General Lights', 'Return Air Fraction Calculated from Plenum Temperature': 'No'}]
"""