Correlation

Correlation: Advanced Atomistic Structural & Dynamic Analysis Suite

DOI Version C++ Standard Conda-Forge License Contributor Covenant DOI

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

🌟 Key Capabilities

📊 Scientific Calculator Suite

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

Category Calculators & Functions Output Properties
Radial / Pair Radial Distribution Function ($J(r)$), Pair Distribution Function ($g(r)$), Reduced Pair Distribution ($G(r)$) Total & partial pair correlations, coordination shells, density scaling
Scattering & Diffraction Structure Factor ($S(Q) / S(K)$), Powder X-ray Diffraction (XRD) Elastic scattering intensity, Faber-Ziman partials, Debye scattering equation
Angular Distributions Plane-Angle Distribution (PAD), Dihedral-Angle Distribution (DAD), Generic Bond Angles 3-body & 4-body angular configurations, tetrahedrality, dihedral orientation
Topology & Local Structure Common Neighbor Analysis (CNA), Coordination Numbers (CN), Ring Distribution (RD), Voronoi Polyhedra, Cluster Connectivity, Motif Detection FCC/HCP/BCC/Icosahedral classification, Voronoi index $\langle n_3, n_4, n_5, n_6 \rangle$, topological shortest-path ring statistics
Order Parameters & Symmetry Steinhardt Bond-Orientational Parameters ($Q_4, Q_6, W_6$), Local Inversion Chirality, Local Excess Entropy ($s_2$), Hyperuniformity Index Global/local orientational order, structural chirality asymmetry, two-body excess entropy, low-$Q$ density fluctuations
Dynamics & Transport Mean Squared Displacement (MSD), Velocity Autocorrelation Function (VACF), Vibrational Density of States (VDOS) Self-diffusion coefficients ($D_{MSD}, D_{VACF}$), relaxation time $\tau$, Deborah number $De$, vibrational power spectra
Spatial & Electronic / ML 3D Spatial Distribution Functions (SDF), Hydrogen Bonding (HBond), Machine Learning Interatomic Potentials (MLIP) 3D local coordinate voxel density, donor-acceptor geometric networks, LibTorch GNN evaluation, PyG graph construction

📂 Comprehensive Format Support

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

⚡ High-Performance Core & Multi-Vendor GPU

📦 Installation

Pre-compiled Packages

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

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

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

CMake Flag Default Description
BUILD_GUI ON Compiles the Slint-based Graphical User Interface (src/correlation)
BUILD_PYTHON_BINDINGS OFF Compiles Python C-extension bindings via pybind11
USE_SINGLE_PRECISION OFF Compiles core algorithms using single-precision float (real_t)
BUILD_WITH_CUDA OFF Enables NVIDIA CUDA GPU acceleration kernels
BUILD_WITH_SYCL OFF Enables Intel oneAPI / SYCL multi-vendor GPU acceleration
BUILD_WITH_HDF5 OFF Enables HDF5 consolidated binary export format
BUILD_WITH_ARROW OFF Enables Apache Arrow / Parquet columnar export format
BUILD_WASM OFF Compiles WebAssembly client-side library bindings
CORRELATION_ENABLE_LIBTORCH OFF Links LibTorch for native GNN MLIP evaluation

🚀 Usage Modes

1. Graphical User Interface (GUI)

Launch the modern Slint-based interface:

./build/src/correlation

Correlation Demo

Key GUI Highlights:

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:

| Flag | Parameter | Description | | :—————————– | :——– | :————————————————————————- | | -o, --output | <path> | Base output path (default: input file stem) | | --calculators | <list> | Comma-separated list of calculators to execute (e.g. RDF,XRD,PAD,CNA) | | --r-max, --r-bin | <float> | Maximum radius ($Å$) and bin width ($Å$) for radial calculations | | --q-max, --q-bin | <float> | Maximum scattering vector $Q$ ($Å^{-1}$) and bin width for $S(Q)$ | | --angle-bin | <float> | Angular bin width in degrees for PAD/DAD (default: 1.0) | | --max-ring-size | <int> | Maximum topological ring size to evaluate (default: 8) | | --time-step | <float> | Simulation timestep in femtoseconds (default: 1.0) | | --min-frame, --max-frame | <int> | 1-based frame evaluation range (-1 for all frames) | | --smoothing-kernel | <str> | Smoothing filter: gaussian, bump, or triweight (default: gaussian) | | --csv, --hdf5, --parquet | | Toggle tabular CSV, consolidated HDF5, or Apache Parquet output |

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

Contributors & Co-Authors

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

This site is open source. Improve this page.