Charge-Density Difference

This tutorial explains how to visualize an already-generated charge-density difference (CDD) cube file with VQkit.

The charge-density difference is commonly defined as:

\[\Delta\rho(\mathbf r) = \rho_{\mathrm{full}}(\mathbf r) - \rho_{\mathrm{fragment\,1}}(\mathbf r) - \rho_{\mathrm{fragment\,2}}(\mathbf r)\]

Important

The current VQkit CDD workflow is a plotting and analysis workflow.

VQkit expects the final, already-combined CDD data in a Gaussian cube file:

*.cube

or:

*.cub

VQkit does not ask for fragment 1 and fragment 2 inside the CDD plotting menu and does not repeat the density subtraction there.

For Quantum ESPRESSO, generate the final CDD cube first, for example using pp.x.

Then place the final cube in the VQkit working directory.

Typical input

A working directory may contain:

charge_difference.cube

or:

CDD.cube

or another final CDD cube file.

VQkit searches all .cube and .cub files.

Files whose names contain terms such as the following are preferred:

cdd
charge_diff
charge-diff
charge_difference
charge-density-difference
difference
delta_rho
deltarho

Open the CDD workflow

From the VQkit main menu choose:

[2] Post-processing

Then choose:

[4] Charge, spin and bonding

Then select:

[1] Charge-density difference

VQkit searches the current working directory for a final CDD cube file.

Single cube file

If only one suitable cube file is found, VQkit selects it automatically.

Multiple cube files

If several cube files are detected, VQkit shows them and asks:

Detected multiple cube files:
  [1] ...
  [2] ...
  ...

Select final CDD cube [1]:

Choose the cube containing the final charge-density difference.

No cube file found

If no cube file is present, VQkit reports:

No .cube/.cub file was found in the working directory.

For Quantum ESPRESSO, first generate the final CDD cube with pp.x.

VQkit expects the already-combined final charge-density difference cube.

Cube-file information

After reading the cube, VQkit reports information such as:

Detected final CDD cube
Grid
Atoms
Plot density units

For QE-style cube data, VQkit converts charge density from:

e/bohr^3

to:

e/Angstrom^3

using the Bohr-to-Angstrom conversion.

1. XY center slice

Choose:

VQkit takes the center grid point along the z direction and plots the charge-density difference in the xy plane.

Output

Typical files are:

VQkit_QE_CDD_XY.png
VQkit_QE_CDD_XY.dat

The .png file is the contour plot.

The .dat file contains:

axis1_A
axis2_A
delta_rho_e_A^-3

2. XZ center slice

Choose:

VQkit takes the center grid point along y and plots the xz plane.

Output:

VQkit_QE_CDD_XZ.png
VQkit_QE_CDD_XZ.dat

3. YZ center slice

Choose:

VQkit takes the center grid point along x and plots the yz plane.

Output:

VQkit_QE_CDD_YZ.png
VQkit_QE_CDD_YZ.dat

4. All center slices

Choose:

or press Enter at:

Select plot type [4]:

VQkit generates all three central planes:

XY
XZ
YZ

Typical outputs are:

VQkit_QE_CDD_XY.png
VQkit_QE_CDD_XY.dat

VQkit_QE_CDD_XZ.png
VQkit_QE_CDD_XZ.dat

VQkit_QE_CDD_YZ.png
VQkit_QE_CDD_YZ.dat

This is the recommended first inspection because it quickly shows the charge redistribution in all principal planes.

5. Custom slice position

Choose:

VQkit asks:

Plane [YZ]:

Allowed values are:

XY
XZ
YZ

Then VQkit asks:

Fractional slice position 0-1 [0.5]:

The fractional position determines where the slice is taken along the axis normal to the plane.

Examples

Center slice:

0.5

Near one side of the cell:

0.2

Near the opposite side:

0.8

VQkit converts the fractional position to the closest grid index.

Example

To inspect a YZ slice at 30% of the x direction:

Plane [YZ]: YZ
Fractional slice position 0-1 [0.5]: 0.3

Typical output is:

VQkit_QE_CDD_YZ_CUSTOM.png
VQkit_QE_CDD_YZ_CUSTOM.dat

The data file also records:

slice index;
slice coordinate in Angstrom;
charge-density units.

6. Planar average along z

Choose:

VQkit averages the three-dimensional charge-density difference over the xy plane and obtains:

\[\langle \Delta\rho(z) \rangle_{xy}\]

This produces a one-dimensional profile along z.

Output

VQkit writes:

VQkit_QE_CDD_PLANAR_Z.png
VQkit_QE_CDD_PLANAR_Z.dat

The data file contains:

coordinate_A
planar_average_delta_rho_e_A^-3

This profile is particularly useful for:

interfaces;
surfaces;
adsorption systems;
layered materials;
charge redistribution normal to a slab.

Color convention

CDD slice plots use a symmetric positive/negative scale.

VQkit uses:

red  = charge accumulation
blue = charge depletion

A zero-density contour is drawn to make the boundary between positive and negative charge redistribution explicit.

Because the color scale is symmetric around zero, positive and negative charge redistribution can be compared directly.

Atomic overlays

VQkit reads the atomic positions stored in the cube file.

Atoms close to the selected slice are overlaid on the contour plot.

The atoms are:

shown with circular markers;
labeled by element symbol.

This helps relate accumulation and depletion regions to specific atoms and bonds.

Example: adsorption-system CDD

Assume you have already generated the final charge-density difference for an adsorbate on a surface.

Your working directory contains:

adsorption_CDD.cube

Step 1 — Start VQkit

Start VQkit in this directory.

Step 2 — Open post-processing

Choose:

Step 3 — Open charge analysis

Choose:

for:

Charge, spin and bonding

Step 4 — Open CDD

Choose:

VQkit detects:

adsorption_CDD.cube

Step 5 — Generate all center slices

At:

Select plot type [4]:

press Enter.

VQkit generates:

VQkit_QE_CDD_XY.png
VQkit_QE_CDD_XZ.png
VQkit_QE_CDD_YZ.png

and their corresponding .dat files.

Step 6 — Find the most informative plane

Inspect the three plots.

For an adsorption geometry, the plane passing through both the adsorbate and surface binding atom is usually the most informative.

If the center slice does not pass through the bond, use:

for a custom slice.

Step 7 — Generate a custom slice

For example:

Plane [YZ]: XZ
Fractional slice position 0-1 [0.5]: 0.42

Adjust the fractional position until the relevant atoms or bonding region are intersected.

Step 8 — Generate the planar average

For a slab or interface, choose:

to generate:

VQkit_QE_CDD_PLANAR_Z.png
VQkit_QE_CDD_PLANAR_Z.dat

Use the profile to inspect charge redistribution normal to the surface.

Generating the final QE CDD cube

The exact subtraction procedure is performed outside the current VQkit CDD plotting menu.

A typical Quantum ESPRESSO workflow is:

Perform the calculation for the complete interacting system.
Perform fragment calculations using a consistent cell and grid.
Generate charge-density data with pp.x.
Form the final difference:

\[\Delta\rho = \rho_{\mathrm{full}} - \rho_{\mathrm{fragment\,1}} - \rho_{\mathrm{fragment\,2}}\]
Export the final difference as a Gaussian cube.
Place that final cube in the VQkit working directory.
Run the VQkit CDD plotting workflow.

The current VQkit workflow begins at step 6.

3D visualization

VQkit generates two-dimensional slices and a planar-average profile.

For three-dimensional CDD isosurfaces, open the original cube file in an external visualization program such as:

VESTA;
VMD;
XCrySDen.

VQkit retains the original cube unchanged.

Interpreting CDD

Charge accumulation

Regions with:

\[\Delta\rho > 0\]

represent increased electron density relative to the chosen fragment reference.

In VQkit plots these regions are shown in red.

Charge depletion

Regions with:

\[\Delta\rho < 0\]

represent decreased electron density relative to the fragment reference.

In VQkit plots these regions are shown in blue.

Zero contour

The zero contour marks:

\[\Delta\rho = 0\]

and separates accumulation from depletion regions.

Common problems

No cube detected

If VQkit reports:

No .cube/.cub file was found

check that:

the final CDD file is in the current working directory;
the extension is .cube or .cub;
VQkit is running in the correct directory.

Wrong cube selected

If several cube files exist, verify that you selected the final CDD cube, not the full-system density or a fragment density.

Incomplete cube

If the cube contains fewer grid values than specified in the cube header, VQkit stops and reports that the grid is incomplete.

Custom slice misses the atoms

Change the fractional slice position until the plane intersects the relevant atoms or bonding region.

Scientific cautions

Consistent fragment calculations

The physical meaning of:

\[\Delta\rho = \rho_{\mathrm{full}} - \rho_{\mathrm{fragment\,1}} - \rho_{\mathrm{fragment\,2}}\]

depends on using compatible full-system and fragment densities.

The fragment calculations should use a consistent simulation cell, geometry reference, real-space grid, pseudopotentials, and electronic-structure settings.

Sign convention

Always state the CDD definition used in your work.

If the subtraction order is changed, the interpretation of positive and negative regions also changes.

Slice dependence

A two-dimensional slice shows only one plane through the three-dimensional charge-density field.

Before drawing conclusions, inspect several planes or use a 3D isosurface visualization when necessary.

Color scale

The absolute magnitude of CDD depends on the system and the generated density.

VQkit automatically uses a symmetric scale based on the maximum absolute density of the selected slice, so different plots may not have identical numerical color ranges.

For quantitative comparison across several systems, compare the numerical .dat values or construct plots using a common fixed scale.

Charge-Density Difference

Important

Typical input

Open the CDD workflow

Single cube file

Multiple cube files

No cube file found

Cube-file information

Plot menu

1. XY center slice

Output

2. XZ center slice

3. YZ center slice

4. All center slices

5. Custom slice position

Examples

Example

6. Planar average along z

Output

Color convention

Atomic overlays

Example: adsorption-system CDD

Step 1 — Start VQkit

Step 2 — Open post-processing

Step 3 — Open charge analysis

Step 4 — Open CDD

Step 5 — Generate all center slices

Step 6 — Find the most informative plane

Step 7 — Generate a custom slice

Step 8 — Generate the planar average

Generating the final QE CDD cube

3D visualization

Interpreting CDD

Charge accumulation

Charge depletion

Zero contour

Common problems

No cube detected

Wrong cube selected

Incomplete cube

Custom slice misses the atoms

Scientific cautions

Consistent fragment calculations

Sign convention

Slice dependence

Color scale