SPECIES
Ver. 1.33
Documentation and Users' Manual
Phillip Barak
University of Wisconsin
Dept of Soil Science
1525 Observatory Dr.
Madison, WI 53706-1299
e-mail: barak@calshp.cals.wisc.edu
November 1992
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . .
2
BASICS . . . . .
Loading . .
Menu . . .
Input . . .
Calculation
Output . .
.
.
.
.
.
.
3
3
3
3
4
5
. . . . . . . . . . . . . . . . . . . . . . . . .
7
MENU TREE
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
STRUCTURE . . . . . . . . . . . . .
Solution Data . . . . . . . . .
Equilibrium Constants . . . . .
Continued Fractions . . . . . .
Concentrations & Ionic Strength
Species Distribution . . . . .
Ion Activities . . . . . . . .
Ion Activity Products . . . . .
MODIFICATIONS
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8
9
9
9
11
11
12
12
. . . . . . . . . . . . . . . . . . . . . . . 12
HARDWARE AND SOFTWARE REQUIREMENTS . . . . . . . . . . . . . 15
DISTRIBUTION & UPDATES . . . . . . . . . . . . . . . . . . . 16
Barak, P. 1990. SPECIES: A spreadsheet program for modeling
speciation of soil solution. J. Agron. Educ. 19(1):44-46.
SPECIES
Documentation and Users' Manual
2
INTRODUCTION
SPECIES is a spreadsheet-based program for equilibrium
calculations of ion activities and chemical speciation in soil
solutions and other aqueous systems. No use of external input
or
output files is required and the internal operation of SPECIES
may be followed without knowledge of a higher-level programming
language. Free ion concentrations are identified by their
standard chemical symbols so that the chemical meaning of each
species remains apparent throughout the program. Equilibrium
calculations are based on iterative solution of mass balance
equations using the continued fraction method, a Gauss-Seideltype iterative algorithm for solving simultaneous nonlinear
equations. The graphics package integrated with the spreadsheet
allows a number of preprogrammed graphs to be viewed on-screen
and sent to disk for printing using the menu-driven software
command language.
As written, SPECIES calculates over 70 hydrolysis species
and complexes of Al, Ca, Mg, Na, K, NH4, PO4, SO4, F, Cl, NO3,
CO3, Fe, Mn, Si, and B, considering solution pH and pe; ion
activity products are computed and solutions are examined for
saturation with respect to more than 25 minerals. SPECIES can
be
expanded and modified by the use of the spreadsheet command
language to include additional species and mineral-regulated
activities.
SPECIES
Documentation and Users' Manual
3
BASICS
LOADING
SPECIES is loaded from the Lotus 1-2-3 environment by
pressing "/File Retrieve", moving the cursor to highlight
"SPECIES.WK1", and keying {ENTER}.
MENU
SPECIES may be operated using the SPECIES menu which may
be
called to the command line of the spreadsheet by pressing AltA.
The major headings of the SPECIES menu tree are GOTO, CALC,
GRAPH, and PRINT. A hierarchal diagram of the SPECIES menu is
given in the section titled MENU TREE.
INPUT
The primary input template can be reached either by
pressing
{HOME}, by using the GOTO command from the SPECIES menu, or by
pressing F5{GOTO}, F3{NAME}, and {ENTER} when "0SOLUTION" is
highlighted. Data is input by moving the cursor to the
appropriate cell using the arrows on the keyboard and then
overwriting the default values (set as either NA for carbonates
or zero for all other species). Soluble carbonates should be
entered as either titratable or total carbonates, or as
carbonates in equilibrium with a specified CO2 partial pressure
by filling in one of three alternatives under "Carbonates" in
the
input template.
SPECIES
Documentation and Users' Manual
4
Unit conversion may be performed at the input cell. For
example, at the Cl input cell, 72 mg Cl/L can be converted to
moles/L by typing "72/35.5/1000 {ENTER}"; "0.0020281" will be
entered on the screen but the formula for unit conversion will
be
retained in memory at the Cl input cell for future use.
The equilibrium constants are also input values and are
listed in a field which may be reached either by using the GOTO
commands of the SPECIES menu or by keying F5{GOTO}, F3{NAME},
using the arrows to highlight "2CONSTANTS", and pressing
{ENTER}.
Existing constants may be updated by overwriting current
values.
Adding constants will be described in MODIFICATIONS.
CALCULATION
Calculations begin by either keying F9{CALC} for a single
iteration or by selecting CALC from the SPECIES menu (Alt-A)
for
automatic iteration to a preset convergence criterion. The
command "RESTART" from the CALC menu will reset the iteration
counter from a previous speciation calculation to zero before
resuming iterations. The automatic iteration may be interrupted
with {Control}{Break}, followed by {ESC} to resume normal
operation.
If calculations are begun with F9{CALC}, then the cursor
can
be set at the primary output field "5ION_ACTIV" beforehand in
order to monitor the course of the calculations.
SPECIES
Documentation and Users' Manual
5
OUTPUT
The primary output field is reached by either selecting
the
GOTO commands from the SPECIES menu or pressing F5{GOTO},
F3{NAMES}, using the arrows to highlight "5ION_ACTIV", and
pressing {ENTER}. This output field displays the current number
of iterations, ionic strength and charge balance, tests
convergence, and lists the negative logarithm values of total
concentration, free ion concentration, and free ion activity
for
each input component. The partial pressure of CO2 based on free
carbonate species, pH, and Henry's Law is also calculated.
The second output field is reached by either selecting the
GOTO commands of the SPECIES menu or by keying F5{GOTO},
F3{NAME}, using the arrows to highlight "4SPECIES_DIST", and
pressing {ENTER}. This output field lists the concentration of
all species of a given component and the species distribution
for
each. In addition, a mass balance check, i.e., the sum of
species/total concentration, is displayed for each species;
upon
convergence of calculations, the mass balance check equals
unity
for each component.
Graphic display of species distribution may be viewed onscreen by either following the GRAPH commands of the SPECIES
menu
or pressing "/Graph Name Use" and then highlighting the desired
component using the arrow commands and pressing {ENTER}. The
graphs are programmed as pie graphs but may be changed to
histograms either through the SPECIES menu or by keying
"(/Graph)
SPECIES
Documentation and Users' Manual
6
Type Bar View". Hard copy of the graph may be obtained either
through the SPECIES menu or by typing "(/Graph) Save", with a
filename of the user's choice; the graph file can be sent to
the
printer using the Printgraph program of Lotus 1-2-3. If the
input
concentration of a component is zero, the corresponding graph
is
not available; if an unavailable graph is called, the program
will beep and operation will resume after pressing any key.
The third output field is reached either through the GOTO
commands of the SPECIES menu or by keying F5{GOTO}, F3{NAME},
using the arrows to highlight "6IAP" and pressing {ENTER}. This
output field calculates the negative logarithm of a number of
ion
activity products (pIAP); corresponding values for equilibrium
with defined mineral species are listed.
Any field can be output to the printer or disk either by
selecting PRINT commands from the SPECIES menu or by using
either
"/Print Printer" or "/Print File" commands; context-sensitive
help may be called with F1{HELP} for assistance in defining
range
and format of output. The use of {PRINTSCREEN} will print the
current screen contents, together with the Lotus menu and
frame.
Some fields are wider than those printed on standard printers;
in
such cases, text will either be wrapped around or printed on
several forms, depending on printer configuration. Condensed
fonts can be selected for most printers and wider print fields
can be obtained using the Lotus "/Print Printer Options Margins
Right" commands.
SPECIES
Documentation and Users' Manual
7
MENU TREE
The SPECIES menu is called to the command line of the
spreadsheet by pressing the ALT and A keys simultaneously. At
each level of the menu, the primary command line contains a
list
one word commands, beneath which the secondary command line
contains a short description of the command currently
highlighted. Commands may be selected by moving the cursor to
highlight the desired command and then pressing {ENTER}. The
SPECIES menu tree is as follows:
GoTo
INPUT
CALCULATIONS
OUTPUT
Soln_Dat, Equi_Constants, Xret
Cont_Fract, Concn&Ion_Str, Xret
Species_Dist, Ion_Activ, IAP,
Xret
Calculate
START
RESTART
SeeGraph
[Enter name to make current: {list}]
PIE
BAR
SAVE [Enter graph file name: {list}]
Cancel,
Replace
NEXT
BACK
Print
Soln_Dat, Equi_Constants, Species_Dist, Ion_Activ,
IAP,
Xret
Exit
AboutSPECIES
Alternatively, SPECIES may be run without the SPECIES menu
by using the built-in command structure of Lotus 1-2-3 or
compatible spreadsheet (usually called to the command line with
"/") and software-defined function keys.
SPECIES
Documentation and Users' Manual
8
STRUCTURE
The transparent structure of SPECIES may be viewed by
scrolling through the spreadsheet. All computational cells are
annotated. The user is therefore urged to become familiar with
the internal workings of the program. SPECIES comprises two
input
fields, two computational fields, and three output fields.
SPECIES iterates from the top of the worksheet to the bottom,
left to right, with the following fields and their equivalent
range names:
Field Type
Field Content
Range Name
Input:
Solution Data
0SOLN_DAT
Equilibrium Constants
1CONSTANTS
Continued Fractions
2CONT_FRACT
Computations:
Concentrations &
Ionic Strength
3CONCN&ION_STR
Output:
Species Distribution
4SPECIES_DIST
Ion Activities
5ION_ACTIV
Ion Activity Products
6IAP
SPECIES
Documentation and Users' Manual
9
SOLUTION DATA
All input values are in mole/L units. Input values are
total
concentrations of a given component, for example, total Ca,
total
Si, and total PO4, irrespective of speciation. By filling in
the
appropriate cell of the input template, input of soluble
carbonates is either titratable carbonates (= HCO3 + CO3, and
derived complexes), total carbonates (= H2CO3 + HCO3 + CO3, and
derived complexes), or equilibrium with a specified CO2 partial
pressure.
EQUILIBRIUM CONSTANTS
Equilibrium constants are all activity-based and are
correct
for 25 C (298 K). Constants are all expressed in terms of ion
activities of Al, Ca, Mg, Na, K, NH4, PO4, SO4, F, Cl, NO3,
CO3,
Fe3+, Mn2+, H4SiO4, and B(OH)4. These constants represent
results
of experiments of various types and are empirical. Some
controversy exists as to the best values and the correct
reactions which occur. Equilibrium constants are usually
reported
in the chemical literature as log K and are here translated
back
to antilog form by "10^{log K}".
CONTINUED FRACTIONS
The calculations of this field are the essence of SPECIES.
Mass balance equations for each component are solved by the
method of continued fractions, in which the nonlinear mass
SPECIES
Documentation and Users' Manual
balance equations are rearranged to solve for free ion
concentrations. As an example, assume a simplified system
consisting only of Ca\2+ (=CA), SO4\2- (=SO_4), and the ion
pair
CaSO4\0, for which the equilibrium constant is defined as:
(1)
K = f_0*[CaSO4\0]/(f_2*CA)*(f_2*SO_4)
where [ ] indicate concentrations and f_z is the activity
coefficient of an ion of charge
z. Writing the mass balance
equation for Ca and substituting for [CaSO4\0] gives:
(2)
[Ca(total)] = CA + [CaSO4\0]
= CA + K*(f_2*CA)*(f_2*SO_4)/f_0
Rearranging to solve for CA gives:
(3)
CA = [Ca(total)]/(1 + K*f_2*(f_2*SO_4)/f_0)
The equivalent expression for SO_4 is:
(4)
SO_4 = [SO4(total)]/(1 + K*f_2*(f_2*CA/f_0)
For each component, the denominator of the fraction is
continued
to include all desired hydrolysis species and complexes.
In SPECIES, use is made of the chemical symbols
themselves,
e.g., CA, MG, etc, with the exception of combinations of
letters
10
and numbers, e.g., NO_3, SO_4, F_2, etc., which are written to
avoid ambiguity with cell NO3, SO4, and f2. The location of the
expression used in the spreadsheet for their calculation can be
SPECIES
Documentation and Users' Manual
11
located by keying F5{GOTO}, F3{NAME}, using the arrows to
highlight the desired name, and pressing {ENTER}. Equilibrium
constants are taken from the list in the CONSTANTS field.
CONCENTRATIONS & IONIC STRENGTH
In this field, all species considered are collected in
columns based on their ionic charge, using concentrations based
on current values of free ion concentrations from the previous
sections. Ionic strength is calculated from the sum of ions of
each charge, according to:
I = 1/2 SUM [ z^2 * Conc(z) ]
Activity coefficients are then calculated by the Davies
equation:
f_z = 10^[-0.509*z^2*{I^0.5/(I^0.5 + 1) - 0.3 I}]
When a value for pe is entered in the solution data field,
Fe and Mn are speciated for Fe(3+), Fe(2+), Mn(4+), Mn(3+),
Mn(2+) and their complexes. If no value is input for pe, Fe and
Mn, if entered, are speciated as Fe(3+) and Mn(2+).
SPECIES DISTRIBUTION
For each component, there is a row each for all species,
their concentrations, and relative fraction of the total
component. Next follows a sum of the relative fractions which
on
SPECIES
Documentation and Users' Manual
12
complete convergence of all equilibrium calculations is unity
for
all components.
ION ACTIVITIES
In this primary output field are an iteration counter, a
convergence test, calculated ionic strength, charge balance
check, and a table summarizing negative logarithm values of
total
concentration, free ion concentration, and free ion activity.
Convergence is determined as the maximum deviation from perfect
mass balance among the components.
ION ACTIVITY PRODUCTS ( = IAP)
Based on the -log [ion activities] of the previous
section,
-log [ion activity products] are calculated and compared to
reference values for a number of known minerals. A positive
saturation index indicates that the solution is supersaturated
with respect to the given mineral.
MODIFICATIONS
SPECIES has been written to teach concepts of ionic
activity
and speciation as applied to soil chemistry using a number of
major ions and their complexes. The flexible structure of the
spreadsheet permits relatively simple customization of SPECIES
to
SPECIES
Documentation and Users' Manual
13
cover more extensive calculations. The advantage of the
spreadsheet format is that expansion of SPECIES by the user
requires understanding the operation of the program rather than
knowledge of a particular programming language. Several types
of
modifications are described below. User-modified versions of
SPECIES should be given alternate names to prevent overwriting
of
the original version upon file save ("/File Save {filename}). A
copy of SPECIES.WK1 is provided also as SPECIES.BAK in the
event
of accidental overwriting and can be called by "/File Retrieve
SPECIES.BAK".
1.
Change convergence criterion.
The convergence criterion
may
be altered by using F5{GOTO}, F3{NAME}, using the arrows to
highlight "TEST", {ENTER}, and overwriting the convergence
criterion.
2.
Mineral equilibrium.
SPECIES as written works from an
input
solution composition, but mineral equilibrium can be
substituted.
For example, if Ca concentration is to be set by equilibrium
with
calcite, the value of CA in the continued fraction calculation
field (located by keying F5{GOTO}, F3{NAME},"CA", {ENTER}) may
be
replaced by "@IF(CO_3>0,10^-8.41/(CO_3*f_2)/f_2,0)". Testing
CO_3
against 0 prevents division by 0 errors. If the value of Ca
concentration is conditional, such as calcite-dependent to a
maximum concentration of 10^-3 moles/L, then CA may be
SPECIES
Documentation and Users' Manual
14
overwritten using the logical if-then statement, "@IF(CO_3>0,
(@IF(10^-8.41/(CO_3*f_2)/f_2>10^-3,10^-3,10^-8.41/(CO_3* f_2)/
f_2)),0)".
3.
Additional species of existing components. Additional
species
may be added to the worksheet by:
A. Adding the equilibrium constant to the list in
2CONSTANTS.
B. Add the appropriate term to the continued fraction of
all
components present in new species.
C. Add the new species and related calculations to both
CONCENTRATIONS and SPECIATION fields.
To simplify the steps, it is recommended that a string be
composed, copied to each field needed, and then modified to
suit
the needs of the field. For CaSO4\0, for which the equilibrium
constant is located at cell S6, the recommended string would be
"'+S6*(F_2*CA)*(F_2*SO_4)/F_0".
4.
Additional components.
Adding new components first
requires
adding rows to the each of the fields using the "/Worksheet
Insert Row" command. Use the "/Range Name Create" command to
identify the cell, e.g., CU, ZN, or LIG (organic ligand),
containing the result of the new continued fraction. Follow the
same steps as adding additional species of existing components.
Compare with the formulae of preexisting components and
species.
SPECIES
5.
Documentation and Users' Manual
15
Ionic strength calculated from electrical conductivity.
Particularly if the chemical analysis of the soil solution is
incomplete or if the cation-anion balance is not satisfactory,
the calculational cell for ionic strength (located by F5{GOTO},
F3{NAME}, IS, {ENTER}) may be overwritten with ionic strength
estimated from electrical conductivity of the solution, which
may
be added to the input template. Literature values for
proportionality constants are typically ~0.013 (moles/L)/(dS/m
=
mmho/cm).
HARDWARE AND SOFTWARE REQUIREMENTS
SPECIES is fully compatible with Lotus 1-2-3 2.x, 3.x, and
123 for Windows operating on IBM PC, XT, AT, PS/2, and
compatible
computers. A properly configured graphics card is required for
on-screen graphics of species distribution.
SPECIES is also fully compatible with QuattroPro 3.0 and
4.0 when either the macro is set to "/Tools Macro KeyReader" or
when QuattroPro is invoked as "Q123". SuperCalc uses a
"//Macro,
Convert, 123" command to translate the SPECIES menu into
equivalent functions and commands. Excel 4.0 for Windows is
also
fully compatible. Spreadsheet programs that are less than fully
Lotus 1-2-3-compatible may not correctly interpret the SPECIES
menu; in such cases, SPECIES may be operated using the
equivalent
spreadsheet commands described in this manual.
SPECIES
Documentation and Users' Manual
16
After conversion with Apple File Exchange, SPECIES can be
used on a Macintosh platform. Lotus 123 for Mac is completely
compatible with SPECIES.WK1. For Excel 4.0 for Mac, set the
Calculate option to manual and iterate before opening the
SPECIES.XLS file; the custom menu will not work in Excel for
Mac.
DISTRIBUTION & UPDATES
SPECIES is copyright by the author and is offered as free
educational software. No warranty is given or implied.
Distribution by users is encouraged. SPECIES should be
distributed with the following files:
1.
2.
3.
4.
5.
README.1ST
SPECIES.BAK
SPECIES.DOC
SPECIES.WK1
SPECIES.XLS
(ASCII, one-screen explanatory file)
(backup copy of SPECIES program)
(ASCII, this documentation file)
(working copy of SPECIES program)
(Excel version, necessary for Excel
for
Mac)
Additional files--PLAYER.TXT, PLAYER.EXE, (C)ALDUS.'92-may
also be distributed to run the file SPECIES.DEM, an optional
file, on PCs. See PLAYER.TXT for instructions and for use on a
Macintosh platform.
The author requests that suggestions, requests for
updates,
and significant modifications be sent to:
Phillip Barak--SPECIES
University of Wisconsin
Dept. of Soil Science
1525 Observatory Dr.
Madison, WI 53706-1298
(e-mail: barak@calshp.cals.wisc.edu)
Where applicable, the appropriate citation for this
program
is:
Barak, P. 1990. SPECIES: A spreadsheet program for modeling
speciation of soil solution. J. Agron. Educ. 19(1):44-46.