Sumo
====
.. image:: https://img.shields.io/github/actions/workflow/status/smtg-ucl/sumo/tests.yml?branch=master
:target: https://github.com/SMTG-UCL/sumo/actions?query=workflow%3A%22Run+tests%22
:alt: Build Status
.. image:: http://joss.theoj.org/papers/d12ca1f4198dffa2642a30b2ab01e16d/status.svg
:target: http://joss.theoj.org/papers/d12ca1f4198dffa2642a30b2ab01e16d
:alt: JOSS Paper
.. image:: https://img.shields.io/pypi/v/sumo
:target: https://pypi.org/project/sumo/
:alt: Pypi Repository
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1338124.svg
:target: https://doi.org/10.5281/zenodo.1338124
:alt: Zenodo Repository
Sumo is a Python toolkit for plotting and analysis of ab initio
solid-state calculation data,
built on existing Python packages from the solid-state
chemistry/physics community.
It is hoped that these command-line tools will bring some of the
benefits of these libraries to a wider user-base while providing
publication-ready plotting (powered by Matplotlib_.)
The main features include:
1. **An extensive framework for generating high-symmetry k-point paths.**
- Crystallographic spacegroups are determined using Spglib_.
- Conventional crystallographic paths are built in as well as interfaces to
the SeeK-path_ and
Pymatgen_ implementations.
2. **Plotting scripts for electronic and phonon band structures, density
of states, and optical absorption diagrams.**
- VASP calculations are imported using Pymatgen_.
- The Phonopy_ framework is supported for phonon band structures.
3. **Analysis scripts to calculate parabolic and non-parabolic band
effective masses.**
- Curve fitting is performed using `Scipy <https://www.scipy.org>`_.
The code currently primarily supports VASP calculations, and has
partial support for CASTEP and for LMTO calculations with
`Questaal <https://www.questaal.org>`_.
We would like to add support for additional solid-state codes in
future releases. Code contributions to interface with these packages
are welcome.
Sumo is free to use, however, we ask that you cite the code if you use
it in your research. See the "contributing" section for information
about reporting bugs and getting involved.
Usage
-----
Sumo is intended to be used via the command-line, however, a
fully-documented python API is also provided. A manual, including
tutorials and API documentation, is `available online
<https://smtg-bham.github.io/sumo/>`_. Additionally, the built-in
help (``-h``) option for each command provides a summary of the
available options.
A guide to using each command can be found on the
`Tutorial page <https://smtg-bham.github.io/sumo/tutorials.html>`_.
For a preview of the functionality of sumo, see the
`Gallery <https://smtg-bham.github.io/sumo/gallery.html>`_.
Currently, the scripts provided are:
- ``sumo-kgen``: For generating VASP KPOINTS files along high-symmetry
k-point paths.
- ``sumo-bandplot``: For plotting publication-ready electronic band
structure diagrams.
- ``sumo-dosplot``: For plotting publication-ready electronic density of
states diagrams.
- ``sumo-optplot``: For plotting publication-ready optical absorption
diagrams.
- ``sumo-phonon-bandplot``: For plotting publication-ready phonon band
structure diagrams.
- ``sumo-bandstats``: For calculating electron and hole effective masses
from a band structure.
Information on how to tweak the style of sumo plots is provided on the
`Customising Sumo Plots page
<https://smtg-bham.github.io/sumo/customising-plots.html>`_.
Feature support for different codes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------+----------+--------+----------+
| Features | VASP | CASTEP | Questaal |
+==================+==========+========+==========+
| k-point path | **Y** | **Y** | **Y** |
| generation | | (1) | |
+------------------+----------+--------+----------+
| band plotting | **Y** | **Y** | **Y** |
+------------------+----------+--------+----------+
| band projections | **Y** | *N* | *N* |
+------------------+----------+--------+----------+
| band analysis | **Y** | *N* | *N* |
+------------------+----------+--------+----------+
| total DOS plot | **Y** | **Y** | **Y** |
+------------------+----------+--------+----------+
| projected DOS | **Y** | **Y** | **Y** |
+------------------+----------+--------+----------+
| phonon band plot | **Y** (2)| **Y** | *N* |
+------------------+----------+--------+----------+
(1) Brillouin-zone path can also be written for CASTEP phonon calculation
(2) VASP phonons are plotted from Phonopy output files
Installation
------------
Sumo is a Python 3 package and requires a
`typical scientific Python stack <https://www.scipy.org/about.html>`_;
we recommend using your main package manager if possible
(e.g. apt, Homebrew), or Anaconda to install Python 3 with setuptools.
It is a good idea to also use this package manager to install
Numpy and Matplotlib, as building them with setuptools can be troublesome.
Sumo can then be installed using the Python package manager "Pip",
which will automatically setup other Python packages as required:
.. code-block:: bash
pip install --user sumo
If this is your first entry to the scientific Python ecosystem, be
aware that the full stack including Scipy with need several hundred MB
of disk space.
Developer installation
~~~~~~~~~~~~~~~~~~~~~~
*Regular users can skip this section!*
Sumo can also be installed from a copy of the source repository
(https://github.com/smtg-bham/sumo); this will be preferred for development
work or if using experimental code branches.
To clone the project from Github and make a local installation:
.. code-block:: bash
git clone https://github.com/smtg-bham/sumo.git
cd sumo
pip install --user -e .
The ``-e`` and ``--user`` options are recommended:
Instead of copying files, with ``-e`` pip will create links to the
source folder so that that tweaks to the code will be immediately
reflected on the PATH.
The ``--user`` flag installs to a directory in your home folder
(usually under the hidden directory *~/.local*),
preventing interference with your root Python installation.
Tests
^^^^^
From a developer installation, the unit tests can be
run (from the root directory of the project) using::
pytest
Automatic testing is run on the master branch of Sumo and proposed
features using GitHub Actions.
Documentation
^^^^^^^^^^^^^
To build the documentation from the project files, install
sumo with extra Sphinx dependencies before compiling with ``sphinx-build``.
.. code-block:: bash
pip install --user .[docs]
sphinx-build docs/src docs_build
The user guide can then be explored from *docs/build/html/index.html*.
How to cite sumo
----------------
If you use sumo in your research, please consider citing the following work:
Alex M. Ganose, Adam J. Jackson, David O. Scanlon. *sumo: Command-line tools for plotting and analysis of periodic ab initio calculations.* Journal of Open Source Software, 2018 3 (28), 717, `doi:10.21105/joss.00717 <https://doi.org/10.21105/joss.00717>`_.
License
-------
Sumo is made available under the MIT License.
Detailed requirements
---------------------
Sumo is currently compatible with Python 3.5+ and relies on a number of
open-source python packages, specifically:
- Pymatgen_ (version >= 2017.12.30)
- Numpy_
- Scipy_
- Matplotlib_
- Spglib_
- Phonopy_
- SeeK-path_
- `H5py <https://www.h5py.org>`_
.. _matplotlib: https://matplotlib.org
.. _numpy: http://www.numpy.org
.. _phonopy: https://atztogo.github.io/phonopy
.. _pymatgen: http://pymatgen.org
.. _scipy: https://www.scipy.org
.. _seek-path: https://github.com/giovannipizzi/seekpath
.. _spglib: https://atztogo.github.io/spglib
Contributing
------------
Bugs reports and feature requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are probably still some bugs. If you think you've found
one, please report it on the `Issue Tracker
<https://github.com/SMTG-bham/sumo/issues>`_.
This is also the place to propose ideas for new features or ask
questions about the design of Sumo.
Poor documentation is considered a bug, but please be as specific as
possible when asking for improvements.
Code contributions
~~~~~~~~~~~~~~~~~~
We welcome your help in improving and extending the package with your
own contributions. This is managed through Github pull requests;
for external contributions we prefer the
`"fork and pull" <https://guides.github.com/activities/forking/>`__
workflow while core developers use branches in the main repository:
1. First open an Issue to discuss the proposed contribution. This
discussion might include how the changes fit Sumo's scope and a
general technical approach.
2. Make your own project fork and implement the changes
there. Please keep your code style compliant with PEP8.
3. Open a pull request to merge the changes into the main
project. A more detailed discussion can take place there before
the changes are accepted.
Raw data
{
"_id": null,
"home_page": "https://github.com/smtg-ucl/sumo",
"name": "sumo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "chemistry pymatgen dft vasp dos band",
"author": "Alex Ganose, Adam J. Jackson",
"author_email": "d.scanlon@ucl.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/95/ee/fde1f386bad2ca538b849953365bf1f5e8a30cfcb897b07e0102992a8519/sumo-2.3.8.tar.gz",
"platform": null,
"description": "Sumo\n====\n\n\n.. image:: https://img.shields.io/github/actions/workflow/status/smtg-ucl/sumo/tests.yml?branch=master\n :target: https://github.com/SMTG-UCL/sumo/actions?query=workflow%3A%22Run+tests%22\n :alt: Build Status\n\n.. image:: http://joss.theoj.org/papers/d12ca1f4198dffa2642a30b2ab01e16d/status.svg\n :target: http://joss.theoj.org/papers/d12ca1f4198dffa2642a30b2ab01e16d\n :alt: JOSS Paper\n\n.. image:: https://img.shields.io/pypi/v/sumo\n :target: https://pypi.org/project/sumo/\n :alt: Pypi Repository\n\n\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1338124.svg\n :target: https://doi.org/10.5281/zenodo.1338124\n :alt: Zenodo Repository\n\nSumo is a Python toolkit for plotting and analysis of ab initio\nsolid-state calculation data,\nbuilt on existing Python packages from the solid-state\nchemistry/physics community.\nIt is hoped that these command-line tools will bring some of the\nbenefits of these libraries to a wider user-base while providing\npublication-ready plotting (powered by Matplotlib_.)\n\nThe main features include:\n\n1. **An extensive framework for generating high-symmetry k-point paths.**\n\n - Crystallographic spacegroups are determined using Spglib_.\n - Conventional crystallographic paths are built in as well as interfaces to\n the SeeK-path_ and\n Pymatgen_ implementations.\n\n2. **Plotting scripts for electronic and phonon band structures, density\n of states, and optical absorption diagrams.**\n\n - VASP calculations are imported using Pymatgen_.\n - The Phonopy_ framework is supported for phonon band structures.\n\n3. **Analysis scripts to calculate parabolic and non-parabolic band\n effective masses.**\n\n - Curve fitting is performed using `Scipy <https://www.scipy.org>`_.\n\nThe code currently primarily supports VASP calculations, and has\npartial support for CASTEP and for LMTO calculations with\n`Questaal <https://www.questaal.org>`_.\nWe would like to add support for additional solid-state codes in\nfuture releases. Code contributions to interface with these packages\nare welcome.\n\nSumo is free to use, however, we ask that you cite the code if you use\nit in your research. See the \"contributing\" section for information\nabout reporting bugs and getting involved.\n\nUsage\n-----\n\nSumo is intended to be used via the command-line, however, a\nfully-documented python API is also provided. A manual, including\ntutorials and API documentation, is `available online\n<https://smtg-bham.github.io/sumo/>`_. Additionally, the built-in\nhelp (``-h``) option for each command provides a summary of the\navailable options.\n\nA guide to using each command can be found on the\n`Tutorial page <https://smtg-bham.github.io/sumo/tutorials.html>`_.\n\nFor a preview of the functionality of sumo, see the\n`Gallery <https://smtg-bham.github.io/sumo/gallery.html>`_.\n\nCurrently, the scripts provided are:\n\n- ``sumo-kgen``: For generating VASP KPOINTS files along high-symmetry\n k-point paths.\n- ``sumo-bandplot``: For plotting publication-ready electronic band\n structure diagrams.\n- ``sumo-dosplot``: For plotting publication-ready electronic density of\n states diagrams.\n- ``sumo-optplot``: For plotting publication-ready optical absorption\n diagrams.\n- ``sumo-phonon-bandplot``: For plotting publication-ready phonon band\n structure diagrams.\n- ``sumo-bandstats``: For calculating electron and hole effective masses\n from a band structure.\n\nInformation on how to tweak the style of sumo plots is provided on the\n`Customising Sumo Plots page\n<https://smtg-bham.github.io/sumo/customising-plots.html>`_.\n\nFeature support for different codes\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n+------------------+----------+--------+----------+\n| Features | VASP | CASTEP | Questaal |\n+==================+==========+========+==========+\n| k-point path | **Y** | **Y** | **Y** |\n| generation | | (1) | |\n+------------------+----------+--------+----------+\n| band plotting | **Y** | **Y** | **Y** |\n+------------------+----------+--------+----------+\n| band projections | **Y** | *N* | *N* |\n+------------------+----------+--------+----------+\n| band analysis | **Y** | *N* | *N* |\n+------------------+----------+--------+----------+\n| total DOS plot | **Y** | **Y** | **Y** |\n+------------------+----------+--------+----------+\n| projected DOS | **Y** | **Y** | **Y** |\n+------------------+----------+--------+----------+\n| phonon band plot | **Y** (2)| **Y** | *N* |\n+------------------+----------+--------+----------+\n\n(1) Brillouin-zone path can also be written for CASTEP phonon calculation\n(2) VASP phonons are plotted from Phonopy output files\n\nInstallation\n------------\n\nSumo is a Python 3 package and requires a\n`typical scientific Python stack <https://www.scipy.org/about.html>`_;\nwe recommend using your main package manager if possible\n(e.g. apt, Homebrew), or Anaconda to install Python 3 with setuptools.\nIt is a good idea to also use this package manager to install\nNumpy and Matplotlib, as building them with setuptools can be troublesome.\nSumo can then be installed using the Python package manager \"Pip\",\nwhich will automatically setup other Python packages as required:\n\n.. code-block:: bash\n\n pip install --user sumo\n\nIf this is your first entry to the scientific Python ecosystem, be\naware that the full stack including Scipy with need several hundred MB\nof disk space.\n\n\nDeveloper installation\n~~~~~~~~~~~~~~~~~~~~~~\n\n*Regular users can skip this section!*\n\nSumo can also be installed from a copy of the source repository\n(https://github.com/smtg-bham/sumo); this will be preferred for development\nwork or if using experimental code branches.\n\nTo clone the project from Github and make a local installation:\n\n.. code-block:: bash\n\n git clone https://github.com/smtg-bham/sumo.git\n cd sumo\n pip install --user -e .\n\nThe ``-e`` and ``--user`` options are recommended:\nInstead of copying files, with ``-e`` pip will create links to the\nsource folder so that that tweaks to the code will be immediately\nreflected on the PATH.\nThe ``--user`` flag installs to a directory in your home folder\n(usually under the hidden directory *~/.local*),\npreventing interference with your root Python installation.\n\nTests\n^^^^^\n\nFrom a developer installation, the unit tests can be\nrun (from the root directory of the project) using::\n\n pytest\n\nAutomatic testing is run on the master branch of Sumo and proposed\nfeatures using GitHub Actions.\n\nDocumentation\n^^^^^^^^^^^^^\n\nTo build the documentation from the project files, install\nsumo with extra Sphinx dependencies before compiling with ``sphinx-build``.\n\n.. code-block:: bash\n\n pip install --user .[docs]\n sphinx-build docs/src docs_build\n\nThe user guide can then be explored from *docs/build/html/index.html*.\n\nHow to cite sumo\n----------------\n\nIf you use sumo in your research, please consider citing the following work:\n\n Alex M. Ganose, Adam J. Jackson, David O. Scanlon. *sumo: Command-line tools for plotting and analysis of periodic ab initio calculations.* Journal of Open Source Software, 2018 3 (28), 717, `doi:10.21105/joss.00717 <https://doi.org/10.21105/joss.00717>`_.\n\nLicense\n-------\n\nSumo is made available under the MIT License.\n\n\nDetailed requirements\n---------------------\n\nSumo is currently compatible with Python 3.5+ and relies on a number of\nopen-source python packages, specifically:\n\n- Pymatgen_ (version >= 2017.12.30)\n- Numpy_\n- Scipy_\n- Matplotlib_\n- Spglib_\n- Phonopy_\n- SeeK-path_\n- `H5py <https://www.h5py.org>`_\n\n.. _matplotlib: https://matplotlib.org\n.. _numpy: http://www.numpy.org\n.. _phonopy: https://atztogo.github.io/phonopy\n.. _pymatgen: http://pymatgen.org\n.. _scipy: https://www.scipy.org\n.. _seek-path: https://github.com/giovannipizzi/seekpath\n.. _spglib: https://atztogo.github.io/spglib\n\n\nContributing\n------------\n\nBugs reports and feature requests\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThere are probably still some bugs. If you think you've found\none, please report it on the `Issue Tracker\n<https://github.com/SMTG-bham/sumo/issues>`_.\nThis is also the place to propose ideas for new features or ask\nquestions about the design of Sumo.\nPoor documentation is considered a bug, but please be as specific as\npossible when asking for improvements.\n\nCode contributions\n~~~~~~~~~~~~~~~~~~\n\nWe welcome your help in improving and extending the package with your\nown contributions. This is managed through Github pull requests;\nfor external contributions we prefer the\n`\"fork and pull\" <https://guides.github.com/activities/forking/>`__\nworkflow while core developers use branches in the main repository:\n\n 1. First open an Issue to discuss the proposed contribution. This\n discussion might include how the changes fit Sumo's scope and a\n general technical approach.\n 2. Make your own project fork and implement the changes\n there. Please keep your code style compliant with PEP8.\n 3. Open a pull request to merge the changes into the main\n project. A more detailed discussion can take place there before\n the changes are accepted.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Heavy weight plotting tools for ab initio solid-state calculations",
"version": "2.3.8",
"project_urls": {
"Homepage": "https://github.com/smtg-ucl/sumo"
},
"split_keywords": [
"chemistry",
"pymatgen",
"dft",
"vasp",
"dos",
"band"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cf725b77e307cff0e19c0454cfef565e1b8bf6bbd302aa00aa181ef96357c5db",
"md5": "7fb2a82422981bad070ffd36701cceee",
"sha256": "a167a6c5a9a05a30accf331f74e002ed3f8afdb01c28e1fc01b86ee5b52f62fe"
},
"downloads": -1,
"filename": "sumo-2.3.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7fb2a82422981bad070ffd36701cceee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 136870,
"upload_time": "2024-01-10T12:29:02",
"upload_time_iso_8601": "2024-01-10T12:29:02.283462Z",
"url": "https://files.pythonhosted.org/packages/cf/72/5b77e307cff0e19c0454cfef565e1b8bf6bbd302aa00aa181ef96357c5db/sumo-2.3.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95eefde1f386bad2ca538b849953365bf1f5e8a30cfcb897b07e0102992a8519",
"md5": "2f6c76a237b46321f480307b9f22787f",
"sha256": "2d672dd0e9ea8c3248da6325bdb482e2ebef28f7e03121c0bb78b3d9f7aa44e1"
},
"downloads": -1,
"filename": "sumo-2.3.8.tar.gz",
"has_sig": false,
"md5_digest": "2f6c76a237b46321f480307b9f22787f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14541999,
"upload_time": "2024-01-10T12:29:05",
"upload_time_iso_8601": "2024-01-10T12:29:05.071522Z",
"url": "https://files.pythonhosted.org/packages/95/ee/fde1f386bad2ca538b849953365bf1f5e8a30cfcb897b07e0102992a8519/sumo-2.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-10 12:29:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smtg-ucl",
"github_project": "sumo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sumo"
}
JSON
