Installation Guide

Overview

ControlDESymulation is a Python library for symbolic dynamical systems with multi-backend support. This guide covers installation methods, backend configuration, and verification steps.

Requirements

System Requirements

  • Python 3.9 or higher
  • pip package manager
  • (Optional) GPU with CUDA support for PyTorch/JAX acceleration

Core Dependencies

The library requires:

  • numpy - Core numerical operations
  • scipy - Scientific computing and integration
  • sympy - Symbolic mathematics
  • matplotlib - Visualization

Optional Backend Dependencies

  • PyTorch: torch - For automatic differentiation and GPU acceleration
  • JAX: jax, jaxlib - For high-performance numerical computing and JIT compilation

Installation Methods

Standard Installation (NumPy Only)

For basic functionality with NumPy backend:

pip install cdesym

This installs the core library with NumPy support, suitable for most educational and prototyping applications.

Installation with PyTorch Backend

For neural network integration and GPU acceleration:

pip install "cdesym[torch]"

For specific CUDA versions, install PyTorch first:

# Example: CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install "cdesym[torch]"

Installation with JAX Backend

For high-performance computing and JIT compilation:

pip install "cdesym[jax]"

For GPU support with JAX:

# CUDA 12
pip install "cdesym[jax]" "jax[cuda12]"

# CUDA 11
pip install "cdesym[jax]" "jax[cuda11]"

Installation with Julia DifferentialEquations.jl and DiffEqPy

For support for Julia DifferentialEquations.jl support, first install Julia and add it to the environment path so that it can be discovered. Then, install and pre-compile DifferentialEquations.jl.

Once that is done, then execute the following:

pip install "cdesym[julia]"

Development Installation

To install from source for development or to access the latest features:

git clone https://github.com/yourusername/ControlDESymulation.git
cd ControlDESymulation
pip install -e .

The -e flag installs in editable mode, allowing you to modify the source code without reinstalling.

Installing All Backends

For full functionality with all backends (including Julia support):

First install Julia and DifferentialEquations.jl, then

pip install "cdesym[torch,jax,julia]"

Other options

These flags will install core library dependencies PLUS

pip install "cdesym[viz]"

Plotly, matplotlib, and seaborn

pip install "cdesym[control]"

Python control library

pip install "cdesym[optimization]"

CVXPY, Clarabel, OSPQ, SCS, CasADi (for future functionality)

pip install "cdesym[dev]"

Pytest and many associated Pytest extensions, Coverage.py, Mutmut, Black, isort, ruff, mypy and extensions, flake8, pylint, bandit, safety, pre-commit, radon, pydeps types-requests, types-setuptools, build, twine, setuptools, and wheel

pip install "cdesym[docs]"

Sphinx and associated extensions, myst-parser

pip install "cdesym[notebooks]"

Jupyter, JupyterLab, IPyKernel, IPyWidgets, Notebook, and IPython

Backend Configuration

Setting the Default Backend

ControlDESymulation automatically detects available backends. You can explicitly set the backend:

from cdesym import DynamicalSystem

# Using NumPy (default)
system = DynamicalSystem(..., backend='numpy')

# Using PyTorch
system = DynamicalSystem(..., backend='torch')

# Using JAX
system = DynamicalSystem(..., backend='jax')

Backend Priority

When no backend is specified, the library searches in order:

  1. JAX (if available)
  2. PyTorch (if available)
  3. NumPy (always available)

Checking Available Backends

from cdesym.backends import get_available_backends

print(get_available_backends())
# Output: ['numpy', 'torch', 'jax']

Verification

Basic Installation Check

Verify the installation:

import cdesym
print(cdesym.__version__)

Testing Backend Functionality

Test each backend with a simple system:

import sympy as sp
from cdesym import DynamicalSystem

# Define symbolic variables
x, y = sp.symbols('x y')

# Define a simple system: dx/dt = -x, dy/dt = -y
dynamics = sp.Matrix([-x, -y])
state_vars = sp.Matrix([x, y])

# Test NumPy backend
system_np = DynamicalSystem(
    dynamics=dynamics,
    state_vars=state_vars,
    backend='numpy'
)

# Test simulation
t_span = (0, 5)
initial_state = [1.0, 1.0]
result = system_np.simulate(t_span, initial_state)
print(f"NumPy backend: {len(result.t)} time points")

# Test PyTorch backend (if available)
try:
    system_torch = DynamicalSystem(
        dynamics=dynamics,
        state_vars=state_vars,
        backend='torch'
    )
    print("PyTorch backend: Available")
except ImportError:
    print("PyTorch backend: Not available")

# Test JAX backend (if available)
try:
    system_jax = DynamicalSystem(
        dynamics=dynamics,
        state_vars=state_vars,
        backend='jax'
    )
    print("JAX backend: Available")
except ImportError:
    print("JAX backend: Not available")

Running Test Suite

If you have the development installation, run the test suite:

pytest tests/

For specific backend tests:

pytest tests/test_numpy_backend.py
pytest tests/test_torch_backend.py
pytest tests/test_jax_backend.py

Troubleshooting

Import Errors

Problem: ModuleNotFoundError: No module named 'cdesym'

Solution: Ensure installation completed successfully:

pip list | grep cdesym

Backend Not Available

Problem: “Backend ‘torch’ not available”

Solution: Install the required backend:

pip install torch

CUDA/GPU Issues

Problem: PyTorch or JAX not utilizing GPU

Solution: Verify GPU availability:

# For PyTorch
import torch
print(torch.cuda.is_available())

# For JAX
import jax
print(jax.devices())

Install appropriate CUDA-enabled versions if needed.

SymPy Compatibility

Problem: Symbolic computation errors

Solution: Ensure SymPy is up to date:

pip install --upgrade sympy

Numerical Integration Warnings

Problem: Integration warnings during simulation

Solution: These are typically harmless but can be addressed by: - Adjusting tolerance parameters (atol, rtol) - Using different integration methods - Checking system stability

GPU Acceleration Setup

PyTorch GPU Configuration

import torch

# Check CUDA availability
if torch.cuda.is_available():
    device = torch.device('cuda')
    print(f"Using GPU: {torch.cuda.get_device_name(0)}")
else:
    device = torch.device('cpu')
    print("Using CPU")

# Create system with PyTorch backend
system = DynamicalSystem(..., backend='torch')

# Move tensors to GPU when needed
initial_state_gpu = torch.tensor(initial_state).to(device)

JAX GPU Configuration

import jax

# JAX automatically uses GPU if available
print(f"JAX backend: {jax.default_backend()}")
print(f"JAX devices: {jax.devices()}")

# Verify GPU usage
import jax.numpy as jnp
x = jnp.ones(1000)
print(x.device())  # Should show GPU device

Virtual Environment Setup

Using venv

# Create virtual environment
python -m venv cds_env

# Activate (Linux/Mac)
source cds_env/bin/activate

# Activate (Windows)
cds_env\Scripts\activate

# Install ControlDESymulation
pip install cdesym

Using conda

# Create conda environment
conda create -n cds_env python=3.12

# Activate environment
conda activate cds_env

# Install ControlDESymulation
pip install cdesym

Next Steps

After successful installation:

  1. Review the Quick Start Guide for basic usage examples
  2. Explore Tutorials for detailed walkthroughs
  3. Check API Reference for comprehensive documentation
  4. See Examples Gallery for application demonstrations

Getting Help

If you encounter issues not covered here:

Version Information

Check your installed version:

import cdesym
print(f"ControlDESymulation version: {cdesym.__version__}")

Update to the latest version:

pip install --upgrade cdesym