Figure: An early test of our new 3-D agent-based cell model, growing from 10 to 80,000 agents in about 25 days (24-threaded simulation required about 5 hours). Rendered in 3D using POVRAY (with a cutaway view). [Read more ...]

Tuesday, January 19, 2016

Setting up gcc / OpenMP on OSX (Homebrew edition)

Note: This is the third in a series of "how-to" blog posts to help new users and developers of BioFVM and PhysiCell. This guide is for OSX users. Windows users should use this guide instead. A Linux guide is expected soon.

These instructions should get you up and running with a minimal environment for compiling 64-bit C++ projects with OpenMP (e.g., BioFVM and PhysiCell) using gcc. These instructions were tested with OSX 10.11 (El Capitan), but they should work on any reasonably recent version of OSX.

In the end result, you'll have a compiler and key makefile capabilities. The entire toolchain is free and open source.

Of course, you can use other compilers and more sophisticated integrated desktop environments, but these instructions will get you a good baseline system with support for 64-bit binaries and OpenMP parallelization.

Note 1: OSX / Xcode appears to have gcc out of the box (you can type "gcc" in a Terminal window), but this really just maps back onto Apple's build of clang. Alas, this will not support OpenMP for parallelization.

Note 2: Yesterday in this post, we showed how to set up gcc using the popular MacPorts package manager. Because MacPorts builds gcc (and all its dependencies!) from source, it takes a very, very long time. On my 2012 Macbook Air, this step took 16 hours.  This tutorial uses Homebrew to dramatically speed up the process!

Note 3: This is an update over the previous version. It incorporates new information that Xcode command line tools can be installed without the full 4.41 GB download / installation of Xcode. Many thanks to Walter de Back and Tim at the Homebrew project for their help!

What you'll need:

  • XCode Command Line Tools: These command line tools are needed for Homebrew and related package managers. Installation instructions are now very simple and included below. As of January 18, 2016, this will install Version 2343.
  • Homebrew: This is a package manager for OSX, which will let you easily download and install many linux utilities without building them from source. You'll particularly need it for getting gcc. Installation is a simple command-line script, as detailed below. As of January 17, 2016, this will download Version 0.9.5. 
  • gcc5 (from Homebrew): This will be an up-to-date 64-bit version of gcc, with support for OpenMP. As of January 17, 2016, this will download Version 5.2.0.

Main steps:

1) Install the XCode Command Line Tools

Open a terminal window (Open Launchpad, then "Other", then "Terminal"), and run:

xcode-select --install

A window should pop up asking you to either get Xcode or install. Choose the "install" option to avoid the huge 4+ GB Xcode download. It should only take a few minutes to complete. 

2) Install Homebrew

Open a terminal window (Open Launchpad, then "Other", then "Terminal"), and run:

> ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Let the script run, and answer "y" whenever asked. This will not take very long. 

3) Get, install, and prepare gcc

Open a terminal window (see above), and search for gcc, version 5.x or above

> brew search gcc5

You should see a list of packages, including gcc5. Take a note of what is found. (In my case, it found homebrew/versions/gcc5

Then, download and install gcc5:

> brew install homebrew/versions/gcc5

This will download whatever dependencies are needed, generally already pre-compiled. The whole process should only take five or ten minutes.

Lastly, you need to get the exact name of your compiler. In your terminal window, type g++, and then hit tab twice to see a list. On my system, I see this:

Pauls-MBA:~ pmacklin$ g++
g++       g++-5       g++-mp-5 

Look for the version of g++ without an "mp" in its name. In my case, it's g++-5. Double-check that you have the right one by checking its version. It should look something like this: 

Pauls-MBA:~ pmacklin$ g++-5 --version
g++-5 (Homebrew gcc5 5.2.0) 5.2.0
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Notice that Homebrew shows up in the information. The correct compiler is g++-5. 

5) Test the compiler

Write a basic parallelized program:

Open Terminal (see above). You should be in your user profile's root directory. Make a new subdirectory, enter it, and create a new file:  

> mkdir omp_test
> cd omp_test
> nano omp_test.cpp

Then, write your basic OpenMP test: 

#include <iostream>
#include <cmath> 
#include <vector>
#include <omp.h>

int main( int argc, char* argv[] ) 
{
 omp_set_num_threads( 8 ); 

 double pi = acos( -1.0 ); 

 std::cout << "Allocating memory ..." << std::endl; 
 std::vector<double> my_vector( 128000000, 0.0 ); 
 std::cout << "Done!" << std::endl << std::endl; 

 std::cout << "Entering main loop ... " << std::endl; 

 #pragma omp parallel for
 for( int i=0; i < my_vector.size(); i++ )
 {
  my_vector[i] = exp( -sin( i*i + pi*log(i+1) ) ); 
 } 
 std::cout << "Done!" << std::endl; 

 return 0; 
}

Save the file (as omp_test.cpp). (In nano, use [Control]-X, Y, and then confirm the choice of filename.)

In the omp_set_num_threads() line above, replace 8 with the maximum number of virtual processors on your CPU. (For a quad-core CPU with hyperthreading, this number is 8. On a hex-core CPU without hyperthreading, this number is 6.) If in doubt, leave it alone for now. 

Write a makefile:

Next,  create a Makefile to start editing:

> nano Makefile 

Add the following contents: 

CC := g++-5
# replace this with your correct compiler as identified above

ARCH := core2 # Replace this with your CPU architecture.
# core2 is pretty safe for most modern machines. 

CFLAGS := -march=$(ARCH) -O3 -fopenmp -m64 -std=c++11

COMPILE_COMMAND := $(CC) $(CFLAGS)

OUTPUT := my_test

all: omp_test.cpp
 $(COMPILE_COMMAND) -o $(OUTPUT) omp_test.cpp

clean:
 rm -f *.o $(OUTPUT).*

Go ahead and save this (as Makefile). ([Control]-X, Y, confirm the filename.)

Compile and run the test:

Go back to your (still open) command prompt. Compile and run the program: 

> make
> ./my_test

The output should look something like this: 

Allocating memory ...
Done!

Entering main loop ... 
Done!

Note 1: If the make command gives errors like "**** missing separator", then you need to replace the white space (e.g., one or more spaces) at the start of the "$(COMPILE_COMMAND)" and "rm -f" lines with a single tab character. 

Note 2: If the compiler gives an error like "fatal error: 'omg.h' not found", you probably used Apple's build of clang, which does not include OpenMP support. You'll need to make sure that you specify your compiler on the CC line of your makefile. 

Now, let's verify that the code is using OpenMP.

Open another Terminal window. While the code is running, run top. Take a look at the performance, particularly CPU usage. While your program is running, you should see CPU usage fairly close to '100% user'. (This is a good indication that your code is running the OpenMP parallelization as expected.)

What's next?

Download a copy of BioFVM and try out the included examples!
  1. BioFVM announcement on Blogspot: [click here
  2. BioFVM on MathCancer.org: http://BioFVM.MathCancer.org 
  3. BioFVM on SourceForge: http://BioFVM.sf.net 
  4. BioFVM Method Paper in BioInformatics: http://dx.doi.org/10.1093/bioinformatics/btv730 

Tutorial series for BioFVM


11 comments:

  1. This comment has been removed by a blog administrator.

    ReplyDelete
  2. This comment has been removed by a blog administrator.

    ReplyDelete
  3. This comment has been removed by the author.

    ReplyDelete
  4. This comment has been removed by a blog administrator.

    ReplyDelete
  5. Nice article.

    I am stuck with this error when I typed my_test:
    zsh: command not found: my_test

    Any idea what the issue could be?

    ReplyDelete
    Replies
    1. Oops. On Linux / BSD-like systems, you should enter:

      make
      ./my_test

      Please let me know if that works. Best -- Paul

      Delete
  6. yes, works :D thank you so much

    ReplyDelete
  7. Thank you so much for this amazing tutorial! This worked a charm, and love your notes. This tutorial is also a good way to be really productive with older hardware. :)

    ReplyDelete
  8. Here is a great herbal doctor who cured me of Hepatitis B. his name is Dr. Imoloa. I suffered Hepatitis B for 11 years, I was very weak with pains all over my body my stomach was swollen and I could hardly eat. And one day my brother came with a herbal medicine from doctor Imoloa and asked me to drink and I drank hence there was no hope, and behold after 2 week of taking the medicine, I started feeling relief, my swollen stomach started shrinking down and the pains was gone. I became normal after the completion of the medication, I went to the hospital and I was tested negative which means I’m cured. He can also cure the following diseases with his herbal medicine...lupus, hay fever, measles, body pain,  dry cough, diabetics hepatitis A.B.C,  mouth ulcer, mouth cancer, bile salt disease, fol ate deficiency,  diarrhoea, cardiovascular disease,  Neoplasms, chronic respiratory disease, mental and behavioural disorder,  liver/kidney inflammatory, eye cancer, skin cancer disease, malaria, chronic kidney disease, high blood pressure, food poisoning, parkinson disease, bowel cancer, bone cancer, brain tumours, asthma,  arthritis, epilepsy, cystic fibrosis, lyme disease, muscle aches, cholera, fatigue, muscle aches, shortness of breath, tuberculosis,  alzhemer's disease, Rheumatoid Arthritis,  Anxiety Disorders, Back Pain, Crohn's Disease, Chronic renal failure,  acute myeloid leukaemia, acute pancreatitis, chronic inflammatory joint disease, inflammatory bowel disease,  Addison's disease,   back acne, breast cancer, allergic bronchitis, Celia disease, bulimia disease, congenital heart disease, cirrhosis, fetal alcohol spectrum,  constipation,  fungal nail infection, fabromyalgia,   (love spell) and many more. he is a great herbalist man.  Contact him on email; drimolaherbalmademedicine@gmail.com. You can also reach him on whatssap- +2347081986098.

    ReplyDelete