start documentation of Numba support

doc/source/index.rst

@@ -153,6 +153,7 @@ development environments.
    stl
    exceptions
    python
+   numba
    lowlevel
    misc
    debugging

doc/source/installation.rst

@@ -11,8 +11,9 @@ clang5, or MSVC'17.
 
 .. note::
 
-    On Windows, a command prompt or Python process needs to be opend with
-    the MSVC environment setup for the compiler to be accessible.
+    On Windows, a command prompt from which to run Python (or Python run
+    directly) needs to be opened from within an environment with MSVC setup,
+    otherwise the compiler will not be accessible.
 
 When installing from source, the only requirement is full support for C++11
 (e.g. minimum gcc 4.8.1 on GNU/Linux), but older compilers than the ones

doc/source/numba.rst

@@ -0,0 +1,99 @@
+.. _Numba:
+
+
+Numba support
+=============
+
+.. warning::
+
+    This is an **experimental** feature, available starting with release
+    2.4.0.
+    It is still incomplete (see listing below) and has only been tested on
+    Linux on x86_64.
+
+`Numba`_ is a JIT compiler for Python functions that can be statically typed
+based on their input arguments.
+Since C++ objects are always statically typed and already implemented at the
+machine level, they can be dynamically integrated into the Numba type tracing
+and lowering by exposing type details through C++ reflection at runtime.
+
+JIT-compiling traces of mixed Python/bound C++ code reduces (or even removes)
+the overhead of boxing/unboxing native data into their Python proxies and vice
+veras.
+It can also remove temporaries, especially for template expressions.
+Thus, there can be a significant speedup for mixed code, beyond the compilation
+of Python code itself.
+Note that the current implementation integrates compiled C++ into the
+intermediate representation (IR) as generated by Numba.
+A future version may integrate C++ (Cling-generated) IR with Numba IR, if the
+C++ code is exposed from (precompiled) header files, thus allowing inlining of
+C++ code into Numba traces, for further expected speedups.
+
+
+`Usage`
+-------
+
+``cppyy`` exposes extension hooks that automatically make it available to
+Numba.
+If, however, you do not use ``setuptools`` (through ``pip`` or otherwise),
+you can load the extensions explicitly::
+
+    >>> import cppyy.numba_ext
+    >>> 
+
+After that, Numba is able to trace ``cppyy`` bound code.
+Note that the ``numba_ext`` module will register only the proxy base classes,
+to keep overheads to a minimum.
+The pre-registerd base classes will, lazily and automatically, register
+further type information for the concrete classess and overloads on actual
+use in Numba traces, not from other uses.
+
+
+`Examples`
+----------
+
+The following, non-exhaustive, set of examples gives an idea of the current
+level of support.
+The overall goal, however, is to be able to use ``cppyy`` bound code in Numba
+traces in the same as it can be used in normal Python code.
+
+C++ free (global) functions can be called and overloads will be selected, or a
+template will be instantiated, based on the provided types, assuming all types
+match explicitly (thus e.g. typedefs, implicit conversions, and default
+arguments are not yet supported).
+Example:
+
+  .. code-block:: python
+
+    >>> import cppyy
+    >>> import numba
+    >>> import numpy as np
+    >>>
+    >>> cppyy.cppdef("""
+    ... template<typename T>
+    ... T square(T t) { return t*t; }
+    ... """)
+    True
+    >>> @numba.jit(nopython=True)
+    ... def tsa(a):
+    ...     total = type(a[0])(0)
+    ...     for i in range(len(a)):
+    ...         total += cppyy.gbl.square(a[i])
+    ...     return total
+    ...
+    >>> a = np.array(range(10), dtype=np.float32)
+    >>> print(tsa(a))
+    285.0
+    >>> a = np.array(range(10), dtype=np.int64)
+    >>> print(tsa(a))
+    285
+    >>>
+
+Instances of C++ classes can be passed into Numba traces.
+They can be returned from functions called _within_ the trace, but can not yet
+be returned _from_ the trace.
+Their public data is accessible (read-only) if of builtin type and their public
+methods can be called.
+Overload selection among methods works.
+
+.. _Numbal: https://numba.pydata.org/