diff --git a/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst b/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst index a7b67f6e9d..f4dc7f4824 100644 --- a/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst +++ b/docs/doc_sources/api_reference/dpctl/examples/usm_ndarray.rst @@ -12,7 +12,7 @@ .. rubric:: Use :meth:`usm_ndarray.device` to specify placement of new array .. code-block:: python - :caption: Create an USM-device empty array on the same device as another array + :caption: Create a USM-device empty array on the same device as another array from dpctl import tensor diff --git a/docs/doc_sources/api_reference/dpctl/memory.rst b/docs/doc_sources/api_reference/dpctl/memory.rst index 9f54c35263..f202b9aafb 100644 --- a/docs/doc_sources/api_reference/dpctl/memory.rst +++ b/docs/doc_sources/api_reference/dpctl/memory.rst @@ -4,11 +4,11 @@ :py:mod:`dpctl.memory` ====================== -Subpackage :py:mod:`dpctl.memory` exposes Unified Shared Memory(USM) operations. +Subpackage :py:mod:`dpctl.memory` exposes Unified Shared Memory (USM) operations. Unified Shared Memory is a pointer-based memory management in SYCL guaranteeing that the host and all devices use a `unified address space `_. -Quoting from the SYCL specification: +As described in the SYCL specification: .. _sycl_unified_address_space: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_unified_addressing diff --git a/docs/doc_sources/api_reference/dpctl/program.rst b/docs/doc_sources/api_reference/dpctl/program.rst index 03518e15f4..683d841541 100644 --- a/docs/doc_sources/api_reference/dpctl/program.rst +++ b/docs/doc_sources/api_reference/dpctl/program.rst @@ -4,7 +4,7 @@ ======================= :py:mod:`dpctl.program` provides a way to create a SYCL kernel -from either an OpenCL program source code represented as a string +from either an OpenCL* program source code represented as a string or a SPIR-V binary file. It implements creation of interoperability diff --git a/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst b/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst index b6f80a1b34..5d564f422f 100644 --- a/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst +++ b/docs/doc_sources/api_reference/dpctl/sycl_usm_array_interface.rst @@ -6,7 +6,7 @@ Python objects representing USM allocations, such as :py:class:`dpctl.memory.MemoryUSMDevice`, :py:class:`dpctl.memory.MemoryUSMShared`, :py:class:`dpctl.memory.MemoryUSMHost`, or :py:class:`dpctl.tensor.usm_ndarray`, distinguish themselves from other Python objects -by providing ``__sycl_usm_array_interface__`` attribute describing the allocation in a +by providing the ``__sycl_usm_array_interface__`` attribute describing the allocation in a Python dictionary with the following fields: ``"shape"`` @@ -32,23 +32,22 @@ Python dictionary with the following fields: is read-only). ``"strides"`` - an optional tuple of integers describing number of array elements needed to jump + An optional tuple of integers describing number of array elements needed to jump to the next array element in the corresponding dimensions. The default value of ``None`` implies a C-style contiguous (row-major compact) layout of the array. ``"offset"`` - an optional Python integer encoding offset in number of elements from the pointer + An optional Python integer encoding offset in number of elements from the pointer provided in ``"data"`` field to the array element with zero indices. Default: `0`. ``"syclobj"`` Python object from which SYCL context to which represented USM allocation is bound. ============================================== ======================================= - Filter selector string Platform's default context for platform - the SYCL device selected by the - :ref:`filter selector string ` - is a part of. - :py:class:`dpctl.SyclContext` An explicitly provided context + Filter selector string The default context of the platform + selected by + :ref:`filter selector string `. + :py:class:`dpctl.SyclContext` An explicitly provided context. Python capsule with name ``"SyclContextRef"`` A Python capsule carrying a ``DPCTLSyclContextRef`` opaque pointer. :py:class:`dpctl.SyclQueue` An explicitly provided queue which @@ -61,7 +60,7 @@ Python dictionary with the following fields: ============================================== ======================================= ``"version"`` - version of the interface. At present, the only supported value is `1`. + Version of the interface. At present, the only supported value is `1`. .. _numpy_array_interface: https://numpy.org/doc/stable/reference/arrays.interface.html diff --git a/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst b/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst index 21c4bec33b..7e3f775aec 100644 --- a/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst +++ b/docs/doc_sources/api_reference/dpctl/tensor.data_type_functions.rst @@ -3,7 +3,7 @@ Data type functions =================== -Package :py:mod:`dpctl.tensor` contains the following data type functions conforming +The package :py:mod:`dpctl.tensor` contains the following data type functions conforming to `Python Array API specification `_: .. _array_api_data_type_fns: https://data-apis.org/array-api/latest/API_specification/data_type_functions.html diff --git a/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst b/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst index 1027da4999..5bd9fa23a9 100644 --- a/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst +++ b/docs/doc_sources/api_reference/dpctl/tensor.data_types.rst @@ -28,11 +28,11 @@ Data types +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``uint64`` | A 64-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{64}` | +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``float16`` | An IEEE-754 half-precision (16-bits) binary floating-point number (see `IEEE 754-2019`_) | +| ``float16`` | An IEEE-754 half-precision (16-bit) binary floating-point number (see `IEEE 754-2019`_) | +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``float32`` | An IEEE-754 single-precision (32-bits) binary floating-point number (see `IEEE 754-2019`_) | +| ``float32`` | An IEEE-754 single-precision (32-bit) binary floating-point number (see `IEEE 754-2019`_) | +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``float64`` | An IEEE-754 double-precision (64-bits) binary floating-point number (see `IEEE 754-2019`_) | +| ``float64`` | An IEEE-754 double-precision (64-bit) binary floating-point number (see `IEEE 754-2019`_) | +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``complex64`` | Single-precision (64-bit) complex floating-point number whose real and imaginary components are IEEE 754 single-precision (32-bit) binary floating-point numbers (see `IEEE 754-2019`_) | +----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -48,7 +48,7 @@ Half-precision floating-point type ``float16`` is supported only for devices who Double-precision floating-point type ``float64`` and double-precision complex floating-point type ``complex128`` are supported only for devices whose attribute :attr:`dpctl.SyclDevice.has_aspect_fp64` evaluates to ``True``. -Requests to create an instance of array object for these types on devices where these prerequisites are not met will raise an exception. +If prerequisites are not met, requests to create an instance of an array object for these types will raise an exception. .. TODO: provide a note on support for sub-normal numbers @@ -118,7 +118,7 @@ Type promotion rules govern the behavior of an array library when a function doe a dedicated implementation for the data type(s) of the input array(s). In such a case, input arrays may be cast to data types for which a dedicated implementation -exists. e.g., when :data:`sin` is applied to array of integral values. +exists. For example, when :data:`sin` is applied to array of integral values. Type promotion rules used in :py:mod:`dpctl.tensor` are consistent with the Python Array API specification's `type promotion rules `_ diff --git a/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst b/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst index 10bcef6572..75d659cf88 100644 --- a/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst +++ b/docs/doc_sources/api_reference/dpctl/tensor.inspection.rst @@ -5,7 +5,7 @@ Inspection API :mod:`dpctl.tensor` implements a way to introspect implementation- and device- -capabilities of array library as specified in +capabilities of an array library as specified in `Python Array API standard `_: .. currentmodule:: dpctl.tensor diff --git a/docs/doc_sources/api_reference/dpctl/tensor.rst b/docs/doc_sources/api_reference/dpctl/tensor.rst index e94d8c60ad..d2aaa6fbc4 100644 --- a/docs/doc_sources/api_reference/dpctl/tensor.rst +++ b/docs/doc_sources/api_reference/dpctl/tensor.rst @@ -7,7 +7,7 @@ .. currentmodule:: dpctl.tensor -:py:mod:`dpctl.tensor` provides a reference implementation of +:py:mod:`dpctl.tensor` provides a reference implementation of the :array_api:`Python Array API <>` specification. The implementation uses :ref:`data-parallel ` algorithms suitable for execution on accelerators, such as GPUs. diff --git a/docs/doc_sources/api_reference/dpctl_capi.rst b/docs/doc_sources/api_reference/dpctl_capi.rst index 45a750bdbb..0d69cf808d 100644 --- a/docs/doc_sources/api_reference/dpctl_capi.rst +++ b/docs/doc_sources/api_reference/dpctl_capi.rst @@ -1,6 +1,6 @@ .. _dpctl_capi: -:py:mod:`dpctl` C-API +:py:mod:`dpctl` C API ===================== :py:mod:`dpctl` core classes are implemented in Cython. C declarations for Python objects @@ -41,7 +41,7 @@ Exported typedefs .. c:struct:: PySyclProgramType -In order to check whether a particular Python objct is an instance of :py:class:`dpctl.SyclQueue` one would write: +To check whether a particular Python object is an instance of :py:class:`dpctl.SyclQueue`: .. code-block:: C :caption: Check if an object is of type :c:struct:`PySyclQueueType` @@ -123,7 +123,7 @@ API for :c:struct:`Py_MemoryObject` .. c:function:: DPCTLSyclUSMRef Memory_GetUsmPointer(struct Py_MemoryObject *o) :param o: Input object - :returns: Opaque pointer to USM allocation represented by Python object + :returns: Opaque pointer to USM allocation represented by Python object. .. c:function:: DPCTLSyclContextRef Memory_GetSyclContext(struct Py_MemoryObject *o) @@ -172,7 +172,7 @@ API for :c:struct:`PyUSMArrayObject` .. c:function:: Py_ssize_t * UsmNDArray_GetShape(struct PyUSMArrayObject *arr) :param arr: Input object - :returns: Pointer to array of sizes of array along each dimension + :returns: Pointer to array of sizes of array along each dimension. The array has at least as many elements as returned by :c:func:`UsmNDArray_GetNDim` applied to input object ``arr``. @@ -180,8 +180,8 @@ API for :c:struct:`PyUSMArrayObject` .. c:function:: Py_ssize_t * UsmNDArray_GetStrides(struct PyUSMArrayObject *arr) :param arr: Input object - :returns: Pointer to array of strides of array along each dimension - :returns: NULL if array is C- or F-contiguous + :returns: Pointer to array of strides of array along each dimension. + :returns: NULL if array is C- or F-contiguous. The array has at least as many elements as returned by :c:func:`UsmNDArray_GetNDim` applied to input object ``arr``. @@ -189,7 +189,7 @@ API for :c:struct:`PyUSMArrayObject` .. c:function:: int UsmNDarray_GetTypenum(struct PyUSMArrayObject *arr) :param arr: Input object - :returns: An integer encoding the type of array elements + :returns: An integer encoding the type of array elements. The encoding is consistent with that integral values corresponding to enums used by :py:mod:`numpy`. See `NumPy Dtype C-API `_. @@ -202,7 +202,7 @@ API for :c:struct:`PyUSMArrayObject` .. c:function:: int UsmNDarray_GetFlags(struct PyUSMArrayObject *arr) :param arr: Input object - :returns: An integer encoding flags attribute of the array + :returns: An integer encoding flags attribute of the array. The flag encodes whether the array is C-contiguous, F-contiguous, whether it is read-only, or can be modified. @@ -219,12 +219,12 @@ API for :c:struct:`PyUSMArrayObject` :param arr: Input object :returns: Offset of zero multi-index array element from the beginning of - the USM allocation + the USM allocation. .. c:function:: void UsmNDArray_SetWritableFlag(struct PyUSMArrayObject *arr, int flag) :param arr: Input object - :param flags: Whether to set writable flag of the array to read-only, or to writable + :param flags: Whether to set writable flag of the array to read-only, or to writable. Non-zero value of ``flag`` parameter sets the array flag bit to writable, a zero-value of ``flag`` parameter sets the flag bit of the array to read-only. diff --git a/docs/doc_sources/api_reference/dpctl_cmake.rst b/docs/doc_sources/api_reference/dpctl_cmake.rst index 7e6ea1fc37..2bbb9c03e4 100644 --- a/docs/doc_sources/api_reference/dpctl_cmake.rst +++ b/docs/doc_sources/api_reference/dpctl_cmake.rst @@ -3,10 +3,10 @@ CMake support ============= -:py:mod:`dpctl` comes with configuration file `dpctl-config.cmake` which is installed +:py:mod:`dpctl` comes with the configuration file `dpctl-config.cmake` which is installed on the `standard search path CMake uses to search for packages `_. -To build your extension that leverages :py:mod:`dpctl` include the following line in your cmake script: +To build your extension that leverages :py:mod:`dpctl`, include the following line in your CMake script: .. code-block:: cmake diff --git a/docs/doc_sources/api_reference/dpctl_cython.rst b/docs/doc_sources/api_reference/dpctl_cython.rst index fb99f3c094..ecafe7966a 100644 --- a/docs/doc_sources/api_reference/dpctl_cython.rst +++ b/docs/doc_sources/api_reference/dpctl_cython.rst @@ -38,5 +38,5 @@ File ``_backend.pxd`` redefines symbols from :ref:`DPCTLSyclInterface library `_ folder in the project +Please refer to the `examples/cython `_ folder in the project repository for a collection of examples. diff --git a/docs/doc_sources/api_reference/dpctl_pybind11.rst b/docs/doc_sources/api_reference/dpctl_pybind11.rst index 87744df211..32c587ef96 100644 --- a/docs/doc_sources/api_reference/dpctl_pybind11.rst +++ b/docs/doc_sources/api_reference/dpctl_pybind11.rst @@ -3,7 +3,7 @@ pybind11 API ============ -:py:mod:`dpctl` builds on top of :ref:`C-API ` to integrate with +:py:mod:`dpctl` builds on top of :ref:`C API ` to integrate with the `pybind11 `_ Python extension generator. .. code-block:: c++ @@ -23,7 +23,7 @@ pybind11 API m.def("get_device_name", &get_device_name); } -The extension should be compiled using Intel(R) oneAPI DPC++ compiler: +The extension should be compiled using the Intel(R) oneAPI DPC++ compiler: .. code-block:: bash diff --git a/docs/doc_sources/api_reference/index.rst b/docs/doc_sources/api_reference/index.rst index f142628e24..a9148d953a 100644 --- a/docs/doc_sources/api_reference/index.rst +++ b/docs/doc_sources/api_reference/index.rst @@ -13,7 +13,7 @@ The package ``dpctl`` provides - :ref:`API objects ` in :py:mod:`dpctl.utils` namespace * SYCL-based Python array library - :ref:`API objects ` in :py:mod:`dpctl.tensor` namespace -* Python C-API +* Python C API - :ref:`C API ` for working with Python classes defined in :mod:`dpctl` * Extension generators - :ref:`Declarations ` for classes defined in :py:mod:`dpctl` and supporting functions for use in `Cython `_. diff --git a/docs/doc_sources/api_reference/libsyclinterface/index.rst b/docs/doc_sources/api_reference/libsyclinterface/index.rst index 288355fd9f..125c406ab0 100644 --- a/docs/doc_sources/api_reference/libsyclinterface/index.rst +++ b/docs/doc_sources/api_reference/libsyclinterface/index.rst @@ -1,11 +1,11 @@ .. _libsyclinterface: C Library SyclInterface -======================= +======================== -:py:mod:`dpctl` contains SyclInterface library that provides C API to a subset of functionality exposed in DPC++ runtime classes. +:py:mod:`dpctl` contains the SyclInterface library which provides C APIs to a subset of functionality exposed in DPC++ runtime classes. -The C-API was necessary to support :py:mod:`numba_dpex` project to use DPC++ runtime classes from LLVM it generates. +The C API was necessary to support the :py:mod:`numba_dpex` project to use DPC++ runtime classes from LLVM it generates. Full :doc:`API reference ` is generated using doxyrest from doxygen strings.