honeybee_energy.schedule.day module

Schedule describing a single day.

class honeybee_energy.schedule.day.ScheduleDay(identifier, values, times=None, interpolate=False)

Bases: object

Schedule for a single day.

Note that a ScheduleDay cannot be assigned to Rooms, Shades, etc. The ScheduleDay must be added to a ScheduleRuleset or a ScheduleRule and then the ScheduleRuleset can be applied to such objects.

Parameters

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

• values – A list of floats or integers for the values of the schedule. The length of this list must match the length of the times list.

• times – A list of ladybug Time objects with the same length as the input values. Each time represents the time of day that the corresponding value begins to take effect. For example [0:00, 9:00, 17:00] in combination with the values [0, 1, 0] denotes a schedule value of 0 from 0:00 to 9:00, a value of 1 from 9:00 to 17:00 and 0 from 17:00 to the end of the day. If this input is None, the default will be a single time at 0:00, indicating the values input should be a single constant value that goes all of the way until the end of the day. Note that these times follow a different convention than EnergyPlus, which uses “time until” instead of “time of beginning”.

• interpolate – Boolean to note whether values in between times should be linearly interpolated or whether successive values should take effect immediately upon the beginning time corresponding to them. Default: False

Properties:

• identifier

• display_name

• times

• values

• interpolate

• is_constant

ToString()

Overwrite .NET ToString.

add_value(value, time)

Add a value to the schedule along with the time it begins to take effect.

Parameters

• value – A number for the schedule value.

• time – The ladybug Time object for the time at which the value begins to take effect.

static average_schedules(identifier, schedules, weights=None, timestep_resolution=1)

Create a ScheduleDay that is a weighted average between other ScheduleDays.

Parameters

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

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

• weights – An optional list of fractional numbers with the same length as the input schedules that sum to 1. These will be used to weight each of the ScheduleDay objects in the resulting average schedule. If None, the individual schedules will be weighted equally.

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

data_collection(date=01 Jan, schedule_type_limit=None, timestep=1)

Get a ladybug DataCollection representing this schedule at a given timestep.

Note that ladybug DataCollections always follow the “Ladybug Tools Interpretation” of date time values as noted in the values_at_timestep documentation.

Parameters

• date – A ladybug Date object for the day of the year the DataCollection is representing. (Default: 1 Jan)

• schedule_type_limit – A ScheduleTypeLimit object that describes the schedule, which will be used to make the header for the DataCollection. If None, a generic “Unknown” type will be used. (Default: None)

• timestep – An integer for the number of steps per hour at which to make the resulting DataCollection.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create a ScheduleDay from a dictionary.

Parameters

data – ScheduleDay dictionary following the format below.

{
"type": 'ScheduleDay',
"identifier": 'Office_Occ_900_1700',
"display_name": 'Office Occupancy',
"values": [0, 1, 0],
"times": [(0, 0), (9, 0), (17, 0)],
"interpolate": False
}

classmethod from_idf(idf_string)

Create a ScheduleDay from an EnergyPlus IDF text string.

Note that this method can accept all 3 types of EnergyPlus Schedule:Day (Schedule:Day:Interval, Schedule:Day:Hourly, and Schedule:Day:List).

Parameters

idf_string – A text string fully describing an EnergyPlus Schedule:Day:Interval.

classmethod from_values_at_timestep(identifier, values, timestep=1, remove_repeated=True)

Make a ScheduleDay from a list of values at a certain timestep.

Parameters

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

• values – A list of numerical values with a length equal to 24 * timestep.

• timestep – An integer for the number of steps per hour that the input values correspond to. For example, if each value represents 30 minutes, the timestep is 2. For 15 minutes, it is 4. Default is 1, meaning each value represents a single hour. Must be one of the following: (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)

• remove_repeated – Boolean to note whether sequentially repeated values should be removed from the resulting values and times comprising the schedule. Default is True, which results in a lighter, more compact schedule. However, you may want to set this to False when planning to set the schedule’s interpolate property to True as this avoids interpolation over long, multi-hour periods.

lock()

remove_value(value_index)

Remove a value from the schedule by its index.

Parameters

value_index – An integer for the index of the value to remove.

remove_value_by_time(time)

Remove a value from the schedule by its time in the times property.

Parameters

time – An ladybug Time for the time and the value to remove.

replace_value(value_index, new_value)

Replace an existing value in the schedule with a new one.

Parameters

• value_index – An integer for the index of the value to replace.

• new_value – A number for the new value to use at the given index.

replace_value_by_time(time, new_value)

Replace an existing value in the schedule using its time.

Parameters

• time – An ladybug Time for the time and the value to replace.

• new_value – A number for the new value to use at the given time.

shift_by_step(step_count=1, timestep=1)

Get a version of this object where the values are shifted in time.

This is useful when attempting to derive a set of diversified schedules from a single average schedule.

Parameters

• step_count – An integer for the number of timesteps at which the schedule will be shifted. Positive values indicate a shift of values forward in time while negative values indicate a shift backwards in time. (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)

to_dict()

ScheduleDay dictionary representation.

to_idf(schedule_type_limit=None)

IDF string representation of ScheduleDay object.

Parameters

schedule_type_limits – Optional ScheduleTypeLimit object, which will be written into the IDF string in order to validate the values within the schedule during the EnergyPlus run.

unlock()

values_at_timestep(timestep=1)

Get a list of sequential schedule values over the day at a given timestep.

Note that there are two possible ways that these values can be mapped to corresponding times (here referred to as the “Ladybug Tools Interpretation” and the “EnergyPlus Interpretation”). Both of these interpretations ultimately refer to the exact same schedule in the calculations of EnergyPlus but the times of day that each of the values are mapped to differ.

Ladybug Tools Interpretation - The first value in the returned list here corresponds to the time 0:00 and the value for this time is applied over the rest of the following timestep. In this way, an office schedule that is set to be occupied from 9:00 until 17:00 will show 9:00 as occupied but 17:00 as unoccupied.

EnergyPlus Interpretation - The first value in the returned list here corresponds to the timestep after 0:00. For example, if the timestep is 1, the time mapped to the first value is 1:00. If the timestep is 6, the first value corresponds to 0:10. In this interpretation, the value for this time is applied over all of the previous timestep. In this way, an office schedule that is set to be occupied from 9:00 until 17:00 will show 9:00 as unoccupied but 17:00 as occupied.

Parameters

timestep – An integer for the number of steps per hour at which to return the resulting values.

VALIDTIMESTEPS = (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60)

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 identifier

Get or set a text string for a unique schedule day identifier.

property interpolate

Get or set a boolean noting whether values should be interpolated.

property is_constant

Boolean noting whether the schedule is representable with a single value.

property times

Get or set the Schedule’s times, which correspond to the numerical values.

property values

Get or set the schedule’s numerical values, which correspond to the times.