Skip to content

SMolSAT Documentation

Welcome to the SMolSAT (Soft-Matter Molecular Simulation Analysis Toolkit) documentation!

Overview

SMolSAT is a modern, high-performance toolkit for analyzing molecular dynamics simulations of soft matter systems. It combines the computational efficiency of C++ with the convenience and flexibility of Python, providing researchers with powerful tools for molecular dynamics analysis.

🚀 Quick Start

import smolsat
import matplotlib.pyplot as plt

# Create example trajectory
trajectory = smolsat.create_example_trajectory(num_particles=100, num_frames=1000)

# Quick analysis
lag_times, msd_values = smolsat.quick_msd(trajectory)
times, rg_values = smolsat.quick_rg(trajectory)

# Visualization
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
ax1.loglog(lag_times, msd_values)
ax1.set_title('Mean Square Displacement')
ax2.plot(times, rg_values)
ax2.set_title('Radius of Gyration')
plt.show()

🔧 Installation

pip install .

git clone https://github.com/your-org/smolsat.git
cd smolsat
pip install .

✨ Key Features

🐍 Python Interface

  • Complete Python API with all C++ functionality accessible
  • NumPy Integration for seamless data conversion and array operations
  • Matplotlib Plotting with built-in visualization functions
  • High-Level Functions like quick_msd() and quick_rg() for rapid analysis

🔬 Analysis Methods

  • Mean Square Displacement (MSD): Particle mobility and diffusion analysis
  • Radius of Gyration: Molecular size and shape characterization
  • Correlation Analysis: Time correlation functions for various properties
  • Time Series Analysis: General time-dependent property analysis

📁 Data Management

  • Flexible Data Loading: Support for XYZ and other molecular dynamics formats
  • Trajectory Management: Efficient handling of large trajectory datasets
  • Periodic Boundary Conditions: Full support for PBC in all calculations
  • System Analysis: Comprehensive molecular system characterization

⚡ Performance

  • C++ Backend: High-performance computational core
  • Efficient Memory Management: Smart pointers and optimized data structures
  • Parallel Processing: Multi-threaded analysis capabilities
  • Large Dataset Support: Handle trajectories with millions of particles

📚 Documentation Structure

  • Getting Started

    Quick installation guide and basic concepts to get you up and running with SMolSAT.

  • API Reference

    Comprehensive documentation of all classes, methods, and functions in SMolSAT.

  • Examples

    Practical examples and code snippets demonstrating common analysis workflows.

  • Tutorials

    Step-by-step guides for specific analysis types and research applications.

🎯 Common Use Cases

Polymer Dynamics

# Analyze polymer chain dynamics
trajectory = smolsat.load_trajectory("polymer_simulation.xyz")
system = smolsat.System(trajectory, periodic_boundaries=True)

# Create molecules from polymer chains
polymer_particles = trajectory.particles_of_type_name("POL")
msd_analysis = smolsat.MeanSquareDisplacement(system, polymer_particles)
msd_analysis.compute()

# Calculate diffusion coefficient
lag_times, msd_values = smolsat.quick_msd(trajectory)
diff_coeff = smolsat.calculate_diffusion_coefficient(lag_times, msd_values)

Solvent Analysis

# Study solvent behavior around solutes
solvent_particles = trajectory.particles_of_type_name("SOL")
rg_analysis = smolsat.RadiusOfGyration(system, solvent_particles)

# Time evolution of system properties
times, rg_values = smolsat.quick_rg(trajectory)
smolsat.plot_time_series(times, rg_values, ylabel="Radius of Gyration")

Custom Analysis Workflows

# Convert to NumPy for custom analysis
data = smolsat.trajectory_to_numpy(trajectory)
positions = data['positions']  # Shape: (n_frames, n_particles, 3)

# Custom calculations using NumPy
center_of_mass = np.mean(positions, axis=1)
distances = np.linalg.norm(positions - center_of_mass[:, np.newaxis, :], axis=2)

🛠️ Architecture

SMolSAT follows a layered architecture design:

graph TB
    A[Python High-Level API] --> B[Python Utility Modules]
    B --> C[pybind11 Bindings]
    C --> D[C++ Core Classes]
    D --> E[Eigen3 Linear Algebra]

    A --> F[NumPy Integration]
    A --> G[Matplotlib Plotting]

    H[XYZ Files] --> I[Data Loaders]
    I --> D

    D --> J[Analysis Methods]
    J --> K[MSD, Rg, Correlations]

📊 Performance Benchmarks

SMolSAT is designed for high performance:

Dataset Size Particles Frames MSD Analysis Time Memory Usage
Small 1,000 1,000 0.1s 50 MB
Medium 10,000 5,000 2.3s 400 MB
Large 100,000 10,000 45s 3.2 GB

🤝 Contributing

We welcome contributions! SMolSAT is an open-source project that benefits from community involvement.

📄 License

SMolSAT is released 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 Python integration. We thank the molecular dynamics community for their valuable feedback and contributions.

Ready to get started? Check out our Installation Guide or jump into the Quick Start Tutorial!