GEMS3K Technical Information 

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.

How to install the GEMS3K source code

Variant 1. Download the archive from this web site

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).

Variant 2. Check out from our Git repository on Bitbucket:

• In your home directory, make a folder named e.g. ~/gitGEMS3 with a subfolder gitGEMS3/standalone.
• Change into ~/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). 
• Alternatively, on Mac OSX or linux, open a terminal and use a command below (do not forget a period) to download the actual "trunk" branch:

git clone https://bitbucket.org/gems4/gems3k.git . 

• To switch to another branch (e.g. devEJDB), use a git client or open a terminal, cd to ~/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.

The 'standalone' folder structure

'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. 'main.cpp': source code of the gemcalc example. 'gemcalc-build': Folder to build and test the gemcalc executable file. '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. 'node-gem': Folder with an example for coupling GEMS3K with mass-transport at TNode level. '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)

How to compile the GEMS3K library for linking within a coupled code

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: 

• QtSDK contains Qmake - a utility program that generates Makefiles for the particular platform from very compact and simple Qmake project files.
• QtSDK contains the QtCreator IDE, with a convenient source code editor, and an efficient GNU Debugger frontend.

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

How to link the GEMS3K library into a coupled code

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

Here, <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. 

How to build and run the "gemcalc" example

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.

How to build and run the "node-gem" example

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.