honeybee_energy.schedule.fixedinterval module

Annual schedule defined by a list of values at a fixed interval or timestep.

class honeybee_energy.schedule.fixedinterval.ScheduleFixedInterval(identifier, values, schedule_type_limit=None, timestep=1, start_date=01 Jan, placeholder_value=0, interpolate=False)[source]

Bases: object

An annual schedule defined by a list of values at a fixed interval or 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 values occurring at a fixed interval over the simulation. Typically, this should be a list of 8760 values for each hour of the year but it can be a shorter list if you don’t plan on using it in an annual simulation. In this case, the start_date should probably be different than the default 1 Jan (it should instead be the start date of your simulation). This list can also have a length much greater than 8760 if a timestep greater than 1 is used.

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

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

  • start_date – A ladybug Date object to note when the input values begin to take effect. Default is 1 Jan for a non-leap year. Note that this default usually should not be changed unless you plan to run a simulation that is much shorter than a year and/or you plan to run the simulation for a leap year.

  • placeholder_value – A value that will be used for all times not covered by the input values. Typically, your simulation should not need to use this value if the input values completely cover the simulation period. However, a default value may still be necessary for EnergyPlus to run. Default: 0.

  • interpolate – Boolean to note whether values in between intervals 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

  • values

  • schedule_type_limit

  • timestep

  • start_date

  • placeholder_value

  • interpolate

  • end_date_time

  • is_leap_year

  • is_constant

  • data_collection

  • user_data

ToString()[source]

Overwrite .NET ToString.

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

Get a ScheduleFixedInterval that’s a weighted average between other schedules.

Parameters:

  • identifier – A unique ID text string for the new unique ScheduleFixedInterval. 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 ScheduleFixedInterval objects that will be averaged together to make a new ScheduleFixedInterval. This list may also contain ScheduleRulesets but it is recommend there be at least one ScheduleFixedInterval. Otherwise, the ScheduleRuleset.average_schedules method should be used.

  • 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 ScheduleFixedInterval objects in the resulting average schedule. If None, the individual schedules will be weighted equally.

data_collection_at_timestep(timestep=1, start_date=01 Jan, end_date=31 Dec)[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 on a non-leap year.

  • end_date – An optional ladybug Date object for when to end the DataCollection. Default: 31 Dec on a non-leap year.

duplicate()[source]

Get a copy of this object.

static extract_all_from_idf_file(idf_file)[source]

Extract all ScheduleFixedInterval objects from an EnergyPlus IDF file.

Parameters:

idf_file – A path to an IDF file containing objects for Schedule:File which should have correct file paths to CSVs storing the schedule values.

Returns:

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

classmethod from_dict(data)[source]

Create a ScheduleFixedInterval from a dictionary.

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

Parameters:

data – ScheduleFixedInterval dictionary following the format below.

{
"type": 'ScheduleFixedInterval',
"identifier": 'Awning_Transmittance_X45NF23U',
"display_name": 'Automated Awning Transmittance',
"values": [], # list of numbers for the values of the schedule
"schedule_type_limit": {}, # ScheduleTypeLimit dictionary representation
"timestep": 1, # Integer for the timestep of the schedule
"start_date": (1, 1), # Date dictionary representation
"placeholder_value": 0, # Number for the values out of range
"interpolate": False # Boolean noting whether to interpolate between values
}
classmethod from_dict_abridged(data, schedule_type_limits)[source]

Create a ScheduleFixedInterval from an abridged dictionary.

Parameters:

  • data – ScheduleFixedIntervalAbridged dictionary with format below.

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

{
"type": 'ScheduleFixedIntervalAbridged',
"identifier": 'Awning_Transmittance_X45NF23U',
"display_name": 'Automated Awning Transmittance',
"values": [], # list of numbers for the values of the schedule
"schedule_type_limit": "", # ScheduleTypeLimit identifier
"timestep": 1, # Integer for the timestep of the schedule
"start_date": (1, 1), # Date dictionary representation
"placeholder_value": 0, # Number for the values out of range
"interpolate": False # Boolean noting whether to interpolate between values
}
classmethod from_idf(idf_string, type_idf_string=None)[source]

Create a ScheduleFixedInterval from an EnergyPlus IDF text strings.

Parameters:

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

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

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

Get a version of this object where the 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]

ScheduleFixedInterval 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(schedule_directory, include_datetimes=False)[source]

IDF string representation of the schedule.

Note that this method does both the production of the IDF string representation of the Schedule:File as well as the actual writing of the schedule to a CSV format that can be read in by EnergyPlus.

Parameters:

  • schedule_directory – [Required] Text string of a path to a folder on this machine to which the CSV version of the file will be written.

  • include_datetimes – Boolean to note whether a column of datetime objects should be written into the CSV alongside the data. Default is False, which will keep the resulting CSV lighter in file size but you may want to include such datetimes in order to verify that values align with the expected timestep. Note that the included datetimes will follow the EnergyPlus interpretation of aligning values to timesteps in which case the timestep to which the value is matched means that the value was utilized over all of the previous timestep.

Returns:

schedule_file – Text string representation of the Schedule:File describing this schedule.

Schedule:File,
    elecTDVfromCZ01res, !- Name
    Any Number,         !- ScheduleType
    TDV_kBtu_CTZ01.csv, !- Name of File
    2,                  !- Column Number
    4,                  !- Rows to Skip at Top
    8760,               !- Number of Hours of Data
    Comma;              !- Column Separator
static to_idf_collective_csv(schedules, schedule_directory, file_name, include_datetimes=False)[source]

Write several ScheduleFixedIntervals into the same CSV file and get IDF text.

This method is useful when several ScheduleFixedInterval objects are serving a similar purpose and the data would be more easily managed if they all were in the same file.

Parameters:

  • schedules – A list of ScheduleFixedInterval objects to be written into the same CSV.

  • schedule_directory – [Required] Text string of a full path to a folder on this machine to which the CSV version of the file will be written.

  • file_name – Text string for the name to be used for the CSV file that houses all of the schedule data.

  • include_datetimes – Boolean to note whether a column of datetime objects should be written into the CSV alongside the data. Default is False, which will keep the resulting CSV lighter in file size but you may want to include such datetimes in order to verify that values align with the expected timestep.

Returns:

schedule_files – A list of IDF text string representations of the Schedule:File describing this schedule.

to_idf_compact()[source]

IDF string representation of the schedule as a Schedule:Compact.

Schedule:Compact strings contain all of the schedule values and can be written directly into IDF files. So they are sometimes preferable to Schedule:Files objects when it’s important that all simulation data be represented in a single IDF file. However, such a representation of the schedule often prevents the IDF from being read by programs such as the IDFEditor and it can increase the overall size of the schedule in the resulting files by an order of magnitude.

unlock()
values_at_timestep(timestep=1, start_date=None, end_date=None)[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:

  • The EnergyPlus interpretation that uses “time until”

  • The Ladybug Tools interpretation that uses “time of beginning”

The EnergyPlus interpretation should be used when aligning the schedule with EnergyPlus results while the Ladybug Tools interpretation should be used when aligning the schedule with ladybug DataCollections or other ladybug objects. 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 with a leap year equal to self.start_date.

  • end_date – An optional ladybug Date object for when to end the list of values. Default: 31 Dec with a leap year equal to self.start_date.

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

DataCollection of schedule values at this schedule’s start_date and timestep.

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 end_date_time

Get a ladybug DateTime object for the end time of the schedule’s values.

property identifier

Get or set the text string for unique schedule 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 is_leap_year

Get a boolean noting whether the schedule is over a leap year.

Note that this property originates from the leap_year property on the input start_date.

property placeholder_value

Get or set the value to be used for all times not covered by the input values.

property properties

Get properties for extensions.

property schedule_type_limit

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

property start_date

Get the ladybug Date object noting when the the input values take effect.

property timestep

Get the integer for the schedule’s number of steps per hour.

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 values

Get or set the schedule’s numerical values, which occur at a fixed interval.