Correlation: Advanced Atomistic Structural & Dynamic Analysis Suite

Correlation is a high-performance C++23 structural and dynamic analysis engine for atomistic simulations of liquids, amorphous solids, crystals, disordered networks, and soft-matter systems.

Built for modern HPC clusters and workstations, Correlation delivers multi-vendor GPU acceleration (CUDA, HIP, Intel oneAPI/SYCL), dynamic SIMD vectorization (AVX2, AVX-512), multi-threaded oneTBB scaling, memory-mapped multi-gigabyte trajectory parsing, a modern Slint GUI with multi-curve comparison overlays, and direct Python/PyTorch Geometric interoperability.

📑 Table of Contents

• Correlation: Advanced Atomistic Structural & Dynamic Analysis Suite
  • 📑 Table of Contents
  • 🌟 Key Capabilities
    • 📊 Scientific Calculator Suite
    • 📂 Comprehensive Format Support
    • ⚡ High-Performance Core & Multi-Vendor GPU
  • 📦 Installation
    • Pre-compiled Packages
    • Conda-Forge / Pixi
    • Building from Source
      • Prerequisites
      • Step-by-Step Build
    • CMake Build Options
  • 🚀 Usage Modes
    • 1. Graphical User Interface (GUI)
      • Key GUI Highlights:
    • 2. Command Line Interface (CLI)
      • Core CLI Arguments:
    • 3. Python Bindings & PyTorch Geometric
  • 👥 Authors & Citation
    • Corresponding Author
    • Contributors & Co-Authors
    • Citation
  • 📜 License
  • 🙏 Acknowledgments

🌟 Key Capabilities

📊 Scientific Calculator Suite

Correlation computes an extensive array of spatial, radial, angular, topological, electronic, and dynamic properties:

📂 Comprehensive Format Support

Native high-speed parsing with content-based format sniffing (ReaderFactory) for automatic detection of extensionless or generic .in/.out files:

• Quantum Chemistry & DFT: VASP (POSCAR, CONTCAR, XDATCAR), Quantum ESPRESSO (.pwi, .pwo, .in, .out), CP2K (.inp, .restart, .out), ORCA (.out), GPAW (.gpw), ABINIT (.abi), DFTB+ (.gen), CASTEP (.cell, .md), ONETEP (.dat), DMol³ / Materials Studio (.outmol, .car, .arc).
• Classical Molecular Dynamics: LAMMPS (.dump, .lammpstrj), GROMACS (.gro, .xtc, .trr), CHARMM / NAMD / Amber (.pdb, .ent).
• Crystallography & Exchange: Extended XYZ (.xyz, .exyz), Crystallographic Information (.cif).
• Export Targets: High-throughput tabular and binary export in CSV, HDF5 (.h5), Apache Arrow / Parquet (.parquet), SVG, PNG, and native vector PDF.

⚡ High-Performance Core & Multi-Vendor GPU

• Multi-Vendor GPU Acceleration: Unified GPU layer supporting NVIDIA (CUDA), AMD (HIP), and Intel (oneAPI / SYCL) for $S(Q)$, pairwise distance binning, Steinhardt order parameters, and XRD Debye scattering.
• SIMD Kernel Dispatch: Optimized runtime vector kernels utilizing AVX2, AVX-512, and scalar fallbacks.
• Configurable Precision (real_t): Native compile-time toggle between single-precision (float) and double-precision (double) execution via -DUSE_SINGLE_PRECISION=ON/OFF.
• Zero-Copy Memory-Mapped I/O: MappedFile architecture allows instant lazy frame seeking across multi-gigabyte trajectories without memory exhaustion.
• Numerical Stability: Project-wide Kahan compensated summation across numerical integrals, unwrapped trajectory tracking, and Debye scattering accumulators.

📦 Installation

Pre-compiled Packages

Download pre-built executables and installers from the GitHub Releases page:

• Linux: Portable AppImage, Debian/Ubuntu .deb, Fedora/RHEL/openSUSE .rpm
• macOS: Universal .dmg
• Windows: Standalone .exe installer

Conda-Forge / Pixi

Install the CLI and Python package via conda-forge:

# Using Conda / Mamba
conda install -c conda-forge correlation

# Using Pixi
pixi add correlation

Building from Source

Prerequisites

• C++ Compiler: Modern C++ compiler supporting C++23 (GCC 13+, Clang 16+, MSVC 2022+)
• CMake: Version 3.24 or higher
• Ninja or Make
• Rust & Cargo: (Required for Slint GUI compilation)
• Intel oneTBB: Threading Building Blocks development headers
• Optional: HDF5 (libhdf5-dev), Apache Arrow (libarrow-dev), FFTW3 (libfftw3-dev), CUDA Toolkit (12.0+) / Intel oneAPI DPC++.

Step-by-Step Build

# 1. Clone the repository
git clone https://github.com/Isurwars/Correlation.git
cd Correlation

# 2. Configure build with CMake
cmake -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_GUI=ON \
  -DBUILD_PYTHON_BINDINGS=ON

# 3. Compile
cmake --build build -j$(nproc)

# 4. Execute test suite (700+ tests)
ctest --test-dir build --output-on-failure

CMake Build Options

🚀 Usage Modes

1. Graphical User Interface (GUI)

Launch the modern Slint-based interface:

./build/src/correlation

Key GUI Highlights:

• Interactive 3-Column Layout: Seamlessly navigate between structure setup, parameter cards, bond cutoff matrices, and live plot rendering.
• Multi-Curve Comparison Overlay: Load and overlay multiple datasets or trajectories simultaneously, compute dynamic difference plots ($Y_{Diff} = Y_1 - Y_2$), and customize individual styles, dashes, and color palettes.
• Vector Publication Export: Export high-resolution plots directly to SVG, PNG, or native PDF with embedded normalized vector fonts and Greek character glyphs.
• Preset Configuration Manager: Save and load custom analysis presets for liquid, crystalline, or amorphous simulations.

2. Command Line Interface (CLI)

Execute headlessly in automated cluster pipelines using correlation-cli:

# Analyze RDF, CNA, and MSD from a VASP trajectory with HDF5 and CSV output
correlation-cli Trajectory.xdatcar -o ./output/run_1 \
  --calculators RDF,CNA,MSD \
  --r-max 15.0 --r-bin 0.02 \
  --time-step 1.5 \
  --csv --hdf5

Core CLI Arguments:

3. Python Bindings & PyTorch Geometric

Integrate Correlation directly into Python data-science environments, NumPy pipelines, and GNN frameworks:

import correlation
import numpy as np

# 1. Load atomistic structure or trajectory
cell = correlation.Cell.from_file("POSCAR")

# 2. Configure structural analysis engine
df = correlation.DistributionFunctions(cell, cutoff=10.0)

# 3. Compute radial and angular distribution functions
df.calculate_rdf(r_max=12.0, bin_width=0.05)
df.calculate_pad(bin_width=1.0)

# 4. Access computed histograms and partials
gr_hist = df.get_histogram("g_r")
bins = gr_hist.bins            # NumPy float array
total_gr = gr_hist.partials["Total"]

print(f"Computed {len(bins)} bins for g(r). Peak value: {np.max(total_gr):.3f}")

# 5. Build periodic graph & convert to PyTorch Geometric Data
graph_data = correlation.build_periodic_graph(cell, cutoff=5.0)
pyg_data = correlation.to_torch_geometric(graph_data)

print(pyg_data)
# Data(pos=[N, 3], z=[N], edge_index=[2, E], edge_shift=[E, 3], edge_vec=[E, 3], cell=[3, 3], pbc=[3])

👥 Authors & Citation

Corresponding Author

• Isaías Rodríguez — Isurwars isurwars@gmail.com

Contributors & Co-Authors

• Flor B. Quiroga quiroga.acbg@ciencias.unam.mx
• Renela M. Valladares renelavalladares@gmail.com
• Salvador Villarreal Lopez Rebuelta salvadorvillarreallr@gmail.com
• Alexander Valladares valladar@ciencias.unam.mx
• David Hinojosa-Romero david18_hr@ciencias.unam.mx
• Ulises Santiago
• Ariel A. Valladares valladar@unam.mx

Citation

If you use Correlation in scientific publications, please cite:

@article{Rodriguez2021Correlation,
  doi = {10.21105/joss.02976},
  url = {https://doi.org/10.21105/joss.02976},
  year = {2021},
  publisher = {The Open Journal},
  volume = {6},
  number = {59},
  pages = {2976},
  author = {Isa{\'i}as Rodr{\'i}guez and David Hinojosa-Romero and Alexander Valladares and Renela M. Valladares and Ariel A. Valladares},
  title = {Correlation: An Analysis Tool for Liquids and for Amorphous Solids},
  journal = {Journal of Open Source Software}
}

📜 License

Correlation is free and open-source software licensed under the GNU Affero General Public License v3 (AGPL-3.0-only). See LICENSE for details.

🙏 Acknowledgments

• I.R. acknowledges SECIHTI and DGAPA-UNAM for postdoctoral fellowship support.
• D.H.R. acknowledges DGAPA-UNAM for postdoctoral fellowship support.
• A.A.V., R.M.V., and A.V. thank DGAPA-UNAM for continued financial support (Grant Nos. IN104617, IN116520, IN118223, and IN119226).
• A.A.V., R.M.V., A.V., and I.R. acknowledge SECIHTI for research project grant support (Grant No. CBF-2025-G-886).
• Simulations and benchmarks were partially conducted at the Supercomputing Center of DGTIC-UNAM and IIM-UNAM.
• Special gratitude to M. A. Carrillo, R. S. Vilchis, S. Calderón, A. de Leon, J. A. Albarran, David A. de Jesús, and A. Perez-Aguiar for testing, benchmarking structures, and feedback.