pyvcham 1.0.0

A scientific module for vibrational coupling Hamiltonian analysis.

PyVCHAM

PyVCHAM is an open-source Python package designed to construct vibronic coupling (VC) Hamiltonians for complex molecular systems where the Born-Oppenheimer approximation fails. Leveraging machine learning techniques, specifically automatic differentiation via TensorFlow, PyVCHAM optimizes Hamiltonian parameters efficiently and accurately. It is built to integrate seamlessly with quantum chemistry tools, enabling high-dimensional nonadiabatic dynamics simulations with enhanced flexibility and precision.

Key Features

• Automatic Differentiation: Uses TensorFlow to compute precise gradients of cost functions, improving optimization efficiency.
• Quantum Chemistry Integration: Interfaces with tools such as OpenMolcas and ADC-connect for ab initio data input.
• Standardized JSON Format: Proposes a structured JSON format for storing VC Hamiltonians, enhancing interoperability with dynamics software like MCTDH.
• Modular Design: Supports custom diabatic or coupling functions to adapt to specific research needs.
• Robust Optimization: Employs the Adam algorithm for parameter fitting, with support for linear and higher-order vibronic coupling terms.
• Symmetry Handling: Incorporates symmetry constraints to ensure physically meaningful coupling terms.

Installation

PyVCHAM requires Python 3.9+ (tested up to 3.12). We strongly recommend using a fresh Conda environment to manage dependencies like TensorFlow and NumPy.

Step 1: Create the Environment

Choose the instructions matching your operating system:

A. Linux / Windows / Intel Macs

Standard installation for most users.

conda create --name pyvcham python=3.12
conda activate pyvcham

B. Apple Silicon (M1/M2/M3) [Recommended]

To ensure TensorFlow utilizes your Mac's GPU (Metal) and avoids architecture conflicts, force a native ARM environment:

# 1. Create a native arm64 environment
CONDA_SUBDIR=osx-arm64 conda create -n pyvcham python=3.12

# 2. Activate it
conda activate pyvcham

# 3. Permanently lock the architecture configuration
conda config --env --set subdir osx-arm64

# 4. Verify architecture (Output must be 'arm64')
python -c "import platform; print(platform.machine())"

Step 2: Install PyVCHAM

Once your environment is active, ensure pip is up to date (crucial for resolving modern wheels) and then install the package.

# 1. Upgrade pip
python -m pip install --upgrade pip

# 2. Install PyVCHAM
pip install pyvcham

For Developers

If you want to modify the source code:

git clone https://gitlab.com/tc-heidelberg/pyvcham.git
cd pyvcham
pip install -e ".[dev]"

Running Examples

If you plan to run the tutorials or examples provided in the documentation, please install Pandas:

pip install pandas

Usage

PyVCHAM enables the construction of VC Hamiltonians using a multi-point approach, fitting ab initio data to analytical potential energy surfaces. A typical workflow includes:

1. Prepare Input Data: Gather normal mode data, ab initio energies, symmetry information, and harmonic frequencies.
2. Build Database: Create a Python object containing the input data.
3. Optimize Parameters: Use PyVCHAM to fit the VC Hamiltonian parameters, starting with linear vibronic coupling (LVC) and adding higher-order terms as needed.
4. Export Results: Save the optimized Hamiltonian in the standardized JSON format.

For detailed examples and instructions, refer to the documentation.

Standardized JSON Format

PyVCHAM introduces a standardized JSON format to store VC Hamiltonians, promoting data exchange and compatibility with quantum dynamics tools. The format includes:

• General Data: System-wide details, ab initio information, and custom functions.
• VC Hamiltonian: Reference geometry, units, state and mode counts, symmetry data, vertical energies, dipole matrices, and LVC parameters.
• Interactions (optional): Parameters for intermolecular interactions in multi-molecule systems.

This structure ensures portability and usability across platforms. Explore examples in the repository (e.g., Examples/li3/results/lvc_li3.json).

License

PyVCHAM is released under the MIT License.

Citations

If you use PyVCHAM in your research, please cite our paper:

[In preparation]

PyVCHAM builds on foundational work in vibronic coupling, including:

• Köppel, H.; Domcke, W.; Cederbaum, L. S. "Multimode Molecular Dynamics Beyond the Born-Oppenheimer Approximation," Advances in Chemical Physics 1984, 57, 59–246.