Decaf Espresso

Introduction

Decaf espresso is light-weight ASE wrapper for Quantum Espresso with convenient features inspired by 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: QE Inputs.
• Automatic validation of (some) parameters inspired by 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 installation

decaf-espresso is most easily installed with pip using:

pip install decaf-espresso

For Mac OSX, homebrew can be used in place of pip

brew install decaf-espresso

For usage on high-performance computers, installation will need to be performed locally which can be done using:

pip install --user decaf-espresso

These commands will install all of the necessary dependencies for you.

Source installation

Alternatively, a version with the most recent commits can be installed through git by running the following in your home directory.

git clone https://github.com/jboes/decaf-espresso.git 

Then, add ~/decaf-espresso to your PYTHONPATH by adding the following line to your ~/.bashrc file.

export PYTHONPATH=~/decaf-espresso:$PYTHONPATH

Once cloned, the requirements and be installed by running the following commands (Add the --user argument if needed):

cd ~/decaf-espresso
pip install -r requirements.txt

Parameter Validation

Parameter 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 Qunatum Espresso Input with a similarly named function in the 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:

from espresso import Espresso

calc = Espresso(kpts=(1, 1, 1))

Will execute the similarly named validation function:

def 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':
        return
    assert isinstance(val, (tuple, list, np.ndarray))
    assert len(val) == 3

If an invalid input is used, and exception will be raised.

from espresso import Espresso

calc = Espresso(kpts=(1, 1))

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
AssertionError

TODO: Make a more helpful validation error.

Writing a validation function

Each validation function follows the simple formula:

def parameter_name(calc, val):
    """Helpful docstring."""
    assert # An appropraite test here

    return updated_val  # optional

Where 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 scripts

Usage of the calculator are shown below for varying structure types.

Additional exampled coming soon.

Molecule relaxation

The example below will relax an H₂ 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.

from decaf import Espresso
from ase.build import molecule

parameters = {
    '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()

Bulk relaxation

The next example demonstrates some basic keywords for relaxing a bulk fcc Al unit cell.

• calculationc: As above, this keyword indicates the type of calculation to perform. Here we want variable cell relaxation to ensure we find the correct local minimum of the unit cell.
• press_conv_thr: The convergence criteria related to the maximum allowed pressure (or stress) on the cell in Kbar. Only useful for bulk with variable cell relaxation.
• kspacing: A convenient single parameter term for creating a Monkhorst-Pack k-point mesh based on reciprocal lattice vectors. It allows for consistency in k-point convergence for unit cells of various sizes.

from decaf import Espresso
from ase.build import bulk

parameters = {
    'calculation': 'vc-relax',
    'input_dft': 'PBE',
    'ecutwfc': 500,
    'kspacing': 0.04,
    'press_conv_thr': 0.5,
}

atoms = bulk('Al')

calc = Espresso(atoms, **parameters)
atoms.get_potential_energy()

Additional documentation

Some additional features are further detailed in the docs folder. These are specific to project requests from members of the SUNCAT group.

Ocean Wrapper