######################################################################
######################################################################
Copyright (C) 2013-2017 Paulo V. C. Medeiros - pvm20@cam.ac.uk
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:
* VASP
* Quantum ESPRESSO
* ABINIT
* CASTEP (tested with the academic version; currently only
available upon request)
* If you use another plane-wave (PW) code and would like to have
support to it added in BandUP:
* Please **send me a subroutine to read the wavefunctions
produced by your code**. Take a look at the routines we have
already implemented for the other 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 cannot unfortunately guarantee I'll be able to do
this as quickly as you (and I, for that matter) would wish
* Run the "build" script: ./build
* Please **run "./build -h" for more information** (usage,
choosing compilers, etc.)
* 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 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
* **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 on 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>
* Running **"bandup -h"** with will print help about the available
tasks and general usage
* Running **"bandup <task> -h"** will print specific help for the
requested task
If what you want is **not covered by the tutorials and information
about it is not available through the use of the "-h" options**
discussed above, then please contact us
* 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 (you might 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, however, 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 --user matplotlib"
should make matplotlib available in your Python install
* Standard python library modules used (just for reference;
the 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!
* 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):
>>> Phys. Rev. B 89, 041407(R) (2014)
<http://dx.doi.org/10.1103/PhysRevB.89.041407>
>>> Phys. Rev. B 91, 041116(R) (2015)
<http://dx.doi.org/10.1103/PhysRevB.91.041116>
* 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.
* 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 "get_SCKPTS_pre_BandUP.x" and
"BandUP.x" that needed to be executed directly in previous
versions. The new "bandup" executable also provides a "plot"
task which reimplements the previously available plotting tool
"plot_unfolded_EBS_BandUP.py" and its GUI -- both of which no
longer exist as individual scripts since v3.0.0.
* The individual fortran executables maintain back-compatibility,
but the older (v<3) bash scripts provided in the tutorials will
certainly not work with the executable "bandup" in BandUP v>=3.
The tutorials have been updated and provide new bash scripts
that are compatible with BandUP V3. These new scripts are much
simpler than their previous counterparts. If you were using the
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 scripts 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 '-h'!**
* Running **"bandup -h" with will print help about the
available tasks** and general usage
* Running **"bandup <task> -h" will print specific help for
the requested task**
* 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 that belongs to your PATH. Alternatively (but
less desirably), you can include the current directory in your
PATH is you prefer to do so. In either case, you'll then be able
to use BandUP in making directory you're working at.
* 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. You might eventually need to play a bit with the
scripts and, very rarely, with the Makefiles and source code.
* 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)!
The idea here (as of v3.0.0-beta.1) is to automate semantic
versioning -- fully for any development branch, and at least
partially for master. To this end, the following workflow must
be adopted (assumes you know Git):
(i) No modification in the code should be made in the master
branch. Use the "devel" branch instead, or create another
branch if appropriate. If working on an existing branch,
then, before doing anything, make sure to pull in any
eventual new changes from master (which should be up-to-
date with the remote master). Once you are happy with the
new/modified code and convinced that it has no obvious
bugs, then go to (ii).
(ii) Make sure again the code to be merged has been tested and
has no obvious bugs.
(iii) Before making the final commit to the branch, the value
attributed to the constant "tag_for_push" (in the file
"constants_and_types_mod.f90" under "src") must be
updated. This must be done in accordance with the semantic
versioning set of conventions (2.0).
See <http://semver.org>.
(iv) After making sure to comply with the items above, commit
any new changes (such as the one you did in (iii)).
(v) If you don't have permissions to push to master, then
push your branch, send me a notification, and stop here.
If you can push to master, then merge your branch into
master and continue. Use "--no-ff" unless you have only
one commit to merge
(vi) Before pushing the merge commit, it must be tagged.
Moreover: The created tag must be (a) identical to the
value attributed to "tag_for_push" in (iii), and (b)
an annotated tag.
See <https://git-scm.com/book/en/v2/Git-Basics-Tagging>.
I use a script for (v) and (vi). It retrieves the value of
"tag_for_push" from the file mentioned in (iii), merges
the changes made in the branch into master, and then
creates the appropriate annotated tag with a message I
choose.
(vii) Now, double-check everything. This is the last chance to
correct mistakes in a straightforward manner.
(viii) Finally, push to the remote repo.
By doing as described above, you will help me greatly and the
semi-automated semantic versioning scheme should work.
If you don't know Git, but have implemented something you think
would help improve BandUP and you'd like to share it with the
community, then please get in touch with me by email. But I
do recommend you learn Git if you are modifying BandUP source!