fortran/2/pm__mathLog1p_8F90_source.html

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

!!!!                                                                                                                            !!!!

!!!!    ParaMonte: Parallel Monte Carlo and Machine Learning Library.                                                           !!!!

!!!!                                                                                                                            !!!!

!!!!    Copyright (C) 2012-present, The Computational Data Science Lab                                                          !!!!

!!!!                                                                                                                            !!!!

!!!!    This file is part of the ParaMonte library.                                                                             !!!!

!!!!                                                                                                                            !!!!

!!!!    LICENSE                                                                                                                 !!!!

!!!!                                                                                                                            !!!!

!!!!       https://github.com/cdslaborg/paramonte/blob/main/LICENSE.md                                                          !!!!

!!!!                                                                                                                            !!!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


module pm_mathLog1p


    use pm_kind, only: SK, IK, LK

    use pm_control, only: selection_type, selection


    implicit none


    character(*, SK), parameter :: MODULE_NAME = "@pm_mathLog1p"


!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


    !                               INTERNAL NOTE: Based on the benchmark results,

    !                               there does not appear to exist any performance benefits in having a control optional argument.

    !                               As such, it is removed from the interface.

    !   \param      control     :   The input scalar object that can be,

    !                               <ol>

    !                                   <li>    the constant [selection](@ref pm_control::selection) or equivalently,

    !                                           an object of type [selection_type](@ref pm_control::selection_type).<br>

    !                                           Specifying this option enables the runtime checks for underflow occurrence via branching and dynamic dispatch.<br>

    !                                           Enabling this option can aid runtime efficiency when the `x` ratio is expected to cause underflow.<br>

    !                                           In such cases, the logarithm can be avoided if `control =` [selection](@ref pm_control::selection), leading

    !                                           to better runtime efficiency since logarithm is highly expensive (on the order of ~200 CPU cycles).<br>

    !                                           See [the relevant benchmark here](#benchmark-getLog1p).<br>

    !                               </ol>

    !                               The presence of this argument is merely for compile-time resolution of the procedures of this generic interface.<br>

    !                               (**optional**. If missing, a sequence control flow will be assumed without dynamic dispatch.)

    !  \benchmarks

    !

    !  \benchmark{getLog1p, The effects of `control` on runtime efficiency}

    !      The following program compares the runtime performance of [getLog1p](@ref pm_mathLog1p::getLog1p)

    !      algorithm with and without checking for underflows.

    !  \include{lineno} benchmark/pm_mathLog1p/getLog1p/main.F90

    !  \compilefb{getLog1p}

    !  \postprocb{getLog1p}

    !  \include{lineno} benchmark/pm_mathLog1p/getLog1p/main.py

    !  \visb{getLog1p}

    !  \image html benchmark/pm_mathLog1p/getLog1p/benchmark.getLog1p.runtime.png width=1000

    !  \image html benchmark/pm_mathLog1p/getLog1p/benchmark.getLog1p.runtime.ratio.png width=1000

    !  \moralb{getLog1p}

    !      -#  If the input value `x` is known to be frequently `< tiny(x)` or `> epsilon(x)` then it is generally beneficial

    !          to call the interface with `control` argument set to [selection](@ref pm_control::selection).<br>

    interface getLog1p


    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


#if CK5_ENABLED

    PURE elemental module function getLog1pSeq_CK5(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_CK5

#endif

        use pm_kind, only: CKG => CK5

        complex(CKG)        , intent(in)    :: x

        complex(CKG)                        :: log1p

    end function

#endif


#if CK4_ENABLED

    PURE elemental module function getLog1pSeq_CK4(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_CK4

#endif

        use pm_kind, only: CKG => CK4

        complex(CKG), intent(in)    :: x

        complex(CKG)                :: log1p

    end function

#endif


#if CK3_ENABLED

    PURE elemental module function getLog1pSeq_CK3(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_CK3

#endif

        use pm_kind, only: CKG => CK3

        complex(CKG), intent(in)    :: x

        complex(CKG)                :: log1p

    end function

#endif


#if CK2_ENABLED

    PURE elemental module function getLog1pSeq_CK2(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_CK2

#endif

        use pm_kind, only: CKG => CK2

        complex(CKG), intent(in)    :: x

        complex(CKG)                :: log1p

    end function

#endif


#if CK1_ENABLED

    PURE elemental module function getLog1pSeq_CK1(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_CK1

#endif

        use pm_kind, only: CKG => CK1

        complex(CKG), intent(in)    :: x

        complex(CKG)                :: log1p

    end function

#endif


    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


#if RK5_ENABLED

    PURE elemental module function getLog1pSeq_RK5(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_RK5

#endif

        use pm_kind, only: RKG => RK5

        real(RKG)   , intent(in)    :: x

        real(RKG)                   :: log1p

    end function

#endif


#if RK4_ENABLED

    PURE elemental module function getLog1pSeq_RK4(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_RK4

#endif

        use pm_kind, only: RKG => RK4

        real(RKG)   , intent(in)    :: x

        real(RKG)                   :: log1p

    end function

#endif


#if RK3_ENABLED

    PURE elemental module function getLog1pSeq_RK3(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_RK3

#endif

        use pm_kind, only: RKG => RK3

        real(RKG)   , intent(in)    :: x

        real(RKG)                   :: log1p

    end function

#endif


#if RK2_ENABLED

    PURE elemental module function getLog1pSeq_RK2(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_RK2

#endif

        use pm_kind, only: RKG => RK2

        real(RKG)   , intent(in)    :: x

        real(RKG)                   :: log1p

    end function

#endif


#if RK1_ENABLED

    PURE elemental module function getLog1pSeq_RK1(x) result(log1p)

#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSeq_RK1

#endif

        use pm_kind, only: RKG => RK1

        real(RKG)   , intent(in)    :: x

        real(RKG)                   :: log1p

    end function

#endif


!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!

!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!

!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!

!#if CK5_ENABLED

!    PURE elemental module function getLog1pSel_CK5(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_CK5

!#endif

!        use pm_kind, only: CKG => CK5

!        type(selection_type), intent(in)    :: control

!        complex(CKG)        , intent(in)    :: x

!        complex(CKG)                        :: log1p

!    end function

!#endif

!

!#if CK4_ENABLED

!    PURE elemental module function getLog1pSel_CK4(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_CK4

!#endif

!        use pm_kind, only: CKG => CK4

!        type(selection_type), intent(in)    :: control

!        complex(CKG)        , intent(in)    :: x

!        complex(CKG)                        :: log1p

!    end function

!#endif

!

!#if CK3_ENABLED

!    PURE elemental module function getLog1pSel_CK3(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_CK3

!#endif

!        use pm_kind, only: CKG => CK3

!        type(selection_type), intent(in)    :: control

!        complex(CKG)        , intent(in)    :: x

!        complex(CKG)                        :: log1p

!    end function

!#endif

!

!#if CK2_ENABLED

!    PURE elemental module function getLog1pSel_CK2(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_CK2

!#endif

!        use pm_kind, only: CKG => CK2

!        type(selection_type), intent(in)    :: control

!        complex(CKG)        , intent(in)    :: x

!        complex(CKG)                        :: log1p

!    end function

!#endif

!

!#if CK1_ENABLED

!    PURE elemental module function getLog1pSel_CK1(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_CK1

!#endif

!        use pm_kind, only: CKG => CK1

!        type(selection_type), intent(in)    :: control

!        complex(CKG)        , intent(in)    :: x

!        complex(CKG)                        :: log1p

!    end function

!#endif

!

!    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

!

!#if RK5_ENABLED

!    PURE elemental module function getLog1pSel_RK5(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_RK5

!#endif

!        use pm_kind, only: RKG => RK5

!        type(selection_type), intent(in)    :: control

!        real(RKG)           , intent(in)    :: x

!        real(RKG)                           :: log1p

!    end function

!#endif

!

!#if RK4_ENABLED

!    PURE elemental module function getLog1pSel_RK4(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_RK4

!#endif

!        use pm_kind, only: RKG => RK4

!        type(selection_type), intent(in)    :: control

!        real(RKG)           , intent(in)    :: x

!        real(RKG)                           :: log1p

!    end function

!#endif

!

!#if RK3_ENABLED

!    PURE elemental module function getLog1pSel_RK3(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_RK3

!#endif

!        use pm_kind, only: RKG => RK3

!        type(selection_type), intent(in)    :: control

!        real(RKG)           , intent(in)    :: x

!        real(RKG)                           :: log1p

!    end function

!#endif

!

!#if RK2_ENABLED

!    PURE elemental module function getLog1pSel_RK2(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_RK2

!#endif

!        use pm_kind, only: RKG => RK2

!        type(selection_type), intent(in)    :: control

!        real(RKG)           , intent(in)    :: x

!        real(RKG)                           :: log1p

!    end function

!#endif

!

!#if RK1_ENABLED

!    PURE elemental module function getLog1pSel_RK1(x, control) result(log1p)

!#if __INTEL_COMPILER && DLL_ENABLED && (_WIN32 || _WIN64)

!        !DEC$ ATTRIBUTES DLLEXPORT :: getLog1pSel_RK1

!#endif

!        use pm_kind, only: RKG => RK1

!        type(selection_type), intent(in)    :: control

!        real(RKG)           , intent(in)    :: x

!        real(RKG)                           :: log1p

!    end function

!#endif


    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

    !%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


    end interface


!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


end module pm_mathLog1p ! LCOV_EXCL_LINE

pm_mathLog1p::getLog1p
Generate and return the expression log(1 + x) robustly (without numerical underflow).
Definition: pm_mathLog1p.F90:136

pm_control
This module contains abstract and concrete derived types that are required for compile-time resolutio...
Definition: pm_control.F90:45

pm_control::MODULE_NAME
character(*, SK), parameter MODULE_NAME
Definition: pm_control.F90:51

pm_control::selection
type(selection_type), parameter selection
This is a scalar parameter object of type selection_type that is exclusively used to request selectio...
Definition: pm_control.F90:320

pm_kind
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268

pm_kind::RK5
integer, parameter RK5
Definition: pm_kind.F90:478

pm_kind::RK4
integer, parameter RK4
Definition: pm_kind.F90:489

pm_kind::RK2
integer, parameter RK2
Definition: pm_kind.F90:511

pm_kind::CK1
integer, parameter CK1
Definition: pm_kind.F90:464

pm_kind::RK3
integer, parameter RK3
Definition: pm_kind.F90:500

pm_kind::LK
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541

pm_kind::CK5
integer, parameter CK5
Definition: pm_kind.F90:420

pm_kind::CK4
integer, parameter CK4
Definition: pm_kind.F90:431

pm_kind::CK2
integer, parameter CK2
Definition: pm_kind.F90:453

pm_kind::CK3
integer, parameter CK3
Definition: pm_kind.F90:442

pm_kind::IK
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
Definition: pm_kind.F90:540

pm_kind::SK
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
Definition: pm_kind.F90:539

pm_kind::RK1
integer, parameter RK1
Definition: pm_kind.F90:522

pm_mathLog1p
This module contains procedures and generic interfaces for computing log(1 + x) more precisely for ti...
Definition: pm_mathLog1p.F90:41

pm_control::selection_type
This is a concrete derived type whose instances are exclusively used to request selection control flo...
Definition: pm_control.F90:295