Skip to content

Commit 62064b6

Browse files
ahbarnettahbarnett
committed
forgot to regen matlab web-facing docs
1 parent 7526a9f commit 62064b6

File tree

2 files changed

+168
-25
lines changed

2 files changed

+168
-25
lines changed

‎docs/matlabhelp.doc‎

Lines changed: 16 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,7 @@
1111
f(k1) = SUM c[j] exp(+/-i k1 x(j)) for -ms/2 <= k1 <= (ms-1)/2
1212
j=1
1313
Inputs:
14-
x locations of nonuniform sources on interval [-pi, pi) length nj.
15-
Values outside will be folded.
16-
Note: folding large values can result in a loss of accuracy.
14+
x length-nj vector of real-valued locations of nonuniform sources
1715
c length-nj complex vector of source strengths. If numel(c)>nj,
1816
expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
1917
transformed with the same source locations.
@@ -62,9 +60,7 @@
6260
where sum is over -ms/2 <= k1 <= (ms-1)/2.
6361

6462
Inputs:
65-
x location of nonuniform targets on interval [-pi, pi), length nj.
66-
Values outside will be folded.
67-
Note: folding large values can result in a loss of accuracy.
63+
x length-nj vector of real-valued locations of nonuniform sources
6864
f complex Fourier coefficients. If a vector, length sets ms
6965
(with mode ordering given by opts.modeord). If a matrix, each
7066
of ntrans columns is transformed with the same nonuniform targets.
@@ -110,13 +106,13 @@
110106
f[k] = SUM c[j] exp(+-i s[k] x[j]), for k = 1, ..., nk
111107
j=1
112108
Inputs:
113-
x locations of nonuniform sources on R (real line), length-nj vector.
109+
x length-nj vector of real-valued locations of nonuniform sources
114110
c length-nj complex vector of source strengths. If numel(c)>nj,
115111
expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
116112
transformed with the same source and target locations.
117113
isign if >=0, uses + sign in exponential, otherwise - sign.
118114
eps relative precision requested (generally between 1e-15 and 1e-1)
119-
s frequency locations of nonuniform targets on R, length-nk vector.
115+
s length-nk vector of frequency locations of nonuniform targets
120116
opts optional struct with optional fields controlling the following:
121117
opts.debug: 0 (silent, default), 1 (timing breakdown), 2 (debug info).
122118
opts.spread_debug: spreader: 0 (no text, default), 1 (some), or 2 (lots)
@@ -158,9 +154,8 @@
158154
for -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2.
159155

160156
Inputs:
161-
x,y coordinates of nonuniform sources on the square [-pi, pi)^2,
162-
each a length-nj vector. Values outside will be folded.
163-
Note: folding large values can result in a loss of accuracy.
157+
x,y real-valued coordinates of nonuniform sources in the plane,
158+
each a length-nj vector
164159
c length-nj complex vector of source strengths. If numel(c)>nj,
165160
expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
166161
transformed with the same source locations.
@@ -210,9 +205,8 @@
210205
where sum is over -ms/2 <= k1 <= (ms-1)/2, -mt/2 <= k2 <= (mt-1)/2,
211206

212207
Inputs:
213-
x,y coordinates of nonuniform targets on the square [-pi, pi)^2,
214-
each a vector of length nj. Values outside will be folded.
215-
Note: folding large values can result in a loss of accuracy.
208+
x,y real-valued coordinates of nonuniform targets in the plane,
209+
each a vector of length nj
216210
f complex Fourier coefficient matrix, whose size determines (ms,mt).
217211
(Mode ordering given by opts.modeord, in each dimension.)
218212
If a 3D array, 3rd dimension sets ntrans, and each of ntrans
@@ -309,9 +303,8 @@
309303
-mu/2 <= k3 <= (mu-1)/2.
310304

311305
Inputs:
312-
x,y,z coordinates of nonuniform sources on the cube [-pi, pi)^3,
313-
each a length-nj vector. Values outside will be folded.
314-
Note: folding large values can result in a loss of accuracy.
306+
x,y,z real-valued coordinates of nonuniform sources,
307+
each a length-nj vector
315308
c length-nj complex vector of source strengths. If numel(c)>nj,
316309
expects a stack of vectors (eg, a nj*ntrans matrix) each of which is
317310
transformed with the same source locations.
@@ -364,9 +357,8 @@
364357
-mu/2 <= k3 <= (mu-1)/2.
365358

366359
Inputs:
367-
x,y,z coordinates of nonuniform targets on the cube [-pi, pi)^3,
368-
each a vector of length nj. Values outside will be folded.
369-
Note: folding large values can result in a loss of accuracy.
360+
x,y,z real-valued coordinates of nonuniform targets,
361+
each a vector of length nj
370362
f complex Fourier coefficient array, whose size sets (ms,mt,mu).
371363
(Mode ordering given by opts.modeord, in each dimension.)
372364
If a 4D array, 4th dimension sets ntrans, and each of ntrans
@@ -548,11 +540,10 @@
548540
plan finufft_plan object
549541

550542
Notes:
551-
* For type 1 and 2, the values in xj (and if nonempty, yj and zj)
552-
lie in the interval [-pi, pi) values outside will be folded.
553-
Note: folding large values can result in a loss of accuracy.
554-
For type 1 they are "sources", but for
555-
type 2, "targets". In contrast, for type 3 there are no restrictions other
543+
* The values in xj (and if nonempty, yj and zj) are real-valued, and
544+
invariant under translations by multiples of 2pi. For type 1
545+
they are "sources", whereas for type 2 they are "targets".
546+
For type 3 there is no periodicity, and no restrictions other
556547
than the resulting size of the internal fine grids.
557548
* s (and t and u) are only relevant for type 3, and may be omitted otherwise
558549
* The matlab vectors xj,... and s,... should not be changed before calling

‎matlab/finufft_plan.m‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,155 @@
1+
% FINUFFT_PLAN is a class which wraps the guru interface to FINUFFT.
2+
%
3+
% Full documentation is given in ../finufft-manual.pdf and online at
4+
% http://finufft.readthedocs.io
5+
% Also see examples in the matlab/examples and matlab/test directories.
6+
%
7+
% PROPERTIES
8+
% mwptr - opaque pointer to a C++ finufft_plan object (see MWrap manual),
9+
% whose properties cannot be accessed directly
10+
% floatprec - either 'double' or 'single', tracks what precision of C++
11+
% library is being called
12+
% type, dim, n_modes, n_trans, nj, nk - other plan parameters
13+
% Note: the user should never alter these plan properties directly! Rather,
14+
% the below methods should be used to create, use, and destroy plans.
15+
%
16+
% METHODS
17+
% finufft_plan - create guru plan object for one/many general nonuniform FFTs.
18+
% setpts - process nonuniform points for general FINUFFT transform(s).
19+
% execute - execute single or many-vector FINUFFT transforms in a plan.
20+
%
21+
% General notes:
22+
% * use delete(plan) to remove a plan after use.
23+
% * See ERRHANDLER, VALID_*, and this code for warning/error IDs.
24+
%
25+
%
26+
%
27+
% =========== Detailed description of guru methods ==========================
28+
%
29+
% 1) FINUFFT_PLAN create guru plan object for one/many general nonuniform FFTs.
30+
%
31+
% plan = finufft_plan(type, n_modes_or_dim, isign, ntrans, eps)
32+
% plan = finufft_plan(type, n_modes_or_dim, isign, ntrans, eps, opts)
33+
%
34+
% Creates a finufft_plan MATLAB object in the guru interface to FINUFFT, of
35+
% type 1, 2 or 3, and with given numbers of Fourier modes (unless type 3).
36+
%
37+
% Inputs:
38+
% type transform type: 1, 2, or 3
39+
% n_modes_or_dim if type is 1 or 2, the number of Fourier modes in each
40+
% dimension: [ms] in 1D, [ms mt] in 2D, or [ms mt mu] in 3D.
41+
% Its length sets the dimension, which must be 1, 2 or 3.
42+
% If type is 3, in contrast, its *value* fixes the dimension
43+
% isign if >=0, uses + sign in exponential, otherwise - sign.
44+
% eps relative precision requested (generally between 1e-15 and 1e-1)
45+
% opts optional struct with optional fields controlling the following:
46+
% opts.debug: 0 (silent, default), 1 (timing breakdown), 2 (debug info).
47+
% opts.spread_debug: spreader: 0 (no text, default), 1 (some), or 2 (lots)
48+
% opts.spread_sort: 0 (don't sort NU pts), 1 (do), 2 (auto, default)
49+
% opts.spread_kerevalmeth: 0: exp(sqrt()), 1: Horner ppval (faster)
50+
% opts.spread_kerpad: (iff kerevalmeth=0) 0: don't pad to mult of 4, 1: do
51+
% opts.fftw: FFTW plan mode, 64=FFTW_ESTIMATE (default), 0=FFTW_MEASURE, etc
52+
% opts.upsampfac: sigma. 2.0 (default), or 1.25 (low RAM, smaller FFT)
53+
% opts.spread_thread: for ntrans>1 only. 0:auto, 1:seq multi, 2:par, etc
54+
% opts.maxbatchsize: for ntrans>1 only. max blocking size, or 0 for auto.
55+
% opts.nthreads: number of threads, or 0: use all available (default)
56+
% opts.floatprec: library precision to use, 'double' (default) or 'single'.
57+
% for type 1 and 2 only, the following opts fields are also relevant:
58+
% opts.modeord: 0 (CMCL increasing mode ordering, default), 1 (FFT ordering)
59+
% opts.chkbnds: [DEPRECATED] has no effect
60+
% Outputs:
61+
% plan finufft_plan object (opaque pointer)
62+
%
63+
% Notes:
64+
% * For type 1 and 2, this does the FFTW planning and kernel-FT precomputation.
65+
% * For type 3, this does very little, since the FFT sizes are not yet known.
66+
% * Be default all threads are planned; control how many with opts.nthreads.
67+
% * The vectorized (many vector) plan, ie ntrans>1, can be much faster
68+
% than repeated calls with the same nonuniform points. Note that here the I/O
69+
% data ordering is stacked rather than interleaved. See ../docs/matlab.rst
70+
% * For more details about the opts fields, see ../docs/opts.rst
71+
%
72+
%
73+
% 2) SETPTS process nonuniform points for general FINUFFT transform(s).
74+
%
75+
% plan.setpts(xj)
76+
% plan.setpts(xj, yj)
77+
% plan.setpts(xj, yj, zj)
78+
% plan.setpts(xj, [], [], s)
79+
% plan.setpts(xj, yj, [], s, t)
80+
% plan.setpts(xj, yj, zj, s, t, u)
81+
%
82+
% When plan is a finufft_plan MATLAB object, brings in nonuniform point
83+
% coordinates (xj,yj,zj), and additionally in the type 3 case, nonuniform
84+
% frequency target points (s,t,u). Empty arrays may be passed in the case of
85+
% unused dimensions. For all types, sorting is done to internally store a
86+
% reindexing of points, and for type 3 the spreading and FFTs are planned.
87+
% The nonuniform points may be used for multiple transforms.
88+
%
89+
% Inputs:
90+
% xj vector of x-coords of all nonuniform points
91+
% yj empty (if dim<2), or vector of y-coords of all nonuniform points
92+
% zj empty (if dim<3), or vector of z-coords of all nonuniform points
93+
% s vector of x-coords of all nonuniform frequency targets
94+
% t empty (if dim<2), or vector of y-coords of all frequency targets
95+
% u empty (if dim<3), or vector of z-coords of all frequency targets
96+
% Input/Outputs:
97+
% plan finufft_plan object
98+
%
99+
% Notes:
100+
% * The values in xj (and if nonempty, yj and zj) are real-valued, and
101+
% invariant under translations by multiples of 2pi. For type 1
102+
% they are "sources", whereas for type 2 they are "targets".
103+
% For type 3 there is no periodicity, and no restrictions other
104+
% than the resulting size of the internal fine grids.
105+
% * s (and t and u) are only relevant for type 3, and may be omitted otherwise
106+
% * The matlab vectors xj,... and s,... should not be changed before calling
107+
% future execute calls, because the plan stores only pointers to the
108+
% arrays (they are not duplicated internally).
109+
% * The precision (double/single) of all inputs must match that chosen at the
110+
% plan stage using opts.floatprec, otherwise an error is raised.
111+
%
112+
%
113+
% 3) EXECUTE execute single or many-vector FINUFFT transforms in a plan.
114+
%
115+
% result = plan.execute(data_in);
116+
%
117+
% For plan a previously created finufft_plan object also containing all
118+
% needed nonuniform point coordinates, do a single (or if ntrans>1 in the
119+
% plan stage, multiple) NUFFT transform(s), with the strengths or Fourier
120+
% coefficient inputs vector(s) from data_in. The result of the transform(s)
121+
% is returned as a (possibly multidimensional) array.
122+
%
123+
% Inputs:
124+
% plan finufft_plan object
125+
% data_in strengths (types 1 or 3) or Fourier coefficients (type 2)
126+
% vector, matrix, or array of appropriate size. For type 1 and 3,
127+
% this is either a length-M vector (where M is the length of xj),
128+
% or an (M,ntrans) matrix when ntrans>1. For type 2, in 1D this is
129+
% length-ms, in 2D size (ms,mt), or in 3D size (ms,mt,mu), or
130+
% each of these with an extra last dimension ntrans if ntrans>1.
131+
% Outputs:
132+
% result vector of output strengths at targets (types 2 or 3), or array
133+
% of Fourier coefficients (type 1), or, if ntrans>1, a stack of
134+
% such vectors or arrays, of appropriate size.
135+
% Specifically, if ntrans=1, for type 1, in 1D
136+
% this is a length-ms column vector, in 2D a matrix of size
137+
% (ms,mt), or in 3D an array of size (ms,mt,mu); for types 2 and 3
138+
% it is a column vector of length M (the length of xj in type 2),
139+
% or nk (the length of s in type 3). If ntrans>1 its is a stack
140+
% of such objects, ie, it has an extra last dimension ntrans.
141+
%
142+
% Notes:
143+
% * The precision (double/single) of all inputs must match that chosen at the
144+
% plan stage using opts.floatprec, otherwise an error is raised.
145+
%
146+
%
147+
% 4) To deallocate (delete) a nonuniform FFT plan, use delete(plan)
148+
%
149+
% This deallocates all stored FFTW plans, nonuniform point sorting arrays,
150+
% kernel Fourier transforms arrays, etc.
151+
%
152+
%
1153

2154
classdef finufft_plan < handle
3155

0 commit comments

Comments
 (0)