removed 3pi from docs in matlab wrappers, and chkbnds from matlab tests [note setting opts.chkbnds=0 segaulfts or fails badly]

ahbarnett · ahbarnett · commit 4cf52e7316f2 · 2024-05-14T22:17:05.000-04:00
diff --git a/matlab/errhandler.m b/matlab/errhandler.m
@@ -14,7 +14,7 @@ function errhandler(ier)
  case 3
   error('FINUFFT:spreadinterp:fineGridSmall','FINUFFT spreader fine grid too small compared to kernel width');
  case 4
-  error('FINUFFT:spreadinterp:NUrange','FINUFFT spreader nonuniform point out of range [-3pi,3pi]^d in type 1 or 2.');
+  error('FINUFFT:spreadinterp:NUrange','[DEPRECATED]');
  case 5
   error('FINUFFT:spreadinterp:malloc','FINUFFT spreader malloc error');
  case 6
diff --git a/matlab/finufft1d1.docsrc b/matlab/finufft1d1.docsrc
@@ -9,7 +9,7 @@
 %     f(k1) =  SUM c[j] exp(+/-i k1 x(j))  for -ms/2 <= k1 <= (ms-1)/2
 %              j=1
 %   Inputs:
-%     x     locations of nonuniform sources on interval [-3pi,3pi), length nj
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source locations.
diff --git a/matlab/finufft1d1.m b/matlab/finufft1d1.m
@@ -9,9 +9,7 @@
 %     f(k1) =  SUM c[j] exp(+/-i k1 x(j))  for -ms/2 <= k1 <= (ms-1)/2
 %              j=1
 %   Inputs:
-%     x     locations of nonuniform sources on interval [-pi, pi) length nj.
-%           Values outside will be folded.
-%           Note: folding large values can result in a loss of accuracy.
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source locations.
diff --git a/matlab/finufft1d2.docsrc b/matlab/finufft1d2.docsrc
@@ -10,7 +10,7 @@
 %     where sum is over -ms/2 <= k1 <= (ms-1)/2.
 %
 %  Inputs:
-%     x     location of nonuniform targets on interval [-3pi,3pi), length nj
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     f     complex Fourier coefficients. If a vector, length sets ms
 %           (with mode ordering given by opts.modeord). If a matrix, each
 %           of ntrans columns is transformed with the same nonuniform targets.
diff --git a/matlab/finufft1d2.m b/matlab/finufft1d2.m
@@ -10,9 +10,7 @@
 %     where sum is over -ms/2 <= k1 <= (ms-1)/2.
 %
 %  Inputs:
-%     x     location of nonuniform targets on interval [-pi, pi), length nj.
-%           Values outside will be folded.
-%           Note: folding large values can result in a loss of accuracy.
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     f     complex Fourier coefficients. If a vector, length sets ms
 %           (with mode ordering given by opts.modeord). If a matrix, each
 %           of ntrans columns is transformed with the same nonuniform targets.
diff --git a/matlab/finufft1d3.docsrc b/matlab/finufft1d3.docsrc
@@ -9,12 +9,12 @@
 %     f[k]  =  SUM   c[j] exp(+-i s[k] x[j]),      for k = 1, ..., nk
 %              j=1
 %   Inputs:
-%     x     locations of nonuniform sources on R (real line), length-nj vector.
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source and target locations.
 ISIGNEPS
-%     s     frequency locations of nonuniform targets on R, length-nk vector.
+%     s     length-nk vector of frequency locations of nonuniform targets
 OPTS
 %   Outputs:
 %     f     length-nk complex vector of values at targets, or, if ntrans>1,
diff --git a/matlab/finufft1d3.m b/matlab/finufft1d3.m
@@ -9,13 +9,13 @@
 %     f[k]  =  SUM   c[j] exp(+-i s[k] x[j]),      for k = 1, ..., nk
 %              j=1
 %   Inputs:
-%     x     locations of nonuniform sources on R (real line), length-nj vector.
+%     x     length-nj vector of real-valued locations of nonuniform sources
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source and target locations.
 %     isign if >=0, uses + sign in exponential, otherwise - sign.
 %     eps   relative precision requested (generally between 1e-15 and 1e-1)
-%     s     frequency locations of nonuniform targets on R, length-nk vector.
+%     s     length-nk vector of frequency locations of nonuniform targets
 %     opts   optional struct with optional fields controlling the following:
 %     opts.debug:   0 (silent, default), 1 (timing breakdown), 2 (debug info).
 %     opts.spread_debug: spreader: 0 (no text, default), 1 (some), or 2 (lots)
diff --git a/matlab/finufft2d1.docsrc b/matlab/finufft2d1.docsrc
@@ -12,7 +12,7 @@
 %     for -ms/2 <= k1 <= (ms-1)/2,  -mt/2 <= k2 <= (mt-1)/2.
 %
 %   Inputs:
-%     x,y   coordinates of nonuniform sources on the square [-3pi,3pi)^2,
+%     x,y   real-valued coordinates of nonuniform sources in the plane,
 %           each a length-nj vector
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
diff --git a/matlab/finufft2d1.m b/matlab/finufft2d1.m
@@ -12,9 +12,8 @@
 %     for -ms/2 <= k1 <= (ms-1)/2,  -mt/2 <= k2 <= (mt-1)/2.
 %
 %   Inputs:
-%     x,y   coordinates of nonuniform sources on the square [-pi, pi)^2,
-%           each a length-nj vector. Values outside will be folded.
-%           Note: folding large values can result in a loss of accuracy.
+%     x,y   real-valued coordinates of nonuniform sources in the plane,
+%           each a length-nj vector
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source locations.
diff --git a/matlab/finufft2d2.docsrc b/matlab/finufft2d2.docsrc
@@ -10,7 +10,7 @@
 %     where sum is over -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2,
 %
 %  Inputs:
-%     x,y   coordinates of nonuniform targets on the square [-3pi,3pi)^2,
+%     x,y   real-valued coordinates of nonuniform targets in the plane,
 %           each a vector of length nj
 %     f     complex Fourier coefficient matrix, whose size determines (ms,mt).
 %           (Mode ordering given by opts.modeord, in each dimension.)
diff --git a/matlab/finufft2d2.m b/matlab/finufft2d2.m
@@ -10,9 +10,8 @@
 %     where sum is over -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2,
 %
 %  Inputs:
-%     x,y   coordinates of nonuniform targets on the square [-pi, pi)^2,
-%           each a vector of length nj. Values outside will be folded.
-%           Note: folding large values can result in a loss of accuracy.
+%     x,y   real-valued coordinates of nonuniform targets in the plane,
+%           each a vector of length nj
 %     f     complex Fourier coefficient matrix, whose size determines (ms,mt).
 %           (Mode ordering given by opts.modeord, in each dimension.)
 %           If a 3D array, 3rd dimension sets ntrans, and each of ntrans
diff --git a/matlab/finufft3d1.docsrc b/matlab/finufft3d1.docsrc
@@ -13,8 +13,8 @@
 %         -mu/2 <= k3 <= (mu-1)/2.
 %
 %   Inputs:
-%     x,y,z  coordinates of nonuniform sources on the cube [-3pi,3pi)^3,
-%            each a length-nj vector
+%     x,y,z real-valued coordinates of nonuniform sources,
+%           each a length-nj vector
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source locations.
diff --git a/matlab/finufft3d1.m b/matlab/finufft3d1.m
@@ -13,9 +13,8 @@
 %         -mu/2 <= k3 <= (mu-1)/2.
 %
 %   Inputs:
-%     x,y,z  coordinates of nonuniform sources on the cube [-pi, pi)^3,
-%            each a length-nj vector. Values outside will be folded.
-%            Note: folding large values can result in a loss of accuracy.
+%     x,y,z real-valued coordinates of nonuniform sources,
+%           each a length-nj vector
 %     c     length-nj complex vector of source strengths. If numel(c)>nj,
 %           expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
 %           transformed with the same source locations.
diff --git a/matlab/finufft3d2.docsrc b/matlab/finufft3d2.docsrc
@@ -12,7 +12,7 @@
 %                       -mu/2 <= k3 <= (mu-1)/2.
 %
 %  Inputs:
-%     x,y,z coordinates of nonuniform targets on the cube [-3pi,3pi)^3,
+%     x,y,z real-valued coordinates of nonuniform targets,
 %           each a vector of length nj
 %     f     complex Fourier coefficient array, whose size sets (ms,mt,mu).
 %           (Mode ordering given by opts.modeord, in each dimension.)
diff --git a/matlab/finufft3d2.m b/matlab/finufft3d2.m
@@ -12,9 +12,8 @@
 %                       -mu/2 <= k3 <= (mu-1)/2.
 %
 %  Inputs:
-%     x,y,z coordinates of nonuniform targets on the cube [-pi, pi)^3,
-%           each a vector of length nj. Values outside will be folded.
-%           Note: folding large values can result in a loss of accuracy.
+%     x,y,z real-valued coordinates of nonuniform targets,
+%           each a vector of length nj
 %     f     complex Fourier coefficient array, whose size sets (ms,mt,mu).
 %           (Mode ordering given by opts.modeord, in each dimension.)
 %           If a 4D array, 4th dimension sets ntrans, and each of ntrans
diff --git a/matlab/finufft_plan.docsrc b/matlab/finufft_plan.docsrc
@@ -85,9 +85,10 @@ OPTS12
 %     plan   finufft_plan object
 %
 % Notes:
-%  * For type 1 and 2, the values in xj (and if nonempty, yj and zj) must
-%    lie in the interval [-3pi,3pi). For type 1 they are "sources", but for
-%    type 2, "targets". In contrast, for type 3 there are no restrictions other
+%  * The values in xj (and if nonempty, yj and zj) are real-valued, and
+%    invariant under translations by multiples of 2pi. For type 1
+%    they are "sources", whereas for type 2 they are "targets".
+%    For type 3 there is no periodicity, and no restrictions other
 %    than the resulting size of the internal fine grids.
 %  * s (and t and u) are only relevant for type 3, and may be omitted otherwise
 %  * The matlab vectors xj,... and s,... should not be changed before calling
diff --git a/matlab/finufft_plan.m b/matlab/finufft_plan.m
@@ -97,11 +97,10 @@
 %     plan   finufft_plan object
 %
 % Notes:
-%  * For type 1 and 2, the values in xj (and if nonempty, yj and zj) 
-%    lie in the interval [-pi, pi) values outside will be folded.
-%    Note: folding large values can result in a loss of accuracy.
-%    For type 1 they are "sources", but for
-%    type 2, "targets". In contrast, for type 3 there are no restrictions other
+%  * The values in xj (and if nonempty, yj and zj) are real-valued, and
+%    invariant under translations by multiples of 2pi. For type 1
+%    they are "sources", whereas for type 2 they are "targets".
+%    For type 3 there is no periodicity, and no restrictions other
 %    than the resulting size of the internal fine grids.
 %  * s (and t and u) are only relevant for type 3, and may be omitted otherwise
 %  * The matlab vectors xj,... and s,... should not be changed before calling
diff --git a/matlab/test/check_finufft.m b/matlab/test/check_finufft.m
@@ -3,6 +3,7 @@
 % Barnett 3/24/17; updated normalization in type-1 6/6/17. upsampfac 6/18/18.
 % new interface 6/10/20.
 % 7/9/20, Changed rel error normalization to max of outputs.
+% 5/14/24, chkbnds deprecated
 
 % Runtime is around 3-10 seconds on a modern machine
 
@@ -13,7 +14,6 @@
 %o.spread_debug=1;   % see detailed spreader info
 FFTW_ESTIMATE = bitshift(1,6); o.fftw = FFTW_ESTIMATE;       % or see fftw3.h
 o.upsampfac=0;    % 0 (auto), 2.0 (default), or 1.25 (low-RAM, small-FFT)
-o.chkbnds=0;      % a few percent faster
 M       = 1e6;    % # of NU pts (in all dims)
 N       = 1e6;    % # of modes (approx total, used in all dims)
 
diff --git a/matlab/test/check_finufft_single.m b/matlab/test/check_finufft_single.m
@@ -1,6 +1,7 @@
 % Matlab/octave demo of interfaces for FINUFFT library, single-precision.
 % Also checks the math, but accuracy cannot be good for long 1D NUFFTs.
 % Barnett 7/6/20-7/9/20. Changed rel error normalization to max of outputs.
+% 5/14/24, chkbnds deprecated
 
 % Runtime is around 1-2 second on modern machine.
 
@@ -10,7 +11,6 @@
 o.debug = 0;      % choose 1 for timing breakdown text output
 FFTW_ESTIMATE = bitshift(1,6); o.fftw = FFTW_ESTIMATE;       % or see fftw3.h
 o.upsampfac=0;    % 0 (auto), 2.0 (default), or 1.25 (low-RAM, small-FFT)
-o.chkbnds=0;      % a few percent faster
 M       = 1e4;    % # of NU pts (in all dims). Kept small to not lose 1d acc.
 N       = 1e4;    % # of modes (approx total, used in all dims).
 

Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`% where sum is over -ms/2 <= k1 <= (ms-1)/2.`
`11`	`11`	`%`
`12`	`12`	`% Inputs:`
`13`		`-% x location of nonuniform targets on interval [-3pi,3pi), length nj`
	`13`	`+% x length-nj vector of real-valued locations of nonuniform sources`
`14`	`14`	`% f complex Fourier coefficients. If a vector, length sets ms`
`15`	`15`	`% (with mode ordering given by opts.modeord). If a matrix, each`
`16`	`16`	`% of ntrans columns is transformed with the same nonuniform targets.`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@`
`12`	`12`	`% for -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2.`
`13`	`13`	`%`
`14`	`14`	`% Inputs:`
`15`		`-% x,y coordinates of nonuniform sources on the square [-3pi,3pi)^2,`
	`15`	`+% x,y real-valued coordinates of nonuniform sources in the plane,`
`16`	`16`	`% each a length-nj vector`
`17`	`17`	`% c length-nj complex vector of source strengths. If numel(c)>nj,`
`18`	`18`	`% expects a stack of vectors (eg, a nj*ntrans matrix) each of which is`