Ticket #10508: trac_10508_update_atlas_docs.patch

doc/en/installation/source.rst

@@ -822 +822 @@
   systems with CPU throttling or if you want to distribute the
   binaries. Available architectures are 
 
-    ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``, ``P5``,
-    ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
-    ``CoreDuo``, ``Core2Solo``, ``Core2``, ``Corei7``, ``P4``,
-    ``P4E``, ``Efficeon``, ``K7``, ``HAMMER``, ``AMD64K10h``,
-    ``IA64Itan``, ``IA64Itan2``, ``USI``, ``USII``, ``USIII``,
-    ``USIV``, ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``
+     ``POWER3``, ``POWER4``, ``POWER5``, ``PPCG4``, ``PPCG5``,
+     ``POWER6``, ``POWER7``, ``IBMz9``, ``IBMz10``, ``IBMz196``,
+     ``x86x87``, ``x86SSE1``, ``x86SSE2``, ``x86SSE3``, ``P5``,
+     ``P5MMX``, ``PPRO``, ``PII``, ``PIII``, ``PM``, ``CoreSolo``,
+     ``CoreDuo``, ``Core2Solo``, ``Core2``, ``Corei1``, ``Corei2``,
+     ``Atom``, ``P4``, ``P4E``, ``Efficeon``, ``K7``, ``HAMMER``,
+     ``AMD64K10h``, ``AMDDOZER``, ``UNKNOWNx86``, ``IA64Itan``,
+     ``IA64Itan2``, ``USI``, ``USII``, ``USIII``, ``USIV``, ``UST2``,
+     ``UnknownUS``, ``MIPSR1xK``, ``MIPSICE9``, ``ARMv7``.
 
   and instruction set extensions are 
    
-    ``AltiVec``, ``SSE3``, ``SSE2``, ``SSE1``, ``3DNow``.
+    ``VSX``, ``AltiVec``, ``AVXMAC``, ``AVXFMA4``, ``AVX``, ``SSE3``,
+    ``SSE2``, ``SSE1``, ``3DNow``, ``NEON``.
 
   In addition, you can also set
 
@@ -843 +847 @@
 
   For example, 
 
-    ``SAGE_ATLAS_ARCH=Corei7,SSE3,SSE2,SSE1``
+    ``SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1``
 
   would be appropriate for a Core i7 CPU.
 
@@ -851 +855 @@
   your system and you want Sage to use it instead of building and
   installing its own version of ATLAS, set this variable to be the
   directory containing your ATLAS installation. It should contain the
-  files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`, and
-  :file:`libf77blas` with extensions ``.a``, ``.so``, or
-  ``.dylib``. For backward compatibility, the libraries may also be in
-  the subdirectory ``SAGE_ATLAS_LIB/lib/``.
+  files :file:`libatlas`, :file:`liblapack`, :file:`libcblas`,
+  :file:`libptcblas`, :file:`libf77blas`, and :file:`libptf77blas`
+  with extensions ``.a``, ``.so``, or ``.dylib``. For backward
+  compatibility, the libraries may also be in the subdirectory
+  ``SAGE_ATLAS_LIB/lib/``.
 
 - :envvar:`SAGE_MATPLOTLIB_GUI` - set this to anything non-empty except
   "no", and Sage will attempt to build the graphical backend when it
@@ -1044 +1049 @@
    processes. You can also omit ``long`` to skip tests which take a long
    time.
 
-Some common problems
---------------------
+ATLAS
+-----
 
-ATLAS
-~~~~~
+Usually Sage will build ATLAS with architectural defaults that are not
+tuned to your particular CPU. In particular, if your CPU has
+powersaving enabled then no accurate timings can be made to tune the
+ATLAS build for your hardware. If BLAS performance is critical for
+you, you must recompile ATLAS after installing Sage either with
+architecture settings that match your hardware, or run through ATLAS'
+automatic tuning process where timings of different implementations
+are compared and the best choice used to build a custom ATLAS
+library. To do so, you have to
 
-Sometimes the ATLAS spkg can fail to build.  Some things to check for:
+- Leave the computer idle while you are reinstalling ATLAS. Most of
+  ATLAS will intentionally only compile/run on a single core. Accurate
+  timings of cache edges require that the CPU is otherwise idle.
 
-- Make sure that CPU throttling mode (= power-saving mode) is turned off
-  when building ATLAS.
+- Make sure that CPU powersaving mode (that is, anything but the
+  ``performance`` cpu scaling governor in Linux) is turned off when
+  building ATLAS. This requires administrator privileges.
 
-- Also, the ATLAS build can fail if the system load is too high, and in
-  particular this has been known to happen when building with
-  ``MAKE='make -jNUM'`` with NUM large.  If this happens, just try
-  running "make" again.  If "make" fails after five or six attempts,
-  report your problem to the sage-devel mailing list.
+- If your architecture is listed in :envvar:`SAGE_ATLAS_ARCH`, you
+  should set it as it can help ATLAS in narrowing down the timing
+  search.
+
+To help you disable CPU power saving, Sage includes a ``atlas-config``
+script that will turn off CPU powersave and rebuild ATLAS. The script
+will call ``sudo`` to gain the necessary rights, which may prompt you
+for the root password. For example::
+
+    atlas-config 
+
+will run through the full automatted tuning, and::
+
+    SAGE_ATLAS_ARCH=Corei2,AVX,SSE3,SSE2,SSE1 atlas-config
+
+would be appropriate if you have a Core i3/5/7 processor with AVX
+support.
+
 
 Special Notes
 -------------