magoptlib

Global spherical harmonic analysis for optimal magnet positioning

magoptlib is a Python toolkit for modeling, analyzing, and optimizing magnetic fields generated by permanent magnets in Halbach configurations. The library provides tools for a spherical harmonic (SH) representation of magnetic fields from measurement data on a sphere, enabling optimization that accounts for real, non-ideal magnet properties.
Furthermore, magoptlib provides GPU-accelerated routines for evaluating candidate magnet arrays, running optimization loops, and generating synthetic measurement data

Documentation · PyPI version · License: MIT

Key features

  • GPU accelerated spherical harmonics – construct SH basis matrices and solve for SH coefficients on the GPU for field reconstructions.

  • Parallel optimisation – use genetic algorithms to determine optimistic Halbach magnet configurations in parallel.

  • Synthetic data generation – create synthetic magnetic field measurements on a sphere using magpylib.

  • Geometry utilities – assemble magnet and sensor rings using the helper functions for typical Halbach configuration.

  • Documentation and notebooks – browse the ReadTheDocs site or explore the Jupyter notebooks for hands-on examples.

Installation

The package is published on PyPI:

pip install magoptlib

GPU requirements

Most high-level routines use CuPy for GPU acceleration. Install the appropriate CuPy distribution for your CUDA toolkit before importing magoptlib. CPU-only execution is currently not supported for the optimisation workflow.

Quick start resources

The introduction.ipynb notebook walks through the typical workflow, such as simulating measurements, fitting spherical harmonics on the GPU, constructing magnet rings, and running optimisation loops. Open it directly in Jupyter or view a rendered version in the documentation site.

Project structure

  • src/magoptlib/sh_gpu.py – low-level GPU utilities for real SH basis evaluation and coordinate transforms.

  • src/magoptlib/sh_fitting.py – SH coefficient fitting and Cartesian⇄spherical conversions for measured field data.

  • src/magoptlib/genetic_algorithm.py – population-based optimisation helpers for Halbach-style magnet arrays and objective evaluations.

  • src/magoptlib/pos.py – helper functions to generate magnet and sensor rings used throughout the optimisation workflow.

  • src/magoptlib/synthetic_measurement.py – utilities to synthesise magnetic field measurements on spherical lattices via magpylib.

Contributing

Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms. Development dependencies can be installed with Poetry.

License

magoptlib was created by Palma Inczeffy. It is licensed under the terms of the MIT license.

Credits

magoptlib was created with cookiecutter and the py-pkgs-cookiecutter template.

Citation

If this library contributes to academic work, please cite it by referencing the project name, version, and GitHub URL in your publication.