Kniffel - eine computergestützte Analyse des Würfelklassikers
Ralf Käck <ralf@kaeck.de>, Dominik Kellner <dkellner@dkellner.de>


1. Installation
===============

Das Programm kann unter den gängigen Linux-Distributionen ohne Installation
gestartet werden. Es wird lediglich ein Python-Interpreter
(Version 2.5 oder höher) benötigt. Optional kann die Psyco-Bibliothek
verwendet werden, was die Ausführungsgeschwindigkeiten merklich erhöht.
Die Einbindung des Psyco-Moduls ist aus Kompatibilitätsgründen standardmäßig
auskommentiert. Bitte entfernen Sie die Raute-Zeichen am Anfang der
entsprechenden Zeilen, um Psyco zu aktivieren. Die Zeilen befinden sich jeweils
am Anfang der Quelldateien und sind entsprechend gekennzeichnet.

Anmerkung für Windows-Nutzer:
-----------------------------
Wir konnten das Programm leider nicht unter Windows testen. Abenteuerlustige
dürfen dennoch den Python-Interpreter von http://python.org herunterladen und
die Funktionsfähigkeit unter Windows testen.


2. Berechnung der Resterwartungswerte
=====================================

Das Skript calc_expvals.py berechnet sämtliche Resterwartungswerte des
angegebenen Spielmodus und speichert diese in modes/MODUS.expvals.
Die Bezeichnung des Spielmodus ergibt sich aus dem Dateinamen der zugehörigen
Datei im Ordner modes/, ohne die Dateiendung ".py". Am Ende der Berechnung
wird der Erwartungswert des leeren Blattes ausgegeben.

Beispiele:

Berechnet die Resterwartungen des Standardspiels und speichert diese in
modes/standard.expvals:
> ./calc_expvals.py standard

Vereinfachtes Spiel mit unterdrückter Bildschirmausgabe (Option -q):
> ./calc_expvals.py -q simple

Die Berechnung der Resterwartungen ist notwendig, damit die anderen Skripte
erwartungsgemäß funktionieren.


3. Abfrage eines Resterwartungswertes
=====================================

Mit query_expval.py können vorher berechnete Resterwartungswerte abgefragt
werden. Das Skript erwartet hierzu zwei Argumente: den Spielmodus und die
gewünschte Spielsituation.
Der Spielmodus wird wie bei calc_expvals.py angegeben. Der Situationsschlüssel
muss von Hand berechnet werden. Hierzu finden sich in den Quelldateien der
entsprechenden Spielmodi die Definitionen der Reihen-Konstanten als
2er-Potenzen.

Auszug aus modes/standard.py:
ROW_ONE = 2 ** 6
ROW_TWO = 2 ** 7
ROW_THREE = 2 ** 8
ROW_FOUR = 2 ** 9
ROW_FIVE = 2 ** 10
ROW_SIX = 2 ** 11
ROW_TOAK = 2 ** 12
ROW_FOAK = 2 ** 13
ROW_FHOUSE = 2 ** 14
ROW_SSTRAIGHT = 2 ** 15
ROW_LSTRAIGHT = 2 ** 16
ROW_YAHTZEE = 2 ** 17
ROW_CHANCE = 2 ** 18

Die Situation errechnet sich nun aus der Addition der freien Reihen und dem
Bonus-Wert. Die Resterwartung für "Nur 1er frei, noch keine Bonus-Punkte"
lässt sich demnach wie folgt ausgeben:
> ./query_expval.py standard 64
2.10648148148

Die Situation für das leere Blatt ist beim Standard-Spiel:
2^6 + 2^7 + ... + 2^18 + 0 (Bonus) = 2^19 - 64 = 524224
> ./query_expval.py standard 524224
245.904728371


4. Abfrage der besten Spielweise
================================

best_choice.py dient zur Abfrage der besten Spielweise bei einer gegebenen
Spielsituation, dem gewürfelten Wurf und der Anzahl der bereits verbrauchten
Versuche. Spielmodus und Situation werden wie bei der Abfrage der
Resterwartungswerte angegeben. Der Wurf muss als aufsteigende Folge der
Augenzahlen durch Kommata getrennt übergeben werden. Das letzte Argument
ist eine Ganzzahl, die die Anzahl der bereits verbrauchten Versuche angibt.

Beispiel: Wir haben beim leeren Blatt 11235 gewürfelt und wollen wissen, welche
Würfel wir behalten sollen.
> ./best_choice.py standard 524224 1,1,2,3,5 0
Teilmenge: (5,), Resterwartung: 242.287999


5. Ausführen der automatischen Tests
====================================
Mit `python tests.py` lassen sich die automatischen Tests ausführen. Treten
Fehler während der Ausführung auf, werden diese in der Konsole angezeigt.
Erscheint keine Ausgabe, sind alle Tests fehlerfrei abgelaufen.
