Merge branch 'master' into speedup_python_ci

Author: ahbarnett

.github/workflows/python_test_win.ps1

@@ -2,3 +2,5 @@ python -m pip install finufft -f .\wheelhouse\
 if (-not $?) {throw "Failed to pip install finufft"}
 python python/test/run_accuracy_tests.py
 if (-not $?) {throw "Tests failed"}
+python python/examples/simple1d1.py
+if (-not $?) {throw "Simple1d1 test failed"}

.github/workflows/python_wheel.yml

@@ -108,6 +108,8 @@ jobs:
       run: |
         make lib
         export FINUFFT_DIR=`pwd`
+        export CC=gcc-11
+        export CXX=g++-11
         cd python
         /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 -m pip install --upgrade setuptools wheel numpy pip
         /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 -m pip install -U wheel --user
@@ -129,14 +131,19 @@ jobs:
         ls wheelhouse/finufft*.whl | xargs -n1 $PYTHON_BIN/delocate-wheel -w fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 -m pip install finufft -f fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 test/run_accuracy_tests.py
+        /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 examples/simple1d1.py
         /Library/Frameworks/Python.framework/Versions/3.7/bin/python3 -m pip install finufft -f fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.7/bin/python3 test/run_accuracy_tests.py
+        /Library/Frameworks/Python.framework/Versions/3.7/bin/python3 examples/simple1d1.py
         /Library/Frameworks/Python.framework/Versions/3.8/bin/python3 -m pip install finufft -f fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.8/bin/python3 test/run_accuracy_tests.py
+        /Library/Frameworks/Python.framework/Versions/3.8/bin/python3 examples/simple1d1.py
         /Library/Frameworks/Python.framework/Versions/3.9/bin/python3 -m pip install finufft -f fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.9/bin/python3 test/run_accuracy_tests.py
+        /Library/Frameworks/Python.framework/Versions/3.9/bin/python3 examples/simple1d1.py
         /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 -m pip install finufft -f fixed_wheel/
         /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 test/run_accuracy_tests.py
+        /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 examples/simple1d1.py
 
     - name: Upload wheels
       uses: actions/upload-artifact@v2

.readthedocs.yml

@@ -7,6 +7,9 @@
 # Required (for this file format)
 version: 2
 
+# Build all formats
+formats: all
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py

CHANGELOG

@@ -1,21 +1,36 @@
 List of features / changes made / release notes, in reverse chronological order
 
-* library private namespacing via finufft::* of all symbols that do not already
-  begin with finufft{f}. This addresses clash with linking against cufinufft
-  (their Issue #138).
+V 2.1.0 (6/10/22)
+
+* BREAKING INTERFACE CHANGE: nufft_opts is now called finufft_opts.
+  This is needed for consistency and fixes a historical problem.
+  We have compile-time warning, and backwards-compatibility for now.
+* Professionalized the public-facing interface:
+  - safe lib (.so, .a) symbols via hierarchical namespacing of private funcs
+    that do not already begin with finufft{f}, in finufft:: namespace.
+    This fixes, eg, clash with linking against cufinufft (their Issue #138).
+  - public headers (finufft.h) has all macro names safe (ie FINUFFT suffix).
+    Headers both public and private rationalized/simplified.
+  - private headers are in include/finufft/, so not exposed by -Iinclude
+  - spread_opts renamed finufft_spread_opts, since publicly exposed and name
+    must respect library naming.
+* change nj and nk in plan to BIGINT (int64_t), new big2d2f perftest, fixing
+  Issue #215.
+* PDF manual moved from local to readthedocs.io hosting, Issue #221.
+* Py doc for dtype fixed, Issue #216.
 * spreadinterp evaluate_kernel_vector uses single arith when FLT=single.
 * spread_opts.h fix duplication for FLT=single/double by making FLT->double.
 * examples/simulplans1d1 demos ability to to wield independent plans.
 * sped up float32 1d type 3 by 20% by using float32 cos()... thanks Wenda Zhou.
 
 V 2.0.4 (1/13/22)
-	
+
 * makefile now appends (not replaces by) environment {C,F,CXX}FLAGS (PR #199).
 * fixed MATLAB Contents.m and guru help strings.
 * fortran examples: avoided clash with keywords "type" and "null", and correct
   creation of null ptr for default opts (issues #195-196, Jiri Kulda).
 * various fixes to python wheels CI.
-* various docs improvements.	
+* various docs improvements.
 * fixed modeord=1 failure for type 3 even though should never be used anyway
   (issue #194).
 * fixed spreadcheck NaN failure to detect bug introduced in 2.0.3 (9566511).

README.md

@@ -13,10 +13,10 @@ see `docs/ackn.rst` for full list of contributors.
 
 This is a lightweight library to compute the three standard types of nonuniform FFT to a specified precision, in one, two, or three dimensions. It is written in C++ with interfaces to C, Fortran, MATLAB/octave, Python, and (in a separate [repository](https://github.com/ludvigak/FINUFFT.jl)) Julia.
 
-Please see the [online documentation](http://finufft.readthedocs.io/en/latest/index.html), or its local PDF equivalent, the [user manual](finufft-manual.pdf).
+Please see the [online documentation](http://finufft.readthedocs.io/en/latest/index.html) which can also be downloaded as a [PDF manual](https://finufft.readthedocs.io/_/downloads/en/latest/pdf/).
 You will also want to see example codes in the directories
 `examples`, `test`, `fortran`, `matlab/test`, and `python/test`.
-If you cannot compile, or `pip install`, try our [precompiled binaries](http://users.flatironinstitute.org/~ahb/codes/finufft-binaries).
+If you cannot compile, or `pip install`, try our rather outdated [precompiled binaries](http://users.flatironinstitute.org/~ahb/codes/finufft-binaries).
 
 If you prefer to read text files, the source to generate the above documentation is in human-readable (mostly .rst) files as follows:
 

docs/README

@@ -1,42 +1,73 @@
 README for developers on FINUFFT documentation.
 
-The .rst files in this directory are designed for sphinx to auto-generate
-documentation in HTML (including from the readthedocs.io website), and in PDF.
+The .rst files (and files they include such as .doc)
+in this directory are designed for sphinx to auto-generate
+documentation, specifically that hosted at the readthedocs.io website
+(HTML and PDF versions).
 
-The main procedure to regenerate the documentation from source is
-``make docs`` from the top-level directory. See ``../makefile`` for
-what's going on here. This does some custom bash scripts for the various
-language interface docs, then uses sphinx to make latex and html
-versions of the entire manual. The readthedocs.io website is triggered
-to update when github master branch changes. The idea is:
+finufft.readthedocs.io should have been set up to be triggered by
+pushes to the git repo master branch to generate HTML/PDF
+documentation, hosted there for the world to see.  Which formats are
+built at that website is controlled by .readthedocs.yml
 
-*.docsrc ---(bash)---> *.doc ----(included in)----> *.rst -----(sphinx)-->
+However we autogenerate several parts of this sphinx source, and this
+is done by ``make docs``, called from the top-level directory. See
+``../makefile`` for what's going on here. It calls some custom bash
+scripts to generate various language interface docs (.rst and files
+that they include). The results are tracked by git, so don't forget to
+commit them and push to master.
 
-/  PDF (sits in the repo)
-\  HTML ---(readthedocs trigger)--->   finufft.readthedocs.io
+Our docs dependency graph is, in broad strokes:
 
-Do not edit files ``docs/*.doc`` since these are machine-generated; your changes will be overwritten. Instead edit files ``*.docsrc`` once you have understood how the bash scripts act on them.
+{*.docsrc, ../matlab/*.docsrc, etc}  ----(bash, via ``make docs'')---->
+{*.doc, *.m}   ----(which are included in)---->   *.rst
 
-There are also separate MATLAB/Octave (bash) and Python (autodoc) doc
-generations going on.
+Then {*.rst, *.doc, *.m, *.py, CHANGELOG, certain source codes, etc}
+  ----(triggered by push to github master)---->
+finufft.readthedocs.io (generates then hosts HTML/PDF)
 
-To perform doc-generation, you need to set up the following environment
-(we have only ever done this on linux):
+As of v2.1.0, the local PDF manual is no longer tracked by
+git, due to its dominant and growing contribution to the size of the repo.
 
-python3
-sphinx  - (at least v1.3), can conda install. Needs latex and latexmk
-          (for ubuntu 20.04: sudo apt install texlive-base latexmk)
-texext  - a small sphinx helper for math, seems only to be pip-installable:
-          https://github.com/matthew-brett/texext
+Note that ../README.md also should be considered part of the docs, since
+it contains a precis for text-loving and github-facing humans.
 
-Then to check the local build of the HTML docs, useful for debugging before you
-wait for a git push origin to be detected by RTD, point your browser to the
-local file _build/html/index.html
 
-finufft.readthedocs.io should have been set up to be triggered by
-pushes to the git repo to regenerate HTML documentation identical to the
-local copy, hosted there for the world to see.
+1) Details for running ``make docs''
+
+Do not edit files ``docs/*.doc`` since these are machine-generated;
+your changes will be overwritten!  Instead edit files ``*.docsrc``,
+once you have understood how the bash scripts act on them.  The same
+applies to the separate MATLAB/Octave doc gen (which is in bash).  The
+python doc gen is *not* done by make docs, instead it is done by
+sphinx through its autodoc extension.  To run ``make docs'' locally,
+you only need bash.
+
+Note that ``make docs`` no longer builds a local copy of the docs in
+either HTML or PDF; to do this keep reading.
+
+
+2) How to do a local sphinx doc build for devs to check them quickly
+
+The github trigger plus readthedocs.io build can take several minutes,
+annoying for debugging. For faster doc build checking you'll want to work
+locally (we have only ever tried this on linux).  For this you'll need
+to install:
+
+  * sphinx  - (at least v1.3), can conda install. Needs latex and latexmk
+              (for ubuntu 20.04: sudo apt install texlive-base latexmk)
+  * texext  - a small sphinx helper for math, seems only to be pip-installable:
+              https://github.com/matthew-brett/texext
+  * python3 - since sphinx autodoc actually runs py to gen docstrings.
+
+Then (from this docs directory), run ``make latexpdf``
+and look in _build/latex/finufft.pdf for the PDF.
+
+Or, run ``make html`` then point your browser to
+the local file _build/html/index.html
+
+Note that there are some sphinx tags indicated by @ in the source codes;
+do not remove them.
 
-Note that ../README.md also should be considered part of the docs, since
-it contains a precis for text-loving and github-facing humans.
 
+Alex Barnett, 2022/6/13.

docs/c.rst

@@ -32,12 +32,12 @@ due to unnecessary array copying.
 
 
 In all of the simple, vectorized, and plan functions below you may either pass ``NULL`` as the last options
-argument to use default options, or a pointer to a valid ``nufft_opts`` struct.
+argument to use default options, or a pointer to a valid ``finufft_opts`` struct.
 In this latter case you will first need to create an options struct
 then set default values by passing a pointer (here ``opts``) to the following::
 
- void finufft_default_opts(nufft_opts* opts)
- void finufftf_default_opts(nufft_opts* opts)
+ void finufft_default_opts(finufft_opts* opts)
+ void finufftf_default_opts(finufft_opts* opts)
    
   Set values in a NUFFT options struct to their default values.
 

docs/c1d.doc

@@ -1,14 +1,14 @@
 ::
 
  int finufft1d1(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t 
- N1, complex<double>* f, nufft_opts* opts)
+ N1, complex<double>* f, finufft_opts* opts)
  int finufftf1d1(int64_t M, float* x, complex<float>* c, int iflag, float eps, int64_t N1, 
- complex<float>* f, nufft_opts* opts)
+ complex<float>* f, finufftf_opts* opts)
 
  int finufft1d1many(int ntr, int64_t M, double* x, complex<double>* c, int iflag, double 
- eps, int64_t N1, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N1, complex<double>* f, finufft_opts* opts)
  int finufftf1d1many(int ntr, int64_t M, float* x, complex<float>* c, int iflag, float 
- eps, int64_t N1, complex<float>* f, nufft_opts* opts)
+ eps, int64_t N1, complex<float>* f, finufftf_opts* opts)
 
    1D complex nonuniform FFT of type 1 (nonuniform to uniform).
 
@@ -43,14 +43,14 @@
 ::
 
  int finufft1d2(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t 
- N1, complex<double>* f, nufft_opts* opts)
+ N1, complex<double>* f, finufft_opts* opts)
  int finufftf1d2(int64_t M, float* x, complex<float>* c, int iflag, float eps, int64_t N1, 
- complex<float>* f, nufft_opts* opts)
+ complex<float>* f, finufftf_opts* opts)
 
  int finufft1d2many(int ntr, int64_t M, double* x, complex<double>* c, int iflag, double 
- eps, int64_t N1, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N1, complex<double>* f, finufft_opts* opts)
  int finufftf1d2many(int ntr, int64_t M, float* x, complex<float>* c, int iflag, float 
- eps, int64_t N1, complex<float>* f, nufft_opts* opts)
+ eps, int64_t N1, complex<float>* f, finufftf_opts* opts)
 
    1D complex nonuniform FFT of type 2 (uniform to nonuniform).
 
@@ -85,14 +85,14 @@
 ::
 
  int finufft1d3(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t 
- N, double* s, complex<double>* f, nufft_opts* opts)
+ N, double* s, complex<double>* f, finufft_opts* opts)
  int finufftf1d3(int64_t M, float* x, complex<float>* c, int iflag, float eps, int64_t N, 
- float* s, complex<float>* f, nufft_opts* opts)
+ float* s, complex<float>* f, finufftf_opts* opts)
 
  int finufft1d3many(int ntr, int64_t M, double* x, complex<double>* c, int iflag, double 
- eps, int64_t N, double* s, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N, double* s, complex<double>* f, finufft_opts* opts)
  int finufftf1d3many(int ntr, int64_t M, float* x, complex<float>* c, int iflag, float 
- eps, int64_t N, float* s, complex<float>* f, nufft_opts* opts)
+ eps, int64_t N, float* s, complex<float>* f, finufftf_opts* opts)
 
    1D complex nonuniform FFT of type 3 (nonuniform to nonuniform).
 

docs/c1d.docsrc

@@ -1,4 +1,4 @@
-int @F1d1(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N1, complex<double>* f, nufft_opts* opts)
+int @F1d1(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N1, complex<double>* f, finufft_opts* opts)
 
   1D complex nonuniform FFT of type 1 (nonuniform to uniform).
 @t
@@ -23,7 +23,7 @@ int @F1d1(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64
 @notes12
 
 
-int @F1d2(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N1, complex<double>* f, nufft_opts* opts)
+int @F1d2(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N1, complex<double>* f, finufft_opts* opts)
 
   1D complex nonuniform FFT of type 2 (uniform to nonuniform).
 @t
@@ -48,7 +48,7 @@ int @F1d2(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64
 @notes12
 
 
-int @F1d3(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N, double* s, complex<double>* f, nufft_opts* opts)
+int @F1d3(int64_t M, double* x, complex<double>* c, int iflag, double eps, int64_t N, double* s, complex<double>* f, finufft_opts* opts)
 
   1D complex nonuniform FFT of type 3 (nonuniform to nonuniform).
 @t

docs/c2d.doc

@@ -1,14 +1,14 @@
 ::
 
  int finufft2d1(int64_t M, double* x, double* y, complex<double>* c, int iflag, double 
- eps, int64_t N1, int64_t N2, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N1, int64_t N2, complex<double>* f, finufft_opts* opts)
  int finufftf2d1(int64_t M, float* x, float* y, complex<float>* c, int iflag, float eps, 
- int64_t N1, int64_t N2, complex<float>* f, nufft_opts* opts)
+ int64_t N1, int64_t N2, complex<float>* f, finufftf_opts* opts)
 
  int finufft2d1many(int ntr, int64_t M, double* x, double* y, complex<double>* c, int 
- iflag, double eps, int64_t N1, int64_t N2, complex<double>* f, nufft_opts* opts)
+ iflag, double eps, int64_t N1, int64_t N2, complex<double>* f, finufft_opts* opts)
  int finufftf2d1many(int ntr, int64_t M, float* x, float* y, complex<float>* c, int iflag, 
- float eps, int64_t N1, int64_t N2, complex<float>* f, nufft_opts* opts)
+ float eps, int64_t N1, int64_t N2, complex<float>* f, finufftf_opts* opts)
 
    2D complex nonuniform FFT of type 1 (nonuniform to uniform).
 
@@ -45,14 +45,14 @@
 ::
 
  int finufft2d2(int64_t M, double* x, double* y, complex<double>* c, int iflag, double 
- eps, int64_t N1, int64_t N2, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N1, int64_t N2, complex<double>* f, finufft_opts* opts)
  int finufftf2d2(int64_t M, float* x, float* y, complex<float>* c, int iflag, float eps, 
- int64_t N1, int64_t N2, complex<float>* f, nufft_opts* opts)
+ int64_t N1, int64_t N2, complex<float>* f, finufftf_opts* opts)
 
  int finufft2d2many(int ntr, int64_t M, double* x, double* y, complex<double>* c, int 
- iflag, double eps, int64_t N1, int64_t N2, complex<double>* f, nufft_opts* opts)
+ iflag, double eps, int64_t N1, int64_t N2, complex<double>* f, finufft_opts* opts)
  int finufftf2d2many(int ntr, int64_t M, float* x, float* y, complex<float>* c, int iflag, 
- float eps, int64_t N1, int64_t N2, complex<float>* f, nufft_opts* opts)
+ float eps, int64_t N1, int64_t N2, complex<float>* f, finufftf_opts* opts)
 
    2D complex nonuniform FFT of type 2 (uniform to nonuniform).
 
@@ -87,14 +87,15 @@
 ::
 
  int finufft2d3(int64_t M, double* x, double* y, complex<double>* c, int iflag, double 
- eps, int64_t N, double* s, double* t, complex<double>* f, nufft_opts* opts)
+ eps, int64_t N, double* s, double* t, complex<double>* f, finufft_opts* opts)
  int finufftf2d3(int64_t M, float* x, float* y, complex<float>* c, int iflag, float eps, 
- int64_t N, float* s, float* t, complex<float>* f, nufft_opts* opts)
+ int64_t N, float* s, float* t, complex<float>* f, finufftf_opts* opts)
 
  int finufft2d3many(int ntr, int64_t M, double* x, double* y, complex<double>* c, int 
- iflag, double eps, int64_t N, double* s, double* t, complex<double>* f, nufft_opts* opts)
+ iflag, double eps, int64_t N, double* s, double* t, complex<double>* f, finufft_opts* 
+ opts)
  int finufftf2d3many(int ntr, int64_t M, float* x, float* y, complex<float>* c, int iflag, 
- float eps, int64_t N, float* s, float* t, complex<float>* f, nufft_opts* opts)
+ float eps, int64_t N, float* s, float* t, complex<float>* f, finufftf_opts* opts)
 
    2D complex nonuniform FFT of type 3 (nonuniform to nonuniform).