HLPWWW (Version 8.7) JESS copyright (C) 1985-2019
Licensee : Webmaster, Murdoch University, Australia
Welcome. Monday, 29-May-23  0:47
The JESS Thermodynamic database (JTH) sub-system is employed to store
and manipulate thermodynamic data. It is used in particular to deal
with the JESS Parent Database (JPD) which holds the current version
of all the data we have compiled from the literature. It can also
be used by you to extend and modify sub-databases which you
need during your calculations of equilibrium distributions.
JTH overcomes many problems associated with existing databases of
equilibrium constants. It is fully interactive. Reactions can be
expressed in any form. Any number of equilibrium constants, enthalpy,
entropy and Gibbs free energy values can be associated with a
reaction. Currently, the database contains over 71,000 reactions and
over 176,000 equilibrium constants. Our data span interactions in
solution of some 100 metal ions with more than 2,500 ligands. A suite
of computer programs exists to facilitate the production of
sub-databases and the interchange of data between databases.

The main features of our thermodynamic database are as follows. * Data (thermodynamic parameters) are stored and retrieved by association with their particular chemical reactions. These reactions are held in a processable form (i.e. they are NOT just like entries in a book). The reactions and data can thus be manipulated automatically by the JESS procedures for modelling. * Data are generally stored as they appear in the literature and are only subsequently manipulated by our system to achieve thermodynamic consistency. This has the advantage that the data in the database are not converted to conform to a particular pre-determined basis set, unlike most other speciation databases. (This minimizes errors and facilitates checking of the data.) * Unlike all other major compilations of equilibrium constants, ternary complex formation is naturally represented by the same conventions as our binary reactions. The data can thus be located directly by searching on the metal ion and two ligands involved. The JESS Parent Database is, overwhelmingly, the largest single source of ternary equilibrium constants. Since reactions are treated in an entirely general way JESS handles many types of interaction that other databases cannot (e.g. host-guest equilibria involving anions only, though so far not very many of these constants have been entered). * Chemical substances are indexed by name, by molecular formula and, often, by CAS registry number. In general, we have many more variants of chemical names than are provided in alternative sources. * Every thermodynamic parameter value is individually associated with (i) the conditions under which it was measured, including e.g. the identity of the background electrolyte, the temperature and the ionic strength, (ii) a literature reference and (iii) our current estimation of its reliability, on a scale of 0 - 9. This approach enables the database to be both comprehensive and critical.
The following is a very brief description of what the more important JTH programs do. Consult the index for more detail about specific programs (by entering the program names). The most frequently used programs VEWJTH - Permits viewing of the database. The program accesses the database as "read only" so the database cannot be corrupted by incorrect usage, power failures, etc. Program VEWJTH is the main facility for interactive searching (interrogation) of JTH databases. UPDJTH - Permits updating of the database. Program UPDJTH is used to enter almost all data that goes into JTH databases. DMTJTH - Dismounts a database producing a set of sequential files containing all the information in the database. The database can be reconstructed from these files using program MNTJTH. MNTJTH - Mounts a database from the *.ARC files produced by program DMTJTH. Consult the index searching for the term "mount" to obtain more details about the mount/demount procedure and the need for it. Less frequently used programs BLDJTH - Builds a new database from the *.ARC files produced by program DMTJTH. Reconstructs all internal links of the database (cf MNTJTH which does not and thus executes significantly faster). NUMJTH - Produces a file of reaction numbers for reactions which satisfy various criteria (such as involve a given set of primitive species). The file is often used as input for programs such as SUBJTH and WRTJTH - search the index for "input + file" (without quotes) for further details. WRTJTH - Produces a file of output for printing with the thermodynamic data for specified reactions and the corresponding list of literature references. Descriptions of the weights associated with each thermodynamic constant and of the techniques used to obtain them are also included. Other output that can be selected includes information on given species and the overall parameters of the reaction (the forward and backward reaction times and the Universal Constant Coefficients). DEVJTH - Produces database statistics and allows a variety of searches that are not available using VEWJTH. These searches include one to find reactions associated with a specified literature reference. GBLJTH - Performs various JTH operations on a specified set of reactions. You first define the set of reactions on which the changes are to be made. You then select the type of change you require. For example, you can change the weight of all data from a given literature reference or you can delete all the data associated with a given set of reactions without deleting the reactions themselves. The latter is useful when you need to synchronise database modifications being made by more than one database compiler. SUBJTH - Permits sub-database generation by producing a set of *.ARC files which can then be turned into the required database by program BLDJTH. PUTJTH - Produces a set of JTH "transfer files" (*.WRK files that are used to move data to another computer) GETJTH - Inserts data from JTH "transfer files" into an existing database. Search the index for "JTH + transfer" for details.
The background information you need to inspect a JESS Thermodyamic Database (using program VEWJTH) is given in the JESS Primer. Using program VEWJTH you can access the JESS Parent Database, JPD, or any other JESS thermodynamic database. Values for the equilibrium constants and other parameters (such as enthalpy change) can be obtained easily and rapidly. You generally locate this information first by identifying the chemical species involved and then either by searching for all data associated with those species or by displaying the data associated with a specified reaction (or reactions). It is important to familiarize yourself with the JTH chapter in the JESS Primer before you attempt to use any JTH program. The Primer tells you about the way we formulate "primitive" and "composite" symbols for species and about the various notations for describing chemical reactions. These conventions allow many possible types of chemical reaction to be defined. (Please inform us if you have a reaction that you think JTH cannot deal with satisfactorily.) At the same time, various abbreviated notations are also available which allow you to express certain of the most common types of reaction with considerably fewer keystrokes than are required by the full form of the reaction specification. For further details about these conventions, consult the index using the keyword "JTH shortcut" (without quotes).
Making changes to a JTH database is relatively straigtforward but it requires a certain amount of background knowledge to be tackled successfully. What you must know before modifying a JTH database 1. How to interrogate the database You need to be familiar with the "View" and "Locate" commands of program VEWJTH, as described in the JESS Primer. You are likely to be frustrated if you start entering new data before you know how about the types of data you must deal with, how the data are structured and what conventions are used to describe chemical species and reactions. 2. How to ensure that your modifications are not subsequently lost You must be aware of the simple steps to take in order to ensure that the effort you put into database development is not wasted, either by accident or when new versions of JESS are installed. Details can be obtained by searching the index for "security" (without quotes). 3. How to perform routine database maintenance / housekeeping You are strongly advised to follow the JESS procedures for database development needed periodically to optimize access performance and minimize filespace requirements. Details can be obtained by searching the index for "housekeeping".
You enter new data into a JTH database using the "Insert" command of program UPDJTH. (Program MEDJTH is used to insert new symbols for solvents, background electrolytes and techniques but this should not often prove necessary, nor should it be attempted by inexperienced users.) New data are always entered into a JTH database in a strict, but obvious, order. Data (such as lgKs, dHs, etc.) can only be entered once the reaction has been defined; reactions can only be entered once the chemical species involved have been defined; species information can only be entered once the I/O symbol for the species has been defined. Note, however, that composite species (those in which underscore characters join together two or more primitives) are inserted automatically during the procedure for inserting the reaction involving them.) N.B. Before you enter a new primitive species you must (i) check carefully that the species doesn't already exist in the JESS Parent Database, JPD, (ii) check that the species cannot be represented as a composite using primitives that already exist and (iii) familiarize yourself with the JESS naming conventions for species symbols - search the index for "JTH + naming" (without quotes) to obtain details.
You modify/alter/change existing data in a JTH database using the "Modify" command of program UPDJTH. (Program MEDJTH is used to modify existing symbols for solvents, background electrolytes and techniques but this should not often prove necessary, nor should it be attempted by inexperienced users.) Select the type of datum you wish to modify from the menu that is displayed after you have entered the Modify command. In modifying thermodynamic data, you simply follow the default responses (by pressing ENTER) until you reach the datum that you want to correct. Then type whatever you want to replace the existing item and accept any remaining data by pressing ENTER repeatedly until the end is reached, The existing data is used to provide the default responses so this leaves all items unchanged except those for which you supply a different entry. Type "Q" (for "Quit") to have the data displayed in modified form and then to return to the JTH Command prompt.
There are a number of conventions used by us when entering new I/O symbols into a JESS thermodynamic database. You should be aware of these and try to adopt them yourself when you use program UPDJTH. First, for species that involve only one element, we use the element symbol, followed by the appropriate phase symbol. Examples are Mn(s), O2(g), Hg(l). Secondly, for species having a net electronic charge, we append the sign and the (integer) value of the charge, in that order. Thus, for example, you will find Cu+1 and Cu+2 as the symbols for the free (aquated) ions of Cu(I) and Cu(II) respectively. Thirdly, for simple inorganic ions we try to represent the species using a formula as close as possible to that which would occur in ordinary chemical writing (e.g. UO2+2 and SO4-2). Fourthly, for organic ligands with a (reasonably) short standard or trivial name, we use the name in full (e.g. Succinic-2 and Citric-3). Fifthly, for other organic ligands we use any convenient abbreviation. For example, we have EDTA-4. Truncation of names is also fairly common, as in Desfer-2 for the anion of Desferrioxamine and Citrul-1 for the anion of Citruline. The systematic use of short (standard) abbreviations for frequently-occurring functional groups is appropriate whenever no simpler alternative is obvious. Thus, you find ClKojic-1, COOMeAmAcetHydroxam-2, Di2AmPyrid, EthDiam, etc. Use the standard three letter abbreviations for amino acid residues joined together when introducing new peptides. Finally, note how the species phase is indicated in parentheses at the end of the symbol, be it a primitive or (after an underscore character) a composite. Examples include H2(g), Cu(s), Al6Si2O13(s), Al2O3(Corrundum,s), and Al+3_OH-1(3)_(Gibbsite,s).
JESS is very much concerned with the quality of the thermodynamic data used for equilibrium modelling. Every parameter entered into a thermodynamic database is associated with a "weight" (Wgt), i.e. an integer in the range from 0 to 9 indicating how reliable the parameter is assessed to be. This assessment is used during the GEM stage calculations to determine the relative value of the thermodynamic data associated with reactions relevant to your modelling. For example, the more reliable reactions are retained when redundancies are detected and eliminated. You can see the outcome of this assessment procedure using programs VEWLGK and VEWBAS to view the reactions actually used for your modelling (for example, by selecting the option "Scan of UCCs"). The linear combinations of reactions are selected on the basis of the Wgt values found in the thermodynamic database. An overall assessment of data quality (reflecting the Wgt values for reactions forming the predominant species of a model) can also be seen under the Speciation option "Data Quality" of program VEWQED. You can obtain more information about our approach to unreliable equilibrium constants in the literature by searching the index for "bad data" (without quotes).
A number of abbreviations are used in the display of JTH reaction data. The conditions under which the constant applies are defined in terms of 'P' (pressure), 't' (temperature in Celcius), and 'I' ionic strength. Data measured on the molal scale are indicated by the symbol '/m' after the background electrode (to be contrasted with the default, molar or mol/L scale). The type of error is indicated as 'SD' (Standard Deviation), 'MD' (Maximum Deviation - approx. three times SD) and 'SF' (Significant Figures). Each of these is meant to reflect error as indicated in the published source of the data (but there are some difficulties in achieving this exactly). The technique by which the data value was determined is indicated by a three-letter code, such as 'CRV' (Critical review), 'EDH' (Debye-Hueckel correction), 'MGL' (Glass electrode). The first in each case indicates the technique class, i.e. 'C' (Critical evaluation), 'E' (Estimate) and 'M' (Measured). You can establish the meaning of the technique code by typing '?T cod' (without quotes) at any prompt, where 'cod' is the three-lettered code. Other abbreviations such as lgK, dH, Cp, and Wgt are described elsewhere. Consult the index.
Mostly, the units of JTH quantities are assumed by default. These are M (molar) for lgK, kcal/mol for dH and dS, cal/mol for Cp, V (volts) for E (std. potentials), M (molar) for ionic strength and C (Celsius) for temperature. The units of lgK, dH, dS, and Cp can be varied at input stage (i.e. when entering data using UPDJTH). lgK can be entered in terms of m (molal), dH and dS in terms of kJ and Cp in terms of J (Joules). On display, quantities having the default unit are shown just as a number (without an explicit unit); otherwise, the unit is appended. The unit of ionic strength is assumed to be the same as lgK. Note that, strictly, lgK is unitless. However, the values depend on the concentration scale used to define the standard state. It is therefore treated by JTH as if it has a unit (m or M).
JTH programs support a number of 'shortcut' mechanisms to facilitate interrogation and data entry. The most important of these mechanisms are those that allow you to specify reactions in abbreviated ways. It is therefore unusual to find that you must enter reactions fully formatted. (Precipitation reactions are the only common exception to this rule that we know of.) By associating the JTH symbols for metal ion and ligand species, reactions can be entered, for example, as 'B110', 'B121', etc. or as 'ml/m.l', 'ml2h/m.l2.h', etc. These conventions are described in detail in the JESS Primer. There is also a way to specify rapidly so-called 'formation reactions' (i.e. reactions in which a single species as the product is formed from its constituent elements. This is done simply by entering, in response to most prompts for 'Reaction:', an equals sign (=) followed by the product species. For example, to enter the reaction 'Mg(s) + 2<O2(g)> + S(s) = Mg+2_SO4-2' simply type '= Mg+2_SO4-2'. The program will then supply the elements (i.e. the first part of the reaction) automatically. The mechanism also works for ionic species. Entering '= Cl-1' will elicit '0.5<Cl2(g)> + e-1 = Cl-1'.
Reactions in a JTH database are sometimes (very occasionally) flagged as having 'priority status'. This means that regardless of their information content, they should be used in preference to other reactions during the GEM stages by programs DOLGK and DOBAS. They are thus included in the linear combinations of reactions even though they may not have many equilibrium constants present in the database. This is necessary, for example, to impose the convention that lgK0 be defined as zero for the reaction 'H+1 + e-1 = 0.5<H2(g)>'.
Every species in a JTH database can be associated with a specific model for the change of its activity coefficient as a function of ionic strength. These functions are used in the GEM stage calculations if data do not exist explicitly under the required conditions for modelling. You can obtain details about these correction functions by searching the index for "activity + coefficient". If a species does not have a particular function associated with it the species data shows the method as "global". This means that during the GEM stage calculations the species activity will be corrected by the global functions used by default in determining the UCCs for each reaction (when experimental data doesn't exist).
Good database management requires that detailed records be kept of all changes: the type of change (insertions, modifications, deletions, etc.), who made them and when. It is also highly desirable to impose a hierachy amongst users regarding the level of change that can be made by a given individual. Unfortunately, the design history of JTH has meant that only rudimentary controls and records are so far implemented within the JTH interface. Better methods are in place with the FIZ and SOL database systems (but these depend on the inherently different way the FIZ and SOL databases are assembled). JTH is a victim of its history! First, JTH depends on the JESS categorization of users which determines who has write-access to JESS-wide databases. (All users have read-access by default.) Only few individuals are involved in database compilation. A relatively new facility identifies and authorizes these so-called 'database builders'. Second, so-called "ownership" rules are used by JESS developers to ensure that database building by multiple contributors remains in sync. Third, some primitive records are kept regarding the creation and modification of database records. These are limited to the date/time stamp for changes to reaction data and the identificattion of individuals making any change. However, in both of these cases, only information regarding the last change made is preserved. We hope to improve this deficiency some time in the future, when priorities permit. The date/time of last modification is displayed with the reaction data, e.g. under 'View Reaction Data' in VEWJTH. The identity of the individual that last modified any particular reaction can also now be determined (although this is a fairly recent facility so it is pre-dated by most reaction data in JPD). The way this information can be inspected is documented in routine JTHVTP.
Many tasks when working with JTH databases involve the execution of several programs in sequence. Frequently this involves making a list of reactions with a particular characteristic and then operating on those reactions in some way or another. The list of reactions is often produced (as a file of reaction numbers) by program NUMJTH. This set can be presented as input to programs like SUBJTH and GBLJTH (consult the index using the keyword "||||" without quotes for further details). NUMJTH can identify reactions that have had their data or parameters modified in various ways since a specified date and time, reactions involving particular species or chemical elements, reactions with data from particular literature references, etc. (Concerning the latter, see also program DEVJTH below for interactive searching.) SUBJTH is used to produce a sub-database of the reactions of interest. These can then be printed using WRTJTH or searched again for another characteristic using VEWJTH or NUMJTH or processed using GBLJTH. GBLJTH is used to make the same change to data from multiple reactions. Those data with a particular characteristic can all be deleted or they can all be modified in a common way. For example, data that have been entered collectively with an incorrect backround electrolyte can have it easily substituted to the correct one throughout. Similarly, all data from a given literature reference can have their weights modified collectively. Be careful, however, of the power of GBLJTH - you can do much damage very quickly! Best make a copy of the database beforehand in case things go wrong and you want to return everything to its original condition. DEVJTH provides a variety of information about JTH databases not readily available using program VEWJTH. This information includes (a) species and reaction statistics (lgK/dH/E0 etc. counts), (b) reactions having data from a given literature reference or for given background electrolytes / non-aqueous solvents, and (c) other output of use to the database developers.