# GEMS Documentation

GEMS is the GEneral Microspeciation Solver. It is aimed at solving acid-base microspeciation equilibria from NMR and spectroscopic data. It is

- Open Source
- Multiplatform
- Free
- Fast

## Installing and Running GEMS

### Installing

GEMS is a python script which needs numpy and scipy to run. Optionally you can have matplotlib for graphs.

You will need

- python 3
- numpy
- scipy
- Optionally matplotlib

### First run

If you execute the command gems.py -h the usage text will show

    usage: gems.py [-h] [-s MOLECULE] [-f FILE] [-p] [-o ORDER] [-w FILE]

    GEMS: The GEneral Microspeciation Solver v0.5

    optional arguments:
      -h, --help            show this help message and exit
      -s MOLECULE, --symmetry MOLECULE
                            display information on the molecule
      -f FILE, --fit FILE   load data in file and start computation
      -p, --plot            display window with plots
      -o ORDER, --order ORDER
                            order of interactions to fit
      -w FILE, --write FILE
                            write results in numpy array for later use

### Fitting NMR data

When run with the -f FILE option, the contents of the file FILE is loaded and fed into the program and fitted. The contents should conform to the format specified in Data File Format.

## Data File Format

GEMS can load text files containing data in the following format:

- LINE1: A title. This line is an identifier. It is ignored.
- LINE2: The symmetry of the molecule.
- LINE3: List of numbers that will be used as initial values for iteration.
- LINE4: A list of space-separated labels of each one of the nuclei
- LINE5 to the end: The pH (or pD) value of this point followed by the NMR shift
    of each one of the nuclei. If some data is missing, those numbers can be replaced with an X.

Input File Example

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    Title example. This is ignored.
    A2B
    10.4 3.0 1.0
           Cpy2     Cpy3     Cpy4     C1      C2      C3      Hpy3   Hpy4   H1     H2      H3
     0.10  143.606  127.528  153.092  45.773  52.189  45.773  7.637  8.079  4.739  3.700  3.700
     1.05  143.515  127.284  152.999  46.436  52.319  46.036  7.617  8.067  4.712  3.604  3.583
     1.80  143.082  126.317  152.628  48.273  52.182  46.752  7.543  8.018  4.663  3.383  3.248
     2.82  142.649  125.390  152.261  50.045  52.234  47.385  7.474  7.974  4.625  3.180  2.958
     4.01  142.563  125.209  152.190  50.379  52.237  47.499  7.463  7.966  4.618  3.141  2.905
     4.89  142.528  125.167  152.158  50.368  52.207  47.477  7.468  7.971  4.624  3.145  2.911
     6.08  142.461  125.098  152.132  50.310  52.160  47.428  7.479  7.982  4.633  3.155  2.915
     6.58  142.445  125.077  152.204  50.289  52.171  47.432  7.478  7.981  4.630  3.156  2.917
     7.02  142.425  125.046  152.390  50.253  52.215  47.459  7.473  7.977  4.622  3.155  2.916
     7.44  142.373  124.977  152.727  50.186  52.298  47.508  7.465  7.970  4.604  3.152  2.915
     7.81  142.304  124.873  153.342  50.076  52.449  47.600  7.447  7.955  4.570  3.145  2.910
     8.28  142.129  124.615  154.880  49.804  52.813  47.825  7.408  7.921  4.491  3.134  2.901
     8.81  141.817  124.167  157.374  49.346  53.422  48.199  7.340  7.862  4.356  3.113  2.884
     9.74  141.396  123.583  160.789  48.763  54.261  48.726  7.251  7.783  4.174  3.077  2.843
    12.11  140.850  123.824  162.032  49.860  55.118  49.771  7.235  7.707  3.956  2.798  2.019

See also

`gems.libio.load_file`

## Interpreting the output

Bear in mind that GEMS is a least-squares minimisation algorithm. In order to have meaningful results you have to be careful with the data you feed the program with and analyse carefuly the output provided.

GEMS provided a verbose output with lots of information that will help you to interpret what happened inside.

### Refinement result

After the optimization ends, the refined parameters are shown with the calculated errors. They are displayed in order.

The correlation matrix shows how the refined parameters are related to each other. A good model should show a low correlation between the parameters. If some parameters show high correlation it usually means that the model is oversized.

### Microstates and Microsteps Analysis

For each one of the macrostates, the possible microstates are shown. For each one of the microstates, the refined free energy F with error is shown along with the calculated population of that microstate.

### Calculated Macroconstants

The macroconstants are displayed. These numbers represent the protonation (or deuteration) equilibria.

## Indices and tables

- Index
- Module Index
- Search Page

- Tutorials
  - Tutorial 1. Using GEMS from command line
    - Command line options
  - Tutorial 2: Obtaining information based on molecule symmetry
- Algorithm Details
  - Microstate Nomenclature
  - Cluster Expansion
  - Symmetry Simplification
  - Theoretical Background
  - Algorithm Implementation
  - References
- Public GEMS API
  - variable definition
    - Free Energy
    - Microstate
    - Microstate Probability
    - Macrostate Probability
    - Conditional Probability
    - Molecule Symmetry
    - A Matrix
    - B Matrix
    - Delta Matrix
  - libuk.py
    - Microstates Nomenclature
    - Functions for Multiplicity and Combinatory
    - Terms calculations
  - report.py
  - fit.py
  - plotter.py
    - Plotting functions with pyplot
    - Plotting functions in Axes
    - Auxiliary plotting functions
  - libio.py
- GEMS Changelog
  - Version 0.7
  - Version 0.6
  - Version 0.5
  - Version 0.4
  - Version 0.3