From e66eca10a0b122dbaa5e1b82b665312c78d20500 Mon Sep 17 00:00:00 2001 From: "marko.vucicevic" Date: Mon, 15 Jan 2024 09:21:33 +0100 Subject: [PATCH 1/2] Updated BIF native precision math functions Issue: KHRGA-114 --- source/iface/native-prec-math-func.rst | 404 +++++++++++++++++++++++++ 1 file changed, 404 insertions(+) diff --git a/source/iface/native-prec-math-func.rst b/source/iface/native-prec-math-func.rst index 7507b44c..055dadbc 100644 --- a/source/iface/native-prec-math-func.rst +++ b/source/iface/native-prec-math-func.rst @@ -7,3 +7,407 @@ ******************************* Native precision math functions ******************************* + +In SYCL the implementation-defined precision math functions are defined in the +namespace ``sycl::native``. The functions that are available within this +namespace are specified in the list below. + +The range of valid input values and the maximum error for these functions +is implementation defined. + +``cos`` +======= + +:: + + float cos(float x) (1) + + template (2) + /*return-type*/ cos(NonScalar x) + +Overload (1): + +Returns: The cosine of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +NonScalar is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the cosine of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``divide`` +========== + +:: + + float divide(float x, float y) (1) + + template (2) + /*return-type*/ divide(NonScalar1 x, NonScalar2 y); + +Overload (1): + +Returns: The value ``x / y``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x`` and ``y``, the value ``x[i] / y[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``exp`` +======= + +:: + + float exp(float x) (1) + + template (2) + /*return-type*/ exp(NonScalar x); + +Overload (1): + +Returns: The base-e exponential of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the base-e exponential of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``exp2`` +======== + +:: + + float exp2(float x) (1) + + template (2) + /*return-type*/ exp2(NonScalar x) + +Overload (1): + +Returns: The base-2 exponential of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the base-2 exponential of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``exp10`` +========= + +:: + + float exp10(float x) (1) + + template (2) + /*return-type*/ exp10(NonScalar x) + +Overload (1): + +Returns: The base-10 exponential of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the base-10 exponential of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``log`` +======= + +:: + + float log(float x) (1) + + template (2) + /*return-type*/ log(NonScalar x) + +Overload (1): + +Returns: The natural logarithm of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the natural logarithm of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``log2`` +======== + +:: + + float log2(float x) (1) + + template (2) + /*return-type*/ log2(NonScalar x) + +Overload (1): + +Returns: The base 2 logarithm of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the base 2 logarithm of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``log10`` +========= + +:: + + float log10(float x) (1) + + template (2) + /*return-type*/ log10(NonScalar x) + +Overload (1): + +Returns: The base 10 logarithm of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the base 10 logarithm of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``powr`` +======== + +:: + + float powr(float x, float y) (1) + + template (2) + /*return-type*/ powr(NonScalar1 x, NonScalar2 y) + +Overload (1): + +Preconditions: The value of ``x`` must be greater than or equal to zero. + +Returns: The value of ``x`` raised to the power ``y``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Preconditions: Each element of ``x`` must be greater than or equal to zero. + +Returns: For each element of ``x`` and ``y``, the value of ``x[i]`` +raised to the power ``y[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``recip`` +========= + +:: + + float recip(float x) (1) + + template (2) + /*return-type*/ recip(NonScalar x) + +Overload (1): + +Returns: The reciprocal of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the reciprocal of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``rsqrt`` +========= + +:: + + float rsqrt(float x) (1) + + template (2) + /*return-type*/ rsqrt(NonScalar x) + +Overload (1): + +Returns: The inverse square root of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the inverse square root of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``sin`` +======= + +:: + + float sin(float x) (1) + + template (2) + /*return-type*/ sin(NonScalar x) + +Overload (1): + +Returns: The sine of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the sine of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``sqrt`` +======== + +:: + + float sqrt(float x) (1) + + template (2) + /*return-type*/ sqrt(NonScalar x) + +Overload (1): + +Returns: The square root of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the square root of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. + +``tan`` +======= + +:: + + float tan(float x) (1) + + template (2) + /*return-type*/ tan(NonScalar x) + +Overload (1): + +Returns: The tangent of ``x``. + +Overload (2): + +Constraints: Available only if all of the following conditions are met: + +``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and + +The element type is ``float``. + +Returns: For each element of ``x``, the tangent of ``x[i]``. + +The return type is ``NonScalar`` unless ``NonScalar`` is the +``__swizzled_vec__`` type, in which case the return type is the +corresponding ``vec``. From bd4ad605d392d264e4bf0e71457a39513a7133b6 Mon Sep 17 00:00:00 2001 From: "marko.vucicevic" Date: Tue, 23 Jan 2024 22:41:52 +0100 Subject: [PATCH 2/2] Fixed review findings Issue: KHRGA-114 --- source/iface/native-prec-math-func.rst | 254 ++++++++++++++----------- 1 file changed, 141 insertions(+), 113 deletions(-) diff --git a/source/iface/native-prec-math-func.rst b/source/iface/native-prec-math-func.rst index 055dadbc..1387a30b 100644 --- a/source/iface/native-prec-math-func.rst +++ b/source/iface/native-prec-math-func.rst @@ -18,24 +18,26 @@ is implementation defined. ``cos`` ======= +.. rubric:: Overloads 1 + :: - float cos(float x) (1) + float cos(float x); - template (2) - /*return-type*/ cos(NonScalar x) +Returns: The cosine of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The cosine of ``x``. +:: -Overload (2): + template + /*return-type*/ cos(NonScalar x); Constraints: Available only if all of the following conditions are met: -NonScalar is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* NonScalar is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the cosine of ``x[i]``. @@ -46,24 +48,26 @@ corresponding ``vec``. ``divide`` ========== +.. rubric:: Overloads 1 + :: - float divide(float x, float y) (1) + float divide(float x, float y); - template (2) - /*return-type*/ divide(NonScalar1 x, NonScalar2 y); +Returns: The value ``x / y``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The value ``x / y``. +:: -Overload (2): + template + /*return-type*/ divide(NonScalar1 x, NonScalar2 y); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x`` and ``y``, the value ``x[i] / y[i]``. @@ -74,24 +78,26 @@ corresponding ``vec``. ``exp`` ======= +.. rubric:: Overloads 1 + :: - float exp(float x) (1) + float exp(float x); - template (2) - /*return-type*/ exp(NonScalar x); +Returns: The base-e exponential of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The base-e exponential of ``x``. +:: -Overload (2): + template + /*return-type*/ exp(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the base-e exponential of ``x[i]``. @@ -102,24 +108,26 @@ corresponding ``vec``. ``exp2`` ======== +.. rubric:: Overloads 1 + :: - float exp2(float x) (1) + float exp2(float x); - template (2) - /*return-type*/ exp2(NonScalar x) +Returns: The base-2 exponential of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The base-2 exponential of ``x``. +:: -Overload (2): + template; + /*return-type*/ exp2(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the base-2 exponential of ``x[i]``. @@ -130,24 +138,26 @@ corresponding ``vec``. ``exp10`` ========= +.. rubric:: Overloads 1 + :: - float exp10(float x) (1) + float exp10(float x); - template (2) - /*return-type*/ exp10(NonScalar x) +Returns: The base-10 exponential of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The base-10 exponential of ``x``. +:: -Overload (2): + template + /*return-type*/ exp10(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the base-10 exponential of ``x[i]``. @@ -158,24 +168,26 @@ corresponding ``vec``. ``log`` ======= +.. rubric:: Overloads 1 + :: - float log(float x) (1) + float log(float x); - template (2) - /*return-type*/ log(NonScalar x) +Returns: The natural logarithm of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The natural logarithm of ``x``. +:: -Overload (2): + template + /*return-type*/ log(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the natural logarithm of ``x[i]``. @@ -186,24 +198,26 @@ corresponding ``vec``. ``log2`` ======== +.. rubric:: Overloads 1 + :: - float log2(float x) (1) + float log2(float x); - template (2) - /*return-type*/ log2(NonScalar x) +Returns: The base 2 logarithm of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The base 2 logarithm of ``x``. +:: -Overload (2): + template + /*return-type*/ log2(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the base 2 logarithm of ``x[i]``. @@ -214,24 +228,26 @@ corresponding ``vec``. ``log10`` ========= +.. rubric:: Overloads 1 + :: - float log10(float x) (1) + float log10(float x); - template (2) - /*return-type*/ log10(NonScalar x) +Returns: The base 10 logarithm of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The base 10 logarithm of ``x``. +:: -Overload (2): + template + /*return-type*/ log10(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the base 10 logarithm of ``x[i]``. @@ -242,26 +258,28 @@ corresponding ``vec``. ``powr`` ======== -:: - - float powr(float x, float y) (1) +.. rubric:: Overloads 1 - template (2) - /*return-type*/ powr(NonScalar1 x, NonScalar2 y) +:: -Overload (1): + float powr(float x, float y); Preconditions: The value of ``x`` must be greater than or equal to zero. Returns: The value of ``x`` raised to the power ``y``. -Overload (2): +.. rubric:: Overloads 2 + +:: + + template + /*return-type*/ powr(NonScalar1 x, NonScalar2 y); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Preconditions: Each element of ``x`` must be greater than or equal to zero. @@ -275,24 +293,26 @@ corresponding ``vec``. ``recip`` ========= +.. rubric:: Overloads 1 + :: - float recip(float x) (1) + float recip(float x); - template (2) - /*return-type*/ recip(NonScalar x) +Returns: The reciprocal of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The reciprocal of ``x``. +:: -Overload (2): + template + /*return-type*/ recip(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the reciprocal of ``x[i]``. @@ -303,24 +323,26 @@ corresponding ``vec``. ``rsqrt`` ========= +.. rubric:: Overloads 1 + :: - float rsqrt(float x) (1) + float rsqrt(float x); - template (2) - /*return-type*/ rsqrt(NonScalar x) +Returns: The inverse square root of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The inverse square root of ``x``. +:: -Overload (2): + template + /*return-type*/ rsqrt(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the inverse square root of ``x[i]``. @@ -331,24 +353,26 @@ corresponding ``vec``. ``sin`` ======= +.. rubric:: Overloads 1 + :: - float sin(float x) (1) + float sin(float x); - template (2) - /*return-type*/ sin(NonScalar x) +Returns: The sine of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The sine of ``x``. +:: -Overload (2): + template + /*return-type*/ sin(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the sine of ``x[i]``. @@ -359,24 +383,26 @@ corresponding ``vec``. ``sqrt`` ======== +.. rubric:: Overloads 1 + :: - float sqrt(float x) (1) + float sqrt(float x); - template (2) - /*return-type*/ sqrt(NonScalar x) +Returns: The square root of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The square root of ``x``. +:: -Overload (2): + template + /*return-type*/ sqrt(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the square root of ``x[i]``. @@ -387,24 +413,26 @@ corresponding ``vec``. ``tan`` ======= +.. rubric:: Overloads 1 + :: - float tan(float x) (1) + float tan(float x); - template (2) - /*return-type*/ tan(NonScalar x) +Returns: The tangent of ``x``. -Overload (1): +.. rubric:: Overloads 2 -Returns: The tangent of ``x``. +:: -Overload (2): + template + /*return-type*/ tan(NonScalar x); Constraints: Available only if all of the following conditions are met: -``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and +* ``NonScalar`` is ``marray``, ``vec``, or the ``__swizzled_vec__`` type; and -The element type is ``float``. +* The element type is ``float``. Returns: For each element of ``x``, the tangent of ``x[i]``.