GEMS3K is the numerical kernel of the GEM-Selektor v.3 package for geochemical modeling. It implements the improved GEM IPM algorithm with excellent mass balance precision and fast convergence to Gibbs energy minimum even in very complex non-ideal chemical systems with two-sided metastability constraints (more ...).
GEMS3K source code is written in C/C++. Using compiler directives, the code can be compiled as a standalone program 'gemcalc'; as a static or dynamic binary library for coupling with the mass transport simulator or another code; or as part of the GEMS3 code together with GEM-Selektor GUI.
Attention: GEM IPM numerical controls in this (v.3) program are not
compatible with those in GEM-Selektor v.2. Hence, any old modeling project
must be opened once in GEM-Selektor v.3 in the 'Remake' mode to reset the
numerical controls (correct results are not guaranteed otherwise!), and
GEMS3K I/O files then re-exported.
To do so, start GEM-Selektor; click on the 'Computation of Equilibria' button in the upper left corner; in the appearing dialog, turn on the 'Activate Project Remake Wizard' checkbox; select the project in the list of modeling projects, and click 'Open Project'. In the appearing 'Step 1 ...' page of the Project Wizard, 'Change pre-configured GEM IPM numerical controls' to 'Restore normal (standard) variant for fast convergence' or another suitable choice, and click 'Next >' twice. The new settings will be saved in the project record, so there will be no need to repeat this procedure when this project is opened next time. Exported GEMS3K input files will now have correct GEM IPM numerical controls.
The archive file has the name:
where <Rev#> is the trunk revision number. The archive contains a folder named 'standalone/'. Unpack it to a folder where another code to couple with GEMS3K, e.g. to 'DevCoupled/', in your home directory (under Windows, on C:\ or D:\ disk).
~/gitGEMS3
with a subfolder gitGEMS3/standalone
.~/gitGEMS3/standalone
and clone the repository from https://bitbucket.org/gems4/gems3k.git using
a pre-installed free git client SourceTree
(the best way on Windows). git clone https://bitbucket.org/gems4/gems3k.git .
~/gitGEMS3/standalone
,
and type in the command line:git checkout -b branches/devEJDB --track origin/branches/devEJDB git pull origin branches/devEJDB
To switch back to trunk, type
git checkout trunk
The Git repository of GEMS3K can also be viewed in any web browser at https://bitbucket.org/gems4/gems3k.git. To learn more about Git version control system, you may start here.
'standalone':
the "root" folder of installed GEMS3K source code. 'Docs': Documentation of GEMS3K code and examples in: 'doxy':
source code documentation in doxygen format HTML files
'html': HTML files describing the use of GEMS3K and programming examples. 'txt': text files with some supporting information. 'gemcalc': Folder with an example for the batch GEMS3K calculations. 'gemcalc.pro':
the Qmake project file.
'gemcalc-build':
Folder to build and test the gemcalc
executable file.'main.cpp': source code of the gemcalc example. 'GEMS3K': folder with GEMS3K source code *.cpp and *.h files. 'lib-gems3k': Folder to build or dynamic ('d') binary libraries of GEMS3K for linking with other codes. 'lib-gems3k-a.pro':
Qmake project file to build static
('a')
binary library.
'lib-gems3k-d.pro': Qmake project file to build dynamically linked ('d') binary library. 'doc':
additional documentation for this example.
'main.cpp' and 'main.h': source code files for the node-gem example. 'node-gem-pri' and 'node-gem.pro': Qmake project files for the node-gem example. 'platform': Make- and project files for specific platforms (incl. parallelization). 'node-gem-build': Folder to build and test the node-gem executable file. 'nodearray-gem': Folder with an example for coupling GEMS3K via TNodeArray (TBD). 'Tests': Folder with sets of GEMS3K input files for automatic testing of upgrades. 'Cases':
folder with subfolders each containing a set of input files
(TBD)
'Results': folder with subfolders containing results for the respective 'Cases' subfolders (TBD) |
For a better compatibility between different desktop platforms, we recommend using using Qt SDK (in Windows, with the MinGW port of the GNU C++ compiler and linker). This has two advantages:
Start QtCreator and open one of the Qmake projects in 'standalone\lib-gems3k\' folder ('lib-gems3k-a.pro' to build the library for static linking, or 'lib-gems3k-d.pro' to build a dynamically linked library). Use shadow building and do not use Qt Simulator. Switch to 'Projects' on the letf pane, and under 'General' 'Build directory' browse to set the build directory to 'standalone\lib-gems3k\', e.g. where the Qmake project file is located. Then change to 'Edit' mode. In the "Build" menu, select first "Run qmake"; this will generate Makefile for this particular desktop platform and the chosen debug or release mode. Now, run "Build" "Build project..." menu command. This will build the library.
In
Windows, the GEMS3K library will have the file name 'gems3k3.dll';
for linking with other programs, the file
'libgems3k3.a'
is also generated. The
files can be found in the 'standalone\lib-gems3k\debug\'
or 'standalone\lib-gems3k\release',
depending on what
was selected for building. Remember that for correct execution on
Windows, three MinGW libraries must be present in the same folder where
the executable file containing GEMS3K or linking to it is present. These
are
"libgcc_s_dw2-1.dll"
, "libstdc++-6.dll"
and "libwinpthread-1.dll"
. For
copying,
you can find them in C:\Qt\Tools\mingw530_32\bin\
folder
(of currently availaible version of Qt5 toolkit).
In
Linux, the dynamically linked library will be called 'libgems3k.so.<v>.<sv>.<ssv>'
and also symlinks to it: 'libgems3k.so.<v>.<sv>',
'libgems3k.so.<v>',
'libgems3k.so'
will be created. Here, <v>
stands vor a version (e.g. 3), <sv>
for a sub-version (e.g.1), and <ssv>
for a sub-sub-version (e.g.2) numbers. The statically linked library
will be called 'libgems3k.a'.
All libraries will be located in the 'standalone\lib-gems3k\'
folder.
In
Mac OS X, the
dynamically linked library will be called 'libgems3k.<v>.<sv>.<ssv>.dylib'
and also symlinks to it: 'libgems3k.<v>.<sv>.dylib',
'libgems3k<v>.dylib',
'libgems3k.dylib'
will be created. Here,
<v>
stands vor a version (e.g. 3), <sv>
for a sub-version (e.g.1), and <ssv>
for a sub-sub-version (e.g.2) numbers. The
statically linked library will be called 'libgems3k.a'.
All libraries will be located in the 'standalone\lib-gems3k\'
folder.
A most recent
addition to the build system of GEMS3K was a collection of cmake files
(not on Windows). Building with cmake
also allows installing GEMS3K as dynamic and static libraries into /usr/local/lib
and corresponding headers - into /usr/local/include
. This
facilitates linking GEMS3K library to various codes that can be coupled
with it. To build GEMS3K with help of cmake utility, do the following.
In terminal, go to
your standalone/
folder and run the commands:
mkdir build
cd build
cmake ..
make
sudo make install
To link another C++ code with the GEMS3K library, the INCPATH and LIBS lists of variables in the Makefile must be set to contain correct paths to GEMS3K C++ include (*.h) files and to the GEMS3K library, respectively (this is not needed if you have built and installed GEMS3K library using cmake, as described above).
We recommend that the source code of the program to which the GEMS3K code will be coupled is located in a folder at the same level as the 'standalone/GEMS3K/' or 'standalone/lib-gems3k/' folders. For example, the directory tree may look like
/home/<me>/MyRMTCode/trunk/Coupled/build/MakefileHere, <me>
is the actual user name. The source code of GEMS3K, including headers,
is located in 'standalone/GEMS3K/',
and the (static)
pre-compiled library to link with is located in 'standalone/lib-gems3k/'
folder. The complete MyRMTcode application will be built in the 'Coupled/build/'
folder, by compiling source codes from 'Coupled/src/'
and 'MTcode/src/'
folders, then linking them with the GEMS3K library.
To do this, the myrmt.pro
file must contain the following declarations:
In the
qmake-generated Makefile, this should result in the
INCPATH
variable containing a parameter "-I../../../standalone/GEMS3K",
and in the LIBS
variable containing the parameters -L/home/<me>/MyRMTCode/trunk/standalone/lib-gems3k
and
-lgems3k.
The coupled code executable will be built in the 'Coupled/build/' folder.
Start the QtCreator and open one a Qmake project file 'standalone/gemcalc/gemcalc.pro'. Use shadow building; do not use Qt Simulator and QML debugging. Switch to 'Projects' on the left pane, and under 'General' 'Build directory', browse to set the build directory to 'standalone/gemcalc-build'. Then change to 'Edit' mode of QtCreator. In the "Build" menu, select first "Run qmake"; this will generate Makefile for this particular desktop platform and the chosen debug or release mode. Now, run "Build" "Build project..." menu command. This will build the gemcalc executable file in the 'standalone/gemcalc-build' folder (under Windows, either in 'standalone\gemcalc-build\debug' or in 'standalone\gemcalc-build\release' folder).
To launch the gemcalc example in the terminal, cd into 'standalone/gemcalc-build' and use the appropriate batch file, e.g. 'linux-run.bat' on linux. The GEMS3K input data files are located in the 'tp_test' subfolder. The example program will produce two output files in that folder, plus two log files in the 'standalone/gemcalc-build' folder.
You can run the example program also from QtCreator. To do so, open the 'Projects' window and switch there to 'Run settings'. In the 'Arguments' line, enter the same command line arguments as those in the batch file variant for the respective OS. To simply execute the program, click on the 'Run' button in the leftmost toolbar pane. To observe how the program works, click instead the 'Start debugging' button below the 'Run' button. Before doing that, it is advisable to open the 'main.cpp' file and set there a breakpoint.
Start the QtCreator and open one a Qmake project file 'standalone/node-gem/node-gem.pro'. Use shadow building; do not use Qt Simulator and QML debugging. Switch to 'Projects' on the left pane, and under 'General' 'Build directory', browse to set the build directory to 'standalone/node-gem-build'. Then change to 'Edit' mode of QtCreator. In the "Build" menu, select first "Run qmake"; this will generate Makefile for this particular desktop platform and the chosen debug or release mode. Now, run "Build" "Build project..." menu command. This will build the node-gem executable file in the 'standalone/node-gem-build' folder (under Windows, either in 'standalone\node-gem-build\debug' or in 'standalone\node-gem-build\release' folder).
To launch the gemcalc example in the terminal, cd into 'standalone\node-gem-build' and use the appropriate batch file, e.g. 'linux-run.bat' on linux. The GEMS3K input data files are located in the 'tp_test' subfolder. The example program will produce one output file and perhaps one log file (with IPM warnings and error messages) in the 'standalone\node-gem-build' folder.
You can run the example program also from QtCreator. To do so, open the 'Projects' window and switch there to 'Run settings'. In the 'Arguments' line, enter the same command line arguments as those in the batch file variant for the respective OS. To simply execute the program, click on the 'Run' button in the leftmost toolbar pane. To observe how the program works, click instead the 'Start debugging' button below the 'Run' button. Before doing that, it is advisable to open the 'main.cpp' file and set there a breakpoint.
You are welcome to modify the examples and observe the effects of modification.