From 68d551c2db92739510b0de5ee7f97ed88fe05eae Mon Sep 17 00:00:00 2001 From: Alexandru Fikl Date: Tue, 8 Nov 2022 20:59:39 +0200 Subject: [PATCH] use inline literals instead of default role --- README.rst | 7 ++- doc/algorithm.rst | 8 +-- doc/array.rst | 37 +++++++------- doc/index.rst | 2 +- doc/misc.rst | 12 ++--- doc/runtime.rst | 6 +-- doc/runtime_memory.rst | 8 +-- doc/runtime_platform.rst | 10 ++-- doc/runtime_program.rst | 10 ++-- doc/runtime_queue.rst | 2 +- pyopencl/algorithm.py | 102 +++++++++++++++++++-------------------- pyopencl/array.py | 26 +++++----- pyopencl/clmath.py | 16 +++--- pyopencl/clrandom.py | 13 ++--- pyopencl/elementwise.py | 2 +- pyopencl/scan.py | 40 +++++++-------- pyopencl/tools.py | 8 +-- 17 files changed, 154 insertions(+), 155 deletions(-) diff --git a/README.rst b/README.rst index c0e07aaa..dce0210e 100644 --- a/README.rst +++ b/README.rst @@ -16,16 +16,15 @@ PyOpenCL: Pythonic Access to OpenCL, with Arrays and Algorithms PyOpenCL lets you access GPUs and other massively parallel compute devices from Python. It tries to offer computing goodness in the -spirit of its sister project `PyCUDA `_: +spirit of its sister project `PyCUDA `__: * Object cleanup tied to lifetime of objects. This idiom, often - called - `RAII `_ + called `RAII `__ in C++, makes it much easier to write correct, leak- and crash-free code. * Completeness. PyOpenCL puts the full power of OpenCL's API at - your disposal, if you wish. Every obscure `get_info()` query and + your disposal, if you wish. Every obscure ``get_info()`` query and all CL calls are accessible. * Automatic Error Checking. All CL errors are automatically diff --git a/doc/algorithm.rst b/doc/algorithm.rst index 19842e1f..bfa66afb 100644 --- a/doc/algorithm.rst +++ b/doc/algorithm.rst @@ -109,8 +109,8 @@ greater than 300:: The value being scanned over is a number of flags indicating whether each array element is greater than 300. These flags are computed by *input_expr*. The prefix sum over this array gives a running count of array items greater than -300. The *output_statement* the compares `prev_item` (the previous item's scan -result, i.e. index) to `item` (the current item's scan result, i.e. +300. The *output_statement* the compares ``prev_item`` (the previous item's scan +result, i.e. index) to ``item`` (the current item's scan result, i.e. index). If they differ, i.e. if the predicate was satisfied at this position, then the item is stored in the output at the computed index. @@ -166,8 +166,8 @@ Simple / Legacy Interface .. versionchanged:: 2013.1 *neutral* is now always required. -For the array `[1,2,3]`, inclusive scan results in `[1,3,6]`, and exclusive -scan results in `[0,1,3]`. +For the array ``[1, 2, 3]``, inclusive scan results in ``[1, 3, 6]``, and exclusive +scan results in ``[0, 1, 3]``. Here's a usage example:: diff --git a/doc/array.rst b/doc/array.rst index a22ab5f6..c2e65941 100644 --- a/doc/array.rst +++ b/doc/array.rst @@ -21,25 +21,26 @@ Vector Types .. class :: vec - All of OpenCL's supported vector types, such as `float3` and `long4` are + All of OpenCL's supported vector types, such as ``float3`` and ``long4`` are available as :mod:`numpy` data types within this class. These - :class:`numpy.dtype` instances have field names of `x`, `y`, `z`, and `w` + :class:`numpy.dtype` instances have field names of ``x``, ``y``, ``z``, and ``w`` just like their OpenCL counterparts. They will work both for parameter passing to kernels as well as for passing data back and forth between kernels and - Python code. For each type, a `make_type` function is also provided (e.g. - `make_float3(x,y,z)`). + Python code. For each type, a ``make_type`` function is also provided (e.g. + ``make_float3(x, y, z)``). If you want to construct a pre-initialized vector type you have three new functions to choose from: - * `zeros_type()` - * `ones_type()` - * `filled_type(fill_value)` + * ``zeros_type()`` + * ``ones_type()`` + * ``filled_type(fill_value)`` .. versionadded:: 2014.1 .. versionchanged:: 2014.1 - The `make_type` functions have a default value (0) for each component. + + The ``make_type`` functions have a default value (0) for each component. Relying on the default values has been deprecated. Either specify all components or use one of th new flavors mentioned above for constructing a vector. @@ -96,8 +97,8 @@ support, PyOpenCL works around that deficiency. By saying:: #include -in your kernel, you get complex types `cfloat_t` and `cdouble_t`, along with -functions defined on them such as `cfloat_mul(a, b)` or `cdouble_log(z)`. +in your kernel, you get complex types ``cfloat_t`` and ``cdouble_t``, along with +functions defined on them such as ``cfloat_mul(a, b)`` or ``cdouble_log(z)``. Elementwise kernels automatically include the header if your kernel has complex input or output. See the `source file @@ -228,16 +229,16 @@ functions available in the OpenCL standard. (See table 6.8 in the spec.) .. function:: fmod(arg, mod, queue=None) - Return the floating point remainder of the division `arg/mod`, - for each element in `arg` and `mod`. + Return the floating point remainder of the division ``arg / mod``, + for each element in ``arg`` and ``mod``. .. TODO: fract .. function:: frexp(arg, queue=None) - Return a tuple `(significands, exponents)` such that - `arg == significand * 2**exponent`. + Return a tuple ``(significands, exponents)`` such that + ``arg == significand * 2**exponent``. .. TODO: hypot @@ -245,8 +246,8 @@ functions available in the OpenCL standard. (See table 6.8 in the spec.) .. function:: ldexp(significand, exponent, queue=None) Return a new array of floating point values composed from the - entries of `significand` and `exponent`, paired together as - `result = significand * 2**exponent`. + entries of ``significand`` and ``exponent``, paired together as + ``result = significand * 2**exponent``. .. function:: lgamma(array, queue=None) @@ -265,8 +266,8 @@ functions available in the OpenCL standard. (See table 6.8 in the spec.) .. function:: modf(arg, queue=None) - Return a tuple `(fracpart, intpart)` of arrays containing the - integer and fractional parts of `arg`. + Return a :class:`tuple` ``(fracpart, intpart)`` of arrays containing the + integer and fractional parts of ``arg``. .. function:: nan(array, queue=None) diff --git a/doc/index.rst b/doc/index.rst index 873d1f04..f4908952 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,7 +12,7 @@ What makes PyOpenCL special? crash-free code. * Completeness. PyOpenCL puts the full power of OpenCL's API at your - disposal, if you wish. Every obscure `get_info()` query and + disposal, if you wish. Every obscure ``get_info()`` query and all CL calls are accessible. * Automatic Error Checking. All errors are automatically translated diff --git a/doc/misc.rst b/doc/misc.rst index 8ded8710..52b4b745 100644 --- a/doc/misc.rst +++ b/doc/misc.rst @@ -193,7 +193,7 @@ checking `this file `__. Note that the triple-quoted strings containing the source must start with -`"""//CL// ..."""`. +``"""//CL// ..."""``. .. _ipython-integration: @@ -252,7 +252,7 @@ Relation with OpenCL's C Bindings We've tried to follow these guidelines when binding the OpenCL's C interface to Python: -* Remove the `cl_`, `CL_` and `cl` prefix from data types, macros and +* Remove the ``cl_``, ``CL_`` and ``cl`` prefix from data types, macros and function names. * Follow :pep:`8`, i.e. @@ -260,7 +260,7 @@ C interface to Python: * If a data type or function name is composed of more than one word, separate the words with a single underscore. -* `get_info` functions become attributes. +* ``get_info`` functions become attributes. * Object creation is done by constructors, to the extent possible. (i.e. minimize use of "factory functions") @@ -630,15 +630,15 @@ Version 0.91 * Add :ref:`gl-interop`. * Add a test suite. -* Fix numerous `get_info` bugs. (reports by David Garcia and the test suite) +* Fix numerous ``get_info`` bugs. (reports by David Garcia and the test suite) * Add :meth:`pyopencl.ImageFormat.__repr__`. * Add :meth:`pyopencl.addressing_mode.to_string` and colleagues. -* The `pitch` arguments to +* The ``pitch`` arguments to ``pyopencl.create_image_2d``, ``pyopencl.create_image_3d``, ``pyopencl.enqueue_read_image``, and ``pyopencl.enqueue_write_image`` - are now defaulted to zero. The argument order of `enqueue_{read,write}_image` + are now defaulted to zero. The argument order of ``enqueue_{read,write}_image`` has changed for this reason. * Deprecate ``pyopencl.create_image_2d``, diff --git a/doc/runtime.rst b/doc/runtime.rst index 800c52b7..22186095 100644 --- a/doc/runtime.rst +++ b/doc/runtime.rst @@ -15,16 +15,16 @@ Version Queries Gives the numeric version of PyOpenCL as a variable-length tuple of integers. Enables easy version checks such as - *VERSION >= (0, 93)*. + ``VERSION >= (0, 93)``. .. data:: VERSION_STATUS - A text string such as `"rc4"` or `"beta"` qualifying the status + A text string such as ``"rc4"`` or ``"beta"`` qualifying the status of the release. .. data:: VERSION_TEXT - The full release name (such as `"0.93rc4"`) in string form. + The full release name (such as ``"0.93rc4"``) in string form. .. function:: get_cl_header_version() diff --git a/doc/runtime_memory.rst b/doc/runtime_memory.rst index 849cce19..0d25c788 100644 --- a/doc/runtime_memory.rst +++ b/doc/runtime_memory.rst @@ -289,7 +289,7 @@ Image the distance in bytes from one scan line to the next, and from one 2D image slice to the next. - If *hostbuf* is given and *shape* is `None`, then *hostbuf.shape* is + If *hostbuf* is given and *shape* is *None*, then *hostbuf.shape* is used as the *shape* parameter. :class:`Image` inherits from :class:`MemoryObject`. @@ -345,11 +345,11 @@ Image .. note:: - When reading from the image object, the indices passed to `read_imagef` are - in the reverse order from what they would be when accessing *ary* from + When reading from the image object, the indices passed to ``read_imagef`` + are in the reverse order from what they would be when accessing *ary* from Python. - If *norm_int* is `True`, then the integer values are normalized to a floating + If *norm_int* is *True*, then the integer values are normalized to a floating point scale of 0..1 when read. .. versionadded:: 2011.2 diff --git a/doc/runtime_platform.rst b/doc/runtime_platform.rst index aeee8c56..4f5b847c 100644 --- a/doc/runtime_platform.rst +++ b/doc/runtime_platform.rst @@ -81,10 +81,10 @@ Device [ 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`. + where ``dpp`` represents :class:`device_partition_property` + and ``dad`` represent :class:`device_affinity_domain`. - `PROPERTIES_LIST_END_EXT` is added automatically. + ``PROPERTIES_LIST_END_EXT`` is added automatically. Only available with CL 1.2. @@ -111,13 +111,13 @@ Context 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 + 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* + 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:: diff --git a/doc/runtime_program.rst b/doc/runtime_program.rst index 91a68966..ea87e604 100644 --- a/doc/runtime_program.rst +++ b/doc/runtime_program.rst @@ -196,8 +196,8 @@ Kernel *arg* may be - * `None`: This may be passed for `__global` memory references - to pass a NULL pointer to the kernel. + * *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` @@ -268,7 +268,7 @@ Kernel 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) + (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 @@ -282,7 +282,7 @@ Kernel 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:`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. @@ -327,7 +327,7 @@ Kernel .. class:: LocalMemory(size) - A helper class to pass `__local` memory arguments to kernels. + A helper class to pass ``__local`` memory arguments to kernels. .. versionadded:: 0.91.2 diff --git a/doc/runtime_queue.rst b/doc/runtime_queue.rst index fbe0b664..dcc60a48 100644 --- a/doc/runtime_queue.rst +++ b/doc/runtime_queue.rst @@ -121,7 +121,7 @@ Event .. attribute:: info Lower case versions of the :class:`profiling_info` constants - may be used as attributes on the attribute `profile` of this + may be used as attributes on the attribute ``profile`` of this class to directly query profiling info. For example, you may use *evt.profile.end* instead of diff --git a/pyopencl/algorithm.py b/pyopencl/algorithm.py index a76b0ff7..0048a245 100644 --- a/pyopencl/algorithm.py +++ b/pyopencl/algorithm.py @@ -87,14 +87,14 @@ _copy_if_template = ScanTemplate( def copy_if(ary, predicate, extra_args=None, preamble="", queue=None, wait_for=None): """Copy the elements of *ary* satisfying *predicate* to an output array. - :arg predicate: a C expression evaluating to a `bool`, represented as a string. - The value to test is available as `ary[i]`, and if the expression evaluates - to `true`, then this value ends up in the output. + :arg predicate: a C expression evaluating to a ``bool``, represented as a string. + The value to test is available as ``ary[i]``, and if the expression evaluates + to ``true``, then this value ends up in the output. :arg extra_args: |scan_extra_args| :arg preamble: |preamble| :arg wait_for: |explain-waitfor| :returns: a tuple *(out, count, event)* where *out* is the output array, *count* - is an on-device scalar (fetch to host with `count.get()`) indicating + is an on-device scalar (fetch to host with ``count.get()``) indicating how many elements satisfied *predicate*, and *event* is a :class:`pyopencl.Event` for dependency management. *out* is allocated to the same length as *ary*, but only the first *count* entries carry @@ -136,14 +136,14 @@ def remove_if(ary, predicate, extra_args=None, preamble="", queue=None, wait_for=None): """Copy the elements of *ary* not satisfying *predicate* to an output array. - :arg predicate: a C expression evaluating to a `bool`, represented as a string. - The value to test is available as `ary[i]`, and if the expression evaluates - to `false`, then this value ends up in the output. + :arg predicate: a C expression evaluating to a ``bool``, represented as a string. + The value to test is available as ``ary[i]``, and if the expression evaluates + to ``false``, then this value ends up in the output. :arg extra_args: |scan_extra_args| :arg preamble: |preamble| :arg wait_for: |explain-waitfor| :returns: a tuple *(out, count, event)* where *out* is the output array, *count* - is an on-device scalar (fetch to host with `count.get()`) indicating + is an on-device scalar (fetch to host with ``count.get()``) indicating how many elements did not satisfy *predicate*, and *event* is a :class:`pyopencl.Event` for dependency management. @@ -178,13 +178,13 @@ def partition(ary, predicate, extra_args=None, preamble="", """Copy the elements of *ary* into one of two arrays depending on whether they satisfy *predicate*. - :arg predicate: a C expression evaluating to a `bool`, represented as a string. - The value to test is available as `ary[i]`. + :arg predicate: a C expression evaluating to a ``bool``, represented as a string. + The value to test is available as ``ary[i]``. :arg extra_args: |scan_extra_args| :arg preamble: |preamble| :arg wait_for: |explain-waitfor| :returns: a tuple *(out_true, out_false, count, event)* where *count* - is an on-device scalar (fetch to host with `count.get()`) indicating + is an on-device scalar (fetch to host with ``count.get()``) indicating how many elements satisfied the predicate, and *event* is a :class:`pyopencl.Event` for dependency management. @@ -247,15 +247,15 @@ def unique(ary, is_equal_expr="a == b", extra_args=None, preamble="", Works like the UNIX command :program:`uniq`, with a potentially custom comparison. This operation is often used on sorted sequences. - :arg is_equal_expr: a C expression evaluating to a `bool`, + :arg is_equal_expr: a C expression evaluating to a ``bool``, represented as a string. The elements being compared are - available as `a` and `b`. If this expression yields `false`, the + available as ``a`` and ``b``. If this expression yields ``false``, the two are considered distinct. :arg extra_args: |scan_extra_args| :arg preamble: |preamble| :arg wait_for: |explain-waitfor| :returns: a tuple *(out, count, event)* where *out* is the output array, *count* - is an on-device scalar (fetch to host with `count.get()`) indicating + is an on-device scalar (fetch to host with ``count.get()``) indicating how many elements satisfied the predicate, and *event* is a :class:`pyopencl.Event` for dependency management. @@ -443,7 +443,7 @@ class RadixSort: (see :func:`pyopencl.tools.get_or_register_dtype`). :arg key_expr: An integer-valued C expression returning the key based on which the sort is performed. The array index - for which the key is to be computed is available as `i`. + for which the key is to be computed is available as ``i``. The expression may refer to any of the *arguments*. :arg sort_arg_names: A list of argument names whose corresponding array arguments will be sorted according to *key_expr*. @@ -763,10 +763,10 @@ class ListOfListsBuilder: assert inf.count == 3000 assert (inf.list.get()[-6:] == [1, 2, 2, 3, 3, 3]).all() - The function `generate` above is called once for each "input object". + The function ``generate`` above is called once for each "input object". Each input object can then generate zero or more list entries. The number of these input objects is given to :meth:`__call__` as *n_objects*. - List entries are generated by calls to `APPEND_(value)`. + List entries are generated by calls to ``APPEND_(value)``. Multiple lists may be generated at once. .. automethod:: __init__ @@ -779,34 +779,34 @@ class ListOfListsBuilder: eliminate_empty_output_lists=False): """ :arg context: A :class:`pyopencl.Context`. - :arg list_names_and_dtypes: a list of `(name, dtype)` tuples + :arg list_names_and_dtypes: a list of ``(name, dtype)`` tuples indicating the lists to be built. :arg generate_template: a snippet of C as described below :arg arg_decls: A string of comma-separated C argument declarations. - :arg count_sharing: A mapping consisting of `(child, mother)` - indicating that `mother` and `child` will always have the - same number of indices, and the `APPEND` to `mother` - will always happen *before* the `APPEND` to the child. + :arg count_sharing: A mapping consisting of ``(child, mother)`` + indicating that ``mother`` and ``child`` will always have the + same number of indices, and the ``APPEND`` to ``mother`` + will always happen *before* the ``APPEND`` to the child. :arg name_prefix: the name prefix to use for the compiled kernels :arg options: OpenCL compilation options for kernels using *generate_template*. - :arg complex_kernel: If `True`, prevents vectorization on CPUs. + :arg complex_kernel: If *True*, prevents vectorization on CPUs. :arg eliminate_empty_output_lists: A Python list of list names for which the empty output lists are eliminated. *generate_template* may use the following C macros/identifiers: - * `index_type`: expands to C identifier for the index type used + * ``index_type``: expands to C identifier for the index type used for the calculation - * `USER_ARG_DECL`: expands to the C declarator for `arg_decls` - * `USER_ARGS`: a list of C argument values corresponding to - `user_arg_decl` - * `LIST_ARG_DECL`: expands to a C argument list representing the + * ``USER_ARG_DECL``: expands to the C declarator for ``arg_decls`` + * ``USER_ARGS``: a list of C argument values corresponding to + ``user_arg_decl`` + * ``LIST_ARG_DECL``: expands to a C argument list representing the data for the output lists. These are escaped prefixed with - `"plg_"` so as to not interfere with user-provided names. - * `LIST_ARGS`: a list of C argument values corresponding to - `LIST_ARG_DECL` - * `APPEND_name(entry)`: inserts `entry` into the list `name`. + ``"plg_"`` so as to not interfere with user-provided names. + * ``LIST_ARGS``: a list of C argument values corresponding to + ``LIST_ARG_DECL`` + * ``APPEND_name(entry)``: inserts ``entry`` into the list ``name``. *entry* must be a valid C expression of the correct type. All argument-list related macros have a trailing comma included @@ -821,16 +821,16 @@ class ListOfListsBuilder: APPEND_mylist(5); } - Internally, the `kernel_template` is expanded (at least) twice. Once, + Internally, the ``kernel_template`` is expanded (at least) twice. Once, for a 'counting' stage where the size of all the lists is determined, and a second time, for a 'generation' stage where the lists are - actually filled. A `generate` function that has side effects beyond - calling `append` is therefore ill-formed. + actually filled. A ``generate`` function that has side effects beyond + calling ``append`` is therefore ill-formed. .. versionchanged:: 2018.1 - Change *eliminate_empty_output_lists* argument type from `bool` to - `list`. + Change *eliminate_empty_output_lists* argument type from ``bool`` to + ``list``. """ if devices is None: devices = context.devices @@ -1062,28 +1062,26 @@ class ListOfListsBuilder: def __call__(self, queue, n_objects, *args, **kwargs): """ - :arg args: arguments corresponding to arg_decls in the constructor. - Array-like arguments must be either - 1D :class:`pyopencl.array.Array` objects or - :class:`pyopencl.MemoryObject` objects, of which the latter + :arg args: arguments corresponding to ``arg_decls`` in the constructor. + Array-like arguments must be either 1D :class:`pyopencl.array.Array` + objects or :class:`pyopencl.MemoryObject` objects, of which the latter can be obtained from a :class:`pyopencl.array.Array` using the :attr:`pyopencl.array.Array.data` attribute. :arg allocator: optionally, the allocator to use to allocate new arrays. - :arg omit_lists: An iterable of list names that should *not* be built + :arg omit_lists: an iterable of list names that should *not* be built with this invocation. The kernel code may *not* call ``APPEND_name`` for these omitted lists. If it does, undefined behavior will result. The returned *lists* dictionary will not contain an entry for names in *omit_lists*. :arg wait_for: |explain-waitfor| - :returns: a tuple ``(lists, event)``, where - *lists* a mapping from (built) list names to objects which - have attributes + :returns: a tuple ``(lists, event)``, where ``lists`` is a mapping from + (built) list names to objects which have attributes * ``count`` for the total number of entries in all lists combined * ``lists`` for the array containing all lists. - * ``starts`` for the array of starting indices in `lists`. - `starts` is built so that it has n+1 entries, so that + * ``starts`` for the array of starting indices in ``lists``. + ``starts`` is built so that it has n+1 entries, so that the *i*'th entry is the start of the *i*'th list, and the *i*'th entry is the index one past the *i*'th list's end, even for the last list. @@ -1097,9 +1095,9 @@ class ListOfListsBuilder: * ``num_nonempty_lists`` for the number of nonempty lists. * ``nonempty_indices`` for the index of nonempty list in input objects. - In this case, `starts` has `num_nonempty_lists` + 1 entries. The *i*'s - entry is the start of the *i*'th nonempty list, which is generated by - the object with index *nonempty_indices[i]*. + In this case, ``starts`` has ``num_nonempty_lists + 1`` entries. + The *i*'s entry is the start of the *i*'th nonempty list, which is + generated by the object with index ``nonempty_indices[i]``. *event* is a :class:`pyopencl.Event` for dependency management. @@ -1348,12 +1346,12 @@ class KeyValueSorter: and a number *nkeys* of keys, returns a tuple `(starts, lists)`, as follows: *values* and *keys* are sorted by *keys*, and the sorted *values* is returned as - *lists*. Then for each index *i* in `range(nkeys)`, + *lists*. Then for each index *i* in ``range(nkeys)``, *starts[i]* is written to indicating where the group of *values* belonging to the key with index *i* begins. It implicitly ends at *starts[i+1]*. - `starts` is built so that it has `nkeys+1` entries, so that + ``starts`` is built so that it has ``nkeys + 1`` entries, so that the *i*'th entry is the start of the *i*'th list, and the *i*'th entry is the index one past the *i*'th list's end, even for the last list. diff --git a/pyopencl/array.py b/pyopencl/array.py index aab88783..2a2757bc 100644 --- a/pyopencl/array.py +++ b/pyopencl/array.py @@ -348,7 +348,7 @@ class Array: operators and many other niceties) are not desired, pass a :class:`~pyopencl.Context`. - *allocator* may be `None` or a callable that, upon being called with an + *allocator* may be *None* or a callable that, upon being called with an argument of the number of bytes to be allocated, returns a :class:`pyopencl.Buffer` object. (A :class:`pyopencl.tools.MemoryPool` instance is one useful example of an object to pass here.) @@ -419,8 +419,8 @@ class Array: .. attribute :: flags - An object with attributes `c_contiguous`, `f_contiguous` and - `forc`, which may be used to query contiguity properties in analogy to + An object with attributes ``c_contiguous``, ``f_contiguous`` and + ``forc``, which may be used to query contiguity properties in analogy to :attr:`numpy.ndarray.flags`. .. rubric:: Methods @@ -891,7 +891,7 @@ class Array: .. versionchanged:: 2019.1.2 - Calling with `async_=True` was deprecated and replaced by + Calling with ``async_=True`` was deprecated and replaced by :meth:`get_async`. The event returned by :meth:`pyopencl.enqueue_copy` is now stored into :attr:`events` to ensure data is not modified before the copy is @@ -910,7 +910,7 @@ class Array: """ if async_: - warn("calling pyopencl.Array.get with `async_=True` is deprecated. " + warn("calling pyopencl.Array.get with 'async_=True' is deprecated. " "Please use pyopencl.Array.get_async for asynchronous " "device-to-host transfers", DeprecationWarning, 2) @@ -922,8 +922,8 @@ class Array: def get_async(self, queue=None, ary=None, **kwargs): """ Asynchronous version of :meth:`get` which returns a tuple ``(ary, event)`` - containing the host array `ary` - and the :class:`pyopencl.NannyEvent` `event` returned by + containing the host array ``ary`` + and the :class:`pyopencl.NannyEvent` ``event`` returned by :meth:`pyopencl.enqueue_copy`. .. versionadded:: 2019.1.2 @@ -1190,7 +1190,7 @@ class Array: # {{{ operators def mul_add(self, selffac, other, otherfac, queue=None): - """Return `selffac * self + otherfac*other`. + """Return ``selffac * self + otherfac * other``. """ queue = queue or self.queue @@ -1589,7 +1589,7 @@ class Array: return TypeError("len() of unsized object") def __abs__(self): - """Return a `Array` of the absolute values of the elements + """Return an ``Array`` of the absolute values of the elements of *self*. """ @@ -2429,13 +2429,13 @@ def _arange_knl(result, start, step): def arange(queue, *args, **kwargs): """arange(queue, [start, ] stop [, step], **kwargs) - Create a :class:`Array` filled with numbers spaced `step` apart, - starting from `start` and ending at `stop`. If not given, *start* + Create a :class:`Array` filled with numbers spaced *step* apart, + starting from *start* and ending at *stop*. If not given, *start* defaults to 0, *step* defaults to 1. For floating point arguments, the length of the result is - `ceil((stop - start)/step)`. This rule may result in the last - element of the result being greater than `stop`. + ``ceil((stop - start)/step)``. This rule may result in the last + element of the result being greater than *stop*. *dtype* is a required keyword argument. diff --git a/pyopencl/clmath.py b/pyopencl/clmath.py index 58c20ce5..b5c4fdfc 100644 --- a/pyopencl/clmath.py +++ b/pyopencl/clmath.py @@ -128,8 +128,8 @@ def _fmod(result, arg, mod): def fmod(arg, mod, queue=None): - """Return the floating point remainder of the division `arg/mod`, - for each element in `arg` and `mod`.""" + """Return the floating point remainder of the division ``arg / mod``, + for each element in ``arg`` and ``mod``.""" queue = (queue or arg.queue) or mod.queue result = arg._new_like_me(_get_common_dtype(arg, mod, queue)) result.add_event(_fmod(result, arg, mod, queue=queue)) @@ -145,8 +145,8 @@ def _frexp(sig, expt, arg): def frexp(arg, queue=None): - """Return a tuple `(significands, exponents)` such that - `arg == significand * 2**exponent`. + """Return a tuple ``(significands, exponents)`` such that + ``arg == significand * 2**exponent``. """ sig = arg._new_like_me(queue=queue) expt = arg._new_like_me(queue=queue, dtype=np.int32) @@ -169,8 +169,8 @@ def _ldexp(result, sig, exp): def ldexp(significand, exponent, queue=None): """Return a new array of floating point values composed from the - entries of `significand` and `exponent`, paired together as - `result = significand * 2**exponent`. + entries of ``significand`` and ``exponent``, paired together as + ``result = significand * 2**exponent``. """ result = significand._new_like_me(queue=queue) result.add_event(_ldexp(result, significand, exponent)) @@ -198,8 +198,8 @@ def _modf(intpart, fracpart, arg): def modf(arg, queue=None): - """Return a tuple `(fracpart, intpart)` of arrays containing the - integer and fractional parts of `arg`. + """Return a tuple ``(fracpart, intpart)`` of arrays containing the + integer and fractional parts of ``arg``. """ intpart = arg._new_like_me(queue=queue) fracpart = arg._new_like_me(queue=queue) diff --git a/pyopencl/clrandom.py b/pyopencl/clrandom.py index d9ca92ac..e9055913 100644 --- a/pyopencl/clrandom.py +++ b/pyopencl/clrandom.py @@ -99,7 +99,7 @@ class RanluxGenerator: >=24, in which case it directly sets the p-value of RANLUXCL. :param num_work_items: is the number of generators to initialize, usually corresponding to the number of work-items in the NDRange - RANLUXCL will be used with. May be `None`, in which case a default + RANLUXCL will be used with. May be *None*, in which case a default value is used. :param max_work_items: should reflect the maximum number of work-items that will be used on any parallel instance of RANLUXCL. So for @@ -108,10 +108,11 @@ class RanluxGenerator: calling ranluxcl_intialization with numWorkitems = 5120 while GPU2's RANLUXCLTab would use numWorkitems = 10240. However maxWorkitems must be at least 10240 for both GPU1 and GPU2, and it - must be set to the same value for both. (may be `None`) + must be set to the same value for both. (may be *None*) .. versionchanged:: 2013.1 - Added default value for `num_work_items`. + + Added default value for ``num_work_items``. """ from warnings import warn @@ -738,7 +739,7 @@ def _get_generator(context): def fill_rand(result, queue=None, luxury=None, a=0, b=1): - """Fill *result* with random values of `dtype` in the range [0,1). + """Fill *result* with random values in the range :math:`[0, 1)`. """ if luxury is not None: from warnings import warn @@ -752,8 +753,8 @@ def fill_rand(result, queue=None, luxury=None, a=0, b=1): def rand(queue, shape, dtype, luxury=None, a=0, b=1): - """Return an array of `shape` filled with random values of `dtype` - in the range [a,b). + """Return an array of *shape* filled with random values of *dtype* + in the range :math:`[a, b)`. """ if luxury is not None: diff --git a/pyopencl/elementwise.py b/pyopencl/elementwise.py index ac66e6f3..4bf69ca5 100644 --- a/pyopencl/elementwise.py +++ b/pyopencl/elementwise.py @@ -216,7 +216,7 @@ class ElementwiseKernel: :arg preamble: a piece of C source code that gets inserted outside of the function context in the elementwise operation's kernel source code. - .. warning :: Using a `return` statement in *operation* will lead to + .. warning :: Using a ``return`` statement in *operation* will lead to incorrect results, as some elements may never get processed. Use ``PYOPENCL_ELWISE_CONTINUE`` instead. diff --git a/pyopencl/scan.py b/pyopencl/scan.py index 0ad64e3a..9d1851bb 100644 --- a/pyopencl/scan.py +++ b/pyopencl/scan.py @@ -953,54 +953,54 @@ class GenericScanKernelBase(ABC): specified. All types used here must be known to PyOpenCL. (see :func:`pyopencl.tools.get_or_register_dtype`). :arg scan_expr: The associative, binary operation carrying out the scan, - represented as a C string. Its two arguments are available as `a` - and `b` when it is evaluated. `b` is guaranteed to be the - 'element being updated', and `a` is the increment. Thus, + represented as a C string. Its two arguments are available as ``a`` + and ``b`` when it is evaluated. ``b`` is guaranteed to be the + 'element being updated', and ``a`` is the increment. Thus, if some data is supposed to just propagate along without being - modified by the scan, it should live in `b`. + modified by the scan, it should live in ``b``. This expression may call functions given in the *preamble*. - Another value available to this expression is `across_seg_boundary`, + Another value available to this expression is ``across_seg_boundary``, a C `bool` indicating whether this scan update is crossing a - segment boundary, as defined by `is_segment_start_expr`. + segment boundary, as defined by ``is_segment_start_expr``. The scan routine does not implement segmentation - semantics on its own. It relies on `scan_expr` to do this. - This value is available (but always `false`) even for a + semantics on its own. It relies on ``scan_expr`` to do this. + This value is available (but always ``false``) even for a non-segmented scan. .. note:: In early pre-releases of the segmented scan, segmentation semantics were implemented *without* - relying on `scan_expr`. + relying on ``scan_expr``. :arg input_expr: A C expression, encoded as a string, resulting in the values to which the scan is applied. This may be used to apply a mapping to values stored in *arguments* before being scanned. The result of this expression must match *dtype*. - The index intended to be mapped is available as `i` in this + The index intended to be mapped is available as ``i`` in this expression. This expression may also use the variables defined by *input_fetch_expr*. This expression may also call functions given in the *preamble*. :arg output_statement: a C statement that writes - the output of the scan. It has access to the scan result as `item`, - the preceding scan result item as `prev_item`, and the current index - as `i`. `prev_item` in a segmented scan will be the neutral element + the output of the scan. It has access to the scan result as ``item``, + the preceding scan result item as ``prev_item``, and the current index + as ``i``. ``prev_item`` in a segmented scan will be the neutral element at a segment boundary, not the immediately preceding item. Using *prev_item* in output statement has a small run-time cost. - `prev_item` enables the construction of an exclusive scan. + ``prev_item`` enables the construction of an exclusive scan. For non-segmented scans, *output_statement* may also reference - `last_item`, which evaluates to the scan result of the last + ``last_item``, which evaluates to the scan result of the last array entry. :arg is_segment_start_expr: A C expression, encoded as a string, - resulting in a C `bool` value that determines whether a new + resulting in a C ``bool`` value that determines whether a new scan segments starts at index *i*. If given, makes the scan a - segmented scan. Has access to the current index `i`, the result - of *input_expr* as `a`, and in addition may use *arguments* and + segmented scan. Has access to the current index ``i``, the result + of *input_expr* as ``a``, and in addition may use *arguments* and *input_fetch_expr* variables just like *input_expr*. If it returns true, then previous sums will not spill over into the @@ -1011,8 +1011,8 @@ class GenericScanKernelBase(ABC): ARG_NAME_TYPE NAME = ARG_NAME[i+OFFSET]; - `OFFSET` is allowed to be 0 or -1, and `ARG_NAME_TYPE` is the type - of `ARG_NAME`. + ``OFFSET`` is allowed to be 0 or -1, and ``ARG_NAME_TYPE`` is the type + of ``ARG_NAME``. :arg preamble: |preamble| The first array in the argument list determines the size of the index diff --git a/pyopencl/tools.py b/pyopencl/tools.py index 1e8840a1..ba9a0eee 100644 --- a/pyopencl/tools.py +++ b/pyopencl/tools.py @@ -383,7 +383,7 @@ def _monkeypatch_svm_docstrings(): .. automethod:: enqueue_release - Synonymous to :meth;`release`, for consistency with + Synonymous to :meth:`release`, for consistency with :class:`~pyopencl.SVMAllocation`. Note that, unlike :meth:`pyopencl.SVMAllocation.enqueue_release`, specifying a queue or events to be waited for is not supported. @@ -1020,8 +1020,8 @@ class _CDeclList: @memoize def match_dtype_to_c_struct(device, name, dtype, context=None): - """Return a tuple `(dtype, c_decl)` such that the C struct declaration - in `c_decl` and the structure :class:`numpy.dtype` instance `dtype` + """Return a tuple ``(dtype, c_decl)`` such that the C struct declaration + in ``c_decl`` and the structure :class:`numpy.dtype` instance ``dtype`` have the same memory layout. Note that *dtype* may be modified from the value that was passed in, @@ -1052,7 +1052,7 @@ def match_dtype_to_c_struct(device, name, dtype, context=None): >>> cl.tools.get_or_register_dtype('id_val', dtype) As this example shows, it is important to call - :func:`get_or_register_dtype` on the modified `dtype` returned by this + :func:`get_or_register_dtype` on the modified ``dtype`` returned by this function, not the original one. """ -- GitLab