pyopencl 2024.2.2__cp312-cp312-win_amd64.whl → 2024.2.4__cp312-cp312-win_amd64.whl

pyopencl-2024.2.2.data/data/doc/runtime_platform.rst

@@ -1,184 +0,0 @@
-.. include:: subst.rst
-
-OpenCL Runtime: Platforms, Devices and Contexts
-===============================================
-
-.. currentmodule:: pyopencl
-
-Platform
---------
-
-.. function:: get_platforms()
-
-    Return a list of :class:`Platform` instances.
-
-.. class:: Platform
-
-    .. attribute:: info
-
-        Lower case versions of the :class:`platform_info` constants
-        may be used as attributes on instances of this class
-        to directly query info attributes.
-
-    .. method:: get_info(param)
-
-        See :class:`platform_info` for values of *param*.
-
-    .. method:: get_devices(device_type=device_type.ALL)
-
-        Return a list of devices matching *device_type*.
-        See :class:`device_type` for values of *device_type*.
-
-        .. versionchanged:: 2013.2
-
-            This used to raise an exception if no matching
-            devices were found. Now, it will simply return
-            an empty list.
-
-    .. automethod:: from_int_ptr
-    .. autoattribute:: int_ptr
-
-    |comparable|
-
-Device
-------
-
-.. class:: Device
-
-    Two instances of this class may be compared using *=="* and *"!="*.
-
-    .. attribute:: info
-
-        Lower case versions of the :class:`device_info` constants
-        may be used as attributes on instances of this class
-        to directly query info attributes.
-
-    .. method:: get_info(param)
-
-        See :class:`device_info` for values of *param*.
-
-    .. automethod:: from_int_ptr
-    .. autoattribute:: int_ptr
-
-    .. attribute :: hashable_model_and_version_identifier
-
-        An unspecified data type that can be used to (as precisely as possible,
-        given identifying information available in OpenCL) identify a given
-        model and software stack version of a compute device. Note that this
-        identifier does not differentiate between different instances of the
-        same device installed in a single host.
-
-        The returned data type is hashable.
-
-        .. versionadded:: 2020.1
-
-    .. method:: create_sub_devices(properties)
-
-        *properties* is an array of one (or more) of the forms::
-
-            [ dpp.EQUALLY, 8]
-            [ dpp.BY_COUNTS, 5, 7, 9, dpp.PARTITION_BY_COUNTS_LIST_END]
-            [ dpp.BY_NAMES, 5, 7, 9, dpp.PARTITION_BY_NAMES_LIST_END]
-            [ dpp.BY_AFFINITY_DOMAIN, dad.L1_CACHE]
-
-        where ``dpp`` represents :class:`device_partition_property`
-        and ``dad`` represent :class:`device_affinity_domain`.
-
-        ``PROPERTIES_LIST_END_EXT`` is added automatically.
-
-        Only available with CL 1.2.
-
-        .. versionadded:: 2011.2
-
-    .. method:: device_and_host_timer
-
-        :returns: a tuple ``(device_timestamp, host_timestamp)``.
-
-        Only available with CL 2.0.
-
-        .. versionadded:: 2020.3
-
-    .. method:: host_timer
-
-        Only available with CL 2.0.
-
-        .. versionadded:: 2020.3
-
-.. autofunction:: choose_devices
-
-Context
--------
-
-.. class:: Context(devices=None, properties=None, dev_type=None, cache_dir=None)
-
-    Create a new context. *properties* is a list of key-value
-    tuples, where each key must be one of :class:`context_properties`.
-    At most one of *devices* and *dev_type* may be not *None*, where
-    *devices* is a list of :class:`Device` instances, and
-    *dev_type* is one of the :class:`device_type` constants.
-    If neither is specified, a context with a *dev_type* of
-    :attr:`device_type.DEFAULT` is created.
-
-    If *cache_dir* is not *None* - it will be used as default *cache_dir*
-    for all its' :class:`Program` instances builds (see also :meth:`Program.build`).
-
-    .. note::
-
-        Calling the constructor with no arguments will fail for
-        CL drivers that support the OpenCL ICD (which applies to most modern systems).
-        If you want similar, just-give-me-a-context-already behavior, we recommend
-        :func:`create_some_context`. See, e.g. this
-        `explanation by AMD
-        <https://web.archive.org/web/20101114195033/https://developer.amd.com/support/KnowledgeBase/Lists/KnowledgeBase/DispForm.aspx?ID=71>`__.
-
-    .. note::
-
-        Because of how OpenCL changed in order to support Installable Client
-        Drivers (ICDs) in OpenCL 1.1, the following will *look* reasonable
-        but often actually not work::
-
-            import pyopencl as cl
-            ctx = cl.Context(dev_type=cl.device_type.ALL)
-
-        Instead, make sure to choose a platform when choosing a device by type::
-
-            import pyopencl as cl
-
-            platforms = cl.get_platforms()
-            ctx = cl.Context(
-                    dev_type=cl.device_type.ALL,
-                    properties=[(cl.context_properties.PLATFORM, platforms[0])])
-
-    .. note::
-
-        For
-        ``context_properties.CL_GL_CONTEXT_KHR``,
-        ``context_properties.CL_EGL_DISPLAY_KHR``,
-        ``context_properties.CL_GLX_DISPLAY_KHR``,
-        ``context_properties.CL_WGL_HDC_KHR``, and
-        ``context_properties.CL_CGL_SHAREGROUP_KHR``
-        ``context_properties.CL_CGL_SHAREGROUP_APPLE``
-        the value in the key-value pair is a PyOpenGL context or display
-        instance.
-
-    .. versionchanged:: 0.91.2
-        Constructor arguments *dev_type* added.
-
-    .. attribute:: info
-
-        Lower case versions of the :class:`context_info` constants
-        may be used as attributes on instances of this class
-        to directly query info attributes.
-
-    .. method:: get_info(param)
-
-        See :class:`context_info` for values of *param*.
-
-    .. automethod:: from_int_ptr
-    .. autoattribute:: int_ptr
-
-    .. method:: set_default_device_command_queue(dev, queue)
-
-    |comparable|
-
-.. autofunction:: create_some_context

pyopencl-2024.2.2.data/data/doc/runtime_program.rst

@@ -1,364 +0,0 @@
-.. include:: subst.rst
-
-OpenCL Runtime: Programs and Kernels
-====================================
-
-.. currentmodule:: pyopencl
-
-Program
--------
-
-.. envvar:: PYOPENCL_NO_CACHE
-
-    By default, PyOpenCL will use cached (on disk) "binaries" returned by the
-    OpenCL runtime when calling :meth:`Program.build` on a program
-    constructed with source. (It will depend on the ICD in use how much
-    compilation work is saved by this.)
-    By setting the environment variable :envvar:`PYOPENCL_NO_CACHE` to any
-    string that :func:`pytools.strtobool` evaluates as ``True``, this caching
-    is suppressed. No additional in-memory caching is performed. To retain the
-    compiled version of a kernel in memory, simply retain the :class:`Program`
-    and/or :class:`Kernel` objects.
-
-    PyOpenCL will also cache "invokers", which are short snippets of Python
-    that are generated to accelerate passing arguments to and enqueuing
-    a kernel.
-
-    .. versionadded:: 2013.1
-
-.. envvar:: PYOPENCL_COMPILER_OUTPUT
-
-    When setting the environment variable :envvar:`PYOPENCL_COMPILER_OUTPUT`
-    to any string that :func:`pytools.strtobool` evaluates as ``True``,
-    PyOpenCL will show compiler messages emitted during program build.
-
-.. envvar:: PYOPENCL_BUILD_OPTIONS
-
-    Any options found in the environment variable
-    :envvar:`PYOPENCL_BUILD_OPTIONS` will be appended to *options*
-    in :meth:`Program.build`.
-
-    .. versionadded:: 2013.1
-
-.. class:: Program(context, src)
-           Program(context, devices, binaries)
-
-    *binaries* must contain one binary for each entry in *devices*.
-    If *src* is a :class:`bytes` object starting with a valid `SPIR-V
-    <https://www.khronos.org/spir>`__ magic number, it will be handed
-    off to the OpenCL implementation as such, rather than as OpenCL C source
-    code. (SPIR-V support requires OpenCL 2.1.)
-
-    .. versionchanged:: 2016.2
-
-        Add support for SPIR-V.
-
-    .. attribute:: info
-
-        Lower case versions of the :class:`program_info` constants
-        may be used as attributes on instances of this class
-        to directly query info attributes.
-
-    .. method:: get_info(param)
-
-        See :class:`program_info` for values of *param*.
-
-    .. method:: get_build_info(device, param)
-
-        See :class:`program_build_info` for values of *param*.
-
-    .. method:: build(options=[], devices=None, cache_dir=None)
-
-        *options* is a string of compiler flags.
-        Returns *self*.
-
-        If *cache_dir* is not None - built binaries are cached in an on-disk cache
-        with given path.
-        If passed *cache_dir* is None, but context of this program was created with
-        not-None cache_dir - it will be used as cache directory.
-        If passed *cache_dir* is None and context was created with None cache_dir:
-        built binaries will be cached in an on-disk cache called
-        :file:`pyopencl-compiler-cache-vN-uidNAME-pyVERSION` in the directory
-        returned by :func:`tempfile.gettempdir`.
-
-        See also :envvar:`PYOPENCL_NO_CACHE`, :envvar:`PYOPENCL_BUILD_OPTIONS`.
-
-        .. versionchanged:: 2011.1
-
-            *options* may now also be a :class:`list` of :class:`str`.
-
-    .. method:: compile(self, options=[], devices=None, headers=[])
-
-        :param headers: a list of tuples *(name, program)*.
-
-        Only available with CL 1.2.
-
-        .. versionadded:: 2011.2
-
-    .. attribute:: kernel_name
-
-        You may use ``program.kernel_name`` to obtain a :class:`Kernel`
-        object from a program. Note that every lookup of this type
-        produces a new kernel object, so that this **won't** work::
-
-            prg.sum.set_args(a_g, b_g, res_g)
-            ev = cl.enqueue_nd_range_kernel(queue, prg.sum, a_np.shape, None)
-
-        Instead, either use the (recommended, stateless) calling interface::
-
-            sum_knl = prg.sum
-            sum_knl(queue, a_np.shape, None, a_g, b_g, res_g)
-
-        or the long, stateful way around, if you prefer::
-
-            sum_knl.set_args(a_g, b_g, res_g)
-            ev = cl.enqueue_nd_range_kernel(queue, sum_knl, a_np.shape, None)
-
-        The following will also work, however note that a number of caches that
-        are important for efficient kernel enqueue are attached to the :class:`Kernel`
-        object, and these caches will be ineffective in this usage pattern::
-
-            prg.sum(queue, a_np.shape, None, a_g, b_g, res_g)
-
-        Note that the :class:`Program` has to be built (see :meth:`build`) in
-        order for this to work simply by attribute lookup.
-
-        .. note::
-
-            The :class:`program_info` attributes live
-            in the same name space and take precedence over
-            :class:`Kernel` names.
-
-    .. method:: all_kernels()
-
-        Returns a list of all :class:`Kernel` objects in the :class:`Program`.
-
-    .. method:: set_specialization_constant(spec_id, buffer)
-
-        Only available with CL 2.2 and newer.
-
-        .. versionadded:: 2020.3
-
-    .. automethod:: from_int_ptr
-    .. autoattribute:: int_ptr
-
-    |comparable|
-
-.. function:: create_program_with_built_in_kernels(context, devices, kernel_names)
-
-    Only available with CL 1.2.
-
-    .. versionadded:: 2011.2
-
-.. function:: link_program(context, programs, options=[], devices=None)
-
-    Only available with CL 1.2.
-
-    .. versionadded:: 2011.2
-
-.. function:: unload_platform_compiler(platform)
-
-    Only available with CL 1.2.
-
-    .. versionadded:: 2011.2
-
-Kernel
-------
-
-.. class:: Kernel(program, name)
-
-    .. attribute:: info
-
-        Lower case versions of the :class:`kernel_info` constants
-        may be used as attributes on instances of this class
-        to directly query info attributes.
-
-    .. method:: clone()
-
-        Only available with CL 2.1.
-
-        .. versionadded:: 2020.3
-
-    .. method:: get_info(param)
-
-        See :class:`kernel_info` for values of *param*.
-
-    .. method:: get_work_group_info(param, device)
-
-        See :class:`kernel_work_group_info` for values of *param*.
-
-    .. method:: get_arg_info(arg_index, param)
-
-        See :class:`kernel_arg_info` for values of *param*.
-
-        Only available in OpenCL 1.2 and newer.
-
-    .. method:: get_sub_group_info(self, device, param, input_value=None)
-
-        When the OpenCL spec requests *input_value* to be of type ``size_t``,
-        these may be passed directly as a number. When it requests
-        *input_value* to be of type ``size_t *``, a tuple of integers
-        may be passed.
-
-        Only available in OpenCL 2.1 and newer.
-
-        .. versionadded:: 2020.3
-
-    .. method:: set_arg(self, index, arg)
-
-        *arg* may be
-
-        * *None*: This may be passed for ``__global`` memory references
-          to pass a *NULL* pointer to the kernel.
-        * Anything that satisfies the Python buffer interface,
-          in particular :class:`numpy.ndarray`, :class:`str`,
-          or :mod:`numpy`'s sized scalars, such as :class:`numpy.int32`
-          or :class:`numpy.float64`.
-
-          .. note::
-
-              Note that Python's own :class:`int` or :class:`float`
-              objects will not work out of the box. See
-              :meth:`Kernel.set_scalar_arg_dtypes` for a way to make
-              them work. Alternatively, the standard library module
-              :mod:`struct` can be used to convert Python's native
-              number types to binary data in a :class:`str`.
-
-        * An instance of :class:`MemoryObject`. (e.g. :class:`Buffer`,
-          :class:`Image`, etc.)
-        * An instance of :class:`LocalMemory`.
-        * An instance of :class:`Sampler`.
-        * An instance of :class:`CommandQueue`. (CL 2.0 and higher only)
-
-    .. method:: set_args(self, *args)
-
-        Invoke :meth:`set_arg` on each element of *args* in turn.
-
-        .. versionadded:: 0.92
-
-    .. method:: set_scalar_arg_dtypes(arg_dtypes)
-
-        Inform the wrapper about the sized types of scalar
-        :class:`Kernel` arguments. For each argument,
-        *arg_dtypes* contains an entry. For non-scalars,
-        this must be *None*. For scalars, it must be an
-        object acceptable to the :class:`numpy.dtype`
-        constructor, indicating that the corresponding
-        scalar argument is of that type.
-
-        After invoking this function with the proper information,
-        most suitable number types will automatically be
-        cast to the right type for kernel invocation.
-
-        .. note ::
-
-            The information set by this method is attached to a single kernel
-            instance. A new kernel instance is created every time you use
-            `program.kernel` attribute access. The following will therefore not
-            work::
-
-               prg = cl.Program(...).build()
-               prg.kernel.set_scalar_arg_dtypes(...)
-               prg.kernel(queue, n_globals, None, args)
-
-
-    .. method:: __call__(queue, global_size, local_size, *args, global_offset=None, wait_for=None, g_times_l=False, allow_empty_ndrange=False)
-
-        Use :func:`enqueue_nd_range_kernel` to enqueue a kernel execution, after using
-        :meth:`set_args` to set each argument in turn. See the documentation for
-        :meth:`set_arg` to see what argument types are allowed.
-
-        |glsize|
-
-        |empty-nd-range|
-
-        |std-enqueue-blurb|
-
-        .. note::
-
-            :meth:`__call__` is *not* thread-safe. It sets the arguments using :meth:`set_args`
-            and then runs :func:`enqueue_nd_range_kernel`. Another thread could race it
-            in doing the same things, with undefined outcome. This issue is inherited
-            from the C-level OpenCL API. The recommended solution is to make a kernel
-            (i.e. access ``prg.kernel_name``, which corresponds to making a new kernel)
-            for every thread that may enqueue calls to the kernel.
-
-            A solution involving implicit locks was discussed and decided against on the
-            mailing list in `October 2012
-            <https://lists.tiker.net/pipermail/pyopencl/2012-October/001311.html>`__.
-
-        .. versionchanged:: 0.92
-
-            *local_size* was promoted to third positional argument from being a
-            keyword argument. The old keyword argument usage will continue to
-            be accepted with a warning throughout the 0.92 release cycle.
-            This is a backward-compatible change (just barely!) because
-            *local_size* as third positional argument can only be a
-            :class:`tuple` or *None*. :class:`tuple` instances are never valid
-            :class:`Kernel` arguments, and *None* is valid as an argument, but
-            its treatment in the wrapper had a bug (now fixed) that prevented
-            it from working.
-
-        .. versionchanged:: 2011.1
-
-            Added the *g_times_l* keyword arg.
-
-        .. versionchanged:: 2020.2
-
-            Added the *allow_empty_ndrange* keyword argument.
-
-    .. method:: capture_call(output_file, queue, global_size, local_size, *args, global_offset=None, wait_for=None, g_times_l=False)
-
-        This method supports the exact same interface as :meth:`__call__`, but
-        instead of invoking the kernel, it writes a self-contained PyOpenCL program
-        to *filename* that reproduces this invocation. Data and kernel source code
-        will be packaged up in *filename*'s source code.
-
-        This is mainly intended as a debugging aid. For example, it can be used
-        to automate the task of creating a small, self-contained test case for
-        an observed problem. It can also help separate a misbehaving kernel from
-        a potentially large or time-consuming outer code.
-
-        :arg output_file: a a filename or a file-like to which the generated
-            code is to be written.
-
-        To use, simply change::
-
-            evt = my_kernel(queue, gsize, lsize, arg1, arg2, ...)
-
-        to::
-
-            evt = my_kernel.capture_call("bug.py", queue, gsize, lsize, arg1, arg2, ...)
-
-        .. versionadded:: 2013.1
-
-    .. automethod:: from_int_ptr
-    .. autoattribute:: int_ptr
-
-    |comparable|
-
-.. class:: LocalMemory(size)
-
-    A helper class to pass ``__local`` memory arguments to kernels.
-
-    .. versionadded:: 0.91.2
-
-    .. attribute:: size
-
-        The size of local buffer in bytes to be provided.
-
-.. function:: enqueue_nd_range_kernel(queue, kernel, global_work_size, local_work_size, global_work_offset=None, wait_for=None, g_times_l=False, allow_empty_ndrange=False)
-
-    |glsize|
-
-    |empty-nd-range|
-
-    |std-enqueue-blurb|
-
-    .. versionchanged:: 2011.1
-
-        Added the *g_times_l* keyword arg.
-
-    .. versionchanged:: 2020.2
-
-        Added the *allow_empty_ndrange* keyword argument.