JDFTx contains a python interface class to the Atomic Simulation Environment. This provides a quick but powerful interface to many features, including phonons and ab-initio molecular dynamics alternative to the now built-in versions, or to barrier calculations using the nudged-elastic band method.

The current implementation of the interface is as a force calculator, which only exchanges forces and potential energies with ASE.

Installation

The interface is available with the JDFTx source code, under the scripts directory (/jdftx/scripts/ase). After installing JDFTx and ASE (follow instructions for each), set the python path to access the interface file. For example, in unix-based systems, add

   export PYTHONPATH=/path-to-jdftx/scripts/ase:$PYTHONPATH

to ~/.bashrc or ~/.profile files. Once this is done, you can import the JDFTx calculator in python using:

   from JDFTx import JDFTx

Use

The JDFTx interface needs to know the path to the executable and to pseudopotentials (if not using a built-in pseudopotential set). This can be done using arguments executable and pseudoDir in the constructor, or by setting environment variables JDFTx and JDFTx_pseudo respectively.

The easiest way to use the interface is to set the environment variables

export JDFTx=/path/to/jdftx
export JDFTx_pseudo=/path/to/pseudopotential/directory

in the current shell, or in the ~/.bashrc or ~/.profile files. Using the constructor, these would be instead:

calculator = JDFTx(
    executable='/path/to/jdftx',
    pseudoDir='/path/to/pseudopotential/directory'
)

The latter variable / argument is only needed if not using a built-in set like GBRV or SG15. If using one of these pseudopotential sets, it is sufficient to only specify the executable and name the set eg. using

calculator = JDFTx(
    executable='/path/to/jdftx',
    pseudoSet='GBRV-pbe'
)

where the supported sets are GBRV (shorthand for GBRV-pbe), GBRV-lda, GBRV-pbesol and SG15.

Finally, to use MPI or a job management system like SLURM, use:

calculator = JDFTx(executable='mpirun -n Nprocs /path/to/jdftx')

or

calculator = JDFTx(executable='srun -n Nprocs /path/to/jdftx')

Note that the command that submits the job eg. srun should not release the shell until the job is completed. Therefore, in slurm, srun would work, but not sbatch.

Example

Below is a sample python script that uses jdftx through the ASE interface to calculate the bond length of CO molecule using the BFGS minimization algorithm. Note that you must edit the executable path in the code below (or remove that argument and set the environment variable JDFTx).

from ase import Atoms
from JDFTx import JDFTx

d = 1.1 #Initial bond length guess
CO = Atoms('CO', 
    positions=[(0, 0, 0), (0, 0, d)],
    cell=[(6,0,0),(0,6,0),(0,0,7)],
    pbc = [False, False, False])

#Set up JDFTx calculator
calculator = JDFTx(
    pseudoSet='GBRV',
    commands={'elec-cutoff' : '20 100'}
)
CO.set_calculator(calculator)

#Structure optimization
from ase.optimize import BFGS
dyn = BFGS(CO)
dyn.run(fmax=0.05)

calculator.clean()  #Clean up run files from /tmp

Output from this script will look something like:

Set up JDFTx calculator with run files in '/tmp/tmpXXXXXXXX'
  Step     Time          Energy         fmax
BFGS:    0 16:54:05     -591.653710        5.8379
BFGS:    1 16:54:13     -591.689501        3.9552
BFGS:    2 16:54:20     -591.766731        0.7019
BFGS:    3 16:54:26     -591.768793        0.1145
BFGS:    4 16:54:30     -591.768846        0.0040

See the ASE tutorials for many examples illustrating ASE's features; it is then straightforward to instead use the JDFTx calculator in any of those examples.

Extracting outputs

Any feature of JDFTx, such as solvation, can be used simply by passing an appropriate dict of JDFTx input file commands, as shown in the example for elec-cutoff. However, dump-name and initial-state will be overridden to work in a temporary path.

If you need to access the dumped files - you can add dumped variables using the dump command as usual, then copy them out from calculator.runDir before calling calculator.clean(). For example, this modified version of the above script outputs the electron density and visualizes it using the createXSF script and VESTA (add them to path or set absolute paths). It also uses the SG15 pseudopotentials set instead of GBRV for illustration:

from ase import Atoms
from JDFTx import JDFTx, shell

d = 1.1 #Initial bond length guess
CO = Atoms('CO', 
    positions=[(0, 0, 0), (0, 0, d)],
    cell=[(6,0,0),(0,6,0),(0,0,7)],
    pbc = [False, False, False])

#Set up JDFTx calculator
calculator = JDFTx(
    pseudoSet='SG15',
    commands={
        'elec-cutoff' : '30',
        'dump' : 'End ElecDensity'
    }
)
CO.set_calculator(calculator)

#Structure optimization
from ase.optimize import BFGS
dyn = BFGS(CO)
dyn.run(fmax=0.05)

#Create XSF and visualize:
shell('createXSF %s/out CO.xsf %s/n' % ((calculator.runDir,)*2))
shell('VESTA CO.xsf &')
calculator.clean()         #Clean up run files from /tmp