fftwEnvironment.hpp

Go to the documentation of this file.

/** \file fftwEnvironment.hpp
 * \brief Declares and defines the fftwEnvironment manager
 * \ingroup ft_files
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 */
 
//***********************************************************************//
// Copyright 2015-2015 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef fftwEnvironment_hpp
#define fftwEnvironment_hpp
 
#include <string>
 
#include "../../sys/environment.hpp"
 
#include "fftwTemplates.hpp"
 
namespace mx
{
namespace math
{
namespace ft
{
 
/** \addtogroup fftw_env
 
mxlib will manage the FFTW environment for you, which really means importing and exporting
wisdom and cleaning up memory.  This can be done in a simple way using
\ref mx::math::ft::fftwEnvironment.
To make the best use of this, create a directory to store FFTW wisdom.  The typical choice is
`$(HOME)/.fftw`
 
Then add the environment variable to your bash profile (i.e. in `.bash_profile` or `.bash_aliases`) as so
\verbatim
export MXFFTW_WISDOM=/path/to/.fftw
\endverbatim
 
Using this facility requires only that you create an object of type \ref mx::math::ft::fftwEnvironment
at the beginning of the program for the real floating point type you are using. E.g.:
\code
 
   #include <mx/fft/fftwEnvironment.hpp>
 
   int main()
   {
      typedef double realT;
      mx::math::ft::fftwEnvironment<realT> fftwEnv;
 
      //do stuff . . .
 
      return 0;
   }
   \endcode
 
See the documentation for \ref mx::math::ft::fftwEnvironment for details.
 
*/
 
/// Return a string corresponding the fftw real floating point type.
/** This is used for wisdom filenames.
 *
 * \tparam realT the real floating point type.
 *
 * \ingroup fftw_env
 */
template <typename realT>
std::string fftw_typename();
 
template <>
std::string fftw_typename<float>();
 
template <>
std::string fftw_typename<double>();
 
template <>
std::string fftw_typename<long double>();
 
#ifdef HASQUAD
template <>
std::string fftw_typename<__float128>();
#endif
 
/// Create the mxlib standard wisdom filename for the type.
/** Looks for the environment variable MXFFTW_WISDOM.  If not found, then pwd "./" is used.
 *
 * \tparam realT is the real floating point type.
 *
 * \ingroup fftw_env
 */
template <typename realT>
std::string fftw_wisdom_filename()
{
    std::string path = sys::getEnv( "MXFFTW_WISDOM" );
    std::string sub = "fftw_wisdom.";
 
    if( path == "" )
    {
        path = ".";
        sub = ".fftw_wisdom.";
    }
 
    std::string filename = path + "/" + sub + fftw_typename<realT>();
 
    return filename;
}
 
/// Manage the FFTW environment and wisdom using RAII
/** This class manages the FFTW environment.  On construction, wisdom is imported from the
  * mxlib standard location, and if threads are used threading is initialized and planners are made thread safe.
  *
  * \note the fftw docs recommend against using fftw_make_planner_thread_safe.  It does seem to play poorly with omp.
  *
  * On destruction, wisdom is exported and the fftw_cleanup[_threads] function is called.
  *
  * Typically, an object of this type should be created in the main function.  Nothing else needs to be done with it,
  * as it will be destructed on program termination. Example:
   \code
 
   #include <mx/fft/fftwEnvironment.hpp>
 
   int main()
   {
      typedef double realT;
      mx::math::ft::fftwEnvironment<realT> fftwEnv;
 
      //do stuff . . .
 
      return 0;
   }
   \endcode
  * Note that there is no need to explicitly destroy the object fftwEnv.
  *
  * \ingroup fftw_env
  */
template <typename realT, bool threads = false>
struct fftwEnvironment
{
    /// Constructor
    explicit fftwEnvironment(unsigned nThreads = 0 /**< [in] [optional] the number of threads to use.  This can be changed any time by the program by calling \ref fftw_plan_with_nthreads() */)
    {
        static_cast<void>( nThreads );
        errno = 0;
        int rv = fftw_import_wisdom_from_filename<realT>( fftw_wisdom_filename<realT>().c_str() );
    }
 
    /// Destructor
    ~fftwEnvironment()
    {
        errno = 0;
        int rv = fftw_export_wisdom_to_filename<realT>( fftw_wisdom_filename<realT>().c_str() );
 
        fftw_cleanup<realT>();
    }
};
 
// Partial specialization for threads.
template <typename realT>
struct fftwEnvironment<realT, true>
{
    /// Constructor
    explicit fftwEnvironment(unsigned nThreads = 1 /**< [in] [optional] the number of threads to use.
                                                   This can be changed any time by the program by calling
                                                   \ref fftw_plan_with_nthreads() */)
    {
        fftw_make_planner_thread_safe<realT>();
 
        if( nThreads == 0 )
        {
            nThreads = 1; // Just to be safe, 1 disables threads but the fftw docs don't say what happens for 0.
        }
 
        fftw_plan_with_nthreads<realT>( nThreads );
 
        fftw_import_wisdom_from_filename<realT>( fftw_wisdom_filename<realT>().c_str() );
    }
 
    /// Destructor
    ~fftwEnvironment()
    {
        fftw_export_wisdom_to_filename<realT>( fftw_wisdom_filename<realT>().c_str() );
 
        fftw_cleanup_threads<realT>();
    }
};
 
} // namespace ft
} // namespace math
} // namespace mx
 
#endif // fftwEnvironment_hpp