Math Functions

Inside kernels, prefer alpaka::math over calling backend-specific math APIs or C++ std math functions directly. alpaka provides a wide range of mathematical functions in the alpaka::math namespace. These enable a portable codebase while delivering the best possible performance for the data types used. To this end, alpaka uses the native math functions of the API (e.g., CUDA built-in math functions) with which a kernel is executed, whenever available. alpaka math functions can also be used in host code outside of kernels.

Element-wise Math

The example is similar to the vector addition: iterate over the data with makeIdxMap and call math functions on each element.

struct TrigIdentityKernel
{
    ALPAKA_FN_ACC void operator()(
        onAcc::concepts::Acc auto const& acc,
        concepts::IMdSpan<float> auto out,
        concepts::IDataSource<float> auto const& angles) const
    {
        for(auto i : onAcc::makeIdxMap(acc, onAcc::worker::threadsInGrid, IdxRange{angles.getExtents()}))
        {
            float sine{};
            float cosine{};
            math::sincos(angles[i], sine, cosine);
            out[i] = math::fma(sine, sine, cosine * cosine);
        }
    }
};

Distance-like Computations

Reciprocal square root is another common operation in physics, graphics, and geometry kernels.

struct DistanceKernel
{
    ALPAKA_FN_ACC void operator()(
        onAcc::concepts::Acc auto const& acc,
        concepts::IMdSpan<float> auto out,
        concepts::IDataSource<float> auto const& input) const
    {
        for(auto i : onAcc::makeIdxMap(acc, onAcc::worker::threadsInGrid, IdxRange{input.getExtents()}))
        {
            auto const squaredLength = math::fma(input[i], input[i], 1.0f);
            out[i] = math::rsqrt(squaredLength);
        }
    }
};

Available Function Families

Complete Source File

140_math.cpp
 1/* Copyright 2026 René Widera
 2 * SPDX-License-Identifier: ISC
 3 */
 4
 5#include "docsTest.hpp"
 6
 7#include <alpaka/alpaka.hpp>
 8
 9#include <catch2/catch_approx.hpp>
10#include <catch2/catch_template_test_macros.hpp>
11#include <catch2/catch_test_macros.hpp>
12
13#include <array>
14#include <cmath>
15
16using namespace alpaka;
17
18struct TrigIdentityKernel
19{
20    ALPAKA_FN_ACC void operator()(
21        onAcc::concepts::Acc auto const& acc,
22        concepts::IMdSpan<float> auto out,
23        concepts::IDataSource<float> auto const& angles) const
24    {
25        for(auto i : onAcc::makeIdxMap(acc, onAcc::worker::threadsInGrid, IdxRange{angles.getExtents()}))
26        {
27            float sine{};
28            float cosine{};
29            math::sincos(angles[i], sine, cosine);
30            out[i] = math::fma(sine, sine, cosine * cosine);
31        }
32    }
33};
34
35
36struct DistanceKernel
37{
38    ALPAKA_FN_ACC void operator()(
39        onAcc::concepts::Acc auto const& acc,
40        concepts::IMdSpan<float> auto out,
41        concepts::IDataSource<float> auto const& input) const
42    {
43        for(auto i : onAcc::makeIdxMap(acc, onAcc::worker::threadsInGrid, IdxRange{input.getExtents()}))
44        {
45            auto const squaredLength = math::fma(input[i], input[i], 1.0f);
46            out[i] = math::rsqrt(squaredLength);
47        }
48    }
49};
50
51
52TEMPLATE_LIST_TEST_CASE("tutorial math functions on device", "[docs]", docs::test::TestBackends)
53{
54    auto selector = onHost::makeDeviceSelector(TestType::makeDict());
55    if(!selector.isAvailable())
56        return;
57    onHost::concepts::Device auto device = selector.makeDevice(0);
58    onHost::Queue queue = device.makeQueue();
59
60    std::array<float, 4u> hostAngles{0.0f, 0.5f, 1.0f, 1.5f};
61    std::array<float, 4u> hostTrig{};
62    std::array<float, 4u> hostInvLen{};
63
64    auto angleBuffer = onHost::allocLike(device, hostAngles);
65    auto trigBuffer = onHost::allocLike(device, hostAngles);
66    auto invLenBuffer = onHost::allocLike(device, hostAngles);
67
68    onHost::memcpy(queue, angleBuffer, hostAngles);
69
70    onHost::concepts::FrameSpec auto frameSpec = onHost::FrameSpec{1u, 64u};
71    queue.enqueue(frameSpec, KernelBundle{TrigIdentityKernel{}, trigBuffer, angleBuffer});
72    queue.enqueue(frameSpec, KernelBundle{DistanceKernel{}, invLenBuffer, angleBuffer});
73
74    onHost::memcpy(queue, hostTrig, trigBuffer);
75    onHost::memcpy(queue, hostInvLen, invLenBuffer);
76    onHost::wait(queue);
77
78    for(auto value : hostTrig)
79    {
80        CHECK(value == Catch::Approx(1.0f).margin(5e-6f));
81    }
82
83    for(size_t i = 0; i < hostAngles.size(); ++i)
84    {
85        auto expected = 1.0f / std::sqrt(hostAngles[i] * hostAngles[i] + 1.0f);
86        CHECK(hostInvLen[i] == Catch::Approx(expected).margin(5e-6f));
87    }
88}