Schedules API Reference

The schedules module provides functions to evaluate EnergyPlus schedules without running a simulation.

Quick Reference

Function/Class	Description
evaluate()	Evaluate a schedule at a specific datetime
values()	Generate values for a date range
to_series()	Convert to pandas Series
plot_schedule()	Quick visualization
get_holidays()	Extract holidays from model

String Parameters

The day_type and interpolation parameters accept strings for convenience:

day_type: "normal", "summer", "winter", "holiday", "customday1", "customday2"

interpolation: "no", "step", "average", "linear"

Core Functions

idfkit.schedules.evaluate

Core schedule evaluation logic.

Provides the main evaluate() and values() functions that dispatch to type-specific evaluators.

MalformedScheduleError

Bases: ScheduleEvaluationError

Raised when a schedule has invalid syntax.

ScheduleEvaluationError

Bases: Exception

Base exception for schedule evaluation errors.

ScheduleReferenceError

Bases: ScheduleEvaluationError

Raised when a referenced schedule cannot be found.

UnsupportedScheduleType

Bases: ScheduleEvaluationError

Raised when a schedule type is not supported.

evaluate(schedule, dt, document=None, day_type=None, fs=None, base_path=None)

Evaluate a schedule at a specific datetime.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object (any supported type).	required
dt	datetime	The datetime to evaluate.	required
document	IDFDocument | None	Required for schedules that reference others (Year, Week). If None, extracted from schedule._document if available.	None
day_type	DayTypeInput | None	Override with design day schedule (for sizing calculations). Accepts "normal", "summer", "winter", "holiday", "customday1", "customday2".	None
fs	FileSystem | None	FileSystem for Schedule:File (default: LocalFileSystem).	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None

Returns:

Type	Description
float	The schedule value as a float.

Raises:

Type	Description
ScheduleEvaluationError	If schedule type is unsupported or malformed.
ScheduleReferenceError	If a referenced schedule cannot be found.

Examples:

>>> evaluate(schedule, datetime(2024, 7, 15, 14, 0))  # Normal evaluation
>>> evaluate(schedule, dt, day_type="summer")  # Summer design day
>>> evaluate(schedule, dt, day_type="winter")  # Winter design day

values(schedule, year=2024, timestep=1, start_date=(1, 1), end_date=(12, 31), document=None, day_type=None, interpolation=None, fs=None, base_path=None)

Generate schedule values for a date range.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year for the date range.	2024
timestep	int	Values per hour (1, 2, 4, 6, 12, or 60).	1
start_date	tuple[int, int]	Start date as (month, day).	(1, 1)
end_date	tuple[int, int]	End date as (month, day).	(12, 31)
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type for all days. Accepts "normal", "summer", "winter", "holiday", "customday1", "customday2".	None
interpolation	InterpolationInput | None	Interpolation mode for sub-hourly values. Accepts "no", "step", "average", "linear".	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None

Returns:

Type	Description
list[float]	List of values, one per timestep for the entire period.

Examples:

>>> values(schedule, year=2024)  # Hourly values for full year
>>> values(schedule, year=2024, timestep=4)  # 15-minute intervals
>>> values(schedule, year=2024, day_type="summer")  # Summer design day

idfkit.schedules.values(schedule, year=2024, timestep=1, start_date=(1, 1), end_date=(12, 31), document=None, day_type=None, interpolation=None, fs=None, base_path=None)

Generate schedule values for a date range.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year for the date range.	2024
timestep	int	Values per hour (1, 2, 4, 6, 12, or 60).	1
start_date	tuple[int, int]	Start date as (month, day).	(1, 1)
end_date	tuple[int, int]	End date as (month, day).	(12, 31)
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type for all days. Accepts "normal", "summer", "winter", "holiday", "customday1", "customday2".	None
interpolation	InterpolationInput | None	Interpolation mode for sub-hourly values. Accepts "no", "step", "average", "linear".	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None

Returns:

Type	Description
list[float]	List of values, one per timestep for the entire period.

Examples:

>>> values(schedule, year=2024)  # Hourly values for full year
>>> values(schedule, year=2024, timestep=4)  # 15-minute intervals
>>> values(schedule, year=2024, day_type="summer")  # Summer design day

Pandas Integration

idfkit.schedules.to_series(schedule, year=2024, freq='h', start_date=(1, 1), end_date=(12, 31), document=None, day_type=None, interpolation=None, fs=None, base_path=None)

Convert a schedule to a pandas Series with DatetimeIndex.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year for the date range.	2024
freq	str	Pandas frequency string ("h" for hourly, "30min", "15min", etc.).	'h'
start_date	tuple[int, int]	Start date as (month, day).	(1, 1)
end_date	tuple[int, int]	End date as (month, day).	(12, 31)
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type ("normal", "summer", "winter", etc.).	None
interpolation	InterpolationInput | None	Interpolation mode ("no", "average", "linear").	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None

Returns:

Type	Description
Any	pandas Series with DatetimeIndex.

Raises:

Type	Description
ImportError	If pandas is not installed.

idfkit.schedules.plot_schedule(schedule, year=2024, start_date=(1, 1), end_date=(12, 31), document=None, day_type=None, fs=None, base_path=None, **plot_kwargs)

Plot a schedule as a time series.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year for the date range.	2024
start_date	tuple[int, int]	Start date as (month, day).	(1, 1)
end_date	tuple[int, int]	End date as (month, day).	(12, 31)
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type ("normal", "summer", "winter", etc.).	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None
**plot_kwargs	Any	Additional arguments passed to pandas Series.plot().	{}

Returns:

Type	Description
Axes	matplotlib Axes object.

Raises:

Type	Description
ImportError	If pandas or matplotlib is not installed.

idfkit.schedules.plot_week(schedule, year=2024, week=1, document=None, day_type=None, fs=None, base_path=None, **plot_kwargs)

Plot a schedule for a single week.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year.	2024
week	int	ISO week number (1-53).	1
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type ("normal", "summer", "winter", etc.).	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None
**plot_kwargs	Any	Additional arguments passed to pandas Series.plot().	{}

Returns:

Type	Description
Axes	matplotlib Axes object.

idfkit.schedules.plot_day(schedule, year=2024, month=1, day=1, document=None, day_type=None, fs=None, base_path=None, **plot_kwargs)

Plot a schedule for a single day.

Parameters:

Name	Type	Description	Default
schedule	IDFObject	An IDF schedule object.	required
year	int	Year.	2024
month	int	Month (1-12).	1
day	int	Day (1-31).	1
document	IDFDocument | None	Required for schedules that reference others.	None
day_type	DayTypeInput | None	Override day type ("normal", "summer", "winter", etc.).	None
fs	FileSystem | None	FileSystem for Schedule:File.	None
base_path	Path | str | None	Base directory for Schedule:File relative paths.	None
**plot_kwargs	Any	Additional arguments passed to pandas Series.plot().	{}

Returns:

Type	Description
Axes	matplotlib Axes object.

Enumerations

idfkit.schedules.DayType

Bases: Enum

Special day type for schedule evaluation.

Used to override the calendar day with a design day schedule, which is useful for sizing calculations.

NORMAL = 'normal' class-attribute instance-attribute

Use calendar day (weekday, weekend, or holiday based on date).

SUMMER_DESIGN = 'summer' class-attribute instance-attribute

Use SummerDesignDay schedule regardless of actual date.

WINTER_DESIGN = 'winter' class-attribute instance-attribute

Use WinterDesignDay schedule regardless of actual date.

HOLIDAY = 'holiday' class-attribute instance-attribute

Treat as holiday regardless of actual date.

CUSTOM_DAY_1 = 'customday1' class-attribute instance-attribute

Use CustomDay1 schedule.

CUSTOM_DAY_2 = 'customday2' class-attribute instance-attribute

Use CustomDay2 schedule.

idfkit.schedules.Interpolation

Bases: Enum

Interpolation mode for schedule values.

Controls how values are computed when the evaluation timestep doesn't align with the schedule's native intervals.

NO = 'no' class-attribute instance-attribute

Step function - value at each interval applies until next interval.

AVERAGE = 'average' class-attribute instance-attribute

Linear interpolation when timestep doesn't align with intervals.

LINEAR = 'linear' class-attribute instance-attribute

Alias for AVERAGE.

Holiday Functions

idfkit.schedules.get_holidays(doc, year)

Get all dates marked as Holiday for a given year.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The IDF document.	required
year	int	Year to get holidays for.	required

Returns:

Type	Description
set[date]	Set of dates that are holidays.

idfkit.schedules.get_special_days_by_type(doc, year, day_type)

Get all dates of a specific day type.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The IDF document.	required
year	int	Year to get dates for.	required
day_type	str	The day type to filter by ("Holiday", "CustomDay1", "CustomDay2").	required

Returns:

Type	Description
set[date]	Set of dates matching the day type.

idfkit.schedules.extract_special_days(doc, year)

Parse all RunPeriodControl:SpecialDays objects from a document.

Parameters:

Name	Type	Description	Default
doc	IDFDocument	The IDF document to extract special days from.	required
year	int	Year to use for date calculations.	required

Returns:

Type	Description
list[SpecialDay]	List of SpecialDay objects representing all special days.

Data Classes

idfkit.schedules.SpecialDay dataclass

A special day period from RunPeriodControl:SpecialDays.

Represents a holiday or custom day type that spans one or more days.

day_type instance-attribute

Day type: "Holiday", "CustomDay1", or "CustomDay2".

duration instance-attribute

Number of days this special day spans.

name instance-attribute

Name of the special day (e.g., "Christmas").

start_date instance-attribute

Start date of the special day period.

contains(d)

Check if a date falls within this special day period.

idfkit.schedules.TimeValue dataclass

A time-value pair for interval schedules.

The value applies from the previous time until this time.

until_time instance-attribute

Time until which the value applies.

value instance-attribute

The schedule value.

idfkit.schedules.CompactDayRule dataclass

A 'For:' block in Schedule:Compact with day types and time-value pairs.

day_types instance-attribute

Day types this rule applies to (e.g., {"Weekdays", "Weekends"}).

time_values instance-attribute

Time-value pairs defining the schedule for these days.

idfkit.schedules.CompactPeriod dataclass

A 'Through:' block in Schedule:Compact covering a date range.

day_rules instance-attribute

Day rules within this period.

end_day instance-attribute

End day of the period (1-31).

end_month instance-attribute

End month of the period (1-12).

contains(d)

Check if a date falls within this period.

Periods implicitly start from January 1 or the end of the previous period. This method only checks the end boundary.

File Support

idfkit.schedules.ScheduleFileCache

Cache for Schedule:File CSV data.

Caches parsed CSV data to avoid repeated file I/O when evaluating the same schedule multiple times.

__init__()

Initialize an empty cache.

clear()

Clear the cache.

get_values(obj, fs, base_path=None)

Get cached values or read from file.

Parameters:

Name	Type	Description	Default
obj	IDFObject	The Schedule:File object.	required
fs	FileSystem	FileSystem for reading the file.	required
base_path	Path | str | None	Base directory for resolving relative paths.	None

Returns:

Type	Description
list[float]	List of schedule values from the file.

invalidate(path)

Invalidate all cache entries whose key starts with path.

Parameters:

Name	Type	Description	Default
path	str | Path	File path to invalidate. All entries for this file (regardless of column / separator settings) are removed.	required

Exceptions

idfkit.schedules.ScheduleEvaluationError

Bases: Exception

Base exception for schedule evaluation errors.

idfkit.schedules.UnsupportedScheduleType

Bases: ScheduleEvaluationError

Raised when a schedule type is not supported.

idfkit.schedules.ScheduleReferenceError

Bases: ScheduleEvaluationError

Raised when a referenced schedule cannot be found.

idfkit.schedules.MalformedScheduleError

Bases: ScheduleEvaluationError

Raised when a schedule has invalid syntax.