diff --git a/doc/source/array.rst b/doc/source/array.rst index df551ca2e02d2c5fb7f98927b3752cf869e1d78e..a8914eb7aa6e0bcdbcbb8851590e4069fbe09f25 100644 --- a/doc/source/array.rst +++ b/doc/source/array.rst @@ -34,6 +34,42 @@ about them using this function: .. versionadded: 2011.2 +Complex Numbers +^^^^^^^^^^^^^^^ + +PyOpenCL's :class:`Array` type supports complex numbers out of the box, by +simply using the corresponding :mod:`numpy` types. + +If you would like to use this support in your own kernels, here's how to +proceed: Since OpenCL 1.2 (and earlier) do not specify native complex number +support, PyOpenCL works around that deficiency. By saying:: + + #include <pyopencl-complex.h> + +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 +<https://github.com/inducer/pyopencl/blob/master/src/cl/pyopencl-complex.h>`_ +for a precise list of what's available. + +If you need double precision support, please:: + + #define PYOPENCL_DEFINE_CDOUBLE + +before including the header, as DP support apparently cannot be reliably +autodetected. + +Under the hood, the complex types are simply `float2` and `double2`. + +.. warning:: + Note that addition (real + complex) and multiplication (complex*complex) + are defined for e.g. `float2`, but yield wrong results, so that you need to + use the corresponding functions. + +.. versionadded:: 2012.1 + The :class:`Array` Class ------------------------ @@ -398,38 +434,6 @@ functions available in the OpenCL standard. (See table 6.8 in the spec.) .. function:: tgamma(array, queue=None) .. function:: trunc(array, queue=None) -Complex Numbers ---------------- - -Since OpenCL 1.2 (and earlier) do not specify native complex number support, -PyOpenCL works around that deficiency. By saying:: - - #include <pyopencl-complex.h> - -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 -<https://github.com/inducer/pyopencl/blob/master/src/cl/pyopencl-complex.h>`_ -for a precise list of what's available. - -If you need double precision support, please:: - - #define PYOPENCL_DEFINE_CDOUBLE - -before including the header, as DP support apparently cannot be reliably -autodetected. - -Under the hood, the complex types are simply `float2` and `double2`. - -.. warning:: - Note that addition (real + complex) and multiplication (complex*complex) - are defined for e.g. `float2`, but yield wrong results, so that you need to - use the corresponding functions. - -.. versionadded:: 2012.1 - Generating Arrays of Random Numbers -----------------------------------