source: trunk/docs/source/packages.rst @ 5285

Last change on this file since 5285 was 5285, checked in by toby, 19 months ago

multiple PDFfit2 changes; seems to work well on Windows w/3.7, 3.8 & 3.9

File size: 10.6 KB
1Required Packages & Supported Platforms
4GSAS-II requires a standard Python interpreter to be installed, as
5well as several separately-developed packages. GSAS-II is being
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.
13Note that the packages listed below are not distributed as part of the Python standard
14library. We have been depending on the free Anaconda
15Python (
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( distribution is recommended
21where needed.
23There are many other Python distributions, such as Enthought Inc.'s Canopy and
24Python(x,y), see here:
25 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.
31More details on allowed and prefered package versions can be found in
32the documentation for variable :attr:`GSASIIdataGUI.versionDict`.
34GUI Requirements
37When using the GSAS-II graphical user interface (GUI), the following
38Python extension packages are required:
40* wxPython ( Note that GSAS-II has been tested with wxPython 2.8.x, 3.0.x and 4.0.x. We encourage use of 3.0 with Python 2.7 and 4.x with Python 3.x.
41* NumPy (,
42* SciPy (,
43* matplotlib (  and
44* PyOpenGL ( Note: a copy of this is distributed with GSAS-II (at present) and will be installed if the Python setuptools package is present.
46Several packages are used in sections of the code, but are not
47required. If these packages are not present, warning messages may be
48generated if they would be needed, but the vast bulk of GSAS-II will function normally.
50* Pillow ( or PIL ( This is used to save
51  and read certain types of images.
52* h5py is the HDF5 interface and hdf5 is the support package. These
53  packages are (not surprisingly) required
54  to import images from HDF5 files. If these libraries are not present,
55  the HDF5 importer(s) will not appear in the import menu and a
56  warning message appears on GSAS-II startup.
57* imageio is used to make movies.
58* svn: When using Anaconda we also encourage installation of the
59  svn (subversion) conda package. This is not actually part of Python
60  and can be installed directly into your system's configuration. It is used by
61  GSAS-II to download updates to our code. This can be skipped if svn
62  is installed directly (easy Linux, but a bit harder on MacOS and
63  Windows).
64* conda: the conda package allows access to conda features from
65  inside Python. It will be used inceasingly by GSAS-II to
66  self-install software. The conda package is installed by default in
67  miniconda and anaconda but if you create an environment for GSAS-II
68  (`conda create -n <env> package-list...`), it will not be added
69  unless you request it specifically. 
71*Conda command*:
72  Here is a typical conda command used to install a GSAS-II compatible
73  Python interpreter::
75    conda install wxpython numpy scipy matplotlib pyopengl pillow h5py imageio svn -c conda-forge
77  or to use a separate environment (here named ``g2python``), use::
79    conda install -n g2python wxpython numpy scipy matplotlib pyopengl pillow h5py imageio svn conda -c conda-forge
81Remember to activate using: ``<path>\Scripts\activate``  (windows);
82``source <path>/bin/activate`` (Mac/Linux). Note that one should add
83``g2python`` (etc.) at the end if using a conda environment.
85Note that svn seems to be unsupported these days by Anaconda. For
86Linux and MacOS, use subversion in conda-forge rather than svn. No
87good solution yet for Windows.
89Scripting  Requirements
92When using the GSAS-II scripting interface (:mod:`GSASIIscriptable`),
93only the following Python extension packages are required:
95* NumPy (,
96* SciPy (
98Note that a few sections of the code require matplotlib (, Pillow
99( (or PIL,
100, or h5py + hdf5, but none of
101these are required to run scripts and the vast
102majority of scripts will not need these packages.
104Optional Packages
107* Sphinx ( is used to generate the
108  documentation you are currently reading. Generation of documentation
109  is not generally something needed by users or even most code developers.
111 * SCons ( is used to compile the small amount of
112   Fortran code that is included with GSAS-II. Use of this is
113   discussed in the last section of this chapter.
116External and Supplied Programs
119GSAS-II provides interfaces to use a number of programs developed by
120others. Some are included with GSAS-II and others must be installed
121separately. When these programs are accessed, citation
122information is provided.
124GSAS-II includes copies of these programs:
126  **DIFFaX**
127    Simulate layered structures with faulting
129  **CifFile**
130    A software library used to read data and structures from CIF
132  **Shapes**
133    Model small angle scattering with shaped particles
135  **NIST FPA**
136    Use Fundamental Parameters to determine GSAS-II profile function
138No additional steps beyond a standard installation
139are needed to access their functionality.
141**Bilboa Crystallographic Server**: GSAS-II directly access the
142Bilboa Crystallographic Server (provided
143the computer has internet access). This allows automated use of the
144k-SUBGROUPSMAG, k-SUBGROUPS and PseudoLattice web utilities for
145computation of space group subgroups, color (magnetic) subgroups &
146lattice search.
148At the request of the program authors, these programs are not included
149with GSAS-II and must be installed separately:
151  **RMCProfile**
152    Large-box PDF & S(Q) fitting. We have heard from users that V6.7.7
153    of RMCProfile is compatible with the input created by GSAS-II,
154    but not V6.7.9.
156  **fullrmc**
157    A modern software toolkit for large-box PDF & S(Q) fitting. Use
158    version 5.0 or later. The implementation for this is not
159    completed.
161  **Dysnomia**
162    Computes enhanced Fourier maps with Maximum Entropy estimated
163    extension of reflection sphere
165  **PDFfit2**
166  Small-box fitting of PDFs. This code is no longer supported, but is
167  still quite useful. It can be installed from conda into Python
168  versions up to Python 3.7, but is supplied for Windows within
169  GSAS-II for Python 3.7, 3.8 and 3.9 and for MacOS only with Python
170  3.7.
172  For other platforms/Python versions, it is probably best to use a
173  separate Python interpreter.
175Supported Platforms
178It should be possible to run GSAS-II on any computer where Python 3.7+ and
179the appropriate required packages are available. For many platforms,
180binary versions of the Fortran code used in GSAS-II are supplied, but the
181binaries must match the platform and the major versions of both Python and
182numpy; even for supported platforms; not all combinations are
183provided. Should one wish to run GSAS-II where binary files are not
184supplied, compilation will be needed. This will require the GNU Fortran (gfortran)
185compiler ( as well as the Python SCons
186package. Instructions are supplied for a number of platforms (such as
187 Note
188that there are prepackaged versions of GSAS-II for most common
189platforms. These include Python, all required and most optional
190packages and a version of all files needed to run GSAS-II -- albeit
191not usually the current version. The
192installation process will try to update to the current version, if the
193computer where installation is occuring has internet access.
195At present the following platforms are directly supported:
197* **Windows-10**: Installation kits are available for both 32-bit and
198  64-bit windows. Running GSAS-II on older versions of Windows is
199  likely possible, but to do so one must locate compatible versions of Python
200  and packages. This is getting increasingly tough. We have not tried
201  Windows-11, but expect the Windows-10 versions to run there.
203* **MacOS**: We provide an installer for Macs with Intel
204  processors. This can also be used on ARM-equipped Macs ("M1" or "Apple
205  Silicon" processors) but native M1 code runs way
206  faster. Installation on the native ARM code is more complex; our
207  instructions (
208  require that the homebrew package installer be installed and then
209  brew (homebrew) be used to install Python and a number of packages.
210  Macs older than
211  Catalina (10.15) may require older distributions of Python.
213* **Linux** (Intel-compatible): GSAS-II does not get a lot of testing in Linux by us, but is
214  fairly widely used on this platform nonetheless.  One can use the
215  installer that we provide, but compatibility with older and very new
216  versions of OSes can be tough and may require compatibility
217  libraries. At times it may be better to use the Linux distribution's
218  versions of Python and packages. This is typically done with a
219  software tool such as apt or yum. An example on how to do this is
220  shown for the Raspberry Pi.
222* **Raspberry Pi** (ARM) Linux: GSAS-II has been installed on both 32-bit
223  and the experimental 64-bit version of the Raspberry Pi OS (formerly
224  called Raspbian) and compiled binaries are provided. It should also
225  run with Ubuntu Linux for this platform, but this has not been
226  tried. It is necessary to use the Raspbian Linux distribution's
227  versions of Python and its packages. Instructions are provided
228  (
229  The performance of GSAS-II on a Raspberry Pi is not blindingly fast,
230  but one can indeed run GSAS-II on a computer that costs only $15!
Note: See TracBrowser for help on using the repository browser.