Version: 1.5.0 Author: Hengyue Xu ORCiD: 0000-0003-4438-9647 Date: 2026-03-02 Copyright: (C) 2024-2026 Hengyue Xu. All rights reserved.
IQCAP (Intelligent Quantum Chemistry Analysis Platform) is an automated quantum chemistry analysis platform designed for molecular design and materials research. Through a systematic modular architecture, it automates the complete pipeline from molecular structure input to electronic structure analysis and publication-quality visualization output, significantly improving computational efficiency and reproducibility.
Users only need to provide a molecular structure file (.xyz format) to automatically perform the following analyses:
- Geometry optimization
- Multi-charge-state single-point energy calculations (N / N+1 / N-1)
- Electrostatic potential (ESP) surface mapping with three-view rendering
- Frontier orbital (HOMO / LUMO) visualization
- Fukui reactivity descriptors (f+, f-, f0, Df dual descriptor) with 2x2 panel rendering
- NCI / RDG weak interaction analysis (isosurface + scatter plot)
- Hirshfeld charge population
- Mayer bond order analysis
- Conceptual DFT (CDFT) reactivity indices
- IGMH (Independent Gradient Model based on Hirshfeld partition) weak interaction analysis
- IRI (Interaction Region Indicator) analysis
- HS (Hirshfeld Surface) analysis with fingerprint plot and element contact area statistics
- CDA (Charge Decomposition Analysis) with orbital interaction diagrams
- Transition state search via NEB-CI / NEB-TS with automatic TS optimization and frequency verification
- IRC (Intrinsic Reaction Coordinate) path tracing with publication-quality energy profile plots
- Single-point energy refinement at higher theory levels for publication-quality barriers
The platform uses a modular design with good extensibility for integrating additional computational and analysis methods.
Important disclaimer: This software is a workflow orchestration and analysis platform. It invokes third-party programs for computation and visualization but does NOT include the third-party program binaries (ORCA, Multiwfn, VMD). Users must obtain and install those programs independently under their respective licenses.
iqcap/
IQCAP.png Promotional banner (README)
bin/
iqcap-opt.sh Geometry optimization module
iqcap-basic_elect_analysis.sh Basic electronic structure analysis
iqcap-elect_interaction.sh Weak Interaction Analysis (NCI/IGMH/IRI/HS/chgdiff/CDA)
iqcap-ts.sh Transition State & Reaction Path Analysis Engine
... Auxiliary utilities (G, summary, report, plotting helpers)
README.md Software documentation (English)
README_zh.md Software documentation (Chinese)
CHANGELOG.md Version history
LICENSE.txt License declaration
| Module | File | Description |
|---|---|---|
| Geometry Optimization | iqcap-opt.sh |
Standalone geometry optimization, two-step optimization, or single-point-only preparation |
| Basic Electronic Analysis | iqcap-basic_elect_analysis.sh |
Multi-state SP -> ESP/orbital/Fukui/NCI visualization -> charges/bond order -> CDFT |
| Weak Interaction Analysis | iqcap-elect_interaction.sh |
NCI/IGMH/IRI/HS/chgdiff/CDA (IGMH/HS/chgdiff/CDA require fragment definition) |
| TS & Reaction Path Engine | iqcap-ts.sh |
NEB-CI path search -> OptTS + freq verification -> IRC path -> energy profile |
The main ground-state workflow is sequential: iqcap-opt.sh prepares the
optimized structure, iqcap-basic_elect_analysis.sh performs the core
electronic-structure analysis, and iqcap-elect_interaction.sh reuses the core
workflow outputs (opt.xyz, *.molden.input, and related volumetric data when
available).
Auxiliary utilities such as iqcap-G.sh, iqcap-summary.sh, and
iqcap-report.sh are optional helpers and are not required for the core
pipeline.
The TS & Reaction Path module is independent and operates on reactant/product XYZ files directly.
- Linux (recommended: Ubuntu 20.04+, CentOS 7+)
- Bash 4.0 or higher
| Program | Version | Purpose |
|---|---|---|
| ORCA | 5.0+ | Quantum chemistry engine (geometry optimization, single-point calculations, NEB, IRC) |
| orca_2aim | Bundled with ORCA | Wavefunction file format conversion |
| orca_2mkl | Bundled with ORCA | Molden-format wavefunction export |
| Multiwfn | 3.8+ | Wavefunction analysis (ESP, orbitals, Fukui, NCI, IGMH, IRI, CDA, CDFT) |
| VMD | 1.9.3+ | Molecular and isosurface visualization (TachyonInternal ray tracing) |
- Python 3.6 or higher
- Required packages:
| Package | Purpose |
|---|---|
| numpy | Fukui cube file arithmetic, NCI data masking |
| scipy | Grid interpolation for differential charge density (chgdiff module) |
| Pillow | TGA-to-PNG conversion, colorbar annotation, panel composition |
| matplotlib | NCI/RDG/IGMH/IRI scatter plots, CDA orbital interaction diagrams |
Installation:
pip install numpy scipy Pillow matplotlib- Molecular structure file: Standard XYZ format (
.xyz) containing atom count, comment line, and atomic coordinates - Command-line arguments: Charge/spin multiplicity, compute resources, module switches, visualization parameters, etc.
| Output Type | File Format | Description |
|---|---|---|
| Optimized structure | opt.xyz |
Molecular coordinates after geometry optimization convergence |
| Wavefunction files | .molden.input, .wfn |
Wavefunction data readable by Multiwfn |
| Volumetric data | .cub / .cube |
3D grid data for electron density, ESP, orbitals, Fukui, NCI |
| Visualization images | .png |
High-resolution (2400x1800) publication-quality images with colorbar annotations |
| Analysis logs | .txt, .out |
Hirshfeld charges, Mayer bond orders, CDFT indices, CDA data |
| Scatter plots | .png |
NCI/IGMH/IRI sign(lambda2)*rho vs RDG/dg/IRI scatter plots |
| Fingerprint plot | .png |
HS d_i vs d_e fingerprint scatter plot (viridis colormap) |
| Contact area statistics | .txt, .png |
HS element contact area table and pie chart |
| Orbital diagrams | .png |
CDA orbital interaction energy-level diagrams |
| Energy profiles | .png |
TS energy barrier diagrams with multi-unit annotations |
| IRC path plots | .png |
Reaction coordinate vs energy along the IRC |
| Energy data | .csv, .txt |
Barrier energies in Hartree / eV / kcal/mol / kJ/mol |
| TS validation panel | .png |
Combined vibrational spectrum, imaginary-mode view, and IRC curve |
| Mode projection plot | .png |
Decomposition of the imaginary mode onto internal coordinates (bond lengths/angles) |
| IRC internal coordinates | .png |
Evolution of key bond lengths/angles along the IRC path |
| NEB convergence diagnostics | .png |
Convergence history of band and climbing-image forces and barrier height |
| IRC animation | .gif |
Animated structural change along the IRC (front/side/top views) |
- DFT-level geometry optimization using ORCA
- Supports direct publication-quality optimization, low+high two-step optimization, and single-point-only preparation modes
- Writes
optimization/opt.xyzand downstream-reusable wavefunction artifacts when available
- Automatic single-point calculations for N (neutral), N+1 (anion), and N-1 (cation) states
- Automatic spin multiplicity inference with electron-count parity validation
- Maps electrostatic potential onto the molecular density isosurface
- Generates three-view renders (front/side/top) with BGR colorbar, isovalue annotation, and surface extrema
- Exports HOMO and LUMO orbital cube files with positive/negative isosurface rendering
- Composes annotated side-by-side panel (with isovalue and phase legend)
- Computes f+, f-, f0, and Df (dual descriptor) via multi-charge-state density differences
- Generates annotated 2x2 panel image
- Computes RDG isosurface colored by sign(lambda2)*rho
- Generates three-view isosurface renders and scatter plot
- Hirshfeld charge population
- Mayer bond order
- Computes chemical potential, hardness, electrophilicity, and related CDFT indices via Multiwfn
- Computes Δρ = ρ(AB) − ρ(A) − ρ(B) between fragment 1 and fragment 2
- Three-view images (front/side/top) with Fukui-style yellow-blue coloring
- Noncovalent interaction isosurface and scatter plot (no fragment definition required)
- Independent Gradient Model based on Hirshfeld partition
- User-defined molecular fragment specification
- Generates dg_inter isosurface three-view renders (BGR coloring) and scatter plot
- Interaction Region Indicator (fine grid, smooth isosurface)
- Simultaneously visualizes covalent and weak interactions
- Constructs the Hirshfeld surface for a user-defined fragment and maps promolecular electron density onto it
- Three-view renders (front/side/top) with BWR colorbar (blue = weak, white = moderate, red = strong interaction)
- Fingerprint scatter plot (d_i vs d_e, viridis colormap) for interaction characterization
- Element contact area statistics with pie chart and tabulated data
- Only requires atomic coordinates (no wavefunction needed), very fast even for large systems
- Automatic fragment geometry extraction and fragment single-point calculations
- Computes d (charge donation), b (back-donation), r (polarization)
- Generates full orbital interaction energy-level diagram and focused publication diagram (HOMO-2 to LUMO+2)
- Renders 3D isosurface images of key orbitals
- Optional geometry optimization of reactant and product at the calculation level
- Ensures consistent energy surface for NEB and barrier calculations
- NEB-CI (Climbing Image NEB, default) or NEB-TS for transition state guess
- NEB-CI drives the highest-energy image toward the true saddle point
- Configurable number of interpolation images and convergence criteria
- ORCA OptTS with automatic numerical Hessian for initial TS search direction
- Combined OptTS + NumFreq for efficiency
- Automatic verification: confirms exactly one imaginary frequency (true first-order saddle point)
- Intrinsic Reaction Coordinate in both directions from the TS
- Confirms the TS connects the expected reactant and product
- Extracts IRC endpoint structures for energy comparison
- SP calculations on reactant, TS, product, and IRC endpoints
- Supports a higher theory level than geometry optimization (e.g., DLPNO-CCSD(T)/def2-TZVPP//B3LYP-D3/def2-TZVP)
- Outputs energy barriers in Hartree, eV, kcal/mol, and kJ/mol
- Publication-quality energy profile diagram with barrier annotations
- Forward barrier (ΔE‡), reverse barrier (ΔE‡_rev), and reaction energy (ΔE_rxn)
- Dual-unit display (kcal/mol and kJ/mol)
- IRC path plot showing energy vs reaction coordinate
- VMD three-view rendering of the optimized TS structure
- Annotated with imaginary frequency value
- TS validation panel combining vibrational spectrum, 2D projection of the imaginary mode, and IRC energy curve.
- Imaginary-mode projection onto internal coordinates (bond lengths/angles) to highlight which bonds stretch, compress, or bend.
- IRC internal-coordinate plots for key bond lengths/angles vs IRC step to aid mechanism analysis.
- NEB convergence diagnostics panel showing band and climbing-image force convergence and barrier-height convergence.
- Automatic IRC animation GIFs for three orthogonal views.
# Step 1: geometry optimization
bash iqcap-opt.sh --mode 1 --xyz 0.xyz --n-charge 0 --n-mult 1
# Step 2: electronic-structure analysis on the optimized geometry
bash iqcap-basic_elect_analysis.sh --xyz 0.xyz --n-charge 0 --n-mult 1
# Two-step optimization for difficult systems
bash iqcap-opt.sh --mode 2 --xyz molecule.xyz --n-charge 0 --n-mult 1
# Re-render figures only from an existing calculation
bash iqcap-basic_elect_analysis.sh --xyz 0.xyz --plot-only
# ESP and orbitals only, skip Fukui / molecule-view / charge / bond-order output
bash iqcap-basic_elect_analysis.sh --no-fukui-plot --no-mol-view --no-charges --no-bondorder
# Custom compute resources
bash iqcap-opt.sh --mode 1 --xyz molecule.xyz --nprocs 32 --maxcore 8192
bash iqcap-basic_elect_analysis.sh --xyz molecule.xyz --nprocs 32 --maxcore 8192
# Show version information
bash iqcap-opt.sh --version
bash iqcap-basic_elect_analysis.sh --version# H2O: fragment 1 = atoms 1-2 (O, first H), fragment 2 = atom 3 (second H)
bash iqcap-elect_interaction.sh --only-chgdiff --frag1-atoms "1-2" --frag2-atoms "3"
# Custom fragment indices
bash iqcap-elect_interaction.sh --only-chgdiff --frag1-atoms "1,3,5" --frag2-atoms "2,4,6" --chgdiff-iso 0.0008# Water dimer (6 atoms): fragment 1 = atoms 1-3, fragment 2 = atoms 4-6
bash iqcap-elect_interaction.sh --frag1-atoms "1-3" --frag2-atoms "4-6"
# HS only (Hirshfeld Surface analysis)
bash iqcap-elect_interaction.sh --only-hs --frag1-atoms "1-3" --frag2-atoms "4-6"
# CDA only, skip NCI/IGMH/IRI/HS/chgdiff
bash iqcap-elect_interaction.sh --only-CDA --frag1-atoms "1-3" --frag2-atoms "4-6"
# Custom IGMH isosurface
bash iqcap-elect_interaction.sh --frag1-atoms "1-3" --frag2-atoms "4-6" \
--igmh-iso 0.005 --igmh-color-min -0.03 --igmh-color-max 0.015
# Show version information
bash iqcap-elect_interaction.sh --version# Full pipeline: NEB-CI -> OptTS + Freq -> IRC -> SP -> energy profile
bash iqcap-ts.sh --reactant reactant.xyz --product product.xyz
# Provide a TS guess directly (skip NEB)
bash iqcap-ts.sh --reactant reactant.xyz --product product.xyz \
--ts-guess ts_guess.xyz
# Use NEB-TS instead of NEB-CI
bash iqcap-ts.sh --neb-method NEB-TS --neb-nimages 12
# Fast testing with low-precision DFT (default)
bash iqcap-ts.sh --reactant reactant.xyz --product product.xyz
# Production run with high-level SP refinement
bash iqcap-ts.sh --reactant reactant.xyz --product product.xyz \
--opt-level "B3LYP D3 def2-TZVP(-f) def2/J RIJCOSX" \
--sp-level "DLPNO-CCSD(T) def2-TZVPP def2-TZVPP/C tightSCF"
# Skip endpoint optimization (pre-optimized structures)
bash iqcap-ts.sh --skip-opt-endpoints
# IRC only (with existing TS)
bash iqcap-ts.sh --ts-guess ts.xyz --no-neb --no-optts --no-freq# Step 1: Prepare molecular structure file
# Save molecular coordinates in XYZ format as 0.xyz
# Step 2: Optimize the geometry
bash iqcap-opt.sh --mode 1 --xyz 0.xyz --n-charge 0 --n-mult 1
# Step 3: Run the basic electronic-structure workflow
bash iqcap-basic_elect_analysis.sh --xyz 0.xyz --n-charge 0 --n-mult 1
# Step 4: Run weak interaction analysis (for intermolecular interaction analysis)
bash iqcap-elect_interaction.sh --frag1-atoms "1-3" --frag2-atoms "4-6"
# Step 5: Run transition state and reaction path analysis (independent workflow)
cd reaction_dir/
bash iqcap-ts.sh --reactant reactant.xyz --product product.xyz
# Output results are saved in subdirectories of the current directory| Parameter | Type | Default | Description |
|---|---|---|---|
--mode |
INT | 1 | 1 = direct optimization, 2 = low+high two-step optimization, 3 = single-point-only preparation |
--xyz |
FILE | 0.xyz | Input structure file |
--output-dir |
DIR | optimization | Output directory |
--n-charge |
INT | 0 | Molecular charge |
--n-mult |
INT | 1 | Spin multiplicity |
--nprocs |
INT | 16 | Number of parallel processes |
--maxcore |
INT | 4096 | Memory per process (MB) |
--opt-low |
STR | B3LYP D3 def2-SVP def2/J RIJCOSX opt |
Low-level optimization for mode 2 |
--opt-pub |
STR | B3LYP D3 def2-TZVP(-f) def2/J RIJCOSX opt |
Publication-level optimization |
--sp-level |
STR | B3LYP D3 def2-TZVP(-f) def2/J RIJCOSX tightSCF |
Single-point level for mode 3 |
-V, --version |
FLAG | - | Show version information |
-h, --help |
FLAG | - | Show help message |
| Parameter | Type | Default | Description |
|---|---|---|---|
--xyz |
FILE | 0.xyz | Reference XYZ file |
--sp-level |
STR | B3LYP D3 def2-TZVP(-f) def2/J RIJCOSX tightSCF |
ORCA single-point theory level |
--n-charge |
INT | 0 | Neutral-state charge |
--n-mult |
INT | 1 | Neutral-state multiplicity |
--nprocs |
INT | 16 | Number of parallel processes |
--maxcore |
INT | 4096 | Memory per process (MB) |
--no-multiwfn |
FLAG | - | Skip all Multiwfn-based analyses |
--no-cdft |
FLAG | - | Skip conceptual DFT analysis |
--no-esp-plot |
FLAG | - | Skip ESP rendering |
--no-mol-view |
FLAG | - | Skip pure molecule three-view rendering |
--no-homo-lumo-plot |
FLAG | - | Skip HOMO/LUMO rendering |
--no-fukui-plot |
FLAG | - | Skip Fukui rendering |
--no-charges |
FLAG | - | Skip Hirshfeld charges |
--no-bondorder |
FLAG | - | Skip Mayer bond-order analysis |
--plot-only |
FLAG | - | Re-render from existing data without recomputation |
--esp-iso |
FLOAT | 0.001 | ESP density isosurface |
--mo-iso |
FLOAT | 0.03 | Orbital isosurface value |
--fukui-iso |
FLOAT | 0.003 | Fukui isosurface value |
-V, --version |
FLAG | - | Show version information |
-h, --help |
FLAG | - | Show help message |
| Parameter | Type | Default | Description |
|---|---|---|---|
--frag1-atoms |
STR | - | Fragment 1 atom indices (required for IGMH/HS/chgdiff/CDA) |
--frag2-atoms |
STR | - | Fragment 2 atom indices |
--only-CDA |
FLAG | - | Run CDA only |
--only-chgdiff |
FLAG | - | Run chgdiff only |
--only-hs |
FLAG | - | Run HS only |
--igmh-iso |
FLOAT | 0.01 | IGMH isosurface value |
--iri-iso |
FLOAT | 1.0 | IRI isosurface value |
--hs-color-min |
FLOAT | 0.0 | HS color scale lower bound (promol. density) |
--hs-color-max |
FLOAT | 0.015 | HS color scale upper bound (promol. density) |
--no-igmh |
FLAG | - | Skip IGMH analysis |
--no-iri |
FLAG | - | Skip IRI analysis |
--no-hs |
FLAG | - | Skip HS analysis |
--no-cda |
FLAG | - | Skip CDA analysis |
-V, --version |
FLAG | - | Show version information |
-h, --help |
FLAG | - | Show help message |
| Parameter | Type | Default | Description |
|---|---|---|---|
--reactant |
FILE | reactant.xyz | Reactant structure file |
--product |
FILE | product.xyz | Product structure file |
--ts-guess |
FILE | - | TS initial guess (skips NEB) |
--charge |
INT | 0 | Molecular charge |
--mult |
INT | 1 | Spin multiplicity |
--nprocs |
INT | 16 | Number of parallel processes |
--maxcore |
INT | 4096 | Memory per process (MB) |
--opt-level |
STR | PBE D3 def2-SVP def2/J | ORCA theory for geometry/NEB/TS/IRC |
--sp-level |
STR | (same as opt-level) | ORCA theory for SP energy refinement |
--neb-method |
STR | NEB-CI | NEB-CI or NEB-TS |
--neb-nimages |
INT | 8 | Number of NEB interpolation images |
--neb-maxiter |
INT | 500 | Max NEB iterations |
--irc-maxiter |
INT | 50 | Max IRC steps per direction |
--irc-stepsize |
FLOAT | 0.3 | IRC step size (Bohr·amu^0.5) |
--irc-maxdisp |
FLOAT | 0.5 | Max IRC displacement per step |
--skip-opt-endpoints |
FLAG | - | Skip endpoint optimization |
--no-neb |
FLAG | - | Skip NEB (requires --ts-guess) |
--no-irc |
FLAG | - | Skip IRC path tracing |
--no-sp-refine |
FLAG | - | Skip SP energy refinement |
--no-eprofile |
FLAG | - | Skip energy profile plot |
--no-irc-plot |
FLAG | - | Skip IRC path plot |
--no-ts-render |
FLAG | - | Skip VMD TS rendering |
--no-ts-panel |
FLAG | - | Skip TS validation panel |
--no-mode-proj |
FLAG | - | Skip imaginary-mode projection plot |
--no-irc-coords |
FLAG | - | Skip IRC internal-coordinates plot |
--no-neb-conv |
FLAG | - | Skip NEB convergence diagnostics plot |
--no-irc-anim |
FLAG | - | Skip IRC animation GIFs |
--mol-zoom |
FLOAT | 1.00 | VMD zoom factor for TS renders |
--monitor-bonds |
STR | - | Comma-separated atom pairs to track along IRC, e.g. "1-2,2-3" |
--vmd-bin |
PATH | auto-detect | Override VMD executable path |
-V, --version |
FLAG | - | Show version information |
-h, --help |
FLAG | - | Show help message |
- Current version: v1.5.0
- Release date: 2026-03-02
- Development language: Bash / Python 3
- Total lines of code: approximately 13,300
- End-to-end automation: From XYZ structure input to publication-quality image output with no manual intervention
- Intelligent parameter inference: Automatic spin multiplicity inference for multi-charge states with electron-count parity validation
- Publication-quality visualization: All images rendered at 2400x1800 resolution with orthographic projection ray tracing, automatic colorbar, annotation, and legend
- Modular architecture: Independent module switches for on-demand composition
- Fault tolerance and self-checking: Automatic dependency detection, input parameter validation, and convergence verification
- Cross-platform compatibility: Supports multiple Multiwfn/VMD naming conventions with automatic executable path resolution
