wiki:InstallLinux

Information here is out-of-date. Please use web site ​https://gsasii.github.io/ for information on GSAS-II

Installing GSAS-II on Linux systems

There are a number huge number of Linux distributions in popular use and it is not clear if a simplified distribution method for GSAS-II can work for all of them. A fully functioning GSAS-II installation requires three things beyond the GSAS-II Python code:

  • the subversion package manager (available for just about every Linux dist). This is run with the svn command, so the names svn and subversion are sometimes used interchangeably,
  • Python, with a handful of Python packages (​described here), and
  • GSAS-II binaries, which are compiled versions of Fortran routines that improve speed or provide capabilities not translated to Python.

GSAS-II provides copies of these binary (.so) files, but these must match both the versions of both Python and the numPy. Also they are prepared on a Redhat Enterprise Linux system using Python and numPy from the conda-forge Python distribution. The diversity of popular Linux varieties means that the distributed binary files may not be compatible with some Linux systems. On those systems, local compilation will be needed. This is easy, requiring only installation of gfortran and the Python scons package.

Option I. Installing the easy way

Most Linux users will be able to install GSAS-II by downloading a single file that contains and installs all needed Python packages, subversion, and a copy of the GSAS-II codes. It then uses subversion to update the GSAS-II code to the latest version, so that this self-installer need not be updated frequently.

For 64-bit Linux dists running on Intel-compatible processor, only two commands are needed to install GSAS-II in Linux with this method: 

curl https://subversion.xray.aps.anl.gov/admin_pyGSAS/downloads/gsas2full-Latest-Linux-x86_64.sh > /tmp/gsas2full-Latest-Linux-x86_64.sh
bash /tmp/gsas2full-Latest-Linux-x86_64.sh -b -p ~/g2full

This will create a desktop shortcut and/or a menu command on many types of Linux desktop managers, but it is also possible to start GSAS-II with either this command: 

~/g2full/bin/python ~/g2full/GSASII/GSASII.py

or this 

bash ~/g2full/start_GSASII.sh

Note that ~/g2full above specifies where GSAS-II and its Python installation will be placed. This can be changed in all of the above at your convenience. You can have multiple GSAS-II installations in separate directories if desired. These instructions provide for more details on the self-installer.

Option II. Using a pre-Installed Conda

If you are already a user of Anaconda Python, then you may not want to install yet another version of Python on your computer. Note however, that Anaconda itself no longer packages modern versions of the wxPython and subversion packages needed by GSAS-II, so use of the conda-forge channel is needed and you are also recommended to install GSAS-II in a separate environment to avoid conflicts with other Python application requirements.

Assuming you have anaconda or miniconda (or for that matter miniforge or mambaforge) installed, the following commands should install a Python environment for GSAS-II: 

g2home=~/GSASII
conda create -n g2python python=3.10 wxpython=4.2 numpy=1.23 scipy matplotlib pyopengl pillow h5py imageio conda subversion requests -c conda-forge -y
conda activate g2python

Note that the first line determines where GSAS-II will be installed. You can change this location as needed.

These commands will then install GSAS-II: 

mkdir -p $g2home
cd $g2home
svn export https://subversion.xray.aps.anl.gov/pyGSAS/install/bootstrap.py $g2home
python $g2home/bootstrap.py

Note that this will ask you for a network proxy, which for most users should be left blank. For more information on network proxies, read this.

These commands will then create a shortcut for starting GSAS-II (optional): 

echo "# Commands to start GSAS-II" > $g2home/start_GSASII.sh
echo "source $CONDA_PREFIX/bin/activate" >> $g2home/start_GSASII.sh
echo "$CONDA_PREFIX/bin/python $g2home/GSASII.py" >> $g2home/start_GSASII.sh

Start GSAS-II with either this command (change depending on where you choose to install GSAS-II location): 

<condapath>/bin/activate g2python
python ~/GSASII/GSASII.py

or this 

bash ~/GSASII/start_GSASII.sh

or depending on the Linux desktop manager, a desktop shortcut and/or a menu command may also be available.

Option III. Installing Python etc. Manually

GSAS-II will run with any distribution of Python, provided it is version >=3.7 (3.10 recommended), and provided you have the GSAS-II required packages, which are wxPython (4.2+ recommended w/Py3.10), NumPy, SciPy, matplotlib and PyOpenGL. (Some additional packages provide optional functionality; see ​here for more information on package requirements in GSAS-II.) This allows GSAS-II to run on ARM platforms. In theory, any CPU where the required Python packages can run should also support GSAS-II, provided that gfortran can also be used to compile (see below).

Satisfying the Python requirements can usually be done with a combination of apt-get/yum commands to obtain the major Python packages and pip to install others. Use the Linux-dist channel rather than pip where the choice is available.

You will also need subversion (svn) to download GSAS-II files. All Linux dists offer this (also found in conda-forge).

Once you have installed Python and subversion, follow these steps to install GSAS-II:

  1. Create an empty directory. Best to have no spaces in the full path. GSASII is recommended as a good name for this. This location will be used as <path> in the instructions below.
  1. Download the installation script (bootstrap.py) from ​https://subversion.xray.aps.anl.gov/pyGSAS/install/. Note that <path> below must be an empty directory. Two ways to do this are
    1. with commands: 
      mkdir -p <path>
cd <path>
svn export https://subversion.xray.aps.anl.gov/pyGSAS/install/bootstrap.py .
    2. or by loading this URL in a browser: ​https://subversion.xray.aps.anl.gov/trac/pyGSAS/browser/install/bootstrap.py?format=txt and then move this file to <path>.
  1. Run the bootstrap.py script using the python package you have installed with this command in a terminal window 
<pypath>python bootstrap.py

Where <pypath> is the location where python has been installed (may be omitted if this Python is at the top of your path).

The installation script will attempt to create a desktop icon for running GSAS-II, but this may not be appropriate for your Linux configuration. If you want to create a shortcut, have it run <pypath>python <path>GSASII.py

If you are installing GSAS-II on a server and want to download binary files for all supported platforms, use 

<pypath>python bootstrap.py -server

or equivalently 

<pypath>python bootstrap.py -allbinaries

Compiling Fortran Code

Most users will not need to do this, but if you get an error message such as: 

Failed to run pyspg in .../GSASII/bindist
error: libgfortran.so.3: cannot open shared object file: No such file or directory

or an error message about a missing symbol... In this case, you have a choice. You can try to modify your Linux installation to have appropriate libraries (which may be older compatibility versions or updates) or compile the GSAS-II files locally. To do the latter you will need to have the Python scons file and the Linux gfortran compiler installed. If you are using 32-bit Linux (where we are no longer generating binaries) you will have to compile yourself.

If you are using Anaconda Python (see I. and II. above), this can be done with a simple command: 

conda install scons gfortran_linux-64

If conda is not in your path, then fix that with this command before running the above: 

source <pypath>/bin/activate

Otherwise, you will need to use your Linux package manager to install gfortran and scons. You will also need the NumPy f2py routine, but that should already be present since you already installed NumPy. In a terminal window use the following commands

  1. change the working directory: 
    cd <path>/GSASII/fsource
    and
  1. run scons to start compilation 
    scons

If you need to change any options, type scons help to see a list of the possible command-line arguments and the values for the options. For testing, help can be used with command-line options to see how they will change the variables.

Problems

As most GSAS-II testing is done with Windows and Macs (sorry), there is a chance we will miss on some Linux-specific problems. Please do report problems, since we can't fix what we don't know about (​see here), but cannot promise to test with your specific Linux dist.

There are many, many versions of Linux and some are too new or old and thus will not have .so libraries installed that allow running our supplied versions of Python or the compiled GSAS-II Fortran code.

You should be able to run GSAS-II with Python and packages from your Linux dist, though sometimes those package versions are so new that you will discover incompatibilities that we have not yet seen. To avoid that you can use the Anaconda Python installer, which is included in the gsas2full-Latest-Linux-x86_64.sh file referenced in Option I above.

  • One problem we have seen with this comes from not running the installer properly. Please make sure you are typing bash correctly and leaving a space between that and the file name, also be sure you are allowed to write files to the location you choose for installation.
  • If you see an error message like this when starting GSAS-II: 
    Failed to run pyspg in /home/me/anaconda3/envs/G2/GSASII/bindist
error: libgfortran.so.4: cannot open shared object file: No such file or directory
    then you may be able to address the problem by installing a compatibility library (using a command like this: yum install libgfortran4. A Google search with the name of the missing library and the name of your distribution (CentOS, Ubuntu, Fedora,...) may help.
  • If you see an error like this when launching GSAS-II: 
    user:/~% ~/g2full/bin/python ~/g2full/GSASII/GSASII.py
Invalid MIT-MAGIC-COOKIE-1 key. 
Unable to access the X Display, is $DISPLAY set properly?
    This means that Python is not being permitted access to your computer's display. As the message states, the DISPLAY environment variable needs to be set for this to happen and X-windows security must allow the access. Use of this command may correct that: 
    xhost +local:

Rerunning bootstrap.py

With gsas2full-Latest-Linux-x86_64.sh and the conda gsas2pkg installers from January 2021 and later, the installer creates file <condapath>/start_G2_bootstrap.sh which can be run in bash to launch the bootstrap process. Otherwise a command like this is needed: 

~/g2full/bin/python ~/g2full/GSASII/bootstrap.py

changing the prefix ~/g2full/ to reflect your choice for <condapath>.

Running the bootstrap.py file should update GSAS-II to the latest version and complete any remaining installation steps and will. Note that this script requests the name of a proxy server. For most people, none is needed and they should simply use the the default by pressing return. However, some sites block web traffic unless it is passed through a particular computer. If needed, enter that computer name or IP address here (e.g. proxyout.lanl.gov); you will be then be requested to also supply a port number, which defaults to 8080. If you are able to download files but updates fail, see the discussion of web proxies.

Last modified 8 months ago Last modified on Aug 15, 2024 11:40:00 AM