enh: Refactoring the viz module to a more modular design

Everything is now based on functions that adhere to functional programming.
We combine these functions to create workflows and then use the sisl.nodes
framework to provide the update functionality.
Plotting backends are now implemented each on a single `Figure` class that
implements generic drawing methods, as well as subplots, animations... functionality.

docs/api/index.rst

@@ -25,6 +25,7 @@ All methods and submodules are listed  :ref:`here <genindex>` and
    default_geom
    physics
    mixing
+   viz/index
    unit_constant
    utilities
 
@@ -38,5 +39,4 @@ All methods and submodules are listed  :ref:`here <genindex>` and
    :caption: Advanced usage
 
    nodes
-   viz/index
 

docs/api/viz/index.rst

@@ -4,12 +4,37 @@
 Visualization
 =============
 
-.. currentmodule:: sisl.viz
+.. module:: sisl.viz
 
-Visualizations of `sisl` objects and data.
+The visualization module contains tools to plot common visualizations, as well
+as to create custom visualizations that support multiple plotting backends
+automatically.
 
+Plot classes
+-----------------
+
+Plot classes are workflow classes that implement some specific plotting.
+
+.. autosummary::
+    :toctree: generated/
+
+    Plot
+    BandsPlot
+    FatbandsPlot
+    GeometryPlot
+    SitesPlot
+    GridPlot
+    WavefunctionPlot
+    PdosPlot
+
+Utilities
+---------
+
+Utilities to build custom plots
 
 .. autosummary::
-   :toctree: generated/
-   :recursive:
+    :toctree: generated/
 
+    get_figure
+    merge_plots
+    Figure

docs/tutorials/tutorial_siesta_1.ipynb

@@ -11,6 +11,7 @@
     "import numpy as np\n",
     "from sisl import *\n",
     "import sisl.viz\n",
+    "from sisl.viz import merge_plots\n",
     "from functools import partial\n",
     "import matplotlib.pyplot as plt\n",
     "%matplotlib inline"
@@ -234,16 +235,17 @@
     "# Find the index of the smallest positive eigenvalue\n",
     "idx_lumo = (es.eig > 0).nonzero()[0][0]\n",
     "es = es.sub([idx_lumo - 1, idx_lumo])\n",
-    "h2o.plot(\n",
-    "    subplots=\"atoms_style\", cols=2,\n",
-    "    axes=\"xy\", \n",
-    "    atoms_style=[{\"size\": n * 30, \"color\": c}\n",
-    "                 for n, c in zip(h2o.apply(es.norm2(sum=False),\n",
+    "\n",
+    "plots = [\n",
+    "    h2o.plot(axes=\"xy\", atoms_style={\"size\": n * 1.5, \"color\": c})\n",
+    "    for n, c in zip(h2o.apply(es.norm2(sum=False),\n",
     "                                           np.sum,\n",
     "                                           mapper=partial(h2o.a2o, all=True),\n",
     "                                           axis=1),\n",
-    "                                 (\"red\", \"blue\", \"green\"))]\n",
-    ")"
+    "                                 (\"red\", \"blue\", \"green\"))\n",
+    "]\n",
+    "\n",
+    "merge_plots(*plots, composite_method=\"subplots\", cols=2)"
    ]
   },
   {
@@ -312,6 +314,13 @@
     "DM.density(diff)\n",
     "print('Real space integrated density difference: {:.3e}'.format(diff.grid.sum() * diff.dvolume))"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -330,9 +339,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.9"
+   "version": "3.8.15"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

docs/tutorials/tutorial_siesta_2.ipynb

@@ -363,9 +363,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.9"
+   "version": "3.8.15"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }