From 9832a59080f5b83974e2311b55fb89ee7109b56d Mon Sep 17 00:00:00 2001 From: Kristjan Eimre Date: Mon, 19 Aug 2024 15:28:38 +0300 Subject: [PATCH] Fix readme and example (#62) --- README.md | 116 +++++++++++++++++------------------------- example/example.ipynb | 89 +++++++++----------------------- 2 files changed, 72 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index 3dd4f6c..5139ed5 100644 --- a/README.md +++ b/README.md @@ -9,83 +9,61 @@ A Jupyter widget to plot band structures and density of states. The widget is us -## Installation & usage +## Installation ```sh pip install widget-bandsplot ``` -## Usage - -### 1. Plot both the band structure and the density of states (DOS) side by side - -```python -w = BandsPlotWidget(bands=[banddata1, banddata2], dos=dosdata, plot_fermilevel = True, show_legend = True, energy_range = [-10,10]) -display(w) -``` - -In order to plot the band structure and density of states, one needs -to provide bands data and DOS data as JSON-files. The examples of the input -JSON-files are provided in the `examples/data` folder. The JSON-files for the -band structure can be exported with the [AiiDA command line interface (CLI) `verdi`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/command_line.html#reference-command-line) as demonstrated in -the code below: - -```bash -verdi data band export --format=json -``` -One can plot several band structure input files together with the widget. -One exampla valid input is: - -```python -dos_data = { - "fermi_energy": -7.0, - "dos": [ - { - "label": "Total DOS", # required - "x": [0.0, 0.1, 0.2], # required - "y": [1.2, 3.2, 0.0], # required - "borderColor": "#41e2b3", # optional - "backgroundColor": "#51258b", # optional - "backgroundAlpha": "52%", #optional: A string with integer between 0-100 and '%' in end. - "lineStyle": "dash", # optional - }, - { - "label": "Co (s↑)", - "x": [0.0, 0.1, 0.2], - "y": [1.2, 3.2, 0.0], - "lineStyle": "solid", - "borderColor": "#43ee8b", - "backgroundColor": "#59595c", - }, - { - "label": "Co (s↓)", - "x": [0.0, 0.1, 0.2], - "y": [1.2, 3.2, 0.0], - "lineStyle": "solid", - "borderColor": "#403bae", - "backgroundColor": "#a16c5e", - }, - ], -} -``` - -### 2. Plot only the band structure - -```python -w = BandsPlotWidget(bands=[banddata1, banddata2], format_settings = {"plotFermil": True, "showLegend": True}, energy_range = [-10,10]) -display(w) -``` +## Usage -### 3. Plot only the density of states (DOS) +Minimal usage example of the widget is the following: ```python -w = BandsPlotWidget(dos=dosdata, format_settings = {"plotFermil": True, "showLegend": True}, energy_range = [-10, 10]) -display(w) +widget = BandsPlotWidget( + bands = [bands_data], + dos = dos_data, + energy_range = [-10.0, 10.0], + format_settings = { + "showFermi": True, + "showLegend": True, + } +) +display(widget) ``` -When only plotting the density of states, the plot will be shown in -horizontal format. - +where `bands_data` and `dos_data` are contain the band structure and density of states data, respectively. The format for these data objects is the following: + +- Band structure data follows the [AiiDA CLI](https://aiida.readthedocs.io/projects/aiida-core/en/latest/reference/command_line.html#reference-command-line) export format that can be generated from an [AiiDA BandsData](https://aiida.readthedocs.io/projects/aiida-core/en/v2.6.2/topics/data_types.html#topics-data-types-materials-bands) node with the following command: + ```bash + verdi data band export --format=json + ``` +- The density of states data uses a custom format, with a a valid example being: + ```python + dos_data = { + "fermi_energy": -7.0, + "dos": [ + { + "label": "Total DOS", # required + "x": [0.0, 0.1, 0.2], # required + "y": [1.2, 3.2, 0.0], # required + "lineStyle": "dash", # optional + "borderColor": "#41e2b3", # optional + "backgroundColor": "#51258b", # optional + }, + { + "label": "Co", + "x": [0.0, 0.1, 0.2], + "y": [1.2, 3.2, 0.0], + "lineStyle": "solid", + "borderColor": "#43ee8b", + "backgroundColor": "#59595c", + }, + ], + } + ``` + +For more detailed usage, see `example/example.ipynb` and for more example input files see `example/data`. ## Development @@ -126,8 +104,8 @@ being displayed correctly in the test. [![screenshot comparison](https://github.com/osscar-org/widget-bandsplot/actions/workflows/screenshot-comparison.yml/badge.svg)](https://github.com/osscar-org/widget-bandsplot/actions/workflows/screenshot-comparison.yml) -If the `widget test` passes but the `screenshot comparison` fails, it indicates the appearance of the widget -is different from the previous version. In this case, you'll need to manually download the artifact from +If the `widget test` passes but the `screenshot comparison` fails, it indicates the appearance of the widget +is different from the previous version. In this case, you'll need to manually download the artifact from the `widget test` and use it to replace the `widget-sample.png` figure in the `test` folder. ## Acknowledgements diff --git a/example/example.ipynb b/example/example.ipynb index 1c8de54..e765874 100644 --- a/example/example.ipynb +++ b/example/example.ipynb @@ -13,79 +13,35 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "

\n", - " This is a Jupyter widget, which plots the bandstructure and density of states from given json files.\n", - "

\n", + "This is a Jupyter widget, which plots the bandstructure and density of states from given json files.\n", "\n", - "## **Input json files**\n", + "## Input json files\n", "\n", - "

\n", - " On the left, it plots the bandstructures. One can input several bandstructure json files as a list.\n", - " The figure on the right shows the density of states, which can only show one DOS plot. The json files\n", - " for the bandstructures can be generated from AiiDA with the verdi command:\n", - "

\n", + "On the left, it plots the bandstructures. One can input several bandstructure json files as a list.\n", + "The figure on the right shows the density of states, which can only show one DOS plot. The json files\n", + "for the bandstructures can be generated from AiiDA with the verdi command:\n", "\n", "```bash\n", "verdi data bands export --format json \n", "```\n", "\n", - "

\n", - " The json format for the DOS can be checked in the github repository.\n", - "

\n", + "The json format for the DOS can be checked from the example data files, e.g. `data/Si_dos.json`.\n", "\n", - "\n", - "https://raw.githubusercontent.com/osscar-org/widget-bandsplot/develop/example/data/Si_dos.json" + "## Note on Fermi energy\n", + "\n", + "The Fermi energy is reading from the bands and DOS json files. And bandstructure and density \n", + "of states plots are aligned to the Fermi energy (shift the Fermi energy to zero).\n", + "\n", + "In the default plot for the DOS, there is a horizontal line to highlight the Fermi level. One \n", + "can turn it off by setting showFermi = False. The legend of the DOS can be turned off\n", + "by set showLegend = False." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "

\n", - " Here, one needs to use the json package to load the json file and pass it to the widget.\n", - "

\n", - "\n", - "```python\n", - "with open('./data/Si_bands.json', 'r') as file:\n", - " band_Si = json.load(file)\n", - " \n", - "with open('./data/Si_dos.json', 'r') as file:\n", - " dos_Si = json.load(file)\n", - "```\n", - "\n", - "## **Fermi energy**\n", - "\n", - "

\n", - " The Fermi energy is reading from the bands and DOS json files. And bandstructure and density \n", - " of states plots are aligned to the Fermi energy (shift the Fermi energy to zero).\n", - "

\n", - "\n", - "

\n", - " In the default plot for the DOS, there is a horizontal line to highlight the Fermi level. One \n", - " can turn it off by setting showFermi = False. The legend of the DOS can be turned off\n", - " by set showLegend = False.\n", - "

\n", - "\n", - "## **Usage of the widget**\n", - "\n", - "

\n", - " Remeber to pass the bandstructure data as a list of json objects. \"energy_range\" sets the \n", - " energy range for the plots.\n", - "

\n", - "\n", - "### **Plot both bandstructure and DOS**\n", - "```python\n", - "w1 = BandsPlotWidget(\n", - " bands = [si_bands],\n", - " dos = si_dos,\n", - " energy_range = [-10.0, 10.0],\n", - " format_settings = {\n", - " \"showFermi\": True,\n", - " \"showLegend\": True,\n", - " }\n", - ")\n", - "display(w1)\n", - "```" + "## Import modules and load example data files" ] }, { @@ -94,9 +50,10 @@ "metadata": {}, "outputs": [], "source": [ - "from widget_bandsplot import BandsPlotWidget\n", - "import json\n", - "from copy import deepcopy" + "# This cell is only needed for development, for javascript changes to be reflected in the notebook automatically.\n", + "%load_ext autoreload\n", + "%autoreload 2\n", + "%env ANYWIDGET_HMR=1" ] }, { @@ -105,6 +62,10 @@ "metadata": {}, "outputs": [], "source": [ + "from widget_bandsplot import BandsPlotWidget\n", + "\n", + "import json\n", + "\n", "def load_file(filename):\n", " with open(filename, 'r') as fhandle:\n", " return json.load(fhandle)\n", @@ -230,7 +191,7 @@ " bands=[si_bands, si_bands_shifted],\n", " dos=si_dos,\n", " energy_range = [-10.0, 10.0],\n", - " bands_color=['red', 'yellow']\n", + " bands_color=['red', 'green']\n", ")\n", "display(w5)" ] @@ -259,7 +220,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.5" + "version": "3.10.0" }, "voila": { "authors": "Dou Du and Giovanni Pizzi"