From 487ea2abe877fcf5cd79833f06aa574471737692 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:10:22 -0500 Subject: [PATCH 1/8] Add new empty line to docstring of has_aspect_atomic64 property per sphinx error --- dpctl/_sycl_device.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 9681c7cbcd..9388c1c69b 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -503,6 +503,7 @@ cdef class SyclDevice(_SyclDevice): Indicates that the device supports the following atomic operations on 64-bit values: + - atomic::load - atomic::store - atomic::fetch_add From def745e6bf92e1ce8821edd63aa31a6a548fb74b Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:10:59 -0500 Subject: [PATCH 2/8] Add new empty line to docstring of USMAllocationError per sphinx error --- dpctl/memory/_memory.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/dpctl/memory/_memory.pyx b/dpctl/memory/_memory.pyx index a8917ee42f..4330ecd25c 100644 --- a/dpctl/memory/_memory.pyx +++ b/dpctl/memory/_memory.pyx @@ -83,6 +83,7 @@ class USMAllocationError(Exception): An exception raised when Universal Shared Memory (USM) allocation call returns a null pointer, signaling a failure to perform the allocation. Some common reasons for allocation failure are: + * insufficient free memory to perform the allocation request * allocation size exceeds the maximum supported by targeted backend """ From f5addb313bec3e94d63c47387da9f618d939c57c Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:11:22 -0500 Subject: [PATCH 3/8] Change docstring of usm_ndarray per Sphinx errors --- dpctl/tensor/_usmarray.pyx | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/dpctl/tensor/_usmarray.pyx b/dpctl/tensor/_usmarray.pyx index a63cb357f7..b018430f03 100644 --- a/dpctl/tensor/_usmarray.pyx +++ b/dpctl/tensor/_usmarray.pyx @@ -82,23 +82,23 @@ cdef class usm_ndarray: If ``dtype`` has the value ``None``, it is determined by default floating point type supported by target device. The supported types are - * ``bool`` - boolean type - * ``int8``, ``int16``, ``int32``, ``int64``, - signed integer types - * ``uint8``, ``uint16``, ``uint32``, ``uint64``, - unsigned integer types - * ``float16`` - half-precision floating type, - supported if target device's property - ``has_aspect_fp16`` is ``True`` - * ``float32``, ``complex64`` - single-precision real and complex floating - types - * ``float64``, ``complex128`` - double-precision real and complex floating - types, supported if target device's property - ``has_aspect_fp64`` is ``True``. + + ``bool``: + boolean type + ``int8``, ``int16``, ``int32``, ``int64``: + signed integer types + ``uint8``, ``uint16``, ``uint32``, ``uint64``: + unsigned integer types + ``float16``: + half-precision floating type, + supported if target device's property + ``has_aspect_fp16`` is ``True`` + ``float32``, ``complex64``: + single-precision real and complex floating types + ``float64``, ``complex128``: + double-precision real and complex floating + types, supported if target device's property + ``has_aspect_fp64`` is ``True``. Default: ``None``. strides (tuple, optional): Strides of the array to be created in elements. From babf58afe2ac55732d97168e6298d484993e255f Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:12:02 -0500 Subject: [PATCH 4/8] tensordot docstring changes per Sphinx errors Indentation fixed, new empty line added before enumeration --- dpctl/tensor/_linear_algebra_functions.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/dpctl/tensor/_linear_algebra_functions.py b/dpctl/tensor/_linear_algebra_functions.py index fd7196b2e6..2885867797 100644 --- a/dpctl/tensor/_linear_algebra_functions.py +++ b/dpctl/tensor/_linear_algebra_functions.py @@ -81,10 +81,11 @@ def tensordot(x1, x2, axes=2): then the contraction is performed over last `N` axes of `x1` and the first `N` axis of `x2` in order. The size of each corresponding axis must match and must be non-negative. - * if `N` equals `0`, the result is the tensor outer product - * if `N` equals `1`, the result is the tensor dot product - * if `N` equals `2`, the result is the tensor double - contraction (default). + + * if `N` equals `0`, the result is the tensor outer product + * if `N` equals `1`, the result is the tensor dot product + * if `N` equals `2`, the result is the tensor double + contraction (default). If `axes` is a tuple of two sequences `(x1_axes, x2_axes)`, the first sequence applies to `x1` and the second sequence applies to `x2`. Both sequences must have equal length, and each axis From 377fc9d24a11a85436e467b5bc66e5e1a51cb0e1 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:13:06 -0500 Subject: [PATCH 5/8] Docstring edits per Sphinx errors Indentation fixes, new line added before enumeration, added semicolons after item and start explanation sentence indented on the next line --- dpctl/tensor/_print.py | 142 ++++++++++++++++++++++++----------------- 1 file changed, 82 insertions(+), 60 deletions(-) diff --git a/dpctl/tensor/_print.py b/dpctl/tensor/_print.py index 81ae27fb68..450f46c0f1 100644 --- a/dpctl/tensor/_print.py +++ b/dpctl/tensor/_print.py @@ -116,50 +116,61 @@ def set_print_options( Set options for printing :class:`dpctl.tensor.usm_ndarray` class. Args: - linewidth (int, optional): Number of characters printed per line. + linewidth (int, optional): + Number of characters printed per line. Raises `TypeError` if linewidth is not an integer. Default: `75`. - edgeitems (int, optional): Number of elements at the beginning and end + edgeitems (int, optional): + Number of elements at the beginning and end when the printed array is abbreviated. Raises `TypeError` if edgeitems is not an integer. Default: `3`. - threshold (int, optional): Number of elements that triggers array - abbreviation. + threshold (int, optional): + Number of elements that triggers array abbreviation. Raises `TypeError` if threshold is not an integer. Default: `1000`. - precision (int or None, optional): Number of digits printed for - floating point numbers. + precision (int or None, optional): + Number of digits printed for floating point numbers. Raises `TypeError` if precision is not an integer. Default: `8`. - floatmode (str, optional): Controls how floating point - numbers are interpreted. - - `"fixed:`: Always prints exactly `precision` digits. - `"unique"`: Ignores precision, prints the number of - digits necessary to uniquely specify each number. - `"maxprec"`: Prints `precision` digits or fewer, - if fewer will uniquely represent a number. - `"maxprec_equal"`: Prints an equal number of digits - for each number. This number is `precision` digits or fewer, - if fewer will uniquely represent each number. + floatmode (str, optional): + Controls how floating point numbers are interpreted. + `"fixed:`: + Always prints exactly `precision` digits. + `"unique"`: + Ignores precision, prints the number of + digits necessary to uniquely specify each number. + `"maxprec"`: + Prints `precision` digits or fewer, + if fewer will uniquely represent a number. + `"maxprec_equal"`: + Prints an equal number of digits + for each number. This number is `precision` digits + or fewer, if fewer will uniquely represent each number. Raises `ValueError` if floatmode is not one of `fixed`, `unique`, `maxprec`, or `maxprec_equal`. Default: "maxprec_equal" - suppress (bool, optional): If `True,` numbers equal to zero - in the current precision will print as zero. + suppress (bool, optional): + If `True,` numbers equal to zero in the current precision + will print as zero. Default: `False`. - nanstr (str, optional): String used to represent nan. + nanstr (str, optional): + String used to represent nan. Raises `TypeError` if nanstr is not a string. Default: `"nan"`. - infstr (str, optional): String used to represent infinity. + infstr (str, optional): + String used to represent infinity. Raises `TypeError` if infstr is not a string. Default: `"inf"`. - sign (str, optional): Controls the sign of floating point - numbers. - `"-"`: Omit the sign of positive numbers. - `"+"`: Always print the sign of positive numbers. - `" "`: Always print a whitespace in place of the - sign of positive numbers. + sign (str, optional): + Controls the sign of floating point numbers. + `"-"`: + Omit the sign of positive numbers. + `"+"`: + Always print the sign of positive numbers. + `" "`: + Always print a whitespace in place of the + sign of positive numbers. Raises `ValueError` if sign is not one of `"-"`, `"+"`, or `" "`. Default: `"-"`. @@ -287,60 +298,71 @@ def usm_ndarray_str( :class:`dpctl.tensor.usm_ndarray`. Args: - x (usm_ndarray): Input array. - line_width (int, optional): Number of characters printed per line. + x (usm_ndarray): + Input array. + line_width (int, optional): + Number of characters printed per line. Raises `TypeError` if line_width is not an integer. Default: `75`. - edgeitems (int, optional): Number of elements at the beginning and end + edgeitems (int, optional): + Number of elements at the beginning and end when the printed array is abbreviated. Raises `TypeError` if edgeitems is not an integer. Default: `3`. - threshold (int, optional): Number of elements that triggers array - abbreviation. + threshold (int, optional): + Number of elements that triggers array abbreviation. Raises `TypeError` if threshold is not an integer. Default: `1000`. - precision (int or None, optional): Number of digits printed for - floating point numbers. + precision (int or None, optional): + Number of digits printed for floating point numbers. Raises `TypeError` if precision is not an integer. Default: `8`. - floatmode (str, optional): Controls how floating point - numbers are interpreted. - - `"fixed:`: Always prints exactly `precision` digits. - `"unique"`: Ignores precision, prints the number of - digits necessary to uniquely specify each number. - `"maxprec"`: Prints `precision` digits or fewer, - if fewer will uniquely represent a number. - `"maxprec_equal"`: Prints an equal number of digits - for each number. This number is `precision` digits or fewer, - if fewer will uniquely represent each number. + floatmode (str, optional): + Controls how floating point numbers are interpreted. + `"fixed:`: + Always prints exactly `precision` digits. + `"unique"`: + Ignores precision, prints the number of + digits necessary to uniquely specify each number. + `"maxprec"`: + Prints `precision` digits or fewer, + if fewer will uniquely represent a number. + `"maxprec_equal"`: + Prints an equal number of digits for each number. + This number is `precision` digits or fewer, + if fewer will uniquely represent each number. Raises `ValueError` if floatmode is not one of `fixed`, `unique`, `maxprec`, or `maxprec_equal`. Default: "maxprec_equal" - suppress (bool, optional): If `True,` numbers equal to zero - in the current precision will print as zero. + suppress (bool, optional): + If `True,` numbers equal to zero in the current precision + will print as zero. Default: `False`. - sign (str, optional): Controls the sign of floating point - numbers. - `"-"`: Omit the sign of positive numbers. - `"+"`: Always print the sign of positive numbers. - `" "`: Always print a whitespace in place of the - sign of positive numbers. + sign (str, optional): + Controls the sign of floating point numbers. + `"-"`: + Omit the sign of positive numbers. + `"+"`: + Always print the sign of positive numbers. + `" "`: + Always print a whitespace in place of the + sign of positive numbers. Raises `ValueError` if sign is not one of `"-"`, `"+"`, or `" "`. Default: `"-"`. - numpy (bool, optional): If `True,` then before other specified print + numpy (bool, optional): + If `True,` then before other specified print options are set, a dictionary of Numpy's print options will be used to initialize dpctl's print options. Default: "False" - separator (str, optional): String inserted between elements of - the array string. + separator (str, optional): + String inserted between elements of the array string. Default: " " - prefix (str, optional): String used to determine spacing to the left - of the array string. + prefix (str, optional): + String used to determine spacing to the left of the array string. Default: "" - suffix (str, optional): String that determines length of the last line - of the array string. + suffix (str, optional): + String that determines length of the last line of the array string. Default: "" Returns: From 397b4a9212fbb9f6ff7f0f4a00d7158763b66e5a Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:14:45 -0500 Subject: [PATCH 6/8] Added new empty lines before enumeration per sphinx errors --- dpctl/tensor/_reduction.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/dpctl/tensor/_reduction.py b/dpctl/tensor/_reduction.py index 00ef5ed85b..8586ed935c 100644 --- a/dpctl/tensor/_reduction.py +++ b/dpctl/tensor/_reduction.py @@ -194,6 +194,7 @@ def sum(x, axis=None, dtype=None, keepdims=False): dtype (Optional[dtype]): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. + * If `x` has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input @@ -220,6 +221,7 @@ def sum(x, axis=None, dtype=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the sums. If the sum was computed over the @@ -254,6 +256,7 @@ def prod(x, axis=None, dtype=None, keepdims=False): dtype (Optional[dtype]): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. + * If `x` has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input @@ -280,6 +283,7 @@ def prod(x, axis=None, dtype=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the products. If the product was computed over @@ -315,6 +319,7 @@ def logsumexp(x, axis=None, dtype=None, keepdims=False): dtype (Optional[dtype]): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. + * If `x` has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input @@ -333,6 +338,7 @@ def logsumexp(x, axis=None, dtype=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the results. If the result was computed over @@ -370,6 +376,7 @@ def reduce_hypot(x, axis=None, dtype=None, keepdims=False): dtype (Optional[dtype]): data type of the returned array. If `None`, the default data type is inferred from the "kind" of the input array data type. + * If `x` has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input @@ -388,6 +395,7 @@ def reduce_hypot(x, axis=None, dtype=None, keepdims=False): compatible with the input arrays according to Array Broadcasting rules. Otherwise, if `False`, the reduced axes are not included in the returned array. Default: `False`. + Returns: usm_ndarray: an array containing the results. If the result was computed over From 396f76464b7606d0bc4b8c062d0879cf713213b7 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:16:26 -0500 Subject: [PATCH 7/8] Add semicolon, and empty new line before enumeration This fixes Sphinx enumeration errors --- dpctl/tensor/_type_utils.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/dpctl/tensor/_type_utils.py b/dpctl/tensor/_type_utils.py index e0327b4410..c16bb6112e 100644 --- a/dpctl/tensor/_type_utils.py +++ b/dpctl/tensor/_type_utils.py @@ -629,7 +629,8 @@ def iinfo(dtype): Returns: iinfo_object: - An object with the following attributes + An object with the following attributes: + * bits: int number of bits occupied by the data type * max: int @@ -658,7 +659,8 @@ def finfo(dtype): Returns: finfo_object: - an object have the following attributes + an object have the following attributes: + * bits: int number of bits occupied by dtype. * eps: float From f9a3e1b377a71476d5c80ecbf0840d49830f95f6 Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Thu, 14 Mar 2024 10:49:08 -0500 Subject: [PATCH 8/8] Address SPHINX error Docorated bash example as bash code-block, added URL for intel/pti-gpu, mentioned `unitrace` as an alternative to `onetrace`. --- dpctl/utils/_onetrace_context.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/dpctl/utils/_onetrace_context.py b/dpctl/utils/_onetrace_context.py index d7a6295c41..f3b5d042a6 100644 --- a/dpctl/utils/_onetrace_context.py +++ b/dpctl/utils/_onetrace_context.py @@ -32,15 +32,20 @@ def onetrace_enabled(): """Enable `onetrace` collection for kernels executed in this context. N.B.: Proper working of this utility assumes that Python interpreter - has been launched by `onetrace` tool from intel/pti-gpu project. + has been launched by `onetrace` or `unitrace` tool from project + `intel/pti-gpu `_. :Example: - Launch the Python interpreter using `onetrace` tool: :: + Launch the Python interpreter using `onetrace` tool: + + .. code-block:: bash $ onetrace --conditional-collection -v -t --demangle python app.py Now using the context manager in the Python sessions enables - data collection and its output for every offloaded kernel :: + data collection and its output for every offloaded kernel: + + .. code-block:: python import dpctl.tensor as dpt from dpctl.utils import onetrace_enabled