edu.davidson.chm.equilibria
Class Titration

java.lang.Object
  extended by edu.davidson.chm.equilibria.Titration

public class Titration
extends java.lang.Object

The Titration class describes a titration. The user supplies a ChemSystem and identifies a titrant and a sample solution. The class provides methods for generating a titration curve and for fitting experimental data by optimization of equilibrium constants and/or analytical concentrations.

Copyright 2001 David N. Blauch

Version:
1.0
Author:
David N. Blauch

Constructor Summary
Titration()
           
Titration(ChemSystem _chemSystem, java.lang.String _titrantLabel, java.lang.String _sampleLabel)
          The Titration object models a titration.
 
Method Summary
 void addReaction(Reaction _rxn)
          Adds a reaction to the collection of reactions whose equilibrium constants are to be determined by the curve-fitting procedure.
 void addSpecies(Species _species)
          Adds a species to the collection of species whose analytical moles are to be determined by the curve-fitting procedure.
 void apply()
          Applies the best-fit parameters to the original ChemSystem.
 double[] calc(double[] _Vt)
          Calculates a titration curve at the titrant volumes contained in _Vt.
 double[][] calcCurve(double _finalVol)
          Calculates the titration curve.
 void clearReactions()
          Clears all reactions to be used in the curve-fitting procedure
 void clearSpecies()
          Clears all species to be used in the curve-fitting procedure
 boolean fit()
          Performs the curve-fitting procedures.
 double getChiSq()
          Returns the chi-squared value
 double[][] getCovariance()
          Returns the covariance matrix from the last execution of the fit method.
 double getDerivative(int _idx)
          Returns the derivative of the titration curve at the indicated index.
 double getDerivative2(int _idx)
          Returns the second derivative of the titration curve at the indicated index.
 double getGoodnessOfFit()
          Returns the goodness-of-fit
 java.lang.String getInfo()
          Returns information about this class
 double[] getPar()
          Returns an array containing the current values of the parameters from the last execution of the fit method.
 double[] getParStd()
          Returns an array containing the standard deviations of the parameters from the last execution of the fit method.
 void setChiSqTolerance(double _tol)
          Sets the relative tolerance for chi-square.
 void setData(double[] _Vt, double[] _Y)
          Sets the experimental data to be fit.
 void setData(double[] _Vt, double[] _Y, double[] _std)
          Sets the experimental data to be fit.
 void setDisplayIterations(boolean _val)
          If true, the iteration results at each step of the curve-fitting procedure are displayed.
 void setDisplayResults(boolean _val)
          If true, the final results of the curve-fitting procedure are displayed.
 void setEquilibriaTolerance(double _tol)
          Sets the relative tolerance for equilibrium calculations.
 void setLambda(double _lambda)
          Sets the initial value of lambda, the parameter that controls the transition from steepest-descent to Hessian method in the Levenberg-Marquardt algorithm.
 void setLambdaScaleFactor(double _factor)
          Sets the lambda scaling factor.
 void setMaxIncrement(double _val)
          Sets the maximum amount by which a parameter (ln K or ln n) may change during an iteration of the Levenberg-Marquardt algorithm.
 void setMinMaxIncrement(double _min, double _max)
          Sets the minimum and maximum volume increment for a titration calculation
 void setMonitor(java.lang.String _chemSpecies)
          Sets the titration to monitor pX where X is the chemical species identified by the label _chemSpecies
 void setMonitor(java.lang.String _label, java.lang.String _refLabel)
          Sets the titration to monitor a half-cell or cell potential where _label identifies the phase whose potential is to be monitored.
 void setStandardDeviation(double _std)
          Sets the standard deviation to be used for all pX or E values if the individual standard deviations are not defined.
 void setTargetIncrement(double _target)
          Sets the target change in pX or E for a titration.
 void setTolerance(double _tol)
          Sets the absolute tolerance for convergence of parameters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Titration

public Titration()

Titration

public Titration(ChemSystem _chemSystem,
                 java.lang.String _titrantLabel,
                 java.lang.String _sampleLabel)
The Titration object models a titration. The user must supply a ChemSystem that defines a titrant phase and a sample solution phase. The ChemSystem is not altered by any operation of the Titration object, except the apply method.

Method Detail

addReaction

public void addReaction(Reaction _rxn)
Adds a reaction to the collection of reactions whose equilibrium constants are to be determined by the curve-fitting procedure. The user-defined equilibrium constant is used as a seed value.


addSpecies

public void addSpecies(Species _species)
Adds a species to the collection of species whose analytical moles are to be determined by the curve-fitting procedure. The user-defined analytical moles are used as a seed value


apply

public void apply()
Applies the best-fit parameters to the original ChemSystem.


calcCurve

public double[][] calcCurve(double _finalVol)
Calculates the titration curve. The first point is Vt = 0 and the final point is _finalVol (both quantities in mL). The method automatically determines optimal volume increments. Returns null if an error is encountered.

Parameters:
_finalVol - final volume of titrant added (in mL)
Returns:
Vt (mL) values in column 0 and pX or E value in column 1

calc

public double[] calc(double[] _Vt)
Calculates a titration curve at the titrant volumes contained in _Vt. The volumes, in mL, must be in increasing value and must be non-negative.

Returns:
pX or E values

clearReactions

public void clearReactions()
Clears all reactions to be used in the curve-fitting procedure


clearSpecies

public void clearSpecies()
Clears all species to be used in the curve-fitting procedure


fit

public boolean fit()
Performs the curve-fitting procedures. Returns true if the procedure terminated successfully, false otherwise.


getChiSq

public double getChiSq()
Returns the chi-squared value


getCovariance

public double[][] getCovariance()
Returns the covariance matrix from the last execution of the fit method. The various partial derivatives are approximated numerically and the accuracy of these values might be poor.


getDerivative

public double getDerivative(int _idx)
Returns the derivative of the titration curve at the indicated index. An experimental data set must have been previously defined.

See Also:
setData(double[], double[])

getDerivative2

public double getDerivative2(int _idx)
Returns the second derivative of the titration curve at the indicated index. An experimental data set must have been previously defined.

See Also:
setData(double[], double[])

getGoodnessOfFit

public double getGoodnessOfFit()
Returns the goodness-of-fit


getInfo

public java.lang.String getInfo()
Returns information about this class


getPar

public double[] getPar()
Returns an array containing the current values of the parameters from the last execution of the fit method. For Reactions, the parameter is ln K and for Species the parameter is ln n.


getParStd

public double[] getParStd()
Returns an array containing the standard deviations of the parameters from the last execution of the fit method. For Reactions, the parameter is ln K and for Species the parameter is ln n.


setChiSqTolerance

public void setChiSqTolerance(double _tol)
Sets the relative tolerance for chi-square. The relative change in chi-square for successive iterations must be less than this value. Default is 0.001


setData

public void setData(double[] _Vt,
                    double[] _Y)
Sets the experimental data to be fit. The monitoring mode (pX or E) should be set prior to calling this method.

Parameters:
_Vt - array of titrant volumes in mL
_Y - array of pX or E values
See Also:
setMonitor(java.lang.String)

setData

public void setData(double[] _Vt,
                    double[] _Y,
                    double[] _std)
Sets the experimental data to be fit.

Parameters:
_Vt - array of titrant volumes in mL
_Y - array of pX or E values
_std - array of standard deviations for pX or E

setDisplayIterations

public void setDisplayIterations(boolean _val)
If true, the iteration results at each step of the curve-fitting procedure are displayed.


setDisplayResults

public void setDisplayResults(boolean _val)
If true, the final results of the curve-fitting procedure are displayed.


setEquilibriaTolerance

public void setEquilibriaTolerance(double _tol)
Sets the relative tolerance for equilibrium calculations.

See Also:
Equilibria.setTolerance(double)

setLambda

public void setLambda(double _lambda)
Sets the initial value of lambda, the parameter that controls the transition from steepest-descent to Hessian method in the Levenberg-Marquardt algorithm. Default is 0.001


setLambdaScaleFactor

public void setLambdaScaleFactor(double _factor)
Sets the lambda scaling factor. When an improved solution is found, lambda is multiplied by this factor. When a poorer solution is found, lambda is divided by this factor. The smaller the factor, the more rapidly the Levenberg-Marquardt algorithm shifts to the standard Hessian method. The factor must satisfy 0 < _factor < 1.0. Default is 0.1


setMaxIncrement

public void setMaxIncrement(double _val)
Sets the maximum amount by which a parameter (ln K or ln n) may change during an iteration of the Levenberg-Marquardt algorithm.


setMinMaxIncrement

public void setMinMaxIncrement(double _min,
                               double _max)
Sets the minimum and maximum volume increment for a titration calculation

Parameters:
_min - minimum volume of titrant added in a step
_max - maximum volume of titrant added in a step

setMonitor

public void setMonitor(java.lang.String _chemSpecies)
Sets the titration to monitor pX where X is the chemical species identified by the label _chemSpecies


setMonitor

public void setMonitor(java.lang.String _label,
                       java.lang.String _refLabel)
Sets the titration to monitor a half-cell or cell potential where _label identifies the phase whose potential is to be monitored. And _refLabel identifies the phase that serves as the reference electrode. If _refLabel is null, only the half-cell potential is monitored.


setStandardDeviation

public void setStandardDeviation(double _std)
Sets the standard deviation to be used for all pX or E values if the individual standard deviations are not defined.


setTargetIncrement

public void setTargetIncrement(double _target)
Sets the target change in pX or E for a titration. Volume increments are increased or decreased to attempt to achieve the target change. (Default = 0.2 or 0.005)


setTolerance

public void setTolerance(double _tol)
Sets the absolute tolerance for convergence of parameters. All parameters must have converged to this absolute tolerance. Bear in mind that the parameters are logarithmic quantities (ln K or ln n) and thus this tolerance is effectively the relative tolerance for K or n. Default is 1E-4