honeybee_energy.load.ventilation module

Complete definition of ventilation in a simulation, including schedule and load.

class honeybee_energy.load.ventilation.Ventilation(identifier, flow_per_person=0, flow_per_area=0, flow_per_zone=0, air_changes_per_hour=0, schedule=None, method='Sum', effectiveness_cooling=1, effectiveness_heating=1, secondary_recirculation=0)[source]

Bases: _LoadBase

A complete definition of ventilation, including schedules and load.

Note the the 4 ventilation types (flow_per_person, flow_per_area, flow_per_zone, and air_changes_per_hour) are ultimately added together to yield the ventilation design flow rate used in the simulation.

Parameters:

  • identifier – Text string for a unique Ventilation ID. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • flow_per_person – A numerical value for the intensity of ventilation in m3/s per person. Note that setting this value here does not mean that ventilation is varied based on real-time occupancy but rather that the design level of ventilation is determined using this value and the People object of the zone. To vary ventilation in real time, the ventilation schedule should be used. Most ventilation standards support that a value of 0.01 m3/s (10 L/s or ~20 cfm) per person is sufficient to remove odors. Accordingly, setting this value to 0.01 and using 0 for the following ventilation terms will often be suitable for many applications. Default: 0.

  • flow_per_area – A numerical value for the intensity of ventilation in m3/s per square meter of floor area. Default: 0.

  • flow_per_zone – A numerical value for the design level of ventilation in m3/s for the entire zone. Default: 0.

  • air_changes_per_hour – A numerical value for the design level of ventilation in air changes per hour (ACH) for the entire zone. This is particularly helpful for hospitals, where ventilation standards are often given in ACH. (Default: 0).

  • schedule – An optional ScheduleRuleset or ScheduleFixedInterval for the ventilation over the course of the year. The type of this schedule should be Fractional and the fractional values will get multiplied by the total design flow rate (determined from the sum or max of the other 4 fields) to yield a complete ventilation profile. Setting this schedule to be the occupancy schedule of the zone will mimic demand controlled ventilation. If None, the design level of ventilation will be used throughout all timesteps of the simulation, meaning that this schedule is Always On. (Default: None).

  • method –

    Text to set how the different ventilation criteria are reconciled against one another. Choose from the options below. (Default: Sum).

    • Sum

    • Max

  • effectiveness_cooling – A positive number to note the air distribution effectiveness of the ventilation system when it operates in cooling mode (or how well the system is able to mix the air when cooling). A value of 1 means that air is well mixed and specified air flows are not adjusted in the course of simulation. Values less than 1 indicate systems that do not mix the air as well and so the specified airflows are increased. Values greater than 1 indicate systems that are particularly good at delivering outdoor air to the occupied region of a room and so the specified airflows can be reduced. (Default: 1).

  • effectiveness_heating – A positive number to note the air distribution effectiveness of the ventilation system when it operates in heating mode (or how well the system is able to mix the air when heating). A value of 1 means that air is well mixed and specified air flows are not adjusted in the course of simulation. Values less than 1 indicate systems that do not mix the air as well and so the specified airflows are increased. Values greater than 1 indicate systems that are particularly good at delivering outdoor air to the occupied region of a room and so the specified airflows can be reduced. (Default: 1).

  • secondary_recirculation – A number that is greater than or equal to zero, which notes to note the fraction of a zone’s recirculation air that does not directly mix with the outdoor air. Used in cases where a central ventilation system supplies several zones and the return air is not collected through ducts back to the central air handler (eg. a plenum return system is used). This means unused outdoor ventilation air from other zones in the central system can be credited to the room. (Default: 0).

Properties:

  • identifier

  • display_name

  • flow_per_person

  • flow_per_area

  • flow_per_zone

  • air_changes_per_hour

  • schedule

  • method

  • effectiveness_cooling

  • effectiveness_heating

  • secondary_recirculation

  • user_data

ToString()

Overwrite .NET ToString.

static average(identifier, ventilations, weights=None, timestep_resolution=1)[source]

Get a Ventilation object that’s an average between other Ventilations.

Parameters:

  • identifier – Text string for a unique ID for the new averaged Ventilation. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • ventilations – A list of Ventilation objects that will be averaged together to make a new Ventilation.

  • weights – An optional list of fractional numbers with the same length as the input ventilations. These will be used to weight each of the Ventilation objects in the resulting average. Note that these weights can sum to less than 1 in which case the average flow rates will assume 0 for the unaccounted fraction of the weights.

  • timestep_resolution – An optional integer for the timestep resolution at which the schedules will be averaged. Any schedule details smaller than this timestep will be lost in the averaging process. Default: 1.

static combine_room_ventilations(identifier, rooms, timestep_resolution=1)[source]

Get a Ventilation object that represents the sum across rooms.

In this process of combining ventilation requirements, the following rules hold: 1. Total flow rates in m3/s are simply added together. 2. Flow per floor area gets recomputed using the floor areas of each room. 3. ACH flow gets recomputed using the volumes of each room in the inputs. 4. Flow per person gets set based on whichever room has the highest ventilation requirement per person.

In the case of ventilation schedules, the strictest schedule governs and note that the absence of a ventilation schedule means the schedule is Always On. So, if one room has a ventilation schedule and the other does not, then the schedule essentially gets removed. If each room has a different ventilation schedule, then a new schedule will be created using the maximum value across the two schedules at each timestep.

In the case of ventilation effectiveness and secondary recirculation, the minimum effectiveness and recirculation fractions across the rooms will be used.

Parameters:

  • identifier – Text string for a unique ID for the new Ventilation object. Must be < 100 characters and not contain any EnergyPlus special characters. This will be used to identify the object across a model and in the exported IDF.

  • rooms – A list of Rooms that will have their Ventilation objects combined to make a new Ventilation.

  • timestep_resolution – An optional integer for the timestep resolution at which conflicting ventilation schedules will be resolved. (Default: 1).

duplicate()

Get a copy of this object.

classmethod from_dict(data, schedules=None)[source]

Create a Ventilation object from a dictionary.

Note that the dictionary must be a non-abridged version for this classmethod to work.

Parameters:

  • data – A Ventilation dictionary in following the format below.

  • schedules – Optional dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). When specified, these will be prioritized over the child objects underneath their unabridged specification.

{
"type": 'Ventilation',
"identifier": 'Office_Ventilation_0010_000050_0_0',
"display_name": 'Office Ventilation',
"flow_per_person": 0.01, # flow per person
"flow_per_area": 0.0005, # flow per square meter of floor area
"flow_per_zone": 0, # flow per zone
"air_changes_per_hour": 0, # air changes per hour
"schedule": {}, # ScheduleRuleset/ScheduleFixedInterval dictionary
"method": "Sum",  # text for the ventilation method
"effectiveness_cooling": 1.0,  # effectiveness during cooling
"effectiveness_heating": 0.8,  # effectiveness during heating
"secondary_recirculation": 0  # fraction of secondary recirculated air
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a Ventilation object from an abridged dictionary.

Parameters:

  • data – A VentilationAbridged dictionary in following the format below.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the Ventilation object.

{
"type": 'VentilationAbridged',
"identifier": 'Office_Ventilation_0010_000050_0_0',
"display_name": 'Office Ventilation',
"flow_per_person": 0.01, # flow per person
"flow_per_area": 0.0005, # flow per square meter of floor area
"flow_per_zone": 0, # flow per zone
"air_changes_per_hour": 0, # air changes per hour
"schedule": "Office Ventilation Schedule", # Schedule identifier
"method": "Sum",  # text for the ventilation method
"effectiveness_cooling": 1.0,  # effectiveness during cooling
"effectiveness_heating": 0.8,  # effectiveness during heating
"secondary_recirculation": 0  # fraction of secondary recirculated air
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create an Ventilation object from an EnergyPlus IDF text string.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus DesignSpecification:OutdoorAir definition.

  • schedule_dict – A dictionary with schedule identifiers as keys and honeybee schedule objects as values (either ScheduleRuleset or ScheduleFixedInterval). These will be used to assign the schedules to the Ventilation object.

Returns:

ventilation – An Ventilation object loaded from the idf_string.

lock()
room_absolute_flow(room)[source]

Get the total flow rate of outdoor ventilation air for a Room in m3/s.

The result of this method accounts for all four ways of specifying ventilation and appropriately accounts for the Ventilation method. It also includes all effects of ventilation effectiveness (using the lower of the two ventilation effectiveness between heating and cooling mode).

It does NOT include the effect of secondary recirculation given that the effect of this is impossible to know without having the other rooms included within the multi-path system.

Parameters:

room – The honeybee Room to which the ventilation object is assigned.

to_dict(abridged=False)[source]

Ventilation dictionary representation.

Parameters:

abridged – Boolean to note whether the full dictionary describing the object should be returned (False) or just an abridged version (True), which only specifies the identifiers of schedules. Default: False.

to_idf(zone_identifier)[source]

IDF string representation of Ventilation object.

Note that this method only outputs a single string for the DesignSpecification: OutdoorAir object. To write everything needed to describe the object into an IDF, this object’s schedule must also be written.

Parameters:

zone_identifier – Text for the zone identifier that the Ventilation object is assigned to.

DesignSpecification:OutdoorAir
    ZoneOAData,            !- Name
    Sum,                   !- Outdoor Air Method
    0.00944,               !- Outdoor Air Flow per Person {m3/s}
    0.00305,               !- Outdoor Air Flow per Zone Floor Area {m3/s-m2}
    ,                      !- Outdoor Air Flow per Zone {m3/s}
    ,                      !- Outdoor Air Flow Air Changes per Hour
    OARequirements Sched;  !- Outdoor Air Schedule Name
unlock()
METHODS = ('Sum', 'Max')
property air_changes_per_hour

Get or set the ventilation in air changes per hour (ACH).

property air_changes_per_hour_ip

Get the air_changes_per_hour in the standard IP unit of ACH.

property air_changes_per_hour_si

Get the air_changes_per_hour in the standard SI unit of ACH.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property effectiveness_cooling

Get or set a number for the air distribution effectiveness in cooling mode.

property effectiveness_heating

Get or set a number for the air distribution effectiveness in heating mode.

property flow_per_area

Get or set the ventilation in m3/s per square meter of zone floor area.

property flow_per_area_ip

Get the flow_per_area in the standard IP unit of cfm/ft2.

property flow_per_area_si

Get the flow_per_area in the standard SI unit of L/s/m2.

property flow_per_person

Get or set the intensity of ventilation in m3/s per person.

Note that setting this value here does not mean that ventilation is varied based on real-time occupancy but rather that the design level of ventilation is determined using this value and the People object of the zone. To vary ventilation in real time, the ventilation schedule should be used or demand controlled ventilation options should be set on the HVAC system.

Most ventilation standards support that a value of 0.01 m3/s (10 L/s or ~20 cfm) per person is sufficient to remove odors. Accordingly, setting this value to 0.01 and using 0 for the following ventilation terms will often be suitable for many applications.

property flow_per_person_ip

Get the flow_per_person in the standard IP unit of cfm/person.

property flow_per_person_si

Get the flow_per_person in the standard SI unit of L/s/person.

property flow_per_zone

Get or set the ventilation in m3/s per zone.

property flow_per_zone_ip

Get the flow_per_zone in the standard IP unit of cfm.

property flow_per_zone_si

Get the flow_per_zone in the standard SI unit of L/s.

property identifier

Get or set the text string for object identifier.

property method

Text to set how the ventilation criteria are reconciled against one another.

Choose from the options below.

  • Sum

  • Max

property properties

Get properties for extensions.

property schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for ventilation.

property secondary_recirculation

Get or set a number for the fraction of recirculation air not mixed outdoor air.

property user_data

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)