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 --env-file .env 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 fetching data, solve the scheduling problem for the same planning unit and date range:

uv run staff-scheduling solve 77 01.11.2024 30.11.2024

This writes solution files to found_solutions/ and uses the fetched case data in cases/77/11_2024/.

2. Viewing¶

Preferred workflow: use StaffSchedulingWeb to inspect solutions in a browser UI. See Web Interface.

Legacy local viewer (optional):

uv run staff-scheduling plot 77

Then open the shown URL in your browser (usually http://127.0.0.1:5020).