pymatgen.command_line.bader_caller module

This module implements an interface to the Henkelmann et al.’s excellent Fortran code for calculating a Bader charge analysis.

This module depends on a compiled bader executable available in the path. Please download the library at http://theory.cm.utexas.edu/henkelman/code/bader/ and follow the instructions to compile the executable.

If you use this module, please cite the following:

G. Henkelman, A. Arnaldsson, and H. Jonsson, “A fast and robust algorithm for Bader decomposition of charge density”, Comput. Mater. Sci. 36, 254-360 (2006).

class BaderAnalysis(chgcar_filename=None, potcar_filename=None, chgref_filename=None, parse_atomic_densities=False, cube_filename=None)

Bases: object

Bader analysis for Cube files and VASP outputs.

Initializes the Bader caller.

Parameters:

• chgcar_filename (str) – The filename of the CHGCAR.

• potcar_filename (str) – The filename of the POTCAR.

• chgref_filename (str) – The filename of the reference charge density.

• parse_atomic_densities (bool) – Optional. turns on atomic partition of the charge density charge densities are atom centered

• cube_filename (str) – Optional. The filename of the cube file.

classmethod from_path(path, suffix='')

Convenient constructor that takes in the path name of VASP run to perform Bader analysis.

Parameters:

• path (str) – Name of directory where VASP output files are stored.

• suffix (str) – specific suffix to look for (e.g. ‘.relax1’ for ‘CHGCAR.relax1.gz’).

get_charge(atom_index)

Convenience method to get the charge on a particular atom. This is the “raw” charge generated by the Bader program, not a partial atomic charge. If the cube file is a spin-density file, then this will return the spin density per atom with positive being spin up and negative being spin down.

Parameters:

atom_index – Index of atom.

Returns:

Charge associated with atom from the Bader analysis.

get_charge_decorated_structure()

Returns a charge decorated structure

Note, this assumes that the Bader analysis was correctly performed on a file with electron densities

get_charge_transfer(atom_index, nelect=None)

Returns the charge transferred for a particular atom. A positive value means that the site has gained electron density (i.e. exhibits anionic character) whereas a negative value means the site has lost electron density (i.e. exhibits cationic character). If the arg nelect is not supplied, then POTCAR must be supplied to determine nelect.

Parameters:

• atom_index – Index of atom.

• nelect – number of electrons associated with an isolated atom at this index. For most DFT codes this corresponds to the number of valence electrons associated with the pseudopotential (e.g. ZVAL for VASP).

Returns:

Charge transfer associated with atom from the Bader analysis. Given by bader charge on atom - nelect for associated atom.

get_decorated_structure(property_name, average=False)

Get a property-decorated structure from the Bader analysis.

This is distinct from getting charge decorated structure, which assumes the “standard” Bader analysis of electron densities followed by converting electron count to charge. The expected way to use this is to call Bader on a non-charge density file such as a spin density file, electrostatic potential file, etc., while using the charge density file as the reference (chgref_filename) so that the partitioning is determined via the charge, but averaging or integrating is done for another property.

User warning: Bader analysis cannot automatically determine what property is inside of the file. So if you want to use this for a non-conventional property like spin, you must ensure that you have the file is for the appropriate property and you have an appropriate reference file.

Parameters:

• property_name – name of the property to assign to the structure, note that if name is “spin” this is handled as a special case, and the appropriate spin properties are set on the species in the structure

• average – whether or not to return the average of this property, rather than the total, by dividing by the atomic volume.

Returns:

structure with site properties assigned via Bader Analysis

get_oxidation_state_decorated_structure(nelects=None)

Returns an oxidation state decorated structure based on bader analysis results. Each site is assigned a charge based on the computed partial atomic charge from bader.

Note, this assumes that the Bader analysis was correctly performed on a file with electron densities

get_partial_charge(atom_index, nelect=None)

Convenience method to get the partial charge on a particular atom. This is simply the negative value of the charge transferred. A positive value indicates that the atom has cationic character, whereas a negative value indicates the site has anionic character.

Parameters:

• atom_index – Index of atom.

• nelect – number of electrons associated with an isolated atom at this index. For most DFT codes this corresponds to the number of valence electrons associated with the pseudopotential (e.g. ZVAL for VASP).

Returns:

Charge associated with atom from the Bader analysis.

property summary

Dict summary of key analysis, e.g., atomic volume, charge, etc.

Type:

return

bader_analysis_from_objects(chgcar, potcar=None, aeccar0=None, aeccar2=None)

Convenience method to run Bader analysis from a set of pymatgen Chgcar and Potcar objects.

This method will:

1. If aeccar objects are present, constructs a temporary reference file as AECCAR0 + AECCAR2 2. Runs Bader analysis twice: once for charge, and a second time for the charge difference (magnetization density).

Parameters:

• chgcar – Chgcar object

• potcar – (optional) Potcar object

• aeccar0 – (optional) Chgcar object from aeccar0 file

• aeccar2 – (optional) Chgcar object from aeccar2 file

Returns:

summary dict

bader_analysis_from_path(path, suffix='')

Convenience method to run Bader analysis on a folder containing typical VASP output files.

This method will:

1. Look for files CHGCAR, AECCAR0, AECCAR2, POTCAR or their gzipped counterparts. 2. If AECCAR* files are present, constructs a temporary reference file as AECCAR0 + AECCAR2 3. Runs Bader analysis twice: once for charge, and a second time for the charge difference (magnetization density).

Parameters:

• path – path to folder to search in

• suffix – specific suffix to look for (e.g. ‘.relax1’ for ‘CHGCAR.relax1.gz’

Returns:

summary dict