CP2K-RS: Rust and Python bindings for CP2K

This project provides Rust bindings for the CP2K quantum chemistry package, with Python bindings generated using PyO3.

Requirements

• Rust toolchain (install via rustup)
• Git (for cloning CP2K)
• Fortran compiler (gfortran)
• MPI library (e.g., OpenMPI or MPICH)
• BLAS, LAPACK, and ScaLAPACK libraries
• Python 3.7+ (for Python bindings)
• Other CP2K dependencies:
  • libxc
  • libint
  • FFTW
  • zlib

Installing Dependencies on Ubuntu/Debian

sudo apt update
sudo apt install build-essential gfortran libopenmpi-dev libscalapack-mpi-dev \
    liblapack-dev libblas-dev libfftw3-dev libxc-dev libz-dev git python3-dev python3-pip

Installing Dependencies on Fedora/RHEL/CentOS/Rocky Linux

sudo dnf install gcc-gfortran openmpi-devel scalapack-openmpi-devel \
    lapack-devel blas-devel fftw-devel libxc-devel zlib-devel git python3-devel \
    cmake make pkgconfig environment-modules

After installation, you need to load the MPI module:

module load mpi/openmpi-x86_64

Building

Development Mode (Header-only)

For development and testing without building CP2K:

cargo build --release

This mode uses only the CP2K headers and allows for fast compilation and testing of the Rust bindings.

Production Mode (With CP2K Library)

To build with the actual CP2K library for full functionality:

Option 1: Using the Build Script (Recommended)

./build_with_cp2k.sh

This script will:

• Check all prerequisites
• Verify available disk space and resources
• Configure optimal build settings
• Guide you through the build process

Option 2: Manual Build with Environment Variable

CP2K_RS_BUILD_CP2K=1 cargo build --release --features build-cp2k

Option 3: Manual Build with Feature Flag

cargo build --release --features build-cp2k

⚠️ Important Notes:

• Building CP2K from source takes 30+ minutes on most systems
• Requires 4+ GB of free disk space
• Requires all CP2K dependencies to be installed (see requirements above)
• Uses parallel compilation (adjustable with NUM_JOBS=N environment variable)

Quick Test Build

To verify everything compiles without building CP2K:

cargo check --all-features

With Python Bindings

pip install maturin
maturin build --release --features python
pip install target/wheels/cp2k_python-*.whl

Configuration

By default, CP2K is built with MPI and OpenMP support. If you want to customize the build, you can modify the build.rs file to specify different build options.

Using in Rust

use cp2k_rs::{init, finalize, ForceEnv};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize CP2K
    init()?;
    
    // Create a force environment from input files
    let mut force_env = ForceEnv::new("input.inp", "output.out")?;
    
    // Run some calculations
    force_env.calc_energy_force()?;
    let energy = force_env.get_potential_energy()?;
    let forces = force_env.get_forces()?;
    
    println!("Energy: {}", energy);
    println!("Forces: {:?}", forces);
    
    // Cleanup happens automatically when force_env goes out of scope
    
    // Finalize CP2K
    finalize()?;
    Ok(())
}

Using in Python

import cp2k_rs as cp2k
import numpy as np

# Initialize CP2K
cp2k.init_cp2k()

# Get the CP2K version
version = cp2k.get_cp2k_version()
print(f"CP2K version: {version}")

# Create a force environment from input files
force_env = cp2k.PyForceEnv("input.inp", "output.out")

# Run some calculations
force_env.calc_energy_force()
energy = force_env.get_potential_energy()
forces = force_env.get_forces()

print(f"Energy: {energy}")
print(f"Forces shape: {forces.shape}")

# Clean up
cp2k.finalize_cp2k()

Troubleshooting

Development Mode Issues

If you encounter build issues in header-only mode:

1. Make sure Rust toolchain is installed: rustup update
2. Install basic dependencies: sudo dnf install clang-devel llvm-devel (Rocky Linux)
3. For MPI features: module load mpi/openmpi-x86_64

Production Mode (CP2K Build) Issues

Build Fails with Missing Dependencies

# Install all required dependencies first:
sudo dnf install gcc-gfortran openmpi-devel scalapack-openmpi-devel \
    lapack-devel blas-devel fftw-devel libxc-devel zlib-devel cmake make

# Load MPI module
module load mpi/openmpi-x86_64

# Set library paths if needed
export LIBRARY_PATH=/usr/lib64/openmpi/lib:$LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/lib64/openmpi/lib:$LD_LIBRARY_PATH

Build Takes Too Long

# Use fewer parallel jobs to reduce memory usage
NUM_JOBS=2 CP2K_RS_BUILD_CP2K=1 cargo build --release --features build-cp2k

Out of Disk Space

CP2K compilation requires ~4GB of space. Clean up or use:

# Build in a different directory
export CARGO_TARGET_DIR=/path/to/large/disk/target

Architecture-specific Issues

The build system creates architecture files for Linux x86_64. For other platforms:

1. Check the CP2K documentation for platform-specific build instructions
2. Modify the arch file generation in build.rs if needed

General Issues

If you encounter other build issues:

1. Make sure all dependencies are installed
2. You may need to set the LIBRARY_PATH and LD_LIBRARY_PATH environment variables to point to your MPI, BLAS, and LAPACK libraries
3. Check the CP2K documentation for platform-specific build instructions: https://github.com/cp2k/cp2k/blob/master/INSTALL.md
4. For Rocky Linux specifically, ensure environment modules are loaded properly

Prerequisites for Building CP2K

Before attempting to build with CP2K, ensure you have:

1. Sufficient Resources:

   • At least 4GB free disk space
   • 8GB+ RAM recommended
   • Multi-core CPU (build time scales with cores)

2. All Dependencies Installed:

   # Rocky Linux/RHEL/CentOS
   sudo dnf install gcc-gfortran openmpi-devel scalapack-openmpi-devel \
       lapack-devel blas-devel fftw-devel libxc-devel zlib-devel \
       cmake make pkgconfig git
   
   # Load MPI environment
   module load mpi/openmpi-x86_64
   

3. Network Access: The build downloads CP2K source code and dependencies

Build Timeline

• First build: 30-60 minutes (depending on system)
• Subsequent builds: 5-15 minutes (incremental)
• Clean rebuild: 30-60 minutes

Verifying the Build

After building with CP2K support, verify it works:

# Run the example (requires the CP2K library)
cargo run --example basic_usage --features build-cp2k

# Run tests with CP2K support
cargo test --features build-cp2k --test integration_tests

If the build was successful, you should see:

• CP2K version information
• Successful force environment creation
• Energy and force calculations

License

This project is licensed under the GPL-2.0-or-later license, same as CP2K.