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:
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 test.nc 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 test.nc -OV' and compare it to the original SSA
(with Gibson & Bruck optimizations) by running './SSA-serial
test.nc -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 test.nc -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