Michael Stangl
1e2eedc62b
Tischedatei, XMLdatei_Bestellung, AusgabeTischePersonen and AusgabePersonTisch are no longer configured in platz.cfg. Instead, platz.py now requires a --indir <dir> command-line switch pointing at a directory that must contain tische.ini and bestellung.xml, and into which TischePersonen.txt/PersonenTische.csv are written - e.g. work/test1 or work/test2. This makes it trivial to run against different guest lists without editing platz.cfg. platz.bat/platz.sh forward extra arguments so --indir can be passed through. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
118 lines
4.5 KiB
Markdown
118 lines
4.5 KiB
Markdown
# 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 --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.
|