From 54f21a2ade731f9f38dd383a3de1c845c03a691e Mon Sep 17 00:00:00 2001 From: "marko.vucicevic" Date: Mon, 15 Jan 2024 09:50:17 +0100 Subject: [PATCH 1/2] Updated BIF half precision math functions Issue: KHRGA-115 --- source/iface/half-prec-math-func.rst | 419 +++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) diff --git a/source/iface/half-prec-math-func.rst b/source/iface/half-prec-math-func.rst index 18f33c8f..b0dbf03e 100644 --- a/source/iface/half-prec-math-func.rst +++ b/source/iface/half-prec-math-func.rst @@ -7,3 +7,422 @@ ***************************** Half precision math functions ***************************** + +In SYCL the half precision math functions are defined in the namespace +``sycl::half_precision``. +The functions that are available within this namespace are specified +in the list below. +These functions are implemented with a minimum of 10-bits of accuracy +i.e. the maximum error is less than or equal to ``8192 ulp``. + +``cos`` +======= + +:: + + float cos(float x) (1) + + template (2) + /*return-type*/ cos(NonScalar x) + +Overload (1): + +Preconditions: The value of ``x`` must be in the range [-216, +216]. + +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``. + +Preconditions: The value of each element of ``x`` must be in +the range [-216, +216]. + +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): + +Preconditions: The value of ``x`` must be in the range [-216, +216]. + +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``. + +Preconditions: The value of each element of ``x`` must be in the +range [-216, +216]. + +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): + +Preconditions: The value of ``x`` must be in the range [-216, +216]. + +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``. + +Preconditions: The value of each element of ``x`` must be in the +range [-216, +216]. + +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 0d027673f5299b69320e8ce40d60df334864f5e9 Mon Sep 17 00:00:00 2001 From: "marko.vucicevic" Date: Tue, 23 Jan 2024 23:02:03 +0100 Subject: [PATCH 2/2] Fixed review findings Issue: KHRGA-115 --- source/iface/half-prec-math-func.rst | 256 ++++++++++++++++----------- 1 file changed, 149 insertions(+), 107 deletions(-) diff --git a/source/iface/half-prec-math-func.rst b/source/iface/half-prec-math-func.rst index b0dbf03e..16f60462 100644 --- a/source/iface/half-prec-math-func.rst +++ b/source/iface/half-prec-math-func.rst @@ -18,26 +18,28 @@ i.e. the maximum error is less than or equal to ``8192 ulp``. ``cos`` ======= -:: - - float cos(float x) (1) +.. rubric:: Overload 1 - template (2) - /*return-type*/ cos(NonScalar x) +:: -Overload (1): + float cos(float x); Preconditions: The value of ``x`` must be in the range [-216, +216]. Returns: The cosine of ``x``. -Overload (2): +.. rubric:: 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``. Preconditions: The value of each element of ``x`` must be in the range [-216, +216]. @@ -51,24 +53,26 @@ is the corresponding ``vec``. ``divide`` ========== +.. rubric:: Overload 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:: Overload 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]``. @@ -79,24 +83,26 @@ is the corresponding ``vec``. ``exp`` ======= +.. rubric:: Overload 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:: Overload 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]``. @@ -107,24 +113,26 @@ is the corresponding ``vec``. ``exp2`` ======== +.. rubric:: Overload 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:: Overload 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]``. @@ -135,24 +143,26 @@ is the corresponding ``vec``. ``exp10`` ========= +.. rubric:: Overload 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:: Overload 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]``. @@ -163,24 +173,26 @@ is the corresponding ``vec``. ``log`` ======= +.. rubric:: Overload 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:: Overload 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]``. @@ -191,24 +203,26 @@ is the corresponding ``vec``. ``log2`` ======== +.. rubric:: Overload 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:: Overload 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]``. @@ -226,17 +240,26 @@ is the corresponding ``vec``. template (2) /*return-type*/ log10(NonScalar x) -Overload (1): +.. rubric:: Overload 1 + +:: + + float log10(float x); Returns: The base 10 logarithm of ``x``. -Overload (2): +.. rubric:: 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]``. @@ -247,26 +270,28 @@ is the corresponding ``vec``. ``powr`` ======== -:: - - float powr(float x, float y) (1) +.. rubric:: Overload 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:: Overload 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. @@ -280,24 +305,26 @@ is the corresponding ``vec``. ``recip`` ========= +.. rubric:: Overload 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:: Overload 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]``. @@ -308,24 +335,26 @@ is the corresponding ``vec``. ``rsqrt`` ========= +.. rubric:: Overload 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:: Overload 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]``. @@ -336,26 +365,28 @@ is the corresponding ``vec``. ``sin`` ======= -:: - - float sin(float x) (1) +.. rubric:: Overload 1 - template (2) - /*return-type*/ sin(NonScalar x) +:: -Overload (1): + float sin(float x); Preconditions: The value of ``x`` must be in the range [-216, +216]. Returns: The sine of ``x``. -Overload (2): +.. rubric:: 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``. Preconditions: The value of each element of ``x`` must be in the range [-216, +216]. @@ -369,24 +400,26 @@ is the corresponding ``vec``. ``sqrt`` ======== +.. rubric:: Overload 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:: Overload 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]``. @@ -404,19 +437,28 @@ is the corresponding ``vec``. template (2) /*return-type*/ tan(NonScalar x) -Overload (1): +.. rubric:: Overload 1 + +:: + + float tan(float x); Preconditions: The value of ``x`` must be in the range [-216, +216]. Returns: The tangent of ``x``. -Overload (2): +.. rubric:: 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``. Preconditions: The value of each element of ``x`` must be in the range [-216, +216].