SMolSAT Python API Documentation¶

Overview¶

SMolSAT provides a comprehensive Python interface to a high-performance C++ molecular dynamics analysis toolkit. The API is designed to be intuitive for Python users while maintaining the computational efficiency of the underlying C++ implementation.

Package Structure¶

smolsat/
├── Core C++ Classes (via _smolsat_core)
│   ├── Coordinate          # 3D coordinate operations with PBC support
│   ├── Particle           # Individual particle data management
│   ├── Molecule           # Multi-particle molecular entities
│   ├── Trajectory         # Time series trajectory data
│   ├── System             # Complete molecular system
│   ├── DataLoader         # Base data loading interface
│   ├── XYZLoader          # XYZ file format loader
│   ├── AnalysisBase       # Base class for analysis methods
│   ├── MeanSquareDisplacement  # MSD analysis
│   ├── RadiusOfGyration   # Radius of gyration analysis
│   ├── CorrelationAnalysis # Time correlation functions
│   └── TimeSeriesAnalysis # General time series analysis
│
├── Python Modules
│   ├── utils              # High-level utility functions
│   ├── data_loader        # Data loading helpers and converters
│   └── analysis          # Analysis convenience functions

Quick Start¶

import smolsat
import numpy as np

# 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
smolsat.plot_msd(lag_times, msd_values, save_path="msd.png")

API Reference¶

Core Classes¶

Coordinate - 3D coordinates with periodic boundary conditions
Particle - Individual particle data and trajectory
Molecule - Multi-particle molecular entities
Trajectory - Complete trajectory data management
System - Molecular system with analysis capabilities

Data Loading¶

DataLoader - Base data loading interface
XYZLoader - XYZ format file loader

Analysis Methods¶

AnalysisBase - Base class for all analysis methods
MeanSquareDisplacement - Diffusion and mobility analysis
RadiusOfGyration - Molecular size and shape analysis
CorrelationAnalysis - Time correlation functions
TimeSeriesAnalysis - General time series analysis

Python Utilities¶

Utils Module - High-level convenience functions
Data Loader Module - Data loading and conversion helpers
Analysis Module - Analysis convenience functions and plotting

Installation¶

pip install .

Dependencies¶

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

Examples¶

See the examples directory for comprehensive usage examples and tutorials.

Contributing¶

See development documentation for contribution guidelines and architecture details.