Merge pull request #41 from FastNFT/release-0.2

Release 0.2.2

Author: wahls

.gitattributes

@@ -0,0 +1 @@
+*.inc linguist-language=C

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.2.2] -- 2018-12-13
+
+### Added
+
+- The routine fnft_nsev_inverse_XI now raises an error if D<2 to avoid division by zero
+- A .gitattribute file to correct incorrect language detection on GitHub
+
+### Fixed
+
+- CMake failed under Windows due to an incomplete install command in CMakeLists.txt
+- Removed incorrect "-SHELL=cmd" parameter for CMake from Windows build instructions
+- Documentation for fnft_nsev_inverse now states that D should be a positive power of two
+- Documentation for fnft_nsev and fnft_nsep now states that passing *K_ptr==0 and *M_ptr==0 is not sufficient in order to completely skip the computation of the corresponding spectra
+- Reformatted changelog for 0.1.1
+
 ## [0.2.1] -- 2018-09-28
 
 ### Fixed
@@ -37,14 +52,11 @@
 
 ## [0.1.1] -- 2018-05-14
 
-### Added
+### Fixed
 
 - Mex files now compile also with Matlab R2018a
-
-### Changed
-
-- Fixed: Several potential memory violations in fnft_nsev, poly_chirpz and nsev_testcases
-- Fixed: Some return codes in fnft_nsep had not been checked
-- Fixed: misc_merge did not work correctly for empty input vectors
-- Fixed: The continuous spectrum in mex_fnft_nsev_example.m was plotted over t, not xi
-- Fixed: A superfluous parameter kappa was given in the documentation of mex_fnft_kdvv
+- Several potential memory violations in fnft_nsev, poly_chirpz and nsev_testcases
+- Some return codes in fnft_nsep had not been checked
+- misc_merge did not work correctly for empty input vectors
+- The continuous spectrum in mex_fnft_nsev_example.m was plotted over t, not xi
+- A superfluous parameter kappa was given in the documentation of mex_fnft_kdvv

CMakeLists.txt

@@ -21,7 +21,7 @@ project(fnft C)
 
 set(FNFT_VERSION_MAJOR 0)
 set(FNFT_VERSION_MINOR 2)
-set(FNFT_VERSION_PATCH 1)
+set(FNFT_VERSION_PATCH 2)
 set(FNFT_VERSION_SUFFIX "") # should not be longer than FNFT_SUFFIX_MAXLEN
 set(FNFT_VERSION ${FNFT_VERSION_MAJOR}.${FNFT_VERSION_MINOR}.${FNFT_VERSION_PATCH}${FNFT_VERSION_SUFFIX})
 
@@ -172,8 +172,8 @@ target_link_libraries(fnft ${FFTW3_LIB})
 file(GLOB PUBLIC_HEADERS "include/*.h")
 set_target_properties(fnft PROPERTIES VERSION ${FNFT_VERSION} SOVERSION ${FNFT_VERSION_MAJOR} LIBRARY_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/lib" PUBLIC_HEADER "${PUBLIC_HEADERS}")
 
-# installation under Linux
-install(TARGETS fnft LIBRARY DESTINATION lib PUBLIC_HEADER DESTINATION include)
+# installation (under Windows, DLL's are considered runtime, while DLL import libraries are considered ARCHIVE)
+install(TARGETS fnft LIBRARY DESTINATION lib PUBLIC_HEADER DESTINATION include RUNTIME DESTINATION lib ARCHIVE DESTINATION lib)
 
 # generate examples
 foreach (srcfile ${EXAMPLE_SOURCES})

INSTALL.md

@@ -66,7 +66,7 @@ To uninstall FNFT, run the commands
 
 ## Building under Windows
 
-The following instructions have been tested under Windows 7/8/10. A simple way to build FNFT is via the [Scoop](http://scoop.sh/) packet manager. Make sure that [PowerShell 3](https://docs.microsoft.com/en-us/powershell/scripting/setup/installing-windows-powershell?view=powershell-6) is available. Run the command
+The following instructions have been tested under Windows 7/8/10. A simple way to build FNFT is via the [Scoop](http://scoop.sh/) packet manager. Make sure that [PowerShell 3](https://docs.microsoft.com/en-us/powershell/scripting/setup/installing-windows-powershell?view=powershell-6) is available. (We recommend _not_ to run the 32 bit version "PowerShell (x86)" on a 64 bit machine unless there are specific reasons for it.) Run the command
 
     powershell.exe -ExecutionPolicy RemoteSigned
 
@@ -90,7 +90,7 @@ Create a build directory and run cmake there
 
     mkdir build
     cd build
-    cmake .. -SHELL=cmd -G"MinGW Makefiles"
+    cmake .. -G"MinGW Makefiles"
 
 Build the library:
 
@@ -100,8 +100,7 @@ Run the tests:
 
     mingw32-make -j4 test
 
-_Note:_ If MATLAB is installed, the MATLAB interface should have been built
-automatically. It can be found in the 'matlab' folder. Please copy the libfnft... dll file and the mex_... mexw... files manually from the 'build' into the 'matlab' folder.
+_Note:_ If MATLAB is installed, the MATLAB interface should have been built automatically. It can be found in the 'matlab' folder. Please copy the libfnft... dll file and the mex_... mexw... files manually from the 'build' into the 'matlab' folder.
 
 ## Building under MacOS
 

include/fnft_nsep.h

@@ -161,6 +161,8 @@ fnft_nsep_opts_t fnft_nsep_default_opts();
  *  points in the main spectrum. If the length of the array main_spec was not
  *  sufficient to store all of the detected points in the main spectrum, a
  *  warning is printed and as many points as possible are returned instead.
+ *  Note that in order to skip the computation of the main spectrum completely,
+ *  it is not sufficient to pass *K_ptr==NULL. Instead, pass main_spec==NULL.
  * @param[out] main_spec Array. Upon return, the routine has stored the detected
  *  main specrum points (i.e., the points for which the trace of the monodromy
  *  matrix is either +2 or -2) in the first *K_ptr entries of this array.
@@ -172,7 +174,9 @@ fnft_nsep_opts_t fnft_nsep_default_opts();
  *  points in the auxiliary spectrum. If the length of the array aux_spec was
  *  not sufficient to store all of the detected points in the auxiliary
  *  spectrum, a warning is printed and as many points as possible are returned
- *  instead.
+ *  instead. Note that in order to skip the computation of the auxiliary
+ *  spectrum completely, it is not sufficient to pass *M_ptr==NULL. Instead,
+ *  pass aux_spec==NULL.
  * @param[out] aux_spec Array. Upon return, the routine has stored the detected
  *  auxiliary specrum points (i.e., the points for which the upper right
  *  element of the monodromy matrix is zero) in the first *M_ptr entries of

include/fnft_nsev.h

@@ -261,7 +261,9 @@ FNFT_UINT fnft_nsev_max_K(const FNFT_UINT D,
  *  bound_states. Upon return, *K_ptr contains the number of actually detected
  *  bound states. If the length of the array bound_states was not sufficient
  *  to store all of the detected bound states, a warning is printed and as many
- *  bound states as possible are returned instead.
+ *  bound states as possible are returned instead. Note that in order to skip
+ *  the computation of the bound states completely, it is not sufficient to pass
+ *  *K_ptr==0. Instead, one needs to pass bound_states==NULL.
  * @param[out] bound_states Array. Upon return, the routine has stored the detected
  *  bound states (aka eigenvalues) in the first *K_ptr entries of this array.
  *  If NULL is passed instead, the discrete spectrum will not be computed.

include/fnft_nsev_inverse.h

@@ -91,11 +91,11 @@ typedef enum {
  *  The maximum number of iterations can be controlled using the max_iter
  *  field in \link fnft_nsev_inverse_opts_t \endlink. Requires M=D. Defocusing
  *  case only.\n\n
- *  fnft_nsev_inverse_csmethod_USE_SEED_POTENTIAL_INSTEAD: This algorithm 
- *  adds discrete spectrum over the given seed potential. It uses Boffetta and Osborne 
+ *  fnft_nsev_inverse_csmethod_USE_SEED_POTENTIAL_INSTEAD: This algorithm
+ *  adds discrete spectrum over the given seed potential. It uses Boffetta and Osborne
  * (<a href="http://dx.doi.org/10.1016/0021-9991(92)90370-E">J. Comput. Physics 1992 </a>)
  *  method to compute the intermediate eigenfunctions and then uses the classical
- *  Darboux transform in <a href="https://doi.org/10.1007/BF02015338">[Lin, 
+ *  Darboux transform in <a href="https://doi.org/10.1007/BF02015338">[Lin,
  *  J. Acta Mathematicae Applicatae Sinica (1990) 6: 308]</a> to add the discrete spectrum.
  */
 typedef enum {
@@ -176,7 +176,7 @@ fnft_nsev_inverse_opts_t fnft_nsev_inverse_default_opts();
  * the grid that has to be used when providing a continuous spectrum
  * to \link fnft_nsev_inverse \endlink.
  *
- * @param[in] D Number of samples of the to be generated signal q.
+ * @param[in] D Number of samples of the to be generated signal q. Should be >=2.
  * @param[in] T Array of length two. Contains the desired location
  *  of the first and last sample of the signal q.
  * @param[in] M Number of samples in the nonlinear frequency domain.
@@ -238,11 +238,12 @@ FNFT_INT fnft_nsev_inverse_XI(
  *  whether the user adheres to this requirement.
  * @param[in] K Number of discrete spectrum points.
  * @param[in] bound_states Complex array of length K. Complex roots of
- * \f$ a(\xi) \f$ in the upper half of the complex-plane.
+ *  \f$ a(\xi) \f$ in the upper half of the complex-plane.
  * @param[in] normconsts_or_residues Complex array of length K. Values of
- * either the norming constants \f$ b(\xi) \f$ or the residues
- * \f$ \frac{b(\xi)}{\partial{a(\xi)}/\partial{\xi}}\f$ at the values bound_states.
- * @param[in] D Number of samples of the to be generated signal q.
+ *  either the norming constants \f$ b(\xi) \f$ or the residues
+ *  \f$ \frac{b(\xi)}{\partial{a(\xi)}/\partial{\xi}}\f$ at the values bound_states.
+ * @param[in] D Number of samples of the to be generated signal q. Should be a
+ *  positive power of two.
  * @param[out] q Array of length D. Is filled with samples
  *  \f$ q(t_n) \f$, where \f$ t_n = T[0] + n(T[1]-T[0])/(D-1) \f$
  *  and \f$n=0,1,\dots,D-1\f$, of the to-be-generated signal in ascending order

src/fnft_nsev_inverse.c

@@ -50,6 +50,8 @@ INT fnft_nsev_inverse_XI(const UINT D, REAL const * const T,
         const UINT M, REAL * const XI,
         const nse_discretization_t discretization)
 {
+    if (D<2)
+        return E_INVALID_ARGUMENT(D);
     if (M == 0)
         return E_INVALID_ARGUMENT(M);
     if (XI == NULL)
@@ -794,7 +796,7 @@ static INT add_discrete_spectrum(
                 }
             }
             norm_consts[i]=(norm_consts[i]/bnd_states_diff[i])*tmp;
-        }        
+        }
     }
 
     // In absence of contspec some tricks can be used to