1. Installing GSAS-II: Overview

Running GSAS-II requires a number of coordinated installation steps and there are many different ways this can be accomplished. One needs not only the necessary Python source code for GSAS-II, but a Python interpreter that includes a number of “add-on” Python packages for additional capabilities. This much match the operating system for the computer where the software will be run. Further, GSAS-II requires that a small amount of its code be compiled, typically for speed and this must be matched both the computer OS and to the Python version. Here I outline different a few different approaches.

1.1. GSAS2FULL installer

Most users of GSAS-II are seeking a simple way to install and run the software and can live with the idea that they may have duplicated Python installations (several hundreds of MB each) on their computer. The GSAS2FULL self-installer provides simple installation and can be downloaded from here. Brief installation instructions are outlined below with links to more complete instructions:

1.1.1. Windows

For Windows download file https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2full-Latest-Windows-x86_64.exe and run it. After the installer is started You will have a choice for where to install the software (the default is usually OK, but something like c:\software might be better, if your computer security allows that.)

More complete installation instructions are here.

1.1.2. MacOS and Linux

For MacOS and Linux use a command such as:

g2="https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2full-Latest-<platform>"
curl -L "$g2" > /tmp/g2.sh; bash /tmp/g2.sh -b -p <install-loc>

where:

• <platform> is replaced by Linux-x86_64.sh for Linux, MacOSX-arm64.sh for MacOS with “Apple Silicon” (M1, etc.) processors and MacOSX-x86_64.sh is for older Intel-based machines. Note that the MacOSX-x86_64.sh installer will run on “Apple Silicon” processors, but significantly more slowly. Thus choices are:

  g2="https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2full-Latest-Linux-x86_64.sh"
  g2="https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2full-Latest-MacOSX-arm64.sh"
  g2="https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2full-Latest-MacOSX-x86_64.sh"
  

• <install-loc> is where you want to install the software. (Use of ~/g2full, a subdirectory named g2full in your home directory is a good choice.) After installation is complete, you may be asked if you want to place a shortcut for GSAS-II into the MacOS dock.

More complete installation instructions are provided for MacOS and Linux.

1.1.3. GSAS2FULL Additional Details

The pages listed below go through the GSAS2FULL installation process on each identified platform in much greater detail.

• 1.1.3.1. Windows GSAS2FULL Installation Details
  • 1.1.3.1.1. Notes
• 1.1.3.2. MacOS GSAS2FULL Installation Details
• 1.1.3.3. Linux GSAS2FULL Installation Details

1.2. GSAS2PKG Conda Package

Users who work extensively with Python and use the conda Python installer may prefer to utilize their existing conda installation to obtain GSAS-II along with the Python configuration that GSAS-II prefers. This can be done with this command (on all platforms):

conda create -n GSASII briantoby::gsas2pkg  -c conda-forge

This creates a conda virtual environment named GSASII (this can be changed) for use by GSAS-II. While it is also possible to install GSAS-II into the conda base environment, this is not recommended as it can create conflicts between Python and package versions needed by GSAS-II and those required by other packages. (If you choose to do this anyway, be sure to specify conda install python=3.11 briantoby::gsas2pkg as Python is likely to be pinned to a different version.)

After this command is run, use command conda activate GSASII to access the conda environment that has been created. On Linux and MacOS computers, two shortcut commands will then be available in the path, The first command, gsasII.sh, which will start GSAS-II. This can optionally be used as gsasII.sh project.gpx to open existing project file project.gpx in GSAS-II. The second command, reset-gsasII.sh will rarely be used. This command will download the latest version of GSAS-II and update to that version, replacing any locally modified files with the original versions. This can be used to update GSAS-II when the program will not start, so the normal Help->Update menu command cannot be accessed. (Shortcuts available with gsas2pkg v5.1+.)

Note that on MacOS, a Mac app is also created and is displayed in the Finder see steps 5 & 6 here. This app can be used to start GSAS-II from the dock or desktop.

1.3. Installing GSAS-II with separate Python Installation

A small number of users or sites prefer to use Python distributions supplied via other routes (such as Debian packages) or using PyPi, etc. or prefer to handle use of conda on their own. Some discussion on Python installation is found here. Independent of how Python is installed, multiple packages are needed, please see the discussion on Python package requirements, noting that the GSAS-II GUI requires at a minimum wxPython, matplotlib, PyOpenGL, NumPy and SciPy, while for scripting use, only NumPy and SciPy are required. For full functionality, several other optional packages are needed. If versions other than those recommended are selected (Python=3.11 and NumPy=1.26), you will likely need to either locate older binaries and install them manually or compile them yourself (see compilation information).

A simple way to install GSAS-II with a supplied Python environment uses the gitstrap.py script provided for this purpose. Use these commands (on any platform) to install GSAS-II:

cd ~/G2
curl -L -O https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/raw/main/install/gitstrap.py
python gitstrap.py

This will place the install script in directory ~/G2 (which you may wish to change) and will place all GSAS-II files in subdirectory ~/G2/GSAS-II

Note that you can also clone the GitHub repo. If you do this, the GSAS-II binary files will not be installed. However, when GSAS-II is first run, it will provide an opportunity to do this.

1.4. Installing directly from GitHub

While all of the above approaches will clone a copy of the GSAS-II repository from GitHub, software developers may find it more convenient to clone the repo themselves. This will typically be done as part of a process where a copy of GSAS-II is forked on GitHub. This is described in a separate page.

• 1.4.1. Installing GSAS-II for code development
  • 1.4.1.1. Create a GitHub account
  • 1.4.1.2. Establish a connection
  • 1.4.1.3. create a fork of GSAS-II
  • 1.4.1.4. Install GSAS-II from your forked copy
    • 1.4.1.4.1. Install directly from your forked copy
    • 1.4.1.4.2. Repurpose a standard GSAS-II installation
  • 1.4.1.5. Make changes and submit them
• 1.4.2. Code development tip

1.5. Older installers

Previously GSAS-II was provided via an Advanced Photon Source-maintained subversion (svn) server, with differing installation processes. The subversion server is not longer being updated, so those installers should not be used because if GSAS-II is installed from subversion, you will not be able to update to the current GSAS-II version. If you previously installed GSAS-II from that server, you will be shown a message when trying to update that you should reinstall GSAS-II as described above.

1.6. Installation details

Most people will not need these details, but some specific installation details are discussed in the topics below.

• 1.6.1. Compiling GSAS-II
• 1.6.2. Customized Python Installation
  • 1.6.2.1. conda
  • 1.6.2.2. pip
  • 1.6.2.3. homebrew
  • 1.6.2.4. Distro-supplied packages
• 1.6.3. Web Proxies