honeybee_energy.schedule.ruleset module

Complete annual schedule object built from ScheduleDay and rules for applying them.

class honeybee_energy.schedule.ruleset.ScheduleRuleset(identifier, default_day_schedule, schedule_rules=None, schedule_type_limit=None, holiday_schedule=None, summer_designday_schedule=None, winter_designday_schedule=None)[source]

Bases: object

A complete schedule assembled from ScheduleDay and ScheduleRules.

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.

  • default_day_schedule – A ScheduleDay object that will be used for all days where there is no ScheduleRule applied.

  • schedule_rules – A list of ScheduleRule objects that note exceptions to the default_day_schedule. These rules should be ordered from highest to lowest priority.

  • schedule_type_limit – A ScheduleTypeLimit object that will be used to validate schedule values against upper/lower limits and assign units to the schedule values. If None, no validation will occur.

  • summer_designday_schedule – A ScheduleDay object that will be used for the summer design day (used to size the cooling system).

  • winter_designday_schedule – A ScheduleDay object that will be used for the winter design day (used to size the heating system).

  • holiday_schedule – A ScheduleDay object that will be used for holidays.

Properties:

  • identifier

  • display_name

  • default_day_schedule

  • schedule_rules

  • schedule_type_limit

  • summer_designday_schedule

  • winter_designday_schedule

  • holiday_schedule

  • day_schedules

  • typical_day_schedules

  • is_constant

  • is_single_week

  • user_data

ToString()[source]

Overwrite .NET ToString.

add_rule(rule)[source]

Add a ScheduleRule to this ScheduleRuleset.

Note that adding a rule here will add it as highest priority in the full list of schedule_rules, meaning it may overwrite other rules underneath it.

Parameters:

rule – A ScheduleRule object to be added to this ScheduleRuleset. ScheduleRule objects note the exceptions to the default_day_schedule.

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

Create a ScheduleRuleset that is a weighted average between ScheduleRulesets.

Parameters:

  • identifier – Text string for a unique ID for the new unique ScheduleRuleset. 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 ScheduleRuleset objects that will be averaged together to make a new ScheduleRuleset.

  • 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 ScheduleRuleset 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(timestep=1, start_date=01 Jan, end_date=31 Dec, start_dow='Sunday', holidays=None, leap_year=False)[source]

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 ScheduleDay.values_at_timestep documentation.

Parameters:

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

  • start_date – An optional ladybug Date object for when to start the DataCollection. Default: 1 Jan.

  • end_date – An optional ladybug Date object for when to end the DataCollection. Default: 31 Dec.

  • start_dow – An optional text string for the starting day of the week. Default: Sunday.

  • holidays – An optional list of ladybug Date objects for the holidays. For any holiday in this list, schedule rules set to apply_holiday will take effect.

  • leap_year – Boolean to note whether the generated values should be for a leap year (True) or a non-leap year (False). Default: False.

duplicate()[source]

Get a copy of this object.

static extract_all_from_idf_file(idf_file, import_compact=False)[source]

Extract all ScheduleRuleset objects from an EnergyPlus IDF file.

Parameters:

  • idf_file – A path to an IDF file containing objects for Schedule:Year and corresponding Schedule:Week and Schedule:Day objects. The Schedule:Year will be used to assemble all of these into a ScheduleRuleset.

  • import_compact – Boolean to note whether to parse Schedule:Compact (True) or not (False). Default: False.

Returns:

schedules – A list of all Schedule:Year objects in the IDF file as honeybee_energy ScheduleRuleset objects.

classmethod from_constant_value(identifier, value, schedule_type_limit=None)[source]

Create a ScheduleRuleset fromm a single constant value.

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.

  • value – A single constant value to be applied throughout the whole year.

  • schedule_type_limit – A ScheduleTypeLimit object that will be used to validate schedule values against upper/lower limits and assign units to the schedule values.

classmethod from_daily_values(identifier, daily_values, timestep=1, schedule_type_limit=None)[source]

Create a ScheduleRuleset from a list of repeating daily values at a 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.

  • daily_values – A list of [24 * timestep] numbers for schedule values.

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

  • schedule_type_limit – A ScheduleTypeLimit object that will be used to validate schedule values against upper/lower limits and assign units to the schedule values.

classmethod from_dict(data)[source]

Create a ScheduleRuleset from a dictionary.

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

Parameters:

data – ScheduleRuleset dictionary following the format below.

{
"type": 'ScheduleRuleset',
"identifier": 'Office_Occ_900_1700_weekends',
"display_name": 'Office Occupancy',
"day_schedules": [], # Array of ScheduleDay dictionary representations
"default_day_schedule": str, # ScheduleDay identifier
"schedule_rules": [], # list of ScheduleRuleAbridged dictionaries
"schedule_type_limit": {}, # ScheduleTypeLimit dictionary representation
"holiday_schedule": str, # ScheduleDay identifier
"summer_designday_schedule": str, # ScheduleDay identifier
"winter_designday_schedule": str # ScheduleDay identifier
}
classmethod from_dict_abridged(data, schedule_type_limits)[source]

Create a ScheduleRuleset from an abridged dictionary.

Parameters:

  • data – ScheduleRulesetAbridged dictionary.

  • schedule_type_limits – A dictionary with identifiers of schedule type limits as keys and Python schedule type limit objects as values.

{
"type": 'ScheduleRulesetAbridged',
"identifier": 'Office_Occ_900_1700_weekends',
"display_name": 'Office Occupancy',
"day_schedules": [], # Array of ScheduleDay dictionary representations
"default_day_schedule": str, # ScheduleDay identifier
"schedule_rules": [], # list of ScheduleRuleAbridged dictionaries
"schedule_type_limit": str, # ScheduleTypeLimit identifier
"holiday_schedule": str, # ScheduleDay identifier
"summer_designday_schedule": str, # ScheduleDay identifier
"winter_designday_schedule": str # ScheduleDay identifier
}
classmethod from_idf(year_idf_string, week_idf_strings, day_idf_strings, type_idf_string=None)[source]

Create a ScheduleRuleset from an EnergyPlus IDF text strings.

Parameters:

  • year_idf_string – A text string fully describing an EnergyPlus Schedule:Year.

  • week_idf_strings – A list of text strings for all of the Schedule:Week objects used in the Schedule:Year.

  • day_idf_strings – A list of text strings for all of the Schedule:Day objects used in the week_idf_strings.

  • type_idf_string – An optional text string for the ScheduleTypeLimits. If None, the resulting schedule will have no ScheduleTypeLimit.

classmethod from_idf_constant(idf_string, type_idf_string=None)[source]

Create a ScheduleRuleset from an EnergyPlus Schedule:Constant string.

Parameters:

  • idf_string – A text string fully describing an EnergyPlus Schedule:Constant.

  • type_idf_string – An optional text string for the ScheduleTypeLimits. If None, the resulting schedule will have no ScheduleTypeLimit.

classmethod from_week_daily_values(identifier, sunday_values, monday_values, tuesday_values, wednesday_values, thursday_values, friday_values, saturday_values, holiday_values, timestep=1, schedule_type_limit=None, summer_designday_values=None, winter_designday_values=None)[source]

Create a ScheduleRuleset from lists of daily values for each day of the week.

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.

  • sunday_values – A list of [24 * timestep] numerical values for Sundays.

  • monday_values – A list of [24 * timestep] numerical values for Mondays.

  • tuesday_values – A list of [24 * timestep] numerical values for Tuesdays.

  • wednesday_values – A list of [24 * timestep] numerical values for Wednesdays.

  • thursday_values – A list of [24 * timestep] numerical values for Thursdays.

  • friday_values – A list of [24 * timestep] numerical values for Fridays.

  • saturday_values – A list of [24 * timestep] numerical values for Saturdays.

  • holiday_values – A list of [24 * timestep] numerical values for Holidays.

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

  • schedule_type_limit – A ScheduleTypeLimit object that will be used to validate schedule values against upper/lower limits and assign units to the schedule values. (Default: None).

  • summer_designday_values – A list of [24 * timestep] numerical values for the summer design day. If None, the daily schedule with the highest average value will be used unless the schedule_type_limit has a Temperature unit_type, in which case it will be the daily schedule with the lowest average value. (Default: None).

  • winter_designday_values – A list of [24 * timestep] numerical values for the winter design day. If None, the daily schedule with the lowest average value will be used unless the schedule_type_limit has a Temperature unit_type, in which case it will be the daily schedule with the highest average value. (Default: None).

classmethod from_week_day_schedules(identifier, sunday_schedule, monday_schedule, tuesday_schedule, wednesday_schedule, thursday_schedule, friday_schedule, saturday_schedule, holiday_schedule, summer_designday_schedule, winter_designday_schedule, schedule_type_limit=None)[source]

Create a ScheduleRuleset from ScheduleDay objects for each day of the week.

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.

  • sunday_schedule – A ScheduleDay for Sundays.

  • monday_schedule – A ScheduleDay for Mondays.

  • tuesday_schedule – A ScheduleDay for Tuesdays.

  • wednesday_schedule – A ScheduleDay for Wednesdays.

  • thursday_schedule – A ScheduleDay for Thursdays.

  • friday_schedule – A ScheduleDay for Fridays.

  • saturday_schedule – A ScheduleDay for Saturdays.

  • holiday_schedule – A ScheduleDay for Holidays.

  • summer_designday_schedule – A ScheduleDay for the summer design day.

  • winter_designday_schedule – A ScheduleDay for the winter design day.

  • schedule_type_limit – A ScheduleTypeLimit object that will be used to validate schedule values against upper/lower limits and assign units to the schedule values.

lock()[source]

The lock() method also locks the ScheduleDay and ScheduleRule objects.

remove_rule(rule_index)[source]

Remove a ScheduleRule from the schedule by its index in schedule_rules.

Parameters:

rule_index – An integer for the index of the rule to remove.

reorder_rule(rule_index, new_index=0)[source]

Change the priority of a ScheduleRule in the full schedule_rules list.

Lower indices (ordered first) in the schedule_rules indicate the rule has a higher priority.

Parameters:

  • rule_index – An integer for the index of the rule to reorder.

  • new_index – An integer for the new index of the rule. The default is 0, which will re-insert the selected rule at the top of the priority list.

shift_by_step(step_count=1, timestep=1)[source]

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

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(abridged=False)[source]

Schedule Ruleset 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 identifier of the ScheduleTypeLimit. Default: False.

to_idf()[source]

IDF string representation of the schedule.

Note that this method only outputs Schedule:Year and Schedule:Week objects (or a Schedule:Constant object if applicable). However, to write the full schedule into an IDF, the schedules’s day_schedules must also be written as well as the ScheduleTypeLimit object.

The method is set up this way primarily to give better control over the export process. For example, you usually want to see if there are other schedules in a model using the same ScheduleTypeLimit object and then write it into the IDF only once rather than writing it multiple times for each schedule that references it. ScheduleDay objects can often follow a similar logic where the same ScheduleDay objects are used by multiple ScheduleRulesets.

Returns:

A tuple with two elements

  • year_schedule: Text string representation of the Schedule:Year describing this schedule. This will be a Schedule:Constant if this schedule can be described as such.

  • week_schedules: A list of Schedule:Week:Daily test strings that are referenced in the year_schedule. Will be None when year_schedule is a Schedule:Constant.

Schedule:Year,
    test_name,               !- Name
    'Availability',          !- Schedule Type Limits Name
    avail_schedge1,          !- Schedule:Week Name 1
    1,                       !- Start Month 1
    1,                       !- Start Day 1
    12,                      !- End Month 1
    31;                      !- End Day 1
to_rules(start_date, end_date)[source]

Get all of rules needed to implement this ScheduleRuleset over a date range.

This is useful when you want to apply this entire ScheduleRuleset over a particular time period of another ScheduleRuleset.

Parameters:

  • start_date – A ladybug Date object for the start of the period that rules should be obtained.

  • end_date – A ladybug Date object for the end of the period that rules should be obtained.

unlock()[source]

The unlock() method also unlocks the ScheduleDay and ScheduleRule objects.

values(timestep=1, start_date=01 Jan, end_date=31 Dec, start_dow='Sunday', holidays=None, leap_year=False)[source]

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

Note that there are two possible ways that these values can be mapped to corresponding times. See the ScheduleDay.values_at_timestep method documentation for a complete description of these two interpretations.

Parameters:

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

  • start_date – An optional ladybug Date object for when to start the list of values. Default: 1 Jan.

  • end_date – An optional ladybug Date object for when to end the list of values. Default: 31 Dec.

  • start_dow – An optional text string for the starting day of the week. Default: Sunday.

  • holidays – An optional list of ladybug Date objects for the holidays. For any holiday in this list, schedule rules set to apply_holiday will take effect.

  • leap_year – Boolean to note whether the generated values should be for a leap year (True) or a non-leap year (False). Default: False.

property day_schedules

Get a list of all unique ScheduleDay objects used in this ScheduleRuleset.

property default_day_schedule

Get or set the DaySchedule object that will be used by default.

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 holiday_schedule

Get or set the DaySchedule that will be used for holidays.

Note that, if this property is None, the default_day_schedule is ultimately written into the IDF for the holidays.

property identifier

Get or set the text string for schedule unique identifier.

property is_constant

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

property is_single_week

Boolean noting whether this schedule is representable with one week schedule.

property properties

Get properties for extensions.

property schedule_rules

Get or set an array of ScheduleRules that note exceptions to the default.

These rules are ordered from highest priority to lowest priority meaning that, if two rules cover the same date range and day of the week, the rule that comes first in this list will take precedence. Following this logic, you typically want rules that only apply for part of a year to precede rules that are applied over the whole year. This way, the schedule over the whole year doesn’t overwrite the partial-year schedule underneath it.

property schedule_type_limit

Get or set a ScheduleTypeLimit object used to assign units to schedule values.

property summer_designday_schedule

Get or set the DaySchedule that will be used for the summer design day.

Note that, if this property is None, the default_day_schedule is ultimately written into the IDF for the summer design day.

property typical_day_schedules

Get a list of all unique ScheduleDay objects used over the annual run period.

This excludes the schedules of the design days and the holiday schedule, which gives a sense of the typical schedule over the year.

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 winter_designday_schedule

Get or set the DaySchedule that will be used for the winter design day.

Note that, if this property is None, the default_day_schedule is ultimately written into the IDF for the winter design day.