Installation Guide

This guide will help you install JALAN-Sim on your system. There are multiple installation methods depending on your needs and platform.

The easiest way to install JALAN-Sim is using pip:

pip install jalansim

This will install the pre-built Python bindings with CPU support. For GPU acceleration, see the GPU Support section below.

System Requirements

Minimum Requirements

  • Python: 3.8 or higher
  • Operating System: Windows 10+, macOS 10.14+, or Linux (Ubuntu 18.04+)
  • Memory: 4GB RAM minimum, 8GB+ recommended for batch simulations

For GPU Support

  • NVIDIA GPU: CUDA Compute Capability 6.0+ (GTX 1060 or better)
  • CUDA Toolkit: 12.2 or higher
  • GPU Memory: 2GB+ VRAM recommended

Installation Methods

Install the latest stable release from PyPI:

pip install jalansim

Method 2: Development Installation

For the latest features and development work:

# Clone the repository
git clone https://github.com/damanikjosh/jalansim.git
cd jalansim

# Install in editable mode
pip install -e .

Method 3: Build from Source

For custom builds or platforms not supported by pre-built wheels:

# Clone the repository
git clone https://github.com/damanikjosh/jalansim.git
cd jalansim

# Install build dependencies
pip install cmake scikit-build-core pybind11 numpy ninja

# Build and install
pip install .

GPU Support

JALAN-Sim automatically detects CUDA availability and enables GPU acceleration when possible.

CUDA Installation

  1. Install NVIDIA Drivers: Download from NVIDIA's website

  2. Install CUDA Toolkit: Visit NVIDIA's CUDA Downloads page and follow the installation guide for your platform. Make sure to install CUDA Toolkit 12.2 or higher.

  3. Verify Installation:

nvidia-smi
nvcc --version

Forcing CPU-Only Build

If you want to disable CUDA support (e.g., for CPU-only deployment):

# Set environment variable
export JALANSIM_DISABLE_CUDA=1
pip install jalansim --force-reinstall --no-cache-dir

Common Issues and Solutions

Import Errors

Problem: ImportError: No module named 'jalansim'

Solution: Ensure Python can find the module:

pip list | grep jalansim
# If not found, reinstall:
pip install --force-reinstall jalansim

CUDA Issues

Problem: CUDA not detected despite having NVIDIA GPU

Solutions:

  1. Verify CUDA installation: nvidia-smi and nvcc --version
  2. Check Python CUDA binding: python -c "import torch; print(torch.cuda.is_available())"
  3. Reinstall with verbose output: pip install jalansim -v

Problem: Out of memory errors on GPU

Solutions: 1. Reduce batch size in simulations 2. Use smaller numeric precision (float32 instead of float64) 3. Monitor GPU memory: nvidia-smi -l 1

Build Issues

Problem: CMake or compiler errors during installation

Solutions:

  1. Update build tools: pip install --upgrade cmake scikit-build-core pybind11

  2. Install compiler (if missing):

# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install

# Windows: Install Visual Studio Build Tools

Platform-Specific Issues

Windows

  • Install Microsoft Visual C++ 14.0+ (Visual Studio Build Tools)
  • Use Command Prompt or PowerShell as Administrator for installation

macOS

  • Install Xcode command line tools: xcode-select --install
  • For M1/M2 Macs, ensure compatible Python version (3.9+)

Linux

  • Install development packages:
sudo apt update
sudo apt install build-essential cmake python3-dev

Virtual Environments

Recommended setup with virtual environments:

# Create virtual environment
python -m venv jalansim-env

# Activate (Linux/macOS)
source jalansim-env/bin/activate

# Activate (Windows)
jalansim-env\Scripts\activate

# Install JALAN-Sim
pip install jalansim

# Deactivate when done
deactivate

Next Steps

Once installed, check out:

Getting Help

If you encounter issues:

  1. Check the FAQ
  2. Search GitHub Issues
  3. Create a new issue with:
  4. Your platform and Python version
  5. Complete error messages
  6. Steps to reproduce the problem