title

Quick Start¶

BaderKit 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, BaderKit runs on Numba and NumPy to parallelize and vectorize calculations. This allows BaderKit to reach speeds comparable or faster than the original code.

Installation¶

conda (recommended)pipGUI App (Optional)

If you haven't already, install a conda environment manager such as Anaconda.

Create a conda environment using the following command in your terminal. Replace my_env with whatever name you prefer.
```
conda create -n my_env
```
Activate your environment.
```
conda activate my_env
```
Install BaderKit.
```
conda install -c conda-forge baderkit
```
Confirm the install by running the help command.
```
baderkit --help
```

We generally recommend using a virtual environment manager such as Anaconda or venv to keep your Python work environments isolated. If you don't want to, you can still use pip so long as Python is installed.

Install BaderKit with the following command in your terminal.
```
pip install baderkit
```
Confirm the install by running the help command
```
baderkit --help
```

In addition to the core package, there is an optional GUI feature which allows for easy viewing and plotting of results. This requires extra dependencies which can be installed through pip.

pip install baderkit[gui]

Note

This is kept as optional as the GUI requires significantly more dependencies than the base app. Unfortunately, this means conda cannot be used, as it does not allow for optional dependencies.

Basic Use¶

Once installed, 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. 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

The core functionality of BaderKit revolves around the Bader class. First, 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.results_summary
```

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_results_summary()
```
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.