Error (status) codes

In all FINUFFT interfaces, the returned value ier is a status indicator. It is 0 if successful, otherwise the error code has the following meanings which are used by both CPU and GPU versions (see codes in include/finufft_errors.h):

1  [DEPRECATED] requested tolerance epsilon too small (was warning, now see code 26)
2  stopped due to needing internal array size >MAX_NF (defined in plan.hpp)
3  spreader: fine grid too small compared to spread (kernel) width
4  spreader: [DEPRECATED]
5  spreader: array allocation error
6  spreader: illegal direction (should be 1 or 2)
7  upsampfac too small (should be >1.0)
8  upsampfac not a value with known Horner poly eval rule (currently 2.0 or 1.25 only)
9  ntrans not valid in "many" (vectorized) or guru interface (should be >= 1)
10 transform type invalid
11 general internal allocation failure
12 dimension invalid
13 spread_thread option invalid
14 invalid mode array (more than ~2^31 modes, dimension with 0 modes, etc)
15 CUDA failure (failure to call any cuda function/kernel, malloc/memset, etc))
16 attempt to destroy an uninitialized plan
17 invalid spread/interp method for dim (attempt to blockgather in 1D, e.g.)
18 size of bins for subprob/blockgather invalid
19 GPU shmem too small for subprob/blockgather parameters
20 invalid number of nonuniform points: nj or nk negative, or too big (see plan.hpp)
21 invalid input argument not covered by other errors
22 invalid FFTW lock function
23 nthreads invalid
24 spread kernel formula type invalid
25 unknown exception caught
26 requested tolerance epsilon too small to achieve (hard error; tolerance must be >= machine epsilon)
27 iteration inside the setup code for the PSWF function evaluator failed to converge

For any nonzero value of ier the transform may not have been performed and the output should not be trusted. However, we hope that the value of ier will help to narrow down the problem.

Note

On CPU, prior to v2.6.0, ier=1 was a warning that still completed the transform at reduced accuracy. The default CPU behavior is now a hard error (ier=26). Setting opts.allow_eps_too_small=1 clamps the requested tolerance to machine epsilon and allows the transform to proceed with no warning. GPU behavior is unchanged for now.

FINUFFT sometimes also sends error text to stderr if it detects faulty input parameters. Please check your terminal output.

If you are getting error codes, please reread the documentation for your language, then see our troubleshooting advice.

Large internal arrays

In case your input parameters demand the allocation of very large arrays, an internal check is done to see if their size exceeds a rather generous internal limit, set in include/finufft/plan.hpp as MAX_NF. The current value in the source code is 1e12, which corresponds to about 10TB for double precision. Allocations beyond this cause a graceful exit with error code 2 as above. Such a large allocation can be due to enormous N (in types 1 or 2), or M, but also large values of the space-bandwidth product (loosely, range of \(\mathbf{x}_j\) points times range of \(\mathbf{k}_j\) points) for type 3 transforms; see Remark 5 in reference FIN. If you have a large-RAM machine and want to exceed the above hard-coded limit, you will need to edit plan.hpp and recompile.

Similar sanity checks are done on the numbers of nonuniform points, and it is (barely) conceivable that you could want to increase MAX_NU_PTS beyond its current value of 1e14 in plan.hpp, and recompile.

All internal memory allocations performed by FINUFFT are checked for success, and error code 11 (general internal allocation failure) will be returned in case of an error. As a consequence, there should be no segmentation faults due to failing memory allocations; so if you observe one, it’s very likely a genuine bug in the application.