honeybee_energy.load.infiltration module

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

class honeybee_energy.load.infiltration.Infiltration(identifier, flow_per_exterior_area, schedule, constant_coefficient=1, temperature_coefficient=0, velocity_coefficient=0)[source]

Bases: _LoadBase

A complete definition of infiltration, including schedules and load.

Parameters:

  • identifier – Text string for a unique Infiltration 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_exterior_area –

    A numerical value for the intensity of infiltration in m3/s per square meter of exterior surface area. Typical values for this property are as follows (note all values are at typical building pressures of ~4 Pa):

    • 0.0001 (m3/s per m2 facade) - Tight building

    • 0.0003 (m3/s per m2 facade) - Average building

    • 0.0006 (m3/s per m2 facade) - Leaky building

  • schedule – A ScheduleRuleset or ScheduleFixedInterval for the infiltration over the course of the year. The type of this schedule should be Fractional and the fractional values will get multiplied by the flow_per_exterior_area to yield a complete infiltration profile.

  • constant_coefficient – A number for the fraction of the infiltration that remains constant in spite of exterior wind and the difference between interior/exterior temperature. EnergyPlus uses 1 by default but BLAST and DOE-2 (the EnergyPlus predecessors) used 0.606 and 0 for this coefficient respectively. Default: 1.

  • temperature_coefficient – A number that will get multiplied by the difference in interior/exterior temperature (in C) to yield a coefficient that gets multiplied by the flow_per_exterior_area. EnergyPlus uses 0 by default but BLAST and DOE-2 (the EnergyPlus predecessors) used 0.03636 and 0 for this coefficient respectively. Default: 0.

  • velocity_coefficient – A number that will get multiplied by the hourly exterior wind velocity (in m/s) to yield a coefficient that gets multiplied by the flow_per_exterior_area. EnergyPlus uses 0 by default but BLAST and DOE-2 (the EnergyPlus predecessors) used 0.1177 and 0.224 for this coefficient respectively. Default: 0.

Properties:

  • identifier

  • display_name

  • flow_per_exterior_area

  • schedule

  • constant_coefficient

  • temperature_coefficient

  • velocity_coefficient

  • user_data

ToString()

Overwrite .NET ToString.

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

Get an Infiltration object that’s an average between other Infiltrations.

Parameters:

  • identifier – Text string for a unique ID for the new averaged Infiltration. 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.

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

  • weights – An optional list of fractional numbers with the same length as the input infiltrations. These will be used to weight each of the Infiltration objects in the resulting average. Note that these weights can sum to less than 1 in which case the average flow_per_exterior_area will assume 0 for the unaccounted fraction of the weights. If None, the objects will be weighted equally. Default: None.

  • 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.

diversify(count, flow_stdev=20, schedule_offset=1, timestep=1, schedule_indices=None)[source]

Get an array of diversified Infiltration derived from this “average” one.

Approximately 2/3 of the schedules in the output objects will be offset from the mean by the input schedule_offset (1/3 ahead and another 1/3 behind).

Parameters:

  • count – An positive integer for the number of diversified objects to generate from this mean object.

  • flow_stdev – A number between 0 and 100 for the percent of the flow_per_exterior_area representing one standard deviation of diversification from the mean. (Default 20 percent).

  • schedule_offset – A positive integer for the number of timesteps at which the lighting schedule of the resulting objects will be shifted - roughly 1/3 of the objects ahead and another 1/3 behind. (Default: 1).

  • timestep – An integer for the number of timesteps per hour at which the shifting is occurring. This must be a value between 1 and 60, which is evenly divisible by 60. 1 indicates that each step is an hour while 60 indicates that each step is a minute. (Default: 1).

  • schedule_indices – An optional list of integers from 0 to 2 with a length equal to the input count, which will be used to set whether a given schedule is behind (0), ahead (2), or the same (1). This can be used to coordinate schedules across diversified programs. If None a random list of integers will be genrated. (Default: None).

duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Create a Infiltration object from a dictionary.

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

Parameters:

data – A Infiltration dictionary in following the format below.

{
"type": 'Infiltration',
"identifier": 'Residentail_Infiltration_000030_1_0_0',
"display_name": 'Residentail Infiltration',
"flow_per_exterior_area": 0.0003, # flow per square meter of exterior area
"schedule": {}, # ScheduleRuleset/ScheduleFixedInterval dictionary
"constant_coefficient": 1, # optional constant coefficient
"temperature_coefficient": 0, # optional temperature coefficient
"velocity_coefficient": 0 # optional velocity coefficient
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a Infiltration object from an abridged dictionary.

Parameters:

  • data – A InfiltrationAbridged 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 Infiltration object.

{
"type": 'InfiltrationAbridged',
"identifier": 'Residentail_Infiltration_000030_1_0_0',
"display_name": 'Residentail Infiltration',
"flow_per_exterior_area": 0.0003, # flow per square meter of exterior area
"schedule": "Residentail Infiltration Schedule", # Schedule identifier
"constant_coefficient": 1, # optional constant coefficient
"temperature_coefficient": 0, # optional temperature coefficient
"velocity_coefficient": 0 # optional velocity coefficient
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create an Infiltration object from an EnergyPlus IDF text string.

Note that the idf_string must use the ‘flow per exterior surface area’ method in order to be successfully imported.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus ZoneInfiltration:DesignFlowRate 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 Infiltration object.

Returns:

A tuple with two elements

  • infiltration: An Infiltration object loaded from the idf_string.

  • zone_identifier: The identifier of the zone to which the Infiltration object should be assigned.

lock()
to_dict(abridged=False)[source]

Infiltration 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 Infiltration object.

Note that this method only outputs a single string for the ZoneInfiltration: DesignFlowRate object and, 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 ZoneInfiltration: DesignFlowRate object is assigned to.

ZoneInfiltration:DesignFlowRate,
    Infiltration 1,              !- Name
    DORM ROOMS AND COMMON AREAS, !- Zone Name
    Infiltration Sch,            !- Schedule Name
    Flow/Zone,                   !- Design Flow Rate Calculation Method
    2.831685,                    !- Design Flow Rate {m3/s}
    ,                            !- Flow Rate per Floor Area {m3/s/m2}
    ,                            !- Flow Rate per Exterior Surface Area {m3/s/m2}
    ,                            !- Air Changes per Hour
    0.6060000    ,               !- Constant Term Coefficient
    3.6359996E-02,               !- Temperature Term Coefficient
    0.1177165    ,               !- Velocity Term Coefficient
    0.0000000E+00;               !- Velocity Squared Term Coefficient
unlock()
property constant_coefficient

Get or set the fraction of infiltration remaining constant despite outdoors.

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 flow_per_exterior_area

Get or set the infiltration in m3/s per square meter of exterior surface area.

Typical values for this property are as follows:

  • 0.0001 (m3/s per m2 facade) - Tight building

  • 0.0003 (m3/s per m2 facade) - Average building

  • 0.0006 (m3/s per m2 facade) - Leaky building

property identifier

Get or set the text string for object identifier.

property properties

Get properties for extensions.

property schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for infiltration.

property temperature_coefficient

Get or set the coefficient for the interior/exterior temperature difference.

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)

property velocity_coefficient

Get or set the coefficient for the exterior wind speed.