+A  Click here to enlarge/reduce to/back from full screen 
Paul Scherrer Institut PSI GEM Software (GEMS) Home

Paul Scherrer Institut
5232 Villigen PSI, Schweiz/Switzerland
Tel. +41 56 310 21 11
Fax. +41 56 310 21 99



Updated:
19.04.2015
E-Mail: gems2.support@psi.ch


Printer Friendly Printout without Logo or Navigation Elements available here... just click and print

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 GEMS-Vizor 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:

GEMS3K-src-r<Rev#>.zip 

where <Rev#> is the trunk svn 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 the SVN repository mirror

<under construction>
Using the command line
svn checkout command or a SVN client, check out the trunk into 'DevCoupled/standalone/' folder in your home directory.

The 'standalone' folder structure

doc/img/Dir-standalone-structure.png
'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 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 very convenient source code editor, and an efficient Python-based 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, only the dynamically linked library can be built; it 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.

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.


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.

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/Makefile
                                  /conf/myrmt.pro
                          /Coupled/src/
   
                          /MTcode/src/
                          /standalone/lib-gems3k/
                                     /GEMS3K/

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:

DEFINES += IPMGEMPLUGIN
DEFINES += NOPARTICLEARRAY

Coupled_CPP
= ../../src
MTcode_CPP = ../../../MTcode/src
GEMS3K_CPP = ../../../standalone/GEMS3K
GEMS3K_LIB = /home/<me>/MyRMTCode/trunk/standalone/lib-gems3k

Coupled_H
= $$Coupled_CPP
MTcode_H = $$MTcode_CPP
GEMS3K_H = $$GEMS3K_CPP

DEPENDPATH += $$Coupled_H

DEPENDPATH += $$MTcode_H

DEPENDPATH += $$GEMS3K_LIB


INCLUDEPATH += $$FIT_H

INCLUDEPATH += $$GEMS3K_H
INCLUDEPATH += $$GEMS3K_LIB
<other third-party include paths, if any>

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.


Last updated:  20. 12. 2012

Copyright (c) 2003-2012  GEMS-PSI Development Team.