Events

The scheduler reacts to different events throughout the night allowing him to emulate the behavior that could happen if the telescope is shutdown or a rapid ToO is activated.

The following are the types of events that are currently handle by the scheduler:

Base event

`scheduler.core.events.queue.Event(site, time, description)`

Bases: UUIDIdentified, ABC

Superclass for all events. They contain:

ATTRIBUTE	DESCRIPTION
`site`	The site at which the event occurred. TYPE: `Site`
`time`	The time at which the event occurred. TYPE: `datetime`
`description`	A human-readable description of the event. TYPE: `str`

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

Abstract events

These events are general purpose events that describe a non-specific behavior in the night.

`scheduler.core.events.queue.RoutineEvent(site, time, description)`

Bases: Event, ABC

A routine event that is predictable and processed by the Scheduler. Examples include evening and morning twilight.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.InterruptionEvent(site, time, description)`

Bases: Event, ABC

Parent class for any interruption that might cause a new schedule to be created. These events include:

Events that have no specified end time (e.g. weather changes).
Events that have a specified end time (e.g. engineering tasks, faults) and thus are paired together with an InterruptionResolutionEvent.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

Twilight events

They marked the start and end of the night. Without them the event cycle won't start and the final plan can't be created.

`scheduler.core.events.queue.TwilightEvent(site, time, description)`

Bases: RoutineEvent, ABC

An event indicating that the 12 degree starting twilight for a night has been reached.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.EveningTwilightEvent(site, time, description)`

Bases: TwilightEvent

An event indicating that the 12 degree starting twilight for a night has been reached.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.MorningTwilightEvent(site, time, description)`

Bases: TwilightEvent

An event indicating that the 12 degree morning twilight for a night has been reached. This is used to finalize the time accounting for the night.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

Interruption and Resolution events

Are all the events that might interrupt the current plan and might trigger a different plan with different conditions. Some interruptions create a lasting effect that might be resolved later in the night.

`scheduler.core.events.queue.WeatherChangeEvent(site, time, description, variant_change)`

Bases: InterruptionEvent

Interruption that occurs when new a new weather variant comes in.

ATTRIBUTE	DESCRIPTION
`variant_change`	The variant snapshot that changed. TYPE: `VariantSnapshot`

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.ToOActivationEvent(site, time, description, too_id)`

Bases: InterruptionEvent

Change the status of a ToO from ON_HOLD to READY.

ATTRIBUTE	DESCRIPTION
`too_id`	The observation ID for the ToO that was activated. TYPE: `ObservationID`

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.FaultEvent(site, time, description, affects)`

Bases: InterruptionEvent

Interruption that occurs when there is a fault in a resource. In OCS, this will likely be the site itself where the fault occurred.

ATTRIBUTE	DESCRIPTION
`affects`	Resource affected for the fault. TYPE: `FrozenSet[Resource]`

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.WeatherClosureEvent(site, time, description)`

Bases: InterruptionEvent

A weather closure for a given site. This will be treated like a FaultEvent, but the "affects" Resource will be the entire site.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`scheduler.core.events.queue.InterruptionResolutionEvent(uuid_identified, site, time, description)`

Bases: Event, UUIDReferenced, ABC

A class representing the resolution of an interruption that can be resolved (e.g. a resolved fault or the end of an engineering task.)

These events, signifying the end of a period of time, can be used to generate a time loss.

`time_loss`

Calculate the time loss from this InterruptionEvent to this InterruptionEventResolution as a timedelta.

TO DO

TODO: This assumes that Interruption events are notified or processed at Twilight (or near) situation that might TODO: be completely different when Resource is implemented and real input is processed.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`time_slot_loss(time_slot_length)`

Given the length of a time slot, calculate the number of time slots lost from the InterruptionEvent to this InterruptionEventResolution.

PARAMETER	DESCRIPTION
`time_slot_length`	The length of the time slot to calculate the number of time slots lost. TYPE: `timedelta`

RETURNS	DESCRIPTION
`int`	The number of time slots lost from the Interruption. TYPE: `int`

`scheduler.core.events.queue.FaultResolutionEvent(uuid_identified, site, time, description)`

Bases: InterruptionResolutionEvent, UUIDReferenced

Interruption that occurs when a Fault is resolved.

`time_loss`

Calculate the time loss from this InterruptionEvent to this InterruptionEventResolution as a timedelta.

TO DO

TODO: This assumes that Interruption events are notified or processed at Twilight (or near) situation that might TODO: be completely different when Resource is implemented and real input is processed.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`time_slot_loss(time_slot_length)`

Given the length of a time slot, calculate the number of time slots lost from the InterruptionEvent to this InterruptionEventResolution.

PARAMETER	DESCRIPTION
`time_slot_length`	The length of the time slot to calculate the number of time slots lost. TYPE: `timedelta`

RETURNS	DESCRIPTION
`int`	The number of time slots lost from the Interruption. TYPE: `int`

`scheduler.core.events.queue.WeatherClosureResolutionEvent(uuid_identified, site, time, description)`

Bases: InterruptionResolutionEvent, UUIDReferenced

Interruption that occurs when a WeatherClosure is resolved.

`time_loss`

Calculate the time loss from this InterruptionEvent to this InterruptionEventResolution as a timedelta.

TO DO

TODO: This assumes that Interruption events are notified or processed at Twilight (or near) situation that might TODO: be completely different when Resource is implemented and real input is processed.

`to_timeslot_idx(twi_eve_time, time_slot_length)`

Given an event, calculate the timeslot offset it falls into relative to another datetime. This would typically be the twilight of the night on which the event occurs, hence the name twi_eve_time.

PARAMETER	DESCRIPTION
`twi_eve_time`	Evening twilight time. TYPE: `datetime`
`time_slot_length`	Set time slot length in which the Scheduler work. TYPE: `timedelta`

RETURNS	DESCRIPTION
`TimeslotIndex`	The timeslot offset relative to the twilight. TYPE: `TimeslotIndex`

`time_slot_loss(time_slot_length)`

Given the length of a time slot, calculate the number of time slots lost from the InterruptionEvent to this InterruptionEventResolution.

PARAMETER	DESCRIPTION
`time_slot_length`	The length of the time slot to calculate the number of time slots lost. TYPE: `timedelta`

RETURNS	DESCRIPTION
`int`	The number of time slots lost from the Interruption. TYPE: `int`

Event Queue

The Event Queue allows the scheduler to keep all events ordered chronologically. This is separated in two: One that compromises all the nights and sites and one that is specific for a night.

`scheduler.core.events.queue.EventQueue(night_indices, sites)`

`get_night_events(night_idx, site)`

Returns the sorted list for the site for the night index if it exists, else None.

`scheduler.core.events.queue.NightEventQueue(night_idx, site)`

Event Cycle

Encapsulates all the behavior the events can be affected through the night and pass the event to be process by the Change Monitor and controls when the time accounting and the plans creation happens.

`scheduler.core.events.cycle.EventCycle(params, queue, scp)`

ATTRIBUTE	DESCRIPTION
`params`	Scheduler parameters TYPE: `SchedulerParams`
`queue`	Event queue that orders the events chronologically TYPE: `EventQueue`
`scp`	The Scheduler Core Pipeline that allows creating plans. TYPE: `SCP`

`run(site, night_idx, nightly_timeline)`

Executes the Event cycle for a specific site and night.

PARAMETER	DESCRIPTION
`site`	Site to process events from the night. TYPE: `Site`
`night_idx`	Night to process events from. TYPE: `NightIndex`
`nightly_timeline`	Records all the events and their corresponding plans. TYPE: `NightlyTimeline`

RAISES	DESCRIPTION
`RuntimeError`	If required events are missing

Change Monitor

Matches the event with their specific behavior. These are usually modifications to both Collector and Selector.

`scheduler.core.components.changemonitor.ChangeMonitor(collector, selector)`

Bases: SchedulerComponent

Triggers different changes caused by events in the Scheduler components

ATTRIBUTE	DESCRIPTION
`collector`	Collector instance when observations need to be updated or changed their Status. TYPE: `Collector`
`selector`	Selector instance when weather conditions are modified. TYPE: `Selector`

`__post_init__()`

Create the blocking event set for each site.

`is_site_unblocked(site)`

Check if a site is unblocked.

PARAMETER	DESCRIPTION
`site`	Site to check. TYPE: `Site`

RETURNS	DESCRIPTION
`bool`	True if the given site is NOT blocked by one or more events that need to be resolved before the site can have a plan, and False if the site is blocked. TYPE: `bool`

`process_event(site, event, plans, night_idx)`

Given an event occurring at a given site and an optional plan running on the site, determine the next timeslot where the plan should be recalculated, if any.

The plan is optional, because for EveningTwilightEvent, no plan has yet been computed and thus None should be passed in.

If the ChangeMonitor determines that a new plan should be calculated, then a timeslot index indicating when the plan should be calculated is returned, and if no new plan should be calculated, then None is returned.

PARAMETER	DESCRIPTION
`site`	the site at which the event occurred TYPE: `Site`
`event`	the event that occurred TYPE: `Event`
`plans`	the plans that are currently in action (if any) for the night, which consist of a plan per site TYPE: `Plans`
`night_idx`	the night index TYPE: `NightIdx`

TO DO

TODO: Might want to make return type a Tuple[NightIndex, TimeslotIndex].

RETURNS	DESCRIPTION
`TimeCoordinateRecord`	a time coordinate record which provides information about when the next plan should be computed (if any), if a night is done, and if time accounting should be performed TYPE: `Optional[TimeCoordinateRecord]`

The Change Monitor gives updates to the Event Cycle through Time Coordinate Record so the cycle knows which updates are needed after that event.

`scheduler.core.components.changemonitor.TimeCoordinateRecord(event, timeslot_idx, perform_time_accounting=True, done=False)`

Time coordinate record calculated for an event.

ATTRIBUTE	DESCRIPTION
`event`	the event for which this time coordinate record holds TYPE: `Event`
`timeslot_idx`	the timeslot index for which the plan should be recalculated TYPE: `Optional[TimeslotIndex]`
`perform_time_accounting`	True if time accounting should be performed, and False to suppress time accounting TYPE: `bool`
`done`	True if the night is done, and False otherwise TYPE: `bool`