Installation

Installation#

This page contains detailed instructions for installing soliton_solver and verifying your setup.

System Requirements#

Before installing soliton_solver, the following system-level dependencies must be available. These provide the OpenGL context and CUDA bindings required for GPU computation and real-time visualization.

Required software#

  • NVIDIA GPU with CUDA support — An NVIDIA graphics card with compute capability 3.0 or higher

  • CUDA Toolkit — Compatible with your GPU and operating system (download from NVIDIA)

  • OpenGL drivers — Normally included with NVIDIA drivers; verify with your system

Verify system setup#

Check NVIDIA driver installation:

nvidia-smi

This should display your GPU information. Check CUDA Toolkit installation:

nvcc --version

This should display the CUDA compiler version. If either command fails, install the missing software before proceeding.

Python Requirements#

  • Python 3.10 or later

  • pip or conda package manager

Installation Methods#

From source#

For development or to use the latest code:

git clone https://github.com/paulnleask/soliton_solver.git
cd soliton_solver
pip install -e .

The -e flag installs the package in editable mode, allowing you to modify the code and see changes immediately.

With documentation dependencies#

To build the documentation locally:

pip install -e ".[docs]"

This installs the package along with Sphinx, sphinx-book-theme, and related documentation tools.

Dependencies#

The soliton_solver package automatically installs the following Python dependencies:

  • numpy — Array operations and numerical computing

  • numba-cuda — JIT compilation for CUDA kernels

  • moderngl — Modern OpenGL rendering abstraction

  • glfw — Window creation and input handling for the OpenGL viewer

  • PyOpenGL — Python bindings for OpenGL rendering

  • cuda-python — Low-level CUDA driver bindings used for CUDA–OpenGL interoperability

Verify Installation#

Test that the installation was successful:

import soliton_solver
print(soliton_solver.__version__)

Try running a built-in example:

python -m soliton_solver.examples.chiral_magnet_gl

This will launch an interactive visualization of magnetic skyrmions. You should see a real-time simulation window with a colormap visualization of the magnetic field.

Troubleshooting#

CUDA not detected#

If you get errors related to CUDA not being found:

  • Ensure NVIDIA drivers are installed (nvidia-smi should work)

  • Ensure CUDA Toolkit is installed (nvcc --version should work)

  • Check that your GPU has CUDA support (compute capability 3.0+)

OpenGL errors#

If you get OpenGL-related errors:

  • Ensure your NVIDIA drivers are up to date

  • Verify OpenGL support with glxinfo (Linux) or check System Information (Windows/Mac)

  • Ensure you have a display attached (SSH connections may require X11 forwarding)

Import errors#

If import soliton_solver fails:

  • Verify the package installed with pip list | grep soliton

  • Try reinstalling with pip install --upgrade --force-reinstall soliton-solver

For additional help, please open an issue on the GitHub repository.

Contents