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.
- Discovers ordered VASP frame directories and selects individual frames or slices.
- Reads
POSCAR/CONTCARstructures and VASPELFCAR/CHGCARgrids, sumsAECCAR0andAECCAR2into a Bader reference, and splits a spin-polarizedCHGCARinto 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
POTCARorOUTCARsupplies 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.
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.
The built-in demo runs without external scientific software:
electrace demo --output .electrace-demo
electrace inspect .electrace-demo/electrace-resultsThe 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-resultsIt is an illustrative hand-defined static scan, not an optimized reaction path or benchmark. No licensed pseudopotentials, executables, or large density files are included.
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-resultsTo 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-figureVASP 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/AECCAR2For 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.
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.yamlValidation 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.yamlWith 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 --forceAfter 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.
See Using ElecTrace, the coding-agent reference, and scientific scope.
ElecTrace is available under the BSD 3-Clause License.