MSEL, NIST Center for Neutron Research Materials Science and Engineering Laboratory NIST Center for Neutron Research National Institute of Standards and Technology
Home Instruments Science Experiments SiteMap
EXPGUI home


Installing GSAS/EXPGUI under Mac OS X

This page contains information on installing and running GSAS & EXPGUI on Macintosh OS X computers. The software has been built using OS X 10.2.8 and has been installed successfully on 10.2 and 10.3 machines.

Installation

New! Installation has been dramatically simplified. You may still want to install the development environment (XCODE) and Fink, but these are no longer required to install and run GSAS and EXPGUI. GSAS & EXPGUI now contains a copy of the Tcl/Tk package (that includes BLT), so installation of this package is also now optional.

  1. Install X11
    Before you can run the GSAS package (or, for that matter, a large number of other Unix-derived graphics applications), you need to load the X Windows system (X11) onto your computer.

    For 10.2 (Jaguar), this is a bit complex to explain, so you will need to do some searching on the web, find a guru or consult one of the many Mac OS X books that cover this subject.

    For 10.3 (Panther), Apple bundles a version of X11 with the OS and installing can be very simple. It can be installed directly from CD-ROM #3 of the OS X distribution CD disks. To install X11, insert CDROM #3, then click on the Packages folder and within that folder, click on X11User.pkg. Read the installation screens, click on the "next" button a few times, and X11 is installed.

    X11 for 10.3 can also be downloaded (43 Mb!) from Apple (http://www.apple.com/support/downloads/x11formacosx.html).

    If you have a PowerBook that shipped with 10.3, you may have your OS X distribution on two DVDs, so you don't have CDROM #3. While Apple technical support does not appear to know this (or at least they did not, when I called), I found the X11 package in a folder hidden on the DVD. Use the finder Go/"Go to folder" (shift-command-G) menu item to open hidden folder /Volumes/PowerBook Software/System on the first Powerbook software DVD; then double-click on the Installation folder to open it and then open the Packages folder. (Yes, you could have typed /Volumes/PowerBook Software/System/Installation/Packages, but why buy a Mac if you like to type long names?). Finally, double-click on the X11User.pkg file and X11 is installed. Just like that!

    For people who do like the command line, typing this works too:

         find /Volumes  -name "X11User.pkg"
    
    You can then copy the file to some place that is easy to access (like the desktop) so that it is easy to click on with a command like this:
        cp "/Volumes/PowerBook Software/System/Installation/Packages/X11User.pkg" ~/Desktop/
    

  2. Download the GSAS & EXPGUI programs as a Mac disk image.
    Download this file from the NIST website:
    ftp://ftp.ncnr.nist.gov/pub/cryst/gsas/osx_gsasexpgui.dmg (~13 Mb)
    This file can also be downloaded from the CCP14 mirrors: [(UK), (Canada), (US) or (Australia)].

    Mount this file by double-clicking on it. This should create a new volume in your top-level ("Computer") called "GSASvol"; clicking on this device will open a finder window with a single folder ("gsas") present. (Note that some browsers will automatically perform this step for you.)

    While you can run GSAS & EXPGUI from this location, you are strongly suggested to instead copy the entire package to your computer by dragging the gsas folder icon to another finder window, or by clicking on it and using Copy and Paste.

  3. Install a "shortcut" to launch EXPGUI
    EXPGUI AppleScript icon The OS X version of GSAS & EXPGUI has an EXPGUI AppleScript application named expgui.app in the gsas folder with the icon shown to the right. This AppleScript will start X11, if needed and then lauch EXPGUI. (If you have ideas for improving the script, the code can be found in file expgui_applescript.txt.) The EXPGUI AppleScript can be used in three ways:

    • Double-clicking on the icon will launch EXPGUI so that it starts with the "file open" window in your home directory. This window can then be used to navigate to access/create experiments in other folders.

    • Dropping one or more GSAS Experiment (.EXP) files onto the EXPGUI icon will cause the experiment files to be opened. If more than one file is dropped, each file will open in a separate EXPGUI session.

    • Dropping one or more folders onto the EXPGUI icon will cause EXPGUI to be started with the "file open" window in that folder.

    If you will use GSAS a fair amount, you will likely find it convenient to drag the EXPGUI icon to the dock for easy access.

    Note, that this EXPGUI app will not work correctly if copied or moved to another folder. It must be located in the gsas folder along with all the other files and subdirectories needed by GSAS & EXPGUI -- you can instead create an alias (by highlighting the AppleScript icon in the Finder and using the File/"Make alias" menu item or the Command-L shortcut). An alias created in this fashion can be moved wherever desired -- for example, to the desktop or to the Application folder.

  4. For Unix power users: Make a command line shortcut (optional)
    People who have not become completely enlighted to the Mac may wish to set up a way to type something (gasp!) in a terminal window that will allow them to start EXPGUI. There are a number of ways this can be done, (see section 2.2 in the Unix installation notes.) Also, on the Mac it is possible to add applications to the X11 Applications menu, by using the Applications/Customize menu option. Note that the command used to start Tcl/Tk and EXPGUI will vary depending on where you installed the package. I install the package in ~/Applications so the command string to start EXPGUI using:
              ~/Applications/gsas/ncnrpack-osx  ~/Applications/gsas/expgui/expgui
    


EXPGUI Enhancements specific to the Mac

EXPGUI will automatically designate the EXPGUI AppleScript as the "open with" application for every GSAS experiment (.EXP) file that is read or written by EXPGUI. This is done with the Development Tools program Rez, found in /Developer/Tools or in the gsas folder. At the same time, EXPGUI will also set an icon for the .EXP file. After this has been done, EXPGUI can be invoked by simply double-clicking on a GSAS experiment file (.EXP file) icon.

If for some reason you would prefer this not be done (I would be interested to hear why) -- deselect the "Assign app to .EXP files" checkbox in the Options menu.



Mac ideosyncracies

Unlike in the Windows & Unix versions of GSAS, Mac windows may not be updated until they are brought to the top of the screen by clicking on them (given focus). This is most noticible for PGPLOT graphics (in POWPLOT, RAWPLOT,...). When you type graphics commands in a terminal window, the plot does not appear to change. However, click on the PGPLOT's window bar and the plot will update.



The Tcl/Tk Starkit

The GSAS-EXPGUI distribution now includes a single file version of the entire Tcl/Tk package, as well as a graphics package for Tcl/Tk, called BLT, that is used extensively within EXPGUI. The inclusion of this file within the package simplifies installation considerably. This single 3 Mb file, gsas/ncnrpack_osx, contains many other Tcl/Tk packages (that are not used within EXPGUI) and may be of value for use with other applications. Note that the EXPGUI AppleScript will look for Tcl/Tk first as the ncnrpack_osx file in the same folder as where the expgui.app script is located. If this ncnrpack_osx file is deleted, renamed or moved, then the script will look for the standard Tcl/Tk program (wish) in the /sw/bin directory.



Problems

If you cannot get EXPGUI or the GSAS graphics programs to work, you may have a setup problem with X-windows (X11). One common reason for this is that X11 must be restarted any time your computer's hostname changes, which may be caused by starting/stopping networking, dialing in for e-mail or even by a change in IP address initiated by the network DHCP server, if you are hardwired into a network. If exiting and restarting X11 does not address your problem, the following paragraphs may help you diagnose problems.
  1. One possible problem is the definition for the X11 display (shell environment variable DISPLAY). On my machine, this variable seems to be set correctly in X11 xterm windows, but is not set by default within an Aqua terminal window unless you make changes to your shell startup.

    A quick test for X11 problems is to type xclock at the shell prompt:

         bash-2.05a$ xclock
    
    If you get a clock display -- great, X windows is working!

    If you get the following error message the DISPLAY variable is not set:

         bash-2.05a$ xclock
         Error: Can't open display: 
    
    If on the other hand, you get this error message, there is a security problem with X windows:
         bash-2.05a$ xclock
         Error: Can't open display: localhost:0.0
    
    This will most likely be solved by exiting and restarting X11 (see above).

    You can set the DISPLAY variable in bash/zsh, etc. using:

         bash-2.05a$ export DISPLAY=localhost:0.0
    
    or in csh/tcsh, etc. using:
         [d120234:~] toby% setenv DISPLAY localhost:0.0
    
    (For info on how to do this automatically, see step 2 in http://www.chemistry.ucsc.edu/~wgscott/xtal/page1.html).

  2. A second possible problem relates to the installation of the Tcl/Tk and BLT packages. This problem seems unlikely, now that the Tcl/Tk package is included in the distribution, but if you have removed the ncnrpack_osx file from the gsas folder, the expgui.app AppleScript will try to use wish installed in /sw/bin. If you are choosing to do this, you can test if Tcl/Tk and the BLT package are installed correctly using the following commands:
         [d120234:~] toby% wish
         % package require BLT
         2.4
         % pack [blt::graph .g]
         % exit
    
    When you type "wish" and press Enter, a new small blank window should appear. when you type the 2nd line, "package require BLT," there will be no change in the blank window, but the computer should respond "2.4". After the "pack [blt::graph .g]" command is entered, a set of x- and y-axes should appear in this window. The window should disappear after "exit" is typed.


The EXPGUI icon, the original version of the EXPGUI AppleScript and help with this documentation was provided by Francois Farges -- many thanks!

Thanks to Paul Kienzle of the NCNR DAVE project for providing the "all in one file" (starkit) version of Tcl/Tk for OS X.

GSAS is Copyright, 1984-2000, by the Regents of the University of California. The GSAS software was produced under a U.S. Government contract (W-7405-ENG-36) by the Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Permission is granted to the public to copy and use this software without charge, provided that this notice and any statement of authorship are reproduced on all copies. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software.

The author of EXPGUI is a U.S. Government employee which means that EXPGUI is not subject to copyright. Have fun with it. Modify it. Please write new sections and make them available to the rest of the world.

Neither the U.S. Government nor any author makes any warranty, expressed or implied, or assumes any liability or responsibility for the use of this information or the software described here. Brand names cited herein are used for identification purposes and do not constitute an endorsement by NIST.


Questions/Problems: crystal@nist.gov
$Revision: 1.7 $ $Date: 2005/09/07 21:16:07 $