Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 457 lines (302 sloc) 13.619 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
Building and installing SciPy
+++++++++++++++++++++++++++++

See http://www.scipy.org/scipy/scipy/wiki/GetCode
for updates of this document.

.. Contents::

PREREQUISITES
=============

SciPy requires the following software installed:

1) Python__ 2.4.x or newer

   Debian packages: python python-dev

   Make sure that the Python package distutils is installed before
   continuing. For example, in Debian GNU/Linux, distutils is included
   in the python-dev package.

   Python must also be compiled with the zlib module enabled.

__ http://www.python.org

2) NumPy__ 1.2.0 or newer

   Debian package: python-numpy

__ http://www.numpy.org/

3) Complete LAPACK__ library (see NOTES 1, 2, 3)

   Debian/Ubuntu packages (g77): atlas3-base atlas3-base-dev

   Various SciPy packages do linear algebra computations using the LAPACK
   routines. SciPy's setup.py scripts can use number of different LAPACK
   library setups, including optimized LAPACK libraries such as ATLAS__ or
   the Accelerate/vecLib framework on OS X. The notes below give
   more information on how to prepare the build environment so that
   SciPy's setup.py scripts can use whatever LAPACK library setup one has.

__ http://www.netlib.org/lapack/
__ http://math-atlas.sourceforge.net/



OPTIONAL PACKAGES
=================

The following software is optional, but SciPy can use these if present
for extra functionality:

1) C, C++, Fortran 77 compilers (see COMPILER NOTES)

   To build SciPy or any other extension modules for Python, you'll need
   a C compiler. Scipy also requires a C++ compiler.
   
   Various SciPy modules use Fortran 77 libraries, so you'll need also
   at least a Fortran 77 compiler installed.
   
   gcc__ 3.x compilers are recommended. gcc 2.95 and 4.0.x also work on
   some platforms, but may be more problematic (see COMPILER NOTES).

   Debian packages: gcc g++ g77

__ http://gcc.gnu.org/


2) FFTW__ x (see Lib/fftpack/NOTES.txt)

   FFTW 2.1.x and 3.x work.

   Debian packages: fftw2 fftw-dev fftw3 fftw3-dev

__ http://www.fftw.org/



NOTES
-----

1) To use ATLAS, version 3.2.1 or newer and a *complete* LAPACK library
   are required. See

     http://math-atlas.sourceforge.net/errata.html#completelp

   for instructions. Please be aware than building your own atlas is
   error-prone, and should be avoided as much as possible if you don't want to
   spend time on build issues. Use the blas/lapack packaged by your
   distribution on Linux; on Mac Os X, you should use the vecLib/Accelerate
   framework, which are available when installing the apple development tools.

   Below follows basic steps for building ATLAS+LAPACK from scratch.
   In case of trouble, consult the documentation of the corresponding
   software.

   * Get and unpack http://www.netlib.org/lapack/lapack.tgz
     to ``/path/to/src/``.

   * Copy proper ``/path/to/src/LAPACK/INSTALL/make.inc.?????``
     to ``/path/to/src/LAPACK/make.inc``.

   * Build LAPACK::

       cd /path/to/src/LAPACK
       make lapacklib # On 400MHz PII it takes about 15min.

     that will create lapack_LINUX.a when using
     INSTALL/make.inc.LINUX, for example.
     If using Intel Fortran Compiler, see additional notes below.

   * Get the latest stable ATLAS sources from
     http://math-atlas.sourceforge.net/
     and unpack to ``/path/to/src/``.

   * Build ATLAS::

       cd /path/to/src/ATLAS
       make # Number of questions will be asked
       make install arch=Linux_PII # This takes about 45min.

     where arch may vary (see the output of the previous command).

   * Make optimized LAPACK library::

       cd /path/to/src/ATLAS/lib/Linux_PII/
       mkdir tmp; cd tmp
       ar x ../liblapack.a
       cp /path/to/src/LAPACK/lapack_LINUX.a ../liblapack.a
       ar r ../liblapack.a *.o
       cd ..; rm -rf tmp

   * Move all ``lib*.a`` files from ``/path/to/src/ATLAS/lib/Linux_PII/``,
     say, to ``/usr/local/lib/atlas/``.
     Also copying ``/path/to/src/ATLAS/include/{cblas.h,clapack.h}`` to
     ``/usr/local/lib/atlas/`` might be a good idea.

   * Define environment variable ATLAS that contains path to the directory
     where you moved the atlas libraries. For example, in bash run::

       export ATLAS=/usr/local/lib/atlas

2) If you are willing to sacrifice the performance (by factor of 5 to 15
   for large problems) of the linalg module then it is possible to build
   SciPy without ATLAS. For that you'll need either Fortran LAPACK/BLAS
   libraries installed in your system or Fortran LAPACK/BLAS sources to be
   accessible by SciPy setup scripts (use ``LAPACK_SRC``/``BLAS_SRC``
   environment variables to indicate the location of the corresponding
   source directories). More details of how to do this are on the SciPy
   Wiki, at:

     http://www.scipy.org/Installing_SciPy/BuildingGeneral

3) Users of Debian (and derivatives like Ubuntu) can use the following
   deb packages::

     atlas2-headers

   and

     atlas2-base atlas2-base-dev
     or
     atlas2-sse atlas2-sse-dev
     or
     atlas2-sse2 atlas2-sse2-dev
     or
     atlas2-3dnow atlas2-3dnow-dev

   It is not necessary to install blas or lapack libraries in addition.

 4) Compiler flags customization (FFLAGS, CFLAGS, etc...). If you customize
 CFLAGS and other related flags from the command line or the shell environment,
 beware that is does not have the standard behavior of appending options.
 Instead, it overrides the options. As such, you have to give all options in the
 flag for the build to be successful.

GETTING SCIPY
=============

For the latest information, see the web site:

  http://www.scipy.org


Development version from Subversion (SVN)
-----------------------------------------
Use the command::

  svn co http://svn.scipy.org/svn/scipy/trunk scipy

Before building and installing from SVN, remove the old installation
(e.g. in /usr/lib/python2.4/site-packages/scipy or
$HOME/lib/python2.4/site-packages/scipy). Then type:

  cd scipy
  rm -rf build
  python setup.py install
 
 

INSTALLATION
============

First make sure that all SciPy prerequisites are installed and working
properly. Then be sure to remove any old SciPy installations (e.g.
/usr/lib/python2.4/site-packages/scipy or $HOME/lib/python2.4/
site-packages/scipy).

From tarballs
-------------
Unpack ``SciPy-<version>.tar.gz``, change to the ``SciPy-<version>/``
directory, and run
::

  python setup.py install

This may take several minutes to an hour depending on the speed of your
computer. This may require root privileges. To install to a
user-specific location instead, run

  python setup.py install --prefix=$MYDIR

where $MYDIR is, for example, $HOME or $HOME/usr.



TESTING
=======

To test SciPy after installation (highly recommended), execute in Python

   >>> import scipy
   >>> scipy.test()

To run the full test suite use

   >>> scipy.test('full')

Please note that you must have version 0.10 or later of the 'nose' test
framework installed in order to run the tests. More information about nose is
available here:

http://somethingaboutorange.com/mrl/projects/nose/

COMPILER NOTES
==============

Note that SciPy is developed mainly using GNU compilers. Compilers from
other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland,
Lahey, HP, IBM are supported in the form of community feedback.

gcc__ compiler is recommended. gcc 3.x and 4.x are known to work.
If building on OS X, you should use the provided gcc by xcode tools, and the
gfortran compiler available here:

http://r.research.att.com/tools/

You can specify which Fortran compiler to use by using the following
install command::

  python setup.py config_fc --fcompiler=<Vendor> install

To see a valid list of <Vendor> names, run::

  python setup.py config_fc --help-fcompiler

IMPORTANT: It is highly recommended that all libraries that scipy uses (e.g.
blas and atlas libraries) are built with the same Fortran compiler. In most
cases, if you mix compilers, you will not be able to import scipy at best, have
crashes and random results at worse.

__ http://gcc.gnu.org/

Using non-GNU Fortran compiler with gcc/g77 compiled Atlas/Lapack libraries
---------------------------------------------------------------------------

When Atlas/Lapack libraries are compiled with GNU compilers but
one wishes to build scipy with some non-GNU Fortran compiler then
linking extension modules may require -lg2c. You can specify it
in installation command line as follows::

  python setup.py build build_ext -lg2c install

If using non-GNU C compiler or linker, the location of g2c library can
be specified in a similar manner using -L/path/to/libg2c.a after
build_ext command.

Intel Fortran Compiler
----------------------

Note that code compiled by the Intel Fortran Compiler (IFC) is not
binary compatible with code compiled by g77. Therefore, when using IFC,
all Fortran codes used in SciPy must be compiled with IFC. This also
includes the LAPACK, BLAS, and ATLAS libraries. Using GCC for compiling
C code is OK. IFC version 5.0 is not supported (because it has bugs that
cause SciPy's tests to segfault).

Minimum IFC flags for building LAPACK and ATLAS are
::

  -FI -w90 -w95 -cm -O3 -unroll

Also consult 'ifc -help' for additional optimization flags suitable
for your computers CPU.

When finishing LAPACK build, you must recompile ?lamch.f, xerbla.f
with optimization disabled (otherwise infinite loops occur when using
these routines)::

  make lapacklib # in /path/to/src/LAPACK/
  cd SRC
  ifc -FI -w90 -w95 -cm -O0 -c ?lamch.f xerbla.f
  cd ..
  make lapacklib


KNOWN INSTALLATION PROBLEMS
===========================

BLAS sources shipped with LAPACK are incomplete
-----------------------------------------------
Some distributions (e.g. Redhat Linux 7.1) provide BLAS libraries that
are built from such incomplete sources and therefore cause import
errors like
::

  ImportError: .../fblas.so: undefined symbol: srotmg_

Fix:
  Use ATLAS or the official release of BLAS libraries.

LAPACK library provided by ATLAS is incomplete
----------------------------------------------
You will notice it when getting import errors like
::

  ImportError: .../flapack.so : undefined symbol: sgesdd_

To be sure that SciPy is built against a complete LAPACK, check the
size of the file liblapack.a -- it should be about 6MB. The location
of liblapack.a is shown by executing
::

    python /lib/python2.4/site-packages/numpy/distutils/system_info.py

(or the appropriate installation directory).

To fix: follow the instructions in

    http://math-atlas.sourceforge.net/errata.html#completelp

  to create a complete liblapack.a. Then copy liblapack.a to the same
  location where libatlas.a is installed and retry with scipy build.

Using ATLAS 3.2.1
-----------------
If import clapack fails with the following error
::
  
  ImportError: .../clapack.so : undefined symbol: clapack_sgetri

then you most probably have ATLAS 3.2.1 but linalg module was built
for newer versions of ATLAS.
Fix:

  1) Remove Lib/linalg/clapack.pyf

  2) Rebuild/reinstall scipy.

Using non-GNU Fortran Compiler
------------------------------
If import scipy shows a message
::

  ImportError: undefined symbol: s_wsfe

and you are using non-GNU Fortran compiler, then it means that any of
the (may be system provided) Fortran libraries such as LAPACK or BLAS
were compiled with g77. See also compilers notes above.

Recommended fix: Recompile all Fortran libraries with the same Fortran
compiler and rebuild/reinstall scipy.

Another fix: See `Using non-GNU Fortran compiler with gcc/g77 compiled
Atlas/Lapack libraries` section above.


TROUBLESHOOTING
===============

If you experience problems when building/installing/testing SciPy, you
can ask help from scipy-user@scipy.org or scipy-dev@scipy.org mailing
lists. Please include the following information in your message:

NOTE: You can generate some of the following information (items 1-5,7)
in one command::

  python -c 'from numpy.f2py.diagnose import run; run()'

1) Platform information::

     python -c 'import os,sys;print os.name,sys.platform'
     uname -a
     OS, its distribution name and version information
     etc.

2) Information about C,C++,Fortran compilers/linkers as reported by
   the compilers when requesting their version information, e.g.,
   the output of
   ::

     gcc -v
     g77 --version

3) Python version::

     python -c 'import sys;print sys.version'

4) NumPy version::

     python -c 'import numpy;print numpy.__version__'

5) ATLAS version, the locations of atlas and lapack libraries, building
   information if any. If you have ATLAS version 3.3.6 or newer, then
   give the output of the last command in
   ::

     cd scipy/Lib/linalg
     python setup_atlas_version.py build_ext --inplace --force
     python -c 'import atlas_version'

7) The output of the following commands
   ::

     python INSTALLDIR/numpy/distutils/system_info.py

where INSTALLDIR is, for example, /usr/lib/python2.4/site-packages/.

8) Feel free to add any other relevant information.
   For example, the full output (both stdout and stderr) of the SciPy
   installation command can be very helpful. Since this output can be
   rather large, ask before sending it into the mailing list (or
   better yet, to one of the developers, if asked).

9) In case of failing to import extension modules, the output of
   ::

     ldd /path/to/ext_module.so

   can be useful.

You may find the following notes useful:

  http://www.tuxedo.org/~esr/faqs/smart-questions.html

  http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
Something went wrong with that request. Please try again.