Analyzer Module

The Analyzer module provides high-performance tools for molecular dynamics trajectory analysis. It combines Python interface logic with C++ computational backends to deliver efficient calculations of key physical properties from simulation trajectories.

Analysis Methods

Radial Distribution Function (RDF)

The RDF (or pair correlation function) g(r) describes how the atomic density varies as a function of distance from a reference particle:

\[g_{ab}(r)= \dfrac{V}{N_{a} \cdot N_{b}} \displaystyle \sum_{i=1}^{N_{a}} \displaystyle \sum_{j=i+1}^{N_{b}} \langle \delta(r - \left\vert \vec{r}_{i}(t) - \vec{r}_{j}(t) \right\vert) \rangle _{t}\]

Where: - ρ is the average number density - n(r) is the number of atoms in a shell of width Δr at distance r

Implementation features:

  • Bin-based histogram calculation with configurable resolution

  • Automatic normalization for correct physical interpretation

  • Support for arbitrary atom pairs

  • Multiple RDFs can be calculated in a single analysis run

  • Handles periodic boundary conditions correctly

Mean Square Displacement (MSD)

The MSD measures how far atoms travel from their initial positions as a function of time:

\[\text{MSD}(t) = \left\langle |r_i(t+\tau) - r_i(t)|^2 \right\rangle_{t,i}\]

Where: - r_i(t) is the position of atom i at time t - The average is taken over all atoms of a given type

Implementation features:

  • Automatic unwrapping of trajectories with periodic boundary conditions

  • Calculation of diffusion coefficients using Einstein relation

  • Supports multiple atom types in a single analysis run

Single-particle Mean Square Displacement (sMSD)

The sMSD tracks displacement for individual atoms rather than ensemble averages:

\[\text{sMSD}_i(t) = \left\langle |r_i(t+\tau) - r_i(t)|^2 \right\rangle_t\]

Implementation features:

  • Statistical distribution of single-particle diffusion coefficients

  • Identification of outlier particles with anomalous diffusion

  • Supports multiple atom types in a single analysis run

Vector Autocorrelation Function (VACF)

The VACF measures how a particle’s velocity remains correlated with its initial velocity over time:

\[\text{VACF}(t) = \left\langle v_i(t) \cdot v_i(0) \right\rangle_i\]

Implementation features:

  • Supports multiple atom pairs in a single analysis run

Usage

Command Line Interface

Interactive Q&A Mode:

amaceing_ana

This guides you through:

  1. Selecting trajectory files (supports multiple files)

  2. Defining periodic boundary conditions

  3. Setting timestep values for each trajectory

  4. Selecting which analyses to perform

  5. Choosing atom types or pairs for each analysis

  6. Configuring visualization options

Direct Command Line Mode:

amaceing_ana -f="traj.xyz" -p="pbc.dat" -t="0.5" -v="y" -r="O-H,O-O" -m="O,H" -s="O" -a="O-H"

Parameters:

  • -f, --file: Path to trajectory file(s) (comma-separated for multiple)

  • -p, --pbc: Path to PBC file(s) (comma-separated for multiple)

  • -t, --timestep: Timestep in fs (comma-separated for multiple)

  • -v, --visualize: Whether to visualize (y/n)

  • -r, --rdf_pairs: Atom pairs for RDF analysis (comma-separated, format: atom1-atom2)

  • -m, --msd_list: Atoms for MSD analysis (comma-separated)

  • -s, --smsd_list: Atoms for single-particle MSD analysis (comma-separated)

  • -a, --autocorr_pairs: Pairs for vector autocorrelation (comma-separated, format: atom1-atom2)

Python API

from amaceing_toolkit.workflow import analyzer_api

# Configure the analysis
config = {
    'traj_file': 'trajectory.xyz',
    'pbc_file': 'pbc.dat',
    'timestep': 0.5,
    'analysis_types': ['rdf', 'msd'],
    'rdf_pairs': [['O', 'H'], ['O', 'O']],
    'msd_atoms': ['O', 'H'],
    'visualize': True
}

# Run the analysis
results = analyzer_api(config=config)

Input File Formats

Trajectory Files:

The analyzer accepts standard XYZ format trajectory files containing multiple frames:

N_atoms
comment line
atom_type_1 x1 y1 z1
atom_type_2 x2 y2 z2
...
N_atoms
comment line
atom_type_1 x1 y1 z1
...

PBC Files:

The PBC (periodic boundary condition) file format is a simple text file containing the simulation cell vectors:

A B C
D E F
G H I

Output and Visualization

For each analysis type, the analyzer produces:

  1. Raw Data:

    • CSV files containing the numerical results

    • Data is organized for easy import into other analysis tools

  2. Visualizations:

    • Publication-quality plots generated using matplotlib

    • Automatic formatting and styling for clarity

    • PNG and PDF output formats

  3. Derived Quantities:

    • Diffusion coefficients from MSD curves

    • Coordination numbers from RDF peaks

    • Correlation times from VACF decay

  4. LaTeX Report (optional):

    • Comprehensive summary of all analyses

    • Tables of derived quantities

    • Embedded figures

    • Ready to compile for publication or presentations

  • Diffusion coefficients are calculated by fitting the MSD curve in the time range 10-30 ps

  • For sMSD analysis, statistics include mean, standard deviation, median, and the five highest diffusion coefficients

  • The Analyzer automatically handles periodic boundary conditions

  • Multiple trajectory analysis allows for direct comparison between different simulations