GEMS3K Code for Solving for GeoChemical Equilibria

GEM Task Data Structure and IPM-3 Kernel Module

Contents

1. The Gem Task (Multi) Data Structure 

2. The GEM Algorithm and IPM-3 Kernel Module

2.1. Stage 1: AIA Procedure

2.2. Stage 2: MBR Procedure

2.3. Stage 3: IPM Descent Procedure

2.4. Stage 4: PSSC Procedure

3. Numerical Settings  to Control GEM IPM-3 Module Operation

4. Warnings and Error Messages

1. The GEM Task (Multi) Data Structure

The GEM Task ("Multi") data structure is dynamically allocated in computer memory and keeps all scalars and arrays containing input, work and output data of the GEM IPM-3 algorithm used in calculation of an equilibrium state. Within the GEM-Selektor code, contents of the Multi structure can be exported into GEMS3K input files and then used in standalone coupled code calculations. In the standalone GEMS3K program, the Multi data structure is created and filled out by reading DCH and IPM input data files; it remains intact during the whole runtime of GEMS3K instance.

This manual provides a short overview of the GEM algorithm and IPM-3 kernel program, the main work data in the Multi structure accessible in Multi: window pages, and describes the numerical settings that control the operation of the GEM IPM-3 algorithm.

There are two main modes of operation of GEM IPM-3 kernel: the "automatic initial approximation" mode (AIA) and the "smart initial approximation mode" (SIA). In GEMS3K, the operation mode can be set before every call of GEM calculation. 

The AIA mode always uses the LP simplex procedure to get initial approximation of the GEM primal solution. In this mode, the MBR and IPM algorithms do more iterations, but require no a priori information about the stable phase assemblage and equilibrium speciation in the system.

The SIA mode needs a previous GEM task solution for the same setup of chemical system because it avoids the LP simplex step. In most cases, GEM IPM converges rapidly in this mode with a 10-20 times gain in computation speed. However, there is no guarantee that the previous GEM task result is a good initial approximation for a system with changed bulk composition, temperature, pressure, or metastability constraints. There is no universal criterion to check this before performing the whole GEM IPM calculation; at every step, it may turn out that the initial approximation was bad, leading to inconsistent results or to divergence in IPM or MBR numerical algorithm. At any such error condition, the program will automatically switch to the AIA mode for this task only. If the mode was already AIA, the GEM IPM calculation is stopped and an error message is generated (more...).

2. The GEM Algorithm and IPM-3 Kernel Program

The operation of GEM IPM-3 module proceeds in four (AIA mode) or three (SIA mode) main stages, as shown on the flow chart (from Kulik D.A., Wagner T., Dmytrieva S.V., Kosakowski G., Hingerl F.F., Chudnenko K.V., Berner U. (2012): GEM-Selektor geochemical modeling package: Numerical kernel GEMS3K for coupled simulation codes. Computational Geosciences (in press), http://dx.doi.org/10.1007/s10596-012-9310-6).

To start calculations, the GEM Task data structure must be correctly filled out with input data (BCC etc.), including a feasible initial approximation (FIA) of the GEM primal solution.  FIA is the speciation (i.e. amounts of Dependent Components) that is compatible with the equilibrium phase assemblage, mass balance and metastability constraints, and is close enough to the Gibbs energy minimum so that the IPM algorithm can reach it and not another (local) minimum in a strongly non-ideal system. If FIA is available e.g. from a previously computed equilibrium state in a similar system, the AIA procedure can be skipped, and calculation proceeds in "Smart Initial Approximation" (SIA) mode. Otherwise, the IPM-3 algorithm begins from the AIA procedure in the "cold-start" Automatic Initial Approximation (AIA) mode.    

Stage 1: AIA Procedure

An automatic initial approximation (AIA) must be used in all cases when the stable phase assemblage or the redox state is going to be (very) different from the previously computed equilibrium state, or if the latter is not available. In the generic non-linear GEM problem is first truncated into a LP (linear programming) subproblem
by cutting off the concentration and activity coefficient terms in chemical potential expressions for all dependent components. In this case, each dependent component (species) is treated as a separate pure phase. This LP sub-problem is then solved using a modified simplex algorithm with two-side (metastability) constraints. There are two controls - Pa_EPS[0] and Pa_GAN[1] - that influence the precision and the result of the Simplex calculation, respectively.

The GEM calculation is completed at this point, if no solution phases (having two or more dependent components) are present in the chemical system definition. Otherwise, the original non-linear GEM problem is restored, and the "Fill-out" step is applied. This step ensures that no thermodynamically stable phases and species will not be eliminated from the final GEM result, even though their amounts were set to zeros after simplex LP calculation. The program goes through the whole primal solution approximation vector and checks each element against the respective Pa_DFY value. If the data element contains a value equal or greater than Pa_DFY then it remains unchanged; otherwise the Pa_DFY value is inserted.

Note that this Fill-out procedure makes the mass balance precision worse and its improvement within the MBR procedure mandatory. Too large insertion constants in Pa_DFY can result in MBR algorithm failure, whereas some DCs can be lost upon GEM IPM descent iterations after too small fill-out insertions.  

Stage 2: MBR Procedure

In order to obtain a FIA before starting the main IPM descent loop, the mass balance precision must be checked and improved, if necessary (especially in the AIA mode). This is done within the MBR (Mass Balance Refinement) procedure that iteratively adjusts some DC amounts in such a way that the approximation remains in the feasible domain, until any mass balance residual for i-th IC does not exceed a small value b_i* Pa_DHB. The MBR algorithm tries first to adjust larger amounts of DCs, if possible. MBR iterations are sensitive to several tolerances - Pa_DHB, Pa_DFY, Pa_DPV - which also define the final precision of GEM IPM results. 

Stage 3: GEM IPM Descent Procedure

After successful convergence of MBR, The Main IPM Descent procedure iteratively adjusts both the primal and the dual solution vectors, while trying to decrease the total Gibbs energy function of the system G(X). At each iteration, first the descent-direction vector is obtained, then the optimal step length is estimated, and finally the primal solution approximation is corrected by adding products of descent direction (gradient) and step length for each DC.

Optionally, after each IPM iteration, the dual solution approximation (vector u) can be checked for divergence (as controlled by Pa_LLG tolerance). This check actually compares how chemical potentials of ICs vary between IPM iterations. In well-posed chemical systems, such variations occur rather monotonously, whereas in an ill-defined system (e.g. with respect to redox state), some chemical potentials may change erratically because there is not enough internal constraints to fix them. In this case, the Divergence Detector issues a warning; further IPM iterations will not improve but worsen the GEM task results.

The minimization problem is considered as solved, when the calculated value of the Dikin convergence criterion CD becomes smaller than the Pa_DK tolerance, and the maximum allowed total number of IPM iterations Pa_IIM is not yet exceeded. At each IPM iteration, the CalculateActivityCoefficients() subroutine is called to update DC activity coefficients (and optionally electrostatic terms) in multi-component phases. This calculation  is controlled by Pa_AG, Pa_DGC, Pa_PRD settings. In the course of IPM iterations, some phases and components can be eliminated (zeroed-off), if their quantities become smaller than the respective tolerances in Pa_DS and Pa_XMI fields. Changing these tolerances beyond recommended limits can strongly affect IPM convergence and precision of GEM IPM calculation results.

Stage 4: Phase Selection Procedure

After convergence of the Main IPM descent, the control goes to the PSSC (Phase Selection and Speciation Cleanup) procedure that calculates stability criteria for all species and phases, and checks whether some phases have been lost from the x and Xa vectors and must be restored. If this was the case, the control will go back to MBR Procedure; the whole loop can be repeated up to up to five times. Behavior of the PSSC() algorithm mainly depends on the Pa_PC and Pa_DF controls.

In addition, the mass balance precision of the GEM IPM result is analyzed using the Pa_DHB, Pa_GAN, Pa_DPV controls. For each multi-component phase present in non-zero amount, the amount of each DC with trivial metastability constraints is checked for consistency with dual solution (see Pa_GAN[2] and Pa_PRD[1] tolerances). If an inconsistency is found, it will be corrected and, if the correction is too strong, the control goes to MBR Procedure again.

3. Numerical Settings to Control GEM IPM-3 Module Operation

The data objects listed below control the operation of GEM IPM-3 kernel program. For the GEMS3K standalone code, these settings can be changed in the IPM input file. Such a file is usually exported from a chemical system definition created within the modeling project in the GEM-Selektor package. 

For the standalone GEMS3K program, the numerical settings read from the IPM input file remain valid for the whole duration of the GEMS3K instance in computer memory. If some entries are not present in the IPM file, they will be set to default values, shown on this screenshot from GEM-Selektor code:

Note that usually, there is no need to change default numerical settings. The default values given below correspond to aqueous systems of 1000 total moles of independent components in the internal Multi b vector; re-scaling from-to actual BCC occurs automatically within the IPM-3 kernel program. Ad-hoc changes of the IPM-3 numerical controls, especially setting them beyond the indicated validity intervals, may cause the program to crash, freeze, or produce meaningless results. However, some controls must be adjusted for certain types of systems.

Pa_DB - Tolerance for minimum mole amount of Independent Component in the b vector { 1e-17 }

  

This cutoff number of moles of IC is used in calculation of the input bulk chemical composition BCC (vector b) of the chemical system to be solved for the equilibrium state the using the GEM IPM-3 kernel.

In the GEM-Selektor CSD setup recipe calculation, if the calculated mole amount  b_i  of i-th Independent Component is less than Pa_DB, this IC will be automatically turned off in the CSD and excluded from the (compressed) GEM task data structure.

In the GEMS3K program, it is checked that any element b_i  of the input BCC (b) vector is greater than or equal to Pa_DB tolerance; if not, this b_i  will be set to Pa_DB value, the warning W20IPM will be issued, and the GEM calculations will continue. 

Possible values: 1e-8 to 1e-20, default 1e-17 mol.

Related warning: W20IPM.

Pa_DS - Tolerance for minimum mole amount of stable pure phase present in GEM primal solution {1e-20}

  

The GEM IPM algorithm will automatically eliminate (zero off) the mole amount of any pure (single-component) phase in Xa vector, including all its species in the primal solution vector x, if current total number of moles of DCs in this phase becomes less than Pa_DS .

Possible values: 1e-8 to 1e-30 mol, recommended is 1e-20 mol (default).

Related  error:  E13IPM.

The IPM elimination criteria for special cases (multi-component phases of different kinds and their species) are given as Pa_XMI  tolerances described below.  

 

Pa_XMI[0] -  Mole amount tolerance for water-solvent at aqueous phase elimination{ 1e-13 }

 

The aqueous electrolyte phase will be eliminated (zeroed off) if the amount of water-solvent goes below this tolerance.  Possible range: 1e-8 to 1e-30 mol.

 

Pa_XMI[1] - Mole amount tolerance for the solid sorbent at sorption phase elimination { 1e-13 }

 

The sorption phase will be eliminated (zeroed off), if the amount of solid sorbent goes below this tolerance. Possible range: 1e-8 to 1e-30 mol.

 

Pa_XMI[2] - Mole amount tolerance for elimination of solute (sorbate) species { 1e-33 }

  

This value defines, which DCs in multi-component phases will be excluded from the the L_S  set (see Karpov et al., 1997). Any element x_j in the GEM primal solution approximation with the amount below this tolerance will be set to zero.  

Possible values: 1e-17 to 1e-99;  default value is 1e-33 moles.

Setting this tolerance to lower values (1e-60 and less) may be necessary, if some minor species with general activities (lga) in the range 1e-10 - 1e-15 have zero amounts in the phase present in a significant amount in equilibrium state. This means that these species were eliminated at some early iterations of IPM and have not been restored in the Speciation Cleanup procedure (perhaps because it has been deactivated).

Pa_XMI[3] - Mole amount tolerance for elimination of solution phases other than aqueous { 1e-20 }

 

This value defines, which non-aqueous multi-component phases will be excluded from the mass balance if their amounts in the Xa vector fall below this tolerance after some IPM Main Descent iteration.

Possible range: 1e-8 to 1e-30 mol, recommended is 1e-20 mol (default), the same as in Pa_DS.    

 

Pa_XMI[4] - Tolerance for the effective molal ionic strength to calculate aqueous activity coefficients { 1e-5 }

  

Calculation of activity coefficients of aqueous species is performed only when the effective molal ionic strength IS is not less than this value.

Otherwise, the internal activity coefficients will be set to 1.0 regardless of  the used aqueous model.

Possible range: 1e-3 to 1e-10; default 1e-5.  

 

Pa_DHB - Maximum allowed relative mass balance residual for Independent Components { 1e-13 }

  

This tolerance defines a relative value of mass balance residuals for all independent components that must be reached in the Mass Balance Refinement (MBR) step and maintained by the Main IPM Descent step of the GEM algorithm. Actually, this is the tolerance for the convergence criterion of the MBR algorithm for entering the feasible domain of the initial approximation of GEM primal solution (more...) 

Possible values: 1e-10 to 1e-15, default is 1e-13 (for a system of 1000 total moles in BCC). 

Related error conditions: E02IPM;  W09IPM;  E10IPM.

 Exact application of this tolerance within the MBR procedure depends on the Pa_DPV[2] control parameter. Maximum allowed number of MBR iterations can be set in Pa_DPV[0]; reaction of the program on reaching this number of iterations is defined by a flag in Pa_DPV[1].   

Pa_DFY[0] - Insertion mole amount for water-solvent in the AIA Fill-Out procedure { 1e-5 }

    

This and following controls are used in the Fill-Out procedure, which is applied immediately after obtaining the AIA LP simplex initial approximation y of the GEM primal solution (more...).  Separate insertion constants may be applied to components of certain phase types (see below). 

This must be done because to obtain a LP simplex initial speciation, each Dependent Component is temporarily considered as a separate pure phase; according to Gibbs phase rule, the number of non-zero quantities of such phases in isobaric-isothermal equilibrium cannot exceed the number of Independent Components.

In a real chemical multi-system containing aqueous and several other multi-component phases, much more dependent components may be present in positive quantities at equilibrium, but it is not known at the beginning, which of them will be present in significant amounts.

For this reason, the Fill-Out procedure is applied on each element of the y vector: If  y_j  <  Pa_DFY then  y_j  is set equal to Pa_DFY. This procedure actually violates the mass balance that must be improved in the MBR procedure to make sure that the initial appeoximation lies within the 'Fesible Domain'.

Magnitudes of Pa_DFY insertion values have a major impact on the convergence of the MBR procedure and on the whole GEM task calculation result.

Too low values may lead to missing solution phases or some components in them, which may render the GEM task solution infeasible.

Too large Pa_DFY values may prevent MBR algorithm convergence and cause persistent  errors  E04IPM or E05IPM.

Possible values: 1e-4 to 1e-7, default is 1e-5 (for a system of 1000 total moles in BCC).   

 

Pa_DFY[1]  - Insertion mole amount  for aqueous species in the AIA Fill-Out procedure { 1e-5 }

  

Pa_DFY[2] - Insertion mole amount for species of ideal solutions in the AIA Fill-Out procedure { 1e-5 }

  

Pa_DFY[3] - Insertion mole amount for a major species in a solution in the AIA Fill-Out procedure { 1e-5 }

  

Pa_DFY[4] - Insertion mole amount for a junior species in a solution in the AIA Fill-Out procedure { 1e-5 }

  

Pa_DFY[5] - Insertion mole amount for a single-component phase in the AIA Fill-Out procedure { 1e-5 }

  

 

Pa_DFY[6] - Insertion mole amount for a single-component phase in the PhaseSelection procedure { 1e-7 }

 

In the Phase Selection procedure (more...), a phase can be detected that is not present in positive amount in Xa vector, but shows a significant positive value of the phase stability criterion in the Fa vector.  In this case, the amounts of all DCs components will be set to this insertion value, and the control goes to MBR procedure and then again to the main IPM Descent algorithm.  Because the primal solution is very close to reality in this case, much lower insertion constants will be tolerated in comparison with the AIA Fill-Out procedure.

   

Pa_EPS[0] - Tolerance of the mass balance for the LP simplex solver convergence { 1e-10 }

  

This criterion defines the desired absolute mass balance precision for the LP simplex calculation of the automatic initial approximation (AIA).

Too low tolerances may cause persistent E01IPM errors.

Possible values: 1e-7 to 1e-14, default is 1e-10 (for a system of 1000 total moles in BCC).

Usually there is no need to adjust this tolerance.   

 

Pa_EPS[1] - Tolerance for calculation of the surface activity coefficient terms (SACT) for surface species { 1e-3 }

  

This is an experimental value for smoothing the stiff numerical behavior of SACT at high surface coverages.

In most cases, the value between 1e-4 and 1e-2 should be sufficient (under construction). 

Pa_GAN[0] - Fictive activity coefficient for a major (M) species in a solution phase, used only in AIA LP simplex calculation  { 1 }

 

This value can usually be set to 1. 

Possible values: 0.0001 to 1.

See also comments for Pa_GAN[1] below.

Pa_GAN[1] - Fictive activity coefficient for a minor (J) species in a solution phase, used only in AIA LP simplex calculation { 1000 }

  

The Pa_GAN[1] and perhaps Pa_GAN[0] controls are important for highly positively non-ideal solution systems that may potentially produce miscibility gaps (see "/Resources/doc/pdf/ActivityCoeffs.pdf" documentation file for details).

In this case, two or more phase definitions for a given solution model must be included in the system setup. The initial approximation must be chosen within the miscibility (single-phase) region for each possible phase. If the initial approximation is chosen in the middle of the miscibility gap, the GEM algorithm will converge to an incorrect metastable single-phase solution (the same as if only one solution phase definition would have been included in the system).

In the AIA mode, this means that some end members must be temporary made less stable at the step of LP simplex initial approximation. In the Phase definition and in the GEMS3K kernel program, this is achieved by denoting such end members as "junior" 'J', and those that should not be suppressed - as "major" 'M'. These codes result in automatic insertion of  ln(PA_GAN[1]) for 'J' and  ln(PA_GAN[0]) for 'M' end members into lngmf_ input data vector, then copied into the lngmf input data vector in the GEM task data structure.

 Before starting the LP simplex procedure, the molar Gibbs energy values G0 (in dimensionless ln a scale) of DCs are automatically corrected by adding the respective lngmf values. These corrections are automatically removed after the LP simplex calculation is finished, the mixing models are restored, and the control goes to Fill-Out and then MBR procedures.

Possible values:  10 to 100000, default 1000. 

 

Pa_GAN[2] -  Threshold for primal-dual normalized chemical potential difference used in Speciation Cleanup  { 1e-5 }

   

In all multi-component phases present in the primal solution in positive amounts, the Speciation Cleanup procedure compares the amounts of DCs in the primal solution vector x with their amounts restored using the dual solution vector u and DC chemical formula (more...).  The comparison is done by calculating the difference of primal (v) and dual (Fx) chemical potential (in dimensionless scale); if for j-th DC this difference is greater than this threshold, then the x_j value is replaced by that XU_j restored from the dual solution, if the correction is not too strong, e.g. log10(|XU_j - x_j|) does not exceed the Pa_PRD[1] threshold.

Possible values: 0.001 to 1e-7 (default 1e-5). See also Pa_PRD[1] control.                   

 

Pa_DG - Total number of moles used in internal re-scaling of the GEM task system { 1000 }

  

Most numerical settings of the GEM IPM algorithm must be slightly adjusted if the size (mass) of the system changes significantly. In order to allow more accurate settings that ensure the most stable optimal convergence of IPM, the GEM task is automatically re-scaled to total number of moles in the b vector equal to that given in this control setting. When the GEM IPM calculation is finished, the results (i.e. all extensive properties of the system, phases and components) are automatically re-scaled back to the original size of the system from the CSD. 

Possible values: 0.001 to 10000, default 1000.

At large Pa_DG values, take care that the amount of any DC after up-scaling  does not exceed 0.999999e6 moles (the trivial metastability constraint from above).  

Note that default values of other numerical settings in this document correspond to the default value of Pa_DG = 1000. If this value is changed, many settings may need to be re-adjusted to achieve optimal convergence and precision of GEM IPM algorithm.

Pa_DPV[0] - Maximal number of iterations allowed in the Mass Balance Refinement procedure { 130 }

 

This setting defines a maximum number of MBR iterations.

If the procedure did not converge until this control has been reached, the error condition E04IPM is activated, which declares that the IPM feasible domain cannot be entered at the requested mass balance accuracy, as defined by the Pa_DHB  threshold.

Most chemical systems require 1 to 6 iterations, but some systems with many non-ideal phases need 300 iterations or more.

Possible values: 10 to 1000, recommended value: 15, default value: 130.    

 

Pa_DPV[1] - Activate (1) of disable (0) the E04IPM error condition on maximum number of MBR iterations { 1 }

 If the error condition is activated (set to 1), and MBR procedure did not converge in Pa_DPV[0] iterations, the error E04IPM is issued and the GEM task calculation stopped, declared as failed.

If the error condition is disabled (set to 0) then the control goes to IPM Main Descent procedure, even if the MBR procedure did not converge properly, with the risk of the IPM Descent failure.  

 

Pa_DPV[2] - Mode for applying the tolerances to mass balance residuals in the MBR procedure { 0 }

This setting defines how relative mass balance residual tolerances (see Pa_DHB) will be applied to ICs present in large amounts in the BCC (b vector)  in the Mass Balance Refinement (MBR) procedure.

If this setting is 0 (default) then the MBR procedure will try to satisfy relative tolerances for all ICs mass balance residuals (Cb) regardless of their amounts in the b vector.

If this setting is +1 or -1 then Pa_DHB value will be interpreted as relative or absolute tolerance for the residuals. This means that MBR iterations continue if at least for one ICs except charge 'Zz', the residual exceeds Pa_DHB or exceeds b_i*Pa_DHB. Sometimes using this mode leads to better precision for major elements such as H, O, Si, Ca, Mg etc. in aquatic and rock systems. 

If this setting is +2, -2, +3, -3, ..., +12, -12 then the residuals are checked only against the absolute tolerance equal to 10^|Pa_DPV[2]|  instead of Pa_DHB. This corresponds to absolute criteria used in early versions of Selektor code.     

Possible values: integer, 0 (default); +1, -1 to +12, -12.

Related error conditions: W09IPM; E10IPM; E09IPM. 

   

Pa_LLG - Tolerance for checking divergence in the GEM dual solution between IPM iterations { 13000 or 0 (disable) }

 

In certain chemical systems, some chemical potentials are not well constrained by physically significant amounts of relevant chemical species. This leads to indefinite values of some IC chemical potentials in the dual solution vector u and numerically stiff behavior in GEM IPM iterations. The resulting IPM solution may strongly depend on the chosen values of numerical tolerances and on the parameters of smoothing (more...). Therefore, early detection of such divergence saves time and helps identify problems with the setup or composition of the system. The detection is performed within the Check-uDD algorithm, starting from 2nd IPM Main Descent iteration. The Check_uDD procedure actually monitors how strongly chemical potentials of ICs change between IPM iterations (more...) by means of calculating moving averages of u_i values over 3 IPM iterations for each i-th IC (see uc).

This tolerance is used for finding ICs that exhibit too large variations of chemical potential. There are two modes: one, set by negative value of Pa_LLG, checks that the absolute difference of moving average for this and previous IPM iteration is not greater than -Pa_LLG * Psi_DK[0]; another, set by positive Pa_LLG, checks that the absolute difference of moving average differences for iterations r (this), r-1 and r-2 is not greater than Pa_LLG * Psi_DK[0].

 If a divergence is detected then the symbol of IC is added to the list in the warning W14IPM, and the warning is issued after all ICs have been checked.

Possible values:

       0 - disables the divergence detection (in stiff systems, failure of GEM IPM algorithm may occur);

       32001 or -32001 - enables divergence detection in the respective mode, but blocks the warning message (to export data for plotting changes in the dual solution on IPM iterations at Pa_PRD[2] = 3);

       other values between 1 and 32000 or -1 and -32000 enable the divergence detection and warning W14IPM.

Default value: 13000.    

 

Pa_DF[0] - Tolerance DF for the stability index (logSI >= DF) or Karpov criterion (|Fa| >= DF) for a lost stable phase to be inserted { 0.01 }

  

This numerical tolerance is used after the main IPM descent in the Phase Selection procedure to check stability of all pure (single-component) phases absent from the system mass balance. A k-th phase is declared stable, if all its components have only trivial metastability constraints; its amount Xa[k] is greater than or equal to 0; its stability index Fa[k] is greater than 0 but less than or equal to Pa_DF[0].

If a phase has Xa[k] = 0 and Fa[k] > Pa_DF[0], this means that  this is phase is stable, but IPM has lost it from the mass balance. DCs in this phase will be inserted in Pa_DFY[6] amounts; after checking of all phases is finished, the MBR + IPM loop will be repeated up to 5 times. If the situation persists then the stability and/or stoichiometry of this phase has to be checked.

Recommended value: 0.01. In many internally consistent and non-stiff systems, a tighter tolerance of 0.001 can be used.

Related error conditions: W08IPM; E04IPM.  

 

Pa_DF[1] - Tolerance DFM for the stability index (logSI <= -DFM) for a present unstable phase to be eliminated { 0.01 }

  

This numerical tolerance is used after the main IPM descent in the Phase Selection procedure to check stability of all phases present in the system mass balance. A k-th phase is declared stable, if all its components have only trivial metastability constraints; its amount Xa[k] equals to 0; its stability index Fa[k] is less than -Pa_DF[1].

If a phase has Xa[k] > 0 and Fa[k] < Pa_DF[1], this means that  this is phase is unstable, but IPM did not eliminate it from the mass balance. Amounts of DCs in this phase will be set to zero; after checking of all phases is finished, the MBR + IPM loop will be repeated up to 5 times. If the situation persists then the stability and/or stoichiometry of this phase has to be checked.  

Recommended value: 0.01.

Related error conditions: W08IPM; E04IPM.  

 

Pa_DNS -  Default reference density of surface species at standard state { 12.05 nm^-2 }

  

 Set to 12.05 nm^-2 (as defined in Kulik, 2002) (under construction).

Pa_DK - Tolerance threshold for the Dikin criterion CD of IPM convergence { 3e-6 }

  

This tolerance (copied to Psi_DK[1]) is compared with the current value of Dikin criterion (Psi_DK[0]) at each IPM iteration in order to decide whether the IPM Main Descent minimization procedure has converged (more...).

Possible values: 1e-3 to 1e-9; values between 1e-6 and 1e-5 are recommended in most cases.

Too small tolerance (< 1e-7) may cause dramatic increase in the number of GEM IPM iterations or a non-convergence of the IPM algorithm.

Related error condition:  E06IPM.

The tolerance Pa_DK is given here for systems of approximately 1000 total moles in the BCC vector (see Pa_DG setting). The optimal Pa_DK value will be different for systems of significantly different size.

Pa_IIM  - Maximum allowed number of iterations in one GEM IPM Main Descent run { 7000 }

  

If this number is exceeded, the program assumes that IPM convergence is not achieved and the GEM task has failed. Possible values: 20 to 9999, default (recommended) value is 7000 (needed to resolve highly non-ideal systems in the vicinity of critical points).

Convergence of IPM also strongly depends on the selected Pa_DK tolerance value  and on the smoothing parameters (Pa_AG, Pa_DGC).

Usually in aquatic systems, the IPM algorithm converges in 20 to 130 iterations in the AIA (LP simplex automatic initial approximation) mode, or in 0 to 30 iterations in the SIA (smart initial approximation) mode, when a previous GEM IPM result for this system setup was used as an initial approximation.

Note that in the SIA case, the correctness of IPM results are not guaranteed if the input bulk composition or temperature were changed so that some new phases must appear in the equilibrium state.

The SIA mode uses a number of criteria and IPM error conditions to obtain a correct GEM IPM solution by automatically switching to AIA mode, whenever necessary.

Related error condition:  E06IPM.    

 

Pa_AG - Smoothing parameter AG for excess chemical potential increments (-1 to +1) { 1; -1.0 or 0.7 for adsorption }

  

In some highly non-ideal systems, the IPM convergence may not be achieved due to rather strong dependence of excess part of DC chemical potentials on the phase composition. Therefore, smoothing of the excess part (composed from ln(gamma) terms) may be necessary before adding it to the primal chemical potential. In GEM-Selektor, three smoothing functions are available.

One smoothing function uses the logarithmic distance between the current index of IPM iteration IT and the maximum allowed number of iterations IIM in Pa_IIM. This function has the form

        SF= DGC + ( AG - DGC ) / ( 1. + exp( log(1/IIM) - log(1/IT ) / DGC ) + exp( log( 1. - AG ) + log(1/IT) ).

This function will be invoked when Pa_AG <= -0.0001 and Pa_DGC > -0.0001 (internally, the sign of AG is inverted to positive). The SF (smoothing factor) value will be truncated to 1.0 if it exceeds 1.0. Example: set Pa_AG to -1 and Pa_DGC to 0.7.

Another smoothing function uses the logarithmic distance between the current Dikin criterion CD (Psi_DK[0]) and the convergence threshold given in Pa_DK.

       SF = DGC + ( AG - DGC ) / ( 1. + exp( log(DK) - log(CD) ) / DGC ) + exp( log( 1. - AG ) + log(CD) ).

The SF value will be truncated to 1.0 if it exceeds 1.0. This function is invoked when both Pa_AG and Pa_DGK are set less than -0.0001 (internally, both will have the sign inverted to positive). Example: set Pa_AG to -1 and Pa_DGC to -0.7; this gives very good convergence of IPM in systems containing  highly non-ideal solid solutions, even without global IPM refinement loops (see Pa_PRD[1]).

For both functions, Pa_AG should usually be set to -1.0. If |AG| is set less than 1.0 then the smoothing will effectively begin after several IPM iterations.

The third (old) smoothing function is retained mainly for surface complexation models with Langmuir-type surface activity coefficient terms. It has the form 

      SF = AG * ( 1 - pow(1-exp(-DGC*IT),60)).

If SF < 1e-6 then SF is set to 1e-6.  After ca. 50th iteration, the value of smoothing factor SF will be decreased down to 1e-6 more or less steep upon iterations, depending on the Pa_DGC value. This function is chosen when 0.0001 < Pa_AG < 0.9999 and 0.0001 < Pa_DGC < 0.1. Typical setting for adsorption models: Pa_AG = 0.7 and Pa_DGC = 0.07.

Setting Pa_AG to 1 and Pa_DGC to 0 disables smoothing.  Default value of Pa_AG is 1.0.

Related error condition:  E06IPM.   

 

Pa_DGC -  Smoothing parameter DGC - smoothing function exponent (-1 to +1) { 0; -0.9 or 0.07 for adsorption }

  

This empirical parameter controls how strongly the smoothing parameter (Pa_AG) will be decreased as function of the number of performed IPM descent iterations. Possible values: 

      0 (smoothing is disabled if also Pa_AG is set to 1);

      0.0001 to 0.9999 (or -0.9999 to -0.0001) to enable smoothing. 

Default value: 0. Too high or to low values may cause non-convergence of GEM IPM in highly non-ideal systems and especially in systems with sorption phases.

In some smoothing functions (see Pa_AG above), the DGC parameter defines the smallest value of the smoothing factor SF reached when the IPM Dikin criterion CD becomes equal to Pa_DK, or the number of IPM iterations IT approaches Pa_IIM.

In these cases, DGC should be set (in absolute value) between 0.0001 and Pa_AG. To invoke these new functions, just invert the sign of Pa_AG to negative (in the second function, also Pa_DGC to negative).

Attention: for surface complexation models, provisionally the old smoothing function with Pa_AG = 0.7 and Pa_DGC = 0.07 must be used.

Related error condition:  E06IPM.  

 

Pa_PE - Include electroneutrality condition? { 1 }

  

Possible values:

      1 - electroneutrality balance equation is included (required for systems containing aqueous electrolyte, adsorption or plasma);

      0 - charge balance is excluded from the GEM task formulation.

The program can change this flag automatically if e.g. the aqueous phase has been eliminated during the IPM descent iterations. 

  

Pa_PC - Mode of Phase Selection operation, old (1) and new (2) variants  { 2 }

 

This flag defines the behavior of Phase Selection procedure (more...) (disabled when this flag is set to 0).

     The new Phase Selection algorithm uses stability (saturation) indexes of phases (see also Pa_DF[0] and Pa_DF[1]) to check for consistency.

     The old mode uses Karpov f_alpha phase stability criteria to check phases for consistency (if Pa_PC is set to 1).

Default value: 2. 

 

Pa_PRD[0] - Mode of calculation of activity coefficients and metastability factors (2, 3) { 2 } 

  

Possible values (under construction):

     2 - at each MBR and IPM Descent iteration;

     3 - reserved.

This mode should be fixed to 2 in the present version of GEM-Selektor.

Pa_PRD[1] -  Decimal exponent for maximal DC amount correction in Speciation Cleanup { -5; 0 disables }

 

In all multi-component phases present in the primal solution in positive amounts, the Speciation Cleanup procedure compares the amounts of DCs in the primal solution vector x with their amounts restored using the dual solution vector u and DC chemical formula (see also Pa_GAN[2]). In the case of discrepancy, the x_j value is replaced by that XU_j restored from the dual solution, if the correction is not going to be too large, i.e. log10(|XU_j - x_j|) does not exceed the Pa_PRD[1] threshold. If ir does then x_j value is replaced by 10^Pa_PRD[1].

This tolerance is especially useful if the detection of divergence in the dual GEM solution is disabled (see Pa_LLG).

Possible values: from -7 to -3; default exponent is -5; 0 disables the Speciation Cleanup procedure.  

Pa_PRD[2] - Level of diagnostic messages: 0- disabled (no ipmlog.txt file); 1 - normal; 2 - with warnings; 3 - with uDD output { 1 }

 

This flag controls writing of the diagnostic information into the "ipmlog.txt" file (important for coupled codes that use the GEMS3K program). The file can be found in the work directory of GEMS executable or of the coupled code.

Possible values: 0-disabled: nothing is written in "ipmlog.txt" file;

1 - normal: only error codes and no warnings are written in "ipmlog.txt" e.g.as E04IPM: MBR();

2 - extended: both error messages and warnings will be written in "ipmlog.txt" as error codes and brief explanations, e.g. as E04IPM: EnterFeasibleDomain(): Maximum allowed number of Mass Balance Refinement iterations exceeded!;

3 - the same as 2 plus the trace output of triplicate dual solution values used in Dual Solution Divergence Detection (uDD) procedure (see also Pa_LLG). 

Default value: 1.

 

Pa_DKI - Tolerance for non-trivial metastability restrictions on amounts of Dependent Components, moles { 1e-10 }

  

This tolerance defines minimum allowed restriction from above (DUL) and minimum slackness between DUL and the restriction from below (DLL) if both set to the same value. The DLL value must be consistent with bulk chemical composition of the system.

For example, if total amount of Si in the system is 2 mol then DLL for quarts SiO₂ cannot be set to a value that exceeds 2 - Pa_DKI moles.

If DUL for a j-th DC is set to zero then the primal solution amount will be automatically set to x_j = 0.

If DUL for a j-th DC is set to any non-zero number less than Pa_DKI then the primal solution amount x_j will be less than or equal to Pa_DKI.

Possible values: 1e-8 to 1e-11.

Recommended value: 1e-10.

Related errors: E11IPM; E12IPM; E16IPM; E17IPM.

5. Warnings and Error Messages

Warnings (indicated by 'W') mean that the result of GEM IPM-3 calculation is conditionally valid, but not of the best quality, hence it must be used with precautions.

Most GEM-IPM error messages (indicated by 'E') have one of the following reasons:

• Bulk composition vector b is not well (charge) balanced
• Some DC stoichiometries are in error
• Some standard-state thermodynamic data for DCs are inconsistent
• Some relevant phases or DCs are missing from chemical system definition
• Some metastability constraints on DC are inconsistent
• Some numerical thresholds or tolerances are too tight
• The system is too small or too large (numerical settings are optimized for ca. 1000 moles in total in the BCC b vector)    

We recommend checking these issues before proceeding with further calculations.

E00IPM: SolveSimplex()    Inconsistent LP problem (negative UP[J] value(s) in START())

Very rare error in the LP simplex AIA procedure; may occur when some DLL metastability restrictions for DCs are incompatible with the system bulk composition.
 

E01IPM: SolveSimplex()    LP simplex solution cannot be obtained with required mass balance precision

This error in LP simplex AIA procedure usually shows that the Pa_EPS[0] tolerance for the mass balance is set too low; increase and try again.

If this tolerance is already set to 1e-6 mol or greater, this may be due to an inconsistent CSD or BCC; perhaps, invalid stoichiometry of some DC.

E02IPM: PSSC():    Mass balance is broken on iteration <It> for Independent Components <IC1> {, <IC2>, ... }

This error message occurs when, after corrections and cleanup of the primal solution x in Phase Selection or Speciation Cleanup procedures, some mass balance residuals in Cb vector exceed Pa_DHB * 1e10 or 0.01, whatever is less. Such mismatch usually occurs upon divergence in the GEM dual solution and cannot be improved in the MBR procedure, hence no GEM solution can be obtained for a given system defiition.

If this error occurs, try first to enable the detection of the divergence in GEM dual solution approximation (see Pa_LLG), and run GEM calculation again. If the W14IPM warning appears, this means that the system or bulk composition definition must be revised to ensure robust redox and alkalinity states (more...).

E03IPM: Mass Balance Refinement:   (MBR(<It>)):   Too small LM step size - cannot converge (check Pa_DG?)

This error occurs rarely if the mass balance precision tolerance Pa_DHB is inconsistent with the system size.

Check also Pa_DG setting.

E04IPM: Mass Balance Refinement:   (MBR(<CallPointID>)) Maximum allowed number of MBR iterations <Pa_DPV[0]> exceeded!

This error shows that the MBR procedure could not reach the requested mass balance precision, as defined by the Pa_DHB tolerance.

The <CallPointID> indicates from where the MBR procedure has been started: 0 - after the AIA LP simplex and Fill-Out procedure; 1 - at the SIA entry (skipped LP simplex and Fill-Out); 2 - after the pust-IPM Speciation Cleanup; 3 - after Phase Selection.

If this error condition occurs in SIA mode, the program automatically turns into AIA mode and starts the GEM calculation again without dispaying this error message. Other possible reasons:

E05IPM: Mass Balance Refinement:   (MBR(<CallPointID>))  Degeneration in R matrix (fault in SLE solver). Not possible to proceed.

Indicates problematic chemical system definition, inappropriate use of SIA mode, or divergence in GEM dual solution approximation (see Pa_LLG).

<CallPointID> indicates from where the MBR procedure has been started: 0 - after the AIA LP simplex and Fill-Out procedure; 1 - at the SIA entry (skipped LP simplex and Fill-Out); 2 - after the pust-IPM Speciation Cleanup; 3 - after Phase Selection.

If this error condition occurs in SIA mode, the program automatically turns into AIA mode and starts the GEM calculation again without dispaying this error message.

To fix the problem, check input chemical system definition and bulk chemical composition, and try again (in AIA mode).

E06IPM: IPM Main Descent:    IPM convergence criterion tolerance (Pa_DK) could not be reached (more than Pa_IIM iterations done)

This error indicates that the GEM task solution is incomplete because the Dikin criterion tolerance has not been reached. This can occur in some highly no-ideal systems with composition and temperature falling near critical points (then 6000 iterations or more can be necessary), or when strong smoothing is used (see Pa_AG).

In the AIA (LP simplex) mode, try increasing Pa_DK and/or Pa_IIM and run the GEM task calculation again. If this does not help then reconsider chemical system definition (or look for inconsistent input thermodynamic data).

In the SIA mode, this error condition causes the program to try automatically in the AIA mode (which is failed too, if you see this errror message).
 

E07IPM: IPM Main Descent:    Degeneration in R matrix (fault in the linearized system solver). It is not possible to obtain a valid GEM IPM solution.   

Indicates problematic setup of chemical system definition or corrupt input data. Occurs also upon divergence in the dual solution (see Pa_LLG).

Check input data or reconsider the CSD and the recipe, and try again.

W08IPM: PSSC():    Computed phase assemblage remains inconsistent after 5 phase selection loops. Problematic phase(s):  <Ph1> {,<Ph2>, ...}

Phase Selection procedure finds violations of phase stability criteria which persist after 5 refinement loops for indicated phases. The GEM IPM result is not perfect and can be used only provisionally (Speciation Cleanup could make it still useful).

One possible reason is that one of tolerances Pa_DF[0]  or Pa_DF[1]  is not optimal.

A more probable reason is that thermodynamic data or mixing models for some phases are inconsistent, or some relevant phases or components were not included in the chemical system definition.

In the SIA mode, this warning condition causes an automatic attempt to solve the problem using the AIA (LP simplex). This usually happens when a relevant multricomponent phase was absent in the previous GEM primal solution used as initial approximation, because Phase Selection algorithm is not allowed to insert multicomponent phases.

W09IPM: Phase Selection:    Computed phase assemblage remains inconsistent after 3 phase selection loops. Problematic phase(s):  <Ph1> {,<Ph2>, ...}

E10IPM: under construction

Under construction.

E11IPM: Set_DC_limits()    Inconsistent upper DC metastability limits <j>  <k> XU= <value> XFU=<value>

Under construction.

E12IPM: Set_DC_limits()    Inconsistent lower DC metastability limits <j>  <k> XL= <value> XFL=<value>

Under construction.

E13IPM: PrimalChemicalPotentials()    Broken phase amount from primal approximation: Phase <Ph> Yf= <value>

Under construction; probable reason is the divergence in GEM dual solution.

W14IPM: IPM Main Descent    Divergence in dual solution approximation (u) at IPM iteration <It> with gen.tolerance <LLG> for <n> ICs: <IC1>, <IC2>, ...

This warning indicates a stiff behavior of the chemical system, manifested in detected divergence of dual solution values (vector u) between IPM iterations (see Pa_LLG). Usually, some ui values will be unrealistically large.

At best, the chemical system definition should be re-considered such that redox-controlling species would appear in amounts not less than 1e-10 mol.

In SIA mode, this warning is not issued, and the program automatically tries the AIA mode.

E15IPM: under construction

Under construction

E16IPM: IPM Main Descent:   Error in codes of some DC metastability constraints

Under construction

E17IPM: Mass Balance Refinement:    Invalid initial Lagrange multiplier for metastability-constrained DC <DC>

Under construction.

E18IPM: IPM Main Descent:    Bad CalculateActivityCoefficients() status in SIA mode

Error code returned by CalculateActivityCoefficients() - problem with calculation of activity coefficients. Incompatible system used as initial approximation?

Reconfigure the system definition and restart it with the AIA initial approximation.

E19IPM: ConvertDCC()    Invalid DC class code. Memory corruption?

W20IPM: IPM Main Descent:    Too small input amount of independent component <IC1> {, <IC2>, ... }