HLPWWW (Version 8.7) JESS copyright (C) 1985-2019 Licensee : Webmaster, Murdoch University, Australia Welcome. Thursday, 25-Apr-24 20:16 We call the sequence of operations by which thermodynamic data is extracted from a database, transformed into a thermodynamically consistent set of equations and solved to determine an equilibrium distribution of species the 'GEM stages'. GEM stands for Generalized Equilibrium Modelling. JESS differs fundamentally from other computer packages used to determine equilibrium distributions in that this sequence of operations is highly automated. This allows the many assumptions which are always involved in such calculations to be dealt with comprehensively and reproducibly. You can control most, if not all, of the assumptions which are made. However, you must do so explicitly, i.e. by identifying what they are and recording that they are to be changed. By dividing the procedure into a number of discrete stages, your ability to modify assumptions and repeat the calculation is facilitated. In this way, you can easily and quickly investigate the effects of making different assumptions. Consult the index for further details searching for the term "GEM" (without quotes) + each of the following: (i) "database", (ii) "GEM stage", (iii) "basis", (iv) "linear comb", (v) "constant", (vi) "equilibrium" and (vii) "output".
When you begin modelling, it is best to locate yourself in an empty directory. In this way, the many files that are created by JESS during the GEM stages will be confined to a particular location. They can thus easily all be deleted, say when your modelling exercise is completed or if you must begin again for some reason. You need to be familiar with the JESS methods for inserting and modifying a thermodynamic database (using program UPDJTH) and for editing (using program JED) before you commence modelling.
The first formal GEM stage is called the SUB stage. At this stage, you establish a sub-database in your current working directory. This should contain all the reactions and thermodynamic data relevant to the chemical system you want to model. The sub-database serves a number of purposes. Being much smaller than, say, the JESS Parent Database (JPD) it speeds up your modelling. You can also modify the data or insert new data independently of other users of JESS. Above all, the selection of data for your sub-database establishes the domain of reactions which can be considered in the subsequent GEM stages. It is therefore very important to ensure all the reactions which can possibly influence the chemical system of interest to you are extracted into your sub-database. The database from which the reactions and data originate is called the "Source" and the sub-database created by the SUB stage (and used in all subsequent calculations) is called the "User" database. The default "Source" database is JPD and the default "User" database is DBA. You can alter these defaults under the "Advanced Facilities" option of program TELSUB. Note that if you make any changes to your sub-database (using program UPDJTH) you MUST update the UCC parameters that will be used in your calculations (using program UPDUCC). Consult the index also for other information about those programs which comprise the SUB stage, namely TELSUB, DOSUB and VEWSUB.
The second formal GEM stage is called the LGK stage. At this stage, the thermodynamic stabilities are determined for all species that may subsequently be used in your calculations. The range of conditions of pressure, temperature and ionic strength that you indicate at this stage should be those you judge to be the most appropriate for your modelling. These conditions are used to select the best thermodynamic data for your purposes. Consult the index for those programs which comprise the LGK stage, namely TELLGK, DOLGK and VEWLGK.
Once you have created a sub-database (i.e. completed the SUB stage) and established the thermodynamic stability of all species (i.e. run program DOLGK), you should check the outcome to ensure (as far as you can) that your data is thermodynamically consistent. There are two main ways of achieving this: (a) inspect the output of program VEWLGK obtained by selecting the "Rogue's Gallery" option; and (b) inspect the output of program VEWJTH obtained by selecting "Another reaction combination for a given reaction" option under the "Locate" command. This checking procedure is optional. However, you are strongly urged to do it whenever you set up a modelling sub-database for the first time. Usually, the checking for thermodynamic consistency is done using the whole of the appropriate JTH database (specified as the one to use by program TELLGK). For further details, consult the index searching for "thermodynamic consistency + procedure" (without quotes).
The third formal GEM stage is called the BAS stage. At this stage, you establish the sets of basis species to be used for your modelling. (The basis species are those from which all other species are taken as being formed.) Unlike most software for calculating chemical speciation, JESS determines two basis sets. These are called the 'Variable Basis Species' and the 'Mass Balance Units'. They have different functions: the 'Mass Balance Units' are used to specify the total concentrations that define the chemical composition of the system; the 'Variable Basis Species' are used as the unknowns in solving the mass balance equations. Determining a basis set is a mathematical operation which need not involve species of real significance. 'Mass Balance Units', especially, determine stoichiometic ratios and may be just notional. 'Variable Basis Species' on the other hand should not only be real but, preferably, amongst the most predominant in solution. The greater the concentration of 'Variable Basis Species', the easier it is to solve the mass balance equations. It is at the BAS stage that you can, optionally, eliminate chemical links between species to simulate the effects of kinetic constraints on the chemical speciation distributions. This, in effect, allows any mass balance equation that would occur in the default calculation (for true thermodynamic equilibrium) to be 'reassigned' into two or more mass balance equations. In other words, sets of chemical species that could be in equilibrium with one another are partioned into subsets that are only at equilbrium with those in their own subset and not with those in other subsets. Consult the index using the keyword "Basis" (without quotes) to obtain further details on the criteria for selecting basis species.) During the BAS stage, the thermodynamic stability of all species in the chemical model is defined (relative to the 'Variable Basis species') by appropriate formation reactions. This involves construction of a function for the equilibrium constant of each formation reaction with respect to the temperature, pressure and ionic strength. The parameters of these functions, known as 'Unconditional Correction Coefficients' (or 'UCCs') are determined by linear combinations of the corresponding values for reactions evaluated at the LGK-stage. Consult the index for those programs which comprise the BAS stage, namely TELBAS, DOBAS and VEWBAS.
In JESS, the evaluation of equilibrium constants is achieved by an entirely generic approach in which ALL the constants known for each reaction are taken into account. This allows averaging (or smoothing) of equilibrium constants and above all ensures that internal consistency is possible. (Otherwise one easily lands up with a calculation exhibiting all manner of thermodynamic impossibility!). Note that we do not claim that all these inconsistencies have yet been eliminated from the JESS parent database JPD), only that it is now possible. At the same time, we have been hard at work and this goal is now being progressively achieved. The procedure by which equilibrium constants are obtained during the GEM calculations is, briefly, as follows. For each reaction in JPD, the smoothing functions (the so-called UCCs) are pre-evaluated and have their parameters stored in the database itself. This pre-evaluation is a massive job, that has not yet been fully completed (and probably never will be!). Consult the index using the search terms "UCC + Program" to see how the UCCs can be managed by you if you insert or modify reaction data. These pre-evaluated UCCs are then used in the GEM Stages, being manipulated additively in the same way as equilibrium constants would be, to obtain the set of equilibrium constants ultimately needed to calculate the chemical speciation of the system under the required conditions of temperature and ionic strength. All the reactions are assessed and the 'best' selected to define the relative stability of all relevant species. This is done by program DOLGK. It determines the appropriate linear combinations of reactions (eliminating redundancies) and adds together the corresponding database UCCs. This gives a set of UCCs which define the equilibrium constants that could be used to calculate the thermodynamically most stable distribution of species. These relationships are specified in terms of the LGK-stage basis species. The choice of reactions is, at least to some extent, made to suit the conditions of your modelling as specified using program TELLGK. The equations actually to be used in the modelling are generated in terms of the BAS-stage basis sets, both 'Variable' and 'MBU'. This is done by program DOBAS. If the Variable basis species differ from those of the LGK-stage, the necessary linear combinations of reactions are worked out to yield the UCCs needed in the speciation calculations. These are generally what you are interested in. They can be seen using program VEWBAS (option 3). The UCC parameters themselves can be inspected or you can have them evaluated to give the lgK value for any specified conditions of pressure, temperature and ionic strength.
The fourth formal GEM stage is called the QED stage. At this stage, you determine the equilibrium distributions by solving the mass balance (and other) equations set up for your modelling purposes. The name QED refers to "quasi-equilibrium" distributions because most calculations you will wish to perform will not apply strictly to thermodynamic equilibrium. Consult the index using the keyword "quasi" (without quotes) for further details. Consult the index for those programs which comprise the QED stage, namely TELQED, DOQED and VEWQED.
The fifth formal GEM stage is called the OUT stage. At this stage, you prepare your output from the equilibrium calculation for printing (or other kinds of display, including plotting). Consult the index for those programs which comprise the OUT stage, namely TELOUT, DOOUT and VEWOUT.
A set of "basis species" is a smallest set of species in terms of which ALL other species can be expressed (via reactions). These other species are thus called the "non-basis species". In the JESS context, we are usually concerned with three basis sets The first basis set comprises those species which are to be used in (at the LGK-stage of the GEM procedure) to calculate the relative stability of all species in the database with respect to one another. These are referred to as the "thermodynamic basis species". The second basis set comprises those species which are to be used as unknowns in the solution of the equations. These are referred to as the "variable basis species" (abbreviated "VBL"). They are determined at the BAS-stage of the GEM procedure. In general, no one variable basis set will be ideal for all the modelling which can be done on your chemical system. The best sets to select depend on particular circumstances and the application. There are also mathematical constraints, such as the need for independence. The programs will ensure mathematical integrity but cannot guarantee to choose automatically the best sets of species for your context. The third basis set comprises those species which are to be used to specify the total concentrations which are summed in the mass balance equations of your model. These species are referred to as your "mass balance units" (or MBUs). It is convenient to select MBU species to accord with the analytical information on which your model will be based. The MBU basis species are also determined at the BAS-stage of the GEM procedure. Both the 'variable' and 'MBU' basis sets, necessarily, have the same number of basis species but the species themselves may or may not be identical. The number of 'thermodynamic' basis species will be equal to or less than the number of 'variable' and 'MBU' basis species. (The number of the latter increases when kinetic constraints are imposed on the equilibrium calculation.)
The criteria for preferring one set of basis species over another are complicated. Clearly, the results of your modelling ought NOT to depend on how you choose to set up your equations. Even though your equations may be formulated in different ways, all of them ought to be mathematically equivalent as long as the chemical system is properly defined. Ideally, this should indeed be so. However, it is not the case in practice. There are two reasons for this. The first, and most fundamental, arises because of the way errors are propagated. Secondly, differences may also appear in numerical behaviour whilst the equations are being solved. The convergence difficulties that you are likely to encounter most frequently (when you come to solve your modelling equations) are closely associated with the latter reason. Since there are two ways in which the basis species can influence your modelling, your choice of basis species depends on their relative importance in your particular context. Unfortunately, there may be some conflict between the two. First, you want to avoid convergence problems by ensuring the best numerical properties for your system. This can be achieved by making the most predominant chemical species at equilibrium appear as the basis species. This implies that you know the outcome of your calculation before it has been performed! In practice, however, you can often guess the species which are likely to be favoured under your conditions of pH and redox potential (if not exactly, then well enough for the purpose). Secondly, you want to ensure that the effect of experimental errors in the equilibrium constants of the chemical reactions is minimized. This can be achieved by selecting the basis species which give the best linear combinations of reactions, where "best" means least affected by the errors. This is also difficult to know in advance. The selection criteria for reactions during the calculation procedure aim to use the most suitable reactions but this is necessarily only within the scope allowed by the basis set (which, by then, has already been determined). For further details about the criteria and method by which reactions are selected consult the index searching under "Reaction selection" (without the quotes). Until you have acquired considerable experience, it is wise to accept the basis species sets which JESS determines by default. This policy favours the second of the above requirements, i.e. it tends to minimize the effects of errors on your results. Unavoidably, this is at the expense of increasing the likelihood that you will experience convergence difficulties, especially early on in your modelling procedure. Fortunately, there are various tactics you can employ to overcome or bypass these problems. The simplest is to ensure that the first point in your calculation refers to conditions (especially of pH and redox potential) where the selected basis species will in fact predominate at equilibrium. Alternatively, or in addition, you will need to adjust the initial estimates used by program DOQED. Futher details can be obtained from the HELPER program using the keyword "estimates".
The method used to determine the basis species and to select those reactions in the database that will make up the linear combinations used to define the stability of all other species (relative to the basis species) is conceptually straightforward. In essence, the job is done by a Gaussian elimination procedure that works through all the available reactions and determines which will yield the most reliable linear combinations of reactions for each non-basis species. To do this, it is first necessary to establish orders of preference for both reactions and for species. The reactions are processed in order of their reliability (starting with the best) whereas the species are processed in a reverse order that begins with those least desired as the basis species. In this way, the best reaction is used to define that (single) species in it which is NOT going to be a basis species; the next best reaction is then used to define the subsequent non-basis species; and so on. Whenever a non-basis species that has already been defined, occurs in the reaction that must be processed next, it can be substituted using the reaction (or reactions) found earlier to define it. Thus, progressively, reactions are used up and non-basis species related to a diminishing number of (as yet) unassigned species. Linear combinations of reactions appear whenever the next best reaction (i.e. the one about to be used to define the next non-basis species) involves previously defined (non-basis) species. Ultimately, there will be no further reactions that have unassigned species able to be expressed in terms of other unassigned species (i.e. able to be defined as another non-basis species). The species then remaining unassigned comprise the basis set.
To establish the mass balance equations which are to be solved in your modelling procedure, it is necessary to select a set of species whose concentrations can be taken as the equation's unknowns and then to express the concentrations of all other species in terms of those unknowns. (The set of species selected as the unknowns is called the "variable basis" or "VBL" set.) Expressing the concentrations of all other species in terms of this basis set involves finding the appropriate sequence of chemical reactions by which each species can be formed from the basis species. Mathematically, this amounts to establishing a linear combination of reactions from the thermodynamic database to give the required formation reaction for each non-basis species. In practice, this procedure is not straightforward, largely because the reactions in the thermodynamic database are not entirely consistent (i.e. there is more than one way in which the reactions can be combined to give the required product species and, because of experimental errors in the equilibrium constants, these various ways do not yield identical results). Accordingly, one of the most important tasks of the GEM stages is to establish the linear combination of reactions which will be used to set up the mass balance equations. This done at the LGK and BAS stages. Consult the index using the keyword "coefficient" (without quotes) to obtain further details on how the equilibrium constants are processed.
Unconditional correction coefficients (or 'UCCs') are the parameters of the empirical functions used in JESS to describe how the equilibrium constants vary as a function of ionic strength and temperature. They are obtained for each linear combination of reactions that determines the concentration of a species from the concentration of the basis species (those selected as the unknowns in the mass balance equations). In terms of solution theory, UCCs represent the reaction behaviour of chemical species at infinite dilution in an inert medium, devoid of specific ionic interactions. Consequently, UCCs represent an ideal behaviour which is additive at given temperature and ionic strength. This allows thermodynamic consistency to be established between reactions but it also means that models with reactants at high concentrations have questionable reliability, UCCs should be present for every reaction in a JESS thermodynamic database. They are evaluated by a least squares procedure which fits the JESS function to the data in the database for that reaction. The procedure can be performed either by program UPDUCC or by programs ESTUCC and LODUCC used in sequence. UCCs must be re-evaluated (e.g. by UPDUCC) in order for any modifications to the data in a thermodynamic database to take effect in chemical speciation calculations. UCCs are stored in the JTH database where they can be inspected using the VEWJTH 'View Reaction' command. Each set of UCC parameters are associated with 'scores' which indicate how well the UCC spans the ranges of ionic strength and temperature that you may specfy for your modelling purposes. These scores are used by program DOBAS to determine which reactions should be used in the linear combinations carried forward to the QED stage. In this way, at the QED stage, equilibrium constant values can be calculated during the modelling procedure for any ionic stength or temperature.
In JESS, the evaluation of equilibrium constants is achieved by an entirely generic approach in which ALL the constants known for each reaction are taken into account. This allows averaging (or smoothing) of equilibrium constants and above all ensures that internal consistency is possible. (Otherwise one easily lands up with a calculation exhibiting all manner of thermodynamic impossibility!). Note that we do not claim that all these inconsistencies have yet been eliminated from the JESS parent database JPD), only that it is now possible. At the same time, we have been hard at work and this goal is now being progressively achieved. The procedure by which equilibrium constants are obtained during the GEM calculations is, briefly, as follows. For each reaction in JPD, the smoothing functions (the so-called UCCs) are pre-evaluated and have their parameters stored in the database itself. This pre-evaluation is a massive job, that has not yet been fully completed (and probably never will be!). Consult the index using the search terms "UCC + Program" to see how the UCCs can be managed by you if you insert or modify reaction data. These pre-evaluated UCCs are then used in the GEM Stages, being manipulated additively in the same way as equilibrium constants would be, to obtain the set of equilibrium constants ultimately needed to calculate the chemical speciation of the system under the required conditions of temperature and ionic strength. All the reactions are assessed and the 'best' selected to define the relative stability of all relevant species. This is done by program DOLGK. It determines the appropriate linear combinations of reactions (eliminating redundancies) and adds together the corresponding database UCCs. This gives a set of UCCs which define the equilibrium constants that could be used to calculate the thermodynamically most stable distribution of species. These relationships are specified in terms of the LGK-stage basis species. The choice of reactions is, at least to some extent, made to suit the conditions of your modelling as specified using program TELLGK. The equations actually to be used in the modelling are generated in terms of the BAS-stage basis sets, both 'Variable' and 'MBU'. This is done by program DOBAS. If the Variable basis species differ from those of the LGK-stage, the necessary linear combinations of reactions are worked out to yield the UCCs needed in the speciation calculations. These are generally what you are interested in. They can be seen using program VEWBAS (option 3). The UCC parameters themselves can be inspected or you can have them evaluated to give the lgK value for any specified conditions of pressure, temperature and ionic strength.
All reactions are characterised better under some experimental conditions than others. This means that the reactions which ought to be used (to establish the relative thermodynamic stability of species most accurately) differ, depending on which ionic strength temperature and pressure are to be specified for the equilibrium model. Program DOLGK takes this into account in the selection of reactions that are combined linearly and for which UCCs are evaluated. You specify the conditions of pressure, temperature and ionic strength to use for this purpose using program TELLGK. The criteria used by program DOLGK to select reactions involve various trade-offs. In essence, the appropriateness of each reaction is quantified in terms of the number of constants in the database (NCST), the so-called 'information content' (IC) which is a measure of the reliability of the constants as indicated by their weights (Wgt) plus the suitability of the experimental conditions to which they apply, and the so-called 'intrinsic reliability' of the reaction (IR) which a measure intended to minimise the number of reactions involved in the linear combinations. You can inspect these various quantities using program VEWLGK under option 3. of the View command. Of course, this selection by program DOLGK cannot be done ideally when the modelling conditions are uncertain at the LGK stage. This arises, typically, when you intend to calculate the ionc strength at equilibrium or when you intend to scan a range of conditions at the QED stage. In practice, this will not introduce problems for most chemical systems. Whether it does, or not, depends on the thermodynamic consistency between reactions in the database. Obviously, large inconsistencies mean that different answers will be obtained from models based on a different selection of reactions. You can check the extent of inconsistencies using program VEWLGK (option 9) and program VEWJTH (option 8 under the 'Locate' command). Hopefully, the inconsistencies found in this way will not be too serious because eliminating them can sometimes be very tricky.
The procedure by which the UCCs for reactions in a JTH database are made thermodynamically consistent is often protracted. There is no simple, general recipe. The following describes a good approach to adopt initially and some principles to apply. However, you will quite typically need to vary what you do, to fit the particular circumstances. The key points for you to remember are that (a) most chemical systems have not been well characterised experimentally so that only a few UCC parameters ought to be used to describe them - in fact, the fewest possible - and (b) discuss your problem with PMM before investing a significant amount of your time in a quest of this kind. To avoid non-convergence (i.e perpetually going around in circles) you need to adopt a very systematic approach: do not try to achieve consistency in a complicated model by commencing work on the whole system. Rather, ensure first that the reactions involving a single element or single primitive and water are OK. Then, gradually, introduce combinations of elements and.or primitives, checking that each combination is itself without a problem and correcting the raw data where necessary. The golden rule is not to alter a reaction of lower 'order' in an attempt to eliminate an inconsistency with a reaction of higher 'order', where the 'order' of reactions involving only the components of water is zero, involving only a single element/primitive and water is one, two elements/primitives and water is two, etc. The overall correction procedure generally involves two main lines of attack: (a) comparison of data to determine which of the inconsistent values are likely to be least accurate, so that as many of these 'bad' data as are necessary can be eliminated by putting Wgt=0 and adding a suitable footnote and (b) trasmitting information, usually about the effects of temperature and ionic strength, from reactions with measured values to those without them. By convention, the values inserted into the database for this purpose are assigned the technique 'ELC' and given Wgt=1. Both of these approaches tend to be long-winded; you generally need to cycle between program UPDJTH and program ESTUCC. The former is used to insert data and modify 'Wgt's; the latter is used to optimise the UCCs arising because of the changed circumstances. Be aware that program UPDUCC can sometimes replace ESTUCC for the processing of many reactions in one hit but that UPDUCC does not change the set of UCC parameters being optimised so is unsuitable if you are inserting data that, say, introduce the need for dH0 or GucC. Finally, to achieve consistency over a wide range of conditions, it is recommended that you first check and correct for 't=25, I=0', then 't=100, I=0', then 't=25, I=3', and finally 't=100, I=3'. Each set of conditions needs to be fixed before preceeding to the next. If changes are required (as is usually the case) ensure that these have not upset the conditions previously processed. Unfortunately, there is no quicker way in our experience!
Program DOLGK checks that the UCCs of all selected reactions are up-to-date. You cannot sensibly proceed otherwise. If JTH reaction data are ever altered, it is therefore nececessary to re-determine the relevant UCCs. This happens both when reaction data are modified or when new data are inserted. The procedure is usually done immediately, using the 'Modify Reaction parameters' command (option 7) in program UPDJTH. Alternatively, you can use program UPDUCC, that automatically processes all reactions that are out-of-date. Very occasionally you may need to control the UCC determination differently using programs ESTUCC and LODUCC. Once good sets of parameters for every reaction are installed in the database, the GEM stage programs look after everything else.
You can impose kinetic constraints on your chemical equilibrium calculations at the BAS stage. This is done by 'uncoupling' one or more of the LGK-stage basis species. For each of the LGK-stage basis species that is to be 'uncoupled', you select one or more species defined in terms of that basis species (at the LGK stage) which are to become basis species at the BAS stage. This means that chemical interconversion between the species you so specify and the LGK-basis species is eliminated. Consequently, both species are deemed to occur in solution independently so that, for example, the concentrations of both must be given at the QED stage. To accomplish this, select option 'Uncoupled basis species' using program TELBAS. Then specify the basis species at the LGK-stage which you want uncoupled, along with the species that should be made independent from it. It is easiest if, to begin with, you then select the option 'Create a new list of all available species'. A list of all species defined by the LGK-stage basis species in question and which are to be linked instead to the new BAS-stage species is thus prepared. Opposite each species, the symbol of the BAS-stage basis species with which it is to be associated appears in angle brackets. For example, oxalate and carbonate may be in equilibrium with one another but are often not. Assuming 'CO3-2' is the LGK-stage basis species, 'Oxalic-2' will not also appear as a LGK-stage basis species because all oxalate species can have their thermodynamic stability defined in terms of carbonate. However, the two substances may be uncoupled from each other using program TELBAS by a list reassigning all the oxalate species into their own mass balance equation. Such a list should include the following lines (amongst others) H+1_CO3-2 <CO3-2> H+1_Oxalic-2 <Oxalic-2> to indicate the necessary reassignments. 'Oxalic-2' would then emerge as a BAS-stage basis species. It is very important to include ALL the oxalate species for reassignment in this way; if any are omitted from the list they will be treated as remaining in equilibrium with carbonate (not oxalate) in subsequent speciation calculations. This is unlikely to be correct! If you create the list of species automatically, as recommended above, this problem of omission is avoided. You then need only check that the decisions made by TELBAS, as to what the assignments should be, are correct. There is no certain way to know about this, which is why you must take responsibility!