Skip to content

Commit 53d7e68

Browse files
charrischarris
committed
Merge pull request numpy#6560 from pv/userguide-up
DOC: user guide update
2 parents 42fefc5 + 4b1f124 commit 53d7e68

File tree

17 files changed

+2276
-282
lines changed

17 files changed

+2276
-282
lines changed

‎doc/source/reference/routines.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _routines:
2+
13
********
24
Routines
35
********

‎doc/source/user/basics.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ Numpy basics
33
************
44

55
.. toctree::
6-
:maxdepth: 2
6+
:maxdepth: 1
77

88
basics.types
99
basics.creation

‎doc/source/user/building.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
.. _building-from-source:
2+
3+
Building from source
4+
====================
5+
6+
A general overview of building NumPy from source is given here, with detailed
7+
instructions for specific platforms given seperately.
8+
9+
Prerequisites
10+
-------------
11+
12+
Building NumPy requires the following software installed:
13+
14+
1) Python 2.6.x, 2.7.x, 3.2.x or newer
15+
16+
On Debian and derivatives (Ubuntu): python, python-dev (or python3-dev)
17+
18+
On Windows: the official python installer at
19+
`www.python.org <http://www.python.org>`_ is enough
20+
21+
Make sure that the Python package distutils is installed before
22+
continuing. For example, in Debian GNU/Linux, installing python-dev
23+
also installs distutils.
24+
25+
Python must also be compiled with the zlib module enabled. This is
26+
practically always the case with pre-packaged Pythons.
27+
28+
2) Compilers
29+
30+
To build any extension modules for Python, you'll need a C compiler.
31+
Various NumPy modules use FORTRAN 77 libraries, so you'll also need a
32+
FORTRAN 77 compiler installed.
33+
34+
Note that NumPy is developed mainly using GNU compilers. Compilers from
35+
other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland,
36+
Lahey, HP, IBM, Microsoft are only supported in the form of community
37+
feedback, and may not work out of the box. GCC 4.x (and later) compilers
38+
are recommended.
39+
40+
3) Linear Algebra libraries
41+
42+
NumPy does not require any external linear algebra libraries to be
43+
installed. However, if these are available, NumPy's setup script can detect
44+
them and use them for building. A number of different LAPACK library setups
45+
can be used, including optimized LAPACK libraries such as ATLAS, MKL or the
46+
Accelerate/vecLib framework on OS X.
47+
48+
Basic Installation
49+
------------------
50+
51+
To install NumPy run::
52+
53+
python setup.py install
54+
55+
To perform an in-place build that can be run from the source folder run::
56+
57+
python setup.py build_ext --inplace
58+
59+
The NumPy build system uses ``distutils`` and ``numpy.distutils``.
60+
``setuptools`` is only used when building via ``pip`` or with ``python
61+
setupegg.py``. Using ``virtualenv`` should work as expected.
62+
63+
*Note: for build instructions to do development work on NumPy itself, see
64+
:ref:`development-environment`*.
65+
66+
.. _parallel-builds:
67+
68+
Parallel builds
69+
~~~~~~~~~~~~~~~
70+
71+
From NumPy 1.10.0 on it's also possible to do a parallel build with::
72+
73+
python setup.py build -j 4 install --prefix $HOME/.local
74+
75+
This will compile numpy on 4 CPUs and install it into the specified prefix.
76+
to perform a parallel in-place build, run::
77+
78+
python setup.py build_ext --inplace -j 4
79+
80+
The number of build jobs can also be specified via the environment variable
81+
``NPY_NUM_BUILD_JOBS``.
82+
83+
84+
FORTRAN ABI mismatch
85+
--------------------
86+
87+
The two most popular open source fortran compilers are g77 and gfortran.
88+
Unfortunately, they are not ABI compatible, which means that concretely you
89+
should avoid mixing libraries built with one with another. In particular, if
90+
your blas/lapack/atlas is built with g77, you *must* use g77 when building
91+
numpy and scipy; on the contrary, if your atlas is built with gfortran, you
92+
*must* build numpy/scipy with gfortran. This applies for most other cases
93+
where different FORTRAN compilers might have been used.
94+
95+
Choosing the fortran compiler
96+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97+
98+
To build with g77::
99+
100+
python setup.py build --fcompiler=gnu
101+
102+
To build with gfortran::
103+
104+
python setup.py build --fcompiler=gnu95
105+
106+
For more information see::
107+
108+
python setup.py build --help-fcompiler
109+
110+
How to check the ABI of blas/lapack/atlas
111+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
One relatively simple and reliable way to check for the compiler used to build
114+
a library is to use ldd on the library. If libg2c.so is a dependency, this
115+
means that g77 has been used. If libgfortran.so is a a dependency, gfortran
116+
has been used. If both are dependencies, this means both have been used, which
117+
is almost always a very bad idea.
118+
119+
Disabling ATLAS and other accelerated libraries
120+
-----------------------------------------------
121+
122+
Usage of ATLAS and other accelerated libraries in Numpy can be disabled
123+
via::
124+
125+
BLAS=None LAPACK=None ATLAS=None python setup.py build
126+
127+
128+
Supplying additional compiler flags
129+
-----------------------------------
130+
131+
Additional compiler flags can be supplied by setting the ``OPT``,
132+
``FOPT`` (for Fortran), and ``CC`` environment variables.
133+
134+
135+
Building with ATLAS support
136+
---------------------------
137+
138+
Ubuntu
139+
~~~~~~
140+
141+
You can install the necessary package for optimized ATLAS with this command::
142+
143+
sudo apt-get install libatlas-base-dev

‎doc/source/user/howtofind.rst‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎doc/source/user/index.rst‎

Lines changed: 5 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,25 +9,13 @@ explains how to install and make use of the most important features of
99
NumPy. For detailed reference documentation of the functions and
1010
classes contained in the package, see the :ref:`reference`.
1111

12-
.. warning::
13-
14-
This "User Guide" is still a work in progress; some of the material
15-
is not organized, and several aspects of NumPy are not yet covered
16-
sufficient detail. We are an open source community continually
17-
working to improve the documentation and eagerly encourage interested
18-
parties to contribute. For information on how to do so, please visit
19-
the NumPy `doc wiki <http://docs.scipy.org/numpy/Front%20Page>`_.
20-
21-
More documentation for NumPy can be found on the `numpy.org
22-
<http://www.numpy.org>`__ website.
23-
24-
Thanks!
25-
2612
.. toctree::
27-
:maxdepth: 2
13+
:maxdepth: 1
2814

29-
introduction
15+
setting-up
16+
quickstart
3017
basics
31-
performance
3218
misc
19+
numpy-for-matlab-users
20+
building
3321
c-info

‎doc/source/user/install.rst‎

Lines changed: 7 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -1,194 +1,11 @@
1-
*****************************
2-
Building and installing NumPy
3-
*****************************
4-
5-
Binary installers
6-
=================
1+
****************
2+
Installing NumPy
3+
****************
74

85
In most use cases the best way to install NumPy on your system is by using an
9-
installable binary package for your operating system.
10-
11-
Windows
12-
-------
13-
14-
Good solutions for Windows are, `Enthought Canopy
15-
<https://www.enthought.com/products/canopy/>`_, `Anaconda
16-
<http://continuum.io/downloads.html>`_ (which both provide binary installers
17-
for Windows, OS X and Linux) and `Python (x, y) <http://www.pythonxy.com>`_.
18-
Both of these packages include Python, NumPy and many additional packages.
19-
20-
A lightweight alternative is to download the Python
21-
installer from `www.python.org <http://www.python.org>`_ and the NumPy
22-
installer for your Python version from the Sourceforge `download site
23-
<http://sourceforge.net/projects/numpy/files/NumPy`_.
24-
25-
The NumPy installer includes binaries for different CPU's (without SSE
26-
instructions, with SSE2 or with SSE3) and installs the correct one
27-
automatically. If needed, this can be bypassed from the command line with ::
28-
29-
numpy-<1.y.z>-superpack-win32.exe /arch nosse
30-
31-
or ``sse2`` or ``sse3`` instead of ``nosse``.
32-
33-
Linux
34-
-----
35-
36-
All major distributions provide packages for NumPy. These are usually
37-
reasonably up-to-date, but sometimes lag behind the most recent NumPy release.
38-
39-
Mac OS X
40-
--------
41-
42-
Universal binary installers for NumPy are available from the `download site
43-
<http://sourceforge.net/projects/numpy/files/NumPy`_, and wheel packages
44-
from PyPi. With a recent version of `pip`<https://pip.pypa.io/en/latest/>`_
45-
this will give you a binary install (from the wheel packages) compatible with
46-
at python.org Python, Homebrew and MacPorts::
47-
48-
pip install numpy
49-
50-
51-
.. _building-from-source:
52-
53-
Building from source
54-
====================
55-
56-
A general overview of building NumPy from source is given here, with detailed
57-
instructions for specific platforms given seperately.
58-
59-
Prerequisites
60-
-------------
61-
62-
Building NumPy requires the following software installed:
63-
64-
1) Python 2.6.x, 2.7.x, 3.2.x or newer
65-
66-
On Debian and derivatives (Ubuntu): python, python-dev (or python3-dev)
67-
68-
On Windows: the official python installer at
69-
`www.python.org <http://www.python.org>`_ is enough
70-
71-
Make sure that the Python package distutils is installed before
72-
continuing. For example, in Debian GNU/Linux, installing python-dev
73-
also installs distutils.
74-
75-
Python must also be compiled with the zlib module enabled. This is
76-
practically always the case with pre-packaged Pythons.
77-
78-
2) Compilers
79-
80-
To build any extension modules for Python, you'll need a C compiler.
81-
Various NumPy modules use FORTRAN 77 libraries, so you'll also need a
82-
FORTRAN 77 compiler installed.
83-
84-
Note that NumPy is developed mainly using GNU compilers. Compilers from
85-
other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland,
86-
Lahey, HP, IBM, Microsoft are only supported in the form of community
87-
feedback, and may not work out of the box. GCC 4.x (and later) compilers
88-
are recommended.
89-
90-
3) Linear Algebra libraries
91-
92-
NumPy does not require any external linear algebra libraries to be
93-
installed. However, if these are available, NumPy's setup script can detect
94-
them and use them for building. A number of different LAPACK library setups
95-
can be used, including optimized LAPACK libraries such as ATLAS, MKL or the
96-
Accelerate/vecLib framework on OS X.
97-
98-
Basic Installation
99-
------------------
100-
101-
To install NumPy run::
102-
103-
python setup.py install
104-
105-
To perform an in-place build that can be run from the source folder run::
106-
107-
python setup.py build_ext --inplace
108-
109-
The NumPy build system uses ``distutils`` and ``numpy.distutils``.
110-
``setuptools`` is only used when building via ``pip`` or with ``python
111-
setupegg.py``. Using ``virtualenv`` should work as expected.
112-
113-
*Note: for build instructions to do development work on NumPy itself, see
114-
:ref:`development-environment`*.
115-
116-
.. _parallel-builds:
117-
118-
Parallel builds
119-
~~~~~~~~~~~~~~~
120-
121-
From NumPy 1.10.0 on it's also possible to do a parallel build with::
122-
123-
python setup.py build -j 4 install --prefix $HOME/.local
124-
125-
This will compile numpy on 4 CPUs and install it into the specified prefix.
126-
to perform a parallel in-place build, run::
127-
128-
python setup.py build_ext --inplace -j 4
129-
130-
The number of build jobs can also be specified via the environment variable
131-
``NPY_NUM_BUILD_JOBS``.
132-
133-
134-
FORTRAN ABI mismatch
135-
--------------------
136-
137-
The two most popular open source fortran compilers are g77 and gfortran.
138-
Unfortunately, they are not ABI compatible, which means that concretely you
139-
should avoid mixing libraries built with one with another. In particular, if
140-
your blas/lapack/atlas is built with g77, you *must* use g77 when building
141-
numpy and scipy; on the contrary, if your atlas is built with gfortran, you
142-
*must* build numpy/scipy with gfortran. This applies for most other cases
143-
where different FORTRAN compilers might have been used.
144-
145-
Choosing the fortran compiler
146-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
147-
148-
To build with g77::
149-
150-
python setup.py build --fcompiler=gnu
151-
152-
To build with gfortran::
153-
154-
python setup.py build --fcompiler=gnu95
155-
156-
For more information see::
157-
158-
python setup.py build --help-fcompiler
159-
160-
How to check the ABI of blas/lapack/atlas
161-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162-
163-
One relatively simple and reliable way to check for the compiler used to build
164-
a library is to use ldd on the library. If libg2c.so is a dependency, this
165-
means that g77 has been used. If libgfortran.so is a a dependency, gfortran
166-
has been used. If both are dependencies, this means both have been used, which
167-
is almost always a very bad idea.
168-
169-
Disabling ATLAS and other accelerated libraries
170-
-----------------------------------------------
171-
172-
Usage of ATLAS and other accelerated libraries in Numpy can be disabled
173-
via::
174-
175-
BLAS=None LAPACK=None ATLAS=None python setup.py build
176-
177-
178-
Supplying additional compiler flags
179-
-----------------------------------
180-
181-
Additional compiler flags can be supplied by setting the ``OPT``,
182-
``FOPT`` (for Fortran), and ``CC`` environment variables.
183-
184-
185-
Building with ATLAS support
186-
---------------------------
187-
188-
Ubuntu
189-
~~~~~~
190-
191-
You can install the necessary package for optimized ATLAS with this command::
6+
pre-built package for your operating system.
1927

193-
sudo apt-get install libatlas-base-dev
8+
Please see http://scipy.org/install.html for links to available options.
1949

10+
For instructions on building for source package, see
11+
:doc:`building`. This information is useful mainly for advanced users.

0 commit comments

Comments
 (0)