Ignore:
Timestamp:
Jan 19, 2022 9:52:51 PM (7 months ago)
Author:
toby
Message:

more doc formatting cleanup

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/source/packages.rst

    r5020 r5149  
    1 Required packages
    2 ====================
     1Required Packages & Supported Platforms
     2==========================================
    33
    44GSAS-II requires a standard Python interpreter to be installed, as
    55well as several separately-developed packages. GSAS-II is being
    6 developed using Python 2.7, 3.6 and 3.7. At this point we think that
    7 most sections of the code have been exercised in Python 2 and 3,
    8 but  bugs are still expected (please report them). Our
    9 goal is to keep the code compliant with both Python 2.7 and 3.x for
    10 the immediate future.
     6developed using Python 3.7 and 3.9. At this point we think that
     7most sections of the code have been exercised in Python 3,
     8but  bugs are still expected (please report them). We are no longer
     9testing with Python 2.7 and strongly urge everyone to upgrade,
     10but if problems running GSAS-II in Python 2.7 are reported, we will
     11consider making that the code compliant with both.
    1112
    1213Note that the packages listed below are not distributed as part of the Python standard
    13 library. We use the free Anaconda Python (https://www.anaconda.com/)
    14 distribution (and provide installers based on that), but there are
    15 many other fine distributions, such as Enthought Inc.'s Canopy and
    16 Python(x,y), see here: https://www.python.org/download/alternatives/.
    17 We do some testing using the older Enthought Python Distribution
    18 (EPD); this is known to have some problems with reading CIFs and
    19 encourage updating from that.
     14library. We have been depending on the free Anaconda
     15Python (https://www.anaconda.com/)
     16distribution (and provide installers based on that), but Anaconda does
     17not seem to be supplying up to date versions of the wxpython package
     18that the GUI requires and does not have versions for all supported
     19platforms. Use of the miniforge
     20(https://github.com/conda-forge/miniforge) distribution is recommended
     21where needed.
     22
     23There are many other Python distributions, such as Enthought Inc.'s Canopy and
     24Python(x,y), see here:
     25https://www.python.org/download/alternatives/. We are no longer using
     26any of them and are unsure of how they will function. Some very old
     27GSAS-II installations were based on the quite outdated Enthought Python Distribution
     28(EPD); this is known to have some problems with reading CIFs and we
     29strongly encourage updating from that.
    2030
    2131More details on allowed and prefered package versions can be found in
     
    6070* SciPy (http://docs.scipy.org/doc/scipy/reference/).
    6171
    62 Note that some sections of the code may require matplotlib (http://matplotlib.org/contents.html), Pillow
     72Note that a few sections of the code require matplotlib (http://matplotlib.org/contents.html), Pillow
    6373(https://pillow.readthedocs.org) (or PIL,
    64 http://www.pythonware.com/products/pil/), or h5py + hdf5 to function
    65 but scripts will load and run without these.
     74http://www.pythonware.com/products/pil/), or h5py + hdf5, but none of
     75these are required to run scripts and the vast
     76majority of scripts will not need these packages.
     77
     78Optional Packages
     79-----------------------
     80
     81* Sphinx (https://www.sphinx-doc.org) is used to generate the
     82  documentation you are currently reading. Generation of documentation
     83  is not generally something needed by users or even most code developers.
     84
     85 * SCons (https://scons.org/) is used to compile the small amount of
     86   Fortran code that is included with GSAS-II. Use of this is
     87   discussed in the last section of this chapter.
    6688
    6789
     
    113135    Computes enhanced Fourier maps with Maximum Entropy estimated
    114136    extension of reflection sphere
     137
     138Supported Platforms
     139--------------------------------
     140
     141It should be possible to run GSAS-II on any computer where Python 3.7+ and
     142the appropriate required packages are available. For many platforms,
     143binary versions of the Fortran code used in GSAS-II are supplied, but the
     144binaries must match the platform and the major versions of both Python and
     145numpy; even for supported platforms; not all combinations are
     146provided. Should one wish to run GSAS-II where binary files are not
     147supplied, compilation will be needed. This will require the GNU Fortran (gfortran)
     148compiler (https://gcc.gnu.org/fortran/) as well as the Python SCons
     149package. Instructions are supplied for a number of platforms (such as
     150https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/InstallLinux#CompilingFortranCode). Note
     151that there are prepackaged versions of GSAS-II for most common
     152platforms. These include Python, all required and most optional
     153packages and a version of all files needed to run GSAS-II -- albeit
     154not usually the current version. The
     155installation process will try to update to the current version, if the
     156computer where installation is occuring has internet access.
     157
     158At present the following platforms are directly supported:
     159
     160* **Windows-10**: Installation kits are available for both 32-bit and
     161  64-bit windows. Running GSAS-II on older versions of Windows is
     162  likely possible, but to do so one must locate compatible versions of Python
     163  and packages. This is getting increasingly tough. We have not tried
     164  Windows-11, but expect the Windows-10 versions to run there.
     165
     166* **MacOS**: We provide an installer for Macs with Intel
     167  processors. This can also be used on ARM-equipped Macs ("M1" or "Apple
     168  Silicon" processors) but native M1 code runs way
     169  faster. Installation on the native ARM code is more complex; our
     170  instructions (https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/MacM1Notes)
     171  require that the homebrew package installer be installed and then
     172  brew (homebrew) be used to install Python and a number of packages.
     173  Macs older than
     174  Catalina (10.15) may require older distributions of Python.
     175
     176* **Linux** (Intel-compatible): GSAS-II does not get a lot of testing in Linux by us, but is
     177  fairly widely used on this platform nonetheless.  One can use the
     178  installer that we provide, but compatibility with older and very new
     179  versions of OSes can be tough and may require compatibility
     180  libraries. At times it may be better to use the Linux distribution's
     181  versions of Python and packages. This is typically done with a
     182  software tool such as apt or yum. An example on how to do this is
     183  shown for the Raspberry Pi.
     184
     185* **Raspberry Pi** (ARM) Linux: GSAS-II has been installed on both 32-bit
     186  and the experimental 64-bit version of the Raspberry Pi OS (formerly
     187  called Raspbian) and compiled binaries are provided. It should also
     188  run with Ubuntu Linux for this platform, but this has not been
     189  tried. It is necessary to use the Raspbian Linux distribution's
     190  versions of Python and its packages. Instructions are provided
     191  (https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/InstallPiLinux).
     192  The performance of GSAS-II on a Raspberry Pi is not blindingly fast,
     193  but one can indeed run GSAS-II on a computer that costs only $15!
     194 
Note: See TracChangeset for help on using the changeset viewer.