Home page Models Systems Tools IT staff References
Development Environment Get Source Build Procedures Run Result Processing
There have been several versions of the 2D lung node model. The origianl model was by Segovia, followed by a version by Christian Ray. These are C++ programs that are not in our svn archive. The current version was originally created by Mohammed El Kebir and uses a class hierarchy for the core simulation model and a Qt based GUI framework of his design and implementation.
The 3D lung model was created by Paul Wolberg, by copying the 2D lung model and modifying it to be 3D. Mostly this was making the simulation grid 3D and making whatever related changes were necessary. This did not have 3D graphics, but did have the ability to show any 2D slice of the the 3D grid. Cory Perry then added 3D graphics and made a number of changes to improve performance.
Here are the tools needed for working with the 2D and 3D lung models on various paltforms.
Be sure to check if a tool is already installed before trying to install it again. This is often done by using the "--version" command line option for those tools that are programs that can be invoked from a terminal window command line. See the decription for a tool for more information on how to determine if the tool is installed.
These are needed to run the models and to process the model run results.
If you want a gui svn client.
Needed for command line builds, which are needed to avoid including any Microsoft .Net manifest in a release build. This might be installed with Qt. It includes make and g++, as mingw-make and mingw-gcc.
The 2D model source is in the svn archive in "svn://innoculant.micro.med.umich.edu/dev/gr2d/GR-ABM-ODE".
The 3D model source is in the svn archive in "svn://innoculant.micro.med.umich.edu/dev/GR-ABM-ODE-3D".
Use the svn command line program, or a GUI svn client, to get a copy of the source code or to get the latest version is you already have a copy. Access the description for the svn client you are using from our tools web page for information on how to use a particular svn client.
If using Eclipse or Qt Creator, then follow these directions after checking out the source or performing an "svn up" command.
To build the model on a Linux system:
make cleanmake
This will perform a compile and link. Obviously you will need to fix any compiler or linker errors.
Also look for any warning messages in the compiler output (they can be hard to spot in the dense output
the compiler produces). There shouldn't be any. If there are any fix them or get help from a programmer
to diagnose them.
The output from the make will be an executable file called "grviz-lung" for the gui version and "gr"
for the non-gui version.
Both the gui and non-gui versions of the model require a parameter file, which is an XML file. See parameter processing for an overview of how to use parameter files. There are general model parameters as attributes of the <GR> root node of the parameter file, macrophage parameters in the <Mac> node, general T cell parameters in the <Tcell> node, gamma (helper) T cell, cytotoxic (killer) T cell, regulatory T cell parameters in the <Tcyt>, <Tgam> and <Treg> nodes, and mtb bacteria parameters in the <Mtb> node. The <Init> node specifies the initial conditions. It has one <Mac> node and one <Mtb> node for each infected macrophage and bacterium to place on the grid at the simulation start. Each of these nodes specifies a grid position as the location for that item. This is row and column for the 2D model and row, column and slice for the 3D model. Typically there is only one infected mac at the simulation start and sometimes one bacterium, both in the center of the grid. However, there can be any number of these, which can be useful for testing and debugging.
Both the non-gui and gui versions can write statistics to a file. In the non-gui version this is done in the functions writeOutputHeader and writeOutput in file grmain.cpp. In the GUI version this is in the file snapshot.cpp - the header is written in the Snapshot class constructor and the data in the takeSnapshot function. Both statistics file are similar. When adding new columns to the statistics file being written, for either version, add the new columns to the end of the line being written. There are many scripts which depend on the order of the columns written, especially Matlab scripts that perform statistical analysis on run results. The column order should only be changed in consultation with the scientists that use the statistics files.
Use the command ./gr -i parameter-file.xml to run the non-gui version.
Use ./gr -h to see a list of the non-gui command line arguments.
Use ./gr -v to see the version, and also the grid size, being used.
When the non-gui version runs it displays a line of statistics with the same time step frequency as the --csv-interval command line argument. If not specified this defaults to every time step. Look at the code in file grmain.cpp that writes this line to see what statistics are being displayed.
Use the command ./grviz-lung -i parameter-file.xml to run the gui version
Use ./grviz-lung -h to see a list of the gui command line arguments.
Use ./grviz-lung -v to see the version, and also the grid size, being used.
When the gui version runs it displays two windows, a gui window with a set of tabs for sub-windows and a 2D grahpics window that show the simulation grid. The gui window has tabs for setting what gets displayed in the graphics window (which agents, what chemical gradient, etc.), what data gets saved to files (statistics, simulation states, snapshots of the graphics window) and how frequently. Some of these items can also be controlled from the command line, which is useful when running the program from a script.
The 3D model gui version also displays a 3D graphics window. In the 3D version both the 2D and 3D graphics windows have a help icon in the lower right corner that displays in a tool tip when the mouse rolls over it the keyboard and mouse strokes that window responds. These keystrokes and mouse events are more extensive than those available in the 2D code.
See LHS parameter processing for a description of how to run and process the results of an LHS run.