BandUP: Band Unfolding code for Plane-wave based calculations

Copyright (C) 2013-2017 Paulo V. C. Medeiros - pvm20@cam.ac.uk

Please visit http://www.ifm.liu.se/theomod/compphys/band-unfolding

BandUP is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

BandUP is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with BandUP. If not, see http://www.gnu.org/licenses/.

Currently supported plane-wave codes

At the moment, BandUP can parse wavefunctions generated by:

• VASP
• Quantum ESPRESSO
• ABINIT
• CASTEP (tested with the academic version; currently only available on request)

If you would like support to other plane-wave (PW) code(s) to be added to BandUP, then:

• Please send me a subroutine that reads the wavefunctions produced by your PW code. Take a look at the routines we have already implemented for the supported PW codes to have an idea of how your subroutine's interface should look like. I am more than happy to assist you with this.
• If you don't know how to write such a subroutine, then, of course, I'll do my best to help you out anyway, so please contact me. Due to limitations in time and resources, however, I unfortunately cannot guarantee to be able to do this as quickly as you (and I, for that matter) would wish.

How to compile BandUP

Run the build script:

               ./build 

A symlink named bandup will be created, in the same directory, if compilation is successful. This is a single executable that wraps all BandUP main functionalities:

• Getting SC-Kpoints pre-unfolding (task kpts-sc-get)
• Actual unfolding code (task unfold)
• Plotting (task plot)
• Atom/orbital-decomposed unfolded band structure (task projected-unfold, currently only available for VASP)

If installation doesn't go well, please double-check the system requirements (below) and make sure they have all been fulfilled. If you still cannot install BandUP after having done this, then please contact us. But I insist: Check the system requirements first. Most installation problems reported to us are caused by failure to do so!

For more information (usage, choosing compilers, etc.), please run:

               ./build -h

How to use BandUP

The easiest way to understand how BandUP works is by going through the examples under the tutorial directory.

If you keep the directory structure used in the examples, BandUP will look for input/output files in the appropriate directories (step_1*, step_2*, etc.). Otherwise, you'll need to copy/link them manually to wherever you intend to run BandUP, or, alternatively, you'll need to use the task-specific options to inform BandUP about the location of these files (see below).

The general syntax for bandup is (since v3.0.0):

               bandup <task> <task_options>

For help about available tasks and general usage, please run:

               bandup -h 

For help about a particular task, please run:

               bandup <task> -h 

If what you wish BandUP to do is not covered in the tutorials, and information about it is not available through the use of the -h options discussed above, then please contact us.

System requirements:

• Unix environment
  • Preferably Linux
• Fortran 95 and C compilers
  • Preferably Intel compilers (ifort and icc), v>=15.0.3
  • Should work with GNU compilers (gfortran and gcc) v>=5.2
• Python 2.X (X>=7) (NB: Mandatory since BandUP V3.0.0)

  • Mandatory non-standard Python packages (maybe you already have them; only worry about this if the code fails):

    • numpy
    • scipy
    • matplotlib
    • six

  • Optional: Either PyQt4 or PyQt5

    • This is only needed if you wish to use the GUI version of the plotting tool.
    • If the GUI doesn't work with you, you can keep using the plotting tool through the command line, just as usual. I'd appreciate, anyway, it if you'd let me know should this happen -- even though I can't promise to provide quick assistance with GUI-related issues, as everything can be done without it.

  • If you don't have any of the packages listed above, you can easily install them using, e.g., pip. For instance,

              pip install --upgrade --user matplotlib
    

    should make matplotlib available in your Python install.

  • Standard python library modules used (just for reference; this list might even be incomplete):

    • argparse
    • os
    • sys
    • time
    • subprocess
    • fractions
    • json
    • shutil
    • collections
    • glob
    • pickle
    • errno
    • itertools
    • warnings

  • Please let me know if I've forgotten to list any other non-standard python package!

Publications:

If you use BandUP (or any part or modified version of it) in your work, you should:

• State EXPLICITLY that you've used the BandUP code (or a modified version of it, if this is the case).
• Read and cite the following papers (and the appropriate references therein):

Paulo V. C. Medeiros, Sven Stafström, and Jonas Björk, Phys. Rev. B 89, 041407(R) (2014)
Paulo V. C. Medeiros, Stepan S. Tsirkin, Sven Stafström, and Jonas Björk, Phys. Rev. B 91, 041116(R) (2015)

An appropriate way of acknowledging the use of BandUP in your publications would be, for instance, adding a sentence like:

     "The unfolding has been performed using the BandUP code"

followed by the citation to our papers.

A constantly growing list of publications using BandUP is available at http://www.ifm.liu.se/theomod/compphys/band-unfolding/publications

IMPORTANT: Major changes in V3.0.0:

As of May 2017, you should use the executable bandup for all BandUP tasks. This is a Python script that provides an interface to the fortran binaries that needed to be executed directly in previous versions.

The new bandup script also provides a plot task which reimplements the previously available plotting tool and its GUI -- both of which no longer exist as individual scripts since v3.0.0.

The individual fortran executables maintain back-compatibility, and can be found under the src dir if compilation succeeds. The older (v<3) bash scripts provided in the tutorials, however, will certainly not work with the new executable bandup.

The tutorials have been updated, and new bash scripts have been provided. These are much simpler than their previous counterparts. If you were using the now deprecated scripts in your actual calculations (which you didn't need to), please replace them by the new ones to be able to use BandUP V3.

Note, nonetheless, that you still don't really need any bash script to run BandUP. The ones provided in the tutorials serve primarily as practical tools to illustrate how BandUP can be executed from the command line.

Tips (some of which already mentioned above):

• BandUP accepts some optional arguments and flags. To find out more about them, please use the -h options!

  • For help about the available tasks and general usage, run:

              "bandup -h" 
    

  • For help about a specific task, run:

              bandup <task> -h
    

• Since BandUP's plotting task has a lot of different options, I've given it a GUI. You can launch it by using the option --gui when launching BandUP with the task plot.

  • This requires that either PyQt4 or PyQt5 is available in your python install. If the GUI doesn't work for you, however, you can still make the plots using the command line

• It might be handy placing a symlink to the bandup executable in some directory belonging to your PATH. Alternatively (but less desirably), you can include the current directory in your PATH if you prefer to do so. In either case, you'll then be able to use BandUP, in any directory you may be working at, by simply using the command bandup.

Contributing to BandUP

If you wish to contribute with BandUP by doing some coding, you are more than welcome. Please read the CONTRIBUTING.md file for further instructions.

Please mind that:

Although we have very limited time and resources, we do our best to provide good user support. You can help us to continue to do so by making sure to do the following before writing to us for assistance:

• Certify that all system requirements are met
• Certify that you are using the latest version of BandUP
• Make use of the help (-h) options. Most of the times, what you need is already explained there!

I've tried to make compilation as simple as possible - and it has indeed worked fine with many combinations of compilers, OSs and computers. I cannot, however, guarantee that it will always work smoothly. Please contact us if you have problems with this.

In the calculations and tests I've performed with BandUP so far, I've mostly used Intel compilers (v. 15.0.3) and, a few times, also GNU compilers (v. 5.2). I believe you should have no problem using other versions of ifort/icc, as well as more recent versions of gfortran/gcc. Mind, however, that I cannot guarantee that this will always be the case. It is better to make sure you use the supported compilers (the GNUs are free).

Last, but not least: Always check the results with a critical eye, specially if they don't look the way you think they are supposed to. Please notify me if weird stuff happens and you think it's the code's fault (but do double-check first)!

Have fun!