Q: Which kind of problems can be modeled with HBGC123D?
A: HBGC123D can be used to simulated
transport of one or more species in one-, two-, or
three-dimensional model domains. It is also able to simulate heat
transfer. For multicomponent systems, a variety of reactions can
be modeled: Kinetic and equilibrium geochemical and
microbiological reactions. The code can be used for simulations
of both laboratory scale and field scale experiments. Keep in
mind, though, that multicomponent multireaction problems on a
large scale require a lot of CPU time that may exceed the
capacity of your computer system. It takes 25 minutes
to run sample problem 8b on a Pentium II 266 MHz under Windows NT.
However, the given number of time steps (80) was chosen so that
the problem runs in an acceptable time. For a full simulation,
more time steps would be required so that the total simulation
time increases accordingly.
The precompiled MS Windows version of HBGC123D requires
at least 32 MB of memory.
Q: Which kind of computer system is required to run HBGC123D?
A: HBGC123D is designed to run on a large variety of computer systems, including PCs running MS-Windows or Linux and workstations running various UNIX flavors. Large problems (many nodes and/or many components and reactions) may require a lot of CPU time (see previous question). A special multi-processing option is available for SGI machines with multiple processors to reduce the computation time.
Q: How much hard drive space is required to install and run HBGC123D?
A: The executable code needs about 1 to 1.5 MB, depending on the operating system and compiler. The source code needs less than 3 MB. While the input files are usually fairly small, output files for large problems with many output time steps may require hundreds of MB of hard disk space. You can decrease the size of the output files by specifying fewer output time steps in data set 4. If you want to use mainly the program PostHBGC, you may use very few or no output steps for the ASCII output file as specified by the variables KPR0 and KPR(I) in data set 4. You can further reduce the size of the ASCII output file by setting all variables in the second line of data set 1 to 0.
The following table lists the size of the ASCII and binary output files for all sample applications as well as the required time to run these samples. This CPU time refers to a Pentium II/266 MHz PC with 64 MB of RAM running Windows NT. Depending on your processor and operating system, you will get different execution times.
| Sample | CPU time [min] | Size of ASCII output file [MB] | Size of binary output file [MB] |
| 1 | 9 | 17 | 2.3 |
| 2 | 119 | 27.6 | 8.4 |
| 3 | 230 | 86.2 | 9.7 |
| 4 | 3 | 1.6 | 4.6 |
| 5a (1D) | 4 | 5.4 | 4 |
| 5b (2D) | 9 | 10.5 | 8 |
| 5c (3D) | 18 | 20.7 | 16.1 |
| 6 | 17 | 14 | 11 |
| 7 | < 1 | 1 | 0.2 |
| 8a (tracer) | 1 | 2.8 | 1.4 |
| 8b (reactive) | 20 | 13.5 | 10 |
Q: Do I have to compile the source code?
A: An executable version of the code is included in the distribution. You only have to recompile the code if you need to change the size of the allocatable memory (see below).
Q: There is no executable code for my operating system included in the distribution. How do I compile the code?
A: If your operating system (OS) is not included in the distribution list and not compatible to these systems, please contact Dr. Gwo for assistance. If you don't find the exact version of your OS in the distribution list, you may try a different version that is listed. For instance, the HBGC123D executable for SunOS 4.1.4 also runs on Solaris version 2 (2.6, 2.7 etc).
Q: Can I make modifications to the code?
A: Yes, you are allowed to make modifications to the source code of HBGC123D for your own use. The publicly released sources of HBGC123D include all routines that perform input and output.
Q: Can HBGC123D be used free of charge?
A: Yes. HBGC123D is a public-domain code for the use of the entire scientific community. Please read also the Legal Notice and License as well as the next question and answer. Duplication or distribution of the code to others is not allowed. Please contact Dr. Gwo for more information.
Q: Can I use results obtained from HBGC123D for publications?
A: Yes. However, you have to reference HBGC123D in all your publications based on its use. A reference should follow this example: "Our simulations were performed with HydroBioGeoChem123D [Gwo et al., 1999] which is an extended version of the code "HydroBioGeoChem" [Yeh et al., 1998]."
Gwo, J. P., D’Azevedo, E. F, Frenzel, H., Hoffman, F. M., Salvage, K. M., and Yeh, G. T. (1999): HydroBioGeoChem123D: A Coupled Model of Hydrologic Transport and Mixed Biogeochemical Kinetic/Equilibrium Reactions in Saturated-Unsaturated Media in One, Two, and Three Dimensions. Computer code and documentation available at http://hbgc.esd.ornl.gov.
Yeh, G.-T., Salvage, K. M., Gwo, J. P., Zachara, J. M., and Szecsody, J. E. (1998): HydroBioGeoChem: A Coupled Model of Hydrologic Transport and Mixed Biogeochemical Kinetic/Equilibrium Reactions in Saturated-Unsaturated Media. Report ORNL/TM-13668. Oak Ridge National Laboratory, Oak Ridge, TN.
It is appreciated if you send reprints or manuscripts of your publications with references to HBGC123D to Dr. Gwo.
Q: How do I set up the input files for HBGC123D?
A: You can use any text editor to create the main input file for HBGC123D according to the data format as described in the input guide. If you want to use a transient flow field, you need a separate program (see next question). If you want to restart an HBGC123D simulation based on results of a previous run, you need to use the binary output file produced by the previous HBGC123D simulation. The names for all input and output files can be arbitrary as long as they follow the conventions of your operating system. These names are specified in the superfile named "hbgc123d.in" (see the input guide for details). The maximum length of all file names (including the path, if specified) is 80 characters each.
Only the superfile has to be present in the directory you are working in. All other files can reside or be created in other directories, if you specify the path to them in the superfile accordingly. The path can be specified as either an absolute or a relative path. For instance, a path to an ASCII input file named "tracer.in" can be specified under Windows as
C:\HBGC123D\simulations\TracerTransport\tracer.in
or, if you start the simulation from the dircetory C:\HBGC123D\simulationsTracerTransport\tracer.in
Under a UNIX system, the equivalent would be e.g.
/home/users/smith/HBGC123D/simulations/TracerTransport/tracer.in
or, if you start the simulation from the directory/home/users/smith/HBGC123D/simulations
TracerTransport/tracer.in
All input and output files can reside in different directories.
We are currently developing a Java-based interface for HBGC123D. At this point, the interface has limited capabilities for preparing the HBGC123D input file and postprocessing the output (special version of HBGC123D required). Please see the GUI page for details.
Q: Which additional software is necessary to run HBGC123D?
A: If you need to change the size of allocatable memory (see below), you need a standard Fortran 77 compiler to build the executable from the source code.
If you want to use a transient flow field, you will need another program (e.g. FEMWATER) to produce these data. FEMWATER/3DFEMWATER was developed at Pennsylvania State University. An executable version for DOS is available at the U.S. Environmental Protection Agency (EPA).
Q: Is there a tool for postprocessing the output of HBGC123D?
A: We have developed a non-graphical postprocessor as an interface between HBGC123D and visualization software like Excel, Gnuplot, Surfer, and GMS. Please see the Postprocessing page for details.
Q: The program does not run due to incorrect input. How can I locate the error?
A: Unfortunately, there is no simple way to detect incorrect input. If an error occurs e.g. in data set 11, the real problem may be in data sets 2 or 10. Special attention is required when the number of components and/or species is changed. For instance, the user has to make sure that the number of components and kinetic species in data set 10 and the number of species in data set 17 are consistent. Changing the number of species also requires changing stoichiometry information in data sets 24 to 27 and changing indices of species in the reaction formulation (data set 29).
A: The pre-compiled executables of HBGC123D are designed to allow fairly large problems. (All sample problems need at most 30 % of the allocated memory.) However, if you want to run a simulation with a very large number of nodes and/or species, you have to increase the amount of allocatable memory. This is done by recompiling the code after increasing the values in the PARAMETER statements for the variables IMEMDIM and DMEMDIM in file "memcom.h".
Q: The program does not run under Windows. A message box appears that reads "Not enough memory in the swap file" (or a similar text). What can I do?
A: The pre-compiled executables of HBGC123D
are designed to allow fairly large problems. The attempted memory
allocation may exceed the capacities of your system. You may first
try to run HBGC123D after you have closed all other applications.
If this still does not help, you need to decrease the values
in the PARAMETER statements for the variables IMEMDIM and DMEMDIM
in file "memcom.h" and
recompile HBGC123D.
This problem occurred mostly with Version 1.0 of HBGC123D. We have
reduced the amount of allocated memory for the MS Windows version
of HBGC123D (release version 1.1). You may encounter this problem
if you have 32 MB of RAM or less and a small swap file.
Q: A run-time error occurred. What is wrong with the input?
A: First you should make sure that the setup of components and species is correct. The number of chemical species (NOMX + NOMY + NOMZ + NOMP, data set 17) has to be equal to the number of geochemical reactions (number of reactions with KRTYP(I) = 0 or 1 in data set 29). It should also be checked that the reactions are described correctly, including the stoichiometry information. It has to be consistent with the stoichiometry defined in data sets 24 to 27. Sometimes a numerical solution to the set of (bio)geochemical equations cannot be found. Under some circumstances, increasing the maximum number of iterations (NITERC in data set 22) or changing the convergence criterion (EPSC in data set 22) may help. You can also try again with a smaller time step (DELT in data set 3). This may be particularly helpful if you are simulating kinetic reactions with fast reaction rates.
Q: I cannot find any error in the input file, but the program does not run. Where can I get support? Could there be a bug in the code?
A: Unfortunately, due to limited resources we are currently not able to provide support. There were some minor bugs in the first versions of the public release of HBGC123D. Please see the page Known Bugs for details. These bugs are fixed now. If you use a version that is not affected by these bugs, you are encouraged to post your problem to the HBGC discussion forum. If you find a bug in the code, you are also encouraged to post it to the forum. It is appreciated if you additionally notify Dr. Gwo about any suspected bugs in the code.