====== MDPMaze ======

===== Příklad použití =====

Vytvořme mapu jednoduchého bludiště:

<code python>
>>> EMPTY = (255, 255, 255)
>>> WALL = (0, 0, 0)
>>> GOAL = (255, 0, 0)
>>> START = (0, 0, 255)

>>> MAP1 = ((EMPTY, START, EMPTY, EMPTY, EMPTY),
            (EMPTY, WALL,  WALL,  WALL,  EMPTY),
            (EMPTY, EMPTY, EMPTY, WALL,  GOAL))
</code>

Import balíku kuimaze a třídy ''State'':

<code python>
>>> import kuimaze
>>> from kuimaze import State
</code>

Vytvoření prostředí, nejprve deterministického:
<code python>
>>> env = kuimaze.MDPMaze(MAP1)
</code>

Pokud chceme vytvořit prostřední nedeterministické (a to v případě MDP obvykle chceme), musíme zadat přechodové pravděpodobnosti:
<code python>
env2 = kuimaze.MDPMaze(MAP1, probs=(0.8, 0.1, 0.1, 0.0))
</code>

Seznam všech validních stavů v prostředí:
<code python>
>>> env.get_all_states()
[(x=0, y=0),
 (x=0, y=1),
 (x=0, y=2),
 (x=1, y=0),
 (x=1, y=2),
 (x=2, y=0),
 (x=2, y=2),
 (x=3, y=0),
 (x=4, y=0),
 (x=4, y=1),
 (x=4, y=2)]
</code>

Zjištění, zda je stav terminální:
<code python>
>>> env.is_terminal_state(State(0, 0)), env.is_terminal_state(State(4, 2))
(False, True)
</code>

Jaké odměny jsou spojeny s jednotlivými stavy? Odměny se vyplácejí při opuštění stavu.
<code python>
>>> env.get_reward(State(1,0)), env.get_reward(State(4,2))
(-0.04, 1.0)
</code>

Jaké akce jsou ve stavu přípustné? V našem prostředí budou přípustné vždy všechny 4 akce, ale pokud narazíme do zdi, zůstaneme na místě.
<code python>
>>> actions = tuple(env.get_actions(State(1,0)))
>>> actions
(<ACTION.UP: 0>, <ACTION.RIGHT: 1>, <ACTION.DOWN: 2>, <ACTION.LEFT: 3>)
</code>

Do jakých stavů a s jakou pravděpodobností se mohu dostat, pokud v aktuálním stavu provedu danou akci?
<code python>
>>> env.get_next_states_and_probs(State(1,0), actions[0])
[((x=1, y=0), 1), ((x=2, y=0), 0), ((x=0, y=0), 0)]
</code>
V nedeterministickém prostředí bude výsledek jiný:
<code python>
>>> env2.get_next_states_and_probs(State(1,0), actions[0])
[((x=1, y=0), 0.8), ((x=2, y=0), 0.1), ((x=0, y=0), 0.1)]
</code>

===== Popis potřebných metod =====
V následující dokumentaci se vyskytuje proměnná ''state'':
  * Pokud je ''state'' vstupem do funkce/metody, může to být buď dvojice (x,y) celých kladných čísel, nebo instance třídy ''kuimaze.State'', která je [[https://docs.python.org/3/library/collections.html#collections.namedtuple|pojmenovanou n-ticí]] a umožňuje k souřadnicím přistupovat jako ''state.x'' a ''state.y''.
  * Pokud některá z funkcí vrací ''state'', bude to vždy instance třídy ''State'' (s níž ve svém kódu můžete nakládat stejně jako s dvojicí hodnot (x,y)).


Ke komunikaci s prostředím ''MDPMaze'' slouží následující metody:

''get_all_states()'': vrátí seznam všech dosažitelných stavů (instance třídy ''State''), tedy bez zdí.

''is_terminal_state(state)'': vrací ''True'', pokud je zadaný stav koncový. Může se jednat jak o "dobrý" koncový stav, tak i o "špatný" (nebezpečný) koncový stav (představte si propast, nebo minu). 

''get_reward(state)'': Vrací reward pro daný stav. Reward je "vyplácen" až při opuštění stavu, nikoli při jeho dosažení.

''get_actions(state)'': Pro daný stav postupně generuje možné akce, které se typicky použijí v kombinaci s následující metodou. Akce je typu [[https://docs.python.org/3.4/library/enum.html|enum]], ale tím se nemusíte zabývat, viz příklad použití výše (nebo v ''mdp_sandbox.py''). Pokud chcete získat seznam možných akcí, použijte ''list(get_actions(state))''.

''get_next_states_and_probs(state, action)'' : pro daný stav a požadovanou akci navrátí seznam dvojic ''(<State>, probability)'' ; např. ''[(State(x=1, y=0), 0.8), (State(x=2, y=0), 0.1), (State(x=0, y=0), 0.1)]'' 

''visualise(dictlist=None)'' : bez parametru visualizuje obvyklé bludiště. Jinak očekává seznam slovníků ''{'x': x_coord, 'y': y_coord, 'value: val'}'', kde val může být buď skalární hodnota, nebo seznam/n-tice o čtyřech prvcích. Zde můžete konkrétně využít k vizualizaci:
  - rewards ci values přirazených jednotlivým stavům - viz ''env.visualise(get_visualisation_values(utils))''
  - policy - viz ''env.visualise(get_visualisation_values(policy))''

Rovněž zůstávají k dispozici obvyklé metody ''render()'', ''reset()''

Základní příklad použítí je vidět v souboru ''mdp_sandbox.py''.