Quick Start Guide

Get up and running with SMolSAT in just a few minutes!

🚀 Your First SMolSAT Analysis

1. Import SMolSAT

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

2. Create Example Data

# Create a trajectory with random walk motion
trajectory = smolsat.create_example_trajectory(
    num_particles=100,
    num_frames=1000,
    box_size=(10.0, 10.0, 10.0),
    time_step=0.001
)

print(f"Created trajectory: {trajectory.num_particles()} particles, {trajectory.num_frames()} frames")

3. Quick Analysis

# Mean Square Displacement analysis
lag_times, msd_values = smolsat.quick_msd(trajectory)
print(f"MSD analysis: {len(msd_values)} data points")

# Radius of Gyration analysis
times, rg_values = smolsat.quick_rg(trajectory)
print(f"Rg analysis: {len(rg_values)} data points")

4. Visualization

# Create plots
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))

# MSD plot (log-log scale)
ax1.loglog(lag_times, msd_values, 'b-', linewidth=2)
ax1.set_xlabel('Lag Time')
ax1.set_ylabel('Mean Square Displacement')
ax1.set_title('Diffusion Analysis')
ax1.grid(True, alpha=0.3)

# Radius of gyration plot
ax2.plot(times, rg_values, 'r-', alpha=0.7)
ax2.set_xlabel('Time')
ax2.set_ylabel('Radius of Gyration')
ax2.set_title('System Size Evolution')
ax2.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

🎯 Common Analysis Workflows

Diffusion Analysis

# Calculate diffusion coefficient
diff_results = smolsat.calculate_diffusion_coefficient(lag_times, msd_values)
print(f"Diffusion coefficient: {diff_results['D']:.6f}")
print(f"R-squared: {diff_results['r_squared']:.4f}")

System Properties

# Get comprehensive system information
info = smolsat.get_system_info(trajectory)
print(f"System density: {info['density']:.4f}")
print(f"Average box volume: {info['average_box_volume']:.2f}")

Data Conversion

# Convert to NumPy arrays for custom analysis
data = smolsat.trajectory_to_numpy(trajectory)
positions = data['positions']  # Shape: (frames, particles, 3)
times = data['times']

# Calculate center of mass trajectory
center_of_mass = np.mean(positions, axis=1)
print(f"Center of mass shape: {center_of_mass.shape}")

🔬 Advanced Usage

Custom Particle Selection

# Create system for detailed analysis
system = smolsat.System(trajectory, periodic_boundaries=True)

# Select specific particles (first 50)
selected_particles = [trajectory.particle(i) for i in range(50)]

# Detailed MSD analysis
msd_analysis = smolsat.MeanSquareDisplacement(system, selected_particles)
msd_analysis.compute()

if msd_analysis.is_computed():
    msd_values = msd_analysis.msd_values()
    print(f"Detailed MSD computed: {len(msd_values)} values")

Molecular Analysis

# Create molecules from particle groups
molecule_ids = [list(range(i*10, (i+1)*10)) for i in range(10)]  # 10-particle molecules
molecules = []

for ids in molecule_ids:
    molecule = trajectory.add_molecule(ids)
    molecules.append(molecule)

print(f"Created {len(molecules)} molecules")

# Analyze molecular properties
rg_analysis = smolsat.RadiusOfGyration(system, selected_particles)
rg_analysis.compute()

📊 Built-in Plotting Functions

SMolSAT provides convenient plotting functions:

# Quick MSD plot with automatic formatting
smolsat.plot_msd(lag_times, msd_values, save_path="msd_analysis.png")

# Time series plotting
smolsat.plot_time_series(
    times, rg_values,
    ylabel="Radius of Gyration",
    title="System Size Evolution",
    save_path="rg_evolution.png"
)

🎨 Customizing Analysis

Custom Analysis Function

def analyze_particle_distances(trajectory):
    """Custom analysis: average particle distances from center."""
    data = smolsat.trajectory_to_numpy(trajectory)
    positions = data['positions']

    # Calculate center of mass for each frame
    com = np.mean(positions, axis=1)

    # Calculate distances from COM
    distances = np.linalg.norm(
        positions - com[:, np.newaxis, :], 
        axis=2
    )

    # Average distance per frame
    avg_distances = np.mean(distances, axis=1)

    return data['times'], avg_distances

# Use custom analysis
times, avg_dist = analyze_particle_distances(trajectory)
plt.plot(times, avg_dist)
plt.xlabel('Time')
plt.ylabel('Average Distance from COM')
plt.show()

🚨 Troubleshooting

Common Issues

ImportError: Make sure SMolSAT is installed:

import smolsat
print(smolsat.__version__)  # Should print version number

Empty plots: Check that your trajectory has data:

print(f"Particles: {trajectory.num_particles()}")
print(f"Frames: {trajectory.num_frames()}")

Performance issues: For large trajectories, use particle selection:

# Analyze subset of particles for faster computation
subset = [trajectory.particle(i) for i in range(0, trajectory.num_particles(), 10)]

🎯 Next Steps

Now that you're familiar with the basics:

1. Explore the API - Learn about all available classes and methods
2. Try Examples - See more detailed usage examples
3. Read Concepts - Understand key concepts
4. Load Real Data - Work with your simulation files

---

Congratulations! 🎉 You've completed your first SMolSAT analysis. Ready to explore more advanced features?