1. GSAS-II Installation Options

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 additonal capabilities. This much match 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 that 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.

• <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.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 after 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

1.4. Installation for GSAS-II Software Developers

While all of the above approaches do clone a copy of the GSAS-II repository from GitHub, software developers may find it more convenient to clone the repo themselves in a location that they prefer. This will also require a properly configured Python, as described immediately above. Cloning is done from git@github.com:AdvancedPhotonSource/GSAS-II.git or https://github.com/AdvancedPhotonSource/GSAS-II.git. with a command like:

git clone git@github.com:AdvancedPhotonSource/GSAS-II.git ~/myProjects/myGSASII

If the repo is cloned at ~/myProjects/myGSASII then the local copy of GSAS-II can be run as a GUI using:

python ~/myProjects/myGSASII/GSASII/GSASII.py

Installation scripts used inside the previously described installers are available for creating shortcuts to run GSAS-II from a GitHub repo that has been manually installed. See discussion of makeMacApp.py, makeLinux.py and makeBat.py (for MacOS, Linux and Windows, respectively) in the Developer’s Documentation. Also, to simplify use of your local clone of the GSAS-II repo when scripting GSAS-II, see this note on scripting shortcuts.

1.5. Older methods

Previously GSAS-II was provided via an Advanced Photon Source-maintained subversion (svn) server, with differing installation processes. While the installers for those processes are still available, this is not encouraged. Also, updates will be provided for those past svn installations for the immediate future, this will not be continued indefinitely. Thus, we are encouraging users to reinstall GSAS-II via one of the above methods if they previously installed GSAS-II via svn. When updates via svn will be phased out, GSAS-II will provide warning messages.