Scheduler Module

Clinic scheduling and resource allocation management.

This module implements a scheduler for managing clinic appointments with capacity constraints and automatic rescheduling. It supports configurable daily capacity and working days per week.

Classes

ClinicScheduler

Manages appointment scheduling with capacity constraints

Key Features

  • Daily capacity limits

  • Configurable clinic days per week

  • Automatic rescheduling when capacity exceeded

  • Weekend/holiday handling

  • Appointment tracking

Examples

>>> scheduler = ClinicScheduler(daily_capacity=20, days_per_week=5)
>>> event = Event(time=datetime(2023,1,1), ...)
>>> if not scheduler.request_slot(event, end_date=datetime(2023,12,31)):
...     print("Visit needs rescheduling")

Notes

  • Time values should be timezone-naive datetimes

  • Capacity checks are performed per calendar day

  • Rescheduling maintains original appointment details

class simulation.scheduler.ClinicScheduler(daily_capacity, days_per_week)[source]

Bases: object

Manages clinic scheduling and resource allocation.

This class handles the scheduling of patient visits while respecting clinic capacity constraints. It supports configurable daily patient capacity and working days per week, with automatic rescheduling when capacity is exceeded.

Parameters:

  • daily_capacity (int) – Maximum number of patients that can be seen per day

  • days_per_week (int) – Number of clinic days per week (e.g., 5 for Mon-Fri)

Variables:

  • daily_capacity (int) – Maximum patients per day

  • days_per_week (int) – Working days per week

  • daily_slots (Dict[datetime, int]) – Tracks number of appointments for each date

  • rescheduled_visits (int) – Counter for number of rescheduled appointments

__init__(daily_capacity, days_per_week)[source]
Parameters:

  • daily_capacity (int)

  • days_per_week (int)

request_slot(event, end_date)[source]

Check if there’s capacity for a visit on the requested day.

Verifies if the requested visit can be accommodated on the specified day, considering both clinic working days and daily capacity constraints.

Parameters:

  • event (Event) – Event containing visit details including requested time

  • end_date (datetime) – Simulation end date for rescheduling bounds

Returns:

True if slot is available, False if needs rescheduling

Return type:

bool

Examples

>>> event = Event(time=datetime(2023,1,1), ...)
>>> if scheduler.request_slot(event, end_date=datetime(2023,12,31)):
...     print("Slot available")
... else:
...     print("Visit needs rescheduling")

Notes

  • Automatically initializes tracking for new dates

  • Handles non-clinic days (e.g., weekends) by rescheduling

  • Updates appointment counts when slot is granted

  • Rescheduling maintains original appointment details

  • Time values should be timezone-naive datetimes

The algorithm follows these steps:

  1. Check if requested date is a clinic day

  2. Initialize slot count if new date

  3. Check daily capacity

  4. If no capacity or non-clinic day, trigger rescheduling

  5. If capacity available, increment count and return True

schedule_next_visit(event_factory, patient_id, last_visit, next_visit_interval)[source]
No-index:

Parameters:

  • event_factory (Callable)

  • patient_id (str)

  • last_visit (datetime)

  • next_visit_interval (int)

Return type:

Event | None

Schedule the next visit for a patient.

Creates a new visit event for a patient based on their last visit and the specified interval.

Parameters:

  • event_factory (Callable) – Function to create visit events with signature: (time: datetime, event_type: str, patient_id: str, data: dict) -> Event

  • patient_id (str) – Patient identifier

  • last_visit (datetime) – Time of the last visit

  • next_visit_interval (int) – Number of weeks until the next visit (must be positive)

Returns:

Scheduled visit event, or None if beyond simulation end

Return type:

Optional[Event]

Raises:

ValueError – If next_visit_interval is not positive

Examples

>>> next_visit = scheduler.schedule_next_visit(
...     event_factory=create_visit_event,
...     patient_id="123",
...     last_visit=datetime(2023,1,1),
...     next_visit_interval=4
... )

Notes

  • Maintains the same time of day as the original appointment

  • Handles week-to-day conversion automatically

  • Returns None if calculated visit would be after simulation end

  • Visit intervals must be positive integers