********************
Elementary Functions
********************

GNSTLIB includes exponential, logarithmic, powers, trigonometric and hyperbolic functions. These elementary functions are included in the following header file:

.. code-block:: C++

   #include <gnstlib_basic.hpp>

======================
Exponentials functions
======================

GNSTLIB::exp
------------

.. cpp:function:: double exp(const double x)

   Computes the exponential function :math:`e^x` for real :math:`x`.
   The exponential function is defined by 

   .. math::
      e^x = \sum_{k=0}^{\infty} \frac{x^k}{k!}.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

   #. **Example:**

      .. code-block:: C++

         #include <iomanip>
         #include <iostream>

         #include <gnstlib_basic.hpp>

         void test_exp()
         {
            double x = 3.2;
            double result = GNSTLIB::exp(x);
            std::cout << std::setprecision(16) << result << std::endl;
         }

.. cpp:function:: std::complex<double> exp(const std::complex<double> z)

   Computes the exponential function :math:`e^z` for complex :math:`z`.
   The exponential function for complex argument is defined by the above power series and satisfies the following functional relation

   .. math::
      e^{(x + iy)} = e^x(\cos(y) + i \sin(y)).
   
   #. **Arguments:**

      * **z**: (complex) - *argument*.

   #. **Example:**

      .. code-block:: C++

         #include <complex>
         #include <iomanip>
         #include <iostream>

         #include <gnstlib_basic.hpp>

         void test_exp()
         {
            std::complex<double> z = std::complex<double>(3.2, 2.1);
            std::complex<double> result = GNSTLIB::exp(z);
            std::cout << std::setprecision(16) << result << std::endl;
         }


GNSTLIB::exp2
-------------

.. cpp:function:: double exp2(const double x)

   Computes :math:`2^x` for real power :math:`x`.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::exp10
--------------

.. cpp:function:: double exp10(const double x)

   Computes :math:`10^x` for real power :math:`x`.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::expm1
--------------

.. cpp:function:: double expm1(const double x)

   Computes :math:`e^x - 1` for real power :math:`x`. The function is more accurate than evaluating ``exp(x)-1.0`` for :math:`x` close to 0.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::expm1x
---------------

.. cpp:function:: double expm1x(const double x)

   Computes :math:`\frac{e^x - 1}{x}` for real :math:`x`. The function is more accurate than evaluating ``(exp(x)-1.0)/x`` for :math:`x` close to 0.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::expm1mx
----------------

.. cpp:function:: double expm1mx(const double x)

   Computes :math:`\frac{2(e^x - 1)}{x^2}` for real :math:`x`. The function is more accurate than evaluating ``2.0*(exp(x)-1.0-x)/(x*x)`` for :math:`x` close to 0.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.

=====================
Logarithmic functions
=====================

GNSTLIB::log
------------

.. cpp:function:: double log(const double x)

   Computes the natural logarithm :math:`\log(x)` for real :math:`x \ge 0`. 

   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` 0.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. The natural logarithm is real for **x** > 0.0. For **x** :math:`=` 0.0, :math:`-\infty` is returned. If **x** < 0.0 the result is complex and it is returned as NaN.

.. cpp:function:: std::complex<double> log(const std::complex<double> z)

   Computes the natural logarithm :math:`\log(z)` for complex :math:`z` or when :math:`z` is real and :math:`z <0`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.


GNSTLIB::log2
-------------

.. cpp:function:: double log2(const double x)

   Computes the binary (base-2) logarithm :math:`\mathrm{log}_2(x)` for real :math:`x \ge 0`.

   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` 0.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. The result is real for **x** > 0.0. For **x** :math:`=` 0.0, :math:`-\infty` is returned. If **x** < 0.0 the result is complex and it is returned as NaN.

GNSTLIB::log10
--------------

.. cpp:function:: double log10(const double x)

   Computes the base-10 logarithm :math:`\mathrm{log}_{10}(x)` for real :math:`x \ge 0`.

   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` 0.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. The result is real for **x** > 0.0. For **x** :math:`=` 0.0, :math:`-\infty` is returned. If **x** < 0.0 the result is complex and it is returned as NaN.

GNSTLIB::log1p
--------------

.. cpp:function:: double log1p(const double x)

   Computes the shifted logarithmic function :math:`\log(1+x)` for real :math:`x \ge -1`. The function is more accurate than evaluating ``log(1+x)`` for :math:`x` close to 0.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` -1.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. The result is real for **x** > -1.0. For **x** :math:`=` -1.0, :math:`-\infty` is returned. If **x** < -1.0 the result is complex and it is returned as NaN.

GNSTLIB::log1pmx
----------------

.. cpp:function:: double log1pmx(const double x)

   Computes :math:`\log(1+x)-x` for real :math:`x \ge -1`. The function is more accurate than evaluating ``log(1+x)-x`` for :math:`x` close to 0.
   
   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` -1.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. The result is real for **x** > -1.0. For **x** math:`=` -1.0, :math:`-\infty` is returned. If **x** < -1.0 the result is complex and it is returned as NaN.


GNSTLIB::log1pexp
-----------------
.. cpp:function:: double log1pexp(const double x)

   Computes :math:`\log(1+e^x)` for real :math:`x`.

   #. **Algorithm:**

      :cpp:func:`log1pexp` is derived from the algorithm in [1]. The scheme of computation is given by

      .. math::
         \mathrm{log1pexp}(x) = \begin{cases} 
            \exp(x) & x \le -37\\
            \mathrm{log1p}(\exp(x)) & -37 < x \le 18\\
            x + \exp(-x) & 18 < x \le 33.3\\
            x & x > 33.3
         \end{cases}

      See :cpp:func:`log1p`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::log1mexp
-----------------

.. cpp:function:: double log1mexp(const double x, int& err_id)

   Computes :math:`\log(1-e^x)` for real :math:`x < 0`.
   
   #. **Algorithm:**

      :cpp:func:`log1mexp` is derived from the algorithm in [1]. The scheme of computation is given by

      .. math::
         \mathrm{log1mexp}(x) = \begin{cases} 
            \log(-\mathrm{expm1(x)}) & 0 \le -x \le \log(2)\\
            \mathrm{log1p}(-\mathrm{exp(x)}) & -x > \log(2)\\
         \end{cases}

      See :cpp:func:`expm1` and :cpp:func:`log1p`.

   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** < 0.0.

      * **err_id**: (int) - *error identifier*.

   #. **Errors and Warnings:**

      * ``err_id`` = 1: 
         Argument **x** :math:`\ge` 0.0. The result is complex and it is returned as NaN.

   #. **Example:**

      .. code-block:: C++

         #include <iomanip>
         #include <iostream>

         #include <gnstlib_basic.hpp>

         void test_log1mexp()
         {
            double x = 1.5;
            int err_id = 0;
            double result = GNSTLIB::log1mexp(x, err_id);
            std::cout << std::setprecision(16) << result << std::endl;
            std::cout << err_id = << err_id << std::endl;
         }

      The above example produces the following output::

         nan
         err_id = 1

=======================
Trigonometric functions
=======================

GNSTLIB::cos
------------

.. cpp:function:: double cos(const double x)

   Computes the cosine function :math:`\cos(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> cos(const std::complex<double> z)

   Computes :math:`\cos(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::sin
------------

.. cpp:function:: double sin(const double x)

   Computes the sine function :math:`\sin(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> sin(const std::complex<double> z)

   Computes :math:`\sin(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::tan
------------

.. cpp:function:: double tan(const double x)

   Computes the tangent function :math:`\tan(x)` for real :math:`x`. The tangent function has poles at :math:`x = \pi (n + 1/2)`, but :math:`\pi/2` cannot be exactly represented in common floating-point arithmetic.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> tan(const std::complex<double> z)

   Computes :math:`\tan(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::sec
------------

.. cpp:function:: double sec(const double x)

   Computes the secant function :math:`\sec(x)` for real :math:`x`. The secant function has poles at :math:`x = \pi (n + 1/2)`, but :math:`\pi/2` cannot be exactly represented in common floating-point arithmetic.

   #. **Arguments:**

      * **x**: (double) - *argument*.   

.. cpp:function:: std::complex<double> sec(const std::complex<double> z)

   Computes :math:`\sec(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.


GNSTLIB::csc
------------

.. cpp:function:: double csc(const double x)

   Computes the cosecant function :math:`\csc(x)` for real :math:`x`. The cosecant function has poles at :math:`x = \pi n`, but :math:`\pi n` cannot be exactly represented in common floating-point arithmetic.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> csc(const std::complex<double> z)

   Computes :math:`\csc(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::cot
------------

.. cpp:function:: double cot(const double x)

   Computes the cotangent function :math:`\csc(x)` for real :math:`x`. The cotangent function has poles at :math:`x = \pi n`, but :math:`\pi n` cannot be exactly represented in common floating-point arithmetic.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> cot(const std::complex<double> z)

   Computes :math:`\cot(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::acos
-------------

.. cpp:function:: double acos(const double x)

   Computes arccosine function :math:`\text{acos}(x)` for real :math:`x \in [-1, 1]`. Outside this domain NaN is returned.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acos(const std::complex<double> z)


   Computes :math:`\text{acos}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::asin
-------------

.. cpp:function:: double asin(const double x)

   Computes arcsine function :math:`\text{asin}(x)` for real :math:`x \in [-1, 1]`. Outside this domain NaN is returned.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> asin(const std::complex<double> z)

   Computes :math:`\text{asin}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::atan
-------------

.. cpp:function:: double atan(const double x)

   Computes the arctangent function :math:`\text{atan}(x)` for real argument :math:`x \in (-\pi /2, \pi / 2)`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> atan(const std::complex<double> z)

   Computes :math:`\text{atan}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::atan2
--------------

.. cpp:function:: double atan2(const double y, const double x)

   Computes the arctangent function :math:`\text{atan}(y/x)` using the signs of arguments to determine the angle for the correct quadrant.

   #. **Arguments:**

      * **x**: (double) - *argument*.

      * **y**: (double) - *argument*.

GNSTLIB::asec
-------------

.. cpp:function:: double asec(const double x)

   Computes the inverse secant function :math:`\text{asec}(x) = \text{acos}(1/x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> asec(const std::complex<double> z)

   Computes :math:`\text{asec}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.


GNSTLIB::acsc
-------------

.. cpp:function:: double acsc(const double x)

   Computes the inverse cosecant function :math:`\text{acsc}(x) = \text{asin}(1/x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acsc(const std::complex<double> z)

   Computes :math:`\text{acsc}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::acot
-------------

.. cpp:function:: double acot(const double x)

   Computes the inverse cotangent function :math:`\text{acsc}(x) = \text{atan}(1/x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acot(const std::complex<double> z)

   Computes :math:`\text{acot}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::cospi
--------------

.. cpp:function:: double cospi(const double x)

   Computes :math:`\cos(\pi x)` for real :math:`x`. This function is more accurate than evaluating ``cos(pi * x)``.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> cospi(const std::complex<double> z)

   Computes :math:`\cos(\pi z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::sinpi
--------------

.. cpp:function:: double sinpi(const double x)

   Computes :math:`\sin(\pi x)` for real :math:`x`. This function is more accurate than evaluating ``sin(pi * x)``.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> sinpi(const std::complex<double> z)

   Computes :math:`\sin(\pi z)` for complex :math:`z`.
    
   #. **Arguments:**

      * **z**: (complex) - *argument*.

====================
Hyperbolic functions
====================

GNSTLIB::cosh
-------------

.. cpp:function:: double cosh(const double x)

   Computes the hyperbolic cosine function :math:`\cosh(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> cosh(const std::complex<double> z)

   Computes :math:`\cosh(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::sinh
-------------

.. cpp:function:: double sinh(const double x)

   Computes the hyperbolic sine function :math:`\sinh(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> sinh(const std::complex<double> z)

   Computes :math:`\sinh(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::tanh
-------------

.. cpp:function:: double tanh(const double x)

   Computes the hyperbolic tangent function :math:`\tanh(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> tanh(const std::complex<double> z)

   Computes :math:`\tanh(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::sech
-------------

.. cpp:function:: double sech(const double x)

   Computes the hyperbolic secant function :math:`\text{sech}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> sech(const std::complex<double> z)

   Computes :math:`\text{sech}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::csch
-------------

.. cpp:function:: double csch(const double x)

   Computes the hyperbolic cosecant function :math:`\text{csch}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> csch(const std::complex<double> z)

   Computes :math:`\text{csch}(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::coth
-------------

.. cpp:function:: double coth(const double x)

   Computes the hyperbolic cotangent function :math:`\coth(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> coth(const std::complex<double> z)

   Computes :math:`\coth(z)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::acosh
--------------

.. cpp:function:: double acosh(const double x)

   Computes the inverse hyperbolic cosine function :math:`\text{acosh}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acosh(const std::complex<double> z) 

   Computes :math:`\text{acosh}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::asinh
--------------

.. cpp:function:: double asinh(const double x)

   Computes the inverse hyperbolic sine function :math:`\text{asinh}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> asinh(const std::complex<double> z)

   Computes :math:`\text{asinh}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::atanh
--------------

.. cpp:function:: double atanh(const double x)

   Computes the inverse hyperbolic tangent function :math:`\text{atanh}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> atanh(const std::complex<double> z)

   Computes :math:`\text{atanh}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::asech
--------------

.. cpp:function:: double asech(const double x)

   Computes the inverse hyperbolic secant function :math:`\text{asech}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> asech(const std::complex<double> z)

   Computes :math:`\text{asech}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::acsch
--------------

.. cpp:function:: double acsch(const double x)

   Computes the inverse hyperbolic cosecant function :math:`\text{acsch}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acsch(const std::complex<double> z)

   Computes :math:`\text{acsch}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::acoth
--------------

.. cpp:function:: double acoth(const double x)

   Computes the inverse hyperbolic cotangent function :math:`\text{acoth}(x)` for real :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

.. cpp:function:: std::complex<double> acoth(const std::complex<double> z)

   Computes :math:`\text{acoth}(x)` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

===============
Power functions
===============

GNSTLIB::pow
------------

.. cpp:function:: double pow(const double x, const double y)

   Computes :math:`x^y` for real :math:`x` and :math:`y`.
      
   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: If **x** :math:`<` 0.0, **y** must be an integer.

      * **y**: (double) - *argument*.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. For **x** :math:`<` 0.0 and non-integer **y** the result is complex and it is returned as NaN. For **x** :math:`=` 0.0 and **y** :math:`<` 0.0, :math:`\infty` is returned. For **x** :math:`=` 0.0 and **y** :math:`=` 0.0, 1.0 is returned.

.. cpp:function:: std::complex<double> pow(const std::complex<double> x, const std::complex<double> y)

   Computes :math:`x^y` for complex :math:`x` and :math:`y` using ``std::exp(y*std::log(x))``.

   #. **Arguments:**

      * **x**: (complex) - *argument*.

      * **y**: (complex) - *argument*.

GNSTLIB::powm1
--------------

.. cpp:function:: double powm1(const double x, const double y, int& err_id)

   Computes :math:`x^y - 1` for real :math:`x` and :math:`y`. The function is more accurate than evaluating ``x^y - 1`` for :math:`x` close to 1 (equivalently for :math:`y` close to 0).
      
   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: If **x** :math:`<` 0.0, **y** must be an integer.

      * **y**: (double) - *argument*.

      * **err_id**: (int) - *error identifier*.

   #. **Errors and Warnings:**

      * ``err_id`` = 1: 
         Argument **x** :math:`<` 0.0 and **y** non-integer. The result is complex and it is returned as NaN.      


GNSTLIB::sqrt
-------------

.. cpp:function:: double sqrt(const double x)

   Computes the square root of :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.
         *Constraint*: **x** :math:`\ge` 0.0.

   #. **Errors and Warnings:**

      * Not ``err_id`` is used. For **x** :math:`<` 0.0 the result is complex and it is returned as NaN.

.. cpp:function:: std::complex<double> sqrt(const std::complex<double> z)

   Computes :math:`\sqrt{z}` for complex :math:`z`.

   #. **Arguments:**

      * **z**: (complex) - *argument*.

GNSTLIB::cbrt
-------------

.. cpp:function:: double cbrt(const double x)

   Computes the cubic root of :math:`x`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

GNSTLIB::hypot
--------------

.. cpp:function:: double hypot(const double x, const double y)

   Computes the length of the hypotenuse of a right-angled triangle :math:`\sqrt{x^2 + y^2}` with real sides :math:`x` and :math:`y`.

   #. **Arguments:**

      * **x**: (double) - *argument*.

      * **y**: (double) - *argument*.      

==========
References
==========

.. [1] M. Mächler (2012). Accurately Computing :math:`\log(1-\exp(-|a|))` Assessed by the Rmpfr package. [`https://cran.r-project.org/web/packages/Rmpfr/vignettes/log1mexp-note.pdf <https://cran.r-project.org/web/packages/Rmpfr/vignettes/log1mexp-note.pdf>`_]