Home page Models Systems Tools IT staff References
Development Environment Get Source Build Procedures Run Result Processing
The 3D lymph node model was originally coded by a contract programmer named Robert Vogt IV, based on a model design by Mohammad Fallahi, a graduate student in Dr. Linderman's lab. That code is in the svn archive in directory dev/viz3d. This code attempted to combine both a 3D lymph model and a 3D lung model, with the choice of model to run specified by conditional compilation. It did not compile as is, and once the compiler problems were fixed it did not run - it would generate a segmentation fault on initialization. Once the seg fault problem was fixed, it became apparent that the code treated a model time step as different time intervals in different parts of the code, and treated the 2 coordinate as the vertical axis in one part of the code and the 3rd coordinate as the the vertical axis in another part of the code. The code was rather messy as well, with only one agent class and a single function with a single set of nested if statements to manage the agent state transitions. Also a number of model components were not implemented, for example DCs (dendritic cells) were the same size as T cells, instead of being larger, T cell/DC binding was not implemented and toroidal movement was not implemented, among other things.
A copy of the original code code was made and placed in the svn archive in directory dev/viz3dLN (there is also dev/viz3dPSW, which was an aborted attempt to deal with the problems in dev/viz3d, and is no longer used). This code was cleaned up to a significant degree and the rest of the model was implemented. The parameters were moved from a header file to an external XML file, using parameter processing similar to (but somewhat different than) that used in the lung model models, using the Boost program options library. The parameter processing is described in detail in LNCodeDocumentation.docx in the lymph node svn source archive. The random number generator source files were deleted and replaced by the Boost random number generator library. Extensive changes and additions were then made as part of the research effort by post-doc Henry Mirsky in Dr. Linderman's lab, particularly to the toroidal movement, support for large DCs, T cell/DC binding, among others. The coding for this version of the code was done by Paul Wolberg, a staff programmer in both the Kisrchner and Linderman labs.
There is extensive documentation of the model and its code in file LNCodeDocumentation.docx in the svn archive with the source code. There is documentation on the particular geometry used to represent a section of a lymph node and of various runs and analysis of run results on the Linderman lab CTools web site. These documents were all created by Henry Mirsky.
Here are the tools needed for working with the 3D lymph node model.
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.
There are ffmpeg header files in the include directory of the main lymph node source directory, as checked out from the svn archive. The include flags in the make file reference these header files, instead of (or in addition to) the header files installed when ffmpeg is installed. Changing the make file to not using the ones in the lymph node source directory caused builds to fail on Fedora, so the make file was left referencing the ones in the lymph node source directory, even though it would be preferrable to only reference headers installed with ffmpeg.
The source is in the svn archive in "svn://innoculant.micro.med.umich.edu/dev/viz3dLN".
Use the svn command line client, 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.
To get the source using the command line client use:
svn co svn://innoculant.micro.med.umich.edu/dev/viz3dLN
The viz3dLN/include directory has SDL header files and 2 MS Visual Studio specific header files - inttypes.h and stdint.h. These 2 header files are part of the standard C header files, but are not supplied as part of Visual Studio. File inttypes.h is included by viz3dLN\include\libavutil\common.h and in turn inttypes.h includes stdint.h. libavutil is one of the ffmpeg audio/video libraries used by viz3dLN. It is not known where these 2 header files were obtained from. viz3dLN Visual Studio builds will not work without them.
On Unix/Linux systems DO NOT COPY the contents of viz3dLN\include to a system include directory, such as /usr/include, since builds won't work - the inttypes.h and stdint.h header files will generate fatal compiler errors because they will detect that they are not on a Windows system (an MS Visual Studio specific #define macro won't be defined).
The proper way to handle this is to install the appropriate libraries - SDL, libavutil, etc., which will install their header files in the correct places and not install MS Visual Studio specific header files anywhere.
To build the model on a Linux or Mac 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 "viz3dLN".
The Windows builds can use either Visual Studio or command line builds, if mingw has been installed. Visual Studio uses solution files ("*.sln" files), which are configuration files that contain the list of source files, build dependencies, compiler and linker flags, including header file and library locations, target directories for build result files, etc. The solution file for the lymph node code is Viz3DLN.sln.
Some changes were made to get Windows builds to work, during the switch from the viz3d project to the viz3dLN project. The precompiled header is no longer used, since builds would fail if using it once we started using the Boost program options library to handle command line arguments.
Visual Studio is a full featured integrated development environment so it can be used for editing
and debugging in addition to builds. To perform a build, do the following, which is equivalent
to make clean and make.
To build the model on Windows:
Since the model executable is called viz3dLN, use the command ./viz3dLN -p parameter-file.xml.
The program requires a parameter file, which is an xml file. See parameter
processing for an overview on how to use parameter files. Some, or all, of the parameter files
from the source archive may not work as is and need to have parameters added. An error message will be displayed
when the program is run if it expects parameters that are missing from the parameter file used.
The program also has a number of command line options. Use ./viz3dLN -h to see a list of them with short descriptions.
Use ./viz3dLN -v to see the version number. Some of the command line options control the number of
simulation steps, in days or time steps, and what statistics to produce, how frequently and what files to write them
to, among other options. When the -h or -v option is used the program does not run the model, even if a parameter
file was specified.
Once the program is up and running there will be a graphics window that shows the simulation grid as it runs. Statistics for each time step will be written to the terminal window where the program was invoked. When the graphics window is the active window it responds to certain keystrokes and mouse movements. Here are some of the basic keystrokes the program responds to. Pause the simulation with "," before using "h", otherwise the "h" output will scroll off the screen. The "h" output will be displayed in the terminal window.
Valgrind is, among other things, a memory checking tool that is useful for debugging memory problems. The lymph node model make file has several valgrind related targets to generate an executable for use with valgrind. Each causes debug symbols to be included in the executable (the -g option). Each also uses a particular g++ optimization level - O0, O1 or O3. The targets are valgrindO0, valgrindO1 and valgrindO3. The valgrindO3 target is probably the best to use, since it runs the fastest. The downside is that it may not always accurately report the location of an error in the source code, but so far that hasn't been a problem.
To use valgrind, do a "make clean" and then a make with one of the valgrind targets, ex. "make valgrindO3". The "make clean" is to ensure that all the model source code is compiled for valgrind. Then run as normally, except begin the command to run the model with "valgrind", ex. "valgrind ./viz3dLN -i base.xml". Valgrind has a number of options that can be used. The ones we use when running the lymph model with valgrind are stored in the file .valgrindrc, which is used by valgrind if present, so they don't have to be specified manually. This includes an option to use the valgrind suppression file lymphValgrind.supp. This causes valgrind to suppress memory error messages related to 3rd party libraries, such as SDL and ffmpeg, since those are not relevant to debugging our model code.
See file LNCodeDocumentation.docx, in the main source code directory for the model, for information on what output files can be produced, what they contain and how they can be analyzed.