diff --git a/pull/1473/.buildinfo b/pull/1473/.buildinfo new file mode 100644 index 0000000000..63c469a162 --- /dev/null +++ b/pull/1473/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 8e6a26269fbd26be477994f69239c608 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/pull/1473/.nojekyll b/pull/1473/.nojekyll new file mode 100644 index 0000000000..e69de29bb2 diff --git a/pull/1473/_sources/autoapi/index.rst.txt b/pull/1473/_sources/autoapi/index.rst.txt new file mode 100644 index 0000000000..056d157624 --- /dev/null +++ b/pull/1473/_sources/autoapi/index.rst.txt @@ -0,0 +1,14 @@ +API Reference +============= + +This page contains auto-generated API reference documentation [#f1]_. + +.. toctree:: + :maxdepth: 1 + + numba_dpex/kernel_api/index + numba_dpex/core/decorators/index + numba_dpex/core/kernel_launcher/index + + +.. [#f1] Created with `sphinx-autoapi `_ \ No newline at end of file diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/boxing/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/index.rst.txt new file mode 100644 index 0000000000..bdbd1ee08c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/index.rst.txt @@ -0,0 +1,385 @@ + +numba_dpex.core.boxing +====================== + +.. py:module:: numba_dpex.core.boxing + +.. autoapi-nested-parse:: + + Contains the ``box`` and ``unbox`` functions for numba_dpex types that are + passable as arguments to a kernel or dpjit decorated function. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`NdRangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`RangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`NdRange ` + - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + * - :py:obj:`Range ` + - Analogue to the :sycl_range:`sycl::range <>` class. + * - :py:obj:`USMNdArray ` + - A type class to represent dpctl.tensor.usm_ndarray. + * - :py:obj:`NdRange ` + - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + * - :py:obj:`Range ` + - Analogue to the :sycl_range:`sycl::range <>` class. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`unbox_range `\ (typ, obj, c) + - Converts a Python Range object to numba-dpex's native struct representation + * - :py:obj:`unbox_ndrange `\ (typ, obj, c) + - Converts a Python Range object to numba-dpex's native struct representation + * - :py:obj:`box_range `\ (typ, val, c) + - Convert a native range structure to a Range object. + * - :py:obj:`box_ndrange `\ (typ, val, c) + - Convert a native range structure to a Range object. + * - :py:obj:`unbox_dpnp_nd_array `\ (typ, obj, c) + - Converts a dpctl.tensor.usm_ndarray/dpnp.ndarray object to a Numba-dpex + * - :py:obj:`box_array `\ (typ, val, c) + - Boxes a NativeValue representation of USMNdArray/DpnpNdArray type into a + + + +Classes +------- + +.. py:class:: NdRangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.NdRange` + + + + +.. py:class:: RangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.Range` + + + + +.. py:class:: NdRange(global_size, local_size) + + Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + + The NdRange defines the index space for a work group as well as + the global index space. It is passed to parallel_for to execute + a kernel on a set of work items. + + This class basically contains two Range object, one for the global_range + and the other for the local_range. The global_range parameter contains + the global index space and the local_range parameter contains the index + space of a work group. This class mimics the behavior of `sycl::nd_range` + class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_range `\ () + - Returns a Range defining the index space. + * - :py:obj:`get_local_range `\ () + - Returns a Range defining the index space of a work group. + + + .. rubric:: Members + + .. py:method:: get_global_range() + + Returns a Range defining the index space. + + :returns: A `Range` object defining the index space. + :rtype: Range + + + .. py:method:: get_local_range() + + Returns a Range defining the index space of a work group. + + :returns: A `Range` object to specify index space of a work group. + :rtype: Range + + + + +.. py:class:: Range + + Bases: :py:obj:`tuple` + + Analogue to the :sycl_range:`sycl::range <>` class. + + The range is an abstraction that describes the number of elements + in each dimension of buffers and index spaces. It can contain + 1, 2, or 3 numbers, depending on the dimensionality of the + object it describes. + + This is just a wrapper class on top of a 3-tuple. The kernel launch + parameter is consisted of three int's. This class basically mimics + the behavior of `sycl::range`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get `\ (index) + - Returns the range of a single dimension. + * - :py:obj:`size `\ () + - Returns the size of a range. + + + .. rubric:: Members + + .. py:method:: get(index) + + Returns the range of a single dimension. + + :param index: The index of the dimension, i.e. [0,2] + :type index: int + + :returns: The range of the dimension indexed by `index`. + :rtype: int + + + .. py:method:: size() + + Returns the size of a range. + + Returns the size of a range by multiplying + the range of the individual dimensions. + + :returns: The size of a range. + :rtype: int + + + + +.. py:class:: USMNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba.core.types.npytypes.Array` + + A type class to represent dpctl.tensor.usm_ndarray. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`copy `\ (dtype, ndim, layout, readonly, addrspace, device, usm_type) + - \- + * - :py:obj:`unify `\ (typingctx, other) + - Unify this with the *other* USMNdArray. + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Convert this USMNdArray to the *other*. + + + .. rubric:: Members + + .. py:method:: copy(dtype=None, ndim=None, layout=None, readonly=None, addrspace=None, device=None, usm_type=None) + + + .. py:method:: unify(typingctx, other) + + Unify this with the *other* USMNdArray. + + + .. py:method:: can_convert_to(typingctx, other) + + Convert this USMNdArray to the *other*. + + + + +.. py:class:: NdRange(global_size, local_size) + + Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + + The NdRange defines the index space for a work group as well as + the global index space. It is passed to parallel_for to execute + a kernel on a set of work items. + + This class basically contains two Range object, one for the global_range + and the other for the local_range. The global_range parameter contains + the global index space and the local_range parameter contains the index + space of a work group. This class mimics the behavior of `sycl::nd_range` + class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_range `\ () + - Returns a Range defining the index space. + * - :py:obj:`get_local_range `\ () + - Returns a Range defining the index space of a work group. + + + .. rubric:: Members + + .. py:method:: get_global_range() + + Returns a Range defining the index space. + + :returns: A `Range` object defining the index space. + :rtype: Range + + + .. py:method:: get_local_range() + + Returns a Range defining the index space of a work group. + + :returns: A `Range` object to specify index space of a work group. + :rtype: Range + + + + +.. py:class:: Range + + Bases: :py:obj:`tuple` + + Analogue to the :sycl_range:`sycl::range <>` class. + + The range is an abstraction that describes the number of elements + in each dimension of buffers and index spaces. It can contain + 1, 2, or 3 numbers, depending on the dimensionality of the + object it describes. + + This is just a wrapper class on top of a 3-tuple. The kernel launch + parameter is consisted of three int's. This class basically mimics + the behavior of `sycl::range`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get `\ (index) + - Returns the range of a single dimension. + * - :py:obj:`size `\ () + - Returns the size of a range. + + + .. rubric:: Members + + .. py:method:: get(index) + + Returns the range of a single dimension. + + :param index: The index of the dimension, i.e. [0,2] + :type index: int + + :returns: The range of the dimension indexed by `index`. + :rtype: int + + + .. py:method:: size() + + Returns the size of a range. + + Returns the size of a range by multiplying + the range of the individual dimensions. + + :returns: The size of a range. + :rtype: int + + + + +Functions +--------- +.. py:function:: unbox_range(typ, obj, c) + + Converts a Python Range object to numba-dpex's native struct representation + for RangeType. + + +.. py:function:: unbox_ndrange(typ, obj, c) + + Converts a Python Range object to numba-dpex's native struct representation + for NdRangeType. + + +.. py:function:: box_range(typ, val, c) + + Convert a native range structure to a Range object. + + +.. py:function:: box_ndrange(typ, val, c) + + Convert a native range structure to a Range object. + + +.. py:function:: unbox_dpnp_nd_array(typ, obj, c) + + Converts a dpctl.tensor.usm_ndarray/dpnp.ndarray object to a Numba-dpex + internal array structure. + + :param typ: The Numba type of the PyObject + :param obj: The actual PyObject to be unboxed + :param c: The unboxing context + + Returns: A NativeValue object representing an unboxed + dpctl.tensor.usm_ndarray/dpnp.ndarray + + +.. py:function:: box_array(typ, val, c) + + Boxes a NativeValue representation of USMNdArray/DpnpNdArray type into a + dpctl.tensor.usm_ndarray/dpnp.ndarray PyObject + + :param typ: The representation of the USMNdArray/DpnpNdArray type. + :param val: A native representation of a Numba USMNdArray/DpnpNdArray type + object. + :param c: The boxing context. + + Returns: A Pyobject for a dpctl.tensor.usm_ndarray/dpnp.ndarray boxed from + the Numba-dpex native value. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/boxing/ranges/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/ranges/index.rst.txt new file mode 100644 index 0000000000..4b4774d1b1 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/ranges/index.rst.txt @@ -0,0 +1,59 @@ + + +:orphan: + +numba_dpex.core.boxing.ranges +============================= + +.. py:module:: numba_dpex.core.boxing.ranges + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`unbox_range `\ (typ, obj, c) + - Converts a Python Range object to numba-dpex's native struct representation + * - :py:obj:`unbox_ndrange `\ (typ, obj, c) + - Converts a Python Range object to numba-dpex's native struct representation + * - :py:obj:`box_range `\ (typ, val, c) + - Convert a native range structure to a Range object. + * - :py:obj:`box_ndrange `\ (typ, val, c) + - Convert a native range structure to a Range object. + + + + +Functions +--------- +.. py:function:: unbox_range(typ, obj, c) + + Converts a Python Range object to numba-dpex's native struct representation + for RangeType. + + +.. py:function:: unbox_ndrange(typ, obj, c) + + Converts a Python Range object to numba-dpex's native struct representation + for NdRangeType. + + +.. py:function:: box_range(typ, val, c) + + Convert a native range structure to a Range object. + + +.. py:function:: box_ndrange(typ, val, c) + + Convert a native range structure to a Range object. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/boxing/usm_ndarray/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/usm_ndarray/index.rst.txt new file mode 100644 index 0000000000..0eb4ba65bf --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/boxing/usm_ndarray/index.rst.txt @@ -0,0 +1,60 @@ + + +:orphan: + +numba_dpex.core.boxing.usm_ndarray +================================== + +.. py:module:: numba_dpex.core.boxing.usm_ndarray + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`unbox_dpnp_nd_array `\ (typ, obj, c) + - Converts a dpctl.tensor.usm_ndarray/dpnp.ndarray object to a Numba-dpex + * - :py:obj:`box_array `\ (typ, val, c) + - Boxes a NativeValue representation of USMNdArray/DpnpNdArray type into a + + + + +Functions +--------- +.. py:function:: unbox_dpnp_nd_array(typ, obj, c) + + Converts a dpctl.tensor.usm_ndarray/dpnp.ndarray object to a Numba-dpex + internal array structure. + + :param typ: The Numba type of the PyObject + :param obj: The actual PyObject to be unboxed + :param c: The unboxing context + + Returns: A NativeValue object representing an unboxed + dpctl.tensor.usm_ndarray/dpnp.ndarray + + +.. py:function:: box_array(typ, val, c) + + Boxes a NativeValue representation of USMNdArray/DpnpNdArray type into a + dpctl.tensor.usm_ndarray/dpnp.ndarray PyObject + + :param typ: The representation of the USMNdArray/DpnpNdArray type. + :param val: A native representation of a Numba USMNdArray/DpnpNdArray type + object. + :param c: The boxing context. + + Returns: A Pyobject for a dpctl.tensor.usm_ndarray/dpnp.ndarray boxed from + the Numba-dpex native value. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/config/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/config/index.rst.txt new file mode 100644 index 0000000000..89b2eb0259 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/config/index.rst.txt @@ -0,0 +1,99 @@ + +numba_dpex.core.config +====================== + +.. py:module:: numba_dpex.core.config + +.. autoapi-nested-parse:: + + The config options are meant to provide extra information and tweak optimization + configurations to help debug code generation issues. + + There are two ways of setting these config options: + + - Config options can be directly set programmatically, *e.g.*, + + .. code-block:: python + + from numba_dpex.core.config import DUMP_KERNEL_LLVM + + DUMP_KERNEL_LLVM = 1 + + - The options can also be set globally using environment flags. The name of the + environment variable for every config option is annotated next to its + definition. + + .. code-block:: bash + + export NUMBA_DPEX_DUMP_KERNEL_LLVM = 1 + + + + + + + + +Attributes +---------- +.. py:data:: SAVE_IR_FILES + :type: Annotated[int, Save the IR files (LLVM and SPIRV-V) generated for each kernel to current directory, default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_SAVE_IR_FILES] + + + +.. py:data:: OFFLOAD_DIAGNOSTICS + :type: Annotated[int, Print diagnostic information for automatic offloading of parfor nodes to kernels, default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_OFFLOAD_DIAGNOSTICS] + + + +.. py:data:: DEBUG + :type: Annotated[int, Generates extra debug prints when set to a non-zero value, default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG] + + + +.. py:data:: DEBUGINFO_DEFAULT + :type: Annotated[int, Compiles in the debug mode generating debug symbols in the compiler IR. It is a global way of setting the "debug" keyword for all numba_dpex.kernel and numba_dpex.device_func decorators used in a program., default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_DEBUGINFO] + + + +.. py:data:: DUMP_KERNEL_LLVM + :type: Annotated[int, Writes the optimized LLVM IR generated for a numba_dpex.kernel decorated function to current directory, default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LLVM] + + + +.. py:data:: DUMP_KERNEL_LAUNCHER + :type: Annotated[int, Writes the optimized LLVM IR generated for every numba_dpex.call_kernel function to current directory, default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LAUNCHER] + + + +.. py:data:: DEBUG_KERNEL_LAUNCHER + :type: Annotated[int, Enables debug printf messages inside the compiled module generated for a numba_dpex.call_kernel function.default = 0, ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER] + + + +.. py:data:: BUILD_KERNEL_OPTIONS + :type: Annotated[str, Can use used to pass extra flags to the device driver compiler during kernel compilation. For available OpenCL options refer https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options, default = "", ENVIRONMENT FLAG: NUMBA_DPEX_BUILD_KERNEL_OPTIONS] + + + +.. py:data:: TESTING_SKIP_NO_DEBUGGING + + + +.. py:data:: TESTING_LOG_DEBUGGING + :type: Annotated[int, Generates extra logs when using gdb to debug a kernel, defaults = 0, ENVIRONMENT_FLAG: NUMBA_DPEX_TESTING_LOG_DEBUGGING] + + + +.. py:data:: DPEX_OPT + :type: Annotated[int, Sets the optimization level globally for every function compiled by numba-dpex, default = 2, ENVIRONMENT_FLAG: NUMBA_DPEX_OPT] + + + +.. py:data:: INLINE_THRESHOLD + :type: Annotated[int, Sets the inlining-threshold level globally for every function compiled by numba-dpex. A higher value enables more aggressive inlining settings for the compiler. Note: Even if NUMBA_DPEX_INLINE_THRESHOLD is set to 0, many internal functions that are attributed "alwaysinline" will still get inlined., default = 2, ENVIRONMENT_FLAG: NUMBA_DPEX_INLINE_THRESHOLD] + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/index.rst.txt new file mode 100644 index 0000000000..a4b03c4e7e --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.datamodel +========================= + +.. py:module:: numba_dpex.core.datamodel + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/models/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/models/index.rst.txt new file mode 100644 index 0000000000..2a15df6d5c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/datamodel/models/index.rst.txt @@ -0,0 +1,248 @@ + + +:orphan: + +numba_dpex.core.datamodel.models +================================ + +.. py:module:: numba_dpex.core.datamodel.models + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`GenericPointerModel ` + - A primitive type can be represented natively in the target in all + * - :py:obj:`IntEnumLiteralModel ` + - Representation of an object of LiteralIntEnum type using Numba's + * - :py:obj:`USMArrayDeviceModel ` + - A data model to represent a usm array type in the LLVM IR generated for a + * - :py:obj:`USMArrayHostModel ` + - Data model for the USMNdArray type when used in a host-only function. + * - :py:obj:`SyclQueueModel ` + - Represents the native data model for a dpctl.SyclQueue PyObject. + * - :py:obj:`SyclEventModel ` + - Represents the native data model for a dpctl.SyclEvent PyObject. + * - :py:obj:`RangeModel ` + - The numba_dpex data model for a numba_dpex.kernel_api.Range PyObject. + * - :py:obj:`NdRangeModel ` + - The numba_dpex data model for a numba_dpex.kernel_api.NdRange PyObject. + * - :py:obj:`AtomicRefModel ` + - Data model for AtomicRefType. + * - :py:obj:`EmptyStructModel ` + - Data model that does not take space. Intended to be used with types that + * - :py:obj:`DpctlMDLocalAccessorModel ` + - Data model to represent DpctlMDLocalAccessorType. + * - :py:obj:`LocalAccessorModel ` + - Data model for the LocalAccessor type when used in a host-only function. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_flattened_member_count `\ (ty) + - Returns the number of fields in an instance of a given StructModel. + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dpex_data_model_manager ` + - \- + * - :py:obj:`dpjit_data_model_manager ` + - \- + + +Classes +------- + +.. py:class:: GenericPointerModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.PrimitiveModel` + + A primitive type can be represented natively in the target in all + usage contexts. + + + + +.. py:class:: IntEnumLiteralModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.PrimitiveModel` + + Representation of an object of LiteralIntEnum type using Numba's + PrimitiveModel that can be represented natively in the target in all + usage contexts. + + + + +.. py:class:: USMArrayDeviceModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + A data model to represent a usm array type in the LLVM IR generated for a + device-only kernel function. + + The USMArrayDeviceModel adds an extra address space attribute to the data + member. The extra attribute is needed when passing usm_ndarray array + arguments to kernels that are compiled for certain OpenCL GPU devices. Note + that the address space attribute is applied only to the data member and not + other members of USMArrayDeviceModel that are pointers. It is done this way + as other pointer members such as meminfo are not used inside a kernel and + these members maybe removed from the USMArrayDeviceModel in + future (refer #929). + + We use separate data models for host (USMArrayHostModel) and device + (USMArrayDeviceModel) as the address space attribute is only required for + kernel functions and not needed for functions that are compiled for a host + memory space. + + + + +.. py:class:: USMArrayHostModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Data model for the USMNdArray type when used in a host-only function. + + USMArrayHostModel is used by the numba_dpex.types.USMNdArray and + numba_dpex.types.DpnpNdArray type and abstracts the usmarystruct_t C type + defined in numba_dpex.core.runtime._usmarraystruct.h. + + The USMArrayDeviceModel differs from numba's ArrayModel by including an + extra member sycl_queue that maps to _usmarraystruct.sycl_queue pointer. The + _usmarraystruct.sycl_queue pointer stores the C++ sycl::queue pointer that + was used to allocate the data for the dpctl.tensor.usm_ndarray or + dpnp.ndarray represented by an instance of _usmarraystruct. + + + + +.. py:class:: SyclQueueModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Represents the native data model for a dpctl.SyclQueue PyObject. + + Numba-dpex uses a C struct as defined in + numba_dpex/core/runtime._queuestruct.h to store the required attributes for + a ``dpctl.SyclQueue`` Python object. + + - ``queue_ref``: An opaque C pointer to an actual SYCL queue C++ object. + - ``parent``: A PyObject* that stores a reference back to the original + ``dpctl.SyclQueue`` PyObject if the native struct is + created by unboxing the PyObject. + + + + +.. py:class:: SyclEventModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Represents the native data model for a dpctl.SyclEvent PyObject. + + Numba-dpex uses a C struct as defined in + numba_dpex/core/runtime._eventstruct.h to store the required attributes for + a ``dpctl.SyclEvent`` Python object. + + - ``event_ref``: An opaque C pointer to an actual SYCL event C++ object. + - ``parent``: A PyObject* that stores a reference back to the original + ``dpctl.SyclEvent`` PyObject if the native struct is + created by unboxing the PyObject. + + + + +.. py:class:: RangeModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + The numba_dpex data model for a numba_dpex.kernel_api.Range PyObject. + + + + +.. py:class:: NdRangeModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + The numba_dpex data model for a numba_dpex.kernel_api.NdRange PyObject. + + + + +.. py:class:: AtomicRefModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Data model for AtomicRefType. + + + + +.. py:class:: EmptyStructModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Data model that does not take space. Intended to be used with types that + are presented only at typing stage and not represented physically. + + + + +.. py:class:: DpctlMDLocalAccessorModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Data model to represent DpctlMDLocalAccessorType. + + Must be the same structure as + dpctl/syclinterface/dpctl_sycl_queue_interface.h::MDLocalAccessor. + + Structure intended to be used only on host side of the kernel call. + + + + +.. py:class:: LocalAccessorModel(dmm, fe_type) + + Bases: :py:obj:`numba.core.datamodel.models.StructModel` + + Data model for the LocalAccessor type when used in a host-only function. + + + + +Functions +--------- +.. py:function:: get_flattened_member_count(ty) + + Returns the number of fields in an instance of a given StructModel. + + + +Attributes +---------- +.. py:data:: dpex_data_model_manager + + + +.. py:data:: dpjit_data_model_manager + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/debuginfo/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/debuginfo/index.rst.txt new file mode 100644 index 0000000000..6dd7c6b484 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/debuginfo/index.rst.txt @@ -0,0 +1,79 @@ + + +:orphan: + +numba_dpex.core.debuginfo +========================= + +.. py:module:: numba_dpex.core.debuginfo + +.. autoapi-nested-parse:: + + Implements a custom debug metadata generator class for numba-dpex kernels. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DIBuilder ` + - Overrides Numba's default DIBuilder with numba-dpex-specific customizations. + + + + +Classes +------- + +.. py:class:: DIBuilder(module, filepath, cgctx, directives_only) + + Bases: :py:obj:`numba.core.debuginfo.DIBuilder` + + Overrides Numba's default DIBuilder with numba-dpex-specific customizations. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`mark_subprogram `\ (function, qualname, argnames, argtypes, line) + - Sets DW_AT_name and DW_AT_linkagename tags for a kernel decorated function. + + + .. rubric:: Members + + .. py:method:: mark_subprogram(function, qualname, argnames, argtypes, line) + + Sets DW_AT_name and DW_AT_linkagename tags for a kernel decorated function. + + Numba generates a unique name for every function it compiles, but in + upstream Numba the unique name is not used as the "qualified" name of + the function. The behavior leads to a bug discovered in Numba-dpex when + a compiled function uses closure variables. + Refer (https://github.com/IntelPython/numba-dpex/issues/898). + To resolve the issue numba-dpex uses the unique_name as the qualified + name. Refer to + :class:`numba_dpex.core.passes.passes.QualNameDisambiguationLowering`. + However, doing so breaks setting GDB breakpoints based on function + name as the function name is no longer what is in the source, but what + is the unique name generated by Numba. To fix it, numba-dpex uses a + modified DISubprogram metadata generator. The name (DW_AT_name) tag is + set to the base function name, discarding the unique qualifier and + linkagename is set to an empty string. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/decorators/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/decorators/index.rst.txt new file mode 100644 index 0000000000..61393f9d3f --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/decorators/index.rst.txt @@ -0,0 +1,232 @@ + + +:orphan: + +numba_dpex.core.decorators +========================== + +.. py:module:: numba_dpex.core.decorators + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`kernel `\ (function_or_signature, \*\*options) + - A decorator to compile a function written using :py:mod:`numba_dpex.kernel_api`. + * - :py:obj:`device_func `\ (function_or_signature, \*\*options) + - Compiles a device-callable function that can be only invoked from a kernel. + * - :py:obj:`dpjit `\ (\*args, \*\*kws) + - \- + + + + +Functions +--------- +.. py:function:: kernel(function_or_signature=None, **options) + + A decorator to compile a function written using :py:mod:`numba_dpex.kernel_api`. + + The ``kernel`` decorator triggers the compilation of a function written + using the data-parallel kernel programming API exposed by + :py:mod:`numba_dpex.kernel_api`. Such a function is conceptually + equivalent to a kernel function written in the C++ SYCL eDSL. The + decorator will compile the function based on the types of the arguments + to a SPIR-V binary that can be executed either on OpenCL CPU, GPU + devices or Intel Level Zero GPU devices. + + Any function to be compilable using the kernel decorator should + adhere to the following semantic rules: + + - The first argument to the function should be either an instance of the + :class:`numba_dpex.kernel_api.Item` class or an instance of the + :class:`numba_dpex.kernel_api.NdItem`. + + - The function should not return any value. + + - The function should have at least one array type argument that can + either be an instance of ``dpnp.ndarray`` or an instance of + ``dpctl.tensor.usm_ndarray``. + + + :param signature_or_function: An optional signature or list of + signatures for which a function is to be compiled. Passing in a + signature "specializes" the decorated function and no other versions + of the function will be compiled. A function can also be + directly passed instead of a signature and the signature will get + inferred from the function. The actual compilation happens on every + invocation of the :func:`numba_dpex.experimental.call_kernel` + function where the decorated function is passed in as an argument + along with the argument values for the decorated function. + :type signature_or_function: optional + :param options: + - **debug** (bool): Whether the compilation should happen in debug + mode. *(Default = False)* + - **inline_threshold** (int): Specifies the level of inlining that + the compiler should attempt. *(Default = 2)* + :type options: optional + + :returns: An instance of + :class:`numba_dpex.kernel_api_impl.spirv.dispatcher.KernelDispatcher`. + The ``KernelDispatcher`` object compiles the decorated function when + passed in to :func:`numba_dpex.experimental.call_kernel`. + + Examples: + + 1. Decorate a function and pass it to ``call_kernel`` for compilation and + execution. + + .. code-block:: python + + import dpnp + import numba_dpex as dpex + from numba_dpex import kernel_api as kapi + + + # Data parallel kernel implementing vector sum + @dpex.kernel + def vecadd(item: kapi.Item, a, b, c): + i = item.get_id(0) + c[i] = a[i] + b[i] + + + N = 1024 + a = dpnp.ones(N) + b = dpnp.ones_like(a) + c = dpnp.zeros_like(a) + dpex.call_kernel(vecadd, kapi.Range(N), a, b, c) + + 2. Specializes a kernel and then compiles it directly before executing it + via ``call_kernel``. The kernel is specialized to expect a 1-D + ``dpnp.ndarray`` with either ``float32`` type elements or ``int64`` type + elements. + + .. code-block:: python + + import dpnp + import numba_dpex as dpex + from numba_dpex import kernel_api as kapi + from numba_dpex import DpnpNdArray, float32, int64 + from numba_dpex.core.types.kernel_api.index_space_ids import ItemType + + i64arrty = DpnpNdArray(ndim=1, dtype=int64, layout="C") + f32arrty = DpnpNdArray(ndim=1, dtype=float32, layout="C") + item_ty = ItemType(ndim=1) + + specialized_kernel = dpex.kernel( + [ + (item_ty, i64arrty, i64arrty, i64arrty), + (item_ty, f32arrty, f32arrty, f32arrty), + ] + ) + + + def vecadd(item: kapi.Item, a, b, c): + i = item.get_id(0) + c[i] = a[i] + b[i] + + + # Compile all specializations for vecadd + precompiled_kernels = specialized_kernel(vecadd) + N = 1024 + a = dpnp.ones(N, dtype=dpnp.int64) + b = dpnp.ones_like(a) + c = dpnp.zeros_like(a) + # Call a specific pre-compiled version of vecadd + dpex.call_kernel(precompiled_kernels, kapi.Range(N), a, b, c) + + + +.. py:function:: device_func(function_or_signature=None, **options) + + Compiles a device-callable function that can be only invoked from a kernel. + + The decorator is used to express auxiliary device-only functions that can + be called from a kernel or another device function, but are not callable + from the host. This decorator :func:`numba_dpex.experimental.device_func` + has no direct analogue in SYCL and primarily is provided to help programmers + make their kapi applications modular. + + A ``device_func`` decorated function does not require the first argument to + be a :class:`numba_dpex.kernel_api.Item` object or a + :class:`numba_dpex.kernel_api.NdItem` object, and unlike a ``kernel`` + decorated function is allowed to return any value. + All :py:mod:`numba_dpex.kernel_api` functionality can be used in a + ``device_func`` decorated function. + + The decorator is also used to compile overloads in the ``DpexKernelTarget``. + + A ``device_func`` decorated function is not compiled down to device binary + and instead is compiled down to LLVM IR. Final compilation to binary happens + when the function is invoked from a ``kernel`` decorated function. The + compilation happens this was to allow a ``device_func`` decorated function + to be internally linked into the kernel module at the LLVM level, leading to + more optimization opportunities. + + :param signature_or_function: An optional signature or list of + signatures for which a function is to be compiled. Passing in a + signature "specializes" the decorated function and no other versions + of the function will be compiled. A function can also be + directly passed instead of a signature and the signature will get + inferred from the function. The actual compilation happens on every + invocation of the decorated function from another ``device_func`` or + ``kernel`` decorated function. + :type signature_or_function: optional + :param options: + - **debug** (bool): Whether the compilation should happen in debug + mode. *(Default = False)* + - **inline_threshold** (int): Specifies the level of inlining that + the compiler should attempt. *(Default = 2)* + :type options: optional + + :returns: An instance of + :class:`numba_dpex.kernel_api_impl.spirv.dispatcher.KernelDispatcher`. + The ``KernelDispatcher`` object compiles the decorated function when + it is called from another function. + + Example: + + .. code-block:: python + + import dpnp + + from numba_dpex import experimental as dpex_exp + from numba_dpex import kernel_api as kapi + + + @dpex_exp.device_func + def increment_value(nd_item: NdItem, a): + i = nd_item.get_global_id(0) + + a[i] += 1 + group_barrier(nd_item.get_group(), MemoryScope.DEVICE) + + if i == 0: + for idx in range(1, a.size): + a[0] += a[idx] + + + @dpex_exp.kernel + def another_kernel(nd_item: NdItem, a): + increment_value(nd_item, a) + + + N = 16 + b = dpnp.ones(N, dtype=dpnp.int32) + + dpex_exp.call_kernel(another_kernel, dpex.NdRange((N,), (N,)), b) + + +.. py:function:: dpjit(*args, **kws) + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/descriptor/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/descriptor/index.rst.txt new file mode 100644 index 0000000000..02ac2fcdf3 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/descriptor/index.rst.txt @@ -0,0 +1,174 @@ + + +:orphan: + +numba_dpex.core.descriptor +========================== + +.. py:module:: numba_dpex.core.descriptor + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpexTargetOptions ` + - Target options maps user options from decorators to the + * - :py:obj:`DpexKernelTarget ` + - Implements a target descriptor for numba_dpex.kernel decorated functions. + * - :py:obj:`DpexTarget ` + - Implements a target descriptor for numba_dpex.dpjit decorated functions. + + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dpex_kernel_target ` + - \- + * - :py:obj:`dpex_target ` + - \- + + +Classes +------- + +.. py:class:: DpexTargetOptions + + Bases: :py:obj:`numba.core.cpu.CPUTargetOptions` + + Target options maps user options from decorators to the + ``numba.core.compiler.Flags`` used by lowering and target context. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`experimental ` + - \- + * - :py:obj:`release_gil ` + - \- + * - :py:obj:`no_compile ` + - \- + * - :py:obj:`inline_threshold ` + - \- + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`finalize `\ (flags, options) + - Subclasses can override this method to make target specific + + + .. rubric:: Members + + .. py:attribute:: experimental + + + + .. py:attribute:: release_gil + + + + .. py:attribute:: no_compile + + + + .. py:attribute:: inline_threshold + + + + .. py:method:: finalize(flags, options) + + Subclasses can override this method to make target specific + customizations of default flags. + + :param flags: + :type flags: Flags + :param options: + :type options: dict + + + + +.. py:class:: DpexKernelTarget(target_name) + + Bases: :py:obj:`numba.core.descriptors.TargetDescriptor` + + Implements a target descriptor for numba_dpex.kernel decorated functions. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`options ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: options + + + + + +.. py:class:: DpexTarget(target_name) + + Bases: :py:obj:`numba.core.descriptors.TargetDescriptor` + + Implements a target descriptor for numba_dpex.dpjit decorated functions. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`options ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: options + + + + + + +Attributes +---------- +.. py:data:: dpex_kernel_target + + + +.. py:data:: dpex_target + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/dpjit_dispatcher/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/dpjit_dispatcher/index.rst.txt new file mode 100644 index 0000000000..9e9552f0fe --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/dpjit_dispatcher/index.rst.txt @@ -0,0 +1,63 @@ + + +:orphan: + +numba_dpex.core.dpjit_dispatcher +================================ + +.. py:module:: numba_dpex.core.dpjit_dispatcher + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpjitDispatcher ` + - A dpex.djit-specific dispatcher. + + + + +Classes +------- + +.. py:class:: DpjitDispatcher(py_func, locals={}, targetoptions={}, pipeline_class=dpjit_compiler.DpjitCompiler) + + Bases: :py:obj:`numba.core.dispatcher.Dispatcher` + + A dpex.djit-specific dispatcher. + + The DpjitDispatcher sets the targetdescr string to "dpex" so that Numba's + Dispatcher can lookup the global target_registry with that string and + correctly use the DpexTarget context. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`targetdescr ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: targetdescr + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/exceptions/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/exceptions/index.rst.txt new file mode 100644 index 0000000000..ada5ed3206 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/exceptions/index.rst.txt @@ -0,0 +1,22 @@ + + +:orphan: + +numba_dpex.core.exceptions +========================== + +.. py:module:: numba_dpex.core.exceptions + +.. autoapi-nested-parse:: + + The module defines the custom error classes used in numba_dpex. + + + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/index.rst.txt new file mode 100644 index 0000000000..e1dd2d6f5a --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/index.rst.txt @@ -0,0 +1,340 @@ + +numba_dpex.core +=============== + +.. py:module:: numba_dpex.core + + +Subpackages +----------- +.. toctree:: + :titlesonly: + :maxdepth: 3 + + boxing/index.rst + datamodel/index.rst + overloads/index.rst + parfors/index.rst + passes/index.rst + pipelines/index.rst + runtime/index.rst + targets/index.rst + types/index.rst + typing/index.rst + utils/index.rst + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpctlSyclQueue ` + - A Numba type to represent a dpctl.SyclQueue PyObject. + * - :py:obj:`DpctlSyclEvent ` + - A Numba type to represent a dpctl.SyclEvent PyObject. + * - :py:obj:`DpnpNdArray ` + - The Numba type to represent an dpnp.ndarray. The type has the same + * - :py:obj:`IntEnumLiteral ` + - A Literal type for IntEnum objects. The type contains the original Python + * - :py:obj:`KernelDispatcherType ` + - The type of KernelDispatcher dispatchers + * - :py:obj:`NdRangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`RangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`USMNdArray ` + - A type class to represent dpctl.tensor.usm_ndarray. + + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`none ` + - \- + * - :py:obj:`uint32 ` + - \- + * - :py:obj:`uint64 ` + - \- + * - :py:obj:`int32 ` + - \- + * - :py:obj:`int64 ` + - \- + * - :py:obj:`float32 ` + - \- + * - :py:obj:`float64 ` + - \- + * - :py:obj:`b1 ` + - \- + * - :py:obj:`i4 ` + - \- + * - :py:obj:`i8 ` + - \- + * - :py:obj:`u4 ` + - \- + * - :py:obj:`u8 ` + - \- + * - :py:obj:`f4 ` + - \- + * - :py:obj:`f8 ` + - \- + * - :py:obj:`float_ ` + - \- + * - :py:obj:`double ` + - \- + * - :py:obj:`usm_ndarray ` + - \- + * - :py:obj:`void ` + - \- + + +Classes +------- + +.. py:class:: DpctlSyclQueue(sycl_queue) + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclQueue PyObject. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`rand_digit_str `\ (n) + - \- + + + .. rubric:: Members + + .. py:method:: rand_digit_str(n) + + + + +.. py:class:: DpctlSyclEvent + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclEvent PyObject. + + + + +.. py:class:: DpnpNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba_dpex.core.types.usm_ndarray_type.USMNdArray` + + The Numba type to represent an dpnp.ndarray. The type has the same + structure as USMNdArray used to represent dpctl.tensor.usm_ndarray. + + + + +.. py:class:: IntEnumLiteral(value) + + Bases: :py:obj:`numba.core.types.Literal`, :py:obj:`numba.core.types.Integer` + + A Literal type for IntEnum objects. The type contains the original Python + value of the IntEnum class in it. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Check whether this type can be converted to the *other*. + + + .. rubric:: Members + + .. py:method:: can_convert_to(typingctx, other) -> bool + + Check whether this type can be converted to the *other*. + If successful, must return a string describing the conversion, e.g. + "exact", "promote", "unsafe", "safe"; otherwise None is returned. + + + + +.. py:class:: KernelDispatcherType(dispatcher) + + Bases: :py:obj:`numba.core.types.Dispatcher` + + The type of KernelDispatcher dispatchers + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + +.. py:class:: NdRangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.NdRange` + + + + +.. py:class:: RangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.Range` + + + + +.. py:class:: USMNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba.core.types.npytypes.Array` + + A type class to represent dpctl.tensor.usm_ndarray. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`copy `\ (dtype, ndim, layout, readonly, addrspace, device, usm_type) + - \- + * - :py:obj:`unify `\ (typingctx, other) + - Unify this with the *other* USMNdArray. + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Convert this USMNdArray to the *other*. + + + .. rubric:: Members + + .. py:method:: copy(dtype=None, ndim=None, layout=None, readonly=None, addrspace=None, device=None, usm_type=None) + + + .. py:method:: unify(typingctx, other) + + Unify this with the *other* USMNdArray. + + + .. py:method:: can_convert_to(typingctx, other) + + Convert this USMNdArray to the *other*. + + + + + +Attributes +---------- +.. py:data:: none + + + +.. py:data:: uint32 + + + +.. py:data:: uint64 + + + +.. py:data:: int32 + + + +.. py:data:: int64 + + + +.. py:data:: float32 + + + +.. py:data:: float64 + + + +.. py:data:: b1 + + + +.. py:data:: i4 + + + +.. py:data:: i8 + + + +.. py:data:: u4 + + + +.. py:data:: u8 + + + +.. py:data:: f4 + + + +.. py:data:: f8 + + + +.. py:data:: float_ + + + +.. py:data:: double + + + +.. py:data:: usm_ndarray + + + +.. py:data:: void + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/kernel_launcher/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/kernel_launcher/index.rst.txt new file mode 100644 index 0000000000..308b5bc958 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/kernel_launcher/index.rst.txt @@ -0,0 +1,87 @@ + + +:orphan: + +numba_dpex.core.kernel_launcher +=============================== + +.. py:module:: numba_dpex.core.kernel_launcher + +.. autoapi-nested-parse:: + + Provides a helper function to call a numba_dpex.kernel decorated function + from either CPython or a numba_dpex.dpjit decorated function. + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`call_kernel `\ (kernel_fn, index_space, \*kernel_args) + - Compiles and synchronously executes a kernel function. + * - :py:obj:`call_kernel_async `\ (kernel_fn, index_space, dependent_events, \*kernel_args) + - Compiles and asynchronously executes a kernel function. + + + + +Functions +--------- +.. py:function:: call_kernel(kernel_fn, index_space, *kernel_args) -> None + + Compiles and synchronously executes a kernel function. + + Kernel execution happens in synchronous way, so the main thread will be + blocked till the kernel done execution. + + :param kernel_fn: A + :func:`numba_dpex.experimental.kernel` decorated function that is + compiled to a ``KernelDispatcher``. + :type kernel_fn: numba_dpex.experimental.KernelDispatcher + :param index_space: A Range or NdRange type object that + specifies the index space for the kernel. + :type index_space: Range | NdRange + :param kernel_args: List of objects that are passed to the numba_dpex.kernel + decorated function. + + +.. py:function:: call_kernel_async(kernel_fn, index_space, dependent_events: list[dpctl.SyclEvent], *kernel_args) -> tuple[dpctl.SyclEvent, dpctl.SyclEvent] + + Compiles and asynchronously executes a kernel function. + + Calls a :func:`numba_dpex.experimental.kernel` decorated function + asynchronously from CPython or from a :func:`numba_dpex.dpjit` function. As + the kernel execution happens asynchronously, so the main thread will not be + blocked till the kernel done execution. Instead the function returns back to + caller a handle for an *event* to track kernel execution. It is a user's + responsibility to properly track kernel execution completion and not use any + data that may still be used by the kernel prior to the kernel's completion. + + :param kernel_fn: A + :func:`numba_dpex.experimental.kernel` decorated function that is + compiled to a ``KernelDispatcher``. + :type kernel_fn: KernelDispatcher + :param index_space: A Range or NdRange type object that + specifies the index space for the kernel. + :type index_space: Range | NdRange + :param kernel_args: List of objects that are passed to the numba_dpex.kernel + decorated function. + + :returns: A pair of ``dpctl.SyclEvent`` objects. The pair of events constitute of + a host task and an event associated with the kernel execution. The event + associated with the kernel execution indicates the execution status of + the submitted kernel function. The host task manages the lifetime of any + PyObject passed in as a kernel argument and automatically decrements the + reference count of the object on kernel execution completion. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/lowering/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/lowering/index.rst.txt new file mode 100644 index 0000000000..ad0d35b235 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/lowering/index.rst.txt @@ -0,0 +1,65 @@ + + +:orphan: + +numba_dpex.core.lowering +======================== + +.. py:module:: numba_dpex.core.lowering + +.. autoapi-nested-parse:: + + Registers any custom lowering functions to default Numba lowering registry. + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dpex_dispatcher_const `\ (context) + - Dummy lowering function for a KernelDispatcherType object. + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`registry ` + - \- + * - :py:obj:`lower_constant ` + - \- + + + +Functions +--------- +.. py:function:: dpex_dispatcher_const(context) + + Dummy lowering function for a KernelDispatcherType object. + + The dummy lowering function for the KernelDispatcher types is added so that + a :func:`numba_dpex.core.decorators.kernel` decorated function can be passed + as an argument to dpjit. + + + +Attributes +---------- +.. py:data:: registry + + + +.. py:data:: lower_constant + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/overloads/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/overloads/index.rst.txt new file mode 100644 index 0000000000..e490aca9fb --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/overloads/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.overloads +========================= + +.. py:module:: numba_dpex.core.overloads + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/overloads/ranges_overloads/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/overloads/ranges_overloads/index.rst.txt new file mode 100644 index 0000000000..7ee44909ba --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/overloads/ranges_overloads/index.rst.txt @@ -0,0 +1,24 @@ + + +:orphan: + +numba_dpex.core.overloads.ranges_overloads +========================================== + +.. py:module:: numba_dpex.core.overloads.ranges_overloads + + + + + + + +Attributes +---------- +.. py:data:: DPEX_TARGET_NAME + :value: 'dpex' + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/index.rst.txt new file mode 100644 index 0000000000..90355b8399 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/index.rst.txt @@ -0,0 +1,16 @@ + +numba_dpex.core.parfors +======================= + +.. py:module:: numba_dpex.core.parfors + + +Subpackages +----------- +.. toctree:: + :titlesonly: + :maxdepth: 3 + + kernel_templates/index.rst + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_builder/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_builder/index.rst.txt new file mode 100644 index 0000000000..809a2c3746 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_builder/index.rst.txt @@ -0,0 +1,81 @@ + + +:orphan: + +numba_dpex.core.parfors.kernel_builder +====================================== + +.. py:module:: numba_dpex.core.parfors.kernel_builder + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ParforKernel ` + - \- + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`create_kernel_for_parfor `\ (lowerer, parfor_node, typemap, loop_ranges, races, parfor_outputs) + - Creates a numba_dpex.kernel function for a parfor node. + * - :py:obj:`update_sentinel `\ (kernel_ir, sentinel_name, kernel_body, new_label) + - Searched all the blocks in the IR generated from a kernel template and + + + +Classes +------- + +.. py:class:: ParforKernel(signature, kernel_args, kernel_arg_types, local_accessors=None, work_group_size=None, kernel_module=None) + + + + +Functions +--------- +.. py:function:: create_kernel_for_parfor(lowerer, parfor_node, typemap, loop_ranges, races, parfor_outputs) -> ParforKernel + + Creates a numba_dpex.kernel function for a parfor node. + + There are two parts to this function: + + 1) Code to iterate across the iteration space as defined by + the schedule. + 2) The parfor body that does the work for a single point in + the iteration space. + + Part 1 is created as Python text for simplicity with a sentinel + assignment to mark the point in the IR where the parfor body + should be added. This Python text is 'exec'ed into existence and its + IR retrieved with run_frontend. The IR is scanned for the sentinel + assignment where that basic block is split and the IR for the parfor + body inserted. + + +.. py:function:: update_sentinel(kernel_ir, sentinel_name, kernel_body, new_label) + + Searched all the blocks in the IR generated from a kernel template and + replaces the __sentinel__ instruction with the actual op for the parfor. + + :param kernel_ir: Numba FunctionIR that was generated from a kernel template + :param sentinel_name: The name of the sentinel instruction that is to be + :param replaced.: + :param kernel_body: The function body of the kernel template generated + :param numba_dpex.kernel function: + :param new_label: The new label to be used for the basic block created to store + :param the instructions that replaced the sentinel: + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/index.rst.txt new file mode 100644 index 0000000000..5459e0caa4 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/index.rst.txt @@ -0,0 +1,18 @@ + +numba_dpex.core.parfors.kernel_templates +======================================== + +.. py:module:: numba_dpex.core.parfors.kernel_templates + +.. autoapi-nested-parse:: + + Provides string templates for numba_dpex.kernel decorated functions. + + During lowering of a parfor node using the SPIRVKernelTarget, the node is + first converted into a kernel function. The module provides a set of templates + to generate the basic stub of a kernel function. The string template is + compiled down to Numba IR using the Numba compiler front end and then the + necessary body of the kernel function is inserted directly as Numba IR. + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/kernel_template_iface/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/kernel_template_iface/index.rst.txt new file mode 100644 index 0000000000..1cdc3b7e7d --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/kernel_template_iface/index.rst.txt @@ -0,0 +1,54 @@ + + +:orphan: + +numba_dpex.core.parfors.kernel_templates.kernel_template_iface +============================================================== + +.. py:module:: numba_dpex.core.parfors.kernel_templates.kernel_template_iface + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`KernelTemplateInterface ` + - \- + + + + +Classes +------- + +.. py:class:: KernelTemplateInterface + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dump_kernel_string `\ () + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: dump_kernel_string() + :abstractmethod: + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/range_kernel_template/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/range_kernel_template/index.rst.txt new file mode 100644 index 0000000000..ddcbd6e199 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/range_kernel_template/index.rst.txt @@ -0,0 +1,58 @@ + + +:orphan: + +numba_dpex.core.parfors.kernel_templates.range_kernel_template +============================================================== + +.. py:module:: numba_dpex.core.parfors.kernel_templates.range_kernel_template + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`RangeKernelTemplate ` + - A template class to generate a numba_dpex.kernel decorated function + + + + +Classes +------- + +.. py:class:: RangeKernelTemplate(kernel_name, kernel_params, kernel_rank, ivar_names, sentinel_name, loop_ranges, param_dict) + + A template class to generate a numba_dpex.kernel decorated function + representing a basic range kernel. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dump_kernel_string `\ () + - Helper to print the kernel function string. + + + .. rubric:: Members + + .. py:method:: dump_kernel_string() + + Helper to print the kernel function string. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/reduction_template/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/reduction_template/index.rst.txt new file mode 100644 index 0000000000..9fe45b76cd --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/kernel_templates/reduction_template/index.rst.txt @@ -0,0 +1,91 @@ + + +:orphan: + +numba_dpex.core.parfors.kernel_templates.reduction_template +=========================================================== + +.. py:module:: numba_dpex.core.parfors.kernel_templates.reduction_template + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`TreeReduceIntermediateKernelTemplate ` + - The class to build reduction main kernel_txt template and + * - :py:obj:`RemainderReduceIntermediateKernelTemplate ` + - The class to build reduction remainder kernel_txt template and + + + + +Classes +------- + +.. py:class:: TreeReduceIntermediateKernelTemplate(kernel_name, kernel_params, ivar_names, sentinel_name, loop_ranges, param_dict, parfor_dim, redvars, parfor_args, parfor_reddict, redvars_dict, local_accessors_dict, typemap) + + Bases: :py:obj:`numba_dpex.core.parfors.kernel_templates.kernel_template_iface.KernelTemplateInterface` + + The class to build reduction main kernel_txt template and + compiled Numba functionIR. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dump_kernel_string `\ () + - Helper to print the kernel function string. + + + .. rubric:: Members + + .. py:method:: dump_kernel_string() + + Helper to print the kernel function string. + + + + +.. py:class:: RemainderReduceIntermediateKernelTemplate(kernel_name, kernel_params, sentinel_name, redvars, parfor_reddict, redvars_dict, typemap, legal_loop_indices, global_size_var_name, global_size_mod_var_name, partial_sum_size_var_name, partial_sum_var_name, final_sum_var_name, reductionKernelVar) + + Bases: :py:obj:`numba_dpex.core.parfors.kernel_templates.kernel_template_iface.KernelTemplateInterface` + + The class to build reduction remainder kernel_txt template and + compiled Numba functionIR. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dump_kernel_string `\ () + - Helper to print the kernel function string. + + + .. rubric:: Members + + .. py:method:: dump_kernel_string() + + Helper to print the kernel function string. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_diagnostics/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_diagnostics/index.rst.txt new file mode 100644 index 0000000000..45db17651c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_diagnostics/index.rst.txt @@ -0,0 +1,63 @@ + + +:orphan: + +numba_dpex.core.parfors.parfor_diagnostics +========================================== + +.. py:module:: numba_dpex.core.parfors.parfor_diagnostics + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ExtendedParforDiagnostics ` + - Holds parfor diagnostic info, this is accumulated throughout the + + + + +Classes +------- + +.. py:class:: ExtendedParforDiagnostics + + Bases: :py:obj:`numba.parfors.parfor.ParforDiagnostics` + + Holds parfor diagnostic info, this is accumulated throughout the + PreParforPass and ParforPass, also in the closure inlining! + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dump `\ (level) + - \- + * - :py:obj:`print_auto_offloading `\ (lines) + - \- + + + .. rubric:: Members + + .. py:method:: dump(level=1) + + + .. py:method:: print_auto_offloading(lines) + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_lowerer/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_lowerer/index.rst.txt new file mode 100644 index 0000000000..c7573b79ff --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_lowerer/index.rst.txt @@ -0,0 +1,92 @@ + + +:orphan: + +numba_dpex.core.parfors.parfor_lowerer +====================================== + +.. py:module:: numba_dpex.core.parfors.parfor_lowerer + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ParforLowerImpl ` + - Provides a custom lowerer for parfor nodes that generates a SYCL kernel + * - :py:obj:`ParforLowerFactory ` + - A pseudo-factory class that maps a device filter string to a lowering + + + + +Classes +------- + +.. py:class:: ParforLowerImpl + + Provides a custom lowerer for parfor nodes that generates a SYCL kernel + for a parfor and submits it to a queue. + + + + +.. py:class:: ParforLowerFactory + + A pseudo-factory class that maps a device filter string to a lowering + function. + + Each Parfor instruction can have an optional "lowerer" attribute. The + lowerer attribute determines how the parfor instruction should be lowered + to LLVM IR. In addition, the lower attribute decides which parfor + instructions can be fused together. + + The factory class maintains a dictionary mapping every device + type (filter string) encountered so far to a lowerer function for that + device type. At this point numba-dpex does not generate device-specific code + and the lowerer used is same for all device types. However, as a different + ParforLowerImpl instance is returned for every parfor instruction that has + a distinct compute-follows-data inferred device it prevents illegal + parfor fusion. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`device_to_lowerer_map ` + - \- + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_lowerer `\ (device) + - :summarylabel:`class` \- + + + .. rubric:: Members + + .. py:attribute:: device_to_lowerer_map + + + + .. py:method:: get_lowerer(device) + :classmethod: + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_pass/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_pass/index.rst.txt new file mode 100644 index 0000000000..8c5a12b38c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_pass/index.rst.txt @@ -0,0 +1,109 @@ + + +:orphan: + +numba_dpex.core.parfors.parfor_pass +=================================== + +.. py:module:: numba_dpex.core.parfors.parfor_pass + +.. autoapi-nested-parse:: + + This module follows the logic of numba/parfors/parfor.py with changes required + to use it with dpnp instead of numpy. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ConvertDPNPPass ` + - Convert supported Dpnp functions, as well as arrayexpr nodes, to + * - :py:obj:`ParforPass ` + - Based on the NumpyParforPass. Lot's of code was copy-pasted, with minor + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_dpnp_ufunc_typ `\ (func) + - get type of the incoming function from builtin registry + * - :py:obj:`mk_alloc `\ (typingctx, typemap, calltypes, lhs, size_var, dtype, scope, loc, lhs_typ, \*\*kws) + - generate an array allocation with np.empty() and return list of nodes. + + + +Classes +------- + +.. py:class:: ConvertDPNPPass(pass_states) + + Bases: :py:obj:`numba.parfors.parfor.ConvertNumpyPass` + + Convert supported Dpnp functions, as well as arrayexpr nodes, to + parfor nodes. + + Based on the ConvertNumpyPass. Lot's of code was copy-pasted, with minor + changes due to lack of extensibility of the original package. + + + + +.. py:class:: ParforPass + + Bases: :py:obj:`numba.core.typed_passes.ParforPass` + + Based on the NumpyParforPass. Lot's of code was copy-pasted, with minor + changes due to lack of extensibility of the original package. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Convert data-parallel computations into Parfor nodes. + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Convert data-parallel computations into Parfor nodes. + + Exactly same as the original one, but with mock to _ParforPass. + + + + +Functions +--------- +.. py:function:: get_dpnp_ufunc_typ(func) + + get type of the incoming function from builtin registry + + +.. py:function:: mk_alloc(typingctx, typemap, calltypes, lhs, size_var, dtype, scope, loc, lhs_typ, **kws) + + generate an array allocation with np.empty() and return list of nodes. + size_var can be an int variable or tuple of int variables. + lhs_typ is the type of the array being allocated. + + Taken from numba, added kws argument to pass it to __allocate__ + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_sentinel_replace_pass/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_sentinel_replace_pass/index.rst.txt new file mode 100644 index 0000000000..0c2327341b --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/parfor_sentinel_replace_pass/index.rst.txt @@ -0,0 +1,105 @@ + + +:orphan: + +numba_dpex.core.parfors.parfor_sentinel_replace_pass +==================================================== + +.. py:module:: numba_dpex.core.parfors.parfor_sentinel_replace_pass + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ParforBodyArguments ` + - Arguments containing information to inject parfor code inside kernel. + * - :py:obj:`ParforSentinelReplacePass ` + - Base class for function passes + + + + +Classes +------- + +.. py:class:: ParforBodyArguments + + Bases: :py:obj:`NamedTuple` + + Arguments containing information to inject parfor code inside kernel. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`loop_body ` + - \- + * - :py:obj:`param_dict ` + - \- + * - :py:obj:`legal_loop_indices ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: loop_body + :type: any + + + + .. py:attribute:: param_dict + :type: any + + + + .. py:attribute:: legal_loop_indices + :type: any + + + + + +.. py:class:: ParforSentinelReplacePass + + Bases: :py:obj:`numba.core.compiler_machinery.FunctionPass` + + Base class for function passes + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Runs the pass itself. Must return True/False depending on whether + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Runs the pass itself. Must return True/False depending on whether + statement level modification took place. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_helper/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_helper/index.rst.txt new file mode 100644 index 0000000000..5a9ac18ac2 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_helper/index.rst.txt @@ -0,0 +1,67 @@ + + +:orphan: + +numba_dpex.core.parfors.reduction_helper +======================================== + +.. py:module:: numba_dpex.core.parfors.reduction_helper + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ReductionHelper ` + - The class to define and allocate reduction intermediate variables. + * - :py:obj:`ReductionKernelVariables ` + - The parfor body and the main function body share ir.Var nodes. + + + + +Classes +------- + +.. py:class:: ReductionHelper + + The class to define and allocate reduction intermediate variables. + + + + +.. py:class:: ReductionKernelVariables(lowerer, parfor_node, typemap, parfor_outputs, reductionHelperList) + + The parfor body and the main function body share ir.Var nodes. + We have to do some replacements of Var names in the parfor body + to make them legal parameter names. If we don't copy then the + Vars in the main function also would incorrectly change their name. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`copy_final_sum_to_host `\ (queue_ref) + - \- + + + .. rubric:: Members + + .. py:method:: copy_final_sum_to_host(queue_ref) + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_kernel_builder/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_kernel_builder/index.rst.txt new file mode 100644 index 0000000000..95313ab9a3 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/parfors/reduction_kernel_builder/index.rst.txt @@ -0,0 +1,43 @@ + + +:orphan: + +numba_dpex.core.parfors.reduction_kernel_builder +================================================ + +.. py:module:: numba_dpex.core.parfors.reduction_kernel_builder + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`create_reduction_main_kernel_for_parfor `\ (loop_ranges, parfor_node, typemap, reductionKernelVar, parfor_reddict) + - Creates a numba_dpex.kernel function for reduction main kernel. + * - :py:obj:`create_reduction_remainder_kernel_for_parfor `\ (parfor_node, typemap, reductionKernelVar, parfor_reddict, reductionHelperList) + - Creates a numba_dpex.kernel function for a reduction remainder kernel. + + + + +Functions +--------- +.. py:function:: create_reduction_main_kernel_for_parfor(loop_ranges, parfor_node, typemap, reductionKernelVar: numba_dpex.core.parfors.reduction_helper.ReductionKernelVariables, parfor_reddict=None) + + Creates a numba_dpex.kernel function for reduction main kernel. + + +.. py:function:: create_reduction_remainder_kernel_for_parfor(parfor_node, typemap, reductionKernelVar, parfor_reddict, reductionHelperList) + + Creates a numba_dpex.kernel function for a reduction remainder kernel. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/passes/dufunc_inliner/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/passes/dufunc_inliner/index.rst.txt new file mode 100644 index 0000000000..21c9c176e9 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/passes/dufunc_inliner/index.rst.txt @@ -0,0 +1,34 @@ + + +:orphan: + +numba_dpex.core.passes.dufunc_inliner +===================================== + +.. py:module:: numba_dpex.core.passes.dufunc_inliner + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dufunc_inliner `\ (func_ir, calltypes, typemap, typingctx, targetctx) + - \- + + + + +Functions +--------- +.. py:function:: dufunc_inliner(func_ir, calltypes, typemap, typingctx, targetctx) + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/passes/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/passes/index.rst.txt new file mode 100644 index 0000000000..607b6a8964 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/passes/index.rst.txt @@ -0,0 +1,120 @@ + +numba_dpex.core.passes +====================== + +.. py:module:: numba_dpex.core.passes + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ParforLegalizeCFDPass ` + - Base class for function passes + * - :py:obj:`DumpParforDiagnostics ` + - Base class for analysis passes (no modification made to state) + * - :py:obj:`NoPythonBackend ` + - Base class for function passes + + + + +Classes +------- + +.. py:class:: ParforLegalizeCFDPass + + Bases: :py:obj:`numba.core.compiler_machinery.FunctionPass` + + Base class for function passes + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Legalize CFD of parfor nodes. + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Legalize CFD of parfor nodes. + + + + +.. py:class:: DumpParforDiagnostics + + Bases: :py:obj:`numba.core.compiler_machinery.AnalysisPass` + + Base class for analysis passes (no modification made to state) + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Runs the pass itself. Must return True/False depending on whether + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Runs the pass itself. Must return True/False depending on whether + statement level modification took place. + + + + +.. py:class:: NoPythonBackend + + Bases: :py:obj:`numba.core.compiler_machinery.FunctionPass` + + Base class for function passes + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Back-end: Generate LLVM IR from Numba IR, compile to machine code + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Back-end: Generate LLVM IR from Numba IR, compile to machine code + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/passes/parfor_legalize_cfd_pass/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/passes/parfor_legalize_cfd_pass/index.rst.txt new file mode 100644 index 0000000000..980edd4864 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/passes/parfor_legalize_cfd_pass/index.rst.txt @@ -0,0 +1,124 @@ + + +:orphan: + +numba_dpex.core.passes.parfor_legalize_cfd_pass +=============================================== + +.. py:module:: numba_dpex.core.passes.parfor_legalize_cfd_pass + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`ParforLegalizeCFDPassImpl ` + - Legalizes the compute-follows-data based device attribute for parfor + * - :py:obj:`ParforLegalizeCFDPass ` + - Base class for function passes + + + + +Classes +------- + +.. py:class:: ParforLegalizeCFDPassImpl(state) + + Legalizes the compute-follows-data based device attribute for parfor + nodes. + + DpnpNdArray array-expressions populate the type of the left-hand-side (LHS) + of each expression as a default DpnpNdArray instance derived from the + __array_ufunc__ method of DpnpNdArray class. The pass fixes the LHS type by + properly applying compute follows data programming model. The pass first + checks if the right-hand-side (RHS) DpnpNdArray arguments are on the same + device, else raising a ExecutionQueueInferenceError. Once the RHS has + been validated, the LHS type is updated. + + The pass also updated the usm_type of the LHS based on a USM type + propagation rule: device > shared > host. Thus, if the usm_type attribute of + the RHS arrays are "device" and "shared" respectively, the LHS array's + usm_type attribute will be "device". + + Once the pass has identified a parfor with DpnpNdArrays and legalized it, + the "lowerer" attribute of the parfor is set to + ``numba_dpex.core.passes.parfor_lowering_pass._lower_parfor_as_kernel`` so + that the parfor node is lowered using Dpex's lowerer. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`inputUsmTypeStrToInt ` + - \- + * - :py:obj:`inputUsmTypeIntToStr ` + - \- + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run `\ () + - \- + + + .. rubric:: Members + + .. py:attribute:: inputUsmTypeStrToInt + + + + .. py:attribute:: inputUsmTypeIntToStr + + + + .. py:method:: run() + + + + +.. py:class:: ParforLegalizeCFDPass + + Bases: :py:obj:`numba.core.compiler_machinery.FunctionPass` + + Base class for function passes + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Legalize CFD of parfor nodes. + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Legalize CFD of parfor nodes. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/passes/passes/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/passes/passes/index.rst.txt new file mode 100644 index 0000000000..05596c89ae --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/passes/passes/index.rst.txt @@ -0,0 +1,135 @@ + + +:orphan: + +numba_dpex.core.passes.passes +============================= + +.. py:module:: numba_dpex.core.passes.passes + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`NoPythonBackend ` + - Base class for function passes + * - :py:obj:`DumpParforDiagnostics ` + - Base class for analysis passes (no modification made to state) + * - :py:obj:`QualNameDisambiguationLowering ` + - Qualified name disambiguation lowering pass + + + + +Classes +------- + +.. py:class:: NoPythonBackend + + Bases: :py:obj:`numba.core.compiler_machinery.FunctionPass` + + Base class for function passes + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Back-end: Generate LLVM IR from Numba IR, compile to machine code + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Back-end: Generate LLVM IR from Numba IR, compile to machine code + + + + +.. py:class:: DumpParforDiagnostics + + Bases: :py:obj:`numba.core.compiler_machinery.AnalysisPass` + + Base class for analysis passes (no modification made to state) + + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Runs the pass itself. Must return True/False depending on whether + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Runs the pass itself. Must return True/False depending on whether + statement level modification took place. + + + + +.. py:class:: QualNameDisambiguationLowering + + Bases: :py:obj:`numba.core.typed_passes.NativeLowering` + + Qualified name disambiguation lowering pass + + If there are multiple @func decorated functions exist inside + another @func decorated block, the numba compiler machinery + creates same qualified names for different compiled function. + Therefore, we utilize `unique_name` to resolve the ambiguity. + + :param NativeLowering: Superclass from which this + :type NativeLowering: CompilerPass + :param class has been inherited.: + + :returns: True if `run_pass()` of the superclass is successful. + :rtype: bool + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`run_pass `\ (state) + - Runs the pass itself. Must return True/False depending on whether + + + .. rubric:: Members + + .. py:method:: run_pass(state) + + Runs the pass itself. Must return True/False depending on whether + statement level modification took place. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/dpjit_compiler/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/dpjit_compiler/index.rst.txt new file mode 100644 index 0000000000..19406a6db3 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/dpjit_compiler/index.rst.txt @@ -0,0 +1,60 @@ + + +:orphan: + +numba_dpex.core.pipelines.dpjit_compiler +======================================== + +.. py:module:: numba_dpex.core.pipelines.dpjit_compiler + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpjitCompiler ` + - Dpex's compiler pipeline to offload parfor nodes into SYCL kernels. + + + + +Classes +------- + +.. py:class:: DpjitCompiler(typingctx, targetctx, library, args, return_type, flags, locals) + + Bases: :py:obj:`numba.core.compiler.CompilerBase` + + Dpex's compiler pipeline to offload parfor nodes into SYCL kernels. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`define_pipelines `\ () + - Child classes override this to customize the pipelines in use. + + + .. rubric:: Members + + .. py:method:: define_pipelines() + + Child classes override this to customize the pipelines in use. + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/index.rst.txt new file mode 100644 index 0000000000..cab60cc824 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.pipelines +========================= + +.. py:module:: numba_dpex.core.pipelines + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/kernel_compiler/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/kernel_compiler/index.rst.txt new file mode 100644 index 0000000000..92105589d5 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/pipelines/kernel_compiler/index.rst.txt @@ -0,0 +1,60 @@ + + +:orphan: + +numba_dpex.core.pipelines.kernel_compiler +========================================= + +.. py:module:: numba_dpex.core.pipelines.kernel_compiler + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`KernelCompiler ` + - Dpex's kernel compilation pipeline. + + + + +Classes +------- + +.. py:class:: KernelCompiler(typingctx, targetctx, library, args, return_type, flags, locals) + + Bases: :py:obj:`numba.core.compiler.CompilerBase` + + Dpex's kernel compilation pipeline. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`define_pipelines `\ () + - Child classes override this to customize the pipelines in use. + + + .. rubric:: Members + + .. py:method:: define_pipelines() + + Child classes override this to customize the pipelines in use. + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/runtime/context/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/runtime/context/index.rst.txt new file mode 100644 index 0000000000..5347954cbf --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/runtime/context/index.rst.txt @@ -0,0 +1,294 @@ + + +:orphan: + +numba_dpex.core.runtime.context +=============================== + +.. py:module:: numba_dpex.core.runtime.context + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpexRTContext ` + - An object providing access to DPEXRT API in the lowering pass. + + + + +Classes +------- + +.. py:class:: DpexRTContext(context) + + Bases: :py:obj:`object` + + An object providing access to DPEXRT API in the lowering pass. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`meminfo_alloc `\ (builder, size, usm_type, queue_ref) + - Wrapper to call :func:`~context.DpexRTContext.meminfo_alloc_unchecked` + * - :py:obj:`meminfo_fill `\ (builder, meminfo, itemsize, dest_is_float, value_is_float, value, queue_ref) + - Wrapper to call :func:`~context.DpexRTContext.meminfo_fill_unchecked` + * - :py:obj:`meminfo_alloc_unchecked `\ (builder, size, usm_type, queue_ref) + - Allocate a new MemInfo with a data payload of `size` bytes. + * - :py:obj:`meminfo_fill_unchecked `\ (builder, meminfo, itemsize, dest_is_float, value_is_float, value, queue_ref) + - Fills an allocated `MemInfo` with the value specified. + * - :py:obj:`arraystruct_from_python `\ (pyapi, obj, ptr) + - Generates a call to DPEXRT_sycl_usm_ndarray_from_python C function + * - :py:obj:`queuestruct_from_python `\ (pyapi, obj, ptr) + - Calls the c function DPEXRT_sycl_queue_from_python + * - :py:obj:`queuestruct_to_python `\ (pyapi, val) + - Calls the c function DPEXRT_sycl_queue_to_python + * - :py:obj:`eventstruct_from_python `\ (pyapi, obj, ptr) + - Calls the c function DPEXRT_sycl_event_from_python + * - :py:obj:`eventstruct_to_python `\ (pyapi, val) + - Calls the c function DPEXRT_sycl_event_to_python + * - :py:obj:`eventstruct_init `\ (pyapi, event, struct) + - Calls the c function DPEXRT_sycl_event_init + * - :py:obj:`usm_ndarray_to_python_acqref `\ (pyapi, aryty, ary, dtypeptr) + - Boxes a DpnpNdArray native object into a Python dpnp.ndarray. + * - :py:obj:`get_queue_from_filter_string `\ (builder, device) + - Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + * - :py:obj:`submit_range `\ (builder, kref, qref, args, argtys, nargs, range, nrange, depevents, ndepevents) + - Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + * - :py:obj:`submit_ndrange `\ (builder, kref, qref, args, argtys, nargs, grange, lrange, ndims, depevents, ndepevents) + - Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + * - :py:obj:`acquire_meminfo_and_schedule_release `\ (builder, args) + - Inserts LLVM IR to call nrt_acquire_meminfo_and_schedule_release. + * - :py:obj:`build_or_get_kernel `\ (builder, args) + - Inserts LLVM IR to call build_or_get_kernel. + * - :py:obj:`kernel_cache_size `\ (builder) + - Inserts LLVM IR to call kernel_cache_size. + + + .. rubric:: Members + + .. py:method:: meminfo_alloc(builder, size, usm_type, queue_ref) + + Wrapper to call :func:`~context.DpexRTContext.meminfo_alloc_unchecked` + with null checking of the returned value. + + + .. py:method:: meminfo_fill(builder, meminfo, itemsize, dest_is_float, value_is_float, value, queue_ref) + + Wrapper to call :func:`~context.DpexRTContext.meminfo_fill_unchecked` + with null checking of the returned value. + + + .. py:method:: meminfo_alloc_unchecked(builder, size, usm_type, queue_ref) + + Allocate a new MemInfo with a data payload of `size` bytes. + + The result of the call is checked and if it is NULL, i.e. allocation + failed, then a MemoryError is raised. If the allocation succeeded then + a pointer to the MemInfo is returned. + + :param builder: LLVM IR builder. + :type builder: `llvmlite.ir.builder.IRBuilder` + :param size: LLVM uint64 value specifying + the size in bytes for the data payload, i.e. i64 %"arg.allocsize" + :type size: `llvmlite.ir.values.Argument` + :param usm_type: An LLVM Argument object + specifying the type of the usm allocator. The constant value + should match the values in + ``dpctl's`` ``libsyclinterface::DPCTLSyclUSMType`` enum, + i.e. i64 %"arg.usm_type". + :type usm_type: `llvmlite.ir.values.Argument` + :param queue_ref: An LLVM argument value storing + the pointer to the address of the queue object, the object can be + `dpctl.SyclQueue()`, i.e. i8* %"arg.queue". + :type queue_ref: `llvmlite.ir.values.Argument` + + :returns: + + A pointer to the `MemInfo` + is returned from the `DPEXRT_MemInfo_alloc` C function call. + :rtype: ret (`llvmlite.ir.instructions.CallInstr`) + + + .. py:method:: meminfo_fill_unchecked(builder, meminfo, itemsize, dest_is_float, value_is_float, value, queue_ref) + + Fills an allocated `MemInfo` with the value specified. + + The result of the call is checked and if it is `NULL`, i.e. the fill + operation failed, then a `MemoryError` is raised. If the fill operation + is succeeded then a pointer to the `MemInfo` is returned. + + :param builder: LLVM IR builder. + :type builder: `llvmlite.ir.builder.IRBuilder` + :param meminfo: LLVM uint64 value + specifying the size in bytes for the data payload. + :type meminfo: `llvmlite.ir.instructions.LoadInstr` + :param itemsize: An LLVM Constant value + specifying the size of the each data item allocated by the + usm allocator. + :type itemsize: `llvmlite.ir.values.Constant` + :param dest_is_float: An LLVM Constant + value specifying if the destination array type is floating + point. + :type dest_is_float: `llvmlite.ir.values.Constant` + :param value_is_float: An LLVM Constant + value specifying if the input value is a floating point. + :type value_is_float: `llvmlite.ir.values.Constant` + :param value: An LLVM Constant value + specifying if the input value that will be used to fill + the array. + :type value: `llvmlite.ir.values.Constant` + :param queue_ref: An LLVM ExtractValue + instruction object to extract the pointer to the queue from the + DpctlSyclQueue type, i.e. %".74" = extractvalue {i8*, i8*} %".73", 1. + :type queue_ref: `llvmlite.ir.instructions.ExtractValue` + + :returns: + + A pointer to the `MemInfo` + is returned from the `DPEXRT_MemInfo_fill` C function call. + :rtype: ret (`llvmlite.ir.instructions.CallInstr`) + + + .. py:method:: arraystruct_from_python(pyapi, obj, ptr) + + Generates a call to DPEXRT_sycl_usm_ndarray_from_python C function + defined in the _DPREXRT_python Python extension. + + + + .. py:method:: queuestruct_from_python(pyapi, obj, ptr) + + Calls the c function DPEXRT_sycl_queue_from_python + + + .. py:method:: queuestruct_to_python(pyapi, val) + + Calls the c function DPEXRT_sycl_queue_to_python + + + .. py:method:: eventstruct_from_python(pyapi, obj, ptr) + + Calls the c function DPEXRT_sycl_event_from_python + + + .. py:method:: eventstruct_to_python(pyapi, val) + + Calls the c function DPEXRT_sycl_event_to_python + + + .. py:method:: eventstruct_init(pyapi, event, struct) + + Calls the c function DPEXRT_sycl_event_init + + + .. py:method:: usm_ndarray_to_python_acqref(pyapi, aryty, ary, dtypeptr) + + Boxes a DpnpNdArray native object into a Python dpnp.ndarray. + + :param pyapi: _description_ + :type pyapi: _type_ + :param aryty: _description_ + :type aryty: _type_ + :param ary: _description_ + :type ary: _type_ + :param dtypeptr: _description_ + :type dtypeptr: _type_ + + :returns: _description_ + :rtype: _type_ + + + .. py:method:: get_queue_from_filter_string(builder, device) + + Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + from a given filter string. + + :param device: An LLVM ArrayType + storing a const string for a DPC++ filter selector string. + :type device: llvmlite.ir.values.FormattedConstant + + Returns: A DPCTLSyclQueueRef pointer. + + + .. py:method:: submit_range(builder, kref, qref, args, argtys, nargs, range, nrange, depevents, ndepevents) + + Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + from a given filter string. + + Returns: A DPCTLSyclQueueRef pointer. + + + .. py:method:: submit_ndrange(builder, kref, qref, args, argtys, nargs, grange, lrange, ndims, depevents, ndepevents) + + Calls DPEXRTQueue_CreateFromFilterString to create a new sycl::queue + from a given filter string. + + Returns: A LLVM IR call inst. + + + .. py:method:: acquire_meminfo_and_schedule_release(builder: llvmlite.ir.IRBuilder, args) + + Inserts LLVM IR to call nrt_acquire_meminfo_and_schedule_release. + + .. code-block:: c + + DPCTLSyclEventRef + DPEXRT_nrt_acquire_meminfo_and_schedule_release( + NRT_api_functions *nrt, + DPCTLSyclQueueRef QRef, + NRT_MemInfo **meminfo_array, + size_t meminfo_array_size, + DPCTLSyclEventRef *depERefs, + size_t nDepERefs, + int *status, + ); + + + + .. py:method:: build_or_get_kernel(builder: llvmlite.ir.IRBuilder, args) + + Inserts LLVM IR to call build_or_get_kernel. + + .. code-block:: c + + DPCTLSyclKernelRef + DPEXRT_build_or_get_kernel( + const DPCTLSyclContextRef ctx, + const DPCTLSyclDeviceRef dev, + size_t il_hash, + const char *il, + size_t il_length, + const char *compile_opts, + const char *kernel_name, + ); + + + + .. py:method:: kernel_cache_size(builder: llvmlite.ir.IRBuilder) + + Inserts LLVM IR to call kernel_cache_size. + + .. code-block:: c + + size_t DPEXRT_kernel_cache_size(); + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/runtime/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/runtime/index.rst.txt new file mode 100644 index 0000000000..8c78c28b6b --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/runtime/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.runtime +======================= + +.. py:module:: numba_dpex.core.runtime + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/targets/dpjit_target/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/targets/dpjit_target/index.rst.txt new file mode 100644 index 0000000000..67953d4fb9 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/targets/dpjit_target/index.rst.txt @@ -0,0 +1,157 @@ + + +:orphan: + +numba_dpex.core.targets.dpjit_target +==================================== + +.. py:module:: numba_dpex.core.targets.dpjit_target + +.. autoapi-nested-parse:: + + Defines the target and typing contexts for numba_dpex's dpjit decorator. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`Dpex ` + - Mark the target as CPU. + * - :py:obj:`DpexTypingContext ` + - Custom typing context to support dpjit compilation. + * - :py:obj:`DpexTargetContext ` + - Changes BaseContext calling convention + + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DPEX_TARGET_NAME ` + - \- + * - :py:obj:`dpex_function_registry ` + - \- + + +Classes +------- + +.. py:class:: Dpex + + Bases: :py:obj:`numba.core.target_extension.CPU` + + Mark the target as CPU. + + + + + +.. py:class:: DpexTypingContext + + Bases: :py:obj:`numba.core.typing.Context` + + Custom typing context to support dpjit compilation. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`load_additional_registries `\ () + - Register dpjit specific functions like dpnp ufuncs. + + + .. rubric:: Members + + .. py:method:: load_additional_registries() + + Register dpjit specific functions like dpnp ufuncs. + + + + +.. py:class:: DpexTargetContext(typingctx, target=DPEX_TARGET_NAME) + + Bases: :py:obj:`numba.core.cpu.CPUContext` + + Changes BaseContext calling convention + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`init `\ () + - For subclasses to add initializer + * - :py:obj:`dpexrt `\ () + - \- + * - :py:obj:`load_additional_registries `\ () + - Load dpjit-specific registries. + * - :py:obj:`get_ufunc_info `\ (ufunc_key) + - Get the ufunc implementation for a given ufunc object. + + + .. rubric:: Members + + .. py:method:: init() + + For subclasses to add initializer + + + .. py:method:: dpexrt() + + + .. py:method:: load_additional_registries() + + Load dpjit-specific registries. + + + .. py:method:: get_ufunc_info(ufunc_key) + + Get the ufunc implementation for a given ufunc object. + + The default implementation in BaseContext always raises a + ``NotImplementedError`` exception. Subclasses may raise ``KeyError`` + to signal that the given ``ufunc_key`` is not available. + + :param ufunc_key: + :type ufunc_key: NumPy ufunc + + :returns: **res** -- A mapping of a NumPy ufunc type signature to a lower-level + implementation. + :rtype: dict[str, callable] + + + + + +Attributes +---------- +.. py:data:: DPEX_TARGET_NAME + :value: 'dpex' + + + +.. py:data:: dpex_function_registry + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/targets/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/targets/index.rst.txt new file mode 100644 index 0000000000..bef3acf755 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/targets/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.targets +======================= + +.. py:module:: numba_dpex.core.targets + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/dpctl_types/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/dpctl_types/index.rst.txt new file mode 100644 index 0000000000..1f3d716fbb --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/dpctl_types/index.rst.txt @@ -0,0 +1,126 @@ + + +:orphan: + +numba_dpex.core.types.dpctl_types +================================= + +.. py:module:: numba_dpex.core.types.dpctl_types + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpctlSyclQueue ` + - A Numba type to represent a dpctl.SyclQueue PyObject. + * - :py:obj:`DpctlSyclEvent ` + - A Numba type to represent a dpctl.SyclEvent PyObject. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`unbox_sycl_queue `\ (typ, obj, c) + - Convert a SyclQueue object to a native structure. + * - :py:obj:`box_sycl_queue `\ (typ, val, c) + - Boxes a NativeValue representation of DpctlSyclQueue type into a + * - :py:obj:`unbox_sycl_event `\ (typ, obj, c) + - Convert a SyclEvent object to a native structure. + * - :py:obj:`box_sycl_event `\ (typ, val, c) + - Boxes a NativeValue representation of DpctlSyclEvent type into a + + + +Classes +------- + +.. py:class:: DpctlSyclQueue(sycl_queue) + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclQueue PyObject. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`rand_digit_str `\ (n) + - \- + + + .. rubric:: Members + + .. py:method:: rand_digit_str(n) + + + + +.. py:class:: DpctlSyclEvent + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclEvent PyObject. + + + + +Functions +--------- +.. py:function:: unbox_sycl_queue(typ, obj, c) + + Convert a SyclQueue object to a native structure. + + +.. py:function:: box_sycl_queue(typ, val, c) + + Boxes a NativeValue representation of DpctlSyclQueue type into a + dpctl.SyclQueue PyObject + + At this point numba-dpex does not support creating a dpctl.SyclQueue inside + a dpjit decorated function. For this reason, boxing is only returns the + original parent object stored in DpctlSyclQueue's data model. + + :param typ: The representation of the DpnpNdArray type. + :param val: A native representation of a Numba DpnpNdArray type object. + :param c: The boxing context. + + Returns: A Pyobject for a dpnp.ndarray boxed from the Numba native value. + + +.. py:function:: unbox_sycl_event(typ, obj, c) + + Convert a SyclEvent object to a native structure. + + +.. py:function:: box_sycl_event(typ, val, c) + + Boxes a NativeValue representation of DpctlSyclEvent type into a + dpctl.SyclEvent PyObject + + At this point numba-dpex does not support creating a dpctl.SyclEvent inside + a dpjit decorated function. For this reason, boxing is only returns the + original parent object stored in DpctlSyclEvent's data model. + + :param typ: The representation of the dpctl.SyclEvent type. + :param val: A native representation of a Numba DpctlSyclEvent type object. + :param c: The boxing context. + + Returns: A Pyobject for a dpctl.SyclEvent boxed from the Numba native value. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/dpnp_ndarray_type/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/dpnp_ndarray_type/index.rst.txt new file mode 100644 index 0000000000..cf2dcffc6b --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/dpnp_ndarray_type/index.rst.txt @@ -0,0 +1,57 @@ + + +:orphan: + +numba_dpex.core.types.dpnp_ndarray_type +======================================= + +.. py:module:: numba_dpex.core.types.dpnp_ndarray_type + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpnpNdArray ` + - The Numba type to represent an dpnp.ndarray. The type has the same + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`partialclass `\ (cls, \*args, \*\*kwds) + - Creates fabric class of the original class with preset initialization + + + +Classes +------- + +.. py:class:: DpnpNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba_dpex.core.types.usm_ndarray_type.USMNdArray` + + The Numba type to represent an dpnp.ndarray. The type has the same + structure as USMNdArray used to represent dpctl.tensor.usm_ndarray. + + + + +Functions +--------- +.. py:function:: partialclass(cls, *args, **kwds) + + Creates fabric class of the original class with preset initialization + arguments. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/index.rst.txt new file mode 100644 index 0000000000..ca1bd69c9c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/index.rst.txt @@ -0,0 +1,330 @@ + +numba_dpex.core.types +===================== + +.. py:module:: numba_dpex.core.types + + +Subpackages +----------- +.. toctree:: + :titlesonly: + :maxdepth: 3 + + kernel_api/index.rst + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpctlSyclEvent ` + - A Numba type to represent a dpctl.SyclEvent PyObject. + * - :py:obj:`DpctlSyclQueue ` + - A Numba type to represent a dpctl.SyclQueue PyObject. + * - :py:obj:`DpnpNdArray ` + - The Numba type to represent an dpnp.ndarray. The type has the same + * - :py:obj:`IntEnumLiteral ` + - A Literal type for IntEnum objects. The type contains the original Python + * - :py:obj:`NdRangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`RangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`KernelDispatcherType ` + - The type of KernelDispatcher dispatchers + * - :py:obj:`USMNdArray ` + - A type class to represent dpctl.tensor.usm_ndarray. + + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`b1 ` + - \- + * - :py:obj:`double ` + - \- + * - :py:obj:`f4 ` + - \- + * - :py:obj:`f8 ` + - \- + * - :py:obj:`float32 ` + - \- + * - :py:obj:`float64 ` + - \- + * - :py:obj:`float_ ` + - \- + * - :py:obj:`i4 ` + - \- + * - :py:obj:`i8 ` + - \- + * - :py:obj:`int32 ` + - \- + * - :py:obj:`int64 ` + - \- + * - :py:obj:`none ` + - \- + * - :py:obj:`u4 ` + - \- + * - :py:obj:`u8 ` + - \- + * - :py:obj:`uint32 ` + - \- + * - :py:obj:`uint64 ` + - \- + * - :py:obj:`void ` + - \- + * - :py:obj:`usm_ndarray ` + - \- + + +Classes +------- + +.. py:class:: DpctlSyclEvent + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclEvent PyObject. + + + + +.. py:class:: DpctlSyclQueue(sycl_queue) + + Bases: :py:obj:`numba.types.Type` + + A Numba type to represent a dpctl.SyclQueue PyObject. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`rand_digit_str `\ (n) + - \- + + + .. rubric:: Members + + .. py:method:: rand_digit_str(n) + + + + +.. py:class:: DpnpNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba_dpex.core.types.usm_ndarray_type.USMNdArray` + + The Numba type to represent an dpnp.ndarray. The type has the same + structure as USMNdArray used to represent dpctl.tensor.usm_ndarray. + + + + +.. py:class:: IntEnumLiteral(value) + + Bases: :py:obj:`numba.core.types.Literal`, :py:obj:`numba.core.types.Integer` + + A Literal type for IntEnum objects. The type contains the original Python + value of the IntEnum class in it. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Check whether this type can be converted to the *other*. + + + .. rubric:: Members + + .. py:method:: can_convert_to(typingctx, other) -> bool + + Check whether this type can be converted to the *other*. + If successful, must return a string describing the conversion, e.g. + "exact", "promote", "unsafe", "safe"; otherwise None is returned. + + + + +.. py:class:: NdRangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.NdRange` + + + + +.. py:class:: RangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.Range` + + + + +.. py:class:: KernelDispatcherType(dispatcher) + + Bases: :py:obj:`numba.core.types.Dispatcher` + + The type of KernelDispatcher dispatchers + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + +.. py:class:: USMNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba.core.types.npytypes.Array` + + A type class to represent dpctl.tensor.usm_ndarray. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`copy `\ (dtype, ndim, layout, readonly, addrspace, device, usm_type) + - \- + * - :py:obj:`unify `\ (typingctx, other) + - Unify this with the *other* USMNdArray. + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Convert this USMNdArray to the *other*. + + + .. rubric:: Members + + .. py:method:: copy(dtype=None, ndim=None, layout=None, readonly=None, addrspace=None, device=None, usm_type=None) + + + .. py:method:: unify(typingctx, other) + + Unify this with the *other* USMNdArray. + + + .. py:method:: can_convert_to(typingctx, other) + + Convert this USMNdArray to the *other*. + + + + + +Attributes +---------- +.. py:data:: b1 + + + +.. py:data:: double + + + +.. py:data:: f4 + + + +.. py:data:: f8 + + + +.. py:data:: float32 + + + +.. py:data:: float64 + + + +.. py:data:: float_ + + + +.. py:data:: i4 + + + +.. py:data:: i8 + + + +.. py:data:: int32 + + + +.. py:data:: int64 + + + +.. py:data:: none + + + +.. py:data:: u4 + + + +.. py:data:: u8 + + + +.. py:data:: uint32 + + + +.. py:data:: uint64 + + + +.. py:data:: void + + + +.. py:data:: usm_ndarray + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/atomic_ref/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/atomic_ref/index.rst.txt new file mode 100644 index 0000000000..5c2f2ab16d --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/atomic_ref/index.rst.txt @@ -0,0 +1,67 @@ + + +:orphan: + +numba_dpex.core.types.kernel_api.atomic_ref +=========================================== + +.. py:module:: numba_dpex.core.types.kernel_api.atomic_ref + +.. autoapi-nested-parse:: + + Collection of numba-dpex typing classes for kernel_api Python classes. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`AtomicRefType ` + - numba-dpex internal type to represent a Python object of + + + + +Classes +------- + +.. py:class:: AtomicRefType(dtype: numba.core.types.Type, memory_order: int, memory_scope: int, address_space: int) + + Bases: :py:obj:`numba.core.types.Type` + + numba-dpex internal type to represent a Python object of + :class:`numba_dpex.kernel_api.AtomicRef`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` The helper function is not overloaded and using it on the + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + The helper function is not overloaded and using it on the + AtomicRefType throws a NotImplementedError. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index.rst.txt new file mode 100644 index 0000000000..a8e97da676 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.types.kernel_api +================================ + +.. py:module:: numba_dpex.core.types.kernel_api + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index_space_ids/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index_space_ids/index.rst.txt new file mode 100644 index 0000000000..004f07be3f --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/index_space_ids/index.rst.txt @@ -0,0 +1,121 @@ + + +:orphan: + +numba_dpex.core.types.kernel_api.index_space_ids +================================================ + +.. py:module:: numba_dpex.core.types.kernel_api.index_space_ids + +.. autoapi-nested-parse:: + + Defines numba types for Item and NdItem classes + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`GroupType ` + - Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.Group` + * - :py:obj:`ItemType ` + - Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.Item` + * - :py:obj:`NdItemType ` + - Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.NdItem` + + + + +Classes +------- + +.. py:class:: GroupType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.Group` + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + +.. py:class:: ItemType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.Item` + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + +.. py:class:: NdItemType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to :class:`numba_dpex.kernel_api.NdItem` + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/literal_intenum/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/literal_intenum/index.rst.txt new file mode 100644 index 0000000000..9353fa2240 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/literal_intenum/index.rst.txt @@ -0,0 +1,84 @@ + + +:orphan: + +numba_dpex.core.types.kernel_api.literal_intenum +================================================ + +.. py:module:: numba_dpex.core.types.kernel_api.literal_intenum + +.. autoapi-nested-parse:: + + Definition of a new Literal type in numba-dpex that allows treating IntEnum + members as integer literals inside a JIT compiled function. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`IntEnumLiteral ` + - A Literal type for IntEnum objects. The type contains the original Python + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`box_literal_integer `\ (typ, val, ctx) + - Defines how a Numba representation for an IntEnumLiteral object should + + + +Classes +------- + +.. py:class:: IntEnumLiteral(value) + + Bases: :py:obj:`numba.core.types.Literal`, :py:obj:`numba.core.types.Integer` + + A Literal type for IntEnum objects. The type contains the original Python + value of the IntEnum class in it. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Check whether this type can be converted to the *other*. + + + .. rubric:: Members + + .. py:method:: can_convert_to(typingctx, other) -> bool + + Check whether this type can be converted to the *other*. + If successful, must return a string describing the conversion, e.g. + "exact", "promote", "unsafe", "safe"; otherwise None is returned. + + + + +Functions +--------- +.. py:function:: box_literal_integer(typ, val, ctx) + + Defines how a Numba representation for an IntEnumLiteral object should + be converted to a PyObject* object and returned back to Python. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/local_accessor/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/local_accessor/index.rst.txt new file mode 100644 index 0000000000..2f4ad9e44e --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/local_accessor/index.rst.txt @@ -0,0 +1,101 @@ + + +:orphan: + +numba_dpex.core.types.kernel_api.local_accessor +=============================================== + +.. py:module:: numba_dpex.core.types.kernel_api.local_accessor + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpctlMDLocalAccessorType ` + - numba-dpex internal type to represent a dpctl SyclInterface type + * - :py:obj:`LocalAccessorType ` + - numba-dpex internal type to represent a Python object of + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`unbox_local_accessor `\ (typ, obj, c) + - Unboxes a Python LocalAccessor PyObject* into a numba-dpex internal + + + +Classes +------- + +.. py:class:: DpctlMDLocalAccessorType + + Bases: :py:obj:`numba.core.types.Type` + + numba-dpex internal type to represent a dpctl SyclInterface type + `MDLocalAccessorTy`. + + + + +.. py:class:: LocalAccessorType(ndim, dtype) + + Bases: :py:obj:`numba_dpex.core.types.USMNdArray` + + numba-dpex internal type to represent a Python object of + :class:`numba_dpex.experimental.kernel_iface.LocalAccessor`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` The helper function is not overloaded and using it on the + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + The helper function is not overloaded and using it on the + LocalAccessorType throws a NotImplementedError. + + + + +Functions +--------- +.. py:function:: unbox_local_accessor(typ, obj, c) + + Unboxes a Python LocalAccessor PyObject* into a numba-dpex internal + representation. + + A LocalAccessor object is represented internally in numba-dpex with the + same data model as a numpy.ndarray. It is done as a LocalAccessor object + serves only as a placeholder type when passed to ``call_kernel`` and the + data buffer should never be accessed inside a host-side compiled function + such as ``call_kernel``. + + When a LocalAccessor object is passed as an argument to a kernel function + it uses the USMArrayDeviceModel. Doing so allows numba-dpex to correctly + generate the kernel signature passing in a pointer in the local address + space. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/ranges/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/ranges/index.rst.txt new file mode 100644 index 0000000000..988c5f38f9 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_api/ranges/index.rst.txt @@ -0,0 +1,53 @@ + + +:orphan: + +numba_dpex.core.types.kernel_api.ranges +======================================= + +.. py:module:: numba_dpex.core.types.kernel_api.ranges + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`RangeType ` + - Numba-dpex type corresponding to + * - :py:obj:`NdRangeType ` + - Numba-dpex type corresponding to + + + + +Classes +------- + +.. py:class:: RangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.Range` + + + + +.. py:class:: NdRangeType(ndim: int) + + Bases: :py:obj:`numba.core.types.Type` + + Numba-dpex type corresponding to + :class:`numba_dpex.kernel_api.ranges.NdRange` + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_dispatcher_type/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_dispatcher_type/index.rst.txt new file mode 100644 index 0000000000..361477174a --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/kernel_dispatcher_type/index.rst.txt @@ -0,0 +1,63 @@ + + +:orphan: + +numba_dpex.core.types.kernel_dispatcher_type +============================================ + +.. py:module:: numba_dpex.core.types.kernel_dispatcher_type + +.. autoapi-nested-parse:: + + Experimental types that will eventually move to numba_dpex.core.types + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`KernelDispatcherType ` + - The type of KernelDispatcher dispatchers + + + + +Classes +------- + +.. py:class:: KernelDispatcherType(dispatcher) + + Bases: :py:obj:`numba.core.types.Dispatcher` + + The type of KernelDispatcher dispatchers + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`cast_python_value `\ (args) + - :summarylabel:`abc` \- + + + .. rubric:: Members + + .. py:method:: cast_python_value(args) + :abstractmethod: + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/numba_types_short_names/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/numba_types_short_names/index.rst.txt new file mode 100644 index 0000000000..562709a3da --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/numba_types_short_names/index.rst.txt @@ -0,0 +1,87 @@ + + +:orphan: + +numba_dpex.core.types.numba_types_short_names +============================================= + +.. py:module:: numba_dpex.core.types.numba_types_short_names + + + + + + + +Attributes +---------- +.. py:data:: none + + + +.. py:data:: uint32 + + + +.. py:data:: uint64 + + + +.. py:data:: int32 + + + +.. py:data:: int64 + + + +.. py:data:: float32 + + + +.. py:data:: float64 + + + +.. py:data:: b1 + + + +.. py:data:: i4 + + + +.. py:data:: i8 + + + +.. py:data:: u4 + + + +.. py:data:: u8 + + + +.. py:data:: f4 + + + +.. py:data:: f8 + + + +.. py:data:: float_ + + + +.. py:data:: double + + + +.. py:data:: void + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/types/usm_ndarray_type/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/types/usm_ndarray_type/index.rst.txt new file mode 100644 index 0000000000..41c8d5ea3f --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/types/usm_ndarray_type/index.rst.txt @@ -0,0 +1,76 @@ + + +:orphan: + +numba_dpex.core.types.usm_ndarray_type +====================================== + +.. py:module:: numba_dpex.core.types.usm_ndarray_type + +.. autoapi-nested-parse:: + + A type class to represent dpctl.tensor.usm_ndarray type in Numba + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`USMNdArray ` + - A type class to represent dpctl.tensor.usm_ndarray. + + + + +Classes +------- + +.. py:class:: USMNdArray(ndim, layout='C', dtype=None, usm_type='device', device=None, queue=None, readonly=False, name=None, aligned=True, addrspace=address_space.GLOBAL.value) + + Bases: :py:obj:`numba.core.types.npytypes.Array` + + A type class to represent dpctl.tensor.usm_ndarray. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`copy `\ (dtype, ndim, layout, readonly, addrspace, device, usm_type) + - \- + * - :py:obj:`unify `\ (typingctx, other) + - Unify this with the *other* USMNdArray. + * - :py:obj:`can_convert_to `\ (typingctx, other) + - Convert this USMNdArray to the *other*. + + + .. rubric:: Members + + .. py:method:: copy(dtype=None, ndim=None, layout=None, readonly=None, addrspace=None, device=None, usm_type=None) + + + .. py:method:: unify(typingctx, other) + + Unify this with the *other* USMNdArray. + + + .. py:method:: can_convert_to(typingctx, other) + + Convert this USMNdArray to the *other*. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/typing/dpnpdecl/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/typing/dpnpdecl/index.rst.txt new file mode 100644 index 0000000000..76a961aeb5 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/typing/dpnpdecl/index.rst.txt @@ -0,0 +1,166 @@ + + +:orphan: + +numba_dpex.core.typing.dpnpdecl +=============================== + +.. py:module:: numba_dpex.core.typing.dpnpdecl + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`DpnpRulesArrayOperator ` + - Defines method ``generic(self, args, kws)`` which compute a possible + * - :py:obj:`DpnpRulesInplaceArrayOperator ` + - Defines method ``generic(self, args, kws)`` which compute a possible + * - :py:obj:`DpnpRulesUnaryArrayOperator ` + - Defines method ``generic(self, args, kws)`` which compute a possible + + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`registry ` + - \- + * - :py:obj:`infer ` + - \- + * - :py:obj:`infer_global ` + - \- + * - :py:obj:`infer_getattr ` + - \- + * - :py:obj:`all_ufuncs ` + - \- + * - :py:obj:`supported_ufuncs ` + - \- + + +Classes +------- + +.. py:class:: DpnpRulesArrayOperator(context) + + Bases: :py:obj:`numba.core.typing.npydecl.NumpyRulesArrayOperator` + + Defines method ``generic(self, args, kws)`` which compute a possible + signature base on input types. The signature does not have to match the + input types. It is compared against the input types afterwards. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`install_operations `\ () + - :summarylabel:`class` \- + + + .. rubric:: Members + + .. py:method:: install_operations() + :classmethod: + + + + +.. py:class:: DpnpRulesInplaceArrayOperator(context) + + Bases: :py:obj:`numba.core.typing.npydecl.NumpyRulesInplaceArrayOperator` + + Defines method ``generic(self, args, kws)`` which compute a possible + signature base on input types. The signature does not have to match the + input types. It is compared against the input types afterwards. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`install_operations `\ () + - :summarylabel:`class` \- + + + .. rubric:: Members + + .. py:method:: install_operations() + :classmethod: + + + + +.. py:class:: DpnpRulesUnaryArrayOperator(context) + + Bases: :py:obj:`numba.core.typing.npydecl.NumpyRulesUnaryArrayOperator` + + Defines method ``generic(self, args, kws)`` which compute a possible + signature base on input types. The signature does not have to match the + input types. It is compared against the input types afterwards. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`install_operations `\ () + - :summarylabel:`class` \- + + + .. rubric:: Members + + .. py:method:: install_operations() + :classmethod: + + + + + +Attributes +---------- +.. py:data:: registry + + + +.. py:data:: infer + + + +.. py:data:: infer_global + + + +.. py:data:: infer_getattr + + + +.. py:data:: all_ufuncs + + + +.. py:data:: supported_ufuncs + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/typing/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/typing/index.rst.txt new file mode 100644 index 0000000000..f312ed4f1d --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/typing/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.typing +====================== + +.. py:module:: numba_dpex.core.typing + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/typing/typeof/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/typing/typeof/index.rst.txt new file mode 100644 index 0000000000..04044e032a --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/typing/typeof/index.rst.txt @@ -0,0 +1,184 @@ + + +:orphan: + +numba_dpex.core.typing.typeof +============================= + +.. py:module:: numba_dpex.core.typing.typeof + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`typeof_usm_ndarray `\ (val, c) + - Registers the type inference implementation function for + * - :py:obj:`typeof_dpnp_ndarray `\ (val, c) + - Registers the type inference implementation function for dpnp.ndarray. + * - :py:obj:`typeof_dpctl_sycl_queue `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_dpctl_sycl_event `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_range `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_ndrange `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_atomic_ref `\ (val, ctx) + - Returns a ``numba_dpex.experimental.dpctpp_types.AtomicRefType`` + * - :py:obj:`typeof_group `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_item `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_nditem `\ (val, c) + - Registers the type inference implementation function for a + * - :py:obj:`typeof_local_accessor `\ (val, c) + - Returns a ``numba_dpex.experimental.dpctpp_types.LocalAccessorType`` + + + + +Functions +--------- +.. py:function:: typeof_usm_ndarray(val, c) + + Registers the type inference implementation function for + dpctl.tensor.usm_ndarray + + :param val: A Python object that should be an instance of a + :param dpctl.tensor.usm_ndarray: + :param c: Unused argument used to be consistent with Numba API. + + :raises ValueError: If an unsupported dtype encountered or val has + :raises no ``usm_type`` or sycl_device attribute.: + + Returns: The Numba type corresponding to dpctl.tensor.usm_ndarray + + +.. py:function:: typeof_dpnp_ndarray(val, c) + + Registers the type inference implementation function for dpnp.ndarray. + + :param val: A Python object that should be an instance of a + :param dpnp.ndarray: + :param c: Unused argument used to be consistent with Numba API. + + :raises ValueError: If an unsupported dtype encountered or val has + :raises no ``usm_type`` or sycl_device attribute.: + + Returns: The Numba type corresponding to dpnp.ndarray + + +.. py:function:: typeof_dpctl_sycl_queue(val, c) + + Registers the type inference implementation function for a + dpctl.SyclQueue PyObject. + + :param val: An instance of dpctl.SyclQueue. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.core.types.dpctl_types.DpctlSyclQueue instance. + + +.. py:function:: typeof_dpctl_sycl_event(val, c) + + Registers the type inference implementation function for a + dpctl.SyclEvent PyObject. + + :param val: An instance of dpctl.SyclEvent. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.core.types.dpctl_types.DpctlSyclEvent instance. + + +.. py:function:: typeof_range(val, c) + + Registers the type inference implementation function for a + numba_dpex.Range PyObject. + + :param val: An instance of numba_dpex.Range. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.core.types.range_types.RangeType instance. + + +.. py:function:: typeof_ndrange(val, c) + + Registers the type inference implementation function for a + numba_dpex.NdRange PyObject. + + :param val: An instance of numba_dpex.Range. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.core.types.range_types.RangeType instance. + + +.. py:function:: typeof_atomic_ref(val: numba_dpex.kernel_api.AtomicRef, ctx) -> numba_dpex.core.types.kernel_api.atomic_ref.AtomicRefType + + Returns a ``numba_dpex.experimental.dpctpp_types.AtomicRefType`` + instance for a Python AtomicRef object. + + :param val: Instance of the AtomicRef type. + :type val: AtomicRef + :param ctx: Numba typing context used for type inference. + + Returns: AtomicRefType object corresponding to the AtomicRef object. + + + +.. py:function:: typeof_group(val: numba_dpex.kernel_api.Group, c) + + Registers the type inference implementation function for a + numba_dpex.kernel_api.Group PyObject. + + :param val: An instance of numba_dpex.kernel_api.Group. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.experimental.core.types.kernel_api.items.GroupType + instance. + + +.. py:function:: typeof_item(val: numba_dpex.kernel_api.Item, c) + + Registers the type inference implementation function for a + numba_dpex.kernel_api.Item PyObject. + + :param val: An instance of numba_dpex.kernel_api.Item. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.experimental.core.types.kernel_api.items.ItemType + instance. + + +.. py:function:: typeof_nditem(val: numba_dpex.kernel_api.NdItem, c) + + Registers the type inference implementation function for a + numba_dpex.kernel_api.NdItem PyObject. + + :param val: An instance of numba_dpex.kernel_api.NdItem. + :param c: Unused argument used to be consistent with Numba API. + + Returns: A numba_dpex.experimental.core.types.kernel_api.items.NdItemType + instance. + + +.. py:function:: typeof_local_accessor(val: numba_dpex.kernel_api.LocalAccessor, c) -> numba_dpex.core.types.kernel_api.local_accessor.LocalAccessorType + + Returns a ``numba_dpex.experimental.dpctpp_types.LocalAccessorType`` + instance for a Python LocalAccessor object. + :param val: Instance of the LocalAccessor type. + :type val: LocalAccessor + :param c: Numba typing context used for type inference. + + Returns: LocalAccessorType object corresponding to the LocalAccessor object. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/utils/call_kernel_builder/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/utils/call_kernel_builder/index.rst.txt new file mode 100644 index 0000000000..f5bd35b75c --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/utils/call_kernel_builder/index.rst.txt @@ -0,0 +1,256 @@ + + +:orphan: + +numba_dpex.core.utils.call_kernel_builder +========================================= + +.. py:module:: numba_dpex.core.utils.call_kernel_builder + +.. autoapi-nested-parse:: + + Module that contains numba style wrapper around sycl kernel submit. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`SPIRVKernelModule ` + - Represents SPIRV binary code and function name in this binary + * - :py:obj:`KernelLaunchIRBuilder ` + - Helper class to build the LLVM IR for the submission of a kernel. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_queue_from_llvm_values `\ (ctx, builder, ty_kernel_args, ll_kernel_args) + - Get the sycl queue from the first USMNdArray argument. Prior passes + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`MAX_SIZE_OF_SYCL_RANGE ` + - \- + * - :py:obj:`OPEN_CL_OPT_DISABLE_FLAG ` + - \- + * - :py:obj:`L0_OPT_DISABLE_FLAG ` + - \- + + +Classes +------- + +.. py:class:: SPIRVKernelModule + + Bases: :py:obj:`NamedTuple` + + Represents SPIRV binary code and function name in this binary + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`kernel_name ` + - \- + * - :py:obj:`kernel_bitcode ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: kernel_name + :type: str + + + + .. py:attribute:: kernel_bitcode + :type: bytes + + + + + +.. py:class:: KernelLaunchIRBuilder(context: numba.core.cpu.CPUContext, builder: llvmlite.ir.builder.IRBuilder, kernel_dmm: numba.core.datamodel.DataModelManager) + + Helper class to build the LLVM IR for the submission of a kernel. + + The class generates LLVM IR inside the current LLVM module that is needed + for submitting kernels. The LLVM Values that + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`dpexrt `\ () + - Dpex runtime context. + * - :py:obj:`get_queue `\ (exec_queue) + - Allocates memory on the stack to store a DPCTLSyclQueueRef. + * - :py:obj:`set_kernel `\ (sycl_kernel_ref) + - Sets kernel to the argument list. + * - :py:obj:`set_kernel_from_spirv `\ (kernel_module, debug) + - Sets kernel to the argument list from the SPIRV bytecode. + * - :py:obj:`set_queue `\ (sycl_queue_ref) + - Sets queue to the argument list. + * - :py:obj:`set_queue_from_arguments `\ () + - Sets the sycl queue from the first USMNdArray argument provided + * - :py:obj:`set_range `\ (global_range, local_range) + - Sets global and local range if provided to the argument list. + * - :py:obj:`set_range_from_indexer `\ (ty_indexer_arg, ll_index_arg) + - Returns two lists of LLVM IR Values that hold the unboxed extents of + * - :py:obj:`set_arguments `\ (ty_kernel_args, kernel_args) + - Sets flattened kernel args, kernel arg types and number of those + * - :py:obj:`set_arguments_form_tuple `\ (ty_kernel_args_tuple, ll_kernel_args_tuple) + - Sets flattened kernel args, kernel arg types and number of those + * - :py:obj:`set_dependent_events `\ (dep_events) + - Sets dependent events to the argument list. + * - :py:obj:`set_dependent_events_from_tuple `\ (ty_dependent_events, ll_dependent_events) + - Set's dependent events from tuple represented by LLVM IR. + * - :py:obj:`submit `\ () + - Submits kernel by calling sycl.dpctl_queue_submit_range or + * - :py:obj:`acquire_meminfo_and_submit_release `\ () + - Schedule sycl host task to release nrt meminfo of the arguments used + + + .. rubric:: Members + + .. py:method:: dpexrt() + + Dpex runtime context. + + + .. py:method:: get_queue(exec_queue: dpctl.SyclQueue) -> llvmlite.ir.Instruction + + Allocates memory on the stack to store a DPCTLSyclQueueRef. + + Returns: A LLVM Value storing the pointer to the SYCL queue created + using the filter string for the Python exec_queue (dpctl.SyclQueue). + + + .. py:method:: set_kernel(sycl_kernel_ref: llvmlite.ir.Instruction) + + Sets kernel to the argument list. + + + .. py:method:: set_kernel_from_spirv(kernel_module: SPIRVKernelModule, debug=False) + + Sets kernel to the argument list from the SPIRV bytecode. + + It pastes bytecode as a constant string and create kernel bundle from it + using SYCL API. It caches kernel, so it won't be sent to device second + time. + + + .. py:method:: set_queue(sycl_queue_ref: llvmlite.ir.Instruction) + + Sets queue to the argument list. + + + .. py:method:: set_queue_from_arguments() + + Sets the sycl queue from the first USMNdArray argument provided + earlier. + + + .. py:method:: set_range(global_range: list, local_range: list = None) + + Sets global and local range if provided to the argument list. + + + .. py:method:: set_range_from_indexer(ty_indexer_arg: Union[numba_dpex.core.types.kernel_api.ranges.RangeType, numba_dpex.core.types.kernel_api.ranges.NdRangeType], ll_index_arg: llvmlite.ir.BaseStructType) + + Returns two lists of LLVM IR Values that hold the unboxed extents of + a Python Range or NdRange object. + + + .. py:method:: set_arguments(ty_kernel_args: list[numba.core.types.Type], kernel_args: list[llvmlite.ir.Instruction]) + + Sets flattened kernel args, kernel arg types and number of those + arguments to the argument list. + + + .. py:method:: set_arguments_form_tuple(ty_kernel_args_tuple: numba.core.types.containers.UniTuple, ll_kernel_args_tuple: llvmlite.ir.Instruction) + + Sets flattened kernel args, kernel arg types and number of those + arguments to the argument list based on the arguments stored in tuple. + + + .. py:method:: set_dependent_events(dep_events: list[llvmlite.ir.Instruction]) + + Sets dependent events to the argument list. + + + .. py:method:: set_dependent_events_from_tuple(ty_dependent_events: numba.core.types.containers.UniTuple, ll_dependent_events: llvmlite.ir.Instruction) + + Set's dependent events from tuple represented by LLVM IR. + + :param ll_dependent_events: tuple of numba's data models. + + + .. py:method:: submit() -> llvmlite.ir.Instruction + + Submits kernel by calling sycl.dpctl_queue_submit_range or + sycl.dpctl_queue_submit_ndrange. Must be called after all arguments + set. + + + .. py:method:: acquire_meminfo_and_submit_release() -> llvmlite.ir.Instruction + + Schedule sycl host task to release nrt meminfo of the arguments used + to run job. Use it to keep arguments alive during kernel execution. + + + + +Functions +--------- +.. py:function:: get_queue_from_llvm_values(ctx: numba.core.cpu.CPUContext, builder: llvmlite.ir.builder.IRBuilder, ty_kernel_args: list[numba.core.types.Type], ll_kernel_args: list[llvmlite.ir.Instruction]) + + Get the sycl queue from the first USMNdArray argument. Prior passes + before lowering make sure that compute-follows-data is enforceable + for a specific call to a kernel. As such, at the stage of lowering + the queue from the first USMNdArray argument can be extracted. + + + +Attributes +---------- +.. py:data:: MAX_SIZE_OF_SYCL_RANGE + :value: 3 + + + +.. py:data:: OPEN_CL_OPT_DISABLE_FLAG + :value: '-cl-opt-disable' + + + +.. py:data:: L0_OPT_DISABLE_FLAG + :value: '-g' + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/utils/cgutils_extra/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/utils/cgutils_extra/index.rst.txt new file mode 100644 index 0000000000..1cafc8baff --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/utils/cgutils_extra/index.rst.txt @@ -0,0 +1,192 @@ + + +:orphan: + +numba_dpex.core.utils.cgutils_extra +=================================== + +.. py:module:: numba_dpex.core.utils.cgutils_extra + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`LLVMTypes ` + - A helper class to get LLVM Values for integer C types. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`declare_function `\ (context, builder, name, sig, cargs, mangler) + - Insert declaration for a opencl builtin function. + * - :py:obj:`get_llvm_type `\ (context, type) + - Returns the LLVM Value corresponding to a Numba type. + * - :py:obj:`get_llvm_ptr_type `\ (type) + - Returns an LLVM pointer type for a give LLVM type object. + * - :py:obj:`create_null_ptr `\ (builder, context) + - Allocates a new LLVM Value storing a ``void*`` and returns the Value to + * - :py:obj:`get_zero `\ (context) + - Returns an LLVM Constant storing a 64 bit representation for zero. + * - :py:obj:`get_one `\ (context) + - Returns an LLVM Constant storing a 64 bit representation for one. + + + +Classes +------- + +.. py:class:: LLVMTypes + + A helper class to get LLVM Values for integer C types. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`byte_t ` + - \- + * - :py:obj:`byte_ptr_t ` + - \- + * - :py:obj:`byte_ptr_ptr_t ` + - \- + * - :py:obj:`int32_t ` + - \- + * - :py:obj:`int32_ptr_t ` + - \- + * - :py:obj:`int64_t ` + - \- + * - :py:obj:`int64_ptr_t ` + - \- + * - :py:obj:`void_t ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: byte_t + + + + .. py:attribute:: byte_ptr_t + + + + .. py:attribute:: byte_ptr_ptr_t + + + + .. py:attribute:: int32_t + + + + .. py:attribute:: int32_ptr_t + + + + .. py:attribute:: int64_t + + + + .. py:attribute:: int64_ptr_t + + + + .. py:attribute:: void_t + + + + + +Functions +--------- +.. py:function:: declare_function(context, builder, name, sig, cargs, mangler=mangle_c) + + Insert declaration for a opencl builtin function. + Uses the Itanium mangler. + + :param context: + :type context: target context + :param builder: + :type builder: llvm builder + :param name: symbol name + :type name: str + :param sig: function signature of the symbol being declared + :type sig: signature + :param cargs: C type names for the arguments + :type cargs: sequence of str + :param mangler: function to use to mangle the symbol + :type mangler: a mangler function + + +.. py:function:: get_llvm_type(context, type) + + Returns the LLVM Value corresponding to a Numba type. + + :param context: The LLVM context or the execution state of the current IR + :param generator.: + :param type: A Numba type object. + + Returns: An Python object wrapping an LLVM Value corresponding to the + specified Numba type. + + + +.. py:function:: get_llvm_ptr_type(type) + + Returns an LLVM pointer type for a give LLVM type object. + + :param type: An LLVM type for which we need the corresponding pointer type. + + Returns: An LLVM pointer type object corresponding to the input LLVM type. + + + +.. py:function:: create_null_ptr(builder, context) + + Allocates a new LLVM Value storing a ``void*`` and returns the Value to + caller. + + :param builder: The LLVM IR builder to be used for code generation. + :param context: The LLVM IR builder context. + + Returns: An LLVM value storing a null pointer + + + +.. py:function:: get_zero(context) + + Returns an LLVM Constant storing a 64 bit representation for zero. + + :param context: The LLVM IR builder context. + + Returns: An LLVM Constant Value storing zero. + + + +.. py:function:: get_one(context) + + Returns an LLVM Constant storing a 64 bit representation for one. + + :param context: The LLVM IR builder context. + + Returns: An LLVM Constant Value storing one. + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/utils/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/utils/index.rst.txt new file mode 100644 index 0000000000..372dd6e0b1 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/utils/index.rst.txt @@ -0,0 +1,7 @@ + +numba_dpex.core.utils +===================== + +.. py:module:: numba_dpex.core.utils + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/utils/itanium_mangler/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/utils/itanium_mangler/index.rst.txt new file mode 100644 index 0000000000..4f9ab91992 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/utils/itanium_mangler/index.rst.txt @@ -0,0 +1,203 @@ + + +:orphan: + +numba_dpex.core.utils.itanium_mangler +===================================== + +.. py:module:: numba_dpex.core.utils.itanium_mangler + +.. autoapi-nested-parse:: + + Itanium CXX ABI Mangler + + Reference: https://itanium-cxx-abi.github.io/cxx-abi/abi.html + + The basics of the mangling scheme. + + We are hijacking the CXX mangling scheme for our use. We map Python modules + into CXX namespace. A `module1.submodule2.foo` is mapped to + `module1::submodule2::foo`. For parameterized numba types, we treat them as + templated types; for example, `array(int64, 1d, C)` becomes an + `array`. + + All mangled names are prefixed with "_Z". It is followed by the name of the + entity. A name contains one or more identifiers. Each identifier is encoded + as "". If the name is namespaced and, therefore, + has multiple identifiers, the entire name is encoded as "NE". + + For functions, arguments types follow. There are condensed encodings for basic + built-in types; e.g. "i" for int, "f" for float. For other types, the + previously mentioned name encoding should be used. + + For templated types, the template parameters are encoded immediately after the + name. If it is namespaced, it should be within the 'N' 'E' marker. Template + parameters are encoded in "IE", where each parameter is encoded using + the mentioned name encoding scheme. Template parameters can contain literal + values like the '1' in the array type shown earlier. There is special encoding + scheme for them to avoid leading digits. + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`mangle_type_or_value `\ (typ) + - Mangle type parameter and arbitrary value. + * - :py:obj:`mangle_ext `\ (ident, argtys, \*None, abi_tags) + - Mangle identifier with Numba type objects and abi-tags. + * - :py:obj:`mangle_abi_tag `\ (abi_tag) + - \- + * - :py:obj:`mangle_identifier `\ (ident, template_params, \*None, abi_tags, uid) + - Mangle the identifier with optional template parameters and abi_tags. + * - :py:obj:`mangle_type_c `\ (typ) + - Mangle C type name + * - :py:obj:`mangle_type_or_value_numba `\ (typ) + - Mangle type parameter and arbitrary value. + * - :py:obj:`mangle_templated_ident `\ (identifier, parameters) + - Mangle templated identifier. + * - :py:obj:`mangle_args_c `\ (argtys) + - Mangle sequence of C type names + * - :py:obj:`mangle_args `\ (argtys) + - Mangle sequence of Numba type objects and arbitrary values. + * - :py:obj:`mangle_c `\ (ident, argtys) + - Mangle identifier with C type names + * - :py:obj:`mangle `\ (ident, argtys, \*None, abi_tags, uid) + - Mangle identifier with Numba type objects and abi-tags. + * - :py:obj:`prepend_namespace `\ (mangled, ns) + - Prepend namespace to mangled name. + + +.. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`PREFIX ` + - \- + * - :py:obj:`C2CODE ` + - \- + * - :py:obj:`N2C ` + - \- + * - :py:obj:`mangle_type ` + - \- + * - :py:obj:`mangle_value ` + - \- + + + +Functions +--------- +.. py:function:: mangle_type_or_value(typ) + + Mangle type parameter and arbitrary value. + + This function extends Numba's `magle_type_or_value()` to + support numba.types.CPointer type, e.g. an ``int *`` argument will be + mangled to "Pi". + Mangling of extended qualifiers is supported only + for address space qualifiers. In which case, the mangling + follows the rule defined in Section 5.1.5.1 of the ``Itanium ABI + ``_. + For example, an ``int global *`` argument will be mangeled to "PU3AS1i". + + :param typ: Type to mangle + :type typ: numba.types, int, str + + :returns: The mangled name of the type + :rtype: str + + +.. py:function:: mangle_ext(ident, argtys, *, abi_tags=()) + + Mangle identifier with Numba type objects and abi-tags. + + +.. py:function:: mangle_abi_tag(abi_tag: str) -> str + + +.. py:function:: mangle_identifier(ident, template_params='', *, abi_tags=(), uid=None) + + Mangle the identifier with optional template parameters and abi_tags. + + Note: + + This treats '.' as '::' in C++. + + +.. py:function:: mangle_type_c(typ) + + Mangle C type name + + :param typ: C type name + :type typ: str + + +.. py:function:: mangle_type_or_value_numba(typ) + + Mangle type parameter and arbitrary value. + + +.. py:function:: mangle_templated_ident(identifier, parameters) + + Mangle templated identifier. + + +.. py:function:: mangle_args_c(argtys) + + Mangle sequence of C type names + + +.. py:function:: mangle_args(argtys) + + Mangle sequence of Numba type objects and arbitrary values. + + +.. py:function:: mangle_c(ident, argtys) + + Mangle identifier with C type names + + +.. py:function:: mangle(ident, argtys, *, abi_tags=(), uid=None) + + Mangle identifier with Numba type objects and abi-tags. + + +.. py:function:: prepend_namespace(mangled, ns) + + Prepend namespace to mangled name. + + + +Attributes +---------- +.. py:data:: PREFIX + :value: '_Z' + + + +.. py:data:: C2CODE + + + +.. py:data:: N2C + + + +.. py:data:: mangle_type + + + +.. py:data:: mangle_value + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/core/utils/kernel_flattened_args_builder/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/core/utils/kernel_flattened_args_builder/index.rst.txt new file mode 100644 index 0000000000..c7ac630da7 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/core/utils/kernel_flattened_args_builder/index.rst.txt @@ -0,0 +1,147 @@ + + +:orphan: + +numba_dpex.core.utils.kernel_flattened_args_builder +=================================================== + +.. py:module:: numba_dpex.core.utils.kernel_flattened_args_builder + +.. autoapi-nested-parse:: + + Provides helpers to populate the list of kernel arguments that will + be passed to a DPCTLQueue_Submit function call by a KernelLaunchIRBuilder + object. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`KernelArg ` + - Stores the llvm IR value and the dpctl typeid for a kernel argument. + * - :py:obj:`KernelFlattenedArgsBuilder ` + - Helper to generate the flattened list of kernel arguments to be + + + + +Classes +------- + +.. py:class:: KernelArg + + Bases: :py:obj:`NamedTuple` + + Stores the llvm IR value and the dpctl typeid for a kernel argument. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`llvm_val ` + - \- + * - :py:obj:`typeid ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: llvm_val + :type: llvmlite.ir.Instruction + + + + .. py:attribute:: typeid + :type: int + + + + + +.. py:class:: KernelFlattenedArgsBuilder(context: numba.core.cpu.CPUContext, builder: llvmlite.ir.IRBuilder, kernel_dmm) + + Helper to generate the flattened list of kernel arguments to be + passed to a DPCTLQueue_Submit function. + + **Note** Two separate data models are used when building a flattened + kernel argument for the following reason: + + Different numba-dpex targets can use different data models for the same + data type that may have different number of attributes and a different + type for each attribute. + + In the case the DpnpNdArray type, two separate data models are used for + the CPUTarget and for the SPIRVTarget. The SPIRVTarget does not have the + ``parent``, ``meminfo`` and ``sycl_queue`` attributes that are present + in the data model used by the CPUTarget. The SPIRVTarget's data model + for DpnpNdArray also requires an explicit address space qualifier for + the ``data`` attribute. + + When generating the LLVM IR for the host-side control code for executing + a SPIR-V kernel, the kernel arguments are represented using the + CPUTarget's data model for each argument's type. However, the actual + kernel function generated as a SPIR-V binary by the SPIRVTarget uses its + own data model manager to build the flattened kernel function argument + list. For this reason, when building the flattened argument list for a + kernel launch call the host data model is used to extract the + required attributes and then the kernel data model is used to get the + correct type for the attribute. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`add_argument `\ (arg_type, arg_packed_llvm_val) + - Add flattened representation of a kernel argument. + * - :py:obj:`get_kernel_arg_list `\ () + - Returns a list of KernelArg objects representing a flattened kernel + * - :py:obj:`print_kernel_arg_list `\ () + - Prints out the kernel argument list in a human readable format. + + + .. rubric:: Members + + .. py:method:: add_argument(arg_type, arg_packed_llvm_val) + + Add flattened representation of a kernel argument. + + + .. py:method:: get_kernel_arg_list() -> list[KernelArg] + + Returns a list of KernelArg objects representing a flattened kernel + argument. + + :returns: List of flattened KernelArg objects + :rtype: list[KernelArg] + + + .. py:method:: print_kernel_arg_list() -> None + + Prints out the kernel argument list in a human readable format. + + :param args_list: List of kernel arguments to be printed + :type args_list: list[KernelArg] + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_fence/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_fence/index.rst.txt new file mode 100644 index 0000000000..b7d22a1ba2 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_fence/index.rst.txt @@ -0,0 +1,55 @@ + + +:orphan: + +numba_dpex.kernel_api.atomic_fence +================================== + +.. py:module:: numba_dpex.kernel_api.atomic_fence + +.. autoapi-nested-parse:: + + Python functions that simulate SYCL's atomic_fence primitives. + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`atomic_fence `\ (memory_order, memory_scope) + - Performs a memory fence operations across all work-items. + + + + +Functions +--------- +.. py:function:: atomic_fence(memory_order: numba_dpex.kernel_api.memory_enums.MemoryOrder, memory_scope: numba_dpex.kernel_api.memory_enums.MemoryScope) + + Performs a memory fence operations across all work-items. + + The function is equivalent to the ``sycl::atomic_fence`` function and + controls the order of memory accesses (loads and stores) by individual + work-items. + + .. important:: + The function is a no-op during CPython execution and only available in + JIT compiled mode of execution. + + :param memory_order: The memory synchronization order. + :type memory_order: MemoryOrder + :param memory_scope: The set of work-items and devices to which + the memory ordering constraints apply. + :type memory_scope: MemoryScope + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_ref/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_ref/index.rst.txt new file mode 100644 index 0000000000..3cc82ead94 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/atomic_ref/index.rst.txt @@ -0,0 +1,210 @@ + + +:orphan: + +numba_dpex.kernel_api.atomic_ref +================================ + +.. py:module:: numba_dpex.kernel_api.atomic_ref + +.. autoapi-nested-parse:: + + Implements a mock Python class to represent ``sycl::atomic_ref`` for + prototyping numba_dpex kernel functions before they are JIT compiled. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`AtomicRef ` + - Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class. + + + + +Classes +------- + +.. py:class:: AtomicRef(ref, index, memory_order=MemoryOrder.RELAXED, memory_scope=MemoryScope.DEVICE, address_space=None) + + Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class. + + An atomic reference is a view into a data container that can be then updated + atomically using any of the ``fetch_*`` member functions of the class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`fetch_add `\ (val) + - Adds the operand ``val`` to the object referenced by the AtomicRef + * - :py:obj:`fetch_sub `\ (val) + - Subtracts the operand ``val`` to the object referenced by the + * - :py:obj:`fetch_min `\ (val) + - Calculates the minimum value of the operand ``val`` and the object + * - :py:obj:`fetch_max `\ (val) + - Calculates the maximum value of the operand ``val`` and the object + * - :py:obj:`fetch_and `\ (val) + - Calculates the bitwise AND of the operand ``val`` and the object + * - :py:obj:`fetch_or `\ (val) + - Calculates the bitwise OR of the operand ``val`` and the object + * - :py:obj:`fetch_xor `\ (val) + - Calculates the bitwise XOR of the operand ``val`` and the object + * - :py:obj:`load `\ () + - Loads the value of the object referenced by the AtomicRef. + * - :py:obj:`store `\ (val) + - Stores operand ``val`` to the object referenced by the AtomicRef. + * - :py:obj:`exchange `\ (val) + - Replaces the value of the object referenced by the AtomicRef + * - :py:obj:`compare_exchange `\ (expected, desired, expected_idx) + - Compares the value of the object referenced by the AtomicRef + + + .. rubric:: Members + + .. py:method:: fetch_add(val) + + Adds the operand ``val`` to the object referenced by the AtomicRef + and assigns the result to the value of the referenced object. Returns + the original value of the object. + + :param val: Value to be added to the object referenced by the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_sub(val) + + Subtracts the operand ``val`` to the object referenced by the + AtomicRef and assigns the result to the value of the referenced object. + Returns the original value of the object. + + :param val: Value to be subtracted from the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_min(val) + + Calculates the minimum value of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be compared against the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_max(val) + + Calculates the maximum value of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be compared against the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_and(val) + + Calculates the bitwise AND of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise ANDed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_or(val) + + Calculates the bitwise OR of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise ORed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_xor(val) + + Calculates the bitwise XOR of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise XORed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + + .. py:method:: load() + + Loads the value of the object referenced by the AtomicRef. + + Returns: The value of the object referenced by the AtomicRef. + + + .. py:method:: store(val) + + Stores operand ``val`` to the object referenced by the AtomicRef. + + :param val: Value to be stored in the object referenced by the AtomicRef. + + + .. py:method:: exchange(val) + + Replaces the value of the object referenced by the AtomicRef + with value of ``val``. Returns the original value of the referenced + object. + + :param val: Value to be exchanged against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: compare_exchange(expected, desired, expected_idx=0) + + Compares the value of the object referenced by the AtomicRef + against the value of ``expected[expected_idx]``. If the values are + equal, replaces the value of the referenced object with the value of + ``desired``. Otherwise assigns the original value of the referenced + object to ``expected[expected_idx]``. + + :param expected: Array containing the expected value of the object + referenced by the AtomicRef. + :param desired: Value that replaces the value of the object referenced by + the AtomicRef. + :param expected_idx: Offset in `expected` array where the expected + :param value of the object referenced by the AtomicRef is present.: + + Returns: ``True`` if the comparison operation and replacement operation + were successful. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/barrier/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/barrier/index.rst.txt new file mode 100644 index 0000000000..d4f8a08e2e --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/barrier/index.rst.txt @@ -0,0 +1,66 @@ + + +:orphan: + +numba_dpex.kernel_api.barrier +============================= + +.. py:module:: numba_dpex.kernel_api.barrier + +.. autoapi-nested-parse:: + + Python functions that simulate SYCL's group_barrier function. + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`group_barrier `\ (group, fence_scope) + - Performs a barrier operation across all work-items in a work-group. + + + + +Functions +--------- +.. py:function:: group_barrier(group: numba_dpex.kernel_api.index_space_ids.Group, fence_scope: numba_dpex.kernel_api.memory_enums.MemoryScope = MemoryScope.WORK_GROUP) + + Performs a barrier operation across all work-items in a work-group. + + The function is equivalent to the ``sycl::group_barrier`` function. It + synchronizes work within a group of work-items. All the work-items + of the group must execute the barrier call before any work-item + continues execution beyond the barrier. + + The ``group_barrier`` performs a memory fence operation ensuring that memory + accesses issued before the barrier are not re-ordered with those issued + after the barrier. All work-items in group G execute a release fence prior + to synchronizing at the barrier, all work-items in group G execute an + acquire fence afterwards, and there is an implicit synchronization of these + fences as if provided by an explicit atomic operation on an atomic object. + + .. important:: + The function is not implemented yet for pure CPython execution and is + only supported in JIT compiled mode of execution. + + :param group: Indicates the work-group inside which the barrier is to + be executed. + :type group: Group + :param fence_scope: scope of any memory + consistency operations that are performed by the barrier. + :type fence_scope: MemoryScope) (optional + + :raises NotImplementedError: When the function is called directly from Python. + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/flag_enum/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/flag_enum/index.rst.txt new file mode 100644 index 0000000000..2f8fa1ecae --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/flag_enum/index.rst.txt @@ -0,0 +1,72 @@ + + +:orphan: + +numba_dpex.kernel_api.flag_enum +=============================== + +.. py:module:: numba_dpex.kernel_api.flag_enum + +.. autoapi-nested-parse:: + + Provides a FlagEnum class to help distinguish IntEnum types that numba_dpex + intends to use as Integer literal types inside the compiler type inferring + infrastructure. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`FlagEnum ` + - Helper class to distinguish IntEnum types that numba_dpex should consider + + + + +Classes +------- + +.. py:class:: FlagEnum + + Bases: :py:obj:`enum.IntEnum` + + Helper class to distinguish IntEnum types that numba_dpex should consider + as Numba Literal types. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`basetype `\ () + - :summarylabel:`class` Returns an dummy int object that helps numba_dpex infer the type of + + + .. rubric:: Members + + .. py:method:: basetype() -> int + :classmethod: + + Returns an dummy int object that helps numba_dpex infer the type of + an instance of a FlagEnum class. + + :returns: Dummy int value + :rtype: int + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index.rst.txt new file mode 100644 index 0000000000..7baa358a8e --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index.rst.txt @@ -0,0 +1,902 @@ + +numba_dpex.kernel_api +===================== + +.. py:module:: numba_dpex.kernel_api + +.. autoapi-nested-parse:: + + The kernel_api module provides a set of Python classes and functions that are + analogous to the C++ SYCL API. The kernel_api module is meant to allow + prototyping SYCL-like kernels in pure Python before compiling them using + numba_dpex. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`AtomicRef ` + - Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class. + * - :py:obj:`Group ` + - Analogue to the :sycl_group:`sycl::group <>` class. + * - :py:obj:`Item ` + - Analogue to the :sycl_item:`sycl::item <>` class. + * - :py:obj:`NdItem ` + - Analogue to the :sycl_nditem:`sycl::nd_item <>` class. + * - :py:obj:`LocalAccessor ` + - Analogue to the :sycl_local_accessor:`sycl::local_accessor <>` class. + * - :py:obj:`AddressSpace ` + - Analogue of :sycl_addr_space:`SYCL address space classes <>`. + * - :py:obj:`MemoryOrder ` + - Analogue of :sycl_memory_order:`sycl::memory_order <>` enumeration. + * - :py:obj:`MemoryScope ` + - Analogue of :sycl_memory_scope:`sycl::memory_scope <>` enumeration. + * - :py:obj:`PrivateArray ` + - An array that gets allocated on the private memory of a work-item. + * - :py:obj:`NdRange ` + - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + * - :py:obj:`Range ` + - Analogue to the :sycl_range:`sycl::range <>` class. + + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`atomic_fence `\ (memory_order, memory_scope) + - Performs a memory fence operations across all work-items. + * - :py:obj:`group_barrier `\ (group, fence_scope) + - Performs a barrier operation across all work-items in a work-group. + * - :py:obj:`call_kernel `\ (kernel_fn, index_range, \*kernel_args) + - Mocks the launching of a kernel function over either a Range or NdRange. + + + +Classes +------- + +.. py:class:: AtomicRef(ref, index, memory_order=MemoryOrder.RELAXED, memory_scope=MemoryScope.DEVICE, address_space=None) + + Analogue to the :sycl_atomic_ref:`sycl::atomic_ref <>` class. + + An atomic reference is a view into a data container that can be then updated + atomically using any of the ``fetch_*`` member functions of the class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`fetch_add `\ (val) + - Adds the operand ``val`` to the object referenced by the AtomicRef + * - :py:obj:`fetch_sub `\ (val) + - Subtracts the operand ``val`` to the object referenced by the + * - :py:obj:`fetch_min `\ (val) + - Calculates the minimum value of the operand ``val`` and the object + * - :py:obj:`fetch_max `\ (val) + - Calculates the maximum value of the operand ``val`` and the object + * - :py:obj:`fetch_and `\ (val) + - Calculates the bitwise AND of the operand ``val`` and the object + * - :py:obj:`fetch_or `\ (val) + - Calculates the bitwise OR of the operand ``val`` and the object + * - :py:obj:`fetch_xor `\ (val) + - Calculates the bitwise XOR of the operand ``val`` and the object + * - :py:obj:`load `\ () + - Loads the value of the object referenced by the AtomicRef. + * - :py:obj:`store `\ (val) + - Stores operand ``val`` to the object referenced by the AtomicRef. + * - :py:obj:`exchange `\ (val) + - Replaces the value of the object referenced by the AtomicRef + * - :py:obj:`compare_exchange `\ (expected, desired, expected_idx) + - Compares the value of the object referenced by the AtomicRef + + + .. rubric:: Members + + .. py:method:: fetch_add(val) + + Adds the operand ``val`` to the object referenced by the AtomicRef + and assigns the result to the value of the referenced object. Returns + the original value of the object. + + :param val: Value to be added to the object referenced by the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_sub(val) + + Subtracts the operand ``val`` to the object referenced by the + AtomicRef and assigns the result to the value of the referenced object. + Returns the original value of the object. + + :param val: Value to be subtracted from the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_min(val) + + Calculates the minimum value of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be compared against the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_max(val) + + Calculates the maximum value of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be compared against the object referenced by the + AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_and(val) + + Calculates the bitwise AND of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise ANDed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_or(val) + + Calculates the bitwise OR of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise ORed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: fetch_xor(val) + + Calculates the bitwise XOR of the operand ``val`` and the object + referenced by the AtomicRef and assigns the result to the value of the + referenced object. Returns the original value of the object. + + :param val: Value to be bitwise XORed against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + + .. py:method:: load() + + Loads the value of the object referenced by the AtomicRef. + + Returns: The value of the object referenced by the AtomicRef. + + + .. py:method:: store(val) + + Stores operand ``val`` to the object referenced by the AtomicRef. + + :param val: Value to be stored in the object referenced by the AtomicRef. + + + .. py:method:: exchange(val) + + Replaces the value of the object referenced by the AtomicRef + with value of ``val``. Returns the original value of the referenced + object. + + :param val: Value to be exchanged against the object referenced by + the AtomicRef. + + Returns: The original value of the object referenced by the AtomicRef. + + + .. py:method:: compare_exchange(expected, desired, expected_idx=0) + + Compares the value of the object referenced by the AtomicRef + against the value of ``expected[expected_idx]``. If the values are + equal, replaces the value of the referenced object with the value of + ``desired``. Otherwise assigns the original value of the referenced + object to ``expected[expected_idx]``. + + :param expected: Array containing the expected value of the object + referenced by the AtomicRef. + :param desired: Value that replaces the value of the object referenced by + the AtomicRef. + :param expected_idx: Offset in `expected` array where the expected + :param value of the object referenced by the AtomicRef is present.: + + Returns: ``True`` if the comparison operation and replacement operation + were successful. + + + + +.. py:class:: Group(global_range: numba_dpex.kernel_api.ranges.Range, local_range: numba_dpex.kernel_api.ranges.Range, group_range: numba_dpex.kernel_api.ranges.Range, index: list) + + Analogue to the :sycl_group:`sycl::group <>` class. + + Represents a particular work-group within a parallel execution and + provides API to extract various properties of the work-group. An instance + of the class is not user-constructible. Users should use + :func:`numba_dpex.kernel_api.NdItem.get_group` to access the Group to which + a work-item belongs. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_group_id `\ (dim) + - Returns a specific coordinate of the multi-dimensional index of a group. + * - :py:obj:`get_group_linear_id `\ () + - Returns a linearized version of the work-group index. + * - :py:obj:`get_group_range `\ (dim) + - Returns the extent of the range of groups in an nd-range for given dimension. + * - :py:obj:`get_group_linear_range `\ () + - Returns the total number of work-groups in the nd_range. + * - :py:obj:`get_local_range `\ (dim) + - Returns the extent of the range of work-items in a work-group for given dimension. + * - :py:obj:`get_local_linear_range `\ () + - Return the total number of work-items in the work-group. + + + .. rubric:: Members + + .. py:method:: get_group_id(dim) + + Returns a specific coordinate of the multi-dimensional index of a group. + + Since the work-items in a work-group have a defined position within the + global nd-range, the returned group id can be used along with the local + id to uniquely identify the work-item in the global nd-range. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The coordinate for the ``dim`` dimension for the group's + multi-dimensional index within an nd-range. + :rtype: int + + :raises ValueError: If the ``dim`` argument is not in the (1..3) interval. + + + .. py:method:: get_group_linear_id() + + Returns a linearized version of the work-group index. + + :returns: The linearized index for the group's position within an + nd-range. + :rtype: int + + + .. py:method:: get_group_range(dim) + + Returns the extent of the range of groups in an nd-range for given dimension. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The extent of group range for the specified dimension. + :rtype: int + + + .. py:method:: get_group_linear_range() + + Returns the total number of work-groups in the nd_range. + + :returns: Returns the number of groups in a parallel execution of an + nd-range kernel. + :rtype: int + + + .. py:method:: get_local_range(dim) + + Returns the extent of the range of work-items in a work-group for given dimension. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The extent of the local work-item range for the specified + dimension. + :rtype: int + + + .. py:method:: get_local_linear_range() + + Return the total number of work-items in the work-group. + + :returns: Returns the linearized size of the local range inside an + nd-range. + :rtype: int + + + + +.. py:class:: Item(extent: numba_dpex.kernel_api.ranges.Range, index: list) + + Analogue to the :sycl_item:`sycl::item <>` class. + + Identifies the work-item in a parallel execution of a kernel launched with + the :class:`.Range` index-space class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_linear_id `\ () + - Returns the linear id associated with this item for all dimensions. + * - :py:obj:`get_id `\ (idx) + - Get the id for a specific dimension. + * - :py:obj:`get_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_range `\ (idx) + - Get the range size for a specific dimension. + + + .. rubric:: Members + + .. py:method:: get_linear_id() + + Returns the linear id associated with this item for all dimensions. + + :returns: The linear id of the work item in the global range. + :rtype: int + + + .. py:method:: get_id(idx) + + Get the id for a specific dimension. + + :returns: The id + :rtype: int + + + .. py:method:: get_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_range(idx) + + Get the range size for a specific dimension. + + :returns: The size + :rtype: int + + + + +.. py:class:: NdItem(global_item: Item, local_item: Item, group: Group) + + Analogue to the :sycl_nditem:`sycl::nd_item <>` class. + + Identifies an instance of the function object executing at each point in an + :class:`.NdRange`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_id `\ (idx) + - Get the global id for a specific dimension. + * - :py:obj:`get_global_linear_id `\ () + - Get the linearized global id for the item for all dimensions. + * - :py:obj:`get_local_id `\ (idx) + - Get the local id for a specific dimension. + * - :py:obj:`get_local_linear_id `\ () + - Get the local linear id associated with this item for all + * - :py:obj:`get_global_range `\ (idx) + - Get the global range size for a specific dimension. + * - :py:obj:`get_local_range `\ (idx) + - Get the local range size for a specific dimension. + * - :py:obj:`get_local_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_global_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_group `\ () + - Returns the group. + + + .. rubric:: Members + + .. py:method:: get_global_id(idx) + + Get the global id for a specific dimension. + + :returns: The global id + :rtype: int + + + .. py:method:: get_global_linear_id() + + Get the linearized global id for the item for all dimensions. + + :returns: The global linear id. + :rtype: int + + + .. py:method:: get_local_id(idx) + + Get the local id for a specific dimension. + + :returns: The local id + :rtype: int + + + .. py:method:: get_local_linear_id() + + Get the local linear id associated with this item for all + dimensions. + + :returns: The local linear id. + :rtype: int + + + .. py:method:: get_global_range(idx) + + Get the global range size for a specific dimension. + + :returns: The size + :rtype: int + + + .. py:method:: get_local_range(idx) + + Get the local range size for a specific dimension. + + :returns: The size + :rtype: int + + + .. py:method:: get_local_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_global_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_group() + + Returns the group. + + :returns: A group object. + + + + +.. py:class:: LocalAccessor(shape, dtype) + + Analogue to the :sycl_local_accessor:`sycl::local_accessor <>` class. + + The class acts as a proxy to allocating device local memory and + accessing that memory from within a :func:`numba_dpex.kernel` decorated + function. + + + + +.. py:class:: AddressSpace + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_addr_space:`SYCL address space classes <>`. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`PRIVATE ` + - \- + * - :py:obj:`GLOBAL ` + - \- + * - :py:obj:`CONSTANT ` + - \- + * - :py:obj:`LOCAL ` + - \- + * - :py:obj:`GENERIC ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: PRIVATE + :value: 0 + + + + .. py:attribute:: GLOBAL + :value: 1 + + + + .. py:attribute:: CONSTANT + :value: 2 + + + + .. py:attribute:: LOCAL + :value: 3 + + + + .. py:attribute:: GENERIC + :value: 4 + + + + + +.. py:class:: MemoryOrder + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_memory_order:`sycl::memory_order <>` enumeration. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`RELAXED ` + - \- + * - :py:obj:`ACQUIRE ` + - \- + * - :py:obj:`CONSUME_UNSUPPORTED ` + - \- + * - :py:obj:`RELEASE ` + - \- + * - :py:obj:`ACQ_REL ` + - \- + * - :py:obj:`SEQ_CST ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: RELAXED + :value: 0 + + + + .. py:attribute:: ACQUIRE + :value: 1 + + + + .. py:attribute:: CONSUME_UNSUPPORTED + :value: 2 + + + + .. py:attribute:: RELEASE + :value: 3 + + + + .. py:attribute:: ACQ_REL + :value: 4 + + + + .. py:attribute:: SEQ_CST + :value: 5 + + + + + +.. py:class:: MemoryScope + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_memory_scope:`sycl::memory_scope <>` enumeration. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`WORK_ITEM ` + - \- + * - :py:obj:`SUB_GROUP ` + - \- + * - :py:obj:`WORK_GROUP ` + - \- + * - :py:obj:`DEVICE ` + - \- + * - :py:obj:`SYSTEM ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: WORK_ITEM + :value: 0 + + + + .. py:attribute:: SUB_GROUP + :value: 1 + + + + .. py:attribute:: WORK_GROUP + :value: 2 + + + + .. py:attribute:: DEVICE + :value: 3 + + + + .. py:attribute:: SYSTEM + :value: 4 + + + + + +.. py:class:: PrivateArray(shape, dtype, fill_zeros=False) + + An array that gets allocated on the private memory of a work-item. + + The class should be used to allocate small arrays on the private + per-work-item memory for fast accesses inside a kernel. It is similar in + intent to the :sycl_private_memory:`sycl::private_memory <>` class but is + not a direct analogue. + + + + +.. py:class:: NdRange(global_size, local_size) + + Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + + The NdRange defines the index space for a work group as well as + the global index space. It is passed to parallel_for to execute + a kernel on a set of work items. + + This class basically contains two Range object, one for the global_range + and the other for the local_range. The global_range parameter contains + the global index space and the local_range parameter contains the index + space of a work group. This class mimics the behavior of `sycl::nd_range` + class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_range `\ () + - Returns a Range defining the index space. + * - :py:obj:`get_local_range `\ () + - Returns a Range defining the index space of a work group. + + + .. rubric:: Members + + .. py:method:: get_global_range() + + Returns a Range defining the index space. + + :returns: A `Range` object defining the index space. + :rtype: Range + + + .. py:method:: get_local_range() + + Returns a Range defining the index space of a work group. + + :returns: A `Range` object to specify index space of a work group. + :rtype: Range + + + + +.. py:class:: Range + + Bases: :py:obj:`tuple` + + Analogue to the :sycl_range:`sycl::range <>` class. + + The range is an abstraction that describes the number of elements + in each dimension of buffers and index spaces. It can contain + 1, 2, or 3 numbers, depending on the dimensionality of the + object it describes. + + This is just a wrapper class on top of a 3-tuple. The kernel launch + parameter is consisted of three int's. This class basically mimics + the behavior of `sycl::range`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get `\ (index) + - Returns the range of a single dimension. + * - :py:obj:`size `\ () + - Returns the size of a range. + + + .. rubric:: Members + + .. py:method:: get(index) + + Returns the range of a single dimension. + + :param index: The index of the dimension, i.e. [0,2] + :type index: int + + :returns: The range of the dimension indexed by `index`. + :rtype: int + + + .. py:method:: size() + + Returns the size of a range. + + Returns the size of a range by multiplying + the range of the individual dimensions. + + :returns: The size of a range. + :rtype: int + + + + +Functions +--------- +.. py:function:: atomic_fence(memory_order: numba_dpex.kernel_api.memory_enums.MemoryOrder, memory_scope: numba_dpex.kernel_api.memory_enums.MemoryScope) + + Performs a memory fence operations across all work-items. + + The function is equivalent to the ``sycl::atomic_fence`` function and + controls the order of memory accesses (loads and stores) by individual + work-items. + + .. important:: + The function is a no-op during CPython execution and only available in + JIT compiled mode of execution. + + :param memory_order: The memory synchronization order. + :type memory_order: MemoryOrder + :param memory_scope: The set of work-items and devices to which + the memory ordering constraints apply. + :type memory_scope: MemoryScope + + +.. py:function:: group_barrier(group: numba_dpex.kernel_api.index_space_ids.Group, fence_scope: numba_dpex.kernel_api.memory_enums.MemoryScope = MemoryScope.WORK_GROUP) + + Performs a barrier operation across all work-items in a work-group. + + The function is equivalent to the ``sycl::group_barrier`` function. It + synchronizes work within a group of work-items. All the work-items + of the group must execute the barrier call before any work-item + continues execution beyond the barrier. + + The ``group_barrier`` performs a memory fence operation ensuring that memory + accesses issued before the barrier are not re-ordered with those issued + after the barrier. All work-items in group G execute a release fence prior + to synchronizing at the barrier, all work-items in group G execute an + acquire fence afterwards, and there is an implicit synchronization of these + fences as if provided by an explicit atomic operation on an atomic object. + + .. important:: + The function is not implemented yet for pure CPython execution and is + only supported in JIT compiled mode of execution. + + :param group: Indicates the work-group inside which the barrier is to + be executed. + :type group: Group + :param fence_scope: scope of any memory + consistency operations that are performed by the barrier. + :type fence_scope: MemoryScope) (optional + + :raises NotImplementedError: When the function is called directly from Python. + + +.. py:function:: call_kernel(kernel_fn, index_range: Union[numba_dpex.kernel_api.ranges.Range, numba_dpex.kernel_api.ranges.NdRange], *kernel_args) + + Mocks the launching of a kernel function over either a Range or NdRange. + + .. important:: + The function is meant to be used only during prototyping a kernel_api + function in Python. To launch a JIT compiled kernel, the + :func:`numba_dpex.core.kernel_launcher.call_kernel` function should be + used. + + :param kernel_fn: A callable function object written using + :py:mod:`numba_dpex.kernel_api`. + :param index_range: An instance of a Range or an NdRange object + :type index_range: Range|NdRange + :param kernel_args: The expanded list of actual arguments with which to + launch the kernel execution. + :type kernel_args: List + + :raises ValueError: If the first positional argument is not callable. + :raises ValueError: If the second positional argument is not a Range or an + Ndrange object + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index_space_ids/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index_space_ids/index.rst.txt new file mode 100644 index 0000000000..9b305d5640 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/index_space_ids/index.rst.txt @@ -0,0 +1,315 @@ + + +:orphan: + +numba_dpex.kernel_api.index_space_ids +===================================== + +.. py:module:: numba_dpex.kernel_api.index_space_ids + +.. autoapi-nested-parse:: + + Implements a mock Python classes to represent ``sycl::item`` and + ``sycl::nd_item``for prototyping numba_dpex kernel functions before they are JIT + compiled. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`Group ` + - Analogue to the :sycl_group:`sycl::group <>` class. + * - :py:obj:`Item ` + - Analogue to the :sycl_item:`sycl::item <>` class. + * - :py:obj:`NdItem ` + - Analogue to the :sycl_nditem:`sycl::nd_item <>` class. + + + + +Classes +------- + +.. py:class:: Group(global_range: numba_dpex.kernel_api.ranges.Range, local_range: numba_dpex.kernel_api.ranges.Range, group_range: numba_dpex.kernel_api.ranges.Range, index: list) + + Analogue to the :sycl_group:`sycl::group <>` class. + + Represents a particular work-group within a parallel execution and + provides API to extract various properties of the work-group. An instance + of the class is not user-constructible. Users should use + :func:`numba_dpex.kernel_api.NdItem.get_group` to access the Group to which + a work-item belongs. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_group_id `\ (dim) + - Returns a specific coordinate of the multi-dimensional index of a group. + * - :py:obj:`get_group_linear_id `\ () + - Returns a linearized version of the work-group index. + * - :py:obj:`get_group_range `\ (dim) + - Returns the extent of the range of groups in an nd-range for given dimension. + * - :py:obj:`get_group_linear_range `\ () + - Returns the total number of work-groups in the nd_range. + * - :py:obj:`get_local_range `\ (dim) + - Returns the extent of the range of work-items in a work-group for given dimension. + * - :py:obj:`get_local_linear_range `\ () + - Return the total number of work-items in the work-group. + + + .. rubric:: Members + + .. py:method:: get_group_id(dim) + + Returns a specific coordinate of the multi-dimensional index of a group. + + Since the work-items in a work-group have a defined position within the + global nd-range, the returned group id can be used along with the local + id to uniquely identify the work-item in the global nd-range. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The coordinate for the ``dim`` dimension for the group's + multi-dimensional index within an nd-range. + :rtype: int + + :raises ValueError: If the ``dim`` argument is not in the (1..3) interval. + + + .. py:method:: get_group_linear_id() + + Returns a linearized version of the work-group index. + + :returns: The linearized index for the group's position within an + nd-range. + :rtype: int + + + .. py:method:: get_group_range(dim) + + Returns the extent of the range of groups in an nd-range for given dimension. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The extent of group range for the specified dimension. + :rtype: int + + + .. py:method:: get_group_linear_range() + + Returns the total number of work-groups in the nd_range. + + :returns: Returns the number of groups in a parallel execution of an + nd-range kernel. + :rtype: int + + + .. py:method:: get_local_range(dim) + + Returns the extent of the range of work-items in a work-group for given dimension. + + :param dim: An integral value between (1..3) for which the group + index is returned. + :type dim: int + + :returns: The extent of the local work-item range for the specified + dimension. + :rtype: int + + + .. py:method:: get_local_linear_range() + + Return the total number of work-items in the work-group. + + :returns: Returns the linearized size of the local range inside an + nd-range. + :rtype: int + + + + +.. py:class:: Item(extent: numba_dpex.kernel_api.ranges.Range, index: list) + + Analogue to the :sycl_item:`sycl::item <>` class. + + Identifies the work-item in a parallel execution of a kernel launched with + the :class:`.Range` index-space class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_linear_id `\ () + - Returns the linear id associated with this item for all dimensions. + * - :py:obj:`get_id `\ (idx) + - Get the id for a specific dimension. + * - :py:obj:`get_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_range `\ (idx) + - Get the range size for a specific dimension. + + + .. rubric:: Members + + .. py:method:: get_linear_id() + + Returns the linear id associated with this item for all dimensions. + + :returns: The linear id of the work item in the global range. + :rtype: int + + + .. py:method:: get_id(idx) + + Get the id for a specific dimension. + + :returns: The id + :rtype: int + + + .. py:method:: get_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_range(idx) + + Get the range size for a specific dimension. + + :returns: The size + :rtype: int + + + + +.. py:class:: NdItem(global_item: Item, local_item: Item, group: Group) + + Analogue to the :sycl_nditem:`sycl::nd_item <>` class. + + Identifies an instance of the function object executing at each point in an + :class:`.NdRange`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_id `\ (idx) + - Get the global id for a specific dimension. + * - :py:obj:`get_global_linear_id `\ () + - Get the linearized global id for the item for all dimensions. + * - :py:obj:`get_local_id `\ (idx) + - Get the local id for a specific dimension. + * - :py:obj:`get_local_linear_id `\ () + - Get the local linear id associated with this item for all + * - :py:obj:`get_global_range `\ (idx) + - Get the global range size for a specific dimension. + * - :py:obj:`get_local_range `\ (idx) + - Get the local range size for a specific dimension. + * - :py:obj:`get_local_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_global_linear_range `\ () + - Return the total number of work-items in the work-group. + * - :py:obj:`get_group `\ () + - Returns the group. + + + .. rubric:: Members + + .. py:method:: get_global_id(idx) + + Get the global id for a specific dimension. + + :returns: The global id + :rtype: int + + + .. py:method:: get_global_linear_id() + + Get the linearized global id for the item for all dimensions. + + :returns: The global linear id. + :rtype: int + + + .. py:method:: get_local_id(idx) + + Get the local id for a specific dimension. + + :returns: The local id + :rtype: int + + + .. py:method:: get_local_linear_id() + + Get the local linear id associated with this item for all + dimensions. + + :returns: The local linear id. + :rtype: int + + + .. py:method:: get_global_range(idx) + + Get the global range size for a specific dimension. + + :returns: The size + :rtype: int + + + .. py:method:: get_local_range(idx) + + Get the local range size for a specific dimension. + + :returns: The size + :rtype: int + + + .. py:method:: get_local_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_global_linear_range() + + Return the total number of work-items in the work-group. + + + .. py:method:: get_group() + + Returns the group. + + :returns: A group object. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/launcher/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/launcher/index.rst.txt new file mode 100644 index 0000000000..34fd63290d --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/launcher/index.rst.txt @@ -0,0 +1,59 @@ + + +:orphan: + +numba_dpex.kernel_api.launcher +============================== + +.. py:module:: numba_dpex.kernel_api.launcher + +.. autoapi-nested-parse:: + + Implementation of mock kernel launcher functions + + + + + +Overview +-------- + +.. list-table:: Function + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`call_kernel `\ (kernel_fn, index_range, \*kernel_args) + - Mocks the launching of a kernel function over either a Range or NdRange. + + + + +Functions +--------- +.. py:function:: call_kernel(kernel_fn, index_range: Union[numba_dpex.kernel_api.ranges.Range, numba_dpex.kernel_api.ranges.NdRange], *kernel_args) + + Mocks the launching of a kernel function over either a Range or NdRange. + + .. important:: + The function is meant to be used only during prototyping a kernel_api + function in Python. To launch a JIT compiled kernel, the + :func:`numba_dpex.core.kernel_launcher.call_kernel` function should be + used. + + :param kernel_fn: A callable function object written using + :py:mod:`numba_dpex.kernel_api`. + :param index_range: An instance of a Range or an NdRange object + :type index_range: Range|NdRange + :param kernel_args: The expanded list of actual arguments with which to + launch the kernel execution. + :type kernel_args: List + + :raises ValueError: If the first positional argument is not callable. + :raises ValueError: If the second positional argument is not a Range or an + Ndrange object + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/local_accessor/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/local_accessor/index.rst.txt new file mode 100644 index 0000000000..4efb50c58d --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/local_accessor/index.rst.txt @@ -0,0 +1,49 @@ + + +:orphan: + +numba_dpex.kernel_api.local_accessor +==================================== + +.. py:module:: numba_dpex.kernel_api.local_accessor + +.. autoapi-nested-parse:: + + Implements a Python analogue to SYCL's local_accessor class. The class is + intended to be used in pure Python code when prototyping a kernel function + and to be passed to an actual kernel function for local memory allocation. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`LocalAccessor ` + - Analogue to the :sycl_local_accessor:`sycl::local_accessor <>` class. + + + + +Classes +------- + +.. py:class:: LocalAccessor(shape, dtype) + + Analogue to the :sycl_local_accessor:`sycl::local_accessor <>` class. + + The class acts as a proxy to allocating device local memory and + accessing that memory from within a :func:`numba_dpex.kernel` decorated + function. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/memory_enums/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/memory_enums/index.rst.txt new file mode 100644 index 0000000000..2ffe839431 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/memory_enums/index.rst.txt @@ -0,0 +1,227 @@ + + +:orphan: + +numba_dpex.kernel_api.memory_enums +================================== + +.. py:module:: numba_dpex.kernel_api.memory_enums + +.. autoapi-nested-parse:: + + A collection of FlagEnum classes that syntactically represents the SYCL + memory enum classes. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`MemoryOrder ` + - Analogue of :sycl_memory_order:`sycl::memory_order <>` enumeration. + * - :py:obj:`MemoryScope ` + - Analogue of :sycl_memory_scope:`sycl::memory_scope <>` enumeration. + * - :py:obj:`AddressSpace ` + - Analogue of :sycl_addr_space:`SYCL address space classes <>`. + + + + +Classes +------- + +.. py:class:: MemoryOrder + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_memory_order:`sycl::memory_order <>` enumeration. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`RELAXED ` + - \- + * - :py:obj:`ACQUIRE ` + - \- + * - :py:obj:`CONSUME_UNSUPPORTED ` + - \- + * - :py:obj:`RELEASE ` + - \- + * - :py:obj:`ACQ_REL ` + - \- + * - :py:obj:`SEQ_CST ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: RELAXED + :value: 0 + + + + .. py:attribute:: ACQUIRE + :value: 1 + + + + .. py:attribute:: CONSUME_UNSUPPORTED + :value: 2 + + + + .. py:attribute:: RELEASE + :value: 3 + + + + .. py:attribute:: ACQ_REL + :value: 4 + + + + .. py:attribute:: SEQ_CST + :value: 5 + + + + + +.. py:class:: MemoryScope + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_memory_scope:`sycl::memory_scope <>` enumeration. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`WORK_ITEM ` + - \- + * - :py:obj:`SUB_GROUP ` + - \- + * - :py:obj:`WORK_GROUP ` + - \- + * - :py:obj:`DEVICE ` + - \- + * - :py:obj:`SYSTEM ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: WORK_ITEM + :value: 0 + + + + .. py:attribute:: SUB_GROUP + :value: 1 + + + + .. py:attribute:: WORK_GROUP + :value: 2 + + + + .. py:attribute:: DEVICE + :value: 3 + + + + .. py:attribute:: SYSTEM + :value: 4 + + + + + +.. py:class:: AddressSpace + + Bases: :py:obj:`numba_dpex.kernel_api.flag_enum.FlagEnum` + + Analogue of :sycl_addr_space:`SYCL address space classes <>`. + + The integer values of the enums is kept consistent with the corresponding + implementation in dpcpp. + + + .. rubric:: Overview + + .. list-table:: Attributes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`PRIVATE ` + - \- + * - :py:obj:`GLOBAL ` + - \- + * - :py:obj:`CONSTANT ` + - \- + * - :py:obj:`LOCAL ` + - \- + * - :py:obj:`GENERIC ` + - \- + + + + .. rubric:: Members + + .. py:attribute:: PRIVATE + :value: 0 + + + + .. py:attribute:: GLOBAL + :value: 1 + + + + .. py:attribute:: CONSTANT + :value: 2 + + + + .. py:attribute:: LOCAL + :value: 3 + + + + .. py:attribute:: GENERIC + :value: 4 + + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/private_array/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/private_array/index.rst.txt new file mode 100644 index 0000000000..9b32b59a8b --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/private_array/index.rst.txt @@ -0,0 +1,50 @@ + + +:orphan: + +numba_dpex.kernel_api.private_array +=================================== + +.. py:module:: numba_dpex.kernel_api.private_array + +.. autoapi-nested-parse:: + + Implements a simple array intended to be used inside kernel work item. + Implementation is intended to be used in pure Python code when prototyping a + kernel function. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`PrivateArray ` + - An array that gets allocated on the private memory of a work-item. + + + + +Classes +------- + +.. py:class:: PrivateArray(shape, dtype, fill_zeros=False) + + An array that gets allocated on the private memory of a work-item. + + The class should be used to allocate small arrays on the private + per-work-item memory for fast accesses inside a kernel. It is similar in + intent to the :sycl_private_memory:`sycl::private_memory <>` class but is + not a direct analogue. + + + + + + + diff --git a/pull/1473/_sources/autoapi/numba_dpex/kernel_api/ranges/index.rst.txt b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/ranges/index.rst.txt new file mode 100644 index 0000000000..ae1ff86cd8 --- /dev/null +++ b/pull/1473/_sources/autoapi/numba_dpex/kernel_api/ranges/index.rst.txt @@ -0,0 +1,144 @@ + + +:orphan: + +numba_dpex.kernel_api.ranges +============================ + +.. py:module:: numba_dpex.kernel_api.ranges + +.. autoapi-nested-parse:: + + Defines types to define the range of execution of a kernel. The types are + designed along the lines of classes defined in the SYCL 2020 spec section 4.9. + + + + + +Overview +-------- +.. list-table:: Classes + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`Range ` + - Analogue to the :sycl_range:`sycl::range <>` class. + * - :py:obj:`NdRange ` + - Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + + + + +Classes +------- + +.. py:class:: Range + + Bases: :py:obj:`tuple` + + Analogue to the :sycl_range:`sycl::range <>` class. + + The range is an abstraction that describes the number of elements + in each dimension of buffers and index spaces. It can contain + 1, 2, or 3 numbers, depending on the dimensionality of the + object it describes. + + This is just a wrapper class on top of a 3-tuple. The kernel launch + parameter is consisted of three int's. This class basically mimics + the behavior of `sycl::range`. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get `\ (index) + - Returns the range of a single dimension. + * - :py:obj:`size `\ () + - Returns the size of a range. + + + .. rubric:: Members + + .. py:method:: get(index) + + Returns the range of a single dimension. + + :param index: The index of the dimension, i.e. [0,2] + :type index: int + + :returns: The range of the dimension indexed by `index`. + :rtype: int + + + .. py:method:: size() + + Returns the size of a range. + + Returns the size of a range by multiplying + the range of the individual dimensions. + + :returns: The size of a range. + :rtype: int + + + + +.. py:class:: NdRange(global_size, local_size) + + Analogue to the :sycl_ndrange:`sycl::nd_range <>` class. + + The NdRange defines the index space for a work group as well as + the global index space. It is passed to parallel_for to execute + a kernel on a set of work items. + + This class basically contains two Range object, one for the global_range + and the other for the local_range. The global_range parameter contains + the global index space and the local_range parameter contains the index + space of a work group. This class mimics the behavior of `sycl::nd_range` + class. + + + .. rubric:: Overview + + + .. list-table:: Methods + :header-rows: 0 + :widths: auto + :class: summarytable + + * - :py:obj:`get_global_range `\ () + - Returns a Range defining the index space. + * - :py:obj:`get_local_range `\ () + - Returns a Range defining the index space of a work group. + + + .. rubric:: Members + + .. py:method:: get_global_range() + + Returns a Range defining the index space. + + :returns: A `Range` object defining the index space. + :rtype: Range + + + .. py:method:: get_local_range() + + Returns a Range defining the index space of a work group. + + :returns: A `Range` object to specify index space of a work group. + :rtype: Range + + + + + + + diff --git a/pull/1473/_sources/config_options.rst.txt b/pull/1473/_sources/config_options.rst.txt new file mode 100644 index 0000000000..07cfd99c22 --- /dev/null +++ b/pull/1473/_sources/config_options.rst.txt @@ -0,0 +1,6 @@ +.. _configopts: + +Configuration Options +##################### + +.. include:: ./autoapi/numba_dpex/core/config/index.rst diff --git a/pull/1473/_sources/experimental/index.rst.txt b/pull/1473/_sources/experimental/index.rst.txt new file mode 100644 index 0000000000..0737f2d4d2 --- /dev/null +++ b/pull/1473/_sources/experimental/index.rst.txt @@ -0,0 +1,126 @@ +.. _index: +.. include:: ./../ext_links.txt + +Experimental Features +===================== + +Numba-dpex includes various experimental features that are not yet suitable for +everyday production usage, but are included as an engineering preview. +The most prominent experimental features currently included in numba-dpex are +listed in this section. + + +Compiling and Offloading ``dpnp`` statements +-------------------------------------------- + +Data Parallel Extension for NumPy* (`dpnp`_) is a drop-in NumPy* replacement +library built using the oneAPI software stack including `oneMKL`_, `oneDPL`_ and +`SYCL*`_. numba-dpex has experimental support for compiling a subset of dpnp +functions. The feature is enabled by the :py:func:`numba_dpex.dpjit` decorator. + +An example of a supported usage of dpnp in numba-dpex is provided in the +following code snippet: + +.. code-block:: python + + import dpnp + from numba_dpex import dpjit + + + @dpjit + def foo(): + a = dpnp.ones(1024, device="gpu") + return dpnp.sqrt(a) + + + a = foo() + print(a) + print(type(a)) + + +Offloading ``prange`` loops +--------------------------- + +numba-dpex supports using the ``numba.prange`` statements with +``dpnp.ndarray`` objects. All such ``prange`` loops are offloaded as kernels and +executed on a device inferred using the compute follows data programming model. +The next examples shows using a ``prange`` loop. + + +.. code-block:: python + + import dpnp + from numba_dpex import dpjit, prange + + + @dpjit + def foo(): + x = dpnp.ones(1024, device="gpu") + o = dpnp.empty_like(a) + for i in prange(x.shape[0]): + o[i] = x[i] * x[i] + return o + + + c = foo() + print(c) + print(type(c)) + + +``prange`` loop statements can also be used to write reduction loops as +demonstrated by the following naive pairwise distance computation. + +.. code-block:: python + + from numba_dpex import dpjit, prange + import dpnp + import dpctl + + + @dpjit + def pairwise_distance(X1, X2, D): + """Naïve pairwise distance impl - take an array representing M points in N + dimensions, and return the M x M matrix of Euclidean distances + + Args: + X1 : Set of points + X2 : Set of points + D : Outputted distance matrix + """ + # Size of inputs + X1_rows = X1.shape[0] + X2_rows = X2.shape[0] + X1_cols = X1.shape[1] + + float0 = X1.dtype.type(0.0) + + # Outermost parallel loop over the matrix X1 + for i in prange(X1_rows): + # Loop over the matrix X2 + for j in range(X2_rows): + d = float0 + # Compute exclidean distance + for k in range(X1_cols): + tmp = X1[i, k] - X2[j, k] + d += tmp * tmp + # Write computed distance to distance matrix + D[i, j] = dpnp.sqrt(d) + + + q = dpctl.SyclQueue() + X1 = dpnp.ones((10, 2), sycl_queue=q) + X2 = dpnp.zeros((10, 2), sycl_queue=q) + D = dpnp.empty((10, 2), sycl_queue=q) + + pairwise_distance(X1, X2, D) + print(D) + + +Kernel fusion +------------- + +.. ``numba-dpex`` can identify each NumPy* (or ``dpnp``) array expression as a +.. data-parallel kernel and fuse them together to generate a single SYCL kernel. +.. The kernel is automatically offloaded to the specified device where the fusion +.. operation is invoked. Here is a simple example of a Black-Scholes formula +.. computation where kernel fusion occurs at different ``dpnp`` math functions: diff --git a/pull/1473/_sources/getting_started.rst.txt b/pull/1473/_sources/getting_started.rst.txt new file mode 100644 index 0000000000..769b300529 --- /dev/null +++ b/pull/1473/_sources/getting_started.rst.txt @@ -0,0 +1,247 @@ +.. _getting_started: +.. include:: ./ext_links.txt + +.. |copy| unicode:: U+000A9 + +.. |trade| unicode:: U+2122 + +Getting Started +=============== + + +Installing pre-built conda packages +----------------------------------- + +``numba-dpex`` along with its dependencies can be installed using ``conda``. +It is recommended to use conda packages from the ``anaconda.org/intel`` channel +to get the latest production releases. + +.. code-block:: bash + + conda create -n numba-dpex-env \ + numba-dpex dpnp dpctl dpcpp-llvm-spirv \ + -c intel -c conda-forge + +To try out the bleeding edge, the latest packages built from tip of the main +source trunk can be installed from the ``dppy/label/dev`` conda channel. + +.. code-block:: bash + + conda create -n numba-dpex-env \ + numba-dpex dpnp dpctl dpcpp-llvm-spirv \ + -c dppy/label/dev -c intel -c conda-forge + + + +Building from source +-------------------- + +``numba-dpex`` can be built from source using either ``conda-build`` or +``setuptools`` (with ``scikit-build`` backend). + +Steps to build using ``conda-build``: + +1. Ensure ``conda-build`` is installed in the ``base`` conda environment or + create a new conda environment with ``conda-build`` installed. + +.. code-block:: bash + + conda create -n build-env conda-build + conda activate build-env + +2. Build using the vendored conda recipe + +.. code-block:: bash + + conda build conda-recipe -c intel -c conda-forge + +3. Install the conda package + +.. code-block:: bash + + conda install -c local numba-dpex + +Steps to build using ``setup.py``: + +As before, a conda environment with all necessary dependencies is the suggested +first step. + +.. code-block:: bash + + # Create a conda environment that hass needed dependencies installed + conda create -n numba-dpex-env \ + scikit-build cmake dpctl dpnp numba dpcpp-llvm-spirv llvmdev pytest \ + -c intel -c conda-forge + # Activate the environment + conda activate numba-dpex-env + # Clone the numba-dpex repository + git clone https://github.com/IntelPython/numba-dpex.git + cd numba-dpex + python setup.py develop + +Building inside Docker +---------------------- + +A Dockerfile is provided on the GitHub repository to build ``numba-dpex`` +as well as its direct dependencies: ``dpctl`` and ``dpnp``. Users can either use +one of the pre-built images on the ``numba-dpex`` GitHub page or use the +bundled Dockerfile to build ``numba-dpex`` from source. Using the Dockerfile +also ensures that all device drivers and runtime libraries are pre-installed. + +Building +~~~~~~~~ + +Numba dpex ships with multistage Dockerfile, which means there are +different `targets `_ +available for build. The most useful ones: + +- ``runtime`` +- ``runtime-gpu`` +- ``numba-dpex-builder-runtime`` +- ``numba-dpex-builder-runtime-gpu`` + +To build docker image + +.. code-block:: bash + + docker build --target runtime -t numba-dpex:runtime ./ + + +To run docker image + +.. code-block:: bash + + docker run -it --rm numba-dpex:runtime + +.. note:: + + When trying to build a docker image with Intel GPU support, the Dockerfile + will attempt to use the GitHub API to get the latest Intel GPU drivers. + Users may run into an issue related to Github API call limits. The issue + can be bypassed by providing valid GitHub credentials using the + ``GITHUB_USER`` and ``GITHUB_PASSWORD`` + `build args `_ + to increase the call limit. A GitHub + `access token `_ + can also be used instead of the password. + +.. note:: + + When building the docker image behind a firewall the proxy server settings + should be provided using the ``http_proxy`` and ``https_proxy`` build args. + These build args must be specified in lowercase. + +The bundled Dockerfile supports different python versions that can be specified +via the ``PYTHON_VERSION`` build arg. By default, the docker image is based on +the official python image based on slim debian. The requested python version +must be from the available python docker images. + +The ``BASE_IMAGE`` build arg can be used to build the docker image from a +custom image. Note that as the Dockerfile is based on debian any custom base +image should be debian-based, like debian or ubuntu. + +The list of other build args are as follows. Please refer the Dockerfile to +see currently all available build args. + +- ``PYTHON_VERSION`` +- ``CR_TAG`` +- ``IGC_TAG`` +- ``CM_TAG`` +- ``L0_TAG`` +- ``ONEAPI_VERSION`` +- ``DPCTL_GIT_BRANCH`` +- ``DPCTL_GIT_URL`` +- ``DPNP_GIT_BRANCH`` +- ``DPNP_GIT_URL`` +- ``NUMBA_DPEX_GIT_BRANCH`` +- ``NUMBA_DPEX_GIT_URL`` +- ``CMAKE_VERSION`` +- ``CMAKE_VERSION_BUILD`` +- ``INTEL_NUMPY_VERSION`` +- ``INTEL_NUMBA_VERSION`` +- ``CYTHON_VERSION`` +- ``SCIKIT_BUILD_VERSION`` +- ``http_proxy`` +- ``https_proxy`` +- ``GITHUB_USER`` +- ``GITHUB_PASSWORD`` +- ``BASE_IMAGE`` + + +Using the pre-built images +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are several pre-built docker images available: + +- ``runtime`` package that provides a pre-built environment with ``numba-dpex`` + already installed. It is ideal to quickly setup and try + ``numba-dpex``. + +.. code-block:: text + + ghcr.io/intelpython/numba-dpex/runtime:-py[-gpu] + +- ``builder`` package that has all required dependencies pre-installed and is + ideal for building ``numba-dpex`` from source. + +.. code-block:: text + + ghcr.io/intelpython/numba-dpex/builder:-py[-gpu] + +- ``stages`` package primarily meant for creating a new docker image that is + built on top of one of the pre-built images. + +After setting up the docker image, to run ``numba-dpex`` the following snippet +can be used. + +.. code-block:: bash + + docker run --rm -it ghcr.io/intelpython/numba-dpex/runtime:0.20.0-py3.10 bash + +It is advisable to verify the SYCL runtime and driver installation within the +container by either running, + +.. code-block:: bash + + sycl-ls + +or, + +.. code-block:: bash + + python -m dpctl -f + +.. note:: + + To enable GPU device, the ``device`` argument should be used and one of the + ``*-gpu`` images should be used. + + For passing GPU into container on linux use arguments ``--device=/dev/dri``. + However if you are using WSL you need to pass + ``--device=/dev/dxg -v /usr/lib/wsl:/usr/lib/wsl`` instead. + +For example, to run ``numba-dpex`` with GPU support on WSL: + +.. code-block:: bash + + docker run --rm -it \ + --device=/dev/dxg -v /usr/lib/wsl:/usr/lib/wsl \ + ghcr.io/intelpython/numba-dpex/runtime:0.20.0-py3.10-gpu + + + +Testing +------- + +``numba-dpex`` uses pytest for unit testing and the following example +shows a way to run the unit tests. + +.. code-block:: bash + + python -m pytest --pyargs numba_dpex.tests + +Examples +-------- + +A set of examples on how to use ``numba-dpex`` can be found in +``numba_dpex/examples``. diff --git a/pull/1473/_sources/index.rst.txt b/pull/1473/_sources/index.rst.txt new file mode 100644 index 0000000000..8582ce97ff --- /dev/null +++ b/pull/1473/_sources/index.rst.txt @@ -0,0 +1,33 @@ +.. _index: +.. include:: ./ext_links.txt + +Data Parallel Extension for Numba* +================================== + +Numba-dpex is an open-source kernel-programming API and JIT compiler for +portable accelerator programming directly in Python. The API and the compiler is +modeled after the C++ SYCL* language and brings a similar programming model and +language design to Python. The page lists the relevant documentation to learn to +program data-parallel kernels using numba-dpex. + +.. module:: numba_dpex + +.. toctree:: + :maxdepth: 1 + + overview + getting_started + programming_model + user_guide/index + autoapi/index + config_options + supported_sycl_features + experimental/index + useful_links + +.. toctree:: + :maxdepth: 1 + :caption: Miscellaneous Notes + + license + release-notes diff --git a/pull/1473/_sources/license.rst.txt b/pull/1473/_sources/license.rst.txt new file mode 100644 index 0000000000..8752d7d639 --- /dev/null +++ b/pull/1473/_sources/license.rst.txt @@ -0,0 +1,10 @@ +.. _license: +.. include:: ./ext_links.txt + +License +======= + +Numba-dpex is Licensed under Apache License 2.0 that can be found in `LICENSE +`_. All usage and +contributions to the project are subject to the terms and conditions of this +license. diff --git a/pull/1473/_sources/overview.rst.txt b/pull/1473/_sources/overview.rst.txt new file mode 100644 index 0000000000..4087fe5009 --- /dev/null +++ b/pull/1473/_sources/overview.rst.txt @@ -0,0 +1,127 @@ +.. _overview: +.. include:: ./ext_links.txt + +Overview +======== + +Data Parallel Extension for Numba* (`numba-dpex`_) is a free and open-source +LLVM-based code generator for portable accelerator programming in Python. The +code generator implements a new kernel programming API (kapi) in pure Python +that is modeled after the API of the C++ embedded domain-specific language +(eDSL) `SYCL*`_. The SYCL eDSL is an open standard developed under the Unified +Acceleration Foundation (`UXL`_) as a vendor-agnostic way of programming +different types of data-parallel hardware such as multi-core CPUs, GPUs, and +FPGAs. Numba-dpex and kapi aim to bring the same vendor-agnostic and +standard-compliant programming model to Python. + +Numba-dpex is built on top of the open-source `Numba*`_ JIT compiler that +implements a CPython bytecode parser and code generator to lower the bytecode to +LLVM intermediate representation (IR). The Numba* compiler is able to compile a +large sub-set of Python and most of the NumPy library. Numba-dpex uses Numba*'s +tooling to implement the parsing and the typing support for the data types and +functions defined in kapi. A custom code generator is also introduced to lower +kapi functions to a form of LLVM IR that defined a low-level data-parallel +kernel. Thus, a function written kapi although purely sequential when executed +in Python can be compiled to an actual data-parallel kernel that can run on +different types of hardware. Compilation of kapi is possible for x86 +CPU devices, Intel Gen9 integrated GPUs, Intel UHD integrated GPUs, and Intel +discrete GPUs. + +The following example presents a pairwise distance matrix computation as written +in kapi. A detailed description of the API and all relevant concepts are dealt +with elsewhere in the documentation, for now the example introduces the core +tenet of the programming model. + +.. code-block:: python + :linenos: + + from numba_dpex import kernel_api as kapi + import math + import dpnp + + + def pairwise_distance_kernel(item: kapi.Item, data, distance): + i = item.get_id(0) + j = item.get_id(1) + + data_dims = data.shape[1] + + d = data.dtype.type(0.0) + for k in range(data_dims): + tmp = data[i, k] - data[j, k] + d += tmp * tmp + + distance[j, i] = math.sqrt(d) + + + data = dpnp.random.ranf((10000, 3), device="gpu") + dist = dpnp.empty(shape=(data.shape[0], data.shape[0]), device="gpu") + exec_range = kapi.Range(data.shape[0], data.shape[0]) + kapi.call_kernel(kernel(pairwise_distance_kernel), exec_range, data, dist) + +The ``pairwise_distance_kernel`` function conceptually defines a data-parallel +function to be executed individually by a set of "work items". That is, each +work item runs the function for a subset of the elements of the input ``data`` +and ``distance`` arrays. The ``item`` argument passed to the function identifies +the work item that is executing a specific instance of the function. The set of +work items is defined by the ``exec_range`` object and the ``call_kernel`` call +instructs every work item in ``exec_range`` to execute +``pairwise_distance_kernel`` for a specific subset of the data. + +The logical abstraction exposed by kapi is referred to as Single Program +Multiple Data (SPMD) programming model. CUDA or OpenCL programmers will +recognize the programming model exposed by kapi as similar to the one in those +languages. However, as Python has no concept of a work item a kapi function +executes sequentially when invoked from Python. To convert it into a true +data-parallel function, the function has to be first compiled using numba-dpex. +The next example shows the changes to the original script to compile and run the +``pairwise_distance_kernel`` in parallel. + +.. code-block:: python + :linenos: + :emphasize-lines: 7, 25 + + import numba_dpex as dpex + + from numba_dpex import kernel_api as kapi + import math + import dpnp + + + @dpex.kernel + def pairwise_distance_kernel(item: kapi.Item, data, distance): + i = item.get_id(0) + j = item.get_id(1) + + data_dims = data.shape[1] + + d = data.dtype.type(0.0) + for k in range(data_dims): + tmp = data[i, k] - data[j, k] + d += tmp * tmp + + distance[j, i] = math.sqrt(d) + + + data = dpnp.random.ranf((10000, 3), device="gpu") + dist = dpnp.empty(shape=(data.shape[0], data.shape[0]), device="gpu") + exec_range = kapi.Range(data.shape[0], data.shape[0]) + + dpex.call_kernel(pairwise_distance_kernel, exec_range, data, dist) + +To compile a kapi function, the ``call_kernel`` function from kapi has to be +substituted by the one provided in ``numba_dpex`` and the ``kernel`` decorator +has to be added to the kapi function. The actual device for which the function +is compiled and on which it executes is controlled by the input arguments to +``call_kernel``. Allocating the input arguments to be passed to a compiled kapi +function is not done by numba-dpex. Instead, numba-dpex supports passing in +tensors/ndarrays created using either the `dpnp`_ NumPy drop-in replacement +library or the `dpctl`_ SYCl-based Python Array API library. The objects +allocated by these libraries encode the device information for that allocation. +Numba-dpex extracts the information and uses it to compile a kernel for that +specific device and then executes the compiled kernel on it. + +For a more detailed description about programming with numba-dpex, refer the +:doc:`programming_model`, :doc:`user_guide/index` and the :doc:`autoapi/index` +sections of the documentation. To setup numba-dpex and try it out refer the +:doc:`getting_started` section. diff --git a/pull/1473/_sources/programming_model.old.rst.txt b/pull/1473/_sources/programming_model.old.rst.txt new file mode 100644 index 0000000000..9c98ead75c --- /dev/null +++ b/pull/1473/_sources/programming_model.old.rst.txt @@ -0,0 +1,277 @@ +.. _programming_model: +.. include:: ./ext_links.txt + +Programming Model +================= + +In a heterogeneous system there may be **multiple** devices a Python user may +want to engage. For example, it is common for a consumer-grade laptop to feature +an integrated or a discrete GPU alongside a CPU. + +To harness their power one needs to know how to answer the following 3 key +questions: + +1. How does a Python program recognize available computational devices? +2. How does a Python workload specify computations to be offloaded to selected + devices? +3. How does a Python application manage data sharing? + +Recognizing available devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Python package ``dpctl`` answers these questions. All the computational devices +known to the underlying DPC++ runtime can be accessed using +``dpctl.get_devices()``. A specific device of interest `can be selected +`__ +either using a helper function, e.g. ``dpctl.select_gpu_device()``, or by +passing a filter selector string to ``dpctl.SyclDevice`` constructor. + +.. code:: python + + import dpctl + + # select a GPU device. If multiple devices present, + # let the underlying runtime select from GPUs + dev_gpu = dpctl.SyclDevice("gpu") + # select a CPU device + dev_cpu = dpctl.SyclDevice("cpu") + + # stand-alone function, equivalent to C++ + # `auto dev = sycl::gpu_selector().select_device();` + dev_gpu_alt = dpctl.select_gpu_device() + # stand-alone function, equivalent to C++ + # `auto dev = sycl::cpu_selector().select_device();` + dev_cpu_alt = dpctl.select_cpu_device() + +A `device object +`__ +can be used to query properies of the device, such as its name, vendor, maximal +number of computational units, memory size, etc. + +Specifying offload target +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To answer the second question on the list we need a digression to explain +offloading in oneAPI DPC++ first. + +.. note:: + In DPC++, a computation kernel can be specified using generic C++ + programming and then the kernel can be offloaded to any device that is + supported by an underlying SYCL runtime. The device to which the kernel + is offloaded is specified using an **execution queue** when *launching + the kernel*. + + The oneAPI unified programming model brings portability across heterogeneous + architectures. Another important aspect of the programming model is its + inherent flexibility that makes it possible to go beyond portability and even + strive for performance portability. An oneAPI library may be implemented + using C++ techniques such as template metaprogramming or dynamic polymorphism + to implement specializations for a generic kernel. If a kernel is implemented + polymorphically, the specialized implementation will be dispatched based on + the execution queue specified during kernel launch. The oneMKL library is an + example of a performance portable oneAPI library. + +A computational task is offloaded for execution on a device by submitting it to +DPC++ runtime which inserts the task in a computational graph. Once the device +becomes available the runtime selects a task whose dependencies are met for +execution. The computational graph as well as the device targeted by its tasks +are stored in a `SYCL queue +`__ +object. The task submission is therefore always associated with a queue. + +Queues can be constructed directly from a device object, or by using a filter +selector string to indicate the device to construct: + +.. code:: python + + # construct queue from device object + q1 = dpctl.SyclQueue(dev_gpu) + # construct queue using filter selector + q2 = dpctl.SyclQueue("gpu") + +The computational tasks can be stored in an oneAPI native extension in which +case their submission is orchestrated during Python API calls. Let’s consider a +function that offloads an evaluation of a polynomial for every point of a NumPy +array ``X``. Such a function needs to receive a queue object to indicate which +device the computation must be offloaded to: + +.. code:: python + + # allocate space for the result + Y = np.empty_like(X) + # evaluate polynomial on the device targeted by the queue, Y[i] = p(X[i]) + onapi_ext.offloaded_poly_evaluate(exec_q, X, Y) + +Python call to ``onapi_ext.offloaded_poly_evaluate`` applied to NumPy arrays of +double precision floating pointer numbers gets translated to the following +sample C++ code: + +.. code:: cpp + + void + cpp_offloaded_poly_evaluate( + sycl::queue q, const double *X, double *Y, size_t n) { + // create buffers from malloc allocations to make data accessible from device + sycl::buffer<1, double> buf_X(X, n); + sycl::buffer<1, double> buf_Y(Y, n); + + q.submit([&](sycl::handler &cgh) { + // create buffer accessors indicating kernel data-flow pattern + sycl::accessor acc_X(buf_X, cgh, sycl::read_only); + sycl::accessor acc_Y(buf_Y, cgh, sycl::write_only, sycl::no_init); + + cgh.parallel_for(n, + // lambda function that gets executed by different work-items with + // different arguments in parallel + [=](sycl::id<1> id) { + auto x = accX[id]; + accY[id] = 3.0 + x * (1.0 + x * (-0.5 + 0.3 * x)); + }); + }).wait(); + + return; + } + +We refer an interested reader to an excellent and freely available “`Data +Parallel C++ `__” +book for details of this data parallel C++. + +Our package ``numba_dpex`` allows one to write kernels directly in Python. + +.. code:: python + + import numba_dpex + + + @numba_dpex.kernel + def numba_dpex_poly(X, Y): + i = numba_dpex.get_global_id(0) + x = X[i] + Y[i] = 3.0 + x * (1.0 + x * (-0.5 + 0.3 * x)) + +Specifying the execution queue is done using Python context manager: + +.. code:: python + + import numpy as np + + X = np.random.randn(10**6) + Y = np.empty_like(X) + + with dpctl.device_context(q): + # apply the kernel to elements of X, writing value into Y, + # while executing using given queue + numba_dpex_poly[numba_dpex.Range(X.size)](X, Y) + +The argument to ``device_context`` can be a queue object, a device object for +which a temporary queue will be created, or a filter selector string. Thus we +could have equally used ``dpctl.device_context(gpu_dev)`` or +``dpctl.device_context("gpu")``. + +Note that in this examples data sharing was implicitly managed for us: in the +case of calling a function from a precompiled oneAPI native extension data +sharing was managed by DPC++ runtime, while in the case of using ``numba_dpex`` +kernel it was managed during execution of ``__call__`` method. + +Data sharing +~~~~~~~~~~~~ + +Implicit management of data is surely convenient, but its use in an interpreted +code comes at a performance cost. A runtime must implicitly copy data from host +to the device before the kernel execution commences and then copy some (or all) +of it back after the execution completes for every Python API call. + +``dpctl`` provides for allocating memory directly accessible to kernels +executing on a device using SYCL’s Unified Shared Memory (`USM +`__) +feature. It also implements USM-based ND-array object +``dpctl.tensor.usm_ndarray`` that conforms `array-API standard +`__. + +.. code:: python + + import dpctl.tensor as dpt + + # allocate array of doubles using USM-device allocation on GPU device + X = dpt.arange(0.0, end=1.0, step=1e-6, device="gpu", usm_type="device") + # allocate array for the output + Y = dpt.empty_like(X) + + # execution queue is inferred from allocation queues. + # Kernel is executed on the same device where arrays were allocated + numba_dpex_poly[X.size, numba_dpex.DEFAULT_LOCAL_SIZE](X, Y) + +The execution queue can be unambiguously determined in this case since both +arguments are USM arrays with the same allocation queues and ``X.sycl_queue == +Y.sycl_queue`` evaluates to ``True``. Should allocation queues be different, +such an inference becomes ambiguous and ``numba_dpex`` raises +``IndeterminateExecutionQueueError`` advising user to explicitly migrate the +data. + +Migration can be accomplished either by using ``dpctl.tensor.asarray(X, +device=target_device)`` to create a copy, or by using +``X.to_device(target_device)`` method. + +A USM array can be copied back into a NumPy array using ``dpt.asnumpy(Y)`` if +needed. + +Compute follows data +~~~~~~~~~~~~~~~~~~~~ + +Automatic deduction of the execution queue from allocation queues is consistent +with “`local control for data allocation target +`__” +in the array API standard. User has full control over memory allocation through +three keyword arguments present in all `array creation functions +`__. +For example, consider + +.. code:: python + + # TODO + +The keyword ``device`` is `mandated by the array API +`__. +In ``dpctl.tensor`` the allowed values of the keyword are + +- Filter selector string, e.g. ``device="gpu:0"`` +- Existing ``dpctl.SyclDevice`` object, e.g. ``device=dev_gpu`` +- Existing ``dpctl.SyclQueue`` object +- ``dpctl.tensor.Device`` object instance obtained from an existing USM array, + e.g. ``device=X.device`` + +In all cases, an allocation queue object will be constructed as described +`earlier <#specifying-offload-target>`__ and stored in the array instance, +accessible with ``X.sycl_queue``. Instead of using ``device`` keyword, one can +alternatively use ``sycl_queue`` keyword for readability to directly specify a +``dpctl.SyclQueue`` object to be used as the allocation queue. + +The rationale for storing the allocation queue in the array is that kernels +submitted to this queue are guaranteed to be able to correctly dereference (i.e. +access) the USM pointer. Array operations that only involve this single USM +array can thus execute on the allocation queue, and the output array can be +allocated on this same allocation queue with the same usm type as the input +array. + +.. note:: + Reusing the allocation queue of the input + array ensures the computational tasks behind the API call can access the + array without making implicit copies and the output array is allocated + on the same device as the input. + +Compute follows data is the rule prescribing deduction of the execution and the +allocation queue as well as the USM type for the result when multiple USM arrays +are combined. It stipulates that arrays can be combined if and only if their +allocation *queues are the same* as measured by ``==`` operator (i.e. +``X.sycl_queue == Y.sycl_queue`` must evaluate to ``True``). Same queues refer +to the same underlying task graphs and DPC++ schedulers. + +An attempt to combine USM arrays with unsame allocation queues raises an +exception advising the user to migrate the data. Migration can be accomplished +either by using ``dpctl.tensor.asarray(X, device=Y.device)`` to create a copy, +or by using ``X.to_device(Y.device)`` method which can sometime do the migration +more efficiently. + +.. warning:: + ``dpctl`` and ``numba_dpex`` are both under heavy development. Feel free to file an + issue on GitHub or reach out on Gitter should you encounter any issues. diff --git a/pull/1473/_sources/programming_model.rst.txt b/pull/1473/_sources/programming_model.rst.txt new file mode 100644 index 0000000000..c4d2eea32a --- /dev/null +++ b/pull/1473/_sources/programming_model.rst.txt @@ -0,0 +1,59 @@ +.. _programming_model: +.. include:: ./ext_links.txt + +Programming Model +================= + +This section describes the multiple facets of the programming model that defines +how programmers can use numba-dpex to develop parallel applications. The goal of +the section is to provide users new to accelerator programming or parallel +programming in general an introduction to some of the core concepts and map +those concepts to numba-dpex's interface. + + +Data-level parallelism +---------------------- + +A large part of the massive-level of parallelism offered by accelerators such as +GPUs is the ability to exploit *data-level parallelism* or simply *data +parallelism*. The term refers to a common pattern that occurs in many types of +programs where multiple units of the data accessed by the program can be +operated by a computer at the same time. All modern computing platforms offer +features to exploit data parallelism. Hardware features such as multiple nodes +of a cluster computer, multiple cores or execution units of a CPU or a GPU, +multiple threads inside a single execution unit, and even short-vector single +instruction multiple data (SIMD) registers on a core, all offer ways to exploit +data parallelism. Some of these hardware features such as SIMD registers are +exclusively designed for data parallelism, whereas others are more +general-purpose. + +The diversity of the hardware landscape coupled with the different API required +by each type of hardware leads to conundrum for both programmers and programming +language designers: *How to define a common programming model that can express +data parallelism?* Defining a common programming model first and foremost +requires a common execution model backed by an operational semantics +:cite:p:`scott70` defining the computational steps of the execution model. + + +SPMD +---- +logical abstraction + +SIMD/SIMT implementation model + + +Execution Model +--------------- + +Memory Model +------------ + +Kernel Dependency Model +----------------------- + +Compute follows data +-------------------- + +References +~~~~~~~~~~ +.. bibliography:: diff --git a/pull/1473/_sources/release-notes.rst.txt b/pull/1473/_sources/release-notes.rst.txt new file mode 100644 index 0000000000..ed091cce62 --- /dev/null +++ b/pull/1473/_sources/release-notes.rst.txt @@ -0,0 +1,8 @@ +.. _release-notes: +.. include:: ./ext_links.txt + +Release Notes +============= + +.. include:: ../../CHANGELOG.md + :parser: myst_parser.sphinx_ diff --git a/pull/1473/_sources/supported_sycl_features.rst.txt b/pull/1473/_sources/supported_sycl_features.rst.txt new file mode 100644 index 0000000000..ddce5a099e --- /dev/null +++ b/pull/1473/_sources/supported_sycl_features.rst.txt @@ -0,0 +1,216 @@ +.. _sycl-vs-dpex: + + +SYCL* and numba-dpex Feature Comparison +####################################### + +The numba-dpex kernel API is developed with the aim of providing a SYCL*-like +kernel programming features directly in Python. The page provides a summary of +the SYCL* kernel programming features that are currently supported in +numba-dpex's kernel API. + +Numba-dpex does not implement wrappers or analogues of SYCL's host-callable +runtime API. Such features are provided by the ``dpctl`` package. + +.. list-table:: Ranges and index space identifiers + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* class + - numba-dpex class + - Notes + * - ``range`` + - :class:`numba_dpex.kernel_api.Range` + - + * - ``nd_range`` + - :class:`numba_dpex.kernel_api.NdRange` + - + * - ``id`` + - + - Not directly supported. All functions that return an ``id`` object in + SYCL have versions in numba-dpex that require the dimension to be + explicitly specified. Equivalent to ``get_id.get(dim)``. + * - ``item`` + - :class:`numba_dpex.kernel_api.Item` + - + * - ``nd_item`` + - :class:`numba_dpex.kernel_api.NdItem` + - + * - ``h_item`` + - + - Not supported. There is no corresponding API in numba-dpex for + ``group::parallel_for_work_item`` or ``parallel_for_work_group``. + * - ``group`` + - :class:`numba_dpex.kernel_api.Group` + - + * - ``sub_group`` + - + - Not supported + +.. list-table:: Reduction variables + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* class + - numba-dpex class + - Notes + * - ``reduction`` + - + - Not supported + * - ``reducer`` + - + - Not supported + +.. list-table:: Invoking kernels + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* function for invoking kernels + - numba-dpex function for invoking kernels + - Notes + * - ``single_task`` + - + - Not supported + * - ``parallel_for`` + - :func:`numba_dpex.core.kernel_launcher.call_kernel` + - + + +.. list-table:: Synchronization and atomics + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* feature + - numba-dpex feature + - Notes + * - Accessor classes + - + - Not supported. Explicit ``sycl::event`` SYCL* objects exposed as + ``dpctl.SyclEvent`` Python objects can be used for asynchronous kernel + invocation using the + :func:`numba_dpex.core.kernel_launcher.call_kernel_async` function. + * - ``group_barrier`` + - :func:`numba_dpex.kernel_api.group_barrier` + - group_barrier does not support synchronization across a sub-group. + * - ``atomic_fence`` + - :func:`numba_dpex.kernel_api.atomic_fence` + - + * - ``device_event`` + - + - Not supported + * - ``atomic_ref`` + - :class:`numba_dpex.kernel_api.AtomicRef` + - Atomic references are supported for both global and local memory. + +.. list-table:: On-device memory allocation + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* class + - numba-dpex class + - Notes + * - ``local_accessor`` + - :class:`numba_dpex.kernel_api.LocalAccessor` + - + * - ``private_memory`` + - + - Not supported as there is no corresponding API in numba-dpex for + ``group::parallel_for_work_item`` or ``parallel_for_work_group``. + + Allocating variables on a work-item's private memory can be done using + :class:`numba_dpex.kernel_api.PrivateMemory`. + * - Constant memory + - + - SYCL 2020 no longer defines a constant memory region in the device memory + model specification and as such the feature is not implemented by + numba-dpex. + * - Global memory + - + - Global memory allocation is not handled by numba-dpex and the kernel + argument is expected to have allocated memory on a device's global + memory region using a USM allocators. Such allocators are provided by + the ``dpctl`` package. + +.. list-table:: Group functions + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* group function + - numba-dpex function + - Notes + * - ``group_broadcast`` + - + - Not supported + * - ``group_barrier`` + - :func:`numba_dpex.kernel_api.group_barrier` + - group_barrier does not support synchronization across a sub-group. + +.. list-table:: Group algorithms + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* group algorithm + - numba-dpex function + - Notes + * - ``joint_any_of`` + - + - Not supported + * - ``joint_all_of`` + - + - Not supported + * - ``joint_none_of`` + - + - Not supported + * - ``any_of_group`` + - + - Not supported + * - ``all_of_group`` + - + - Not supported + * - ``none_of_group`` + - + - Not supported + * - ``shift_group_left`` + - + - Not supported + * - ``shift_group_right`` + - + - Not supported + * - ``permute_group_by_xor`` + - + - Not supported + * - ``select_from_group`` + - + - Not supported + * - ``joint_reduce`` + - + - Not supported + * - ``reduce_over_group`` + - + - Not supported + * - ``joint_exclusive_scan`` + - + - Not supported + * - ``joint_inclusive_scan`` + - + - Not supported + * - ``exclusive_scan_over_group`` + - + - Not supported + * - ``inclusive_scan_over_group`` + - + - Not supported + +.. list-table:: Math functions + :widths: 25 25 50 + :header-rows: 1 + + * - SYCL* math function category + - numba-dpex + - Notes + * - Math functions + - + - Refer the kernel programming guide for list of supported functions. + * - Half and reduced precision math functions + - + - Not supported diff --git a/pull/1473/_sources/useful_links.rst.txt b/pull/1473/_sources/useful_links.rst.txt new file mode 100644 index 0000000000..221cc5cdce --- /dev/null +++ b/pull/1473/_sources/useful_links.rst.txt @@ -0,0 +1,41 @@ +.. _useful_links: +.. include:: ./ext_links.txt + +Useful links +============ + +.. list-table:: **Companion documentation** + :widths: 70 200 + :header-rows: 1 + + * - Document + - Description + * - `Data Parallel Extension for Numpy*`_ + - Documentation for programming NumPy-like codes on data parallel devices + * - `Data Parallel Extension for Numba*`_ + - Documentation for programming Numba codes on data parallel devices the same way as you program Numba on CPU + * - `Data Parallel Control`_ + - Documentation how to manage data and devices, how to interchange data between different tensor implementations, + and how to write data parallel extensions + * - `Intel VTune Profiler`_ + - Performance profiler supporting analysis of bottlenecks from function leve down to low level instructions. + Supports Python and Numba + * - `Intel Advisor`_ + - Analyzes native and Python codes and provides an advice for better composition of heterogeneous algorithms + * - `Python* Array API Standard`_ + - Standard for writing portable Numpy-like codes targeting different hardware vendors and frameworks + operating with tensor data + * - `SYCL*`_ + - Standard for writing C++-like codes for heterogeneous computing + * - `DPC++`_ + - Free e-book how to program data parallel devices using Data Parallel C++ + * - `OpenCl*`_ + - OpenCl* Standard for heterogeneous programming + * - `IEEE 754-2019 Standard for Floating-Point Arithmetic`_ + - Standard for floating-point arithmetic, essential for writing robust numerical codes + * - `Numpy*`_ + - Documentation for Numpy - foundational CPU library for array programming. Used in conjunction with + `Data Parallel Extension for Numpy*`_. + * - `Numba*`_ + - Documentation for Numba - Just-In-Time compiler for Numpy-like codes. Used in conjunction with + `Data Parallel Extension for Numba*`_. diff --git a/pull/1473/_sources/user_guide/debugging/altering.rst.txt b/pull/1473/_sources/user_guide/debugging/altering.rst.txt new file mode 100644 index 0000000000..c7813a3b49 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/altering.rst.txt @@ -0,0 +1,53 @@ +.. include:: ./../../ext_links.txt + +Altering Execution +================== + +See `GDB* documentation `_. + +.. _assignment-to-variables: + +Assignment to Variables +----------------------- + +To alter the value of a variable, evaluate an assignment expression. +This also works for function arguments. + +.. note:: + + Altering arguments has limitation. For it to work correctly + arguments should not be modified in code. + See `Numba issue `_. + +Example +``````` + +Source code :file:`numba_dpex/examples/debug/side-by-side-2.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side-2.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 6 + +Debug session: + +.. code-block:: shell-session + :emphasize-lines: 11- + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_OPT 0 + (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1 + (gdb) break side-by-side-2.py:29 if param_a == 5 + ... + (gdb) run numba_dpex/examples/debug/side-by-side-2.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lane 5, __main__::common_loop_body (i=5, a=..., b=...) at side-by-side-2.py:29 + 29 result = param_c + param_d + (gdb) print param_c + $1 = 15 + (gdb) print param_c=200 + $2 = 200 + (gdb) print param_c + $3 = 200 diff --git a/pull/1473/_sources/user_guide/debugging/backtrace.rst.txt b/pull/1473/_sources/user_guide/debugging/backtrace.rst.txt new file mode 100644 index 0000000000..6935df4f51 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/backtrace.rst.txt @@ -0,0 +1,37 @@ +.. include:: ./../../ext_links.txt + +Backtrace +========== + +The ``backtrace`` command displays a summary of how your program got where it +is. Consider the following example +``numba_dpex/examples/debug/simple_dpex_func.py``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_dpex_func.py + :lines: 5- + :linenos: + :lineno-match: + + +The section presents two examples of using Intel Distribution for GDB* to +generate backtrace from a numa_dpex.kernel function. The first example presents +the case where the kernel function does not invoke any other function. The +second example presents the case where the kernel function invokes a +numba_dpex.func. + +Example 1: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/backtrace_kernel + :language: shell-session + :emphasize-lines: 8,9 + +Example 2: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/backtrace + :language: shell-session + :emphasize-lines: 8-10 + +See also: + + - `Backtraces in GDB* + `_ diff --git a/pull/1473/_sources/user_guide/debugging/breakpoints.rst.txt b/pull/1473/_sources/user_guide/debugging/breakpoints.rst.txt new file mode 100644 index 0000000000..bb6b2504cf --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/breakpoints.rst.txt @@ -0,0 +1,83 @@ +.. include:: ./../../ext_links.txt + +Breakpoints +=========== + +A `breakpoint` makes your program stop whenever a certain point in the program +is reached. + +You can set breakpoints with the ``break`` command to specify the place where +your program should stop in the kernel. Define breakpoints by line numbers or +function names. + +You have several ways to set breakpoints: + - ``break `` + - ``break :`` + - ``break :`` + - ``break … if `` + +See also: + - `Breakpoints in GDB*`_. + +.. _Breakpoints in GDB*: https://sourceware.org/gdb/onlinedocs/gdb/Set-Breaks.html#Set-Breaks + +Consider the following numba-dpex kernel code (refer +``numba_dpex/examples/debug/simple_sum.py`` for full example): + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_sum.py + :lines: 5- + :linenos: + :lineno-match: + +``break function`` +------------------ + +The debugger output: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/break_func + :language: shell-session + :emphasize-lines: 3 + +``break filename:linenumber`` +----------------------------- + +The debugger output: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/break_line_number + :language: shell-session + :emphasize-lines: 3 + +``break filename:function`` +--------------------------- + +The debugger output: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/break_file_func + :language: shell-session + :emphasize-lines: 3 + +``break … if cond`` +------------------- + +The debugger output: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/break_conditional + :language: shell-session + :emphasize-lines: 3 + +Breakpoints with nested functions +--------------------------------- + +Consider numba-dpex kernel code. See the source file +``numba_dpex/examples/debug/simple_dpex_func.py``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_dpex_func.py + :lines: 5- + :linenos: + :lineno-match: + +The debugger output: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/break_nested_func + :language: shell-session + :emphasize-lines: 3 diff --git a/pull/1473/_sources/user_guide/debugging/common_issues.rst.txt b/pull/1473/_sources/user_guide/debugging/common_issues.rst.txt new file mode 100644 index 0000000000..a214a9883d --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/common_issues.rst.txt @@ -0,0 +1,53 @@ +.. include:: ./../../ext_links.txt + +Common issues and tips +====================== + +Breakpoints are not hit +----------------------- +If the breakpoint is not hit, you will see the following output: + +.. code-block:: bash + + ... intelgt: gdbserver-gt failed to start. Check if igfxdcd is installed, + or use env variable INTELGT_AUTO_ATTACH_DISABLE=1 to disable auto-attach. + ... + +To install the debug companion driver (igfxdcd), refer to the +:ref:`debugging-machine-dcd-driver` section. + +Debugging is not stable +----------------------- + +Debug features depend heavily on optimization level. At full optimization +(equivalent to O3), most of the variables are optimized out. It is recommended +to debug at "no optimization" level via :envvar:`NUMBA_OPT` (e.g. :samp:`export +NUMBA_OPT=0`). For more information, refer to the Numba documentation `Debugging +JIT compiled code with GDB*`_. + +It is possible to enable debug mode for the full application by setting the +environment variable ``NUMBA_DPEX_DEBUGINFO=1`` instead of ``debug`` option +inside the ``numba_dpex.kernel`` decorator. This sets the default value of the +debug option in ``numba_dpex.kernel``. If ``NUMBA_DPEX_DEBUGINFO`` is set to a +non-zero value, the debug data is emitted for the full application. Debug mode +can be turned off on individual functions by setting ``debug=False`` in +``numba_dpex.kernel``. + +See also: + + - `Debugging JIT compiled code with GDB* + `_ + - `NUMBA_DEBUGINFO + `_ + +Breakpoint is hit twice +----------------------- + +The first line of the kernel and functions is hit twice. This happens because +you are debugging a multi-threaded program, so multiple events may be received +from different threads. This is the default behavior, but you can configure it +for more efficient debugging. To ensure that the current thread executes a +single line without interference, activate the scheduler-locking setting. + +To activate the scheduler-locking setting, refer to the :ref:`single_stepping` +section. diff --git a/pull/1473/_sources/user_guide/debugging/data.rst.txt b/pull/1473/_sources/user_guide/debugging/data.rst.txt new file mode 100644 index 0000000000..0926a8020e --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/data.rst.txt @@ -0,0 +1,60 @@ +.. include:: ./../../ext_links.txt + +Examining Data +============== + +See `GDB* documentation `_. + +.. _print: + +``print expr`` +-------------- + +To print the value of a variable, run the ``print `` command. + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 67-72 + :emphasize-lines: 1-6 + +.. note:: + + Displaying complex data types requires Numba 0.55 or higher. + +Example - Complex Data Types +```````````````````````````` + +Source code :file:`numba_dpex/examples/debug/side-by-side-2.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side-2.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 6 + +Debug session: + +.. code-block:: shell-session + :emphasize-lines: 9- + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_OPT 0 + (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1 + (gdb) break side-by-side-2.py:29 if param_a == 5 + ... + (gdb) run numba_dpex/examples/debug/side-by-side-2.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lane 5, __main__::common_loop_body (i=5, a=..., b=...) at side-by-side-2.py:29 + 29 result = param_c + param_d + (gdb) print a + $1 = {meminfo = 0x0, parent = 0x0, nitems = 10, itemsize = 4, + data = 0x555558461000, shape = {10}, strides = {4}} + (gdb) x/10f a.data + 0x555558461000: 0 1 2 3 + 0x555558461010: 4 5 6 7 + 0x555558461020: 8 9 + (gdb) print a.data[5] + $2 = 5 + +This example prints array and its element. diff --git a/pull/1473/_sources/user_guide/debugging/debugging_environment.rst.txt b/pull/1473/_sources/user_guide/debugging/debugging_environment.rst.txt new file mode 100644 index 0000000000..abedd0840d --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/debugging_environment.rst.txt @@ -0,0 +1,54 @@ +.. include:: ./../../ext_links.txt + +Configure debugging environment +================================= + +1) Activate the debugger and compiler: + + .. code-block:: bash + + export ONEAPI_ROOT=/path/to/oneapi + source $ONEAPI_ROOT/debugger/latest/env/vars.sh + source $ONEAPI_ROOT/compiler/latest/env/vars.sh + +2) Create and activate conda environment with the installed numba-dpex: + + .. code-block:: bash + + conda create numba-dpex-dev numba-dpex + conda activate numba-dpex-dev + +3) Activate NEO drivers (optional). + + If you want to use the local NEO driver, activate the variables for it. See + the :ref:`NEO-driver`. + +4) Check debugging environment. + + You can check the correctness of the work with the following example: + + .. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_sum.py + :lines: 5- + :linenos: + :lineno-match: + + Launch the Intel® Distribution for GDB* and set a breakpoint in the kernel: + + .. code-block:: shell-session + + $ gdb-oneapi -q --args python simple_sum.py + (gdb) break simple_sum.py:22 + No source file named simple_sum.py. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (simple_sum.py:22) pending. + (gdb) run + + In the output you can see that the breakpoint was hit successfully: + + .. code-block:: shell-session + + Thread 2.2 hit Breakpoint 1, with SIMD lanes [0-7], __main__::data_parallel_sum () at simple_sum.py:22 + 22 i = dpex.get_global_id(0) + (gdb) continue + Done... + ... diff --git a/pull/1473/_sources/user_guide/debugging/features.rst.txt b/pull/1473/_sources/user_guide/debugging/features.rst.txt new file mode 100644 index 0000000000..e6d95e6983 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/features.rst.txt @@ -0,0 +1,26 @@ +.. include:: ./../../ext_links.txt + +Supported Features +================== + +Numba-dpex and Intel® Distribution for GDB* provide at least +following debugging features: + +.. toctree:: + :maxdepth: 2 + + breakpoints + stepping + frame_info + backtrace + data + symbols + altering + +Other topics: + +.. toctree:: + :maxdepth: 2 + + local_variables + numba-0.55 diff --git a/pull/1473/_sources/user_guide/debugging/frame_info.rst.txt b/pull/1473/_sources/user_guide/debugging/frame_info.rst.txt new file mode 100644 index 0000000000..bd2b9e1f76 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/frame_info.rst.txt @@ -0,0 +1,81 @@ +.. include:: ./../../ext_links.txt + +Information About a Frame +========================= + +See `GDB* documentation `_. + +.. _info-args: + +``info args`` +------------- + +Test :file:`numba_dpex/tests/debugging/test_info.py:test_info_args`. + +.. note:: + + Requires Numba 0.55 or higher. + In previous versions ``info args`` always returns ``No arguments.``. + +Example +``````` + +Source code :file:`numba_dpex/examples/debug/side-by-side.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 2 + +Debug session: + +.. code-block:: shell-session + :emphasize-lines: 9-11 + + $ NUMBA_OPT=0 gdb-oneapi -q python + ... + (gdb) break side-by-side.py:25 + ... + (gdb) run numba_dpex/examples/debug/side-by-side.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], __main__::common_loop_body (param_a=0, param_b=0) at side-by-side.py:25 + 25 param_c = param_a + 10 # Set breakpoint here + (gdb) info args + param_a = 0 + param_b = 0 + +.. _info-locals: + +``info locals`` +--------------- + +Test :file:`numba_dpex/tests/debugging/test_info.py:test_info_locals`. + +.. note:: + + Requires Numba 0.55 or higher. + +Example +``````` + +Source code :file:`sum_local_vars.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/sum_local_vars.py + :lines: 5- + :linenos: + :lineno-match: + +Run the debugger with ``NUMBA_OPT=0``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 1-6 + +Use ``info locals``. +Note that uninitialized variables are zeros: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 8-48 + :emphasize-lines: 1-16, 24-39 diff --git a/pull/1473/_sources/user_guide/debugging/index.rst.txt b/pull/1473/_sources/user_guide/debugging/index.rst.txt new file mode 100644 index 0000000000..04916265d6 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/index.rst.txt @@ -0,0 +1,66 @@ +.. _index: +.. include:: ./../../ext_links.txt + +Debugging with Intel® Distribution for GDB* +=========================================== + +Numba-dpex allows you to debug SYCL* kernels with Intel® Distribution for GDB*. +To enable the emission of debug information, set the debug environment variable +:envvar:`NUMBA_DPEX_DEBUGINFO`, for example: +:samp:`export NUMBA_DPEX_DEBUGINFO=1` +To disable debugging, unset the variable: +:samp:`unset NUMBA_DPEX_DEBUGINFO` + +.. note:: + + Enabling debug information significantly increases the memory consumption + for each compiled kernel. For a large application, this may cause + out-of-memory error. + +Not all debugging features supported by Numba on CPUs are yet supported by +numba-dpex. See :ref:`debugging-features-and-limitations`. + +Requirements +------------ + +`Intel® Distribution for GDB*` is required for numba-dpex debugging features to +work. +`Intel® Distribution for GDB*` is part of `Intel oneAPI`. For relevant +documentation, refer to the `Intel® Distribution for GDB* product page`_. + +.. _`Intel® Distribution for GDB* product page`: https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-gdb.html + +.. toctree:: + :maxdepth: 2 + + set_up_machine + debugging_environment + + +Example of Intel® Distribution for GDB* usage +--------------------------------------------- + +You can use a sample kernel code, :file:`simple_sum.py`, for basic debugging: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_sum.py + :lines: 5- + :linenos: + :lineno-match: + +Use the following commands to create a breakpoint inside the kernel and run the +debugger: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/simple_sum + :language: shell-session + +.. _debugging-features-and-limitations: + +Features and Limitations +------------------------ + +.. toctree:: + :maxdepth: 2 + + features + limitations + common_issues diff --git a/pull/1473/_sources/user_guide/debugging/limitations.rst.txt b/pull/1473/_sources/user_guide/debugging/limitations.rst.txt new file mode 100644 index 0000000000..e061148c9f --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/limitations.rst.txt @@ -0,0 +1,23 @@ +.. include:: ./../../ext_links.txt + +Limitations +=========== + +The following functionality is **limited** or **not supported**. + +Altering arguments modified in code +----------------------------------- + +Altering arguments has limitation. For it to work correctly +arguments should not be modified in code. +See `Numba issue `_. + +See :ref:`assignment-to-variables`. + +Using Numba's direct ``gdb`` bindings in ``nopython`` mode +---------------------------------------------------------- + +Using Numba's direct ``gdb`` bindings in ``nopython`` mode is not supported in +numba-dpex. + +See `Numba documentation `_. diff --git a/pull/1473/_sources/user_guide/debugging/local_variables.rst.txt b/pull/1473/_sources/user_guide/debugging/local_variables.rst.txt new file mode 100644 index 0000000000..6bb61d6637 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/local_variables.rst.txt @@ -0,0 +1,382 @@ +.. include:: ./../../ext_links.txt + +Debugging Local Variables +========================= + +Several conditions could influence debugging of local variables: + +1. :ref:`numba-opt` +2. :ref:`local-variables-lifetime` + +.. _numba-opt: + +Optimization Level for LLVM +--------------------------- + +Numba provides environment variable ``NUMBA_OPT`` for configuring +optimization level for LLVM. The default optimization level is three. +Refer `Numba documentation`_ for details. It is recommended to debug with +:samp:`NUMBA_OPT=0`. The possible effect of various optimization levels may be +as follows: + +* :samp:`NUMBA_OPT=0` means "no optimization" level - all local variables are available. +* :samp:`NUMBA_OPT=1` or higher levels - some variables may be optimized out. + +Example +``````` + +Source code :file:`numba_dpex/examples/debug/sum_local_vars.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/sum_local_vars.py + :pyobject: data_parallel_sum + :linenos: + :lineno-match: + :emphasize-lines: 6 + +Debug session with :samp:`NUMBA_OPT=0`: + +.. code-block:: shell-session + :emphasize-lines: 3, 10-13 + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_OPT 0 + (gdb) break sum_local_vars.py:26 + ... + (gdb) run numba_dpex/examples/debug/sum_local_vars.py + ... + Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], __main__::data_parallel_sum (a=..., b=..., c=...) at sum_local_vars.py:26 + 26 c[i] = l1 + l2 + (gdb) info locals + i = 0 + l1 = 2.9795852899551392 + l2 = 0.22986688613891601 + +It printed all local variables with their values. + +Debug session with :samp:`NUMBA_OPT=1`: + +.. code-block:: shell-session + :emphasize-lines: 3, 10-11 + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_OPT 1 + (gdb) break sum_local_vars.py:26 + ... + (gdb) run numba_dpex/examples/debug/sum_local_vars.py + ... + Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], ?? () at sum_local_vars.py:26 from /tmp/kernel_11059955544143858990_e6df1e.dbgelf + 26 c[i] = l1 + l2 + (gdb) info locals + No locals. + +It optimized out local variables ``i``, ``l1`` and ``l2`` with this optimization level. + +.. _local-variables-lifetime: + +Local Variables Lifetime in Numba IR +------------------------------------ + +Lifetime of Python variables are different from lifetime of variables in compiled code. +Numba analyses variables lifetime and try to optimize it. +The debugger can show the variable values, but they may be zeros +after the variable is explicitly deleted when the scope of variable is ended. + +See `Numba variable policy `_. + +Numba provides environment variable ``NUMBA_EXTEND_VARIABLE_LIFETIMES`` +for extending the lifetime of variables to the end of the block in which their lifetime ends. + +See `Numba documentation`_. + +Default is zero. + +It is recommended to debug with :samp:`NUMBA_EXTEND_VARIABLE_LIFETIMES=1`. + +Example 1 - Using ``NUMBA_EXTEND_VARIABLE_LIFETIMES`` +````````````````````````````````````````````````````` + +Source code :file:`numba_dpex/tests/debugging/test_info.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 5 + +Debug session with :samp:`NUMBA_EXTEND_VARIABLE_LIFETIMES=1`: + +.. code-block:: shell-session + :emphasize-lines: 3, 10-12 + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1 + (gdb) break side-by-side.py:28 + ... + (gdb) run numba_dpex/examples/debug/side-by-side.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], __main__::common_loop_body (param_a=0, param_b=0) at side-by-side.py:28 + 28 return result + (gdb) info locals + param_c = 10 + param_d = 0 + result = 10 + +It prints values of ``param_c`` and ``param_d``. + +Debug session with :samp:`NUMBA_EXTEND_VARIABLE_LIFETIMES=0`: + +.. code-block:: shell-session + :emphasize-lines: 3, 10-12 + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 0 + (gdb) break side-by-side.py:28 + ... + (gdb) run numba_dpex/examples/debug/side-by-side.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lanes [0-7], __main__::common_loop_body (param_a=0, param_b=0) at side-by-side.py:28 + 28 return result + (gdb) info locals + param_c = 0 + param_d = 0 + result = 10 + +.. _example-NUMBA_DUMP_ANNOTATION: + +Example 2 - Using ``NUMBA_DUMP_ANNOTATION`` +``````````````````````````````````````````` + +Source code :file:`numba_dpex/examples/debug/sum_local_vars.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/sum_local_vars.py + :pyobject: data_parallel_sum + :linenos: + :lineno-match: + +Run this code with environment variable :samp:`NUMBA_DUMP_ANNOTATION=1` and it +will show where numba inserts `del` for variables. + +.. code-block:: + :linenos: + :emphasize-lines: 28 + + -----------------------------------ANNOTATION----------------------------------- + # File: numba_dpex/examples/debug/sum_local_vars.py + # --- LINE 20 --- + + @numba_dpex.kernel(debug=True) + + # --- LINE 21 --- + + def data_parallel_sum(a, b, c): + + # --- LINE 22 --- + # label 0 + # a = arg(0, name=a) :: array(float32, 1d, C) + # b = arg(1, name=b) :: array(float32, 1d, C) + # c = arg(2, name=c) :: array(float32, 1d, C) + # $2load_global.0 = global(dpex: ) :: Module() + # $4load_method.1 = getattr(value=$2load_global.0, attr=get_global_id) :: Function() + # del $2load_global.0 + # $const6.2 = const(int, 0) :: Literal[int](0) + # i = call $4load_method.1($const6.2, func=$4load_method.1, args=[Var($const6.2, sum_local_vars.py:22)], kws=(), vararg=None, target=None) :: (uint32,) -> int64 + # del $const6.2 + # del $4load_method.1 + + i = dpex.get_global_id(0) + + # --- LINE 23 --- + # $16binary_subscr.6 = getitem(value=a, index=i, fn=) :: float32 + # del a + # $const18.7 = const(float, 2.5) :: float64 + # l1 = $16binary_subscr.6 + $const18.7 :: float64 + # del $const18.7 + # del $16binary_subscr.6 + + l1 = a[i] + 2.5 + + # --- LINE 24 --- + # $28binary_subscr.11 = getitem(value=b, index=i, fn=) :: float32 + # del b + # $const30.12 = const(float, 0.3) :: float64 + # l2 = $28binary_subscr.11 * $const30.12 :: float64 + # del $const30.12 + # del $28binary_subscr.11 + + l2 = b[i] * 0.3 + + # --- LINE 25 --- + # $40binary_add.16 = l1 + l2 :: float64 + # del l2 + # del l1 + # c[i] = $40binary_add.16 :: (array(float32, 1d, C), int64, float64) -> none + # del i + # del c + # del $40binary_add.16 + # $const48.19 = const(NoneType, None) :: none + # $50return_value.20 = cast(value=$const48.19) :: none + # del $const48.19 + # return $50return_value.20 + + c[i] = l1 + l2 + +I.e. in `LINE 23` variable `a` used the last time and numba inserts `del a` as +shown in annotated code in line 28. It means you will see value 0 for the +variable `a` when you set breakpoint at `LINE 24`. + +As a workaround you can expand lifetime of the variable by using it (i.e. +passing to dummy function `revive()`) at the end of the function. So numba will +not insert `del a` until the end of the function. + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/sum_local_vars_revive.py + :lines: 5- + :linenos: + :lineno-match: + +.. code-block:: + :linenos: + :emphasize-lines: 59 + + -----------------------------------ANNOTATION----------------------------------- + # File: numba_dpex/examples/debug/sum_local_vars_revive.py + # --- LINE 24 --- + + @numba_dpex.kernel(debug=True) + + # --- LINE 25 --- + + def data_parallel_sum(a, b, c): + + # --- LINE 26 --- + # label 0 + # a = arg(0, name=a) :: array(float32, 1d, C) + # b = arg(1, name=b) :: array(float32, 1d, C) + # c = arg(2, name=c) :: array(float32, 1d, C) + # $2load_global.0 = global(dpex: ) :: Module() + # $4load_method.1 = getattr(value=$2load_global.0, attr=get_global_id) :: Function() + # del $2load_global.0 + # $const6.2 = const(int, 0) :: Literal[int](0) + # i = call $4load_method.1($const6.2, func=$4load_method.1, args=[Var($const6.2, sum_local_vars_revive.py:26)], kws=(), vararg=None, target=None) :: (uint32,) -> int64 + # del $const6.2 + # del $4load_method.1 + + i = dpex.get_global_id(0) + + # --- LINE 27 --- + # $16binary_subscr.6 = getitem(value=a, index=i, fn=) :: float32 + # $const18.7 = const(float, 2.5) :: float64 + # l1 = $16binary_subscr.6 + $const18.7 :: float64 + # del $const18.7 + # del $16binary_subscr.6 + + l1 = a[i] + 2.5 + + # --- LINE 28 --- + # $28binary_subscr.11 = getitem(value=b, index=i, fn=) :: float32 + # del b + # $const30.12 = const(float, 0.3) :: float64 + # l2 = $28binary_subscr.11 * $const30.12 :: float64 + # del $const30.12 + # del $28binary_subscr.11 + + l2 = b[i] * 0.3 + + # --- LINE 29 --- + # $40binary_add.16 = l1 + l2 :: float64 + # del l2 + # del l1 + # c[i] = $40binary_add.16 :: (array(float32, 1d, C), int64, float64) -> none + # del i + # del c + # del $40binary_add.16 + + c[i] = l1 + l2 + + # --- LINE 30 --- + # $48load_global.19 = global(revive: ) :: Function() + # $52call_function.21 = call $48load_global.19(a, func=$48load_global.19, args=[Var(a, sum_local_vars_revive.py:26)], kws=(), vararg=None, target=None) :: (array(float32, 1d, C),) -> array(float32, 1d, C) + # del a + # del $52call_function.21 + # del $48load_global.19 + # $const56.22 = const(NoneType, None) :: none + # $58return_value.23 = cast(value=$const56.22) :: none + # del $const56.22 + # return $58return_value.23 + + revive(a) # pass variable to dummy function + +Run with environment variables :samp:`NUMBA_DUMP_ANNOTATION=1` and +:samp:`NUMBA_EXTEND_VARIABLE_LIFETIMES=1`. +It will show that numba inserts `del` for variables at the end of the block: + +.. code-block:: + :linenos: + :emphasize-lines: 11-25 + + -----------------------------------ANNOTATION----------------------------------- + # File: numba_dpex/examples/debug/sum_local_vars.py + ... + def data_parallel_sum(a, b, c): + ... + # --- LINE 26 --- + # $40binary_add.16 = l1 + l2 :: float64 + # c[i] = $40binary_add.16 :: (array(float32, 1d, C), int64, float64) -> none + # $const48.19 = const(NoneType, None) :: none + # $50return_value.20 = cast(value=$const48.19) :: none + # del $2load_global.0 + # del $const6.2 + # del $4load_method.1 + # del a + # del $const18.7 + # del $16binary_subscr.6 + # del b + # del $const30.12 + # del $28binary_subscr.11 + # del l2 + # del l1 + # del i + # del c + # del $40binary_add.16 + # del $const48.19 + # return $50return_value.20 + + c[i] = l1 + l2 + + +Example 3 - Using ``info locals`` +````````````````````````````````` + +Source code :file:`sum_local_vars.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/sum_local_vars.py + :lines: 5- + :linenos: + :lineno-match: + +Run the debugger with ``NUMBA_OPT=0``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 1-6 + +Run the ``info locals`` command. The sample output on "no optimization" level ``NUMBA_OPT=0`` is as follows: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 8-48 + :emphasize-lines: 1-16, 24-39 + +Since the debugger does not hit a line with the target variable ``l1``, the value equals 0. The true value of the variable ``l1`` is shown after stepping to line 22. + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 49-66 + :emphasize-lines: 1-16 + +When the debugger hits the last line of the kernel, ``info locals`` command returns all the local variables with their values. + +.. _`Numba documentation`: https://numba.readthedocs.io/en/stable/reference/envvars.html?#envvar-NUMBA_OPT diff --git a/pull/1473/_sources/user_guide/debugging/numba-0.55.rst.txt b/pull/1473/_sources/user_guide/debugging/numba-0.55.rst.txt new file mode 100644 index 0000000000..846a37472f --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/numba-0.55.rst.txt @@ -0,0 +1,73 @@ +.. include:: ./../../ext_links.txt + +Debugging Features in Numba 0.55 +================================ + +Numba 0.55 enables following features: + +Added ``info args`` +------------------- + +See :ref:`info-args`. +In previous versions ``info args`` always returns ``No arguments.``. + +Extended ``info locals`` +------------------------ + +See :ref:`info-locals`. + +Breakpoint with condition by function argument +---------------------------------------------- + +Test :file:`numba_dpex/tests/debugging/test_breakpoints.py:test_breakpoint_with_condition_by_function_argument`. + +When set breakpoint on the function or the first line of the function +than ``info locals`` and ``info args`` provide correct values. +It makes it posible to use breakpoint with condition by function argument. + +Example +``````` + +Source code :file:`numba_dpex/examples/debug/side-by-side.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 2 + +Set breakpoint with condition by function argument: + +.. code-block:: shell-session + :emphasize-lines: 3 + + $ NUMBA_OPT=0 gdb-oneapi -q python + ... + (gdb) break side-by-side.py:25 if param_a == 3 + ... + (gdb) run numba_dpex/examples/debug/side-by-side.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lane 3, __main__::common_loop_body (param_a=3, param_b=3) at side-by-side.py:25 + 25 param_c = param_a + 10 # Set breakpoint here + (gdb) print param_a + $1 = 3 + +Added ``NUMBA_EXTEND_VARIABLE_LIFETIMES`` +----------------------------------------- + +See :ref:`local-variables-lifetime`. + +:samp:``NUMBA_EXTEND_VARIABLE_LIFETIMES=1`` works together with +:samp:``NUMBA_DUMP_ANNOTATION=1``. + +See :ref:`example-NUMBA_DUMP_ANNOTATION`. + +Displaying Complex Data Types +----------------------------- + +Numba 0.55 improves displaying of complex data types like arrays. +It makes it possible to access ``data`` in arrays. +It is possible to get array values by commands like :samp:``x/10f array.data`` and +:samp:``print array.data[5]``. + +See :ref:`print` and :ref:`whatis` diff --git a/pull/1473/_sources/user_guide/debugging/set_up_machine.rst.txt b/pull/1473/_sources/user_guide/debugging/set_up_machine.rst.txt new file mode 100644 index 0000000000..a42666859c --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/set_up_machine.rst.txt @@ -0,0 +1,99 @@ +.. include:: ./../../ext_links.txt + +Set up the machine for debugging +==================================== + +Graphics driver +--------------- + +Install drivers using the following guides: + + - `Intel® GPGPU driver installation guide`_ + - `Intel® oneAPI GPU driver installation guide`_ + +.. _Intel® GPGPU driver installation guide: https://dgpu-docs.intel.com/installation-guides/index.html +.. _Intel® oneAPI GPU driver installation guide: + https://www.intel.com/content/www/us/en/docs/oneapi/installation-guide-linux/current/install-intel-gpu-drivers.html + +The user should be in the "video" group (on Ubuntu* 18, Fedora* 30, and SLES* 15 +SP1) or "render" group (on Ubuntu* 19 and higher, CentOS* 8, and Fedora* 31). An +administrator with sudo or root privileges can change the group owner of +`/dev/dri/renderD*` and `/dev/dri/card*` to a group ID used by your user base: + +.. code-block:: bash + + sudo usermod -a -G video + +.. _NEO-driver: + +NEO driver +---------- + +NEO driver `21.15.19533` or higher is required to make the debugger work correctly. + +1) Download the driver from `GitHub `_. + +2) Install the NEO driver on the system or locally. + + * To install the driver on the system, use the command: + + .. code-block:: bash + + sudo dpkg -i *.deb + + * To install the driver locally: + + 1) Add the path to NEO files in `LD_LIBRARY_PATH`: + + .. code-block:: bash + + cd /path/to/my/neo + for file in `ls *.deb`; do dpkg -x $file .; done + export MY_ACTIVE_NEO=/path/to/my/neo/usr/local/lib + export LD_LIBRARY_PATH=${MY_ACTIVE_NEO}:${MY_ACTIVE_NEO}/intel-opencl:$LD_LIBRARY_PATH + + 2) Add environment variables to change the behavior of the Installable Client Driver (ICD). + ICD uses the system implementation for OpenCL™ by default. To install the driver locally, add all needed from "/etc/OpenCL/vendors/" and custom to `OCL_ICD_FILENAMES`. + To overwrite the default behavior, use :samp:`export OCL_ICD_VENDORS=`: + + .. code-block:: bash + + export OCL_ICD_FILENAMES=/path/to/my/neo/usr/local/lib/intel-opencl/libigdrcl.so:/optional/from/vendors/libintelocl.so + export OCL_ICD_VENDORS= + +See also: + + - `Intel(R) Graphics Compute Runtime for oneAPI Level Zero and OpenCL(TM) Driver `_ + - `Intel(R) Graphics Compute Runtime Releases `_ + - `OpenCL ICD Loader `_ + + +.. _debugging-machine-dcd-driver: + +Debug companion driver (DCD) +---------------------------- + +1) To install the DCD from oneAPI into the system, use the following command: + + .. code-block:: bash + + sudo dpkg -i /path/to/oneapi/debugger/latest/igfxdcd-*-Linux.deb + +2) Activate the driver: + + .. code-block:: bash + + sudo modinfo igfxdcd + +Remove the driver from the system if you want to install a different version: + +.. code-block:: bash + + sudo dpkg -r igfxdcd + +If you are installing DCD for the first time, create keys. For details, see the link at the end of this page. + +See also: + + - `Get Started with Intel® Distribution for GDB* on Linux* OS Host `_ + - `Public signature key `_ diff --git a/pull/1473/_sources/user_guide/debugging/stepping.rst.txt b/pull/1473/_sources/user_guide/debugging/stepping.rst.txt new file mode 100644 index 0000000000..a2b9127776 --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/stepping.rst.txt @@ -0,0 +1,77 @@ +.. include:: ./../../ext_links.txt + +Stepping +======== + +Stepping allows you to go through the program by lines of source code or by +machine instructions. + +Consider the following examples. + +``numba_dpex/examples/debug/simple_sum.py``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_sum.py + :lines: 5- + :linenos: + :lineno-match: + +Example with a nested function ``numba_dpex/examples/debug/simple_dpex_func.py``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_dpex_func.py + :lines: 5- + :linenos: + :lineno-match: + + +``step`` +-------- + +Run the debugger and use the following commands: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/step_sum + :language: shell-session + :emphasize-lines: 8-13 + +You can use stepping to switch to a nested function. See the example below: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/step_dpex_func + :language: shell-session + :emphasize-lines: 8-14 + +``stepi`` +--------- + +The command allows you to move forward by machine instructions. The example uses an additional command ``x/i $pc``, which prints the instruction to be executed. + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/stepi + :language: shell-session + :emphasize-lines: 8-13 + +``next`` +-------- + +The command has stepping-like behavior, but it skips nested functions. + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/next + :language: shell-session + :emphasize-lines: 8-14 + +.. _single_stepping: + +``set scheduler-locking step`` +------------------------------ + +The first line of the kernel and functions is debugged twice. This happens +because you are debugging a multi-threaded program, so multiple events may be +received from different threads. This is the default behavior, but you can +configure it for more efficient debugging. To ensure the current thread executes +a single line without interference, set the scheduler-locking setting to `on` or +`step`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/sheduler_locking + :language: shell-session + :emphasize-lines: 8-13 + +See also: + +- `Continuing and Stepping in GDB* `_ diff --git a/pull/1473/_sources/user_guide/debugging/symbols.rst.txt b/pull/1473/_sources/user_guide/debugging/symbols.rst.txt new file mode 100644 index 0000000000..0586ec9c7b --- /dev/null +++ b/pull/1473/_sources/user_guide/debugging/symbols.rst.txt @@ -0,0 +1,88 @@ +.. include:: ./../../ext_links.txt + +Examining the Symbol Table +========================== + +See `GDB* documentation `_. + +``info functions`` +------------------ + +At least following syntax is supported: + +.. code-block:: bash + + info functions + info functions [regexp] + +.. note:: + + Running the ``info functions`` command without arguments may produce a lot of output + as the list of all functions in all loaded shared libraries is typically very long. + +Example +``````` + +Source file ``numba_dpex/examples/debug/simple_sum.py``: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/simple_sum.py + :lines: 5- + :linenos: + :lineno-match: + +Output of the debug session: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/info_func + :language: shell-session + :emphasize-lines: 5-9 + +.. _whatis: + +``whatis [arg]`` and ``ptype [arg]`` +------------------------------------ + +To print the type of a variable, run the ``ptype `` or ``whatis `` commands: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/commands/docs/local_variables_0 + :language: shell-session + :lines: 73-81 + :emphasize-lines: 1-6 + +Example - Complex Data Types +```````````````````````````` + +Source code :file:`numba_dpex/examples/debug/side-by-side-2.py`: + +.. literalinclude:: ./../../../../numba_dpex/examples/debug/side-by-side-2.py + :pyobject: common_loop_body + :linenos: + :lineno-match: + :emphasize-lines: 6 + +Debug session: + +.. code-block:: shell-session + :emphasize-lines: 9- + + $ gdb-oneapi -q python + ... + (gdb) set environment NUMBA_OPT 0 + (gdb) set environment NUMBA_EXTEND_VARIABLE_LIFETIMES 1 + (gdb) break side-by-side-2.py:29 if param_a == 5 + ... + (gdb) run numba_dpex/examples/debug/side-by-side-2.py --api=numba-dpex-kernel + ... + Thread 2.1 hit Breakpoint 1, with SIMD lane 5, __main__::common_loop_body (i=5, a=..., b=...) at side-by-side-2.py:29 + 29 result = param_c + param_d + (gdb) ptype a + type = struct array(float32, 1d, C) ({float addrspace(1)*, float addrspace(1)*, i64, i64, float addrspace(1)*, [1 x i64], [1 x i64]}) { + float *meminfo; + float *parent; + int64 nitems; + int64 itemsize; + float *data; + i64 shape[1]; + i64 strides[1]; + } + (gdb) whatis a + type = array(float32, 1d, C) ({float addrspace(1)*, float addrspace(1)*, i64, i64, float addrspace(1)*, [1 x i64], [1 x i64]}) diff --git a/pull/1473/_sources/user_guide/index.rst.txt b/pull/1473/_sources/user_guide/index.rst.txt new file mode 100644 index 0000000000..46efb768de --- /dev/null +++ b/pull/1473/_sources/user_guide/index.rst.txt @@ -0,0 +1,12 @@ +.. _index: +.. include:: ./../ext_links.txt + +Tutorials +========= + +.. toctree:: + :maxdepth: 2 + + kernel_programming/index + debugging/index + config diff --git a/pull/1473/_sources/user_guide/kernel_programming/call-kernel-async.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/call-kernel-async.rst.txt new file mode 100644 index 0000000000..b3a657890d --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/call-kernel-async.rst.txt @@ -0,0 +1,4 @@ +.. _launching-an-async-kernel: + +Async kernel execution +====================== diff --git a/pull/1473/_sources/user_guide/kernel_programming/call-kernel.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/call-kernel.rst.txt new file mode 100644 index 0000000000..2655027460 --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/call-kernel.rst.txt @@ -0,0 +1,117 @@ +.. _launching-a-kernel: + +Launching a kernel +================== + +A ``kernel`` decorated kapi function produces a ``KernelDispatcher`` object that +is a type of a Numba* `Dispatcher`_ object. However, unlike regular Numba* +Dispatcher objects a ``KernelDispatcher`` object cannot be directly invoked from +either CPython or another compiled Numba* ``jit`` function. To invoke a +``kernel`` decorated function, a programmer has to use the +:func:`numba_dpex.core.kernel_launcher.call_kernel` function. + +To invoke a ``KernelDispatcher`` the ``call_kernel`` function requires three +things: the ``KernelDispatcher`` object, the ``Range`` or ``NdRange`` object +over which the kernel is to be executed, and the list of arguments to be passed +to the compiled kernel. Once called with the necessary arguments, the +``call_kernel`` function does the following main things: + +- Compiles the ``KernelDispatcher`` object specializing it for the provided + argument types. + +- `Unboxes`_ the kernel arguments by converting CPython objects into Numba* or + numba-dpex objects. + +- Infer the execution queue on which to submit the kernel from the provided + kernel arguments. (TODO: Refer compute follows data.) + +- Submits the kernel to the execution queue. + +- Waits for the execution completion, before returning control back to the + caller. + +.. important:: + Programmers should note the following two things when defining the global or + local range to launch a kernel. + + * Numba-dpex currently limits the maximum allowed global range size to + ``2^31-1``. It is due to the capabilities of current OpenCL GPU backends + that generally do not support more than 32-bit global range sizes. A + kernel requesting a larger global range than that will not execute and a + ``dpctl._sycl_queue.SyclKernelSubmitError`` will get raised. + + The Intel dpcpp SYCL compiler does handle greater than 32-bit global + ranges for GPU backends by wrapping the kernel in a new kernel that has + each work-item perform multiple invocations of the original kernel in a + 32-bit global range. Such a feature is not yet available in numba-dpex. + + * When launching an nd-range kernel, if the number of work-items for a + particular dimension of a work-group exceeds the maximum device + capability, it can result in undefined behavior. + + The maximum allowed work-items for a device can be queried programmatically + as shown in :ref:`ex_max_work_item`. + + .. code-block:: python + :linenos: + :caption: **Example:** Query maximum number of work-items for a device + :name: ex_max_work_item + + import dpctl + import math + + d = dpctl.SyclDevice("gpu") + d.print_device_info() + + max_num_work_items = ( + d.max_work_group_size + * d.max_work_item_sizes1d[0] + * d.max_work_item_sizes2d[0] + * d.max_work_item_sizes3d[0] + ) + print(max_num_work_items, f"(2^{int(math.log(max_num_work_items, 2))})") + + cpud = dpctl.SyclDevice("cpu") + cpud.print_device_info() + + max_num_work_items_cpu = ( + cpud.max_work_group_size + * cpud.max_work_item_sizes1d[0] + * cpud.max_work_item_sizes2d[0] + * cpud.max_work_item_sizes3d[0] + ) + print(max_num_work_items_cpu, f"(2^{int(math.log(max_num_work_items_cpu, 2))})") + + The output for :ref:`ex_max_work_item` on a system with an Intel Gen9 integrated + graphics processor and a 9th Generation Coffee Lake CPU is shown in + :ref:`ex_max_work_item_output`. + + .. code-block:: bash + :caption: **OUTPUT:** Query maximum number of work-items for a device + :name: ex_max_work_item_output + + Name Intel(R) UHD Graphics 630 [0x3e98] + Driver version 1.3.24595 + Vendor Intel(R) Corporation + Filter string level_zero:gpu:0 + + 4294967296 (2^32) + Name Intel(R) Core(TM) i7-9700 CPU @ 3.00GHz + Driver version 2023.16.12.0.12_195853.xmain-hotfix + Vendor Intel(R) Corporation + Filter string opencl:cpu:0 + + 4503599627370496 (2^52) + + +The ``call_kernel`` function can be invoked both from CPython and from another +Numba* compiled function. Note that the ``call_kernel`` function supports only +synchronous execution of kernel and the ``call_kernel_async`` function should be +used for asynchronous mode of kernel execution (refer +:ref:`launching-an-async-kernel`). + + +.. seealso:: + + Refer the API documentation for + :func:`numba_dpex.core.kernel_launcher.call_kernel` for more details. diff --git a/pull/1473/_sources/user_guide/kernel_programming/device-functions.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/device-functions.rst.txt new file mode 100644 index 0000000000..b9dd914a0a --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/device-functions.rst.txt @@ -0,0 +1,86 @@ +Numba-dpex provides a decorator to express auxiliary device-only functions that +can be called from a kernel or another device function, but are not callable +from the host. This decorator :func:`numba_dpex.core.decorators.device_func` has +no direct analogue in SYCL and primarily is provided to help programmers make +their kapi applications modular. :ref:`ex_device_func1` shows a simple usage of +the ``device_func`` decorator. + +.. code-block:: python + :linenos: + :caption: **Example:** Basic usage of device_func + :name: ex_device_func1 + + import dpnp + + import numba_dpex as dpex + from numba_dpex import kernel_api as kapi + + # Array size + N = 10 + + + @dpex.device_func + def a_device_function(a): + """A device callable function that can be invoked from a kernel or + another device function. + """ + return a + 1 + + + @dpex.kernel + def a_kernel_function(item: kapi.Item, a, b): + """Demonstrates calling a device function from a kernel.""" + i = item.get_id(0) + b[i] = a_device_function(a[i]) + + + N = 16 + a = dpnp.ones(N, dtype=dpnp.int32) + b = dpnp.zeros(N, dtype=dpnp.int32) + + dpex.call_kernel(a_kernel_function, dpex.Range(N), a, b) + + +.. code-block:: python + :linenos: + :caption: **Example:** Using kapi functionalities in a device_func + :name: ex_device_func2 + + import dpnp + + import numba_dpex as dpex + from numba_dpex import kernel_api as kapi + + + @dpex.device_func + def increment_value(nd_item: kapi.NdItem, a): + """Demonstrates the usage of group_barrier and NdItem usage in a + device_func. + """ + i = nd_item.get_global_id(0) + + a[i] += 1 + kapi.group_barrier(nd_item.get_group(), kapi.MemoryScope.DEVICE) + + if i == 0: + for idx in range(1, a.size): + a[0] += a[idx] + + + @dpex.kernel + def another_kernel(nd_item: kapi.NdItem, a): + """The kernel does everything by calling a device_func.""" + increment_value(nd_item, a) + + + N = 16 + b = dpnp.ones(N, dtype=dpnp.int32) + + dpex.call_kernel(another_kernel, dpex.NdRange((N,), (N,)), b) + + +A device function does not require the first argument to be an index space id +class, and unlike a kernel function a device function is allowed to return a +value. All kapi functionality can be used in a ``device_func`` decorated +function and at compilation stage numba-dpex will attempt to inline a +``device_func`` into the kernel where it is used. diff --git a/pull/1473/_sources/user_guide/kernel_programming/index.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/index.rst.txt new file mode 100644 index 0000000000..816214b1a7 --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/index.rst.txt @@ -0,0 +1,166 @@ +.. _kernel-programming-guide: +.. include:: ./../../ext_links.txt + +Kernel Programming +################## + +The tutorial covers the numba-dpex kernel programming API (kapi) and introduces +the concepts needed to write data-parallel kernels in numba-dpex. + + +.. Preliminary concepts +.. -------------------- + +.. Data parallelism +.. ++++++++++++++++ + +.. Single Program Multiple Data +.. ++++++++++++++++++++++++++++ + +.. Range v/s Nd-Range Kernels +.. ++++++++++++++++++++++++++ + +.. Work items and Work groups +.. ++++++++++++++++++++++++++ + +Core concepts +************* + +Writing a *range* kernel +======================== + +.. include:: ./writing-range-kernel.rst + +Writing an *nd-range* kernel +============================ + +.. include:: ./writing-ndrange-kernel.rst + +.. Launching a kernel +.. ================== + +.. include:: ./call-kernel.rst + +The ``device_func`` decorator +============================= + +.. include:: ./device-functions.rst + + +Supported types of kernel argument +================================== + +A kapi kernel function can have both array and scalar arguments. At least one of +the argument to every kernel function has to be an array. The requirement is +enforced so that a execution queue can be inferred at the kernel launch stage. +An array type argument is passed as a reference to the kernel and all scalar +arguments are passed by value. + +Supported array types +--------------------- +- `dpctl.tensor.usm_ndarray`_ : A SYCL-based Python Array API complaint tensor. +- `dpnp.ndarray`_ : A ``numpy.ndarray``-like array container that supports SYCL USM memory allocation. + +Scalar types +------------ + +Scalar values can be passed to a kernel function either using the default Python +scalar type or as explicit NumPy or dpnp data type objects. +:ref:`ex_scalar_kernel_arg_ty` shows the two possible ways of defining a scalar +type. In both scenarios, numba-dpex depends on the default Numba* type inferring +algorithm to determine the LLVM IR type of a Python object that represents a +scalar value. At the kernel submission stage the LLVM IR type is reinterpreted +as a C++11 type to interoperate with the underlying SYCL runtime. + +.. code-block:: python + :caption: **Example:** Ways of defining a scalar kernel argument + :name: ex_scalar_kernel_arg_ty + + import dpnp + + a = 1 + b = dpnp.dtype("int32").type(1) + + print(type(a)) + print(type(b)) + +.. code-block:: bash + :caption: **Output:** Ways of defining a scalar kernel argument + :name: ex_scalar_kernel_arg_ty_output + + + + +The following scalar types are currently supported as arguments of a numba-dpex +kernel function: + +- ``int`` +- ``float`` +- ``complex`` +- ``numpy.int32`` +- ``numpy.uint32`` +- ``numpy.int64`` +- ``numpy.uint32`` +- ``numpy.float32`` +- ``numpy.float64`` + +.. important:: + + The Numba* type inferring algorithm by default infers a native Python + scalar type to be a 64-bit value. The algorithm is defined that way to be + consistent with the default CPython behavior. The default inferred 64-bit + type can cause compilation failures on platforms that do not have native + 64-bit floating point support. Another potential fallout of the default + 64-bit type inference can be when a narrower width type is required by a + specific kernel. To avoid these issues, users are advised to always use a + dpnp/numpy type object to explicitly define the type of a scalar value. + +DLPack support +-------------- +At this time direct support for the `DLPack`_ protocol is has not been added to +numba-dpex. To interoperate numba_dpex with other SYCL USM based libraries, +users should first convert their input tensor or ndarray object into either of +the two supported array types, both of which support DLPack. + + +Supported Python features +************************* + +Mathematical operations +======================= + +.. include:: ./math-functions.rst + +Operators +========= + +.. include:: ./operators.rst + +General Python features +======================= + +.. include:: ./supported-python-features.rst + + +Advanced concepts +***************** + +Local memory allocation +======================= + +Private memory allocation +========================= + +Group barrier synchronization +============================= + +Atomic operations +================= + +.. Async kernel execution +.. ====================== + +.. include:: ./call-kernel-async.rst + +Specializing a kernel or a device_func +====================================== diff --git a/pull/1473/_sources/user_guide/kernel_programming/math-functions.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/math-functions.rst.txt new file mode 100644 index 0000000000..f1ef2f512c --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/math-functions.rst.txt @@ -0,0 +1,24 @@ +.. include:: ./../../ext_links.txt + + +Scalar mathematical functions from the Python `math`_ module and the `dpnp`_ +library can be used inside a kernel function. During compilation the +mathematical functions get compiled into device-specific intrinsic instructions. + + +.. csv-table:: Current support matrix of ``math`` module functions + :file: ./math-functions.csv + :widths: 30, 70 + :header-rows: 1 + +.. caution:: + + The supported signature for some of the ``math`` module functions in the + compiled mode differs from CPython. The divergence in behavior is a known + issue. Please refer https://github.com/IntelPython/numba-dpex/issues/759 for + updates. + +.. csv-table:: Current support matrix of ``dpnp`` functions + :file: ./dpnp-ufuncs.csv + :widths: auto + :header-rows: 1 diff --git a/pull/1473/_sources/user_guide/kernel_programming/operators.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/operators.rst.txt new file mode 100644 index 0000000000..f07ef4c986 --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/operators.rst.txt @@ -0,0 +1,6 @@ +List of supported Python operators that can be used in a ``kernel`` or +``device_func`` decorated function. + +.. csv-table:: Current support matrix of Python operators + :file: ./operators.csv + :header-rows: 1 diff --git a/pull/1473/_sources/user_guide/kernel_programming/supported-python-features.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/supported-python-features.rst.txt new file mode 100644 index 0000000000..56b9c91aaa --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/supported-python-features.rst.txt @@ -0,0 +1,51 @@ + +A kapi function when run in the purely interpreted mode by the CPython +interpreter is a regular Python function, and as such in theory any Python +feature can be used in the body of the function. In practice, to be +JIT compilable and executable on a device only a subset of Python language +features are supported in a kapi function. The restriction stems from both +limitations in the Numba compiler tooling and also from the device-specific +calling convention and other restrictions applied by a device's ABI. + +This section provides a partial support matrix for Python features with respect +to their usage in a kapi function. + + +Built-in types +-------------- + +**Supported Types** + +- ``int`` +- ``float`` + +**Unsupported Types** + +- ``complex`` +- ``bool`` +- ``None`` +- ``tuple`` + +Built-in functions +------------------ + +The following built-in functions are supported: + +- ``abs()`` +- ``float`` +- ``int`` +- ``len()`` +- ``range()`` +- ``round()`` + +Unsupported Constructs +---------------------- + +The following Python constructs are **not supported**: + +- Exception handling (``try .. except``, ``try .. finally``) +- Context management (the ``with`` statement) +- Comprehensions (either list, dict, set or generator comprehensions) +- Generator (any ``yield`` statements) +- The ``raise`` statement +- The ``assert`` statement diff --git a/pull/1473/_sources/user_guide/kernel_programming/writing-ndrange-kernel.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/writing-ndrange-kernel.rst.txt new file mode 100644 index 0000000000..43632176d3 --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/writing-ndrange-kernel.rst.txt @@ -0,0 +1,129 @@ + +In a range kernel, the kernel execution is scheduled over a set of work-items +without any explicit grouping of the work-items. The basic form of parallelism +that can be expressed using a range kernel does not allow expressing any notion +of locality within the kernel. To get around that limitation, kapi provides a +second form of expressing a parallel kernel that is called an *nd-range* kernel. +An nd-range kernel represents a data-parallel execution of the kernel by a set +of explicitly defined groups of work-items. An individual group of work-items is +called a *work-group*. :ref:`ex_matmul_kernel` demonstrates an nd-range kernel +and some of the advanced features programmers can use in this type of kernel. + +.. code-block:: python + :linenos: + :caption: **Example:** Sliding window matrix multiplication as an nd-range kernel + :name: ex_matmul_kernel + + from numba_dpex import kernel_api as kapi + import numba_dpex as dpex + import numpy as np + import dpctl.tensor as dpt + + square_block_side = 2 + work_group_size = (square_block_side, square_block_side) + dtype = np.float32 + + + @dpex.kernel + def matmul( + nditem: kapi.NdItem, + X, # IN READ-ONLY (X_n_rows, n_cols) + y, # IN READ-ONLY (n_cols, y_n_rows), + X_slm, # SLM to store a sliding window over X + Y_slm, # SLM to store a sliding window over Y + result, # OUT (X_n_rows, y_n_rows) + ): + X_n_rows = X.shape[0] + Y_n_cols = y.shape[1] + n_cols = X.shape[1] + + result_row_idx = nditem.get_global_id(0) + result_col_idx = nditem.get_global_id(1) + + local_row_idx = nditem.get_local_id(0) + local_col_idx = nditem.get_local_id(1) + + n_blocks_for_cols = n_cols // square_block_side + if (n_cols % square_block_side) > 0: + n_blocks_for_cols += 1 + + output = dtype(0) + + gr = nditem.get_group() + + for block_idx in range(n_blocks_for_cols): + X_slm[local_row_idx, local_col_idx] = dtype(0) + Y_slm[local_row_idx, local_col_idx] = dtype(0) + if (result_row_idx < X_n_rows) and ( + (local_col_idx + (square_block_side * block_idx)) < n_cols + ): + X_slm[local_row_idx, local_col_idx] = X[ + result_row_idx, local_col_idx + (square_block_side * block_idx) + ] + + if (result_col_idx < Y_n_cols) and ( + (local_row_idx + (square_block_side * block_idx)) < n_cols + ): + Y_slm[local_row_idx, local_col_idx] = y[ + local_row_idx + (square_block_side * block_idx), result_col_idx + ] + + kapi.group_barrier(gr) + + for idx in range(square_block_side): + output += X_slm[local_row_idx, idx] * Y_slm[idx, local_col_idx] + + kapi.group_barrier(gr) + + if (result_row_idx < X_n_rows) and (result_col_idx < Y_n_cols): + result[result_row_idx, result_col_idx] = output + + + def _arange_reshaped(shape, dtype): + n_items = shape[0] * shape[1] + return np.arange(n_items, dtype=dtype).reshape(shape) + + + X = _arange_reshaped((5, 5), dtype) + Y = _arange_reshaped((5, 5), dtype) + X = dpt.asarray(X) + Y = dpt.asarray(Y) + device = X.device.sycl_device + result = dpt.zeros((5, 5), dtype, device=device) + X_slm = kapi.LocalAccessor(shape=work_group_size, dtype=dtype) + Y_slm = kapi.LocalAccessor(shape=work_group_size, dtype=dtype) + + dpex.call_kernel(matmul, kapi.NdRange((6, 6), (2, 2)), X, Y, X_slm, Y_slm, result) + + +When writing an nd-range kernel, a programmer defines a set of groups of +work-items instead of a flat execution range.There are several semantic rules +associated both with a work-group and the work-items in a work-group: + +- Each work-group gets executed in an arbitrary order by the underlying + runtime and programmers should not assume any implicit ordering. + +- Work-items in different wok-groups cannot communicate with each other except + via atomic operations on global memory. + +- Work-items within a work-group share a common memory region called + "shared local memory" (SLM). Depending on the device the SLM maybe mapped to a + dedicated fast memory. + +- Work-items in a work-group can synchronize using a + :func:`numba_dpex.kernel_api.group_barrier` operation that can additionally + guarantee memory consistency using a *work-group memory fence*. + +.. note:: + + The SYCL language provides additional features for work-items in a + work-group such as *group functions* that specify communication routines + across work-items and also implement patterns such as reduction and scan. + These features are not yet available in numba-dpex. + +An nd-range kernel needs to be launched with an instance of the +:py:class:`numba_dpex.kernel_api.NdRange` class and the first +argument to an nd-range kernel has to be an instance of +:py:class:`numba_dpex.kernel_api.NdItem`. Apart from the need to provide an +```NdItem`` parameter, the rest of the semantic rules that apply to a range +kernel also apply to an nd-range kernel. diff --git a/pull/1473/_sources/user_guide/kernel_programming/writing-range-kernel.rst.txt b/pull/1473/_sources/user_guide/kernel_programming/writing-range-kernel.rst.txt new file mode 100644 index 0000000000..70daf10975 --- /dev/null +++ b/pull/1473/_sources/user_guide/kernel_programming/writing-range-kernel.rst.txt @@ -0,0 +1,81 @@ +A *range* kernel represents the simplest form of parallelism that can be +expressed in numba-dpex using kapi. Such a kernel represents a data-parallel +execution over a set of work-items with each work-item representing a logical +thread of execution. :ref:`ex_vecadd_kernel` shows an example of a range kernel +written in numba-dpex. + +.. code-block:: python + :linenos: + :caption: **Example:** Vector addition using a range kernel + :name: ex_vecadd_kernel + :emphasize-lines: 9,17 + + import dpnp + import numba_dpex as dpex + from numba_dpex import kernel_api as kapi + + + # Data parallel kernel implementing vector sum + @dpex.kernel + def vecadd(item: kapi.Item, a, b, c): + i = item.get_id(0) + c[i] = a[i] + b[i] + + + N = 1024 + a = dpnp.ones(N) + b = dpnp.ones_like(a) + c = dpnp.zeros_like(a) + dpex.call_kernel(vecadd, kapi.Range(N), a, b, c) + +The highlighted lines in the example demonstrate the definition of the execution +range on **line 17** and extraction of every work-items' *id* or index position +via the ``item.get_id`` call on **line 10**. An execution range comprising of +1024 work-items is defined when calling the kernel and each work-item then +executes a single addition. + +There are a few semantic rules that have to be adhered to when writing a range +kernel: + +* Analogous to the API of SYCL a range kernel can execute only over a 1-, 2-, or + a 3-dimensional set of work-items. + +* Every range kernel requires its first argument to be an instance of the + :class:`numba_dpex.kernel_api.Item` class. The ``Item`` object is an + abstraction encapsulating the index position (id) of a single work-item in the + global execution range. The id will be a 1-, 2-, or a 3-tuple depending + the dimensionality of the execution range. + +* A range kernel cannot return any value. + + **Note** the rule is enforced only in + the compiled mode and not in the pure Python execution on a kapi kernel. + +* A kernel can accept both array and scalar arguments. Array arguments currently + can either be a ``dpnp.ndarray`` or a ``dpctl.tensor.usm_ndarray``. Scalar + values can be of any Python numeric type. Array arguments are passed by + reference, *i.e.*, changes to an array in a kernel are visible outside the + kernel. Scalar values are always passed by value. + +* At least one argument of a kernel should be an array. The requirement is so + that the kernel launcher (:func:`numba_dpex.core.kernel_launcher.call_kernel`) + can determine the execution queue on which to launch the kernel. Refer to the + :ref:`launching-a-kernel` section for more details. + +A range kernel has to be executed via the +:py:func:`numba_dpex.core.kernel_launcher.call_kernel` function by passing in +an instance of the :class:`numba_dpex.kernel_api.Range` class. Refer to the +:ref:`launching-a-kernel` section for more details on how to launch a range +kernel. + +A range kernel is meant to express a basic `parallel-for` calculation that is +ideally suited for embarrassingly parallel kernels such as element-wise +computations over n-dimensional arrays (ndarrays). The API for expressing a +range kernel does not allow advanced features such as synchronization of +work-items and fine-grained control over memory allocation on a device. For such +advanced features, an nd-range kernel should be used. + +.. seealso:: + Refer API documentation for :class:`numba_dpex.kernel_api.Range`, + :class:`numba_dpex.kernel_api.Item`, and + :func:`numba_dpex.core.kernel_launcher.call_kernel` for more details. diff --git a/pull/1473/_static/basic.css b/pull/1473/_static/basic.css new file mode 100644 index 0000000000..f316efcb47 --- /dev/null +++ b/pull/1473/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/pull/1473/_static/debug.css b/pull/1473/_static/debug.css new file mode 100644 index 0000000000..74d4aec33e --- /dev/null +++ b/pull/1473/_static/debug.css @@ -0,0 +1,69 @@ +/* + This CSS file should be overridden by the theme authors. It's + meant for debugging and developing the skeleton that this theme provides. +*/ +body { + font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, + "Apple Color Emoji", "Segoe UI Emoji"; + background: lavender; +} +.sb-announcement { + background: rgb(131, 131, 131); +} +.sb-announcement__inner { + background: black; + color: white; +} +.sb-header { + background: lightskyblue; +} +.sb-header__inner { + background: royalblue; + color: white; +} +.sb-header-secondary { + background: lightcyan; +} +.sb-header-secondary__inner { + background: cornflowerblue; + color: white; +} +.sb-sidebar-primary { + background: lightgreen; +} +.sb-main { + background: blanchedalmond; +} +.sb-main__inner { + background: antiquewhite; +} +.sb-header-article { + background: lightsteelblue; +} +.sb-article-container { + background: snow; +} +.sb-article-main { + background: white; +} +.sb-footer-article { + background: lightpink; +} +.sb-sidebar-secondary { + background: lightgoldenrodyellow; +} +.sb-footer-content { + background: plum; +} +.sb-footer-content__inner { + background: palevioletred; +} +.sb-footer { + background: pink; +} +.sb-footer__inner { + background: salmon; +} +.sb-article { + background: white; +} diff --git a/pull/1473/_static/doctools.js b/pull/1473/_static/doctools.js new file mode 100644 index 0000000000..4d67807d17 --- /dev/null +++ b/pull/1473/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/pull/1473/_static/documentation_options.js b/pull/1473/_static/documentation_options.js new file mode 100644 index 0000000000..0850fc6f18 --- /dev/null +++ b/pull/1473/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '0.23.0+6.g50e6393ee', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/pull/1473/_static/file.png b/pull/1473/_static/file.png new file mode 100644 index 0000000000..a858a410e4 Binary files /dev/null and b/pull/1473/_static/file.png differ diff --git a/pull/1473/_static/graphviz.css b/pull/1473/_static/graphviz.css new file mode 100644 index 0000000000..027576e34d --- /dev/null +++ b/pull/1473/_static/graphviz.css @@ -0,0 +1,19 @@ +/* + * graphviz.css + * ~~~~~~~~~~~~ + * + * Sphinx stylesheet -- graphviz extension. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +img.graphviz { + border: 0; + max-width: 100%; +} + +object.graphviz { + max-width: 100%; +} diff --git a/pull/1473/_static/language_data.js b/pull/1473/_static/language_data.js new file mode 100644 index 0000000000..367b8ed81b --- /dev/null +++ b/pull/1473/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/pull/1473/_static/minus.png b/pull/1473/_static/minus.png new file mode 100644 index 0000000000..d96755fdaf Binary files /dev/null and b/pull/1473/_static/minus.png differ diff --git a/pull/1473/_static/plus.png b/pull/1473/_static/plus.png new file mode 100644 index 0000000000..7107cec93a Binary files /dev/null and b/pull/1473/_static/plus.png differ diff --git a/pull/1473/_static/pygments.css b/pull/1473/_static/pygments.css new file mode 100644 index 0000000000..02b4b12812 --- /dev/null +++ b/pull/1473/_static/pygments.css @@ -0,0 +1,258 @@ +.highlight pre { line-height: 125%; } +.highlight td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #8f5902; font-style: italic } /* Comment */ +.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ +.highlight .g { color: #000000 } /* Generic */ +.highlight .k { color: #204a87; font-weight: bold } /* Keyword */ +.highlight .l { color: #000000 } /* Literal */ +.highlight .n { color: #000000 } /* Name */ +.highlight .o { color: #ce5c00; font-weight: bold } /* Operator */ +.highlight .x { color: #000000 } /* Other */ +.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ +.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */ +.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #a40000 } /* Generic.Deleted */ +.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ +.highlight .ges { color: #000000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #ef2929 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #000000; font-style: italic } /* Generic.Output */ +.highlight .gp { color: #8f5902 } /* Generic.Prompt */ +.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ +.highlight .kc { color: #204a87; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #204a87; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #204a87; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #204a87; font-weight: bold } /* Keyword.Pseudo */ +.highlight .kr { color: #204a87; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #204a87; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #000000 } /* Literal.Date */ +.highlight .m { color: #0000cf; font-weight: bold } /* Literal.Number */ +.highlight .s { color: #4e9a06 } /* Literal.String */ +.highlight .na { color: #c4a000 } /* Name.Attribute */ +.highlight .nb { color: #204a87 } /* Name.Builtin */ +.highlight .nc { color: #000000 } /* Name.Class */ +.highlight .no { color: #000000 } /* Name.Constant */ +.highlight .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #ce5c00 } /* Name.Entity */ +.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #000000 } /* Name.Function */ +.highlight .nl { color: #f57900 } /* Name.Label */ +.highlight .nn { color: #000000 } /* Name.Namespace */ +.highlight .nx { color: #000000 } /* Name.Other */ +.highlight .py { color: #000000 } /* Name.Property */ +.highlight .nt { color: #204a87; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #000000 } /* Name.Variable */ +.highlight .ow { color: #204a87; font-weight: bold } /* Operator.Word */ +.highlight .pm { color: #000000; font-weight: bold } /* Punctuation.Marker */ +.highlight .w { color: #f8f8f8 } /* Text.Whitespace */ +.highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */ +.highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */ +.highlight .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */ +.highlight .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */ +.highlight .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */ +.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ +.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ +.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ +.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ +.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ +.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ +.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ +.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ +.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ +.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ +.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ +.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ +.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #000000 } /* Name.Function.Magic */ +.highlight .vc { color: #000000 } /* Name.Variable.Class */ +.highlight .vg { color: #000000 } /* Name.Variable.Global */ +.highlight .vi { color: #000000 } /* Name.Variable.Instance */ +.highlight .vm { color: #000000 } /* Name.Variable.Magic */ +.highlight .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */ +@media not print { +body[data-theme="dark"] .highlight pre { line-height: 125%; } +body[data-theme="dark"] .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight .hll { background-color: #404040 } +body[data-theme="dark"] .highlight { background: #202020; color: #d0d0d0 } +body[data-theme="dark"] .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body[data-theme="dark"] .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body[data-theme="dark"] .highlight .esc { color: #d0d0d0 } /* Escape */ +body[data-theme="dark"] .highlight .g { color: #d0d0d0 } /* Generic */ +body[data-theme="dark"] .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body[data-theme="dark"] .highlight .l { color: #d0d0d0 } /* Literal */ +body[data-theme="dark"] .highlight .n { color: #d0d0d0 } /* Name */ +body[data-theme="dark"] .highlight .o { color: #d0d0d0 } /* Operator */ +body[data-theme="dark"] .highlight .x { color: #d0d0d0 } /* Other */ +body[data-theme="dark"] .highlight .p { color: #d0d0d0 } /* Punctuation */ +body[data-theme="dark"] .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body[data-theme="dark"] .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body[data-theme="dark"] .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body[data-theme="dark"] .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body[data-theme="dark"] .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body[data-theme="dark"] .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body[data-theme="dark"] .highlight .gd { color: #ff3a3a } /* Generic.Deleted */ +body[data-theme="dark"] .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body[data-theme="dark"] .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body[data-theme="dark"] .highlight .gr { color: #ff3a3a } /* Generic.Error */ +body[data-theme="dark"] .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body[data-theme="dark"] .highlight .gi { color: #589819 } /* Generic.Inserted */ +body[data-theme="dark"] .highlight .go { color: #cccccc } /* Generic.Output */ +body[data-theme="dark"] .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body[data-theme="dark"] .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body[data-theme="dark"] .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body[data-theme="dark"] .highlight .gt { color: #ff3a3a } /* Generic.Traceback */ +body[data-theme="dark"] .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body[data-theme="dark"] .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body[data-theme="dark"] .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body[data-theme="dark"] .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body[data-theme="dark"] .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body[data-theme="dark"] .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body[data-theme="dark"] .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body[data-theme="dark"] .highlight .m { color: #51b2fd } /* Literal.Number */ +body[data-theme="dark"] .highlight .s { color: #ed9d13 } /* Literal.String */ +body[data-theme="dark"] .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body[data-theme="dark"] .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body[data-theme="dark"] .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body[data-theme="dark"] .highlight .no { color: #40ffff } /* Name.Constant */ +body[data-theme="dark"] .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body[data-theme="dark"] .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body[data-theme="dark"] .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body[data-theme="dark"] .highlight .nf { color: #71adff } /* Name.Function */ +body[data-theme="dark"] .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body[data-theme="dark"] .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body[data-theme="dark"] .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body[data-theme="dark"] .highlight .py { color: #d0d0d0 } /* Name.Property */ +body[data-theme="dark"] .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body[data-theme="dark"] .highlight .nv { color: #40ffff } /* Name.Variable */ +body[data-theme="dark"] .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body[data-theme="dark"] .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body[data-theme="dark"] .highlight .w { color: #666666 } /* Text.Whitespace */ +body[data-theme="dark"] .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body[data-theme="dark"] .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body[data-theme="dark"] .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body[data-theme="dark"] .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body[data-theme="dark"] .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body[data-theme="dark"] .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body[data-theme="dark"] .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body[data-theme="dark"] .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body[data-theme="dark"] .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body[data-theme="dark"] .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body[data-theme="dark"] .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body[data-theme="dark"] .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body[data-theme="dark"] .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body[data-theme="dark"] .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body[data-theme="dark"] .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body[data-theme="dark"] .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body[data-theme="dark"] .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body[data-theme="dark"] .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body[data-theme="dark"] .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body[data-theme="dark"] .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body[data-theme="dark"] .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body[data-theme="dark"] .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body[data-theme="dark"] .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body[data-theme="dark"] .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body[data-theme="dark"] .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +@media (prefers-color-scheme: dark) { +body:not([data-theme="light"]) .highlight pre { line-height: 125%; } +body:not([data-theme="light"]) .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight .hll { background-color: #404040 } +body:not([data-theme="light"]) .highlight { background: #202020; color: #d0d0d0 } +body:not([data-theme="light"]) .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body:not([data-theme="light"]) .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body:not([data-theme="light"]) .highlight .esc { color: #d0d0d0 } /* Escape */ +body:not([data-theme="light"]) .highlight .g { color: #d0d0d0 } /* Generic */ +body:not([data-theme="light"]) .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body:not([data-theme="light"]) .highlight .l { color: #d0d0d0 } /* Literal */ +body:not([data-theme="light"]) .highlight .n { color: #d0d0d0 } /* Name */ +body:not([data-theme="light"]) .highlight .o { color: #d0d0d0 } /* Operator */ +body:not([data-theme="light"]) .highlight .x { color: #d0d0d0 } /* Other */ +body:not([data-theme="light"]) .highlight .p { color: #d0d0d0 } /* Punctuation */ +body:not([data-theme="light"]) .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body:not([data-theme="light"]) .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body:not([data-theme="light"]) .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body:not([data-theme="light"]) .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body:not([data-theme="light"]) .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body:not([data-theme="light"]) .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body:not([data-theme="light"]) .highlight .gd { color: #ff3a3a } /* Generic.Deleted */ +body:not([data-theme="light"]) .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body:not([data-theme="light"]) .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body:not([data-theme="light"]) .highlight .gr { color: #ff3a3a } /* Generic.Error */ +body:not([data-theme="light"]) .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body:not([data-theme="light"]) .highlight .gi { color: #589819 } /* Generic.Inserted */ +body:not([data-theme="light"]) .highlight .go { color: #cccccc } /* Generic.Output */ +body:not([data-theme="light"]) .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body:not([data-theme="light"]) .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body:not([data-theme="light"]) .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body:not([data-theme="light"]) .highlight .gt { color: #ff3a3a } /* Generic.Traceback */ +body:not([data-theme="light"]) .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body:not([data-theme="light"]) .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body:not([data-theme="light"]) .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body:not([data-theme="light"]) .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body:not([data-theme="light"]) .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body:not([data-theme="light"]) .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body:not([data-theme="light"]) .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body:not([data-theme="light"]) .highlight .m { color: #51b2fd } /* Literal.Number */ +body:not([data-theme="light"]) .highlight .s { color: #ed9d13 } /* Literal.String */ +body:not([data-theme="light"]) .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body:not([data-theme="light"]) .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body:not([data-theme="light"]) .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body:not([data-theme="light"]) .highlight .no { color: #40ffff } /* Name.Constant */ +body:not([data-theme="light"]) .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body:not([data-theme="light"]) .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body:not([data-theme="light"]) .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body:not([data-theme="light"]) .highlight .nf { color: #71adff } /* Name.Function */ +body:not([data-theme="light"]) .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body:not([data-theme="light"]) .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body:not([data-theme="light"]) .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body:not([data-theme="light"]) .highlight .py { color: #d0d0d0 } /* Name.Property */ +body:not([data-theme="light"]) .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body:not([data-theme="light"]) .highlight .nv { color: #40ffff } /* Name.Variable */ +body:not([data-theme="light"]) .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body:not([data-theme="light"]) .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body:not([data-theme="light"]) .highlight .w { color: #666666 } /* Text.Whitespace */ +body:not([data-theme="light"]) .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body:not([data-theme="light"]) .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body:not([data-theme="light"]) .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body:not([data-theme="light"]) .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body:not([data-theme="light"]) .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body:not([data-theme="light"]) .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body:not([data-theme="light"]) .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body:not([data-theme="light"]) .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body:not([data-theme="light"]) .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body:not([data-theme="light"]) .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body:not([data-theme="light"]) .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body:not([data-theme="light"]) .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body:not([data-theme="light"]) .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body:not([data-theme="light"]) .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body:not([data-theme="light"]) .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body:not([data-theme="light"]) .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body:not([data-theme="light"]) .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body:not([data-theme="light"]) .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body:not([data-theme="light"]) .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body:not([data-theme="light"]) .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body:not([data-theme="light"]) .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body:not([data-theme="light"]) .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body:not([data-theme="light"]) .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body:not([data-theme="light"]) .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body:not([data-theme="light"]) .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +} +} \ No newline at end of file diff --git a/pull/1473/_static/scripts/furo-extensions.js b/pull/1473/_static/scripts/furo-extensions.js new file mode 100644 index 0000000000..e69de29bb2 diff --git a/pull/1473/_static/scripts/furo.js b/pull/1473/_static/scripts/furo.js new file mode 100644 index 0000000000..0267c7e112 --- /dev/null +++ b/pull/1473/_static/scripts/furo.js @@ -0,0 +1,3 @@ +/*! For license information please see furo.js.LICENSE.txt */ +(()=>{var t={856:function(t,e,n){var o,r;r=void 0!==n.g?n.g:"undefined"!=typeof window?window:this,o=function(){return function(t){"use strict";var e={navClass:"active",contentClass:"active",nested:!1,nestedClass:"active",offset:0,reflow:!1,events:!0},n=function(t,e,n){if(n.settings.events){var o=new CustomEvent(t,{bubbles:!0,cancelable:!0,detail:n});e.dispatchEvent(o)}},o=function(t){var e=0;if(t.offsetParent)for(;t;)e+=t.offsetTop,t=t.offsetParent;return e>=0?e:0},r=function(t){t&&t.sort((function(t,e){return o(t.content)=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight,document.body.offsetHeight,document.documentElement.offsetHeight,document.body.clientHeight,document.documentElement.clientHeight)},l=function(t,e){var n=t[t.length-1];if(function(t,e){return!(!s()||!c(t.content,e,!0))}(n,e))return n;for(var o=t.length-1;o>=0;o--)if(c(t[o].content,e))return t[o]},a=function(t,e){if(e.nested&&t.parentNode){var n=t.parentNode.closest("li");n&&(n.classList.remove(e.nestedClass),a(n,e))}},i=function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.remove(e.navClass),t.content.classList.remove(e.contentClass),a(o,e),n("gumshoeDeactivate",o,{link:t.nav,content:t.content,settings:e}))}},u=function(t,e){if(e.nested){var n=t.parentNode.closest("li");n&&(n.classList.add(e.nestedClass),u(n,e))}};return function(o,c){var s,a,d,f,m,v={setup:function(){s=document.querySelectorAll(o),a=[],Array.prototype.forEach.call(s,(function(t){var e=document.getElementById(decodeURIComponent(t.hash.substr(1)));e&&a.push({nav:t,content:e})})),r(a)},detect:function(){var t=l(a,m);t?d&&t.content===d.content||(i(d,m),function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.add(e.navClass),t.content.classList.add(e.contentClass),u(o,e),n("gumshoeActivate",o,{link:t.nav,content:t.content,settings:e}))}}(t,m),d=t):d&&(i(d,m),d=null)}},h=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame(v.detect)},g=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame((function(){r(a),v.detect()}))};return v.destroy=function(){d&&i(d,m),t.removeEventListener("scroll",h,!1),m.reflow&&t.removeEventListener("resize",g,!1),a=null,s=null,d=null,f=null,m=null},m=function(){var t={};return Array.prototype.forEach.call(arguments,(function(e){for(var n in e){if(!e.hasOwnProperty(n))return;t[n]=e[n]}})),t}(e,c||{}),v.setup(),v.detect(),t.addEventListener("scroll",h,!1),m.reflow&&t.addEventListener("resize",g,!1),v}}(r)}.apply(e,[]),void 0===o||(t.exports=o)}},e={};function n(o){var r=e[o];if(void 0!==r)return r.exports;var c=e[o]={exports:{}};return t[o].call(c.exports,c,c.exports,n),c.exports}n.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return n.d(e,{a:e}),e},n.d=(t,e)=>{for(var o in e)n.o(e,o)&&!n.o(t,o)&&Object.defineProperty(t,o,{enumerable:!0,get:e[o]})},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(t){if("object"==typeof window)return window}}(),n.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e),(()=>{"use strict";var t=n(856),e=n.n(t),o=null,r=null,c=window.pageYOffset||document.documentElement.scrollTop;const s=64;function l(){const t=localStorage.getItem("theme")||"auto";var e;"light"!==(e=window.matchMedia("(prefers-color-scheme: dark)").matches?"auto"===t?"light":"light"==t?"dark":"auto":"auto"===t?"dark":"dark"==t?"light":"auto")&&"dark"!==e&&"auto"!==e&&(console.error(`Got invalid theme mode: ${e}. Resetting to auto.`),e="auto"),document.body.dataset.theme=e,localStorage.setItem("theme",e),console.log(`Changed to ${e} mode.`)}function a(){!function(){const t=document.getElementsByClassName("theme-toggle");Array.from(t).forEach((t=>{t.addEventListener("click",l)}))}(),function(){let t=0,e=!1;window.addEventListener("scroll",(function(n){t=window.scrollY,e||(window.requestAnimationFrame((function(){var n;n=t,0==Math.floor(r.getBoundingClientRect().top)?r.classList.add("scrolled"):r.classList.remove("scrolled"),function(t){tc&&document.documentElement.classList.remove("show-back-to-top"),c=t}(n),function(t){null!==o&&(0==t?o.scrollTo(0,0):Math.ceil(t)>=Math.floor(document.documentElement.scrollHeight-window.innerHeight)?o.scrollTo(0,o.scrollHeight):document.querySelector(".scroll-current"))}(n),e=!1})),e=!0)})),window.scroll()}(),null!==o&&new(e())(".toc-tree a",{reflow:!0,recursive:!0,navClass:"scroll-current",offset:()=>{let t=parseFloat(getComputedStyle(document.documentElement).fontSize);return r.getBoundingClientRect().height+2.5*t+1}})}document.addEventListener("DOMContentLoaded",(function(){document.body.parentNode.classList.remove("no-js"),r=document.querySelector("header"),o=document.querySelector(".toc-scroll"),a()}))})()})(); +//# sourceMappingURL=furo.js.map \ No newline at end of file diff --git a/pull/1473/_static/scripts/furo.js.LICENSE.txt b/pull/1473/_static/scripts/furo.js.LICENSE.txt new file mode 100644 index 0000000000..1632189c7e --- /dev/null +++ b/pull/1473/_static/scripts/furo.js.LICENSE.txt @@ -0,0 +1,7 @@ +/*! + * gumshoejs v5.1.2 (patched by @pradyunsg) + * A simple, framework-agnostic scrollspy script. + * (c) 2019 Chris Ferdinandi + * MIT License + * http://github.com/cferdinandi/gumshoe + */ diff --git a/pull/1473/_static/scripts/furo.js.map b/pull/1473/_static/scripts/furo.js.map new file mode 100644 index 0000000000..c3b37aaa94 --- /dev/null +++ b/pull/1473/_static/scripts/furo.js.map @@ -0,0 +1 @@ +{"version":3,"file":"scripts/furo.js","mappings":";iCAAA,MAQWA,SAWS,IAAX,EAAAC,EACH,EAAAA,EACkB,oBAAXC,OACLA,OACAC,KAbO,EAAF,WACP,OAaJ,SAAUD,GACR,aAMA,IAAIE,EAAW,CAEbC,SAAU,SACVC,aAAc,SAGdC,QAAQ,EACRC,YAAa,SAGbC,OAAQ,EACRC,QAAQ,EAGRC,QAAQ,GA6BNC,EAAY,SAAUC,EAAMC,EAAMC,GAEpC,GAAKA,EAAOC,SAASL,OAArB,CAGA,IAAIM,EAAQ,IAAIC,YAAYL,EAAM,CAChCM,SAAS,EACTC,YAAY,EACZL,OAAQA,IAIVD,EAAKO,cAAcJ,EAVgB,CAWrC,EAOIK,EAAe,SAAUR,GAC3B,IAAIS,EAAW,EACf,GAAIT,EAAKU,aACP,KAAOV,GACLS,GAAYT,EAAKW,UACjBX,EAAOA,EAAKU,aAGhB,OAAOD,GAAY,EAAIA,EAAW,CACpC,EAMIG,EAAe,SAAUC,GACvBA,GACFA,EAASC,MAAK,SAAUC,EAAOC,GAG7B,OAFcR,EAAaO,EAAME,SACnBT,EAAaQ,EAAMC,UACF,EACxB,CACT,GAEJ,EAwCIC,EAAW,SAAUlB,EAAME,EAAUiB,GACvC,IAAIC,EAASpB,EAAKqB,wBACd1B,EAnCU,SAAUO,GAExB,MAA+B,mBAApBA,EAASP,OACX2B,WAAWpB,EAASP,UAItB2B,WAAWpB,EAASP,OAC7B,CA2Be4B,CAAUrB,GACvB,OAAIiB,EAEAK,SAASJ,EAAOD,OAAQ,KACvB/B,EAAOqC,aAAeC,SAASC,gBAAgBC,cAG7CJ,SAASJ,EAAOS,IAAK,KAAOlC,CACrC,EAMImC,EAAa,WACf,OACEC,KAAKC,KAAK5C,EAAOqC,YAAcrC,EAAO6C,cAnCjCF,KAAKG,IACVR,SAASS,KAAKC,aACdV,SAASC,gBAAgBS,aACzBV,SAASS,KAAKE,aACdX,SAASC,gBAAgBU,aACzBX,SAASS,KAAKP,aACdF,SAASC,gBAAgBC,aAkC7B,EAmBIU,EAAY,SAAUzB,EAAUX,GAClC,IAAIqC,EAAO1B,EAASA,EAAS2B,OAAS,GACtC,GAbgB,SAAUC,EAAMvC,GAChC,SAAI4B,MAAgBZ,EAASuB,EAAKxB,QAASf,GAAU,GAEvD,CAUMwC,CAAYH,EAAMrC,GAAW,OAAOqC,EACxC,IAAK,IAAII,EAAI9B,EAAS2B,OAAS,EAAGG,GAAK,EAAGA,IACxC,GAAIzB,EAASL,EAAS8B,GAAG1B,QAASf,GAAW,OAAOW,EAAS8B,EAEjE,EAOIC,EAAmB,SAAUC,EAAK3C,GAEpC,GAAKA,EAAST,QAAWoD,EAAIC,WAA7B,CAGA,IAAIC,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASR,aAG7BkD,EAAiBG,EAAI7C,GAV0B,CAWjD,EAOIiD,EAAa,SAAUC,EAAOlD,GAEhC,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASX,UAC7B6D,EAAMnC,QAAQgC,UAAUC,OAAOhD,EAASV,cAGxCoD,EAAiBG,EAAI7C,GAGrBJ,EAAU,oBAAqBiD,EAAI,CACjCM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,EAOIoD,EAAiB,SAAUT,EAAK3C,GAElC,GAAKA,EAAST,OAAd,CAGA,IAAIsD,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASR,aAG1B4D,EAAeP,EAAI7C,GAVS,CAW9B,EA6LA,OA1JkB,SAAUsD,EAAUC,GAKpC,IACIC,EAAU7C,EAAU8C,EAASC,EAAS1D,EADtC2D,EAAa,CAUjBA,MAAmB,WAEjBH,EAAWhC,SAASoC,iBAAiBN,GAGrC3C,EAAW,GAGXkD,MAAMC,UAAUC,QAAQC,KAAKR,GAAU,SAAUjB,GAE/C,IAAIxB,EAAUS,SAASyC,eACrBC,mBAAmB3B,EAAK4B,KAAKC,OAAO,KAEjCrD,GAGLJ,EAAS0D,KAAK,CACZ1B,IAAKJ,EACLxB,QAASA,GAEb,IAGAL,EAAaC,EACf,EAKAgD,OAAoB,WAElB,IAAIW,EAASlC,EAAUzB,EAAUX,GAG5BsE,EASDb,GAAWa,EAAOvD,UAAY0C,EAAQ1C,UAG1CkC,EAAWQ,EAASzD,GAzFT,SAAUkD,EAAOlD,GAE9B,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASX,UAC1B6D,EAAMnC,QAAQgC,UAAUM,IAAIrD,EAASV,cAGrC8D,EAAeP,EAAI7C,GAGnBJ,EAAU,kBAAmBiD,EAAI,CAC/BM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,CAqEIuE,CAASD,EAAQtE,GAGjByD,EAAUa,GAfJb,IACFR,EAAWQ,EAASzD,GACpByD,EAAU,KAchB,GAMIe,EAAgB,SAAUvE,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,sBAAsBf,EAAWgB,OACpD,EAMIC,EAAgB,SAAU3E,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,uBAAsB,WACrChE,EAAaC,GACbgD,EAAWgB,QACb,GACF,EAkDA,OA7CAhB,EAAWkB,QAAU,WAEfpB,GACFR,EAAWQ,EAASzD,GAItBd,EAAO4F,oBAAoB,SAAUN,GAAe,GAChDxE,EAASN,QACXR,EAAO4F,oBAAoB,SAAUF,GAAe,GAItDjE,EAAW,KACX6C,EAAW,KACXC,EAAU,KACVC,EAAU,KACV1D,EAAW,IACb,EAOEA,EA3XS,WACX,IAAI+E,EAAS,CAAC,EAOd,OANAlB,MAAMC,UAAUC,QAAQC,KAAKgB,WAAW,SAAUC,GAChD,IAAK,IAAIC,KAAOD,EAAK,CACnB,IAAKA,EAAIE,eAAeD,GAAM,OAC9BH,EAAOG,GAAOD,EAAIC,EACpB,CACF,IACOH,CACT,CAkXeK,CAAOhG,EAAUmE,GAAW,CAAC,GAGxCI,EAAW0B,QAGX1B,EAAWgB,SAGXzF,EAAOoG,iBAAiB,SAAUd,GAAe,GAC7CxE,EAASN,QACXR,EAAOoG,iBAAiB,SAAUV,GAAe,GAS9CjB,CACT,CAOF,CArcW4B,CAAQvG,EAChB,UAFM,SAEN,uBCXDwG,EAA2B,CAAC,EAGhC,SAASC,EAAoBC,GAE5B,IAAIC,EAAeH,EAAyBE,GAC5C,QAAqBE,IAAjBD,EACH,OAAOA,EAAaE,QAGrB,IAAIC,EAASN,EAAyBE,GAAY,CAGjDG,QAAS,CAAC,GAOX,OAHAE,EAAoBL,GAAU1B,KAAK8B,EAAOD,QAASC,EAAQA,EAAOD,QAASJ,GAGpEK,EAAOD,OACf,CCrBAJ,EAAoBO,EAAKF,IACxB,IAAIG,EAASH,GAAUA,EAAOI,WAC7B,IAAOJ,EAAiB,QACxB,IAAM,EAEP,OADAL,EAAoBU,EAAEF,EAAQ,CAAEG,EAAGH,IAC5BA,CAAM,ECLdR,EAAoBU,EAAI,CAACN,EAASQ,KACjC,IAAI,IAAInB,KAAOmB,EACXZ,EAAoBa,EAAED,EAAYnB,KAASO,EAAoBa,EAAET,EAASX,IAC5EqB,OAAOC,eAAeX,EAASX,EAAK,CAAEuB,YAAY,EAAMC,IAAKL,EAAWnB,IAE1E,ECNDO,EAAoBxG,EAAI,WACvB,GAA0B,iBAAf0H,WAAyB,OAAOA,WAC3C,IACC,OAAOxH,MAAQ,IAAIyH,SAAS,cAAb,EAChB,CAAE,MAAOC,GACR,GAAsB,iBAAX3H,OAAqB,OAAOA,MACxC,CACA,CAPuB,GCAxBuG,EAAoBa,EAAI,CAACrB,EAAK6B,IAAUP,OAAOzC,UAAUqB,eAAenB,KAAKiB,EAAK6B,4CCK9EC,EAAY,KACZC,EAAS,KACTC,EAAgB/H,OAAO6C,aAAeP,SAASC,gBAAgByF,UACnE,MAAMC,EAAmB,GA2EzB,SAASC,IACP,MAAMC,EAAeC,aAAaC,QAAQ,UAAY,OAZxD,IAAkBC,EACH,WADGA,EAaItI,OAAOuI,WAAW,gCAAgCC,QAI/C,SAAjBL,EACO,QACgB,SAAhBA,EACA,OAEA,OAIU,SAAjBA,EACO,OACgB,QAAhBA,EACA,QAEA,SA9BoB,SAATG,GAA4B,SAATA,IACzCG,QAAQC,MAAM,2BAA2BJ,yBACzCA,EAAO,QAGThG,SAASS,KAAK4F,QAAQC,MAAQN,EAC9BF,aAAaS,QAAQ,QAASP,GAC9BG,QAAQK,IAAI,cAAcR,UA0B5B,CAkDA,SAASnC,KART,WAEE,MAAM4C,EAAUzG,SAAS0G,uBAAuB,gBAChDrE,MAAMsE,KAAKF,GAASlE,SAASqE,IAC3BA,EAAI9C,iBAAiB,QAAS8B,EAAe,GAEjD,CAGEiB,GA9CF,WAEE,IAAIC,EAA6B,EAC7BC,GAAU,EAEdrJ,OAAOoG,iBAAiB,UAAU,SAAUuB,GAC1CyB,EAA6BpJ,OAAOsJ,QAE/BD,IACHrJ,OAAOwF,uBAAsB,WAzDnC,IAAuB+D,IA0DDH,EA9GkC,GAAlDzG,KAAK6G,MAAM1B,EAAO7F,wBAAwBQ,KAC5CqF,EAAOjE,UAAUM,IAAI,YAErB2D,EAAOjE,UAAUC,OAAO,YAI5B,SAAmCyF,GAC7BA,EAAYtB,EACd3F,SAASC,gBAAgBsB,UAAUC,OAAO,oBAEtCyF,EAAYxB,EACdzF,SAASC,gBAAgBsB,UAAUM,IAAI,oBAC9BoF,EAAYxB,GACrBzF,SAASC,gBAAgBsB,UAAUC,OAAO,oBAG9CiE,EAAgBwB,CAClB,CAoCEE,CAA0BF,GAlC5B,SAA6BA,GACT,OAAd1B,IAKa,GAAb0B,EACF1B,EAAU6B,SAAS,EAAG,GAGtB/G,KAAKC,KAAK2G,IACV5G,KAAK6G,MAAMlH,SAASC,gBAAgBS,aAAehD,OAAOqC,aAE1DwF,EAAU6B,SAAS,EAAG7B,EAAU7E,cAGhBV,SAASqH,cAAc,mBAc3C,CAKEC,CAAoBL,GAwDdF,GAAU,CACZ,IAEAA,GAAU,EAEd,IACArJ,OAAO6J,QACT,CA6BEC,GA1BkB,OAAdjC,GAKJ,IAAI,IAAJ,CAAY,cAAe,CACzBrH,QAAQ,EACRuJ,WAAW,EACX5J,SAAU,iBACVI,OAAQ,KACN,IAAIyJ,EAAM9H,WAAW+H,iBAAiB3H,SAASC,iBAAiB2H,UAChE,OAAOpC,EAAO7F,wBAAwBkI,OAAS,IAAMH,EAAM,CAAC,GAiBlE,CAcA1H,SAAS8D,iBAAiB,oBAT1B,WACE9D,SAASS,KAAKW,WAAWG,UAAUC,OAAO,SAE1CgE,EAASxF,SAASqH,cAAc,UAChC9B,EAAYvF,SAASqH,cAAc,eAEnCxD,GACF","sources":["webpack:///./src/furo/assets/scripts/gumshoe-patched.js","webpack:///webpack/bootstrap","webpack:///webpack/runtime/compat get default export","webpack:///webpack/runtime/define property getters","webpack:///webpack/runtime/global","webpack:///webpack/runtime/hasOwnProperty shorthand","webpack:///./src/furo/assets/scripts/furo.js"],"sourcesContent":["/*!\n * gumshoejs v5.1.2 (patched by @pradyunsg)\n * A simple, framework-agnostic scrollspy script.\n * (c) 2019 Chris Ferdinandi\n * MIT License\n * http://github.com/cferdinandi/gumshoe\n */\n\n(function (root, factory) {\n if (typeof define === \"function\" && define.amd) {\n define([], function () {\n return factory(root);\n });\n } else if (typeof exports === \"object\") {\n module.exports = factory(root);\n } else {\n root.Gumshoe = factory(root);\n }\n})(\n typeof global !== \"undefined\"\n ? global\n : typeof window !== \"undefined\"\n ? window\n : this,\n function (window) {\n \"use strict\";\n\n //\n // Defaults\n //\n\n var defaults = {\n // Active classes\n navClass: \"active\",\n contentClass: \"active\",\n\n // Nested navigation\n nested: false,\n nestedClass: \"active\",\n\n // Offset & reflow\n offset: 0,\n reflow: false,\n\n // Event support\n events: true,\n };\n\n //\n // Methods\n //\n\n /**\n * Merge two or more objects together.\n * @param {Object} objects The objects to merge together\n * @returns {Object} Merged values of defaults and options\n */\n var extend = function () {\n var merged = {};\n Array.prototype.forEach.call(arguments, function (obj) {\n for (var key in obj) {\n if (!obj.hasOwnProperty(key)) return;\n merged[key] = obj[key];\n }\n });\n return merged;\n };\n\n /**\n * Emit a custom event\n * @param {String} type The event type\n * @param {Node} elem The element to attach the event to\n * @param {Object} detail Any details to pass along with the event\n */\n var emitEvent = function (type, elem, detail) {\n // Make sure events are enabled\n if (!detail.settings.events) return;\n\n // Create a new event\n var event = new CustomEvent(type, {\n bubbles: true,\n cancelable: true,\n detail: detail,\n });\n\n // Dispatch the event\n elem.dispatchEvent(event);\n };\n\n /**\n * Get an element's distance from the top of the Document.\n * @param {Node} elem The element\n * @return {Number} Distance from the top in pixels\n */\n var getOffsetTop = function (elem) {\n var location = 0;\n if (elem.offsetParent) {\n while (elem) {\n location += elem.offsetTop;\n elem = elem.offsetParent;\n }\n }\n return location >= 0 ? location : 0;\n };\n\n /**\n * Sort content from first to last in the DOM\n * @param {Array} contents The content areas\n */\n var sortContents = function (contents) {\n if (contents) {\n contents.sort(function (item1, item2) {\n var offset1 = getOffsetTop(item1.content);\n var offset2 = getOffsetTop(item2.content);\n if (offset1 < offset2) return -1;\n return 1;\n });\n }\n };\n\n /**\n * Get the offset to use for calculating position\n * @param {Object} settings The settings for this instantiation\n * @return {Float} The number of pixels to offset the calculations\n */\n var getOffset = function (settings) {\n // if the offset is a function run it\n if (typeof settings.offset === \"function\") {\n return parseFloat(settings.offset());\n }\n\n // Otherwise, return it as-is\n return parseFloat(settings.offset);\n };\n\n /**\n * Get the document element's height\n * @private\n * @returns {Number}\n */\n var getDocumentHeight = function () {\n return Math.max(\n document.body.scrollHeight,\n document.documentElement.scrollHeight,\n document.body.offsetHeight,\n document.documentElement.offsetHeight,\n document.body.clientHeight,\n document.documentElement.clientHeight,\n );\n };\n\n /**\n * Determine if an element is in view\n * @param {Node} elem The element\n * @param {Object} settings The settings for this instantiation\n * @param {Boolean} bottom If true, check if element is above bottom of viewport instead\n * @return {Boolean} Returns true if element is in the viewport\n */\n var isInView = function (elem, settings, bottom) {\n var bounds = elem.getBoundingClientRect();\n var offset = getOffset(settings);\n if (bottom) {\n return (\n parseInt(bounds.bottom, 10) <\n (window.innerHeight || document.documentElement.clientHeight)\n );\n }\n return parseInt(bounds.top, 10) <= offset;\n };\n\n /**\n * Check if at the bottom of the viewport\n * @return {Boolean} If true, page is at the bottom of the viewport\n */\n var isAtBottom = function () {\n if (\n Math.ceil(window.innerHeight + window.pageYOffset) >=\n getDocumentHeight()\n )\n return true;\n return false;\n };\n\n /**\n * Check if the last item should be used (even if not at the top of the page)\n * @param {Object} item The last item\n * @param {Object} settings The settings for this instantiation\n * @return {Boolean} If true, use the last item\n */\n var useLastItem = function (item, settings) {\n if (isAtBottom() && isInView(item.content, settings, true)) return true;\n return false;\n };\n\n /**\n * Get the active content\n * @param {Array} contents The content areas\n * @param {Object} settings The settings for this instantiation\n * @return {Object} The content area and matching navigation link\n */\n var getActive = function (contents, settings) {\n var last = contents[contents.length - 1];\n if (useLastItem(last, settings)) return last;\n for (var i = contents.length - 1; i >= 0; i--) {\n if (isInView(contents[i].content, settings)) return contents[i];\n }\n };\n\n /**\n * Deactivate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var deactivateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested || !nav.parentNode) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Remove the active class\n li.classList.remove(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n deactivateNested(li, settings);\n };\n\n /**\n * Deactivate a nav and content area\n * @param {Object} items The nav item and content to deactivate\n * @param {Object} settings The settings for this instantiation\n */\n var deactivate = function (items, settings) {\n // Make sure there are items to deactivate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Remove the active class from the nav and content\n li.classList.remove(settings.navClass);\n items.content.classList.remove(settings.contentClass);\n\n // Deactivate any parent navs in a nested navigation\n deactivateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeDeactivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Activate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var activateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Add the active class\n li.classList.add(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n activateNested(li, settings);\n };\n\n /**\n * Activate a nav and content area\n * @param {Object} items The nav item and content to activate\n * @param {Object} settings The settings for this instantiation\n */\n var activate = function (items, settings) {\n // Make sure there are items to activate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Add the active class to the nav and content\n li.classList.add(settings.navClass);\n items.content.classList.add(settings.contentClass);\n\n // Activate any parent navs in a nested navigation\n activateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeActivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Create the Constructor object\n * @param {String} selector The selector to use for navigation items\n * @param {Object} options User options and settings\n */\n var Constructor = function (selector, options) {\n //\n // Variables\n //\n\n var publicAPIs = {};\n var navItems, contents, current, timeout, settings;\n\n //\n // Methods\n //\n\n /**\n * Set variables from DOM elements\n */\n publicAPIs.setup = function () {\n // Get all nav items\n navItems = document.querySelectorAll(selector);\n\n // Create contents array\n contents = [];\n\n // Loop through each item, get it's matching content, and push to the array\n Array.prototype.forEach.call(navItems, function (item) {\n // Get the content for the nav item\n var content = document.getElementById(\n decodeURIComponent(item.hash.substr(1)),\n );\n if (!content) return;\n\n // Push to the contents array\n contents.push({\n nav: item,\n content: content,\n });\n });\n\n // Sort contents by the order they appear in the DOM\n sortContents(contents);\n };\n\n /**\n * Detect which content is currently active\n */\n publicAPIs.detect = function () {\n // Get the active content\n var active = getActive(contents, settings);\n\n // if there's no active content, deactivate and bail\n if (!active) {\n if (current) {\n deactivate(current, settings);\n current = null;\n }\n return;\n }\n\n // If the active content is the one currently active, do nothing\n if (current && active.content === current.content) return;\n\n // Deactivate the current content and activate the new content\n deactivate(current, settings);\n activate(active, settings);\n\n // Update the currently active content\n current = active;\n };\n\n /**\n * Detect the active content on scroll\n * Debounced for performance\n */\n var scrollHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(publicAPIs.detect);\n };\n\n /**\n * Update content sorting on resize\n * Debounced for performance\n */\n var resizeHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(function () {\n sortContents(contents);\n publicAPIs.detect();\n });\n };\n\n /**\n * Destroy the current instantiation\n */\n publicAPIs.destroy = function () {\n // Undo DOM changes\n if (current) {\n deactivate(current, settings);\n }\n\n // Remove event listeners\n window.removeEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.removeEventListener(\"resize\", resizeHandler, false);\n }\n\n // Reset variables\n contents = null;\n navItems = null;\n current = null;\n timeout = null;\n settings = null;\n };\n\n /**\n * Initialize the current instantiation\n */\n var init = function () {\n // Merge user options into defaults\n settings = extend(defaults, options || {});\n\n // Setup variables based on the current DOM\n publicAPIs.setup();\n\n // Find the currently active content\n publicAPIs.detect();\n\n // Setup event listeners\n window.addEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.addEventListener(\"resize\", resizeHandler, false);\n }\n };\n\n //\n // Initialize and return the public APIs\n //\n\n init();\n return publicAPIs;\n };\n\n //\n // Return the Constructor\n //\n\n return Constructor;\n },\n);\n","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId].call(module.exports, module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","// getDefaultExport function for compatibility with non-harmony modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};","// define getter functions for harmony exports\n__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n\t\t}\n\t}\n};","__webpack_require__.g = (function() {\n\tif (typeof globalThis === 'object') return globalThis;\n\ttry {\n\t\treturn this || new Function('return this')();\n\t} catch (e) {\n\t\tif (typeof window === 'object') return window;\n\t}\n})();","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","import Gumshoe from \"./gumshoe-patched.js\";\n\n////////////////////////////////////////////////////////////////////////////////\n// Scroll Handling\n////////////////////////////////////////////////////////////////////////////////\nvar tocScroll = null;\nvar header = null;\nvar lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;\nconst GO_TO_TOP_OFFSET = 64;\n\nfunction scrollHandlerForHeader() {\n if (Math.floor(header.getBoundingClientRect().top) == 0) {\n header.classList.add(\"scrolled\");\n } else {\n header.classList.remove(\"scrolled\");\n }\n}\n\nfunction scrollHandlerForBackToTop(positionY) {\n if (positionY < GO_TO_TOP_OFFSET) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n } else {\n if (positionY < lastScrollTop) {\n document.documentElement.classList.add(\"show-back-to-top\");\n } else if (positionY > lastScrollTop) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n }\n }\n lastScrollTop = positionY;\n}\n\nfunction scrollHandlerForTOC(positionY) {\n if (tocScroll === null) {\n return;\n }\n\n // top of page.\n if (positionY == 0) {\n tocScroll.scrollTo(0, 0);\n } else if (\n // bottom of page.\n Math.ceil(positionY) >=\n Math.floor(document.documentElement.scrollHeight - window.innerHeight)\n ) {\n tocScroll.scrollTo(0, tocScroll.scrollHeight);\n } else {\n // somewhere in the middle.\n const current = document.querySelector(\".scroll-current\");\n if (current == null) {\n return;\n }\n\n // https://github.com/pypa/pip/issues/9159 This breaks scroll behaviours.\n // // scroll the currently \"active\" heading in toc, into view.\n // const rect = current.getBoundingClientRect();\n // if (0 > rect.top) {\n // current.scrollIntoView(true); // the argument is \"alignTop\"\n // } else if (rect.bottom > window.innerHeight) {\n // current.scrollIntoView(false);\n // }\n }\n}\n\nfunction scrollHandler(positionY) {\n scrollHandlerForHeader();\n scrollHandlerForBackToTop(positionY);\n scrollHandlerForTOC(positionY);\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Theme Toggle\n////////////////////////////////////////////////////////////////////////////////\nfunction setTheme(mode) {\n if (mode !== \"light\" && mode !== \"dark\" && mode !== \"auto\") {\n console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);\n mode = \"auto\";\n }\n\n document.body.dataset.theme = mode;\n localStorage.setItem(\"theme\", mode);\n console.log(`Changed to ${mode} mode.`);\n}\n\nfunction cycleThemeOnce() {\n const currentTheme = localStorage.getItem(\"theme\") || \"auto\";\n const prefersDark = window.matchMedia(\"(prefers-color-scheme: dark)\").matches;\n\n if (prefersDark) {\n // Auto (dark) -> Light -> Dark\n if (currentTheme === \"auto\") {\n setTheme(\"light\");\n } else if (currentTheme == \"light\") {\n setTheme(\"dark\");\n } else {\n setTheme(\"auto\");\n }\n } else {\n // Auto (light) -> Dark -> Light\n if (currentTheme === \"auto\") {\n setTheme(\"dark\");\n } else if (currentTheme == \"dark\") {\n setTheme(\"light\");\n } else {\n setTheme(\"auto\");\n }\n }\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Setup\n////////////////////////////////////////////////////////////////////////////////\nfunction setupScrollHandler() {\n // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event\n let last_known_scroll_position = 0;\n let ticking = false;\n\n window.addEventListener(\"scroll\", function (e) {\n last_known_scroll_position = window.scrollY;\n\n if (!ticking) {\n window.requestAnimationFrame(function () {\n scrollHandler(last_known_scroll_position);\n ticking = false;\n });\n\n ticking = true;\n }\n });\n window.scroll();\n}\n\nfunction setupScrollSpy() {\n if (tocScroll === null) {\n return;\n }\n\n // Scrollspy -- highlight table on contents, based on scroll\n new Gumshoe(\".toc-tree a\", {\n reflow: true,\n recursive: true,\n navClass: \"scroll-current\",\n offset: () => {\n let rem = parseFloat(getComputedStyle(document.documentElement).fontSize);\n return header.getBoundingClientRect().height + 2.5 * rem + 1;\n },\n });\n}\n\nfunction setupTheme() {\n // Attach event handlers for toggling themes\n const buttons = document.getElementsByClassName(\"theme-toggle\");\n Array.from(buttons).forEach((btn) => {\n btn.addEventListener(\"click\", cycleThemeOnce);\n });\n}\n\nfunction setup() {\n setupTheme();\n setupScrollHandler();\n setupScrollSpy();\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Main entrypoint\n////////////////////////////////////////////////////////////////////////////////\nfunction main() {\n document.body.parentNode.classList.remove(\"no-js\");\n\n header = document.querySelector(\"header\");\n tocScroll = document.querySelector(\".toc-scroll\");\n\n setup();\n}\n\ndocument.addEventListener(\"DOMContentLoaded\", main);\n"],"names":["root","g","window","this","defaults","navClass","contentClass","nested","nestedClass","offset","reflow","events","emitEvent","type","elem","detail","settings","event","CustomEvent","bubbles","cancelable","dispatchEvent","getOffsetTop","location","offsetParent","offsetTop","sortContents","contents","sort","item1","item2","content","isInView","bottom","bounds","getBoundingClientRect","parseFloat","getOffset","parseInt","innerHeight","document","documentElement","clientHeight","top","isAtBottom","Math","ceil","pageYOffset","max","body","scrollHeight","offsetHeight","getActive","last","length","item","useLastItem","i","deactivateNested","nav","parentNode","li","closest","classList","remove","deactivate","items","link","activateNested","add","selector","options","navItems","current","timeout","publicAPIs","querySelectorAll","Array","prototype","forEach","call","getElementById","decodeURIComponent","hash","substr","push","active","activate","scrollHandler","cancelAnimationFrame","requestAnimationFrame","detect","resizeHandler","destroy","removeEventListener","merged","arguments","obj","key","hasOwnProperty","extend","setup","addEventListener","factory","__webpack_module_cache__","__webpack_require__","moduleId","cachedModule","undefined","exports","module","__webpack_modules__","n","getter","__esModule","d","a","definition","o","Object","defineProperty","enumerable","get","globalThis","Function","e","prop","tocScroll","header","lastScrollTop","scrollTop","GO_TO_TOP_OFFSET","cycleThemeOnce","currentTheme","localStorage","getItem","mode","matchMedia","matches","console","error","dataset","theme","setItem","log","buttons","getElementsByClassName","from","btn","setupTheme","last_known_scroll_position","ticking","scrollY","positionY","floor","scrollHandlerForBackToTop","scrollTo","querySelector","scrollHandlerForTOC","scroll","setupScrollHandler","recursive","rem","getComputedStyle","fontSize","height"],"sourceRoot":""} \ No newline at end of file diff --git a/pull/1473/_static/searchtools.js b/pull/1473/_static/searchtools.js new file mode 100644 index 0000000000..92da3f8b22 --- /dev/null +++ b/pull/1473/_static/searchtools.js @@ -0,0 +1,619 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + "Search finished, found ${resultCount} page(s) matching the search query." + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlinks", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + let score = Math.round(100 * queryLower.length / title.length) + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/pull/1473/_static/skeleton.css b/pull/1473/_static/skeleton.css new file mode 100644 index 0000000000..467c878c62 --- /dev/null +++ b/pull/1473/_static/skeleton.css @@ -0,0 +1,296 @@ +/* Some sane resets. */ +html { + height: 100%; +} + +body { + margin: 0; + min-height: 100%; +} + +/* All the flexbox magic! */ +body, +.sb-announcement, +.sb-content, +.sb-main, +.sb-container, +.sb-container__inner, +.sb-article-container, +.sb-footer-content, +.sb-header, +.sb-header-secondary, +.sb-footer { + display: flex; +} + +/* These order things vertically */ +body, +.sb-main, +.sb-article-container { + flex-direction: column; +} + +/* Put elements in the center */ +.sb-header, +.sb-header-secondary, +.sb-container, +.sb-content, +.sb-footer, +.sb-footer-content { + justify-content: center; +} +/* Put elements at the ends */ +.sb-article-container { + justify-content: space-between; +} + +/* These elements grow. */ +.sb-main, +.sb-content, +.sb-container, +article { + flex-grow: 1; +} + +/* Because padding making this wider is not fun */ +article { + box-sizing: border-box; +} + +/* The announcements element should never be wider than the page. */ +.sb-announcement { + max-width: 100%; +} + +.sb-sidebar-primary, +.sb-sidebar-secondary { + flex-shrink: 0; + width: 17rem; +} + +.sb-announcement__inner { + justify-content: center; + + box-sizing: border-box; + height: 3rem; + + overflow-x: auto; + white-space: nowrap; +} + +/* Sidebars, with checkbox-based toggle */ +.sb-sidebar-primary, +.sb-sidebar-secondary { + position: fixed; + height: 100%; + top: 0; +} + +.sb-sidebar-primary { + left: -17rem; + transition: left 250ms ease-in-out; +} +.sb-sidebar-secondary { + right: -17rem; + transition: right 250ms ease-in-out; +} + +.sb-sidebar-toggle { + display: none; +} +.sb-sidebar-overlay { + position: fixed; + top: 0; + width: 0; + height: 0; + + transition: width 0ms ease 250ms, height 0ms ease 250ms, opacity 250ms ease; + + opacity: 0; + background-color: rgba(0, 0, 0, 0.54); +} + +#sb-sidebar-toggle--primary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--primary"], +#sb-sidebar-toggle--secondary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--secondary"] { + width: 100%; + height: 100%; + opacity: 1; + transition: width 0ms ease, height 0ms ease, opacity 250ms ease; +} + +#sb-sidebar-toggle--primary:checked ~ .sb-container .sb-sidebar-primary { + left: 0; +} +#sb-sidebar-toggle--secondary:checked ~ .sb-container .sb-sidebar-secondary { + right: 0; +} + +/* Full-width mode */ +.drop-secondary-sidebar-for-full-width-content + .hide-when-secondary-sidebar-shown { + display: none !important; +} +.drop-secondary-sidebar-for-full-width-content .sb-sidebar-secondary { + display: none !important; +} + +/* Mobile views */ +.sb-page-width { + width: 100%; +} + +.sb-article-container, +.sb-footer-content__inner, +.drop-secondary-sidebar-for-full-width-content .sb-article, +.drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 100vw; +} + +.sb-article, +.match-content-width { + padding: 0 1rem; + box-sizing: border-box; +} + +@media (min-width: 32rem) { + .sb-article, + .match-content-width { + padding: 0 2rem; + } +} + +/* Tablet views */ +@media (min-width: 42rem) { + .sb-article-container { + width: auto; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 42rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 46rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 46rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 50rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 50rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Tablet views */ +@media (min-width: 59rem) { + .sb-sidebar-secondary { + position: static; + } + .hide-when-secondary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 63rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 67rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Desktop views */ +@media (min-width: 76rem) { + .sb-sidebar-primary { + position: static; + } + .hide-when-primary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} + +/* Full desktop views */ +@media (min-width: 80rem) { + .sb-article, + .match-content-width { + width: 46rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } +} + +@media (min-width: 84rem) { + .sb-article, + .match-content-width { + width: 50rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } +} + +@media (min-width: 88rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-page-width { + width: 88rem; + } +} diff --git a/pull/1473/_static/sphinx_highlight.js b/pull/1473/_static/sphinx_highlight.js new file mode 100644 index 0000000000..8a96c69a19 --- /dev/null +++ b/pull/1473/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/pull/1473/_static/styles/furo-extensions.css b/pull/1473/_static/styles/furo-extensions.css new file mode 100644 index 0000000000..bc447f228f --- /dev/null +++ b/pull/1473/_static/styles/furo-extensions.css @@ -0,0 +1,2 @@ +#furo-sidebar-ad-placement{padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)}#furo-sidebar-ad-placement .ethical-sidebar{background:var(--color-background-secondary);border:none;box-shadow:none}#furo-sidebar-ad-placement .ethical-sidebar:hover{background:var(--color-background-hover)}#furo-sidebar-ad-placement .ethical-sidebar a{color:var(--color-foreground-primary)}#furo-sidebar-ad-placement .ethical-callout a{color:var(--color-foreground-secondary)!important}#furo-readthedocs-versions{background:transparent;display:block;position:static;width:100%}#furo-readthedocs-versions .rst-versions{background:#1a1c1e}#furo-readthedocs-versions .rst-current-version{background:var(--color-sidebar-item-background);cursor:unset}#furo-readthedocs-versions .rst-current-version:hover{background:var(--color-sidebar-item-background)}#furo-readthedocs-versions .rst-current-version .fa-book{color:var(--color-foreground-primary)}#furo-readthedocs-versions>.rst-other-versions{padding:0}#furo-readthedocs-versions>.rst-other-versions small{opacity:1}#furo-readthedocs-versions .injected .rst-versions{position:unset}#furo-readthedocs-versions:focus-within,#furo-readthedocs-versions:hover{box-shadow:0 0 0 1px var(--color-sidebar-background-border)}#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:hover .rst-current-version{background:#1a1c1e;font-size:inherit;height:auto;line-height:inherit;padding:12px;text-align:right}#furo-readthedocs-versions:focus-within .rst-current-version .fa-book,#furo-readthedocs-versions:hover .rst-current-version .fa-book{color:#fff;float:left}#furo-readthedocs-versions:focus-within .fa-caret-down,#furo-readthedocs-versions:hover .fa-caret-down{display:none}#furo-readthedocs-versions:focus-within .injected,#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:focus-within .rst-other-versions,#furo-readthedocs-versions:hover .injected,#furo-readthedocs-versions:hover .rst-current-version,#furo-readthedocs-versions:hover .rst-other-versions{display:block}#furo-readthedocs-versions:focus-within>.rst-current-version,#furo-readthedocs-versions:hover>.rst-current-version{display:none}.highlight:hover button.copybtn{color:var(--color-code-foreground)}.highlight button.copybtn{align-items:center;background-color:var(--color-code-background);border:none;color:var(--color-background-item);cursor:pointer;height:1.25em;opacity:1;right:.5rem;top:.625rem;transition:color .3s,opacity .3s;width:1.25em}.highlight button.copybtn:hover{background-color:var(--color-code-background);color:var(--color-brand-content)}.highlight button.copybtn:after{background-color:transparent;color:var(--color-code-foreground);display:none}.highlight button.copybtn.success{color:#22863a;transition:color 0ms}.highlight button.copybtn.success:after{display:block}.highlight button.copybtn svg{padding:0}body{--sd-color-primary:var(--color-brand-primary);--sd-color-primary-highlight:var(--color-brand-content);--sd-color-primary-text:var(--color-background-primary);--sd-color-shadow:rgba(0,0,0,.05);--sd-color-card-border:var(--color-card-border);--sd-color-card-border-hover:var(--color-brand-content);--sd-color-card-background:var(--color-card-background);--sd-color-card-text:var(--color-foreground-primary);--sd-color-card-header:var(--color-card-marginals-background);--sd-color-card-footer:var(--color-card-marginals-background);--sd-color-tabs-label-active:var(--color-brand-content);--sd-color-tabs-label-hover:var(--color-foreground-muted);--sd-color-tabs-label-inactive:var(--color-foreground-muted);--sd-color-tabs-underline-active:var(--color-brand-content);--sd-color-tabs-underline-hover:var(--color-foreground-border);--sd-color-tabs-underline-inactive:var(--color-background-border);--sd-color-tabs-overline:var(--color-background-border);--sd-color-tabs-underline:var(--color-background-border)}.sd-tab-content{box-shadow:0 -2px var(--sd-color-tabs-overline),0 1px var(--sd-color-tabs-underline)}.sd-card{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)}.sd-shadow-sm{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-md{box-shadow:0 .3rem .75rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-lg{box-shadow:0 .6rem 1.5rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-card-hover:hover{transform:none}.sd-cards-carousel{gap:.25rem;padding:.25rem}body{--tabs--label-text:var(--color-foreground-muted);--tabs--label-text--hover:var(--color-foreground-muted);--tabs--label-text--active:var(--color-brand-content);--tabs--label-text--active--hover:var(--color-brand-content);--tabs--label-background:transparent;--tabs--label-background--hover:transparent;--tabs--label-background--active:transparent;--tabs--label-background--active--hover:transparent;--tabs--padding-x:0.25em;--tabs--margin-x:1em;--tabs--border:var(--color-background-border);--tabs--label-border:transparent;--tabs--label-border--hover:var(--color-foreground-muted);--tabs--label-border--active:var(--color-brand-content);--tabs--label-border--active--hover:var(--color-brand-content)}[role=main] .container{max-width:none;padding-left:0;padding-right:0}.shadow.docutils{border:none;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)!important}.sphinx-bs .card{background-color:var(--color-background-secondary);color:var(--color-foreground)} +/*# sourceMappingURL=furo-extensions.css.map*/ \ No newline at end of file diff --git a/pull/1473/_static/styles/furo-extensions.css.map b/pull/1473/_static/styles/furo-extensions.css.map new file mode 100644 index 0000000000..9ba5637f9a --- /dev/null +++ b/pull/1473/_static/styles/furo-extensions.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo-extensions.css","mappings":"AAGA,2BACE,oFACA,4CAKE,6CAHA,YACA,eAEA,CACA,kDACE,yCAEF,8CACE,sCAEJ,8CACE,kDAEJ,2BAGE,uBACA,cAHA,gBACA,UAEA,CAGA,yCACE,mBAEF,gDAEE,gDADA,YACA,CACA,sDACE,gDACF,yDACE,sCAEJ,+CACE,UACA,qDACE,UAGF,mDACE,eAEJ,yEAEE,4DAEA,mHASE,mBAPA,kBAEA,YADA,oBAGA,aADA,gBAIA,CAEA,qIAEE,WADA,UACA,CAEJ,uGACE,aAEF,iUAGE,cAEF,mHACE,aC1EJ,gCACE,mCAEF,0BAKE,mBAUA,8CACA,YAFA,mCAKA,eAZA,cALA,UASA,YADA,YAYA,iCAdA,YAcA,CAEA,gCAEE,8CADA,gCACA,CAEF,gCAGE,6BADA,mCADA,YAEA,CAEF,kCAEE,cADA,oBACA,CACA,wCACE,cAEJ,8BACE,UC5CN,KAEE,6CAA8C,CAC9C,uDAAwD,CACxD,uDAAwD,CAGxD,iCAAsC,CAGtC,+CAAgD,CAChD,uDAAwD,CACxD,uDAAwD,CACxD,oDAAqD,CACrD,6DAA8D,CAC9D,6DAA8D,CAG9D,uDAAwD,CACxD,yDAA0D,CAC1D,4DAA6D,CAC7D,2DAA4D,CAC5D,8DAA+D,CAC/D,iEAAkE,CAClE,uDAAwD,CACxD,wDAAyD,CAG3D,gBACE,qFAGF,SACE,6EAEF,cACE,uFAEF,cACE,uFAEF,cACE,uFAGF,qBACE,eAEF,mBACE,WACA,eChDF,KACE,gDAAiD,CACjD,uDAAwD,CACxD,qDAAsD,CACtD,4DAA6D,CAC7D,oCAAqC,CACrC,2CAA4C,CAC5C,4CAA6C,CAC7C,mDAAoD,CACpD,wBAAyB,CACzB,oBAAqB,CACrB,6CAA8C,CAC9C,gCAAiC,CACjC,yDAA0D,CAC1D,uDAAwD,CACxD,8DAA+D,CCbjE,uBACE,eACA,eACA,gBAGF,iBACE,YACA,+EAGF,iBACE,mDACA","sources":["webpack:///./src/furo/assets/styles/extensions/_readthedocs.sass","webpack:///./src/furo/assets/styles/extensions/_copybutton.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-design.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-inline-tabs.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-panels.sass"],"sourcesContent":["// This file contains the styles used for tweaking how ReadTheDoc's embedded\n// contents would show up inside the theme.\n\n#furo-sidebar-ad-placement\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n .ethical-sidebar\n // Remove the border and box-shadow.\n border: none\n box-shadow: none\n // Manage the background colors.\n background: var(--color-background-secondary)\n &:hover\n background: var(--color-background-hover)\n // Ensure the text is legible.\n a\n color: var(--color-foreground-primary)\n\n .ethical-callout a\n color: var(--color-foreground-secondary) !important\n\n#furo-readthedocs-versions\n position: static\n width: 100%\n background: transparent\n display: block\n\n // Make the background color fit with the theme's aesthetic.\n .rst-versions\n background: rgb(26, 28, 30)\n\n .rst-current-version\n cursor: unset\n background: var(--color-sidebar-item-background)\n &:hover\n background: var(--color-sidebar-item-background)\n .fa-book\n color: var(--color-foreground-primary)\n\n > .rst-other-versions\n padding: 0\n small\n opacity: 1\n\n .injected\n .rst-versions\n position: unset\n\n &:hover,\n &:focus-within\n box-shadow: 0 0 0 1px var(--color-sidebar-background-border)\n\n .rst-current-version\n // Undo the tweaks done in RTD's CSS\n font-size: inherit\n line-height: inherit\n height: auto\n text-align: right\n padding: 12px\n\n // Match the rest of the body\n background: #1a1c1e\n\n .fa-book\n float: left\n color: white\n\n .fa-caret-down\n display: none\n\n .rst-current-version,\n .rst-other-versions,\n .injected\n display: block\n\n > .rst-current-version\n display: none\n",".highlight\n &:hover button.copybtn\n color: var(--color-code-foreground)\n\n button.copybtn\n // Make it visible\n opacity: 1\n\n // Align things correctly\n align-items: center\n\n height: 1.25em\n width: 1.25em\n\n top: 0.625rem // $code-spacing-vertical\n right: 0.5rem\n\n // Make it look better\n color: var(--color-background-item)\n background-color: var(--color-code-background)\n border: none\n\n // Change to cursor to make it obvious that you can click on it\n cursor: pointer\n\n // Transition smoothly, for aesthetics\n transition: color 300ms, opacity 300ms\n\n &:hover\n color: var(--color-brand-content)\n background-color: var(--color-code-background)\n\n &::after\n display: none\n color: var(--color-code-foreground)\n background-color: transparent\n\n &.success\n transition: color 0ms\n color: #22863a\n &::after\n display: block\n\n svg\n padding: 0\n","body\n // Colors\n --sd-color-primary: var(--color-brand-primary)\n --sd-color-primary-highlight: var(--color-brand-content)\n --sd-color-primary-text: var(--color-background-primary)\n\n // Shadows\n --sd-color-shadow: rgba(0, 0, 0, 0.05)\n\n // Cards\n --sd-color-card-border: var(--color-card-border)\n --sd-color-card-border-hover: var(--color-brand-content)\n --sd-color-card-background: var(--color-card-background)\n --sd-color-card-text: var(--color-foreground-primary)\n --sd-color-card-header: var(--color-card-marginals-background)\n --sd-color-card-footer: var(--color-card-marginals-background)\n\n // Tabs\n --sd-color-tabs-label-active: var(--color-brand-content)\n --sd-color-tabs-label-hover: var(--color-foreground-muted)\n --sd-color-tabs-label-inactive: var(--color-foreground-muted)\n --sd-color-tabs-underline-active: var(--color-brand-content)\n --sd-color-tabs-underline-hover: var(--color-foreground-border)\n --sd-color-tabs-underline-inactive: var(--color-background-border)\n --sd-color-tabs-overline: var(--color-background-border)\n --sd-color-tabs-underline: var(--color-background-border)\n\n// Tabs\n.sd-tab-content\n box-shadow: 0 -2px var(--sd-color-tabs-overline), 0 1px var(--sd-color-tabs-underline)\n\n// Shadows\n.sd-card // Have a shadow by default\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n.sd-shadow-sm\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-md\n box-shadow: 0 0.3rem 0.75rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-lg\n box-shadow: 0 0.6rem 1.5rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Cards\n.sd-card-hover:hover // Don't change scale on hover\n transform: none\n\n.sd-cards-carousel // Have a bit of gap in the carousel by default\n gap: 0.25rem\n padding: 0.25rem\n","// This file contains styles to tweak sphinx-inline-tabs to work well with Furo.\n\nbody\n --tabs--label-text: var(--color-foreground-muted)\n --tabs--label-text--hover: var(--color-foreground-muted)\n --tabs--label-text--active: var(--color-brand-content)\n --tabs--label-text--active--hover: var(--color-brand-content)\n --tabs--label-background: transparent\n --tabs--label-background--hover: transparent\n --tabs--label-background--active: transparent\n --tabs--label-background--active--hover: transparent\n --tabs--padding-x: 0.25em\n --tabs--margin-x: 1em\n --tabs--border: var(--color-background-border)\n --tabs--label-border: transparent\n --tabs--label-border--hover: var(--color-foreground-muted)\n --tabs--label-border--active: var(--color-brand-content)\n --tabs--label-border--active--hover: var(--color-brand-content)\n","// This file contains styles to tweak sphinx-panels to work well with Furo.\n\n// sphinx-panels includes Bootstrap 4, which uses .container which can conflict\n// with docutils' `.. container::` directive.\n[role=\"main\"] .container\n max-width: initial\n padding-left: initial\n padding-right: initial\n\n// Make the panels look nicer!\n.shadow.docutils\n border: none\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Make panel colors respond to dark mode\n.sphinx-bs .card\n background-color: var(--color-background-secondary)\n color: var(--color-foreground)\n"],"names":[],"sourceRoot":""} \ No newline at end of file diff --git a/pull/1473/_static/styles/furo.css b/pull/1473/_static/styles/furo.css new file mode 100644 index 0000000000..e3d4e57b86 --- /dev/null +++ b/pull/1473/_static/styles/furo.css @@ -0,0 +1,2 @@ +/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}[hidden],template{display:none}@media print{.content-icon-container,.headerlink,.mobile-header,.related-pages{display:none!important}.highlight{border:.1pt solid var(--color-foreground-border)}a,blockquote,dl,ol,pre,table,ul{page-break-inside:avoid}caption,figure,h1,h2,h3,h4,h5,h6,img{page-break-after:avoid;page-break-inside:avoid}dl,ol,ul{page-break-before:avoid}}.visually-hidden{height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;width:1px!important;clip:rect(0,0,0,0)!important;background:var(--color-background-primary);border:0!important;color:var(--color-foreground-primary);white-space:nowrap!important}:-moz-focusring{outline:auto}body{--font-stack:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji;--font-stack--monospace:"SFMono-Regular",Menlo,Consolas,Monaco,Liberation Mono,Lucida Console,monospace;--font-stack--headings:var(--font-stack);--font-size--normal:100%;--font-size--small:87.5%;--font-size--small--2:81.25%;--font-size--small--3:75%;--font-size--small--4:62.5%;--sidebar-caption-font-size:var(--font-size--small--2);--sidebar-item-font-size:var(--font-size--small);--sidebar-search-input-font-size:var(--font-size--small);--toc-font-size:var(--font-size--small--3);--toc-font-size--mobile:var(--font-size--normal);--toc-title-font-size:var(--font-size--small--4);--admonition-font-size:0.8125rem;--admonition-title-font-size:0.8125rem;--code-font-size:var(--font-size--small--2);--api-font-size:var(--font-size--small);--header-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*4);--header-padding:0.5rem;--sidebar-tree-space-above:1.5rem;--sidebar-caption-space-above:1rem;--sidebar-item-line-height:1rem;--sidebar-item-spacing-vertical:0.5rem;--sidebar-item-spacing-horizontal:1rem;--sidebar-item-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*2);--sidebar-expander-width:var(--sidebar-item-height);--sidebar-search-space-above:0.5rem;--sidebar-search-input-spacing-vertical:0.5rem;--sidebar-search-input-spacing-horizontal:0.5rem;--sidebar-search-input-height:1rem;--sidebar-search-icon-size:var(--sidebar-search-input-height);--toc-title-padding:0.25rem 0;--toc-spacing-vertical:1.5rem;--toc-spacing-horizontal:1.5rem;--toc-item-spacing-vertical:0.4rem;--toc-item-spacing-horizontal:1rem;--icon-search:url('data:image/svg+xml;charset=utf-8,');--icon-pencil:url('data:image/svg+xml;charset=utf-8,');--icon-abstract:url('data:image/svg+xml;charset=utf-8,');--icon-info:url('data:image/svg+xml;charset=utf-8,');--icon-flame:url('data:image/svg+xml;charset=utf-8,');--icon-question:url('data:image/svg+xml;charset=utf-8,');--icon-warning:url('data:image/svg+xml;charset=utf-8,');--icon-failure:url('data:image/svg+xml;charset=utf-8,');--icon-spark:url('data:image/svg+xml;charset=utf-8,');--color-admonition-title--caution:#ff9100;--color-admonition-title-background--caution:rgba(255,145,0,.2);--color-admonition-title--warning:#ff9100;--color-admonition-title-background--warning:rgba(255,145,0,.2);--color-admonition-title--danger:#ff5252;--color-admonition-title-background--danger:rgba(255,82,82,.2);--color-admonition-title--attention:#ff5252;--color-admonition-title-background--attention:rgba(255,82,82,.2);--color-admonition-title--error:#ff5252;--color-admonition-title-background--error:rgba(255,82,82,.2);--color-admonition-title--hint:#00c852;--color-admonition-title-background--hint:rgba(0,200,82,.2);--color-admonition-title--tip:#00c852;--color-admonition-title-background--tip:rgba(0,200,82,.2);--color-admonition-title--important:#00bfa5;--color-admonition-title-background--important:rgba(0,191,165,.2);--color-admonition-title--note:#00b0ff;--color-admonition-title-background--note:rgba(0,176,255,.2);--color-admonition-title--seealso:#448aff;--color-admonition-title-background--seealso:rgba(68,138,255,.2);--color-admonition-title--admonition-todo:grey;--color-admonition-title-background--admonition-todo:hsla(0,0%,50%,.2);--color-admonition-title:#651fff;--color-admonition-title-background:rgba(101,31,255,.2);--icon-admonition-default:var(--icon-abstract);--color-topic-title:#14b8a6;--color-topic-title-background:rgba(20,184,166,.2);--icon-topic-default:var(--icon-pencil);--color-problematic:#b30000;--color-foreground-primary:#000;--color-foreground-secondary:#5a5c63;--color-foreground-muted:#6b6f76;--color-foreground-border:#878787;--color-background-primary:#fff;--color-background-secondary:#f8f9fb;--color-background-hover:#efeff4;--color-background-hover--transparent:#efeff400;--color-background-border:#eeebee;--color-background-item:#ccc;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#0a4bff;--color-brand-content:#2757dd;--color-brand-visited:#872ee0;--color-api-background:var(--color-background-hover--transparent);--color-api-background-hover:var(--color-background-hover);--color-api-overall:var(--color-foreground-secondary);--color-api-name:var(--color-problematic);--color-api-pre-name:var(--color-problematic);--color-api-paren:var(--color-foreground-secondary);--color-api-keyword:var(--color-foreground-primary);--color-api-added:#21632c;--color-api-added-border:#38a84d;--color-api-changed:#046172;--color-api-changed-border:#06a1bc;--color-api-deprecated:#605706;--color-api-deprecated-border:#f0d90f;--color-api-removed:#b30000;--color-api-removed-border:#ff5c5c;--color-highlight-on-target:#ffc;--color-inline-code-background:var(--color-background-secondary);--color-highlighted-background:#def;--color-highlighted-text:var(--color-foreground-primary);--color-guilabel-background:#ddeeff80;--color-guilabel-border:#bedaf580;--color-guilabel-text:var(--color-foreground-primary);--color-admonition-background:transparent;--color-table-header-background:var(--color-background-secondary);--color-table-border:var(--color-background-border);--color-card-border:var(--color-background-secondary);--color-card-background:transparent;--color-card-marginals-background:var(--color-background-secondary);--color-header-background:var(--color-background-primary);--color-header-border:var(--color-background-border);--color-header-text:var(--color-foreground-primary);--color-sidebar-background:var(--color-background-secondary);--color-sidebar-background-border:var(--color-background-border);--color-sidebar-brand-text:var(--color-foreground-primary);--color-sidebar-caption-text:var(--color-foreground-muted);--color-sidebar-link-text:var(--color-foreground-secondary);--color-sidebar-link-text--top-level:var(--color-brand-primary);--color-sidebar-item-background:var(--color-sidebar-background);--color-sidebar-item-background--current:var( --color-sidebar-item-background );--color-sidebar-item-background--hover:linear-gradient(90deg,var(--color-background-hover--transparent) 0%,var(--color-background-hover) var(--sidebar-item-spacing-horizontal),var(--color-background-hover) 100%);--color-sidebar-item-expander-background:transparent;--color-sidebar-item-expander-background--hover:var( --color-background-hover );--color-sidebar-search-text:var(--color-foreground-primary);--color-sidebar-search-background:var(--color-background-secondary);--color-sidebar-search-background--focus:var(--color-background-primary);--color-sidebar-search-border:var(--color-background-border);--color-sidebar-search-icon:var(--color-foreground-muted);--color-toc-background:var(--color-background-primary);--color-toc-title-text:var(--color-foreground-muted);--color-toc-item-text:var(--color-foreground-secondary);--color-toc-item-text--hover:var(--color-foreground-primary);--color-toc-item-text--active:var(--color-brand-primary);--color-content-foreground:var(--color-foreground-primary);--color-content-background:transparent;--color-link:var(--color-brand-content);--color-link-underline:var(--color-background-border);--color-link--hover:var(--color-brand-content);--color-link-underline--hover:var(--color-foreground-border);--color-link--visited:var(--color-brand-visited);--color-link-underline--visited:var(--color-background-border);--color-link--visited--hover:var(--color-brand-visited);--color-link-underline--visited--hover:var(--color-foreground-border)}.only-light{display:block!important}html body .only-dark{display:none!important}@media not print{body[data-theme=dark]{--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body[data-theme=dark] .only-light{display:none!important}body[data-theme=dark] .only-dark{display:block!important}@media(prefers-color-scheme:dark){body:not([data-theme=light]){--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body:not([data-theme=light]) .only-light{display:none!important}body:not([data-theme=light]) .only-dark{display:block!important}}}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:block}@media(prefers-color-scheme:dark){body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-dark{display:block}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:none}}body[data-theme=dark] .theme-toggle svg.theme-icon-when-dark,body[data-theme=light] .theme-toggle svg.theme-icon-when-light{display:block}body{font-family:var(--font-stack)}code,kbd,pre,samp{font-family:var(--font-stack--monospace)}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}article{line-height:1.5}h1,h2,h3,h4,h5,h6{border-radius:.5rem;font-family:var(--font-stack--headings);font-weight:700;line-height:1.25;margin:.5rem -.5rem;padding-left:.5rem;padding-right:.5rem}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p{margin-top:0}h1{font-size:2.5em;margin-bottom:1rem}h1,h2{margin-top:1.75rem}h2{font-size:2em}h3{font-size:1.5em}h4{font-size:1.25em}h5{font-size:1.125em}h6{font-size:1em}small{font-size:80%;opacity:75%}p{margin-bottom:.75rem;margin-top:.5rem}hr.docutils{background-color:var(--color-background-border);border:0;height:1px;margin:2rem 0;padding:0}.centered{text-align:center}a{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}a:visited{color:var(--color-link--visited);text-decoration-color:var(--color-link-underline--visited)}a:visited:hover{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}a:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link{color:inherit}a.muted-link:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link:hover:visited{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}html{overflow-x:hidden;overflow-y:scroll;scroll-behavior:smooth}.sidebar-scroll,.toc-scroll,article[role=main] *{scrollbar-color:var(--color-foreground-border) transparent;scrollbar-width:thin}.sidebar-scroll::-webkit-scrollbar,.toc-scroll::-webkit-scrollbar,article[role=main] ::-webkit-scrollbar{height:.25rem;width:.25rem}.sidebar-scroll::-webkit-scrollbar-thumb,.toc-scroll::-webkit-scrollbar-thumb,article[role=main] ::-webkit-scrollbar-thumb{background-color:var(--color-foreground-border);border-radius:.125rem}body,html{height:100%}.skip-to-content,body,html{background:var(--color-background-primary);color:var(--color-foreground-primary)}.skip-to-content{border-radius:1rem;left:.25rem;padding:1rem;position:fixed;top:.25rem;transform:translateY(-200%);transition:transform .3s ease-in-out;z-index:40}.skip-to-content:focus-within{transform:translateY(0)}article{background:var(--color-content-background);color:var(--color-content-foreground);overflow-wrap:break-word}.page{display:flex;min-height:100%}.mobile-header{background-color:var(--color-header-background);border-bottom:1px solid var(--color-header-border);color:var(--color-header-text);display:none;height:var(--header-height);width:100%;z-index:10}.mobile-header.scrolled{border-bottom:none;box-shadow:0 0 .2rem rgba(0,0,0,.1),0 .2rem .4rem rgba(0,0,0,.2)}.mobile-header .header-center a{color:var(--color-header-text);text-decoration:none}.main{display:flex;flex:1}.sidebar-drawer{background:var(--color-sidebar-background);border-right:1px solid var(--color-sidebar-background-border);box-sizing:border-box;display:flex;justify-content:flex-end;min-width:15em;width:calc(50% - 26em)}.sidebar-container,.toc-drawer{box-sizing:border-box;width:15em}.toc-drawer{background:var(--color-toc-background);padding-right:1rem}.sidebar-sticky,.toc-sticky{display:flex;flex-direction:column;height:min(100%,100vh);height:100vh;position:sticky;top:0}.sidebar-scroll,.toc-scroll{flex-grow:1;flex-shrink:1;overflow:auto;scroll-behavior:smooth}.content{display:flex;flex-direction:column;justify-content:space-between;padding:0 3em;width:46em}.icon{display:inline-block;height:1rem;width:1rem}.icon svg{height:100%;width:100%}.announcement{align-items:center;background-color:var(--color-announcement-background);color:var(--color-announcement-text);display:flex;height:var(--header-height);overflow-x:auto}.announcement+.page{min-height:calc(100% - var(--header-height))}.announcement-content{box-sizing:border-box;min-width:100%;padding:.5rem;text-align:center;white-space:nowrap}.announcement-content a{color:var(--color-announcement-text);text-decoration-color:var(--color-announcement-text)}.announcement-content a:hover{color:var(--color-announcement-text);text-decoration-color:var(--color-link--hover)}.no-js .theme-toggle-container{display:none}.theme-toggle-container{vertical-align:middle}.theme-toggle{background:transparent;border:none;cursor:pointer;padding:0}.theme-toggle svg{color:var(--color-foreground-primary);display:none;height:1.25rem;vertical-align:middle;width:1.25rem}.theme-toggle-header{float:left;padding:1rem .5rem}.nav-overlay-icon,.toc-overlay-icon{cursor:pointer;display:none}.nav-overlay-icon .icon,.toc-overlay-icon .icon{color:var(--color-foreground-secondary);height:1.25rem;width:1.25rem}.nav-overlay-icon,.toc-header-icon{align-items:center;justify-content:center}.toc-content-icon{height:1.5rem;width:1.5rem}.content-icon-container{display:flex;float:right;gap:.5rem;margin-bottom:1rem;margin-left:1rem;margin-top:1.5rem}.content-icon-container .edit-this-page svg,.content-icon-container .view-this-page svg{color:inherit;height:1.25rem;width:1.25rem}.sidebar-toggle{display:none;position:absolute}.sidebar-toggle[name=__toc]{left:20px}.sidebar-toggle:checked{left:40px}.overlay{background-color:rgba(0,0,0,.54);height:0;opacity:0;position:fixed;top:0;transition:width 0ms,height 0ms,opacity .25s ease-out;width:0}.sidebar-overlay{z-index:20}.toc-overlay{z-index:40}.sidebar-drawer{transition:left .25s ease-in-out;z-index:30}.toc-drawer{transition:right .25s ease-in-out;z-index:50}#__navigation:checked~.sidebar-overlay{height:100%;opacity:1;width:100%}#__navigation:checked~.page .sidebar-drawer{left:0;top:0}#__toc:checked~.toc-overlay{height:100%;opacity:1;width:100%}#__toc:checked~.page .toc-drawer{right:0;top:0}.back-to-top{background:var(--color-background-primary);border-radius:1rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 1px 0 hsla(220,9%,46%,.502);display:none;font-size:.8125rem;left:0;margin-left:50%;padding:.5rem .75rem .5rem .5rem;position:fixed;text-decoration:none;top:1rem;transform:translateX(-50%);z-index:10}.back-to-top svg{height:1rem;width:1rem;fill:currentColor;display:inline-block}.back-to-top span{margin-left:.25rem}.show-back-to-top .back-to-top{align-items:center;display:flex}@media(min-width:97em){html{font-size:110%}}@media(max-width:82em){.toc-content-icon{display:flex}.toc-drawer{border-left:1px solid var(--color-background-muted);height:100vh;position:fixed;right:-15em;top:0}.toc-tree{border-left:none;font-size:var(--toc-font-size--mobile)}.sidebar-drawer{width:calc(50% - 18.5em)}}@media(max-width:67em){.nav-overlay-icon{display:flex}.sidebar-drawer{height:100vh;left:-15em;position:fixed;top:0;width:15em}.toc-header-icon{display:flex}.theme-toggle-content,.toc-content-icon{display:none}.theme-toggle-header{display:block}.mobile-header{align-items:center;display:flex;justify-content:space-between;position:sticky;top:0}.mobile-header .header-left,.mobile-header .header-right{display:flex;height:var(--header-height);padding:0 var(--header-padding)}.mobile-header .header-left label,.mobile-header .header-right label{height:100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:100%}.nav-overlay-icon .icon,.theme-toggle svg{height:1.25rem;width:1.25rem}:target{scroll-margin-top:calc(var(--header-height) + 2.5rem)}.back-to-top{top:calc(var(--header-height) + .5rem)}.page{flex-direction:column;justify-content:center}.content{margin-left:auto;margin-right:auto}}@media(max-width:52em){.content{overflow-x:auto;width:100%}}@media(max-width:46em){.content{padding:0 1em}article aside.sidebar{float:none;margin:1rem 0;width:100%}}.admonition,.topic{background:var(--color-admonition-background);border-radius:.2rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1);font-size:var(--admonition-font-size);margin:1rem auto;overflow:hidden;padding:0 .5rem .5rem;page-break-inside:avoid}.admonition>:nth-child(2),.topic>:nth-child(2){margin-top:0}.admonition>:last-child,.topic>:last-child{margin-bottom:0}.admonition p.admonition-title,p.topic-title{font-size:var(--admonition-title-font-size);font-weight:500;line-height:1.3;margin:0 -.5rem .5rem;padding:.4rem .5rem .4rem 2rem;position:relative}.admonition p.admonition-title:before,p.topic-title:before{content:"";height:1rem;left:.5rem;position:absolute;width:1rem}p.admonition-title{background-color:var(--color-admonition-title-background)}p.admonition-title:before{background-color:var(--color-admonition-title);-webkit-mask-image:var(--icon-admonition-default);mask-image:var(--icon-admonition-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}p.topic-title{background-color:var(--color-topic-title-background)}p.topic-title:before{background-color:var(--color-topic-title);-webkit-mask-image:var(--icon-topic-default);mask-image:var(--icon-topic-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}.admonition{border-left:.2rem solid var(--color-admonition-title)}.admonition.caution{border-left-color:var(--color-admonition-title--caution)}.admonition.caution>.admonition-title{background-color:var(--color-admonition-title-background--caution)}.admonition.caution>.admonition-title:before{background-color:var(--color-admonition-title--caution);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.warning{border-left-color:var(--color-admonition-title--warning)}.admonition.warning>.admonition-title{background-color:var(--color-admonition-title-background--warning)}.admonition.warning>.admonition-title:before{background-color:var(--color-admonition-title--warning);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.danger{border-left-color:var(--color-admonition-title--danger)}.admonition.danger>.admonition-title{background-color:var(--color-admonition-title-background--danger)}.admonition.danger>.admonition-title:before{background-color:var(--color-admonition-title--danger);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.attention{border-left-color:var(--color-admonition-title--attention)}.admonition.attention>.admonition-title{background-color:var(--color-admonition-title-background--attention)}.admonition.attention>.admonition-title:before{background-color:var(--color-admonition-title--attention);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.error{border-left-color:var(--color-admonition-title--error)}.admonition.error>.admonition-title{background-color:var(--color-admonition-title-background--error)}.admonition.error>.admonition-title:before{background-color:var(--color-admonition-title--error);-webkit-mask-image:var(--icon-failure);mask-image:var(--icon-failure)}.admonition.hint{border-left-color:var(--color-admonition-title--hint)}.admonition.hint>.admonition-title{background-color:var(--color-admonition-title-background--hint)}.admonition.hint>.admonition-title:before{background-color:var(--color-admonition-title--hint);-webkit-mask-image:var(--icon-question);mask-image:var(--icon-question)}.admonition.tip{border-left-color:var(--color-admonition-title--tip)}.admonition.tip>.admonition-title{background-color:var(--color-admonition-title-background--tip)}.admonition.tip>.admonition-title:before{background-color:var(--color-admonition-title--tip);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.important{border-left-color:var(--color-admonition-title--important)}.admonition.important>.admonition-title{background-color:var(--color-admonition-title-background--important)}.admonition.important>.admonition-title:before{background-color:var(--color-admonition-title--important);-webkit-mask-image:var(--icon-flame);mask-image:var(--icon-flame)}.admonition.note{border-left-color:var(--color-admonition-title--note)}.admonition.note>.admonition-title{background-color:var(--color-admonition-title-background--note)}.admonition.note>.admonition-title:before{background-color:var(--color-admonition-title--note);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition.seealso{border-left-color:var(--color-admonition-title--seealso)}.admonition.seealso>.admonition-title{background-color:var(--color-admonition-title-background--seealso)}.admonition.seealso>.admonition-title:before{background-color:var(--color-admonition-title--seealso);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.admonition-todo{border-left-color:var(--color-admonition-title--admonition-todo)}.admonition.admonition-todo>.admonition-title{background-color:var(--color-admonition-title-background--admonition-todo)}.admonition.admonition-todo>.admonition-title:before{background-color:var(--color-admonition-title--admonition-todo);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition-todo>.admonition-title{text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd{margin-left:2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:first-child{margin-top:.125rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list,dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:last-child{margin-bottom:.75rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list>dt{font-size:var(--font-size--small);text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd:empty{margin-bottom:.5rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul{margin-left:-1.2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p:nth-child(2){margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p+p:last-child:empty{margin-bottom:0;margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{color:var(--color-api-overall)}.sig:not(.sig-inline){background:var(--color-api-background);border-radius:.25rem;font-family:var(--font-stack--monospace);font-size:var(--api-font-size);font-weight:700;margin-left:-.25rem;margin-right:-.25rem;padding:.25rem .5rem .25rem 3em;text-indent:-2.5em;transition:background .1s ease-out}.sig:not(.sig-inline):hover{background:var(--color-api-background-hover)}.sig:not(.sig-inline) a.reference .viewcode-link{font-weight:400;width:4.25rem}em.property{font-style:normal}em.property:first-child{color:var(--color-api-keyword)}.sig-name{color:var(--color-api-name)}.sig-prename{color:var(--color-api-pre-name);font-weight:400}.sig-paren{color:var(--color-api-paren)}.sig-param{font-style:normal}div.deprecated,div.versionadded,div.versionchanged,div.versionremoved{border-left:.1875rem solid;border-radius:.125rem;padding-left:.75rem}div.deprecated p,div.versionadded p,div.versionchanged p,div.versionremoved p{margin-bottom:.125rem;margin-top:.125rem}div.versionadded{border-color:var(--color-api-added-border)}div.versionadded .versionmodified{color:var(--color-api-added)}div.versionchanged{border-color:var(--color-api-changed-border)}div.versionchanged .versionmodified{color:var(--color-api-changed)}div.deprecated{border-color:var(--color-api-deprecated-border)}div.deprecated .versionmodified{color:var(--color-api-deprecated)}div.versionremoved{border-color:var(--color-api-removed-border)}div.versionremoved .versionmodified{color:var(--color-api-removed)}.viewcode-back,.viewcode-link{float:right;text-align:right}.line-block{margin-bottom:.75rem;margin-top:.5rem}.line-block .line-block{margin-bottom:0;margin-top:0;padding-left:1rem}.code-block-caption,article p.caption,table>caption{font-size:var(--font-size--small);text-align:center}.toctree-wrapper.compound .caption,.toctree-wrapper.compound :not(.caption)>.caption-text{font-size:var(--font-size--small);margin-bottom:0;text-align:initial;text-transform:uppercase}.toctree-wrapper.compound>ul{margin-bottom:0;margin-top:0}.sig-inline,code.literal{background:var(--color-inline-code-background);border-radius:.2em;font-size:var(--font-size--small--2);padding:.1em .2em}pre.literal-block .sig-inline,pre.literal-block code.literal{font-size:inherit;padding:0}p .sig-inline,p code.literal{border:1px solid var(--color-background-border)}.sig-inline{font-family:var(--font-stack--monospace)}div[class*=" highlight-"],div[class^=highlight-]{display:flex;margin:1em 0}div[class*=" highlight-"] .table-wrapper,div[class^=highlight-] .table-wrapper,pre{margin:0;padding:0}pre{overflow:auto}article[role=main] .highlight pre{line-height:1.5}.highlight pre,pre.literal-block{font-size:var(--code-font-size);padding:.625rem .875rem}pre.literal-block{background-color:var(--color-code-background);border-radius:.2rem;color:var(--color-code-foreground);margin-bottom:1rem;margin-top:1rem}.highlight{border-radius:.2rem;width:100%}.highlight .gp,.highlight span.linenos{pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.highlight .hll{display:block;margin-left:-.875rem;margin-right:-.875rem;padding-left:.875rem;padding-right:.875rem}.code-block-caption{background-color:var(--color-code-background);border-bottom:1px solid;border-radius:.25rem;border-bottom-left-radius:0;border-bottom-right-radius:0;border-color:var(--color-background-border);color:var(--color-code-foreground);display:flex;font-weight:300;padding:.625rem .875rem}.code-block-caption+div[class]{margin-top:0}.code-block-caption+div[class] pre{border-top-left-radius:0;border-top-right-radius:0}.highlighttable{display:block;width:100%}.highlighttable tbody{display:block}.highlighttable tr{display:flex}.highlighttable td.linenos{background-color:var(--color-code-background);border-bottom-left-radius:.2rem;border-top-left-radius:.2rem;color:var(--color-code-foreground);padding:.625rem 0 .625rem .875rem}.highlighttable .linenodiv{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;font-size:var(--code-font-size);padding-right:.875rem}.highlighttable td.code{display:block;flex:1;overflow:hidden;padding:0}.highlighttable td.code .highlight{border-bottom-left-radius:0;border-top-left-radius:0}.highlight span.linenos{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;display:inline-block;margin-right:.875rem;padding-left:0;padding-right:.875rem}.footnote-reference{font-size:var(--font-size--small--4);vertical-align:super}dl.footnote.brackets{color:var(--color-foreground-secondary);display:grid;font-size:var(--font-size--small);grid-template-columns:max-content auto}dl.footnote.brackets dt{margin:0}dl.footnote.brackets dt>.fn-backref{margin-left:.25rem}dl.footnote.brackets dt:after{content:":"}dl.footnote.brackets dt .brackets:before{content:"["}dl.footnote.brackets dt .brackets:after{content:"]"}dl.footnote.brackets dd{margin:0;padding:0 1rem}aside.footnote{color:var(--color-foreground-secondary);font-size:var(--font-size--small)}aside.footnote>span,div.citation>span{float:left;font-weight:500;padding-right:.25rem}aside.footnote>:not(span),div.citation>p{margin-left:2rem}img{box-sizing:border-box;height:auto;max-width:100%}article .figure,article figure{border-radius:.2rem;margin:0}article .figure :last-child,article figure :last-child{margin-bottom:0}article .align-left{clear:left;float:left;margin:0 1rem 1rem}article .align-right{clear:right;float:right;margin:0 1rem 1rem}article .align-center,article .align-default{display:block;margin-left:auto;margin-right:auto;text-align:center}article table.align-default{display:table;text-align:initial}.domainindex-jumpbox,.genindex-jumpbox{border-bottom:1px solid var(--color-background-border);border-top:1px solid var(--color-background-border);padding:.25rem}.domainindex-section h2,.genindex-section h2{margin-bottom:.5rem;margin-top:.75rem}.domainindex-section ul,.genindex-section ul{margin-bottom:0;margin-top:0}ol,ul{margin-bottom:1rem;margin-top:1rem;padding-left:1.2rem}ol li>p:first-child,ul li>p:first-child{margin-bottom:.25rem;margin-top:.25rem}ol li>p:last-child,ul li>p:last-child{margin-top:.25rem}ol li>ol,ol li>ul,ul li>ol,ul li>ul{margin-bottom:.5rem;margin-top:.5rem}ol.arabic{list-style:decimal}ol.loweralpha{list-style:lower-alpha}ol.upperalpha{list-style:upper-alpha}ol.lowerroman{list-style:lower-roman}ol.upperroman{list-style:upper-roman}.simple li>ol,.simple li>ul,.toctree-wrapper li>ol,.toctree-wrapper li>ul{margin-bottom:0;margin-top:0}.field-list dt,.option-list dt,dl.footnote dt,dl.glossary dt,dl.simple dt,dl:not([class]) dt{font-weight:500;margin-top:.25rem}.field-list dt+dt,.option-list dt+dt,dl.footnote dt+dt,dl.glossary dt+dt,dl.simple dt+dt,dl:not([class]) dt+dt{margin-top:0}.field-list dt .classifier:before,.option-list dt .classifier:before,dl.footnote dt .classifier:before,dl.glossary dt .classifier:before,dl.simple dt .classifier:before,dl:not([class]) dt .classifier:before{content:":";margin-left:.2rem;margin-right:.2rem}.field-list dd ul,.field-list dd>p:first-child,.option-list dd ul,.option-list dd>p:first-child,dl.footnote dd ul,dl.footnote dd>p:first-child,dl.glossary dd ul,dl.glossary dd>p:first-child,dl.simple dd ul,dl.simple dd>p:first-child,dl:not([class]) dd ul,dl:not([class]) dd>p:first-child{margin-top:.125rem}.field-list dd ul,.option-list dd ul,dl.footnote dd ul,dl.glossary dd ul,dl.simple dd ul,dl:not([class]) dd ul{margin-bottom:.125rem}.math-wrapper{overflow-x:auto;width:100%}div.math{position:relative;text-align:center}div.math .headerlink,div.math:focus .headerlink{display:none}div.math:hover .headerlink{display:inline-block}div.math span.eqno{position:absolute;right:.5rem;top:50%;transform:translateY(-50%);z-index:1}abbr[title]{cursor:help}.problematic{color:var(--color-problematic)}kbd:not(.compound){background-color:var(--color-background-secondary);border:1px solid var(--color-foreground-border);border-radius:.2rem;box-shadow:0 .0625rem 0 rgba(0,0,0,.2),inset 0 0 0 .125rem var(--color-background-primary);color:var(--color-foreground-primary);display:inline-block;font-size:var(--font-size--small--3);margin:0 .2rem;padding:0 .2rem;vertical-align:text-bottom}blockquote{background:var(--color-background-secondary);border-left:4px solid var(--color-background-border);margin-left:0;margin-right:0;padding:.5rem 1rem}blockquote .attribution{font-weight:600;text-align:right}blockquote.highlights,blockquote.pull-quote{font-size:1.25em}blockquote.epigraph,blockquote.pull-quote{border-left-width:0;border-radius:.5rem}blockquote.highlights{background:transparent;border-left-width:0}p .reference img{vertical-align:middle}p.rubric{font-size:1.125em;font-weight:700;line-height:1.25}dd p.rubric{font-size:var(--font-size--small);font-weight:inherit;line-height:inherit;text-transform:uppercase}article .sidebar{background-color:var(--color-background-secondary);border:1px solid var(--color-background-border);border-radius:.2rem;clear:right;float:right;margin-left:1rem;margin-right:0;width:30%}article .sidebar>*{padding-left:1rem;padding-right:1rem}article .sidebar>ol,article .sidebar>ul{padding-left:2.2rem}article .sidebar .sidebar-title{border-bottom:1px solid var(--color-background-border);font-weight:500;margin:0;padding:.5rem 1rem}.table-wrapper{margin-bottom:.5rem;margin-top:1rem;overflow-x:auto;padding:.2rem .2rem .75rem;width:100%}table.docutils{border-collapse:collapse;border-radius:.2rem;border-spacing:0;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)}table.docutils th{background:var(--color-table-header-background)}table.docutils td,table.docutils th{border-bottom:1px solid var(--color-table-border);border-left:1px solid var(--color-table-border);border-right:1px solid var(--color-table-border);padding:0 .25rem}table.docutils td p,table.docutils th p{margin:.25rem}table.docutils td:first-child,table.docutils th:first-child{border-left:none}table.docutils td:last-child,table.docutils th:last-child{border-right:none}table.docutils td.text-left,table.docutils th.text-left{text-align:left}table.docutils td.text-right,table.docutils th.text-right{text-align:right}table.docutils td.text-center,table.docutils th.text-center{text-align:center}:target{scroll-margin-top:2.5rem}@media(max-width:67em){:target{scroll-margin-top:calc(2.5rem + var(--header-height))}section>span:target{scroll-margin-top:calc(2.8rem + var(--header-height))}}.headerlink{font-weight:100;-webkit-user-select:none;-moz-user-select:none;user-select:none}.code-block-caption>.headerlink,dl dt>.headerlink,figcaption p>.headerlink,h1>.headerlink,h2>.headerlink,h3>.headerlink,h4>.headerlink,h5>.headerlink,h6>.headerlink,p.caption>.headerlink,table>caption>.headerlink{margin-left:.5rem;visibility:hidden}.code-block-caption:hover>.headerlink,dl dt:hover>.headerlink,figcaption p:hover>.headerlink,h1:hover>.headerlink,h2:hover>.headerlink,h3:hover>.headerlink,h4:hover>.headerlink,h5:hover>.headerlink,h6:hover>.headerlink,p.caption:hover>.headerlink,table>caption:hover>.headerlink{visibility:visible}.code-block-caption>.toc-backref,dl dt>.toc-backref,figcaption p>.toc-backref,h1>.toc-backref,h2>.toc-backref,h3>.toc-backref,h4>.toc-backref,h5>.toc-backref,h6>.toc-backref,p.caption>.toc-backref,table>caption>.toc-backref{color:inherit;text-decoration-line:none}figure:hover>figcaption>p>.headerlink,table:hover>caption>.headerlink{visibility:visible}:target>h1:first-of-type,:target>h2:first-of-type,:target>h3:first-of-type,:target>h4:first-of-type,:target>h5:first-of-type,:target>h6:first-of-type,span:target~h1:first-of-type,span:target~h2:first-of-type,span:target~h3:first-of-type,span:target~h4:first-of-type,span:target~h5:first-of-type,span:target~h6:first-of-type{background-color:var(--color-highlight-on-target)}:target>h1:first-of-type code.literal,:target>h2:first-of-type code.literal,:target>h3:first-of-type code.literal,:target>h4:first-of-type code.literal,:target>h5:first-of-type code.literal,:target>h6:first-of-type code.literal,span:target~h1:first-of-type code.literal,span:target~h2:first-of-type code.literal,span:target~h3:first-of-type code.literal,span:target~h4:first-of-type code.literal,span:target~h5:first-of-type code.literal,span:target~h6:first-of-type code.literal{background-color:transparent}.literal-block-wrapper:target .code-block-caption,.this-will-duplicate-information-and-it-is-still-useful-here li :target,figure:target,table:target>caption{background-color:var(--color-highlight-on-target)}dt:target{background-color:var(--color-highlight-on-target)!important}.footnote-reference:target,.footnote>dt:target+dd{background-color:var(--color-highlight-on-target)}.guilabel{background-color:var(--color-guilabel-background);border:1px solid var(--color-guilabel-border);border-radius:.5em;color:var(--color-guilabel-text);font-size:.9em;padding:0 .3em}footer{display:flex;flex-direction:column;font-size:var(--font-size--small);margin-top:2rem}.bottom-of-page{align-items:center;border-top:1px solid var(--color-background-border);color:var(--color-foreground-secondary);display:flex;justify-content:space-between;line-height:1.5;margin-top:1rem;padding-bottom:1rem;padding-top:1rem}@media(max-width:46em){.bottom-of-page{flex-direction:column-reverse;gap:.25rem;text-align:center}}.bottom-of-page .left-details{font-size:var(--font-size--small)}.bottom-of-page .right-details{display:flex;flex-direction:column;gap:.25rem;text-align:right}.bottom-of-page .icons{display:flex;font-size:1rem;gap:.25rem;justify-content:flex-end}.bottom-of-page .icons a{text-decoration:none}.bottom-of-page .icons img,.bottom-of-page .icons svg{font-size:1.125rem;height:1em;width:1em}.related-pages a{align-items:center;display:flex;text-decoration:none}.related-pages a:hover .page-info .title{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}.related-pages a svg.furo-related-icon,.related-pages a svg.furo-related-icon>use{color:var(--color-foreground-border);flex-shrink:0;height:.75rem;margin:0 .5rem;width:.75rem}.related-pages a.next-page{clear:right;float:right;max-width:50%;text-align:right}.related-pages a.prev-page{clear:left;float:left;max-width:50%}.related-pages a.prev-page svg{transform:rotate(180deg)}.page-info{display:flex;flex-direction:column;overflow-wrap:anywhere}.next-page .page-info{align-items:flex-end}.page-info .context{align-items:center;color:var(--color-foreground-muted);display:flex;font-size:var(--font-size--small);padding-bottom:.1rem;text-decoration:none}ul.search{list-style:none;padding-left:0}ul.search li{border-bottom:1px solid var(--color-background-border);padding:1rem 0}[role=main] .highlighted{background-color:var(--color-highlighted-background);color:var(--color-highlighted-text)}.sidebar-brand{display:flex;flex-direction:column;flex-shrink:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none}.sidebar-brand-text{color:var(--color-sidebar-brand-text);font-size:1.5rem;overflow-wrap:break-word}.sidebar-brand-text,.sidebar-logo-container{margin:var(--sidebar-item-spacing-vertical) 0}.sidebar-logo{display:block;margin:0 auto;max-width:100%}.sidebar-search-container{align-items:center;background:var(--color-sidebar-search-background);display:flex;margin-top:var(--sidebar-search-space-above);position:relative}.sidebar-search-container:focus-within,.sidebar-search-container:hover{background:var(--color-sidebar-search-background--focus)}.sidebar-search-container:before{background-color:var(--color-sidebar-search-icon);content:"";height:var(--sidebar-search-icon-size);left:var(--sidebar-item-spacing-horizontal);-webkit-mask-image:var(--icon-search);mask-image:var(--icon-search);position:absolute;width:var(--sidebar-search-icon-size)}.sidebar-search{background:transparent;border:none;border-bottom:1px solid var(--color-sidebar-search-border);border-top:1px solid var(--color-sidebar-search-border);box-sizing:border-box;color:var(--color-sidebar-search-foreground);padding:var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal) var(--sidebar-search-input-spacing-vertical) calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size));width:100%;z-index:10}.sidebar-search:focus{outline:none}.sidebar-search::-moz-placeholder{font-size:var(--sidebar-search-input-font-size)}.sidebar-search::placeholder{font-size:var(--sidebar-search-input-font-size)}#searchbox .highlight-link{margin:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0;text-align:center}#searchbox .highlight-link a{color:var(--color-sidebar-search-icon);font-size:var(--font-size--small--2)}.sidebar-tree{font-size:var(--sidebar-item-font-size);margin-bottom:var(--sidebar-item-spacing-vertical);margin-top:var(--sidebar-tree-space-above)}.sidebar-tree ul{display:flex;flex-direction:column;list-style:none;margin-bottom:0;margin-top:0;padding:0}.sidebar-tree li{margin:0;position:relative}.sidebar-tree li>ul{margin-left:var(--sidebar-item-spacing-horizontal)}.sidebar-tree .icon,.sidebar-tree .reference{color:var(--color-sidebar-link-text)}.sidebar-tree .reference{box-sizing:border-box;display:inline-block;height:100%;line-height:var(--sidebar-item-line-height);overflow-wrap:anywhere;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none;width:100%}.sidebar-tree .reference:hover{background:var(--color-sidebar-item-background--hover);color:var(--color-sidebar-link-text)}.sidebar-tree .reference.external:after{color:var(--color-sidebar-link-text);content:url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' fill='none' stroke='%23607D8B' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' viewBox='0 0 24 24'%3E%3Cpath stroke='none' d='M0 0h24v24H0z'/%3E%3Cpath d='M11 7H6a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2-2v-5M10 14 20 4M15 4h5v5'/%3E%3C/svg%3E");margin:0 .25rem;vertical-align:middle}.sidebar-tree .current-page>.reference{font-weight:700}.sidebar-tree label{align-items:center;cursor:pointer;display:flex;height:var(--sidebar-item-height);justify-content:center;position:absolute;right:0;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:var(--sidebar-expander-width)}.sidebar-tree .caption,.sidebar-tree :not(.caption)>.caption-text{color:var(--color-sidebar-caption-text);font-size:var(--sidebar-caption-font-size);font-weight:700;margin:var(--sidebar-caption-space-above) 0 0 0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-transform:uppercase}.sidebar-tree li.has-children>.reference{padding-right:var(--sidebar-expander-width)}.sidebar-tree .toctree-l1>.reference,.sidebar-tree .toctree-l1>label .icon{color:var(--color-sidebar-link-text--top-level)}.sidebar-tree label{background:var(--color-sidebar-item-expander-background)}.sidebar-tree label:hover{background:var(--color-sidebar-item-expander-background--hover)}.sidebar-tree .current>.reference{background:var(--color-sidebar-item-background--current)}.sidebar-tree .current>.reference:hover{background:var(--color-sidebar-item-background--hover)}.toctree-checkbox{display:none;position:absolute}.toctree-checkbox~ul{display:none}.toctree-checkbox~label .icon svg{transform:rotate(90deg)}.toctree-checkbox:checked~ul{display:block}.toctree-checkbox:checked~label .icon svg{transform:rotate(-90deg)}.toc-title-container{padding:var(--toc-title-padding);padding-top:var(--toc-spacing-vertical)}.toc-title{color:var(--color-toc-title-text);font-size:var(--toc-title-font-size);padding-left:var(--toc-spacing-horizontal);text-transform:uppercase}.no-toc{display:none}.toc-tree-container{padding-bottom:var(--toc-spacing-vertical)}.toc-tree{border-left:1px solid var(--color-background-border);font-size:var(--toc-font-size);line-height:1.3;padding-left:calc(var(--toc-spacing-horizontal) - var(--toc-item-spacing-horizontal))}.toc-tree>ul>li:first-child{padding-top:0}.toc-tree>ul>li:first-child>ul{padding-left:0}.toc-tree>ul>li:first-child>a{display:none}.toc-tree ul{list-style-type:none;margin-bottom:0;margin-top:0;padding-left:var(--toc-item-spacing-horizontal)}.toc-tree li{padding-top:var(--toc-item-spacing-vertical)}.toc-tree li.scroll-current>.reference{color:var(--color-toc-item-text--active);font-weight:700}.toc-tree a.reference{color:var(--color-toc-item-text);overflow-wrap:anywhere;text-decoration:none}.toc-scroll{max-height:100vh;overflow-y:scroll}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here){background:rgba(255,0,0,.25);color:var(--color-problematic)}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here):before{content:"ERROR: Adding a table of contents in Furo-based documentation is unnecessary, and does not work well with existing styling. Add a 'this-will-duplicate-information-and-it-is-still-useful-here' class, if you want an escape hatch."}.text-align\:left>p{text-align:left}.text-align\:center>p{text-align:center}.text-align\:right>p{text-align:right} +/*# sourceMappingURL=furo.css.map*/ \ No newline at end of file diff --git a/pull/1473/_static/styles/furo.css.map b/pull/1473/_static/styles/furo.css.map new file mode 100644 index 0000000000..6e02d0b1aa --- /dev/null +++ b/pull/1473/_static/styles/furo.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo.css","mappings":"AAAA,2EAA2E,CAU3E,KACE,gBAAiB,CACjB,6BACF,CASA,KACE,QACF,CAMA,KACE,aACF,CAOA,GACE,aAAc,CACd,cACF,CAUA,GACE,sBAAuB,CACvB,QAAS,CACT,gBACF,CAOA,IACE,+BAAiC,CACjC,aACF,CASA,EACE,4BACF,CAOA,YACE,kBAAmB,CACnB,yBAA0B,CAC1B,gCACF,CAMA,SAEE,kBACF,CAOA,cAGE,+BAAiC,CACjC,aACF,CAeA,QAEE,aAAc,CACd,aAAc,CACd,iBAAkB,CAClB,uBACF,CAEA,IACE,aACF,CAEA,IACE,SACF,CASA,IACE,iBACF,CAUA,sCAKE,mBAAoB,CACpB,cAAe,CACf,gBAAiB,CACjB,QACF,CAOA,aAEE,gBACF,CAOA,cAEE,mBACF,CAMA,gDAIE,yBACF,CAMA,wHAIE,iBAAkB,CAClB,SACF,CAMA,4GAIE,6BACF,CAMA,SACE,0BACF,CASA,OACE,qBAAsB,CACtB,aAAc,CACd,aAAc,CACd,cAAe,CACf,SAAU,CACV,kBACF,CAMA,SACE,uBACF,CAMA,SACE,aACF,CAOA,6BAEE,qBAAsB,CACtB,SACF,CAMA,kFAEE,WACF,CAOA,cACE,4BAA6B,CAC7B,mBACF,CAMA,yCACE,uBACF,CAOA,6BACE,yBAA0B,CAC1B,YACF,CASA,QACE,aACF,CAMA,QACE,iBACF,CAiBA,kBACE,YACF,CCvVA,aAcE,kEACE,uBAOF,WACE,iDAMF,gCACE,wBAEF,qCAEE,uBADA,uBACA,CAEF,SACE,wBAtBA,CCpBJ,iBAGE,qBAEA,sBACA,0BAFA,oBAHA,4BACA,oBAKA,6BAIA,2CAFA,mBACA,sCAFA,4BAGA,CAEF,gBACE,aCTF,KCGE,mHAEA,wGAEA,wCAAyC,CAEzC,wBAAyB,CACzB,wBAAyB,CACzB,4BAA6B,CAC7B,yBAA0B,CAC1B,2BAA4B,CAG5B,sDAAuD,CACvD,gDAAiD,CACjD,wDAAyD,CAGzD,0CAA2C,CAC3C,gDAAiD,CACjD,gDAAiD,CAKjD,gCAAiC,CACjC,sCAAuC,CAGvC,2CAA4C,CAG5C,uCAAwC,CCjCxC,+FAGA,uBAAwB,CAGxB,iCAAkC,CAClC,kCAAmC,CAEnC,+BAAgC,CAChC,sCAAuC,CACvC,sCAAuC,CACvC,qGAIA,mDAAoD,CAEpD,mCAAoC,CACpC,8CAA+C,CAC/C,gDAAiD,CACjD,kCAAmC,CACnC,6DAA8D,CAG9D,6BAA8B,CAC9B,6BAA8B,CAC9B,+BAAgC,CAChC,kCAAmC,CACnC,kCAAmC,CCPjC,+jBCYA,iqCAZF,iaCVA,8KAOA,4SAWA,4SAUA,0CACA,gEAGA,0CAGA,gEAGA,yCACA,+DAIA,4CACA,kEAGA,wCAUA,8DACA,uCAGA,4DACA,sCACA,2DAGA,4CACA,kEACA,uCAGA,6DACA,2GAGA,sHAEA,yFAEA,+CACA,+EAGA,4MAOA,gCACA,sHAIA,kCACA,uEACA,gEACA,4DACA,kEAGA,2DACA,sDACA,0CACA,8CACA,wGAGA,0BACA,iCAGA,+DACA,+BACA,sCACA,+DAEA,kGACA,oCACA,yDACA,sCL7HF,kCAEA,sDAIA,0CK2HE,kEAIA,oDACA,sDAGA,oCACA,oEAEA,0DACA,qDAIA,oDACA,6DAIA,iEAIA,2DAIA,2DAGA,4DACA,gEAIA,gEAEA,gFAEA,oNASA,qDLxKE,gFAGE,4DAIF,oEKkHF,yEAEA,6DAGA,0DAEA,uDACA,qDACA,wDAIA,6DAIA,yDACA,2DAIA,uCAGA,wCACA,sDAGA,+CAGA,6DAEA,iDACA,+DAEA,wDAEA,sEAMA,0DACA,sBACA,mEL9JI,wEAEA,iCACE,+BAMN,wEAGA,iCACE,kFAEA,uEAIF,gEACE,8BAGF,qEMvDA,sCAKA,wFAKA,iCAIA,0BAWA,iCACA,4BACA,mCAGA,+BAEA,sCACA,4BAEA,mCAEA,sCAKA,sDAIA,gCAEA,gEAQF,wCAME,sBACA,kCAKA,uBAEA,gEAIA,2BAIA,mCAEA,qCACA,iCAGE,+BACA,wEAEE,iCACA,kFAGF,6BACA,0CACF,kCAEE,8BACE,8BACA,qEAEE,sCACA,wFCjFN,iCAGF,2DAEE,4BACA,oCAGA,mIAGA,4HACE,gEAMJ,+CAGE,sBACA,yCAEF,uBAEE,sEAKA,gDACA,kEAGA,iFAGE,YAGF,EACA,4HAQF,mBACE,6BACA,mBACA,wCACA,wCACA,2CAIA,eAGA,mBAKE,mBAGA,CAJA,uCACA,iBAFF,gBACE,CAKE,mBACA,mBAGJ,oBAIF,+BAGE,kDACA,OADA,kBAGA,CAFA,gBAEA,mBACA,oBAEA,sCACA,OAGF,cAHE,WAGF,GAEE,oBACA,CAHF,gBAGE,CChHc,YDmHd,+CAIF,SAEE,CAPF,UACE,wBAMA,4BAEA,GAGA,uBACA,CAJA,yBAGA,CACA,iDAKA,2CAGA,2DAQA,iBACA,uCAGA,kEAKE,SAKJ,8BACE,yDACA,2BAEA,oBACA,8BAEA,yDAEE,4BAEJ,uCACE,CACA,iEAGA,CAEA,wCACE,uBACA,kDAEA,0DAEE,CAJF,oBAIE,0GASJ,aAEF,CAFE,YAEF,4HASE,+CACA,sBAGF,sBASE,4BAFF,0CAEE,CARA,qCAwBF,CAhBE,iBAEA,kBACE,aADF,4BACE,WAOF,2BAEF,qCAIA,CAbI,UAaJ,+BACE,uBAEA,SAGA,0CAGE,CANF,qCAGA,CAGE,2DACE,gBAKJ,+CAGF,CAEA,kDAME,CARF,8BAEA,CAQE,YAEA,CAlBI,2BAGJ,CAJI,UACA,CAcJ,UAIA,4GAIF,iCAGE,8BAIA,qBACA,mBACF,QACE,gBAOE,0CAGA,CATF,6DAME,CANF,sBASE,qCAKF,CAEE,cACA,CAHF,sBAGE,gCAEA,qBAOJ,wBACE,sCAIA,mBAEA,6BAKA,kCACA,CAHA,sBAEA,cAJA,eACA,MAIA,2FAIA,UACA,YACA,sBACE,8BAEA,CALF,aACA,WAIE,CACA,0BAEF,aACE,qBAEF,qCAgBA,kBACE,CAhBA,qDASA,qCAEJ,CAGI,YACF,CAJF,2BAGI,CAGA,eACE,CAAF,oBAEA,mEAEA,qBACA,eAGF,CAHE,cAIA,kBADF,kBACE,yBAEJ,oCAGI,qDAIA,+BAMF,oCAEA,+CAEA,gCAIA,YACE,yBAEA,qBACA,eAGA,uBAFA,WAEA,CAHA,cACA,CAEA,4BAIE,qCACA,cAFA,eADA,qBACA,cAEA,mDACE,CACA,oCACA,4EAEN,uCAMA,eACE,kDAIA,mBADF,sBACE,mBAIA,aACA,sCAGA,aADA,WACA,CAMA,UAFF,kBAEE,CAJJ,gBAEE,CAJE,iBAMA,yFAQA,aACA,eEpbJ,cACE,iBACA,YAEA,CAFA,iBAEA,+DAGA,mBAKA,gCAGA,CARA,SAIA,SACA,CALA,0EAIA,CAJA,OAQA,0CACE,UAGF,iDAGF,CAHE,UAGF,8CAEE,CAFF,UAEE,CACA,uCAEA,WACA,WAFA,UAEA,6CAIA,yCACA,WAGA,WAJA,UAIA,gDACE,aASF,0CACE,CAFF,mBAEE,wEACA,CATA,YACA,CAKF,kBACA,CALE,MAGJ,CAII,eACA,CAJF,iCALE,cACA,CAHA,oBACA,CAKJ,SAKI,2BADA,UACA,6BAEJ,WACE,0DACA,kBACE,gCACA,mBADA,YACA,oEACA,2CAMF,mDAII,CAJJ,aADF,cACE,kBAII,kEACA,iBACE,mEACA,6BACE,wBADF,cACE,mCACA,qDANN,kCACE,6BAEE,mBADF,0CACE,CAFF,eACA,MACE,0DACA,wCACE,sGACA,WANN,yBACE,uCACA,CAFF,UAEE,2CACE,0FACA,cACE,kEACA,mEANN,yBACE,4DACA,sBACE,+EAEE,iEACA,qEANN,sCACE,CAGE,iBAHF,gBAGE,qBACE,CAJJ,uBACA,gDACE,wDACA,6DAHF,2CACA,CADA,gBACA,eACE,CAGE,sBANN,8BACE,CAII,iBAFF,4DACA,WACE,YADF,uCACE,6EACA,2BANN,8CACE,kDACA,0CACE,8BACA,yFACE,sBACA,sFALJ,mEACA,sBACE,kEACA,6EACE,uCACA,kEALJ,qGAEE,kEACA,6EACE,uCACA,kEALJ,8CACA,uDACE,sEACA,2EACE,sCACA,iEALJ,mGACA,qCACE,oDACA,0DACE,6GACA,gDAGR,yDCrEA,sEACE,CACA,6GACE,gEACF,iGAIF,wFACE,qDAGA,mGAEE,2CAEF,4FACE,gCACF,wGACE,8DAEE,6FAIA,iJAKN,6GACE,gDAKF,yDACA,qCAGA,6BACA,kBACA,qDAKA,oCAEA,+DAGA,2CAGE,oDAIA,oEAEE,qBAGJ,wDAEE,uCAEF,kEAGA,8CAEA,uDAIF,gEAIE,6BACA,gEAIA,+CACE,0EAIF,sDAEE,+DAGF,sCACA,8BACE,oCAEJ,wBACE,4FAEE,gBAEJ,yGAGI,kBAGJ,CCnHE,2MCFF,oBAGE,wGAKA,iCACE,CADF,wBACE,8GAQA,mBCjBJ,2GAIE,mBACA,6HAMA,YACE,mIAYF,eACA,CAHF,YAGE,4FAGE,8BAKF,uBAkBE,sCACA,CADA,qBAbA,wCAIA,CALF,8BACE,CADF,gBAKE,wCACA,CAOA,kDACA,CACA,kCAKF,6BAGA,4CACE,kDACA,eAGF,cACE,aACA,iBACA,yBACA,8BACA,WAGJ,2BACE,cAGA,+BACA,CAHA,eAGA,wCACA,YACA,iBACA,uEAGA,0BACA,2CAEA,8EAGI,qBACA,CAFF,kBAEE,kBAGN,0CAGE,mCAGA,4BAIA,gEACE,qCACA,8BAEA,gBACA,+CACA,iCAEF,iCAEE,gEACA,qCAGF,8BAEE,+BAIA,yCAEE,qBADA,gBACA,yBAKF,eACA,CAFF,YACE,CACA,iBACA,qDAEA,mDCvIJ,2FAOE,iCACA,CAEA,eACA,CAHA,kBAEA,CAFA,wBAGA,8BACA,eACE,CAFF,YAEE,0BACA,8CAGA,oBACE,oCAGA,kBACE,8DAEA,iBAEN,UACE,8BAIJ,+CAEE,qDAEF,kDAIE,YAEF,CAFE,YAEF,CCpCE,mFADA,kBAKE,CAJF,IAGA,aACE,mCAGA,iDACE,+BAEJ,wBAEE,mBAMA,6CAEF,CAJE,mBAEA,CAEF,kCAGE,CARF,kBACE,CAHA,eAUA,YACA,mBACA,CADA,UACA,wCC9BF,oBDkCE,wBCnCJ,uCACE,+BACA,+DACA,sBAGA,qBCDA,6CAIE,CAPF,uBAGA,CDGE,oBACF,yDAEE,CCDE,2CAGF,CAJA,kCACE,CDJJ,YACE,CAIA,eCTF,CDKE,uBCMA,gCACE,YAEF,oCAEE,wBACA,0BAIF,iBAEA,cADF,UACE,uBAEA,iCAEA,wCAEA,6CAMA,CAYF,gCATI,4BASJ,CAZE,mCAEE,iCAUJ,4BAGE,4DADA,+BACA,CAHF,qBAGE,sCACE,OAEF,iBAHA,SAGA,iHACE,2DAKF,CANA,8EAMA,uSAEE,kBAEF,+FACE,yCCjEJ,WACA,yBAGA,uBACA,gBAEA,uCAIA,CAJA,iCAIA,uCAGA,UACE,gBACA,qBAEA,0CClBJ,gBACE,KAGF,qBACE,YAGF,CAHE,cAGF,gCAEE,mBACA,iEAEA,oCACA,wCAEA,sBACA,WAEA,CAFA,YAEA,8EAEA,mCAFA,iBAEA,6BAIA,wEAKA,sDAIE,CARF,mDAIA,CAIE,cAEF,8CAIA,oBAFE,iBAEF,8CAGE,eAEF,CAFE,YAEF,OAEE,kBAGJ,CAJI,eACA,CAFF,mBAKF,yCCjDE,oBACA,CAFA,iBAEA,uCAKE,iBACA,qCAGA,mBCZJ,CDWI,gBCXJ,6BAEE,eACA,sBAGA,eAEA,sBACA,oDACA,iGAMA,gBAFE,YAEF,8FAME,iJClBF,YACA,gNAUE,6BAEF,oTAcI,kBACF,gHAIA,qBACE,eACF,qDACE,kBACF,6DACE,4BCxCJ,oBAEF,qCAEI,+CAGF,uBACE,uDAGJ,oBAiBI,kDACF,CAhBA,+CAaA,CAbA,oBAaA,0FAEE,CAFF,gGAdA,cACA,iBAaA,0BAGA,mQAIA,oNAEE,iBAGJ,CAHI,gBAFF,gBAKF,8CAYI,CAZJ,wCAYI,sVACE,iCAGA,uEAHA,QAGA,qXAKJ,iDAGF,CARM,+CACE,iDAIN,CALI,gBAQN,mHACE,gBAGF,2DACE,0EAOA,0EAGF,gBAEE,6DC/EA,kDACA,gCACA,qDAGA,qBACA,qDCFA,cACA,eAEA,yBAGF,sBAEE,iBACA,sNAWA,iBACE,kBACA,wRAgBA,kBAEA,iOAgBA,uCACE,uEAEA,kBAEF,qUAuBE,iDAIJ,CACA,geCxFF,4BAEE,CAQA,6JACA,iDAIA,sEAGA,mDAOF,iDAGE,4DAIA,8CACA,qDAEE,eAFF,cAEE,oBAEF,uBAFE,kCAGA,eACA,iBACA,mBAIA,mDACA,CAHA,uCAEA,CAJA,0CACA,CAIA,gBAJA,gBACA,oBADA,gBAIA,wBAEJ,gBAGE,6BACA,YAHA,iBAGA,gCACA,iEAEA,6CACA,sDACA,0BADA,wBACA,0BACA,oIAIA,mBAFA,YAEA,qBACA,0CAIE,uBAEF,CAHA,yBACE,CAEF,iDACE,mFAKJ,oCACE,CANE,aAKJ,CACE,qEAIA,YAFA,WAEA,CAHA,aACA,CAEA,gBACE,4BACA,sBADA,aACA,gCAMF,oCACA,yDACA,2CAEA,qBAGE,kBAEA,CACA,mCAIF,CARE,YACA,CAOF,iCAEE,CAPA,oBACA,CAQA,oBACE,uDAEJ,sDAGA,CAHA,cAGA,0BACE,oDAIA,oCACA,4BACA,sBAGA,cAEA,oFAGA,sBAEA,yDACE,CAIF,iBAJE,wBAIF,6CAHE,6CAKA,eACA,aACA,CADA,cACA,yCAGJ,kBACE,CAKA,iDAEA,CARF,aACE,4CAGA,kBAIA,wEAGA,wDAGA,kCAOA,iDAGA,CAPF,WAEE,sCAEA,CAJF,2CACE,CAMA,qCACA,+BARF,kBACE,qCAOA,iBAsBA,sBACE,CAvBF,WAKA,CACE,0DAIF,CALA,uDACE,CANF,sBAqBA,4CACA,CALA,gRAIA,YAEE,6CAEN,mCAEE,+CASA,6EAIA,4BChNA,SDmNA,qFCnNA,gDACA,sCAGA,qCACA,sDACA,CAKA,kDAGA,CARA,0CAQA,kBAGA,YACA,sBACA,iBAFA,gBADF,YACE,CAHA,SAKA,kBAEA,SAFA,iBAEA,uEAGA,CAEE,6CAFF,oCAgBI,CAdF,yBACE,qBACF,CAGF,oBACE,CAIF,WACE,CALA,2CAGA,uBACF,CACE,mFAGE,CALF,qBAEA,UAGE,gCAIF,sDAEA,CALE,oCAKF,yCC7CJ,oCACE,CD+CA,yXAQE,sCCrDJ,wCAGA,oCACE","sources":["webpack:///./node_modules/normalize.css/normalize.css","webpack:///./src/furo/assets/styles/base/_print.sass","webpack:///./src/furo/assets/styles/base/_screen-readers.sass","webpack:///./src/furo/assets/styles/base/_theme.sass","webpack:///./src/furo/assets/styles/variables/_fonts.scss","webpack:///./src/furo/assets/styles/variables/_spacing.scss","webpack:///./src/furo/assets/styles/variables/_icons.scss","webpack:///./src/furo/assets/styles/variables/_admonitions.scss","webpack:///./src/furo/assets/styles/variables/_colors.scss","webpack:///./src/furo/assets/styles/base/_typography.sass","webpack:///./src/furo/assets/styles/_scaffold.sass","webpack:///./src/furo/assets/styles/variables/_layout.scss","webpack:///./src/furo/assets/styles/content/_admonitions.sass","webpack:///./src/furo/assets/styles/content/_api.sass","webpack:///./src/furo/assets/styles/content/_blocks.sass","webpack:///./src/furo/assets/styles/content/_captions.sass","webpack:///./src/furo/assets/styles/content/_code.sass","webpack:///./src/furo/assets/styles/content/_footnotes.sass","webpack:///./src/furo/assets/styles/content/_images.sass","webpack:///./src/furo/assets/styles/content/_indexes.sass","webpack:///./src/furo/assets/styles/content/_lists.sass","webpack:///./src/furo/assets/styles/content/_math.sass","webpack:///./src/furo/assets/styles/content/_misc.sass","webpack:///./src/furo/assets/styles/content/_rubrics.sass","webpack:///./src/furo/assets/styles/content/_sidebar.sass","webpack:///./src/furo/assets/styles/content/_tables.sass","webpack:///./src/furo/assets/styles/content/_target.sass","webpack:///./src/furo/assets/styles/content/_gui-labels.sass","webpack:///./src/furo/assets/styles/components/_footer.sass","webpack:///./src/furo/assets/styles/components/_sidebar.sass","webpack:///./src/furo/assets/styles/components/_table_of_contents.sass","webpack:///./src/furo/assets/styles/_shame.sass"],"sourcesContent":["/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */\n\n/* Document\n ========================================================================== */\n\n/**\n * 1. Correct the line height in all browsers.\n * 2. Prevent adjustments of font size after orientation changes in iOS.\n */\n\nhtml {\n line-height: 1.15; /* 1 */\n -webkit-text-size-adjust: 100%; /* 2 */\n}\n\n/* Sections\n ========================================================================== */\n\n/**\n * Remove the margin in all browsers.\n */\n\nbody {\n margin: 0;\n}\n\n/**\n * Render the `main` element consistently in IE.\n */\n\nmain {\n display: block;\n}\n\n/**\n * Correct the font size and margin on `h1` elements within `section` and\n * `article` contexts in Chrome, Firefox, and Safari.\n */\n\nh1 {\n font-size: 2em;\n margin: 0.67em 0;\n}\n\n/* Grouping content\n ========================================================================== */\n\n/**\n * 1. Add the correct box sizing in Firefox.\n * 2. Show the overflow in Edge and IE.\n */\n\nhr {\n box-sizing: content-box; /* 1 */\n height: 0; /* 1 */\n overflow: visible; /* 2 */\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\npre {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/* Text-level semantics\n ========================================================================== */\n\n/**\n * Remove the gray background on active links in IE 10.\n */\n\na {\n background-color: transparent;\n}\n\n/**\n * 1. Remove the bottom border in Chrome 57-\n * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.\n */\n\nabbr[title] {\n border-bottom: none; /* 1 */\n text-decoration: underline; /* 2 */\n text-decoration: underline dotted; /* 2 */\n}\n\n/**\n * Add the correct font weight in Chrome, Edge, and Safari.\n */\n\nb,\nstrong {\n font-weight: bolder;\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\ncode,\nkbd,\nsamp {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/**\n * Add the correct font size in all browsers.\n */\n\nsmall {\n font-size: 80%;\n}\n\n/**\n * Prevent `sub` and `sup` elements from affecting the line height in\n * all browsers.\n */\n\nsub,\nsup {\n font-size: 75%;\n line-height: 0;\n position: relative;\n vertical-align: baseline;\n}\n\nsub {\n bottom: -0.25em;\n}\n\nsup {\n top: -0.5em;\n}\n\n/* Embedded content\n ========================================================================== */\n\n/**\n * Remove the border on images inside links in IE 10.\n */\n\nimg {\n border-style: none;\n}\n\n/* Forms\n ========================================================================== */\n\n/**\n * 1. Change the font styles in all browsers.\n * 2. Remove the margin in Firefox and Safari.\n */\n\nbutton,\ninput,\noptgroup,\nselect,\ntextarea {\n font-family: inherit; /* 1 */\n font-size: 100%; /* 1 */\n line-height: 1.15; /* 1 */\n margin: 0; /* 2 */\n}\n\n/**\n * Show the overflow in IE.\n * 1. Show the overflow in Edge.\n */\n\nbutton,\ninput { /* 1 */\n overflow: visible;\n}\n\n/**\n * Remove the inheritance of text transform in Edge, Firefox, and IE.\n * 1. Remove the inheritance of text transform in Firefox.\n */\n\nbutton,\nselect { /* 1 */\n text-transform: none;\n}\n\n/**\n * Correct the inability to style clickable types in iOS and Safari.\n */\n\nbutton,\n[type=\"button\"],\n[type=\"reset\"],\n[type=\"submit\"] {\n -webkit-appearance: button;\n}\n\n/**\n * Remove the inner border and padding in Firefox.\n */\n\nbutton::-moz-focus-inner,\n[type=\"button\"]::-moz-focus-inner,\n[type=\"reset\"]::-moz-focus-inner,\n[type=\"submit\"]::-moz-focus-inner {\n border-style: none;\n padding: 0;\n}\n\n/**\n * Restore the focus styles unset by the previous rule.\n */\n\nbutton:-moz-focusring,\n[type=\"button\"]:-moz-focusring,\n[type=\"reset\"]:-moz-focusring,\n[type=\"submit\"]:-moz-focusring {\n outline: 1px dotted ButtonText;\n}\n\n/**\n * Correct the padding in Firefox.\n */\n\nfieldset {\n padding: 0.35em 0.75em 0.625em;\n}\n\n/**\n * 1. Correct the text wrapping in Edge and IE.\n * 2. Correct the color inheritance from `fieldset` elements in IE.\n * 3. Remove the padding so developers are not caught out when they zero out\n * `fieldset` elements in all browsers.\n */\n\nlegend {\n box-sizing: border-box; /* 1 */\n color: inherit; /* 2 */\n display: table; /* 1 */\n max-width: 100%; /* 1 */\n padding: 0; /* 3 */\n white-space: normal; /* 1 */\n}\n\n/**\n * Add the correct vertical alignment in Chrome, Firefox, and Opera.\n */\n\nprogress {\n vertical-align: baseline;\n}\n\n/**\n * Remove the default vertical scrollbar in IE 10+.\n */\n\ntextarea {\n overflow: auto;\n}\n\n/**\n * 1. Add the correct box sizing in IE 10.\n * 2. Remove the padding in IE 10.\n */\n\n[type=\"checkbox\"],\n[type=\"radio\"] {\n box-sizing: border-box; /* 1 */\n padding: 0; /* 2 */\n}\n\n/**\n * Correct the cursor style of increment and decrement buttons in Chrome.\n */\n\n[type=\"number\"]::-webkit-inner-spin-button,\n[type=\"number\"]::-webkit-outer-spin-button {\n height: auto;\n}\n\n/**\n * 1. Correct the odd appearance in Chrome and Safari.\n * 2. Correct the outline style in Safari.\n */\n\n[type=\"search\"] {\n -webkit-appearance: textfield; /* 1 */\n outline-offset: -2px; /* 2 */\n}\n\n/**\n * Remove the inner padding in Chrome and Safari on macOS.\n */\n\n[type=\"search\"]::-webkit-search-decoration {\n -webkit-appearance: none;\n}\n\n/**\n * 1. Correct the inability to style clickable types in iOS and Safari.\n * 2. Change font properties to `inherit` in Safari.\n */\n\n::-webkit-file-upload-button {\n -webkit-appearance: button; /* 1 */\n font: inherit; /* 2 */\n}\n\n/* Interactive\n ========================================================================== */\n\n/*\n * Add the correct display in Edge, IE 10+, and Firefox.\n */\n\ndetails {\n display: block;\n}\n\n/*\n * Add the correct display in all browsers.\n */\n\nsummary {\n display: list-item;\n}\n\n/* Misc\n ========================================================================== */\n\n/**\n * Add the correct display in IE 10+.\n */\n\ntemplate {\n display: none;\n}\n\n/**\n * Add the correct display in IE 10.\n */\n\n[hidden] {\n display: none;\n}\n","// This file contains styles for managing print media.\n\n////////////////////////////////////////////////////////////////////////////////\n// Hide elements not relevant to print media.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Hide icon container.\n .content-icon-container\n display: none !important\n\n // Hide showing header links if hovering over when printing.\n .headerlink\n display: none !important\n\n // Hide mobile header.\n .mobile-header\n display: none !important\n\n // Hide navigation links.\n .related-pages\n display: none !important\n\n////////////////////////////////////////////////////////////////////////////////\n// Tweaks related to decolorization.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Apply a border around code which no longer have a color background.\n .highlight\n border: 0.1pt solid var(--color-foreground-border)\n\n////////////////////////////////////////////////////////////////////////////////\n// Avoid page break in some relevant cases.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n ul, ol, dl, a, table, pre, blockquote\n page-break-inside: avoid\n\n h1, h2, h3, h4, h5, h6, img, figure, caption\n page-break-inside: avoid\n page-break-after: avoid\n\n ul, ol, dl\n page-break-before: avoid\n",".visually-hidden\n position: absolute !important\n width: 1px !important\n height: 1px !important\n padding: 0 !important\n margin: -1px !important\n overflow: hidden !important\n clip: rect(0,0,0,0) !important\n white-space: nowrap !important\n border: 0 !important\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n:-moz-focusring\n outline: auto\n","// This file serves as the \"skeleton\" of the theming logic.\n//\n// This contains the bulk of the logic for handling dark mode, color scheme\n// toggling and the handling of color-scheme-specific hiding of elements.\n\nbody\n @include fonts\n @include spacing\n @include icons\n @include admonitions\n @include default-admonition(#651fff, \"abstract\")\n @include default-topic(#14B8A6, \"pencil\")\n\n @include colors\n\n.only-light\n display: block !important\nhtml body .only-dark\n display: none !important\n\n// Ignore dark-mode hints if print media.\n@media not print\n // Enable dark-mode, if requested.\n body[data-theme=\"dark\"]\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n // Enable dark mode, unless explicitly told to avoid.\n @media (prefers-color-scheme: dark)\n body:not([data-theme=\"light\"])\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n//\n// Theme toggle presentation\n//\nbody[data-theme=\"auto\"]\n .theme-toggle svg.theme-icon-when-auto-light\n display: block\n\n @media (prefers-color-scheme: dark)\n .theme-toggle svg.theme-icon-when-auto-dark\n display: block\n .theme-toggle svg.theme-icon-when-auto-light\n display: none\n\nbody[data-theme=\"dark\"]\n .theme-toggle svg.theme-icon-when-dark\n display: block\n\nbody[data-theme=\"light\"]\n .theme-toggle svg.theme-icon-when-light\n display: block\n","// Fonts used by this theme.\n//\n// There are basically two things here -- using the system font stack and\n// defining sizes for various elements in %ages. We could have also used `em`\n// but %age is easier to reason about for me.\n\n@mixin fonts {\n // These are adapted from https://systemfontstack.com/\n --font-stack: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial,\n sans-serif, Apple Color Emoji, Segoe UI Emoji;\n --font-stack--monospace: \"SFMono-Regular\", Menlo, Consolas, Monaco,\n Liberation Mono, Lucida Console, monospace;\n --font-stack--headings: var(--font-stack);\n\n --font-size--normal: 100%;\n --font-size--small: 87.5%;\n --font-size--small--2: 81.25%;\n --font-size--small--3: 75%;\n --font-size--small--4: 62.5%;\n\n // Sidebar\n --sidebar-caption-font-size: var(--font-size--small--2);\n --sidebar-item-font-size: var(--font-size--small);\n --sidebar-search-input-font-size: var(--font-size--small);\n\n // Table of Contents\n --toc-font-size: var(--font-size--small--3);\n --toc-font-size--mobile: var(--font-size--normal);\n --toc-title-font-size: var(--font-size--small--4);\n\n // Admonitions\n //\n // These aren't defined in terms of %ages, since nesting these is permitted.\n --admonition-font-size: 0.8125rem;\n --admonition-title-font-size: 0.8125rem;\n\n // Code\n --code-font-size: var(--font-size--small--2);\n\n // API\n --api-font-size: var(--font-size--small);\n}\n","// Spacing for various elements on the page\n//\n// If the user wants to tweak things in a certain way, they are permitted to.\n// They also have to deal with the consequences though!\n\n@mixin spacing {\n // Header!\n --header-height: calc(\n var(--sidebar-item-line-height) + 4 * #{var(--sidebar-item-spacing-vertical)}\n );\n --header-padding: 0.5rem;\n\n // Sidebar\n --sidebar-tree-space-above: 1.5rem;\n --sidebar-caption-space-above: 1rem;\n\n --sidebar-item-line-height: 1rem;\n --sidebar-item-spacing-vertical: 0.5rem;\n --sidebar-item-spacing-horizontal: 1rem;\n --sidebar-item-height: calc(\n var(--sidebar-item-line-height) + 2 *#{var(--sidebar-item-spacing-vertical)}\n );\n\n --sidebar-expander-width: var(--sidebar-item-height); // be square\n\n --sidebar-search-space-above: 0.5rem;\n --sidebar-search-input-spacing-vertical: 0.5rem;\n --sidebar-search-input-spacing-horizontal: 0.5rem;\n --sidebar-search-input-height: 1rem;\n --sidebar-search-icon-size: var(--sidebar-search-input-height);\n\n // Table of Contents\n --toc-title-padding: 0.25rem 0;\n --toc-spacing-vertical: 1.5rem;\n --toc-spacing-horizontal: 1.5rem;\n --toc-item-spacing-vertical: 0.4rem;\n --toc-item-spacing-horizontal: 1rem;\n}\n","// Expose theme icons as CSS variables.\n\n$icons: (\n // Adapted from tabler-icons\n // url: https://tablericons.com/\n \"search\":\n url('data:image/svg+xml;charset=utf-8,'),\n // Factored out from mkdocs-material on 24-Aug-2020.\n // url: https://squidfunk.github.io/mkdocs-material/reference/admonitions/\n \"pencil\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"abstract\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"info\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"flame\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"question\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"warning\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"failure\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"spark\":\n url('data:image/svg+xml;charset=utf-8,')\n);\n\n@mixin icons {\n @each $name, $glyph in $icons {\n --icon-#{$name}: #{$glyph};\n }\n}\n","// Admonitions\n\n// Structure of these is:\n// admonition-class: color \"icon-name\";\n//\n// The colors are translated into CSS variables below. The icons are\n// used directly in the main declarations to set the `mask-image` in\n// the title.\n\n// prettier-ignore\n$admonitions: (\n // Each of these has an reST directives for it.\n \"caution\": #ff9100 \"spark\",\n \"warning\": #ff9100 \"warning\",\n \"danger\": #ff5252 \"spark\",\n \"attention\": #ff5252 \"warning\",\n \"error\": #ff5252 \"failure\",\n \"hint\": #00c852 \"question\",\n \"tip\": #00c852 \"info\",\n \"important\": #00bfa5 \"flame\",\n \"note\": #00b0ff \"pencil\",\n \"seealso\": #448aff \"info\",\n \"admonition-todo\": #808080 \"pencil\"\n);\n\n@mixin default-admonition($color, $icon-name) {\n --color-admonition-title: #{$color};\n --color-admonition-title-background: #{rgba($color, 0.2)};\n\n --icon-admonition-default: var(--icon-#{$icon-name});\n}\n\n@mixin default-topic($color, $icon-name) {\n --color-topic-title: #{$color};\n --color-topic-title-background: #{rgba($color, 0.2)};\n\n --icon-topic-default: var(--icon-#{$icon-name});\n}\n\n@mixin admonitions {\n @each $name, $values in $admonitions {\n --color-admonition-title--#{$name}: #{nth($values, 1)};\n --color-admonition-title-background--#{$name}: #{rgba(\n nth($values, 1),\n 0.2\n )};\n }\n}\n","// Colors used throughout this theme.\n//\n// The aim is to give the user more control. Thus, instead of hard-coding colors\n// in various parts of the stylesheet, the approach taken is to define all\n// colors as CSS variables and reusing them in all the places.\n//\n// `colors-dark` depends on `colors` being included at a lower specificity.\n\n@mixin colors {\n --color-problematic: #b30000;\n\n // Base Colors\n --color-foreground-primary: black; // for main text and headings\n --color-foreground-secondary: #5a5c63; // for secondary text\n --color-foreground-muted: #6b6f76; // for muted text\n --color-foreground-border: #878787; // for content borders\n\n --color-background-primary: white; // for content\n --color-background-secondary: #f8f9fb; // for navigation + ToC\n --color-background-hover: #efeff4ff; // for navigation-item hover\n --color-background-hover--transparent: #efeff400;\n --color-background-border: #eeebee; // for UI borders\n --color-background-item: #ccc; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #0a4bff;\n --color-brand-content: #2757dd;\n --color-brand-visited: #872ee0;\n\n // API documentation\n --color-api-background: var(--color-background-hover--transparent);\n --color-api-background-hover: var(--color-background-hover);\n --color-api-overall: var(--color-foreground-secondary);\n --color-api-name: var(--color-problematic);\n --color-api-pre-name: var(--color-problematic);\n --color-api-paren: var(--color-foreground-secondary);\n --color-api-keyword: var(--color-foreground-primary);\n\n --color-api-added: #21632c;\n --color-api-added-border: #38a84d;\n --color-api-changed: #046172;\n --color-api-changed-border: #06a1bc;\n --color-api-deprecated: #605706;\n --color-api-deprecated-border: #f0d90f;\n --color-api-removed: #b30000;\n --color-api-removed-border: #ff5c5c;\n\n --color-highlight-on-target: #ffffcc;\n\n // Inline code background\n --color-inline-code-background: var(--color-background-secondary);\n\n // Highlighted text (search)\n --color-highlighted-background: #ddeeff;\n --color-highlighted-text: var(--color-foreground-primary);\n\n // GUI Labels\n --color-guilabel-background: #ddeeff80;\n --color-guilabel-border: #bedaf580;\n --color-guilabel-text: var(--color-foreground-primary);\n\n // Admonitions!\n --color-admonition-background: transparent;\n\n //////////////////////////////////////////////////////////////////////////////\n // Everything below this should be one of:\n // - var(...)\n // - *-gradient(...)\n // - special literal values (eg: transparent, none)\n //////////////////////////////////////////////////////////////////////////////\n\n // Tables\n --color-table-header-background: var(--color-background-secondary);\n --color-table-border: var(--color-background-border);\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: transparent;\n --color-card-marginals-background: var(--color-background-secondary);\n\n // Header\n --color-header-background: var(--color-background-primary);\n --color-header-border: var(--color-background-border);\n --color-header-text: var(--color-foreground-primary);\n\n // Sidebar (left)\n --color-sidebar-background: var(--color-background-secondary);\n --color-sidebar-background-border: var(--color-background-border);\n\n --color-sidebar-brand-text: var(--color-foreground-primary);\n --color-sidebar-caption-text: var(--color-foreground-muted);\n --color-sidebar-link-text: var(--color-foreground-secondary);\n --color-sidebar-link-text--top-level: var(--color-brand-primary);\n\n --color-sidebar-item-background: var(--color-sidebar-background);\n --color-sidebar-item-background--current: var(\n --color-sidebar-item-background\n );\n --color-sidebar-item-background--hover: linear-gradient(\n 90deg,\n var(--color-background-hover--transparent) 0%,\n var(--color-background-hover) var(--sidebar-item-spacing-horizontal),\n var(--color-background-hover) 100%\n );\n\n --color-sidebar-item-expander-background: transparent;\n --color-sidebar-item-expander-background--hover: var(\n --color-background-hover\n );\n\n --color-sidebar-search-text: var(--color-foreground-primary);\n --color-sidebar-search-background: var(--color-background-secondary);\n --color-sidebar-search-background--focus: var(--color-background-primary);\n --color-sidebar-search-border: var(--color-background-border);\n --color-sidebar-search-icon: var(--color-foreground-muted);\n\n // Table of Contents (right)\n --color-toc-background: var(--color-background-primary);\n --color-toc-title-text: var(--color-foreground-muted);\n --color-toc-item-text: var(--color-foreground-secondary);\n --color-toc-item-text--hover: var(--color-foreground-primary);\n --color-toc-item-text--active: var(--color-brand-primary);\n\n // Actual page contents\n --color-content-foreground: var(--color-foreground-primary);\n --color-content-background: transparent;\n\n // Links\n --color-link: var(--color-brand-content);\n --color-link-underline: var(--color-background-border);\n --color-link--hover: var(--color-brand-content);\n --color-link-underline--hover: var(--color-foreground-border);\n\n --color-link--visited: var(--color-brand-visited);\n --color-link-underline--visited: var(--color-background-border);\n --color-link--visited--hover: var(--color-brand-visited);\n --color-link-underline--visited--hover: var(--color-foreground-border);\n}\n\n@mixin colors-dark {\n --color-problematic: #ee5151;\n\n // Base Colors\n --color-foreground-primary: #cfd0d0; // for main text and headings\n --color-foreground-secondary: #9ca0a5; // for secondary text\n --color-foreground-muted: #81868d; // for muted text\n --color-foreground-border: #666666; // for content borders\n\n --color-background-primary: #131416; // for content\n --color-background-secondary: #1a1c1e; // for navigation + ToC\n --color-background-hover: #1e2124ff; // for navigation-item hover\n --color-background-hover--transparent: #1e212400;\n --color-background-border: #303335; // for UI borders\n --color-background-item: #444; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #3d94ff;\n --color-brand-content: #5ca5ff;\n --color-brand-visited: #b27aeb;\n\n // Highlighted text (search)\n --color-highlighted-background: #083563;\n\n // GUI Labels\n --color-guilabel-background: #08356380;\n --color-guilabel-border: #13395f80;\n\n // API documentation\n --color-api-keyword: var(--color-foreground-secondary);\n --color-highlight-on-target: #333300;\n\n --color-api-added: #3db854;\n --color-api-added-border: #267334;\n --color-api-changed: #09b0ce;\n --color-api-changed-border: #056d80;\n --color-api-deprecated: #b1a10b;\n --color-api-deprecated-border: #6e6407;\n --color-api-removed: #ff7575;\n --color-api-removed-border: #b03b3b;\n\n // Admonitions\n --color-admonition-background: #18181a;\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: #18181a;\n --color-card-marginals-background: var(--color-background-hover);\n}\n","// This file contains the styling for making the content throughout the page,\n// including fonts, paragraphs, headings and spacing among these elements.\n\nbody\n font-family: var(--font-stack)\npre,\ncode,\nkbd,\nsamp\n font-family: var(--font-stack--monospace)\n\n// Make fonts look slightly nicer.\nbody\n -webkit-font-smoothing: antialiased\n -moz-osx-font-smoothing: grayscale\n\n// Line height from Bootstrap 4.1\narticle\n line-height: 1.5\n\n//\n// Headings\n//\nh1,\nh2,\nh3,\nh4,\nh5,\nh6\n line-height: 1.25\n font-family: var(--font-stack--headings)\n font-weight: bold\n\n border-radius: 0.5rem\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n margin-left: -0.5rem\n margin-right: -0.5rem\n padding-left: 0.5rem\n padding-right: 0.5rem\n\n + p\n margin-top: 0\n\nh1\n font-size: 2.5em\n margin-top: 1.75rem\n margin-bottom: 1rem\nh2\n font-size: 2em\n margin-top: 1.75rem\nh3\n font-size: 1.5em\nh4\n font-size: 1.25em\nh5\n font-size: 1.125em\nh6\n font-size: 1em\n\nsmall\n opacity: 75%\n font-size: 80%\n\n// Paragraph\np\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n\n// Horizontal rules\nhr.docutils\n height: 1px\n padding: 0\n margin: 2rem 0\n background-color: var(--color-background-border)\n border: 0\n\n.centered\n text-align: center\n\n// Links\na\n text-decoration: underline\n\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n &:visited\n color: var(--color-link--visited)\n text-decoration-color: var(--color-link-underline--visited)\n &:hover\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &.muted-link\n color: inherit\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &:visited\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n","// This file contains the styles for the overall layouting of the documentation\n// skeleton, including the responsive changes as well as sidebar toggles.\n//\n// This is implemented as a mobile-last design, which isn't ideal, but it is\n// reasonably good-enough and I got pretty tired by the time I'd finished this\n// to move the rules around to fix this. Shouldn't take more than 3-4 hours,\n// if you know what you're doing tho.\n\n// HACK: Not all browsers account for the scrollbar width in media queries.\n// This results in horizontal scrollbars in the breakpoint where we go\n// from displaying everything to hiding the ToC. We accomodate for this by\n// adding a bit of padding to the TOC drawer, disabling the horizontal\n// scrollbar and allowing the scrollbars to cover the padding.\n// https://www.456bereastreet.com/archive/201301/media_query_width_and_vertical_scrollbars/\n\n// HACK: Always having the scrollbar visible, prevents certain browsers from\n// causing the content to stutter horizontally between taller-than-viewport and\n// not-taller-than-viewport pages.\n\n$icon-size: 1.25rem\n\nhtml\n overflow-x: hidden\n overflow-y: scroll\n scroll-behavior: smooth\n\n.sidebar-scroll, .toc-scroll, article[role=main] *\n // Override Firefox scrollbar style\n scrollbar-width: thin\n scrollbar-color: var(--color-foreground-border) transparent\n\n // Override Chrome scrollbar styles\n &::-webkit-scrollbar\n width: 0.25rem\n height: 0.25rem\n &::-webkit-scrollbar-thumb\n background-color: var(--color-foreground-border)\n border-radius: 0.125rem\n\n//\n// Overalls\n//\nhtml,\nbody\n height: 100%\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n.skip-to-content\n position: fixed\n padding: 1rem\n border-radius: 1rem\n left: 0.25rem\n top: 0.25rem\n z-index: 40\n background: var(--color-background-primary)\n color: var(--color-foreground-primary)\n\n transform: translateY(-200%)\n transition: transform 300ms ease-in-out\n\n &:focus-within\n transform: translateY(0%)\n\narticle\n color: var(--color-content-foreground)\n background: var(--color-content-background)\n overflow-wrap: break-word\n\n.page\n display: flex\n // fill the viewport for pages with little content.\n min-height: 100%\n\n.mobile-header\n width: 100%\n height: var(--header-height)\n background-color: var(--color-header-background)\n color: var(--color-header-text)\n border-bottom: 1px solid var(--color-header-border)\n\n // Looks like sub-script/super-script have this, and we need this to\n // be \"on top\" of those.\n z-index: 10\n\n // We don't show the header on large screens.\n display: none\n\n // Add shadow when scrolled\n &.scrolled\n border-bottom: none\n box-shadow: 0 0 0.2rem rgba(0, 0, 0, 0.1), 0 0.2rem 0.4rem rgba(0, 0, 0, 0.2)\n\n .header-center\n a\n color: var(--color-header-text)\n text-decoration: none\n\n.main\n display: flex\n flex: 1\n\n// Sidebar (left) also covers the entire left portion of screen.\n.sidebar-drawer\n box-sizing: border-box\n\n border-right: 1px solid var(--color-sidebar-background-border)\n background: var(--color-sidebar-background)\n\n display: flex\n justify-content: flex-end\n // These next two lines took me two days to figure out.\n width: calc((100% - #{$full-width}) / 2 + #{$sidebar-width})\n min-width: $sidebar-width\n\n// Scroll-along sidebars\n.sidebar-container,\n.toc-drawer\n box-sizing: border-box\n width: $sidebar-width\n\n.toc-drawer\n background: var(--color-toc-background)\n // See HACK described on top of this document\n padding-right: 1rem\n\n.sidebar-sticky,\n.toc-sticky\n position: sticky\n top: 0\n height: min(100%, 100vh)\n height: 100vh\n\n display: flex\n flex-direction: column\n\n.sidebar-scroll,\n.toc-scroll\n flex-grow: 1\n flex-shrink: 1\n\n overflow: auto\n scroll-behavior: smooth\n\n// Central items.\n.content\n padding: 0 $content-padding\n width: $content-width\n\n display: flex\n flex-direction: column\n justify-content: space-between\n\n.icon\n display: inline-block\n height: 1rem\n width: 1rem\n svg\n width: 100%\n height: 100%\n\n//\n// Accommodate announcement banner\n//\n.announcement\n background-color: var(--color-announcement-background)\n color: var(--color-announcement-text)\n\n height: var(--header-height)\n display: flex\n align-items: center\n overflow-x: auto\n & + .page\n min-height: calc(100% - var(--header-height))\n\n.announcement-content\n box-sizing: border-box\n padding: 0.5rem\n min-width: 100%\n white-space: nowrap\n text-align: center\n\n a\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-announcement-text)\n\n &:hover\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-link--hover)\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for theme\n////////////////////////////////////////////////////////////////////////////////\n.no-js .theme-toggle-container // don't show theme toggle if there's no JS\n display: none\n\n.theme-toggle-container\n vertical-align: middle\n\n.theme-toggle\n cursor: pointer\n border: none\n padding: 0\n background: transparent\n\n.theme-toggle svg\n vertical-align: middle\n height: $icon-size\n width: $icon-size\n color: var(--color-foreground-primary)\n display: none\n\n.theme-toggle-header\n float: left\n padding: 1rem 0.5rem\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for elements\n////////////////////////////////////////////////////////////////////////////////\n.toc-overlay-icon, .nav-overlay-icon\n display: none\n cursor: pointer\n\n .icon\n color: var(--color-foreground-secondary)\n height: $icon-size\n width: $icon-size\n\n.toc-header-icon, .nav-overlay-icon\n // for when we set display: flex\n justify-content: center\n align-items: center\n\n.toc-content-icon\n height: 1.5rem\n width: 1.5rem\n\n.content-icon-container\n float: right\n display: flex\n margin-top: 1.5rem\n margin-left: 1rem\n margin-bottom: 1rem\n gap: 0.5rem\n\n .edit-this-page, .view-this-page\n svg\n color: inherit\n height: $icon-size\n width: $icon-size\n\n.sidebar-toggle\n position: absolute\n display: none\n// \n.sidebar-toggle[name=\"__toc\"]\n left: 20px\n.sidebar-toggle:checked\n left: 40px\n// \n\n.overlay\n position: fixed\n top: 0\n width: 0\n height: 0\n\n transition: width 0ms, height 0ms, opacity 250ms ease-out\n\n opacity: 0\n background-color: rgba(0, 0, 0, 0.54)\n.sidebar-overlay\n z-index: 20\n.toc-overlay\n z-index: 40\n\n// Keep things on top and smooth.\n.sidebar-drawer\n z-index: 30\n transition: left 250ms ease-in-out\n.toc-drawer\n z-index: 50\n transition: right 250ms ease-in-out\n\n// Show the Sidebar\n#__navigation:checked\n & ~ .sidebar-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .sidebar-drawer\n top: 0\n left: 0\n // Show the toc sidebar\n#__toc:checked\n & ~ .toc-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .toc-drawer\n top: 0\n right: 0\n\n////////////////////////////////////////////////////////////////////////////////\n// Back to top\n////////////////////////////////////////////////////////////////////////////////\n.back-to-top\n text-decoration: none\n\n display: none\n position: fixed\n left: 0\n top: 1rem\n padding: 0.5rem\n padding-right: 0.75rem\n border-radius: 1rem\n font-size: 0.8125rem\n\n background: var(--color-background-primary)\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), #6b728080 0px 0px 1px 0px\n\n z-index: 10\n\n margin-left: 50%\n transform: translateX(-50%)\n svg\n height: 1rem\n width: 1rem\n fill: currentColor\n display: inline-block\n\n span\n margin-left: 0.25rem\n\n .show-back-to-top &\n display: flex\n align-items: center\n\n////////////////////////////////////////////////////////////////////////////////\n// Responsive layouting\n////////////////////////////////////////////////////////////////////////////////\n// Make things a bit bigger on bigger screens.\n@media (min-width: $full-width + $sidebar-width)\n html\n font-size: 110%\n\n@media (max-width: $full-width)\n // Collapse \"toc\" into the icon.\n .toc-content-icon\n display: flex\n .toc-drawer\n position: fixed\n height: 100vh\n top: 0\n right: -$sidebar-width\n border-left: 1px solid var(--color-background-muted)\n .toc-tree\n border-left: none\n font-size: var(--toc-font-size--mobile)\n\n // Accomodate for a changed content width.\n .sidebar-drawer\n width: calc((100% - #{$full-width - $sidebar-width}) / 2 + #{$sidebar-width})\n\n@media (max-width: $full-width - $sidebar-width)\n // Collapse \"navigation\".\n .nav-overlay-icon\n display: flex\n .sidebar-drawer\n position: fixed\n height: 100vh\n width: $sidebar-width\n\n top: 0\n left: -$sidebar-width\n\n // Swap which icon is visible.\n .toc-header-icon\n display: flex\n .toc-content-icon, .theme-toggle-content\n display: none\n .theme-toggle-header\n display: block\n\n // Show the header.\n .mobile-header\n position: sticky\n top: 0\n display: flex\n justify-content: space-between\n align-items: center\n\n .header-left,\n .header-right\n display: flex\n height: var(--header-height)\n padding: 0 var(--header-padding)\n label\n height: 100%\n width: 100%\n user-select: none\n\n .nav-overlay-icon .icon,\n .theme-toggle svg\n height: $icon-size\n width: $icon-size\n\n // Add a scroll margin for the content\n :target\n scroll-margin-top: calc(var(--header-height) + 2.5rem)\n\n // Show back-to-top below the header\n .back-to-top\n top: calc(var(--header-height) + 0.5rem)\n\n // Center the page, and accommodate for the header.\n .page\n flex-direction: column\n justify-content: center\n .content\n margin-left: auto\n margin-right: auto\n\n@media (max-width: $content-width + 2* $content-padding)\n // Content should respect window limits.\n .content\n width: 100%\n overflow-x: auto\n\n@media (max-width: $content-width)\n .content\n padding: 0 $content-padding--small\n // Don't float sidebars to the right.\n article aside.sidebar\n float: none\n width: 100%\n margin: 1rem 0\n","// Overall Layout Variables\n//\n// Because CSS variables can't be used in media queries. The fact that this\n// makes the layout non-user-configurable is a good thing.\n$content-padding: 3em;\n$content-padding--small: 1em;\n$content-width: 46em;\n$sidebar-width: 15em;\n$full-width: $content-width + 2 * ($content-padding + $sidebar-width);\n","//\n// The design here is strongly inspired by mkdocs-material.\n.admonition, .topic\n margin: 1rem auto\n padding: 0 0.5rem 0.5rem 0.5rem\n\n background: var(--color-admonition-background)\n\n border-radius: 0.2rem\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n font-size: var(--admonition-font-size)\n\n overflow: hidden\n page-break-inside: avoid\n\n // First element should have no margin, since the title has it.\n > :nth-child(2)\n margin-top: 0\n\n // Last item should have no margin, since we'll control that w/ padding\n > :last-child\n margin-bottom: 0\n\n.admonition p.admonition-title,\np.topic-title\n position: relative\n margin: 0 -0.5rem 0.5rem\n padding-left: 2rem\n padding-right: .5rem\n padding-top: .4rem\n padding-bottom: .4rem\n\n font-weight: 500\n font-size: var(--admonition-title-font-size)\n line-height: 1.3\n\n // Our fancy icon\n &::before\n content: \"\"\n position: absolute\n left: 0.5rem\n width: 1rem\n height: 1rem\n\n// Default styles\np.admonition-title\n background-color: var(--color-admonition-title-background)\n &::before\n background-color: var(--color-admonition-title)\n mask-image: var(--icon-admonition-default)\n mask-repeat: no-repeat\n\np.topic-title\n background-color: var(--color-topic-title-background)\n &::before\n background-color: var(--color-topic-title)\n mask-image: var(--icon-topic-default)\n mask-repeat: no-repeat\n\n//\n// Variants\n//\n.admonition\n border-left: 0.2rem solid var(--color-admonition-title)\n\n @each $type, $value in $admonitions\n &.#{$type}\n border-left-color: var(--color-admonition-title--#{$type})\n > .admonition-title\n background-color: var(--color-admonition-title-background--#{$type})\n &::before\n background-color: var(--color-admonition-title--#{$type})\n mask-image: var(--icon-#{nth($value, 2)})\n\n.admonition-todo > .admonition-title\n text-transform: uppercase\n","// This file stylizes the API documentation (stuff generated by autodoc). It's\n// deeply nested due to how autodoc structures the HTML without enough classes\n// to select the relevant items.\n\n// API docs!\ndl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)\n // Tweak the spacing of all the things!\n dd\n margin-left: 2rem\n > :first-child\n margin-top: 0.125rem\n > :last-child\n margin-bottom: 0.75rem\n\n // This is used for the arguments\n .field-list\n margin-bottom: 0.75rem\n\n // \"Headings\" (like \"Parameters\" and \"Return\")\n > dt\n text-transform: uppercase\n font-size: var(--font-size--small)\n\n dd:empty\n margin-bottom: 0.5rem\n dd > ul\n margin-left: -1.2rem\n > li\n > p:nth-child(2)\n margin-top: 0\n // When the last-empty-paragraph follows a paragraph, it doesn't need\n // to augument the existing spacing.\n > p + p:last-child:empty\n margin-top: 0\n margin-bottom: 0\n\n // Colorize the elements\n > dt\n color: var(--color-api-overall)\n\n.sig:not(.sig-inline)\n font-weight: bold\n\n font-size: var(--api-font-size)\n font-family: var(--font-stack--monospace)\n\n margin-left: -0.25rem\n margin-right: -0.25rem\n padding-top: 0.25rem\n padding-bottom: 0.25rem\n padding-right: 0.5rem\n\n // These are intentionally em, to properly match the font size.\n padding-left: 3em\n text-indent: -2.5em\n\n border-radius: 0.25rem\n\n background: var(--color-api-background)\n transition: background 100ms ease-out\n\n &:hover\n background: var(--color-api-background-hover)\n\n // adjust the size of the [source] link on the right.\n a.reference\n .viewcode-link\n font-weight: normal\n width: 4.25rem\n\nem.property\n font-style: normal\n &:first-child\n color: var(--color-api-keyword)\n.sig-name\n color: var(--color-api-name)\n.sig-prename\n font-weight: normal\n color: var(--color-api-pre-name)\n.sig-paren\n color: var(--color-api-paren)\n.sig-param\n font-style: normal\n\ndiv.versionadded,\ndiv.versionchanged,\ndiv.deprecated,\ndiv.versionremoved\n border-left: 0.1875rem solid\n border-radius: 0.125rem\n\n padding-left: 0.75rem\n\n p\n margin-top: 0.125rem\n margin-bottom: 0.125rem\n\ndiv.versionadded\n border-color: var(--color-api-added-border)\n .versionmodified\n color: var(--color-api-added)\n\ndiv.versionchanged\n border-color: var(--color-api-changed-border)\n .versionmodified\n color: var(--color-api-changed)\n\ndiv.deprecated\n border-color: var(--color-api-deprecated-border)\n .versionmodified\n color: var(--color-api-deprecated)\n\ndiv.versionremoved\n border-color: var(--color-api-removed-border)\n .versionmodified\n color: var(--color-api-removed)\n\n// Align the [docs] and [source] to the right.\n.viewcode-link, .viewcode-back\n float: right\n text-align: right\n",".line-block\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n .line-block\n margin-top: 0rem\n margin-bottom: 0rem\n padding-left: 1rem\n","// Captions\narticle p.caption,\ntable > caption,\n.code-block-caption\n font-size: var(--font-size--small)\n text-align: center\n\n// Caption above a TOCTree\n.toctree-wrapper.compound\n .caption, :not(.caption) > .caption-text\n font-size: var(--font-size--small)\n text-transform: uppercase\n\n text-align: initial\n margin-bottom: 0\n\n > ul\n margin-top: 0\n margin-bottom: 0\n","// Inline code\ncode.literal, .sig-inline\n background: var(--color-inline-code-background)\n border-radius: 0.2em\n // Make the font smaller, and use padding to recover.\n font-size: var(--font-size--small--2)\n padding: 0.1em 0.2em\n\n pre.literal-block &\n font-size: inherit\n padding: 0\n\n p &\n border: 1px solid var(--color-background-border)\n\n.sig-inline\n font-family: var(--font-stack--monospace)\n\n// Code and Literal Blocks\n$code-spacing-vertical: 0.625rem\n$code-spacing-horizontal: 0.875rem\n\n// Wraps every literal block + line numbers.\ndiv[class*=\" highlight-\"],\ndiv[class^=\"highlight-\"]\n margin: 1em 0\n display: flex\n\n .table-wrapper\n margin: 0\n padding: 0\n\npre\n margin: 0\n padding: 0\n overflow: auto\n\n // Needed to have more specificity than pygments' \"pre\" selector. :(\n article[role=\"main\"] .highlight &\n line-height: 1.5\n\n &.literal-block,\n .highlight &\n font-size: var(--code-font-size)\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n // Make it look like all the other blocks.\n &.literal-block\n margin-top: 1rem\n margin-bottom: 1rem\n\n border-radius: 0.2rem\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n\n// All code is always contained in this.\n.highlight\n width: 100%\n border-radius: 0.2rem\n\n // Make line numbers and prompts un-selectable.\n .gp, span.linenos\n user-select: none\n pointer-events: none\n\n // Expand the line-highlighting.\n .hll\n display: block\n margin-left: -$code-spacing-horizontal\n margin-right: -$code-spacing-horizontal\n padding-left: $code-spacing-horizontal\n padding-right: $code-spacing-horizontal\n\n/* Make code block captions be nicely integrated */\n.code-block-caption\n display: flex\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n border-radius: 0.25rem\n border-bottom-left-radius: 0\n border-bottom-right-radius: 0\n font-weight: 300\n border-bottom: 1px solid\n\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n border-color: var(--color-background-border)\n\n + div[class]\n margin-top: 0\n pre\n border-top-left-radius: 0\n border-top-right-radius: 0\n\n// When `html_codeblock_linenos_style` is table.\n.highlighttable\n width: 100%\n display: block\n tbody\n display: block\n\n tr\n display: flex\n\n // Line numbers\n td.linenos\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n padding: $code-spacing-vertical $code-spacing-horizontal\n padding-right: 0\n border-top-left-radius: 0.2rem\n border-bottom-left-radius: 0.2rem\n\n .linenodiv\n padding-right: $code-spacing-horizontal\n font-size: var(--code-font-size)\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n\n // Actual code\n td.code\n padding: 0\n display: block\n flex: 1\n overflow: hidden\n\n .highlight\n border-top-left-radius: 0\n border-bottom-left-radius: 0\n\n// When `html_codeblock_linenos_style` is inline.\n.highlight\n span.linenos\n display: inline-block\n padding-left: 0\n padding-right: $code-spacing-horizontal\n margin-right: $code-spacing-horizontal\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n","// Inline Footnote Reference\n.footnote-reference\n font-size: var(--font-size--small--4)\n vertical-align: super\n\n// Definition list, listing the content of each note.\n// docutils <= 0.17\ndl.footnote.brackets\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\n display: grid\n grid-template-columns: max-content auto\n dt\n margin: 0\n > .fn-backref\n margin-left: 0.25rem\n\n &:after\n content: \":\"\n\n .brackets\n &:before\n content: \"[\"\n &:after\n content: \"]\"\n\n dd\n margin: 0\n padding: 0 1rem\n\n// docutils >= 0.18\naside.footnote\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\naside.footnote > span,\ndiv.citation > span\n float: left\n font-weight: 500\n padding-right: 0.25rem\n\naside.footnote > *:not(span),\ndiv.citation > p\n margin-left: 2rem\n","//\n// Figures\n//\nimg\n box-sizing: border-box\n max-width: 100%\n height: auto\n\narticle\n figure, .figure\n border-radius: 0.2rem\n\n margin: 0\n :last-child\n margin-bottom: 0\n\n .align-left\n float: left\n clear: left\n margin: 0 1rem 1rem\n\n .align-right\n float: right\n clear: right\n margin: 0 1rem 1rem\n\n .align-default,\n .align-center\n display: block\n text-align: center\n margin-left: auto\n margin-right: auto\n\n // WELL, table needs to be stylised like a table.\n table.align-default\n display: table\n text-align: initial\n",".genindex-jumpbox, .domainindex-jumpbox\n border-top: 1px solid var(--color-background-border)\n border-bottom: 1px solid var(--color-background-border)\n padding: 0.25rem\n\n.genindex-section, .domainindex-section\n h2\n margin-top: 0.75rem\n margin-bottom: 0.5rem\n ul\n margin-top: 0\n margin-bottom: 0\n","ul,\nol\n padding-left: 1.2rem\n\n // Space lists out like paragraphs\n margin-top: 1rem\n margin-bottom: 1rem\n // reduce margins within li.\n li\n > p:first-child\n margin-top: 0.25rem\n margin-bottom: 0.25rem\n\n > p:last-child\n margin-top: 0.25rem\n\n > ul,\n > ol\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n\nol\n &.arabic\n list-style: decimal\n &.loweralpha\n list-style: lower-alpha\n &.upperalpha\n list-style: upper-alpha\n &.lowerroman\n list-style: lower-roman\n &.upperroman\n list-style: upper-roman\n\n// Don't space lists out when they're \"simple\" or in a `.. toctree::`\n.simple,\n.toctree-wrapper\n li\n > ul,\n > ol\n margin-top: 0\n margin-bottom: 0\n\n// Definition Lists\n.field-list,\n.option-list,\ndl:not([class]),\ndl.simple,\ndl.footnote,\ndl.glossary\n dt\n font-weight: 500\n margin-top: 0.25rem\n + dt\n margin-top: 0\n\n .classifier::before\n content: \":\"\n margin-left: 0.2rem\n margin-right: 0.2rem\n\n dd\n > p:first-child,\n ul\n margin-top: 0.125rem\n\n ul\n margin-bottom: 0.125rem\n",".math-wrapper\n width: 100%\n overflow-x: auto\n\ndiv.math\n position: relative\n text-align: center\n\n .headerlink,\n &:focus .headerlink\n display: none\n\n &:hover .headerlink\n display: inline-block\n\n span.eqno\n position: absolute\n right: 0.5rem\n top: 50%\n transform: translate(0, -50%)\n z-index: 1\n","// Abbreviations\nabbr[title]\n cursor: help\n\n// \"Problematic\" content, as identified by Sphinx\n.problematic\n color: var(--color-problematic)\n\n// Keyboard / Mouse \"instructions\"\nkbd:not(.compound)\n margin: 0 0.2rem\n padding: 0 0.2rem\n border-radius: 0.2rem\n border: 1px solid var(--color-foreground-border)\n color: var(--color-foreground-primary)\n vertical-align: text-bottom\n\n font-size: var(--font-size--small--3)\n display: inline-block\n\n box-shadow: 0 0.0625rem 0 rgba(0, 0, 0, 0.2), inset 0 0 0 0.125rem var(--color-background-primary)\n\n background-color: var(--color-background-secondary)\n\n// Blockquote\nblockquote\n border-left: 4px solid var(--color-background-border)\n background: var(--color-background-secondary)\n\n margin-left: 0\n margin-right: 0\n padding: 0.5rem 1rem\n\n .attribution\n font-weight: 600\n text-align: right\n\n &.pull-quote,\n &.highlights\n font-size: 1.25em\n\n &.epigraph,\n &.pull-quote\n border-left-width: 0\n border-radius: 0.5rem\n\n &.highlights\n border-left-width: 0\n background: transparent\n\n// Center align embedded-in-text images\np .reference img\n vertical-align: middle\n","p.rubric\n line-height: 1.25\n font-weight: bold\n font-size: 1.125em\n\n // For Numpy-style documentation that's got rubrics within it.\n // https://github.com/pradyunsg/furo/discussions/505\n dd &\n line-height: inherit\n font-weight: inherit\n\n font-size: var(--font-size--small)\n text-transform: uppercase\n","article .sidebar\n float: right\n clear: right\n width: 30%\n\n margin-left: 1rem\n margin-right: 0\n\n border-radius: 0.2rem\n background-color: var(--color-background-secondary)\n border: var(--color-background-border) 1px solid\n\n > *\n padding-left: 1rem\n padding-right: 1rem\n\n > ul, > ol // lists need additional padding, because bullets.\n padding-left: 2.2rem\n\n .sidebar-title\n margin: 0\n padding: 0.5rem 1rem\n border-bottom: var(--color-background-border) 1px solid\n\n font-weight: 500\n\n// TODO: subtitle\n// TODO: dedicated variables?\n",".table-wrapper\n width: 100%\n overflow-x: auto\n margin-top: 1rem\n margin-bottom: 0.5rem\n padding: 0.2rem 0.2rem 0.75rem\n\ntable.docutils\n border-radius: 0.2rem\n border-spacing: 0\n border-collapse: collapse\n\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n th\n background: var(--color-table-header-background)\n\n td,\n th\n // Space things out properly\n padding: 0 0.25rem\n\n // Get the borders looking just-right.\n border-left: 1px solid var(--color-table-border)\n border-right: 1px solid var(--color-table-border)\n border-bottom: 1px solid var(--color-table-border)\n\n p\n margin: 0.25rem\n\n &:first-child\n border-left: none\n &:last-child\n border-right: none\n\n // MyST-parser tables set these classes for control of column alignment\n &.text-left\n text-align: left\n &.text-right\n text-align: right\n &.text-center\n text-align: center\n",":target\n scroll-margin-top: 2.5rem\n\n@media (max-width: $full-width - $sidebar-width)\n :target\n scroll-margin-top: calc(2.5rem + var(--header-height))\n\n // When a heading is selected\n section > span:target\n scroll-margin-top: calc(2.8rem + var(--header-height))\n\n// Permalinks\n.headerlink\n font-weight: 100\n user-select: none\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6,\ndl dt,\np.caption,\nfigcaption p,\ntable > caption,\n.code-block-caption\n > .headerlink\n margin-left: 0.5rem\n visibility: hidden\n &:hover > .headerlink\n visibility: visible\n\n // Don't change to link-like, if someone adds the contents directive.\n > .toc-backref\n color: inherit\n text-decoration-line: none\n\n// Figure and table captions are special.\nfigure:hover > figcaption > p > .headerlink,\ntable:hover > caption > .headerlink\n visibility: visible\n\n:target >, // Regular section[id] style anchors\nspan:target ~ // Non-regular span[id] style \"extra\" anchors\n h1,\n h2,\n h3,\n h4,\n h5,\n h6\n &:nth-of-type(1)\n background-color: var(--color-highlight-on-target)\n // .headerlink\n // visibility: visible\n code.literal\n background-color: transparent\n\ntable:target > caption,\nfigure:target\n background-color: var(--color-highlight-on-target)\n\n// Inline page contents\n.this-will-duplicate-information-and-it-is-still-useful-here li :target\n background-color: var(--color-highlight-on-target)\n\n// Code block permalinks\n.literal-block-wrapper:target .code-block-caption\n background-color: var(--color-highlight-on-target)\n\n// When a definition list item is selected\n//\n// There isn't really an alternative to !important here, due to the\n// high-specificity of API documentation's selector.\ndt:target\n background-color: var(--color-highlight-on-target) !important\n\n// When a footnote reference is selected\n.footnote > dt:target + dd,\n.footnote-reference:target\n background-color: var(--color-highlight-on-target)\n",".guilabel\n background-color: var(--color-guilabel-background)\n border: 1px solid var(--color-guilabel-border)\n color: var(--color-guilabel-text)\n\n padding: 0 0.3em\n border-radius: 0.5em\n font-size: 0.9em\n","// This file contains the styles used for stylizing the footer that's shown\n// below the content.\n\nfooter\n font-size: var(--font-size--small)\n display: flex\n flex-direction: column\n\n margin-top: 2rem\n\n// Bottom of page information\n.bottom-of-page\n display: flex\n align-items: center\n justify-content: space-between\n\n margin-top: 1rem\n padding-top: 1rem\n padding-bottom: 1rem\n\n color: var(--color-foreground-secondary)\n border-top: 1px solid var(--color-background-border)\n\n line-height: 1.5\n\n @media (max-width: $content-width)\n text-align: center\n flex-direction: column-reverse\n gap: 0.25rem\n\n .left-details\n font-size: var(--font-size--small)\n\n .right-details\n display: flex\n flex-direction: column\n gap: 0.25rem\n text-align: right\n\n .icons\n display: flex\n justify-content: flex-end\n gap: 0.25rem\n font-size: 1rem\n\n a\n text-decoration: none\n\n svg,\n img\n font-size: 1.125rem\n height: 1em\n width: 1em\n\n// Next/Prev page information\n.related-pages\n a\n display: flex\n align-items: center\n\n text-decoration: none\n &:hover .page-info .title\n text-decoration: underline\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n svg.furo-related-icon,\n svg.furo-related-icon > use\n flex-shrink: 0\n\n color: var(--color-foreground-border)\n\n width: 0.75rem\n height: 0.75rem\n margin: 0 0.5rem\n\n &.next-page\n max-width: 50%\n\n float: right\n clear: right\n text-align: right\n\n &.prev-page\n max-width: 50%\n\n float: left\n clear: left\n\n svg\n transform: rotate(180deg)\n\n.page-info\n display: flex\n flex-direction: column\n overflow-wrap: anywhere\n\n .next-page &\n align-items: flex-end\n\n .context\n display: flex\n align-items: center\n\n padding-bottom: 0.1rem\n\n color: var(--color-foreground-muted)\n font-size: var(--font-size--small)\n text-decoration: none\n","// This file contains the styles for the contents of the left sidebar, which\n// contains the navigation tree, logo, search etc.\n\n////////////////////////////////////////////////////////////////////////////////\n// Brand on top of the scrollable tree.\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-brand\n display: flex\n flex-direction: column\n flex-shrink: 0\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n text-decoration: none\n\n.sidebar-brand-text\n color: var(--color-sidebar-brand-text)\n overflow-wrap: break-word\n margin: var(--sidebar-item-spacing-vertical) 0\n font-size: 1.5rem\n\n.sidebar-logo-container\n margin: var(--sidebar-item-spacing-vertical) 0\n\n.sidebar-logo\n margin: 0 auto\n display: block\n max-width: 100%\n\n////////////////////////////////////////////////////////////////////////////////\n// Search\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-search-container\n display: flex\n align-items: center\n margin-top: var(--sidebar-search-space-above)\n\n position: relative\n\n background: var(--color-sidebar-search-background)\n &:hover,\n &:focus-within\n background: var(--color-sidebar-search-background--focus)\n\n &::before\n content: \"\"\n position: absolute\n left: var(--sidebar-item-spacing-horizontal)\n width: var(--sidebar-search-icon-size)\n height: var(--sidebar-search-icon-size)\n\n background-color: var(--color-sidebar-search-icon)\n mask-image: var(--icon-search)\n\n.sidebar-search\n box-sizing: border-box\n\n border: none\n border-top: 1px solid var(--color-sidebar-search-border)\n border-bottom: 1px solid var(--color-sidebar-search-border)\n\n padding-top: var(--sidebar-search-input-spacing-vertical)\n padding-bottom: var(--sidebar-search-input-spacing-vertical)\n padding-right: var(--sidebar-search-input-spacing-horizontal)\n padding-left: calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size))\n\n width: 100%\n\n color: var(--color-sidebar-search-foreground)\n background: transparent\n z-index: 10\n\n &:focus\n outline: none\n\n &::placeholder\n font-size: var(--sidebar-search-input-font-size)\n\n//\n// Hide Search Matches link\n//\n#searchbox .highlight-link\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0\n margin: 0\n text-align: center\n\n a\n color: var(--color-sidebar-search-icon)\n font-size: var(--font-size--small--2)\n\n////////////////////////////////////////////////////////////////////////////////\n// Structure/Skeleton of the navigation tree (left)\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-tree\n font-size: var(--sidebar-item-font-size)\n margin-top: var(--sidebar-tree-space-above)\n margin-bottom: var(--sidebar-item-spacing-vertical)\n\n ul\n padding: 0\n margin-top: 0\n margin-bottom: 0\n\n display: flex\n flex-direction: column\n\n list-style: none\n\n li\n position: relative\n margin: 0\n\n > ul\n margin-left: var(--sidebar-item-spacing-horizontal)\n\n .icon\n color: var(--color-sidebar-link-text)\n\n .reference\n box-sizing: border-box\n color: var(--color-sidebar-link-text)\n\n // Fill the parent.\n display: inline-block\n line-height: var(--sidebar-item-line-height)\n text-decoration: none\n\n // Don't allow long words to cause wrapping.\n overflow-wrap: anywhere\n\n height: 100%\n width: 100%\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n &:hover\n color: var(--color-sidebar-link-text)\n background: var(--color-sidebar-item-background--hover)\n\n // Add a nice little \"external-link\" arrow here.\n &.external::after\n content: url('data:image/svg+xml,')\n margin: 0 0.25rem\n vertical-align: middle\n color: var(--color-sidebar-link-text)\n\n // Make the current page reference bold.\n .current-page > .reference\n font-weight: bold\n\n label\n position: absolute\n top: 0\n right: 0\n height: var(--sidebar-item-height)\n width: var(--sidebar-expander-width)\n\n cursor: pointer\n user-select: none\n\n display: flex\n justify-content: center\n align-items: center\n\n .caption, :not(.caption) > .caption-text\n font-size: var(--sidebar-caption-font-size)\n color: var(--color-sidebar-caption-text)\n\n font-weight: bold\n text-transform: uppercase\n\n margin: var(--sidebar-caption-space-above) 0 0 0\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n // If it has children, add a bit more padding to wrap the content to avoid\n // overlapping with the