Metadata-Version: 2.1
Name: ifermi
Version: 0.1.4
Summary: Fermi surface plotting tool from DFT output
Home-page: https://github.com/asearle13/IFermi
Author: Amy Searle
Author-email: amyjadesearle@gmail.com
License: MIT
Keywords: fermi-surface pymatgen dft vasp band materials-science
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
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
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Other/Nonlisted Topic
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: colorlover
Requires-Dist: matplotlib
Requires-Dist: pymatgen (>=2017.12.30)
Requires-Dist: BoltzTraP2
Requires-Dist: trimesh
Requires-Dist: meshcut
Requires-Dist: scikit-image
Requires-Dist: monty
Requires-Dist: spglib
Requires-Dist: plotly
Requires-Dist: pyfftw
Requires-Dist: psutil
Requires-Dist: dataclasses (>=0.6) ; python_version < "3.7"
Provides-Extra: crystal-toolkit
Requires-Dist: crystal-toolkit ; extra == 'crystal-toolkit'
Provides-Extra: decimation
Requires-Dist: open3d ; extra == 'decimation'
Provides-Extra: dev
Requires-Dist: black ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx (==3.2.1) ; extra == 'docs'
Requires-Dist: sphinx-argparse (==0.2.5) ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme (==0.5.0) ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints (==1.11.1) ; extra == 'docs'
Requires-Dist: m2r2 (==0.2.5) ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: nbsphinx-link ; extra == 'docs'
Requires-Dist: ipython ; extra == 'docs'
Provides-Extra: mayavi
Requires-Dist: mayavi ; extra == 'mayavi'
Requires-Dist: mlabtex ; extra == 'mayavi'
Requires-Dist: vtk ; extra == 'mayavi'
Provides-Extra: smooth
Requires-Dist: PyMCubes ; extra == 'smooth'
Provides-Extra: tests
Requires-Dist: nose ; extra == 'tests'
Requires-Dist: coverage ; extra == 'tests'
Requires-Dist: coveralls ; extra == 'tests'

<p align="center">
  <img alt="IFermi logo" src="https://raw.githubusercontent.com/ajsearle97/IFermi/master/docs/src/_static/logo-01.png" height="190px">
</p>

<p align="center">
    📖📖 <a href="https://ajsearle97.github.io/IFermi">Online Documentation</a> 📖📖
</p>

IFermi is a package for plotting Fermi surfaces and from *ab initio* calculation outputs. 
The main features include:

1. Plotting three-dimensional Fermi surfaces, with interactive plotting
   supported by [mayavi](https://docs.enthought.com/mayavi/mayavi/), [plotly](https://plot.ly/) and [matplotlib](https://matplotlib.org).
2. Plotting slices of three-dimensional Fermi surfaces along a specified plane.

IFermi currently only supports VASP calculations but support for additional DFT packages 
will be added in the future.

## Example

An example of the Fermi surface and a two-dimensional slice for MgB<sub>2</sub> is shown below:

![MgB2](https://raw.githubusercontent.com/ajsearle97/IFermi/master/docs/src/_static/fermi_surface_example-01.png)


## Usage

The [online documentation](https://ajsearle97.github.io/IFermi/cli.html) provides a full 
description of the available options. To summarise, three-dimensional Fermi surfaces can
be plotted from a `vasprun.xml` file using:

```bash
ifermi
```

The two-dimensional slice of a Fermi slices along the plane specified by the miller 
indices (A B C) and distance d can be plotted from a `vasprun.xml` file using:

```bash
ifermi --slice A B C d
```

### Python interface

Alternatively, IFermi can be controlled using the Python API. A full summary of the API
is given in the [API introduction page](https://ajsearle97.github.io/IFermi/plotting_using_python.html) in the documentation.

The core classes in IFermi are:

- `Inerpolator`: to take a band structure on a uniform k-point mesh and interpolate it
  onto a denser mesh.
- `FermiSurface`: to store isosurfaces and reciprocal lattice information.
- `FermiSurfacePlotter`: to plot a Fermi surface from a `FermiSurface` object.

A minimal working example to plot the Fermi surface from a `vasprun.xml` file is:

```python
from pymatgen.io.vasp.outputs import Vasprun
from ifermi.fermi_surface import FermiSurface
from ifermi.interpolator import Interpolator
from ifermi.plotter import FermiSurfacePlotter, show_plot, save_plot


vr = Vasprun("vasprun.xml")
bs = vr.get_band_structure()

# interpolate the energies to a finer k-point mesh
interpolator = Interpolator(bs)
dense_bs, kmesh = interpolator.interpolate_bands(interpolation_factor=10)

fs = FermiSurface.from_band_structure(dense_bs, kmesh, mu=0.0, wigner_seitz=True)
plotter = FermiSurfacePlotter(fs)
plot = plotter.get_plot(plot_type='plotly')

save_plot(plot, "fermi-surface.png")  # saves the plot to a file
show_plot(plot)  # displays an interactive plot
```

Note, if you're not running the example in a notebook then it must be proceeded by `if __name__ == '__main__':`.

## Installation

IFermi can be installed with the command:

```bash
pip install ifermi
```

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

- [pymatgen](http://pymatgen.org) for parsing VASP calculation output.
- [BoltzTrap2](https://gitlab.com/sousaw/BoltzTraP2) for band structure interpolation.
- [matplotlib](https://matplotlib.org), [mayavi](https://docs.enthought.com/mayavi/mayavi/), and [plotly](https://plot.ly/) for three-dimensional plotting.

## What’s new?

Track changes to IFermi through the
[changelog](https://ajsearle97.github.io/IFermi/changelog.html).

## Contributing

We greatly appreciate any contributions in the form of Pull Request.
We maintain a list of all contributors [here](https://ajsearle97.github.io/IFermi/contributors.html).

## License

IFermi is made available under the MIT License.

## Acknowledgements

Alex Ganose for developing/improving code and documentation.
Sinead Griffin for suggesting the project.


