edu.davidson.chm.equilibria
Class Titration

java.lang.Object
  |
  +--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