HLPWWW (Version 8.7) JESS copyright (C) 1985-2019 Licensee : Webmaster, Murdoch University, Australia Welcome. Tuesday, 23-Apr-24 22:06 You begin your modelling by specifying the set of elements and, optionally, any particular JTH primitive species, that are to be considered for inclusion in your speciation calculations. In essence, this defines the set of reactions in the JESS Parent Database (JPD) that will be made available. Use program TELSUB to specify the list of elements and primitives you require. Note that this operation requires some familiarity with the 'jed' editing environment. Note, in particular, that the way elements and primitives are specified has a considerable influence over the chemical calculation (or model) that is subsequently developed by the GEM stage procedures. Recommendations are given in the description for program TELSUB. Consult the index for "GEM stages" for further details about the calculation procedure leading to a chemical speciation model.
The specification of elements that are to be included in your modelling is done using program TELSUB (option 1 under the Modify command). These specifications are used to define the data which are to be included in the sub-database created during the first GEM stage (called the SUB stage). Chemical species and reactions that occur in the sub-database are, by default, all included in subsequent processing. If you wish to exclude reactions or primitive species in the sub-database (from being processed subsequently) this must be done explicitly using the Advanced Facilities option of programs TELSUB and TELLGK. Consult the index, searching for "SUB" and "LGK" (without quotes) for further details. Note that the element 'carbon' is treated specially. If 'C' for 'carbon' is specified in the element list, only 'inorganic' species containing carbon will be included. To have reactions extracted from JPD for organic species, you must specify the appropriate primitive species using program TELSUB (option 2 under the Modify command).
It is often convenient to specify particular species to be included in your model by specifying the appropriate (JTH) primitive species. Such primitives (if any) are entered by you using program TELSUB (option 2 under the Modify command). Obviously, the primitive species you specify must match those in the 'source' database. Mistakes can lead to reactions that should be selected being omitted or wrong reactions being included.
Once you have defined the 'domain' of your model by specifying the elements and JTH primitives you wish to be included (using program TELSUB), the relevant reactions are extracted from the 'source' database into the 'target' database located in your working directory. Typically, the 'source' is the JESS Parent Database (JPD) provided with the JESS package. You can change this default by specifying some other database as the 'source' using program TELSUB (under the 'Advanced Facilities' option). Inexperienced users can then simply execute the sequence of programs which comprise the GEM stages. Following programs TELSUB and DOSUB, the least you need to run are DOLGK, DOBAS, TELQED, DOQED and VEWQED. Consult the index for further details about the 'GEM stage' calculations.
You always need to specify as many concentrations (either frees or totals) as are necessary to satisfy the number of equations to be solved. In the most straightforward situation (which occurs by default) this number is the same as the number of basis species. The basis species are displayed when you select either of the options "Fixed log(Free Concentrations)" or "Fixed Total Concentrations" so that it is easy for you to check that your chemical system is adequately defined. Usually you will specify three free concentrations, corresponding to the pH of the solution you are modelling, its "Eh" and the activity of the solvent (water). You define the "pH" by specifying the concentration of the species "H+1" to be the negative log of the hydrogen ion concentration. (It is best, early on, to choose a pH which is likely to favour the formation of your basis species relative to other protonated states in which each species may occur.) Likewise, "Eh" and solvent activity are defined by specifying the values for the species "e-1" and "H2O" (as logarithms). Until you have gained the experience to know the consequences for your calculations, it is best to not to alter the default values for "e-1" (-5.0) and "H2O" (0.0). The remaining concentrations are often specified as fixed totals. The values you then use would generally come from some analytical knowledge about your system. However, there are many possibilities by which a valid set of equations can be established, each requiring your chemical system to be defined in its own way. Take care to distinguish between the ways in which the frees and total concentrations are entered. Free concentrations are given as logs; total concentrations are not. You can achieve interesting effects if you get this wrong! Omitting the minus sign on the logs of free concentrations less than unity can also be fun.
You specify scanned concentrations by selecting the "Scan" option of program TELQED and responding "Yes" to the resulting prompt. This invokes the "Scan interface" in which you enter appropriate commands to set up or modify the parameters being scanned. In addition to fixed free and total concentrations, it is also possible to scan the temperature and the ionic strength. New scan information is usually specified by the "I" (for "Insert") command. However, you can also take scan information directly from a delimited ASCII file using the "G" (for "Get") command. Existing scan information can be inspected by "V" (for "View") and entirely removed by "K" (for "Kill"). The information for a single scan parameter can be selectively removed by "D" (for "Delete"). Note that when concentrations are specified to be scanned, the corresponding individual entries given as Free or Total concentrations (under the Modify menu options) must be deleted.
You specify solids that are, or may be, in equilibrium with the solution by selecting the "Solids" option of TELQED and responding "Yes" to the resulting prompt. You can then specify either or both of two possibilities. The solids selected by you may (i) be required to be in equilibrium with the solution or (ii) be allowed freely to precipitate or dissolve. Which of these options you choose depends on the system you want to model and/or the chemical information you want to obtain. Option (i) is used when you want to determine the properties of a solution (such as the solubility of a component) when the solid is necessarily present. However, if a solid is specified under (i) that cannot possibly be in equilibrium with the solution under the prevailing conditions, program DOQED will fail to converge. Option (ii) is usually used to determine which of a set of possible solids will appear as stable phases under the given conditions of your model. In both cases, you must provide a list of one or more solids to be considered in the equilibrium calculation. An option is available to generate all possible solids (formed by given elements) to reduce the typing required of you. Note however that it is inadvisable to specify too large a number of solids. It is generally best to perform the calculation first without allowing solids to be in equilibrium with the solution and, from the resulting degrees of saturation observed for solids (with a saturation index above or close to zero), select from those that are most appropriate. A very important consideration in this respect is expressed by Ostwald's Law of Stages which holds that the thermodynamically LEAST-FAVOURED solids tend to precipitate first. In practice this means you will often be interested in solids close to saturation rather than highly supersaturated. This is an archetypal example of "quasi-equilibrium" considerations being important. Consult the index under "quasi" (without quotes) for further details. Finally, note that when a solid is specified definitely as being in equilibrium with the solution, i.e. applying option (i) above, two possibilities arise regarding the way the calculation may be performed. First, you may take advantage of the additional chemical constraint being imposed and reduce the number of other equations involved (e.g specifying one fewer total concentration or not invoking the charge balance equation.) Alternatively, you may determine an additional unknown, namely the amount of precipitate which is present at equilibrium. This choice is made by you when you are prompted to specify whether your total concentrations refer to the aqueous solution only or to the whole system (solution and solid phases), respectively.
There are two possible kinds of remedial action which you can take if you experience problems with initial estimates (these frequently being the cause of numerical underflows or overflows). In both cases you need to determine, by systematic investigation, guesswork and/or trial-and-error, which one or more of the VARIABLE basis species is responsible. Underflows and overflows occur when the initial estimate for the concentration of a variable basis species is either much too high or much too low, respectively. Given the limited range of real numbers supported by JESS (10^-38 to 10^+38), it is easy to find chemical systems with very large equilibrium constants that blow a computational foo-foo valve! JESS attempts to protect you from 'hard crashes' when this happens but it is not easy for it to remedy the problem itself automatically. While a larger range of real numbers might help in a few instances, the problem is usually due to some fundamental mismatch in the equations which would have to be diagnosed and corrected anyway. Instead you must yourself try one or both of the following possible approaches. First, you can change the variable basis species. This is done by giving the species you want (instead of that obtained by default) a high(er) priority in the order for variable basis species, which is specified using TELBAS. You must aim to replace the default species by another in the same mass balance equation which, at equilibrium, occurs in greater concentration. For example, in acid solutions, it is much better to have H+1_NH3 as a variable basis species than NH3 itself and in alkaline solutions it is better to use Al+3_(OH)4-1 than Al+3. Secondly, you can make DOQED use a better initial estimate of the variable basis species concentration than it does automatically. By default, the initial estimates used for variable basis species concentrations are the total concentrations specified for the corresponding MBU basis species. This is optimal when the variable basis species is predominant (as just described) but it is unsatisfactory otherwise. You can reduce the initial estimate(s) for any variable basis species using TELQED under the 'Advanced Facilities' option and selecting 'Initial Estimates'. You then simply specify either: '1. log(Free/Total Concentration Ratios)' or '2. log(Free Concentrations)'. The value(s) you enter must be followed by at least one blank space and the variable basis species symbol. Typically, you should use the first of the two options and try '-10.0' or (if that doesn't work) '-25.0'. We are unaware of any equilibrium system which cannot be solved by appropriate action as described above. However, especially with large models, the answer can sometimes be quite tricky to find. Perseverance may be needed! Perhaps the most difficult cases occur when you try to model systems with a set of equations that do not actually have a solution. Such instances can be very opaque. For example, you may be asking for a solid to be held at equilibrium when other constraints require that all its components are fully dissolved. Solving for ionic strength at equilibrium and/or imposing the charge balance equation can also often lead inherently to numerical instability. Consult the index using the search term 'large model' for extra assistance.
Unexpected/unwanted species may sometimes appear amongst the VBL/MBU basis species generated by program DOBAS. These arise simply because there are no reactions in the database linking them to the basis species that you do expect. Typically, this occurs when the species are kinetically inert (as happens for example with Cr(III) and Co(III) complexes). There is nothing wrong about these species; you must simply appreciate that their (total or free) concentrations must be specified in any equilibrium calculation involving them - their concentrations cannot be calculated from the data for the other basis species only. You may, however, wish to remove these species from your calculation, e.g. for cosmetic reasons. This is the same as assuming that they do not occur in your system at equilibrium because they don't have the opportunity (or time) to form. There are a number of ways to eliminate them. Perhaps the best way is to specify their free concentrations using program TELQED such that they have no affect on the equilibrium calculation. Simply select option 2 on the modify menu of TELQED and enter each offending species as having a log(conc) = -999. If, initially, you choose to 'create a new list' all these species will appear automatically, thus saving you from having to type them out yourself. You can also sometimes eliminate them by making appropriate entries in the 'Exclude Primitives' or 'Exclude Reactions' lists found under the 'Advanced Facilities' option of program TELLGK. Finally, there is the possibility of killing the offending species in your sub-database (usually called 'DBA') using program UPDJTH. This is generally not recommended (but only because it is good practice to avoid modifying your sub-database whenever there is some reasonable alternative to doing so).
If you have new reactions and/or equilibrium constants which you want to include in your GEM stages modelling, you can do so by entering them yourself using program UPDJTH. First make a backup copy of the database which is held as JPD*.IND files in the ..\VEWDTA folder. Then make a working copy somewhere else. We use the ..\BUILD folder. Move to the ..\BUILD folder, check it is empty, and copy with command: copy %jv%\jpd*.ind Fire up program UPDJTH. Enter the database name: JPD You then find (or insert) the reaction and then you enter the new constants (called Data). Look up the procedure in the User's manual. (Start with the Primer if you are not familiar with JTH. Prpgram HELPER also has a summary under 'How to enter new data into a JTH database') When finished: 1. Run program UPDUCC 2. Overwrite the database in ..\VEWDTA with: copy jpd*.ind %jv% You should then be good to go!
There are two ways to see which lgKs were used in your speciation calculation (by programs DOQED and VEWQED): 1. Use the OUT stage. lgK (as used) is a determinand that you can request using TELOUT and get by running DOOUT and then PRTOUT. 2. Use VEWBAS to inspect the UCCs and have them evaluated for conditions you specify.
Resident data is the term we give to the data structures which are set up in your directory space for modelling purposes. The data is used throughout the GEM stages of calculation. It exists in a largish number of files and is highly structured (although this structure may not be clearly evident to you). These resident data files serve a variety of purposes. In particular, they provide the means of communication between different programs of the GEM stages, they allow us to set up the default conditions for your modelling and they represent a definitive statement of the current equilibrium calculation. For the most part, you need not concern yourself with the resident data files or their contents - their role in your modelling procedure is handled automatically and transparently. However, there is one important exception to this: you must ensure that the information stored in resident data is not lost in the event of certain accidents (such as a power failure) which might cause your data files to be corrupted. Otherwise you can lose the work you have put into developing your current model. Consult the index using the search term "secure + resident" (without quotes) for the precautions you should take from time to time during your modelling. Further information about resident data is available. Consult the the index using the search term "user + resident" for details that more advanced users might find useful and "utilities + resident" for a short description of the programs available to create and manage resident data manually.
The modular nature of JESS means that your work is generally performed in a sequence of well-separated steps using many, relatively small programs (rather than, say, a single gigantic one). There is consequently an important need for communication between programs. Clearly, the data that must be transferred from one program to another comes in a very wide variety of forms. Putting all this into a conventional (formatted sequential) computer file, or even distributing it between a number of such files, would be inappropriate. Every time a program required data it would have to search linearly through everything, closely following a layout of the data that mostly had nothing to do with itself. This would not only slow you down but it would also make programming horrifyingly more tedious and complicated. A convenient method which overcomes this, and which has, a number of other practical advantages, involves what we have termed "resident data". This refers to an arrangement of data contained in a number of files that permits access to individual items of information conveniently, efficiently and specifically. In computer science jargon the data is structured (i.e. laid out in a well-defined hierarchy), typed (i.e. carefully labelled according to its kind, be it an integer, a number with a decimal point, a string of alphabetic characters or whatever), and named (i.e. identified and accessed by a name rather than by position). Generically, such items of information are called "data objects". Physically, the resident data always comprises at least two files called RSDATA.USE and RSDATA.XXX, which exist in your own filespace. (Other files named RSD*.TXT may also occur.) All programs accessing resident data expect to find these files in your current default directory - so you must ensure that you are in the correct place before executing such programs. Note that you cannot have two different sets of resident data co-existing in the same directory. Further information about resident data is available. Consult the the index using the search term "GEM + resident" (without quotes) for basic details that you need to know in the context of the equilibrium calculations using the GEM stages, the term "secure + resident" for the precautions you should take from time to time during your modelling, and "utilities + resident" for a short description of the programs available to create and manage resident data manually.
It is important to secure the data files used in your modelling calculations in case one of the GEM stage TEL*** programs should terminate prematurely, e.g. if the computer crashes due to a power failure or whatever. You cannot safely recover these files so you must re-instate them from a copy made by you prior to the crash. It is your responsibility to ensure that this copy of your data is made from time to time and sufficiently frequently to avoid a serious loss of your effort should a crash occur. You can, of course, copy the whole contents of your modelling directory to another location. This is the most secure procedure but it can be time-consuming. An alternative, which in practical terms is almost as good, is to use the JESS procedures for saving (and restoring) your resident data. Usually, the save is accomplished by a command (at operating system level) such as "doi save" (without quotes). The corresponding restoration of your resident data (from the most recent saved version) is then accomplished by "doi rcvr".
The symbol dH (for delta-H) is used to indicate enthalpy change throughout JESS. Values for dH under various conditions are stored explicitly for any reaction in a thermodynamic (JTH) database. These are used to determine how the equilibrium constants, lgKs, vary with temperature. Note that dH values are not used directly in the modelling calculations performed during the QED stage of the GEM calculations. The information appears instead in the different values of lgK which are fitted to obtain the unconditional correction coefficients (or UCCs). You can, however, evaluate the value for dH from the UCCs. Brief description of the basic thermodynamic principles concerned with enthalpy can be obtained by searching the index for "equilibrium" (without quotes). Other information relevant to the above is indexed under "GEM", "QED", and "UCC".
A JESS Indexed File (or JIF) is a FORTRAN direct access file structured so that items (strings of characters) can be rapidly stored and then accessed. Such items can be of variable length and they can contain multiple "fields" in terms of which the items are sorted and by which they can be retrieved. JIFs are extensively used for maintaining JESS databases (especially JTH, JLR and RSD). They JIF filename extensions are IND, KEY and USE.
A QIC object is a collection of structured (numerical) data stored in a FORTRAN direct access file so that the values can be rapidly stored and then accessed. QIC objects are used in JESS primarily as a means of communication (data transfer) between computer programs. They are used extensively in the GEM stage calculations. The relevant files have names beginning with Q and having ZZZ as the file extension.