# A Virtual Machine (based on Quantum Mobile) to automatically compute Wannier functions

We provide here a Virtual Machine Appliance (i.e., an importable Virtual 
Machine) to be run with the VirtualBox software.

The Virtual Machine contains a fully working installation of AiiDA, 
Quantum Espresso, Wannier90, and the workflows to compute automatically 
Wannier functions using the SCDM method.

## How to use the VM

### Download and start the Virtual Machine
- Download/get the virtual machine image ('.ova' extension)
- Install Virtual Box 6.0.0 or later from www.virtualbox.org
- Import virtual machine image into Virtualbox (this will require about 
  10GB of disk space), using File => Import Appliance 
  inside the Virtualbox software.
  (Note: when the virtual machine starts, if needed, you can use the following
  credentials -> username: max, password: moritz)
- Configure the hardware settings of your virtual machine:
  - select the imported VM in VirtualBox
  - press on the 'settings' button
  - choose the 'System' tab
  - under 'Motherboard' give at leat 10GB of RAM (if you have them in your 
    machine). Less RAM, beside making the machine quite slow, might not be 
    enough for the quantum simulations to run
  - under 'Processor' give 2 CPUs (or 3 for a bit better usability)
- NOTE: very often the user interface becomes *very* slow after a few minutes of
  usage (the terminal works fine, but dragging windows can start to take tens of
  seconds). You can follow the next step, that seems to provide a good workaround
  solving the issue:
  - under the 'Display' tab, change the Graphics Controller value to "VMSVGA"
- in any case, make sure that 3D acceleration is active in the "Display" tab
- Start the VM

### Run your simulation
- Open a terminal (click on the 'Terminal' icon on the left bar, represented 
  by a black screen with a '>_' symbol inside)
- Type

     workon AiiDA
     
  to enter the "virtual environment" where AiiDA is installed
- In the home folder, run the following script:
    
    ./run_automated_wannier.py xsf/CaO.xsf -n 0.4

- Notes: The above script will run the AiiDA workflows (using Quantum ESPRESSO
  and Wannier90, with the SCDM method) for the CaO material, using a coarser 
  mesh with a density of 0.4 angstrom^-1 than the default (to speed up a bit 
  the simulation, as you will be running with 2 CPUs on your workstation, and 
  not on a supercomputer!). 

  Note that in the 'xsf' subfolder you can also find all other materials 
  used in [1].

- You can also run
     ./run_automated_wannier.py -h
  to inspect other possible variables to change the behavior of the script
  (e.g. to choose a different density of k-points).


## Check the results
- When you run the `run_automated_wannier.py` script above, in output
  you will get a long explanation of how to inspect the output of the workflow
  (that, depending on the performance of your computer, will take some time
  to run, at least a few minutes).
  Follow the instructions to get, export and/or visualize the resulting 
  interpolated bands using maximally-localised Wannier functions (MLWFs).

## Compare with DFT bands
- If you want to compare the interpolated band structure with the bands 
  obtained directly from DFT (Quantum ESPRESSO), you can compute them using 
  the script
    ~/run_DFT_bands.py PK
  where PK is the PK obtained in output from the Wannier90 workflow (note
  that the Wannier90 workflow needs to have completed before you can run this 
  script).

  The information on how to run the DFT bands is also reported in the output 
  of the Wannier90 workflow

- Further information on how to then export the DFT bands, and compare them 
  with the Wannier-interpolated bands obtained automatically thanks to the 
  protocol described in [1], will be printed on output.


## Acknowledgments
The virtual machine has been generated by modified versions of the MaX/MARVEL 
"Quantum Mobile" Virtual machine, whose original version can be found here:
https://www.materialscloud.org/work/quantum-mobile

This version is adapted to contain only the codes relevant to this project, and
to adapt to the exact code versions used in the work [1].

For maximal reproducibility, we also attach the ansible roles that allow to 
rebuild from scratch the Virtual Machine, using the Ansible and Vagrant 
softwares.

This Virtual Machine reproduces the work of the following paper [1].
Please cite this work if you use the automated workflows presented here.

[1] Valerio Vitale, Giovanni Pizzi, Antimo Marrazzo, Jonathan R. Yates, 
    Nicola Marzari, Arash A. Mostofi, Automated high-throughput 
    Wannierisation, to be submitted (2019)