Skip to content

Compute sinh, cosh, tanh, expm1 and exp2 in fixed point and round once - #1562

Open
ibmibmibm wants to merge 4 commits into
boostorg:developfrom
ibmibmibm:fixed-point-hyperbolic
Open

ibmibmibm wants to merge 4 commits into
boostorg:developfrom
ibmibmibm:fixed-point-hyperbolic

Conversation

@ibmibmibm

Copy link
Copy Markdown
Contributor
  • sinh and cosh compute exp(|x|) in the fixed point of exp, and
    exp(-|x|) from the reciprocal of its mantissa. The two parts are
    scaled to the same decimal exponent, then added or subtracted. For
    |x| < 1/16, they use the Taylor series in x^2. The result rounds
    once in the current mode.
  • tanh computes (1 - t) / (1 + t) with t = exp(-2|x|). Where t is
    below the last bit, the result is a value just below 1. For
    |x| < 1/16, it divides the two Taylor series. The result rounds
    once in the current mode.
  • expm1 computes exp(x) - 1 for x >= 1/16, with the 1 scaled to the
    decimal exponent of exp(x), and 1 - exp(x) for x <= -1/16.
    Where exp(x) is below the last bit, the result is a value just
    above -1. For |x| < 1/16, it uses the Taylor series of
    sinh(x) + cosh(x) - 1. The result rounds once in the current mode.
  • exp2 uses the fixed point of exp with log10(2) in place of
    log10(e). 2^n for an integer n is exact. A result in the
    subnormal range is no longer 0, for example exp2(-1300_DD).
  • sinh and cosh do not overflow where exp(|x|) overflows but its half
    does not, for example sinh(887_DD).
  • A subnormal x now gives the correctly rounded result, not 0. A
    signaling NaN gives the quiet NaN with the sign and payload of x.
  • Where x^2 is below the last digit of the result, sinh, cosh and
    tanh need no series: the result rounds as a value next to |x|, or
    next to 1 for cosh. expm1 does the same for |x| < 10^-p, with p
    the precision of the type.
  • exp and the five functions first compute in fewer words: one word for
    decimal64_t and two words for decimal128_t. If the result cannot
    be next to a rounding boundary, it rounds once. If not, the full
    computation runs. For decimal128_t, tanh and expm1 have this first
    try for |x| < 1/16 and for |x| >= 1/2. For decimal32_t, exp,
    exp2, sinh, cosh and tanh have a first try with a short series.
  • Next to a rounding boundary, decimal128_t computes the terms after
    the exact first term (x, or 1 for cosh, exp and exp2) in their own
    precision. This also corrects exp for decimal128_t next to a
    rounding tie, for example exp(-1e-17_DL) in round to nearest.
    github_issue_1557.cpp gets this input.
  • fx_recip and fx_div divide in fixed point. fx_shr, fx_horner,
    fx_int, fx_mul_shr and fx_extend are new helpers. For a
    significand of two words, fx_round divides one time and gets the
    rounding digit from the rest. test_fixed_point.cpp compares
    fx_recip with schoolbook arithmetic for one to five words.
  • The reciprocal in impl/tan_impl.hpp gets the name
    recip_below_one, so that its name is different from fx_recip.
  • The series in impl/sinh_impl.hpp, impl/cosh_impl.hpp,
    impl/tanh_impl.hpp and impl/expm1_impl.hpp have no more users and
    are removed.
  • The new tests github_issue_1561_sinh.cpp, github_issue_1561_tanh.cpp,
    github_issue_1561_expm1.cpp and github_issue_1561_exp2.cpp check hard cases
    in all five modes for each type.
  • test_cmath_bound_cases.cpp holds inputs that give a wrong result if
    an error bound of a first try gets smaller, in all rounding modes. A
    program checked the expected values against MPFR. The test needs no
    MPFR.
  • test_first_try_bounds.cpp compares the first tries of exp and exp2
    with three words, against the error bounds in the library.

Fixes #1561

Accuracy

The test takes 20000 random x per range, with a full significand and a random sign, for each function, each type and each of the five rounding modes. The ranges of |x| are those of the speed tables, and the subnormal range. MPFR gives the exact value. develop gives up to 100% of incorrect results in a range. The branch gives 0 incorrect results in all ranges, types and modes.

Speed

ns per call, best of 3 runs, GCC 16.2.1 -O2, AMD Ryzen 9 3900X. The inputs have a full significand and a random sign.

sinh:

Range of |x| decimal32_t develop branch decimal64_t develop branch decimal128_t develop branch
[1e-20, 1e-3) 73 10 322 27 2009 96
[1e-3, 1) 105 26 387 46 1805 125
[1, 10) 96 34 153 52 313 138
[10, 100) 85 30 143 44 306 127
[100, overflow) 83 31 136 45 282 119

cosh:

Range of |x| decimal32_t develop branch decimal64_t develop branch decimal128_t develop branch
[1e-20, 1e-3) 74 7 316 22 1945 91
[1e-3, 1) 105 26 372 40 1757 121
[1, 10) 102 34 160 51 318 142
[10, 100) 91 30 152 44 309 126
[100, overflow) 87 31 145 45 288 119

tanh:

Range of |x| decimal32_t develop branch decimal64_t develop branch decimal128_t develop branch
[1e-20, 1e-3) 105 11 404 30 2613 138
[1e-3, 1) 122 33 382 55 1777 172
[1, 10) 109 35 168 56 354 139
[10, 100) 88 12 153 26 331 81
[100, overflow) 40 8 69 19 216 28

expm1:

Range of |x| decimal32_t develop branch decimal64_t develop branch decimal128_t develop branch
[1e-20, 1e-3) 106 11 458 47 4043 124
[1e-3, 1) 151 29 440 48 2904 151
[1, 10) 66 34 114 48 232 129
[10, 100) 59 24 109 44 237 125
[100, overflow) 56 22 96 43 194 85

exp2:

Range of |x| decimal32_t develop branch decimal64_t develop branch decimal128_t develop branch
[1e-20, 1e-3) 380 16 762 46 2783 98
[1e-3, 1) 395 31 770 45 2794 101
[1, 10) 409 30 796 42 2838 114
[10, 100) 409 30 796 41 2841 113
[100, overflow) 410 32 796 42 2842 114

For |x| >= 1, sinh and cosh computed exp(x) in the decimal type and
then (exp(x) -+ 1 / exp(x)) / 2, which rounds four times. For |x| < 1,
they used a Taylor series in the decimal type, which rounds at each
step. Thus the last digit was often wrong. Also, exp(x) overflowed
before the division by two, thus sinh(887) gave infinity for
decimal64_t. The rounding mode had no effect.

Now sinh and cosh use the fixed point of exp:

- For |x| < 1/16, the Taylor series of sinh(x) / x and cosh(x) in
  x^2, whose terms are all positive.
- Else exp(|x|) from the reduction y = |x| log10(e), and exp(-|x|)
  from the reciprocal of its mantissa: 10^(1 - f) / 8 = 5/4 * 2^-a / m.
  The two are scaled to the same decimal exponent, then added or
  subtracted. Where exp(-|x|) is below the last bit, it is left out.

fx_round rounds the result once in the current mode.

fx_recip divides in fixed point. In one word, its guess comes from
udiv_2by1, one hardware division. In N words, one Newton step starts
from the result in N - 1 words. test_fixed_point compares fx_recip
with schoolbook arithmetic for one to five words.

exp_fixed is split into parts that sinh and cosh share. exp_whole
divides in 64 bits where the significand fits. fx_shr, fx_horner,
fx_int, fx_mul_shr and fx_extend are new helpers, fx_top moves to
fixed_point.hpp, and the 1/n! table goes to 1/23!. The series in
impl/sinh_impl.hpp and impl/cosh_impl.hpp have no more users and are
removed.

sinh and cosh gave 0 for a subnormal x, because the test for special
values let only a normal x through. Now a subnormal x takes the fixed-
point path too.

For decimal128_t and |x| from 10^-16 to 1/16, the series run in two
words first, with more terms than for decimal64_t. If the result
cannot be next to a rounding boundary, it rounds once. Else the
three-word series runs. Below 10^-16, the result is always next to a
boundary.

Next to a rounding boundary, decimal128_t computes the terms past the
exact lead term x, or 1 for cosh, in their own precision. Where the
first terms sum to an exact decimal, the rest then decides the side.

Where x^2 is below the last digit of the result, sinh and cosh need
no series: sinh(x) rounds as a value just above |x|, and cosh(x) as a
value just above 1. fx_tiny_digits gives this limit, and
fx_round_next_to_x rounds such a value once.

For a signaling NaN x, sinh gives the quiet NaN with the sign and
payload of x.

For a significand of two words, fx_round divides one time and gets
the rounding digit from the rest. The products of the Newton step of
fx_recip are inlined. In two words, the guess of the step has a low
word of zero, and the compiler then removes the multiplications by
that word.

test_cmath_bound_cases holds inputs that give a wrong result if an
error bound of a first try gets smaller, in all rounding modes. A
program checked the expected values against MPFR. The test needs no
MPFR.

Fixes boostorg#1561
For |x| >= 1/4, tanh computed exp(x) and 1 / exp(x) in the decimal
type, then their difference divided by their sum. For |x| < 1/4, it
used a Taylor series in the decimal type. Each step rounds, thus the
last digit was often wrong. The rounding mode had no effect.

Now tanh uses the fixed point of exp:

- For |x| < 1/16, x times the Taylor series of sinh(x) / x divided by
  the Taylor series of cosh(x).
- Else (1 - t) / (1 + t) with t = exp(-2|x|), from the reduction
  y = |x| log10(e). Where t is below the last bit, the result is a
  value just below 1.

The two divisions use the new fx_div. In one word it takes one hardware
division, and in more words it multiplies by fx_recip from sinh and
cosh. fx_round rounds the result once in the current mode. As
tanh(x) < x for x > 0, the digits from the series stay below those of x.

The reciprocal in tan_impl.hpp becomes recip_below_one, so that its name
is different from fx_recip.

The series in impl/tanh_impl.hpp has no more users and is removed.

tanh gave 0 for a subnormal x, because the test for special values let
only a normal x through. Now a subnormal x takes the fixed-point path
too.

For decimal128_t and |x| from 10^-16 to 1/16, the series run in two
words first, with more terms than for decimal64_t. If the result
cannot be next to a rounding boundary, it rounds once. Else the
three-word series runs. Below 10^-16, the result is always next to a
boundary.

Next to a rounding boundary, decimal128_t computes the terms past the
exact lead term x in their own precision. Where the first terms sum to
an exact decimal, the rest then decides the side.

Where x^2 is below the last digit of the result, tanh needs no
series: tanh(x) rounds as a value just below |x|.

For a signaling NaN x, tanh gives the quiet NaN with the sign and
payload of x.

test_cmath_bound_cases gets the inputs next to the error bounds of
these functions.

Fixes boostorg#1561
For |x| > ln(2), expm1 computed exp(x) - 1 or 1 / exp(-x) - 1 in the
decimal type. For smaller |x|, it used a series in the decimal type.
Each step rounds, thus the last digit was often wrong. The rounding
mode had no effect.

Now expm1 uses the fixed point of exp:

- For |x| < 1/16, expm1(x) = sinh(x) + cosh(x) - 1, from the Taylor
  series of sinh(x) / x and (cosh(x) - 1) / x^2.
- For x >= 1/16, exp(x) - 1 with the 1 scaled to the decimal exponent
  of exp(x).
- For x <= -1/16, 1 - exp(x). Where exp(x) is below the last bit, the
  result is a value just above -1.

fx_round rounds the result once in the current mode. As
|expm1(x)| < |x| for x < 0, the digits from the series stay below
those of x.

exp_head takes the first index and the step as template arguments,
and a static_assert makes sure that the coefficients are in the 1/n!
table. The series in impl/expm1_impl.hpp has no more users and is
removed.

expm1 gave 0 for a subnormal x, because the test for special values let
only a normal x through. Now a subnormal x takes the fixed-point path
too.

For decimal128_t and |x| < 1/16, the series run in two words first,
with more terms than for decimal64_t. If the result cannot be next to
a rounding boundary, it rounds once. Else the three-word series runs.

Next to a rounding boundary, decimal128_t computes the terms past the
exact lead term x in their own precision. Where the first terms sum to
an exact decimal, the rest then decides the side.

For |x| < 10^-p, with p the precision of the type, expm1 needs no
series: expm1(x) rounds as a value just above x.

For a signaling NaN x, expm1 gives the quiet NaN with the sign and
payload of x.

test_cmath_bound_cases gets the inputs next to the error bounds of
these functions.

Fixes boostorg#1561
exp2(x) was pow(2, x), which computes exp(x * ln(2)) in the decimal
type and rounds at each step. The error grows with |x|, thus the
last digits were wrong for large |x|. The rounding mode had no
effect.

Now exp2 uses the fixed point of exp with log10(2) in place of
log10(e): y = x * log10(2) = k + f, and 2^x = 10^k * 10^f. fx_round
rounds the result once in the current mode.

2^n for an integer n is exact. Where 2^n or 5^-n fits in 128 bits,
the constructor rounds it from the exact value, thus a tie rounds as
a tie. For other x, 2^x is never exact, as fx_round needs.
x = sig * 10^-k can be an integer only if 2^k divides sig. This test
of the low bits skips the division for almost all other x.

exp_bound and exp_fixed take Base2 as a template argument, and
exp_log10 takes the constant.

For decimal128_t, exp and exp2 compute in two words first, with more
terms of the series of exp(-z) than for decimal64_t. If the result
cannot be next to a rounding boundary, it rounds once. Else the
three-word computation runs. exp10_frac takes this series with Wide.

For decimal64_t, exp and exp2 compute in one word first. If
fx_try_round finds that the result of 19 digits cannot be next to a
rounding boundary and is not subnormal, it rounds once. Else the
two-word computation runs.

For decimal64_t, sinh, cosh, tanh and expm1 also compute in one word
first. Below 1, sinh and expm1 use a longer series in one word, and tanh
uses one below 1/2, where the form with exp loses digits. exp_try_round
rounds the product of an exact integer and such a series once where it
cannot be next to a rounding boundary. sinh_cosh_parts, tanh_quotient
and expm1_large hold the steps that the first try and the full
computation share. tanh_small and expm1_small return the series without
the scale. The error bound of exp in one word comes from the error of
each step, thus it is smaller. For expm1, all steps truncate, so the
error is almost all below the exact value, and the first try moves the
result to the middle of the bound.

For decimal128_t, sinh and cosh, and tanh and expm1 for |x| from 1/2,
compute in two words first in the same way. sinh_cosh_parts,
tanh_quotient and expm1_large take Wide for this. decimal_at_least
compares x with 1/2. Below 1, sinh uses a longer series in two words,
and inv_factorial holds more terms for it.

For decimal32_t, exp and exp2 first take 10^f with the series of
exp(-z) only to z^3, with Short in exp10_frac. fx_try_round finds the
rounding boundaries from the precision of the type, so that it serves
decimal32_t too. For |x| >= 1/16, sinh, cosh and tanh take the same
short series in a first try. sinh and cosh get 10^f and 10^(1 - f)
from exp10_frac_pair, with no division.

Next to a rounding boundary for a small x, decimal128_t exp and exp2
compute the terms past the exact lead term 1 in their own precision,
as 1 + x expm1(x) / x.

For a signaling NaN x, exp2 gives the quiet NaN with the sign and
payload of x.

test_first_try_bounds compares the first tries of exp and exp2 with
three words, against the error bounds in the library.
test_cmath_bound_cases gets the inputs next to the error bounds of
exp and exp2.

Fixes boostorg#1561
@ibmibmibm
ibmibmibm force-pushed the fixed-point-hyperbolic branch from 6410b07 to 5d15603 Compare November 16, 2026 01:30
@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 95.81994% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.4%. Comparing base (215bbf0) to head (24e14c1).

Files with missing lines Patch % Lines
test/test_cmath_bound_cases.cpp 39.7% 35 Missing ⚠️
...clude/boost/decimal/detail/cmath/impl/exp_impl.hpp 98.5% 2 Missing ⚠️
test/test_first_try_bounds.cpp 94.9% 2 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff            @@
##           develop   #1562     +/-   ##
=========================================
- Coverage     98.6%   98.4%   -0.1%     
=========================================
  Files          344     346      +2     
  Lines        29218   30044    +826     
  Branches      2405    2477     +72     
=========================================
+ Hits         28782   29560    +778     
- Misses         436     484     +48     
Files with missing lines Coverage Δ
include/boost/decimal/detail/cmath/cosh.hpp 100.0% <100.0%> (ø)
include/boost/decimal/detail/cmath/exp.hpp 100.0% <ø> (ø)
include/boost/decimal/detail/cmath/exp2.hpp 100.0% <100.0%> (ø)
include/boost/decimal/detail/cmath/expm1.hpp 100.0% <100.0%> (ø)
...de/boost/decimal/detail/cmath/impl/fixed_point.hpp 99.1% <100.0%> (+1.3%) ⬆️
...clude/boost/decimal/detail/cmath/impl/tan_impl.hpp 100.0% <100.0%> (ø)
include/boost/decimal/detail/cmath/sinh.hpp 100.0% <100.0%> (ø)
include/boost/decimal/detail/cmath/tanh.hpp 100.0% <100.0%> (ø)
test/github_issue_1557.cpp 100.0% <100.0%> (ø)
test/github_issue_1561_exp2.cpp 100.0% <100.0%> (ø)
... and 7 more

... and 3 files with indirect coverage changes


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 215bbf0...24e14c1. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ibmibmibm
ibmibmibm force-pushed the fixed-point-hyperbolic branch from 5d15603 to 24e14c1 Compare November 16, 2026 08:45
@ibmibmibm
ibmibmibm marked this pull request as ready for review November 16, 2026 09:55

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

sinh, cosh, tanh, expm1 and exp2 give incorrect results, and 0 or infinity for some finite results

1 participant