Skip to content

Installation Guide

This guide will help you install SMolSAT and get it running on your system.

SMolSAT provides a complete Python interface that's easy to install and use.

Prerequisites

  • Python 3.7 or higher
  • pip package manager
  • A C++17 compatible compiler (for building from source)

Quick Install

# Clone the repository (if not already done)
git clone https://github.com/your-org/smolsat.git
cd smolsat

# Install with pip
pip install .

# For development work
pip install -e .

Verify Installation

import smolsat
print(f"SMolSAT version: {smolsat.__version__}")

# Quick test
coord = smolsat.Coordinate(1.0, 2.0, 3.0)
print(f"Test coordinate: {coord}")
print("✅ SMolSAT installed successfully!")

📦 Dependencies

SMolSAT automatically installs the following Python dependencies:

Required Dependencies

  • NumPy (≥ 1.19.0) - Numerical computing
  • Matplotlib (≥ 3.3.0) - Plotting and visualization

Build Dependencies

  • pybind11 - Python-C++ bindings (automatically installed)
  • CMake (≥ 3.12) - Build system
  • Eigen3 - Linear algebra library (included)

🔧 Building from Source

If you need to build SMolSAT from source (for development or customization):

System Requirements

sudo apt update
sudo apt install build-essential cmake python3-dev python3-pip

sudo yum groupinstall "Development Tools"
sudo yum install cmake python3-devel python3-pip

# Install Xcode command line tools
xcode-select --install

# Install CMake (via Homebrew)
brew install cmake

# Install Visual Studio 2017 or later
# Install CMake from https://cmake.org/
# Install Python 3.7+ from https://python.org/

Build Process

# Clone repository
git clone https://github.com/your-org/smolsat.git
cd smolsat

# Create build directory
mkdir build
cd build

# Configure with CMake
cmake .. -DBUILD_PYTHON=ON -DBUILD_TESTS=ON

# Build
make -j$(nproc)

# Install Python package
cd ..
pip install .

For the best experience, we recommend using a dedicated conda environment:

# Create new environment
conda create -n smolsat python=3.8 numpy matplotlib

# Activate environment
conda activate smolsat

# Install SMolSAT
pip install .

🧪 Testing Installation

Quick Functionality Test

import smolsat
import numpy as np

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

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

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

print("✅ All tests passed!")

Run Test Suite

If you built from source with tests enabled:

# Run C++ tests
cd build
ctest

# Run Python tests (if available)
python -m pytest tests/

🚨 Troubleshooting

Common Issues

ImportError: No module named 'smolsat'

Solution: Make sure SMolSAT is installed in the correct Python environment:

# Check which Python you're using
which python
pip list | grep smolsat

# Reinstall if necessary
pip uninstall smolsat
pip install .

CMake Error: Could NOT find Python3

Solution: Specify Python paths explicitly:

cmake .. -DBUILD_PYTHON=ON \
         -DPython3_EXECUTABLE=$(which python) \
         -DPython3_INCLUDE_DIR=$(python -c "import sysconfig; print(sysconfig.get_path('include'))")

Compilation Errors

Solution: Ensure you have a C++17 compatible compiler:

# Check compiler version
gcc --version  # Should be 7.0 or higher
clang --version  # Should be 5.0 or higher

Permission Denied Errors

Solution: Install in user directory:

pip install . --user

Getting Help

If you encounter issues:

  1. Check the troubleshooting section above for common solutions
  2. Search GitHub Issues for similar problems
  3. Create a new issue with:
  4. Your operating system and version
  5. Python version (python --version)
  6. Complete error message
  7. Steps to reproduce the problem

🔄 Updating SMolSAT

To update to the latest version:

# Pull latest changes
git pull origin main

# Reinstall
pip install . --force-reinstall

🎯 Next Steps

Once SMolSAT is installed:

  1. Quick Start Guide - Learn the basics
  2. Basic Concepts - Understand key concepts
  3. API Reference - Explore all functionality
  4. Examples - See practical examples

Installation complete! 🎉 You're ready to start analyzing molecular dynamics simulations with SMolSAT.