1//===----------------------------------------------------------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10/// This file contains the implementation of the acoshbf16 function.
11///
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_LIBC_SRC___SUPPORT_MATH_ACOSHBF16_H
15#define LLVM_LIBC_SRC___SUPPORT_MATH_ACOSHBF16_H
16
17#include "src/__support/FPUtil/FEnvImpl.h"
18#include "src/__support/FPUtil/FPBits.h"
19#include "src/__support/FPUtil/bfloat16.h"
20#include "src/__support/FPUtil/cast.h"
21#include "src/__support/FPUtil/multiply_add.h"
22#include "src/__support/FPUtil/polyeval.h"
23#include "src/__support/FPUtil/sqrt.h"
24#include "src/__support/macros/config.h"
25#include "src/__support/macros/optimization.h"
26#include "src/__support/math/acoshf_utils.h"
27
28namespace LIBC_NAMESPACE_DECL {
29namespace math {
30
31LIBC_INLINE LIBC_CONSTEXPR bfloat16 acoshbf16(bfloat16 x) {
32 using namespace acoshf_internal;
33 using FPBits = fputil::FPBits<bfloat16>;
34
35 FPBits xbits(x);
36
37 // Handle NaNs before checking the domain. The sign of a NaN does not
38 // determine whether the input is a domain error.
39 if (LIBC_UNLIKELY(xbits.is_inf_or_nan())) {
40 if (xbits.is_signaling_nan()) {
41 fputil::raise_except_if_required(FE_INVALID);
42 return FPBits::quiet_nan().get_val();
43 }
44
45 // Negative infinity is outside the domain.
46 if (xbits.is_inf() && xbits.is_neg()) {
47 fputil::set_errno_if_required(EDOM);
48 fputil::raise_except_if_required(FE_INVALID);
49 return FPBits::quiet_nan().get_val();
50 }
51 // positive infinity and quiet NaNs are returned unchanged.
52 return x;
53 }
54
55 float xf = static_cast<float>(x);
56
57 // acosh(x) is defined for x >= 1. Its value at x = 1 is exactly zero.
58 if (LIBC_UNLIKELY(xf <= 1.0f)) {
59 if (xf == 1.0f)
60 return FPBits::zero().get_val();
61
62 fputil::set_errno_if_required(EDOM);
63 fputil::raise_except_if_required(FE_INVALID);
64 return FPBits::quiet_nan().get_val();
65 }
66
67 uint16_t x_u = xbits.uintval();
68
69 // For x close to 1, let delta = x - 1. Then
70 //
71 // acosh(1 + delta) = sqrt(2 * delta) * P(delta),
72 //
73 // where the Taylor expansion of P is
74 //
75 // P(delta) = 1 - delta / 12 + 3 * delta^2 / 160
76 // - 5 * delta^3 / 896 + O(delta^4).
77 //
78 // Factoring out sqrt(2 * delta) captures the behavior near x = 1
79 // and leaves a smooth function that can be approximated by a
80 // low-degree polynomial. This fast path uses the degree-2 Taylor
81 // polynomial
82 //
83 // P2(delta) = 1 - delta / 12 + 3 * delta^2 / 160.
84 //
85 // for delta in [0, 0.25), corresponding to 1 < x < 1.25.
86 //
87 // The following Sollya commands estimate the absolute error of this
88 // polynomial over the closed interval [0, 0.25], using the same
89 // single-precision rounded coefficients as the implementation:
90 //
91 // prec = 200;
92 // display = hexadecimal;
93 // c1 = round(-1/12, single, RN); // -0x1.555556p-4
94 // c2 = round(3/160, single, RN); // 0x1.333334p-6
95 // P2 = 1 + c1*x + c2*x^2;
96 // dirtyinfnorm(acosh(1 + x) - sqrt(2 * x) * P2, [0; 0.25]);
97 //
98 // Sollya estimated the maximum absolute approximation error over
99 // this interval (including single-precision float coefficient rounding) as:
100 //
101 // 0x1.dce3cfd50cfc0248598bad104690338afe96a2a1efe4359a3cp-15
102 // (approximately 5.68e-5, below 2^-14).
103 //
104 // The coefficients used below are rounded to float:
105 //
106 // round(1 / 12, SG, RN); // 0x1.555556p-4
107 // round(3 / 160, SG, RN); // 0x1.333334p-6
108 //
109 // Precision Context:
110 // Since bfloat16 machine epsilon is 2^-7 (~7.81e-3) and fp16 machine
111 // epsilon is 2^-10 (~9.77e-4), an error of ~5.68e-5 (< 2^-14) guarantees
112 // full precision. It does not include float-operation rounding
113 // or the final conversion to bfloat16, and it does not by itself
114 // establish correct rounding. Separately, exhaustive comparison of
115 // all 31 bfloat16 inputs in (1, 1.25) against a 100-digit acosh
116 // reference found no output mismatches for separate float
117 // multiply/add evaluation or fused multiply_add evaluation.
118 // This polynomial avoids the logarithm and provides a
119 // candidate fast path for BFloat16 inputs in (1, 1.25).
120 //
121 // The threshold 0x3FA0 is the BFloat16 encoding of 1.25.
122 if (x_u < 0x3FA0U) {
123 float delta = xf - 1.0f;
124 float sqrt_2_delta = fputil::sqrt<float>(x: 2.0f * delta);
125
126 float p = fputil::polyeval(x: delta, a0: 1.0f, a: -0x1.555556p-4f, a: 0x1.333334p-6f);
127
128 return fputil::cast<bfloat16>(x: sqrt_2_delta * p);
129 }
130
131 // Away from x = 1, evaluate
132 //
133 // acosh(x) = log(x + sqrt(x^2 - 1)).
134 //
135 // Use double precision for the intermediate calculations. In particular,
136 // this avoids overflow when squaring the largest finite BFloat16 inputs.
137 // Convert directly to BFloat16 to avoid an intermediate float rounding.
138 double xd = static_cast<double>(xf);
139 double sqrt_term = fputil::sqrt<double>(x: fputil::multiply_sub(x: xd, y: xd, z: 1.0));
140 double result = log_eval(x: xd + sqrt_term);
141
142 return fputil::cast<bfloat16>(x: result);
143}
144
145} // namespace math
146} // namespace LIBC_NAMESPACE_DECL
147
148#endif // LLVM_LIBC_SRC___SUPPORT_MATH_ACOSHBF16_H
149