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
    824824
    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``.
    831834
    832835  and instruction set extensions are
    833836   
    834     ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
     837    ``VSX``, ``AltiVec``, ``AVXMAC``, ``AVXFMA4``, ``AVX``, ``SSE3``,
     838    ``SSE2``, ``SSE1``, ``3DNow``, ``NEON``.
    835839
    836840  In addition, you can also set
    837841
     
    843847
    844848  For example,
    845849
    846     ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
     850    ``SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1``
    847851
    848852  would be appropriate for a Core i7 CPU.
    849853
     
    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/``.
    858863
    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.
    10461051
    1047 Some common problems
    1048 --------------------
     1052ATLAS
     1053-----
    10491054
    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
    10521064
    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.
    10541068
    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.
    10571072
    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.
     1076
     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::
     1081
     1082    atlas-config
     1083
     1084will run through the full automatted tuning, and::
     1085
     1086    SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1 atlas-config
     1087
     1088would be appropriate if you have a Core i3/5/7 processor with AVX
     1089support.
     1090
    10631091
    10641092Special Notes
    10651093-------------