SMolSAT: Soft-Matter Molecular Simulation Analysis Toolkit

SMolSAT is a modern C++ toolkit with comprehensive Python bindings for analyzing molecular dynamics simulations of soft matter systems. It provides a flexible and extensible framework for loading trajectory data, managing system information, and performing various analysis methods commonly used in soft-matter molecular simulation research.

🐍 Python Interface Available: Full Python API with NumPy integration, high-level convenience functions, and matplotlib plotting support!

Features

🐍 Python Interface

• Complete Python API: All C++ functionality accessible from Python
• NumPy Integration: Seamless data conversion and array operations
• Matplotlib Plotting: Built-in visualization functions
• High-Level Functions: Quick analysis with quick_msd(), quick_rg(), etc.
• Easy Installation: pip install . from source
• Jupyter Notebook Ready: Perfect for interactive analysis

Data Loader

• Flexible and extensible file format support
• XYZ format: Standard atomic coordinate files
• LAMMPS trajectory files: Custom dump files with various coordinate types
• LAMMPS data files: Initial configuration files
• Easy extension for additional formats

System Management

• Handles molecular dynamics systems with various particle types
• Support for periodic boundary conditions
• Efficient particle selection and grouping
• Time-dependent properties tracking

Analysis Methods

• Mean Square Displacement (MSD): Particle mobility analysis
• Radius of Gyration: Molecular size and shape analysis
• Gyration Tensor: Detailed molecular conformation analysis
• Radial/Pair Distribution Function (RDF): Structural correlations
• Chain End-to-End Distance: Polymer analysis
• Bond Vector Autocorrelation Functions: Orientational dynamics

Installation

🐍 Python Installation (Recommended)

Quick Install:

pip install .

Requirements:

• Python 3.7+
• NumPy >= 1.19.0
• Matplotlib >= 3.3.0
• pybind11 (automatically installed)

C++ Building

Requirements:

• C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
• CMake 3.12 or higher
• Eigen3 library for linear algebra operations

Build Instructions:

mkdir build
cd build
cmake ..
make -j$(nproc)

C++ Installation:

make install

Quick Start

🐍 Python Usage (Recommended)

import smolsat
import numpy as np
import matplotlib.pyplot as plt

# Create or load trajectory
trajectory = smolsat.create_example_trajectory(num_particles=100, num_frames=1000)
# Or load from file: trajectory = smolsat.load_trajectory("trajectory.xyz")

# Quick analysis with built-in functions
lag_times, msd_values = smolsat.quick_msd(trajectory)
times, rg_values = smolsat.quick_rg(trajectory)

# Plot results
smolsat.plot_msd(lag_times, msd_values, save_path="msd_plot.png")
smolsat.plot_time_series(times, rg_values, ylabel="Radius of Gyration", 
                        save_path="rg_plot.png")

# Advanced analysis
system = smolsat.System(trajectory, periodic_boundaries=True)
particles = [trajectory.particle(i) for i in range(10)]  # First 10 particles
msd_analysis = smolsat.MeanSquareDisplacement(system, particles)
msd_analysis.compute()
results = msd_analysis.msd_values()

C++ Usage

#include "smolsat/smolsat.h"

int main() {
    // Load trajectory data
    SMolSAT::DataLoader loader;
    auto trajectory = loader.load_xyz("trajectory.xyz");
    
    // Create system
    SMolSAT::System system(trajectory);
    
    // Perform analysis
    SMolSAT::MeanSquareDisplacement msd(system);
    auto result = msd.calculate();
    msd.write_output("msd.dat");
    
    return 0;
}

Python API Reference

Core Classes

# Coordinate operations
coord = smolsat.Coordinate(x, y, z)
distance = coord1.distance_to(coord2)
magnitude = coord.magnitude()

# Trajectory management
trajectory = smolsat.Trajectory()
particle = trajectory.add_particle(id, type, mass, name)
system = smolsat.System(trajectory, periodic_boundaries=True)

# Analysis methods
msd = smolsat.MeanSquareDisplacement(system, particles)
rg = smolsat.RadiusOfGyration(system, particles)

High-Level Functions

# Quick analysis
lag_times, msd = smolsat.quick_msd(trajectory, max_lag_time=100)
times, rg = smolsat.quick_rg(trajectory)

# Data utilities
positions, times = smolsat.trajectory_to_numpy(trajectory)
new_trajectory = smolsat.numpy_to_trajectory(positions, times)

# Visualization
smolsat.plot_msd(lag_times, msd_values, save_path="msd.png")
smolsat.plot_time_series(times, values, ylabel="Property")

Available Analysis Methods

• MeanSquareDisplacement: Particle diffusion analysis
• RadiusOfGyration: Molecular size analysis
• CorrelationAnalysis: Time correlation functions
• TimeSeriesAnalysis: General time series analysis

Documentation

See dev.md for detailed development documentation and API reference.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

SMolSAT is inspired by the AMDAT (Amorphous Molecular Dynamics Analysis Toolkit) package, reimagined with modern C++ design principles and enhanced extensibility. The comprehensive Python interface brings the power of C++ performance to the convenience and flexibility of Python scientific computing.

Contributing

Contributions are welcome! Please see dev.md for development guidelines and architecture documentation.

Status

• ✅ C++ Core Library: Production-ready with comprehensive testing
• ✅ Python Interface: Complete with pybind11 bindings and high-level API
• ✅ Installation: Fully automated with pip support
• ✅ Documentation: Comprehensive development and API documentation
• 🚀 Ready for Scientific Use: Both C++ and Python interfaces validated