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/.
At the moment, BandUP can parse wavefunctions generated by:
If you would like support to other plane-wave (PW) code(s) to be added to BandUP, then:
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:
kpts-sc-get)unfold)plot)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 -hThe 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.
ifort and icc), v>=15.0.3gfortran and gcc) v>=5.2Python 2.X (X>=7) (NB: Mandatory since BandUP V3.0.0)
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 matplotlibshould make matplotlib available in your Python install.
Standard python library modules used (just for reference; this list might even be incomplete):
If you use BandUP (or any part or modified version of it) in your work, you should:
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
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.
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> -hSince 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.
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.
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.
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:
-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)!