Getting-Started (Dev)

Prerequisites¶

Before setting up the project, make sure the following tools are installed on your system:

1. Install Python 3.10+¶

This project requires Python 3.10 or higher.

Open your terminal (Mac) or Command Prompt (Windows). Check whether and which version of python you have installed by running:

python3 --version

If not installed, download it from the official website: https://www.python.org/downloads/ and install it.

2. Install `uv`¶

uv is a fast Python package manager used to create and manage isolated environments. You can install it following the instructions in the official documentation:

https://docs.astral.sh/uv/getting-started/installation/

3. Install `ODBC Driver`¶

You can install it following the instructions in the official documentation:

Install `Microsoft ODBC Driver 18 for SQL Server` (Windows only)¶

https://learn.microsoft.com/en-us/sql/connect/odbc/

Install `unixodbc` (Mac only)¶

https://pypi.org/project/pyodbc/

Installation¶

Follow these steps to set up the development environment.

1. Download our Project¶

In order to use our application you need to download the code from Github. If you are familiar with Github, you can simply clone the project, if not, you can click on the green "Code" button and choose to download as zip file, which you need to unpack. Then open a command line tool (terminal or command prompt) to navigate to the project folder.

2. Install dependencies¶

Make sure uv is installed.

uv sync

This will install all required dependencies.

2. Set Up Pre-commit Hooks (Only if you want to change something)¶

We use a Git hook called pre-commit which automatically checks and corrects format mistakes in our files. So you need to install Git hooks using pre-commit:

uv run pre-commit install

This enables automatic code checks (e.g., formatting, linting, whitespace trimming) on every commit.

3. Verify Setup¶

To manually run all pre-commit hooks across the entire project:

uv run pre-commit run --all-files

Usage¶

0. Fetching¶

First you would need to fetch the data from the database. For that you need to create a .env file in the root directory, use our template. There you need to define the database credentials, which you should be told by your instructors.

Then you can use the fetch command.

uv run staff-scheduling fetch 77 2024-11-01 2024-11-30

This reads the data from the database from Planungseinheit 77 in November 2024 and creates a folder in cases/.

1. Solving¶

After installing dependencies, you can start solving staff scheduling problems by running

uv run staff-scheduling solve 3 01.11.2024 30.11.2024

The three corresponds to the case_id meaning in the folder cases/3. If you want to create your own case simply copy the folder 3 and rename it to another integer. Then you can change the number of employees etc., see configuration.

The algorithm needs 5 minutes to find a solution.

2. Viewing¶

After the algorithm found a solution you can view it by running

uv run staff-scheduling plot 3

If you have created your own case, you need to change the integer 3 to your new case. You can then view the solution by opening the link you see in the terminal, probably http://127.0.0.1:5020.

Next to the assigned shift, our visualization offers some more insights.

colored small dot: employee is forbidden to work that specific shift (hard)
red background: employee is forbidden to work that day (hard), e.g. vacation day
colored small diamond: employee wishes to have shift corresponding to the color off
brown triangle: employee wished to have the whole day off
green background: wish for specific shift off was granted
yellow background: wish for complete day off was granted