Welcome to dfttk_example’s documentation!¶

Example¶

To get the example, run

git clone https://github.com/yiwang62/dfttk_example #if you have not download the example
cd dfttk_example

The example is designed to have the user to test the DFTTK package using Al. The input settings for the Al example are contained in the Al/ folder by two files

POSCAR - the regular VASP POSSCAR file

SETTINGS.yaml - the setting file for quasiharmonic phonon calculation

The following gives the steps to run the Al example

cd Al
dfttk run -wf robust -f POSCAR -l -m 1

This will submit the batch DFT job to the system. One can check the progress of the DFT calculations by lpad get_wflows. Only when all the values for the ‘states_list’ fields are shown as ‘C’ implies the DFT job done. Then One can go to next step by run

cd dfttk_example #go back the dfttk example folder
dfttk thfind -get -plot DFTTK -expt ExptData.json

The file ExptData.json under the dfttk_example folder contains some experimental thermodynamic data for a collection of materials to verify the DFTTK calculations. The above will produce more thatn 20 figures stored in the folder Al_Fm-3m_225PBE/figures and they can be viewed t by clicking them in Windows/IOS or using the linux command display to show the figure. For example for linux

display Al_Fm-3m_225PBE/figures/LTC.png #to see the linear thermal expansion coefficient

display Al_Fm-3m_225PBE/figures/Heat_capacities.png #to see the heat capaticity, and so on

The Al_Fm-3m_225PBE/ folder contains all calculated thermodynamic properties after post-processing the data stored in the MongoDB database for a finished DFT calculations, in particular

figures/ - plots in png format for most of the thermodynamic properities

readme - extensive summary of the calculated results in json format

fvib_ele - tablated data containing the calculated thermodynamic properties

fvib_eij - tablated data containing the calculated thermal expansion coefficient tensor

record.json - SGTE fitting record for heat capacity, Gibbs energy, enthalpy, and entropy at given temperature range

Installation¶

It is recommended to install DFTTK under the anaconda environment. Under the linux command prompt (or anaconda powershell prompt for Windows), one can create a preferred directory and then run #Note for Windows:

Open your anaconda powershell prompt and run as administrator.
Go to the location where you want to install DFTTK.

Release version

pip install dfttk

Development version

git clone https://github.com/PhasesResearchLab/dfttk.git
cd dfttk
pip install -e .

Alpha interanal daily test version

git clone https://github.com/yiwang62/dfttk.git
cd dfttk
pip install -e .

mkdir a folder named config whereever you want to followed by copy the file db.json, my_launchpad.yaml from your MongoDB manager into config/. See the section Config MongoDB

dfttk config -all --nodes 1 --ppn 16 --pmem 32gb -aci -M yourcomputer -mapi PMG_MAPI_KEY

where

For the system other than aci, “-aci” should be replace by “-psp vasp_psp/” where vasp_psp is a place holding your vasp pseudopotentials

yourcomputer is your computer name, such as aci-vasp5, aci-vasp6, cori-knl, cori-ksw, bridges2, stampede2

yourbactch can be pbs, slurm

PMG_MAPI_KEY can be obtained by: Go to the materials project website, https://materialsproject.org/, under the API section, you will easily find you API Keys number.

finally, you need to change the account number and queue/partition number in the config/my_qadapter.yaml file

Additional steps for installation in Windows

One need to add two environmental variables by right click Windows symbol located in the lower left corner -> system -> (scrolling down to) Advanced system settings -> Environmental variales -> “New..” button

HOME - create a Windows environmental variale named ‘HOME’, something similiar to “C:Usersxxxxx” where xxxxx is your login in user name

FW_CONFIG_FILE - create a Windows environmental variale named ‘FW_CONFIG_FILE’ pointed to the ‘config’ folder

Config MongoDB¶

DFTTK needs MongoDB to manage DFT calculations and outputs. The users of DFTTK can either buy the commercial MongoDB database service or set up their own MongoDB server.

Ask the MongoDB system manager for two json files: one named db.json and another named my_launchpad.yaml and save them in a config folder wherever you choose.

db.json used by FireWorks through MongoDB to access the DFTTK output results, templated as follows.

{
    "database": "userid-results",
    "collection": "tasks",
    "admin_user": "userid",
    "admin_password": "pass1",
    "readonly_user": "userid-ro",
    "readonly_password": "pass2",
    "host": "146.186.149.69",
    "port": 27018,
    "aliases": {}
}

my_launchpad.yaml used by FireWorks through MongoDB for DFT job managements, templated as follows.

host: 146.186.149.69
name: userid-fws
password: pass3
port: 27018
ssl_ca_file: null
strm_lvl: INFO
user_indices: []
username: userid
wf_user_indices: []

Access MongoDB database from desktop¶

One can install robo3T from https://robomongo.org/. One needs to use the information from the db.json file to setup robo3T connection as indicated below

#note

PSU-VM is a label of your choice to remark the MongoDB connection;

146.186.149.69 is the ip address of the MongoDB server;

One needs to replace userid with the one (i.e. the value field of admin_user) from the db.json file together with the the value field of admin_password

Job submission/run¶

Pymatgen task to MongoDB from Windows, MacOS, or Linux

dfttk run –wf robust –f POSCAR –l

Submit DFT job only in Linux

qlaunch singleshot; or
qlaunch rapidfire

Configuration of DFTTK¶

Content¶

On batch job
Preparation
Configure all with one command
Configure separately
- Configuration for atomate
- Configuration for pymatgen
Example
Validation for configuration
Help for dfttk config command

On batch job¶

TO TOP

Preparation¶

For configure dfttk, the following file you need to prepare.

current_folder
 psp                          [specified by -psp]
  pseudopotential_content  [required if you didnot configurate pymatgen]
  ...
 config                       [specified by -c parameter]
  db.json                  [required]
  my_launchpad.yaml        [required]
  FW_config.yaml           [optional]
  my_fworker.yaml          [optional]
  my_qadapter.yaml         [optional]
 vaspjob.pbs                  [optional, specified by -q parameter]

After prepared the above required file, simply run dfttk config -all to finish the configuration. If such command successes, you can skip all of the reset part of this documents. If not, please reading the following parts.

pseudopotential_content: The vasp pseudopotential.

PRL Group Notes: For PRL group, if you use ACI at PSU, you can skip this part, using -aci parameter

It can be compressed file (*.tar.gz) or uncompressed folder. The name is handled as follows:

_images/Parse_PSP_Name.png Parse PSP Name

Note: 1. The split can recognize.,-,_,+,=,* and space .

**2.**  After split, the name will be a list. The condition e.g `contain 52` is the elements' level. It means `52` should be a elements of the list. But `US` is string level, which means `US` only need be a sub-string of the elements of the list.

**3.** For compressed file, it support `*.tar.gz` and `*.tar`

e.g. `potpaw_PBE`, `PBE.tar.gz` and `potpaw_PBE_5254` will be recognized as `PBE`.

	    `potpaw_PBE.52` and `potpaw_PBE_52` will be recognized as `PBE_52`

	    `potUSPP_LDA` and `POT_LDA_US` will be recognized as `LDA_US`

After prepare, the file structure should look like as follows:

Click for details

e.g. psp
      potpaw_LDA.54.tar.gz
      potpaw_PBE.54.tar.gz
      ...
 or: psp
      potpaw_LDA_54
       Ac
       ...
      potpaw_PBE_54
       Ac
       ...
      ...

The original pseudopotential file, please ask those who are in charge of vasp in your group.

MAPI_KEY: The API key of Materials Project, ref. API KEY
vaspjob.pbs: The submitting script of your queue system. Currently, only pbs system is supported
other config files: At least, you need prepare two files, db.json and my_launchpad.yaml. The template is shown in the config folder.
- For more details, please ref. Configure database connections and computing center parameters
PRL GROUP NOTES:
- For db.json and my_launchpad.yaml file, please ask Brandon for help.
- vaspjob.pbs for ACI can be download from github
- For pseudopotential, two choices: 1. using the pseudopotentials in ACI account (Using -aci parameter). 2. Download the pseudopotential from group’s box(Group Documents/VASP_potential note: only PBE_54 and LDA_54).

TO TOP

Configure all with one command¶

dfttk config -all

For ACI at PSU user, please use dfttk config -all -aci

usage: dfttk config [-h] [-all] [-p PATH_TO_STORE_CONFIG] [-a]
                    [-c CONFIG_FOLDER] [-q QUEUE_SCRIPT] [-qt QUEUE_TYPE]
                    [-v VASP_CMD_FLAG] [-mp] [-aci] [-psp VASP_PSP_DIR]
                    [-mapi MAPI_KEY] [-df DEFAULT_FUNCTIONAL]

The meaning of the parameters, please ref Help for dfttk config command or just run dfttk config -h

TO TOP

Configure separately¶

Configuration for atomate¶

Config manual, ref Configure database connections and computing center parameters

dfttk config -a

usage: dfttk config -a [-p PATH_TO_STORE_CONFIG] [-c CONFIG_FOLDER] [-q QUEUE_SCRIPT]
                       [-qt QUEUE_TYPE] [-v VASP_CMD_FLAG]

The meaning of the parameters, please ref Help for dfttk config command or just run dfttk config -h

TO TOP

Configuration for pymatgen¶

Config manual, ref POTCAR setup in pymatgen

dfttk config -mp

usage: dfttk config -mp [-aci] [-p PATH_TO_STORE_CONFIG] [-psp VASP_PSP_DIR] [-mapi MAPI_KEY]
                    [-df DEFAULT_FUNCTIONAL]

The meaning of the parameters, please ref Help for dfttk config command or just run dfttk config -h

TO TOP

Example¶

dfttk config -all -p test_config -mapi test_api

In test_config folder

test_config
 config
  db.json
  FW_config.yaml
  my_fworker.yaml
  my_launchpad.yaml
  my_qadapter.yaml
 logs
 vasp_psp
     POT_GGA_PAW_PBE_54
     Ac
      ...
     POT_LDA_PAW_54
        Ac
         ...

In ~/.bashrc

export FW_CONFIG_FILE=/gpfs/scratch/mjl6505/test/dfttk/tutorial/config/test_config/config/FW_config.yaml

in ~/.pmgrc.yaml

PMG_DEFAULT_FUNCTIONAL: PBE
PMG_MAPI_KEY: test_api
PMG_VASP_PSP_DIR: /gpfs/scratch/mjl6505/test/dfttk/tutorial/config/test_config/vasp_psp

TO TOP

Validation for configuration¶

dfttk config -t

This command will validate the configuration, and give some error or tips for the incorrect configuration
```
dfttk config -t [{all,pymatgen,atomate,none}]
```
- Currently only support validation for the configuration of pymatgen

TO TOP

Help for `dfttk config` command¶

dfttk config -h

DFTTK version: 0.1+121.g8fddda3.dirty
Copyright  Phases Research Lab (https://www.phaseslab.com/)

usage: dfttk config [-h] [-all] [-p PATH_TO_STORE_CONFIG] [-a]
                    [-c CONFIG_FOLDER] [-q QUEUE_SCRIPT] [-qt QUEUE_TYPE]
                    [-v VASP_CMD_FLAG] [-mp] [-aci] [-psp VASP_PSP_DIR]
                    [-mapi MAPI_KEY]
                    [-df {LDA,LDA_52,LDA_54,LDA_US,PBE,PBE_52,PBE_54,PW91,PW91_US,Perdew-Zunger81}]
                    [-t [{all,pymatgen,atomate}]]

optional arguments:
  -h, --help            show this help message and exit
  -all, --all           Configure atomate and pymatgen.
  -p PATH_TO_STORE_CONFIG, --prefix PATH_TO_STORE_CONFIG
                        The folder to store the config files. Default: .
                        (current folder)
  -a, --atomate         Configure atomate.
  -c CONFIG_FOLDER, --config_folder CONFIG_FOLDER
                        The folder containing config files, at least contain
                        db.json and my_launchpad.yaml. Default: '.'
  -q QUEUE_SCRIPT, --queue_script QUEUE_SCRIPT
                        The filename of the script for sumitting vasp job. It
                        will search in current folder and sub-folders.
                        Default: vaspjob.pbs
  -qt QUEUE_TYPE, --queue_type QUEUE_TYPE
                        The type of queue system. Note, only pbs is supported
                        now. Default: pbs
  -v VASP_CMD_FLAG, --vasp_cmd_flg VASP_CMD_FLAG
                        The flag to distinguish vasp_cmd to othe commands in
                        queue_script. Default: vasp_std
  -mp, --pymatgen       Configure pymatgen.
  -aci, --aci           Using the pesudopotential on the ACI cluster at PSU.
  -psp VASP_PSP_DIR, --vasp_psp_dir VASP_PSP_DIR
                        The path of pseudopotentials. Default: psp
  -mapi MAPI_KEY, --mapi_key MAPI_KEY
                        The API key of Materials Projects
  -df {LDA,LDA_52,LDA_54,LDA_US,PBE,PBE_52,PBE_54,PW91,PW91_US,Perdew-Zunger81}, --default_functional {LDA,LDA_52,LDA_54,LDA_US,PBE,PBE_52,PBE_54,PW91,PW91_US,Perdew-Zunger81}
                        The default functional. Default: PBE
  -t [{all,pymatgen,atomate}], --test_config [{all,pymatgen,atomate}]
                        Test for configurations. Note: currently only support
                        for pymatgen.

Settings file¶

The user can change the settings for dfttk calculations by providing a settings file.

File name instruction¶

Globale settings¶

By default, the global settings file is named as SETTINGS.yaml or SETTINGS.json.

The user can change the name by -s parameter in dfttk run. e.g. if the user run dfttk by dfttk run -s SET, then the files named with SET.yaml or SET.json is the global settings file.

Individual settings¶

The user can provide individual settings for some structures whoes settings is different with others. The individual settings file should be named with SETTINGS-FILENAME_WITH_EXT.yaml(json) or FILENAME_WITH_EXT-SETTINGS.yaml(json)

Note:

FILENAME_WITH_EXT is the file name of structure with extension.
SETTINGS is case insensitive, both settings and SETTINGS are OK.

e.g. In the working folder, there are some structure files as follows:

Fe3Ni.cif
POSCAR
POSCAR-2

Then the following files will be recognized as settings files.

SETTINGS-Fe3Ni.cif.yaml
POSCAR-SETTINGS.yaml
settings-POSCAR-2.yaml

Keywords in the file¶

Default settings¶

The settings file is optional, if the user does not provide the settings file, the default value will be used.

Common settings

Keywords	Default Value	Comments
magmom	No	The MAGMOM for each atom, e.g. [4, 4, -4, 4]. Note, the length must agree with the number of atoms
metadata	No	The metadata of the calculation. If the user provides it, DFTTK will find the existing calculations in the databasse. If not, it will generate by uuid4.
isif4	False	If run ISIF=4 following ISIF=7 in RobustOptmizeFW
level	1	Optimize level. If run ISIF=2 after last ISIF=4 in RobustOptimizeFW 1 for run and 2 for not
override_symmetry_tolerances	None	Override the default symmetry tolerance, if None, {‘tol_strain’:0.05,’tol_energy’:0.025, ‘tol_bond’:0.10}
override_default_vasp_params	{}	Override the default vasp settings The optional keys is ‘user_incar_settings’, ‘user_kpoints_settings’, ‘user_potcar_functional’. For more details, ref. https://pymatgen.org/pymatgen.io.vasp.sets.html
modify_incar_params	{}	Modify the incar settings in the fireworks level. e.g. modify_incar_params = { ‘Full relax’: {‘incar_update’: {“LCHARG”:False}}, ‘static’: {‘incar_update’: “LAECHG”:True}}
modify_kpoints_params	{}	Modify the kpoints settings in the fireworks level.
store_volumetric_data	False	Store the volumetric data (True) or not (False)
verbose	False	print(True) or not(False) some informations, for debug
passinitrun	False	Pass init vasp result. It will be dropped in the future
run_isif2	False	If run ISIF=2 before ISIF=4 (True) or not (False). It will be dropped in the future
pass_isif4	False	Whether pass isif=4 calculation. It will be dropped in the future
symmetry_tolerance	0.05	The tolerannce for symmetry. It will be dropped in the future
relax_path	‘’	The path of relaxiation. It will be dropped in the future

Phonon settings

Keywords	Default Value	Comments
phonon	False	Run phonon (True) or not(False, Debye model)
phonon_supercell_matrix	atoms	The supercell matrix for phonon calculations. It can take the following values: Matrix, e.g. [[2, 0, 0], [0, 2, 0], [0, 0, 2]] String: atom/lattice/volume(the first letter works) Determining the supercell matrix automatically by atoms/lattice/volume ranges
phonon_supercell_matrix_min	60	The lower boundary for phonon_supercell_matrix(String)
phonon_supercell_matrix_max	130	The upper boundary for phonon_supercell_matrix(String)
force_phonon	False	Force run phonon (True) or not(False), No matter ISIF=4/stable_tor pass or not
stable_tor	0.01	Stable torlerance (The percentage of negative dos), If the negative part of DOS is larger than this value, DFTTK won’t run phonon for this structure.

QHA settings

Keywords	Default Value	Comments
num_deformations	7	The number of deformations/structures
deformation_fraction	[-0.1, 0.1]	The range of deformation, 0.1 means 10%
eos_tolerance	0.01	The tolerance for eos fitting. If larger than this value, DFTTK will append volumes automatically
t_min	5	The mimimum of temperature in QHA process
t_max	2000	The maximum of temperature in QHA process
t_step	5	The step of temperature in QHA process
volume_spacing_min	0.03	Minimum ratio of Volumes spacing. This keyword will be dropped in the future

Elastic settings

Keywords	Default Value	Comments
strain_states	None	Strain modes, if it is None, it will generated by atomate
stencils	None	The amplitude of the strain modes/states
analysis	True	Analysis (True) or not (False)
sym_reduce	False	Reduce the strain according to the symmetry or not
order	2	The order of the elastic constants
conventional	False	Convert the structure into conventional format or not

Welcome to dfttk_example’s documentation!¶

Example¶

Installation¶

Config MongoDB¶

Access MongoDB database from desktop¶

Job submission/run¶

Configuration of DFTTK¶

Content¶

On batch job¶

Preparation¶

Configure all with one command¶

Configure separately¶

Configuration for atomate¶

Configuration for pymatgen¶

Example¶

Validation for configuration¶

Help for dfttk config command¶

Settings file¶

File name instruction¶

Globale settings¶

Individual settings¶

Keywords in the file¶

Default settings¶

Indices and tables¶

Help for `dfttk config` command¶