Getting Started

What is MagTrack?

MagTrack is a free open-source Python library for tracking symmetric beads in single-molecule magnetic tweezers experiments.

• Sub-pixel XYZ coordinates

• GPU accelerated (optional, requires a CUDA-capable GPU)

• Python notebook included with examples

• Documented, tested, and benchmarked

• Only depends on NumPy, SciPy, and CuPy

• Runs on Windows, macOS, and Linux

• Easy installation with pip

System requirements

• Python >=3.9

• Supports Windows, macOS, and Linux

  • macOS does not support CUDA GPU acceleration

Installation

Method 1: CPU only (easier)

This method supports macOS, Windows, or Linux. But MagTrack will only be able to use your CPU. You can always later use method 2 if you want to add GPU acceleration.

pip install magtrack[cpu]

Method 2: CPU + GPU (a little harder)

This method supports Windows or Linux. This allows MagTrack to use either the CPU or a CUDA-capable GPU.

1. Confirm that your system has an NVIDIA GPU.

2. Install the free CUDA Toolkit.

   • Versions 11, 12, or 13 are supported.

   • You can check the installed version by running nvcc -V in a terminal such as Command Prompt.

3. Install MagTrack using the pip command that matches your CUDA version:

   CUDA Toolkit Version	Pip command
   11.x	pip install magtrack[cu11]
   12.x	pip install magtrack[cu12]
   13.x	pip install magtrack[cu13]

Verify the installation

After installing, you can try a function like center-of-mass, which converts an image stack into x,y bead coordinates:

import magtrack
import numpy as np

stack = np.ones((10, 10, 3))
x, y = magtrack.center_of_mass(stack, background="none")

print(f'x: {x}')
print(f'y: {y}')

If working properly, this will output an array of

x: [4.5 4.5 4.5]
y: [4.5 4.5 4.5]

You may receive a warning that GPU-acceleration with CuPy is unavailable if MagTrack was installed with CPU only.