HLPWWW (Version 8.7) JESS copyright (C) 1985-2019
Licensee : Webmaster, Murdoch University, Australia
Welcome. Monday, 29-May-23  0:57
by   Peter M May, Chemical and Analytical Sciences,
     Murdoch University, Murdoch, Western Australia 6150
     Kevin Murray, Insight Modelling Services, Pretoria, South Africa
and  Darren Rowland, Chemical and Analytical Sciences,
     Murdoch University, Murdoch, Western Australia 6150
JESS is a powerful research tool for modelling chemical speciation in
complex environments. It is designed to solve problems requiring expert
knowledge of solution chemistry. It currently comprises over 500
programs, 3500 subroutines and 420,000 lines of Fortran code. The
software is highly portable and has been implemented under VAX-VMS,
Unix, MS-DOS, Windows (95/98/NT/XP/7/10) and other operating systems.
Copyright and ownership of JESS is held jointly by Mayhem Unit Trust
(Australia) and NALCO, An Ecolab Company (United States of America).

The special focus of JESS is to understand and, progressively, to remedy the reasons for the substantial discrepancies which frequently occur between chemical speciation calculations from different workers. Our aim is to improve the accuracy of quantitative predictions concerning the physicochemical behaviour of aqueous solutions. For further details about this problem consult the index searching for the following terms: (i) "quasi", (ii) "bad data", (iii) "GEM" and (iv) "facilities". A number of papers describing various aspects of JESS development have been published. Reprints are available on request. May PM & Murray K, Talanta, 1991, 38, 1409-1417. May PM & Murray K, Talanta, 1991, 38, 1419-1426. May PM & Murray K, Talanta, 1993, 40, 819-825. May PM & Murray K, J. Chem. Eng. Data, 2001, 46, 1035-1040. Filella M & May PM, Geochim. Cosmochim. Acta, 2003, 67, 4013-4031. May PM et al., Talanta, 2010, 81, 142-148. Rowland D & May PM, Talanta, 2010, 81, 149-155. May PM et al., J. Chem. Eng. Data, 2011, 56, 5066 Rowland D & May PM, J. Chem. Eng. Data, 2012, 57, 2589 Rowland D & May PM, Fluid Phase Equilib., 2013, 328, 54 Rowland D & May PM, J. Chem. Eng. Data, 2014, 59, 2030 May PM, Appl. Geochem., 2015, 55, 170 Rowland et al., Appl. Geochem., 2015, 55, 170 Rowland D & May PM, J. Chem. Eng. Data, 2017, 62, 310
We, the original developers (PMM and KM), dedicate the JESS project to Professor Peter W Linder who introduced us, instructed us and inspired us. We hope our work reflects at least some of his commonsense, his scientific method and his liberal philosophy. May he rest in peace.
Disclaimer: Whilst considerable effort is made to ensure that JESS is error-free and user-friendly, we give no warranties. JESS is made available to you under the condition that you use it entirely at your own risk. Performance may not meet specifications; interfaces may change in future. Consult the JESS Licence Agreement for details.
Acknowledgements The substantial contributions of resources for the development of JESS by Murdoch University (Western Australia) and The CSIR (South Africa) are hereby gratefully acknowledged. We trust that JESS will reward the foresight and patience needed to support such a long-term project. The authors are also indebted to many people who have contributed to the JESS project in word or deed. Numerous discussions with colleagues have been invaluable in correcting errors, fine-tuning JESS philosophy and improving the documentation. Special thanks to Drs Mark Lukas and Ken Harrison (Murdoch University) for their guidance mathematical. And finally, of course, we note our particular appreciation to all who have assisted with the actual development of code or the entry of data. The following must be mentioned individually: Peter Cardy, Ria Jooste, David Liles, Ruth May, Julius Pretorius, Marita Roos, Andrew Stanley, Grahame Strong, Peter Verhoeven, Peter Wade, Danielle Meyrick, Erich Koenigsberger, Khin Than Aye and Sandra Blair.
Please inform the authors of any erors (!) or omissions in this documentation, or, indeed of any other problems you have with JESS. Suggestions as to how JESS may be improved in any way are always welcome. The email address for feedback, or any queries you may have regarding JESS, is "may@murdoch.edu.au" (without quotes).
In most JESS modelling, the speciation is calculated using known thermodynamic parameters for the relevant reactions in aqueous media. All types of chemical equilibria can be modelled including protonation, complex formation, redox, and solubility interactions. If you are unfamiliar with any of the above concepts you should consult the index searching for information on "speciation" and "chemical equilibrium" (without quotes) before proceeding. JESS facilities exist to (i) maintain a large, general database of thermodynamic data, (ii) automatically establish a thermodynamically consistent set of equations for calculating chemical speciation distributions, (iii) predict changes in equilibrium constants as a function of the temperature, pressure and ionic stength, and (iv) determine equilibrium distributions under various - and often numerous - sets of conditions. These facilities allow you to calculate many chemical properties of substances in (mostly aqueous) solution. Predictions of effects in multicomponent mixtures are the most powerful aspect of this. It is also possible to couple large multi-compartment equilibrium models with kinetic calculations. Please note, however, that this latter capability, which we call 'KEM' (for 'Kinetic and Equilibrium Multicompartmental Modelling'), is not included in all distributions of JESS. In particular, KEM is not included in Versions 7 or 8. The chemical speciation resulting from the progressive mixing of two or more solutions can be investigated. The 'best' value of thermodynamic parameters can be determined by least-squares optimization of appropriate experimental data. Two further facilities are those which (a) produce stand-alone FORTRAN programs, called 'Mini-Models', for modelling specific and well-defined chemical systems and (b) simulate systems not involving chemical equilibria by solving sets of differential equations. These are also omitted from some distributions of JESS.
To summarize the main limitations of JESS (as briefly as possible!) we note the following. 1. The databases are still far from comprehensive and no doubt have a significant number of residual errors. We currently estimate that there are about 1,500,000 measured thermodynamic constants; we have entered only about 220,000 of these (noting that our policy is also to include values cited by secondary sources). We have only 70,000 reactions in total. It is hard to estimate how many errors there are; we hope it is less than 0.1% and we are continuing our endeavour to eliminate as many as we can. 2. The ability to deal with constraints (due to kinetics) is still not ideal. Consult the index searching under "kinetic" (without quotes) for a more detailed discussion of this problem. 3. Speciation calculations for non-ideal solutions or for non-standard conditions should always be treated with caution. We cannot yet deal adequately with concentrated solutions when the predominant species themselves participate in reactions; nor are calculations above ambient temperatures (especially above 40C) well supported by the available data. There is no capability for modelling non-aqueous solutions. A quotation from Cardinal John Henry Newman (1801 - 1890) is thus apposite and serves as our JESS motto. "A man would accomplish nothing if he waited till he could do it so well that no one could find fault with it"
Newcomers to JESS should carefully read through the JESS Primer before attempting to work with the system. The Primer consists of a set of documents which introduce you to JESS and tell you how to begin using its main facilities. The Primer is available as printed hardcopy or as a set of MS-Word documents (distributed with CD-ROM versions of JESS in the directory Jeswin\Primer). It can also be downloaded from the JESS wesite at http://jess.murdoch.edu.au
This program provides you with help in two ways. First, it searches an internal index using keywords that you specify and displays any matching entries that are found. At the start of each displayed entry from the index you will find a label for the text dealing with that particular subject. Secondly, the program displays the text (hopefully providing you with the detailed information you seek) whenever you enter a recognizable label. For example, you can discover how to produce printed output from a literature reference database by (a) entering the search term "output + database" (without quotes) and (b) entering the label "T07D" and (c) entering the label "FMTJLR". Try it! The keywords used to search the index are simply terms (words or phrases) that are likely to be associated with the subject of interest to you. You can perform a search on combinations of keywords by appending further terms after " + " (for inclusion) or " - " (for exclusion), omitting the quotes. In general, it is best to specify characteristic bits of words rather than the whole word. This avoids missing entries when abbreviations are used or when there are different forms of the word stem. Likewise, specify single words rather than phrases unless you are sure that the phrase will occur exactly as you give it. Remember that you can also type Q for Quit or H for HELP at this prompt.
JESS software and data are distributed only under a licence agreement, and only in executable form, to protect our intellectual property. However, substantial discounts on our commercial prices are offered to users in academic institutions, particularly where we can negotiate some arrangement of mutual benefit.
Detailed instructions on how to install a JESS system are available in the JESS Developer's Manual. Contact either of the authors if you experience any difficulty. Email inquiries can be sent to "may@murdoch.edu.au" (omitting the quotes).
The JESS approach to chemical speciation / equilibrium calculations differs from that of other codes in several important respects. You can obtain details of these differences by searching the index for "our approach" (without quotes).
One of the main difficulties encountered in performing speciation calculations is that the set of reactions which ought to be included is often ill-defined. This is equivalent to saying that the set of species which are to be regarded as formed, as well as the number of mass balance equations to be established, are not known a priori. The reason for this, in essence, is that kinetics determines the correct set of reactions to use. Slower reactions, of course, only take effect if the modelling timescale is long enough. This means that there is no fundamental way to determine whether an individual thermodynamic reaction should be taken into account or not. The problem is that thermodynamics tells you about the relative stabilities of species in equilibrium with one another but not which species are in equilibrium. Ultimately, you (the modeller) must decide on the subset of reactions to be considered. Since most chemical systems of interest are not at true thermodynamic equilibrium, you must make assumptions about the kinetic constraints which are to be imposed in your models. To emphasise the dependence of your speciation calculations on these kinetic assumptions we call the results "quasi-equilibrium distributions". A quasi-equilibrium model is one that assumes equilibrium between a subset of all possible reactions. It excludes those reactions which take longer to reach equilibrium than is allowed by the timescale of interest. In reality, many reactions will not reach equilibrium quickly enough for the concentrations of the reactants and products to be controlled by the equilibrium constant of the reaction. Omitting such reactions may, in general, increase the number of mass balance equations and the number of components (or basis species) needed to define the state of the system. Even though JESS cannot establish which particular quasi-equilibrium distribution you require, it can assist you to deal with the problem. It does so in various ways, as follows. First, the default calculation performed by JESS involves ALL the chemical relationships which are represented in the JESS Parent Database (JPD). This means that the calculated result refers with some likelihood to the chemically most stable outcome, particularly if you have defined the composition of your system in terms of the elements it contains (as opposed to specifying the primitive species). Thus, the true thermodynamic equilibrium tends to be automatically contrasted with subsequent calculations yielding quasi-equilibrium distributions. Secondly, you can calculate the chemical distributions of species arising when particular kinetic constraints are imposed on the system. This is done by establishing additional mass balance equations for sets of species that do not come into equilibrium with others having the same elements. Thus, you can readily investigate the speciation outcome under several modelling scenarios. Thirdly, the most thermodynamically stable species which emerge from any speciation calculation can be easily suppressed if, on inspection, you consider them to be unrealistic. Fourthly, JESS records the assumptions made by you in reaching any particular calculated result. Thus, these assumptions remain associated with the speciation outcome, explicitly providing the reason for differences between calculations.
Speciation calculations using JESS involve many independent computer programs. This is a major difference between JESS and other computer packages that determine equilibrium distributions. In particular, a sequence of programs is used to extract the necessary data from the JESS Parent Database, to transform the data into a thermodynamically consistent set of equations, to solve these equations and then to produce output in various forms. We call this sequence of program execution the GEM stages. Consult the index using the keyword "GEM" (without quotes) for further details.
JESS adopts a rather different approach to that of most speciation codes regarding both activity coefficients and conditional equilibrium constants (lgKs). Other programs that have their own database of equilibrium constants store a single value only, determined for some standard condition, typically at infinite dilution (i.e. I = 0). Some kind of correction function, usually an extended Debye-Huckel equation, is then employed to predict the change in activity coefficients to the conditions required for modelling. There are various problems with this approach, most importantly associated with (a) the inconsistency that can arise when different correction functions have been used to calculate the (stored) infinite dilution value and (b) the introduction of errors if the functions are not specifically parameterised for each reaction individually. In JESS, all equilibrium constants are stored in the database without correction, just as they were measured (and the relevant conditions under which each was determined are also retained). In this way, corrections for temperature and ionic strength change relect the actual experimentally-observed behaviour as closely as possible and, more to the point, are achieved using the very same function in the backward and forward calculation. This has considerable practical advantage, especially when equilibrium constants from different primary sources are being averaged. Thus, in effect, JESS always works with conditional equilibrium constants (relevant at a particular ionic strength) rather than the "thermodynamic" values (applicable only at infinite dilution). Activity coefficient changes are only calculated to adjust equilibrium constants to an ionic strength other than that in which they were measured if there is no data available that was measured under more appropriate conditions. More details of these functions can be obtained by searching the index for "activity + coefficient". The conditional equilibrium constants used by JESS during modelling are embodied in an empirical function describing how they vary in respect of ionic strength and temperature. The parameters of these empirical functions are called "unconditional correction coefficients" or UCCs. Consult the index using the keyword "UCC" for further details.
What you need to know about activity coefficients / activity quotients and how you can get them from UCCs (in a nutshell). 1. The GEM stages of JESS (as opposed to modelling with the JEF framework) specifically avoid the use of activity coefficients; in particular and for good reason GEM does not use a model of single ion activity coefficients. 2. Instead of an activity coefficient model, the GEM stages use CONDITIONAL equilibrium constants. These are the equilibrium constants actually measured under given conditions, including the ionic strength and the background electrolyte. In the case of brushite, you can see these for the reaction: Ca+2 + H+1_PO4-3 + 2<H2O> = Ca+2_H+1_PO4-3_H2O(2)_(s) where there are several values of lgK (in KCl). 3. The lgKs from the literature (stored in the JPD thermodynamic reaction database) are regressed to produce a function of temperature and ionic strength. The parameters of this function are called UCCs (for Unconditional Correction Coefficients). When there are good data available in the literature this function works very well. You can see how effective it is in J. Chem. Soc., Chem. Commun., 2000,, 1265. Most problems occur in chemical speciation modelling because either there is not a dominant electrolyte medium (such as NaCl) or the measured data are inadequate. Sufficient numbers of good data are rare so it is frequently necessary for JESS to make approximations and estimations. 4. Anyhow, the programs DOLGK and DOBAS do their best with what they are given, determining the UCCs for reactions in terms of the basis species to be used by your model. 5. Using program VEWBAS (option 3) you can inspect these UCCs (sub-option 2) and the lgKs they produce under particular conditions (sub-option 3). 6. To obtain activity quotients for individual reactions IN YOUR MODEL, you simply take the difference in lgK between the conditions used in your model and the standard conditions of t = 25 and I = 0. Remember that lgK in this calculation means log base 10. At infinite dilution (I = 0), the lgK difference is zero so the activity quotient is unity. Remember also that this applies to the reaction used in your model, which is generally a linear combination of reactions in JPD. 7. You can do the same for reactions in JPD but remember that the approximations and estimations applied in the GEM stages will typically change things, hopefully not too much! 8. The difficulties arising from this approach are not easily overcome. They are the reason we have developed the JEF framework for making quantitative predictions. The JEF framework also has its limitations. You must just decide which approach suits your needs best. Horses for courses!
Many of the problems experienced in the development of chemical speciation models can be attributed to the unreliability of the available thermodynamic data. Bad data occur all too often in the literature. Much of the thrust behind the development of JESS has come from the need to develop systematic methods of dealing with this problem. Our approach has several parts. First, we are attempting to compile a large thermodynamic database for a set of components (e.g. metal ions and ligands) selected for their potential usefulness in speciation modelling. For these chemical systems, we are endeavouring to assemble as comprehensive a set of reactions and associated equilibrium constants as possible. Our strategy is to have this database reflect the information exactly as it appears in the literature (or as close to this as we possibly can achieve) since this minimizes the errors of compilation, facilitates checking and reduces the manual effort (and careless errors) inherent in alternative approaches. We include constants from secondary sources (e.g. critical reviews) because this helps greatly to establish an overall description of the current state of knowledge (or, rather, belief) about the equilibrium constants of each reaction. Secondly, we assess each and every equilibrium constant in our thermodynamic database, so that they are characterized by an integral a value, called the weight (Wgt), in the range from zero to nine. A weight of zero indicates that the constant is adjudged to be worthless (and should not be used in any equilibrium calculation). A weight of nine indicates that the constant is of highest accuracy. A typical equilibrium constant measurement is given a Wgt=3, whereas weights above 5 are given to multiply-determined values. Our hope is that, with time and with the assistance of many researchers around the world, these weights will evolve to represent a well-balanced opinion of the reliability of a large fraction of the relevant thermodynamic data existing in the literature. Thirdly, as implemented in the GEM stage calculations, the procedures for dealing with the inconsistencies and redundancies which thus occur in the thermodynamic database are automated. This means that the development of (thermodynamically consistent) speciation models is done in a sytematic, reproducible way. It also allows us to record the many assumptions that are made during the process and which in general affect the result, often rather profoundly. Fourthly, the GEM stage calculations of JESS are designed to enable and to encourage you to regard the outcome of your initial calculations as only the first step in an iterative process of model development. The aim, generally, is to understand the important chemical features of your system (such as in identifying the most likely predominant species and/or the most critical reactions) rather than to obtain a single, quantitative statement of species concentrations. In this process, you will typically need to consider the reliability of the thermodynamic data underpinning the predicted formation of significant species. This will lead to conclusions about the overall robustness of your model and about any ambivalence affecting your predictions due to uncertainties in the available thermodynamic data. Note that this assessment is ultimately your responsibility - it cannot be done automatically. What JESS tries to do is to make this task of yours as easy and as comprehensive as possible.
The main source of thermodynamic data used by JESS is the "JESS Parent Database" called JPD. This database is accessed (by default) during the GEM stages when you perform any chemical speciation / equilibrium modelling. Consult the index searching for "GEM + SUB" (without the quotes) to obtain further details. The JPD and other JESS thermodynamic databases are compiled using the JTH program sub-system. Consult the index searching for "JTH" to obtain further details.
JESS has been expressly designed and built to cope with very large equilibrium models. We have attempted to follow two general philosophies: (a) the programs should be optimised for the biggest possible system because, with modern computing power, small systems can be handled inefficiently without a noticeable loss of performance and (b) the programs should cope with the largest size of system that is practicable. For these reasons you should rarely, if ever, encounter problems with JESS size limits. This is not to claim that there are no size limits; there are. However, they tend to be far beyond most requirements. As a direct result of our design principles, it is difficult to say exacly what most of the limits in JESS actually are! This is because there are few such limits 'hard-wired' into the code, e.g. as array dimensions. Rather, they tend to come about through a combination of several factors, frequently in rather obscure ways. There are, of course, some exceptions to prove the rule! We do know that the thermodynamic database code restricts the number of reactions to about 750,000. Equilibrium models may not have more than 20,000 species. Kinetic models may not have more than 99 compartments. Hopefully, you will not find these limits too restrictive.