Quick Start

Introduction¶

The Bader class reproduces the methods for Bader charge analysis available in the Henkelman group's excellent Fortran code within the Python ecosystem. It is built on top of the PyMatGen package, allowing for easy extension to other projects. Under the hood, Bader runs on Numba and NumPy to parallelize and vectorize calculations. This allows Bader to reach speeds comparable or faster than the original code.

Basic Use¶

BaderKit can be used through the command line interface or through Python script. This page covers only the most simple use case of running Bader charge analysis on a VASP CHGCAR or Gaussian cube file. For more advance usage, see our API reference and Examples pages.

Command LinePythonGUI App

Activate your environment with BaderKit installed. If you are not using an environment manager, skip to step 2.
```
conda activate my_env
```
Navigate to the directory with your charge density file.
```
cd /path/to/directory
```
Run the bader analysis. Replace 'chargefile' with the name of your file.
```
baderkit run chargefile
```

Output files for atoms and bader basins will be written automatically to bader_atom_summary.tsv and bader_basin_summary.tsv respectively. Each file includes rows for each atom or basin with columns for:

atom labels/assignments
coordinates (fractional)
charges (e)
volumes (Å³)
minimum surface distances (Å)
distances to nearest atom (Å) basins only

Additional arguments and options such as those for printing output files or using different algorithms can be viewed by running the help command.

baderkit run --help

Import the Bader class.
```
from baderkit.core import Bader
```

Use the Bader class' from_dynamic method to read a CHGCAR or cube file.

# instantiate the class
bader = Bader.from_dynamic("path/to/charge_file")

To run the analysis, we can call any class property. Try getting a complete summary in dictionary format.
```
results = bader.to_json()
```

Now try getting individual properties. For more details on each property, see the API reference.

atom_charges = bader.atom_charges # Total atom charges
atom_labels = bader.atom_labels # Atom assignments for each point in the grid
basin_volumes = bader.basin_volumes # The volumes of each bader basin
maxima_coords = bader.basin_maxima_frac # Frac coordinates of each attractor

BaderKit also provides convenience methods for writing results to file. First, let's write a summary of the full analysis.
```
bader.write_json()
```
Now let's write the volume assigned to one of our atoms.
```
bader.write_atom_volumes(atom_indices = [0])
```

Tip

After creating a Bader class object, it doesn't matter what order you call properties, summaries, or write methods in. BaderKit calculates properties/results only when they are needed and caches them.

Activate your environment with BaderKit installed. If you are not using an environment manager, skip to step 2.
```
conda activate my_env
```
Run the BaderKit GUI.
```
baderkit gui
```
This will launch a new window:
Browse to find you charge density file, select your method, and run!

Warning for VASP (And other pseudopotential codes)¶

VASP and other pseudopotential codes only include the valence electrons in their charge density outputs. In VASP, there is an option to write out the core electron density by adding the tag LAECHG=.TRUE. to your INCAR file.

This will write the core charge density to an AEECAR0 file and the valence to AECCAR2 which can be summed together to get a total charge density that is much more accurate for partitioning. We highly recommend doing this.

Command LinePython

Sum the files using BaderKit's convenience method.
```
baderkit sum AECCAR0 AECCAR2
```
Run the analysis using this total charge density as the reference for partitioning.
```
baderkit run CHGCAR -ref CHGCAR_sum
```

Import the Bader and Grid classes.
```
from baderkit.core import Bader, Grid
```

Load the CHGCAR, AECCAR0 and AECCAR2

charge_grid = Grid.from_vasp("CHGCAR")
aeccar0_grid = Grid.from_vasp("AECCAR0")
aeccar2_grid = Grid.from_vasp("AECCAR2")

Sum the AECCAR files

reference_grid = aeccar0.linear_add(aeccar2_grid)

Create the bader object

bader = Bader(
    charge_grid = charge_grid,
    reference_grid = reference_grid
    )

From here, the Bader class object can be used as described in the Basic Use section.

Warning

A fine grid is needed to accurately reproduce the core charge density. We have found that a grid density of ~22 pts/Å along each lattice vector (~10000 pts / Å³) is fine enough in most cases, but we generally recommend testing an increasing set of grid densities until convergence is reached.