Programmazione_Dinamica_ITA.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "#  Reinforcement Learning, Fondamenti teorici: Programmazione Dinamica per la risoluzione di problemi\n",
        "\n",
        "Mario Fiorino\n",
        "\n",
        ">1.PREMESSA : Programmazione Dinamica (Dynamic Programming - DP)\n",
        "\n",
        "In informatica la programmazione dinamica è una tecnica di progettazione di algoritmi basata sulla divisione del problema complesso in sottoproblemi più semplici concatenati, ovvero risolve un problema combinando le soluzioni dei suoi sottoproblemi. Si noti : la soluzione ottima di un problema contiene al suo interno la soluzione ottima di un sottoproblema.\n",
        "\n",
        "La programmazione dinamica risolve in modo efficiente problemi di decisione di tipo sequenziale: calcolo del cammino minimo in un grafo con pesi, calcolo del costo minimo di un percorso, ...\n",
        "\n",
        "\n",
        ">2.PREMESSA : Equazione di Bellman\n",
        "\n",
        "Equazione, formulata dal matematico statunitense R.E. Bellman nel 1957, che esprime il valore della soluzione ottimale di un problema di ottimizzazione matematica traducibile in termini di programmazione dinamica ( ovvero scomponibile in una sequenza di sottoproblemi concatenati ).\n",
        "\n",
        "L'equazione di Bellman ci cosente di esprimere il valore ottimo in uno stato come la somma della ricompensa immediata e del valore ottimo atteso nello stato successivo, pesato da un fattore di sconto. Questa equazione fornisce un modo efficace per risolvere problemi complessi decomponendoli in sotto-problemi più gestibili.\n",
        "\n",
        "L’equazione di Bellman sfrutta il cosiddetto principio di ottimalità.\n",
        "\n",
        "Principio di Ottimalità:\n",
        "Ogni punto lungo una traiettoria ottima garantisce che il percorso rimanente sia anch'esso ottimale per il problema specifico associato a quel punto d'inizio.\n",
        "\n",
        "Spiegato con un esempio, tale principio dice semplicemente che, se si considera la strada più corta per andare da Roma a Parigi e questa passa da Milano, il tratto Milano-Parigi di questo percorso ottimale è il più corto fra tutti quelli che vanno da Milano a Parigi (https://www.treccani.it/enciclopedia/equazione-di-bellman_%28Dizionario-di-Economia-e-Finanza%29/\n",
        ").\n",
        "\n",
        "L'equazione di Bellman può essere utilizzata per risolvere problemi di programmazione dinamica in modo iterativo.\n",
        "\n",
        "\n",
        "\n",
        ">3.PREMESSA : Markov Decision Processes\n",
        "\n",
        "Il presente notebook presuppone che il lettore abbia familiarità con il framework Markov Decision Processes (MDP), utilizzato per descrivere l'ambiente in cui si agisce.\n",
        "\n",
        "In alternativa si consiglia:\n",
        "\n",
        "https://www.davidsilver.uk/wp-content/uploads/2020/03/MDP.pdf\n",
        "\n",
        "\n",
        "Chapter 1 - Basic Concepts: https://github.com/MathFoundationRL/Book-Mathmatical-Foundation-of-Reinforcement-Learning/tree/main\n",
        "\n",
        "\n",
        "# Introduzione\n",
        "\n",
        "\n",
        "Nel contesto del RL, la programmazione dinamica (DP) fornisce un insieme di algoritmi (esempio : Policy iteration e Value iteration) utilizzati per calcolare policy ottimali in base a un modello dell'ambiente formalizzato tramite Processo Decisionale Markoviano (MDP), completamente noto. In modo più formale: la programmazione dinamica è un metodo, che sfrutta porcessi iterativi, per trovare soluzioni esatte ai modelli decisionali di tipo Markoviano, completamente noti, senza eseguire una ricerca esaustiva (alias: https://en.wikipedia.org/wiki/Brute-force_search , cioè provare ogni policy possibile e valutarne le prestazioni) nello spazio delle policy.\n",
        "\n",
        "Gli algoritmi DP classici hanno un'utilità limitata nel RL per due motivi: in primo luogo, presuppongono una conoscenza perfetta dell'ambiente, cosa difficilmente ottenibile nella realtà; in secondo luogo, sono computazionalmente costosi.\n",
        "Tuttavia, la DP rimane importante a livello teorico, fornendo un fondamento essenziale per comprendere le pricipipali metodologie usate nel RL. In pratica, queste metodologie possono essere visti come tentativi di ottenere lo stesso risultato della DP, ma con una minore computazione e senza assumere un modello perfettamente noto dell'ambiente.\n",
        "\n",
        "\n",
        ">RIFEMRIMENTI\n",
        "\n",
        "Testo di riferimento di RL:\n",
        "\n",
        "Reinforcement Learning: An Introduction\n",
        "\n",
        "Richard S. Sutton and Andrew G. Barto, Second Edition - MIT Press, Cambridge, 2018\n",
        "\n",
        "Una versione in PDF dovrebbe essere presente qui :\n",
        "\n",
        "https://www.andrew.cmu.edu/course/10-703/\n",
        "\n",
        "\n",
        "Lezioni on-line di RL (in inglese):\n",
        "\n",
        "https://github.com/andri27-ts/Reinforcement-Learning#week-2---rl-basics-mdp-dynamic-programming-and-model-free-control\n",
        "\n",
        "Corso di RL di David Silver:\n",
        "\n",
        "https://www.davidsilver.uk/teaching/\n",
        "\n",
        "\n",
        "Corso di RL di Yuejie Chi:\n",
        "\n",
        "https://users.ece.cmu.edu/~yuejiec/ece18813B.html\n",
        "\n",
        "Corso di RL di Katerina Fragkiadaki, Tom Mitchell\n",
        "\n",
        "https://www.andrew.cmu.edu/course/10-703/\n",
        "\n",
        "Corso di RL di Alberto Castellini\n",
        "\n",
        "https://profs.scienze.univr.it/~castellini/reinforcementLearning22-23.html\n",
        "\n",
        "°\n",
        "\n",
        "Teoria del controllo ottimale (Optimal control theory):\n",
        "\n",
        "Testo di Bertsekas: Dynamic Programming and Optimal Control\n",
        "\n",
        "\n",
        "Sito di Bertsekas:\n",
        "\n",
        "http://web.mit.edu/dimitrib/www/abstractdp_MIT.html\n",
        "\n",
        "Lezioni on-line di Bertsekas:\n",
        "https://www.youtube.com/playlist?list=PLmH30BG15SIqgS8N1TLhSQV1jwiB7ufxI\n",
        "\n",
        "\n",
        "Articolo di Bellman:\n",
        "\n",
        "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1063639/pdf/pnas01581-0064.pdf\n"
      ],
      "metadata": {
        "id": "dPdZQU8BCugh"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "##Policy Evaluation (Prediction)\n",
        "\n",
        "L’idea chiave di DP, è l’uso di funzioni-valore (value functions) per organizzare e strutturare la ricerca di buone politiche. Possiamo facilmente ottenere politiche ottimali una volta trovate le funzioni-valore ottimali. Di base, gli algoritmi DP funzionano trasformando le equazioni di Bellman in regole di update. Queste regole vengono utilizzate per migliorare l'approssimazione delle funzioni-valore desiderate.\n",
        "\n",
        "\n",
        "Iniziamo esaminando il procedimento per il calcolo della funzione-valore associata a una policy arbitraria. Tale procedura è comunemente nota come **policy evaluation** (o problema di previsione) nella letteratura della Programmazione Dinamica.\n",
        "\n",
        "Condizioni di applicabilità: La dinamica dell’ambiente, ovvero il Markov Decision Process (MDP) : $ <S, A, P, R, γ>$ , è completamente nota.\n",
        "\n",
        "Input  : data una certa policy 𝜋\n",
        "\n",
        "Ingrediente di base : calcolare la funzione-valore relativa ad ogni stato di MDP : $v_{𝜋}(s)$ $\\forall s \\in S$, in modo iterativo sfruttando l'equazione di Bellman come regola di aggiornamento:\n",
        "\n",
        "\n",
        "<div>\n",
        "<img src= \"data:image/png;base64,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\" width=\"400\">\n",
        "</div>\n",
        "\n",
        "Dove:\n",
        "\n",
        "$ 𝜋(a|s)$ è la policy , o regola di selezione delle azioni, in pratica è la distribuzione da cui viene campionata un azione $a$ nello stato $s$.\n",
        "\n",
        "$p(s',r|s,a)$ è probabilità di transizione di finire in $s'$ con relativo reward $r$, dati in ingresso $(s,a)$\n",
        "\n",
        "la funzione-valore $v_{k}$ è stata ottenuta nel ciclo iterativo $k$, quello che precede il ciclo $k+1$\n",
        "\n",
        "$𝑠′$ è uno stato successsivo di $𝑠$.\n"
      ],
      "metadata": {
        "id": "dsYu7qJxh9-W"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Procedimento :\n",
        "\n",
        "in pratica si considera una sequenza di funzioni-valore che approssimano progressivamente (durante il ciclo iterativo)  $v_{𝜋}(s)$ ; ovvero : $v_{0}(s)$ , $v_{1}(s)$ , $v_{2}(s)$ ,..., $v_{𝜋}(s)$ . L'approssimazione iniziale, $v_{0}(s)$ , viene scelta arbitrariamente e ogni approssimazione successiva viene ottenuta utilizzando l'equazione di Bellman.\n",
        "\n",
        "\n",
        "Algoritmo : \"**Iterative Policy Evaluation**\".\n",
        "\n",
        "\n",
        "\n",
        "1.   Si inizia con la scelta di una policy arbitraria $π$\n",
        "2.   Si inizializza la funzione-valore di partenza : $v_{0}(s)$ $ \\: \\forall s \\in S$. Ad esempio, si può scegliere di inizializzare  $v_{0}(s) = 0 $ , per tutti gli stati $s$. Questa scelta equivale a non avere alcuna memoria di ricompensa.\n",
        "3.   Calcola la nuova funzione-valore $v_{k+1}(s)$  ovvero, $ v_{1}(s) $  utilizzando l'equazione di Bellman come regola di update, su $v_{k}(s')$ , ovvero su  $ v_{0}(s') $ . Notare: con k=0 si intendono i valori della funzione-valore del ciclo precedente a k=1, mentre $𝑠′$ è uno stato successsivo di $𝑠$.\n",
        "4.   Ripetendo l'elaborazione utilizzando $ v_{1}(s) $ per calcolare $ v_{2}(s) $ e proseguendo...$ v_{∞}(s) $ alla fine convergerà la nostra funzione valore a $ v_{π}(s) $ .\n",
        "\n",
        "°\n",
        "\n",
        "Domanda :\n",
        "\n",
        "Quali condizoini ci garantiscono che la sequenza  $v_{0}(s)$ , $v_{1}(s)$ , $v_{2}(s)$ ,..., $v_{\\infty}(s)$ converga; o melgio che Algoritmo Iterative Policy Evaluation sia convergente in $v_{\\pi}$ ?\n",
        "\n",
        "Risposta: fintanto che:\n",
        "\n",
        "il fattore di sconto risutla $ 0 \\le γ < 1$\n",
        "\n",
        "oppure\n",
        "\n",
        "partendo da qualunque stato $s \\in S$ , sarà sempre possibile raggiungere uno stato terminale in un numero finito di passi, seguendo la politica $π$\n",
        "\n",
        "La convergenza della sequenza $ \\{v_{k}\\} $ , per $k → ∞$ , è garantita.\n",
        "\n",
        "\n",
        "Una dimostrazione più articolata, fondata sul \"Contraction Mapping Theorem\" può essere trovata qui:\n",
        "https://runzhe-yang.science/2017-10-04-contraction/\n",
        "\n",
        "\"Based on these mathematical foundations, we investigate the contractive dynamic programming, where the contraction property and the monotonicity property together guarantee a unique optimal solution can be achieved\"\n",
        "\n",
        "\n",
        "\n"
      ],
      "metadata": {
        "id": "10bJ8PyqqBxH"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Come migliorare una policy? (Control problem)\n",
        "\n",
        "Nell'approccio precedente (Policy Evaluation) abbiamo valutato una determinata policy, ma non abbiamo trovato la policy migliore nel nostro ambiente. Una policy $𝜋'$ è un miglioramento della policy $𝜋$,  se  $v_{𝜋'}(s) \\geq  v_{𝜋}(s)$  $\\:\\: \\forall s \\in S$.\n",
        "\n",
        "Domanda:\n",
        "\n",
        "Data una certa policy $𝜋$ , come trovarne un altra che ci consente di ottenere una maggiore ricompensa complessiva?\n",
        "\n",
        "Nell'esempio precedente, nella fase Policy Evaluation, già possiamo intuire che, data una policy e la sua funzione-valore, possiamo facilmente considerare una policy migliore di quella data, scegliendone una che, per ogni stato, specifichi l'azione che massimizza la funzione-valore nello step successivo (e non segue un azione nata da un campionamento \"random 0.25\", come fa la policy di partenza dell'esempio).\n",
        "\n",
        "Ma andiamo per gradi, per rispondere in modo approfondito alla domanda, prendiamo il considerazione la  Q-function : $q_{𝜋}(s,a)$ , ovvero una funzione (molto simile alla funzione-valore $v_{𝜋}(s)$) che indica la ricompensa cumulativa attesa nell'intraprendere l'azione $a$ nello stato $s$, seguendo una certa policy $𝜋$, in pratica ci dice quanto è buona una certa coppia stato-azione.\n",
        "\n",
        "Definizione formale :\n",
        "\n",
        "<div>\n",
        "<img src=\" data:image/png;base64,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 \", width=\"500\">\n",
        "</div>\n",
        "\n",
        "\n",
        "Per quanto riguarda il legame tra la Q-fuction e la funzione-valore, valgono le realzioni:\n",
        "\n",
        "\n",
        "\n",
        "\n",
        "$v_{𝜋} =  \\sum\\limits_{a\\in A }  𝜋(a|s) q_{𝜋}(s,a) $\n",
        "\n",
        "\n",
        "$q_{𝜋}(s,a)  = \\sum\\limits_{s'\\in S }  p (s'|s,a) \\:   [r(s,a,s')  + γ \\; v_{𝜋}(s') ] $\n",
        "\n",
        "per il leggero abuso formale della notazione di $q_{𝜋}(s,a)$, leggere: Chapter 3, pag-PDF 70 e 71, del libro Reinforcement Learning, Richard Sutton and Andrew Barto, 2018"
      ],
      "metadata": {
        "id": "dEPbmqYPN3Ji"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Seguendo una certa policy $𝜋$, come possiamo identificare un'azione $a$ tale che:\n",
        "\n",
        "$q_{𝜋}(s,a) \\geq  v_{𝜋}(s)$  $ \\:\\: \\forall s \\in S$  ?\n",
        "\n",
        "Per rispondere introduciamo un teorema ed una definizione.\n",
        "\n",
        "\n",
        "\n",
        "Teorema.\n",
        "\n",
        "**Policy improvement theorem**:\n",
        "\n",
        "Scelta una policy stazionaria $π$, e sia $π'$ una policy deterministica tale che :\n",
        "\n",
        "$q_{𝜋}(s,𝜋'(s)) \\geq  v_{𝜋}(s)$  $\\:\\: \\forall s \\in S$\n",
        "\n",
        "allora:\n",
        "\n",
        "$v_{𝜋'}(s) \\geq  v_{𝜋}(s)$  $\\:\\: \\forall s \\in S$.\n",
        "\n",
        "\n",
        "Definizione.\n",
        "\n",
        "Si definisce **greedy**, rispetto $q_{𝜋}$, una certa policy $𝜋'$ se, per ogni stato risulta:\n",
        "\n",
        "$𝜋' \\doteq  \\underset{a}{\\arg\\max}  \\;  q_{𝜋}(s,a) $\n",
        "\n",
        "In pratica una policy greedy sceglie sempre l’azione che massimizza nel breve termine (dopo un solo step) il valore di $q_{𝜋}(s,a)$.\n",
        "\n",
        "*\n",
        "\n",
        "Proviamo adesso a rispondere alla domanda di partenza: \"Seguendo una certa policy $𝜋$, come possiamo identificare un'azione $a$ tale ... \"\n",
        "\n",
        "\n",
        "Sia introdotta la policy greedy:\n",
        "\n",
        "$𝜋' \\doteq  \\underset{a}{\\arg\\max}  \\;  q_{𝜋}(s,a) $\n",
        "\n",
        "Ciò verifica l'uguaglianza:\n",
        "\n",
        "$q_{𝜋}(s,𝜋'(s)) = \\underset{a}{\\max}  \\;  q_{𝜋}(s,a) $\n",
        "\n",
        "Passaggio 1\n",
        "\n",
        "$\\underset{a}{\\max}  \\;  q_{𝜋}(s,a)  \\geq q_{𝜋}(s,𝜋(s)) $\n",
        "\n",
        "Passagggio 2\n",
        "\n",
        "\n",
        "$ q_{𝜋}(s,𝜋(s)) = v_{𝜋}(s) $\n",
        "\n",
        "Passaggio 3, quindi verificata la premessa del Policy improvement theorem,\n",
        "\n",
        "$q_{𝜋}(s,𝜋'(s)) \\geq  v_{𝜋}(s)$\n",
        "\n",
        "ciò garantisce la sua conclusione:\n",
        "\n",
        "$v_{𝜋'}(s) \\geq  v_{𝜋}(s)$\n",
        "\n",
        "La policy greedy soddisfa le condizioni del Policy improvement theorem, quindi sappiamo che è altrettanto buona, o migliore, della policy originale.\n",
        "\n",
        "\n",
        "Per tanto per migliorare una data policy $𝜋(s), $ possiamo  agire greedy! cioè scegliendo l'azione che risulta la migliore nel breve termine - dopo un solo step : \"one step of lookahead \" - rispetto i valori di $v_{𝜋}(s)$\n",
        "\n",
        "*\n",
        "\n",
        "Il processo di creazione di una nuova policy che migliora quella originale, rendendola greedy rispetto alla funzione-valore della policy originale, è chiamato **policy improvement**.\n",
        "\n",
        "**\n",
        "\n",
        "Appendice : Il termine \"greedy\" è usato in informatica per descrivere qualsiasi procedura di ricerca o decisione che seleziona alternative basandosi solo su considerazioni locali o immediate, senza tenre in considerazione la possibilità che tale selezione possa impedire l'accesso futuro ad alternative migliori.\n",
        "\n",
        "Una \"policy greedy\" seleziona le azioni solo in base alle loro conseguenze a breve termine."
      ],
      "metadata": {
        "id": "RSx8hA8we5XL"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Policy optimization\n",
        "\n",
        "\n",
        "Fin'ora abbiamo capito come valutare una policy e come migliorarla, il prossimo passo consiste nel capire:\n",
        "\n",
        "\n",
        "Come trovare una policy ottimale per un dato ambiente MDP ?\n",
        "\n",
        "Si ricorda che una policy ottimale è migliore (ovvero consente di ottenere una maggiore ricompensa complessiva) o uguale a tutte le altre politiche. In genere si denota così $𝜋^{*}$.\n",
        "\n",
        "Mentre la  funzione-valore ottimale è indicata con $v^{*}$. Formalemente si puo scrivere:\n",
        "\n",
        "$v^{*}(s) = \\underset{𝜋}{\\max}  \\;  v_{𝜋}(s) $\n",
        "  $\\: \\: \\: \\forall s \\in S $\n",
        "\n",
        "\n",
        "*\n",
        "\n",
        "Siamo sicuri che esiste sempre una policy ottimale ?\n",
        "\n",
        "C'è un lemma, nel lavoro di Bellman che garantisce che dato un MDP con orizzonte infinito e scontato (cioè il fattore $γ$ sia compreso tra $ 0 < γ < 1 $),\n",
        "esiste sempre almeno una policy stazionaria e deterministica $𝜋^{*}$ che sia ottimale.\n",
        "\n",
        "Nota: policy stazionaria significa che non dipende dal fattore tempo, considera solo lo stato corrente per determinare l’azione. Un esempio di policy non stazionarie può essere facilmente trovato nel contesto RL multi-agente.\n",
        "\n",
        "*\n",
        "\n",
        "Da notare che possiamo facilmente ottenere policy ottimali una volta trovate le funzioni-valore o Q-function ottimali, sfruttando le equazioni di ottimalità di Bellman:\n",
        "\n",
        "\n",
        "<div>\n",
        "<img src=\"data:image/png;base64,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\"\n",
        ", width=\"400\">\n",
        "</div>\n",
        "\n",
        "\n",
        "Si noti:\n",
        "\n",
        "$p(s',r|s,a)$ è probabilità di transizione di finire in $s'$ con relativo reward $r$, dati in ingresso $(s,a)$\n",
        "\n",
        "\n",
        "$𝑠′$ è uno stato successsivo di $𝑠$.\n",
        "\n",
        "$a′$ è l'azione che verrà intrapresa nello stato successsivo $𝑠'$."
      ],
      "metadata": {
        "id": "FfVpQ52qfr8G"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Per rispondere alla domanda sul come trovare una policy ottimale, possimo ragonare in modo iterativo; ovvero:\n",
        "\n",
        "\n",
        "data un certa policy $𝜋$, da questa ricaviamo per ogni stato la funzione valore $v_{𝜋}$.\n",
        "\n",
        "Poi, in modalità greedy, sfruttando la funzione valore $v_{𝜋}$; miglioriamo la policy di partenza, ottenendo una nuova policy : $𝜋'$, di cui possiamo calcolare $v_{𝜋'}$.\n",
        "\n",
        "Da qui, sempre in modalità greedy, sfruttando la funzione valore $v_{𝜋'}$; milgioriamo la policy  $𝜋'$ , ottenendo una nuova policy : $𝜋''$, ... così via ..., ogni policy così ottenuta garantisce un  miglioramento rispetto alla precedente (a meno che non sia già ottimale). Quindi, ripetendo il procedimento più volte possiamo così ottenere a sequenza di policy e funzioni-valore che migliorano monotonicamente. Tale procedimento è detto **policy iteration**.\n",
        "\n",
        "Schema sintetico:\n",
        "\n",
        "![image.png](data:image/png;base64,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)\n",
        "\n",
        "\n",
        "\n",
        "\n",
        "In cui: \"E\" indica la fase di  policy evaluation.\n",
        "Mentre \"I\" la fase di policy improvemen, ovvero l a fase \"greedy\"\n",
        "\n",
        "*\n",
        "\n",
        "Si noti:\n",
        "\n",
        "In un MDP finito che ha  un numero finito di policy, questo processo convergere verso una policy ottimale  in un numero finito di iterazioni. Discorso simile per un MDP con orizzonte infinito e scontato. Per maggiori informazioni (o dimostrazione matematica) rigurdo la convergenza (e le reative condizioni necessarie) di tale processo iterativo si rimanda ai testi:\n",
        "\n",
        "Reinforcement Learning:Theory and Algorithms\n",
        "Alekh Agarwal Nan Jiang Sham M. Kakade Wen Sun\n",
        "\n",
        "il testo di Bertsekas\n",
        "\n",
        "le slide di Silver\n",
        "\n",
        "\n"
      ],
      "metadata": {
        "id": "T-9hfHIsBE9z"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Policy Iteration algorithm**, è composto dai segiueti step:\n",
        "\n",
        "1.\n",
        "Fase di inizializzazione (arbitraria) della funzione valore $v$ e della policy $𝜋$\n",
        "\n",
        "Loop tra le fasi 2 $  ⟷ $ 3\n",
        "\n",
        "2.\n",
        "Fase di Policy Evaluation.\n",
        "\n",
        "(sfruttiamo l'equazione di Bellman come regola di update)\n",
        "\n",
        "Da notare che qui:\n",
        "\n",
        "2.A) il calcolo iterativo, viene avviato con la funzione valore della policy precedentemente ottenuta.\n",
        "\n",
        "2.B) formalmente, il loop sul Bellman-update converge a $v_{𝜋}$\n",
        "solo nel limite $ ∞ $, ma in pratica deve essere fermato prima di raggiungere questo limite. Vanno così introdotte, condizioni di stop: $\\Delta < \\theta $ , dove $\\theta$ è un piccolo numero positivo che determina l'accuratezza della stima.\n",
        "Si può usare come test il valore: $\\Delta = \\max  \\;  |v_{k+1}(s) - v_{k}(s)| $ . Per maggiori dettagli vedi testo: Reinforcement Learning, Richard Sutton and Andrew Barto, 2018 pag pdf 97\n",
        "\n",
        "\n",
        "3.\n",
        "Fase di Policy Improvement\n",
        "\n",
        "(agisci greedy)\n",
        "\n",
        "Se la policy trovata è stabile, cioè non sono più possibili miglioramenti (l' azione greedy scelta è sempre la stessa), allora fermati e ritorna i valori ottimali trovati;\n",
        "\n",
        "Altrimenti ritorna alla fase 2.\n",
        "\n"
      ],
      "metadata": {
        "id": "9AkKy3kiWbc9"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Esempio applicativo - Policy Iteration\n",
        "\n",
        "A titolo di esempio, lavoreremo sull'ambiente **Frozen Lake**, fornito dalla libreria Gym.\n",
        "\n",
        "Frozen Lake 4x4 è composto:\n",
        "\n",
        "da 16 stati,(da Start a Goal) codificati dagli interi 0 a 15;\n",
        "\n",
        "4 azioni: sinistra, giù, destra, su saranno codificate da 0 a 3.\n",
        "\n",
        "L'agente potrebbe non muoversi sempre nella direzione desiderara a causa della natura scivolosa del lago ghiacciato. Prob_transizione =  33,3%\n",
        "\n",
        "Scopo del gioco: raggiungere lo stato terminale (con unico reward +1) dallo stato iniziale senza visitare gli stati con buco.\n",
        "\n",
        "\n",
        "\n",
        "\n",
        "Sito di riferimento:\n",
        "\n",
        "https://www.gymlibrary.dev/environments/toy_text/frozen_lake/\n",
        "\n",
        "Per maggior info:\n",
        "\n",
        "https://github.com/MarioFiorino/Tutorial-Reinforcement-Learning-ITA-Python/blob/main/Introduzione_OpenAI_Gym.ipynb\n",
        "\n"
      ],
      "metadata": {
        "id": "UT2KkqM220zl"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Il codice sottostante è stato ispirato ed ha come riferimento i codici:\n",
        "# https://github.com/PacktPublishing/Deep-Reinforcement-Learning-with-Python/blob/master/03.%20Bellman%20Equation%20and%20Dynamic%20Programming/3.08.%20Solving%20the%20Frozen%20Lake%20Problem%20with%20Policy%20Iteration.ipynb\n",
        "# di Sudharsan Ravichandiran\n",
        "\n",
        "#https://github.com/PacktPublishing/Reinforcement-Learning-Algorithms-with-Python/blob/master/Chapter03/frozenlake8x8_policyiteration.py\n",
        "# di Andrea Lonza\n",
        "\n",
        "import gym\n",
        "import numpy as np\n",
        "\n",
        "# se si desidera il redering caricare anche i moduli qui sotto\n",
        "from matplotlib import pyplot as plt\n",
        "%matplotlib inline\n",
        "from IPython import display"
      ],
      "metadata": {
        "id": "W2m6kELwctZ9"
      },
      "execution_count": 1,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "env = gym.make('FrozenLake-v1')\n",
        "\n",
        "def query_environment(name):\n",
        "    env = gym.make(name)\n",
        "    spec = gym.spec(name)\n",
        "    print(f\"Action Space: {env.action_space}\")\n",
        "    print(f\"Observation Space: {env.observation_space}\")\n",
        "    print(f\"Max Episode Steps: {spec.max_episode_steps}\")\n",
        "    print(f\"Reward Range: {env.reward_range}\")\n",
        "\n",
        "query_environment('FrozenLake-v1')"
      ],
      "metadata": {
        "id": "znFfMeAWHsY_",
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "outputId": "dc5afad7-72ba-49e7-94b5-f31e33bbf23b"
      },
      "execution_count": 2,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Action Space: Discrete(4)\n",
            "Observation Space: Discrete(16)\n",
            "Max Episode Steps: 100\n",
            "Reward Range: (0, 1)\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stderr",
          "text": [
            "/usr/local/lib/python3.10/dist-packages/ipykernel/ipkernel.py:283: DeprecationWarning: `should_run_async` will not call `transform_cell` automatically in the future. Please pass the result to `transformed_cell` argument and any exception that happen during thetransform in `preprocessing_exc_tuple` in IPython 7.17 and above.\n",
            "  and should_run_async(code)\n",
            "/usr/local/lib/python3.10/dist-packages/gym/core.py:317: DeprecationWarning: \u001b[33mWARN: Initializing wrapper in old step API which returns one bool instead of two. It is recommended to set `new_step_api=True` to use new step API. This will be the default behaviour in future.\u001b[0m\n",
            "  deprecation(\n",
            "/usr/local/lib/python3.10/dist-packages/gym/wrappers/step_api_compatibility.py:39: DeprecationWarning: \u001b[33mWARN: Initializing environment in old step API which returns one bool instead of two. It is recommended to set `new_step_api=True` to use new step API. This will be the default behaviour in future.\u001b[0m\n",
            "  deprecation(\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "print(\"Struttura del dato env.P[state][action] \")\n",
        "print(\"Come esempio ho preso il penultimo stato = 14, prossimo alla ricompensa, e l'azione destra = 2\")\n",
        "print(\"(Prob_transizione, stato-succesivo, reward, è uno stato terminale?)\")\n",
        "\n",
        "env.P[14][2]"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "3xR9InDi4KFI",
        "outputId": "adde1599-03a8-4127-b4be-a53d51e9f584"
      },
      "execution_count": 6,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Struttura del dato env.P[state][action] \n",
            "Come esempio ho preso il penultimo stato = 14, prossimo alla ricompensa, e l'azione destra = 2\n",
            "(Prob_transizione, stato-succesivo, reward, è uno stato terminale?)\n"
          ]
        },
        {
          "output_type": "execute_result",
          "data": {
            "text/plain": [
              "[(0.3333333333333333, 14, 0.0, False),\n",
              " (0.3333333333333333, 15, 1.0, True),\n",
              " (0.3333333333333333, 10, 0.0, False)]"
            ]
          },
          "metadata": {},
          "execution_count": 6
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Calcolo della funzione-valore (Policy Evaluation)\n",
        "\n",
        "La funzione-valore viene calcoata per ogni stato dell'ambinete, utilizzando la policy data in input.\n",
        "\n",
        "Tale calcolo sfrutta l'equazione di Bellman come regola di aggiornamento.\n",
        "\n",
        "Ad esempio, se si parte dalla seguente funzione valore:\n",
        "\n",
        "<font color='gray'>old_value_table</font> =\n",
        "\n",
        "<font color='gray'>\n",
        "\n",
        "[0.16,  $\\:\\:$ 0.08, $\\:\\:$ 0.12, $\\:\\:$ 0.06]</font>\n",
        "\n",
        "<font color='gray'>\n",
        "\n",
        "[0.17,  $\\:\\:$ 0.00, $\\:\\:$ 0.17, $\\:\\:$  0.00]</font>\n",
        "\n",
        "\n",
        "<font color='gray'>\n",
        "\n",
        "[0.18,  $\\:\\:$ 0.37, $\\:\\:$ 0.41, $\\:\\:$ 0.00] </font>\n",
        "\n",
        "\n",
        "<font color='gray'>\n",
        "\n",
        "[0.00,  $\\:\\:$ 0.52, $\\:\\:$ 0.70, $\\:\\:$  0.00]</font>\n",
        "\n",
        "\n",
        "In cui, per ogni stato è associato un valore. Per capirci, nello stato = 0, avremo <font color='gray'>old_value_table[0] = 0.16 </font>; mentre nello stato = 6, avremo <font color='gray'>old_value_table[6] = 0.17 </font>\n",
        "\n",
        "Premesso che la probabilità di transizione (state-transition probabilities) è 0.333 oppure 0.\n",
        "\n",
        "Update, nello stato 9, per un'azione speficata dalla policy in quello stato, per esempio \"destra\" , (<font color='gray'> env.P[9][2] </font>);   è la seguente:\n",
        "\n",
        "\n",
        "\n",
        "$ value\\_{table}[9] $\n",
        "\n",
        "$=$\n",
        "\n",
        "$ 0.333 * (   0 + (gamma * (old\\_value\\_table[next state=13] = 0.52) \\;) \\;) $\n",
        "\n",
        "$+$\n",
        "\n",
        "$ 0.333 * (   0 + (gamma * (old\\_value\\_table[next state=10] = 0.41) \\;) \\;) $\n",
        "\n",
        "$+$\n",
        "\n",
        "$ 0.333 * (   0 + (gamma * (old\\_value\\_table[next state=5] = 0.00) \\;) \\;) $\n",
        "\n",
        "\n",
        "$+$\n",
        "\n",
        "$ 0.0 * (   0 + (gamma * (old\\_value\\_table[next state=8] = 0.18) \\;) \\;) $\n",
        "\n",
        "\n",
        "In pratica, sono tre gli stati raggiungibili con la regola data dalla transizione di probabilità dell'ambiente. Lo stato = 8 (a sinistra della cella 9), non ha nessuna probabilità di essere raggiunto avendo in input l'azione \"destra\" (concretamente questo valore non è menzionato nell'informazione <font color='gray'> env.P[9][2] </font> , ma a livello teorico esiste).\n",
        "In questo specifico caso, tutti i reward sono pari a 0.\n",
        "Sommando gli addendi si ottiene il nuovo valore di <font color='gray'>value_table[9]</font>. Questo discorso chiaramente va fatto per ogni stato."
      ],
      "metadata": {
        "id": "tJTlTXEOIBEY"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "2upb6NkFAXkB"
      },
      "outputs": [],
      "source": [
        "def compute_value_function(policy,gamma):\n",
        "\n",
        "    #limite o threshold value - accuracy of estimation 0.000000001\n",
        "    threshold = 1e-9\n",
        "\n",
        "    #Inizializziamo all'inizio di ogni ciclo iterativo\n",
        "    # la tabella della funzione-valore, con zero per tutti gli stati\n",
        "    value_table = np.zeros(env.observation_space.n)\n",
        "\n",
        "    #contatore iterazioni\n",
        "    i=0\n",
        "\n",
        "    while True:\n",
        "\n",
        "        #Appoggiamo la funzione-valore appresa nel ciclo iterativo precedente nella locazione: odl_value_table\n",
        "        old_value_table = np.copy(value_table)\n",
        "\n",
        "        # per ogni stato s\n",
        "        for s in range(env.observation_space.n):\n",
        "\n",
        "            # selezioniamo l'azione in base alla politica data\n",
        "               a = policy[s]\n",
        "\n",
        "            #Calcolo della funzione-valore sfruttando update di Bellman\n",
        "               value_table[s] = sum([prob * (r + (gamma * old_value_table[s_]))\n",
        "                                        for prob, s_, r, _ in env.P[s][a]])\n",
        "        # Si noti nell'update di sopra ho usato l'algoritmo \"with two arrays\" : value_table[] e old_value_table[]\n",
        "        # Il libro di Sutton & Barto discute la cosa, e preferisce usare (dove è possibile farlo)\n",
        "        # un aggiornamento \"in place\", cioè solo value_table[]. Anche nello pseudocode-Iterative Policy Evaluation,\n",
        "        # sceglie di usare tale strategia \"in place\".\n",
        "        # vedi pagina PDF : 97\n",
        "        # \"With two arrays, the new values can be computed one by one from the old values without the old values being changed.\n",
        "        # Of course it is easier to use one array and update the values “in place,” that is, with each new value immediately\n",
        "        # overwriting the old one. Then, depending on the order in which the states are updated, sometimes new values are used instead of old ones on the right-hand side of bellman equation.\n",
        "        # This in-place algorithm also converges ; in fact, it usually converges faster than the two-array version,\n",
        "        # as you might expect, because it uses new data as soon as they are available. \"\n",
        "        # Per tale aggiornamento \"in place\" è garantita a quali condizioni la convergenza?\n",
        "        # Si paral della cosa a pagina PDF : 107, riguardo però il processo di value iteration :\n",
        "        # \" For example, one version of asynchronous value iteration updates the value, in place,\n",
        "        #  of only one state, s_k, on each step, k, using the value iteration update rule.\n",
        "        # If 0 <= gamma  < 1, asymptotic convergence to optimal value fuction is guaranteed given only that all states occur in the\n",
        "        # sequence {sk} an infinite number of times (the sequence could even be stochastic).\"\n",
        "        #\n",
        "        # Per ulteriori info sull'argomento vedere anche il corso di Silver (Asynchronous Dynamic Programming):\n",
        "        # https://www.davidsilver.uk/wp-content/uploads/2020/03/DP.pdf\n",
        "        # oppure una sintesi :\n",
        "        # https://goodboychan.github.io/reinforcement_learning/2020/06/10/02-Variants-of-dynamic-programming.html\n",
        "\n",
        "\n",
        "        # Dopo aver calcolato la tabella della funzione-valore di tutti gli stati,\n",
        "        # controlliamo se la differenza tra la tabella dei valori ottenuta nell'iterazione corrente e\n",
        "        # l'iterazione precedente è minore o uguale a un valore di soglia.\n",
        "        # Se è inferiore, interrompiamo il ciclo e restituiamo la tabella dei valori\n",
        "        if (np.sum((np.fabs(old_value_table - value_table))) <= threshold):\n",
        "            break\n",
        "\n",
        "        i+= 1\n",
        "\n",
        "    print(\"Policy Evaluation : Value_table OUT: \\n\",value_table.reshape((4,4)).round(decimals=4))\n",
        "    print(\"La convegenza della Value_table è stata ottenuta dopo \",i+1,\" iterazioni.\")\n",
        "\n",
        "    return value_table"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Agisci Greedy! (Policy Improvement)\n",
        "\n",
        "Aggiorna la policy in base alla funzione valore"
      ],
      "metadata": {
        "id": "2BYR_DyM7JLP"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#\n",
        "# Premessa Tecnica #\n",
        "#\n",
        "\n",
        "# Per meglio capire il Nested List Comprehensions usato nella funzione: policy_improvement(value_table,policy,gamma):\n",
        "# Studiare l''esempio :\n",
        "\n",
        "lista = [1,2]\n",
        "\n",
        "newlist = [sum([x + a for x in lista]) for a in range(999,1004)]\n",
        "\n",
        "#Il rigo di sopra è equivalente a tutto il codice scritto sotto:\n",
        "\n",
        "k = []\n",
        "for a in range(999,1004):\n",
        "  m = []\n",
        "  for x in lista:\n",
        "      m.append(x+a)\n",
        "  #print(\"Array ausiliario : \",m)\n",
        "  k.append(sum(m)) # La funzione sum() somma degli elemente dell'array e ne restituisce il risultato.\n",
        "\n",
        "\n",
        "\n",
        "print(newlist==k)\n",
        "print(k)"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "7ObdC86JbgiQ",
        "outputId": "9ce943bb-7fcb-43cf-cfdb-c5296c0cb5be"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "True\n",
            "[2001, 2003, 2005, 2007, 2009]\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "def policy_improvement(value_table,policy,gamma):\n",
        "\n",
        "    policy_stable = True\n",
        "\n",
        "    for s in range(env.observation_space.n):\n",
        "\n",
        "        old_a = policy[s]\n",
        "        # aggiornare la policy con l'azione greedy in accordo con la value table(next state), su ogni azione disponibile\n",
        "        act_greedy = np.argmax([np.sum([prob * (r + gamma*value_table[s_]) for prob, s_, r, _ in env.P[s][a]]) for a in range(env.action_space.n)])\n",
        "        policy[s] =  act_greedy\n",
        "\n",
        "        if old_a != policy[s]:\n",
        "            policy_stable = False\n",
        "\n",
        "    #Display la policy\n",
        "    a2w = {0:'<', 1:'v', 2:'>', 3:'^'}\n",
        "    ap = np.array([])\n",
        "    for i in policy:\n",
        "       ap = np.append(ap,a2w[int(i)])\n",
        "    print(\"Greedy Process : Policy OUT: \\n\",ap.reshape((4,4)))\n",
        "\n",
        "    return policy, policy_stable\n"
      ],
      "metadata": {
        "id": "vxMuTxWz1mOb"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Policy Iteration"
      ],
      "metadata": {
        "id": "TiVdXTxQCkGg"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "def policy_iteration(env):\n",
        "\n",
        "    #Discount factor\n",
        "    gamma = 0.95\n",
        "\n",
        "    # Inizializza la policy. Qui ho scritto due alternative.\n",
        "    #1. selects the action 0 in all the states\n",
        "    #policy = np.zeros(env.observation_space.n)\n",
        "\n",
        "    #2. generate 1D policy array of 15 random integers between 0 and 3\n",
        "    policy = np.random.randint(0, 4, 16) + np.zeros(env.observation_space.n)\n",
        "\n",
        "    #Display la policy\n",
        "    a2w = {0:'<', 1:'v', 2:'>', 3:'^'}\n",
        "    a_ini = np.array([])\n",
        "    for i in policy:\n",
        "       a_ini = np.append(a_ini,a2w[int(i)])\n",
        "    print(\"\\n-- Inizializzazione della policy\")\n",
        "    print(\"La policy da cui partiamo: \\n\",a_ini.reshape((4,4)))\n",
        "\n",
        "\n",
        "    policy_stable = False\n",
        "    cont = 0\n",
        "\n",
        "    while not policy_stable:\n",
        "        print(\" \\n-- Policy Iteration process : Iterazione numero\", cont )\n",
        "        value_table = compute_value_function(policy,gamma)\n",
        "        policy, policy_stable = policy_improvement(value_table, policy,gamma)\n",
        "        cont += 1\n",
        "\n",
        "    return policy\n"
      ],
      "metadata": {
        "id": "pl_PtjzeCsFs"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "optimal_policy = policy_iteration(env)"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Nn9afHtGEgT2",
        "outputId": "43a5280b-3b29-430b-d38b-1295db4722bf"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "\n",
            "-- Inizializzazione della policy\n",
            "La policy da cui partiamo: \n",
            " [['>' '<' '>' 'v']\n",
            " ['>' '>' 'v' '^']\n",
            " ['<' '^' '>' '>']\n",
            " ['<' '<' '<' '^']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 0\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0. 0. 0. 0.]\n",
            " [0. 0. 0. 0.]\n",
            " [0. 0. 0. 0.]\n",
            " [0. 0. 0. 0.]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  1  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['<' '<' '<' '<']\n",
            " ['<' '<' '<' '<']\n",
            " ['<' '<' '<' '<']\n",
            " ['<' '<' 'v' '<']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 1\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0.     0.     0.0301 0.014 ]\n",
            " [0.     0.     0.065  0.    ]\n",
            " [0.     0.     0.175  0.    ]\n",
            " [0.     0.     0.4878 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  37  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['<' 'v' '>' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['<' 'v' '<' '<']\n",
            " ['<' 'v' '>' '<']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 2\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0.     0.0304 0.0958 0.0828]\n",
            " [0.     0.     0.124  0.    ]\n",
            " [0.     0.1854 0.2959 0.    ]\n",
            " [0.     0.2896 0.6249 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  138  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['v' '>' '>' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['v' 'v' '<' '<']\n",
            " ['<' '>' '>' '<']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 3\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0.0665 0.0511 0.1103 0.0952]\n",
            " [0.0924 0.     0.1427 0.    ]\n",
            " [0.1328 0.2867 0.3404 0.    ]\n",
            " [0.     0.432  0.6455 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  147  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['<' '^' '>' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['^' 'v' '<' '<']\n",
            " ['<' '>' 'v' '<']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 4\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0.1796 0.1433 0.1296 0.1119]\n",
            " [0.2079 0.     0.1678 0.    ]\n",
            " [0.2691 0.3727 0.4002 0.    ]\n",
            " [0.     0.5079 0.7232 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  226  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['<' '^' '<' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['^' 'v' '<' '<']\n",
            " ['<' '>' 'v' '<']]\n",
            " \n",
            "-- Policy Iteration process : Iterazione numero 5\n",
            "Policy Evaluation : Value_table OUT: \n",
            " [[0.1805 0.1548 0.1535 0.1325]\n",
            " [0.209  0.     0.1764 0.    ]\n",
            " [0.2705 0.3747 0.4037 0.    ]\n",
            " [0.     0.509  0.7237 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  236  iterazioni.\n",
            "Greedy Process : Policy OUT: \n",
            " [['<' '^' '<' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['^' 'v' '<' '<']\n",
            " ['<' '>' 'v' '<']]\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Test della policy finale ottenuta"
      ],
      "metadata": {
        "id": "fEm1F-mpBhn4"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "def test_optimal_poliscy(env, policy, numero_partite=1000):\n",
        "\n",
        "    tot_rew = 0\n",
        "    state = env.reset()\n",
        "\n",
        "    for _ in range(numero_partite):\n",
        "\n",
        "        done = False\n",
        "        while not done:\n",
        "            next_state, reward, done,_ = env.step(policy[state])\n",
        "\n",
        "            state = next_state\n",
        "            tot_rew += reward\n",
        "\n",
        "            if done:\n",
        "                state = env.reset()\n",
        "\n",
        "    print(\"Sono state vinte: \",int(tot_rew),\" su \", numero_partite, \"partite giocate\")"
      ],
      "metadata": {
        "id": "RzatFdqNAw15"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "test_optimal_poliscy(env,optimal_policy)\n",
        "#\n",
        "# Concludendo#\n",
        "#\n",
        "# La optimal policy mira a massimizzare la probabilità\n",
        "# di raggiungere l'obiettivo"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "_cJQH7ACG5Do",
        "outputId": "e2be0090-e618-4653-aeeb-53bfb8920a3e"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Sono state vinte:  740  su  1000 partite giocate\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Considerazioni finali sull'interazione tra la fase Policy evaluation e la fase Policy improvement.\n",
        "\n",
        "In merito a tale interazione, il seguente passo dal testo di Sutton & Barto, pag PDF : 108, è molto esplicativo:\n",
        "\n",
        "\n",
        "\" Almost all reinforcement learning methods are well described as generalized policy iteration. That is, all have identifiable policies and value functions, with the policy always  being improved with respect to the value function and the value function always being driven toward the value function for the  policy.\n",
        "If both the evaluation process and the improvement process stabilize, that  is, no longer produce changes, then the value function and policy must be optimal.\n",
        "The value function stabilizes only when it is consistent with the current policy, and the policy stabilizes only when it is greedy with respect to the current value function. Thus, both processes stabilize only when a policy has been found that is greedy with\n",
        "respect to its own evaluation function\" ...\n"
      ],
      "metadata": {
        "id": "GDFnyEKNjWmZ"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Value Iteration\n",
        "\n",
        "Problema:\n",
        "\n",
        "Uno svantaggio del metodo di Policy Iteration è che ciascuna delle sue iterazioni comporta una  fase di Policy evaluation, che può essere un calcolo iterativo lungo e computazionalmente costoso.\n",
        "\n",
        "Soluzione:\n",
        "\n",
        "Sfruttare la seguente regola di update, basata sull' equazione di ottimalità di Bellman :\n",
        "\n",
        "<div>\n",
        "<img src= \"data:image/png;base64,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\"\n",
        ", width=\"400\">\n",
        "</div>\n",
        "\n",
        "\n",
        "\n",
        "\n",
        "Intuitivamente : si inizia con le ricompense finali e si lavora a ritroso. Senza coinvolgere nessuna policy.\n",
        "\n",
        "<div>\n",
        "<img src= \"\n",
        "\n",
        "\"\n",
        ", width=\"400\">\n",
        "</div>"
      ],
      "metadata": {
        "id": "vTduSK8MTPb6"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Value Iteration Algorithm  :\n",
        "\n",
        "1. Inizializza la funzione valore.\n",
        "2. Sviluppa un loop iterativo, simile a quello della policy evalutation (ma senza policy!), che sfrutta la regola di update sopra indicata\n",
        "3. estrai la policy ottimale dalla funzione valore ottenuta nel passaggio 2.\n",
        "\n",
        "\n",
        "Per capirci di più studiare il codice sottostante: Esempio applicativo - Value Iteration - Frozen Lake"
      ],
      "metadata": {
        "id": "Sm40ArtfcqN3"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Note:\n",
        "\n",
        "\n",
        "-   Le condizioni che garantiscono la convergenza sono le stesse del caso della Policy evaluation\n",
        "-   L'aggiornamento è simile a quello della policy evaluation, con una sola differenza: si prende solo il valore massimo su tutte le  possibili azioni.\n",
        "- A differenza dell'algoritmo di Policy Iteration, che valuta e poi migliora la politica, l'algoritmo di Value Iteration lavora solo sulla funzione valore di stato. Ciò è possibile perché l'algoritmo può calcolare tutte le possibili ricompense future per ogni stato. La policy è implicitamente estratta dalla funzione valore alla fine dell'algoritmo\n",
        "\n"
      ],
      "metadata": {
        "id": "RlnF7tbObtuF"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Esempio applicativo - Value Iteration - Frozen Lake"
      ],
      "metadata": {
        "id": "Bu7BynopcKAj"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Il codice sottostante è stato ispirato ed ha come riferimento:\n",
        "#https://github.com/PacktPublishing/Deep-Reinforcement-Learning-with-Python/blob/master/03.%20Bellman%20Equation%20and%20Dynamic%20Programming/3.06.%20Solving%20the%20Frozen%20Lake%20Problem%20with%20Value%20Iteration.ipynb\n",
        "# di Sudharsan Ravichandiran\n",
        "\n",
        "import gym\n",
        "import numpy as np\n",
        "\n",
        "# se si desidera il redering caricare anche i moduli qui sotto\n",
        "from matplotlib import pyplot as plt\n",
        "%matplotlib inline\n",
        "from IPython import display\n",
        "\n",
        "env = gym.make('FrozenLake-v1')\n",
        "\n",
        "def query_environment(name):\n",
        "    env = gym.make(name)\n",
        "    spec = gym.spec(name)\n",
        "    print(f\"Action Space: {env.action_space}\")\n",
        "    print(f\"Observation Space: {env.observation_space}\")\n",
        "    print(f\"Max Episode Steps: {spec.max_episode_steps}\")\n",
        "    print(f\"Reward Range: {env.reward_range}\")\n",
        "\n",
        "query_environment('FrozenLake-v1')"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "5-3Bbb8_cPwK",
        "outputId": "fb4685d0-add3-4714-df23-7bfa648a9b34"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Action Space: Discrete(4)\n",
            "Observation Space: Discrete(16)\n",
            "Max Episode Steps: 100\n",
            "Reward Range: (0, 1)\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stderr",
          "text": [
            "/usr/local/lib/python3.10/dist-packages/gym/core.py:317: DeprecationWarning: \u001b[33mWARN: Initializing wrapper in old step API which returns one bool instead of two. It is recommended to set `new_step_api=True` to use new step API. This will be the default behaviour in future.\u001b[0m\n",
            "  deprecation(\n",
            "/usr/local/lib/python3.10/dist-packages/gym/wrappers/step_api_compatibility.py:39: DeprecationWarning: \u001b[33mWARN: Initializing environment in old step API which returns one bool instead of two. It is recommended to set `new_step_api=True` to use new step API. This will be the default behaviour in future.\u001b[0m\n",
            "  deprecation(\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "def vi_compute_value_fuction(gamma):\n",
        "\n",
        "    #limite o threshold value - accuracy of estimation\n",
        "    threshold = 1e-12\n",
        "\n",
        "    #Inizializziamo all'inizio di ogni ciclo iterativo\n",
        "    value_table = np.zeros(env.observation_space.n)\n",
        "\n",
        "    #contatore iterazioni\n",
        "    i=0\n",
        "\n",
        "    while True:\n",
        "\n",
        "        #Appoggiamo la funzione-valore appresa nel ciclo iterativo precedente nella locazione: odl_value_table\n",
        "        old_value_table = np.copy(value_table)\n",
        "\n",
        "        # per ogni stato s\n",
        "        for s in range(env.observation_space.n):\n",
        "\n",
        "            #Calcolo della funzione-valore sfruttando update della Bellman optimality equation\n",
        "            #Si noti : l'aggiornamento seguente è simile a quello della policy evaluation,\n",
        "            # con una sola differenza: si prende solo il valore massimo su tutte le  possibili azioni.\n",
        "               support_array_values = [sum([prob*(r + gamma * old_value_table[s_])\n",
        "                             for prob, s_, r, _ in env.P[s][a]])\n",
        "                                   for a in range(env.action_space.n)]\n",
        "\n",
        "               value_table[s] = max(support_array_values)\n",
        "\n",
        "        # Visualizza cosa succede nel ciclo iterativo, durante la propagazione dell'informazione.\n",
        "        if (i < 8) or (i > 318):\n",
        "              print(\"\\n Ciclo: \",i,\"  Value_table : \\n\",value_table.reshape((4,4)).round(decimals=4))\n",
        "\n",
        "        if (np.sum((np.fabs(old_value_table - value_table))) <= threshold):\n",
        "            break\n",
        "\n",
        "        i+= 1\n",
        "\n",
        "    print(\"\\n Value Iteration Loop : Value_table OUT: \\n\",value_table.reshape((4,4)).round(decimals=4))\n",
        "    print(\"La convegenza della Value_table è stata ottenuta dopo \",i+1,\" iterazioni.\")\n",
        "\n",
        "    return value_table"
      ],
      "metadata": {
        "id": "nZ3i_bpyb_zy"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "def obtain_policy(value_table,gamma):\n",
        "\n",
        "    # inizializziamo la struttura della policy\n",
        "    policy = np.zeros(env.observation_space.n)\n",
        "\n",
        "    for s in range(env.observation_space.n):\n",
        "        # aggiornare la policy con l'azione greedy in accordo con la value table(next state), su ogni azione disponibile\n",
        "        act_greedy = np.argmax([np.sum([prob * (r + gamma*value_table[s_]) for prob, s_, r, _ in env.P[s][a]]) for a in range(env.action_space.n)])\n",
        "        policy[s] =  act_greedy\n",
        "\n",
        "    return policy"
      ],
      "metadata": {
        "id": "yA4-Zja5s6ju"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "def value_iteration():\n",
        "\n",
        "    #Discount factor\n",
        "    gamma = 0.95\n",
        "\n",
        "    optimal_value_table = vi_compute_value_fuction(gamma)\n",
        "    policy = obtain_policy(optimal_value_table,gamma)\n",
        "\n",
        "\n",
        "    #Display la policy\n",
        "    a2w = {0:'<', 1:'v', 2:'>', 3:'^'}\n",
        "    ap = np.array([])\n",
        "    for i in policy:\n",
        "       ap = np.append(ap,a2w[int(i)])\n",
        "    print(\"\\nPolicy OUT: \\n\",ap.reshape((4,4)))\n",
        "\n",
        "    return policy"
      ],
      "metadata": {
        "id": "dmC5mjhNtkDi"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "optimal_policy = value_iteration()"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "SlegI6HwuSIY",
        "outputId": "f3b918bf-4691-4ff2-f355-27f76266aa6c"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "\n",
            " Ciclo:  0   Value_table : \n",
            " [[0.     0.     0.     0.    ]\n",
            " [0.     0.     0.     0.    ]\n",
            " [0.     0.     0.     0.    ]\n",
            " [0.     0.     0.3333 0.    ]]\n",
            "\n",
            " Ciclo:  1   Value_table : \n",
            " [[0.     0.     0.     0.    ]\n",
            " [0.     0.     0.     0.    ]\n",
            " [0.     0.     0.1056 0.    ]\n",
            " [0.     0.1056 0.4389 0.    ]]\n",
            "\n",
            " Ciclo:  2   Value_table : \n",
            " [[0.     0.     0.     0.    ]\n",
            " [0.     0.     0.0334 0.    ]\n",
            " [0.     0.0669 0.139  0.    ]\n",
            " [0.     0.1724 0.5057 0.    ]]\n",
            "\n",
            " Ciclo:  3   Value_table : \n",
            " [[0.     0.     0.0106 0.    ]\n",
            " [0.     0.     0.044  0.    ]\n",
            " [0.0212 0.0986 0.1919 0.    ]\n",
            " [0.     0.2359 0.5481 0.    ]]\n",
            "\n",
            " Ciclo:  4   Value_table : \n",
            " [[0.     0.0034 0.0173 0.0034]\n",
            " [0.0067 0.     0.0641 0.    ]\n",
            " [0.0379 0.1422 0.2187 0.    ]\n",
            " [0.     0.2795 0.5816 0.    ]]\n",
            "\n",
            " Ciclo:  5   Value_table : \n",
            " [[0.0032 0.0065 0.0268 0.0076]\n",
            " [0.0141 0.     0.0747 0.    ]\n",
            " [0.0592 0.1698 0.2495 0.    ]\n",
            " [0.     0.3177 0.606  0.    ]]\n",
            "\n",
            " Ciclo:  6   Value_table : \n",
            " [[0.0076 0.0116 0.0346 0.0133]\n",
            " [0.0242 0.     0.0875 0.    ]\n",
            " [0.077  0.1983 0.2693 0.    ]\n",
            " [0.     0.3463 0.6258 0.    ]]\n",
            "\n",
            " Ciclo:  7   Value_table : \n",
            " [[0.0137 0.017  0.0429 0.0194]\n",
            " [0.0344 0.     0.0962 0.    ]\n",
            " [0.0949 0.2193 0.2887 0.    ]\n",
            " [0.     0.3706 0.6412 0.    ]]\n",
            "\n",
            " Ciclo:  319   Value_table : \n",
            " [[0.1805 0.1548 0.1535 0.1325]\n",
            " [0.209  0.     0.1764 0.    ]\n",
            " [0.2705 0.3747 0.4037 0.    ]\n",
            " [0.     0.509  0.7237 0.    ]]\n",
            "\n",
            " Value Iteration Loop : Value_table OUT: \n",
            " [[0.1805 0.1548 0.1535 0.1325]\n",
            " [0.209  0.     0.1764 0.    ]\n",
            " [0.2705 0.3747 0.4037 0.    ]\n",
            " [0.     0.509  0.7237 0.    ]]\n",
            "La convegenza della Value_table è stata ottenuta dopo  320  iterazioni.\n",
            "\n",
            "Policy OUT: \n",
            " [['<' '^' '<' '^']\n",
            " ['<' '<' '<' '<']\n",
            " ['^' 'v' '<' '<']\n",
            " ['<' '>' 'v' '<']]\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Si noti:\n",
        "\n",
        "*Quelle ottenute, sono esattamente la stessa policy e la stessa value_fuction ottenute nel processo di Policy Iteration.*\n",
        "\n",
        "*\n",
        "\n",
        "Per chi desidera esercitarsi ulteriormente, suggerisco di risolvere l'esercizio:\n",
        "\n",
        "https://github.com/dennybritz/reinforcement-learning/blob/master/DP/Gamblers%20Problem.ipynb\n",
        "\n"
      ],
      "metadata": {
        "id": "LAXDj5x0aLnT"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "# Alcune considerazioni finali sulla Dynamic Programming nel contesto RL\n",
        "\n",
        "1.Asynchronous Dynamic Programming methods\n",
        "\n",
        "I metodi iterativi della DP possono essere troppo costosi per essere applicati a problemi con un numero di stati molto elevato. Questi devono aggiornare ogni stato dell'MDP, anche se non sono tutti importanti per trovare la politica ottimale.\n",
        "\n",
        "Ad esempio, il gioco del backgammon ha più di $10^{20}$ stati. Anche se potessimo eseguire l'aggiornamento della Value iteration su un milione di stati al secondo ci vorrebbero più di mille anni per completare un'unica scansione dell'intero spazio di stati.\n",
        "\n",
        "\n",
        "Per soluzioni ed idee, che consentono la gestione in modo più efficente della propagazione delle informazioni all'interno dei cicli iterativi (rispetto i metodi classici della DP), riducendo significativamente il calcolo computazionale e garantendo la convergenza, vedere : *Asynchronous Dynamic Programming algorithms*.\n",
        "Come esempio, per capire l'idea intuitiva di base prendiamo il metodo Prioritized Sweeping: nella selezione degli stati da aggiornare, assegna priorità agli stati che, secondo un certo criterio, si ritiene abbiano il maggiore impatto sulla politica ottimale.\n",
        "\n",
        "*Nei problemi con un grande numero di stati, spesso vengono preferiti i metodi Asynchronous Dynamic Programming*\n",
        "\n",
        "°\n",
        "\n",
        "2.Quando usare la DP?\n",
        "\n",
        "Condizione primaria di utilizzo: tutto è matematicamente esprimibile e analizzabile (MDP è completamente conosciuto).\n",
        "\n",
        "Se il problema è relativamente piccolo (nei computer moderni, forse qualche centinaia di migliaia di stati e fino a poche centinaia di azioni), i metodi DP potrebbero essere la soluzione migliore perché sono i più stabili, i più sicuri e offrono le più semplici garanzie di convergenza.\n",
        "\n",
        "I metodi DP potrebbero non essere pratici per problemi molto grandi, ma sono comunque più efficienti di altri metodi per risolvere MDP. Infatti, nello scenario peggiore (cioè quando l'algoritmo impiega il tempo più lungo per convergere verso la politica ottimale), i metodi di programmazione dinamica possono trovare una politica ottimale per un processo decisionale di Markov in un tempo polinomiale nel numero di stati (n) e azioni (k). In altre parole, la complessità computazionale dei metodi DP per trovare una politica ottimale cresce a un ritmo che non è altro che una funzione polinomiale di (n) e (k).\n",
        "\n",
        "Quindi, sia $T(n,k)$ il tempo di esecuzione dell'algoritmo DP, su input stati/azioni di dimensione $f(n,k)$.\n",
        "\n",
        "$T(n,k) \\le c_{d} f(n,k)^{d} + c_{d-1} f(n,k)^{d-1} + ... + c_{1} f(n,k)^{1} + c_{0} $\n",
        "\n",
        "dove il grado $d ≥ 0$ ed i coifficenti $c_{d},...,c_{1},c_{0}$ sono costanti\n",
        "\n",
        "Questo è un risultato notevole, perché il numero totale di politiche deterministiche per un MDP è $k^{n}$, che può essere un numero enorme. In questo senso, la DP è esponenzialmente più veloce di qualsiasi ricerca diretta nello spazio delle politiche, che dovrebbe esaminare in modo esaustivo ciascuna politica per trovare quella l'ottimale. In sintesi la DP riduce la complessità di esecuzione di un algoritmo dal tempo esponenziale al tempo polinomiale.\n",
        "\n",
        "°\n",
        "\n",
        "3.Policy Iteration vs. Value Iteration\n",
        "\n",
        "Policy iteration e value iteration sono entrambi metodi ampiamente utilizzati, e non è ancora chiaro quale dei due sia complessivamente migliore.\n",
        "\n",
        "*Entrambi tendono a convergere più rapidamente se vengono inizializzati con appropriate funzioni valore o policy.*\n",
        "\n",
        "\n",
        "°\n",
        "\n",
        "4.Bootstrapping\n",
        "\n",
        "\n",
        "I metodi DP aggiornano le stime dei valori degli stati sulla base delle stime dei valori degli stati successivi. Questo è un esempio di bootstrapping (un metodo che aggiorna un valore di una stima in base ad alcune stime ottenute in precedenza, e non ai valori esatti)\n",
        "\n",
        "Anche molti altri metodi di RL eseguono il bootstrap, ma non tutti richiedono un modello MDP completo e accurato dell'ambiente come la programmazione dinamica."
      ],
      "metadata": {
        "id": "Y1GXleipRy3a"
      }
    }
  ]
}