# platz

A genetic-algorithm-based solver that assigns people to tables ("Tische") for an event,
given group memberships, table sizes/neighbor relationships, and a configurable penalty
scheme. It reads a guest list (XML) and a table layout (INI), searches for a good seating
using a small custom GA framework, and writes the result to text/CSV output files.

**This is Python 3 code** (migrated from an original Python 2 implementation). There are no
third-party dependencies (standard library only), so `requirements.txt` is empty — it
exists only so `bin/install_py` has something to install.

## Project structure

```
platz/
├── bin/           # environment + launcher scripts (.bat + .sh pairs)
├── cfg/           # GA cycle definition and penalty scheme
├── libs/          # the two Python modules (ga.py, Strukturdaten.py, platz.py)
├── tests/         # unittest suite for Strukturdaten.py
└── work/          # per-run input (table layout, guest list) and output
    ├── test1/
    └── test2/
```

- `libs/platz.py` — entry point; wires together config, input data, and the GA run.
- `libs/ga.py` — generic genetic-algorithm scaffolding (`Loesung`, `Zyklus`, `Farm`).
- `libs/Strukturdaten.py` — domain model for the seating problem (`Person`, `Gruppe`,
  `Tisch`, `Strafliste`, `Sitzplatzverteilung`, `XMLConfig`).

## Running the tests

```bash
python -m unittest discover -s tests -p "test_*.py" -v
```

If a stray global `PYTHONPATH` entry shadows the standard-library `tests` package name
(unrelated to this project), clear it for the command, e.g. `PYTHONPATH= python -m
unittest discover -s tests -p "test_*.py" -v`.

## Setup

1. Install a Python interpreter (`py` on Windows / `python3` on Linux/macOS must be on
   `PATH`).
2. Run the installer for your platform to create a `.venv` and install `requirements.txt`:

   ```bat
   :: Windows
   bin\install_py.bat
   ```

   ```bash
   # Linux/macOS
   bin/install_py.sh
   ```

All `bin/` scripts derive `PLATZ` automatically from their own location (no path editing
required) by calling `setenv.bat`/`setenv.sh` first.

## Running

```bat
:: Windows
bin\activate_venv.bat
bin\platz.bat --indir work\test1
```

```bash
# Linux/macOS
source bin/activate_venv.sh
bin/platz.sh --indir work/test1
```

`bin/platz.bat` / `bin/platz.sh` call `setenv` to set `PLATZ`, `PLATZ_CFG`, `PLATZ_LIBS`,
`PLATZ_WORK`, `PLATZ_IN`, `PLATZ_OUT`, add `PLATZ_LIBS` to `PYTHONPATH`, and then run
`libs/platz.py`, forwarding any extra arguments (like `--indir`) to it.

Other helper scripts (`bin/setenv.*`, `bin/get_cmd.*`) follow the same environment
convention:

- `setenv` — sets all `PLATZ_*` environment variables and creates missing folders; sourced
  by every other script, not normally called directly.
- `activate_venv` — activates the `.venv` created by `install_py`.
- `get_cmd` — opens a new shell with the `PLATZ_*` environment already set.

### Configuring a run

`--indir <dir>` is required and points at a directory containing the input files and
receiving the output files for one run — e.g. `work/test1/` or `work/test2/`:

- `tische.ini` — one section per table: `Nummer`, `Hof` (venue/court), `Plaetze` (seat
  count), `Nachbarliste` (neighboring table ids), `Koordinaten`.
- `bestellung.xml` — `<Gruppe>` blocks, each with a `<Person>` template
  (`Vorname`/`Nachname`/optional `Titel`) and an `<Anzahl>` (how many bookings to expand
  that template into). A `<Gruppe>` containing a `<Tisch>` tag is treated as a VIP group
  pinned to that table instead of being placed by the GA.

To run against a different dataset, create a new folder with a `tische.ini` and
`bestellung.xml` following the same layout and pass it via `--indir`.

`cfg/platz.cfg` still selects the GA cycle/penalty config (independent of `--indir`):

```ini
[Config]
Zyklusdatei=$PLATZ_CFG/zyklus.cfg
Zyklusart=Easy
Strafendatei=$PLATZ_CFG/strafen.cfg
```

`cfg/zyklus.cfg` defines the GA run schedule ("Zyklus") as an `Abfolge` (sequence of
actions) and matching `Anzahl` (counts): `e` create, `s` select best, `S` select randomly,
`m` mutate, `j` keep parents, `z` advance generation.

`cfg/strafen.cfg` defines the penalty scheme: cost of splitting a group across tables (by
group size and number of splits), cost of a person sitting alone or without a group-mate at
a neighboring table, and per-table seat-utilization penalties.

### Output

A run writes two files into the `--indir` directory:

- `TischePersonen.txt` — table → seated people, with venue/table/seat numbers.
- `PersonenTische.csv` — person → table, sorted alphabetically by name.

## Further details

See `CLAUDE.md` for a deeper architectural walkthrough of the GA framework and domain
model, intended for AI coding assistants but equally useful for human contributors.