platz/README.md

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:

   :: Windows
   bin\install_py.bat
   

   # 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

:: Windows
bin\activate_venv.bat
bin\platz.bat

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

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