diff --git a/README.rst b/README.rst index c0e07aaa83c4ec2ddc02798c9bfb0fba5daa7056..dce0210ef2a80966e64e11310f9754388156d202 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 19842e1fba4ca9f40c6822aebc1d436ac5a760a3..bfa66afb2603f29446957ecf409509cf7436f05b 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 a22ab5f6cd226d149a06da96aff0344809e2eb9a..c2e65941da166d7499a4e1dbe4e88c831a3e41cc 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 873d1f0443c28fe5b4a81e1a2abde07ea677f6a7..f490895267d8c2286e325e72bc5e41f7d09f690f 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 8ded8710a0cc2de33f917ed6173fcb629924d4cd..52b4b745e53646ac648308fe25b5ddb9196df6b3 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 800c52b791b9211855277c72e71011e548f2df96..22186095c1322558698c6f4077cf183f87350cfb 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 849cce190c2a54d362f83a6f958329a5f3f3c0ea..0d25c788b55429ba53d35deeeee6aada70345ac7 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 aeee8c56460cd505ba0665a0760a395de3c4a2ef..4f5b847c0789afcc50abf652ffee027e89974c87 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 91a68966acf45d0b5e1ca01090b9224636726c82..ea87e6041c88d63076a0a27be8f12564f52b43cf 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 fbe0b66455511c7aa0c0eea6420363db98c73f3d..dcc60a48cbc1189ddf23e64cb3c21ae882840e49 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 a76b0ff71df12361d43f4750fbdd6b0c34f95995..0048a2455d0a122a1ceee807f24fe3055cef976c 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 aab8878349273abb4cd4ec0d3ad6707c46ef3fcd..2a2757bca9af202adb93e6e97ea8a7be09e1b079 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 58c20ce5f48fa25379dd5d84bce95709537c6d61..b5c4fdfcba28d34487fedcb9dd1a88ae8646b07c 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 d9ca92ac1eef66fa1c067a7f4bd776ee4252056f..e9055913e7b63c68605395bab7e816c5917d8927 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 ac66e6f36d795f2ab104aec4865432d2326fb54b..4bf69ca5cd3452946c98b132447e4077fb00e3d2 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 0ad64e3ad8828e57350ac9d310c36acc79994bd9..9d1851bb58670375d9ad0b75736fd8f9a1b7e8d6 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 1e8840a1bd814ad1bea8eb5bae3145783b0ee971..ba9a0eee47285aafdb62fd3c987c88fae7b16e8e 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. """