edit names of variables and technical docs

Author: martinsimsa

mastermind-testing-algorithms.py

@@ -96,13 +96,13 @@ def higher_is_better(first, second):
 # Vraci mnoziny potomku vzhledem k danemu kodu a velikosti techto mnozin
 def create_next_partition(next_guess, possible_codes, len_pegs, len_colours, all_scores):
     partition_table = [0]*len(all_scores)
-    partition_of_codes = [[] for i in range(len(all_scores))]
+    partition = [[] for i in range(len(all_scores))]
     for code in possible_codes:
         temp_score = evaluate_codes(code, next_guess, len_pegs, len_colours)
         index_of_temp_score = all_scores.index(temp_score)
         partition_table[index_of_temp_score] += 1
-        partition_of_codes[index_of_temp_score].append(code)
-    return partition_table, partition_of_codes
+        partition[index_of_temp_score].append(code)
+    return partition_table, partition
 
 
 # Nalezne nejlepsi pokus pro dany stav, valuaci a strategii, vraci tento pokus, velikosti mnozin potomku a mnoziny potomku
@@ -112,52 +112,52 @@ def find_best_guess(possible_codes, len_pegs, len_colours, all_scores, all_codes
         best_partition_table_value = -1
     else:
         best_partition_table_value = len(possible_codes)
-    best_partition:list[int] = []
+    best_partition_table:list[int] = []
     best_next_guess = -1
-    best_partition_with_codes = []
+    best_partition = []
     # Pokud je mnozina kandidatu jednoprvkova, vraci jediny kod
     if len(possible_codes) == 1:
-        return possible_codes[0], best_partition, best_partition_with_codes
+        return possible_codes[0], best_partition_table, best_partition
     # Overeni krajniho pripadu
     elif len(possible_codes) == 0:
         return [], [], []
     # Vyber prvniho tahu, v pripade, ze je urceny prvni tah, algoritmus jej vybere
     elif len(possible_codes) == len_colours**len_pegs and start_code != None:
-        temp_partition_table, partition_of_codes = create_next_partition(start_code, possible_codes, len_pegs, len_colours, all_scores)
+        temp_partition_table, temp_partition = create_next_partition(start_code, possible_codes, len_pegs, len_colours, all_scores)
         temp_partition_table_value = partition_table_function(temp_partition_table)
         # Zapsani do hodnot na vystupu
-        best_partition = temp_partition_table
+        best_partition_table = temp_partition_table
         best_next_guess = start_code
-        best_partition_with_codes = partition_of_codes
+        best_partition = temp_partition
     # V pripade vyberu pouze z kandidatu
     elif choose_from_candidates == True:
         for code in possible_codes:
-            temp_partition_table, partition_of_codes = create_next_partition(code, possible_codes, len_pegs, len_colours, all_scores)
+            temp_partition_table, temp_partition = create_next_partition(code, possible_codes, len_pegs, len_colours, all_scores)
             temp_partition_table_value = partition_table_function(temp_partition_table)
             # v kazde iteraci porovnavame valuaci s aktualni nejlepsi hodnotou, protoze vybirame kod s nejvyssi nebo nejnizsi valuaci
             if compare_function(temp_partition_table_value, best_partition_table_value):
                 best_partition_table_value = temp_partition_table_value
-                best_partition = temp_partition_table
+                best_partition_table = temp_partition_table
                 best_next_guess = code
-                best_partition_with_codes = partition_of_codes
+                best_partition = temp_partition
     # V obecnem pripade vybirame dalsi kod z celeho prostoru kodu
     else:
         for code in all_codes:
-            temp_partition_table, partition_of_codes = create_next_partition(code, possible_codes, len_pegs, len_colours, all_scores)
+            temp_partition_table, temp_partition = create_next_partition(code, possible_codes, len_pegs, len_colours, all_scores)
             temp_partition_table_value = partition_table_function(temp_partition_table)
             if compare_function(temp_partition_table_value, best_partition_table_value):
                 best_partition_table_value = temp_partition_table_value
-                best_partition = temp_partition_table
+                best_partition_table = temp_partition_table
                 best_next_guess = code
-                best_partition_with_codes = partition_of_codes
+                best_partition = temp_partition
             # V pripade, ze vice kodu nabyva nejlepsi strategie chceme prednostne vybrat kod z mnoziny kandidatu
             if temp_partition_table_value == best_partition_table_value and (best_next_guess not in possible_codes) and (code in possible_codes):
                 best_partition_table_value = temp_partition_table_value
-                best_partition = temp_partition_table
+                best_partition_table = temp_partition_table
                 best_next_guess = code
-                best_partition_with_codes = partition_of_codes
+                best_partition = temp_partition
 
-    return best_next_guess, best_partition, best_partition_with_codes
+    return best_next_guess, best_partition_table, best_partition
 
 
 # Vraci vysledky algoritmu, pro kazdy stav hleda nejlepsi dalsi pokus a tim prochazi strom daneho algoritmu
@@ -224,14 +224,14 @@ def solve_one_game(len_pegs, len_colours, secret_code, partition_table_function,
     # Dokud neni tajny kod uhodnut
     while score != [len_pegs,0]:
         len_guesses +=1
-        next_guess, next_partition, best_partition_with_codes = find_best_guess(possible_codes, len_pegs, len_colours, all_scores, all_codes, partition_table_function, compare_function, start_code, choose_from_candidates)
+        next_guess, next_partition_table, best_partition = find_best_guess(possible_codes, len_pegs, len_colours, all_scores, all_codes, partition_table_function, compare_function, start_code, choose_from_candidates)
         b,w = evaluate_codes(secret_code, next_guess, len_pegs, len_colours)
         print(next_guess, b, w)
         score = [b,w]
         # pokud hra neni dohrana, je aktualizovana mnozina kandidatu po tomto kole hry
         if score != [len_pegs,0]:
             score_index = all_scores.index([b,w])
-            possible_codes = best_partition_with_codes[score_index]
+            possible_codes = best_partition[score_index]
     return len_guesses
 
 
@@ -252,8 +252,8 @@ def get_valuation_of_first_guess(len_pegs, len_colours, start_code, partition_ta
 
     # Testuje algoritmy s pevně daným prvním pokusem
     # get_results_of_algorithm(len_pegs, len_colours, [1,1,2,2], find_max, lower_is_better, False)
-    get_results_of_algorithm(len_pegs, len_colours, [1,1,2,2], find_entropy, higher_is_better, False)
-    # get_results_of_algorithm(len_pegs, len_colours, [1,1,2,3], find_number_of_parts, higher_is_better, False)
+    # get_results_of_algorithm(len_pegs, len_colours, [1,2,3,4], find_entropy, higher_is_better, False)
+    get_results_of_algorithm(len_pegs, len_colours, [1,1,2,3], find_number_of_parts, higher_is_better, False)
 
 
     # Spustí algoritmus pro daný tajný kód

technical-docs.md

@@ -1,55 +1,83 @@
 # Technická dokumentace
-Tohle je technická dokumentace programu Mastermind - testování algoritmů
+Tohle je technická dokumentace programu Mastermind - testování algoritmů. Byla vytvořena jako příloha k bakalářské práci Logik - algoritmy a strategie. 
 
 ## Obsah
 Dokumentace obsahuje popisy jednotlivých funkcí a jejich propojení. 
 - [Process](#installation)
-- [Functions](#functions)
-- [main_function](#main_function)
-- [Global variables]
+- [Proměnné](#proměnné)
+- [Funkce](#funkce)
+
+## Proměnné
+len_pegs - označuje počet pozic, v bakalářské práci tuto hodnotu značíme písmenem $n$.
+
+len_colours - určuje počet barev (v práci jako $k$).
+
+all_scores - seznam všech ohodnocení v $H_{n,k}$
+
+all_codes - seznam všech kódů $H_{n,k}$
+
+start_code - volba prvního pokusu, aby algoritmus nemusel procházet všechny kódy
+
+possible_codes - Množina kandidátů aktuálního stavu.
+
+partition - Množina potomků aktuální množiny kandidátů
+
+partition_table - Velikosti množin potomků množiny kandidátů
+
+secret_code - tajný kód
+
+partition_table_function - proměnná uchovávající aktuálně používanou valuaci (find_max, find_entropy, find_number_of_parts)
+
+compare_function - proměnná uchovávající aktuálně používanou strategii (higher_is_better, lower_is_better)
+
+choose_from_candidates - proměnná, která udává, zda algoritmus vybírá kódy pro další pokusy pouze z množiny kandidátů (True), anebo z celého prostoru kódů (False)
+
+partition_table_value - uchovává hodnotu valuace pro danou množinu kandidátů a kód.
+
 
 ## Funkce
 
 #### evaluate_codes
-Funkce evaluate_codes na vstupu dostane dva kódy a počet pozic a barev. Vrátí ohodnocení těchto dvou kódů. Nejprve spočítá počet černých kolíčků a pčty výskytů barev v obou kódech. Následně vypočítá počet bílých kolíčků podle definice ohodnocení. 
+Funkce evaluate_codes na vstupu dostane dva kódy a počet pozic a barev. Vrátí ohodnocení těchto dvou kódů. Nejprve spočítá počet černých kolíčků a počty výskytů barev v obou kódech. Následně vypočítá počet bílých kolíčků podle definice ohodnocení. 
 
 #### generate_all_codes
-Funkce generate_all_codes vygeneruje seznam všech kódů podle zadaného počtu pozic a počtu barev. Prochází všechna čísla od nuly do k^n - 1 a každé číslo konvertuje do kódu, který v lexikografickém pořadí odpovídá danému číslu. 
+Funkce generate_all_codes vygeneruje seznam všech kódů podle zadaného počtu pozic a počtu barev. Prochází všechna čísla od nuly do $k^n - 1$ a každé číslo konvertuje do kódu, který v lexikografickém pořadí odpovídá danému číslu. 
 
 #### generate_all_scores
 Tato funkce vygeneruje seznam všech možných ohodnocení pro zadaný počet pozic len_pegs. Nezohledňuje počet barev, a tedy pro dvě barvy generuje i ohodnocení, která mají lichý počet bílých kolíčků. Díky použitým valuacím a strategiím to ale na algoritmech nic nezmění.
 
 #### find_max
-Funkce pro zadané velikosti |K_{u,r}| vrátí maximální hodnotu. 
+Funkce pro zadané velikosti $|K_{u,r}|$ vrátí maximální hodnotu. 
 
 #### find_entropy
-Funkce pro zadané velikosti |K_{u,r}| vrátí entropii tohoto rozdělení. Entropie je před vrácením výsledku zaokrouhlena na 7 desetinných míst, protože při různém pořadí výpočtu entropie se tento součet zaokrouhluje jinak a nevracel by rovnosti pro stejné rozdělení potomků.
+Funkce pro zadané velikosti $|K_{u,r}|$ vrátí entropii tohoto rozdělení. Entropie je před vrácením výsledku zaokrouhlena na 7 desetinných míst, protože při různém pořadí výpočtu entropie se tento součet zaokrouhluje jinak a nevracel by rovnosti pro stejné rozdělení potomků.
 
 #### find_number_of_parts
-Funkce pro zadané velikosti |K_{u,r}| vrátí počet neprázdných potomků.
+Funkce pro zadané velikosti $|K_{u,r}|$ vrátí počet neprázdných potomků.
 
 #### lower_is_better
 Tato funkce slouží na místo strategie. Porovnává hodnoty valuací a vrací pravdivostní hodnoty, zda je první množina menší než druhá. Ve výsledku napomáhá k nalezení minimální hodnoty valuace.
 
 #### higher_is_better
 Tato funkce slouží na místo strategie. Porovnává hodnoty valuací a vrací pravdivostní hodnoty, zda je první množina větší než druhá.Ve výsledku napomáhá k nalezení maximální hodnoty valuace.
 
------------------------------------------------------------- Find expected size - doplnit nebo vymazat ---- ------------------------------------------------------
-
 #### create_next_partition
-Tato funkce bere jako argumenty množinu kandidátů K (possible codes) a další pokus u. Vrátí počty prvků v potomcích K_{u,r} pro všechna ohodnocení r.
+Tato funkce bere jako argumenty množinu kandidátů $K$ (possible codes) a další pokus $u$. Vrátí počty prvků v potomcích $K_{u,r}$ pro všechna ohodnocení $r \in S_{n,k}$.
 
 #### find_best_guess
-Tato funkce pro aktuální stav a zvolenou valuaci a strategii vrátí odpovídající další pokus. 
+find_best_guess(possible_codes, len_pegs, len_colours, all_scores, all_codes, partition_table_function, compare_function, start_code=None, choose_from_candidates=False)
 
-#### get_results_of_algorithm
-Toto je hlavní funkce, která testuje algoritmy. Prochází stavový prostor a pro každý stav nalezne další pokus. Počty pokusů přičítá v případě, kdy zkoumá potomka s ohodnocením (len_pegs,0)
+Tato funkce pro aktuální stav a zvolenou valuaci a strategii vrátí odpovídající další pokus. Vychází z proměnné possible_codes - množiny kandidátů. Projde celý prostor kódů (případně pouze množinu kandidátů) a pro každý kód (code) nalezne potomky množiny kandidátů vzhledem k tomuto kódu (temp_partition) a jejich velikosti (temp_partition_table). O to se stará funkce create_next_partition. Dále nalezne valuaci aktuálního kódu (temp_partition_table_value) a porovná ji s aktuální nejlepší hodnotou z hlediska zvolené strategie (compare_function). Ve chvíli, kdy je aktuální hodnota valuace menší, respektive větší (podle zvolené strategie) než průběžná nejlepší hodnota valuace (best_partition_table_value), program aktualizuje nejlepší hodnoty valuace, potomků a velikostí potomků. Pokud se valuace aktuálního kódu rovná průběžné nejlepší hodnotě valuace, program zkontroluje, jestli byl průběžně nejlepší kód kandidát. Pokud nebyl a aktuální kód je kandidátem, algoritmus aktualizuje nejlepší hodnoty valuace, potomků a velikostí potomků. 
 
+Díky tomu, že algoritmy vybírají lexikograficky nejmenší kódy z množiny kódů s nejlepší valuací (případně průniku této množiny s množinou kandidátů), tak stačí uchovávat pouze první kód s nejlepší hodnotou valuace. Případně stačí kontrolovat, zda náleží do množiny kandidátů.
 
-#### solve_one_game
-Tato funkce je implementací algoritmu 1 v bakalářské práci. Na vstupu vezme počet pozic a barev, tajný kód, valuaci, strategii, případný pevně stanovený první pokus a True/False hodnotu, jestli se další pokus vybírá pouze z kandidátů. 
+Ve chvíli, kdy program projde všechny kódy, ze kterých vybírá, vrátí zvolený nejlepší kód pro tento stav (best_next_guess). Společně s ním vrací i proměnné best_partition_table a best_partition. 
 
-Z důvodu zrychlení algoritmu je průběžný nejlepší další pokus uchováván v průběhu prohledávání všech kódů jako dalšího pokračování. Díky tomu, že další pokus je vybírán jako lexikograficky nejmenší kód, který minimalizuje/maximalizuje valuaci, stačí si uchovávat vždy aktuální nejlepší hodnotu a fakt, jestli je aktuálně nejlepší kód kandidátem. 
+#### get_results_of_algorithm
+Toto je hlavní funkce, která testuje algoritmy. Prochází stavový prostor a pro každý stav nalezne další pokus. Počty pokusů přičítá v případě, kdy zkoumá potomka vzhledem k ohodnocení $(n ,0)$.
+
+#### solve_one_game
+Tato funkce je implementací algoritmu $1$ v bakalářské práci. Na vstupu vezme počet pozic a barev, tajný kód, valuaci, strategii, případný pevně stanovený první pokus a True/False hodnotu, jestli se další pokus vybírá pouze z kandidátů. 
 
 Pokud další pokus dostal maximální ohodnocení, shoduje se s tajným kódem a hra končí. 
 
@@ -63,14 +91,6 @@ Tato funkce vrátí hodnotu valuace pro nějaký první pokus a zadanou valuaci.
 
 
 
-## globální proměnné
-len_pegs - tato proměnná označuje počet pozic, v práci tuto hodnotu značíme písmenem n.
-len_colours - tato hodnota určuje počet barev (v práci jako k).
-all_scores - seznam všech ohodnocení v H_{n,k}
-all_codes - seznam všech kódů H_{n,k}
-start_code - volba prvního pokusu, aby algoritmus nemusel procházet všechny kódy
-possible_codes - Množina kandidátů aktuálního stavu.
-