Policy_Gradient__ITA.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": [],
      "collapsed_sections": [
        "W-D7yGghOtof",
        "PCQDs_HibFNI"
      ]
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "#Policy Based Methods\n",
        "\n",
        "Mario Fiorino\n",
        "\n",
        "$\\;$\n",
        "\n",
        "**Introduzione**\n",
        "\n",
        "I metodi presentati nei notebook precedenti (noti come approcci \"value-based\" o \"action-value methods\") si basano sulla funzione valore $Q(s,a)$ . Ovvero:\n",
        "\n",
        "- Si apprendere la funzione $Q(s,a)$ attraverso l'interazione con l'ambiente.  \n",
        "\n",
        "- Una volta appresa tale la funzione, l'agente seleziona l'azione da intraprendere nello stato corrente $s$ basandosi sui valori stimati di $Q(s,a)$. Tipicamente, viene scelta l'azione che massimizza il valore di $Q(s,a)$.\n",
        "\n",
        "-  Tali metodi non esplicitano una funzione policy $\\pi:  a → s $, poichè questa è implicitamente determinata dai valori di $Q(s,a)$.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "I metodi \"policy-based\" invece:\n",
        "\n",
        "Apprendono una mappatura (funzione di policy) diretta dallo stato all'azione, senza la necessità di consultare una funzione valore stato-azione $Q(s,a)$.\n",
        "\n",
        "Ad esempio, questa mappatura può essere implementata utilizzando una rete neurale dove il valore dei parametri, pesi e bias, è determinato durante l'addestramento per massimizzare il return.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Vantaggi\n",
        "\n",
        "- Presentano una buona efficacia nei \"High-dimensional space\" ed/o nei \"Continuous action spaces\".\n",
        "\n",
        "- Semplificano l'implementazione quando la policy da apprendere è di tipo stocastico: cioè che descrive una distribuzione di probabilità sulle azioni.\n",
        "\n",
        "- Tali medoti consentono di sfruttare eventuali conosceze pregressa sulla forma desiderata della funzione di policy.\n",
        "\n",
        "Svantaggi:\n",
        "\n",
        "- Presentano un'alta varianza; tendendo a convergere verso un ottimo locale, piuttosto che verso l'ottimo globale."
      ],
      "metadata": {
        "id": "7XIrltRMwtbO"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Idee di base\n",
        "\n"
      ],
      "metadata": {
        "id": "zmDpyzWy_uk9"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Notazioni**\n",
        "\n",
        "$\\textbf{θ}$ è il vettore dei parametri della policy $\\pi_\\theta$ , con dimensioni $d'$. Ovvero : $\\textbf{θ} \\in R^{d'}$\n",
        "\n",
        "$\\pi(a|s, \\textbf{θ}) = Pr \\{ A_t =a | S_t =s, \\textbf{θ}_t = \\textbf{θ} \\} \\; \\; $  indica la probabilità che l'azione $a$ venga intrapresa nello stato $s$ al tempo $t$, con i parametri della policy uguali $\\textbf{θ}$.\n",
        "\n",
        "$J(\\textbf{θ})$ è una funzione, spesso chiamata **funzione obiettivo** (*objective function*), che misura le performance policy ${\\pi_\\theta}$, dipendente dalla variazione dei suoi parametri. Ad esempio negli ambienti episodici, un modo molto semplice per valutare tale rendimento, è quello di scegliere la value fuction della policy nello stato di partenza, cioè expected return ottenuto seguendo tale policy,  partendo da uno specifico stato iniziale :\n",
        "$J(\\textbf{θ}) = V_{\\pi_\\theta} (s_{0}) = \\mathbb{E}_{ {\\pi_\\theta}} [ \\sum_{t=0}^{T} r_t | s_0] $ .\n",
        "\n",
        "Si noti, in questa introduzione, per semplicità didattica, si assume che il discount factor $\\gamma = 1 $, e,  si considera un numero finito di episodi.\n",
        "\n",
        "$s_0$ indica lo stato iniziale.\n",
        "\n",
        "$r_t$ è il reward ottenuto allo step $t$.\n",
        "\n",
        "$T$ è lo step nel Terminal state.\n",
        "\n",
        "Sia  $\\tau$ una certa traiettoria di eventi stato-azione campionata da $\\pi_\\theta$ che parte da un stato $s_0$ (  Nota, in questa semplice formulazione, assumerò che il valore di $s_0$ sia costante, ossia l'agente inizierà ogni volta dallo stesso stato, generando da lì diverse traiettorie)\n",
        "\n",
        "$\\tau = (s_0, a_0, s_1, a_1, ..., s_T).$\n",
        "\n",
        "Allora:\n",
        "\n",
        "$  \\mathbb{E}_{ {\\pi_\\theta}} [ \\sum_{t=0}^{T} r_t | s_0] = \\mathbb{E}_{\\tau\\sim \\pi_θ} [R(\\tau)] = \\int_{\\tau} P(\\tau|\\pi_\\theta) R(\\tau) $\n",
        "\n",
        "Dove $R(\\tau)$ è il \"Return\", ovvero la somma totale dei reward ottenuti seguendo una certa traiettoria $\\tau$ di eventi stato-azione campionati da $\\pi_\\theta$.\n",
        "\n",
        "Mentre $P(\\tau|\\pi_\\theta)$ è la probabilità di ottenere $\\tau$ segeundo una certa policy $\\pi_\\theta$. Per essere formalmente più precisi:\n",
        "\n",
        "$P(\\tau|\\pi_\\theta) =  \\prod_{t=0}^{T-1} P(s_{t+1} | s_t, a_t) \\pi_\\theta(a_t | s_t)$\n",
        "\n",
        "La formula evidenzia come il campionamento di una traiettoria sia condizionato:\n",
        "- dalla policy $\\pi_\\theta$  \n",
        "- dal modello di transizione, che descrive la probabilità di passare da uno stato all'altro: la così detta \"dinamica dell'ambiente\"; nei contesti model-free ignota.\n",
        "\n",
        "Nota nella produttoria abbiamo $T-1$, in quanto $P(s_{T} | s_{T-1}, a_{T-1})$; dove $s_T$ è lo stato terminale\n",
        "\n",
        "$\\;$\n",
        "\n",
        "**Obiettivo**:\n",
        "\n",
        "Stimare (o apprendere) i parametri $\\textbf{θ}$  della policy al fine di massimizzare il valore della funzione obiettivo.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Come?\n",
        "\n",
        "Per risolvere tale problema, si possono impiegare diverse strategie, le più comuni si suddividono in due categorie:\n",
        "\n",
        "Metodi non basati sul gradiente:\n",
        "\n",
        "- Hill climbing (Questo metodo esplora lo spazio dei parametri in modo iterativo, muovendosi nella direzione che aumenta i valori della funzione obiettivo)\n",
        "\n",
        "- Simplex / amoeba / Nelder Mead\n",
        "\n",
        "- Genetic algorithms\n",
        "\n",
        "Metodi basati sul gradiente:\n",
        "\n",
        "- Gradient descent\n",
        "\n",
        "- Conjugate gradient\n",
        "\n",
        "- Quasi-newton\n",
        "\n",
        "\n",
        "In questo notebook, ci concentriamo specificamente sull' approccio Gradient descent; data la sua ampia diffusione, e la sua efficacia in molti scenari."
      ],
      "metadata": {
        "id": "7QMy3PYTFCe5"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Policy Gradient\n",
        "\n",
        "L'idea di fondo dei metodi policy gradient è quello di ottimizzare la policy del sistema incrementando la probabilità di azioni che conducono a rendimenti più elevati, e diminuendo la probabilità di azioni associate a rendimenti inferiori.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Consideriamo la funzione obiettivo descritta nell'introduzione:\n",
        "\n",
        "$ J(\\textbf{θ}) = \\mathbb{E}_{\\tau\\sim \\pi_θ} [R(\\tau)]  $\n",
        "\n",
        "Gli algoritmi policy gradient si prefiggono di individuare quei valori ottimali dei parametri $\\mathbf{θ^{*}}$ che definiscono la policy $\\pi_\\mathbf{θ}$, con l'obiettivo di massimizzare la funzione obiettivo $J(\\mathbf{θ})$.\n",
        "Per realizzare ciò, questi algoritmi impiegano la tecnica del **Gradient ascent optimization**, ovvero, aggiornando i parametri nel seguente modo:\n",
        "\n",
        "$\\mathbf{\\theta_{k+1}} = \\mathbf{\\theta_k} + \\alpha \\nabla_{\\mathbf{\\theta}} J(\\mathbf{\\theta_k}) \\; \\;$ $\\; \\;$  \n",
        "\n",
        "Nota formale - limitazioni di LaTeX nel notebook: se pur nell'equazione esposta, i parametri $\\mathbf{{\\theta_k}}$ non sono rappresentati in grassetto, sono sempre da pensarsi come vettori di dimensione $d'$.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "**Problema** : Come ricavare  $\\nabla_{\\theta} J(\\textbf{θ})$ ?\n",
        "\n",
        "Non è sempre possibile ricavare la derivata (\"in forma chiusa\") di  $\\mathbb{E}_{\\tau\\sim \\pi_θ} [R(\\tau)] $ rispetto a $\\textbf{θ}$, in quanto, in genere, non abbiamo una forma analitica esplicita di questa dipendente da $\\textbf{θ}$ ( per definizione, nei contesti model-free la dinamica dell'ambiente e la funzione reward sono del tutto ignoti)\n",
        "\n",
        "Quindi non possiamo calcolare direttamente il gradiente $\\nabla_{\\theta} J(\\mathbf{θ})$.\n",
        "\n",
        "Che fare?"
      ],
      "metadata": {
        "id": "XKGVY4WNPoR1"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "#####Soluzione: **Policy Gradient Theorem**\n",
        "\n",
        "Il teorema Policy Gradient fornisce un'espressione analitica computazionalmente fattibile del gradiente in questione:\n",
        "\n",
        "$\\nabla_{\\theta} J(\\mathbf{θ}) = \\mathbb{E}_{\\tau\\sim \\pi_θ} [\\; \\sum_{t=0} ^ {T} R_t(\\tau)  \\cdot  \\nabla_{\\theta} \\log \\pi_{θ}(a_t|s_t) \\; ] $\n",
        "\n",
        "Dove:\n",
        "\n",
        "$R_t(τ ) = \\sum_{t'= t} ^{T} r_{t'}$ cioè la somma dei singoli reward raccolti dallo step temporale $t$ alla fine della traiettoria.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Per la verifica analitico-matematica del teorema:\n",
        "\n",
        "Foundations of Deep Reinforcement Learning, Graesser & Wah Loon Keng, PDF 57\n",
        "\n",
        "oppure, altre versioni:\n",
        "\n",
        "Sutton & Barto, 2018, PDF 347\n",
        "\n",
        "o:\n",
        "\n",
        "https://users.ece.cmu.edu/~yuejiec/ece18813B_notes/lecture12-policy-optimization.pdf\n",
        "\n",
        "$\\;$\n",
        "\n",
        "In pratica, il teorema esprime una relazione tra il gradiente della policy: $\\nabla_{\\theta} \\pi(a|s)$, un vettore colonna che possiamo campionare, ed, il gradiente $ \\nabla_{\\theta} J(\\mathbf{θ})$.\n",
        "Quindi, così espresso, possiamo usare un campionamento per approssimarlo.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Formulazione generale in sintesi:\n",
        "\n",
        "Sia $X$ una variabile casuale, e data una funzione di densità di probabilità  $p_θ(x)$. Si definisce funzione obiettivo $J(θ)$:\n",
        "\n",
        "$J(θ)=\\mathbb{E_{x∼p_θ(x)}}[f(x)] = ∫_x f(x)p_{θ} (x)dx$\n",
        "\n",
        "Per $f(x)$ funzione arbitraria che non dipende da $θ$\n",
        "\n",
        "Vogliamo calcolare $∇_θ J(θ)$.\n",
        "\n",
        "Con delle manipolazioni matematiche, possiamo cambiare il gradiente dell'expectation nell'expectation del gradiente; saltando molti passaggi otteniamo:\n",
        "\n",
        "$ ∇_θ J(θ) = ∇_θ ∫_x f(x) ∇_θ p_θ(x) dx = \\mathbb{E}[f(x)∇_θ \\log(p_θ(x) )]$\n",
        "\n",
        "Si osservi, che avremmo potuto scegliere anche un'altra funzione obiettivo, il risultato finale del Policy Gradient Theorem è indipendente da questa scelta.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Ref:\n",
        "\n",
        "Foundations of Deep Reinforcement Learning: Theory and Practice in Python di Laura Graesser, Wah Loon Keng.\n",
        "\n",
        "Reinforcement Learning: An Introduction. Richard S. Sutton and Andrew G. Barto. 2018\n",
        "\n",
        "Compendio Policy Gradient Algorithms, chiaro e completo:\n",
        "\n",
        "https://lilianweng.github.io/posts/2018-04-08-policy-gradient/\n",
        "\n",
        "Corso di David Silver:\n",
        "\n",
        "https://www.youtube.com/watch?v=KHZVXao4qXs\n",
        "\n",
        "Elliot Waite - Machine learning video; un ottima spiegazione con un esempio pratico:\n",
        "\n",
        "https://www.youtube.com/watch?v=cQfOQcpYRzE\n",
        "\n",
        "A List of Reinforcement Learning Derivations\n",
        "\n",
        "https://www.alexirpan.com/rl-derivations/\n",
        "\n",
        "*\n",
        "\n",
        "Expectation and Functions of Random Variables\n",
        "\n",
        "https://imai.fas.harvard.edu/teaching/files/Expectation.pdf\n",
        "\n",
        "\n",
        "*\n",
        "\n",
        "Per capire al meglio la tecnica \"Gradient ascent optimization\", si provi a ricavare con questa, a modo di esercizio, il punto in cui la funzione $J(x) = 3x - x^2$ assume il valore massimo. [Soluzione: La derivata di $J(x)$ è $ 3 - 2 x$ ; punto di massimo $x = 1.5$ ]\n",
        "\n"
      ],
      "metadata": {
        "id": "xa_xEdL5g9Rl"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## REINFORCE (aka Monte Carlo Policy Gradient)\n",
        "\n",
        "\n",
        "REINFORCE = REward Increment = Non-negative Factor × Offset Reinforcement × Characteristic Eligibility\n",
        "\n",
        "\n",
        "L'algoritmo è stato introdotto da Ronald J. Williams nel 1992.\n",
        "\n",
        "https://people.cs.umass.edu/~barto/courses/cs687/williams92simple.pdf\n",
        "\n",
        "$\\;$\n",
        "\n",
        "Implementazione dell'algoritmo in pseudocodice:\n"
      ],
      "metadata": {
        "id": "4nrDVHLiZeK2"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "<div>\n",
        "<img src=\"data:image/png;base64,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\", width=\"400\">\n",
        "</div>"
      ],
      "metadata": {
        "id": "DZ7zCHU3-jj1"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Idee chiave**:\n",
        "\n",
        "- L' apprendimento dei parametri $\\mathbf{θ}$ avviene tramite la tecnica *Gradient ascent optimization* . Per implementarla si sfrutta il *Policy Gradient Theorem*, così da ricavare $\\nabla_{\\theta} J(\\mathbf{θ})$.\n",
        "\n",
        "- Il campionamento di $\\nabla_{\\theta} J(\\mathbf{θ})$ viene effettuato utilizzando il metodo Monte Carlo. Questo significa che, per ogni episodio, viene generata una traiettoria (ottenuta dall'interazione dell'agente con l'ambiente, seguendo una certa policy $\\pi_θ$) fino ad uno stato terminale.\n",
        "\n",
        "- Generata la traiettoria, vengono calcolati i return parziali $R_t$ per ogni time step $t$ :  questi rappresentano il ritorno accumulato a partire da ogni step $t$ fino allo stato terminale. Questi return parziali vengono combinati tra loro attraverso una somma pesata, dove il peso associato a ciascun step è dato da $\\nabla_{\\theta} \\log \\pi_{θ}(a_t|s_t)$; così da ottenere una stima di $\\nabla_{\\theta} J(\\mathbf{θ})$ .\n",
        "\n",
        "Si noti:\n",
        "\n",
        "L' aggiormento dei parametri avviene esclusivamente al termine, e, per ogni traiettoria campionata.\n",
        "\n",
        "Solo una volta ottenuti i nuovi parametri, viene estratta una nuova traiettoria."
      ],
      "metadata": {
        "id": "JqWtG5JZ-4mY"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Convergenza**\n",
        "\n",
        "Per valori di $α$ sufficentemente piccoli,\n",
        "è garantito un miglioramento delle prestazioni della policy nella massimizzazione della ricompensa.\n",
        "\n",
        "La convergenza verso un ottimo locale è garantita con le condizioni di approssimazione stocastica (stochastic approximation conditions) standard, viste più volte in questi notebook, per $α$ decrescente.\n",
        "\n",
        "$\\;$\n",
        "\n",
        "**Svantaggi**\n",
        "\n",
        "\n",
        "Come nel metodo Monte Carlo classico, in cui ogni coppia stato-azione di una traiettoria è generata in modo completamente casuale, REINFORCE può soffrire di un'elevata varianza. Questo comporta:  \n",
        "\n",
        "- Rallentamento nell'apprendimento: il miglioramento delle policy avviene di rado, causando una convergenza lenta.  \n",
        "\n",
        "- Tendenza a convergere su ottimi locali: raggiungere l'ottimo globale richiede spesso tempi impraticabili.  \n",
        "\n",
        "Numerosi studi hanno affrontato tale problema dell'elevata varianza\n",
        "\n",
        "Un primo meccanismo risolutivo estremamente semplice, descritto da Sutton e Barto (2018, PDF 351), è l'utilizzo di: REINFORCE with Baseline.\n",
        "\n",
        "Tuttavia, i migliori risultati sono stati ottenuti con approcci Actor-Critic, come A2C, PPO, SAC e DDPG, che rappresentano attualmente gli algoritmi di RL-model free più utilizzati in molte applicazioni.  \n"
      ],
      "metadata": {
        "id": "UAt3tzWBuKYI"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Env: Cart Pole (Gym)\n",
        "\n",
        "Nota : In CartPole, l'agente riceve una ricompensa con un valore pari a $+1$ per ogni singolo time-step in cui riesce a mantenere l'equilibrio .\n",
        "\n",
        "https://www.gymlibrary.dev/environments/classic_control/cart_pole/\n",
        "\n",
        "\n",
        "https://github.com/openai/gym/wiki/Table-of-environments\n"
      ],
      "metadata": {
        "id": "W-D7yGghOtof"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "import gym\n",
        "\n",
        "env=gym.make('CartPole-v1')\n",
        "#help(env.unwrapped)\n",
        "\n",
        "episodeNumber=2\n",
        "max_timeSteps=3\n",
        "\n",
        "\n",
        "for episodeIndex in range(1,episodeNumber):\n",
        "    initial_state=env.reset()\n",
        "\n",
        "    #print(\"Ep:\",episodeIndex)\n",
        "    #appendedObservations=[]\n",
        "\n",
        "    for timeIndex in range(1,max_timeSteps+1):\n",
        "        print(\"timeIndex=\",timeIndex)\n",
        "\n",
        "        random_action=env.action_space.sample()\n",
        "        print(\"random_action=\",random_action)\n",
        "\n",
        "        observation, reward, done,  info = env.step(random_action)\n",
        "\n",
        "        #appendedObservations.append(observation)\n",
        "\n",
        "        print(\"[Cart Position,Cart Velocity,Pole Angle,Pole Angular Velocity]:\",observation)\n",
        "        print(\"reward=\",reward)\n",
        "        print(\"done=\",done)\n",
        "        print(\"info=\",info)\n",
        "        print(\"\")\n",
        "\n",
        "        if done:\n",
        "            break\n",
        "\n",
        "env.close()"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "9xovkHfpOvek",
        "outputId": "57bda386-2e60-470f-98f1-68b97cbf90f5"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "timeIndex= 1\n",
            "random_action= 0\n",
            "[Cart Position,Cart Velocity,Pole Angle,Pole Angular Velocity]: [-0.03882672 -0.17139114  0.04385891  0.34949616]\n",
            "reward= 1.0\n",
            "done= False\n",
            "info= {}\n",
            "\n",
            "timeIndex= 2\n",
            "random_action= 1\n",
            "[Cart Position,Cart Velocity,Pole Angle,Pole Angular Velocity]: [-0.04225454  0.02308048  0.05084883  0.07095963]\n",
            "reward= 1.0\n",
            "done= False\n",
            "info= {}\n",
            "\n",
            "timeIndex= 3\n",
            "random_action= 0\n",
            "[Cart Position,Cart Velocity,Pole Angle,Pole Angular Velocity]: [-0.04179293 -0.1727322   0.05226803  0.37924212]\n",
            "reward= 1.0\n",
            "done= False\n",
            "info= {}\n",
            "\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "###Moduli ed Inizializzazione ambiente"
      ],
      "metadata": {
        "id": "PCQDs_HibFNI"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "import gym\n",
        "import numpy as np\n",
        "from collections import deque\n",
        "import warnings\n",
        "warnings.filterwarnings('ignore')\n",
        "import matplotlib.pyplot as plt\n",
        "plt.rcParams['figure.figsize'] = (16, 10)\n",
        "\n",
        "import torch\n",
        "import torch.nn as nn\n",
        "import torch.nn.functional as F\n",
        "import torch.optim as optim\n",
        "from torch.distributions import Categorical\n",
        "torch.manual_seed(0)\n",
        "\n",
        "import base64, io\n",
        "\n",
        "# For visualization\n",
        "from gym.wrappers.monitoring import video_recorder\n",
        "from IPython.display import HTML\n",
        "from IPython import display\n",
        "import glob\n",
        "\n",
        "device = torch.device(\"cuda:0\" if torch.cuda.is_available() else \"cpu\")\n",
        "device\n",
        "\n",
        "env = gym.make('CartPole-v1')"
      ],
      "metadata": {
        "id": "x82A8OrsML9i"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Premesse tecniche per una policy implementata tramite rete neurale\n",
        "\n",
        "La **funzione softmax** trasforma un vettore di numeri reali in una distribuzione di probabilità.\n",
        "\n",
        "In pratica, applica una funzione esponenziale a ciascun elemento, rendendolo positivo, e poi divide per la somma di tutti i valori esponenzializzati; ottenendo in uscita un valore compreso in un intervallo  $(0,1)$, e garantendo che la somma totale di tali valori di output risulti pari a $1$.\n",
        "\n",
        "Input di $N$ numeri reali:\n",
        "\n",
        "$[ z_1, z_2 ,...,z_i,...,z_N]$\n",
        "\n",
        "Output della funzione softmax:\n",
        "\n",
        "$[ \\sigma(z_1),\\sigma(z_2),...,\\sigma(z_i),...,\\sigma(z_N) ] = [\\frac{e^{z_{1}}}{\\sum_{j=1}^N e^{z_{j}}},\\frac{e^{z_{2}}}{\\sum_{j=1}^N e^{z_{j}}},..., \\frac{e^{z_{i}}}{\\sum_{j=1}^N e^{z_{j}}},... \\frac{e^{z_{N}}}{\\sum_{j=1}^N e^{z_{j}}} ]\\ $\n",
        "\n",
        "\n",
        "La funzione di softmax è spesso utilizzata nello strato di output delle reti neurali per gestire attività di classificazione.\n",
        "\n",
        "Questa assicura che l'output del modello possa essere interpretato come un insieme di probabilità per ogni classe.\n",
        "\n",
        "Nello scenario `'CartPole-v1'`, dove ci sono solo due azioni discrete ($N = 2$), la funzione softmax produce una distribuzione di probabilità su queste due azioni. Un output interpretabile in questo modo:\n",
        "\n",
        "$[\\pi(a_0 | s_t ),\\pi(a_1 | s_t )]$\n"
      ],
      "metadata": {
        "id": "M5NKE1oDoxAJ"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "v = np.array([[1,4,3],\n",
        "              [1,6,0]])\n",
        "v =  torch.from_numpy(v).float()\n",
        "\n",
        "# Funzione softmax in Pytorch\n",
        "# dim (int) – A dimension along which Softmax will be computed (so every slice along dim will sum to 1)\n",
        "\n",
        "softmax0 = torch.nn.Softmax(dim=0) # Applies along columns\n",
        "print(softmax0(v))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "-dFHXbyk25jl",
        "outputId": "d3e57435-374b-42fb-c920-1e8de9f1d7f4"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[0.5000, 0.1192, 0.9526],\n",
            "        [0.5000, 0.8808, 0.0474]])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "softmax1 = torch.nn.Softmax(dim=1) # Applies along rows\n",
        "print(softmax1(v))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "361zT7K1NeIn",
        "outputId": "f6ccfcee-ab32-4646-e8d0-1618127f99f3"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[0.0351, 0.7054, 0.2595],\n",
            "        [0.0067, 0.9909, 0.0025]])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "# Scenario CartPole-v1, ultima layer della NN\n",
        "tc = np.array([[-0.0344,  0.0977]])  # logit\n",
        "tc =  torch.from_numpy(tc).float()\n",
        "\n",
        "softmax2 = torch.nn.Softmax(dim=1)   # la \"funzione di attivazione\"\n",
        "print(softmax2(tc))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "tPOpDNmRV4Tg",
        "outputId": "923b6fdc-f562-4728-8a6e-9632dff0d122"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[0.4670, 0.5330]])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "I due tipi più comuni di **policy stocastiche** nell'ambito della Deep RL sono\n",
        "- le *categorical policies*\n",
        "- le *diagonal Gaussian policies*\n",
        "\n",
        "Si mostrerà in seguito come due concetti sono di fondamentale importanza per l'utilizzo e l'addestramento delle policy stocastiche:\n",
        "\n",
        "- il campionamento (sampling) delle azioni dalla policy\n",
        "\n",
        "- log-prob : ovvero il logaritmo di probabilità di estrare un azione specifica seguendo una certa policy, in simboli  $\\log \\pi_{\\theta}(a_t|s_t)$."
      ],
      "metadata": {
        "id": "o9NHkwfSizPn"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "\n",
        "**Categorical policy**\n",
        "\n",
        "Una *categorical distribution* è una forma specifica di distribuzione di probabilità per variabili aleatorie discrete, che riguarda variabili che assumono valori da un insieme finito di categorie distinte.\n",
        "\n",
        "Una *Categorical Policy* è una policy che assegna a ciascuna delle possibili azioni discrete in un determinato stato, una certa probabilità di essere campionata.\n",
        "\n",
        "Questa viene rappresentata da una \"categorical distribution\".\n",
        "\n",
        "In termini di reti neurali, esse possono essere pensate come classificatori: che ad ogni azione, associano a una probabilità.\n",
        "\n",
        "Implementazione:\n",
        "\n",
        "La classe `Categorical` in PyTorch implementa una distribuzione di probabilità discreta. Si può specificare la distribuzione in due modi (ma non contemporaneamente):\n",
        "\n",
        "- Probabilità (probs): Tramite un tensore contenente le probabilità relative di ciascuna categoria. La somma degli elementi di questo tensore deve essere pari a 1 (lungo la dimensione specificata durante il campionamento).\n",
        "\n",
        "- Logit (logits): Tramite un tensore contenente i logit (output non normalizzato in senso probabilistico) per ciascuna categoria.\n",
        "\n",
        "Se probs è unidimensionale con lunghezza $N$, ciascun elemento rappresenta la probabilità relativa di campionare la categoria corrispondente all'indice.\n",
        " ovvero i campioni saranno interi da ${0,…,N−1}$\n",
        "\n",
        "Info:\n",
        "\n",
        "https://pytorch.org/docs/stable/distributions.html"
      ],
      "metadata": {
        "id": "cx8R2Akdkjg5"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#Premessa: log_prob\n",
        "# Restituisce semplicemente il logaritmo della probabilità che si verifichi un determinato campione (o categoria)\n",
        "# estratto dalla distribuzione.\n",
        "# L'uso delle probabilità logaritmiche significa rappresentare le probabilità su una scala logaritmica (- ∞ , 0 ]\n",
        "#https://en.wikipedia.org/wiki/Log_probability\n",
        "#https://chrispiech.github.io/probabilityForComputerScientists/en/part1/log_probabilities/\n",
        "\n",
        "print(\"E1\")\n",
        "m = Categorical(torch.tensor([ 0.25, 0.25, 0.25, 0.25 ]))\n",
        "s = m.sample() # è un tensore che contiene l'indice campionato del vettore [ 0.25, 0.25, 0.25, 0.25 ].\n",
        "print(s)       # Nota: in questo cosa ci sono uguali probabilità di campionare: tensor(0), tensor(1), tensor(2), tensor(3)\n",
        "print(type(s)) # <class 'torch.Tensor'>\n",
        "\n",
        "print(m.log_prob(s)) #  Nota: il ln(0.25) = -1.38629436112 ; ln : \"natural logarithm\"\n",
        "print(np.ones(1)*3)  # = [3.]\n",
        "print(m.log_prob(torch.from_numpy(np.ones(1)*3)))\n",
        "# la log_probabilità di campionare 3. è uguale a quella di campionare 0.\n",
        "print(m.log_prob(torch.from_numpy(np.ones(1)*3)) == m.log_prob(torch.tensor([0.])) )"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "FgiKyfKo5kPx",
        "outputId": "347b5379-d67f-4161-d36b-1352defe346c"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "E1\n",
            "tensor(0)\n",
            "<class 'torch.Tensor'>\n",
            "tensor(-1.3863)\n",
            "[3.]\n",
            "tensor([-1.3863])\n",
            "tensor([True])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "print(\"E2\")\n",
        "m = Categorical(torch.tensor([ 0.9999, 0.00001 ]))\n",
        "s = m.sample()\n",
        "print(s)  # quasi sempre campiona 0\n",
        "print(m.log_prob(s))\n",
        "print(m.log_prob(torch.from_numpy(np.ones(1))))\n",
        "print(m.log_prob(torch.from_numpy(np.zeros(1))))\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "mZDT2_vWTrgN",
        "outputId": "0d0beaf2-3413-4e78-ec34-260aff98747b"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "E2\n",
            "tensor(0)\n",
            "tensor(-1.0014e-05)\n",
            "tensor([-11.5128])\n",
            "tensor([-1.0014e-05])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "print(\"E3\")  # Scenario CartPole-v1\n",
        "m = Categorical(torch.tensor([[0.4670, 0.5330]]))\n",
        "s = m.sample()\n",
        "print(s)\n",
        "print(m.log_prob(s))\n",
        "print(m.log_prob(torch.tensor([0.])))\n",
        "print(m.log_prob(torch.tensor([1.])))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "esY7w6ndT5HQ",
        "outputId": "ee158d93-2840-469e-9c5b-872840e2b8e4"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "E3\n",
            "tensor([1])\n",
            "tensor([-0.6292])\n",
            "tensor([-0.7614])\n",
            "tensor([-0.6292])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "print(\"E4\")\n",
        "m = Categorical(torch.tensor([1, 870, 19.9 ])) # qui lavora con i logit\n",
        "s = m.sample()\n",
        "print(s)\n",
        "print(m.log_prob(s))\n",
        "print(m.log_prob(torch.tensor([0.])))\n",
        "print(m.log_prob(torch.tensor([1.])))\n",
        "print(m.log_prob(torch.tensor([2.])))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "nOiMcaFkj0xZ",
        "outputId": "24995458-f112-4d49-a5b7-c8f56f53c782"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "E4\n",
            "tensor(1)\n",
            "tensor(-0.0237)\n",
            "tensor([-6.7922])\n",
            "tensor([-0.0237])\n",
            "tensor([-3.8015])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Diagonal Gaussian Policy**\n",
        "\n",
        "Le *Diagonal Gaussian Policy* sono un tipo particolare di policy utilizzate quando lo spazio delle azioni è continuo. In questo caso, una certa azione è rappresentata da un vettore n-dimensionale (con $n > 1$) a valori reali; pertanto, è necessario definire una distribuzione di probabilità su vettori a valori reali.\n",
        "\n",
        "Il modo più comune per rappresentare queste politiche è utilizzare una *Diagonal Gaussian distribution*, ovvero una *Distribuzione normale multivariata* la cui matrice di covarianza ha solo voci sulla diagonale (tutti gli altri sono sempre nulli - i.e. le diverse dimensioni dell'azione sono considerate indipendenti tra loro). Di conseguenza, tale matrice può essere rappresentata tramite un vettore di sole deviazioni standard.\n",
        "\n",
        "Per implementare una *Diagonal Gaussian Policy*, di solito si utilizzia una rete neurale che mappa gli stati $s_t$, in un *means vector* delle azioni, $\\mathbf{\\mu} (s_t)$ : dove ciascuna componente rappresenta la media della corrispondente componente del vettore azione.\n",
        "\n",
        "In più, si utilizza un vettore legato alle informazioni della deviazioni standard, che può essere implementato in diversi modi:\n",
        "\n",
        "- Il più semplice, definendo un vettore composto da valori costanti delle deviazioni standard: $\\sigma$, una per ciascun componente del vettore azione.\n",
        "\n",
        "- Con una rete neurale specifica che mappa gli stati $s_t$ in un vettore dei logaritmi delle deviazioni standard, $\\log \\sigma_{\\theta}(s_t)$, sempre una per ciascun componente del vettore azione.\n",
        "\n",
        "- Usando la stessa rete neurale che ha prodotto il *means vector* delle azioni, condividendone il layer finale (o \"attaccandosi\" ad altri layer); al fine di ottenere il vettore dei logaritmi delle deviazioni standard, $\\log \\sigma_{\\theta}(s_t)$.\n",
        "\n",
        "- Definendo il vettore dei logaritmi delle deviazioni standard, $\\log \\sigma$, tramite parametri indipendenti (\"standalone parameters\") cioè che non sono direttamente collegati a una rete neurale, a un layer specifico della rete, né dipendono funzionalmente dallo stato $s_t$.\n",
        "\n",
        "Si noti:\n",
        "\n",
        "generalmente, si preferisce apprendere i logaritmi delle deviazioni standard, piuttosto che le deviazioni standard stesse; in quanto i log std sono liberi di assumere qualsiasi valore in $(-\\infty, \\infty)$, mentre gli std devono essere non negativi $(0, \\infty)$.\n",
        "L'addestramento dei parametri risulta facilitato in assenza di vincoli di questo tipo.\n",
        "\n",
        "Questa scelta non comporta alcuna complicazione, poiché le deviazioni standard originali possono essere facilmente recuperate applicando la funzione esponenziale ai logaritmi delle deviazioni standard.\n",
        "\n",
        "In matematica; sia $log$ un logaritmo naturale (o logaritmo neperiano), allora:  $\\log(x) = y \\Leftrightarrow e^y = x$\n",
        "\n",
        "Ref.\n",
        "\n",
        "Covariance Matrix :\n",
        "https://www.youtube.com/watch?v=OHojomysBJM\n",
        "\n",
        "Stochastic policies:\n",
        "https://avandekleut.github.io/reinforce/#:~:text=Diagonal%20Gaussian%20policies%20define%20a,distribution%20over%20real%2Dvalued%20vectors.\n"
      ],
      "metadata": {
        "id": "AHY4pSmcgGFG"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Nota matematica sulla relazione tra \"log\" e \"exp\"\n",
        "\n",
        "import math\n",
        "\n",
        "print(math.log(2.))  # si intende il log in base naturale\n",
        "print(torch.exp(torch.tensor([math.log(2.)])))\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "rhCEJ-ZYmPhp",
        "outputId": "e42b5f4d-c960-45a0-b171-9a8cba5ec94b"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "0.6931471805599453\n",
            "tensor([2.])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "La classe `MultivariateNormal` in PyTorch implementa una distribuzione normale multivariata, definita da un vettore delle medie e una matrice di covarianza.\n",
        "\n",
        "Questa classe consente in modo diretto:\n",
        "- il campionamento(sampling),\n",
        "- il calcolo del logaritmo della *joint probability density*, ovvero: si consideri un campione $v$, un vettore: $[v_1, v_2, ..., v_i, ..., v_n]$ i cui compomenti sono numeri reali estratti da distribuzioni normali, rispettivamente definite da $ \\theta_i = [\\mu_i, \\sigma_i]$; sia $\\mathbf{θ}$ il vettore dei parametri che le definisce. Allora il log della *joint probability density* del campione $v$ è dato dalla formula: $\\log ( L (v | \\theta) ) = -\\frac{1}{2}\\left(\\sum_{i=1}^n \\left(\\frac{(v_i - \\mu_i)^2}{\\sigma_i^2} + 2 \\log \\sigma_i \\right) + k \\log 2\\pi \\right)$\n",
        "\n",
        "Si ricordi, a riguardo dell'ultimo punto che:\n",
        "\n",
        "per le variabili casuali continue, non ha senso determinare la probabilità che la variabile assuma un valore specifico, come per le variabili discrete, poiché questa probabilità è sempre nulla ( essendo infiniti casi possibili; $ 1 / \\infty  = 0 $).\n",
        "\n",
        "Tuttavia, ha senso parlare della probabilità che la variabile casuale assuma valori all'interno di un intervallo, anche molto piccolo. Per questo motivo, si introduce la funzione di densità di probabilità (o PDF: Probability Density Function), che descrive la probabilità che una variabile casuale continua assuma un valore all'interno di un intervallo specificato nello spazio campionario [ *Intuitivamente, la densità di probabilità in un punto rappresenta la \"concentrazione\" di probabilità attorno a quel punto. Più la densità è alta, maggiore è la probabilità che la variabile aleatoria assuma un valore vicino a quel punto* ].\n",
        "\n",
        "Estendendo il concetto di densità di probabilità a più di una variabile aleatoria continua otteniamo: la funzione densità di probabilità congiunta (joint probability density).\n",
        "\n",
        "Ad esempio, la densità di probabilità congiunta: *dpc(x, y)* di due variabili casuali continue X e Y (che possono essere tra loro indipendenti o meno) rappresenta la probabilità relativa di osservare valori di X e Y nelle immediate vicinanze del punto (x, y).\n",
        "\n",
        "\n",
        "Ref.\n",
        "\n",
        "http://progettomatematica.dm.unibo.it/Prob2/6funzionedidens.html\n",
        "\n",
        "https://www.statlect.com/glossary/log-likelihood\n",
        "\n",
        "https://statlect.com/glossary/joint-probability-density-function\n",
        "\n"
      ],
      "metadata": {
        "id": "amyQXB1HBu3Z"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#https://pytorch.org/docs/stable/distributions.html#multivariatenormal\n",
        "\n",
        "#Creates a multivariate normal (also called Gaussian) distribution parameterized\n",
        "# by a mean vector and a covariance matrix.\n",
        "\n",
        "v = np.array([1.5, 45, 39.5])       # means vector\n",
        "mu =  torch.from_numpy(v).float()\n",
        "\n",
        "sig = np.array([0.8, 10, 0.01])     # dev-std vector\n",
        "sigma = torch.from_numpy(sig).float()\n",
        "print(torch.diag(sigma))            # covariance matrix\n",
        "\n",
        "pi = torch.distributions.MultivariateNormal(mu, torch.diag(sigma))\n",
        "\n",
        "s = pi.sample()  # Essendo un punto nello spazio dimendionale 3D;\n",
        "                 # campiona tre valori: estratti dalle rispettive distribuzioni gaussiane\n",
        "                 # con media \"mu\" e std \"sigma\"\n",
        "print(s)\n",
        "print(pi.log_prob(s))   # Ricava il log-prob"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "g6OzCSILETp3",
        "outputId": "7a1c5d41-a541-4b30-b45e-ba2a5203c517"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[8.0000e-01, 0.0000e+00, 0.0000e+00],\n",
            "        [0.0000e+00, 1.0000e+01, 0.0000e+00],\n",
            "        [0.0000e+00, 0.0000e+00, 1.0000e-02]])\n",
            "tensor([ 0.8567, 43.7245, 39.4403])\n",
            "tensor(-2.0119)\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Per avere una comprensione più chiara della funzione di densità di probabilità."
      ],
      "metadata": {
        "id": "ki3LfseABCBg"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Definisco la distribuzione\n",
        "v = np.array([1., 3.])          # means vector\n",
        "mu =  torch.from_numpy(v).float()\n",
        "\n",
        "sig = np.array([0.01, 0.5])     # dev-std vector\n",
        "sigma = torch.from_numpy(sig).float()\n",
        "\n",
        "pi = torch.distributions.MultivariateNormal(mu, torch.diag(sigma))\n",
        "                                          # Si noti\n",
        "                                          # torch.diag(sigma) :  una matrice di covarianza con diagonale non nulla\n",
        "                                          # e fuori diagonale nulla indica che le variabili tra loro indipendenti.\n",
        "\n",
        "# Creo una grid per il plotting\n",
        "x = np.linspace(0.5, 1.5, 100)\n",
        "y = np.linspace(1, 5, 100)\n",
        "X, Y = np.meshgrid(x, y)\n",
        "pos = np.empty(X.shape + (2,))\n",
        "pos[:, :, 0] = X\n",
        "pos[:, :, 1] = Y\n",
        "\n",
        "# Calcolo la probability density\n",
        "Z = torch.from_numpy(pos).float()\n",
        "prob_density = torch.exp(pi.log_prob(Z)).numpy()\n",
        "\n",
        "# Plot della probability density\n",
        "plt.figure(figsize=(6, 4))\n",
        "plt.contourf(X, Y, prob_density, levels=10, cmap='viridis') # level=10, per i valori della Probability Density\n",
        "plt.colorbar()\n",
        "plt.xlabel('V_1')\n",
        "plt.ylabel('V_2')\n",
        "plt.grid()\n",
        "plt.show()\n",
        "\n",
        "s = pi.sample()\n",
        "print(\"Campione estratto :\", s)\n",
        "print(\"Log(Probability Density) :\", pi.log_prob(s))\n",
        "print(\"Probability Density      :\", torch.exp(pi.log_prob(s)))\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 447
        },
        "id": "SF_Jxovs87Cb",
        "outputId": "210b57b8-4182-431f-eb5b-2f6906b3f75f"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "display_data",
          "data": {
            "text/plain": [
              "<Figure size 600x400 with 2 Axes>"
            ],
            "image/png": "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\n"
          },
          "metadata": {}
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Campione estratto : tensor([1.0887, 3.5430])\n",
            "Log(Probability Density) : tensor(0.1229)\n",
            "Probability Density      : tensor(1.1308)\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Esempio di implementazione di una *Diagonal Gaussian Policy* , che definisce il vettore dei logaritmi delle deviazioni standard, $\\log \\sigma$, tramite parametri indipendenti."
      ],
      "metadata": {
        "id": "zWGAnhFbGZo-"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#Codice di riferimento :\n",
        "# https://avandekleut.github.io/reinforce/#:~:text=Diagonal%20Gaussian%20policies%20define%20a,distribution%20over%20real%2Dvalued%20vectors.\n",
        "\n",
        "class DiagonalGaussianPolicy:\n",
        "    def __init__(self, env=None, lr=1e-3):\n",
        "\n",
        "        self.dim_state = 2  # env.observation_space.shape[0]\n",
        "        self.dim_action = 5 # env.action_space.shape[0]\n",
        "\n",
        "        self.mu = torch.nn.Sequential(\n",
        "            torch.nn.Linear(self.dim_state, 32),\n",
        "            torch.nn.ReLU(),\n",
        "            torch.nn.Linear(32, 64),\n",
        "            torch.nn.ReLU(),\n",
        "            torch.nn.Linear(64, self.dim_action)\n",
        "        )\n",
        "\n",
        "        self.log_sigma = torch.ones(self.dim_action, requires_grad=True)\n",
        "\n",
        "        self.opt = torch.optim.Adam(list(self.mu.parameters()) + [self.log_sigma], lr=lr)\n",
        "\n",
        "    def d_pi(self, s_t):\n",
        "        s_t = torch.as_tensor(s_t)\n",
        "\n",
        "        mu = self.mu(s_t)\n",
        "\n",
        "        log_sigma = self.log_sigma\n",
        "        sigma = torch.exp(log_sigma)\n",
        "\n",
        "        pi = torch.distributions.MultivariateNormal(mu, torch.diag(sigma))\n",
        "        return pi\n",
        "\n",
        "    def act(self, s_t):\n",
        "        pi = self.d_pi(s_t)\n",
        "\n",
        "        s = pi.sample()\n",
        "        log_prob = pi.log_prob(s)\n",
        "        return s, log_prob\n"
      ],
      "metadata": {
        "id": "Ddy8sIqhByKC"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "# Test\n",
        "es =  DiagonalGaussianPolicy()\n",
        "\n",
        "for _ in range(5):\n",
        "   sam,lg_p = es.act([1.5,2.6])\n",
        "   print(sam,\"\\n\",lg_p)\n",
        "   print(\"\")"
      ],
      "metadata": {
        "id": "KHnQVbVHEiAt",
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "outputId": "97be496e-9063-40cd-b0db-41c038a4ca27"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([ 1.4882,  1.5517,  0.2731, -0.6836,  0.0581]) \n",
            " tensor(-8.2581, grad_fn=<SubBackward0>)\n",
            "\n",
            "tensor([-3.1596, -0.3767,  2.2847, -1.3025, -0.1868]) \n",
            " tensor(-10.3941, grad_fn=<SubBackward0>)\n",
            "\n",
            "tensor([ 2.0875, -1.1980, -1.2228,  1.5360, -0.7728]) \n",
            " tensor(-8.7581, grad_fn=<SubBackward0>)\n",
            "\n",
            "tensor([-2.1970, -2.3320,  1.5046, -1.3329,  0.8451]) \n",
            " tensor(-9.6521, grad_fn=<SubBackward0>)\n",
            "\n",
            "tensor([-0.3607,  1.6623, -3.6963,  3.0831, -0.4386]) \n",
            " tensor(-12.1550, grad_fn=<SubBackward0>)\n",
            "\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "###Policy implementata tramite rete neurale\n",
        "\n",
        "La rete neurale che useremo nel training produce in uscita una certa distribuzione di probabilità discreta sulle azioni disponibili.\n",
        "\n",
        "'CartPole-v1' ha due azioni discrete per ogni stato; la rete produce in uscita una distribuzione del tipo $[0.21 \\;\\; 0.79]$.\n",
        "\n",
        "Si noti: per garantire l’esplorazione e quindi l'apprendimento, si richiede che la policy non diventi mai puramente deterministica.\n"
      ],
      "metadata": {
        "id": "TlFj5UzVbIR2"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#Codice ispirato :\n",
        "#https://github.com/goodboychan?tab=repositories\n",
        "\n",
        "class Policy(nn.Module):\n",
        "\n",
        "    #Definiamo una ANN a due layer fully connected con relative activation function\n",
        "    def __init__(self, state_size=4, action_size=2, hidden_size=32):\n",
        "        super(Policy, self).__init__()\n",
        "        self.fc1 = nn.Linear(state_size, hidden_size)  # Matrice pesi fc1.weight: torch.Size([32, 4])\n",
        "        self.activation1 = nn.ReLU()\n",
        "        self.fc2 = nn.Linear(hidden_size, action_size) # Matrice pesi fc2.weight: torch.Size([2, 32])\n",
        "        self.activation2 = torch.nn.Softmax(dim=1)     # Nota: per (dim=0) produce chiaramente [[1., 1.]]\n",
        "\n",
        "    def forward(self, state):\n",
        "        x = self.fc1(state)\n",
        "        x1 = self.activation1(x)\n",
        "        x2 = self.fc2(x1)  # è una roba del tipo: tensor([[-0.0344,  0.0977]], grad_fn=<AddmmBackward0>)\n",
        "        x3 = self.activation2(x2)\n",
        "        return x3\n",
        "\n",
        "    # Definiamo un modo per campionare un azione e ricavare log della sua probabilità\n",
        "    def act(self, state):\n",
        "        state = torch.from_numpy(state).float().unsqueeze(0).to(device) # questo rigo evita il TypeError:\n",
        "                              # linear(): argument 'input' (position 1) must be Tensor, not numpy.ndarray\n",
        "\n",
        "        probs = self.forward(state).cpu()\n",
        "\n",
        "        model = Categorical(probs)\n",
        "        action = model.sample() #  campiona l'azione usando i risultati della rete neurale\n",
        "        return action.item(), model.log_prob(action)"
      ],
      "metadata": {
        "id": "tcwqe0gIbH6P"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "#Testing della classe\n",
        "\n",
        "p = Policy().to(device)\n",
        "state = env.reset()\n",
        "\n",
        "for timeIndex in range(1,2):\n",
        "\n",
        "        state1 = torch.from_numpy(state).float().unsqueeze(0)\n",
        "        print(\"p.forward(state)=\", p.forward(state1))\n",
        "\n",
        "        action, log_prob = p.act(state)\n",
        "        print(\"action=\",action)\n",
        "        print(\"log_prob=\",log_prob)\n",
        "\n",
        "        state, reward, done, _ = env.step(action)\n",
        "\n",
        "        if done:\n",
        "            break\n",
        "\n",
        "env.close()"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "outputId": "99e1c770-fc16-4a10-eb6b-210f7540284e",
        "id": "UUfSutVMwR6l"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "p.forward(state)= tensor([[0.5816, 0.4184]], grad_fn=<SoftmaxBackward0>)\n",
            "action= 0\n",
            "log_prob= tensor([-0.5419], grad_fn=<SqueezeBackward1>)\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Premesse alla REINFORCE Core function\n"
      ],
      "metadata": {
        "id": "iKBt4S-CCeqM"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#Premssa Tecnica 1:\n",
        "# torch.cat serve a concatenare o unire tensori lungo una dimensione specificata.\n",
        "#https://pytorch.org/docs/stable/generated/torch.cat.html\n",
        "\n",
        "x = torch.randn(2, )\n",
        "print(x)\n",
        "y = torch.randn(1, )\n",
        "print(y)\n",
        "\n",
        "print(torch.cat([x,y],dim=0))\n",
        "print( (torch.cat([x,y],dim=0))[0])    # Accesso ad un elemento di torch.cat\n",
        "print(\"sum=\", torch.cat([x,y]).sum())  # Somma i componenti di torch.cat"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "hIShOYzZHfoo",
        "outputId": "3ba2b79f-33d3-4ceb-f6e5-bcd1d6ba3ad6"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([-0.3359,  0.1574])\n",
            "tensor([-0.1858])\n",
            "tensor([-0.3359,  0.1574, -0.1858])\n",
            "tensor(-0.3359)\n",
            "sum= tensor(-0.3644)\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "x = torch.randn(2,3)\n",
        "print(x)\n",
        "print(\"\")\n",
        "print(torch.cat([x, x, x],dim=0))\n",
        "print(\"\")\n",
        "print(torch.cat([x, x, x],dim=1))"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "h5lI0Wz2wh-E",
        "outputId": "347450ca-e976-4dcc-89b6-97cc00a29b65"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "tensor([[-2.8238,  1.3212, -0.5233],\n",
            "        [-1.6234,  0.6547,  0.1918]])\n",
            "\n",
            "tensor([[-2.8238,  1.3212, -0.5233],\n",
            "        [-1.6234,  0.6547,  0.1918],\n",
            "        [-2.8238,  1.3212, -0.5233],\n",
            "        [-1.6234,  0.6547,  0.1918],\n",
            "        [-2.8238,  1.3212, -0.5233],\n",
            "        [-1.6234,  0.6547,  0.1918]])\n",
            "\n",
            "tensor([[-2.8238,  1.3212, -0.5233, -2.8238,  1.3212, -0.5233, -2.8238,  1.3212,\n",
            "         -0.5233],\n",
            "        [-1.6234,  0.6547,  0.1918, -1.6234,  0.6547,  0.1918, -1.6234,  0.6547,\n",
            "          0.1918]])\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "pol_l = [torch.tensor([12.8589], requires_grad=True),\n",
        "         torch.tensor([12.5127], requires_grad=True),\n",
        "         torch.tensor([8.6259], requires_grad=True)]\n",
        "\n",
        "print(pol_l)\n",
        "\n",
        "# Concatena i tensori lungo la dimensione 0\n",
        "pol_l = torch.cat(pol_l)\n",
        "\n",
        "print(pol_l)  # Output: tensor([12.8589, 12.5127, 8.6259])"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "1pjlXCxaImNa",
        "outputId": "98f4984c-e054-42ab-a804-a8550106b186"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "[tensor([12.8589], requires_grad=True), tensor([12.5127], requires_grad=True), tensor([8.6259], requires_grad=True)]\n",
            "tensor([12.8589, 12.5127,  8.6259], grad_fn=<CatBackward0>)\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "#Premssa Tecnica 2:\n",
        "#loop for in \"reverse mode\"\n",
        "\n",
        "print(list(range(5-1, -1, -1)))\n",
        "\n",
        "for i in range(5-1, -1, -1):\n",
        "      print(i)"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Il4_mssTDHWY",
        "outputId": "4f933cdc-67bf-4777-fb77-e55b1b2d52a0"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "[4, 3, 2, 1, 0]\n",
            "4\n",
            "3\n",
            "2\n",
            "1\n",
            "0\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Buono a sapersi:\n",
        "\n",
        "Anche se non è il caso di Cart Pole, dove tutti i rewads sono uguali (e non verrà qui applicato); generalmente, per questioni di stabilità, si preferisce normalizzare il return dei rewards.\n",
        "\n",
        "Se si analizza le equazioni di backpropagation, si osserva che il return influenza i gradienti. Per tale ragione, si vuole mantenere i valori campionati del return, in un intervallo specifico.\n",
        "\n",
        "L' adozione di questa normalizzazione non si basa su solide garanzie teoriche, bensì su considerazioni di natura pratica."
      ],
      "metadata": {
        "id": "Xtw5eSbZ3kVT"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "def normalize_rewards(r):\n",
        "  # r è la lista contenente i rewads accumulati dell'episodio\n",
        "  r = torch.tensor(r).to(device)\n",
        "  print(r.mean())\n",
        "  print(r.std())\n",
        "  r = (r - r.mean()) / (r.std() + 1e-9)\n",
        "  return r # ritorno la lista di reward normalizzati"
      ],
      "metadata": {
        "id": "hLi2D03v3gKY"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### REINFORCE Core function\n",
        "\n",
        "Note sulla funzione di loss implementata nel codice\n",
        "\n",
        "Si ricordi che  il gradient ascent è esattamente l'opposto di gradient descent. Mentre gradient descent regola i parametri nella direzione opposta del gradiente per ridurre al minimo la loss function, il gradient ascent regola i parametri nella direzione del gradiente per trovarne i massimi (locali).\n",
        "\n",
        "Per la realizzazione dell'algoritmo gradient ascent, si tenga a mente che si può sempre descrivere un problema di massimizzazione in termini di problema di minimizzazione: basta moltiplicare la funzione obiettivo (ovvero la nostra loss) per $-1$.\n",
        "\n",
        "Per maggiori info teorico matematiche:\n",
        "\n",
        "Metodi di ottimizzazione globale - Stefano Lucidi\n",
        "\n",
        "http://www.diag.uniroma1.it/~lucidi/didattica/main-Ott-Glob.pdf\n",
        "\n",
        "Per capirci con un esempio: si consideri la funzione obiettivo : $f(x) = 1 - x^2$.\n",
        "\n",
        "Il valore del parametro $x$ che massimizza tale funzione si può ricavare anche ricercando il valore di $x$ che minizza la funzione: $ -f(x) = -(1 - x^2) = x^2 - 1$\n"
      ],
      "metadata": {
        "id": "Mz_O9I7R4K-e"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "def list_G_for_each_step(input_list):\n",
        "    output_list = []\n",
        "    # Itera in reverse order\n",
        "    for i in range(len(input_list)-1, -1, -1):\n",
        "\n",
        "        current_sum = sum(input_list[i:])  # Calcola return parziali  R_t\n",
        "        # Nota: la formula sopra semplifica le cose assumendo che gamma = 1.\n",
        "        # Altrimenti avremmo dovuto considerare anche\n",
        "        # il fattore discount:  *gamma**(t'-t))\n",
        "        # ed aggiungere il parametro \"gamma\" in \"def list_G_for_each_step(input_list):\"\n",
        "\n",
        "        output_list.append(current_sum)   # Li conserva\n",
        "\n",
        "    output_list.reverse()\n",
        "    return output_list\n",
        "\n",
        "\n",
        "def reinforce(policy, optimizer, n_episodes=1000, max_t=1000, gamma=1.0, print_every=100):\n",
        "\n",
        "    scores_deque = deque(maxlen=100)\n",
        "    scores = []\n",
        "\n",
        "    for e in range(1, n_episodes+1):\n",
        "        saved_log_probs = []\n",
        "        rewards = []\n",
        "        state = env.reset()\n",
        "\n",
        "        # Genera una traiettoria\n",
        "        for t in range(max_t):\n",
        "            action, log_prob = policy.act(state)\n",
        "            saved_log_probs.append(log_prob) # è roba del tipo : log_prob= tensor([-0.7196])\n",
        "            state, reward, done, _ = env.step(action)\n",
        "            rewards.append(reward)\n",
        "            #La lista reward cresce in dimensione ad ogni step: rewards [1.0], rewards [1.0, 1.0], rewards [1.0, 1.0, 1.0], ...\n",
        "            if done:\n",
        "                break\n",
        "\n",
        "        #Ricava e conserva in una lista 'G', i vari return R_t, per ogni time step t\n",
        "        G = list_G_for_each_step(rewards)\n",
        "        #R = sum(rewards)  # un alternativa praticabile\n",
        "\n",
        "        # Utility\n",
        "        scores_deque.append(sum(rewards)) # Serve per il debug\n",
        "        scores.append(sum(rewards))       # Serve per il grafico\n",
        "\n",
        "        # Ricava la loss\n",
        "        policy_loss = []\n",
        "        for j in range(len(G)):\n",
        "            policy_loss.append(-saved_log_probs[j] * G[j])\n",
        "            # Si Tenga presente che stiamo utilizzando Gradient Ascent, non il Descent.\n",
        "            # E' una convenzione standard, sia in PyTorch che TF, eseguire la minimizzazione anziché la massimizzazione.\n",
        "            # Quindi, dobbiamo convertire l'obiettivo da massimizzazione in obiettivo da minimizzazione.\n",
        "            # Come? semplicemente inserendo il segno negativo: '-saved_log_probs[j]'\n",
        "\n",
        "        policy_loss = torch.cat(policy_loss).sum()  # policy_loss è del tipo : tensor(10.4294, grad_fn=<MeanBackward0>)\n",
        "\n",
        "        # Update dei parametri alla fine di ogni episodio\n",
        "        optimizer.zero_grad()\n",
        "        policy_loss.backward()   # Calcola i gradienti della 'policy_loss' rispetto ai parametri del modello\n",
        "        optimizer.step()         # Realizza l'aggiornamento dei parametri (weights+bias) del modello sulla base dei gradienti ricavati\n",
        "\n",
        "        # Debug\n",
        "        if e % print_every == 0:\n",
        "            print('Episode {}\\tAverage Score: {:.2f}'.format(e, np.mean(scores_deque)))\n",
        "\n",
        "        # Se raggiungi un certo punteggio, esempio 195.0, ferma il processo di training\n",
        "        #if np.mean(scores_deque) >= 195.0:\n",
        "        #    print('Environment solved in {:d} episodes!\\tAverage Score: {:.2f}'.format(e - 100, np.mean(scores_deque)))\n",
        "        #    break\n",
        "\n",
        "    print(\"\\n...End of the training.\\n\")\n",
        "    return scores"
      ],
      "metadata": {
        "id": "73f5baxkDBTE"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### SPERIMENTAZIONI - Varianti dell'algoritmo standard\n",
        "\n",
        "(Non vincolate al caso specifico di 'Cart Pole-v1')"
      ],
      "metadata": {
        "id": "MZvMPduCJq2R"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "1.\n",
        "\n",
        "Si provi a sostituire la sola l'istruzione:\n",
        "\n",
        "`policy_loss = torch.cat(policy_loss).sum()`\n",
        "\n",
        "con:\n",
        "\n",
        "`policy_loss = torch.cat(policy_loss).mean()`\n",
        "\n",
        "Nel caso di 'Cart Pole-v1' usando tale istruzione, le cose non sembrano funzionare, ottengo valori fortemente fluttuanti:\n",
        "\n",
        "`Average Score: 75.22,... 493.66, 177.89 , ... , 91.63`\n",
        "\n",
        "e performance poco efficaci:\n",
        "\n",
        "`Max reward was taken in 0.0 % of times`"
      ],
      "metadata": {
        "id": "OUtSuonJTkUg"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "2.\n",
        "\n",
        "Se una traiettoria risulta molto lunga, una volta completata, si procede all'elaborazione di un sottoinsieme dei segmenti di questa alla volta, scelti casualmente. In pratica, si opera su un sotto-dominio della traiettoria anziché su di essa nella sua interezza.\n",
        "\n",
        "Estratto il sotto-dominio, si ricava:\n",
        "\n",
        "```python\n",
        "for j in range(len(Sotto-dominio)):\n",
        " policy_loss.append(-saved_log_probs[j] * G[j])\n",
        "\n",
        "policy_loss = torch.cat(policy_loss).sum()\n",
        "```\n",
        "\n",
        "Successivamente, viene eseguito l'aggiornamento dei parametri classico.\n",
        "\n",
        "Il processo viene ripetuto su un altro segmento della traiettoria, diverso dal precedente, con un conseguente aggiornamento dei parametri.\n",
        "\n",
        "Questo ciclo continua fino a quando tutti i segmenti della traiettoria sono stati elaborati.\n",
        "\n",
        "Tale approccio consentirebbe di ottenere risultati soddisfacenti campionando un numero limitato di traiettorie.\n",
        "\n",
        "\n",
        "\n"
      ],
      "metadata": {
        "id": "ZtM7V5OeMBFh"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "3.\n",
        "\n",
        "Se le traiettorie sono molto brevi, i valori di `policy_loss` ottenuti da ciascuna di esse (nel modo \"standard\") possono essere raggruppati in una lista:\n",
        "\n",
        "`policy_loss_list.append(policy_loss)`\n",
        "\n",
        "Quando la lista raggiunge una dimensione sufficiente, ad esempio 30 elementi, si calcola la media dei valori raccolti.\n",
        "\n",
        "`p_loss_mean_trajectories = policy_loss_list.mean()`\n",
        "\n",
        "L'aggiornamento dei parametri viene effettuato solo sulla base di questa media, e non prima.\n",
        "\n",
        "Tale processo si ripete iterativamente con nuove estrazioni e successivi aggiornamenti."
      ],
      "metadata": {
        "id": "hGoqQve5QFnf"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Training"
      ],
      "metadata": {
        "id": "dbvhfbCIelAM"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "#torch.autograd.set_detect_anomaly(True)\n",
        "#env.spec.reward_threshold = 600  # the standard threshold for rewards is 500 for v1\n",
        "\n",
        "policy = Policy().to(device)\n",
        "optimizer = optim.Adam(policy.parameters(), lr=1e-2)\n",
        "score = reinforce(policy, optimizer, n_episodes=1_000)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "M_2MwvsXLBy7",
        "outputId": "7327b5f8-ce52-4315-cd6a-2632b115a4c9"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Episode 100\tAverage Score: 53.81\n",
            "Episode 200\tAverage Score: 204.24\n",
            "Episode 300\tAverage Score: 266.08\n",
            "Episode 400\tAverage Score: 153.34\n",
            "Episode 500\tAverage Score: 281.38\n",
            "Episode 600\tAverage Score: 258.84\n",
            "Episode 700\tAverage Score: 255.41\n",
            "Episode 800\tAverage Score: 422.23\n",
            "Episode 900\tAverage Score: 494.36\n",
            "Episode 1000\tAverage Score: 500.00\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "###Plot"
      ],
      "metadata": {
        "id": "hkJBCeeEjwdj"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# plot the scores\n",
        "fig = plt.figure(figsize=(4,2))\n",
        "#ax = fig.add_subplot(111)\n",
        "ax = plt.gca()\n",
        "ax.set_ylim([1, 600])\n",
        "plt.plot(np.arange(1, len(score)+1), score)\n",
        "plt.ylabel('Score')\n",
        "plt.xlabel('Episode')\n",
        "plt.show()"
      ],
      "metadata": {
        "id": "m_8UQxeSjqa8"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Test con Video"
      ],
      "metadata": {
        "id": "jprU4k4QkLc0"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "def show_video(env_name):\n",
        "    mp4list = glob.glob('./*.mp4')\n",
        "    if len(mp4list) > 0:\n",
        "        mp4 = './{}.mp4'.format(env_name)\n",
        "        video = io.open(mp4, 'r+b').read()\n",
        "        encoded = base64.b64encode(video)\n",
        "        display.display(HTML(data='''<video alt=\"test\" autoplay\n",
        "                loop controls style=\"height: 400px;\">\n",
        "                <source src=\"data:video/mp4;base64,{0}\" type=\"video/mp4\" />\n",
        "             </video>'''.format(encoded.decode('ascii'))))\n",
        "    else:\n",
        "        print(\"Could not find video\")\n",
        "\n",
        "def show_video_of_model(policy, env_name):\n",
        "    env = gym.make(env_name)\n",
        "    vid = video_recorder.VideoRecorder(env, path=\"./{}.mp4\".format(env_name))\n",
        "    state = env.reset()\n",
        "    done = False\n",
        "    for t in range(1000):\n",
        "        vid.capture_frame()\n",
        "        action, _ = policy.act(state)\n",
        "        next_state, reward, done, _ = env.step(action)\n",
        "        state = next_state\n",
        "        if done:\n",
        "            break\n",
        "    vid.close()\n",
        "    env.close()"
      ],
      "metadata": {
        "id": "7RO2VEqokRxc"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "show_video_of_model(policy, 'CartPole-v1')"
      ],
      "metadata": {
        "id": "_qO1FxNNkVTQ"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "show_video('CartPole-v1')"
      ],
      "metadata": {
        "id": "zNvm98ziLJ0o"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Test su 100 campioni"
      ],
      "metadata": {
        "id": "wBaxTF2BnY0p"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "episodeNumber=100\n",
        "max_timeSteps=1_000\n",
        "\n",
        "cont = 0\n",
        "max_reward = 500\n",
        "\n",
        "\n",
        "for episodeIndex in range(1,episodeNumber):\n",
        "    observation=env.reset()\n",
        "    rewards = 0\n",
        "\n",
        "    for timeIndex in range(1,max_timeSteps+1):\n",
        "        action, _ = policy.act(observation)\n",
        "        observation, reward, done,  info = env.step(action)\n",
        "        rewards += reward\n",
        "\n",
        "        if done:\n",
        "            if max_reward == rewards:\n",
        "                  cont += 1\n",
        "\n",
        "            break\n",
        "\n",
        "env.close()\n",
        "\n",
        "print(\"Max reward was taken in \", round((cont/episodeNumber)*episodeNumber,2), \"% of times\" )"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "jO-HG2hknesH",
        "outputId": "6cf642e1-61ee-4f29-ceca-803b510b262b"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Max reward was taken in  99.0 % of times\n"
          ]
        }
      ]
    }
  ]
}