tuto_adapter.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sage Combinat Widgets Adapter Tutorial"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get rid of long error messages for clarity.\n",
    "from __future__ import print_function\n",
    "import sys\n",
    "ipython = get_ipython()\n",
    "\n",
    "def exception_handler(exception_type, exception, traceback):\n",
    "    print(\"%s: %s\" % (exception_type.__name__, exception), file=sys.stderr)\n",
    "\n",
    "ipython._showtraceback = exception_handler\n",
    "#%xmode Plain # in case you want the tracebacks, uncomment this line and comment above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose we want to play with a matrix, ie edit cells, add or drop rows or columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%display latex\n",
    "from sage.matrix.constructor import Matrix\n",
    "m = Matrix(ZZ, 3, 4, range(12))\n",
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To be able to display this matrix as a widget, we need to write an *adapter* [NB: here, link to a doc that explains in more details what an adapter is]. As we want a *grid-like* representation for our matrix, we will base our adapter on *GridViewAdapter*. Additionally, we specify the matrix element type. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sage_widget_adapters.generic_grid_view_adapter import GridViewAdapter\n",
    "class MyAdapter(GridViewAdapter):\n",
    "    celltype = Integer\n",
    "    cellzero = Integer(0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check what happens at this stage:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sage_combinat_widgets import GridViewWidget\n",
    "ma = MyAdapter()\n",
    "GridViewWidget(m,ma)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We need to tell the widget which cells are to be displayed in the grid view."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#from sage_widget_adapters.generic_grid_view_adapter import GridViewAdapter\n",
    "class MyAdapter(GridViewAdapter):\n",
    "    celltype = Integer\n",
    "    cellzero = Integer(0)\n",
    "    # See the documentation to check methods types and signatures\n",
    "    @staticmethod\n",
    "    def compute_cells(obj):\n",
    "        \"\"\"Compute cell positions.\"\"\"\n",
    "        from itertools import product\n",
    "        return {(i,j):obj[i][j] for (i,j) in product(range(obj.nrows()), range(len(obj[0])))}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ma = MyAdapter()\n",
    "w = GridViewWidget(m,ma)\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We need to tell the widget which type are our matrix cells, and which would be a default cell content (for blank or empty cells)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see the graphical display. Yet if we try to edit a cell, our matrix is unchanged:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we will learn how to make our widget editable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Editing cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to turn our widget into an editable matrix widget, we need a method to establish a new matrix value from a new dictionary of cells."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sage.matrix.constructor import matrix\n",
    "from sage_widget_adapters.generic_grid_view_adapter import GridViewAdapter\n",
    "class MyAdapter(GridViewAdapter):\n",
    "    constructorname = 'matrix'\n",
    "    celltype = Integer\n",
    "    cellzero = Integer(0)\n",
    "\n",
    "    # See the documentation to check methods types and signatures\n",
    "    @staticmethod\n",
    "    def compute_cells(obj):\n",
    "        \"\"\"Compute cell positions.\"\"\"\n",
    "        from itertools import product\n",
    "        return {(i,j):obj[i][j] for (i,j) in product(range(obj.nrows()), range(len(obj[0])))}\n",
    "\n",
    "    @classmethod\n",
    "    def from_cells(cls, cells={}):\n",
    "        \"\"\"Compute a new matrix from a cells dictionary `cells`\"\"\"\n",
    "        nrows = max(pos[0]+1 for pos in cells)\n",
    "        ncols = max(pos[1]+1 for pos in cells)\n",
    "        return cls.constructorname([[cells[(i,j)] for j in range(ncols)] for i in range(nrows)])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#from sage_combinat_widgets import GridViewWidget\n",
    "ma = MyAdapter()\n",
    "w = GridViewWidget(m,ma)\n",
    "w"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Observe the value change after editing a cell. \n",
    "w.value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ipywidgets import HBox, Label\n",
    "m_input = GridViewWidget(m)\n",
    "@interact\n",
    "def f(x = m_input):\n",
    "    return HBox((Label('m mult. by 2 --->'), GridViewWidget(x*2)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interactivity modes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides editing cells, we can define modes of interactivity, such as adding or removing cells ... \n",
    "For a matrix, we want to append/insert/remove rows or columns.\n",
    "Here is the code for appending a row/column:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sage.matrix.constructor import matrix\n",
    "from sage_widget_adapters.generic_grid_view_adapter import GridViewAdapter\n",
    "class MyAdapter(GridViewAdapter):\n",
    "    constructorname = 'matrix'\n",
    "    celltype = Integer\n",
    "    cellzero = Integer(0)\n",
    "\n",
    "    # See the documentation to check methods types and signatures\n",
    "    @staticmethod\n",
    "    def compute_cells(obj):\n",
    "        \"\"\"Compute cell positions.\"\"\"\n",
    "        from itertools import product\n",
    "        return {(i,j):obj[i][j] for (i,j) in product(range(obj.nrows()), range(len(obj[0])))}\n",
    "\n",
    "    @classmethod\n",
    "    def from_cells(cls, cells={}):\n",
    "        \"\"\"Compute a new matrix from a cells dictionary `cells`\"\"\"\n",
    "        nrows = max(pos[0]+1 for pos in cells)\n",
    "        ncols = max(pos[1]+1 for pos in cells)\n",
    "        return cls.constructorname([[cells[(i,j)] for j in range(ncols)] for i in range(nrows)])\n",
    "\n",
    "    def append_row(self, obj, r):\n",
    "        \"\"\"Return a new matrix with one more row 'r'\"\"\"\n",
    "        if not r or not hasattr(r, '__len__') or len(r) > obj.ncols():\n",
    "            raise ValueError(\"Row size must be <= %d\" % obj.ncols())\n",
    "        if len(r) < obj.ncols():\n",
    "            r = list(r) + [self.cellzero] * (obj.ncols() - len(r))\n",
    "        return obj.stack(vector([self.display_to_cell(x) for x in r]))\n",
    "\n",
    "    def append_column(self, obj, c):\n",
    "        \"\"\"Return a new matrix with one more column 'c'\"\"\"\n",
    "        if not c or not hasattr(c, '__len__') or len(c) > obj.nrows():\n",
    "            raise ValueError(\"Column size must be <= %d\" % obj.nrows())\n",
    "        if len(c) < obj.nrows():\n",
    "            c = list(c) + [self.cellzero] * (obj.nrows() - len(c))\n",
    "        return obj.augment(vector([self.display_to_cell(x) for x in c]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ma = MyAdapter()\n",
    "w = GridViewWidget(m,ma)\n",
    "w.append_row((12,13,14,15))\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can drive these interactivity modes with a pair of buttons: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ipywidgets import HBox, VBox, Button\n",
    "b_newrow = Button()\n",
    "b_newrow.description = \"Append row\"\n",
    "b_newcol = Button()\n",
    "b_newcol.description = \"Append column\"\n",
    "\n",
    "w = GridViewWidget(m,ma)\n",
    "def on_button_clicked(button):\n",
    "    w.append_row((w.value[-1][0]+4, w.value[-1][1]+4, w.value[-1][2]+4, w.value[-1][3]+4))\n",
    "b_newrow.on_click(on_button_clicked)\n",
    "def on_button_clicked(button):\n",
    "    w.append_column((w.value[0][-1]*2, w.value[1][-1]*2, w.value[2][-1]*2))\n",
    "b_newcol.on_click(on_button_clicked)\n",
    "\n",
    "box = VBox((HBox((w, b_newcol)), b_newrow))\n",
    "box"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more interactivity modes, please consult the generic adapter documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For various examples of widgets, see the demo."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "SageMath 8.9.rc0",
   "language": "sage",
   "name": "sagemath"
  },
  "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}