\(\renewcommand\AA{\text{Å}}\)

1. GSAS-II Execution Environment

1.1. Supported Platforms

It should be possible to run GSAS-II on any computer where Python 3.7+ and the appropriate required packages are available, as discussed below, but GSAS-II also requires that some code must be compiled. For the following platforms, binary images for this compiled code are currently provided:

  • Windows-10: 64-bit Intel-compatible processors

  • MacOS: Intel processors

  • MacOS: ARM processors, aka Apple Silicon (M1, etc)

  • Linux: 64-bit Intel-compatible processors

  • Linux: ARM processors (64-bit Raspberry Pi OS only)

Details for GSAS-II use on these specific platforms follows below:

  • Windows: self-Installation kits are provided for 64-bit Windows-10 and -11 here. Less testing has been done with Windows-11, but both appear to working interchangeably with respect to GSAS-II.

    In theory it should be possible to run GSAS-II on older versions of Windows, including 32-bit OS versions, but no current installation kit can be provided. Installing GSAS-II will require locating a compatible version (or compiling) Python and the required packages. It may be necessary to recompile the GSAS-II binaries.

  • MacOS: GSAS-II can run natively on Intel (or ARM (“M1”-“M3” aka “Apple Silicon”) processors with relatively current versions of MacOS, with self-installers that can be run from the command-line available for download here. The Intel version will run on both types of Mac processors, but the native ARM versions offer the highest GSAS-II performance we see on any platform.

    It appears that this installer can be used with MacOS versions 11.0 and later. Macs older than Catalina (10.15) will likely require older distributions of Python.

  • Intel Linux: Note that GSAS-II does not get a lot of testing in Linux by us, but is used fairly widely on this platform nonetheless. We provide an installer here that includes Python and needed packages for Intel-compatible Linuxes, but compatibility with older and very new versions of Linux can sometimes be tricky as compatibility libraries may be needed – not always easy to do. It may be better to use your Linux distribution’s versions of Python and packages (typically done with a software tool such as apt or yum or pip. See https://advancedphotonsource.github.io/GSAS-II-tutorials/install-pip.html for more information.

  • Non-Intel Linux: Will GSAS-II run on Linux with other types of CPUs? That will mostly depend on support for Python and wxPython on that CPU. If those can be used, you can likely build the GSAS-II binaries with gcc & gfortran. Expect to need to modify the meson files.

    Raspberry Pi (ARM) Linux: GSAS-II has been installed on both 32-bit and the 64-bit version of the Raspberry Pi OS (formerly called Raspbian) and some older compiled binaries are provided at present for both, but 32-bit support may not continue. It is expected that these binaries will also function on Ubuntu Linux for Raspberry Pi, but this has not been tried. The performance of GSAS-II on a Raspberry Pi is not blindingly fast, but one can indeed run GSAS-II on a motherboard that costs only $15 (perhaps even one that costs $5) and uses <5 Watts!

    Note that the 64-bit OS is preferred on the models where it can be run (currently including models 3A+, 3B, 3B+, 4, 400, CM3, CM3+, CM4, and Zero 2 W) . With the 32-bit Raspberry Pi OS, which does run on all Raspberry Pi models, it is necessary to use the OS distribution’s versions of Python and its packages, see here for more information. With 64-bit Pi OS it may be possible for us to provide a GSAS2MAIN installer (which will need to include a custom-supplied wxPython wheel, since that is not available in conda-forge) or else pip must be used to download and build wxpython (quite slow). Please let Brian know if you are intending to use GSAS-II on a Raspberry Pi for a classroom, etc and would need help with this.

1.2. Source Code Management

The master version of the source code for GSAS-II resides on GitHub at URL (in branch main) and the git version control system (VCS) is usually used to install the files needed by GSAS-II. When GSAS-II is installed in this manner, the software can be easily updated, as git commands can download only the changed sections of files that need to be updated. It is likewise possible to use git to regress to an older version of GSAS-II, though there are some limitations on how far back older versions of GSAS-II will be with current versions of Python and associated packages. While git is not required for use of GSAS-II, special procedures must be used to install GSAS-II without it and once installed without git, updates of GSAS-II must be done manually.

1.3. Python Requirements

GSAS-II requires a standard Python interpreter to be installed, as well as several separately-developed packages that are not supplied with Python, as are described below. While for some packages, we have not seen much dependence on versions, for others we do find significant differences; this is also discussed further below. The GSAS-II GUI will warn about Python and packages versions that are believed to be problematic, as defined in variable GSASIIdataGUI.versionDict, but for new installations we are currently recommending the following interpreter/package versions:

  • Python 3.11, 3.12 or 3.13 is recommended. No testing has yet been done with Python 3.14, but no problems are expected. GSAS-II should run with any Python version from 3.7 or later, but we do not create binaries for all versions of Python and numpy. You will need to locate (from the old subversion server) older binaries to match older Python versions or compile them yourself.

  • wxPython 4.2 or later is recommended, but with Python <=3.9 any wx4.x version should be OK. Problems with newer sections of the GUI are expected for wx <4.0.

  • NumPy 1.26 recommended with Python 3.11 and 2.2 with 3.12 or 3.13, but anything from 1.17 on is likely fine, but if you do not match the supplied GSAS-II binaries you will need to build them yourself.

  • matplotlib-base Note that matplotlib-base is preferred over matplotlib unless matplotlib will be used outside GSAS-II. 3.10 is recommended, but anything later than 3.4 should be fine.

  • pyOpenGL: no version-related problems have been seen.

  • SciPy: no version-related problems have been seen, but in at least one case multiple imports are tried to account for where function names have changed.

  • PyCifRW: no version issues are known. We had been using an older version for a long time, but in 2025 switched to the latest version and did not see any problems.

  • pybaselines: no version issues are known.

For more details on problems noted with specific versions of Python and Python packages, see comments below and details here: GSASIIdataGUI.versionDict,

Note that GSAS-II is currently being developed using Python 3.11 through 3.13. We are no longer supporting Python 2.7 and <=3.6, and strongly encourage that systems running GSAS-II under these older Python versions reinstall Python. Typically this is done by reinstalling GSAS-II from a current self-installer.

There are a number of ways to install Python plus the packages needed by GSAS-II. See https://advancedphotonsource.github.io/GSAS-II-tutorials/install.html and links therein for a discussion of installation.

Python package requirements depend on how GSAS-II will be run, as will be discussed in the next section. In order to run the GUI for GSAS-II, a much larger number of packages are required. Several more packages are optional, but some functionally will not be available without those optional packages. Far fewer packages are required to run GSAS-II on a compute server via the scripting interface and without a GUI.

1.3.1. GUI Requirements

When using the GSAS-II graphical user interface (GUI), the following Python extension packages are required:

GSAS-II will not start or will start but will not be able to do much if the above packages are not available.

1.3.3. Scripting Requirements

The GSAS-II scripting interface (GSASIIscriptable) will not run without the NumPy Python extension package:

In theory, GSAS-II should start without access to the CIF read/write library, PyCifRW, but in practice, almost everything one wants to do with GSAS-II needs CIF access at some point and I have never tested without this package, so I will consider this also as mandatory for scripting:

While not required, and not used very much in GSAS-II scripting, installing the SciPy is recommended:

These packages fortunately are common and are easy to install.

1.3.5. Optional Python Packages

  • Sphinx (https://www.sphinx-doc.org) is used to generate the documentation you are currently reading. Generation of this documentation is not generally something needed by users or even most code developers, since the prepared documentation on https://gsas-ii.readthedocs.io is usually reasonably up to date.

  • The sphinx-rtd-theme is required to build the documentation in standard the format (though this can be changed with minor editing.)

1.3.6. Compilation Requirements

Most users on Windows and Mac will not need to compile GSAS-II. Binaries are supplied as part of the gsas2main self-installer. Linux users may need to install the software in a manner that allows for local compilation. Developers may wish to perform all installation steps for themselves. These are the requirements:

  • The gfortran complier is required. There has been some work done with glang, and I think this passes the self-tests but it is unknown if there are other problems. This can be installed in a number of ways. For Windows and Mac, conda-forge is a good choice. (For MacOS, Apple’s XCode must also be installed). For Linux, dist-supplied versions are probably a better choice.

  • gcc or other c compiler is required to build one binary for image processing. For Windows use Microsoft Visual C/C++. On Mac, use of conda-forge to install gcc is a good installation choice (again XCode is required). For Linux, dist-supplied versions are probably a better choice.

  • meson (https://mesonbuild.com/meson-python/) is used to compile the relatively small amount of Fortran, C and Cython code that is included with GSAS-II. This is a Python package typically installed with conda or pip. On Linux, a dist-supplied version (Debian, RedHat, etc.) is likely available too.

  • Cython is needed to build one binary used for magnetism (k-vector searching). Install this typically with conda or pip.

1.3.7. Installation Notes for Minimal Python configuration

There are many ways to install a minimal Python configuration. Below, I show some example commands used to install using the the free miniconda installer from Anaconda, Inc., but I now tend to use the Conda-Forge miniforge distributions instead. However, there are also plenty of other ways to install Python, Numpy and Scipy, depending on if they will be used on Linux, Windows and MacOS. For Linux, the standard Linux distributions provide these using yum or apt-get etc., but these often supply package versions that are so new that they probably have not been tested with GSAS-II.

bash ~/Downloads/Miniconda3-latest-<platform>-x86_64.sh -b -p /loc/pyg2script
source /loc/pyg2script/bin/activate
conda install numpy scipy pycifrw matplotlib-base pillow h5py hdf5

Some discussion on these commands follows:

  • the 1st command (bash) assumes that the appropriate version of Miniconda has been downloaded from https://docs.conda.io/en/latest/miniconda.html and /loc/pyg2script is where I have selected for python to be installed. You might want to use something like ~/pyg2script.

  • the 2nd command (source) is needed to access Python with miniconda.

  • the 3rd command (conda) installs all possible packages that might be used by scripting, but note that matplotlib, pillow, h5py and hdf5 are not commonly needed and could be omitted.

Once Python has been installed and is in the path, use these commands to install GSAS-II:

git clone https://github.com/AdvancedPhotonSource/GSAS-II.git /loc/GSAS-II
python /loc/GSAS-II/GSASII/GSASIIscriptable.py

Notes on these commands:

  • the 1st command (git) is used to download the GSAS-II software. /loc/GSASII is the location where I decided to install the software. You can select something different.

  • the 2nd command (python) is used to invoke GSAS-II scriptable for the first time, which is needed to load the binary files from the server.

1.4. Required Binary Files

As noted before, GSAS-II also requires that some code be compiled. For the following platforms:

  • Windows-10: 64-bit Intel-compatible processors.

  • MacOS: Intel processors.

  • MacOS: ARM processors, aka Apple Silicon (M1, etc).

  • Linux: 64-bit Intel-compatible processors.

Some binaries are also supplied for Raspberry Pi, but may not be up-to-date. Please ask for newer if needed:

  • Linux: ARM processors (64-bit and 32-bit Raspberry Pi OS and Ubuntu for Raspberry Pi).

Binary images are provided at https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/latest. At present binaries are supplied for the following versions:

  • Python 3.11 and NumPy 1.26

  • Python 3.12 and NumPy 2.2

  • Python 3.13 and NumPy 2.2

Note that these binaries must match the major and minor version of both Python. Usually if the minor version is close to the numpy version (1.25.x and 1.27.x for 1.26) the binaries will still work.

Should one wish to run GSAS-II where binary files are not supplied (such as 32-bit Windows or Linux) or with other combinations of Python/NumPy, compilation will be need to be done by the user. See the compilation information for more information. The build process was recently updated to use meson (in place of scons).

1.5. Supported Externally-Developed Software

GSAS-II provides interfaces to use a number of programs developed by others. Some are included with GSAS-II and others must be installed separately. When these programs are accessed, citation information is provided as we hope that users will recognize the contribution made by the authors of these programs and will honor those efforts by citing that work in addition to GSAS-II.

GSAS-II includes copies of the following programs. No additional steps beyond a standard installation are needed to access their functionality.

DIFFaX

Simulate layered structures with faulting. https://www.public.asu.edu/~mtreacy/DIFFaX.html

Shapes

Derives the shapes of particles from small angle scattering data.

NIST FPA

Use Fundamental Parameters to determine GSAS-II profile function

NIST*LATTICE

Searches for higher symmetry unit cells and possible relationships between unit cells. An API has been written and this will be integrated into the GSAS-II GUI.

The following web services can also be accessed from computers that have internet access. All software needed for this access is included with GSAS-II.

Bilbao Crystallographic Server (http://cryst.ehu.es/):

GSAS-II can directly access the Bilbao Crystallographic Server to utilize the k-SUBGROUPSMAG, k-SUBGROUPS and PseudoLattice web utilities for computation of space group subgroups, color (magnetic) subgroups & lattice search.

BYU ISOTROPY Software Suite (https://iso.byu.edu/isotropy.php):

GSAS-II directly accesses capabilities in the ISOTROPY Software Suite from Brigham Young University for representational analysis and magnetism analysis.

At the request of the program authors, other programs that can be accessed within GSAS-II are not included as part of the GSAS-II distribution. These are listed below. See the web installation instructions for details on how they are installed.

Dysnomia

Computes enhanced Fourier maps with Maximum Entropy estimated extension of the reflection sphere. See https://jp-minerals.org/dysnomia/en/.

RMCProfile

Provides large-box PDF & S(Q) fitting. The GSAS-II interface was originally written for use with release 6.7.7 of RMCProfile, but updates have been made for compatible with 6.7.9 as well. RMCProfile must be downloaded by the user from http://rmcprofile.org/Downloads or https://rmcprofile.pages.ornl.gov/nav_pages/download/

fullrmc

A modern software framework for large-box PDF & S(Q) fitting. Note that the GSAS-II implementation is not compatible with the last open-source version of fullrmc, but rather the version 5.0 must be used, which is distributed only as compiled versions and only for 64-bit Intel-compatible processors running Windows, Linux and MacOS.

PDFfit2

For small-box fitting of PDFs; see https://github.com/diffpy/diffpy.pdffit2?tab=readme-ov-file#-diffpypdffit2. This software is no longer developed, but it is being maintained with respect to new Python versions.