1.. _math: 2 3====== 4math.h 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 stdfix.rst 20 21 22.. contents:: Table of Contents 23 :depth: 4 24 :local: 25 26Source Locations 27================ 28 29- The main source is located at: `libc/src/math <https://github.com/llvm/llvm-project/tree/main/libc/src/math>`_. 30- The tests are located at: `libc/test/src/math <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math>`_. 31- The floating point utilities are located at: `libc/src/__support/FPUtil <https://github.com/llvm/llvm-project/tree/main/libc/src/__support/FPUtil>`_. 32 33Implementation Requirements / Goals 34=================================== 35 36* The highest priority is to be as accurate as possible, according to the C and 37 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>`_. 38 The current rounding mode of the floating point environment is used to perform 39 computations and produce the final results. 40 41 - To test for correctness, we compare the outputs with other correctly rounded 42 multiple-precision math libraries such as the `GNU MPFR library <https://www.mpfr.org/>`_ 43 or the `CORE-MATH library <https://core-math.gitlabpages.inria.fr/>`_. 44 45* Our next requirement is that the outputs are consistent across all platforms. 46 Notice that the consistency requirement will be satisfied automatically if the 47 implementation is correctly rounded. 48 49* Our last requirement for the implementations is to have good and predicable 50 performance: 51 52 - The average performance should be comparable to other ``libc`` 53 implementations. 54 - The worst case performance should be within 10X-20X of the average. 55 - Platform-specific implementations or instructions could be added whenever it 56 makes sense and provides significant performance boost. 57 58* For other use cases that have strict requirements on the code size, memory 59 footprint, or latency, such as embedded systems, we will aim to be as accurate 60 as possible within the memory or latency budgets, and consistent across all 61 platforms. 62 63 64Add a new math function to LLVM libc 65==================================== 66 67* 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>`_. 68 69Implementation Status 70===================== 71 72* To check math functions enabled for Linux: 73 74 - `linux-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64/entrypoints.txt>`_ 75 76 - `linux-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/aarch64/entrypoints.txt>`_ 77 78 - `linux-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/arm/entrypoints.txt>`_ 79 80 - `linux-riscv and linux-riscv32 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/riscv/entrypoints.txt>`_ 81 82* To check math functions enabled for Windows: 83 84 - `windows-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/windows/entrypoints.txt>`_ 85 86 - windows-aarch64 - to be added 87 88* To check math functions enabled for macOS: 89 90 - `darwin-x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/x86_64/entrypoints.txt>`_ 91 92 - `darwin-aarch64 <https://github.com/llvm/llvm-project/tree/main/libc/config/darwin/arm/entrypoints.txt>`_ 93 94* To check math functions enabled for GPU: 95 96 - `gpu-entrypoints <https://github.com/llvm/llvm-project/tree/main/libc/config/gpu/entrypoints.txt>`_ 97 98* To check math functions enabled for embedded system: 99 100 - `baremetal-aarch32 <https://github.com/llvm/llvm-project/tree/main/libc/config/baremetal/arm/entrypoints.txt>`_ 101 102 - baremetal-riscv32 - to be added 103 104 105Basic Operations 106================ 107 108+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 109| <Func> | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section | 110+==================+==================+=================+========================+======================+========================+========================+============================+ 111| ceil | |check| | |check| | |check| | |check| | |check| | 7.12.9.1 | F.10.6.1 | 112+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 113| canonicalize | |check| | |check| | |check| | |check| | |check| | 7.12.11.7 | F.10.8.7 | 114+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 115| copysign | |check| | |check| | |check| | |check| | |check| | 7.12.11.1 | F.10.8.1 | 116+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 117| dadd | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.1 | F.10.11 | 118+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 119| ddiv | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.4 | F.10.11 | 120+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 121| dfma | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.5 | F.10.11 | 122+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 123| dmul | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.3 | F.10.11 | 124+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 125| dsub | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.2 | F.10.11 | 126+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 127| f16add | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.1 | F.10.11 | 128+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 129| f16div | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.4 | F.10.11 | 130+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 131| f16fma | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.5 | F.10.11 | 132+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 133| f16mul | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.5 | F.10.11 | 134+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 135| f16sub | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.2 | F.10.11 | 136+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 137| fabs | |check| | |check| | |check| | |check| | |check| | 7.12.7.3 | F.10.4.3 | 138+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 139| fadd | N/A | |check| | |check| | N/A | |check| | 7.12.14.1 | F.10.11 | 140+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 141| fdim | |check| | |check| | |check| | |check| | |check| | 7.12.12.1 | F.10.9.1 | 142+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 143| fdiv | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.4 | F.10.11 | 144+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 145| ffma | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.5 | F.10.11 | 146+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 147| floor | |check| | |check| | |check| | |check| | |check| | 7.12.9.2 | F.10.6.2 | 148+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 149| fmax | |check| | |check| | |check| | |check| | |check| | 7.12.12.2 | F.10.9.2 | 150+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 151| fmaximum | |check| | |check| | |check| | |check| | |check| | 7.12.12.4 | F.10.9.4 | 152+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 153| fmaximum_mag | |check| | |check| | |check| | |check| | |check| | 7.12.12.6 | F.10.9.4 | 154+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 155| fmaximum_mag_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.10 | F.10.9.5 | 156+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 157| fmaximum_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.8 | F.10.9.5 | 158+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 159| fmin | |check| | |check| | |check| | |check| | |check| | 7.12.12.3 | F.10.9.3 | 160+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 161| fminimum | |check| | |check| | |check| | |check| | |check| | 7.12.12.5 | F.10.9.4 | 162+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 163| fminimum_mag | |check| | |check| | |check| | |check| | |check| | 7.12.12.7 | F.10.9.4 | 164+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 165| fminimum_mag_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.11 | F.10.9.5 | 166+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 167| fminimum_num | |check| | |check| | |check| | |check| | |check| | 7.12.12.9 | F.10.9.5 | 168+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 169| fmod | |check| | |check| | |check| | |check| | |check| | 7.12.10.1 | F.10.7.1 | 170+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 171| fmul | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.3 | F.10.11 | 172+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 173| frexp | |check| | |check| | |check| | |check| | |check| | 7.12.6.7 | F.10.3.7 | 174+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 175| fromfp | |check| | |check| | |check| | |check| | |check| | 7.12.9.10 | F.10.6.10 | 176+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 177| fromfpx | |check| | |check| | |check| | |check| | |check| | 7.12.9.11 | F.10.6.11 | 178+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 179| fsub | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.2 | F.10.11 | 180+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 181| getpayload | |check| | |check| | |check| | |check| | |check| | F.10.13.1 | N/A | 182+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 183| ilogb | |check| | |check| | |check| | |check| | |check| | 7.12.6.8 | F.10.3.8 | 184+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 185| iscanonical | |check| | |check| | |check| | |check| | |check| | 7.12.3.2 | N/A | 186+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 187| issignaling | |check| | |check| | |check| | |check| | |check| | 7.12.3.8 | N/A | 188+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 189| ldexp | |check| | |check| | |check| | |check| | |check| | 7.12.6.9 | F.10.3.9 | 190+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 191| llogb | |check| | |check| | |check| | |check| | |check| | 7.12.6.10 | F.10.3.10 | 192+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 193| llrint | |check| | |check| | |check| | |check| | |check| | 7.12.9.5 | F.10.6.5 | 194+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 195| llround | |check| | |check| | |check| | |check| | |check| | 7.12.9.7 | F.10.6.7 | 196+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 197| logb | |check| | |check| | |check| | |check| | |check| | 7.12.6.17 | F.10.3.17 | 198+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 199| lrint | |check| | |check| | |check| | |check| | |check| | 7.12.9.5 | F.10.6.5 | 200+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 201| lround | |check| | |check| | |check| | |check| | |check| | 7.12.9.7 | F.10.6.7 | 202+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 203| modf | |check| | |check| | |check| | |check| | |check| | 7.12.6.18 | F.10.3.18 | 204+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 205| nan | |check| | |check| | |check| | |check| | |check| | 7.12.11.2 | F.10.8.2 | 206+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 207| nearbyint | |check| | |check| | |check| | |check| | |check| | 7.12.9.3 | F.10.6.3 | 208+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 209| nextafter | |check| | |check| | |check| | |check| | |check| | 7.12.11.3 | F.10.8.3 | 210+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 211| nextdown | |check| | |check| | |check| | |check| | |check| | 7.12.11.6 | F.10.8.6 | 212+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 213| nexttoward | |check| | |check| | |check| | |check| | N/A | 7.12.11.4 | F.10.8.4 | 214+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 215| nextup | |check| | |check| | |check| | |check| | |check| | 7.12.11.5 | F.10.8.5 | 216+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 217| remainder | |check| | |check| | |check| | |check| | |check| | 7.12.10.2 | F.10.7.2 | 218+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 219| remquo | |check| | |check| | |check| | |check| | |check| | 7.12.10.3 | F.10.7.3 | 220+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 221| rint | |check| | |check| | |check| | |check| | |check| | 7.12.9.4 | F.10.6.4 | 222+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 223| round | |check| | |check| | |check| | |check| | |check| | 7.12.9.6 | F.10.6.6 | 224+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 225| roundeven | |check| | |check| | |check| | |check| | |check| | 7.12.9.8 | F.10.6.8 | 226+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 227| scalbln | |check| | |check| | |check| | |check| | |check| | 7.12.6.19 | F.10.3.19 | 228+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 229| scalbn | |check| | |check| | |check| | |check| | |check| | 7.12.6.19 | F.10.3.19 | 230+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 231| setpayload | |check| | |check| | |check| | |check| | |check| | F.10.13.2 | N/A | 232+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 233| setpayloadsig | |check| | |check| | |check| | |check| | |check| | F.10.13.3 | N/A | 234+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 235| totalorder | |check| | |check| | |check| | |check| | |check| | F.10.12.1 | N/A | 236+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 237| totalordermag | |check| | |check| | |check| | |check| | |check| | F.10.12.2 | N/A | 238+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 239| trunc | |check| | |check| | |check| | |check| | |check| | 7.12.9.9 | F.10.6.9 | 240+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 241| ufromfp | |check| | |check| | |check| | |check| | |check| | 7.12.9.10 | F.10.6.10 | 242+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 243| ufromfpx | |check| | |check| | |check| | |check| | |check| | 7.12.9.11 | F.10.6.11 | 244+------------------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 245 246 247Higher Math Functions 248===================== 249 250+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 251| <Func> | <Func_f> (float) | <Func> (double) | <Func_l> (long double) | <Func_f16> (float16) | <Func_f128> (float128) | C23 Definition Section | C23 Error Handling Section | 252+===========+==================+=================+========================+======================+========================+========================+============================+ 253| acos | |check| | | | | | 7.12.4.1 | F.10.1.1 | 254+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 255| acosh | |check| | | | | | 7.12.5.1 | F.10.2.1 | 256+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 257| acospi | | | | | | 7.12.4.8 | F.10.1.8 | 258+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 259| asin | |check| | | | | | 7.12.4.2 | F.10.1.2 | 260+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 261| asinh | |check| | | | | | 7.12.5.2 | F.10.2.2 | 262+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 263| asinpi | | | | | | 7.12.4.9 | F.10.1.9 | 264+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 265| atan | |check| | | | | | 7.12.4.3 | F.10.1.3 | 266+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 267| atan2 | |check| | 1 ULP | | | | 7.12.4.4 | F.10.1.4 | 268+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 269| atan2pi | | | | | | 7.12.4.11 | F.10.1.11 | 270+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 271| atanh | |check| | | | | | 7.12.5.3 | F.10.2.3 | 272+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 273| atanpi | | | | | | 7.12.4.10 | F.10.1.10 | 274+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 275| cbrt | |check| | |check| | | | | 7.12.7.1 | F.10.4.1 | 276+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 277| compoundn | | | | | | 7.12.7.2 | F.10.4.2 | 278+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 279| cos | |check| | |check| | | |check| | | 7.12.4.5 | F.10.1.5 | 280+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 281| cosh | |check| | | | |check| | | 7.12.5.4 | F.10.2.4 | 282+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 283| cospi | |check| | | | |check| | | 7.12.4.12 | F.10.1.12 | 284+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 285| dsqrt | N/A | N/A | |check| | N/A | |check|\* | 7.12.14.6 | F.10.11 | 286+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 287| erf | |check| | | | | | 7.12.8.1 | F.10.5.1 | 288+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 289| erfc | | | | | | 7.12.8.2 | F.10.5.2 | 290+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 291| exp | |check| | |check| | | |check| | | 7.12.6.1 | F.10.3.1 | 292+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 293| exp10 | |check| | |check| | | |check| | | 7.12.6.2 | F.10.3.2 | 294+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 295| exp10m1 | |check| | | | |check| | | 7.12.6.3 | F.10.3.3 | 296+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 297| exp2 | |check| | |check| | | |check| | | 7.12.6.4 | F.10.3.4 | 298+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 299| exp2m1 | |check| | | | |check| | | 7.12.6.5 | F.10.3.5 | 300+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 301| expm1 | |check| | |check| | | |check| | | 7.12.6.6 | F.10.3.6 | 302+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 303| fma | |check| | |check| | | | | 7.12.13.1 | F.10.10.1 | 304+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 305| f16sqrt | |check|\* | |check|\* | |check|\* | N/A | |check| | 7.12.14.6 | F.10.11 | 306+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 307| fsqrt | N/A | |check| | |check| | N/A | |check|\* | 7.12.14.6 | F.10.11 | 308+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 309| hypot | |check| | |check| | | | | 7.12.7.4 | F.10.4.4 | 310+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 311| lgamma | | | | | | 7.12.8.3 | F.10.5.3 | 312+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 313| log | |check| | |check| | | |check| | | 7.12.6.11 | F.10.3.11 | 314+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 315| log10 | |check| | |check| | | |check| | | 7.12.6.12 | F.10.3.12 | 316+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 317| log10p1 | | | | | | 7.12.6.13 | F.10.3.13 | 318+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 319| log1p | |check| | |check| | | | | 7.12.6.14 | F.10.3.14 | 320+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 321| log2 | |check| | |check| | | |check| | | 7.12.6.15 | F.10.3.15 | 322+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 323| log2p1 | | | | | | 7.12.6.16 | F.10.3.16 | 324+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 325| logp1 | | | | | | 7.12.6.14 | F.10.3.14 | 326+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 327| pow | |check| | 1 ULP | | | | 7.12.7.5 | F.10.4.5 | 328+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 329| powi\* | | | | | | | | 330+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 331| pown | | | | | | 7.12.7.6 | F.10.4.6 | 332+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 333| powr | | | | | | 7.12.7.7 | F.10.4.7 | 334+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 335| rootn | | | | | | 7.12.7.8 | F.10.4.8 | 336+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 337| rsqrt | | | | | | 7.12.7.9 | F.10.4.9 | 338+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 339| sin | |check| | |check| | | |check| | | 7.12.4.6 | F.10.1.6 | 340+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 341| sincos | |check| | |check| | | | | | | 342+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 343| sinh | |check| | | | |check| | | 7.12.5.5 | F.10.2.5 | 344+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 345| sinpi | |check| | | | |check| | | 7.12.4.13 | F.10.1.13 | 346+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 347| sqrt | |check| | |check| | |check| | |check| | |check| | 7.12.7.10 | F.10.4.10 | 348+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 349| tan | |check| | |check| | | |check| | | 7.12.4.7 | F.10.1.7 | 350+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 351| tanh | |check| | | | |check| | | 7.12.5.6 | F.10.2.6 | 352+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 353| tanpi | | | | |check| | | 7.12.4.14 | F.10.1.14 | 354+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 355| tgamma | | | | | | 7.12.8.4 | F.10.5.4 | 356+-----------+------------------+-----------------+------------------------+----------------------+------------------------+------------------------+----------------------------+ 357 358Legends: 359 360* |check| : correctly rounded for all 4 rounding modes. 361* CR: correctly rounded for the default rounding mode (round-to-the-nearest, 362 tie-to-even). 363* x ULPs: largest errors recorded. 364* N/A: Not defined in the standard or will not be added. 365* \*: LLVM libc extension. 366 367.. 368 TODO(lntue): Add a new page to discuss about the algorithms used in the 369 implementations and include the link here. 370 371 372Performance 373=========== 374 375* Simple performance testings are located at: `libc/test/src/math/performance_testing <https://github.com/llvm/llvm-project/tree/main/libc/test/src/math/performance_testing>`_. 376 377* We also use the *perf* tool from the `CORE-MATH <https://core-math.gitlabpages.inria.fr/>`_ 378 project: `link <https://gitlab.inria.fr/core-math/core-math/-/tree/master>`_. 379 The performance results from the CORE-MATH's perf tool are reported in the 380 table below, using the system library as reference (such as the `GNU C library <https://www.gnu.org/software/libc/>`_ 381 on Linux). Fmod performance results obtained with "performance_testing". 382 383+--------------+-------------------------------+-------------------------------+-------------------------------------+----------------------------------------------------------------------+ 384| <Func> | Reciprocal throughput (clk) | Latency (clk) | Testing ranges | Testing configuration | 385| +-----------+-------------------+-----------+-------------------+ +-------------+-------------------------+--------------+---------------+ 386| | LLVM libc | Reference (glibc) | LLVM libc | Reference (glibc) | | CPU | OS | Compiler | Special flags | 387+==============+===========+===================+===========+===================+=====================================+=============+=========================+==============+===============+ 388| acosf | 24 | 29 | 62 | 77 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 389+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 390| acoshf | 18 | 26 | 73 | 74 | :math:`[1, 21]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 391+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 392| asinf | 23 | 27 | 62 | 62 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 393+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 394| asinhf | 21 | 39 | 77 | 91 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 395+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 396| atanf | 27 | 29 | 79 | 68 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 397+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 398| atanhf | 18 | 66 | 68 | 133 | :math:`[-1, 1]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 399+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 400| cosf | 13 | 32 | 53 | 59 | :math:`[0, 2\pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 401+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 402| coshf | 14 | 20 | 50 | 48 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 403+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 404| expf | 9 | 7 | 44 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 405+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 406| exp10f | 10 | 8 | 40 | 38 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 407+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 408| exp2f | 9 | 6 | 35 | 31 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 409+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 410| expm1f | 9 | 44 | 42 | 121 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 411+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 412| fmodf | 73 | 263 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | 413| +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 414| | 9 | 11 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | 415+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 416| fmod | 595 | 3297 | - | - | [MIN_NORMAL, MAX_NORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | 417| +-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 418| | 14 | 13 | - | - | [0, MAX_SUBNORMAL] | i5 mobile | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | 419+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 420| hypotf | 25 | 15 | 64 | 49 | :math:`[-10, 10] \times [-10, 10]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | | 421+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 422| logf | 12 | 10 | 56 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 423+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 424| log10f | 9 | 17 | 35 | 48 | :math:`[e^{-1}, e]` | Ryzen 5900X | Ubuntu 22.04 LTS x86_64 | Clang 15.0.6 | FMA | 425+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 426| 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 | 427+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 428| log2f | 13 | 10 | 57 | 46 | :math:`[e^{-1}, e]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 429+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 430| sinf | 12 | 25 | 51 | 57 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 431+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 432| sincosf | 19 | 30 | 57 | 68 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 20.04 LTS x86_64 | Clang 12.0.0 | FMA | 433+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 434| sinhf | 13 | 63 | 48 | 137 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 435+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 436| tanf | 16 | 50 | 61 | 107 | :math:`[-\pi, \pi]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 437+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 438| tanhf | 13 | 55 | 57 | 123 | :math:`[-10, 10]` | Ryzen 1700 | Ubuntu 22.04 LTS x86_64 | Clang 14.0.0 | FMA | 439+--------------+-----------+-------------------+-----------+-------------------+-------------------------------------+-------------+-------------------------+--------------+---------------+ 440 441Algorithms + Implementation Details 442=================================== 443 444* :doc:`log` 445 446Fixed-point Arithmetics 447======================= 448 449* :doc:`stdfix` 450 451References 452========== 453 454* `CRLIBM <https://hal-ens-lyon.archives-ouvertes.fr/ensl-01529804/file/crlibm.pdf>`_. 455* `RLIBM <https://people.cs.rutgers.edu/~sn349/rlibm/>`_. 456* `Sollya <https://www.sollya.org/>`_. 457* `The CORE-MATH Project <https://core-math.gitlabpages.inria.fr/>`_. 458* `The GNU C Library (glibc) <https://www.gnu.org/software/libc/>`_. 459* `The GNU MPFR Library <https://www.mpfr.org/>`_. 460