USCD1100 SOLUPLOT.

1. NAME OR DESIGNATION OF PROGRAM:  SOLUPLOT.

3. DESCRIPTION OF PROBLEM OR FUNCTION

SOLUPLOT is a program designed  to calculate and plot complex potential - pH diagrams and log oxygen activity - pH diagrams for aqueous chemical systems, considering speciation of ligands, from free energy and thermodynamic activity data. These diagrams, commonly referred to as Eh-pH and aO2-pH diagrams, respectively, define areas of predominance in Eh-pH diagrams or aO2-pH space for chemical species of a chemical system at equilibrium. Over an area of predominance, one predominant species is at greater activity than the other species of the system  considered. The diagram axes, pH (a measure of hydrogen ion activity) and either Eh or log aO2 (measures of the tendency toward  either oxidation or reduction), are parameters commonly applied in describing the chemistry of aqueous systems.

4. METHOD OF SOLUTION

SOLUPLOT calculates a diagram involving the speciation of ligands in three general steps. First the speciation of a pH-dependent ligand system, if specified in the input data, is  calculated. Since this system is solely pH-dependent, areas of pre-  dominance are defined by constant pH lines which divide the diagram  vertically into a number of rectangular subsections.
Secondly the program calculates the speciation of an Eh-pH- dependent ligand system, if so specified in the input data. This speciation may be represented by vertical, horizontal, and sloping bounds. The initial diagram is now effectively divided into a number of subdiagrams, each representing the intersection of the area of predominance of one Eh-pH-dependent ligand species.
Finally the program takes each subdiagram separately and calcu- lates the speciation of the main system. Within each subdiagram the  program actually calculates two speciations, one among all the species in the main system (the solid-aqueous diagram), and one among only the aqueous species (the aqueous species diagram). The main system within a subdiagram includes main system species, all non-speciating ions, and the pH-dependent ligand species and the Eh-pH-dependent ligand species that are predominant within that subdiagram.

5. RESTRICTIONS ON THE COMPLEXITY OF THE PROBLEM

Program SOLUPLOT will, when properly employed, produce highly reliable represen- tations of the equilibrium states of a wide variety of chemical systems. In general, the complexing of any ion with a large number of ligands with characteristic atoms oppositely charged with respect to that ion may be readily calculated. Results as accurate as carefully hand-plotted diagrams may be routinely obtained in a fraction of the time required for hand calculations.

The user may wish to consider species of variable composition, such Fe(1-x)S(pyrrhotite). This is generally possible if the input file is suitably constructed. The pyrrhotite solid solution may be represented in this example by a series of "S" cards for the species FeS, Fe11S12, Fe10S11, etc. The resultant diagram will be effectively "contoured" according to relative iron-sulphur composition.

The limitations of this model should be taken into account when attempting more specialised calculations. Specifically, since the program first independently calculates ligand speciation and then calculates main system speciation within each ligand species' area of predominance, no interaction among ligand systems (and non- speciating ions) is considered. Therefore, any attempt to calculate  a diagram considering both cations and anions as ligand species or ions will not produce a rigorously correct equilibrium diagram. As an example, a calculation with a main system of copper species and ligand systems of iron species and sulphur species would not produce species forming iron sulphides would not be considered.

Most calculations attempted with this class of model, however, utilise main system cation (or in some cases anion) species reacting with a number of anions (or cations) either as ligand system species or non-speciating ions. In these cases, complexing among ligand species is negligible and all relevant chemical reactions are considered by the program.

6. TYPICAL RUNNING TIME

Time requirements for job execution at Penn State vary from under 20 seconds to about 35 seconds depending on the complexity of the chemical system considered.
NEA-DB executed the test cases included in the package on VAX-11/780 in 1 minute and 45 seconds of CPU time.

7. UNUSUAL FEATURES OF THE PROGRAM:  Both Eh-pH and aO2-pH can be calculated.

8. RELATED AND AUXILIARY PROGRAMS:  None. See part 13. for library subroutines.

10. REFERENCES:

- C.M. Bethke:
  Program SOLUPLOT.  Report Draft (December 1978)

11. MACHINE REQUIREMENTS

The program writes to disk, uses a line printer and needs 280K of memory. A Calcomp or Tektronics 4662 plotter are used to create the final output.
NEA-DB implemented the program on VAX-11/780 in 99,840 bytes of main storage for SOLUPLOT and 73,728 bytes for the auxiliary programs. To test the graphics features, a VERSATEC plotter was employed.

13. OPERATING SYSTEM UNDER WHICH PROGRAM IS EXECUTED

While SOLUPLOT in its present implementation is explicitly designed for use with Penn  States's computation facilities, its adaptation to most other systems should present few problems.

   See section 14. for WATFIV and GCS requirements.

Several subroutines called during program execution are specific to Penn State. Subroutine UPPER called from SOLUPLOT subroutine INPUT converts upper and lower case alphanumeric strings to upper case. If all control characters and control words in the input data  are in upper case this subroutine may be removed from the source code. However, replacing UPPER with a subroutine of similar function should not be a problem. Also, two subroutines in the graphics portion of the program may need to be replaced or removed. Subroutine NAME returns the alphanumeric image of the current user's account number (characters 1 to 13) and name field (characters 14 to 33). Subroutine DATE returns an alphanumeric image of the data on which the program is run.
Program CONTK is a Penn State routine to convert Calcomp plotting code produced by GCS to plotting code decipherable by a Tektronics flat-bed plotter. In normal implementation of GCS this job step is not necessary.
The implementation at NEA-DB was done under VMS 3.4 (VAX-11/780).

14. OTHER PROGRAMMING OR OPERATING INFORMATION OR RESTRICTIONS

Most of the program is written in WATFIV and will not run without modifi- cation on a standard FORTRAN IV compiler. Extensions of the ANSI standard used in SOLUPLOT source include in-memory READ and WRITE statements, multiple assignment statements, IF-THEN DO-ELSE DO blocks, format free input, multiple statements per card, arithmetic  expressions in I/O lists, COMMON block initialisation outside of BLOCK DATA subprograms, CHARACTER type statements, character re- placement statements, and relational operators applied to alpha- numeric strings. A recent WATFIV manual should be referred to before attempting to translate the program into standard FORTRAN.
The graphics portion of the program is written in FORTRAN IV for a G compiler and uses the Graphics Compatibility System (GCS), written at the United States Military Academy, which is generally available at major computer installations. However, and graphic system may be substituted for the GCS since only general functions are utilised (moves, straight line segments, and character output).
If the original implementation of GCS is retained, particular attention should be payed to the argument of subroutine USTART.
Legal values of this argument depend on the output device to be used and will vary from system to system.

15. NAME AND ESTABLISHMENT OF AUTHOR

C.M. Bethke
Department of Geosciences
Pennsylvania State University
University Park, PA 16802

File name	File description	Records
USCD1100_01.003	INFORMATION FILE	109
USCD1100_01.004	SOLUPLOT SOURCE PROGRAM MODIFIED AT NEA DB.	2606
USCD1100_01.005	GRAPHICS SOURCE PROGRAM MODIFIED AT NEA DB.	619
USCD1100_01.006	PROCEDURE TO IMPLEMENT SOLUPLOT ON VAX	43
USCD1100_01.007	SOLUPLOT TEST CASE1 INPUT	41
USCD1100_01.008	SOLUPLOT PRINTED OUTPUT FOR TEST CASE 1	883
USCD1100_01.009	SOLUPLOT TEST CASE 2 INPUT	42
USCD1100_01.010	SOLUPLOT PRINTED OUTPUT FOR TEST CASE 2	893
USCD1100_01.011	SOLUPLOT ORIGINAL SOURCE PROGRAM	2390
USCD1100_01.012	AUXILIARY ASSEMBLER ROUTINES(TIME,DATE) IBM	112
USCD1100_01.013	GRAPHICS ORIGINAL SOURCE FOR CALCOMP	566
USCD1100_01.014	GRAPHICS ORIGINAL SOURCE FOR GCS	338