libc/docs/math/index.rst

   1 .. _math:
   2
   3 ==============
   4 Math Functions
   5 ==============
   6
   7 .. include:: ../check.rst
   8
   9 .. raw:: html
  10
  11     <style> .green {color:green} </style>
  12
  13 .. role:: green
  14
  15 .. toctree::
  16   :hidden:
  17
  18   log.rst
  19
  20
  21 .. contents:: Table of Contents
  22   :depth: 4
  23   :local:
  24
  25 Source Locations
  26 ================
  27
  28 - The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_.
  29 - The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_.
  30 - The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_.
  31
  32 Implementation Requirements / Goals
  33 ===================================
  34
  35 * The highest priority is to be as accurate as possible, according to the C and
  36   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>`_.
  37   The current rounding mode of the floating point environment is used to perform
  38   computations and produce the final results.
  39
  40   - To test for correctness, we compare the outputs with other correctly rounded
  41     multiple-precision math libraries such as the `GNU MPFR library <https://www.mpfr.org/>`_
  42     or the `CORE-MATH library <https://core-math.gitlabpages.inria.fr/>`_.
  43
  44 * Our next requirement is that the outputs are consistent across all platforms.
  45   Notice that the consistency requirement will be satisfied automatically if the
  46   implementation is correctly rounded.
  47
  48 * Our last requirement for the implementations is to have good and predicable
  49   performance:
  50
  51   - The average performance should be comparable to other ``libc``
  52     implementations.
  53   - The worst case performance should be within 10X-20X of the average.
  54   - Platform-specific implementations or instructions could be added whenever it
  55     makes sense and provides significant performance boost.
  56
  57 * For other use cases that have strict requirements on the code size, memory
  58   footprint, or latency, such as embedded systems, we will aim to be as accurate
  59   as possible within the memory or latency budgets, and consistent across all
  60   platforms.
  61
  62
  63 Add a new math function to LLVM libc
  64 ====================================
  65
  66 * 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>`_.
  67
  68 Implementation Status
  69 =====================
  70
  71 Basic Operations
  72 ----------------
  73
  74 ============== ================ =============== ======================
  75 <Func>         <Func_f> (float) <Func> (double) <Func_l> (long double)
  76 ============== ================ =============== ======================
  77 ceil           :green:`XA`      :green:`XA`     :green:`XA`
  78 copysign       :green:`XA`      :green:`XA`     :green:`XA`
  79 fabs           :green:`XA`      :green:`XA`     :green:`XA`
  80 fdim           :green:`XA`      :green:`XA`     :green:`XA`
  81 floor          :green:`XA`      :green:`XA`     :green:`XA`
  82 fmax           :green:`XA`      :green:`XA`     :green:`XA`
  83 fmin           :green:`XA`      :green:`XA`     :green:`XA`
  84 fmod           :green:`XA`      :green:`XA`
  85 fpclassify
  86 frexp          :green:`XA`      :green:`XA`     :green:`XA`
  87 ilogb          :green:`XA`      :green:`XA`     :green:`XA`
  88 isfinite
  89 isgreater
  90 isgreaterequal
  91 isinf
  92 isless
  93 islessequal
  94 islessgreater
  95 isnan
  96 isnormal
  97 isubordered
  98 ldexp          :green:`XA`      :green:`XA`     :green:`XA`
  99 llrint         :green:`XA`      :green:`XA`     :green:`XA`
 100 llround        :green:`XA`      :green:`XA`     :green:`XA`
 101 logb           :green:`XA`      :green:`XA`     :green:`XA`
 102 lrint          :green:`XA`      :green:`XA`     :green:`XA`
 103 lround         :green:`XA`      :green:`XA`     :green:`XA`
 104 modf           :green:`XA`      :green:`XA`     :green:`XA`
 105 nan
 106 nearbyint      :green:`XA`      :green:`XA`     :green:`XA`
 107 nextafter      :green:`XA`      :green:`XA`     :green:`XA`
 108 nexttoward
 109 remainder      :green:`XA`      :green:`XA`     :green:`XA`
 110 remquo         :green:`XA`      :green:`XA`     :green:`XA`
 111 rint           :green:`XA`      :green:`XA`     :green:`XA`
 112 round          :green:`XA`      :green:`XA`     :green:`XA`
 113 scalbn         :green:`XA`      :green:`XA`     :green:`XA`
 114 signbit
 115 trunc          :green:`XA`      :green:`XA`     :green:`XA`
 116 ============== ================ =============== ======================
 117
 118 Higher Math Functions
 119 ---------------------
 120
 121 ============== ================ =============== ======================
 122 <Func>         <Func_f> (float) <Func> (double) <Func_l> (long double)
 123 ============== ================ =============== ======================
 124 acos           :green:`XA`
 125 acosh          :green:`XA`
 126 asin           :green:`XA`
 127 asinh          :green:`XA`
 128 atan           :green:`XA`
 129 atan2
 130 atanh          :green:`XA`
 131 cbrt
 132 cos            :green:`XA`      :green:`XA`
 133 cosh           :green:`XA`
 134 erf
 135 erfc
 136 exp            :green:`XA`
 137 exp10          :green:`XA`
 138 exp2           :green:`XA`
 139 expm1          :green:`XA`
 140 fma            :green:`XA`      :green:`XA`
 141 hypot          :green:`XA`      :green:`XA`
 142 lgamma
 143 log            :green:`XA`
 144 log10          :green:`XA`      :green:`XA`
 145 log1p          :green:`XA`
 146 log2           :green:`XA`
 147 pow
 148 sin            :green:`XA`      :green:`XA`
 149 sincos         :green:`XA`      :green:`XA`
 150 sinh           :green:`XA`
 151 sqrt           :green:`XA`      :green:`XA`     :green:`XA`
 152 tan            :green:`XA`
 153 tanh           :green:`XA`
 154 tgamma
 155 ============== ================ =============== ======================
 156
 157 Accuracy of Higher Math Functions
 158 =================================
 159
 160 ============== ================ =============== ======================
 161 <Func>         <Func_f> (float) <Func> (double) <Func_l> (long double)
 162 ============== ================ =============== ======================
 163 acos           :green:`XA`
 164 acosh          :green:`XA`
 165 asin           :green:`XA`
 166 asinh          :green:`XA`
 167 atan           :green:`XA`
 168 atanh          :green:`XA`
 169 cos            :green:`XA`      large
 170 cosh           :green:`XA`
 171 exp            :green:`XA`
 172 exp10          :green:`XA`
 173 exp2           :green:`XA`
 174 expm1          :green:`XA`
 175 fma            :green:`XA`      :green:`XA`
 176 hypot          :green:`XA`      :green:`XA`
 177 log            :green:`XA`
 178 log10          :green:`XA`      :green:`XA`
 179 log1p          :green:`XA`
 180 log2           :green:`XA`
 181 sin            :green:`XA`      large
 182 sincos         :green:`XA`      large
 183 sinh           :green:`XA`
 184 sqrt           :green:`XA`      :green:`XA`     :green:`XA`
 185 tan            :green:`XA`
 186 tanh           :green:`XA`
 187 ============== ================ =============== ======================
 188
 189 Legends:
 190
 191 * `X` = x86_64, `A` = aarch64, `a` = arm32
 192 * Green text (eg. :green:`XA`): correctly rounded for all 4 rounding modes.
 193 * CR: correctly rounded for the default rounding mode (round-to-the-nearest,
 194   tie-to-even).
 195 * x ULPs: largest errors recorded.
 196
 197 ..
 198   TODO(lntue): Add a new page to discuss about the algorithms used in the
 199   implementations and include the link here.
 200
 201
 202 Performance
 203 ===========
 204
 205 * 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>`_.
 206
 207 * We also use the *perf* tool from the `CORE-MATH <https://core-math.gitlabpages.inria.fr/>`_
 208   project: `link <https://gitlab.inria.fr/core-math/core-math/-/tree/master>`_.
 209   The performance results from the CORE-MATH's perf tool are reported in the
 210   table below, using the system library as reference (such as the `GNU C library <https://www.gnu.org/software/libc/>`_
 211   on Linux). Fmod performance results obtained with "differential_testing".
 212
 213 +--------------+-------------------------------+-------------------------------+-------------------------------------+----------------------------------------------------------------------+
 214 | <Func>       | Reciprocal throughput (clk)   | Latency (clk)                 | Testing ranges                      | Testing configuration                                                |
 215 |              +-----------+-------------------+-----------+-------------------+                                     +-------------+-------------------------+--------------+---------------+
 216 |              | LLVM libc | Reference (glibc) | LLVM libc | Reference (glibc) |                                     | CPU         | OS                      | Compiler     | Special flags |
 217 +==============+===========+===================+===========+===================+=====================================+=============+=========================+==============+===============+
 218 | acosf        |        24 |                29 |        62 |                77 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 219 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 220 | acoshf       |        18 |                26 |        73 |                74 | :math:`[1, 21]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 221 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 222 | asinf        |        23 |                27 |        62 |                62 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 223 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 224 | asinhf       |        21 |                39 |        77 |                91 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 225 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 226 | atanf        |        27 |                29 |        79 |                68 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 227 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 228 | atanhf       |        18 |                66 |        68 |               133 | :math:`[-1, 1]`                     | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 229 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 230 | cosf         |        13 |                32 |        53 |                59 | :math:`[0, 2\pi]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 231 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 232 | coshf        |        14 |                20 |        50 |                48 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 233 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 234 | expf         |         9 |                 7 |        44 |                38 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 235 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 236 | exp10f       |        10 |                 8 |        40 |                38 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 237 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 238 | exp2f        |         9 |                 6 |        35 |                31 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 239 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 240 | expm1f       |         9 |                44 |        42 |               121 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 241 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 242 | fmodf        |        73 |               263 |        -  |                 - | [MIN_NORMAL, MAX_NORMAL]            | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 243 |              +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 244 |              |         9 |                11 |        -  |                 - | [0, MAX_SUBNORMAL]                  | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 245 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 246 | fmod         |       595 |              3297 |        -  |                 - | [MIN_NORMAL, MAX_NORMAL]            | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 247 |              +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 248 |              |        14 |                13 |        -  |                 - | [0, MAX_SUBNORMAL]                  | i5 mobile   | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 249 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 250 | hypotf       |        25 |                15 |        64 |                49 | :math:`[-10, 10] \times [-10, 10]`  | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 |               |
 251 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 252 | logf         |        12 |                10 |        56 |                46 | :math:`[e^{-1}, e]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 253 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 254 | log10f       |         9 |                17 |        35 |                48 | :math:`[e^{-1}, e]`                 | Ryzen 5900X | Ubuntu 22.04 LTS x86_64 | Clang 15.0.6 | FMA           |
 255 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 256 | 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           |
 257 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 258 | log2f        |        13 |                10 |        57 |                46 | :math:`[e^{-1}, e]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 259 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 260 | sinf         |        12 |                25 |        51 |                57 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 261 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 262 | sincosf      |        19 |                30 |        57 |                68 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA           |
 263 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 264 | sinhf        |        13 |                63 |        48 |               137 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 265 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 266 | tanf         |        16 |                50 |        61 |               107 | :math:`[-\pi, \pi]`                 | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 267 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 268 | tanhf        |        13 |                55 |        57 |               123 | :math:`[-10, 10]`                   | Ryzen 1700  | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA           |
 269 +--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+
 270
 271 Algorithms + Implementation Details
 272 ===================================
 273
 274 * :doc:`log`
 275
 276 References
 277 ==========
 278
 279 * `CRLIBM <https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf>`_.
 280 * `RLIBM <https://people.cs.rutgers.edu/~sn349/rlibm/>`_.
 281 * `Sollya <https://www.sollya.org/>`_.
 282 * `The CORE-MATH Project <https://core-math.gitlabpages.inria.fr/>`_.
 283 * `The GNU C Library (glibc) <https://www.gnu.org/software/libc/>`_.
 284 * `The GNU MPFR Library <https://www.mpfr.org/>`_.