Honeybee Simulation Parameter Schema (2.2.0)

Download OpenAPI specification:Download

Honeybee simulation-parameter schema.

ASHRAEClearSky

date
required
Array of integers <int32> (Date) [ 2 .. 3 ] items [ items <int32 > ]

A list of two integers for [month, day], representing the date for the day of the year on which the design day occurs. A third integer may be added to denote whether the date should be re-serialized for a leap year (it should be a 1 in this case).

clearness
required
number <double> (Clearness) [ 0 .. 1.2 ]

Value between 0 and 1.2 that will get multiplied by the irradiance to correct for factors like elevation above sea level.

daylight_savings
boolean (Daylight Savings)
Default: false

Boolean to indicate whether daylight savings time is active on the design day.

type
string (Type)
Default: "ASHRAEClearSky"
Value: "ASHRAEClearSky"
{
  • "date": [
    ],
  • "clearness": 1.2,
  • "daylight_savings": false,
  • "type": "ASHRAEClearSky"
}

ASHRAETau

date
required
Array of integers <int32> (Date) [ 2 .. 3 ] items [ items <int32 > ]

A list of two integers for [month, day], representing the date for the day of the year on which the design day occurs. A third integer may be added to denote whether the date should be re-serialized for a leap year (it should be a 1 in this case).

tau_b
required
number <double> (Tau B) [ 0 .. 1.2 ]

Value for the beam optical depth. Typically found in .stat files.

tau_d
required
number <double> (Tau D) [ 0 .. 3 ]

Value for the diffuse optical depth. Typically found in .stat files.

daylight_savings
boolean (Daylight Savings)
Default: false

Boolean to indicate whether daylight savings time is active on the design day.

type
string (Type)
Default: "ASHRAETau"
Value: "ASHRAETau"
{
  • "date": [
    ],
  • "tau_b": 1.2,
  • "tau_d": 3,
  • "daylight_savings": false,
  • "type": "ASHRAETau"
}

CalculationMethod

string (CalculationMethod)
Enum: "PolygonClipping" "PixelCounting"
"PolygonClipping"

CalculationUpdateMethod

string (CalculationUpdateMethod)
Enum: "Periodic" "Timestep"
"Periodic"

ClimateZones

string (ClimateZones)
Enum: "0A" "1A" "2A" "3A" "4A" "5A" "6A" "0B" "1B" "2B" "3B" "4B" "5B" "6B" "3C" "4C" "5C" "7" "8"
"0A"

DaylightSavingTime

type
string (Type)
Default: "DaylightSavingTime"
Value: "DaylightSavingTime"
start_date
Array of integers <int32> (Start Date) [ 2 .. 3 ] items [ items <int32 > ]
Default: [3,12]

A list of two integers for [month, day], representing the date for the start of daylight savings time. Default: 12 Mar (daylight savings in the US in 2017).

end_date
Array of integers <int32> (End Date) [ 2 .. 3 ] items [ items <int32 > ]
Default: [11,5]

A list of two integers for [month, day], representing the date for the end of daylight savings time. Default: 5 Nov (daylight savings in the US in 2017).

{
  • "type": "DaylightSavingTime",
  • "start_date": [
    ],
  • "end_date": [
    ]
}

DaysOfWeek

string (DaysOfWeek)
Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday"
"Sunday"

DesignDay

name
required
string (Name) [ 1 .. 100 ] characters

Text string for a unique design day name. This name remains constant as the object is mutated, copied, and serialized to different formats (eg. dict, idf, osm). It is also used to reference the object within SimulationParameters. It must be < 100 characters, use only ASCII characters and exclude (, ; ! \n \t).

day_type
required
string (DesignDayTypes)
Enum: "SummerDesignDay" "WinterDesignDay" "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Holiday" "CustomDay1" "CustomDay2"
required
object (DryBulbCondition)

Used to specify dry bulb conditions on a design day.

required
object (HumidityCondition)

Used to specify humidity conditions on a design day.

required
object (WindCondition)

Used to specify wind conditions on a design day.

required
ASHRAEClearSky (object) or ASHRAETau (object) (Sky Condition)
type
string (Type)
Default: "DesignDay"
Value: "DesignDay"
{
  • "name": "string",
  • "day_type": "SummerDesignDay",
  • "dry_bulb_condition": {
    },
  • "humidity_condition": {
    },
  • "wind_condition": {
    },
  • "sky_condition": {
    },
  • "type": "DesignDay"
}

DesignDayTypes

string (DesignDayTypes)
Enum: "SummerDesignDay" "WinterDesignDay" "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Holiday" "CustomDay1" "CustomDay2"
"SummerDesignDay"

DryBulbCondition

dry_bulb_max
required
number <double> (Dry Bulb Max) [ -90 .. 70 ]

The maximum dry bulb temperature on the design day [C].

dry_bulb_range
required
number <double> (Dry Bulb Range) >= 0

The difference between min and max temperatures on the design day [C].

type
string (Type)
Default: "DryBulbCondition"
Value: "DryBulbCondition"
{
  • "dry_bulb_max": -90,
  • "dry_bulb_range": 0,
  • "type": "DryBulbCondition"
}

EfficiencyStandards

string (EfficiencyStandards)
Enum: "ASHRAE_2019" "ASHRAE_2016" "ASHRAE_2013" "ASHRAE_2010" "ASHRAE_2007" "ASHRAE_2004" "DOE_Ref_1980_2004" "DOE_Ref_Pre_1980"
"ASHRAE_2019"

HumidityCondition

humidity_type
required
string (HumidityTypes)
Enum: "Wetbulb" "Dewpoint" "HumidityRatio" "Enthalpy"
humidity_value
required
number <double> (Humidity Value)

The value correcponding to the humidity_type.

type
string (Type)
Default: "HumidityCondition"
Value: "HumidityCondition"
barometric_pressure
number <double> (Barometric Pressure) [ 31000 .. 120000 ]
Default: 101325

Barometric air pressure on the design day [Pa].

rain
boolean (Rain)
Default: false

Boolean to indicate rain on the design day.

snow_on_ground
boolean (Snow On Ground)
Default: false

Boolean to indicate snow on the ground during the design day.

{
  • "humidity_type": "Wetbulb",
  • "humidity_value": 0,
  • "type": "HumidityCondition",
  • "barometric_pressure": 101325,
  • "rain": false,
  • "snow_on_ground": false
}

HumidityTypes

string (HumidityTypes)
Enum: "Wetbulb" "Dewpoint" "HumidityRatio" "Enthalpy"
"Wetbulb"

ReportingFrequency

string (ReportingFrequency)
Enum: "Timestep" "Hourly" "Daily" "Monthly" "Annual"
"Timestep"

RunPeriod

type
string (Type)
Default: "RunPeriod"
Value: "RunPeriod"
start_date
Array of integers <int32> (Start Date) = 2 items [ items <int32 > ]
Default: [1,1]

A list of two integers for [month, day], representing the date for the start of the run period. Must be before the end date.

end_date
Array of integers <int32> (End Date) = 2 items [ items <int32 > ]
Default: [12,31]

A list of two integers for [month, day], representing the date for the end of the run period. Must be after the start date.

start_day_of_week
string (DaysOfWeek)
Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday"
Array of Holidays (integers) or Holidays (null) (Holidays)
Default: null

A list of lists where each sub-list consists of two integers for [month, day], representing a date which is a holiday within the simulation. If None, no holidays are applied.

DaylightSavingTime (object) or null
Default: null

A DaylightSavingTime to dictate the start and end dates of daylight saving time. If None, no daylight saving time is applied to the simulation.

leap_year
boolean (Leap Year)
Default: false

Boolean noting whether the simulation will be run for a leap year.

{
  • "type": "RunPeriod",
  • "start_date": [
    ],
  • "end_date": [
    ],
  • "start_day_of_week": "Sunday",
  • "holidays": null,
  • "daylight_saving_time": null,
  • "leap_year": false
}

ShadowCalculation

type
string (Type)
Default: "ShadowCalculation"
Value: "ShadowCalculation"
solar_distribution
string (SolarDistribution)
Enum: "MinimalShadowing" "FullExterior" "FullInteriorAndExterior" "FullExteriorWithReflections" "FullInteriorAndExteriorWithReflections"
calculation_method
string (CalculationMethod)
Enum: "PolygonClipping" "PixelCounting"
calculation_update_method
string (CalculationUpdateMethod)
Enum: "Periodic" "Timestep"
calculation_frequency
integer <int32> (Calculation Frequency) >= 1
Default: 30

Integer for the number of days in each period for which a unique shadow calculation will be performed. This field is only used if the Periodic calculation_method is used.

maximum_figures
integer <int32> (Maximum Figures) >= 200
Default: 15000

Number of allowable figures in shadow overlap calculations.

{
  • "type": "ShadowCalculation",
  • "solar_distribution": "MinimalShadowing",
  • "calculation_method": "PolygonClipping",
  • "calculation_update_method": "Periodic",
  • "calculation_frequency": 30,
  • "maximum_figures": 15000
}

SimulationControl

type
string (Type)
Default: "SimulationControl"
Value: "SimulationControl"
do_zone_sizing
boolean (Do Zone Sizing)
Default: true

Boolean for whether the zone sizing calculation should be run.

do_system_sizing
boolean (Do System Sizing)
Default: true

Boolean for whether the system sizing calculation should be run.

do_plant_sizing
boolean (Do Plant Sizing)
Default: true

Boolean for whether the plant sizing calculation should be run.

run_for_run_periods
boolean (Run For Run Periods)
Default: true

Boolean for whether the simulation should be run for the sizing periods.

run_for_sizing_periods
boolean (Run For Sizing Periods)
Default: false

Boolean for whether the simulation should be run for the run periods.

{
  • "type": "SimulationControl",
  • "do_zone_sizing": true,
  • "do_system_sizing": true,
  • "do_plant_sizing": true,
  • "run_for_run_periods": true,
  • "run_for_sizing_periods": false
}

SimulationOutput

type
string (Type)
Default: "SimulationOutput"
Value: "SimulationOutput"
reporting_frequency
string (ReportingFrequency)
Enum: "Timestep" "Hourly" "Daily" "Monthly" "Annual"
Array of Outputs (strings) or Outputs (null) (Outputs)
Default: null

A list of EnergyPlus output names as strings, which are requested from the simulation.

Array of Summary Reports (strings) or Summary Reports (null) (Summary Reports)
Default: null

A list of EnergyPlus summary report names as strings.

unmet_setpoint_tolerance
number <double> (Unmet Setpoint Tolerance) [ 0 .. 10 ]
Default: 1.11

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.

{
  • "type": "SimulationOutput",
  • "reporting_frequency": "Timestep",
  • "outputs": null,
  • "summary_reports": null,
  • "unmet_setpoint_tolerance": 1.11
}

SimulationParameter

type
string (Type)
Default: "SimulationParameter"
Value: "SimulationParameter"
SimulationOutput (object) or null
Default: null

A SimulationOutput that lists the desired outputs from the simulation and the format in which to report them.

RunPeriod (object) or null
Default: null

A RunPeriod to describe the time period over which to run the simulation.

timestep
integer <int32> (Timestep) [ 1 .. 60 ]
Default: 6

An integer for the number of timesteps per hour at which the energy calculation will be run.

SimulationControl (object) or null
Default: null

A SimulationControl object that describes which types of calculations to run.

ShadowCalculation (object) or null
Default: null

A ShadowCalculation object describing settings for the EnergyPlus Shadow Calculation.

SizingParameter (object) or null
Default: null

A SizingParameter object with criteria for sizing the heating and cooling system.

north_angle
number <double> (North Angle) [ -360 .. 360 ]
Default: 0

A number between -360 and 360 for the north direction in degrees.This is the counterclockwise difference between the North and the positive Y-axis. 90 is West and 270 is East. Note that this is different than the convention used in EnergyPlus, which uses clockwise difference instead of counterclockwise difference.

terrain_type
string (TerrianTypes)
Enum: "Ocean" "Country" "Suburbs" "Urban" "City"
{
  • "type": "SimulationParameter",
  • "output": null,
  • "run_period": null,
  • "timestep": 6,
  • "simulation_control": null,
  • "shadow_calculation": null,
  • "sizing_parameter": null,
  • "north_angle": 0,
  • "terrain_type": "Ocean"
}

SizingParameter

type
string (Type)
Default: "SizingParameter"
Value: "SizingParameter"
Array of Design Days (objects) or Design Days (null) (Design Days)
Default: null

A list of DesignDays that represent the criteria for which the HVAC systems will be sized.

heating_factor
number <double> (Heating Factor) > 0
Default: 1.25

A number that will be multiplied by the peak heating load for each zone in order to size the heating system.

cooling_factor
number <double> (Cooling Factor) > 0
Default: 1.15

A number that will be multiplied by the peak cooling load for each zone in order to size the heating system.

EfficiencyStandards (string) or null
Default: null

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 depending on 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.

ClimateZones (string) or null
Default: null

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 on this sizing parameter object.

Building Type (string) or Building Type (null) (Building Type)
Default: null

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 specified systems per the standard: Residential, NonResidential, MidriseApartment, HighriseApartment, LargeOffice, MediumOffice, SmallOffice, Retail, StripMall, PrimarySchool, SecondarySchool, SmallHotel, LargeHotel, Hospital, Outpatient, Warehouse, SuperMarket, FullServiceRestaurant, QuickServiceRestaurant, Laboratory, Courthouse.

bypass_efficiency_sizing
boolean (Bypass Efficiency Sizing)
Default: false

A boolean to indicate whether the efficiency standard should trigger an sizing run that sets the efficiencies of all HVAC equipment in the Model (False) or the standard should only be written into the OSM and the sizing run should be bypassed (True). Bypassing the sizing run is useful when you only want to check that the overall HVAC system architecture is correct and you do not want to wait the extra time that it takes to run the sizing calculation.

{
  • "type": "SizingParameter",
  • "design_days": null,
  • "heating_factor": 1.25,
  • "cooling_factor": 1.15,
  • "efficiency_standard": null,
  • "climate_zone": null,
  • "building_type": null,
  • "bypass_efficiency_sizing": false
}

SolarDistribution

string (SolarDistribution)
Enum: "MinimalShadowing" "FullExterior" "FullInteriorAndExterior" "FullExteriorWithReflections" "FullInteriorAndExteriorWithReflections"
"MinimalShadowing"

TerrianTypes

string (TerrianTypes)
Enum: "Ocean" "Country" "Suburbs" "Urban" "City"
"Ocean"

WindCondition

wind_speed
required
number <double> (Wind Speed) [ 0 .. 40 ]

Wind speed on the design day [m/s].

type
string (Type)
Default: "WindCondition"
Value: "WindCondition"
wind_direction
number <double> (Wind Direction) [ 0 .. 360 ]
Default: 0

Wind direction on the design day [degrees].

{
  • "wind_speed": 40,
  • "type": "WindCondition",
  • "wind_direction": 0
}