Occupancy#

smart_control.simulator.randomized_arrival_departure_occupancy #

A randomized occupancy model for the building simulation.

In this model, N occupants arrive between the earliest and latest arrival hour and depart between the earliest and latest departure hour. The probability of departure is specified so that the expected arrival and departure times occur halfway in the interval. For a standard Bernoulli RV, E[X] = n*p, so p = E[X] / n / 2, where E[X] is the expected number of arrivals, which equals 1.

RandomizedArrivalDepartureOccupancy #

RandomizedArrivalDepartureOccupancy(
    zone_assignment: int,
    earliest_expected_arrival_hour: int,
    latest_expected_arrival_hour: int,
    earliest_expected_departure_hour: int,
    latest_expected_departure_hour: int,
    time_step_sec: int,
    seed: Optional[int] = 17321,
    time_zone: str = "UTC",
)

Bases: BaseOccupancy

Provides the RL agent information about how many people are in a zone.

Attributes:

Name	Type	Description
`zone_assignment`		number of occupants in a zone
`earliest_expected_arrival_hour`		earliest arrivel, 0 - 22
`latest_expected_arrival_hour`		latest arrivel, 1 - 23
`earliest_expected_departure_hour`		earliest departure, 0 - 22
`latest_expected_departure_hour`		latest departure, 1 - 23
`seed`		integer used to set the random state for repeatability

average_zone_occupancy #

average_zone_occupancy(
    zone_id: str, start_time: Timestamp, end_time: Timestamp
) -> float

Returns the occupancy within start_time, end_time for the zone.

If the zone is not found, implementations should raise a ValueError.

Parameters:

Name	Type	Description	Default
`zone_id`	`str`	specific zone identifier for the building.	required
`start_time`	`Timestamp`	local time w/ TZ for the beginning of the interval.	required
`end_time`	`Timestamp`	local time w/ TZ for the end of the interval.	required

Returns:

Type	Description
`float`	average number of people in the zone for the interval.

ZoneOccupant #

ZoneOccupant(
    earliest_expected_arrival_hour: int,
    latest_expected_arrival_hour: int,
    earliest_expected_departure_hour: int,
    latest_expected_departure_hour: int,
    step_size: Timedelta,
    random_state: RandomState,
    time_zone: Union[tzinfo, str] = "UTC",
)

Represents a single occupant in a zone.

Attributes:

Name	Type	Description
`earliest_expected_arrival_hour`		earliest arrivel, 0 - 22
`latest_expected_arrival_hour`		latest arrivel, 1 - 23
`earliest_expected_departure_hour`		earliest departure, 0 - 22
`latest_expected_departure_hour`		latest departure, 1 - 23
`random_state`		random state used to generate events

peek #

peek(current_time: Timestamp) -> OccupancyStateEnum

Returns the state (WORK or AWAY) of the occupant for the current_time.

smart_control.simulator.step_function_occupancy #

A very basic occupancy model for smart buildings smart control.

Occupancy is the average number of people in a zone during a specific interval.

Occupancy is an input to the RL agent reward function.

This implementation assumes

(a) all zones have the same occupancy patterns. (b) the occupancy is constant for work periods, and (c) the occupancy is constant for non-work periods (off hours, weekends and holidays).

StepFunctionOccupancy #

StepFunctionOccupancy(
    work_start_time: Timedelta,
    work_end_time: Timedelta,
    work_occupancy: float,
    nonwork_occupancy: float,
)

Bases: BaseOccupancy

An occupancy model with constant level for work and non-work times.

This model ignores the specific zone and returns the same value for all zones.

Attributes:

Name	Type	Description
`work_start_time`		time-of-day when work period starts
`work_end_time`		time-of-day when work period ends
`work_occupancy`		avg number of people in zone during work times
`nonwork_occupancy`		avg number of people in zone during non-work times

average_zone_occupancy #

average_zone_occupancy(
    zone_id: str, start_time: Timestamp, end_time: Timestamp
) -> float

Returns the occupancy within start_time, end_time for the zone.

This model applies a constant for work time and non-work times, and returns a weighted average. Evaluates weekends and holidays as non-working times.

Ignores the zone - assumes each zone is equally occupied.

Parameters:

Name	Type	Description	Default
`zone_id`	`str`	specific zone identifier for the building.	required
`start_time`	`Timestamp`	local time w/o TZ for the beginning of the interval.	required
`end_time`	`Timestamp`	local time w/o TZ for the end of the interval.	required

Returns:

Type	Description
`float`	average number of people in the zone for the interval.

smart_control.simulator.stochastic_occupancy #

A stochastic occupancy model for building simulation.

This model simulates the behavior of occupants in a building by defining arrival, departure, and lunch break times based on random sampling. Each zone is assigned a specified number of occupants, and their schedules are generated using cumulative probability functions (CPFs) to ensure realistic variability.

For each occupant, arrival and departure times are sampled within defined earliest and latest bounds. Lunch break times and durations are also generated stochastically. The model determines whether an occupant is present in the work zone or away at any given time, accounting for work hours, lunch breaks, and holidays.

The LIGHTSWITCHOccupancy class calculates the average occupancy for a zone over a specified time interval, enabling integration with larger building simulation frameworks.

Debugging features are included to provide insights into sampling and state transition processes when debug_print is enabled.

LIGHTSWITCHOccupancy #

LIGHTSWITCHOccupancy(
    zone_assignment: int,
    earliest_expected_arrival_hour: int,
    latest_expected_arrival_hour: int,
    earliest_expected_departure_hour: int,
    latest_expected_departure_hour: int,
    lunch_start_hour: int = 12,
    lunch_end_hour: int = 14,
    time_step_sec: int = 3600,
    seed: Optional[int] = 511211,
    time_zone: str = "UTC",
)

Bases: BaseOccupancy

Light Switch Occupancy.

Calculates the average occupancy for a zone over a specified time interval, enabling integration with larger building simulation frameworks.

average_zone_occupancy #

average_zone_occupancy(
    zone_id: str, start_time: Timestamp, end_time: Timestamp
) -> float

Calculates the average occupancy within a time interval for a zone.

Parameters:

Name	Type	Description	Default
`zone_id`	`str`	specific zone identifier for the building.	required
`start_time`	`Timestamp`	local time with TZ for the beginning of the interval.	required
`end_time`	`Timestamp`	local time with TZ for the end of the interval.	required

Returns:

Type	Description
`float`	Average number of people in the zone for the interval.

ZoneOccupant #

ZoneOccupant(
    earliest_expected_arrival_hour: int,
    latest_expected_arrival_hour: int,
    earliest_expected_departure_hour: int,
    latest_expected_departure_hour: int,
    lunch_start_hour: int,
    lunch_end_hour: int,
    step_size: Timedelta,
    random_state: RandomState,
    time_zone: Union[tzinfo, str] = "UTC",
)

Zone Occupant.

peek #

peek(current_time: Timestamp) -> OccupancyStateEnum

Checks the current occupancy state based on the provided timestamp.

This method determines the occupancy state (AWAY or WORK) based on the current time, considering workdays, arrival/departure times, and a lunch break.

Parameters:

Name	Type	Description	Default
`current_time`	`Timestamp`	The current timestamp to evaluate.	required

Returns:

Type	Description
`OccupancyStateEnum`	The current `OccupancyStateEnum` (AWAY or WORK).