BBP on OS X Guide

From SCECpedia
Jump to navigationJump to search

Introduction

The Broadband Platform is compatible with Linux as well as OS X. However, due to some recent changes that Apple has made to their Xcode development tools, users on Mavericks (OS X 10.9) and Yosemite (OS X 10.10) will need to follow some additional steps to make the installation work. There are several installation issues or limitations related to the BBP on a Mac. The primary target operating system for BBP is Linux. Mac's OS is somewhat different environment, so installation on a Mac is a bit more complex.

The key Mac OS X-specific issues include:

  • Mac must have a full Python installation that includes NumPy, SciPy, matplotlib and other packages
  • Mac must have a gcc compiler environment, obtained through the XCODE software
  • Mac must have a gcc fortran compiler installed, not available in XCODE. If you follow the instructions given in the Mac Ports section below, it will required administrator account privileges because these will be required to install the fortran compiler in the default location.
  • Mac must have specialized Python language geographic project module pyproj installed
  • Currently, the SDSU BBToolbox software is not compatible with the Mac environment. The code will crash and as a result the SDSU method does not pass all Unit tests when compiled on a Mac. This is a known, Mac-specific issue. The SDSU method passes all tests in the target Linux environment. We will provide a resolution to this know limitation of the Mac-version of the BBP, as soon as one is available.

Method 1: Installation using Mac Ports

This method uses Mac Ports, a software tool designed help install software on a Mac. The steps below describe alternative way to install the BBP on a Mac running Mac OS X Mavericks and Yosemite. Mac Ports helps you install all the needed Python and GNU packages on your Mac. Please note that you only need to follow on of the methods. If you decide to use Method 1: Mac Ports, you do not need to do anything in Method 2 and vice-versa.

OS X 10.9 Mavericks using MacPorts

Installing OS X on Mavericks is possible by following these steps:

  1. Install Xcode from the Mac App Store
  2. Install the Xcode command line tools. To do this, in your Terminal window, please type:
    $ sudo xcode-select --install
    A dialog box will pop-up asking if you want to install the command line tools. Please choose "OK" on this box.
  3. Accept Xcode license by typing:
    $ sudo xcodebuild -license
    Scroll to the end and then type 'agree'.
  4. Then install MacPorts from http://www.macports.org. MacPorts helps install the requirements to compile the Broadband Platform. The version of MacPorts we used was 2.3.3.
  5. Install GCC 4.8 using the following command:
    $ sudo port install gcc48
  6. ​​​​ Select the new compiler as the default compiler using the command:
    $ sudo port select gcc mp-gcc48
  7. Install the PIP package manager for Python, using the command:
    $ sudo easy_install pip
  8. Install PyProj, using the command:
    $ sudo pip install pyproj
  9. Compile the Broadband Platform by going into the src directory and typing "make"

OS X 10.10 Yosemite using MacPorts

In order to install the Broadband Platform on Yosemite, you must follow these steps:

  1. Install Xcode from the Mac App Store
  2. Install the Xcode command line tools. To do this, in your Terminal window, please type:
    $ sudo xcode-select --install
    A dialog box will pop-up asking if you want to install the command line tools. Please choose "OK" on this box.
  3. Accept Xcode license by typing:
    $ sudo xcodebuild -license
    Scroll to the end and then type 'agree'.
  4. Then install MacPorts from http://www.macports.org. MacPorts helps install the requirements to compile the Broadband Platform. The version of MacPorts we used was 2.3.3, please make sure you select the package for OS X 10.10 Yosemite
  5. Install GCC 4.9 using the following command:
    $ sudo port install gcc49
  6. Select the new compiler as the default compiler using the command:
    $ sudo port select gcc mp-gcc49
  7. Install the PIP package manager for Python, using the command:
    $ sudo easy_install pip
  8. Install PyProj, using the command:
    $ sudo pip install pyproj
  9. Compile the Broadband Platform by going into the src directory and typing "make"

Method 2: Installation Without Mac Ports

This method does not require the use of Mac Ports. If you use the steps below, you don't need to follow the steps for the Method 1 above.

Installation on Mac Yosemite

The following section describes one developers experiences installing Broadband Platform on their Mac running Yosemite OS. Here is the list of steps that we went through to successfully install and run BBP v15.3 on a Macbook Pro with 16GB Ram and 10GB of disk space running OS X v10.10.3 (Yosemite).

  1. The default Mac python does not include all the required scientific python modules. For a well-integrated collection of scientific python modules for a Mac, we installed anaconda python:
  2. Evaluate the Mac command line environment. Bring up terminal, and run "env" and "which python":
    $ env
TERM_PROGRAM=Apple_Terminal
SHELL=/bin/bash
TERM=xterm-256color
TERM_PROGRAM_VERSION=343.7
TERM_SESSION_ID=177D5090-D37D-4EFD-998D-9290C7DD789B
USER=maechlin
PATH=/Users/maechlin/anaconda/bin:/opt/local/gmt/bin:/usr/local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/bin
PWD=/Users/maechlin
LANG=en_US.UTF-8
XPC_FLAGS=0x0
XPC_SERVICE_NAME=0
SHLVL=1
HOME=/Users/maechlin
PYTHONPATH=/Users/maechlin/anaconda/lib

and

$ which python
/Users/maechlin/anaconda/bin/python
  3. Download the minimum set of required BBP files (6 file required currently) from the BBP web site:
    • bbp-dist-15.3.0.tar.gz
    • bbp-dist-15.3.0.tar.gz.md5
    • labasin-velocity-model-15.3.0.tar.gz
    • labasin-velocity-model-15.3.0.tar.gz.md5
    • northridge-validation-15.3.0.tar.gz
    • northridge-validation-15.3.0.tar.gz.md5
  4. MD5 checksum is different on Mac than on Linux. Here's a way to do md5 sum check like this on a Mac:
    $ cat bbp-dist-15.3.0.tar.gz.md5
24d88c5a22543409e89a22d64b451f85  bbp-dist-15.3.0.tar.gz
$ md5 bbp-dist-15.3.0.tar.gz
MD5 (bbp-dist-15.3.0.tar.gz) = 24d88c5a22543409e89a22d64b451f85

$ cat labasin-velocity-model-15.3.0.tar.gz.md5
f24dc01a6b1bf533b83067fbaa75c9d3  labasin-velocity-model-15.3.0.tar.gz
$ md5 labasin-velocity-model-15.3.0.tar.gz
MD5 (labasin-velocity-model-15.3.0.tar.gz) = f24dc01a6b1bf533b83067fbaa75c9d3

$ cat northridge-validation-15.3.0.tar.gz.md5
d4f396be3b29082841ddd4622f39cabb  northridge-validation-15.3.0.tar.gz
$ md5 northridge-validation-15.3.0.tar.gz
MD5 (northridge-validation-15.3.0.tar.gz) = d4f396be3b29082841ddd4622f39cab
  5. Check Xcode on Mac Yosemite. You should have Xcode Version 6.3
  6. Check on Mac Python installation. Use anaconda because it includes many of the packages, such as numpy and matplotlib that are required by the BBP. Also, this version can be installed without root access, which I did in my Mac account user Maechlin
  7. At command line which gcc, gcc -v
    $ which gcc
/usr/bin/gcc

$ gcc -v
Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 6.1.0 (clang-602.0.49) (based on LLVM 3.6.0svn)
Target: x86_64-apple-darwin14.3.0
Thread model: posix
  8. A BBP Issue is that Xcode does not install a gcc fortran compiler. Details to install fortran: Download the gcc compiler for Yosemite to the downloads direction. Then run as sudo to install gcc and gfortran.
    gunzip gcc-4.9-bin.tar.gz
sudo tar xvf gcc-4.9-bin.tar -C /
    This installs things in root, in /usr/local/…
  9. Create the data structure defined in the installation guide.
    /Users/Maechlin/Documents/dev/bbp_2015/15.3.0
../bbp_gf
../bbp_val
../bbp_data
  10. Now, in the BBP src directory, type make and everything should build without error.
  11. At this stage, the compiled BBP code has been built. However, we have not confirmed that the Python environment has been setup correctly. We can test the installation by running the unit tests. When we do, the ./UnitTests.py command fails, and we get an error message saying that Python is unable to find pyproj
  12. Install pyproj Go to pyproj, download, build and install
    python setup.py build 
python setup.py install (with sudo if necessary).

    To test, run python -c "import pyproj; pyproj.test()"

  13. Now ./UnitTests.py gives deprecation warnings, and one of the UnitTests fails on a Mac. This reduces the available number of ground motion methods that can be run on the Mac. On Linux, there are five methods available (GP, SDSU, UCSB, EXSIM, CSM). On a Mac, there are four methods available (GP, UCSB, EXSIM, CSM).
    $ ./UnitTests.py
/Users/maechlin/anaconda/lib/python2.7/site-packages/matplotlib/cbook.py:137: MatplotlibDeprecationWarning: The matplotlib.mpl module was  deprecated in version 1.3. Use `import matplotlib as mpl` instead.
warnings.warn(message, mplDeprecation, stacklevel=1)
test_runprog (test_bband_utils.Test_bband_utils) ... ok
test_runprog2 (test_bband_utils.Test_bband_utils) ... ok
test_runprog3 (test_bband_utils.Test_bband_utils) ... ok
test_execute_platform_bbp (test_python_code.Test_PythonCode) ... /Users/maechlin/anaconda/lib/python2.7/site-packages/matplotlib/cbook.py:137:   MatplotlibDeprecationWarning: The matplotlib.mpl module was deprecated in version 1.3. Use `import matplotlib as mpl` instead.
warnings.warn(message, mplDeprecation, stacklevel=1)
ok
test_bbtoolbox (test_bbtoolbox.Test_BBToolbox) ... /bin/sh: line 1:  6027 Abort trap: 6           /Users/maechlin/Documents/dev/bbp_2015/15.3.0/bbp/src/sdsu/bin/BBtoolbox.exe < /Users/maechlin/Documents/dev/bbp_2015/bbp_data/tmpdata/9642805/bbtoolbox_test_stat/parfilename_test_stat >> /Users/maechlin/Documents/dev/bbp_2015/bbp_data/logs/9642805/9642805.bbtoolbox_test_stat.log 2>&1

    The BBToolbox does not pass its unit test, but this is a known limitation of the BBP installation. At the end of the tests, the BBP will print the following message: 

    ERROR
test_amp_fac (test_amp_fac.Test_Amp_Fac) ... ok
Ran 26 tests in 1171.378s

FAILED (errors=1)
    Once your Mac can successfully complete 25 of the 26 Unit tests, you are ready to run the acceptance tests. Now, you can refer to the material in the main BBP Users Guide, describing how to run the acceptance tests to confirm that for of the methods pass their acceptance tests. Once these methods pass their acceptance tests, they can be used for engineering and research purposes. These tests take overnight to run. At the end, however, you should receive a message like this:
    
TBD
    At this point, the BBP is ready for use on the Mac. We do not recommend us of the SDSU method on a Mac. However, the other methods work as expected on a Mac, produce results equivalent to a Linux installation.

Potential Additional Steps

One developer needed to run these commands to make the Mac installation work:

  • export PYTHONPATH=/Library/Python/2.7/site-packages/:$PYTHONPATH
  • sudo pip install scipy --upgrade
  • sudo pip install numpy --upgrade
  • sudo pip install matplotlib --upgrade

Related Entries

Retrieved from "https://strike.scec.org/scecwiki/index.php?title=BBP_on_OS_X_Guide&oldid=13292"