Metadata-Version: 2.0
Name: sumo
Version: 1.0.4
Summary: Heavy weight plotting tools for ab initio calculations
Home-page: https://github.com/smtg-ucl/sumo
Author: Alex Ganose, Adam J. Jackson
Author-email: d.scanlon@ucl.ac.uk
License: MIT
Keywords: chemistry pymatgen dft vasp dos band
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Provides-Extra: docs
Requires-Dist: spglib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pymatgen
Requires-Dist: h5py
Requires-Dist: phonopy
Requires-Dist: matplotlib
Requires-Dist: seekpath
Provides-Extra: docs
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-argparse; extra == 'docs'

Sumo
====

.. image:: https://travis-ci.org/SMTG-UCL/sumo.svg?branch=master
    :target: https://travis-ci.org/SMTG-UCL/sumo

.. image:: https://readthedocs.org/projects/sumo/badge/?version=latest
    :target: http://sumo.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

Sumo is a Python toolkit for plotting and analysing VASP calculations. The main features include:

1. An extensive framework for generating high-symmetry k-point paths.
2. Plotting scripts for electronic and phonon band structures, density of states, and optical absorption.
3. Analysis scripts to calculate band edge effective masses.

Sumo is built on pymatgen, meaning there is no effort required to read and write typical VASP files.
Sumo is free to use, however, we welcome your help in improving and extending the
package with your own contributions.

Warning: There are probably still some bugs. If you think you've find any,
please report them on the Issue Tracker.

Usage
-----

Primarily, sumo is intended to be used via the command-line, however, a fully-documented
python API is also provided.
A full manual, including tutorials and API documentation,
is `available online <http://sumo.readthedocs.io/en/latest/>`__.
Additionally, the built-in help (``-h``) option for each command provides a
summary of the available options.

Currently the scripts provided by sumo 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 state diagrams.
- ``sumo-optplot``: For plotting publication-ready optical absorption plots.
- ``sumo-phonon-bandplot``: For plotting publication-ready phonon band structure diagrams.
- ``sumo-bandstats``: For calculating electron and hole effective masses from a band structure.

A guide to using each command can be found on the
`Tutorial page <http://sumo.readthedocs.io/en/latest/tutorials.html>`_.

For a preview of the functionality of sumo, see the
`Gallery <http://sumo.readthedocs.io/en/latest/gallery.html>`_.

Installation
------------

We recommend installation from source with Pip, this will automatically install any dependencies:

.. code-block:: bash

    pip3 install --user sumo

To build the documentation, download the package source and install with extra dependecies:

.. code-block:: bash

    pip3 install --user .[docs]
    cd docs
    make html

Developer installation
~~~~~~~~~~~~~~~~~~~~~~

Developers may prefer to install using ``pip3 install --user -e .`` which
creates an "editable" local installation. Instead of copying files,
this creates links to the source folder so that that tweaks to the
code in your source folder will be immediately reflected on the PATH.

Tests
~~~~~

To ensure the code has been installed correctly, the unittests can be run using::

  python -m unittest discover tests

Requirements
------------

Sumo is currently compatible with Python 3.5+ and relies on a number of
open-source python packages, specifically:

- Pymatgen
- Numpy
- Scipy
- Matplotlib
- Spglib
- Phonopy
- SeeK-path
- H5py (optional dependency for phonon plotting features)

Sumo uses Pip and setuptools for installation. You *probably* already
have this; if not, your GNU/Linux package manager will be able to oblige
with a package named something like ``python-setuptools``. On Max OSX
the Python distributed with `Homebrew <http://brew.sh>`_. includes
setuptools and Pip.

License
-------

Sumo is made available under the MIT License.


