Package: decaf-espresso
#+Title: Decaf Espresso#+Author: Jacob Boes#+OPTIONS: toc:nil#+LATEX_HEADER: \setlength{\parindent}{0em}* IntroductionDecaf espresso is light-weight [[https://wiki.fysik.dtu.dk/ase/][ASE]] wrapper for Quantum Espresso with convenient features inspired by [[https://github.com/vossjo/ase-espresso][ase-espresso]]. The goal is to produce a simplified version which allows for most of the non-interactive functionality without so much of the verbosity of ase-espresso. The code is meant to be short and segmented into logical portions to help those who are new to Quantum Espresso learn more easily. The majority of the simplification comes from farming out the =io= functionality to ASE, which also amounts to less code to maintain.*Pros:*- Input units are eV (similar to ase-espresso) and converted automatically.- All input keywords are identical to Quantum Espresso to prevent confusion. See: [[https://www.quantum-espresso.org/Doc/INPUT_PW.html][QE Inputs]].- Automatic validation of (some) parameters inspired by [[https://github.com/jkitchin/vasp][Vaspy]].- Straight forward record of default parameters used for simplified documentation.- Automatic handling of calculation node scratch assignment for general clusters (SLURM, LSF, PBS/TORQUE), to prevent unnecessary disk-io.- Automatic handling of MPI execution of general clusters (SLURM, LSF, PBS/TORQUE) and intelligent assignment of k-point parallelization (npool).- Specific executable setups for compatibility on SLAC, Sherlock, and NERSC clusters. (works out of the box)- Has post-processing functions which are not yet available in ASE.- Written in Python 3- DRY code with extensive documentation.*Cons:*- Not all post processing features available from ase-espresso have been implemented.- No support for interactive ASE without efficiency loss- Not all parameters are currently validated or tested (such as DFT+U parameters).- Limited testing in Python 2 and will not be supported moving forward.* Installation** Pip installationdecaf-espresso is most easily installed with pip using:#+BEGIN_SRC shpip install decaf-espresso#+END_SRCFor Mac OSX, homebrew can be used in place of pip#+BEGIN_SRC shbrew install decaf-espresso#+END_SRCFor usage on high-performance computers, installation will need to be performed locally which can be done using:#+BEGIN_SRC shpip install --user decaf-espresso#+END_SRCThese commands will install all of the necessary dependencies for you.** Source installationAlternatively, a version with the most recent commits can be installed through git by running the following in your home directory.#+BEGIN_SRC shgit clone https://github.com/jboes/decaf-espresso.git#+END_SRCThen, add =~/decaf-espresso= to your =PYTHONPATH= by adding the following line to your =~/.bashrc= file.#+BEGIN_SRC shexport PYTHONPATH=~/decaf-espresso:$PYTHONPATH#+END_SRCOnce cloned, the requirements and be installed by running the following commands (Add the =--user= argument if needed):#+BEGIN_SRC shcd ~/decaf-espressopip install -r requirements.txt#+END_SRC* Parameter ValidationParameter validation is currently performed for the arguments which I use most frequently for my calculations, but the general formula for validation is easily extensible by anyone. The basic idea is that any [[https://www.quantum-espresso.org/Doc/INPUT_PW.html][Qunatum Espresso Input]] with a similarly named function in the [[./espresso/validate.py][validation module]] will have the entailed function executed if the parameter is input by the user.For example, If I were to initialize a calculation as:#+BEGIN_SRC python :results output org drawerfrom espresso import Espressocalc = Espresso(kpts=(1, 1, 1))#+END_SRCWill execute the similarly named validation function:#+BEGIN_SRC python :results output org drawerdef kpts(calc, val):"""Test k-points to be 'gamma' or list_like of 3 values.Only automatic assignment is currently supported.https://www.quantum-espresso.org/Doc/INPUT_PW.html#idm45922794051696"""if val == 'gamma':returnassert isinstance(val, (tuple, list, np.ndarray))assert len(val) == 3#+END_SRCIf an invalid input is used, and exception will be raised.#+BEGIN_SRC python :exports bothfrom espresso import Espressocalc = Espresso(kpts=(1, 1))#+END_SRC#+RESULTS:: Traceback (most recent call last)::   File "Org SRC", line 3, in <module>:     calc = Espresso(kpts=(1, 1)):   File "/home/jboes/research/decaf-espresso/espresso/espresso.py", line 62, in __init__:     new_val = f(self, val):   File "/home/jboes/research/decaf-espresso/espresso/validate.py", line 226, in kpts:     assert len(val) == 3: AssertionErrorTODO: Make a more helpful validation error.** Writing a validation functionEach validation function follows the simple formula:#+BEGIN_SRC python :results output org drawerdef parameter_name(calc, val):"""Helpful docstring."""assert # An appropraite test herereturn updated_val  # optional#+END_SRCWhere =parameter_name= is the exact name of the Quantum espresso parameter, and =(calc, val)= are always passed as arguments. Here, =calc= is the =Espresso= calculator object, which can be used to all other calculator parameters and =val= is the user defined value for the given parameter which can be directly tested against.In decaf-espresso, validation functions also server the double role of updating certain values. For Example, Quantum Espresso takes units of energy in Rydbergs, but eV are more commonly used in surface science. So, any validation function which takes Rydbergs will also return and =updated_val= which is the value converted to Rydbergs from eV so the user can specify inputs in eV. This sacrifices some readability, but avoids looping over extra lists of known value types, helping keep the code DRY.* Example scriptsUsage of the calculator are shown below for varying structure types.Additional exampled coming soon.** Molecule relaxationThe example below will relax an H_{2} molecule using some standard flags. Below is the rational for some of the flags used.- =ecutwfc=: A required argument, represents the energy cutoff for the wave functions.- =conv_thr=: The threshold for considering a total energy converged. DFT is only accurate to about 0.1 eV at best, so 1e-4 should be sufficient for most use cases.- =degauss=: Gaussian smearing coefficient. This is a non-physical contribution meant only to help atomic structures with d-bands converge correctly. For molecules we set it to be small.#+BEGIN_SRC python :results output org drawerfrom espresso import Espressofrom ase.build import moleculeparameters = {'calculation': 'relax','input_dft': 'PBE','ecutwfc': 500,'conv_thr': 1e-4,'degauss': 0.01}atoms = molecule('H2', vacuum=6)calc = Espresso(atoms, **parameters)atoms.get_potential_energy()#+END_SRC