BBP on OS X Guide 16 5

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 later version (Yosemite (OS X 10.10), El Capitan (OS X 10.11.0)) 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 key Mac OS X-specific issues include:

1. Mac must have a gcc compiler environment, and the Mac command line tools, obtained through the Xcode software distribution available through the Mac App store.
2. Mac must have a gcc fortran compiler installed, which is not available in the Mac Xcode distribution. We recommend use of a gnu Mac binary distribution of gfortan.
3. Mac must have a full Python installation that includes NumPy, SciPy, matplotlib and other packages. We recommend use of a free commercial Python distribution called Anaconda, that includes all these required python libraries.
4. Mac must have specialized Python language geographic project module, called pyproj, installed. The required pyproj can be installed using anaconda package update tool.
5. The current SDSU BBToolbox software is not compatible with the Mac environment. The code will crash and as a result the SDSU method will not be tested by the 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.

Installing the BBP Platform v16.5.0 on OS X 10.11.5 (El Capitan)

This section describes the installation of the BBP 16.5.0 distribution on Mac OS X system. The following steps were tested on a Macbook Pro running Mac OS 10.11.5 (El Capitan).

The steps below will guide you through installation of the necessary C/Fortran GNU compilers in addition to the Python packages required by the Broadband Platform. At the end of this section, we provide information about running the Unit and Acceptance Tests available on the Broadband Platform, along with some Mac OS X-specific details.

The following steps will install the BBP v16.5.0 installation on a Mac running a new, default, installation of OS 10.11.5 (El Capitan). Some of these steps may not be required if you have already added compilers, or other libraries, to your Mac.

1. Install Xcode from the Mac App Store.
2. Install the Xcode command line tools.
3. Install a gfortan compiler from the gnu site.
4. Install a collection of python libraries using the Continuum anaconda distribution.
5. Update a python library, called pyproj, using the condo install command.
6. Install the Broadband Platform software and required libraries using the BBP easy install script.
7. Update the .bash_profile in your user account
8. Run the unit tests and acceptance tests to esure the platform is working properly on your Mac.
9. Use the Broadband Platform for your research purposes.

Step-by-Step Installation of BBP v16.50 on OS X 10.11.5 (El Capitan)

The following sections provide a step-by-step process for installing Broadband Platform v16.5.0 on Mac OS 10.11.5 (El Capitan). Several steps, including the installation of the Xcode compilers (gcc) and the fortran compilers (fortran) require administrator access on the Mac. These instruction assume the account you are using has administrator privileged. If your Mac account does not have administrator privileges, you will need to modify some of the commands to include "sudo" commands. Those are not included here.

1. Install Xcode from the Mac App Store

Mac OS does not ship with compilers. However, the Mac App store provides a software distribution called Xcode that include current gcc compilers, and other tools, such as makefile system needed to build the BBP Platform. To download and install the Xcode distribution, you will need to go to the Mac App store, find the Xcode software, and install it on your Mac. This will required an Apple ID (free) and administrator privileges on your Mac.

Xcode is listed in the Mac App store under "developer tools". The current version that we tested with, as of May 2016 is Version 7.3.1 Please following apple instruction for downloading and installing the Xcode software. You will need to agree to apple licenses. Once the Xcode is installed, you should open a Terminal window on your Mac and confirm the gcc compilers are installed and work by invoking the gcc compiler. You should see something like the following:

scecadms-MacBook-Pro-2:~ maechlin$ gcc -v Using built-in specs. COLLECT_GCC=gcc COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/x86_64-apple-darwin14.0.0/4.9.2/lto-wrapper Target: x86_64-apple-darwin14.0.0 Configured with: ../gcc-4.9-20141029/configure --enable-languages=c++,fortran Thread model: posix gcc version 4.9.2 20141029 (prerelease) (GCC)

2. Install the Xcode command line tools.

Not all required software tools are included in the default Xcode installation. To update the Xcode installation with the additional "command line" tools needed by the Broadband Platform type the following:

3. Install Fortran Compiler

https://gcc.gnu.org/wiki/GFortranBinaries#MacOS

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.

1. Accept Xcode license by typing:
   $ sudo xcodebuild -license
   Scroll to the end and then type 'agree'.
2. 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
3. Install GCC 4.9 using the following command:
   $ sudo port install gcc49
4. Select the new compiler as the default compiler using the command:
   $ sudo port select gcc mp-gcc49
5. Install the PIP package manager for Python, using the command:
   $ sudo easy_install pip
6. Install PyProj, using the command:
   $ sudo pip install pyproj
7. Compile the Broadband Platform by going into the src directory and typing "make"
8. Continue the Installation Instructions on Broadband User Guide v16.5.0

Running Unit Tests

In order to run the unit tests, users should go to the tests directory and type:

$ ./UnitTests.py

The tests should begin and will take between 30-60 minutes to run, depending on your computer speed. At the end of each test, a "ok" should be printed if the test was successful. At the end, the program will print the number of tests that passed and the number of tests that failed. If a test has failed, first check that you have built the executables.You can rerun just the specific test that failed (test_<module>.py). If the test is still failing, also verify that you have the ref_data directory, since it contains the input and reference files. If you're looking for more information about the failure, you can consult the Unit Tests log file in $BBP_DATA_DIR/logs/unit_tests.log . If you can't determine the reason for the failure, contact support.

Please note that one of the SDSU components, BBToolbox, does not pass its Unit Test when running on a Mac OS X system and will be skipped when tests are executed on a Mac. This is a known limitation of the current BBP release. This reduces the available number of ground motion methods that can be run on the Mac. On Linux, there are six methods available (GP, SDSU, UCSB, EXSIM, SONG, CSM). On a Mac, there are five methods available (GP, UCSB, EXSIM, SONG, CSM).

After running the unit tests, users can proceed to the acceptance tests below.

Running Acceptance Tests

To run the acceptance tests, users should:

$ ./AcceptTests.py

There will be one test for each method in the platform, for both the validation mode (historical events) and the scenario modes (hypotethical earthquakes). These tests will take somewhere between 2 and 3 hours to run, depending on how fast the computer is.

Since the acceptance tests can take a long time to run, you may wish to resume where you left off. This feature is supported automatically. If you do not wish to resume, delete the resume file in $BBP_DATA_DIR/logs/resume.txt. If there are any failure or errors while running the acceptance tests, consult the Troubleshooting section at the end of this user guide for known issues and their solutions.

When they're complete, the console will either print "OK" or how many tests failed. Acceptance test failures indicate that the modules are not integrated correctly. On Mac OS X, the SDSU codebase is not yet fully supported and will cause the 3 SDSU acceptance tests to fail. These tests will be automatically skipped by the Platform when Acceptance Tests are executed on a Mac OS X computer. For the other tests, if a certain acceptance test fails, you can get more information by consulting the acceptance test logs in $BBP_DATA_DIR/logs/acceptance_test_logs/<test that failed>.log. If you can't determine the reason for the failure, contact support.

Here's the expected output when running on a Mac OS X, showing the three SDSU tests failing (which is expected for this release):

-bash-4.1$ ./AcceptTests.py 
Number of tests to run: 11
test_user-CSM (__main__.BBP2G_Acceptance_Tests) ... ok
test_user-EXSIM (__main__.BBP2G_Acceptance_Tests) ... ok
test_user-GP (__main__.BBP2G_Acceptance_Tests) ... ok
test_user-SONG (__main__.BBP2G_Acceptance_Tests) ... ok
test_user-UCSB (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-CSM (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-EXSIM (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-GP (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-GP_seis (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-SONG (__main__.BBP2G_Acceptance_Tests) ... ok
test_valid-northridge-UCSB (__main__.BBP2G_Acceptance_Tests) ... ok

----------------------------------------------------------------------
Ran 11 tests in 3647.739s

Potential Additional Steps

One developer needed to run the following commands to make the Mac installation work. These are not needed on a clean installation but could be required to repair or upgrade an existing Mac OS X setup.

• 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

• Broadband Platform
• Broadband User Guide v16.5.0
• CME Project