1 files changed, 52 insertions, 0 deletions
diff --git a/doc/alphametiken.md b/doc/alphametiken.md
new file mode 100644
index 0000000..de06565
--- /dev/null
+++ b/doc/alphametiken.md
@@ -0,0 +1,52 @@
+Alphametiken
+============
+
+Das Programm ist in zwei Teile gegliedert:
+
+* `löse(zu_lösendes_Alphametikum)` gibt eine Liste mit allen Lösungen eines Alphametikums in dem Format `[['Rechnung', {'Buchstabe': zugehörige_Zahl, ...}], ...]` zurück (zum Beispiel `[['8928-3164=5764', {'Ü': 9, 'F': 8, 'W': 7, 'N': 2, 'Z': 5, 'I': 4, 'E': 6, 'D': 3, 'R': 1}]]` für `FÜNF-DREI=ZWEI`).
+
+* `generiere(Länge)` gibt ein Alphametikum als String zurück (zum Beispiel `FÜNF-DREI=ZWEI`), für welches mindestens eine Lösung vorhanden ist.
+
+Alphametikum lösen
+------------------
+
+Die Funktion `ersetze`, aufgerufen durch `löse`, ersetzt jeweils den ersten Buchstaben im Alphametikum durch eine Zahl, nacheinander 0 bis 9. Für den Rest des Alphametikum-Strings wird die Funktion rekursiv aufgerufen. Ist der letzte Buchstabe ersetzt, wird mithilfe von Pythons `eval`-Funktion überprüft, ob die ersetzten Zahlen zu einer wahren Gleichung führen. Ist dies der Fall, wird die gefundene Lösung in einer Liste festgehalten und nach Überprüfen aller Kombinationen zurückgegeben.
+Der Ausnahmefall, dass die Lösung eine Null als erste Ziffer einer Zahl hat, wird durch einen regulären Ausdruck `re.search` überprüft. Um gleiche Zahlen nicht an mehrere Buchstaben zu verteilen wird in der rekursiven Funktion die Liste an bereits verwendeten Zahlen mitgegeben.
+
+Beispiel für eine Lösung:
+```
+>>> import alphametiken
+>>> alphametiken.löse("SEND + MORE = MONEY")
+[['9567 + 1085 = 10652', {'O': 0, 'N': 6, 'M': 1, 'E': 5, 'Y': 2, 'S': 9, 'D': 7, 'R': 8}]]
+```
+
+Alphametikum finden
+-------------------
+
+Zum Finden von Alphametiken in der Form `FÜNF-DREI=ZWEI` ist es zuerst nötig, eine valide Gleichung - hier `5-3=2` zu finden. Um dies für eine beliebige Länge zu tun, wird in der Funktion `generiere` ein Template erstellt, in dem `_` dann durch ein zufälliges Rechenzeichen, `x` und `y` durch eine zufällige Zahl von 0-9 ersetzte wird, sodass bei einer Länge von 1 dieses Schema entsteht:
+```
+x_x=y
+```
+das nun auf Richtigkeit, wieder durch `eval`, geprüft wird. Eine Gleichung wie `5-3=2` wird schließlich mithilfe von Zahlwörtern abgebildet: `FÜNF-DREI=ZWEI`. Jetzt wird mit `löse` geprüft, ob eine Lösung vorhanden ist. Wenn ja, endet die Funktion, sonst wird nach einer neuen Gleichung gesucht.
+`random.choice` und `random.randrange` dienen hier zum Finden zufälliger Rechenzeichen und Zahlen.
+
+
+Beispiel für ein Alphametikum mit mehr als 20 Zeichen:
+```
+>>> import alphametiken
+>>> alphametiken.generiere(3)
+'FÜNF-ZWEI+VIER-ZWEI=FÜNF'
+>>> alphametiken.löse('FÜNF-ZWEI+VIER-ZWEI=FÜNF')
+...
+['9589-3102+6204-3102=9589', {'Z': 3, 'V': 6, 'I': 2, 'Ü': 5, 'R': 4, 'E': 0, 'N': 8, 'F': 9, 'W': 1}]
+...
+>>> alphametiken.generiere()
+'SECHS-VIER=ZWEI'
+>>> alphametiken.löse('SECHS-VIER=ZWEI')
+[['12051-3427=8624', {'H': 5, 'W': 6, 'E': 2, 'Z': 8, 'I': 4, 'S': 1, 'C': 0, 'R': 7, 'V': 3}],
+>>> alphametiken.generiere(2)
+'ACHT-ZWEI-DREI=DREI'
+>>> alphametiken.löse('ACHT-ZWEI-DREI=DREI')
+[['4567-2389-1089=1089', {'T': 7, 'A': 4, 'W': 3, 'E': 8, 'Z': 2, 'I': 9, 'H': 6, 'C': 5, 'D': 1, 'R': 0}],
+...
+```