# 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 2 code** (print statements, `ConfigParser`, `sets.Set`, `UserList`,
`string.split`, old-style `raise Exception, "msg"`, `xrange`, `dict.has_key`,
`dict.iteritems`). 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)
└── 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`).

## 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
```

```bash
# Linux/macOS
source bin/activate_venv.sh
bin/platz.sh
```

`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`.

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

`cfg/platz.cfg` selects which cycle/penalty config and which working directory
(`work/<name>/`) to use for a given run:

```ini
[Config]
Zyklusdatei=$PLATZ_CFG/zyklus.cfg
Zyklusart=Easy
Strafendatei=$PLATZ_CFG/strafen.cfg
Tischedatei=$PLATZ_WORK/test1/tische.ini
XMLdatei_Bestellung=$PLATZ_WORK/test1/bestellung.xml
AusgabeTischePersonen=$PLATZ_WORK/test1/TischePersonen.txt
AusgabePersonTisch=$PLATZ_WORK/test1/PersonenTische.csv
```

To run against a different dataset, point the `Tischedatei`/`XMLdatei_Bestellung`/output
entries at another `work/<name>/` folder, or add a new one following the same layout:

- `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.

`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 configured working 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.