Ticket #10508: trac_10508_update_atlas_docs.patch

File trac_10508_update_atlas_docs.patch, 5.0 KB (added by vbraun, 9 years ago)

Initial patch

  • doc/en/installation/source.rst

    # HG changeset patch
    # User Volker Braun <vbraun@stp.dias.ie>
    # Date 1343958891 14400
    # Node ID 8b9c05388d29c3f09b032f0686957be852b2318e
    # Parent  7c3b2d89756d939d39f7350fa87b9556f7a93ff7
    Update the installation guide for ATLAS 3.10.0
    diff --git a/doc/en/installation/source.rst b/doc/en/installation/source.rst
    a b  
    822822  systems with CPU throttling or if you want to distribute the
    823823  binaries. Available architectures are
    825     ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
    826     ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
    827     ``CoreDuo``, ``Core2Solo``, ``Core2``, ``Corei7``, ``P4``,
    828     ``P4E``, ``Efficeon``, ``K7``, ``HAMMER``, ``AMD64K10h``,
    829     ``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
    830     ``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
     825     ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``,
     826     ``POWER6``, ``POWER7``, ``IBMz9``, ``IBMz10``, ``IBMz196``,
     827     ``x86x87``, ``x86SSE1``, ``x86SSE2``, ``x86SSE3``, ``P5``,
     828     ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
     829     ``CoreDuo``, ``Core2Solo``, ``Core2``, ``Corei1``, ``Corei2``,
     830     ``Atom``, ``P4``, ``P4E``, ``Efficeon``, ``K7``, ``HAMMER``,
     831     ``AMD64K10h``, ``AMDDOZER``, ``UNKNOWNx86``, ``IA64Itan``,
     832     ``IA64Itan2``, ``USI``, ``USII``, ``USIII``, ``USIV``, ``UST2``,
     833     ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``, ``ARMv7``.
    832835  and instruction set extensions are
    834     ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
     837    ``VSX``, ``AltiVec``, ``AVXMAC``, ``AVXFMA4``, ``AVX``, ``SSE3``,
     838    ``SSE2``, ``SSE1``, ``3DNow``, ``NEON``.
    836840  In addition, you can also set
    844848  For example,
    846     ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
     850    ``SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1``
    848852  would be appropriate for a Core i7 CPU.
    851855  your system and you want Sage to use it instead of building and
    852856  installing its own version of ATLAS, set this variable to be the
    853857  directory containing your ATLAS installation. It should contain the
    854   files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`, and
    855   :file:`libf77blas` with extensions ``.a``, ``.so``, or
    856   ``.dylib``. For backward compatibility, the libraries may also be in
    857   the subdirectory ``SAGE_ATLAS_LIB/lib/``.
     858  files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`,
     859  :file:`libptcblas`, :file:`libf77blas`, and :file:`libptf77blas`
     860  with extensions ``.a``, ``.so``, or ``.dylib``. For backward
     861  compatibility, the libraries may also be in the subdirectory
     862  ``SAGE_ATLAS_LIB/lib/``.
    859864- :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything non-empty except
    860865  "no", and Sage will attempt to build the graphical backend when it
    10441049   processes. You can also omit ``long`` to skip tests which take a long
    10451050   time.
    1047 Some common problems
    1048 --------------------
    1050 ATLAS
    1051 ~~~~~
     1055Usually Sage will build ATLAS with architectural defaults that are not
     1056tuned to your particular CPU. In particular, if your CPU has
     1057powersaving enabled then no accurate timings can be made to tune the
     1058ATLAS build for your hardware. If BLAS performance is critical for
     1059you, you must recompile ATLAS after installing Sage either with
     1060architecture settings that match your hardware, or run through ATLAS'
     1061automatic tuning process where timings of different implementations
     1062are compared and the best choice used to build a custom ATLAS
     1063library. To do so, you have to
    1053 Sometimes the ATLAS spkg can fail to build.  Some things to check for:
     1065- Leave the computer idle while you are reinstalling ATLAS. Most of
     1066  ATLAS will intentionally only compile/run on a single core. Accurate
     1067  timings of cache edges require that the CPU is otherwise idle.
    1055 - Make sure that CPU throttling mode (= power-saving mode) is turned off
    1056   when building ATLAS.
     1069- Make sure that CPU powersaving mode (that is, anything but the
     1070  ``performance`` cpu scaling governor in Linux) is turned off when
     1071  building ATLAS. This requires administrator privileges.
    1058 - Also, the ATLAS build can fail if the system load is too high, and in
    1059   particular this has been known to happen when building with
    1060   ``MAKE='make -jNUM'`` with NUM large.  If this happens, just try
    1061   running "make" again.  If "make" fails after five or six attempts,
    1062   report your problem to the sage-devel mailing list.
     1073- If your architecture is listed in :envvar:`SAGE_ATLAS_ARCH`, you
     1074  should set it as it can help ATLAS in narrowing down the timing
     1075  search.
     1077To help you disable CPU power saving, Sage includes a ``atlas-config``
     1078script that will turn off CPU powersave and rebuild ATLAS. The script
     1079will call ``sudo`` to gain the necessary rights, which may prompt you
     1080for the root password. For example::
     1082    atlas-config
     1084will run through the full automatted tuning, and::
     1086    SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1 atlas-config
     1088would be appropriate if you have a Core i3/5/7 processor with AVX
    10641092Special Notes