Difference between revisions of "BBP on OS X Guide 16 5"

From SCECpedia
Jump to navigationJump to search
 
(19 intermediate revisions by 2 users not shown)
Line 4: Line 4:
  
 
The key Mac OS X-specific issues include:
 
The key Mac OS X-specific issues include:
 +
#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.
 +
#Mac must have a gfortran compiler installed, which is not available in the Mac Xcode distribution. We recommend use of a gnu Mac binary distribution of gfortran.
 +
#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.
 +
#Mac must have specialized Python language geographic project module, called pyproj, installed. The required pyproj can be installed using the Anaconda package update tool.
 +
#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.
  
−
#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.
+
== Installing BBP v16.5.0 on Mac OS X 10.11.5 (El Capitan) ==
−
#Mac must have a gcc compiler environment, obtained through the XCODE software
+
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).  
−
#Mac must have a gcc fortran compiler installed, not available in XCODE. We recommend use of a gnu Mac binary distribution of gfortan.
 
−
#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 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.
 
  
−
== BBP 16.5.0 Installation on Mac OS X ==
+
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.
  
−
This section describes the installation of the BBP 16.5.0 distribution on Mac OS X using a package management tool called Mac Ports. Mac Ports simplifies the installation process by automating several of the installation steps, but it will require administrator access unless you want to install it from the source (a few extra steps that we will not cover in this guide). If you prefer not to use Mac Ports in order to have greater flexibility in selecting the packages you would like to install, you can follow the directions provided by one developer who installed BBP 16.5.0 on his Mac OS X laptop without using Mac Ports. Details are provided in the [[BBP_on_OS_X_Guide_Without_Mac_Ports]] page.
+
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.
  
−
The steps below will guide you through the installation of Mac Ports and 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.
+
# Install Xcode from the Mac App Store.
 +
# Install the Xcode command line tools.
 +
# Install a gfortran compiler from the gnu site.
 +
# Install a collection of Python libraries using the Continuum Anaconda distribution.
 +
# Update a Python library, called pyproj, using Anaconda's conda install command.
 +
# Install the Broadband Platform software and required libraries using the BBP easy install script.
 +
# Update the .bash_profile in your user account
 +
# Run the unit tests and acceptance tests to ensure the platform is working properly on your Mac.
 +
# Use the Broadband Platform for your research purposes.
  
−
=== OS X 10.9 Mavericks using MacPorts ===
+
== Step-by-Step Installation of BBP v16.50 on Mac OS  ==
 +
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 (gfortran) require administrator access on the Mac. These instruction assume the account you are using has administrator privileges. 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.
  
−
Installing OS X on Mavericks is possible by following these steps:
+
== 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.
  
−
# Install Xcode from the Mac App Store
+
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.  
−
# Install the Xcode command line tools. To do this, in your Terminal window, please type:<br />$ sudo xcode-select --install<br />A dialog box will pop-up asking if you want to install the command line tools. Please choose "OK" on this box.
 
−
# Accept Xcode license by typing:<br />$ sudo xcodebuild -license<br />Scroll to the end and then type 'agree'.
 
−
# 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 install the package for OS X 10.9 Mavericks
 
−
# Install GCC 4.8 using the following command:<br />$ sudo port install gcc48
 
−
#​​​​ Select the new compiler as the default compiler using the command:<br />$ sudo port select gcc mp-gcc48
 
−
# Install the PIP package manager for Python, using the command:<br />$ sudo easy_install pip
 
−
# Install PyProj, using the command: <br />$ sudo pip install pyproj
 
−
# Compile the Broadband Platform by going into the src directory and typing "make"
 
−
# Continue the Installation Instructions on [[Broadband_User_Guide_v16.5.0#User_Account_Setup|Broadband User Guide v16.5.0]]
 
  
−
=== OS X 10.10 Yosemite using MacPorts ===
+
Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal)
  
−
In order to install the Broadband Platform on Yosemite, you must follow these steps:
+
If you type gcc -v in the terminal window, you should see something like the following:
  
−
# Install Xcode from the Mac App Store
+
$ gcc -v
−
# Install the Xcode command line tools. To do this, in your Terminal window, please type:<br />$ sudo xcode-select --install<br />A dialog box will pop-up asking if you want to install the command line tools. Please choose "OK" on this box.
+
Using built-in specs.
−
# Accept Xcode license by typing:<br />$ sudo xcodebuild -license<br />Scroll to the end and then type 'agree'.
+
COLLECT_GCC=gcc
−
# 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
+
COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/x86_64-apple-darwin14.0.0/4.9.2/lto-wrapper
−
# Install GCC 4.9 using the following command: <br />$ sudo port install gcc49
+
Target: x86_64-apple-darwin14.0.0
−
# Select the new compiler as the default compiler using the command:<br />$ sudo port select gcc mp-gcc49
+
Configured with: ../gcc-4.9-20141029/configure --enable-languages=c++,fortran
−
# Install the PIP package manager for Python, using the command:<br />$ sudo easy_install pip
+
Thread model: posix
−
# Install PyProj, using the command: <br />$ sudo pip install pyproj
+
gcc version 4.9.2 20141029 (prerelease) (GCC)
−
# Compile the Broadband Platform by going into the src directory and typing "make"
 
−
# Continue the Installation Instructions on [[Broadband_User_Guide_v16.5.0#User_Account_Setup|Broadband User Guide v16.5.0]]
 
  
−
=== Unit and Acceptance Tests for Mac OS X ===
+
== 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 (free) needed by the Broadband Platform type the following:
  
−
==== Running Unit Tests ====
+
Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal)
 +
Type xcode-select --install and respond to the the dialogs that open. These dialogs may ask you to agree to the apple license.
  
−
In order to run the unit tests, users should go to the tests directory and type:
+
== Install Fortran Compiler ==
 +
Xcode does not include a fortran compiler which is required by the BBP platform software. We recommend that you download a Mac binary installation of the GFortran compiler from the GNU web site (free).
  
−
$ ./UnitTests.py
+
Selest the appropriate version of the Mac Fortran compiler from the following gnu website:
 +
*[https://gcc.gnu.org/wiki/GFortranBinaries#MacOS Mac OS GFORTRAN distributions]
  
−
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
+
It should be possible to install the fortran from the gnu source code, but we have not tested this approach.
−
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 [mailto:software@scec.org 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).
+
Once fortran is installed, you should open a terminal window, and type gfortran -v to verify the compiler is installed and working.
 +
To do this, in your Terminal window, if should look something like this
  
−
After running the unit tests, users can proceed to the acceptance tests below.
+
$ gfortran -v
 +
Using built-in specs.
 +
COLLECT_GCC=gfortran
 +
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)
  
−
==== Running Acceptance Tests ====
+
== Install Python 2.7 Distribution ==
 +
The BBP v16.5.0 requires Python v2.7+ and several optional python libraries. It is possible to collect all necessary Python libraries, but we recommend using a Python distribution that includes nearly all the required libraries. We recommend use of the Continuum Anaconda Python distribution (free).
  
−
To run the acceptance tests, users should:
+
Go to the Continuum Anaconda download site, and download the Python 2.7 command line distribution tool (free).
 +
*[https://www.continuum.io/downloads#_macosx Continuum Anaconda Python for Mac]
  
−
  $ ./AcceptTests.py
+
Once this is downloaded, run the installer by typing:
 +
  % bash Anaconda2-4.0.0-MacOSX-x86_64.sh
  
−
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.
+
It will ask you to agree to the license, and then install a current version of Python 2.7 and most of the Python libraries required by the BBP v16.5.0. Anaconda Python can be installed in your user directory and does not require administrator privileges.
  
−
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.
+
The end of the installation process will update your .bash_profile to put the Anaconda Python into your default path. We tested using the Anaconda version given above, and it worked with BBP v16.5.0
  
−
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 [mailto:software@scec.org support].
+
== Update the PyProj library in Anaconda Python ==
 +
One Python package that must be updated to in the pyproj library. Use the Anaconda update tool. Open a terminal window and type:
  
−
Here's the expected output when running on a Mac OS X, showing the three SDSU tests failing (which is expected for this release):
+
% conda install pyproj
  
−
-bash-4.1$ ./AcceptTests.py
+
The conda installer program will run, and it will identify what needs to be installed, or updated. When it asks for approval to proceed, enter yes.
−
Number of tests to run: 11
+
Pyproj will be added/updated to your Mac.
−
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
 
  
−
----------------------------------------------------------------------
+
== Install the Broadband Platform using the Easy Install Script ==
−
Ran 11 tests in 3647.739s
+
At this point, your Mac has all the software tools needed to install, compile and run the Broadband Platform. Please return to the Broadband Users Guide and follow the easy install instructions. Continue the installation instructions at [[Broadband_User_Guide_v16.5.0#Broadband_Platform_Easy_Installation|Broadband Platform Easy Installation]]
−
 
−
== 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.
+
Once the easy install process completes, users should run the Unit Tests and Acceptance tests to ensure the BBP v16.5.0 is installed and operating properly on your Mac, following instructions given on [[Broadband_User_Guide_v16.5.0#Running_the_Tests]]. When the Unit Tests and Acceptance tests pass on your computer, it provides evidence that the platform is properly installed and is producing results equivalent to the released version used for SCEC research purposes.
  
−
* export PYTHONPATH=/Library/Python/2.7/site-packages/:$PYTHONPATH
+
Additional information about the installation process is included on the [[Broadband_Platform_Manual_Installation_16_5_0|Broadband Platform Manual Installation]] page.
−
* sudo pip install scipy --upgrade
 
−
* sudo pip install numpy --upgrade
 
−
* sudo pip install matplotlib --upgrade
 
  
 
== Related Entries ==
 
== Related Entries ==
 
*[[Broadband Platform]]
 
*[[Broadband Platform]]
 
*[[Broadband User Guide v16.5.0]]
 
*[[Broadband User Guide v16.5.0]]
 +
*[[Broadband_Platform_Manual_Installation_16_5_0]]
 
*[[CME Project]]
 
*[[CME Project]]

Latest revision as of 17:00, 25 May 2016

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 gfortran compiler installed, which is not available in the Mac Xcode distribution. We recommend use of a gnu Mac binary distribution of gfortran.
  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 the 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 BBP v16.5.0 on Mac 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 gfortran 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 Anaconda's conda 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 ensure 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 Mac OS

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 (gfortran) require administrator access on the Mac. These instruction assume the account you are using has administrator privileges. 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.

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.

Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal)

If you type gcc -v in the terminal window, you should see something like the following: 

$ 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)

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 (free) needed by the Broadband Platform type the following:

Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal) Type xcode-select --install and respond to the the dialogs that open. These dialogs may ask you to agree to the apple license.

Install Fortran Compiler

Xcode does not include a fortran compiler which is required by the BBP platform software. We recommend that you download a Mac binary installation of the GFortran compiler from the GNU web site (free).

Selest the appropriate version of the Mac Fortran compiler from the following gnu website:

It should be possible to install the fortran from the gnu source code, but we have not tested this approach.

Once fortran is installed, you should open a terminal window, and type gfortran -v to verify the compiler is installed and working. To do this, in your Terminal window, if should look something like this 

$ gfortran -v
Using built-in specs.
COLLECT_GCC=gfortran
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)

Install Python 2.7 Distribution

The BBP v16.5.0 requires Python v2.7+ and several optional python libraries. It is possible to collect all necessary Python libraries, but we recommend using a Python distribution that includes nearly all the required libraries. We recommend use of the Continuum Anaconda Python distribution (free).

Go to the Continuum Anaconda download site, and download the Python 2.7 command line distribution tool (free).

Once this is downloaded, run the installer by typing: 

% bash Anaconda2-4.0.0-MacOSX-x86_64.sh

It will ask you to agree to the license, and then install a current version of Python 2.7 and most of the Python libraries required by the BBP v16.5.0. Anaconda Python can be installed in your user directory and does not require administrator privileges.

The end of the installation process will update your .bash_profile to put the Anaconda Python into your default path. We tested using the Anaconda version given above, and it worked with BBP v16.5.0

Update the PyProj library in Anaconda Python

One Python package that must be updated to in the pyproj library. Use the Anaconda update tool. Open a terminal window and type: 

% conda install pyproj

The conda installer program will run, and it will identify what needs to be installed, or updated. When it asks for approval to proceed, enter yes. Pyproj will be added/updated to your Mac.

Install the Broadband Platform using the Easy Install Script

At this point, your Mac has all the software tools needed to install, compile and run the Broadband Platform. Please return to the Broadband Users Guide and follow the easy install instructions. Continue the installation instructions at Broadband Platform Easy Installation

Once the easy install process completes, users should run the Unit Tests and Acceptance tests to ensure the BBP v16.5.0 is installed and operating properly on your Mac, following instructions given on Broadband_User_Guide_v16.5.0#Running_the_Tests. When the Unit Tests and Acceptance tests pass on your computer, it provides evidence that the platform is properly installed and is producing results equivalent to the released version used for SCEC research purposes.

Additional information about the installation process is included on the Broadband Platform Manual Installation page.

Related Entries

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