Skip to content
Austin243Public

About

Track Bader charges, ELF/QTAIM topology, and LOBSTER ICOHP across VASP NEB and ordered periodic structure series.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

ElecTrace banner. Seven frames of the HCN to HNC example, each drawn to scale, with ribbons joining the bond critical points from frame to frame. A ribbon's width is the density at its critical point. One critical point stays on one track as it changes from tying C and H to tying N and H

ElecTrace tracks how electronic-structure features change across ordered periodic structures, including VASP NEB images and static or pressure series. It combines per-frame results from electronic-analysis tools with periodic atom and feature matching to compare evidence across frames and produce a single analysis for the full path.

ElecTrace can work with descriptor results that already exist, or it can stage and launch configured calculations across selected frames through a local or Slurm workflow.

What it does

  • Discovers ordered VASP frame directories and selects individual frames or slices.
  • Reads POSCAR/CONTCAR structures and VASP ELFCAR/CHGCAR grids, sums AECCAR0 and AECCAR2 into a Bader reference, and splits a spin-polarized CHGCAR into total and magnetization grids for Bader.
  • Ingests supported Bader/BaderKit, critic2, LOBSTER, and Chargemol results, including per-atom spin populations and spin-resolved LOBSTER lists, and gives Bader net charges when a frame's POTCAR or OUTCAR supplies ZVAL.
  • Matches atoms and electronic features across periodic and changing cells.
  • Builds feature correspondences and reports births, deaths, conservation-backed split/merge candidates, and descriptor changes.
  • Lists each bond's distance, critical-point density and Laplacian, and ICOHP/ICOBI frame by frame, with rows that begin or end as bonds form or break.
  • Sums charges and spins over named atom groups and the molecules of the first frame, with a noise floor from molecules that take no part.
  • Draws chosen bonds and atoms along the path as a figure: the energy profile, or the enthalpy profile for a variable-cell path at a stated pressure, the bond-critical-point densities and distances, and the net charges and spins.
  • Stages VASP, Bader/BaderKit, critic2, and LOBSTER steps from a YAML workflow, including Bader charges and spin populations on the all-electron reference and a critic2 search seeded along every atom pair across periodic images.
  • Writes JSON, CSV, and HTML results with available source and tool provenance.

Install

ElecTrace supports CPython 3.11–3.13. From a source checkout:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

The base installation includes a deterministic assignment solver. Use python -m pip install ".[accelerate]" for the SciPy solver, which is much faster for cells with hundreds of features per frame, python -m pip install ".[plot]" for path figures, or python -m pip install ".[all]" for all optional features.

Try the demo

The built-in demo runs without external scientific software:

electrace demo --output .electrace-demo
electrace inspect .electrace-demo/electrace-results

Try real native outputs

The compact HCN-to-HNC example includes seven GPU-generated VASP frames plus native Bader and critic2 results:

cd examples/hcn-hnc
electrace analyze electrace.toml
electrace inspect electrace-results

It is an illustrative hand-defined static scan, not an optimized reaction path or benchmark. No licensed pseudopotentials, executables, or large density files are included.

Analyze existing results

Create a configuration for an ordered VASP path, then point it to supported descriptor files in the frame directories or an external descriptor directory:

electrace init electrace.toml --images /absolute/path/to/neb-images
# Review electrace.toml and set the descriptor source as needed.
electrace analyze electrace.toml
electrace inspect electrace-results

To draw chosen bonds and atoms along the path as PDF, SVG, and PNG files, see path figures:

electrace figure electrace-results --bond C41-H227 --atom H227 --output path-figure

VASP scalar grids can also be summarized or sampled directly:

electrace volume /path/to/ELFCAR
electrace volume /path/to/ELFCAR --sample 0.5,0.5,0.5
electrace volume /path/to/CHGCAR --split-spin
electrace volume /path/to/AECCAR0 --add /path/to/AECCAR2

For a spin-polarized (ISPIN = 2) run, --split-spin writes spin/CHGCAR_tot and spin/CHGCAR_mag for a Bader spin-population run, and --add writes CHGCAR_sum, the all-electron reference for bader -ref; see spin-polarized runs. A workflow can run both for every frame, followed by Bader and critic2; see all-electron density analysis.

Run calculations across frames

The workflow YAML defines executable paths, input templates, dependencies, scheduler settings, and frame selection. Selections can combine explicit indices with slices, for example frames: "0,2:11:2".

Create the manifest, edit it for the calculation, and stage the selected frames:

electrace workflow init electrace-workflow.yaml \
  --images /absolute/path/to/neb-images
# Set executable paths, templates, frames, and scheduler settings in the YAML.
electrace workflow validate electrace-workflow.yaml --json
electrace workflow stage electrace-workflow.yaml

Validation resolves the selected frames, commands, inputs, outputs, dependencies, and scheduler settings without creating a workspace. Use --json when a script or coding agent needs machine-readable output.

Run locally and analyze the collected outputs:

electrace workflow run electrace-workflow.yaml --yes --max-parallel 2
electrace workflow analyze electrace-workflow.yaml

With scheduler.kind: slurm, prepare scripts for review and then submit them:

electrace workflow submit electrace-workflow.yaml --job-name electrace
electrace workflow submit electrace-workflow.yaml --job-name electrace --yes --force

After the Slurm jobs finish, electrace workflow analyze electrace-workflow.yaml collects the supported outputs—or reuses a valid existing collection—and runs the same path analysis.

Learn more

See Using ElecTrace, the coding-agent reference, and scientific scope.

ElecTrace is available under the BSD 3-Clause License.

About

Track Bader charges, ELF/QTAIM topology, and LOBSTER ICOHP across VASP NEB and ordered periodic structure series.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages