GACELLE (GPU-AcCELerated toolbox for high-throughput multi-dimensionaL quantitative parameter Estimation)

GACELLE is a MATLAB parameter estimation tool optimised for high-throughput data processing.

GACELLE provides two types of solvers to handle parameter estimation prolem:

1. Determinisic, minimisation-based solver: askAdam.m
2. Stochastic, Markov chain Monte Carlo solver: mcmc.m

Full documentation can be found on http://gacelle.readthedocs.io

• Unified askadam/mcmc solver interface. Every model class now exposes a single fitting.solver = 'askadam' | 'mcmc' option and one estimate(...) entry point, replacing the old pattern of separate gpu<Model> / gpu<Model>mcmc classes (e.g. gpuJointR1R2starMapping + gpuJointR1R2starMappingmcmc are now just gpuJointR1R2starMapping).
• New QSM module (qsm/):
  • gpumcTFI - multi-echo complex Total Field Inversion: jointly reconstructs susceptibility, R2*, M0 and a phase offset directly from raw complex multi-echo GRE in a single nonlinear fit (MEDI-style anatomically-weighted TV regularisation, optional CSF zero-referencing).
  • gpuPDF - GPU Projection onto Dipole Fields background field removal.
• Automatic GPU memory management (fitting.autoMemManage = 1): a probe-based memory predictor (utils.find_optimal_segment_3D) transparently segments large volumes into density-balanced, halo-padded chunks processed sequentially when the full dataset won't fit in available VRAM, for both askadam.m and mcmc.m, with manual override via fitting.segmentOverlap / fitting.NSegmentUser.
• Reworked askadam.m convergence handling: five independent stopping criteria (loss threshold, robust loss convergence via fitting.robustConvergence, step-norm, gradient-norm, max iterations), selectable linear/EMA convergence models, and per-criterion patience windows.
• New default parameter-space transform for askadam.m: fitting.parameterTransform = 'sigmoid' (unconstrained logit/sigmoid reparameterisation) is now the default, fixing a boundary-sticking numerical failure mode present in the old hard-clamped linear rescaling ('linear', the v1.0 behaviour, is still available).
• MCMC ensemble improvements, including a fixed-anchor-walkers option.
• addpath_gacelle.m - adds the whole toolbox to the MATLAB path in one call, automatically excluding docs/, sandbox/, deprecated/ and mpl_training/.
• Expanded documentation: new "Advanced" pages (convergence, parameter transform, automatic memory management), a "Writing a new model" tutorial, an "Understanding the output" page, and reference pages for the new QSM classes plus R2starMapping/mcmicro/SANDI.

An example MCR-MWI (multi-compartment relaxometry myelin water imaging) dataset is available on Zenodo: 10.5281/zenodo.22666992.

Please check the license file for more information.

If you use GACELLE in your research, please cite the following article:

Chan, K.-S., Lee, H., Ma, Y., Bilgic, B., Huang, S.Y., Lee, H.-H., Marques, J.P., 2025. GACELLE: GPU-accelerated tools for model parameter estimation and image reconstruction. arXiv:2511.22094.

If you use GACELLE's implementation of NEXI, please also cite:

Chan, K.-S., Ma, Y., Lee, H., Marques, J.P., Olesen, J.L., Coelho, S., Novikov, D.S., Jespersen, S.N., Huang, S.Y., Lee, H.-H., 2025. In vivo human neurite exchange time imaging at 500 mT/m diffusion gradients. Imaging Neurosci. 3, imag_a_00544.

If you use GACELLE's implementation of MCR-MWI, please also cite:

Chan, K.-S., Kim T.H., Bilgic B., Marques J.P. Semi-supervised learning for fast multi-compartment relaxometry myelin water imaging (MCR-MWI). In: Proceedings 30. Annual Meeting International Society for Magnetic Resonance in Medicine. Vol 30. London, United Kingdom; 2022:1639.,

Chan, K.-S., Marques, J.P., 2020. Multi-compartment relaxometry and diffusion informed myelin water imaging – Promises and challenges of new gradient echo myelin water imaging methods. Neuroimage 221, 117159., and

Chan, K.-S., Chamberland, M., Marques, J.P., 2023. On the performance of multi-compartment relaxometry for myelin water imaging (MCR-MWI) – test-retest repeatability and inter-protocol reproducibility. Neuroimage 266, 119824.

Please report any bugs on the Issue page.

If you have a more general question regarding the usage of GACELLE, please make use of the Discussion board.

Planning to modify the toolbox yourself? See CONTRIBUTING.md.