Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Create a custom simulation output object by plugging in one or more names of EnergyPlus simulation ouputs. The resulting object can be used to request output variables from EnergyPlus.
base_sim_output
An optional simulation output object to serve as the starting point for the sim_output object returned by this component. All of the output names will simply be appended to this initial starting object.
output_names
A list of EnergyPlus output names as strings (eg. 'Surface Window System Solar Transmittance'. These outputs will be requested from the simulation.
report_frequency
Text for the frequency at which the outputs are reported. Default: 'Hourly'. Choose from the following:
summary_reports
An optional list of EnergyPlus summary report names as strings. If None, only the 'AllSummary' report will be requested from the simulation and will appear in the HTML report output by EnergyPlus. See the Input Output Reference SummaryReports section for a full list of all reports that can be requested. https://bigladdersoftware.com/ epx/docs/9-1/input-output-reference/output-table-summaryreports.html
unmet_setpt_tol
A number in degrees Celsius for the difference that the zone conditions must be from the thermostat setpoint in order for the setpoint to be considered unmet. This will affect how unmet hours are reported in the output. ASHRAE 90.1 uses a tolerance of 1.11C, which is equivalent to 1.8F. (Default: 1.11C).
report
Report!
sim_output
A SimulationOutput object that can be connected to the "HB Simulation Parameter" component in order to specify which types of outputs should be written from EnergyPlus.
Write a honeybee Model to an OSM file (OpenStudio Model), which can then be translated to an IDF file and then run through EnergyPlus.
model [Required]
A honeybee model object possessing all geometry and corresponding energy simulation properties.
epw_file [Required]
Path to an .epw file on this computer as a text string.
sim_par
A honeybee Energy SimulationParameter object that describes all of the setting for the simulation. If None, some default simulation parameters will automatically be used.
measures
An optional list of measures to apply to the OpenStudio model upon export. Use the "HB Load Measure" component to load a measure into Grasshopper and assign input arguments. Measures can be downloaded from the NREL Building Components Library (BCL) at
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The input here should be complete EnergyPlus objects as a single string following the IDF format. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
folder
An optional folder on this computer, into which the IDF and result files will be written.
write [Required]
Set to "True" to write out the honeybee jsons (containing the Honeybee Model and Simulation Parameters) and write the OpenStudio Workflow (.osw) file with instructions for executing the simulation.
run
Set to "True" to translate the Honeybee jsons to an OpenStudio Model (.osm) and EnergyPlus Input Data File (.idf) and then simulate the .idf in EnergyPlus. This will ensure that all result files appear in their respective outputs from this component. This input can also be the integer "2", which will only translate the honeybee jsons to an osm and idf format without running the model through EnergyPlus. It can also be the integer "3", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
jsons
The file paths to the honeybee JSON files that describe the Model and SimulationParameter. These will be translated to an OpenStudio model.
osw
File path to the OpenStudio Workflow JSON on this machine. This workflow is executed using the OpenStudio command line interface (CLI) and it includes measures to translate the Honeybee model JSON as well as any other connected measures_.
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the EnergyPlus Input Data File (IDF) that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on this computer. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the "HB Read Result Dictionary" component to see what outputs can be requested.
html
The HTML file path containing all requested Summary Reports.
Create simulation controls with instructions for which types of EnergyPlus calculations to run.
do_zone_sizing
Boolean for whether the zone sizing calculation should be run. Default: True.
do_system_sizing
Boolean for whether the system sizing calculation should be run. Default: True.
do_plant_sizing
Boolean for whether the plant sizing calculation should be run. Default: True.
for_sizing_period
Boolean for whether the simulation should be run for the sizing periods. Default: False.
for_run_period
Boolean for whether the simulation should be run for the run periods. Default: True.
sim_control
A SimulationControl object that can be connected to the "HB Simulation Parameter" component in order to specify which types of EnergyPlus calculations to run.
Execute an OpenStudio workflow (.osw) and run the resulting IDF file through EnergyPlus.
osw [Required]
Path to an OSW file as a text string. This can also be a list of OSW files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected OSW file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
translate [Required]
Set to "True" to execute the input OSWs using the OpenStudio command line interface (CLI). This will translate any honeybee jsons referenced in the osw to an osm and idf file.
run
Set to "True" to run the resulting IDF through EnergyPlus.
This input can also be the integer "2", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the IDF file that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on your machine. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and run_ is set to True.
Create parameters with criteria for sizing the heating and cooling system.
ddy_file
An optional path to a .ddy file on your system, which contains information about the design days used to size the hvac system. If None, honeybee will look for a .ddy file next to the .epw and extract all 99.6% and 0.4% design days.
filter_ddays
Boolean to note whether the design days in the ddy_file_ should be filtered to only include 99.6% and 0.4% design days. If None or False, all design days in the ddy_file_ will be incorporated into the sizing parameters. This can also be the integer 2 to filter for 99.0% and 1.0% design days.
heating_fac
A number that will get multiplied by the peak heating load for each zone in the model in order to size the heating system for the model. Must be greater than 0. (Default: 1.25).
cooling_fac
A number that will get multiplied by the peak cooling load for each zone in the model in order to size the cooling system for the model. Must be greater than 0. (Default: 1.15).
eff_standard
Text to specify the efficiency standard, which will automatically set the efficiencies of all HVAC equipment when provided. Note that providing a standard here will cause the OpenStudio translation process to perform an additional sizing calculation with EnergyPlus, which is needed since the default efficiencies of equipment vary dependingon their size. THIS WILL SIGNIFICANTLY INCREASE TRANSLATION TIME TO OPENSTUDIO. However, it is often worthwhile when the goal is to match the HVAC specification with a particular standard. The "HB Building Vintages" component has a full list of supported HVAC efficiency standards. You can also choose from the following.
climate_zone
Text indicating the ASHRAE climate zone to be used with the efficiency_standard. When unspecified, the climate zone will be inferred from the design days. This input can be a single integer (in which case it is interpreted as A) or it can include the A, B, or C qualifier (eg. 3C). Typically, the "LB Import STAT" component can yield the climate zone for a particular location.
bldg_type
Text for the building type to be used in the efficiency_standard. If the type is not recognized or is None, it will be assumed that the building is a generic NonResidential. The following have meaning for the standard.
sizing
Parameters with criteria for sizing the heating and cooling system. These can be connected to the "HB Simulation Parameter" component in order to specify settings for the EnergyPlus simulation.
Translate a fully-simualte-able OpenStudio model (.osm) to an IDF and run the it through EnergyPlus.
osm [Required]
Path to an OpenStudio Model (OSM) file as a text string. This can also be a list of OSM files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected OSM file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
translate [Required]
Set to "True" to translate the OSM files to IDFs using the OpenStudio command line interface (CLI).
run
Set to "True" to run the resulting IDF through EnergyPlus.
This input can also be the integer "2", which will run the whole translation and simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
idf
The file path of the IDF file that has been generated on this computer.
sql
The file path of the SQL result file that has been generated on your machine. This will be None unless run_ is set to True.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days. This will be None unless run_ is set to True.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and run_ is set to True.
Create a simulation output object by selecting sets of commonly-requested output variables. The resulting object can be used to request output variables from EnergyPlus.
zone_energy_use
Set to True to add outputs for zone energy use when ideal air systems are assigned. This includes, ideal air heating + cooling, lighting, electric + gas equipment, and fan electric energy.
system_energy_use
Set to True to add outputs for HVAC energy use from detailed systems. This includes outputs for different pieces of HVAC equipment, which together catch all energy-consuming parts of a system. (eg. chillers, boilers, coils, humidifiers, fans, pumps). It also includes the energy use of components of Service Hot Water (SHW) systems as well as any electricity generated on site, such at that coming from photovoltaics.
gains_and_losses
Set to True to Add outputs for zone gains and losses. This includes such as people gains, solar gains, infiltration losses/gains, and ventilation losses/gains.
comfort_metrics
Set to True to add outputs for zone thermal comfort analysis. This includes air temperature, mean radiant temperature, relative humidity, and unmet setpoint time.
surface_temperature
Set to True to add outputs for indoor and outdoor surface temperature.
surface_energy_flow
Set to True to add outputs for energy flow across all surfaces.
load_type
An optional text value to set the type of load outputs requested. Default - 'All'. Choose from the following:
report_frequency
Text for the frequency at which the outputs are reported. Default: 'Hourly'. Choose from the following:
report
Report!
sim_output
A SimulationOutput object that can be connected to the "HB Simulation Parameter" component in order to specify which types of outputs should be written from EnergyPlus.
Run an IDF file through EnergyPlus.
idf [Required]
Path to an IDF file as a text string. This can also be a list of IDF files.
epw_file [Required]
Path to an .epw file as a text string.
add_str
THIS OPTION IS JUST FOR ADVANCED USERS OF ENERGYPLUS. You can input additional text strings here that you would like written into the IDF. The strings input here should be complete EnergyPlus objects that are correctly formatted. This input can be used to write objects into the IDF that are not currently supported by Honeybee.
cpu_count
An integer to set the number of CPUs used in the execution of each connected IDF file. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine (or 1 if only one processor is available).
run [Required]
Set to "True" to run the IDF through EnergyPlus. This input can also be the integer "2", which will run the whole simulation silently (without any batch windows).
report
Check here to see a report of the EnergyPlus run.
sql
The file path of the SQL result file that has been generated on your machine.
zsz
Path to a .csv file containing detailed zone load information recorded over the course of the design days.
rdd
The file path of the Result Data Dictionary (.rdd) file that is generated after running the file through EnergyPlus. This file contains all possible outputs that can be requested from the EnergyPlus model. Use the Read Result Dictionary component to see what outputs can be requested.
html
The HTML file path of the Summary Reports. Note that this will be None unless the input sim_par denotes that an HTML report is requested and _run is set to True.
Load OpenStudio measures into Grasshopper and assign the measure's input arguments. The resulting measure object can be plugged into the "measures_" input of the "HB Model To OSM" component in order to be included in the export to OpenStudio.
Read more about OpenStudio measures and creating your own here: http://nrel.github.io/OpenStudio-user-documentation/reference/measure_writing_guide/
You can also download several measures created by others from here: https://bcl.nrel.gov/nrel/types/measure
measure_path [Required]
Path to the folder in which the measure exists. This folder must contain a measure.rb and a measure.xml file. Note that connecting an input here will transform the component, essentially removing this input and changing all of the other component inputs to be input arguments for the measure.
report
The execution information, as output and error streams
measure
A measure measure object can be plugged into the "measures_" input of the "HB Model To OSM" component in order to be included in the export to OpenStudio.
Run an OpenStudio Meausre that is intended to create an entire OSM file (OpenStudio Model). Examples of such measures include the "Create DOE Prototype Building" measure such as that wich can be downloaded here:
https://github.com/NREL/openstudio-model-articulation-gem/tree/develop/lib/ measures/create_DOE_prototype_building
measure [Required]
A Measure from the "HB Load Measure" component that is intended to generate an OSM from input arguments. Measures can be downloaded from the NREL Building Components Library (BCL) at (https://bcl.nrel.gov/).
add_str
Optional additional text strings here to be written into the IDF. The input here should be complete EnergyPlus objects as a single string following the IDF format. This can be used to add addition EnergyPlus outputs in the resulting IDF among other features.
folder
An optional folder on this computer, into which the IDF and OSM files will be written. If none, a sub-folder within the default simulation folder will be used.
run [Required]
Script variable Python
out
The execution information, as output and error streams
osw
File path to the OpenStudio Workflow JSON on this machine. This workflow is executed using the OpenStudio command line interface (CLI) and it includes measures to create the OSM from the measure
osm
The file path to the OpenStudio Model (OSM) that has been generated on this computer.
idf
The file path of the EnergyPlus Input Data File (IDF) that has been generated on this computer.
Run Honeybee Rooms through a quick energy simulation to obtain an estimate of room-level peak cooling and heating on summer and winter design days.
rooms [Required]
A list of Honeybee Rooms for which peak loads will be computed.
shades
An optional list of Honeybee Shades that can block the sun to the input _rooms.
ddy_file [Required]
Path to a .ddy file on your system as a text string, which contains design day conditions for the peak load analysis. This can also be the path to an .epw file, in which case design days will be determined by statitically analysing the annual data to approximate 0.4% and 99.6% design conditions. Note that custom .ddy files can be crafted from EPW or STAT data using the "LB EPW to DDY" component. They can also also be created from raw sets of outdoor conditions using the "DF Construct Design Day" and "DF Write DDY" components. When constructing custom DDY files, it is recommended that the .ddy file contain only one summer and one winter design day. Alternatively, if you wish to specify multiple cooling design day conditions for each month of the year (to evaluate solar load in each month), each of these cooling design days should contain "0.4%" in the design day name along with " DB=>MWB". This convention will automatically be followed when using the "monthly_cool_" option on the "LB EPW to DDY" component. In this situation of multiple monthly cooling design days, this component will report peak_cool zone sizes that correspond to the highest month for each zone and the output cooling data collection will be for the month with the highest coincident peak cooling.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
timestep
An integer for the number of timesteps per hour at which the energy simulation will be run and results reported. It is recommended that this be at least 6 but it can be increased to better capture the minute in which peak cooling occurs. (Default: 6). The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
run_bal
Set to True to have the load balance computed after the simulation is run. This ensures that data collections for various terms of the load balance are output from the "balance". This can help explain why the loads are what they are but can also increase the component run time. (Default: False).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
peak_cool
A list of numbers that align with the input _rooms and correspond to the peak cooling of each room on the summer design day in Watts. Note that, for multi-room simulations, the individual room peaks may not be coincident, meaning that summing these values together won't give a correct sense of the size of cetral cooling equipment serving multiple rooms. For such equipment, the max of the cooling data collection should be used.
peak_heat
A list of numbers that align with the input _rooms and correspond to the peak heating of each room on the winter design day in Watts. Note that, for multi-room simulations, the individual room peaks may not be coincident, meaning that summing these values together won't give a correct sense of the size of cetral heating equipment serving multiple rooms. For such equipment, the max of the heating data collection should be used.
cooling
A Data Collection indicating the combined cooling demand of the rooms at each simulation timestep of the summer design day. This can be plugged into the "LB Monthly Chart" component to visualize the demand or it can be deconstructed with the "LB Deconstruct Data" component for analysis.
heating
A Data Collection indicating the combined heating demand of the rooms at each simulation timestepof the winter design day. This can be plugged into the "LB Monthly Chart" component to visualize the demand or it can be deconstructed with the "LB Deconstruct Data" component for analysis.
cool_bal
A list of data collections for the various terms of the sensible load balance that contribute to peak cooling on the summer design day. These can be plugged into the "LB Monthly Chart" component (with stack_ set to True) to visualize the terms contributing to the peak. Will be None unless run_bal_ is set to True.
heat_bal
A list of data collections for the various terms of the sensible load balance that contribute to peak heating on the summer design day. These can be plugged into the "LB Monthly Chart" component (with stack_ set to True) to visualize the terms contributing to the peak. Will be None unless run_bal_ is set to True.
Create a simulation parameter object that carries a complete set of EnergyPlus simulation settings and can be plugged into the "HB Model To OSM" component.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0)
output
A SimulationOutput that lists the desired outputs from the simulation and the format in which to report them. This can be created using the "HB Simulation Output" component. Default is to request zone energy use at an hourly timestep.
run_period
A ladybyg AnalysisPeriod object to describe the time period over which to run the simulation. the default is to run the simulation for the whole year.
daylight_saving
An optional ladybug AnalysisPeriod object to describe start and end of daylight savings time in the simulation. If None, no daylight savings time will be applied to the simulation.
holidays
A list of Ladybug Date objects for the holidays within the simulation. These should be in the format of 'DD Month' (eg. '1 Jan', '25 Dec'). If None, no holidays are applied. Default: None.
start_dow
Text for the day of the week on which the simulation starts. Default: 'Sunday'. Choose from the following:
timestep
An integer for the number of timesteps per hour at which the calculation will be run. Default: 6. The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
terrain
Text for the terrain type in which the model sits, used to determine the wind profile. Default: 'City'. Choose from:
sim_control
A SimulationControl object that describes which types of calculations to run. This can be generated from the "HB Simulation Control" component. Default: perform a sizing calculation but only run the simulation for the RunPeriod.
shadow_calc
A ShadowCalculation object describing settings for the EnergyPlus Shadow Calculation. This can be generated from the "HB Shadow Calculation" component. Default: Average over 30 days with FullExteriorWithReflections.
sizing
A SizingParameter object with criteria for sizing the heating and cooling system. This can be generated from the "HB Sizing Parameter" component.
sim_par
A SimulationParameter object that can be connected to the "HB Model To IDF" component in order to specify EnergyPlus simulation settings
-
Create settings for the EnergyPlus Shadow Calculation.
solar_dist
An integer or text desribing how EnergyPlus should treat beam solar radiation and reflectances from surfaces that strike the building surfaces. Default is "FullExteriorWithReflections". Choose from the following.
0 = "MinimalShadowing" - In this case, exterior shadowing is only computedfor windows and not for other opaque surfaces that might have their surface temperature affected by the sun. All beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
1 = "FullExterior" - The simulation will perform the solar calculationin a manner that only accounts for direct sun and whether it is blocked by surrounding context geometry. For the inside of the building, all beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
2 = "FullInteriorAndExterior" - The simulation will perform the solarcalculation in a manner that models the direct sun (and wheter it is blocked by outdoor context goemetry. It will also ray trace the direct sun on the interior of rooms to distribute it correctly between interior surfaces. Any indirect sun or sun bouncing off of objects will not be modled. Note that, if you use this method without setting the calc_method to PixelCounting, EnergyPlus will give Severe warnings if your rooms have concave geometry (aka. are "L"-shaped). So it is recommended that this solar distribution only be used with the PixelCounting.
3 = "FullExteriorWithReflections" - [DEFAULT] The simulation will perform thesolar calculation in a manner that accounts for both direct sun and the light bouncing off outdoor surrounding context. For the inside of the building, all beam solar radiation entering the room is assumed to fall on the floor. A simple window view factor calculation is used to distribute incoming diffuse solar energy between interior surfaces.
4 = "FullInteriorAndExteriorWithReflections" - The simulation will performthe solar calculation in a manner that accounts for light bounces that happen both outside and inside the rooms. This is the most accurate method but will take longer to run. Note that, if you use this method without setting the calc_method to PixelCounting, EnergyPlus will give Severe warnings if your rooms have concave geometry (aka. are "L"-shaped). So it is recommended that this solar distribution only be used with the PixelCounting.
calc_method
Text noting whether CPU-based polygon clipping method or GPU-based pixel counting method should be used. For low numbers of shading surfaces (less than ~200), PolygonClipping requires less runtime than PixelCounting. However, PixelCounting runtime scales significantly better at higher numbers of shading surfaces. PixelCounting also has no limitations related to room concavity when used with any “FullInterior” solar distribution options. (Default: PolygonClipping). Choose from the following:
PolygonClipping
PixelCounting
update_method
Text describing how often the solar and shading calculations are updated with respect to the flow of time in the simulation. (Default: Periodic) Choose from the following:
Periodic
Timestep
frequency
Integer for the number of days in each period in which a unique shadow calculation will be performed. This field is only used if the AverageOverDaysInFrequency method is used in the previous field. Default - 30.
max_figures
Integer for the number of figures used in shadow overlaps. Default - 15000.
shadow_calc
A ShadowCalculation object that can be connected to the "HB Simulation Parameter" component in order to specify settings for the EnergyPlus Shadow Calculation.
-
Run Honeybee objects capable of generating electricity (such as Shades with PV properties) through a quick energy simulation to obtain an estimate of electricity production.
Note that this component only evaluates electricity production and not energy consumption. Any number of Honeybee Rooms or other objects can be connected but they will only be simulated as context shade that casts shadows on the generator objects.
hb_objs [Required]
An array of honeybee Rooms, Faces, Apertures, Doors or Shades to be included in the simulation of electricity production. This can also be an entire Model to be simulated. Any number of Honeybee Rooms or non-generating objects can be connected but they will only be simulated as context shade that casts shadows on the generator objects.
epw_file [Required]
Path to an .epw file on your system as a text string.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
inverter_eff
A number between 0 and 1 for the load centers's inverter nominal rated DC-to-AC conversion efficiency. An inverter converts DC power, such as that output by photovoltaic panels, to AC power, such as that distributed by the electrical grid and is available from standard electrical outlets. Inverter efficiency is defined as the inverter's rated AC power output divided by its rated DC power output. (Default: 0.96).
dc_to_ac_size
A positive number (typically greater than 1) for the ratio of the inverter's DC rated size to its AC rated size. Typically, inverters are not sized to convert the full DC output under standard test conditions (STC) as such conditions rarely occur in reality and therefore unnecessarily add to the size/cost of the inverter. For a system with a high DC to AC size ratio, during times when the DC power output exceeds the inverter's rated DC input size, the inverter limits the array's power output by increasing the DC operating voltage, which moves the arrays operating point down its current-voltage (I-V) curve. The default value of 1.1 is reasonable for most systems. A typical range is 1.1 to 1.25, although some large-scale systems have ratios of as high as 1.5. The optimal value depends on the system's location, array orientation, and module cost. (Default: 1.1).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
total_ac
A number for the total on-site produced alternating current (AC) electricity in kWh.
ac_power
A data collection of all on-site produced electricity (kWh). This represents the alternating current (AC) electricity coming out of the inverter that processes all on-site power production.
generators
A list of names for each of the electricity generation objects that were found among the connected _hb_objs. These names align with the tota_dc output below as well as the dc_power data collections.
total_dc
A list of numbers for the direct current (DC) electricity produced by each generator object in kWh.
dc_power
A list of data collections for the direct current (DC) electricity produced by each on-site electricity generator (kWh). Each photovoltaic object will have a separate data collection.
-
Visualize the desirability of shade in terms of its impact on the annual heating and cooling loads of Honeybee Rooms.
The calculation runs by performing a simple fast energy simulation of the connected Honeybee Rooms without any shade other than context. The resulting heating/cooling loads are extracted at each timestep of the simulation along with the direct (beam) solar gain through each of the Room's windows. Solar vectors are generated for each step of the simulation and projected from the Room's Aperture geometries through the shades assigned to those Apertures.
Solar vectors for timesteps when the Room is cooling mode contribute positively to shade desirability (shade help) while solar vectors for hours when the Room is heating mode contribute negatively (shade harm). This contribution is weighted by how much cooling or heating energy the Room requires at the timestep along with the direct solar gain through each Aperture at the timestep.
The component outputs a colored mesh of the shades assigned to the Room Apertures illustrating the net effect of shading each part of the geometry. A higher saturation of blue indicates that shading the cell is desirable. A higher saturation of red indicates that shading the cell is harmful (blocking more sun when the Room is in heating mode than cooling mode). Desaturated cells indicate that shading the cell will have relatively little effect on the heating or cooling loads of the Room.
The units for shade desirability are kWh of Room cooling load avoided per unit area of shade if the test cell of the shade is helpful (blue). If the test cell is harmful (red), the units are kWh of Room heating load increased per unit area of shade. So, if a given square meter of input _shade_geo has a shad desirability of 10 kWh/m2, this means that a shade in this location provides roughly 10 kWh of avoided cooling load to the parent Room over the year.
The method used by this component is based off of the Shaderade method developed by Jon Sargent, Jeffrey Niemasz and Christoph Reinhart. More information can be found in the following publication document: Sargent, Jon; Niemasz, Jeffrey; Reinhart, Christoph. SHADERADE: Combining Rhinoceros and EnergyPlus for the Design of Static Exterior Shading Devices. Building Simulation, 2011, Sydney, Australia. http://www.ibpsa.org/proceedings/bs2011/p_1209.pdf
rooms [Required]
A list of Honeybee Rooms for which cooling/heating shade benefit/harm will be evaluated. At least some of these Rooms should have Apertures with Shades assigned to them in order for this component to produce meaningful results. Note that all Shades generated with the "HB Louver Shades" component or the "HB Extruded Border" component are automatically assigned to a parent Aperture. For more complex Shade geometries, the "HB Add Shade" component can be used to assign the Shade to a parent Aperture.
context
Honeybee Shades representing context geometry that can block sun to the _rooms, therefore discounting any benefit or harm that could come to the Room's Shades.
epw_file [Required]
Path to an .epw file on your system as a text string. This will be used in the energy simulation to determine heating/cooling loads and to generate solar vectors for the shade benefit calculation.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
grid_size [Required]
A positive number in Rhino model units for the size of grid cells at which the Shade geometries of the input _rooms will be subdivided for shade benefit analysis. The smaller the grid size, the higher the resolution of the analysis and the longer the calculation will take. So it is recommended that one start with a large value here and decrease the value as needed. However, the grid size should usually be smaller than the dimensions of the smallest piece of Shade geometry in order to yield meaningful results.
timestep
An integer for the number of timesteps per hour at which the energy simulation will run and sun vectors will be generated for the analysis. Higher values will result in the generation of more vectors, which will make the resulting shade meshes smoother and produce a better representation of real benefit/harm. However, the calculation will take longer as there are more intersection operations to perform. The default is 1 timestep per hour, which is the coarsest resolution avalable and the fastest calculation.
legend_par
Optional legend parameters from the "LB Legend Parameters" that will be used to customize the display of the results.
lag_time
A number for the amount of time in hours between when solar gain eneters the room and the gain results in an increased cooling load. Typically, it takes an hour or so for solar gains falling on the room floors to heat up the floor surface and then convect to the room air where the gain can be absorbed by a cooling system. This means that the cooling value associated with each sun vector should be a step or two after the time of the sun vector. Lag time can be longer than an hour if the room has a particularly high thermal mass or it may be shorter if the room has less mass or uses a radiant cooling system integrated into the floor where the sun is absorbed. Note that the value input here can be a decimal value to indicate that the lag time is a fraction of an hour. (Default: 1.0 hour).
cpu_count
An integer to set the number of CPUs used in the execution of the intersection calculation. If unspecified, it will automatically default to one less than the number of CPUs currently available on the machine or 1 if only one processor is available.
run [Required]
Set to "True" to run the component and perform shade benefit analysis.
report
...
vectors
The sun vectors that were used to evaluate the shade (note that these will increase as the timestep increases).
points
Points across the room Aperture geometry from which sun vectors are projected. Note that only Apertures with assigned Shades are evaluated in order to avoid unnessarily increasing the calculation time by evaluating windows for which there is not shade.
mesh
A colored mesh of the Shades assigned to the room's apertures showing where shading is helpful (blue), harmful (red), or does not make much of a difference (white or desaturated colors). Note that the colors can change depending upon the input legend_par_.
legend
Legend showing the numeric values of kWh per unit shade area of decreased/increased cooling/heating load that correspond to the colors in the shade mesh.
title
A text object for the study title.
shade_help
The cumulative kWh of avoided cooling load per square area unit obtained by shading the given cell. If a given square meter of shade geometry has a helpfulness of 10 kWh/m2, this means that a shade in this location decreases the cooling load of the Room by roughly 10 kWh over the year.
shade_harm
The cumulative kWh of increased heating load per square area unit obtained by shading the given cell. If a given square meter of shade geometry has a harmfulness of -10 kWh/m2, this means that a shade in this location increases the heating load of the Room by roughly 10 kWh over the year.
shade_net
The sum of the helpfulness and harmfulness for each cell. This will be negative if shading the cell has a net harmful effect and positive if the shade has a net helpful effect.
Run Honeybee Rooms through a quick energy simulation to obtain an estimate of annual heating, cooling, lighting, equipment, and service hot water loads.
Note that the default settings used by this component are only suitable for evaluating annual loads in the case where an error of up to 5% is acceptable. Also note that annual loads are not the same as annual energy use or utility costs and, while the "cop" inputs can be used to approximate some effects of real heating + cooling systems, any evaulation of actual energy use, utility costs, or GHG emissions should be done by modeling a detailed HVAC using the "HB Model to OSM" component.
rooms [Required]
A list of Honeybee Rooms for which annual loads will be computed.
shades
An optional list of Honeybee Shades that can block the sun to the input _rooms.
epw_file [Required]
Path to an .epw file on your system as a text string.
north
A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East. (Default: 0).
timestep
An integer for the number of timesteps per hour at which the energy balance calculation will be run. This has a dramatic impact on the speed of the simulation and the accuracy of results. Higher timesteps lead to longer simulations and more accurate results. At the lowest aceptable timestep of 1, the results can have an error up to 5% but increasing the timestep to 4 should drop errors to below 1%. (Default: 1). The following values are acceptable: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)
cool_cop
An optional number which the cooling load will be divided by to account for the relative importance of cooling loads compared to heating loads (aka. the Coefficient of Performance or COP). For most cooling systems, this is value greater than 1, though how much greater varies widely between cooling systems and it is ultimately a function of how close the temperature of the cooling system's heat sink is to the room temperature setpoints. If set to 1, the output cooling will be the energy that must be removed from the _rooms to meet the setpoint (aka. the cooling demand). (Default: 1).
heat_cop
An optional number which the heating load will be divided by to account for the relative importance of heating loads compared to cooling loads (aka. the Coefficient of Performance or COP). For fuel-based systems like gas boilers, this value tends to be less than 1 in order to represent the efficiency of the boiler and account for losses of heat, such as that through flue gases. For certain electric systems like heat pumps, this can be a value greater than 1 as such pumps may be able to pump more heat energy into a room per unit of electricity consumed. If set to 1, the output will be the energy that must be added to the _rooms to meet the setpoint (aka. the heating demand). (Default: 1).
run_bal
Set to True to have the full load balance computed after the simulation is run. This ensures that data collections for various terms of the load balance are output from the "balance". This can help explain why the loads are what they are but can also increase the component run time. (Default: False).
run [Required]
Set to "True" to run the simulation to obtain annual loads. This can also be the integer 2 to run the simulation while being able to see the simulation process (with a batch window).
report
A report of the energy simulation run.
total_load
A list of numbers for the 4-5 output load terms normalized by the floor area of the input _rooms. Units are kWh/m2. They are ordered as follows.
cooling
A monthly Data Collection for the cooling load intensity in kWh/m2.
heating
A monthly Data Collection for the heating load intensity in kWh/m2.
lighting
A monthly Data Collection for the lighting load intensity in kWh/m2.
equip
A monthly Data Collection for the equipment load intensity in kWh/m2. Typically, this is only the load from electric equipment but, if the attached _rooms have gas equipment, this will be a list of two data collections for electric and gas equipment respectively.
process
A monthly Data Collection for the process load intensity in kWh/m2.
hot_water
A monthly Data Collection for the service hot water load intensity in kWh/m2.
balance
A list of monthly data collections for the various terms of the floor-normalized load balance in kWh/m2. Will be None unless run_bal_ is set to True.
