[pypy-commit] pypy.org extradoc: Update the "Installing NumPy" section. Push numpy-via-cpyext forward.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: extradoc
Changeset: r775:2f768f8073b0
Date: 2016-08-06 13:02 +0200
http://bitbucket.org/pypy/pypy.org/changeset/2f768f8073b0/

Log:	Update the "Installing NumPy" section. Push numpy-via-cpyext
	forward.

diff --git a/download.html b/download.html
--- a/download.html
+++ b/download.html
@@ -206,14 +206,38 @@
 <h1>Installing more modules</h1>
 <p>The recommended way is to install <tt class="docutils literal">pip</tt>, which is the standard package
 manager of Python.  It works like it does on CPython as explained in the
-<a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a></p>
+<a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a>.</p>
 </div>
 <div class="section" id="installing-numpy">
 <h1>Installing NumPy</h1>
-<p>NumPy is an exception to the rule that most packages work without
-changes.  The “numpy” module needs to be installed from <a class="reference external" href="https://bitbucket.org/pypy/numpy">our own
-repository</a> rather than from the official source.</p>
-<p>If you have pip:</p>
+<p><strong>There are two different versions of NumPy for PyPy.</strong></p>
+<div class="section" id="numpy-via-cpyext">
+<h2>1. NumPy via cpyext</h2>
+<p>The generally recommended way is to install the original NumPy via the
+CPython C API compatibility layer, cpyext.  Modern versions of PyPy
+support enough of the C API to make this a reasonable choice in many
+cases.  Performance-wise, the speed is mostly the same as CPython's
+NumPy (it is the same code); the exception is that interactions between
+the Python side and NumPy objects are mediated through the slower cpyext
+layer (which hurts a few benchmarks that do a lot of element-by-element
+array accesses, for example).</p>
+<p>Installation works as usual.  For example, without using a virtualenv:</p>
+<pre class="literal-block">
+$ ./pypy-xxx/bin/pypy -m ensurepip
+$ ./pypy-xxx/bin/pip install numpy
+</pre>
+<p>(See the general <a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a> for more.)</p>
+</div>
+<div class="section" id="numpypy">
+<h2>2. NumPyPy</h2>
+<p>The “numpy” module can be installed from <a class="reference external" href="https://bitbucket.org/pypy/numpy">our own repository</a> rather
+than from the official source.  This version uses internally our
+built-in <tt class="docutils literal">_numpypy</tt> module.  This module is slightly incomplete.
+Also, its performance is hard to predict exactly.  For regular NumPy
+source code that handles large arrays, it is likely to be slower than
+the native NumPy with cpyext.  It is faster on the kind of code that
+contains many Python loops doing things on an element-by-element basis.</p>
+<p>Installation (see the <a class="reference external" href="http://doc.pypy.org/en/latest/install.html">installation documentation</a> for installing <tt class="docutils literal">pip</tt>):</p>
 <pre class="literal-block">
 pypy -m pip install git+https://bitbucket.org/pypy/numpy.git
 </pre>
@@ -227,10 +251,11 @@
 <pre class="literal-block">
 sudo pypy -c 'import numpy'
 </pre>
-<p>Note that NumPy support is still a work-in-progress, many things do not
-work and those that do may not be any faster than NumPy on CPython.
+<p>Note again that this version is still a work-in-progress: many things do
+not work and those that do may not be any faster than NumPy on CPython.
 For further instructions see <a class="reference external" href="https://bitbucket.org/pypy/numpy">the pypy/numpy repository</a>.</p>
 </div>
+</div>
 <div class="section" id="building-from-source">
 <span id="translate"></span><h1>Building from source</h1>
 <p>(see more build <a class="reference external" href="http://pypy.readthedocs.org/en/latest/build.html">instructions</a>)</p>
diff --git a/source/download.txt b/source/download.txt
--- a/source/download.txt
+++ b/source/download.txt
@@ -216,7 +216,7 @@
 
 The recommended way is to install ``pip``, which is the standard package
 manager of Python.  It works like it does on CPython as explained in the 
-`installation documentation`_
+`installation documentation`_.
 
 .. _installation documentation: http://doc.pypy.org/en/latest/install.html
 
@@ -224,13 +224,43 @@
 Installing NumPy
 -------------------------------
 
-NumPy is an exception to the rule that most packages work without
-changes.  The "numpy" module needs to be installed from `our own
-repository`__ rather than from the official source.
+**There are two different versions of NumPy for PyPy.**
+
+
+1. NumPy via cpyext
++++++++++++++++++++
+
+The generally recommended way is to install the original NumPy via the
+CPython C API compatibility layer, cpyext.  Modern versions of PyPy
+support enough of the C API to make this a reasonable choice in many
+cases.  Performance-wise, the speed is mostly the same as CPython's
+NumPy (it is the same code); the exception is that interactions between
+the Python side and NumPy objects are mediated through the slower cpyext
+layer (which hurts a few benchmarks that do a lot of element-by-element
+array accesses, for example).
+
+Installation works as usual.  For example, without using a virtualenv::
+    
+    $ ./pypy-xxx/bin/pypy -m ensurepip
+    $ ./pypy-xxx/bin/pip install numpy
+
+(See the general `installation documentation`_ for more.)
+
+
+2. NumPyPy
+++++++++++
+
+The "numpy" module can be installed from `our own repository`__ rather
+than from the official source.  This version uses internally our
+built-in ``_numpypy`` module.  This module is slightly incomplete.
+Also, its performance is hard to predict exactly.  For regular NumPy
+source code that handles large arrays, it is likely to be slower than
+the native NumPy with cpyext.  It is faster on the kind of code that
+contains many Python loops doing things on an element-by-element basis.
 
 .. __: https://bitbucket.org/pypy/numpy
 
-If you have pip::
+Installation (see the `installation documentation`_ for installing ``pip``)::
 
     pypy -m pip install git+https://bitbucket.org/pypy/numpy.git
 
@@ -244,8 +274,8 @@
 
     sudo pypy -c 'import numpy'
 
-Note that NumPy support is still a work-in-progress, many things do not
-work and those that do may not be any faster than NumPy on CPython.
+Note again that this version is still a work-in-progress: many things do
+not work and those that do may not be any faster than NumPy on CPython.
 For further instructions see `the pypy/numpy repository`__.
 
 .. __: https://bitbucket.org/pypy/numpy