NuMagSANS: a GPU-accelerated open-source software package for the generic computation of nuclear and magnetic small-angle neutron scattering observables of complex systems

Adams, M.P.; Michels, A.

doi:10.1107/S160057672600258X

computer programs

JOURNAL OF
APPLIED
CRYSTALLOGRAPHY

ISSN: 1600-5767

Volume 59| Part 3| June 2026| Pages 943-959

https://doi.org/10.1107/S160057672600258X

Open

access

NuMagSANS: a GPU-accelerated open-source software package for the generic computation of nuclear and magnetic small-angle neutron scattering observables of complex systems

Michael P. Adams ^a ^* and Andreas Michels ^a

^aDepartment of Physics and Materials Science, University of Luxembourg, 162A avenue de la Faïencerie, L-1511 Luxembourg, Luxembourg
^*Correspondence e-mail: [email protected]

Edited by J. Ilavsky, Argonne National Laboratory, USA (Received 9 January 2026; accepted 10 March 2026; online 8 May 2026)

We present NuMagSANS, a GPU-accelerated software package for calculating nuclear and magnetic small-angle neutron scattering (SANS) cross sections and correlation functions. The program allows users to import position-dependent nuclear density and magnetization data, providing significant flexibility for analyzing the scattering signatures of complex systems, particularly magnetic materials. Full rotational control of the sample is supported, allowing a comprehensive exploration of angle-dependent scattering features. NuMagSANS includes a versatile library of approximately 100 response functions that encompass two-dimensional SANS cross sections, correlation functions and azimuthally averaged quantities. These capabilities allow users to gain detailed insight into the structural and magnetic characteristics of their samples. GPU acceleration ensures rapid computations, even for large data sets, making NuMagSANS a powerful and efficient tool for advanced SANS analysis.

Keywords: nuclear and magnetic small-angle neutron scattering; GPU-accelerated software; complex systems; micromagnetic simulations.

1. Introduction

NuMagSANS is a GPU-accelerated software package developed to overcome the computational challenges associated with accurately evaluating nuclear and magnetic small-angle neutron scattering (SANS) observables in structurally and magnetically complex systems. Taking advantage of the parallel processing capabilities of NVIDIA GPUs, NuMagSANS delivers substantial performance improvements compared with conventional CPU-based real-space implementations. This acceleration enables efficient and precise computation of two-dimensional SANS cross sections and correlation functions from large user-defined three-dimensional real-space nuclear scattering-length density and magnetization data. The explicit GPU parallelization and optimization for large micromagnetic datasets distinguish NuMagSANS from existing software solutions, including SASfit (Kohlbrecher & Breßler, 2022 ), mag2exp (Holt et al., 2025 ) and the generic SAS calculator available within the open-source SasView platform (https://www.sasview.org/).

NuMagSANS is implemented in C++ (Stroustrup, 2013 ) and CUDA (NVIDIA Corporation, 2026 ) and is distributed as open-source software under the MIT License at https://github.com/AdamsMP92/NuMagSANS. The version of NuMagSANS used to generate the results presented in this study is archived at Zenodo (Adams, 2026b ). Users are requested to cite this article when employing NuMagSANS in scientific publications. The source code can be obtained from the GitHub repository and compiled using the NVIDIA CUDA compiler via the nvcc command.

The execution of NuMagSANS requires an NVIDIA GPU and a supported operating system (Linux, macOS or Windows). Aside from the standard NVIDIA GPU drivers, no external dependencies are required, facilitating a straightforward installation and configuration process.

NuMagSANS was developed during several theoretical research projects that aimed to advance the understanding of magnetic SANS. The core code was used in studies to simulate the scattering of nanoparticles with Néel surface anisotropy (Adams et al., 2022 ; Adams et al., 2024a ) and to analyze the angular anisotropy of the magnetic SANS cross section of randomly oriented Stoner–Wohlfarth particles (Adams et al., 2023 ). It also enabled detailed investigations of magnetic nanoparticles with pore-type defects (Pratami Sinaga et al., 2023 ), vortex-type spin structures (Adams et al., 2024b ) and the spin-flip SANS related to the Dzyaloshinskii–Moriya interaction (Sinaga et al., 2024 ). Experimental neutron and X-ray studies where micromagnetic simulations have supported the data analysis—and where NuMagSANS would therefore be of relevance—have been reported, for example, by Meynell et al. (2017 ), Mistonov et al. (2019 ), Ukleev et al. (2020 ), Ukleev et al. (2021 ) and Ukleev et al. (2024 ).

Beyond the work presented in the above publications, the current version of NuMagSANS incorporates several important features, including support for nuclear scattering and nuclear–magnetic interference terms. A key strength of NuMagSANS lies in its seamless integration with micromagnetic simulation tools such as MuMax3 (Vansteenkiste et al., 2014 ; Leliaert et al., 2018 ), allowing researchers to directly compute magnetic SANS observables from simulated spin configurations. This capability broadens the scope of the software and enhances its utility to investigate a wide range of magnetic systems.

A particularly promising feature of NuMagSANS is its ability to separate particle form factors from interparticle interference contributions, providing a robust framework for analyzing structure factor effects. This functionality allows researchers to systematically examine how (nuclear and magnetic) interparticle correlations influence scattering cross sections, thereby offering new opportunities to uncover subtle features in complex materials. For example, in studies of skyrmion lattices, isolating the form factor of individual skyrmions and subsequently incorporating the Bragg peaks associated with the skyrmion lattice can yield valuable insights into their mutual interactions. By enabling such detailed analyzes, NuMagSANS provides a versatile and powerful platform for advancing the understanding of intricate scattering phenomena in purely magnetic and hybrid (i.e. nuclear and magnetic) systems.

The four benchmark data sets supporting this work are openly available on Zenodo as part of the NuMagSANS framework (Adams, 2025a ; Adams, 2025b ; Adams, 2025c ; Adams, 2026a ). Each data set contains the corresponding magnetic configuration in real space, the NuMagSANS input and output files, and visualization figures. Together, they provide a reproducible benchmark suite for testing and validating SANS simulations within the NuMagSANS framework.

The article is organized as follows. In Section 2 we provide the expressions for the nuclear and magnetic SANS cross sections and related quantities, such as the pair-distance distribution function and the correlation function. In Section 3 we describe the implementation and workflow of NuMagSANS. Finally, Section 4 features a few example cases.

2. SANS observables

In this section, we provide the basic and well-known expressions for the SANS observables, which include the various unpolarized, polarized, chiral and nuclear–magnetic interference cross sections as well as the ensuing correlation and pair-distance distribution functions. We emphasize that nuclear spin-dependent scattering is not taken into account in NuMagSANS. Fig. 1 depicts the scattering geometry that is implemented in NuMagSANS: the incident neutron beam propagates along the x axis, with the two-dimensional detector placed in the y–z plane (see inset in Fig. 1). This implies that, in the small-angle approximation, the scattering vector $[{\bf q}]$ has only components in the y–z plane. The relevant SANS expressions for the two most-often employed geometries, where the applied magnetic field $[{\bf B}_{0}]$ is perpendicular ( $[{\bf B}_{0}\perp{\bf k}_{0}]$ ) or parallel ( $[{\bf B}_{0}\parallel{\bf k}_{0}]$ ) to the incident neutron beam, are explicitly shown below. The theoretical framework for magnetic neutron scattering is thoroughly discussed by Lovesey (1984 ), Maleev (2002 ), Squires (2012 ), Boothroyd (2016 ) and Michels (2021 ).

Figure 1
Sketch of the neutron scattering geometry that is implemented in NuMagSANS. The neutron optical elements (polarizer, spin flipper, analyzer) that are required to measure the spin-resolved SANS cross sections are not drawn. The external magnetic field $[{\bf B}_{0}\parallel{\bf e}_{z}]$ is here applied perpendicular to the wavevector $[{\bf k}_{0}\parallel{\bf e}_{x}]$ of the incident neutron beam ( $[{\bf B}_{0}\perp{\bf k}_{0}]$ ). The momentum transfer or scattering vector $[{\bf q}]$ is defined as the difference between $[{\bf k}_{0}]$ and $[{\bf k}_{1}]$ , i.e. $[{\bf q} = {\bf k}_{0}-{\bf k}_{1}]$ . Its magnitude for elastic scattering, $[q = ({{4\pi}/ {\lambda}})\sin\psi]$ , depends on the average neutron wavelength λ and on the scattering angle $[2\psi]$ . The angle $[\theta = \angle({\bf q},{\bf e}_{z})]$ is used to describe the angular anisotropy of the scattering pattern on the two-dimensional detector. In the small-angle approximation the component of $[{\bf q}]$ along $[{\bf k}_{0}]$ is small compared with the other two components, so that $[{\bf q}\cong\{0,q_{y},q_{z}\}]$ .

2.1. Basic SANS cross sections and conventions

We begin by introducing the continuum Fourier transforms of the (scalar) nuclear scattering-length density $[N({\bf r}) = N(x,y,z)]$ and the magnetization vector field $[{\bf M}({\bf r}) =]$ $[ \{M_{x}({\bf r}),M_{y}({\bf r}),M_{z}({\bf r})\}]$ :

$[\displaystyle\widetilde{N}({\bf q}) = {{1} \over {(2\pi)^{3/2}}}\int\limits_{{\bb R}^ {3}}N({\bf r})\exp(-i{\bf q}\cdot{\bf r})\ {\rm d}^{3}r,\eqno(1)]$

$[\displaystyle\widetilde{{\bf M}}({\bf q}) = {{1} \over {(2\pi)^{3/2}}}\int\limits_{ {\bb R}^{3}}{\bf M}({\bf r})\exp(-i{\bf q}\cdot{\bf r})\ {\rm d}^{3}r. \eqno(2)]$

These Fourier transforms are functions of the wavevector $[{\bf q} = \{q_{x},q_{y},q_{z}\}]$ , whereas the magnetic SANS cross section (see below) is a function of the scattering vector, say $[{\bf q}^{\prime}]$ , which is the difference between the incident ( $[{\bf k}_{0}]$ ) and scattered ( $[{\bf k}_{1}]$ ) wavevectors of the neutron (compare Fig. 1). In contrast to $[{\bf q}]$ , the quantity $[{\bf q}^{\prime}]$ is not a wavevector, since its magnitude for elastic scattering is not given by $[2\pi/\lambda]$ . However, the SANS cross section at the scattering vector $[{\bf q}^{\prime}]$ depends exclusively on the Fourier components of the magnetization at the wavevector $[{\bf q} = {\bf q}^{\prime}]$ , and a consistent separate handling of the symbols $[{\bf q}]$ and $[{\bf q}^{\prime}]$ would unnecessarily encumber the discussion. In agreement with common usage in the neutron scattering literature, we ignore the distinction between the two quantities and use the symbol $[{\bf q}]$ to denote both the wavevector and the scattering vector. In NuMagSANS the above Fourier integrals are evaluated by discrete sums (see Section 3.3).

The nuclear and (unpolarized) magnetic scattering contributions are then expressed as (Squires, 2012)

$[\displaystyle{{{\rm d}\Sigma_{{\rm N}}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}| \widetilde{N}|^{2} = {{8\pi^{3}} \over {V}}\left(\widetilde{N}\widetilde{ N}^{\ast}\right),\eqno(3)]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma_{{\rm M}}} \over {{\rm d}\Omega}} & = {{8\pi^{3}} \over {V}}b_{\rm {H}}^{2}|\widetilde{{\bf Q}}|^{2} = {{8\pi^{3}} \over {V}}b_{{\rm H }}^{2}\left(\widetilde{{\bf Q}}\cdot\widetilde{{\bf Q}}^{\ast}\right) \cr & = {{8\pi^{3}} \over {V}}b_{{\rm H}}^{2}\left(|\widetilde{Q}_{x}|^{2}\ +\ |\widetilde{Q}_{y}|^{2}\ +\ |\widetilde{Q}_{z}|^{2}\right),&(4)}]$

where V is the scattering volume, $[b_{{\rm H}} = 2.91\times 10^{8}]$ Å⁻¹ m⁻¹ denotes the atomic magnetic scattering length in the small-angle regime, the asterisk ` $[{}^\ast]$ ' refers to the complex conjugate, and

$[\displaystyle\widetilde{{\bf Q}}({\bf q}) = \hat{{\bf q}}\times\left[\hat{{\bf q}}\times\widetilde{{\bf M}}({\bf q})\right]\eqno(5)]$

is known as the Halpern–Johnson or magnetic interaction vector. In NuMagSANS, the incident neutron wavevector $[{\bf k}_{0}]$ is fixed to be parallel to the x direction of a Cartesian laboratory coordinate system, and the detector plane is spanned by the y–z directions (compare Fig. 1). This implies that, in the small-angle approximation, the unit scattering vector $[\hat{{\bf q}}]$ takes on the following form:

$[\displaystyle\hat{{\bf q}} = {{{\bf q}} \over {|{\bf q}|}} = \lbrace0,\sin\theta, \cos\theta\rbrace,\eqno(6)]$

which results in

$[\displaystyle\widetilde{{\bf Q}} = \left\{\matrix{\widetilde{Q}_{x} \cr \widetilde{Q}_{y}\cr \widetilde{Q}_{z}}\right\} = \left\{\matrix{-\widetilde{M}_{ x}\cr \noalign{\vskip1ex}-\widetilde{M}_{y}\cos^{2}\theta+\widetilde{M}_{z}\sin\theta\cos\theta \cr \noalign{\vskip1ex}\widetilde{M}_{y}\sin\theta\cos\theta-\widetilde{M}_{z}\sin^{2}\theta}\right\}.\eqno(7)]$

One of the first inputs the user must specify in NuMagSANS is the direction of the unit vector $[\hat{{\bf P}}]$ . This quantity determines the orientation of the applied magnetic (guide) field $[{\bf B}_{0}]$ with respect to the wavevector $[{\bf k}_{0}]$ of the incoming beam. For example, $[\hat{{\bf P}} = \{0,0,1\}]$ for $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ , while $[\hat{{\bf P}} = \{1,0,0\}]$ for $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ . With this in mind, and for the purpose of computational efficiency, we introduce the following quantity:

$[\displaystyle{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{\rm {H}}^{2}\left|\hat{{\bf P}}\cdot\widetilde{{\bf Q}}\right|^{2},\eqno(8)]$

which represents the projection of the Halpern–Johnson vector $[\widetilde{{\bf Q}}]$ onto the polarization unit vector $[\hat{{\bf P}}]$ . In particular, $[{\rm d}\Sigma_{{\rm P}}/{\rm d}\Omega]$ is an auxiliary quantity that is not directly accessible in a SANS experiment and is typically not analyzed separately. However, it serves as a fundamental building block for the additive construction of directly measurable SANS cross sections, thereby enabling a higher degree of modularity and reusability in theoretical formulations and numerical implementations (see below). For a transverse scattering geometry $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ , we have $[{\rm d}\Sigma_{{\rm P}}/{\rm d}\Omega\propto|\widetilde{Q}_{z}|^{2}]$ , whereas for the longitudinal geometry $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ , it follows that $[{\rm d} \Sigma_{{\rm P}}/{\rm d}\Omega\propto|\widetilde{Q}_{x}|^{2}]$ . More specifically,

$[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$

$[\eqalignno{\displaystyle { {{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}} = \ & {{8\pi^{3}} \over {V}}b_{\rm {H}}^{2}\left[|\widetilde{M}_{y}|^{2}\sin^{2}\theta\cos^{2}\theta+|\widetilde{ M}_{z}|^{2}\sin^{4}\theta \right.\cr & \left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+ \widetilde{M}_{y}^{\ast}\widetilde{M}_{z})\sin^{3}\theta\cos\theta\right].&(9)}]$

$[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$

$[\displaystyle{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{\rm {H}}^{2}\,|\widetilde{M}_{x}|^{2}.\eqno(10)]$

2.2. POLARIS cross sections

In uniaxial or longitudinal polarization analysis experiments (denoted as POLARIS in the SANS community), one has access to four neutron scattering cross sections (spin channels). These include non-spin-flip and spin-flip processes. POLARIS experiments employ neutron optical elements to polarize the beam (relative to the magnetic guide field) before the sample, to flip the neutron spin direction before the sample and to determine its polarization after the scattering process. The four partial cross sections are denoted as $[{\rm d}\Sigma^{++}/{\rm d}\Omega]$ , $[{\rm d}\Sigma^{--}/{\rm d}\Omega]$ , $[{\rm d}\Sigma^{+-}/{\rm d}\Omega]$ and $[{\rm d}\Sigma^{-+}/{\rm d}\Omega]$ , where the first superscript to $[{\rm d}\Sigma/{\rm d}\Omega]$ (e.g. +) refers to the spin state of the incident neutrons, while the second (e.g. −) specifies the spin state of the scattered neutrons. The direction of $[\hat{{\bf P}}\parallel{\bf B}_{0}]$ specifies the quantization axis for neutron spins.

The and spin-flip cross sections can be expressed as follows:

$[\displaystyle{{{\rm d}\Sigma^{+-}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma_{{\rm sf}}} \over {{\rm d}\Omega }}+{{{\rm d}\Sigma_{\chi}} \over {{\rm d}\Omega}},\eqno(11)]$

$[\displaystyle{{{\rm d}\Sigma^{-+}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma_{{\rm sf}}} \over {{\rm d}\Omega }}-{{{\rm d}\Sigma_{\chi}} \over {{\rm d}\Omega}},\eqno(12)]$

where

$[{{{\rm d}\Sigma_{{\rm sf}}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma_{{\rm M}}} \over {{\rm d}\Omega}}- {{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}}\eqno(13)]$

represents the polarization-independent part of the spin-flip SANS cross section and

$[\displaystyle{{{\rm d}\Sigma_{\chi}} \over {{\rm d}\Omega}} = -i{{8\pi^{3}} \over {V}}b_{{\rm H}} ^{2}\,\hat{{\bf P}}\cdot\left(\widetilde{{\bf Q}}\times\widetilde{ {\bf Q}}^{\ast}\right) = -i{{8\pi^{3}} \over {V}}b_{{\rm H}}^{2}\,\chi \eqno(14)]$

is known as the chiral SANS cross section and depends on the polarization of the incident beam ( $[i^{2} = -1]$ ). Equation (13) shows that $[{\rm d}\Sigma_{{\rm sf}}/{\rm d}\Omega\propto(|\widetilde{Q}_{x}|^{2}+|\widetilde{Q}_{y }|^{2})]$ for $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ , while $[{\rm d}\Sigma_{{\rm sf}}/{\rm d}\Omega\propto(|\widetilde{Q}_{y}|^{2}+|\widetilde{Q}_{z }|^{2})]$ for $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ . Equation (14) also defines the function $[\chi({\bf q}) = \hat{{\bf P}}\cdot(\widetilde{{\bf Q}}\times\widetilde{ {\bf Q}}^{\ast})]$ , which for $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ equals

$[\eqalignno{\displaystyle\chi = &\ \widetilde{Q}_{x}\widetilde{Q}_{y}^{\ast}-\widetilde{Q}_{x}^ {\ast}\widetilde{Q}_{y} = \left(\widetilde{M}_{x}\widetilde{M}_{y}^{\ast}- \widetilde{M}_{x}^{\ast}\widetilde{M}_{y}\right)\cos^{2}\theta \cr & -\left(\widetilde{M}_{x}\widetilde{M}_{z}^{\ast}-\widetilde{M}_{x}^{\ast}\widetilde{M }_{z}\right)\sin\theta\cos\theta.&(15)}]$

$[\chi({\bf q})]$ vanishes at complete magnetic saturation ( $[M_{x} = M_{y} = 0]$ ) or for purely real-valued or purely imaginary magnetization Fourier components (irrespective of the value of the field) (Michels et al., 2016 ; Sinaga et al., 2024). For example, for the case where the magnetization distribution is an even function of the position, i.e. $[{\bf M}({\bf r}) = {\bf M}(-{\bf r})]$ , the corresponding Fourier transform $[\widetilde{{\bf M}}({\bf q})]$ is also an even and real-valued function (Brigham, 1974 ), with the consequence that $[\chi({\bf q})]$ vanishes. Similarly, if $[{\bf M}({\bf r})]$ is an odd function, then $[\widetilde{{\bf M}}({\bf q})]$ is an odd and imaginary function, and $[\chi = 0]$ . Note also that $[\chi = 0]$ for $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ .

The ++ and - SANS cross sections are computed in NuMagSANS as

$[\displaystyle{{{\rm d}\Sigma^{++}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma_{{\rm N}}} \over {{\rm d}\Omega}} +{{{\rm d}\Sigma_{{\rm NM}}} \over {{\rm d}\Omega}}+{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}},\eqno(16)]$

$[\displaystyle{{{\rm d}\Sigma^{--}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma_{{\rm N}}} \over {{\rm d}\Omega}} -{{{\rm d}\Sigma_{{\rm NM}}} \over {{\rm d}\Omega}}+{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}},\eqno(17)]$

where $[{\rm d}\Sigma_{{\rm N}}/{\rm d}\Omega]$ is the nuclear coherent SANS, $[{\rm d}\Sigma_{{\rm P}}/{\rm d}\Omega]$ has been defined by equation (8) and

$[\displaystyle{{{\rm d}\Sigma_{{\rm NM}}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{ {\rm H}}\,\hat{{\bf P}}\cdot\left(\widetilde{N}\widetilde{{\bf Q}}^{ \ast}+\widetilde{N}^{\ast}\widetilde{{\bf Q}}\right)\eqno(18)]$

denotes the nuclear–magnetic interference terms. For $[\hat{{\bf P}}\parallel{\bf B}_{0}\parallel]$ $[{\bf e}_{z}\perp{\bf k}_ {0}]$ , $[{\rm d}\Sigma_{{\rm NM}}/{\rm d}\Omega\propto(\widetilde{N}\widetilde{Q}_{z}^{\ast}+ \widetilde{N}^{\ast}\widetilde{Q}_{z})]$ , while for $[\hat{{\bf P}}\parallel{\bf B}_{0}\parallel{\bf e}_{x}\parallel]$ $[{\bf k}_{0}]$ the corresponding term involves $[(\widetilde{N}\widetilde{Q}_{x}^{\ast}+\widetilde{N}^{\ast}\widetilde{Q}_{x})]$ .

In the following, we provide the POLARIS SANS cross sections for a perpendicular $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ and the parallel $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ scattering geometry:

$[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$

$[\eqalignno{ & \displaystyle{{{\rm d}\Sigma^{\pm\pm}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{{\rm H}} ^{2}\left[b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{y}|^{2}\sin^{ 2}\theta\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{4}\theta\right. \cr & \quad \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin^{3}\theta\cos\theta \mp b_{{\rm H}}^{-1}(\widetilde{N}\widetilde{M}_{z}^{ \ast}+\widetilde{N}^{\ast}\widetilde{M}_{z})\sin^{2}\theta \right. \cr & \quad \displaystyle\left.\pm \ b_{{\rm H}}^{ -1}(\widetilde{N}\widetilde{M}_{y}^{\ast}+\widetilde{N}^{\ast}\widetilde{M}_{y })\sin\theta\cos\theta\right],&(19)}]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma^{\pm\mp}} \over {{\rm d}\Omega}} = \ & {{8\pi^{3}} \over {V}}b_{{\rm H}} ^{2}\left[|\widetilde{M}_{x}|^{2}+|\widetilde{M}_{y}|^{2}\cos^{4}\theta+| \widetilde{M}_{z}|^{2}\sin^{2}\theta\cos^{2}\theta\right. \cr & \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin\theta\cos^{3}\theta\mp i\chi\right].&(20)}]$

Although the spin-flip SANS cross section does not depend on the longitudinal Fourier component of the Halpern–Johnson vector ( $[\widetilde{Q}_{z}]$ in the $[\hat{{\bf P}}\parallel{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_ {0}]$ geometry), equation (20) demonstrates that $[{\rm d}\Sigma^{\pm\mp}/{\rm d}\Omega]$ does depend on the longitudinal Fourier component $[\widetilde{M}_{z}]$ of the magnetization. This term gives rise to a pronounced $[\sin^{2}\theta\cos^{2}\theta]$ angular anisotropy of the spin-flip SANS cross section in the saturated state ( $[M_{x} = M_{y} = 0]$ ).

$[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$

$[\displaystyle{{{\rm d}\Sigma^{\pm\pm}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{{\rm H}} ^{2}\left[b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{x}|^{2}\mp b_ {{\rm H}}^{-1}(\widetilde{N}\widetilde{M}_{x}^{\ast}+\widetilde{N}^{\ast} \widetilde{M}_{x})\right],\eqno(21)]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma^{\pm\mp}} \over {{\rm d}\Omega}} =\ & {{8\pi^{3}} \over {V}}b_{{\rm H}} ^{2}\left[|\widetilde{M}_{y}|^{2}\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{2 }\theta\right. \cr & \left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{y}^{\ast} \widetilde{M}_{z})\sin\theta\cos\theta\right].&(22)}]$

Due to the neglect of nuclear spin-dependent SANS, and since $[\chi({\bf q}) = 0]$ for $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ , $[{\rm d}\Sigma^{\pm\mp}/{\rm d}\Omega]$ is independent of the incoming polarization for $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ .

For the determination of the POLARIS cross sections [equations (19)–(22)], it is generally necessary to measure the four partial cross sections to correct for spin leakage between the different channels (Wildes, 2006 ). Such corrections can, e.g., be achieved by means of the Pol-Corr (Krycka et al., 2012b ; Krycka et al., 2012a ) and GRASP (Dewhurst, 2023 ) software tools.

2.3. SANSPOL cross sections

The half-polarized SANS cross sections (known as SANSPOL) are expressed in NuMagSANS as

$[\displaystyle{{{\rm d}\Sigma^{+}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma^{++}} \over {{\rm d}\Omega}}+{{{\rm d} \Sigma^{+-}} \over {{\rm d}\Omega}},\eqno(23)]$

$[\displaystyle{{{\rm d}\Sigma^{-}} \over {{\rm d}\Omega}} = {{{\rm d}\Sigma^{--}} \over {{\rm d}\Omega}}+{{{\rm d} \Sigma^{-+}} \over {{\rm d}\Omega}}.\eqno(24)]$

These cross sections combine non-spin-flip and spin-flip contributions. Using equations (19)–(22), we obtain the following for the perpendicular ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ ) and parallel ( $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ ) scattering geometries:

$[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$

$[\eqalignno{& \displaystyle{{{\rm d}\Sigma^{\pm}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{{\rm H}}^{2 }\left[b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{x}|^{2}+| \widetilde{M}_{y}|^{2}\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{2}\theta\right. \cr & \quad \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin\theta\cos\theta\mp b_{{\rm H}}^{-1}(\widetilde{N}\widetilde{M}_{z}^{\ast}+\widetilde{N}^{\ast}\widetilde{M}_{z}) \sin^{2}\theta\right. \cr & \quad \displaystyle\left.\pm \ b_{{\rm H}}^{-1}(\widetilde{N}\widetilde{M}_{y}^{ \ast}+\widetilde{N}^{\ast}\widetilde{M}_{y})\sin\theta\cos\theta\mp i\chi \right].& (25)}]$

$[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$

$[\eqalignno{& \displaystyle{{{\rm d}\Sigma^{\pm}} \over {{\rm d}\Omega}} = {{8\pi^{3}} \over {V}}b_{{\rm H}}^{2 }\left[b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{x}|^{2}+| \widetilde{M}_{y}|^{2}\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{2}\theta\right. \cr & \quad \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin\theta\cos\theta\mp b_{{\rm H}}^{-1}(\widetilde{N}\widetilde{M}_{x}^{\ast}+\widetilde{N}^{\ast}\widetilde{M}_{x}) \right].&(26)}]$

2.4. Unpolarized SANS cross sections

Finally, the unpolarized SANS cross section is computed according to

$[\eqalignno{\displaystyle{{{\rm d}\Sigma} \over {{\rm d}\Omega}} & = {{1} \over {2}}\left({{{\rm d}\Sigma^{++}} \over {{\rm d} \Omega}}+{{{\rm d}\Sigma^{--}} \over {{\rm d}\Omega}}+{{{\rm d}\Sigma^{+-}} \over {{\rm d}\Omega}}+{{{\rm d} \Sigma^{-+}} \over {{\rm d}\Omega}}\right) \cr \displaystyle & = {{1} \over {2}}\left({{{\rm d}\Sigma^{+}} \over {{\rm d}\Omega}}+{{{\rm d}\Sigma^{-}} \over { {\rm d}\Omega}}\right).&(27)}]$

$[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma} \over {{\rm d}\Omega}} = \ & {{8\pi^{3}} \over {V}}b_{{\rm H}}^{2}\left [b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{x}|^{2}+|\widetilde{M} _{y}|^{2}\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{2}\theta\right. \cr & \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin\theta\cos\theta\right].&(28)}]$

$[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma} \over {{\rm d}\Omega}} =\ & {{8\pi^{3}} \over {V}}b_{{\rm H}}^{2}\left [b_{{\rm H}}^{-2}|\widetilde{N}|^{2}+|\widetilde{M}_{x}|^{2}+|\widetilde{M} _{y}|^{2}\cos^{2}\theta+|\widetilde{M}_{z}|^{2}\sin^{2}\theta\right. \cr & \displaystyle\left.-\ (\widetilde{M}_{y}\widetilde{M}_{z}^{\ast}+\widetilde{M}_{ y}^{\ast}\widetilde{M}_{z})\sin\theta\cos\theta\right].&(29)}]$

We note that equations (28) and (29) are formally identical in their dependence on the Fourier components of the nuclear and magnetic scattering-length density contrasts. However, in an actual experiment or in a micromagnetic simulation, different orientations of the applied field B₀ may lead to different magnetization states inside the sample, so that the Fourier amplitudes entering the two expressions need not be identical.

2.5. Azimuthally averaged SANS cross sections

All the computed two-dimensional SANS data sets $[f(q,\theta)]$ can be azimuthally averaged according to

$[I(q) = {{1} \over {2\pi}}\int\limits_{0}^{2\pi}f(q,\theta)\ {\rm d}\theta,\eqno(30)]$

where θ is the azimuthal angle on the detector plane (compare Fig. 1). The chiral SANS cross section $[{\rm d}\Sigma_{\chi}/{\rm d}\Omega]$ , which exhibits a left–right asymmetry on the two-dimensional detector, always averages to zero using the integral (30). To analyze angular averages of $[{\rm d}\Sigma_{\chi}/{\rm d}\Omega]$ we suggest using the modal decomposition (31) (see below). The integrals in equations (30), (31), (34) and (36) (see below) are numerically solved using the trapezoidal rule.

Beyond the azimuthal average, typically employed for the analysis of experimental data, NuMagSANS includes an advanced angular Fourier decomposition that enables a more detailed quantification of anisotropy in two-dimensional scattering patterns. More specifically, the two-dimensional scattering cross sections are decomposed into sine and cosine harmonics as

$[\displaystyle I_{k}^{{\rm s,c}}(q) = {{2-\delta_{k,0}} \over {2\pi}}\int\limits_{0}^{2 \pi}f(q,\theta)\,\left\lbrace\matrix{\sin(k\theta)\cr \cos(k\theta)}\right\rbrace\ {\rm d}\theta.\eqno(31)]$

These modal intensities $[I_{k}^{{\rm c}}(q)]$ and $[I_{k}^{{\rm s}}(q)]$ represent the angular spectral components of the scattering cross section. Using the q-dependent intensities, NuMagSANS computes the related amplitudes

$[\displaystyle a_{k}^{{\rm s,c}} = \sum_{i}I_{k}^{{\rm s,c}}(q_{i}),\eqno(32)]$

with the following normalization:

$[\displaystyle A_{k}^{{\rm s,c}} = {{a_{k}^{{\rm s,c}}} \over {\sum_{j = 0}^{k_{ {\rm max}}}\sqrt{|a_{j}^{{\rm s}}|^{2}+|a_{j}^{{\rm c}}|^{2}}}}.\eqno(33)]$

These amplitudes allow for a direct anisotropy identification. In NuMagSANS the user can manually select a $[k_{{\rm max}}]$ , which is the highest modal order up to which the SANS cross section is being decomposed ( $[0\leq k\leq k_{{\rm max}}]$ ). For example, a twofold $[\sin^{2}\theta]$ anisotropy yields $[A_{0}^{{\rm c}}/A_{2}^{{\rm c}} = -1]$ , whereas for the case of a fourfold $[\sin^{2}\theta\cos^{2}\theta]$ anisotropy $[A_{0}^{{\rm c}}/A_{4}^{{\rm c}} = -1]$ .

2.6. Correlation and pair-distance distribution functions

Azimuthally averaged SANS cross sections I(q) can be further analyzed by applying the inverse Fourier transform to obtain real-space correlation functions and pair-distance distribution functions. These quantities provide insights into the internal structure and characteristic length scales of the sample. The correlation function c(r) and the pair-distance distribution function p(r) are calculated by numerically solving the following equations:

$[\displaystyle c(r) = {{1} \over {2\pi^{2}}}\int\limits_{0}^{\infty}I(q)\,j_{0}(qr)\,q^{2}\ {\rm d}q,\eqno(34)]$

$[\displaystyle p(r) = r^{2}\,c(r),\eqno(35)]$

where $[j_{0}(x) = (\sin x)/x]$ denotes the zeroth-order spherical Bessel function. For detailed discussions of the properties of p(r) and for practical aspects of its computation via indirect Fourier transformation, we refer the reader to the review articles by Glatter & Kratky (1982 ) and Svergun & Koch (2003 ).

In addition to the one-dimensional correlation functions, NuMagSANS supports the computation of two-dimensional correlation functions, which are defined as the inverse two-dimensional Fourier transforms of the two-dimensional SANS cross sections $[{{{\rm d}\Sigma}/{{\rm d}\Omega}} = ({{{\rm d}\Sigma} / {{\rm d}\Omega}})(q,\theta)]$ :

$[\displaystyle C(\rho,\alpha) = \int\limits_{0}^{2\pi}\!\int\limits_{0}^{\infty}{{{\rm d}\Sigma} \over { {\rm d}\Omega}}(q,\theta)\exp\left[iq\rho\cos(\theta-\alpha)\right]\,q\ {\rm d}q\ {\rm d}\theta, \eqno(36)]$

where $[\rho = \sqrt{x^2 + y^2}]$ and $[\tan\alpha = y/x]$ . The one-dimensional correlation function c(r) and the azimuthal average of the two-dimensional correlation function $[C(\rho,\alpha)]$ (with respect to α) are connected via an Abel transform. Therefore, c(r) is not just simply the azimuthal average of $[C(\rho,\alpha)]$ (Michels, 2021).

3. Program description: implementation and workflow

The implementation and workflow of NuMagSANS are organized into several modular components, as outlined in Fig. 2. These components allow for a streamlined and efficient calculation of SANS observables based on the real-space nuclear scattering-length density, the magnetization distribution and the structural (object position) data provided by the user. This section provides an overview of the overall workflow, followed by detailed discussions of the configuration file, the real-space data organization, the summation methodology and the SANS data computation.

Figure 2
Schematic of the basic workflow of NuMagSANS (see the main text for explanations).

As shown in Fig. 2, the workflow begins with the configuration file, which serves as the central input to specify the parameters and settings required for the SANS computations. The configuration file is parsed by the configuration file interpreter, which initializes the workflow by providing relevant parameters to other modules.

Next, the data explorer modules (NucDataExplorer, MagDataExplorer, StructDataExplorer) manage the user-supplied nuclear scattering-length density, magnetization vector field and structural data, collectively referred to as real space data. These data are crucial for defining the physical system to be analyzed.

The real-space data are subsequently processed during the memory allocation and initialization phase, where both the input real-space and the output SANS data structures are loaded into the RAM. Following this, the real-space data are transferred to the GPU memory to leverage CUDA for high-performance computation of the SANS observables. Once the calculations are complete, the resulting SANS data are saved to the hard drive, and both RAM and GPU memory are cleared to prepare for subsequent runs.

In the following subsections, we describe the role and structure of the configuration file (Section 3.1), the organization of the real-space input data (Section 3.2), the summation scheme (Section 3.3), and the organization of the output data for the SANS observables (Section 3.4).

3.1. Configuration file

The configuration file serves as the central control unit for defining all input parameters, simulation settings and data paths required for a NuMagSANS computation. It is a human-readable text file located in the main directory of the GitHub repository under the name NuMagSANSInput.conf. The file is parsed by the internal configuration interpreter, which initializes the workflow and allocates the corresponding memory structures.

In this configuration file, the user specifies the following information:

(1) the paths to the nuclear, magnetic and structural (object position) data

—denoted in the configuration file as NucDataPath, MagDataPath and StructDataFilename

(2) the output directory name, where all simulation results are stored

—denoted as foldernameSANSData in the configuration file

(3) whether nuclear, magnetic or structural contributions are activated

—denoted in the configuration file as NucData_activate, MagData_activate and StructData_activate

(4) the computational mode (atomistic or micromagnetic) to be applied

—denoted as Fourier_Approach in the configuration file

(5) the saturation magnetization $[M_{{\rm s}}]$ (in A m⁻¹, micromagnetic simulation mode only)

—denoted as Cell_Magnetization in the configuration file

(6) the proportionality factor $[N_{{\rm s}}]$ for the nuclear scattering-length density (SLD, in m⁻², mesoscopic simulation mode only)

—denoted as Cell_Nuclear_SLD in the configuration file

(7) the scaling factor s for the lattice length scale (if the input data are in nm then ; if the input data are in metres then $[s = 10^{9}]$ ; if the input data are in Å then $[s = 10^{-1}]$ )

—denoted as XYZ_Unit_Factor in the configuration file

(8) the discretization volume a_x,a_y,a_z used in the micromagnetic simulations (in nm)

—denoted as Cuboid_Cell_Size_x, Cuboid_Cell_Size_y and Cuboid_Cell_Size_z in the configuration file

(9) the total scattering volume V (in m³), which is required for computing absolute SANS intensities

—denoted as Scattering_Volume_V in the configuration file

(10) the maximum scattering vector magnitude range $[q_{{\rm max}}]$ (in nm⁻¹); note that $[q_{{\rm min}} = 0]$ is fixed

—denoted as q_max in the configuration file

(11) the corresponding real-space range $[r_{{\rm max}}]$ (in nm) for the computation of correlation functions

—denoted as r_max in the configuration file

(12) the q, θ, r and α resolution (number of bins; a typical value is 1000)

—denoted as Number_Of_q_Points, Number_Of_theta_Points, Number_Of_r_Points and Number_Of_alpha_Points, respectively, in the configuration file

(13) two sample rotation angles, α and β (in °), describing rotations of the sample with respect to the fixed laboratory coordinate system

—denoted as RotMat_alpha and RotMat_beta in the configuration file

(14) Cartesian components of the polarization direction vector $[\hat{{\bf P}} = \{\hat{P}_{x},\hat{P}_{y},\hat{P}_{z}\}]$ (internally normalized) relative to the fixed laboratory coordinate system

—denoted as Polarization_x, Polarization_y and Polarization_z in the configuration file

(15) optional loop modes that enable automated batch runs for field-dependent, temperature-dependent or time-dependent real-space data sets

(16) the desired outputs, selected by 0 or 1

We emphasize that the user does not need to change the options in the configuration file, as it acts as a fixed template where the user can specify the relevant metadata like data path, system properties and desired outputs.

In the atomistic simulation mode (in the configuration file Fourier_Approach = atomistic), the parameters a_x, a_y, a_z are irrelevant, as the atomic positions are treated as discrete point objects. Likewise, the saturation magnetization $[M_{{\rm s}}]$ is not used, since the atomic magnetic moments are expressed in units of the Bohr magneton $[\mu_{{\rm B}} =9.274]$ × $[ 10^{-24}]$ J T⁻¹, and the nuclear scattering length is given in units of $[10^{-15}]$ m.

In the micromagnetic simulation mode (in the configuration file Fourier_Approach = micromagnetic), where the data typically originate from MuMax3-type simulations, the user must specify the simulation-cell-size parameters a_x,a_y,a_z (in nm) and the saturation magnetization $[M_{{\rm s}}]$ (in A m⁻¹), which serves as a scaling factor for the magnetization vectors. Similarly, for nuclear scattering-length density data in the mesoscopic mode, a proportionality factor $[N_{{\rm s}}]$ can be defined to match the physical scattering-length density contrast.

In the micromagnetic (mesoscopic) simulation mode, where an idealized continuous (nonperiodic) nuclear scattering-length density and magnetization vector field are considered, the resulting SANS cross section does not exhibit Bragg reflections originating from the atomic crystal structure. In contrast, as NuMagSANS handles numerical data sets (e.g. from micromagnetic solvers such as MuMax3), spurious Bragg peaks can appear due to the underlying numerical grid used in the simulations. To avoid these artifacts, the maximum accessible scattering vector magnitude $[q_{{\rm max}}]$ should be chosen so that these discretization-induced peaks are excluded. For instance, if the discretization is defined by $[a_{x} = a_{y} = a_{z} = a]$ , the first artificial Bragg peak arising from the discrete real-space lattice (numerical grid) is expected to appear at

$[q_{{\rm Bragg}} = {{2\pi} \over {a}}.]$

A suitable choice is to limit the data to the Nyquist condition:

$[q_{{\rm max}}\simeq q_{{\rm Nyquist}} = {{\pi} \over {a}}.]$

This ensures that the SANS intensity is sampled within the physically significant Fourier range of the input field.

For the correlation functions, the maximum correlation distance $[r_{{\rm max}}]$ should be chosen to be equal to or larger than the largest geometrical distance represented in the input data. For correlation distances that exceed the largest geometrical distance in the user input data, the one-dimensional correlation functions and pair-distance distribution functions are typically expected to vanish for compact objects. This behavior is confirmed analytically for a uniformly magnetized sphere (Section 4.1) and for a linear vortex configuration (Section 4.2) [see also Adams et al. (2023) and Adams et al. (2024b)] and can therefore be used as a numerical consistency check within NuMagSANS. However, this condition is in general not fulfilled for the two-dimensional magnetic correlation functions, since the two-dimensional SANS cross section depends on the Fourier transform of the magnetic induction field $[{\bf B}({\bf r})]$ , which may give rise to correlations both inside and outside of the sample due to stray-field contributions.

In the case of polarized SANS, the direction of the polarization unit vector $[\hat{{\bf P}} = \{P_{x},P_{y},P_{z}\}]$ must be selected. The choice of $[\hat{{\bf P}}\parallel{\bf B}_{0}]$ allows the user to define the standard (most-often employed) scattering geometries: $[\hat{{\bf P}} = \{0,0,1\}]$ or $[\hat{{\bf P}} = \{0,1,0\}]$ (perpendicular) or $[\hat{{\bf P}} = \{1,0,0\}]$ (parallel), referring to the relative orientation of the polarization vector and the neutron beam.

The configuration file also allows for the definition of two sample rotation angles, α and β, which describe the rotations of the sample with respect to the fixed laboratory coordinate system. The rotation matrix is defined as a composition of z- and y-axis rotations:

$[\displaystyle{\bf R}(\alpha,\beta) = {\bf R}_{z}(\beta)\,{\bf R}_{y}(\alpha) = \left\{\matrix{R_{11}&R_{12}&R_{13}\cr R_{21}&R_{22}&R_{23}\cr R_{31}&R_{32}&R_{33}}\right\}.\eqno(37)]$

The rotation matrix $[{\bf R}]$ only acts on the positional and magnetic vector input data described below and does not act on the polarization direction vector $[\hat{{\bf P}}]$ . We use active right-handed rotations acting on the spatial coordinates. This allows for the independent sample rotation and selection of the polarization direction $[\hat{{\bf P}}]$ .

A typical example is the micromagnetic simulation of a nanoparticle under an external magnetic field $[{\bf B}_{0}]$ applied along the z-axis direction. For this configuration, $[\alpha = \beta = 0]$ corresponds to the perpendicular scattering geometry, since the neutron beam is always assumed to be parallel to the x axis, and the polarization vector $[\hat{{\bf P}} = \{0,0,1\}]$ is directed along the applied field. To switch to the parallel scattering geometry ( $[\hat{{\bf P}}\parallel{\bf B}_{0}\parallel{\bf k}_{0}]$ ), the user sets $[\alpha = 90]$ ° and $[\beta = 0]$ , which corresponds to a 90° rotation of the sample around the y axis, and the polarization direction must be set to $[\hat{{\bf P}} = \{1,0,0\}]$ . Conversely, if a micromagnetic simulation was performed by selecting the applied magnetic field parallel to the neutron beam direction, which is fixed to $[{\bf k}_{0}\parallel{\bf e}_{x}]$ ( $[{\bf B}_{0}\parallel{\bf e}_{x}\parallel{\bf k}_{0}]$ ), the parallel scattering geometry in NuMagSANS is defined by $[\alpha = 0]$ , $[\beta = 0]$ and $[\hat{{\bf P}} = \{1,0,0\}]$ , as the sample is already oriented correctly, while the perpendicular scattering geometry is selected by $[\alpha = -90^{\circ}]$ , $[\beta = 0]$ and $[\hat{{\bf P}} = \{0,0,1\}]$ .

3.2. Real-space input data

As well as the configuration file, NuMagSANS deals with three different types of input data: one for the nuclear structure, one for the magnetic structure and one for the structural data describing the spatial arrangement of the objects (particles). The structure of the respective types of files is as follows:

(i) Nuclear scattering-length density data (NucData): $[\{x^{kl},y^{kl},z^{kl},\nu^{kl}\}]$ .

(ii) Magnetic data (MagData): $[\{x^{kl},y^{kl},z^{kl},\mu_{x}^{kl},\mu_{y}^{kl},\mu_{z}^{kl}\}]$ .

(iii) Global object position data (StructData): {r_x^k,r_y^k,r_z^k}.

Here x^kl, y^kl, z^kl specify the position data corresponding to the nuclear scattering-length data $[\nu^{kl}]$ or the magnetic vector data $[\mu_{x}^{kl}]$ , $[\mu_{y}^{kl} ]$ , $[\mu_{z}^{kl}]$ . The parameters r_x^k, r_y^k, r_z^k specify additional structural data for advanced analysis (see below). Possible file extensions are .txt, .csv and .obj, and the data files are always expected to have a columnar structure with a space as delimiter (see Table 1). In the configuration file, the user must select the types (nuclear, magnetic, structural) of input data. For example, in the following configuration file, MagData is activated, and NucData and StructData are deactivated:

$[\eqalign{ & {\tt NucData\_activate = 0} \semi \cr & \quad / / \ {\tt activate\ nuclear\ data\ (1 = on, 0 = off)}\cr &{\tt MagData} \_{\tt activate = 1}\semi \cr & \quad / / \ {\tt activate \ magnetic\ data \ (1 = on, 0 = off)} \cr & {\tt StructData\_activate = 0}\semi \cr &\quad / / \ {\tt activate \ structure \ data \ (1 = on, 0 = off)}}]$

Table 1
Example of the contents of a magnetic data file (MagData) used by NuMagSANS

Note that the actual data file does not include the headers (numbers only). Each horizontal row lists the spatial coordinates {x,y,z} of a voxel and the associated magnetization vector $[\{\mu_{x},\mu_{y},\mu_{z}\}]$ . The example shown corresponds to the test data set of a uniformly magnetized nanoparticle, where all magnetization vectors point along the z direction (see Section 4.1).

x	y	z	μ_x	μ_y	μ_z
0.0	−20.0	0.0	0.0	0.0	1.0
−6.0	−19.0	−1.0	0.0	0.0	1.0
−6.0	−19.0	0.0	0.0	0.0	1.0
−6.0	−19.0	1.0	0.0	0.0	1.0
−5.0	−19.0	−3.0	0.0	0.0	1.0
−5.0	−19.0	−2.0	0.0	0.0	1.0
−5.0	−19.0	−1.0	0.0	0.0	1.0
−5.0	−19.0	0.0	0.0	0.0	1.0
−5.0	−19.0	1.0	0.0	0.0	1.0
−5.0	−19.0	2.0	0.0	0.0	1.0
:	:	:	:	:	:

The input data indexing is organized as follows:

(i) Object index (e.g. a particle with a certain orientation): $[k = \{0,1,2,\ldots,K-1\}]$ .

(ii) Atom/cell index inside object k: $[l = \{0,1,2,\ldots, ]$ $[N_{k}-1\}]$ .

(iii) Total number of objects (e.g. particles) in the sample: K.

(iv) Total number of atoms/cells per object: N_k.

(v) Total number of atoms/cells per sample: $[W = \sum_{k = 0}^{K-1}N_{k}]$ .

(vi) Average number of atoms/cells per object: $[\overline{N} = W/K]$ .

The use of distinct indices k and l reflects the hierarchical data organization shown in Fig. 3. The index k labels individual objects (Object_1, Object_2,…) within the sample, whereas the index l enumerates the discretized magnetization data entries within the corresponding data files (m_1.csv, m_2.csv,…) associated with each object. The two-index notation is therefore required to distinguish between the object level (k) and the intra-object discretization level (l). This structure enables the treatment of systems as either perfectly diluted or interacting, thereby allowing the investigation of interparticle scattering effects, as illustrated in Fig. 9.

Figure 3
Organization of the real-space input data used by NuMagSANS. (a) General case in which all input channels are active: nuclear SLD data (NucData), magnetic vector-field data (MagData) and an optional structural description (StructData.csv) defining the spatial arrangement of multiple objects. This setup enables simulations ranging from fully dilute ensembles (no interparticle interference) to ordered or densely packed systems that exhibit structure factor effects. Users may either represent many individual particles or encode the entire sample in a single object. (b) Case with only magnetic data activated, corresponding to code listing in Section 3.2. This situation corresponds to a dilute particle system, since no structural data are specified.

We reemphasize that in the atomistic simulation mode the atomic magnetic moment components $[\mu_{x}^{kl}]$ , $[\mu_{y}^{kl}]$ , $[\mu_{z}^{kl}]$ are expressed in units of the Bohr magneton $[\mu_{{\rm B}} = 9.274]$ × $[ 10^{-24}]$ J T⁻¹. The corresponding magnetic moment in SI units is given by $[{\bf m}^{kl} = \mu_{{\rm B}}{\boldmu}^{kl}]$ . In the micromagnetic simulation mode, the quantities $[\mu_{x}^{kl}]$ , $[\mu_{y}^{kl}]$ , $[\mu_{z}^{kl}]$ are dimensionless and represent the components of the normalized magnetization vector. The physical magnetization is defined as $[{\bf M}^{kl} = M_{{\rm s}}{\boldmu}^{kl}]$ , where $[M_{{\rm s}}]$ (in A m⁻¹) is specified in the configuration file. The magnetic moment of a cell is then given by $[{\bf m}^{kl} = V_{{\rm cell}}M_{{\rm s}}{\boldmu}^{kl},]$ with the cell volume defined as $[V_{{\rm cell}} = a_{x}a_{y}a_{z}]$ .

Likewise, in the atomistic simulation mode the quantities $[\nu^{kl}]$ are given in units of $[10^{-15}]$ m, corresponding directly to nuclear scattering lengths $[n^{kl} = \nu^{kl}\times 10^{-15}]$ m. In the micromagnetic (continuum) simulation mode, $[\nu^{kl}]$ are dimensionless. The physical nuclear scattering-length density is obtained by scaling with the factor $[N_{\rm s}]$ (in units of m⁻²), specified in the configuration file, such that $[\rho_{{\rm n}}^{kl} = N_{\rm s}\nu^{kl}]$ . The corresponding nuclear scattering length of a cell is then given by $[n^{kl} = V_{{\rm cell}}N_{\rm s}\nu^{kl}]$ .

For the simulation of complex systems and big data, we need a well-organized structure for the input data sets. In Fig. 3, we show that in the main data directory we have two directories, NucData and MagData, and the StructData file. A concrete example case is a dilute ensemble of 800 spherical iron nanoparticles with 1000 different applied magnetic fields $[{\bf B}_{0}]$ along the hysteresis loop (Adams et al., 2024b). For the 800 iron spheres (= objects), each one having a different orientation of its magnetic anisotropy axis with respect to $[{\bf B}_{0}]$ , this means that we have a MagData directory that includes 800 directories (Object_1…Object_800), where each of these 800 directories stores 1000 magnetic structure data files (m_1.csv…m_1000.csv) corresponding to the different applied fields. Note that the numbering of these directories and files must be continuous, starting from `1'.

The global object position data r_x,r_y,r_z allow the user to perform an advanced analysis, where the effects between interacting and noninteracting objects can be studied. In the noninteracting case, the global object position data are not needed, and the StructData.csv file can be excluded in the configuration file (see code listing above). For the case of interacting objects, the user needs to generate their own global object position data that define the spatial arrangement of the objects. Examples for StructData.csv files are discussed in Section 4.3 and provided on Zenodo (Adams, 2025c).

For the case of nonzero rotation angles $[\alpha,\beta]$ (see Section 3.1), the transformation of the global position data x^kl+r_x^k, y^kl+r_y^k, z^kl+r_z^k is then performed as

$[\displaystyle X^{kl} = s[R_{11}(x^{kl}+r_{x}^{k})+R_{12}(y^{kl}+r_{y}^{k})+R_{13 }(z^{kl}+r_{z}^{k})],\eqno(38)]$

$[\displaystyle Y^{kl} = s[R_{21}(x^{kl}+r_{x}^{k})+R_{22}(y^{kl}+r_{y}^{k})+R_{23 }(z^{kl}+r_{z}^{k})],\eqno(39)]$

$[\displaystyle Z^{kl} = s[R_{31}(x^{kl}+r_{x}^{k})+R_{32}(y^{kl}+r_{y}^{k})+R_{33 }(z^{kl}+r_{z}^{k})].\eqno(40)]$

Note that for a noninteracting (dilute) system, r_x^k, r_y^k, r_z^k are all equal to zero, and s is the XYZ_Unit_Factor which is equal to unity if the spacial input is in units of nanometres.

In NuMagSANS a fixed scattering geometry is implemented, where the incoming neutron beam is parallel to the $[{\bf e}_{x}]$ direction of a Cartesian laboratory coordinate system and the two-dimensional detector plane is spanned by the Fourier coordinates $[q_{y} = q\sin\theta]$ and $[q_{z} = q\cos\theta]$ (compare Fig. 1). This means that NuMagSANS computes two-dimensional scattering cross sections as a function of the two polar Fourier coordinates $[(q,\theta)]$ . For the further analysis (e.g. azimuthal averages), it is convenient to define the following phase function $[\Psi^{kl}(q,\theta)]$ :

$[\displaystyle\Psi^{kl}(q,\theta) = q(Y^{kl}\sin\theta+Z^{kl}\cos\theta),\eqno(41)]$

which is used in the Fourier summation approach.

3.3. Summation approach

The Fourier transform $[\widetilde{{\bf M}}({\bf q})]$ of the magnetization vector field is expressed in units of A m², whereas the Fourier transform $[\widetilde{N}({\bf q})]$ of the nuclear scattering-length density is expressed in units of m. The corresponding discrete-space Fourier transforms (DSFTs) are given by

$[\displaystyle\widetilde{N}({\bf q}) = {{1} \over {(2\pi)^{3/2}}}\sum_{j}n_{j}\exp (-i{\bf q}\cdot{\bf r}_{j}),\eqno(42)]$

$[\displaystyle\widetilde{{\bf M}}({\bf q}) = {{1} \over {(2\pi)^{3/2}}}\sum_{j} {\bf m}_{j}\exp(-i{\bf q}\cdot{\bf r}_{j}),\eqno(43)]$

where the index `j' enumerates the real-space discretization cells (or atoms) with coordinates $[{\bf r}_{j}]$ . The vectors $[{\bf m}_{j}]$ represent the cell or atomic magnetic moments in units of A m², and n_j are the corresponding nuclear scattering lengths in units of m. This DSFT formulation serves as the basis for further developments in complex particle systems.

Since C++/CUDA does not support complex-number arithmetic in kernel code, the real and imaginary parts of the Fourier transforms are computed separately via discrete cosine and sine transforms according to

$[\displaystyle\widetilde{\nu}{\, }^{\rm R}(q,\theta) = +{{1} \over {\sqrt{W\overline{N}}}}\sum _{k = 0}^{K-1}\sum_{l = 0}^{N_{k}-1}\nu^{kl}\cos[\Psi^{kl}(q,\theta)],\eqno(44)]$

$[\displaystyle\widetilde{\nu}{\, }^{\rm I}(q,\theta) = -{{1} \over {\sqrt{W\overline{N}}}}\sum _{k = 0}^{K-1}\sum_{l = 0}^{N_{k}-1}\nu^{kl}\sin[\Psi^{kl}(q,\theta)],\eqno(45)]$

$[\displaystyle\widetilde{\mu}_{\alpha}^{\rm R}(q,\theta) = +{{1} \over {\sqrt{W\overline {N}}}}\sum_{k = 0}^{K-1}\sum_{l = 0}^{N_{k}-1}\mu_{\alpha}^{kl}\cos[\Psi^{kl}(q, \theta)],\eqno(46)]$

$[\displaystyle\widetilde{\mu}_{\alpha}^{\rm I}(q,\theta) = -{{1} \over {\sqrt{W\overline {N}}}}\sum_{k = 0}^{K-1}\sum_{l = 0}^{N_{k}-1}\mu_{\alpha}^{kl}\sin[\Psi^{kl}(q, \theta)],\eqno(47)]$

where $[\alpha\in\{x,\,y,\,z\}]$ and the Fourier sums are scaled by the factor $[(W\overline{N})^{-1/2}]$ , which is introduced solely as an intermediate numerical rescaling factor in order to keep the magnitude of the Fourier sums well conditioned during the computation. Since the physical cross section involves the squared moduli of these quantities, the factor $[(W\overline{N})^{-1/2}]$ reappears in the corresponding normalization step and cancels out exactly in the final physical result. These summations are executed in parallel on the GPU for each Fourier-space tuple $[\{q_{i},\theta_{j}\}]$ , providing the primary performance gain compared with a sequential CPU implementation. The resulting nuclear ( $[\widetilde{\nu}]$ ) and magnetic ( $[\widetilde{\mu}]$ ) Fourier components are then used to construct the Halpern–Johnson vector and the corresponding unpolarized and polarized SANS cross sections.

To obtain the SANS cross section in absolute units of cm⁻¹, the cross section data are rescaled prior to their export. For example, in the atomistic simulation mode, the scaling factor for the purely magnetic contribution reads

$[\displaystyle{{{\rm d}\Sigma_{{\rm M}}} \over {{\rm d}\Omega}} = W\overline{N}\,{{b_{ {\rm H}}^{2}} \over {V}}\mu_{{\rm B}}^{2}{{{\rm d}S_{{\rm M}}} \over {{\rm d}\Omega}},\eqno(48)]$

where $[\mu_{{\rm B}} = 9.274\times 10^{-24}]$ J T⁻¹ denotes the Bohr magneton and $[{{{\rm d}S_{{\rm M}}}/ {{\rm d}\Omega}}]$ represents the dimensionless magnetic SANS cross section that is evaluated internally from equations (44)–(47) prior to multiplication with the physical prefactors. The factor $[8\pi^{3}]$ does not appear explicitly in equation (48) since it cancels out with the normalization of the unitary Fourier transform defined in equation (43).

The combination of the local position data $[{\bf x}^{kl} =]$ $[ \{x^{kl},y^{kl},z^{kl}\}]$ and the global object position data $[{\bf r}^{k} =]$ $[ \{r_{x}^{k},r_{y}^{k},r_{z}^{k}\}]$ generally leads to the following summation relation for the scattering amplitude (here given for the example of nuclear scattering):

$[\eqalignno{& \displaystyle\left|\sum_{k}\sum_{l}\nu^{kl}\exp[-i{\bf q}\cdot({\bf x}^{ kl}+{\bf r}^{k})]\right|^{2} = \sum_{k}\left|\sum_{l}\nu^{kl}\exp(-i{\bf q }\cdot{\bf x}^{kl})\right|^{2} \cr & \displaystyle+\sum_{k}\sum_{k^{\prime}\neq k}\sum_{l}\sum_{l^{\prime}}\nu^{kl} \nu^{k^{\prime}l^{\prime}}\exp\{-i{\bf q}\cdot[({\bf x}^{kl}+{\bf r}^{ k})-({\bf x}^{k^{\prime}l^{\prime}}+{\bf r}^{k^{\prime}})]\}.\cr & &(49)}]$

The first term on the right-hand side, with the summation over k outside the absolute square expression, describes the averaged intraparticle contributions, whereas the second term accounts for the interparticle interference between different objects $[k\neq k^{\prime}]$ .

By contrast, for a dilute or noninteracting system, where no StructData are provided by the user, the summation simplifies to (Michels, 2021)

$[\displaystyle\left|\sum_{k}\sum_{l}\nu^{kl}\exp[-i{\bf q}\cdot({\bf x}^{ kl}+{\bf r}^{k})]\right|^{2}\cong\sum_{k}\left|\sum_{l}\nu^{kl}\exp(-i {\bf q}\cdot{\bf x}^{kl})\right|^{2},\eqno(50)]$

where all interparticle interference terms are neglected.

3.4. Fourier and real-space output data

The output data of NuMagSANS consist of four CSV files named SANS1D.csv, SANS2D.csv, Corr1D.csv and Corr2D.csv, and an additional directory named AngularSpectrum that contains the results computed by equations (31) and (33). In the case of magnetic-field-dependent data, where the user data set comprises multiple real-space files (m_1.csv, m_2.csv,…) and the loop mode is enabled, a separate output folder named SANS_i is created for each index i (e.g. magnetic field value). This contains the corresponding set of output files (four CSV files), as illustrated in Fig. 4.

Figure 4
Directory structure of the NuMagSANS_Output folder generated by NuMagSANS. The file NuMagSANSlog.txt acts as a metadata record of all program steps and the user-defined settings specified in NuMagSANSInput.conf. Depending on how many parameter sets were requested (e.g. applied field values), the output contains several subdirectories SANS_i. Each SANS_i directory includes the two-dimensional SANS cross section (SANS2D.csv); the azimuthally averaged intensity I(q) according to equation (30) (SANS1D.csv); the two-dimensional real-space correlation function $[C(\rho,\alpha)]$ from equation (36) (Corr2D.csv); and the one-dimensional correlation and pair-distance distribution functions c(r) and p(r), defined in equations (34) and (35) (Corr1D.csv). Furthermore, each directory may contain an AngularSpectrum folder, which stores the modal sine and cosine intensities $[I_{k}^{{\rm s,c}}(q)]$ computed from equation (31) and the corresponding normalized modal amplitudes $[A_{k}^{{\rm s,c}}]$ defined in equation (33).

The files SANS1D.csv and SANS2D.csv contain the azimuthally averaged and the two-dimensional magnetic SANS cross sections, respectively. The scattering vector magnitude q is provided in units of nm⁻¹, the detector angle θ is in radians and the scattering cross section is in units of cm⁻¹. The SANS2D.csv file stores the two-dimensional SANS cross sections in a single-column format. For post-processing, the data must therefore be rearranged, for example using the reshape function in MATLAB or the reshape function of the NumPy package (https://numpy.org/) for Python. The same logic applies to the two-dimensional correlation function data file Corr2D.csv.

In addition to the two-dimensional SANS cross sections, the user can also export the Fourier cross-correlation function components (cross-energy density spectra) of the magnetization vector field (or atomistic magnetic moment lattice). These quantities can be optionally exported to the SANS2D.csv file. These Fourier correlation functions are generally complex quantities, meaning that the exported data are stored as separate real and imaginary parts:

$[\displaystyle G_{\alpha\beta}^{\rm R}(q,\theta) = {\rm Re}\{\widetilde{M}_{\alpha }(q,\theta)\widetilde{M}_{\beta}^{\ast}(q,\theta)\},\eqno(51)]$

$[\displaystyle G_{\alpha\beta}^{\rm I}(q,\theta) = {\rm Im}\{\widetilde{M}_{\alpha }(q,\theta)\widetilde{M}_{\beta}^{\ast}(q,\theta)\},\eqno(52)]$

where $[\alpha,\beta\in\{x,y,z\}]$ .

The file Corr1D.csv contains the one-dimensional correlation functions (34) and the related pair-distance functions (35), and the file Corr2D.csv contains the two-dimensional correlation functions (36). In the output files the correlation distance r is given in nm, the correlation functions are expressed in units of nm⁻⁴ and the pair-distance distribution functions are in units of nm⁻².

4. Verification and applications

As part of the validation and benchmarking of the NuMagSANS software package, it is essential to employ reference problems with known analytical solutions. In Section 4.1, we examine the classic case of a spherical nanomagnet with a uniform nuclear scattering-length density and a uniform magnetization. This benchmark is widely used in SANS modeling because it is mathematically tractable, is physically well understood, and admits closed-form expressions for the relevant real- and reciprocal-space quantities. It is therefore ideally suited for verifying the correctness of the implemented SANS cross-section calculations, conducting regression tests for future software versions and comparing NuMagSANS output with that of other scattering codes. In addition, the symmetry and simplicity of this model make it a convenient baseline for exploring extensions such as nonuniform magnetization textures, polydispersity or particle assemblies. In Section 4.2, we consider a more complex yet analytically tractable system: a spherical nanomagnet exhibiting a (nonuniform) linear vortex structure. In Section 4.3, we demonstrate the integration of NuMagSANS into a MuMax3-based large-scale simulation workflow, using an ensemble of inhomogeneously magnetized iron nanoparticles with randomly oriented magnetic anisotropy axes as a representative test case. Finally, in Section 4.4, we assess the computational performance and scaling behavior of NuMagSANS by performing a dedicated runtime experiment using an analytically well-defined micromagnetic test system.

The analytical formulas for the various SANS cross sections and pair-distance distribution functions that are presented in Sections 4.1 and 4.2 are used to calculate the numerical values given in Tables 2 and 3. These provide reference values for the corresponding NuMagSANS simulations shown in Figs. 5–8.

Both approaches are based on the same scattering formalism. The difference lies in the representation of the system (continuous analytical model versus discretized real-space configuration). Consequently, small systematic differences may arise from discretization effects, such as variations in effective volume or boundary representation.

4.1. Spherical form factor model

4.1.1. Model definition

In real space, the nuclear scattering-length density $[N({\bf r})]$ and the magnetization vector field $[{\bf M}({\bf r})]$ are modeled as

$[\displaystyle N({\bf r}) = N_{0}\,\Theta\left(1-{{r} \over {R}}\right),\eqno(53)]$

$[\displaystyle{\bf M}({\bf r}) = M_{0}\,{\bf n}\,\Theta\left(1-{{r } \over {R}}\right),\eqno(54)]$

where N₀ is the nuclear scattering-length density contrast (relative to vacuum), M₀ is the saturation magnetization, $[{\bf n} = \{n_{x},n_{y},n_{z}\}]$ is a unit vector specifying the magnetization direction and the Heaviside function Θ confines the fields to the sphere of radius R.

4.1.2. Fourier transforms and form factor

The Fourier transforms of the nuclear and magnetic components are

$[\displaystyle\widetilde{N}(qR) = {{3V_{{\rm s}}N_{0}} \over {(2\pi)^{3/2}}}{{ j_{1}(qR)} \over {qR}},\eqno(55)]$

$[\displaystyle\widetilde{{\bf M}}(qR) = {{3V_{{\rm s}}M_{0}} \over {(2\pi)^{3/ 2}}}{{j_{1}(qR)} \over {qR}}\,{\bf n},\eqno(56)]$

where $[V_{{\rm s}} = ({{4\pi} / {3}})R^{3}]$ and the first-order spherical Bessel function is given by ( $[\upsilon = qR]$ )

$[\displaystyle j_{1}(\upsilon) = {{\sin\upsilon} \over {\upsilon^{2}}}-{{\cos \upsilon} \over {\upsilon}}.\eqno(57)]$

It is convenient to introduce the normalized sphere form factor

$[\displaystyle g(\upsilon) = {{j_{1}(\upsilon)} \over {\upsilon}},\quad\lim_{\upsilon \to 0}g(\upsilon) = {{1} \over {3}}.\eqno(58)]$

4.1.3. Differential SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

In the perpendicular scattering geometry the basic SANS cross sections are as follows (Michels, 2021):

$[\displaystyle{{{\rm d}\Sigma_{{\rm N}}} \over {{\rm d}\Omega}}(q,\theta) = 9N_{0}^{2}V_{ {\rm s}}[g(qR)]^{2},\eqno(59)]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma_{{\rm M}}} \over {{\rm d}\Omega}}(q,\theta) = \ & 9b_{{\rm H}}^{2 }M_{0}^{2}V_{{\rm s}}[g(qR)]^{2}\left(n_{x}^{2}+n_{y}^{2}\cos^{2}\theta+n_{ z}^{2}\sin^{2}\theta \right.\cr & \left.-\ 2n_{y}n_{z}\sin\theta\cos\theta\right),& (60)}]$

$[\displaystyle{{{\rm d}\Sigma_{{\rm NM}}} \over {{\rm d}\Omega}}(q,\theta) = 18b_{{\rm H}}M _{0}N_{0}V_{{\rm s}}[g(qR)]^{2}\left(n_{y}\sin\theta\cos\theta-n_{z}\sin^{2 }\theta\right),\eqno(61)]$

$[\eqalignno{\displaystyle{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}}(q,\theta) = \ & 9b_{{\rm H}}^{2 }M_{0}^{2}V_{{\rm s}}[g(qR)]^{2}\left(n_{y}^{2}\sin^{2}\theta\cos^{2}\theta +n_{z}^{2}\sin^{4}\theta\right. \cr & \left. -\ 2n_{y}n_{z}\sin^{3}\theta\cos\theta\right),&(62)}]$

$[\displaystyle{{{\rm d}\Sigma_{\chi}} \over {{\rm d}\Omega}}(q,\theta) = 0.\eqno(63)]$

4.1.4. Azimuthally averaged SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

The azimuthally averaged SANS cross sections are

$[\displaystyle I_{{\rm N}}(q) = 9N_{0}^{2}V_{{\rm s}}[g(qR)]^{2},\eqno(64)]$

$[\displaystyle I_{{\rm M}}(q) = 9b_{{\rm H}}^{2}M_{0}^{2}V_{{\rm s}}[g(qR)]^{2}{{2n_{x}^{2}+n_{y}^{2}+n_{z}^{2}} \over {2}},\eqno(65)]$

$[\displaystyle I_{{\rm NM}}(q) = -9b_{{\rm H}}M_{0}N_{0}V_{{\rm s}}[g(qR)]^{2}n_{z},\eqno(66)]$

$[\displaystyle I_{{\rm P}}(q) = 9b_{{\rm H}}^{2}M_{0}^{2}V_{{\rm s}}[g(qR)]^{2}{{n_{y}^{2}+3n_{z}^{2}} \over {8}},\eqno(67)]$

$[\displaystyle I_{\chi}(q) = 0.\eqno(68)]$

For this model, all cross sections scale with the sphere volume $[V_{{\rm s}}]$ due to the definition in equation (4) combined with the spherical Fourier transforms equations (55) and (56).

At , the expressions simplify to

$[\displaystyle I_{{\rm N}}(0) = N_{0}^{2}V_{{\rm s}},\eqno(69)]$

$[\displaystyle I_{{\rm M}}(0) = b_{{\rm H}}^{2}M_{0}^{2}V_{{\rm s}}{{2n_{x}^{2}+n_{y}^{2}+n_{z}^{2}} \over {2}},\eqno(70)]$

$[\displaystyle I_{{\rm NM}}(0) = -b_{{\rm H}}M_{0}N_{0}V_{{\rm s}}n_{z},\eqno(71)]$

$[\displaystyle I_{{\rm P}}(0) = b_{{\rm H}}^{2}M_{0}^{2}V_{{\rm s}}{{n_{y}^{2}+3n_{z}^{2}} \over {8}},\eqno(72)]$

$[\displaystyle I_{\chi}(0) = 0.\eqno(73)]$

4.1.5. Pair-distance distribution functions ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

Using equations (34) and (35) and the expression for the normalized (squared) sphere form factor $[[g(\upsilon)]^{2}]$ [equation (58)], we obtain the following expression for $[f(\xi)]$ , which describes the functionality of the pair-distance distribution function ( $[\xi = r/R]$ ):

$[\displaystyle f(\xi) = {{1} \over {4}}\xi^{2}\left(\xi-2\right)^{2}\left(\xi+4\right),\quad\xi\in[0,2].\eqno(74)]$

The maximum of this polynomial function in the interval $[\xi\in[0,2]]$ is given by

$[\displaystyle\xi_{{\rm max}} = {{\sqrt{105}} \over {5}}-1\cong 1.0494,\eqno(75)]$

$[\displaystyle f(\xi_{{\rm max}}) = {{144} \over {5}}-{{336\sqrt{105}} \over {125}} \cong 1.2562.\eqno(76)]$

Using $[f(\xi = r/R)]$ , the various pair-distance distribution functions read

$[\displaystyle p_{{\rm N}}(r) = {{3\pi V_{{\rm s}}N_{0}^{2}} \over {8R}}f(r/R),\eqno(77)]$

$[\displaystyle p_{{\rm M}}(r) = {{3\pi V_{{\rm s}}M_{0}^{2}b_{{\rm H }}^{2}} \over {8R}}f(r/R){{2n_{x}^{2}+n_{y}^{2}+n_{z}^{2}} \over {2}},\eqno(78)]$

$[\displaystyle p_{{\rm NM}}(r) = -{{3\pi V_{{\rm s}}N_{0}M_{0}b_{ {\rm H}}} \over {8R}}f(r/R)n_{z},\eqno(79)]$

$[\displaystyle p_{{\rm P}}(r) = {{3\pi V_{{\rm s}}M_{0}^{2}b_{{\rm H }}^{2}} \over {8R}}f(r/R){{n_{y}^{2}+3n_{z}^{2}} \over {8}},\eqno(80)]$

$[\displaystyle p_{\chi}(r) = 0.\eqno(81)]$

Note that all components of the unit vector $[{\bf n}]$ are considered, in analogy to the Stoner–Wohlfarth model, where the nanoparticles are fully saturated (single domain) but magnetic anisotropy may cause superspin misalignment with respect to $[{\bf B}_{0}\parallel\hat{{\bf P}}\parallel{\bf e}_{z}]$ . This degree of freedom is also useful for testing the NuMagSANS software, particularly for two-dimensional SANS cross sections, where the anisotropy patterns depend on $[{\bf n}]$ (Adams et al., 2023).

4.1.6. Reference example

For a spherical nanomagnet with a diameter of D = 40 nm ( $[V_{{\rm s}}\cong 3.35103\times 10^{-23}]$ m³), magnetized along the z axis ( $[{\bf n} = {\bf e}_{z}]$ ), $[M_{0} = 1700]$ kA m⁻¹ and $[N_{0} = 8.0\times 10^{14}]$ m⁻², the intensities and the maxima of the pair-distance distribution functions are listed in Table 2. Figs. 5 and 6 display some of the q-dependent response functions obtained with NuMagSANS. The data corresponding to this reference example are openly available in a Zenodo repository (Adams, 2025a).

Table 2
Analytical reference values for a uniformly magnetized spherical nanomagnet with a diameter of D = 2R = 40 nm

Intensities are given at ; $[p_{{\rm max}}]$ values correspond to $[r/R = \xi_{{\rm max}}]$ .

I(q = 0)	Value [cm⁻¹]	p_max	Value [nm⁻²]
$[I_{{\rm N}}(0)]$	$[2.145\times 10^{5}]$	$[p_{{\rm N}}]$	$[15.87\times 10^{-4}]$
$[I_{{\rm M}}(0)]$	$[0.410\times 10^{5}]$	$[p_{{\rm M}}]$	$[3.03\times 10^{-4}]$
$[I_{{\rm NM}}(0)]$	$[-1.326\times 10^{5}]$	$[p_{{\rm NM}}]$	0
$[I_{{\rm P}}(0)]$	$[0.308\times 10^{5}]$	$[p_{{\rm P}}]$	$[2.28\times 10^{-4}]$
$[I_{\chi}(0)]$	0	$[p_{\chi}]$	0
$[I_{{\rm sf}}(0)]$	$[0.103\times 10^{5}]$	$[p_{{\rm sf}}]$	$[0.76\times 10^{-4}]$
$[I_{{\rm sf}}^{+-}(0)]$	$[0.103\times 10^{5}]$	$[p_{{\rm sf}}^{+-}]$	$[0.76\times 10^{-4}]$
$[I_{{\rm sf}}^{-+}(0)]$	$[0.103\times 10^{5}]$	$[p_{{\rm sf}}^{-+}]$	$[0.76\times 10^{-4}]$
$[I_{{\rm nsf}}^{++}(0)]$	$[1.126\times 10^{5}]$	$[p_{{\rm nsf}}^{++}]$	$[8.33\times 10^{-4}]$
$[I_{{\rm nsf}}^{--}(0)]$	$[3.778\times 10^{5}]$	$[p_{{\rm nsf}}^{--}]$	$[27.96\times 10^{-4}]$
I⁺(0)	$[1.229\times 10^{5}]$	p⁺	$[9.09\times 10^{-4}]$
$[I^{-}(0)]$	$[3.881\times 10^{5}]$	$[p^{-}]$	$[28.72\times 10^{-4}]$

Figure 5
Magnetic SANS from a uniformly magnetized nanoparticle. (a) Three-dimensional visualization of a spherical nanoparticle with a spatially uniform magnetization pointing along the z direction, cf. equation (54). Colors indicate the m_z component. (b) Magnetization profile along the x axis through the particle center, showing the expected constant values $[m_{x} = 0]$ , $[m_{y} = 0]$ and $[m_{z} = 1]$ . (c) Azimuthally averaged SANS cross sections for the same particle (log–log scale): nuclear scattering $[I_{{\rm N}}(q)]$ , unpolarized magnetic scattering $[I_{{\rm M}}(q)]$ and spin-flip scattering $[I_{{\rm sf}}(q)]$ , cf. equation (30). The curves exhibit the characteristic form factor oscillations of a homogeneous sphere. (d) Two-dimensional spin-flip SANS cross section $[({\rm d}\Sigma_{{\rm sf}}/{\rm d}\Omega)(q_{y},q_{z})]$ , cf. equation (13). The intensity shows the expected $[\sin^{2}\theta\cos^{2}\theta]$ angular dependence for a uniform magnetization aligned perpendicular to the neutron-beam direction (here: along the z axis, with the beam along x), producing the characteristic fourfold symmetry of the spin-flip scattering pattern.

Figure 6
Magnetic SANS from a uniformly magnetized nanoparticle. (a) Absolute cosine-mode intensities of the spin-flip SANS cross section (log–log scale), cf. equation (31). (b) Modal amplitudes from equation (33), highlighting the

contribution which reflects the fourfold symmetry of the two-dimensional spin-flip SANS pattern. (c) Spin-flip pair-distance distribution function $[p_{{\rm sf}}(r)]$ , see equation (35). (d) Two-dimensional real-space correlation function $[C_{{\rm sf}}(r_{y},r_{z})]$ , cf. equation (36).

4.2. Spherical nanomagnet with linear vortex texture

To test the capability of NuMagSANS to handle magnetization textures with broken inversion symmetry and nonzero chirality, it is useful to consider a reference configuration that is still analytically tractable. The spherical nanomagnet with an additional linear vortex term represents such a case (Adams et al., 2024b): the nuclear density remains uniform as in Section 4.1, but the magnetization acquires a spatially varying component that mimics the onset of a flux-closure state. This model is valuable for validating the correct treatment of magnetization textures with finite chirality, checking phase factors and imaginary components in the Fourier-space magnetization, and benchmarking the handling of vortex-like states against the uniform magnetization reference.

4.2.1. Model definition

The real-space nuclear density $[N({\bf r})]$ and magnetization $[{\bf M}({\bf r})]$ are given by (Adams et al., 2024b)

$[\displaystyle N({\bf r}) = N_{0}\,\Theta\left(1-{{r} \over {R}}\right),\eqno(82)]$

$[\displaystyle{\bf M}({\bf r}) = \left[M_{0}\,{\bf e}_{z}+M_{1}\,(x\, {\bf e}_{y}-y\,{\bf e}_{x})\right]\,\Theta\left(1-{{r} \over {R}}\right),\eqno(83)]$

where all terms have the same meaning as before. The new parameter M₁ models the magnitude of the vortex structure that forms in the x–y plane. For a fully saturated state along $[{\bf e}_{z}]$ , $[M_{1} = 0]$ . As the applied magnetic field is reduced towards zero, M₁ becomes nonzero, providing a simple phenomenological model for the field dependence of the magnetization texture.

4.2.2. Fourier transforms

Using the Fourier derivative theorem, the x- and y-dependent terms in $[{\bf M}({\bf r})]$ transform into partial derivatives with respect to q_x and q_y:

$[\displaystyle\widetilde{N}({\bf q}) = {{3V_{{\rm s}}N_{0}} \over {(2\pi)^{3/2 }}}\,{{j_{1}(qR)} \over {qR}},\eqno(84)]$

$[\displaystyle\widetilde{{\bf M}}({\bf q}) = {{3V_{{\rm s}}} \over {(2\pi)^ {3/2}}}\left[M_{0}\,{\bf e}_{z}+iM_{1}\left({\bf e}_{y}\partial_{q_{x}}- {\bf e}_{x}\partial_{q_{y}}\right)\right]{{j_{1}(qR)} \over {qR}}.\eqno(85)]$

In contrast to the uniform case, the Fourier-space magnetization now includes a nonzero imaginary component, directly linked to the broken inversion symmetry introduced by the vortex term. In a linear approximation, such a vector field can model the effects of dipole–dipole coupling, which tends to favor flux-closure-type magnetization textures (Adams et al., 2024b).

The derivatives in equation (85) can be resolved using the chain rule ( $[\upsilon = qR]$ ):

$[\displaystyle{{\partial g(qR)} \over {\partial q_{x}}} = \left.{{{\rm d}g(\upsilon)} \over {{\rm d}\upsilon}}\right|_{\upsilon = qR}{{\partial(qR)} \over {\partial q_{x}}} = g^{\prime}(qR)\,\hat{q}_{x}\,R,\eqno(86)]$

$[\displaystyle{{\partial g(qR)} \over {\partial q_{y}}} = \left.{{{\rm d}g(\upsilon)} \over {{\rm d} \upsilon}}\right|_{\upsilon = qR}{{\partial(qR)} \over {\partial q_{y}}} = g^{\prime}(qR)\,\hat{q}_{y}\,R,\eqno(87)]$

with $[\hat{q}_{x} = q_{x}/q]$ , $[\hat{q}_{y} = q_{y}/q]$ and

$[\displaystyle g(\upsilon) = {{j_{1}(\upsilon)} \over {\upsilon}} = {{\sin\upsilon- \upsilon\cos\upsilon} \over {\upsilon^{3}}},\quad\lim_{\upsilon\to 0}g(\upsilon) = {{1} \over {3}},\eqno(88)]$

$[\displaystyle g^{\prime}(\upsilon) = {{(\upsilon^{2}-3)\sin\upsilon+3 \upsilon\cos\upsilon} \over {\upsilon^{4}}},\quad\lim_{\upsilon\to 0}g^{\prime}(\upsilon) = 0.\eqno(89)]$

Finally, the Fourier transforms are obtained as

$[\displaystyle\widetilde{N}({\bf q}) = {{3V_{{\rm s}}N_{0}} \over {(2\pi)^{3/2 }}}\,g(qR),\eqno(90)]$

$[\displaystyle\widetilde{{\bf M}}({\bf q}) = {{3V_{{\rm s}}} \over {(2\pi)^ {3/2}}}\left[M_{0}\,g(qR)\,{\bf e}_{z}+iM_{1}R\,g^{\prime}(qR)\,\left(\hat{q }_{x}{\bf e}_{y}-\hat{q}_{y}{\bf e}_{x}\right)\right].\eqno(91)]$

4.2.3. Differential SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

For the linear vortex term in the x–y plane, the SANS cross sections are

$[\displaystyle{{{\rm d}\Sigma_{{\rm N}}} \over {{\rm d}\Omega}}(q,\theta) = 9N_{0}^{2}V_{ {\rm s}}[g(qR)]^{2},\eqno(92)]$

$[\displaystyle{{{\rm d}\Sigma_{{\rm M}}} \over {{\rm d}\Omega}}(q,\theta) = 9b_{{\rm H}}^{2 }V_{{\rm s}}\left\{M_{0}^{2}[g(qR)]^{2}+M_{1}^{2}R^{2}[g^{\prime}(qR)]^{2} \right\}\sin^{2}\theta,\eqno(93)]$

$[\displaystyle{{{\rm d}\Sigma_{{\rm NM}}} \over {{\rm d}\Omega}}(q,\theta) = -18b_{{\rm H}} M_{0}N_{0}V_{{\rm s}}[g(qR)]^{2}\sin^{2}\theta,\eqno(94)]$

$[\displaystyle{{{\rm d}\Sigma_{{\rm P}}} \over {{\rm d}\Omega}}(q,\theta) = 9b_{{\rm H}}^{2 }M_{0}^{2}V_{{\rm s}}[g(qR)]^{2}\sin^{4}\theta,\eqno(95)]$

$[\displaystyle{{{\rm d}\Sigma_{\chi}} \over {{\rm d}\Omega}}(q,\theta) = 18V_{{\rm s}}b_{ {\rm H}}^{2}M_{0}M_{1}g(qR)g^{\prime}(qR)\sin^{2}\theta\cos\theta.\eqno(96)]$

The angular dependencies differ qualitatively from the uniform case, making this configuration useful for checking the anisotropy handling and the presence of imaginary Fourier components in the software.

4.2.4. Azimuthally averaged SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

For unpolarized scattering and $[\hat{{\bf P}}\parallel{\bf e}_{z}]$ , the azimuthally averaged cross sections are

$[\displaystyle I_{{\rm N}}(q) = 9N_{0}^{2}V_{{\rm s}}[g(qR)]^{2},\eqno(97)]$

$[\displaystyle I_{{\rm M}}(q) = {{9V_{{\rm s}}b_{{\rm H}}^{2}} \over {2}} \left\{M_{0}^{2}[g(qR)]^{2}+M_{1}^{2}R^{2}[g^{\prime}(qR)]^{2}\right\},\eqno(98)]$

$[\displaystyle I_{{\rm NM}}(q) = -9V_{{\rm s}}b_{{\rm H}}M_{0}N_{0}[g(qR)]^{2},\eqno(99)]$

$[\displaystyle I_{{\rm P}}(q) = {{27b_{{\rm H}}^{2}M_{0}^{2}V_{{\rm s}}} \over {8}}[g(qR)]^{2},\eqno(100)]$

$[\displaystyle I_{\chi}(q) = 0.\eqno(101)]$

4.2.5. Pair-distance distribution functions ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

Using the definitions introduced in Section 4.1, we derive the analytical pair-distance distribution functions of the linear vortex model. To this end, we introduce the following dimensionless auxiliary functions:

$[\displaystyle f(\xi) = {{1} \over {4}}\,\xi^{2}(\xi-2)^{2}(\xi+4),\qquad\xi\in[0,2],\eqno(102)]$

$[\displaystyle h(\xi) = -{{1} \over {32}}\,\xi^{2}(\xi-2)^{2}\left(\xi^{3}+4\xi^{2}+2 \xi-8\right),\qquad\xi\in[0,2].\eqno(103)]$

In terms of these functions, the pair-distance distribution functions associated with the basic SANS observables read

$[\displaystyle p_{{\rm N}}(r) = {{3\pi V_{{\rm s}}N_{0}^{2}} \over {8R}}\,f(r/R),\eqno(104)]$

$[\displaystyle p_{{\rm M}}(r) = {{3\pi V_{{\rm s}}M_{0}^{2}b_{{\rm H }}^{2}} \over {16R}}\,f(r/R)+{{9\pi V_{{\rm s}}M_{1}^{2}R^{2}b_{{\rm H}}^{2} } \over {20R}}\,h(r/R),\eqno(105)]$

$[\displaystyle p_{{\rm NM}}(r) = -{{3\pi V_{{\rm s}}N_{0}M_{0}b_{ {\rm H}}} \over {8R}}\,f(r/R),\eqno(106)]$

$[\displaystyle p_{{\rm P}}(r) = {{9\pi V_{{\rm s}}M_{0}^{2}b_{{\rm H }}^{2}} \over {64R}}\,f(r/R),\eqno(107)]$

$[\displaystyle p_{\chi}(r) = 0.\eqno(108)]$

4.2.6. Reference example

For a sphere with D = 40 nm ( $[V_{{\rm s}}\cong 3.35103\times 10^{-23}]$ m³), $[M_{0} = 1700]$ kA m⁻¹, $[M_{1} = 5M_{0}/R]$ and $[N_{0} = 8.0\times 10^{14}]$ m⁻², the intensities and $[p_{{\rm max}}]$ values are summarized in Table 3. Figs. 7 and 8 display some of the q-dependent response functions obtained with NuMagSANS. The data corresponding to this reference example are openly available in a Zenodo repository (Adams, 2025b).

Table 3
Analytical reference values for a spherical nanomagnet with a linear vortex texture ( $[D = 40\,{\rm nm}]$ )

Intensities are given at ; $[p_{{\rm max}}]$ values correspond to $[r/R = \xi_{{\rm max}}]$ .

I(q = 0)	Value [cm⁻¹]	I_max	Value [cm⁻¹]	p_max	Value [nm⁻²]
$[I_{{\rm N}}(0)]$	$[2.145\times 10^{5}]$	$[I_{{\rm N}}]$	$[2.145\times 10^{5}]$	$[p_{{\rm N}}]$	$[15.87\times 10^{-4}]$
$[I_{{\rm M}}(0)]$	$[0.410\times 10^{5}]$	$[I_{{\rm M}}]$	$[1.113\times 10^{5}]$	$[p_{{\rm M}}]$	$[18.68\times 10^{-4}]$
$[I_{{\rm NM}}(0)]$	$[-1.326\times 10^{5}]$	$[I_{{\rm NM}}]$	0	$[p_{{\rm NM}}]$	0
$[I_{{\rm P}}(0)]$	$[0.308\times 10^{5}]$	$[I_{{\rm P}}]$	$[0.308\times 10^{5}]$	$[p_{{\rm P}}]$	$[2.28\times 10^{-4}]$
$[I_{\chi}(0)]$	0	$[I_{\chi}]$	0	$[p_{\chi}]$	0
$[I_{{\rm sf}}(0)]$	$[0.103\times 10^{5}]$	$[I_{{\rm sf}}]$	$[1.025\times 10^{5}]$	$[p_{{\rm sf}}]$	$[17.07\times 10^{-4}]$
$[I_{{\rm sf}}^{+-}(0)]$	$[0.103\times 10^{5}]$	$[I_{{\rm sf}}^{+-}]$	$[1.025\times 10^{5}]$	$[p_{{\rm sf}}^{+-}]$	$[17.07\times 10^{-4}]$
$[I_{{\rm sf}}^{-+}(0)]$	$[0.103\times 10^{5}]$	$[I_{{\rm sf}}^{-+}]$	$[1.025\times 10^{5}]$	$[p_{{\rm sf}}^{-+}]$	$[17.07\times 10^{-4}]$
$[I_{{\rm nsf}}^{++}(0)]$	$[1.126\times 10^{5}]$	$[I_{{\rm nsf}}^{++}]$	$[1.126\times 10^{5}]$	$[p_{{\rm nsf}}^{++}]$	$[8.33\times 10^{-4}]$
$[I_{{\rm nsf}}^{--}(0)]$	$[3.778\times 10^{5}]$	$[I_{{\rm nsf}}^{--}]$	$[3.778\times 10^{5}]$	$[p_{{\rm nsf}}^{--}]$	$[27.96\times 10^{-4}]$
I⁺(0)	$[1.229\times 10^{5}]$	I⁺	$[1.448\times 10^{5}]$	p⁺	$[23.17\times 10^{-4}]$
$[I^{-}(0)]$	$[3.881\times 10^{5}]$	$[I^{-}]$	$[3.881\times 10^{5}]$	$[p^{-}]$	$[39.22\times 10^{-4}]$

Figure 7
Magnetic SANS from a linear vortex magnetization state. (a) Three-dimensional visualization of the spherical nanoparticle hosting a linear vortex texture. Shown are the normalized magnetization vectors $[{\bf m}^{\prime} = {\bf m}/\|{\bf m}\|]$ , cf. equation (83), with colors indicating the normalized axial component $[m_{z}^{\prime} = m_{z}/\|{\bf m}\|]$ . (b) Magnetization components along the radial coordinate ρ: the expected vortex structure is observed, with $[m_{\varphi} = 5\rho/R]$ increasing linearly with ρ, $[m_{\rho} = 0]$ and a constant axial component $[m_{z} = 1]$ . (c) Azimuthally averaged SANS cross sections for the same texture (log–log scale): nuclear scattering $[I_{{\rm N}}(q)]$ , unpolarized magnetic scattering $[I_{{\rm M}}(q)]$ and spin-flip magnetic scattering $[I_{{\rm sf}}(q)]$ , cf. equation (30). The modified form factor oscillations reflect the nonuniform, tangential magnetization distribution of the vortex. (d) Two-dimensional spin-flip SANS cross section $[({\rm d}\Sigma_{{\rm sf}}/{\rm d}\Omega)(q_{y},q_{z})]$ . The characteristic two-lobe pattern arises from the curling of the vortex magnetization.

Figure 8
Magnetic SANS from a linear vortex magnetization state. (a) Cosine-mode intensities of the spin-flip SANS cross section $[|I^{\rm c}_{{\rm sf},k}(q)|]$ (log–log scale), illustrating the dominant contributions for

and

, which reflect the azimuthal symmetry of the vortex state. Because the linear vortex includes a uniform magnetization component, very small values of q exhibit a pronounced fourfold angular anisotropy, whereas at intermediate and larger q a twofold anisotropy becomes dominant. (b) Two-dimensional chiral SANS cross section $[({\rm d}\Sigma_{\chi}/{\rm d}\Omega)(q_{y},q_{z})]$ , cf. equation (14), showing the expected four-lobe antisymmetric pattern associated with the handedness of the vortex. (c) Spin-flip pair-distance distribution function $[p_{{\rm sf}}(r)]$ , demonstrating the oscillatory real-space correlations induced by the curling magnetization. (d) Two-dimensional real-space correlation function $[C_{{\rm sf}}(r_{y},r_{z})]$ , cf. equation (36), revealing the characteristic positive–negative correlation structure that reflects the axial and azimuthal components of the linear vortex texture.

4.3. Spherical iron nanoparticles: effect of interparticle interference

This example expands on previous work (Pratami Sinaga et al., 2023; Sinaga et al., 2024; Adams et al., 2024b) that combines NuMagSANS with MuMax3 in a micromagnetic SANS workflow. The previous studies focused on dilute, noninteracting ensembles of iron nanoparticles with dipolar-energy-driven internal vortex structures inside of each particle, i.e. the magnetodipolar coupling between particles has been neglected. Here, as an example for interparticle interference scattering, we consider positional correlations between the particles while still neglecting the interparticle dipole–dipole coupling.

The simulations involve 800 spherical iron nanoparticles arranged in three different configurations: a dilute ensemble, an isotropic random arrangement and an ordered simple cubic lattice structure. The simulations are conducted for the remanent state (zero applied field after prior saturation). By including structural interparticle interference, this study captures the collective effects often observed in experimental systems.

Fig. 9 displays the spatial arrangement of the nanoparticles (top row) and their corresponding two-dimensional (middle row) and one-dimensional (lower row) spin-flip SANS cross sections. Unlike the smooth SANS signal observed for the dilute case (left column), the middle and right columns exhibit noisy SANS signals due to the included interparticle interference scattering. Additionally, Fig. 9(h) shows Bragg-peak-like features due to simple cubic ordering.

Figure 9
Spin-flip SANS observables at the remanent state for three different ensembles of 800 iron nanoparticles with equal diameters of D = 40 nm (micromagnetic spin textures were simulated with MuMax3). Left column (a, b, c): dilute ensemble (single-particle case). (a) Representative particle with its internal spin texture color coded by m_x. (b) Corresponding two-dimensional spin-flip SANS cross section $[({\rm d}\Sigma_{{\rm sf}}/{\rm d}\Omega)(q_{y},q_{z})]$ showing a smooth intensity distribution that is characteristic of weak interparticle correlations. (c) Azimuthally averaged spin-flip intensity $[I_{{\rm sf}}(q)]$ displaying the expected sphere-like form factor oscillations (log–log scale). Middle column (d, e, f): moderately densely packed system. (d) Particles are positioned inside a supersphere with a volume fraction of $[\eta = 5\%]$ . The two-dimensional (e) and the one-dimensional (f) spin-flip SANS cross sections exhibit an increased statistical noise due to the disordered arrangement of the particles. Right column (g, h, i): simple cubic structure. (g) Particles are placed on a simple cubic lattice inside a supersphere (volume fraction: $[\eta = 30\%]$ ; center-to-center distance between spheres: 45 nm). (h) The two-dimensional spin-flip SANS cross section now shows emerging Bragg-peak-like features reflecting the underlying periodic packing. (i) $[I_{{\rm sf}}(q)]$ displays modulations and peak structures associated with these lattice correlations.

As a reference, the execution time for a single system configuration in this example (with only one applied magnetic field value) is approximately 60 s on an NVIDIA RTX 3090 GPU. The simulation comprises a total of ∼ $[3.38\times 10^{6}]$ magnetization cells, corresponding to 800 nanoparticles with 4224 cells per particle. A uniform nuclear scattering length is assumed, nuclear data files are included, and all the possible NuMagSANS output options are enabled. The reciprocal-space sampling is performed on a $[\{q,\theta\}]$ grid of 1000 × 1000 points, and the corresponding real-space correlation functions are also evaluated on a $[\{\rho,\alpha\}]$ grid of 1000 × 1000 points. The full output of this single system configuration amounts to approximately 670 MB in CSV format, reflecting the high reciprocal-space and real-space sampling resolutions.

In many practical cases, not all the available output quantities are required (e.g. the two-dimensional correlation functions). This can substantially reduce the execution time of NuMagSANS. Under such conditions, parameter sweeps along a hysteresis curve comprising applied field values of the order of 1000 become computationally feasible within a few hours on a single GPU.

The data corresponding to this reference example are openly available in a Zenodo repository (Adams, 2025c).

4.4. Runtime experiment

To assess the computational performance and scaling behavior of NuMagSANS, we performed a dedicated runtime experiment based on a controlled and analytically well-defined micromagnetic test system. Specifically, we consider a linear vortex-like magnetization configuration,

$[\displaystyle{\bf m}({\bf r}) = {{\left\lbrace-5y/R,\,+5x/R,\,1\right\rbrace} \over { \sqrt{(5x/R)^{2}+(5y/R)^{2}+1}}},\eqno(109)]$

defined inside a spherical nanoparticle of diameter D = 2R = 40 nm. The nuclear scattering-length density is assumed to be spatially uniform.

The nanoparticle is discretized on a simple cubic lattice with a cell size of a = 2 nm, resulting in a total of 4169 cells per particle. This configuration is representative of the micromagnetic vortex states considered throughout this work, while remaining sufficiently simple to isolate computational scaling effects from physical complexity.

The runtime benchmark is carried out by increasing the number of identical nanoparticles from N = 10 (corresponding to 41690 cells) up to N = 25600 (corresponding to approximately $[1.067\times 10^{8}]$ cells). All simulations are executed on a single NVIDIA RTX 3090 GPU using identical numerical settings and output options.

Fig. 10 summarizes the resulting execution times as a function of the total number of discretization cells. For small system sizes, the run time is dominated by a nearly constant overhead associated with initialization and data setup. Beyond this regime, the execution time increases approximately linearly with the number of cells over more than two orders of magnitude in system size. At the largest system sizes, a moderate increase in slope is observed, which can be attributed to increased GPU memory traffic and reduced cache efficiency. Importantly, no superlinear scaling behavior or numerical instabilities are observed within the investigated range.

Figure 10
Execution time of the NuMagSANS software as a function of the total number of discretization cells, measured on a single NVIDIA RTX 3090 GPU (log–linear scale).

These results demonstrate that NuMagSANS enables the efficient evaluation of large-scale micromagnetic SANS problems comprising tens of millions of discretization cells on a single GPU, thereby bridging the gap between desktop-scale simulations and traditional large-scale high-performance computing approaches.

The data corresponding to this reference example are openly available in a Zenodo repository (Adams, 2026a).

5. Summary and conclusion

We have presented NuMagSANS, a GPU-accelerated framework for calculating nuclear and magnetic small-angle neutron scattering (SANS) cross sections and correlation functions of complex systems. The software accounts for nuclear, magnetic and interference scattering contributions and enables the computation of unpolarized, polarized, chiral and azimuthally averaged observables, facilitating the direct comparison between theoretical models and experimental SANS measurements.

The modular design of NuMagSANS allows users to import user-defined nuclear and magnetic real-space data, making it a versatile tool for investigating a wide range of systems, including bulk magnetic materials, magnetic nanoparticles and ordered assemblies of nanoscaled objects. Its GPU-accelerated implementation ensures high computational efficiency, enabling simulations of large-scale systems. The versatility of NuMagSANS has been shown through applications to dilute as well as densely packed arrangements of spherical iron nanoparticles. A particular strength of NuMagSANS lies in the possibility of seamlessly integrating the results of large-scale micromagnetic simulations (performed, e.g., with MuMax3) into a SANS workflow.

Looking ahead, NuMagSANS offers numerous opportunities for further development. Future work could include the extension of the software to account for resolution effects and the inclusion of time-dependent magnetic scattering phenomena. These developments would further expand its applicability and enhance its relevance to the SANS community.

In conclusion, NuMagSANS provides a powerful and flexible platform for advancing the understanding of nuclear and magnetic SANS phenomena. Its ability to simulate complex systems and incorporate collective effects makes it a valuable tool for researchers studying nanoscale magnetic and structural interactions.

Acknowledgements

We thank Evelyn Pratami Sinaga, Ivan Titov, Štefan Liščák, Elizabeth Jefremovas and Annika Stellhorn for fruitful discussions.

Conflict of interest

The authors specify no conflict of interest.

Data availability

All data generated and analyzed in this study are publicly available in the Zenodo repositories cited as Adams (2025a), Adams (2025b), Adams (2025c) and Adams (2026a). The version of NuMagSANS used in this study is archived at Zenodo (Adams, 2026b). The actively maintained development version of the software is available under the MIT License at https://github.com/AdamsMP92/NuMagSANS.

Funding information

Financial support from the National Research Fund of Luxembourg is gratefully acknowledged (AFR Grant No. 15639149).

References

Adams, M. P. (2025a). NuMagSANS – Example 1: Spherical Nanoparticle with Uniform Magnetization (v1.0) [Data set], https://doi.org/10.5281/zenodo.17491221. Google Scholar
Adams, M. P. (2025b). NuMagSANS – Example 2: Spherical Nanoparticle with Linearized Vortex Magnetization (v1.0) [Data set], https://doi.org/10.5281/zenodo.17594693. Google Scholar
Adams, M. P. (2025c). NuMagSANS – Example 3: MuMax3-Based Simulation Pipeline for an Ensemble of Iron Nanoparticles with Vortex Spin Textures (v1.1) [Data set], https://doi.org/10.5281/zenodo.17931156. Google Scholar
Adams, M. P. (2026a). NuMagSANS – Runtime Experiment (v1.0) [Data set], https://doi.org/10.5281/zenodo.18187509. Google Scholar
Adams, M. P. (2026b). NuMagSANS (v1.0.0), https://doi.org/10.5281/zenodo.18824364. Google Scholar
Adams, M. P., Michels, A. & Kachkachi, H. (2022). J. Appl. Cryst. 55, 1488–1499. Web of Science CrossRef CAS IUCr Journals Google Scholar
Adams, M. P., Pratami Sinaga, E. & Michels, A. (2023). IUCrJ 10, 261–269. CrossRef CAS PubMed IUCr Journals Google Scholar
Adams, M. P., Sinaga, E. P., Kachkachi, H. & Michels, A. (2024a). Phys. Rev. B 109, 024429. CrossRef Google Scholar
Adams, M. P., Sinaga, E. P., Liščák, S. & Michels, A. (2024b). Phys. Rev. B 110, 014420. CrossRef Google Scholar
Boothroyd, A. (2016). Principles of Neutron Scattering from Condensed Matter, https://doi.org/10.1093/oso/9780198862314.001.0001. Oxford University Press. Google Scholar
Brigham, E. O. (1974). The Fast Fourier Transform. Englewood Cliffs: Prentice-Hall. Google Scholar
Dewhurst, C. D. (2023). J. Appl. Cryst. 56, 1595–1609. Web of Science CrossRef CAS IUCr Journals Google Scholar
Glatter, O. & Kratky, O. (1982). Editors. Small Angle X-ray Scattering. London: Academic Press. Google Scholar
Holt, S. J. R., Lang, M., Loudon, J. C., Hicken, T. J., Suess, D., Cortés-Ortuño, D., Pathak, S. A., Beg, M., Zulfiqar, K. & Fangohr, H. (2025). npj Comput. Mater. 11, 201. CrossRef PubMed Google Scholar
Kohlbrecher, J. & Breßler, I. (2022). J. Appl. Cryst. 55, 1677–1688. Web of Science CrossRef IUCr Journals Google Scholar
Krycka, K., Borchers, J., Ijiri, Y., Booth, R. & Majetich, S. (2012a). J. Appl. Cryst. 45, 554–565. CrossRef CAS IUCr Journals Google Scholar
Krycka, K., Chen, W., Borchers, J., Maranville, B. & Watson, S. (2012b). J. Appl. Cryst. 45, 546–553. CrossRef CAS IUCr Journals Google Scholar
Leliaert, J., Dvornik, M., Mulkers, J., De Clercq, J., Milošević, M. V. & Van Waeyenberge, B. (2018). J. Phys. D Appl. Phys. 51, 123002. CrossRef Google Scholar
Lovesey, S. W. (1984). Theory of Neutron Scattering from Condensed Matter, Vols. I and II. Oxford University Press. Google Scholar
Maleev, S. V. (2002). Phys.-Usp. 45, 569–596. CAS Google Scholar
Meynell, S. A., Wilson, M. N., Krycka, K. L., Kirby, B. J., Fritzsche, H. & Monchesky, T. L. (2017). Phys. Rev. B 96, 054402. Web of Science CrossRef Google Scholar
Michels, A. (2021). Magnetic Small-Angle Neutron Scattering: A Probe for Mesoscale Magnetism Analysis, https://doi.org/10.1093/oso/9780198855170.001.0001. Oxford University Press. Google Scholar
Michels, A., Mettus, D., Honecker, D. & Metlov, K. L. (2016). Phys. Rev. B 94, 054424. CrossRef Google Scholar
Mistonov, A. A., Dubitskiy, I. S., Shishkin, I. S., Grigoryeva, N. A., Heinemann, A., Sapoletova, N. A., Valkovskiy, G. A. & Grigoriev, S. V. (2019). J. Magn. Magn. Mater. 477, 99–108. Web of Science CrossRef CAS Google Scholar
NVIDIA Corporation (2026). CUDA Programming Guide, https://docs.nvidia.com/cuda/cuda-programming-guide/. Google Scholar
Pratami Sinaga, E., Adams, M. P., Bersweiler, M., Vivas, L. G., Hasdeo, E. H., Leliaert, J., Bender, P., Honecker, D. & Michels, A. (2023). Phys. Rev. B 107, 014416. CrossRef Google Scholar
Sinaga, E. P., Adams, M. P., Hasdeo, E. H. & Michels, A. (2024). Phys. Rev. B 110, 054404. CrossRef Google Scholar
Squires, G. L. (2012). Introduction to the Theory of Thermal Neutron Scattering, 3rd ed. Cambridge University Press. Google Scholar
Stroustrup, B. (2013). The C++ Programming Language, 4th ed. Boston: Addison-Wesley. Google Scholar
Svergun, D. I. & Koch, M. H. J. (2003). Rep. Prog. Phys. 66, 1735–1782. Web of Science CrossRef CAS Google Scholar
Ukleev, V., Ajejas, F., Devishvili, A., Vorobiev, A., Steinke, N.-J., Cubitt, R., Luo, C., Abrudan, R.-M., Radu, F., Cros, V., Reyren, N. & White, J. S. (2024). Sci. Technol. Adv. Mater. 25, 2315015. CrossRef PubMed Google Scholar
Ukleev, V., Utesov, O., Yu, L., Luo, C., Chen, K., Radu, F., Yamasaki, Y., Kanazawa, N., Tokura, Y., Arima, T. & White, J. S. (2021). Phys. Rev. Res. 3, 013094. CrossRef Google Scholar
Ukleev, V., Yamasaki, Y., Utesov, O., Shibata, K., Kanazawa, N., Jaouen, N., Nakao, H., Tokura, Y. & Arima, T. (2020). Phys. Rev. B 102, 014416. CrossRef Google Scholar
Vansteenkiste, A., Leliaert, J., Dvornik, M., Helsen, M., Garcia-Sanchez, F. & Van Waeyenberge, B. (2014). AIP Advances, 4, 107133. Google Scholar
Wildes, A. R. (2006). Neutron News 17(2), 17–25. CrossRef Google Scholar

This is an open-access article distributed under the terms of the Creative Commons Attribution (CC-BY) Licence, which permits unrestricted use, distribution, and reproduction in any medium, provided the original authors and source are cited.

JOURNAL OF
APPLIED
CRYSTALLOGRAPHY

ISSN: 1600-5767

Volume 59| Part 3| June 2026| Pages 943-959

https://doi.org/10.1107/S160057672600258X

Open

access

Format		BIBTeX
		EndNote
		RefMan
		Refer
		Medline
		CIF
		SGML
		Plain Text
		Text

Format		BIBTeX
		EndNote
		RefMan
		Refer
		Medline
		CIF
		SGML
		Plain Text
		Text

Search IUCr Journals		doi		Advanced search
Author		volume	page

computer programs\(\def\hfill{\hskip 5em}\def\hfil{\hskip 3em}\def\eqno#1{\hfil {#1}}\)

NuMagSANS: a GPU-accelerated open-source software package for the generic computation of nuclear and magnetic small-angle neutron scattering observables of complex systems

1. Introduction

2. SANS observables

2.1. Basic SANS cross sections and conventions

2.2. POLARIS cross sections

2.3. SANSPOL cross sections

2.4. Unpolarized SANS cross sections

2.5. Azimuthally averaged SANS cross sections

2.6. Correlation and pair-distance distribution functions

3. Program description: implementation and workflow

3.1. Configuration file

3.2. Real-space input data

3.3. Summation approach

3.4. Fourier and real-space output data

4. Verification and applications

4.1. Spherical form factor model

4.1.1. Model definition

4.1.2. Fourier transforms and form factor

4.1.3. Differential SANS cross sections ()

4.1.4. Azimuthally averaged SANS cross sections ()

4.1.5. Pair-distance distribution functions ()

4.1.6. Reference example

4.2. Spherical nanomagnet with linear vortex texture

4.2.1. Model definition

4.2.2. Fourier transforms

4.2.3. Differential SANS cross sections ()

4.2.4. Azimuthally averaged SANS cross sections ()

4.2.5. Pair-distance distribution functions ()

4.2.6. Reference example

4.3. Spherical iron nanoparticles: effect of interparticle interference

4.4. Runtime experiment

5. Summary and conclusion

Acknowledgements

Conflict of interest

Data availability

Funding information

References

computer programs

4.1.3. Differential SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

4.1.4. Azimuthally averaged SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

4.1.5. Pair-distance distribution functions ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

4.2.3. Differential SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

4.2.4. Azimuthally averaged SANS cross sections ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )

4.2.5. Pair-distance distribution functions ( $[{\bf B}_{0}\parallel{\bf e}_{z}\perp{\bf k}_{0}]$ )