Merge pull request #476 from pfebrer/viz_data_sources

Refactoring the viz module to a more modular design.

Author: zerothi

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_es_1.ipynb

@@ -9,6 +9,7 @@
     "import numpy as np\n",
     "from sisl import *\n",
     "import sisl.viz\n",
+    "from sisl.viz import merge_plots\n",
     "import matplotlib.pyplot as plt\n",
     "%matplotlib inline"
    ]
@@ -119,8 +120,8 @@
     "system = graphene.remove(index)\n",
     "graphene.plot(axes=\"xy\", atoms_style=[\n",
     "  {\"opacity\": 0.5}, # Default style for all atoms\n",
-    "  {\"atoms\": indices, \"color\": \"black\", \"size\": 20, \"opacity\": 1}, # Styling for indices_close_to_center on top of defaults.\n",
-    "  {\"atoms\": index, \"color\": \"red\", \"size\": 10, \"opacity\": 1} # Styling for center_atom_index on top of defaults.\n",
+    "  {\"atoms\": indices, \"color\": \"black\", \"size\": 1.2, \"opacity\": 1}, # Styling for indices_close_to_center on top of defaults.\n",
+    "  {\"atoms\": index, \"color\": \"red\", \"size\": 1, \"opacity\": 1} # Styling for center_atom_index on top of defaults.\n",
     "])"
    ]
   },
@@ -195,12 +196,13 @@
     "es = H.eigenstate()\n",
     "# Reduce the contained eigenstates to only 3 states around the Fermi-level\n",
     "es_fermi = es.sub(range(len(H) // 2 - 1, len(H) // 2 + 2))\n",
-    "system.plot(\n",
-    "    subplots=\"atoms_style\", cols=3,\n",
-    "    axes=\"xy\", \n",
-    "    atoms_style=[{\"size\": n * 300, \"color\": c}\n",
-    "                 for n, c in zip(es_fermi.norm2(sum=False), (\"red\", \"blue\", \"green\"))]\n",
-    ")"
+    "\n",
+    "plots = [\n",
+    "    system.plot(axes=\"xy\", atoms_style=[{\"size\": n * 20, \"color\": c}]) \n",
+    "    for n, c in zip(es_fermi.norm2(sum=False), (\"red\", \"blue\", \"green\"))\n",
+    "]\n",
+    "\n",
+    "merge_plots(*plots, composite_method=\"subplots\", cols=3)"
    ]
   },
   {
@@ -243,7 +245,7 @@
     "E = np.linspace(-1, -.5, 100)\n",
     "dE = E[1] - E[0]\n",
     "PDOS = es.PDOS(E).sum((0, 2)) * dE # perform integration\n",
-    "system.plot(axes=\"xy\", atoms_style={\"size\": PDOS * 300})\n",
+    "system.plot(axes=\"xy\", atoms_style={\"size\": PDOS * 15})\n",
     "#plt.scatter(system.xyz[:, 0], system.xyz[:, 1], 500 * PDOS);\n",
     "#plt.scatter(xyz_remove[0], xyz_remove[1], c='k', marker='*'); # mark the removed atom"
    ]
@@ -274,8 +276,8 @@
    "source": [
     "band = BandStructure(H, [[0, 0, 0], [0, 0.5, 0], \n",
     "                         [1/3, 2/3, 0], [0, 0, 0]], 400, \n",
-    "                        [r'$\\Gamma$', r'$M$', \n",
-    "                         r'$K$', r'$\\Gamma$'])"
+    "                        [r'Gamma', r'M', \n",
+    "                         r'K', r'Gamma'])"
    ]
   },
   {
@@ -479,7 +481,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "grid.plot(axes=\"xy\", xaxis_range=(0, None))"
+    "grid.plot(axes=\"xy\")"
    ]
   },
   {
@@ -517,9 +519,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.9"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

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
 }