sumo-phonon-bandplot
=====================

``sumo-phonon-bandplot`` is a program for generating publication-ready phonon band
structure diagrams based on ``phonopy`` calculations.

.. contents:: Table of Contents
   :local:
   :backlinks: None

Usage
-----

The full range of options supported by ``sumo-phonon-bandplot`` are detailed in the
`Command-Line Interface`_ section, and be can be accessed using the command::

    sumo-phonon-bandplot -h

To plot a phonon band structure, simply run the following command in a folder
containing ``FORCE_SETS`` and ``SPOSCAR`` files generated by ``phonopy`` and a VASP ``POSCAR``::

    sumo-phonon-bandplot

The plot will be written to a file named ``phonon_band.pdf``, with the raw band structure
data written to ``phonon_band.dat`` and a yaml formatted band structure written to ``phonon_band.yaml``

For example, if we run the command in the ``sumo/tests/data/Rb2SnI6/phonopy`` directory, the band structure
should look like:

.. image:: figures/phonon_band_basic.png
   :height: 400px
   :align: center


Supercell Size
~~~~~~~~~~~~~~

``sumo-phonon-bandplot`` will attempt to extract the supercell size from the structure information, however,
sometimes it will fail and an error occurs. In this case, the supercell size should be specified manually using
the ``--dim`` option. For example, if the force constants were calculated in a 3x3x3 supercell, the
command would be::

    sumo-phonon-bandplot --dim 3 3 3


Supported Inputs
~~~~~~~~~~~~~~~~

``sumo-phonon-bandplot`` will automatically look for a ``FORCE_SETS`` file in the current directory,
however, other input types are supported. The input can be specified using the ``--filename`` option.
The supported inputs are:

- ``FORCE_SETS``: If ``--dim`` not specified, ``POSCAR`` and ``SPOSCAR`` files should also be
  in the current directory.
- ``FORCE_CONSTANTS``: In this case, a corresponding ``POSCAR`` and ``SPOSCAR`` are not required.
- ``band.yaml``: ``phonopy``-type band structure yaml file. Please note that when using this mode,
  the high-symmetry path cannot be altered.


Basic Options
~~~~~~~~~~~~~

The height, and width of the graphic, along with the y-axis limits, can be controlled via the
``--width``, ``--height``, ``--ymax``, and ``--ymin`` options.

By default, the eigenvectors are not written to the ``phonon_band.yaml`` file.
To enable writing of the eigenvectors use the ``--eigenvectors`` option.

The Born effective charges can be included, in order to calculate the LO-TO splitting.
The usage is ``--born BORN_FILE``, where ``BORN_FILE`` is a file containing the Born effective
charges. The easiest way to generate this file is using the ``phonopy-vasp-born`` script,
included in the ``phonopy`` installation.

If the force constant calculations have been performed on the conventional cell,
the ``--primitive-axis`` option can be used to unfold the band structure onto the
primitive cell. The input for this option should be formatted as a list of 9 numbers, specifying
the full matrix transformation. For example, to convert from the F centered cubic conventional
cell to primitive cell, the usage would be::

    sumo-phonon-bandplot --primitive-axis 0 0.5 0.5  0.5 0 0.5  0.5 0.5 0


High-Symmetry k-Point Path
~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, the paths used are those from Bradley and Cracknell [brad]_. To use the k-point paths provided
SeeK-path [seek]_ or pymatgen [curt]_. The options ``--seekpath`` or ``--pymatgen`` can be used.

``sumo-phonon-bandplot`` also supports generating k-points along custom k-point paths.
This is controlled using the ``--kpoints`` option. The custom k-point path is specified
as a string with commas separating the k-points.
For example, to plot the band structure along ``0. 0. 0. -> 0.5 0.5 0.5``, the usage is::

    sumo-phonon-bandplot --kpoints "0 0 0, 0.5 0.5 0.5"

Breaks in the band structure can be indicated using the pipe character.
For example, the path ``0. 0. 0. -> 0.5 0.5 0.5 | 0. 0. 0. -> 0.5 0. 0.``, is specified as::

    sumo-phonon-bandplot --kpoints "0 0 0, 0.5 0.5 0.5 | 0 0 0, 0.5 0 0"

Custom labels can also be provided using the ``--labels`` option. The syntax is the same as for the
``--kpoints`` option. For example, the labels for the above path are written as::

    sumo-phonon-bandplot --kpoints "0 0 0, 0.5 0.5 0.5 | 0 0 0, 0.5 0 0" \
                          --labels "\Gamma, M | \Gamma, X"

Note: in all cases the arguments are surrounded in parentheses.


Command-Line Interface
----------------------

.. argparse::
   :module: sumo.cli.phonon_bandplot
   :func: _get_parser
   :prog: sumo-phonon-bandplot
