Getting Started

What is MagTrack?

MagTrack is a Python package for tracking symmetric beads in single-molecule magnetic tweezers experiments. The library focuses on fast, accurate bead localization and includes an optional GPU pipeline for labs with CUDA-capable hardware. Out of the box it provides documented, benchmarked algorithms that return sub-pixel XYZ coordinates and the underlying radial intensity profiles used during axial fitting.

Key features

  • GPU accelerated (optional, requires a CUDA GPU)

  • Sub-pixel XYZ coordinates

  • Python notebook included with examples

  • Documented, tested, and benchmarked

  • Only depends on NumPy, SciPy, and CuPy

  • Actively maintained

System requirements

MagTrack requires Python 3.9 or newer as well as recent versions of NumPy and SciPy. Optional GPU acceleration is available through CuPy (CUDA 12.x builds). The package works on Windows, Linux, and macOS. macOS can run the CPU algorithms, but NVIDIA GPU acceleration is only available on platforms with CUDA support.

Installation

Install the latest release from PyPI. Include the [gpu] extra if you plan to use CuPy-based acceleration:

pip install magtrack[gpu]

To install only the CPU dependencies:

pip install magtrack

If you intend to use GPU acceleration, make sure that the CUDA Toolkit compatible with your GPU is installed before installing CuPy. Refer to the CuPy installation guide for detailed instructions.

Verify the installation

After installing, import magtrack in a Python session and print the version string. This confirms that Python can locate the package and that the compiled extensions were installed correctly:

import magtrack
print(magtrack.__version__)

You can also execute the quick-start pipeline, which converts an image stack into lateral and axial bead coordinates:

import magtrack

x, y, z, profiles = magtrack.stack_to_xyzp(stack)

Here stack is a 3D NumPy array of bead images (frames × rows × columns). The function returns the fitted lateral coordinates x and y, axial positions z, and the radial profiles profiles that were used in the axial fit.

Explore the examples

The examples/examples.ipynb notebook walks through the core functionality, including simulation, tracking, and GPU acceleration. Download the notebook to run it locally or open it in Google Colab from the README badge. The notebook’s scenarios are mirrored throughout the User Guide, so reading both side-by-side provides an effective first tour of MagTrack.