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 ...]

Friday, January 8, 2016

Setting up a 64-bit gcc environment on Windows

Note: This is the first in a series of "how-to" blog posts to help new users and developers of BioFVM and PhysiCell. This guide is for Windows users. OSX users should use this guide for Homebrew (preferred method) or this guide for MacPorts (much slower but reliable). 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 a 64-bit Windows port of gcc. These instructions should work for any modern Windows installation, say Windows 7 or above. This tutorial assumes you have a 64-bit CPU running on a 64-bit operating system.

In the end result, you'll have a compiler, key makefile capabilities, and a decent text editor. 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.

What you'll need:

  • MinGW-w64 compiler: This is a native port of the venerable gcc compiler for windows, with support for 64-bit executables. Download the latest installer (mingw-w64-install.exe) here. As of January 8, 2016, this installer will download gcc 5.3.0.
  • MSYS tools: This gets you some of the common command-line utilities from Linux, Unix, and BSD systems (make, touch, etc.). Download the latest installer (mingw-get-setup.exe) here
  • Notepad++ text editor: This is a full-featured text editor for Windows, including syntax highlighting, easy commenting, tabbed editing, etc. Download the latest version here.  As of January 8, 2016, this will download Version 6.8.8. 

Main steps:

1) Install the compiler

Run the mingw-w64-install.exe. When asked, select:

Version: 5.3.0 (or later)
Architecture: x86_64
Threads: win32 (While I have tested posix, the native threading should be faster.)
Exception: seh (While sjlj works and should be more compatible with various GNU tools, the native SEH should be faster.)
Build version: 0 (or the default)

Leave the destination folder wherever the installer wants to put it. In my case, it is:

c:\Program Files\mingw-w64\x86_64-5.3.0-win32-seh-rt_v4_rev0

Let MinGW-w64 download and install whatever it needs.

2) Install the MSYS tools 

Run mingw-get-setup.exe. Leave the default installation directory and any other defaults on the initial screen. Click "continue" and let it download what it needs to get started. (a bunch of XML files, for the most part.) Click "Continue" when it's done. 

This will open up a new package manager. Our goal here is just to grab MSYS, rather than the full (but merely 32-bit) compiler. Scroll through and select ("mark for installation") the following: 
  • mingw-developer-toolkit. (Note: This should automatically select msys-base.)
Next, click "Apply Changes" in the "Installation" menu. When prompted, click "Apply." Let the package manager download and install what it needs (on the order of 95 packages). Go ahead and close things once the installation is done, including the package manager. 

3) Install the text editor

Run the Notepad++ installer. You can stick with the defaults. 

4) Add these tools to your system path

Adding the compiler, text editor, and MSYS tools to your path helps you to run make files from the compiler. First, get the path of your compiler:
  1. Open Windows Explorer ( [Windows]+E )
  2. Browse through C:\, then Program Files, mingw-w64, then a messy path name corresponding to our installation choices (in my case, x86_64-5.3.0-win32-seh_rt_v4-rev0), then mingw64, and finally bin
  3. Open notepad ([Windows]+R , notepad), 
  4. Go to the address bar of Explorer and copy ([Control]+C) the full path of the directory you just browsed to.
  5. Paste it into notepad ([Control]+V), preceded and followed by a semicolon, and a final slash if it isn't there. In my case: 
;c:\Program Files\mingw-w64\x86_64-5.3.0-win32-seh-rt_v4_rev0\mingw64\bin\; 

Then, get the path to Notepad++.
  1. Go back to Explorer, and choose "This PC" or "My Computer" from the left column.  
  2. Browse through C:\, then Program Files (x86), then Notepad++.
  3. Copy the path from the Explorer address bar. 
  4. Paste this path just after the final semicolon in notepad, followed by a backslash and a semicolon. In my case: 
;c:\Program Files\mingw-w64\x86_64-5.3.0-win32-seh-rt_v4_rev0\mingw64\bin\;c:\Program Files (x86)\Notepad++\; 

Then, get the path for MSYS:
  1. Go back to Explorer, and choose "This PC" or "My Computer" from the left column.  
  2. Browse through C:\, then MinGW, then msys, then 1.0, and finally bin.
  3. Copy the path from the Explorer address bar. 
  4. Paste this path just after the final semicolon in notepad, followed by a backslash and a semicolon. In my case: 
;c:\Program Files\mingw-w64\x86_64-5.3.0-win32-seh-rt_v4_rev0\mingw64\bin\;c:\Program Files (x86)\Notepad++\;C:\MinGW\msys\1.0\bin\; 

Lastly, add these paths to the system path: 
  1. Go the Start Menu, the right-click "This PC" or "My Computer", and chose "Properties."
  2. Click on "Advanced system settings"
  3. Click on "Environment Variables..." in the "Advanced" tab
  4. Scroll through the "System Variables" below until you find Path. 
  5. Select "Path", then click "Edit..."
  6. At the very end of "Variable Value", paste what you made in Notepad in the prior steps. Make sure to paste at the end of the existing value, rather than overwriting it!
  7. Hit OK, OK, and OK to completely exit the "Advanced system settings." 

5) Test the compiler

Write a basic parallelized program:

Enter a command prompt ( [windows]-R, then cmd ). 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
> notepad++ 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 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, open up a new tab in Notepad++, and save it as "Makefile". Add the following contents: 

CC := g++
ARCH := core2 # Replace this 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).

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!

Open up the Windows task manager ([windows]-R, taskmgr) while the code is running.  Take a look at the performance tab, particularly the graphs of the CPU usage history. While your program. is running, you should see all your virtual processes 100% utilized. (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 

Return to News   Return to MathCancer