{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# First steps"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sisl\n",
    "\n",
    "# We define the root directory where our files are\n",
    "siesta_files = (\n",
    "    sisl._environ.get_environ_variable(\"SISL_FILES_TESTS\") / \"sisl\" / \"io\" / \"siesta\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Your first plots\n",
    "\n",
    "The most straightforward way to plot things in sisl is to call their `plot` method. For example if we have the path to a bands file we can call plot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sisl.get_sile(siesta_files / \"SrTiO3.bands\").plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can pass arguments to the plotting function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx-thumbnail": {
     "tooltip": "A variety of introduction plots to see what can be done"
    },
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "rho_file = sisl.get_sile(siesta_files / \"SrTiO3.RHO\")\n",
    "rho_file.plot(axes=\"xy\", nsc=[2, 1, 1], smooth=True).show(\"png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some objects can be plotted in different ways, and just calling `plot` will do it in the default way. You can however **choose which plot you want** from the available representations. For example, out of a PDOS file you can plot the PDOS (the default):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_file = sisl.get_sile(siesta_files / \"SrTiO3.PDOS\")\n",
    "\n",
    "pdos_file.plot(groups=[{\"species\": \"O\", \"name\": \"O\"}, {\"species\": \"Ti\", \"name\": \"Ti\"}])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or the geometry (not the default, you need to specify it):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_file.plot.geometry(atoms_scale=0.7)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Updating your plots\n",
    "----------------\n",
    "\n",
    "When you call `.plot()`, you receive a `Plot` object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot = pdos_file.plot()\n",
    "type(pdos_plot)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`Plot` objects are a kind of `Workflow`. You can check the `sisl.nodes` documentation to understand what exactly this means. But long story short, this means that the computation is split in multiple nodes, as you can see in the following diagram:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.network.visualize(notebook=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With that knowledge, when you update the inputs of a plot, only the necessary parts are recalculated. In that way, you may avoid repeating expensive calculations or reading to files that no longer exist. Inputs are updated with `update_inputs`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.update_inputs(Erange=[-3, 3])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some inputs are a bit cumbersome to write by hand, and therefore along your journey you'll find that plots have some helper methods to modify inputs much faster. For example, `PdosPlot` has the `split_DOS` method, which generates groups of orbitals for you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.split_DOS()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "    \n",
    "Don't worry!\n",
    "    \n",
    "Each plot class has its own dedicated notebook in the documentation to guide you through all the knobs that they have!\n",
    "    \n",
    "</div>\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Different plotting backends\n",
    "\n",
    "Hidden between all the inputs, you can find a **very special input**: `backend`.\n",
    "\n",
    "This input allows you to choose the plotting backend used to display a plot. If you don't like the default one, just change it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.update_inputs(backend=\"matplotlib\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's go back to the default one, `plotly`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.update_inputs(backend=\"plotly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further customization\n",
    "\n",
    "If you are a master of some backend, you'll be happy to know that you can run any backend specific method on the plot. For example, plotly has a method called `add_vline` that draws a vertical line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pdos_plot.add_vline(-1).add_vline(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In fact, if you need the raw figure for something, you can find it under the `figure` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "type(pdos_plot.figure)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "source": [
    "## Discover more\n",
    "\n",
    "This notebook has shown you the most basic features of the framework with the hope that you will be hooked into it :)\n",
    "\n",
    "If it succeeded, we invite you to check the rest of the documentation. **It only gets better from here!**"
   ]
  }
 ],
 "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.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}