sparkmath.h

Go to the documentation of this file.

/////////////////////////////////////////////////////////////////////////////////////////
/// \file  sparkmath.h 
/// \brief Math functions
///
/// Declares constant variables :
/// - SPARK::TINY
/// - SPARK::SQRT_UROUND
///
/// Declares functions :
/// - SPARK::min()
/// - SPARK::max()
/// - SPARK::sign()
/// - SPARK::abs()
/// - SPARK::InfiniteOrNaN()
/// - SPARK::log2()
///
/////////////////////////////////////////////////////////////////////////////////////////
///
/// \author  Dimitri Curtil (LBNL/SRG)
/// \date    May 21, 2002
///
/////////////////////////////////////////////////////////////////////////////////////////
/// \attention
/// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n
/// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA .
///   PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED.
///
/////////////////////////////////////////////////////////////////////////////////////////


#if !defined(__SPARKMATH_H__)
#define __SPARKMATH_H__


// Gets rid of warning messages about dll-interface for private data member
// Message shows typically with std classes, e.g., std::string
#pragma warning(disable:4251)


#include <cmath>        // for sqrt, fabs
#include <limits>

#include "compat.h"     // for UROUND



/////////////////////////////////////////////////////////////////////////////////////////
namespace SPARK {

        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Constant Declaration 
        //@{

        /// Considered essentially as zero in solver (e.g., used to detect singularity)
        const double TINY = 1.0E-30;

        /// Square root of the unit round-off error
        const double SQRT_UROUND = sqrt(UROUND); 

        //@}
        /////////////////////////////////////////////////////////////////////////////////////

        
        ///////////////////////////
        // Function declarations //
        ///////////////////////////

        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Functions used in HVAC toolkit 
        //@{

        /// Returns the absolute value of x
        ///
        /// \warning Use SPARK::abs() to avoid possible confusion with abs(), fabs()
        ///          defined in the system include files <math.h> or <cmath>.
        ///          The abs() function has the prototype int abs(int x) which forces 
        ///          a type conversion from double to int. Usually, this is not the 
        ///          desired effect and it is a tricky bug hard to detect.
        ///          Therefore, we recommend using SPARK::abs() to avoid any confusion.
        inline API_DECLSPEC(double) abs(double x) { return fabs(x); }

        /// Returns the min of two variables that can be compared using <
        ///
        /// \warning Use SPARK::min() to avoid possible confusion with std::min()
        inline API_DECLSPEC(double) min(double x, double y) { return (x < y ? x : y); }
        
        /// Returns the max of two variables that can be compared using >
        ///
        /// \warning Use SPARK::max() to avoid possible confusion with std::max()
        inline API_DECLSPEC(double) max(double x, double y) { return (x > y ? x : y); }
        
        /// Returns the +1.0 if \c x is positive, -1.0 otherwise
        inline API_DECLSPEC(double) sign(double x) { return (x < 0.0 ? -1.0 : 1.0); }

        /// Returns the \c a if \c b is strictly positive, \c -a otherwise
        inline API_DECLSPEC(double) sign(double retval, double test) { return (test > 0.0 ? fabs(retval) : -fabs(retval)); }

        /// Returns the log in base 2 of the double x
        ///
        /// \note Use log() and log10() declared in <cmath> to compute the logarithms in base 
        ///       e and 10 respectively
        inline API_DECLSPEC(double) log2(double x) { return (1.4426950408889634074*log(x)); }
        
        //@}
        /////////////////////////////////////////////////////////////////////////////////////
        
        
        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Functions used inside the solver code
        //@{

        /// Codes returned by SPARK::InfiniteOrNaN() function
        enum NumericalValueTypes { 
                NumericalValueType_VALID        =  0,  ///< numerical value is valid
                NumericalValueType_INF          =  1,  ///< numerical value is positive infinite
                NumericalValueType_NAN          =  2   ///< numerical value is not a number
        };


        /// \brief Checks whether the floating-point number \c scalar is infinite or NaN or a valid numerical scalar
    /// 
    /// \return  Numerical type as enum NumericalValueTypes
    /// \param   scalar   floating-point value of type T to check
    ///
    template<typename T>
    API_DECLSPEC(NumericalValueTypes) InfiniteOrNaN(T scalar)
    {
        // NaN Floating-Point Behavior (from MS website)
        // NaN comparisons have changed to better support IEEE 754.
        // ·    NaN equality rules have changed: NaN == NaN tests now return false, NaN != NaN tests now return true.
        // ·    NaN ordering tests always return false: NaN [<, <=, >, >=] [any number] will be false.
        // For more information, see the section "Not a Number (NAN)" in the topic "C++ Compiler, Linker, and C++ Language" in the Visual C++ online documentation.

        // Some compilers also implement the following non-standard functions: 
        //   #include <math.h>
        //   double nan(const char *tagp); 
        //   float nanf(const char *tagp); 
        //   long double nanl(const char *tagp);
        //   int _isnan(double );  
        //       => does not catch a quiet NaN though 

        /// \bug g++ 3.2 does not like the definition of INFINITY from std::numeric_limits<T>::max() !!
        // const T INFINITY = std::numeric_limits<T>::max();

        static T ZERO(0);  

        // Probably NaN according to standard IEEE 754.
        // This might also catch the positive inifinte and negative infinite cases!
        if (scalar != scalar || !(scalar >= scalar) || !(scalar <= scalar)) { 
                    return SPARK::NumericalValueType_NAN;
            }
        else if ( (scalar < ZERO ? -scalar : scalar) >= std::numeric_limits<T>::max() ) {
                    return SPARK::NumericalValueType_INF;
            }
            else {
                    return SPARK::NumericalValueType_VALID;
            }
    }

        //@}
        /////////////////////////////////////////////////////////////////////////////////////
        

}; // namespace SPARK
/////////////////////////////////////////////////////////////////////////////////////////


#endif // __SPARKMATH_H__

---