Correlation

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #typescript #llm #go #linux #macos #cli #vue #pytorch #security #mcp #open-source

(★ 22)

Correlation: A high-performance, Material Design GUI tool for the structural and dynamic analysis of liquids, amorphous solids, and crystalline materials. Beyond standard RDF and PAD, it now supports VDOS, VACF, S(Q), and XRD, with parallelized processing and support for major simulation formats (CAR, CELL, ARC, etc.).

Correlation Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![](https://raw.githubusercontent.com/Isurwars/Correlation/main/Images/Banner.png)

# `Correlation`: An Analysis Tool for Liquids and for Amorphous Solids

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5514113.svg)](https://doi.org/10.5281/zenodo.5514113) [![Version](https://img.shields.io/badge/version-3.8.5-green)](https://img.shields.io/badge/version-3.8.5-green) [![License](https://img.shields.io/badge/license-AGPLv3-brightgreen)](https://img.shields.io/badge/license-AGPLv3-brightgreen) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://raw.githubusercontent.com/Isurwars/Correlation/main/docs/CODE_OF_CONDUCT.md) [![DOI](https://joss.theoj.org/papers/10.21105/joss.02976/status.svg)](https://doi.org/10.21105/joss.02976)

`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.

---

## Table of Contents
- [`Correlation`: An Analysis Tool for Liquids and for Amorphous Solids](#correlation-an-analysis-tool-for-liquids-and-for-amorphous-solids)
  - [Table of Contents](#table-of-contents)
  - [Key Features](#key-features)
    - [📊 Comprehensive Calculator Suite](#-comprehensive-calculator-suite)
    - [📂 Broad File Format Support](#-broad-file-format-support)
    - [🚀 High Performance Core](#-high-performance-core)
  - [Installation](#installation)
    - [Prerequisites](#prerequisites)
      - [Package Managers Installation Examples](#package-managers-installation-examples)
        - [Linux (Debian/Ubuntu)](#linux-debianubuntu)
        - [Linux (Arch/Manjaro)](#linux-archmanjaro)
        - [MacOS (Homebrew)](#macos-homebrew)
        - [Windows](#windows)
    - [Build Instructions](#build-instructions)
    - [CMake Build Options](#cmake-build-options)
  - [Usage Modes](#usage-modes)
    - [1. Graphical User Interface (GUI)](#1-graphical-user-interface-gui)
      - [GUI Workflow:](#gui-workflow)
    - [2. Command Line Interface (CLI)](#2-command-line-interface-cli)
      - [Usage Example:](#usage-example)
      - [Command Options:](#command-options)
      - [Calculator IDs for `--calculators`:](#calculator-ids-for---calculators)
    - [3. Python Bindings](#3-python-bindings)
      - [Installation](#installation-1)
      - [Code Example](#code-example)
  - [Built with](#built-with)
  - [Authors](#authors)
  - [License](#license)
  - [Acknowledgments](#acknowledgments)

---

## Key Features

### 📊 Comprehensive Calculator Suite
`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).

### 📂 Broad File Format Support
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`)

### 🚀 High Performance Core
- **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`.

---

## Installation

> [!TIP]
> **Pre-compiled Packages**: Pre-built packages for **Linux** (**AppImage**, **Debian/Ubuntu** `.deb`, **Fedora/RHEL** `.rpm`), **macOS** (`.dmg`), and **Windows** (`.exe` installer) are provided directly in the GitHub [Releases](https://github.com/Isurwars/Correlation/releases) section.

### Prerequisites
* **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

#### Package Managers Installation Examples

##### Linux (Debian/Ubuntu)
```bash
sudo apt update
sudo apt install build-essential cmake git rustc cargo libtbb-dev
# Optional:
sudo apt install libhdf5-dev
```

##### Linux (Arch/Manjaro)
```bash
sudo pacman -Syu
sudo pacman -S base-devel cmake git rust intel-tbb
# Optional:
sudo pacman -S hdf5
```

##### MacOS (Homebrew)
```bash
xcode-select --install
brew install cmake git rustup tbb
# Optional:
brew install hdf5
```

##### Windows
1. Install [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the "Desktop development with C++" workload (includes MSVC and CMake).
2. Install [Rust](https://www.rust-lang.org/tools/install) (required by the Slint GUI compiler).
3. Install [Git](https://git-scm.com/download/win).

---

### Build Instructions

1. **Clone the repository:**
   ```bash
   git clone https://github.com/isurwars/correlation.git
   cd correlation
   ```

2. **Configure and Build:**
   ```bash
   mkdir build && cd build
   cmake ..
   cmake --build .
   ```

3. **Run Tests:**
   ```bash
   ctest -V
   ```

4. **Install (Optional):**
   ```bash
   sudo cmake --install .
   ```

---

### CMake Build Options

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

---

## Usage Modes

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

### 1. Graphical User Interface (GUI)
Start the GUI version by running the main executable:
```bash
./build/src/correlation
```

![Correlation Demo](https://raw.githubusercontent.com/Isurwars/Correlation/main/Images/demo.gif)

#### GUI Workflow:
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.

---

### 2. Command Line Interface (CLI)
Run calculations headlessly using `correlation-cli` without requiring any graphical shell:
```bash
./build/src/correlation-cli <input_file> [options]
```

#### Usage Example:
```bash
./build/src/correlation-cli Trajectory.xdatcar -o ./output/run_1 --calculators RDF,CNA,MSD --r-max 12.0 --csv --hdf5
```

---

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

#### Installation

Via **Conda-Forge** (recommended):
```bash
conda install -c conda-forge correlation
# Or using pixi:
pixi add correlation
```

Or build and install locally from source:
```bash
pip install .
```

#### Code Example
```python
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])
```

---

## Built with
- [emacs](https://www.gnu.org/software/emacs/) - An extensible, customizable, free/libre text editor — and more.

## Authors
- **Isaías Rodríguez** - _Corresponding Author_ - [Isurwars](https://github.com/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>

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

## Acknowledgments
* 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.

Correlation

Correlation Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Correlation

Correlation Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README