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

From SCECpedia
Jump to navigationJump to search
 
(10 intermediate revisions by 2 users not shown)
Line 5: Line 5:
 
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 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 gcc fortran compiler installed, which is not available in the Mac Xcode distribution. We recommend use of a gnu Mac binary distribution of gfortan.
+
#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 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 anaconda package update tool.
+
#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.
 
#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) ==
+
== 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).  
 
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).  
  
Line 19: Line 19:
 
# Install Xcode from the Mac App Store.
 
# Install Xcode from the Mac App Store.
 
# Install the Xcode command line tools.
 
# Install the Xcode command line tools.
# Install a gfortan compiler from the gnu site.
+
# Install a gfortran compiler from the gnu site.
# Install a collection of python libraries using the Continuum anaconda distribution.
+
# Install a collection of Python libraries using the Continuum Anaconda distribution.
# Update a python library, called pyproj, using the condo install command.
+
# 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.
 
# Install the Broadband Platform software and required libraries using the BBP easy install script.
 
# Update the .bash_profile in your user account
 
# Update the .bash_profile in your user account
# Run the unit tests and acceptance tests to esure the platform is working properly on your Mac.
+
# 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.
 
# Use the Broadband Platform for your research purposes.
  
== Step-by-Step Installation of BBP v16.50 on OS X 10.11.5 (El Capitan) ==
+
== 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 (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.  
+
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.  
  
== 1. Install Xcode from the Mac App Store ==
+
== 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.
 
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.  
+
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)
 
Open a terminal window, by opening the Terminal application (Applications > Utilities > Terminal)
Line 39: Line 39:
 
If you type gcc -v in the terminal window, you should see something like the following:
 
If you type gcc -v in the terminal window, you should see something like the following:
  
  scecadms-MacBook-Pro-2:~ maechlin$ gcc -v
+
  $ gcc -v
 
  Using built-in specs.
 
  Using built-in specs.
 
  COLLECT_GCC=gcc
 
  COLLECT_GCC=gcc
Line 48: Line 48:
 
  gcc version 4.9.2 20141029 (prerelease) (GCC)  
 
  gcc version 4.9.2 20141029 (prerelease) (GCC)  
  
== 2.  Install the Xcode command line tools. ==
+
== 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:
 
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:
  
Line 54: Line 54:
 
Type xcode-select --install and respond to the the dialogs that open. These dialogs may ask you to agree to the apple license.
 
Type xcode-select --install and respond to the the dialogs that open. These dialogs may ask you to agree to the apple license.
  
== 3. Install Fortran Compiler ==
+
== 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).
 
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).
  
Line 62: Line 62:
 
It should be possible to install the fortran from the gnu source code, but we have not tested this approach.
 
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 fortran -v to verify the compiler is installed and working.
+
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
 
To do this, in your Terminal window, if should look something like this
  
  scecadms-MacBook-Pro-2:~ maechlin$ gfortran -v
+
  $ gfortran -v
 
  Using built-in specs.
 
  Using built-in specs.
 
  COLLECT_GCC=gfortran
 
  COLLECT_GCC=gfortran
Line 74: Line 74:
 
  gcc version 4.9.2 20141029 (prerelease) (GCC)  
 
  gcc version 4.9.2 20141029 (prerelease) (GCC)  
  
== 3. Install Python Distribution ==
+
== Install Python 2.7 Distribution ==
The BBP v16.5.0 requires Python v2.7+ and many 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).
+
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).
 
Go to the Continuum Anaconda download site, and download the Python 2.7 command line distribution tool (free).
Line 81: Line 81:
  
 
Once this is downloaded, run the installer by typing:
 
Once this is downloaded, run the installer by typing:
%bash Anaconda2-4.0.0-MacOSX-x86_64.sh  
+
% 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.
+
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
+
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
  
== 4. Update the PyProj library in Anaconda Python ==
+
== 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:
+
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
 
  
This will identify what needs to be installed, or updated. When it asks for approval to proceed, enter yes.
+
% 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.
 
Pyproj will be added/updated to your Mac.
  
== 5. Install the Broadband Platform using the Easy Install Script ==
+
== 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_User_Guide_v16.5.0#Broadband_Platform_Easy_Installation]]
+
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]]
 
 
==== Running Unit Tests ====
 
 
 
In order to run the unit tests, users should cd into bbp/tests directory and type:
 
 
 
% nohup ./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 [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).
 
 
 
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 (hypothetical earthquakes). These tests will take somewhere between 2 and 3 hours to run, depending on how fast the computer is.
+
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_16_5_0|Broadband Platform Manual Installation]] page.
  
 
== 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