Skip to content

Commit 5e476b3

Browse files
authored
GH-44903: [C++] Add the Expm1(exponent) scalar arithmetic function (#44904)
`Expm1(exponent)` is a more accurate way of computing `Exp(exponent) - 1.0` for small values of exponent. ### Rationale for this change `expm1(x)` is specifically designed to compute `exp(x)−1` more accurately, particularly for small x. It uses numerical techniques and approximations that minimize the loss of precision. When x is very small (close to 0), `exp(x)` is approximately `1+x`. Subtracting 1 from `exp(x)` (i.e., `(exp(x)−1)` can result in significant cancellation of significant digits due to floating-point arithmetic, leading to a loss of precision). For example: When `x = 10^−8`, `exp(x)` is close to `1 + 10^−8`, so subtracting 1 leaves only the small `10^−8`, which may lose accuracy due to floating-point limitations. ### Are these changes tested? Yes. ### Are there any user-facing changes? Yes and documentation was updated to list the new function. * GitHub Issue: #44903 Authored-by: Felipe Oliveira Carvalho <[email protected]> Signed-off-by: Felipe Oliveira Carvalho <[email protected]>
1 parent 1838d0a commit 5e476b3

6 files changed

Lines changed: 133 additions & 4 deletions

File tree

‎cpp/src/arrow/compute/api_scalar.cc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -744,6 +744,7 @@ SCALAR_ARITHMETIC_UNARY(Sin, "sin", "sin_checked")
744744
SCALAR_ARITHMETIC_UNARY(Tan, "tan", "tan_checked")
745745
SCALAR_EAGER_UNARY(Atan, "atan")
746746
SCALAR_EAGER_UNARY(Exp, "exp")
747+
SCALAR_EAGER_UNARY(Expm1, "expm1")
747748
SCALAR_EAGER_UNARY(Sign, "sign")
748749

749750
Result<Datum> Round(const Datum& arg, RoundOptions options, ExecContext* ctx) {

‎cpp/src/arrow/compute/api_scalar.h‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -684,6 +684,18 @@ Result<Datum> Power(const Datum& left, const Datum& right,
684684
ARROW_EXPORT
685685
Result<Datum> Exp(const Datum& arg, ExecContext* ctx = NULLPTR);
686686

687+
/// \brief More accurately calculate `exp(arg) - 1` for values close to zero.
688+
/// If the exponent value is null the result will be null.
689+
///
690+
/// This function is more accurate than calculating `exp(value) - 1` directly for values
691+
/// close to zero.
692+
///
693+
/// \param[in] arg the exponent
694+
/// \param[in] ctx the function execution context, optional
695+
/// \return the element-wise Euler's number raised to the power of exponent minus 1
696+
ARROW_EXPORT
697+
Result<Datum> Expm1(const Datum& arg, ExecContext* ctx = NULLPTR);
698+
687699
/// \brief Left shift the left array by the right array. Array values must be the
688700
/// same length. If either operand is null, the result will be null.
689701
///

‎cpp/src/arrow/compute/kernels/base_arithmetic_internal.h‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -532,6 +532,14 @@ struct Exp {
532532
}
533533
};
534534

535+
struct Expm1 {
536+
template <typename T, typename Arg>
537+
static T Call(KernelContext*, Arg exp, Status*) {
538+
static_assert(std::is_same<T, Arg>::value);
539+
return std::expm1(exp);
540+
}
541+
};
542+
535543
struct Power {
536544
ARROW_NOINLINE
537545
static uint64_t IntegerPower(uint64_t base, uint64_t exp) {

‎cpp/src/arrow/compute/kernels/scalar_arithmetic.cc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1087,6 +1087,12 @@ const FunctionDoc exp_doc{
10871087
("If exponent is null the result will be null."),
10881088
{"exponent"}};
10891089

1090+
const FunctionDoc expm1_doc{
1091+
"Compute Euler's number raised to the power of specified exponent, "
1092+
"then decrement 1, element-wise",
1093+
("If exponent is null the result will be null."),
1094+
{"exponent"}};
1095+
10901096
const FunctionDoc pow_checked_doc{
10911097
"Raise arguments to power element-wise",
10921098
("An error is returned when integer to negative integer power is encountered,\n"
@@ -1614,6 +1620,10 @@ void RegisterScalarArithmetic(FunctionRegistry* registry) {
16141620
auto exp = MakeUnaryArithmeticFunctionFloatingPoint<Exp>("exp", exp_doc);
16151621
DCHECK_OK(registry->AddFunction(std::move(exp)));
16161622

1623+
// ----------------------------------------------------------------------
1624+
auto expm1 = MakeUnaryArithmeticFunctionFloatingPoint<Expm1>("expm1", expm1_doc);
1625+
DCHECK_OK(registry->AddFunction(std::move(expm1)));
1626+
16171627
// ----------------------------------------------------------------------
16181628
auto sqrt = MakeUnaryArithmeticFunctionFloatingPoint<SquareRoot>("sqrt", sqrt_doc);
16191629
DCHECK_OK(registry->AddFunction(std::move(sqrt)));

‎cpp/src/arrow/compute/kernels/scalar_arithmetic_test.cc‎

Lines changed: 100 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ namespace arrow {
4343
namespace compute {
4444
namespace {
4545

46+
// 2.718281828459045090795598298427648842334747314453125
47+
constexpr double kEuler64 = 0x1.5bf0a8b145769p+1;
48+
4649
using IntegralTypes = testing::Types<Int8Type, Int16Type, Int32Type, Int64Type, UInt8Type,
4750
UInt16Type, UInt32Type, UInt64Type>;
4851

@@ -1485,8 +1488,7 @@ TYPED_TEST(TestUnaryArithmeticUnsigned, Exp) {
14851488
this->AssertUnaryOp(
14861489
exp, "[null, 1, 10]",
14871490
ArrayFromJSON(float64(), "[null, 2.718281828459045, 22026.465794806718]"));
1488-
this->AssertUnaryOp(exp, this->MakeScalar(1),
1489-
arrow::MakeScalar<double>(2.718281828459045F));
1491+
this->AssertUnaryOp(exp, this->MakeScalar(1), arrow::MakeScalar(kEuler64));
14901492
}
14911493

14921494
TYPED_TEST(TestUnaryArithmeticSigned, Exp) {
@@ -1502,8 +1504,7 @@ TYPED_TEST(TestUnaryArithmeticSigned, Exp) {
15021504
ArrayFromJSON(float64(),
15031505
"[0.000045399929762484854, 0.36787944117144233, "
15041506
"null, 2.718281828459045, 22026.465794806718]"));
1505-
this->AssertUnaryOp(exp, this->MakeScalar(1),
1506-
arrow::MakeScalar<double>(2.718281828459045F));
1507+
this->AssertUnaryOp(exp, this->MakeScalar(1), arrow::MakeScalar(kEuler64));
15071508
}
15081509

15091510
TYPED_TEST(TestUnaryArithmeticFloating, Exp) {
@@ -1563,6 +1564,101 @@ TEST_F(TestUnaryArithmeticDecimal, Exp) {
15631564
}
15641565
}
15651566

1567+
TYPED_TEST(TestUnaryArithmeticUnsigned, Expm1) {
1568+
auto expm1 = [](const Datum& arg, ArithmeticOptions, ExecContext* ctx) {
1569+
return Expm1(arg, ctx);
1570+
};
1571+
// Empty arrays
1572+
this->AssertUnaryOp(expm1, "[]", ArrayFromJSON(float64(), "[]"));
1573+
// Array with nulls
1574+
this->AssertUnaryOp(expm1, "[null]", ArrayFromJSON(float64(), "[null]"));
1575+
this->AssertUnaryOp(expm1, this->MakeNullScalar(), arrow::MakeNullScalar(float64()));
1576+
this->AssertUnaryOp(
1577+
expm1, "[null, 0, 1, 10]",
1578+
ArrayFromJSON(float64(), "[null, 0.0, 1.718281828459045, 22025.465794806718]"));
1579+
this->AssertUnaryOp(expm1, this->MakeScalar(1), arrow::MakeScalar(kEuler64 - 1.0));
1580+
}
1581+
1582+
TYPED_TEST(TestUnaryArithmeticSigned, Expm1) {
1583+
auto expm1 = [](const Datum& arg, ArithmeticOptions, ExecContext* ctx) {
1584+
return Expm1(arg, ctx);
1585+
};
1586+
// Empty arrays
1587+
this->AssertUnaryOp(expm1, "[]", ArrayFromJSON(float64(), "[]"));
1588+
// Array with nulls
1589+
this->AssertUnaryOp(expm1, "[null]", ArrayFromJSON(float64(), "[null]"));
1590+
this->AssertUnaryOp(expm1, this->MakeNullScalar(), arrow::MakeNullScalar(float64()));
1591+
this->AssertUnaryOp(expm1, "[-10, -1, 0, null, 1, 10]",
1592+
ArrayFromJSON(float64(),
1593+
"[-0.9999546000702375, -0.6321205588285577, 0.0, "
1594+
"null, 1.718281828459045, 22025.465794806718]"));
1595+
this->AssertUnaryOp(expm1, this->MakeScalar(1), arrow::MakeScalar(kEuler64 - 1.0));
1596+
}
1597+
1598+
TYPED_TEST(TestUnaryArithmeticFloating, Expm1) {
1599+
using CType = typename TestFixture::CType;
1600+
1601+
auto min = std::numeric_limits<CType>::lowest();
1602+
auto max = std::numeric_limits<CType>::max();
1603+
1604+
auto expm1 = [](const Datum& arg, ArithmeticOptions, ExecContext* ctx) {
1605+
return Expm1(arg, ctx);
1606+
};
1607+
// Empty arrays
1608+
this->AssertUnaryOp(expm1, "[]", "[]");
1609+
// Array with nulls
1610+
this->AssertUnaryOp(expm1, "[null]", "[null]");
1611+
this->AssertUnaryOp(expm1, this->MakeNullScalar(), this->MakeNullScalar());
1612+
this->AssertUnaryOp(expm1, "[-1.0, 0.0, 0.1, 0.00000001, null, 10.0]",
1613+
"[-0.6321205588285577, 0.0, "
1614+
"0.10517091807564763, 0.000000010000000050000001, "
1615+
"null, 22025.465794806718]");
1616+
// Ordinary arrays (positive, negative, fractional, and zero inputs)
1617+
this->AssertUnaryOp(expm1, "[-10.0, 0.0, 0.1, 0.00000001, 0.5, 1.0]",
1618+
"[-0.9999546000702375, 0.0, "
1619+
"0.10517091807564763, 0.000000010000000050000001, "
1620+
"0.6487212707001282, 1.718281828459045]");
1621+
this->AssertUnaryOp(expm1, 1.3F, 2.6692964926535487F);
1622+
this->AssertUnaryOp(expm1, this->MakeScalar(1.3F),
1623+
this->MakeScalar(2.6692964926535487F));
1624+
// Arrays with infinites
1625+
this->AssertUnaryOp(expm1, "[-Inf, Inf]", "[-1, Inf]");
1626+
// Arrays with NaNs
1627+
this->SetNansEqual(true);
1628+
this->AssertUnaryOp(expm1, "[NaN]", "[NaN]");
1629+
// Min/max
1630+
this->AssertUnaryOp(expm1, min, -1.0);
1631+
this->AssertUnaryOp(expm1, max, std::numeric_limits<CType>::infinity());
1632+
}
1633+
1634+
TEST_F(TestUnaryArithmeticDecimal, Expm1) {
1635+
auto max128 = Decimal128::GetMaxValue(38);
1636+
auto max256 = Decimal256::GetMaxValue(76);
1637+
const auto func = "expm1";
1638+
for (const auto& ty : PositiveScaleTypes()) {
1639+
CheckScalar(func, {ArrayFromJSON(ty, R"([])")}, ArrayFromJSON(float64(), "[]"));
1640+
CheckScalar(
1641+
func, {ArrayFromJSON(ty, R"(["-1.00", "0.00", "0.10", "0.01", "10.00", null])")},
1642+
ArrayFromJSON(float64(),
1643+
"[-0.6321205588285577, 0.0, "
1644+
"0.10517091807564763, 0.010050167084168058, "
1645+
"22025.465794806718, null]"));
1646+
}
1647+
CheckScalar(func, {std::make_shared<Decimal128Scalar>(max128, decimal128(38, 0))},
1648+
ScalarFromJSON(float64(), "Inf"));
1649+
CheckScalar(func, {std::make_shared<Decimal128Scalar>(-max128, decimal128(38, 0))},
1650+
ScalarFromJSON(float64(), "-1.0"));
1651+
CheckScalar(func, {std::make_shared<Decimal256Scalar>(max256, decimal256(76, 0))},
1652+
ScalarFromJSON(float64(), "Inf"));
1653+
CheckScalar(func, {std::make_shared<Decimal256Scalar>(-max256, decimal256(76, 0))},
1654+
ScalarFromJSON(float64(), "-1.0"));
1655+
for (const auto& ty : NegativeScaleTypes()) {
1656+
CheckScalar(func, {ArrayFromJSON(ty, R"([])")}, ArrayFromJSON(float64(), "[]"));
1657+
CheckScalar(func, {DecimalArrayFromJSON(ty, R"(["12E2", "0", "-42E2", null])")},
1658+
ArrayFromJSON(float64(), "[Inf, 0.0, -1.0, null]"));
1659+
}
1660+
}
1661+
15661662
TEST_F(TestUnaryArithmeticDecimal, Log) {
15671663
std::vector<std::string> unchecked = {"ln", "log2", "log10", "log1p"};
15681664
std::vector<std::string> checked = {"ln_checked", "log2_checked", "log10_checked",

‎docs/source/cpp/compute.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,8 @@ Mixed time resolution temporal inputs will be cast to finest input resolution.
476476
+------------------+--------+-------------------------+---------------------------+-------+
477477
| exp | Unary | Numeric | Float32/Float64 | |
478478
+------------------+--------+-------------------------+---------------------------+-------+
479+
| expm1 | Unary | Numeric | Float32/Float64 | |
480+
+------------------+--------+-------------------------+---------------------------+-------+
479481
| multiply | Binary | Numeric/Temporal | Numeric/Temporal | \(1) |
480482
+------------------+--------+-------------------------+---------------------------+-------+
481483
| multiply_checked | Binary | Numeric/Temporal | Numeric/Temporal | \(1) |

0 commit comments

Comments
 (0)