Command Line Interface

The package installs command line tool: imdg - the master script for VASP workflows.

imdg status

Monitor the status of VASP calculations in the current or specified directories.

# Check status of all runs in current directory and subdirectories
imdg status

# Only show problematic runs (warnings or failures)
imdg status --problematic

# Exclude specific directories using regex
imdg status --exclude "test_runs"

Features:

  • Identifies running SLURM jobs.

  • Checks convergence (electronic, ionic, and multi-step sequences).

  • Parses and highlights VASP warnings (e.g., convergence failures, internal errors).

  • Displays NEB image convergence summaries.

imdg analyze

Summarize key properties of VASP outputs in a tabular format. This tool uses caching to quickly re-analyze large directory trees.

# Analyze all runs in the current directory
imdg analyze

# Report specific fields only
imdg analyze --fields energy e_per_atom displ

# Group results by similar INCAR parameters
imdg analyze --group

Available Fields:

  • energy, e_per_atom: Final reliable energy and energy per atom.

  • %vol: Percentage change in volume between initial and final structure.

  • displ: Average atomic displacement between initial and final structure.

  • %a, %b, %c, %alpha, %beta, %gamma: Percentage change in lattice parameters.

  • total_mag: Total magnetization.

  • max_force: Maximum atomic force in the final step (eV/Å).

imdg create

Generate fresh VASP inputs from various sources.

# Create input from Materials Project ID
imdg create mp-48

# Create input from a CIF/POSCAR file
imdg create structure.cif

# Create a box with a single atom
imdg create "Li 10x10x10"

imdg derive

This is the primary tool for chaining VASP calculations. It creates new input sets derived from existing VASP directories (inputs or outputs), allowing for complex workflows like relaxation chains, strain application, or NEB setup.

General usage

# Derive a new calculation in 'new_dir' based on 'old_dir'
imdg derive old_dir --output new_dir <subcommand> [args]

Subcommands

  • relax: Set up relaxation (ISIF 2-7).

    imdg derive . --output relax_run relax RELAX_POS_SHAPE_VOL

  • scf: Set up static self-consistent field calculation.

  • kpoints: Change K-point density.

    imdg derive . --output dense_kpoints kpoints --density 5000

  • strain: Apply lattice strain (e.g., for elastic constants).

    imdg derive . --output strain_run strain --amin 0.98 --amax 1.02 --asteps 3

  • perturb: Perturb atomic positions (e.g., to break symmetry).

  • supercell: Generate a supercell.

  • functional: Switch DFT functional (e.g., PBE, PBE+D3-BJ, optB88-vdW).

  • incar: Modify specific INCAR tags.

    imdg derive . --output high_prec incar PREC:Accurate EDIFF:1e-7

  • fix: Apply selective dynamics constraints.

  • ins: Insert atoms/molecules into voids (see pmg-insert-molecule).

  • fill: Fill sites based on relaxed unique insertion points.

  • atat: Generate input for ATAT (Alloy Theoretic Automated Toolkit) from a VASP run.

NEB and Diffusion

imdg derive includes specialized tools for Nudged Elastic Band (NEB) calculations.

# Simple NEB between current dir and target dir
imdg derive . neb target_dir --nimages 5

# Complex diffusion analysis: find all unique paths between stable sites
imdg derive prototype_dir neb_diffusion --diffusion_points site1_dir site2_dir site3_dir --nimages 5

The neb_diffusion subcommand analyzes the topology of interstitial sites and automatically generates unique diffusion paths between them.

imdg diff

Compare structures or input parameters between directories.

# Compare structures in directories, grouping identical ones
imdg diff structure dir1 dir2 dir3

# Compare INCAR files, showing differences
imdg diff incar dir1 dir2

imdg visualize

Generate visual summaries of calculations.

neb

Visualize converged NEB trajectories as CIF files.

imdg visualize neb

imdg visualize neb scans the directory tree for NEB runs. For each converged NEB run, it writes a NEB_trajectory_converged.cif file containing all images along the minimum-energy path.

atat

Visualise ATAT cluster-expansion results.

# Requires running inside an ATAT directory
imdg visualize atat [--plot_extra <dirs>] \
  [--cmin <min>] [--cmax <max>]

Output files (written inside each ATAT directory):

  • atat-summary-test.png / atat-summary-test.svg: Six-panel summary figure (fitted energies, calculated energies, calculated-vs-fitted, fit residuals, sublattice deviation, ECI-vs-cluster-diameter).

  • fit2.out: fit.out augmented with a sublattice deviation column (NaN for unconverged runs or when sublattice flip is detected).

  • <extradir>.out: Extra energy points from --plot_extra dirs (only when the option is used).

hull

Plot a formation-energy convex hull from VASP outputs or a pickle file.

# From a directory tree of VASP calculations
imdg visualize hull . --ion Li [options]

# From a pickle file containing a DataFrame with ASE Atoms
imdg visualize hull results.pkl --ion Na [options]

Output files (written in the current working directory):

  • formation_en.<format> (default: formation_en.png): Phase diagram plot (density --dpi, default 600). A formation_en.svg is also saved unless the requested format is svg.

  • formation_en.txt: All entries (both ground state and above hull) in space-separated columns: ID, Energy, Concentration, Formation Energy (meV/atom), Energy above hull (meV/atom), Formula.

  • formation_en_gs.txt: Same format, ground-state entries only.

  • formation_en_min.txt: Minimum-energy entry per reduced composition: ID, Energy, Formation energy (meV/atom), Energy above hull (meV/atom), Reduced formula.

The command reads entries from VASP directories recursively (optionally filtered with --include / --exclude) or from a pickle file. Pure-element references for both the working ion (--ion) and the host matrix must be present in the data.

voltage

Plot a voltage profile from VASP outputs or a pickle file.

# From a directory tree of VASP calculations
imdg visualize voltage . --ion Li [options]

# From a pickle file
imdg visualize voltage results.pkl --ion K [options]

Output files (written in the directory specified on the command line):

  • voltage.<format> (default: voltage.png): Voltage profile plot. A voltage.svg is also saved unless the requested format is svg.

  • voltage.out: Voltage profile data in space-separated columns: x (working-ion fraction), voltage (V), capacity (mAh/g, normalised by the most-discharged host).

The command uses pymatgen’s InsertionElectrode machinery on the same entry-reading pipeline as hull. The x-axis of the plot can be set with --xaxis (choices: frac_x, x_form, capacity_grav, capacity_vol).

pmg-insert-molecule

Systematically insert a molecule or atom into a host structure at various positions and orientations, making sure to cover all viable positions without overlaps.

# Insert water molecule into host.cif, stepping 0.5A grid, rotating 45 degrees
pmg-insert-molecule water.xyz host.cif output_dir --step 0.5 --anglestep 45

There is also imdg ins subcommand counterpart that can directly use VASP folder as input.