updated docs

Author: DiamonDinoia

CMakeLists.txt

@@ -18,7 +18,7 @@ option(FINUFFT_ENABLE_SANITIZERS "Whether to enable sanitizers, only effective f
 option(FINUFFT_USE_OPENMP "Whether to use OpenMP for parallelization. If disabled, the finufft library will be single threaded. This does not affect the choice of FFTW library." ON)
 option(FINUFFT_USE_CPU "Whether to build the ordinary FINUFFT library (libfinufft)." ON)
 option(FINUFFT_USE_CUDA "Whether to build CUDA accelerated FINUFFT library (libcufinufft). This is completely independent of the main FINUFFT library" OFF)
-option(FINUFFT_STATIC_LINKING "Whether to build the static FINUFFT library." ON)
+option(FINUFFT_STATIC_LINKING "If ON builds the static finufft library, if OFF build a shared finufft library." ON)
 option(FINUFFT_BUILD_DEVEL "Whether to build development executables" OFF)
 option(FINUFFT_BUILD_EXAMPLES "Whether to build the FINUFFT examples" OFF)
 option(FINUFFT_BUILD_TESTS "Whether to build the FINUFFT tests" OFF)
@@ -141,6 +141,9 @@ include(cmake/setupCPM.cmake)
 
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
   include(CTest)
+  if(FINUFFT_BUILD_TESTS)
+    enable_testing()
+  endif()
   include(cmake/setupSphinx.cmake)
 endif()
 

docs/README

@@ -60,7 +60,12 @@ to install:
               https://github.com/matthew-brett/texext
   * python3 - since sphinx autodoc actually runs py to gen docstrings.
 
-Then (from this docs directory), run ``make latexpdf``
+Then it is possible to build docs locally in two ways. The cmake way or the make way
+
+The cmake way requires to run ``cmake --build [path to the build dir] --target finufft_sphinx``
+It creates a subfolder inside the build directory called ``finufft_sphinx`` containing the ``index.html``
+
+Alternatively (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
@@ -71,3 +76,4 @@ do not remove them.
 
 
 Alex Barnett, 2022/6/13.
+Marco Barbone, 2024/08/01

docs/devnotes.rst

@@ -4,14 +4,14 @@ Developer notes
 ===============
 
 * Developers needing to update/regenerate documentation in general, including our readthedocs website, see ``docs/README``. Developers changing MATLAB/octave interfaces or docs, also see ``matlab/README``. Please also see ``contributing.md`` for code style and git hook guidelines.
-* cmake supports sphinx generation one can do by ``cmake --build . --target finufft_sphinx``. This will crete a folder called finufft_sphinx in your build directory, opening ``index.html`` will preview the updated documentation.
-* cmake sphinx requires shpinx and texext to be installed in python
+
 * To update the version number, this needs to be done by hand in the following places:
 
   - ``CMakeLists.txt`` for cmake
   - ``docs/conf.py`` for sphinx
-  - ``python/finufft/setup.py`` for the python pkg version
-  - ``python/cufinufft/setup.py`` for the GPU python pkg version
+  - ``docs/install.rst`` cmake git tags
+  - ``python/finufft/finufft/__init__.py`` for the python pkg version
+  - ``python/cufinufft/cufinufft/__init__.py`` for the GPU python pkg version
   - ``include/finufft/defs.h`` for the debug>0 output
   - ``matlab/Contents.m`` for the MATLAB/Octave help
   - ``CHANGELOG``: don't forget to describe the new features and changes, folding lines at 80 chars.

docs/install.rst

@@ -12,20 +12,18 @@ a precompiled binary for your platform under Assets for various
 `releases <https://github.com/flatironinstitute/finufft/releases>`_.
 Please post an `Issue <https://github.com/flatironinstitute/finufft/issues>`_
 to document your installation problem.
-When using CMake, finufft requires no external dependencies except (c/c++ compilers supporting OpenMP).
+When using CMake, finufft requires no external dependencies except (c/c++ compilers supporting OpenMP and c++17).
 However GNU ``makefile`` assumes that FFTW (single/double) are installed.
+Python-only users can simply install via ``pip install finufft`` which downloads a generic binary from PyPI. Only if you prefer a custom compilation, see :ref:`below<install-python>`.
 
 .. note::
     finufft builds with no issues on Linux and MacOS using any compiler, in our experience GCC-13 gives best performance.
     On Windows MSVC works fine. The llvm toolchain included in Visual Studio does not seem to have OpenMP, it is possible to build single-threaded FINUFFT.
     The official windows LLVM distribution builds finufft with no issues but debug builds using sanitizers break.
-
-.. note::
-
     On windows finufft built with MSVC requires ``VCOMP140D.DLL`` which is part of the `Microsoft Visual C++ Redistributable <https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170>`_.
     It is likely to be already installed in your system.
     If the library is built with LLVM it requires ``libomp140.x86.64.dll``, more information `here <https://devblogs.microsoft.com/cppblog/improved-openmp-support-for-cpp-in-visual-studio/>`_.
-    Python-only users can simply install via ``pip install finufft`` which downloads a generic binary from PyPI. Only if you prefer a custom compilation, see :ref:`below<install-python>`.
+
 
 CMake CPM Based Installation
 ----------------------------
@@ -40,13 +38,13 @@ Then add the following to your ``CMakeLists.txt``:
 .. code-block:: cmake
 
   # short version
-  CPMAddPackage("gh:flatironinstitute/finufft@2.3")
+  CPMAddPackage("gh:flatironinstitute/finufft@2.2")
 
   # alternative in case custom options are needed
   CPMAddPackage(
     NAME             Finufft
     GIT_REPOSITORY   https://github.com/flatironinstitute/finufft.git
-    GIT_TAG          2.3
+    GIT_TAG          2.2
     GIT_SHALLOW      Yes
     GIT_PROGRESS     Yes
     EXCLUDE_FROM_ALL Yes
@@ -72,7 +70,7 @@ To do so add the following to your ``CMakeLists.txt``:
     FetchContent_Declare(
       finufft
       GIT_REPOSITORY https://github.com/flatironinstitute/finufft.git
-      GIT_TAG 2.3
+      GIT_TAG 2.2
     )
 
     # Make the content available
@@ -96,8 +94,8 @@ The basic quick download, building, and test is then:
   cd finufft
   cmake -S . -B build -DFINUFFT_BUILD_TESTS=ON --install-prefix /path/to/install
   cmake --build build
-  ctest
-  cmake --install .
+  ctest --test-dir build/
+  cmake --install build
 
 .. note::
 
@@ -127,11 +125,12 @@ Here are all our build options, showing name, explanatory text, and default valu
    :end-before: @cmake_opts_end
 
 .. note::
-    It is possible to choose between ``FFTW`` and `DUCC fft <https://gitlab.mpcdf.mpg.de/mtr/ducc>`_, Ducc fft is from the same author as `pocket fft <https://gitlab.mpcdf.mpg.de/mtr/pocketfft>`_.
+    It is possible to choose between ``FFTW`` and `ducc fft <https://gitlab.mpcdf.mpg.de/mtr/ducc>`_, ducc fft is from the same author as `pocket fft <https://gitlab.mpcdf.mpg.de/mtr/pocketfft>`_.
     Pocket fft is the fft used by `scipy <https://scipy.org/>`_.
-    An idea about ducc performance can be found in `this discussion <https://github.com/flatironinstitute/finufft/pull/463#issuecomment-2223988300>`_. We encourage the power user can try switching to ducc0 to see if it improves performance.
+    An idea about ducc performance can be found in `this discussion <https://github.com/flatironinstitute/finufft/pull/463#issuecomment-2223988300>`_. We encourage the power user to try switching to ducc to see if it improves performance.
 
 .. warning::
+    Note to the user, using --fast-math or /fp:fast can break finufft and its tests.
     On windows with msvc cl, ``ducc fft`` has to compile with ``/fp:fast``, otherwise some tests (run_finufft3d_test_float, run_finufft3dmany_test_float) may fail because of the resulting error is larger than the tolerance.
     On the other hand, finufft on windows with msvc cl should not compile with flag ``/fp:fast``, with ``/fp:fast`` the test run_dumbinputs_double will result in segfault, because /fp:fast makes values (NaN, +infinity, -infinity, -0.0) may not be propagated or behave strictly according to the IEEE-754 standard.
 
@@ -143,7 +142,7 @@ For example, to configure, build and test the development preset (which builds t
 
   cmake -S . -B build --preset dev # dev is the preset name
   cmake --build build
-  ctest
+  ctest --test-dir build/
 
 .. warning::
 
@@ -179,7 +178,7 @@ If there is an error in testing on what you consider a standard set-up,
 please file a detailed bug report as a New Issue at https://github.com/flatironinstitute/finufft/issues
 
 
-Quick linux GNU MAKE install instructions
+Quick linux GNU make install instructions
 --------------------------------
 
 Make sure you have packages ``fftw3`` and ``fftw3-dev`` (or their
@@ -460,7 +459,7 @@ section of ``mexopts.sh``.
 
 
 
-3) Windows GNU MAKE: tips for compiling
+3) Windows GNU make: tips for compiling
 -------------------------------
 
 We have users who have adjusted the makefile to work - at least to some extent - on Windows 10. If you are only interested in calling from Octave (which already comes with MinGW-w64 and FFTW), then we have been told this can be done very simply: from within Octave, go to the ``finufft`` directory and do ``system('make octave')``. You may have to tweak ``OCTAVE`` in your ``make.inc`` in a similar fashion to below.

docs/overview.src

@@ -7,7 +7,7 @@
     :width: 45%
 .. image:: spreadpic.png
     :width: 54%
-	    
+
 `FINUFFT <https://github.com/flatironinstitute/finufft>`_ is a library to compute efficiently the three most common types of nonuniform fast Fourier transform
 (NUFFT) to a specified precision, in one, two, or three dimensions,
 either on a multi-core shared-memory machine, or on a GPU.
@@ -18,7 +18,7 @@ has very simple interfaces to most major numerical languages
 but also has more advanced (vectorized and "guru") interfaces that
 allow multiple strength vectors and the reuse of FFT plans.
 The CPU library
-is written in C++ (with limited use of ++ features), OpenMP, and calls
+is written in C++, OpenMP, and calls
 `FFTW <http://www.fftw.org>`_.
 It has been developed since 2017 at the `Center for Computational Mathematics
 <https://www.simonsfoundation.org/flatiron/center-for-computational-mathematics/>`_ at the `Flatiron Institute <https://www.simonsfoundation.org/flatiron>`_,
@@ -158,4 +158,3 @@ $a_{kj} = e^{ik x_j}$, then use BLAS3 (eg ``ZGEMM``) to compute $F = AC$,
 where each column of $F$ and $C$ is a new instance of :eq:`1d1`.
 If you have very many columns this can be competitive with a NUFFT
 even for $M$ and $N$ up to $10^4$, because BLAS3 is so fast.
-