Skip to content

X-Hydrogen/IQCAP

Repository files navigation

IQCAP -- Intelligent Quantum Chemistry Analysis Platform

IQCAP — Intelligent Quantum Chemistry Analysis Platform

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.


1. Overview

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.


2. Software Architecture

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

2.1 Module Overview

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.


3. System Requirements

3.1 Operating System

  • Linux (recommended: Ubuntu 20.04+, CentOS 7+)
  • Bash 4.0 or higher

3.2 Third-Party Dependencies

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)

3.3 Python Environment

  • 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

4. Input and Output

4.1 Input

  • 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.

4.2 Output

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)

5. Functional Modules

5.1 Core Ground-State Workflow (iqcap-opt.sh + iqcap-basic_elect_analysis.sh)

5.1.1 Geometry Optimization (iqcap-opt.sh)

  • 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.xyz and downstream-reusable wavefunction artifacts when available

5.1.2 Multi-Charge-State Single-Point Calculations (iqcap-basic_elect_analysis.sh)

  • Automatic single-point calculations for N (neutral), N+1 (anion), and N-1 (cation) states
  • Automatic spin multiplicity inference with electron-count parity validation

5.1.3 ESP Surface Mapping

  • Maps electrostatic potential onto the molecular density isosurface
  • Generates three-view renders (front/side/top) with BGR colorbar, isovalue annotation, and surface extrema

5.1.4 Frontier Orbital Visualization

  • Exports HOMO and LUMO orbital cube files with positive/negative isosurface rendering
  • Composes annotated side-by-side panel (with isovalue and phase legend)

5.1.5 Fukui Reactivity Descriptors

  • Computes f+, f-, f0, and Df (dual descriptor) via multi-charge-state density differences
  • Generates annotated 2x2 panel image

5.1.6 NCI / RDG Weak Interaction Analysis

  • Computes RDG isosurface colored by sign(lambda2)*rho
  • Generates three-view isosurface renders and scatter plot

5.1.7 Charge and Bond Order Analysis

  • Hirshfeld charge population
  • Mayer bond order

5.1.8 Conceptual DFT (CDFT)

  • Computes chemical potential, hardness, electrophilicity, and related CDFT indices via Multiwfn

5.2 Weak Interaction Analysis (iqcap-elect_interaction.sh)

5.2.1 chgdiff (Differential Charge Density)

  • Computes Δρ = ρ(AB) − ρ(A) − ρ(B) between fragment 1 and fragment 2
  • Three-view images (front/side/top) with Fukui-style yellow-blue coloring

5.2.2 NCI / RDG Analysis

  • Noncovalent interaction isosurface and scatter plot (no fragment definition required)

5.2.3 IGMH Analysis

  • Independent Gradient Model based on Hirshfeld partition
  • User-defined molecular fragment specification
  • Generates dg_inter isosurface three-view renders (BGR coloring) and scatter plot

5.2.4 IRI Analysis

  • Interaction Region Indicator (fine grid, smooth isosurface)
  • Simultaneously visualizes covalent and weak interactions

5.2.5 HS (Hirshfeld Surface) Analysis

  • 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

5.2.6 CDA (Charge Decomposition Analysis)

  • 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

5.3 Transition State & Reaction Path Engine (iqcap-ts.sh)

5.3.1 Endpoint Optimization

  • Optional geometry optimization of reactant and product at the calculation level
  • Ensures consistent energy surface for NEB and barrier calculations

5.3.2 NEB Path Search

  • 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

5.3.3 TS Optimization and Frequency Verification

  • 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)

5.3.4 IRC Path Tracing

  • 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

5.3.5 Single-Point Energy Refinement

  • 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

5.3.6 Energy Profile Visualization

  • 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

5.3.7 TS Structure Rendering

  • VMD three-view rendering of the optimized TS structure
  • Annotated with imaginary frequency value

5.3.8 TS Validation and Diagnostics

  • 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.

6. Usage Examples

6.1 Basic Analysis (Core Workflow)

# 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

6.2 Differential Charge Density (chgdiff)

# 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

6.3 Weak Interactions and Charge Decomposition

# 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

6.4 Transition State & Reaction Path Analysis

# 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

6.5 Complete Workflow Example

# 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

7. Command-Line Reference

iqcap-opt.sh

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

iqcap-basic_elect_analysis.sh

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

iqcap-elect_interaction.sh

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

iqcap-ts.sh

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

8. Version Information

  • Current version: v1.5.0
  • Release date: 2026-03-02
  • Development language: Bash / Python 3
  • Total lines of code: approximately 13,300

9. Key Technical Features

  1. End-to-end automation: From XYZ structure input to publication-quality image output with no manual intervention
  2. Intelligent parameter inference: Automatic spin multiplicity inference for multi-charge states with electron-count parity validation
  3. Publication-quality visualization: All images rendered at 2400x1800 resolution with orthographic projection ray tracing, automatic colorbar, annotation, and legend
  4. Modular architecture: Independent module switches for on-demand composition
  5. Fault tolerance and self-checking: Automatic dependency detection, input parameter validation, and convergence verification
  6. Cross-platform compatibility: Supports multiple Multiwfn/VMD naming conventions with automatic executable path resolution

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors