ARBTools is a Python library containing a Lekien-Marsden type tricubic spline method for interpolating three-dimensional scalar or vector fields presented as a set of discrete data points on a regular cuboid grid. ARBTools was developed for simulations of magnetic molecular traps, in which the magnitude, gradient and vector components of a magnetic field are required. Numerical integrators for solving particle trajectories are included, but the core interpolator can be used for any scalar or vector field. The only additional system requirements are NumPy.

It is often necessary to smoothly interpolate vector or scalar fields known as a set of discrete data points across a grid. For one- and two-dimensional problems cubic and bicubic spline implementations exist (for example, in the SciPy interpolate library [

The tricubic method described by Lekien and Marsden [

There are several commonly available implementations of this interpolator in a variety of programming languages, but none were suitable for the specific requirements of our work. ARBTools was written in Python [

Interpolation coefficients are calculated on-the-fly and subsequently reused where required to reduce processor time. For arbitrary points inside the interpolation volume the field magnitude, partial derivatives and vector components are readily accessible from a single query. Separate query methods are included for dealing with interpolation of a single point, or for multiple simultaneous coordinates. A fourth-order Runge-Kutta [

Although produced for the specific application of modelling low-field-seeking neutral particles, this software has been developed to be more general. It can work directly with either a scalar or vector field input, and is suitable for a variety of applications with any field supplied across a regular, cuboid grid.

ARBTools is written in Python [

The ‘ARBTraj’ module contains functions to create a random sample of argon atoms and solve its motion through a quadrupole field. By simply changing mass and magnetic moment values this can be adapted for different atomic species, or a differently shaped magnetic potential could be specified. The included Runge-Kutta integrator can be easily modified to solve particle motion in alternative systems – for example, we have recently discussed simulating the operation of an atomic tweezer apparatus with a colleague.

To install on Linux run ‘sudo python setup.py install’. The interpolator is contained in a file called ‘ARBInterp.py’ and the command ‘from ARBTools.ARBInterp import tricubic’ will import the interpolation class.

To instantiate the class, pass it a source field –

Norm: takes the norm of the vector field and return the magnitude and gradient (as three partial derivatives)

Vector: returns the interpolated vector components

Both: takes vector norm, and returns the magnitude and norm of the vector plus the vector components at the interpolation point

If no keyword is passed, the interpolator defaults to vector mode. Two query modes are implemented: ‘sQuery’ interpolates a single point within the volume, accepting an input in the form ([_{1}, _{1}, _{1}]…[_{n}, y_{n}, z_{n}

Figure ^{3} data points; the left plot is a 2D slice through the central plane. A less dense grid of 40^{3} points was then calculated, and the middle image shows a plot through the centre. Lastly, the sparse grid was interpolated to reproduce the 400^{3} data, and is shown on the right.

A quadrupole electric field, left, 400 × 400 pixel analytic solution, centre, 40 × 40 pixel exported subset, right, 400 × 400 pixel interpolation of the subset.

ARBTools was written with Python 2.7.12 and NumPy 1.13.3 on Linux Mint 18.3, and has been tested with Python 3.5.2 on the same platform. It has also been tested on Enthought Canopy v2.1.9 on Microsoft Windows 7 and 10.

Example input fields and query scripts are available to download from the source repository. Performance benchmarking on 64-bit Linux with an Intel Core i7 CPU shows 100 unique interpolations for a given data set take between 20 and 50 ms, depending on which components are being returned. As expected, there is a linear relationship between number of queries and run time.

The main constraint when using ARBTools is the amount of memory required to load the source file; this is determined by the size of the input grid. For example; a cubic volume 20 mm on a side with a grid spacing of 0.5 mm contains 41^{3} = 68921 grid points, which will load in less than a second with negligible memory usage. The same data sampled at 0.25 mm intervals contains 531441 points, this may take several seconds to load and consume ≈500 MB memory. At 0.125 mm intervals we have 4173281 points, this may take up to a minute to load and consume over 5 GB of memory. Once loaded, however, querying these different datasets takes almost exactly the same amount of time.

The tricubic interpolation method values smoothness of the interpolated function and its first derivatives over absolute accuracy [

The magnitude of the magnetic field around a ring magnet, left, 400 × 400 pixel finite-element analysis model, centre, 40 × 40 pixel exported subset, right, 400 × 400 pixel interpolation of the subset.

For both cases a high-resolution source dataset was created, and then a sparse subset of this data was interpolated and compared with it. Figure ^{–6}%.

Root-mean-square error in interpolated data as compared to ‘true’ values from either a finite-element analysis model or an analytic solution.

ARBTools was developed on Linux Mint 18.3, and has been tested on Windows 7 and 10.

ARBTools was developed in Python 2.7.12 and has been tested on 3.5.2. Any version of Python from 2.7 upwards should be suitable.

Several GB of RAM should be suitable for most applications. ARBTools has been used with large datasets on the Durham university supercomputer.

Written using NumPy 1.13.3. Earlier versions may work.

English

The core of ARBTools is the tricubic interpolator, which can be used with any suitably-formatted input field, for many possible tasks – for example, visualising the shape of a three-dimensional potential or extracting coherent Lagrangian structures from a time-dependent two-dimensional flow. The interpolator has been designed to be imported as a library in Python, and the output from the evaluation methods can easily be passed into third-party code, or output to file for use in non-Python systems.

As is, ARBTools can be used to model the trajectories of low-field-seeking argon atoms in a magnetic field. Simply altering the mass and magnetic moment parameters would allow other species to be modelled. If the functions defining the acceleration due to a potential are replaced, trajectories in alternative systems could easily be modelled, for example, the motion of charges in electric fields, or masses moving under gravity.

Support may be requested through the project GitHub page: (

Many thanks to Dr. Lewis McArd for his invaluable advice on this and other projects.

The authors have no competing interests to declare.