edu.davidson.chm.equilibria
Class Equilibria

java.lang.Object
  extended by edu.davidson.chm.equilibria.Equilibria
All Implemented Interfaces:
PhysicalConstants

public class Equilibria
extends java.lang.Object
implements PhysicalConstants

Sets up the mathematical description of a arbitrary equilibrium problems

Copyright (c) David N. Blauch

Version:
2.3
Author:
David N. Blauch

Field Summary
 
Fields inherited from interface edu.davidson.chm.equilibria.PhysicalConstants
F, k, No, perm, qe, R, RJ
 
Constructor Summary
Equilibria()
           
Equilibria(ChemSystem _chemSystem)
          This constructor defines the chemical system.
 
Method Summary
 void clearMessages()
          Clears the message list
protected  boolean createEquations()
          Constructs the mass balance, charge-balance, and equilibrium equations for this chemical system.
 java.lang.String getChargeBalance(Phase _soln)
          Returns a string representing the charge balance relation for the phase.
 java.lang.String getInfo()
          Returns information about this class
 java.lang.String[] getMassBalance()
          Returns an array of strings representing the mass balance relations for the chemical system.
 java.lang.String[] getMessages()
          Returns the last set of messages generated by the parse method.
 double getMinValue()
          Returns the minimum positive value for the moles of any species.
 int getNbrMassBalance()
          Returns the number of mass balance equations for the system
 double getTolerance()
          Returns the tolerance for convergence of variables
 boolean parse()
          Parses a chemical system to determine if it a solution exists.
 void printMessages()
          Prints parse messages on the Java console.
 void setChemicalSystem(ChemSystem _chemSystem)
          Sets the chemical system
 void setDisplayIterations(boolean _displayIterations)
          If true, the results of each iteration in the solve() method are displayed.
 void setDisplayLinearSystem(boolean _displayLinearSystem)
          If true, the linear system of equations are displayed at each iteration of the solve method.
 void setDisplayResults(boolean _displayResults)
          If true, the final results of the solve method are displayed.
 void setDisplayTime(boolean _displayTime)
          If true, the time in seconds required to solve an equilibrium problem via the solveProblem method is displayed on the Java console.
 void setEquationTolerance(double _eqnTol)
          Sets the convergence tolerance for functions.
 void setMaxCnt(int _maxCnt)
          Sets the maximum number of iterations to be used in solving the nonlinear system of equations.
 void setMaxInc(double _maxInc)
          Sets the maximum amount a variable can change during a single iteration.
 void setRedundantTolerance(double _tol)
          Sets the tolerance for aborting analysis when redundant chemical equations are encountered.
 void setSVDThreshold(double _svdThreshold)
          Sets the threshold value for setting the diagonal elements from svd to zero.
 void setTolerance(double _tol)
          Sets the relative tolerance for convergence of the amounts of each species
 void setUsePrevious(boolean _usePrevious)
          Sets the usePrevious property.
protected  boolean solve()
          Solves the mathematical problem and automatically updates number of moles for all species.
 boolean solveProblem()
          Solves the equilibrium problem.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Equilibria

public Equilibria()

Equilibria

public Equilibria(ChemSystem _chemSystem)
This constructor defines the chemical system.

Method Detail

parse

public boolean parse()
Parses a chemical system to determine if it a solution exists. Method returns true if no problems are found; false otherwise. The getParseMessages method can be used to retrieve a list of messages generated by the parse method. The first element of the array contains the status of the chemical system. "Okay" indicates the chemical system is valid. "Failed" indicates a problem that must be corrected by the user. If redundant chemical equations are found, a message to this effect is returned, the redundant equation is marked as such, and parse returns true.


getInfo

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


clearMessages

public void clearMessages()
Clears the message list


getChargeBalance

public java.lang.String getChargeBalance(Phase _soln)
Returns a string representing the charge balance relation for the phase. Returns null if the phase is not a solution.


getMassBalance

public java.lang.String[] getMassBalance()
Returns an array of strings representing the mass balance relations for the chemical system. Returns null if the mass balance equations cannot be constructed.


getMessages

public java.lang.String[] getMessages()
Returns the last set of messages generated by the parse method.


getMinValue

public double getMinValue()
Returns the minimum positive value for the moles of any species. If the equilibrium solution of a problem requires an amount closer to or smaller than this value, the solve method will not be able to find a solution.


getNbrMassBalance

public int getNbrMassBalance()
Returns the number of mass balance equations for the system


getTolerance

public double getTolerance()
Returns the tolerance for convergence of variables

See Also:
getTolerance()

printMessages

public void printMessages()
Prints parse messages on the Java console.


setChemicalSystem

public void setChemicalSystem(ChemSystem _chemSystem)
Sets the chemical system


setDisplayIterations

public void setDisplayIterations(boolean _displayIterations)
If true, the results of each iteration in the solve() method are displayed.


setDisplayLinearSystem

public void setDisplayLinearSystem(boolean _displayLinearSystem)
If true, the linear system of equations are displayed at each iteration of the solve method. The numbers to the left of the equal sign make up the Jacobian matrix for the system. The numbers to the right of the equal sign are negative of the function values, which should approach zero as the solution is approached.

The condition number for the Jacobian is also displayed for each iteration. The numbers in brackets indicate the index of the element with the smallest diagonal element and the value of that element.


setDisplayResults

public void setDisplayResults(boolean _displayResults)
If true, the final results of the solve method are displayed.


setDisplayTime

public void setDisplayTime(boolean _displayTime)
If true, the time in seconds required to solve an equilibrium problem via the solveProblem method is displayed on the Java console. The time is only displayed if the algorithm successfully converged.

See Also:
solveProblem()

setEquationTolerance

public void setEquationTolerance(double _eqnTol)
Sets the convergence tolerance for functions. This value is the "relative" uncertainty permit when determining if the original system of equations are satisfied.


setMaxCnt

public void setMaxCnt(int _maxCnt)
Sets the maximum number of iterations to be used in solving the nonlinear system of equations.


setMaxInc

public void setMaxInc(double _maxInc)
Sets the maximum amount a variable can change during a single iteration. The variable is the natural logarithm of the number of moles.


setRedundantTolerance

public void setRedundantTolerance(double _tol)
Sets the tolerance for aborting analysis when redundant chemical equations are encountered. The equilibrium constant for a redundant equation should reduce to unity when all of the stoichiometric coefficients are eliminated. Failure to do so indicates that while two or more chemical equations are redundant, their equilibrium constants are mutually inconsistent. The default value is 0.05.


setSVDThreshold

public void setSVDThreshold(double _svdThreshold)
Sets the threshold value for setting the diagonal elements from svd to zero. If the product of the svdThreshold and the matrix condition number exceeds unity, the smallest diagonal element is identified and set to zero. Rows for which the diagonal elements are zero are disregarded in solving the linear system.


setTolerance

public void setTolerance(double _tol)
Sets the relative tolerance for convergence of the amounts of each species


setUsePrevious

public void setUsePrevious(boolean _usePrevious)
Sets the usePrevious property. If usePrevious is true, the existing amounts of each species are used as seed values in the current calculation. If usePrevious is false, the amounts of each species are set to their analytical values. In either case, values of zero are replaced with a nonzero starting value.


solveProblem

public boolean solveProblem()
Solves the equilibrium problem. The chemical system is parsed to catch any problems. If no problems are found, the mathematical equations are constructed and the problem is then solved. Upon completion, the moles, concentrations, pressures, etc. of each species are updated.


createEquations

protected boolean createEquations()
Constructs the mass balance, charge-balance, and equilibrium equations for this chemical system. Should be called after the chemical systems is parsed to catch any problems.


solve

protected boolean solve()
Solves the mathematical problem and automatically updates number of moles for all species. Returns true if method converged without problems, false otherwise.