| .. _math: |
| |
| ============== |
| Math Functions |
| ============== |
| |
| .. include:: ../check.rst |
| |
| .. raw:: html |
| |
| <style> .green {color:green} </style> |
| |
| .. role:: green |
| |
| .. toctree:: |
| :hidden: |
| |
| log.rst |
| |
| |
| .. contents:: Table of Contents |
| :depth: 4 |
| :local: |
| |
| Source Locations |
| ================ |
| |
| - The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_. |
| - The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_. |
| - The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_. |
| |
| Implementation Requirements / Goals |
| =================================== |
| |
| * The highest priority is to be as accurate as possible, according to the C and |
| IEEE 754 standards. By default, we will aim to be correctly rounded for `all rounding modes <https://en.cppreference.com/w/c/numeric/fenv/FE_round>`_. |
| The current rounding mode of the floating point environment is used to perform |
| computations and produce the final results. |
| |
| - To test for correctness, we compare the outputs with other correctly rounded |
| multiple-precision math libraries such as the `GNU MPFR library <https://www.mpfr.org/>`_ |
| or the `CORE-MATH library <https://core-math.gitlabpages.inria.fr/>`_. |
| |
| * Our next requirement is that the outputs are consistent across all platforms. |
| Notice that the consistency requirement will be satisfied automatically if the |
| implementation is correctly rounded. |
| |
| * Our last requirement for the implementations is to have good and predicable |
| performance: |
| |
| - The average performance should be comparable to other ``libc`` |
| implementations. |
| - The worst case performance should be within 10X-20X of the average. |
| - Platform-specific implementations or instructions could be added whenever it |
| makes sense and provides significant performance boost. |
| |
| * For other use cases that have strict requirements on the code size, memory |
| footprint, or latency, such as embedded systems, we will aim to be as accurate |
| as possible within the memory or latency budgets, and consistent across all |
| platforms. |
| |
| |
| Add a new math function to LLVM libc |
| ==================================== |
| |
| * To add a new math function, follow the steps at: `libc/src/math/docs/add_math_function.md <https://github.com/llvm/llvm-project/tree/main/libc/src/math/docs/add_math_function.md>`_. |
| |
| Implementation Status |
| ===================== |
| |
| * To check math functions enabled for Linux: |
| |
| - `linux-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64/entrypoints.txt>`_ |
| |
| - `linux-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64/entrypoints.txt>`_ |
| |
| - `linux-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm/entrypoints.txt>`_ |
| |
| - `linux-riscv64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/riscv64/entrypoints.txt>`_ |
| |
| * To check math functions enabled for Windows: |
| |
| - `windows-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_ |
| |
| - windows-aarch64 - to be added |
| |
| * To check math functions enabled for macOS: |
| |
| - `darwin-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/x86_64/entrypoints.txt>`_ |
| |
| - `darwin-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/arm/entrypoints.txt>`_ |
| |
| * To check math functions enabled for GPU: |
| |
| - `gpu-entrypoints <https://github.com/llvm/llvm-project/tree/main/libc/config/gpu/entrypoints.txt>`_ |
| |
| * To check math functions enabled for embedded system: |
| |
| - `barebone-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/baremetal/arm/entrypoints.txt>`_ |
| |
| - barebone-riscv32 - to be added |
| |
| Basic Operations |
| ---------------- |
| |
| +--------------+---------------------------------------+-------------------+-------------------+-------------------+-------------------+ |
| | <Func> | Linux | Windows | MacOS | Embedded | GPU | |
| | +---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | | x86_64 | aarch64 | aarch32 | riscv64 | x86_64 | aarch64 | x86_64 | aarch64 | aarch32 | riscv32 | AMD | nVidia | |
| +==============+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+ |
| | ceil | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ceilf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ceill | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | copysign | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | copysignf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | copysignl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fabs | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fabsf | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fabsl | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fdim | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fdimf | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fdiml | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | floor | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | floorf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | floorl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmax | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmaxf | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmaxl | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmin | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fminf | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fminl | |check| | |check| | |check| | |check| | |check| | | | |check| | |check| | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmod | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmodf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmodl | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | frexp | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | frexpf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | frexpl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ilogb | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ilogbf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ilogbl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ldexp | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ldexpf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | ldexpl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llrint | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llrintf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llrintl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llround | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llroundf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | llroundl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | logb | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | logbf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | logbl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lrint | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lrintf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lrintl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lround | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lroundf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lroundl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | modf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | modff | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | modfl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nan | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nanf | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nanl | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nearbyint | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nearbyintf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nearbyintl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nextafter | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nextafterf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nextafterl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nexttoward | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nexttowardf | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | nexttowardl | | | | | | | | | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remainder | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remainderf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remainderl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remquo | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remquof | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | remquol | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | rint | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | rintf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | rintl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | round | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | roundf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | roundl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | scalbn | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | scalbnf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | scalbnl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | trunc | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | truncf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | truncl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +--------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| |
| |
| Higher Math Functions |
| --------------------- |
| |
| +------------+---------------------------------------+-------------------+-------------------+-------------------+-------------------+ |
| | <Func> | Linux | Windows | MacOS | Embedded | GPU | |
| | +---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | | x86_64 | aarch64 | aarch32 | riscv64 | x86_64 | aarch64 | x86_64 | aarch64 | aarch32 | riscv32 | AMD | nVidia | |
| +============+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+=========+ |
| | acos | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | acosf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | acosl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | acosh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | acoshf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | acoshl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asin | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asinf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asinl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asinh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asinhf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | asinhl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atan | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atanf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atanl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atan2 | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atan2f | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atan2l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atanh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atanhf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | atanhl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cbrt | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cbrtf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cbrtl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cos | |check| | | | | |check| | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cosf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cosl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | cosh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | coshf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | coshl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erff | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erfl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erfc | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erfcf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | erfcl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | expf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | expl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp10 | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp10f | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp10l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp2 | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp2f | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | exp2l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | expm1 | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | expm1f | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | expm1l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fma | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmaf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | fmal | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | hypot | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | hypotf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | hypotl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lgamma | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lgammaf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | lgammal | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log | |check| | |check| | | | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | logf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | logl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log10 | |check| | |check| | | | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log10f | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log10l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log1p | |check| | |check| | | | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log1pf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log1pl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log2 | |check| | |check| | | | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log2f | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | log2l | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | pow | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | powf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | powl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sin | |check| | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sinf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sinl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sincos | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sincosf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sincosl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sinh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sinhf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sinhl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sqrt | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sqrtf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | sqrtl | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tan | |check| | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tanf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tanl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tanh | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tanhf | |check| | |check| | | |check| | |check| | | | |check| | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tanhl | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tgamma | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tgammaf | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| | tgammal | | | | | | | | | | | | | |
| +------------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+---------+ |
| |
| |
| Accuracy of Higher Math Functions |
| ================================= |
| |
| ============== ================ =============== ====================== |
| <Func> <Func_f> (float) <Func> (double) <Func_l> (long double) |
| ============== ================ =============== ====================== |
| acos |check| |
| acosh |check| |
| asin |check| |
| asinh |check| |
| atan |check| |
| atanh |check| |
| cos |check| large |
| cosh |check| |
| exp |check| |
| exp10 |check| |
| exp2 |check| |
| expm1 |check| |
| fma |check| |check| |
| hypot |check| |check| |
| log |check| |check| |
| log10 |check| |check| |
| log1p |check| |check| |
| log2 |check| |check| |
| sin |check| large |
| sincos |check| large |
| sinh |check| |
| sqrt |check| |check| |check| |
| tan |check| |
| tanh |check| |
| ============== ================ =============== ====================== |
| |
| |
| Legends: |
| |
| * |check| : correctly rounded for all 4 rounding modes. |
| * CR: correctly rounded for the default rounding mode (round-to-the-nearest, |
| tie-to-even). |
| * x ULPs: largest errors recorded. |
| |
| .. |
| TODO(lntue): Add a new page to discuss about the algorithms used in the |
| implementations and include the link here. |
| |
| |
| Performance |
| =========== |
| |
| * Simple performance testings are located at: `libc/test/src/math/differential_testing <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math/differential_testing>`_. |
| |
| * We also use the *perf* tool from the `CORE-MATH <https://core-math.gitlabpages.inria.fr/>`_ |
| project: `link <https://gitlab.inria.fr/core-math/core-math/-/tree/master>`_. |
| The performance results from the CORE-MATH's perf tool are reported in the |
| table below, using the system library as reference (such as the `GNU C library <https://www.gnu.org/software/libc/>`_ |
| on Linux). Fmod performance results obtained with "differential_testing". |
| |
| +--------------+-------------------------------+-------------------------------+-------------------------------------+----------------------------------------------------------------------+ |
| | <Func> | Reciprocal throughput (clk) | Latency (clk) | Testing ranges | Testing configuration | |
| | +-----------+-------------------+-----------+-------------------+ +-------------+-------------------------+--------------+---------------+ |
| | | LLVM libc | Reference (glibc) | LLVM libc | Reference (glibc) | | CPU | OS | Compiler | Special flags | |
| +==============+===========+===================+===========+===================+=====================================+=============+=========================+==============+===============+ |
| | acosf | 24 | 29 | 62 | 77 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | acoshf | 18 | 26 | 73 | 74 | :math:`[1, 21]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | asinf | 23 | 27 | 62 | 62 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | asinhf | 21 | 39 | 77 | 91 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | atanf | 27 | 29 | 79 | 68 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | atanhf | 18 | 66 | 68 | 133 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | cosf | 13 | 32 | 53 | 59 | :math:`[0, 2\pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | coshf | 14 | 20 | 50 | 48 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | expf | 9 | 7 | 44 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | exp10f | 10 | 8 | 40 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | exp2f | 9 | 6 | 35 | 31 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | expm1f | 9 | 44 | 42 | 121 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | fmodf | 73 | 263 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | |
| | +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | | 9 | 11 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | fmod | 595 | 3297 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | |
| | +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | | 14 | 13 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | hypotf | 25 | 15 | 64 | 49 | :math:`[-10, 10] \times [-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | logf | 12 | 10 | 56 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | log10f | 9 | 17 | 35 | 48 | :math:`[e^{-1}, e]` | Ryzen 5900X | Ubuntu 22.04 LTS x86_64 | Clang 15.0.6 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | log1pf | 16 | 33 | 61 | 97 | :math:`[e^{-0.5} - 1, e^{0.5} - 1]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | log2f | 13 | 10 | 57 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | sinf | 12 | 25 | 51 | 57 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | sincosf | 19 | 30 | 57 | 68 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | sinhf | 13 | 63 | 48 | 137 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | tanf | 16 | 50 | 61 | 107 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| | tanhf | 13 | 55 | 57 | 123 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | |
| +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ |
| |
| Algorithms + Implementation Details |
| =================================== |
| |
| * :doc:`log` |
| |
| References |
| ========== |
| |
| * `CRLIBM <https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf>`_. |
| * `RLIBM <https://people.cs.rutgers.edu/~sn349/rlibm/>`_. |
| * `Sollya <https://www.sollya.org/>`_. |
| * `The CORE-MATH Project <https://core-math.gitlabpages.inria.fr/>`_. |
| * `The GNU C Library (glibc) <https://www.gnu.org/software/libc/>`_. |
| * `The GNU MPFR Library <https://www.mpfr.org/>`_. |
