notebooks/viewers.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the default AiiDA profile.\n",
    "from aiida import load_profile, orm\n",
    "\n",
    "load_profile();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# AiiDA Viewers\n",
    "(widget-list:viewers)=\n",
    "\n",
    "This module contains the viewers, which are used to visualize AiiDA objects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to visualize an AiiDA object\n",
    "(widget:viwers:how-to-visualize-an-aiida-object)=\n",
    "\n",
    "The simplest way is to import the {py:meth}`~aiidalab_widgets_base.viewer` function and call it with the object:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiidalab_widgets_base import viewer\n",
    "\n",
    "p = orm.Dict(\n",
    "    dict={\n",
    "        \"parameter 1\": \"some string\",\n",
    "        \"parameter 2\": 2,\n",
    "        \"parameter 3\": 3.0,\n",
    "        \"parameter 4\": [1, 2, 3],\n",
    "    }\n",
    ")\n",
    "vwr = viewer(p.store(), downloadable=True)\n",
    "display(vwr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function takes two inputs: the object to show and an optional flag for displaying the download button.\n",
    "The function gives back a viewer object for notebook display.\n",
    "If the viewer for the object is not available, the object itself is returned, allowing for a very basic representation of it.\n",
    "\n",
    "An alternative way is to use the {py:class}`~aiidalab_widgets_base.AiidaNodeViewWidget` class:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida import orm\n",
    "\n",
    "from aiidalab_widgets_base import AiidaNodeViewWidget\n",
    "\n",
    "p = orm.Dict(\n",
    "    dict={\n",
    "        \"parameter 1\": \"some string\",\n",
    "        \"parameter 2\": 2,\n",
    "        \"parameter 3\": 3.0,\n",
    "        \"parameter 4\": [1, 2, 3],\n",
    "    }\n",
    ")\n",
    "wdgt = AiidaNodeViewWidget(node=p.store())\n",
    "display(wdgt)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the {py:class}`~aiidalab_widgets_base.AiidaNodeViewWidget` lets you visualize different AiiDA objects without making a new widget.\n",
    "Just update the ``node`` attribute of the widget as in the example below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida import plugins\n",
    "from ase.build import molecule\n",
    "\n",
    "m = molecule(\"H2O\")\n",
    "m.center(vacuum=2.0)\n",
    "\n",
    "StructureData = plugins.DataFactory(\"core.structure\")\n",
    "s = StructureData(ase=m)\n",
    "\n",
    "wdgt.node = s.store()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you update the ``node`` attribute, the widget will automatically refresh and display the new object, such as a water molecule in this case."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Build-in viewers\n",
    "(widget-list:viewers:build-in-viewers)=\n",
    "\n",
    "The viewers for several AiiDA objects are available:\n",
    "\n",
    "* {py:class}`~aiidalab_widgets_base.viewers.DictViewer` for the `orm.Dict` object representation.\n",
    "* {py:class}`~aiidalab_widgets_base.viewers.StructureDataViewer` for the `orm.StructureData` and `orm.CifData` object representation.\n",
    "* {py:class}`~aiidalab_widgets_base.viewers.FolderDataViewer` for the `orm.FolderDataViewer` object representation.\n",
    "* {py:class}`~aiidalab_widgets_base.viewers.BandsDataViewer` for the `orm.BandsData` object representation.\n",
    "* {py:class}`~aiidalab_widgets_base.viewers.ProcessNodeViewerWidget` for the `orm.ProcessNode` (and its children such as `orm.CalcJobNode` or `orm.WorkChainNode`) object representation.\n",
    "* and others...\n",
    "\n",
    "To see the full list of available viewers, visit the module API documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## List of build-in viewers\n",
    "(widget-list:viewers:list-of-build-in-viewers)=\n",
    "\n",
    "\n",
    "In this section, we list the build-in viewers and show how to use them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dict viewer\n",
    "(widget-list:viewers:list-of-build-in-viewers:dict-viewer)=\n",
    "\n",
    "The {py:class}`~aiidalab_widgets_base.viewers.DictViewer` is used to visualize dictionaries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida import plugins\n",
    "\n",
    "from aiidalab_widgets_base.viewers import DictViewer\n",
    "\n",
    "Dict = plugins.DataFactory(\"core.dict\")\n",
    "p = Dict(\n",
    "    dict={\n",
    "        \"Parameter\": \"super long string \" * 4,\n",
    "        \"parameter 2\": \"value 2\",\n",
    "        \"parameter 3\": 1,\n",
    "        \"parameter 4\": 2,\n",
    "    }\n",
    ")\n",
    "vwr = DictViewer(p.store(), downloadable=True)\n",
    "display(vwr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CifData and StructureData viewer\n",
    "(widget-list:viewers:list-of-build-in-viewers:cif-and-strucutre-data-viewer)=\n",
    "\n",
    "The {py:class}`~aiidalab_widgets_base.viewers.StructureDataViewer` is used to visualize both `CifData`` and `StructureData`` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ase.build import bulk, molecule\n",
    "\n",
    "from aiidalab_widgets_base.viewers import StructureDataViewer\n",
    "\n",
    "# create bulk Pt\n",
    "pt = bulk(\"Pt\", cubic=True)\n",
    "\n",
    "# Cif data.\n",
    "CifData = plugins.DataFactory(\"core.cif\")\n",
    "s = CifData(ase=pt)\n",
    "vwr_cif = StructureDataViewer(s.store())\n",
    "display(vwr_cif)\n",
    "\n",
    "# Structure data.\n",
    "m = molecule(\"H2O\")\n",
    "m.center(vacuum=2.0)\n",
    "\n",
    "StructureData = plugins.DataFactory(\"core.structure\")\n",
    "s = StructureData(ase=m)\n",
    "vwr_structure = StructureDataViewer(s.store())\n",
    "display(vwr_structure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### BandsData viewer\n",
    "(widget-list:viewers:list-of-build-in-viewers:bands-data-viewer)=\n",
    "\n",
    "The {py:class}`~aiidalab_widgets_base.viewers.BandsDataViewer` is used to visualize `BandsData` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from aiida import plugins\n",
    "\n",
    "from aiidalab_widgets_base.viewers import BandsDataViewer\n",
    "\n",
    "BandsData = plugins.DataFactory(\"core.array.bands\")\n",
    "bs = BandsData()\n",
    "kpoints = np.array(\n",
    "    [\n",
    "        [0.0, 0.0, 0.0],  # array shape is 12 * 3\n",
    "        [0.1, 0.0, 0.1],\n",
    "        [0.2, 0.0, 0.2],\n",
    "        [0.3, 0.0, 0.3],\n",
    "        [0.4, 0.0, 0.4],\n",
    "        [0.5, 0.0, 0.5],\n",
    "        [0.5, 0.0, 0.5],\n",
    "        [0.525, 0.05, 0.525],\n",
    "        [0.55, 0.1, 0.55],\n",
    "        [0.575, 0.15, 0.575],\n",
    "        [0.6, 0.2, 0.6],\n",
    "        [0.625, 0.25, 0.625],\n",
    "    ]\n",
    ")\n",
    "\n",
    "bands = np.array(\n",
    "    [\n",
    "        [\n",
    "            -5.64024889,\n",
    "            6.66929678,\n",
    "            6.66929678,\n",
    "            6.66929678,\n",
    "            8.91047649,\n",
    "        ],  # array shape is 12 * 5, where 12 is the size of the kpoints mesh\n",
    "        [\n",
    "            -5.46976726,\n",
    "            5.76113772,\n",
    "            5.97844699,\n",
    "            5.97844699,\n",
    "            8.48186734,\n",
    "        ],  # and 5 is the number of states\n",
    "        [-4.93870761, 4.06179965, 4.97235487, 4.97235488, 7.68276008],\n",
    "        [-4.05318686, 2.21579935, 4.18048674, 4.18048675, 7.04145185],\n",
    "        [-2.83974972, 0.37738276, 3.69024464, 3.69024465, 6.75053465],\n",
    "        [-1.34041116, -1.34041115, 3.52500177, 3.52500178, 6.92381041],\n",
    "        [-1.34041116, -1.34041115, 3.52500177, 3.52500178, 6.92381041],\n",
    "        [-1.34599146, -1.31663872, 3.34867603, 3.54390139, 6.93928289],\n",
    "        [-1.36769345, -1.24523403, 2.94149041, 3.6004033, 6.98809593],\n",
    "        [-1.42050683, -1.12604118, 2.48497007, 3.69389815, 7.07537154],\n",
    "        [-1.52788845, -0.95900776, 2.09104321, 3.82330632, 7.20537566],\n",
    "        [-1.71354964, -0.74425095, 1.82242466, 3.98697455, 7.37979746],\n",
    "    ]\n",
    ")\n",
    "bs.set_kpoints(kpoints)\n",
    "bs.set_bands(bands)\n",
    "labels = [(0, \"GAMMA\"), (5, \"X\"), (6, \"Z\"), (11, \"U\")]\n",
    "bs.labels = labels\n",
    "\n",
    "\n",
    "vwr = BandsDataViewer(bs.store(), downloadable=True)\n",
    "display(vwr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### FolderData viewer\n",
    "(widget-list:viewers:list-of-build-in-viewers:folder-data-viewer)=\n",
    "\n",
    "The {py:class}`~aiidalab_widgets_base.viewers.FolderDataViewer` is used to visualize `FolderData` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import io\n",
    "\n",
    "from aiida import plugins\n",
    "\n",
    "FolderData = plugins.DataFactory(\"core.folder\")\n",
    "fd = FolderData()\n",
    "with io.StringIO(\"content of test1 file\") as fobj:\n",
    "    fd.put_object_from_filelike(fobj, path=\"test1.txt\")\n",
    "with io.StringIO(\"content of test2 file\") as fobj:\n",
    "    fd.put_object_from_filelike(fobj, path=\"test2.txt\")\n",
    "with io.StringIO(\"content of test_long file\" * 1000) as fobj:\n",
    "    fd.put_object_from_filelike(fobj, path=\"test_long.txt\")\n",
    "vwr = viewer(fd.store(), downloadable=True)\n",
    "display(vwr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ProcessNode viewer\n",
    "(widget-list:viewers:list-of-build-in-viewers:workfunctions-and-calcfunctions)=\n",
    "\n",
    "The {py:class}`~aiidalab_widgets_base.viewers.ProcessNodeViewerWidget` is used to visualize `CalcFunctionNode` and `WorkFunctionNode` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aiida import engine, orm\n",
    "from aiida.workflows.arithmetic.add_multiply import add, add_multiply\n",
    "\n",
    "from aiidalab_widgets_base.viewers import ProcessNodeViewerWidget\n",
    "\n",
    "result, workfunction = engine.run_get_node(\n",
    "    add_multiply, orm.Int(3), orm.Int(4), orm.Int(5)\n",
    ")\n",
    "vwr_workfunction = ProcessNodeViewerWidget(workfunction)\n",
    "display(vwr_workfunction)\n",
    "\n",
    "result, calcfunction = engine.run_get_node(add, orm.Int(3), orm.Int(4))\n",
    "vwr_calcfunction = ProcessNodeViewerWidget(calcfunction)\n",
    "display(vwr_calcfunction)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a custom viewer\n",
    "(widget-list:viewers:create-a-custom-viewer)=\n",
    "\n",
    "To create a custom viewer one usually inherits from an existing ipywidgets widget and implements the logic for displaying the object.\n",
    "The only requirement is that the first argument of the constructor is the object to visualize.\n",
    "\n",
    "Also to make the new class recognizable by the {py:meth}`~aiidalab_widgets_base.viewer` function, the class should be decorated with the {py:func}`~aiidalab_widgets_base.register_viewer_widget` decorator.\n",
    "\n",
    "\n",
    "To demonstrate how this works we create a simple viewer for the `orm.Int` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ipywidgets as ipw\n",
    "\n",
    "from aiidalab_widgets_base import register_viewer_widget\n",
    "\n",
    "\n",
    "@register_viewer_widget(\"data.core.int.Int.\")\n",
    "class IntViewerWidget(ipw.HTML):\n",
    "    def __init__(self, node, **kwargs):\n",
    "        super().__init__(**kwargs)\n",
    "        self.value = f\"Int object: <b>{node.value}<b>\"\n",
    "\n",
    "\n",
    "vwr = viewer(orm.Int(3).store())\n",
    "display(vwr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The string to be put as an argument of the `register_viewer_widget` decorator can be obtained from the `node_type` property of an object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "i_node = orm.Int(1)\n",
    "print(i_node.node_type)"
   ]
  }
 ],
 "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}