Hy3S -- Hybrid Stochastic Simulation for Supercomputers
Home | Examples | Download | Developers | Publications | SF Project Page

Instructions on Installing Hy3S (version 1.0)

There's two components to Hy3S: the graphical user interface (GUI) (requires Matlab v7.0 R14 to run) and the Fortran95 simulation programs. Instructions on how to install both are below. If anything is ambiguous, please let me know by emailing me at the address at the end of the page.

Installing a Pre-Compiled Package

If you want to get started quickly, consider using a pre-compiled package from the list of available platforms. The package contains the source code for the simulation programs, the platform-specific compiled binaries, and the necessary pre-compiled, platform specific NetCDF files (v3.6.0-p1). If you extract/decompress the package on the correct platform, it should just work (cross your fingers ...). Both serial and MPI versions of the program are included. You will need to have MPI installed in order to run the program in MPI mode. The binaries are compiled with aggressive optimization (but no profiling as of yet) so it would take about 10 minutes if you do it yourself. A program that creates a large-scale system benchmark is also included.
There is no pre-compiled package for the GUI because it's written using Matlab's GUI engine. Follow the instructions below for installing the GUI.

Installing the GUI

Download the Hy3S GUI tarball or zipfile and extract it.

For Windows98/2k/XP:

Open Matlab. Set the current directory (at the top) to ../Hy3S-v1.0/GUI/Matlab. Run 'mexcdf53_pcwin_install' at the Matlab prompt. This will install the DLL file for the NetCDF Toolbox for MATLAB. Then run 'netcdf_install' at the Matlab prompt. This will install a bunch of M files for the toolbox. Go to 'Set Path' under the File menu. Add with subdirectories the ../Hy3S-v1.0/GUI/Matlab directory. Type 'mexcdf53' at the Matlab prompt. This should produce a list of mex functions (if it produces an error, try it again. This sometimes happens.)
Type 'netcdf' at the Matlab prompt. This should produce the help file for the NetCDF Toolbox. (If it doesn't work, make sure your Matlab path includes the directories where those files are located.)

For all other platforms:

Download the gzipped tarball of the NetCDF Toolbox from the MexCDF website. Important: You will also need a mexfile from their list of available platforms. Save the mexfile and gzipped tarball to your ../Hy3S-v1.0/GUI/Matlab directory and extract the mexfile (if zipped/tared) and the tarball. Open Matlab and go to 'Set Path' under the file menu. Add with subdirectories the ../Hy3S-v1.0/GUI/Matlab directory. Make sure the locations of the extracted files are in your Matlab path. To make sure everything is installed, type 'test_mexnc'.

To run the Hy3S GUI, type 'designgui' at the prompt. And you're done!

To read more about how to use the GUI to create biochemical reaction networks and about additional simulation options, go to the instructions page.

Installing the Simulation Programs (From Scratch)

Obtain a copy of the NetCDF API with Fortran95 support (the latest stable version is 3.6.0-p1) from the Unidata website. Extract the tarball and go to the ../netcdf-version/src/ directory. Execute ./configure, ./make, ./make test, and ./make install. If you want to make sure the Large File Support (LFS) works, execute ./make extra_test. LFS allows you to create a ~2^63 byte file on a 32-bit machine. Cool, huh? The LFS test will require 12 GB of extra space.

After executing ./configure, it's best to read through the result and make sure the following happened: 1) it found your Fortran90/95 compiler. 2) There are no WARNINGS about the Fortran90 interface not being built. 3) If you're on a 32-bit machine, it needs to set special flags to build LFS. If none of these problems were encountered then you can just proceed to the ./make step. If you did see some errors, the most common problem is a missing directory in your PATH or LD_LIBRARY_PATH environmental variables. Make sure you can find your compiler from the terminal and that all of the necessary compiler libraries are accessible.

After executing ./make, it will compile all of the files. The only error I've come across is when you use the Intel Fortran compiler. If you're using the Intel Fortran compiler, you'll need to set some additional environmental variables before executing ./configure. Here they are:

FFLAGS="-O2 -mp -recursive"

Basically, the Intel Fortran compiler has the same calling style as the Portland Group one (hence the pgiFortran flag). The -mp is necessary in order to ensure floating point precision.

Now download the Hy3S simulation program as a gzipped tarball and extract it. Copy the libnetcdf.a file from the NetCDF /lib subdirectory and the netcdf.mod and typesizes.mod files from the NetCDF /include subdirectory to the ../Hy3S/lib/ directory. These files contain the NetCDF API and the Fortran90 module interface. So far, I've been unable to coax a Fortran compiler into 'seeing' the Fortran90 interface from inside the libnetcdf.a library. To get around this, we extract the netcdf.o and typeSizes.o object files from the library. To do this, go to the ../Hy3S/lib/ directory and type 'ar x libnetcdf.a netcdf.o' and 'ar x libnetcdf.a typeSizes.o'. Note the capital 'S' in typeSizes.o.

The next step is to compile the simulation programs. There are two included Makefiles to help you do this: one for the Intel Fortran compiler for Linux and one for the Sun Fortran compiler. If you're using Linux and the Intel compiler, then just go to to the ../Hy3S/src directory and type 'make'. If you're using a Sun machine, then type 'make -f Makefile-Sun'. This will compile all of the simulation programs with full, aggressive optimization. If you do not have MPI on your machine, when the compiler tries to compile the MPI-enabled version of the programs you will get an error. To compile with debugging information and no optimization, type 'make debug' or 'make -f Makefile-Sun debug'. You can also compile specific programs. The targets are hyhomss-serial, SSA-serial, hyhomss-MPI, and SSA-MPI for the non-optimized ones and hyhomss-serial-opt, SSA-serial-opt, hyhomss-MPI-opt, and SSA-MPI-opt for the optimized ones. So 'make -f Makefile-Sun SSA-serial-opt' will compile the SSA program with full optimization using the Sun compiler on a Sun machine.

If you're using neither a Linux or Sun machine, then you'll have to edit the Makefile yourself.

To test it out, go to the ../Hy3S/bin directory and create a large-scale system benchmark by typing './BenchMarkMaker 2 100 5', which will create a reaction network with 2 fast reactions, 100 slow reactions, and 5 independent trials'. Run the Hy3S program on it using './Hy3S-serial -OV' and compare it to the original SSA (with Gibson & Bruck optimizations) by running './SSA-serial -OV'. If you're not impressed, then check your pulse. You might be dead. But, seriously, you can create even larger reaction networks and see the difference grow, especially for systems with many fast reactions.

To use the MPI version, run 'mpirun -np <#> ./Hy3S-MPI -OV'.
To read more about how to use the GUI to create biochemical reaction networks and about additional simulation options, go to the instructions page.
For tips on how to read NetCDF files into Matlab, quickly analyze the results, and make pretty graphs, go to the useful tips page.

Email any questions about the installation process to Howard Salis (email at the bottom). Footer

Maintained by Howard Salis
Kaznessis Research Group
Dept. of Chemical Engineering & Materials Science
University of Minnesota (spam is evil)

Site last modified at Thursday, 07-Jul-2005 17:55:14 UTC