Correlation is a high-performance, user-friendly tool for calculating and analyzing the structural and dynamic properties of materials. It is designed for researchers working with atomistic simulations of liquids, amorphous solids, crystalline structures, and soft-matter systems.

The software computes key correlation functions from atomic coordinate trajectories and exports results in multiple formats (CSV, Parquet, HDF5), making it easy to integrate into scientific workflows.

• Correlation: An Analysis Tool for Liquids and for Amorphous Solids
  • Table of Contents
  • Key Features
    • 📊 Comprehensive Calculator Suite
    • 📂 Broad File Format Support
    • 🚀 High Performance Core
  • Installation
    • Prerequisites
      • Package Managers Installation Examples
        • Linux (Debian/Ubuntu)
        • Linux (Arch/Manjaro)
        • MacOS (Homebrew)
        • Windows
    • Build Instructions
    • CMake Build Options
  • Usage Modes
    • 1. Graphical User Interface (GUI)
      • GUI Workflow:
    • 2. Command Line Interface (CLI)
      • Usage Example:
      • Command Options:
      • Calculator IDs for --calculators:
    • 3. Python Bindings
      • Installation
      • Code Example
  • Built with
  • Authors
  • License
  • Acknowledgments

Correlation computes a rich set of structural, angular, ring, and dynamic properties:

• Radial/Pair Distributions: Radial Distribution Function ($J(r)$), Pair Distribution Function ($g(r)$), and Reduced Pair Distribution Function ($G(r)$).
• Structure Factor & Diffraction: Structure Factor ($S(Q)$ or $S(K)$) and X-ray Diffraction (XRD) patterns.
• Angular Distributions: Plane-Angle Distribution (PAD), Dihedral-Angle Distribution (DAD), and generic bond angles.
• Topological & Neighbors: Coordination Number (CN), Common Neighbor Analysis (CNA), Ring Distribution (RD), and Cluster Analysis.
• Dynamics: Mean Squared Displacement (MSD), Velocity Autocorrelation Function (VACF), and Vibrational Density of States (VDOS).
• Advanced Mapping: Steinhardt Bond-Orientational Parameters ($Q_4, Q_6, W_6$), Hydrogen Bond Analysis, and 3D Spatial Distribution Functions (SDF).

Compatible with structure and trajectory files from:

• VASP (.poscar, .contcar, .vasp, .xdatcar)
• LAMMPS (.dump, .lammpstrj)
• GROMACS (.gro, .xtc, .trr)
• PDB (.pdb, .ent)
• Quantum ESPRESSO (.pwi, .pwo, .in, .out)
• CP2K (.inp, .restart, .out, .cp2k)
• Extended XYZ (.xyz, .exyz)
• Crystallographic Information (.cif)
• Materials Studio / Accelrys (.car, .arc)
• CASTEP (.cell, .md)
• ONETEP (.dat)

• Cell-Lists Partitioning: Neighbor searching scales at $O(N)$ complexity instead of $O(N^2)$ for large systems.
• SIMD Vectorization: Optimization using AVX2/AVX-512 vector execution.
• Task-Based Parallelism: Advanced parallelization using Intel Threading Building Blocks (TBB).
• Optional GPU Acceleration: CUDA-accelerated $S(Q)$ computation (-DBUILD_WITH_CUDA=ON) with automatic CPU fallback.
• Memory-Mapped I/O: Efficient lazy loading of multi-gigabyte trajectory files via MappedFile.

• Compiler: Modern C++ compiler with C++23 support (GCC 13+, Clang 16+, MSVC 2022+)
• CMake: Version 3.24 or higher
• Git: To clone the repository
• Intel TBB: For parallelization
• Slint: Required for GUI compilation
• Optional Dependencies:
  • HDF5: For HDF5 output format support
  • Apache Arrow/Parquet: For Parquet output format support
  • CUDA Toolkit: For GPU acceleration
  • Python 3.9+ & pybind11: For compiling Python bindings

sudo apt update
sudo apt install build-essential cmake git rustc cargo libtbb-dev
# Optional:
sudo apt install libhdf5-dev

sudo pacman -Syu
sudo pacman -S base-devel cmake git rust intel-tbb
# Optional:
sudo pacman -S hdf5

xcode-select --install
brew install cmake git rustup tbb
# Optional:
brew install hdf5

1. Install Visual Studio with the "Desktop development with C++" workload (includes MSVC and CMake).
2. Install Rust (required by the Slint GUI compiler).
3. Install Git.

1. Clone the repository:

   git clone https://github.com/isurwars/correlation.git
   cd correlation

2. Configure and Build:

   mkdir build && cd build
   cmake ..
   cmake --build .

3. Run Tests:

   ctest -V

4. Install (Optional):

   sudo cmake --install .

Configure these options using cmake .. -D<OPTION>=<ON|OFF> during compilation:

Correlation can be executed in three ways: via GUI, headless CLI, or Python.

Start the GUI version by running the main executable:

./build/src/correlation

1. Load File: Click "Load a structure file" to import trajectories or structures.
2. Verify File Info: Check element distributions and frames in the File Info card.
3. Configure Options: Adjust thresholds, maximum integration lengths, bin widths, and smoothing parameters (Gaussian, Bump, Triweight).
4. Define Bond Cutoffs: Review or customize element-pair bond distance cutoffs.
5. Run & Save: Choose output formats (CSV, HDF5, Parquet), run calculations, inspect the interactive dynamic plot preview, and save plots (SVG) or output datasets.

Run calculations headlessly using correlation-cli without requiring any graphical shell:

./build/src/correlation-cli <input_file> [options]

./build/src/correlation-cli Trajectory.xdatcar -o ./output/run_1 --calculators RDF,CNA,MSD --r-max 12.0 --csv --hdf5

Integrate Correlation directly into Python data-science workflows (e.g., Jupyter Notebooks):

Build and install the Python library from the repository root:

pip install .

import correlation

# Load structure or trajectory file
cell = correlation.Cell.from_file("structure.poscar")

# Set up distribution functions analysis
df = correlation.DistributionFunctions(cell, cutoff=8.0)

# Calculate RDF g(r), G(r), J(r)
df.calculate_rdf(r_max=15.0, bin_width=0.05)

# Access calculated histogram datasets
rdf_hist = df.get_histogram("g_r")

# Retrieve values
bins = rdf_hist.get_bins()          # numpy float64 view
total_gr = rdf_hist.get_partial("Total")  # total RDF list

print("Bins:", bins[:5])
print("Total g(r):", total_gr[:5])

• emacs - An extensible, customizable, free/libre text editor — and more.

• Isaías Rodríguez - Corresponding Author - Isurwars isurwars@gmail.com
• Salvador Villareal Lopez Rebuelta salvadorvillarreallr@gmail.com
• Renela M. Valladares renelavalladares@gmail.com
• Alexander Valladares valladar@ciencias.unam.mx
• David Hinojosa-Romero david18_hr@ciencias.unam.mx
• Ulises Santiago
• Ariel A. Valladares valladar@unam.mx

This project is licensed under the GNU Affero General Public License v3 (AGPLv3) - see the LICENSE file for details.

• I.R. acknowledge SECIHTI and DGAPA-UNAM for his postdoctoral fellowship.
• D.H.R. acknowledge DGAPA-UNAM for his postdoctoral fellowship.
• A.A.V., R.M.V., and A.V. thank DGAPA-UNAM for continued financial support to carry out research projects under Grant No. IN104617, IN116520, IIN118223 and IN119226.
• A.A.V., R.M.V., A.V., and I.R. acknowledge SECIHTI for the financial support to carry out research projects under Grant No. CBF-2025-G-886.
• M. T. Vázquez and O. Jiménez provided the information requested.
• A. Pompa helped with the maintenance and support of the supercomputer in IIM-UNAM.
• Simulations were partially carried out in the Supercomputing Center of DGTIC-UNAM.
• I.R. would like to express his gratitude to F. B. Quiroga, M. A. Carrillo, R. S. Vilchis, S. Calderón, A. de Leon, J.A. Albarran, David A. de Jésus and A. Perez-Aguiar for their time invested in testing the code, as well as the structures provided for benchmarks and tests.