honeybee_energy.load.setpoint module

Temperature (thermostat) and humidity (humidistat) setpoints for a thermal zone.

class honeybee_energy.load.setpoint.Setpoint(identifier, heating_schedule, cooling_schedule, humidifying_schedule=None, dehumidifying_schedule=None, setpoint_cutout_difference=0)[source]

Bases: _LoadBase

Temperature (thermostat) and humidity (humidistat) setpoints for a thermal zone.

Parameters:

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

  • heating_schedule – A ScheduleRuleset or ScheduleFixedInterval for the heating setpoint.

  • cooling_schedule – A ScheduleRuleset or ScheduleFixedInterval for the cooling setpoint.

  • humidifying_schedule – A ScheduleRuleset or ScheduleFixedInterval for the humidification setpoint. If None, no additional humidification will be applied by the HVAC system. (Default: None).

  • dehumidifying_schedule – A ScheduleRuleset or ScheduleFixedInterval for the dehumidification setpoint. If None, no additional dehumidification will be performed by the HVAC system. (Default: None).

  • setpoint_cutout_difference – An optional positive number for the temperature difference between the cutout temperature and the setpoint temperature. Specifying a non-zero number here is useful for modeling the throttling range associated with a given setup of setpoint controls and HVAC equipment. Throttling ranges describe the range where a zone is slightly over-cooled or over-heated beyond the thermostat setpoint. They are used to avoid situations where HVAC systems turn on only to turn off a few minutes later, thereby wearing out the parts of mechanical systems faster. They can have a minor impact on energy consumption and can often have significant impacts on occupant thermal comfort, though using the default value of zero will often yield results that are close enough when trying to estimate the annual heating/cooling energy use. Specifying a value of zero effectively assumes that the system will turn on whenever conditions are outside the setpoint range and will cut out as soon as the setpoint is reached. (Default: 0).

Properties:

  • identifier

  • display_name

  • heating_schedule

  • cooling_schedule

  • humidifying_schedule

  • dehumidifying_schedule

  • setpoint_cutout_difference

  • heating_setpoint

  • cooling_setpoint

  • humidifying_setpoint

  • dehumidifying_setpoint

  • heating_setback

  • cooling_setback

  • humidifying_setback

  • dehumidifying_setback

  • user_data

ToString()

Overwrite .NET ToString.

add_humidity_from_idf(idf_string, schedule_dict)[source]

Add humidity setpoints to this object from an EnergyPlus IDF text string.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus ZoneControl:Humidistat 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 Setpoint object.

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

Get an Setpoint object that’s an average between other Setpoints.

Parameters:

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

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

  • weights – An optional list of fractional numbers with the same length as the input setpoints. These will be used to weight each of the Setpoint objects in the resulting average. Note that, if the sum of the weights is less than 1, the unaccounted fraction will be assumed to be at the weighted average setpoints of the other objects. 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, schedule_offset=1, timestep=1, schedule_indices=None)[source]

Get an array of diversified Setpoints 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.

  • schedule_offset – A positive integer for the number of timesteps at which the setpoint 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 Setpoint object from a dictionary.

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

Parameters:

data – A Setpoint dictionary in following the format below.

{
"type": 'Setpoint',
"identifier": 'Hospital_Patient_Room_Setpoint_210_230',
"display_name": 'Patient Room Setpoint',
"heating_schedule": {}, # ScheduleRuleset/FixedInterval dictionary
"cooling_schedule": {}, # ScheduleRuleset/FixedInterval dictionary
"humidifying_schedule": {}, # ScheduleRuleset/FixedInterval dictionary
"dehumidifying_schedule": {}, # ScheduleRuleset/FixedInterval dictionary
"setpoint_cutout_difference": 0.5  # number for cutout difference
}
classmethod from_dict_abridged(data, schedule_dict)[source]

Create a Setpoint object from an abridged dictionary.

Parameters:

  • data – A SetpointAbridged 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 Setpoint object.

{
"type": 'SetpointAbridged',
"identifier": 'Hospital_Patient_Room_Setpoint_210_230',
"display_name": 'Patient Room Setpoint',
"heating_schedule": "Hospital Pat Room Heating", # Schedule identifier
"cooling_schedule": "Hospital Pat Room Cooling", # Schedule identifier
"humidifying_schedule": "Hospital Pat Room Humidify", # Schedule identifier
"dehumidifying_schedule": "Hospital Pat Room Dehumidify", # Sched identifier
"setpoint_cutout_difference": 0.5  # number for cutout difference
}
classmethod from_idf(idf_string, schedule_dict)[source]

Create an Setpoint object from an EnergyPlus IDF text string.

Note that this method only loads the heating and cooling setpoints from an IDF and, to also load humidity setpoints, the add_humidity_from_idf method should be used.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus HVACTemplate:Thermostat 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 Setpoint object.

Returns:

setpoint – A Setpoint object loaded from the idf_string.

lock()
remove_humidity_setpoints()[source]

Remove all humidity setpoints from this object.

to_dict(abridged=False)[source]

Setpoint 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 Setpoint object’s thermostat.

Note that this method only outputs a string for the HVACTemplate:Thermostat object and, to write everything needed to describe the object into an IDF, this object’s schedules must also be written. If the humidifying or dehumidifying schedules are not None, the to_idf_humidistat method should also be used to write the humidistat.

Parameters:

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

ZoneControl:Thermostat,
    AllControlledZones Thermostat,      !- Name
    AllControlledZones,                 !- Zone Name
    Zone Control Type Sched,            !- Control Type Schedule Name
    ThermostatSetpoint:SingleCooling,   !- Control 1 Object Type
    CoolingSetPoint,                    !- Control 1 Name
    ThermostatSetpoint:SingleHeating,   !- Control 2 Object Type
    HeatingSetpoint,                    !- Control 2 Name
    ThermostatSetpoint:DualSetpoint,    !- Control 3 Object Type
    DualSetPoint;                       !- Control 3 Name
to_idf_humidistat(zone_identifier)[source]

IDF string representation of Setpoint object’s humidistat.

Note that this method only outputs strings for the ZoneControl:Humidistat and, to write everything needed to describe the object into an IDF, this object’s schedules must also be written.

Also note that this method will return None if no humidity setpoint schedules have been assigned.

Parameters:

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

ZoneControl:Humidistat,
    Zone 2 Humidistat,   !- Humidistat Name
    EAST ZONE,           !- Zone Name
    Min Rel Hum Set Sch, !- Humidifying Relative Humidity Setpoint SCHEDULE Name
    Max Rel Hum Set Sch; !- Dehumidifying Relative Humidity Setpoint SCHEDULE Name
unlock()
property cooling_schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for the cooling setpoint.

property cooling_setback

Get the highest temperature in the cooling setpoint schedule [C].

Note that, if a constant cooling_setpoint has been assigned to this object, this property will the same as the cooling_setpoint.

property cooling_setpoint

Get or set a single constant temperature for the cooling setpoint [C].

Note that, if a varying cooling_schedule has been assigned to this object, this property will be the lowest temperature within the cooling_schedule.

property dehumidifying_schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for dehumidification.

property dehumidifying_setback

Get the highest humidity in the dehumidifying setpoint schedule [%].

Note that, if a constant dehumidifying_setpoint has been assigned to this object, this property will the same as the dehumidifying_setpoint.

property dehumidifying_setpoint

Get or set a single constant value for the dehumidifying setpoint [%].

Note that, if a varying dehumidifying_schedule has been assigned to this object, this property will be the lowest value within the dehumidifying_schedule.

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 heating_schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for the heating setpoint.

property heating_setback

Get the lowest temperature in the heating setpoint schedule [C].

Note that, if a constant heating_setpoint has been assigned to this object, this property will the same as the heating_setpoint.

property heating_setpoint

Get or set a single constant temperature for the heating setpoint [C].

Note that, if a varying heating_schedule has been assigned to this object, this property will be the highest temperature within the heating_schedule.

property humidifying_schedule

Get or set a ScheduleRuleset or ScheduleFixedInterval for humidification.

property humidifying_setback

Get the lowest humidity in the humidifying setpoint schedule [%].

Note that, if a constant humidifying_setpoint has been assigned to this object, this property will the same as the humidifying_setpoint.

property humidifying_setpoint

Get or set a single constant value for the humidifying setpoint [%].

Note that, if a varying humidifying_schedule has been assigned to this object, this property will be the lowest value within the humidifying_schedule.

property identifier

Get or set the text string for object identifier.

property properties

Get properties for extensions.

property setpoint_cutout_difference

Get or set the temperature difference between the cutout and the setpoint.

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)