Installing GSAS-II with a Single-Step Download (with figures)

This process downloads an installer that will place a working version of Python and the required packages onto your computer, it will then initially install a slightly out-of-date version of GSAS-II including the binaries files needed for running on a Mac. If internet access is available, the GSAS-II distribution site will be checked and updates will be applied to bring GSAS-II up to date. If the installer is moved to a computer without an internet connection, this will provide a working, though slightly out-of-date, copy of GSAS-II.

Use the following steps to install GSAS-II on a Mac:

Step 1:

In this step you will ​download a file and then use bash to run it. A simple way to do this is to open a terminal window (use the Terminal app in Applications/Utilities folder; typing terminal.app into the finder search box should find this for you).

In that window cut and paste the two commands below:

g2="https://subversion.xray.aps.anl.gov/admin_pyGSAS/downloads/gsas2full-Latest-MacOSX-x86_64.sh"
curl "$g2" > /tmp/g2.sh; bash /tmp/g2.sh -b -p ~/g2full

A few notes on this step.

• By using the -b option in the command above, you are agreeing to the Python and GSAS-II license shown below; the text of the GSAS-II license is also below.
• The -p option specifies where GSAS-II is installed. Note that -p ~/g2full installs GSAS-II into directory g2full in your home folder. Change ~/g2full if desired.
• The curl command will likely fail if your network requires a proxy to access the internet. In that case you can download file ​https://subversion.xray.aps.anl.gov/admin_pyGSAS/downloads/gsas2full-Latest-MacOSX-x86_64.sh by clicking on it here in your browser and run it using steps listed below. Note though that you will need to know the proxy settings in order to get GSAS-II to properly update, see ProxyInfo for more.
• If you want to install GSAS-II onto a computer that does not have an internet connection (or has a slow or expensive connection), download file ​https://subversion.xray.aps.anl.gov/admin_pyGSAS/downloads/gsas2full-Latest-MacOSX-x86_64.sh on a computer with better access and move the downloaded file on a USB stick, etc to where you wish to install it. Note that the installation process will use the internet if access is available, but usually only very minor amounts of information will be transferred. Installation will complete properly even without network access, but a not quite up-to-date version of GSAS-II will be will installed.

Step 2:

[

Step 3:

The installation procedure creates an app to help launch GSAS-II and places that app in the GSAS-II folder. It also opens a Finder window, showing that app (labeled as GSAS-II), as below. This app will not run if moved to another location, but it can be dragged to the toolbar, as is shown below. It may not appear with the GSAS-II icon, as shown in the figure (the reason for this is not yet understood.)

Confirm that GSAS-II can run from this app by double-clicking on it. The first time this is done, you will likely be asked to confirm this app should have access to the Terminal app with this message:

Click OK and three windows should open (the terminal window, the GSAS-II main window and the GSAS-II Plots window).

Step 4: (drag to dock, optional)

The GSAS-II app created by the installation procedure can be dragged to the dock to make launching GSAS-II simple. Note the app will not run if moved to another location, such as the desktop. See the next step on how to create a desktop icon.

Step 5: (Desktop icon, optional)

If you would like place the GSAS-II app in another location (for example your computer's desktop) to make it convenient to start GSAS-II, you need to make an alias. This alias file can be moved. Press control and click on the GSAS-II app (or use right-click with a 2 or 3 button mouse) and a menu of options is shown. Click on "Make Alias" and a new file, "GSAS-II alias" is created in that folder.

Note that the "GSAS-II alias" file can be dragged to the desktop, or wherever it is convenient for your use. It can also be renamed after the file is moved.

Update Error Message

After Python and packages are installed, the GSASII/bootstrap.py file is invoked. This tests that the GSAS-II binaries files work, creates shortcuts and updates the GSAS-II files using program svn (subversion) from the APS server https://subversion.xray.aps.anl.gov/pyGSAS. The svn update requires a working internet connection. If the svn program is not able to update properly then this error message is shown:

If the computer does not have an internet connection, this error is expected and can be ignored. If the computer is later connected to the internet, you are recommended to use the Help/Update command to obtain the latest version of GSAS-II and continue updating periodically.

If the computer does have a working internet connection, it is likely that the update failed due to your network requiring an internet proxy (discussed in the next section).

Note the message for recreating the error:

/<your location>/bin/python /<your location>/GSASII/bootstrap.py --noinstall

If GSAS-II is installed, but the installation process is unable to update, create an app, etc., it may be worthwhile to run this command again by copying the information from your error message into a Terminal.app window (the flag such as --noinstall may be omitted.) This will provide better warning and error messages than above.

Installing with a web proxy or to a system without the internet

If the above "curl" command in step 1 fails, but you are able to download the same file in a web browser, your network is most likely set up so that internet traffic is routed through a proxy computer. If you have a proxy, you will need to know either the name or IP address of the proxy computer and you will need to know the IP port (usually 80 but sometimes something else, such as 8080 or 8000.) Finding a network administrator who knows what your site is doing can be tough but may be needed to get updating to work. The web site http:/www.whatismyproxy.com/ may help.

The easiest way to setup a proxy is to download the installation file with a browser and start it, as described in steps A1 and A2 below, then continue with step 2, above. After completing this installation process, start GSAS-II and from inside GSAS-II use the File/"Edit Proxy" menu command to enter the proxy information; check if the values work using the Help/"Check for Updates" menu command to update to the latest version.

Step A1:

Download this file in a web browser:

• ​https://subversion.xray.aps.anl.gov/admin_pyGSAS/downloads/gsas2full-Latest-MacOSX-x86_64.sh (provides Python 3.7, all required Python packages and a recent version of GSAS-II which will be updated via the internet; can be installed on computers without an internet connection, but without that update.) This file is also available here ​https://anl.app.box.com/v/GSASIIdistributions, where you will need to use the "..." menu to the right of entry gsas2full-latest-MacOSX-x86_64.sh to download that file.

Step A2:

Execute this file.

Type "bash " into a terminal window (note space after "h"), then drag the downloaded file from a finder window into the terminal window.

This places the file name with full path name into the terminal window, then press Enter.

Debugging

Two files are created as the GSAS-II installation is done.

• File /tmp/bootstrap1.log contains the output when creating the app and making other installation steps.
• File /tmp/bootstrap2.log contains the output when performing an update.

If installation fails and you want to get help, please include these files in your e-mail. Note they will deleted during your next reboot.

Licenses

GSAS-II Information & Anaconda license:

====================================================
This is a single-download installer for GSAS-II. It includes other
software such as subversion (svn, used to update GSAS-II), a Python 
interpreter and a number of Python packages required by GSAS-II. The
file you are running will install GSAS-II, Python, etc. and will then
run the bootstrap.py script to create shortcuts and will use svn to
update to the latest version of GSAS-II, if an internet connection is
available. Note that the bootstrap.py script can be rerun manually to
obtain updates.

*** Note that while this installer can be rerun to install the software
in a new location, once these files are installed, they should not be
moved. ***

If you use GSAS-II in your research, please show your support by citing:
B.H. Toby & R.B. Von Dreele, J. Appl. Cryst. 46, 544-549 (2013)  
(also see Help/About)

See the GSAS-II source code for license information. Material
below is relevant to the Anaconda Python distribution, which is
freely provided by Continuum Analytics, Inc. 

====================================================
 Copyright (c) 2016, Continuum Analytics, Inc.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of Continuum Analytics, Inc. nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL CONTINUUM ANALYTICS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

GSAS-II License:

           General Structure Analysis System - II (GSAS-II)
                         OPEN SOURCE LICENSE

Copyright 2010, UChicago Argonne, LLC, Operator of Argonne National Laboratory 
All rights reserved.

GSAS-II may be used by anyone on a royalty-free basis. Use and
redistribution, with or without modification, are permitted provided
that the following conditions are met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
* Software changes, modifications, or derivative works should be noted
  with comments and the author and organization's name.
* Distribution of changed, modified or derivative works based on
  GSAS-II grants the GSAS-II copyright holder unrestricted permission
  to include any, or all, new and changed code in future GSAS-II
  releases.
* Redistributions that include binary forms must include all relevant
  source code and reproduce the above copyright notice, this list of
  conditions and the following disclaimers in the documentation and/or
  other materials provided with the distribution.
* Neither the names of UChicago Argonne, LLC or the Department of
  Energy nor the names of its contributors may be used to endorse or
  promote products derived from this software without specific prior
  written permission.
* The software and the end-user documentation included with the
  redistribution, if any, must include the following acknowledgment:
  "This product includes software produced by UChicago Argonne, LLC
  under Contract No. DE-AC02-06CH11357 with the Department of Energy."

*****************************************************************************
WARRANTY DISCLAIMER: THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY
OF ANY KIND. THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE
UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR
EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME
ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS,
OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE
SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT
THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE
OR THAT ANY ERRORS WILL BE CORRECTED.

LIMITATION OF LIABILITY: IN NO EVENT WILL THE COPYRIGHT HOLDERS, THEIR
THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT
OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE,
INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY
REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF
CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR
OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGES.
******************************************************************************

Prompted Installation

Answer prompts from the install script.

1. Press enter to start the procedure

2. Press space several times to page through the copyright notice. For convenience the full text from this screen and the GSAS-II license are shown below.

3. Type "yes" to accept the copyright information and start the installation.

4. Enter a location for where the files should be installed, if the default is not what you prefer. The default will usually be OK, in which case you can simply press enter. Installation has not been tested where paths contain spaces or special characters, so it is a good idea to install GSAS-II in an alternate location if the default has spaces or Unicode characters. Note that GSAS-II cannot be moved once installed. If you need it to move it please reinstall and delete the old copy.

Make a note of where you have installed GSAS-II; this will be needed if you have problems with the software.

5. Pressing enter to accept the default installation location or providing a installation location will trigger installation of the software with a series of messages. If the installation progresses normally, the final messages will appear as below:

If error or warning messages are seen, it is suggested that you save a screen image or use cut and paste to save the text in the window to a file. The most common error message is discussed below.

6. It is recommended that you type "no" for the question about initializing gsas2full using conda init as it is not needed to run GSAS-II. If you say "yes" or use the default, then the version of Python installed by GSAS-II becomes the default version, which usually will not cause problems either. The installation completes with these messages (which can be ignored):

Older installers

See these older instructions? for infomation on older distributions. They may be needed for systems with older versions of MacOS. Note that these installers do require an internet connection to complete the installation.