{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1766a5fc",
   "metadata": {},
   "source": [
    "# Example: Gradient approximation\n",
    "\n",
    "We will approximate the derivative of the Rosenbrock function at `(1,0,0)`, with the [forward and backward difference methods](https://en.wikipedia.org/wiki/Finite_difference#Basic_types), and with two different step sizes.\n",
    "\n",
    "We will also compute an approximation of the central difference, as the average of the forward and backward results.\n",
    "\n",
    "Success will be determined by whether results between the different methods (forward, backward, central) are consistent (i.e., equal, within some tolerance).\n",
    "\n",
    "Function inputs and outputs are NumPy arrays of arbitrary positive dimension."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b82bcbc8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[ 400.00001657 -202.00002612    0.        ]\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from scipy.optimize import rosen, rosen_der\n",
    "\n",
    "from fiddy import MethodId, get_derivative\n",
    "from fiddy.analysis import ApproximateCentral\n",
    "from fiddy.success import Consistency\n",
    "\n",
    "# Point at which to compute the derivative\n",
    "point = np.array([1, 0, 0])\n",
    "# Step sizes for finite differences\n",
    "sizes = [1e-10, 1e-5]\n",
    "\n",
    "derivative = get_derivative(\n",
    "    function=rosen,\n",
    "    point=point,\n",
    "    sizes=sizes,\n",
    "    method_ids=[MethodId.FORWARD, MethodId.BACKWARD],\n",
    "    direction_ids=[\"x\", \"y\", \"z\"],\n",
    "    analysis_classes=[ApproximateCentral],\n",
    "    success_checker=Consistency(rtol=1e-2, atol=1e-15),\n",
    ")\n",
    "print(\"Computed derivative:\", derivative.value)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bac6607b",
   "metadata": {},
   "source": [
    "The full (`derivative.df_full`) or the concise (`derivative.df`) dataframe can be used for debugging gradients.\n",
    "\n",
    "The IDs correspond to the directions in which finite differences were computed. These directions can be any vector in the function's parameter space. In this case, directions were not specified, so the default directions were used, which is the standard basis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "4f5840fb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>direction</th>\n",
       "      <th>success</th>\n",
       "      <th>value</th>\n",
       "      <th>completed</th>\n",
       "      <th>computer_results</th>\n",
       "      <th>analysis_results</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>direction</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>x</th>\n",
       "      <td>[1, 0, 0]</td>\n",
       "      <td>True</td>\n",
       "      <td>400.000017</td>\n",
       "      <td>True</td>\n",
       "      <td>method_id       value         metad...</td>\n",
       "      <td>method_id       value         met...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>y</th>\n",
       "      <td>[0, 1, 0]</td>\n",
       "      <td>True</td>\n",
       "      <td>-202.000026</td>\n",
       "      <td>True</td>\n",
       "      <td>method_id       value         metad...</td>\n",
       "      <td>method_id       value         met...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>z</th>\n",
       "      <td>[0, 0, 1]</td>\n",
       "      <td>True</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>True</td>\n",
       "      <td>method_id  value         metadata\n",
       "0...</td>\n",
       "      <td>method_id  value         metadata...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           direction  success       value  completed  \\\n",
       "direction                                              \n",
       "x          [1, 0, 0]     True  400.000017       True   \n",
       "y          [0, 1, 0]     True -202.000026       True   \n",
       "z          [0, 0, 1]     True    0.000000       True   \n",
       "\n",
       "                                            computer_results  \\\n",
       "direction                                                      \n",
       "x                     method_id       value         metad...   \n",
       "y                     method_id       value         metad...   \n",
       "z                     method_id  value         metadata\n",
       "0...   \n",
       "\n",
       "                                            analysis_results  \n",
       "direction                                                     \n",
       "x                       method_id       value         met...  \n",
       "y                       method_id       value         met...  \n",
       "z                       method_id  value         metadata...  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "derivative.df"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14799145",
   "metadata": {},
   "source": [
    "The `*_results` columns can be printed separately to view the specific derivative values that were computed.\n",
    "\n",
    "These values differ from the values reported in `derivative.values`. This is because the `success_checker` (`Consistency`) provides the derivative values as the average of all consistent derivative values. Consistency is checked on the level of `size`, so if any of the values for `1e-05` were inconsistent to the rest, they would not contribute to the average reported by the `Consistency` success checker."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "63d7e327",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>method_id</th>\n",
       "      <th>value</th>\n",
       "      <th>metadata</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>MethodId.FORWARD</td>\n",
       "      <td>400.000033</td>\n",
       "      <td>{'size': 1e-10}</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>MethodId.BACKWARD</td>\n",
       "      <td>400.000033</td>\n",
       "      <td>{'size': 1e-10}</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>MethodId.FORWARD</td>\n",
       "      <td>400.006010</td>\n",
       "      <td>{'size': 1e-05}</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>MethodId.BACKWARD</td>\n",
       "      <td>399.993990</td>\n",
       "      <td>{'size': 1e-05}</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           method_id       value         metadata\n",
       "0   MethodId.FORWARD  400.000033  {'size': 1e-10}\n",
       "1  MethodId.BACKWARD  400.000033  {'size': 1e-10}\n",
       "2   MethodId.FORWARD  400.006010  {'size': 1e-05}\n",
       "3  MethodId.BACKWARD  399.993990  {'size': 1e-05}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "derivative.df.loc[\"x\", \"computer_results\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "38b3d2b6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>method_id</th>\n",
       "      <th>value</th>\n",
       "      <th>metadata</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>approximate_central</td>\n",
       "      <td>400.000000</td>\n",
       "      <td>{'size': 1e-05}</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>approximate_central</td>\n",
       "      <td>400.000033</td>\n",
       "      <td>{'size': 1e-10}</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             method_id       value         metadata\n",
       "0  approximate_central  400.000000  {'size': 1e-05}\n",
       "1  approximate_central  400.000033  {'size': 1e-10}"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "derivative.df.loc[\"x\", \"analysis_results\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd9807aa",
   "metadata": {},
   "source": [
    "In this case, the finite difference values are all consistent with each other, and we now compare them with the expected derivative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "5b8ae013",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[ 400 -202    0]\n"
     ]
    }
   ],
   "source": [
    "expected_derivative = rosen_der(point)\n",
    "print(f\"{expected_derivative=}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "c01098c7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.isclose(derivative.value, expected_derivative).all()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}