GA Scheduling Optimizer

A genetic algorithm-based scheduling optimizer designed for practitioners (such as healthcare providers, consultants, or service professionals) who manage multiple clients. The system optimizes appointment scheduling by considering both practitioner availability and client constraints, maximizing bookings while respecting configurable rules like buffer times, appointment durations, and frequency limits.

The optimizer takes practitioner and client schedule data as input, runs a genetic algorithm to evolve optimal booking arrangements, and outputs an optimized weekly schedule along with a waitlist of clients who couldn't be accommodated. It can be accessed via a REST API or command-line interface, with Docker support for easy deployment.

Architecture

flowchart LR
    subgraph Input
        P[Practitioner Data<br/>- Work schedule<br/>- Booking durations<br/>- Buffer times]
        C[Client Data<br/>- Availability<br/>- Treatment duration<br/>- Frequency limits]
    end

    subgraph Processing
        SM[Schedule Manager]
        SE[Solution Executor]
        GA[PyGAD Genetic Algorithm<br/>100 generations<br/>20 population size]
    end

    subgraph Output
        B[Optimized Bookings]
        W[Waitlist]
    end

    P --> SM
    C --> SM
    SM --> SE
    SE <--> GA
    GA --> B
    GA --> W

Loading

Key Features

• Practitioner Constraints: Configurable work schedules, available booking durations, and buffer times between appointments
• Client Constraints: Weekly availability windows, ideal treatment duration, preferred frequency, and monthly booking limits
• Genetic Algorithm Optimization: Binary GA using PyGAD with steady-state selection to evolve optimal schedules
• Multiple Interfaces: REST API (FastAPI) and CLI (Typer) for flexible integration
• Docker Support: Containerized deployment ready

---

Environment Requirements

The required python version is 3.8.

It is strongly recommended to use PyCharm as the IDE for this project.

VsCode is alright, however, you will have to do more setup since scripts aren't made yet.

Important Notes

The algorithm is timezone-aware, and assumes that all times provided are in UTC in 24 hour format.

Setup

Virtual Environment

Be sure to set up a virtual environment before installing the required packages.

PyCharm --> has a built-in virtual environment manager.

CLI --> run the following command in the root directory of the project:

python3 -m venv .venv
source .venv/bin/activate

Required Packages

PyCharm --> Navigate to the requirements.txt file and install.

CLI --> Run the following command in the root directory of the project to install the required packages

pip install -r /path/to/requirements.txt

Package Installation

Install the schedulizer package by running the following command in the root directory of the project:

pip install -e .

Running the Application

PyCharm --> Run via configuration

CLI --> Run the following command in the root directory of the project:

python test/main.py

Project Structure

The project structure is as follows:

/GA_Optimizer
    /config --> any configuration setup
    /api --> any code that interacts with external services (ie. database, API)
    /data --> any data files that are used in the project
    /schedulizer --> core library consisting of optimizer, models, and utilities
        /optimizer --> optimization algorithm entry point via fitness.py
    /test --> any type of automated or manual testing (ie. main.py)
 

Running an Optimization from CLI

For an example of what the input data should look like, refer to the test/sample_input directory.

To see all the available options for running an optimization, run the following command in the root directory of the project:

python schedulizer/optimizer/fitness.py --help

To run an optimization from the CLI, run the following command in the root directory of the project:

python schedulizer/optimizer/fitness.py \
  --practitioner-data-path "path to json file of practitioner data" \
  --patient-data-path "path to json file of patient data"

Here is an example input:

python schedulizer/optimizer/fitness.py \
  --practitioner-data-path "./test/sample_input/practitioner_input_sample.json" \
  --patient-data-path "./test/sample_input/patients_input_sample.json"

The patient-data-path is an optional field to allow for easier testing. If the patient-data-path is not provided, then we generate num_random_patients patient schedules. This functionality requires debug-mode to be enabled, Example:

python schedulizer/optimizer/fitness.py \
  --practitioner-data-path "./test/sample_input/practitioner_input_sample.json" \
  --debug-mode

Running Optimizer from API

To run the optimizer from the API in dev mode, run the following command in the root directory of the project:

fastapi dev api/main.py

Or run with uvicorn (recommended):

uvicorn --port 80 api.main:app --reload

See the API documentation at http://localhost:8000/docs or http://localhost:8000/redoc

Build Docker Image

To build the docker image, run the following command in the root directory of the project:

docker build -t gaSchedulizerImage .

Run the image:

docker run -d --name gaSchedulizerContainer -p 80:80 gaSchedulizerImage

See the API documentation at http://localhost:80/docs or http://localhost:80/redoc

Building a Distribution

Note that you likely won't need to do this anymore and should instead make a docker image. Do this only if you want to install the application as a CLI tool

Have pythons build tool installed

pip install build

Build a distribution from the root directory of the project

python -m build

This generates a distribution within the dist directory.

You can install this distribution by running the following command:

Note that it is good to set up a test virtual environment instead of installing it in the current environment

pip install dist/schedulizer-<version_num>.tar.gz

Be sure to sub out the <version_num> with the respective version number of the distribution.

Testing Optimizer CLI Distribution

Run the helper script from the root directory:

./create_and_test_distribution.sh