*********************************************** Error Functions, Dawson’s and Fresnel Integrals *********************************************** GNSTLIB includes implementations of the error functions, Dawson's integral and more generally the Faddeeva function for complex arguments by wrapping the C++ library `Faddeeva package `_. These functions and other such as Fresnel integrals or Voigt profiles are included in the main header file: .. code-block:: C++ #include ============= Main function ============= GNSTLIB::erf ------------ .. cpp:function:: double erf(const double x, int& err_id) Computes the error function :math:`\text{erf}(x)` for real :math:`x`.The error function is defined by .. math:: \text{erf}(z) = \frac{2}{\sqrt{\pi}} \int_0^z e^{-t^2} \mathop{dt}. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Argument **x** is too small. Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex erf(const std::complex z, int& err_id) #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Argument **z** is too large. Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Argument **z** is too small. Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::erfc ------------- .. cpp:function:: double erfc(const double x, int& err_id) Computes the complementary error function :math:`\text{erfc}(x)` for real :math:`x`. The complementary error function is defined by .. math:: \text{erfc}(z) = \frac{2}{\sqrt{\pi}} \int_z^{\infty} e^{-t^2} \mathop{dt} = 1 - \text{erf}(z). #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Argument **x** is too large, more precisely **x** :math:`\gtrsim 26.55`. Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex erfc(const std::complex z, int& err_id) Computes the complementary error function :math:`\text{erfc}(z)` for complex :math:`z`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::erfcx -------------- .. cpp:function:: double erfcx(const double x, int& err_id) Computes the scaled complementary error function :math:`\text{erfcx}(x)` for real :math:`x`. :math:`\text{erfcx}(z)` is given by .. math:: \text{erfcx}(z) = e^{z^2} \text{erfc}(z). The scaled complement of the error function may be used to replace and expression of the form :math:`e^{z^2} \text{erfc}(z)`, in order to handle cases prone to underflow or overflow errors. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Argument **x** is too large and negative, more precisely **x** :math:`< -26.628`. Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Argument **x** is too large, more precisely **x** :math:`>` ``MAXDOUBLE``. Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex erfcx(const std::complex z, int& err_id) Computes the scaled complementary error function :math:`\text{erfcx}(z)` for complex :math:`z`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::erfi ------------- .. cpp:function:: double erfi(const double x, int& err_id) Computes the imaginary error function :math:`\text{erfi}(x)` for real :math:`x`. :math:`\text{erfi}(z)` is an entire function defined by .. math:: \text{erfi}(z) = -i \text{erf}(iz). #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Argument **x** is too large, more precisely :math:`|` **x** :math:`|` :math:`> 26.642`. Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Argument **x** is too small, more precisely **x** :math:`<` 1.0/``MAXDOUBLE``. Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex erfi(const std::complex z, int& err_id) Computes the imaginary error function :math:`\text{erfi}(z)` for complex :math:`z`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::faddeeva ----------------- .. cpp:function:: std::complex faddeeva(const std::complex z, int& err_id) Computes the Faddeeva function or plasma dispersion function :math:`w(z)` for complex :math:`z`. Most of the error functions are expressible in terms of :math:`w(z)`. The Faddeeva function is defined by .. math:: w(z) = e^{-z^2} \left(1 + \frac{2i}{\sqrt{\pi}} \int_0^z e^{t^2} \mathop{dt} \right) = e^{-z^2} \text{erfc}(-iz). The Faddeeva function has the symmetry property: :math:`w(-z) = 2 e^{-z^2} - w(z)` and :math:`w(\overline{z}) = \overline{w(-z)}`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::dawson --------------- .. cpp:function:: double dawson(const double x, int& err_id) Computes the Dawson's integral :math:`F(x)` for real :math:`x`. The Dawson's integral is defined by .. math:: F(z) = e^{-z^2} \int_0^z e^{t^2} \mathop{dt} = \frac{\sqrt{\pi}}{2} e^{-z^2} \text{erfi}(z). #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex dawson(const std::complex z, int& err_id) Computes the Dawson's integral :math:`F(z)` for complex :math:`z`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::fresnelc ----------------- .. cpp:function:: double fresnelc(const double x, int& err_id) Computes the Fresnel integral :math:`C(x)` for real :math:`x`. The Fresnel integral :math:`C(z)` is defined by .. math:: C(z) = \int_0^z \cos \left(\frac{\pi t^2}{2}\right) \mathop{dt}. Function :math:`C(z)` satisfies the symmetry property :math:`C(-z) = -C(z)`. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex fresnelc(const std::complex z, int& err_id) Computes the Fresnel integral :math:`C(z)` for complex :math:`z`. A relevant case is, :math:`C(iz) = i C(z)`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. GNSTLIB::fresnels ----------------- .. cpp:function:: double fresnels(const double x, int& err_id) Computes the Fresnel integral :math:`S(x)` for real :math:`x`. The Fresnel integral :math:`S(z)` is defined by .. math:: S(z) = \int_0^z \sin \left(\frac{\pi t^2}{2}\right) \mathop{dt} Function :math:`C(z)` satisfies the symmetry property :math:`S(-z) = -S(z)`. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **x** is NaN or an unexpected error occurred. Contact the authors. .. cpp:function:: std::complex fresnels(const std::complex z, int& err_id) Computes the Fresnel integral :math:`S(z)` for complex :math:`z`. A relevant case is, :math:`S(iz) = -i S(z)`. #. **Arguments:** * **z**: (complex) - *argument*. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = -1: Argument **z** is NaN or an unexpected error occurred. Contact the authors. ================= Inverse functions ================= GNSTLIB::inverf --------------- .. cpp:function:: double inverf(const double x, int& err_id) Computes the inverse function for :math:`\text{erf}(x)` for real :math:`x \in [-1, 1]`, defined by :math:`\text{erf}(\text{erf}^{-1}(x)) = x`. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. GNSTLIB::inverfc ---------------- .. cpp:function:: double inverfc(const double x, int& err_id) Computes the inverse function for :math:`\text{erfc}(x)` for real :math:`x \in [0, 2]`, defined by :math:`\text{erfc}(\text{erfc}^{-1}(x)) = x`. #. **Arguments:** * **x**: (double) - *argument*. * **err_id**: (int) - *error identifier*. ============ Applications ============ GNSTLIB::voigt_profile ---------------------- .. cpp:function:: double voigt_profile(const double x, const double sigma, const double gamma, int& err_id) The Voigt profile is a line profile resulting from the convolution of the two broadening mechanisms, a Gaussian profile and a Lorentzian profile. Voigt profiles typically arise in many branches of spectroscopy and diffraction, and in particular, in the modelling and analysis of radiative transfer in the atmosphere. A closed form is given by .. math:: V(x; \sigma, \gamma) = \frac{\Re(w(z))}{\sigma \sqrt{2\pi}}, \quad z = \frac{x + i \gamma}{\sigma \sqrt{2}}, where :math:`\Re(w(z))` indicates the real part of the Faddeeva function. #. **Arguments:** * **x**: (double) - *argument*. * **sigma**: (double) - *argument*. *Constraint*: **sigma** :math:`> 0`. * **gamma**: (double) - *argument*. *Constraint*: **gamma** :math:`> 0`. * **err_id**: (int) - *error identifier*. #. **Errors and Warnings:** * ``err_id`` = 1: Result is too large to be represented and :math:`\infty` is returned. * ``err_id`` = 2: Result is too small to be represented and 0.0 is returned. * ``err_id`` = 3: The result is a denormalized / subnormal number. * ``err_id`` = 4: Argument **sigma** and/or **gamma** is negative or zero, NaN is returned. * ``err_id`` = -1: One or several arguments are NaN or an unexpected error occurred. Contact the authors. ==================== Vectorized functions ==================== GNSTLIB::erf_vec ---------------- .. cpp:function:: void erf_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void erf_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void erf_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void erf_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::erfc_vec ----------------- .. cpp:function:: void erfc_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void erfc_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void erfc_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void erfc_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::erfcx_vec ------------------ .. cpp:function:: void erfcx_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void erfcx_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void erfcx_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void erfcx_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::erfi_vec ----------------- .. cpp:function:: void erfi_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void erfi_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void erfi_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void erfi_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::dawson_vec ------------------- .. cpp:function:: void dawson_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void dawson_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void dawson_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void dawson_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::faddeeva_vec --------------------- .. cpp:function:: void faddeeva_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void faddeeva_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::fresnelc_vec --------------------- .. cpp:function:: void fresnelc_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void fresnelc_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void fresnelc_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void fresnelc_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0) GNSTLIB::fresnels_vec --------------------- .. cpp:function:: void fresnels_vec(std::vector& v, std::vector& r, unsigned short option = 0) .. cpp:function:: void fresnels_vec(const int n, const double *v, double *r, unsigned short option = 0) .. cpp:function:: void fresnels_vec(std::vector>& v, std::vector>& r, unsigned short option = 0) .. cpp:function:: void fresnels_vec(const int n, const std::complex *v, std::complex *r, unsigned short option = 0)