DFTtoolbox 1.6
A toolbox to initialize or postpocess several DFT codes
License: MIT
Keywords: density-functional-theory,qantum-espresso,elk,abinit

# DFTtoolbox
DFTtoolbox is a Python module that aims to help computational condensed 
matter physicist or material scientists who use density functional 
theory (DFT) codes , such as quantum espresso, abinit, elk, etc., as a 
tool to study material properties quickly build their calculations and 
analyze the calculated results.

Most DFT codes usually come with massive variables. Users are required 
to be familar with all the variable not only in the building stage but 
also the postprocess stage. Therefore, the philosophy of DFTtoolbox is 
"the less user input the better!". Users only need to feed very few
variables to DFTtoolbox to build a DFT input file or to analyze the 
calculated results. No painc learning curves for DFT codes 
anymore!

# Prerequisite
DFTtoolbox is a Python module which helps DFT code users quickly build an 
input file in seconds and analyze+visuallize the output data immediately. 

Currently, DFTtoolbox can support three popular DFT codes:
- Quantum Espresso (tested in v6.1) http://www.quantum-espresso.org/
- Abinit (tested in v8.4.2) http://www.abinit.org/
- Elk (tested in v4.3.6) http://elk.sourceforge.net/

DFTtoolbox is based on numpy and matplotlib. Before installing DFTtoolbox,
please make sure you have these package installed. Also, DFTtoolbox can 
only read the crystal structure and band high-symmytry 
path in xcrysden format (.xsf and .kpf). If you're not familar with 
xcrysden, check their websit (http://www.xcrysden.org/). It is very
easy to learn. Then you are all set ! 

# How does DFTtoolbox build a DFT task ?
Before building a input file using DFTtoolbox, the user has to prepare
the structure file and the k-path file in xcrysden format (.xsf and .kpf.)
Then DFTtoolbox can:
- initialize a ground state calculation
  The user only need to feed very few parameters, DFTtoolbox will automatically
  generate the input files to perform four basic ground state calculation:
  -- self-consistent field calculation
  -- band structure calculation
  -- projected band structure calculation (i.e. fatband)
  -- partial density of state calculation
  
- initialize a structural relaxation calculation 
  DFTtoolbox can automatically generate an input file for structural relaxation
  by requesting "zero" input! DFTtoolbox will pick the values that fit for most
  calculations for you. 
  
Note: 
Because DFTtoolbox is designed based on the philosophy "the less user inputs
the better". I don't want you to learn another complicated code to deal with
the already-very-complicated DFT codes. So the input files are only for general 
purposes and will not fit all kinds of ground state or structural relaxation 
calculations. However even if the generated input files don't completely satisify
your need, it is always a good starting point for you to tweak your own input files. 
  
# How does DFTtoolbox help analyze the results?
One of the painc part of DFT users is the output files are usually very complicated
and are lack of appropriate tools to visuallize the results beaufitully and 
easily. DFTtoolbox can automatically read the output data of band calculation, 
projected band calculation and PDOS calculations, save them in numpy array format
(.npz files) and plot the results with publishable qualities. A convenient feature
of DFTtoolbox is that it can combine arbitary states to plot projected band
structures and PDOS making it a useful tool to band character analysis. 
In addition, if you want to use your own tools to plot the results, 
the output .npz file can also let you load the data in numpy standard format
immediately, so you can postprocess your data in Python framework easily.

# Is there a quick tutorial?
Yes, check (/examples/). There is a simple example FeO. I believe 
anyone can learn how to use it in a few minutes. You will find it only needs 
very few necesary input variabless to initialize or postprocess a DFT calculation.  
Also, in /template/ there are template files for your to use.

# Installation
- from the tarball:
Just download the tarball. Unzip it and put it anywhere you want. Go to the 
folder, type:

python setup.py install

- from PyPI:

pip install DFTtoolbox

# Figures Demo
Here are examples of the figure generated by DFTtoolbox. These figure were
obtained from ferromagnetic FeO. This example has been included in the module.
- Fig.1 band stucture (green and blue are different spin)
![band](https://github.com/pipidog/DFTtoolbox/raw/master/examples/abinit/lsda/band-DS2.png)
- Fig.2 band structure projected on Fe d-orbital
![Fatband](https://github.com/pipidog/DFTtoolbox/raw/master/examples/abinit/lsda/fatband-DS3-0.png)
- Fig.3 PDOS (data-1: Fe d-oribtal, data-2: O p-orbital)
![PDOS](https://github.com/pipidog/DFTtoolbox/raw/master/examples/abinit/lsda/pdos-DS4.png)