edu.davidson.chm.equilibria
Class ChemSystem

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

public class ChemSystem
extends java.lang.Object

Chemical Equilibria Problem Solver

This project contains the files necessary to solve arbitrary equilibrium problems

Copyright: Copyright (c) David N. Blauch

Company: Davidson College

Version:
2.1
Author:
David N. Blauch

Constructor Summary
ChemSystem()
          Creates a chemical system using the default parameters
ChemSystem(java.lang.String _label)
          Creates a chemical system using user-defined parameters
ChemSystem(java.lang.String _label, double _temp, double _pressure)
          Creates a chemical system using user-defined parameters
 
Method Summary
 void addHalfReaction(HalfReaction _halfReaction)
          Adds a half-reaction to the chemical system
 HalfReaction addHalfReaction(java.lang.String _rxn, java.lang.String _label, double _Eo)
          Creates a new half-reaction and adds the half-reaction to the chemical system The reaction is described by a string in the conventional chemical notation.
 void addPhase(Phase _phase)
          Adds a existing phase to the chemical system
 void addReaction(Reaction _reaction)
          Adds an existing reaction to the chemical system
 Reaction addReaction(java.lang.String _rxn, java.lang.String _label, double _K)
          Creates a new reaction and adds the reaction to the chemical system The reaction is described by a string in the conventional chemical notation.
 ChemSystem copyOf(java.lang.String _label)
          Returns a new ChemSystem with the indicated label.
 Species[] createAcidBaseSpecies(Phase _phase, ChemSpecies[] _chemSpecies, double[] _moles, double[] _Ka, java.lang.String _reactionLabel)
          Creates a series of acid-base species and adds the acid-base species to _phase and the acid-base reactions to the chemical system.
 AqueousSolution createAqueousPhase(java.lang.String _label, double _volume)
          Creates and adds an aqueous solution to the chemical system.
 Species[] createComplexationSpecies(Phase _phase, ChemSpecies[] _chemSpecies, double[] _moles, double[] _Kf, java.lang.String _reactionLabel)
          Creates a series of complex species and adds the complex species to _phase and the complexation reactions to the chemical system.
 Gas createGasPhase(java.lang.String _label)
          Creates and adds a gas to the chemical system.
 Gas createGasPhase(java.lang.String _label, ChemSpecies _chemSpecies, double _moles)
          Creates and adds a gas to the chemical system.
 Liquid createLiquidPhase(ChemSpecies _chemSpecies, double _mass)
          Creates and adds a liquid to the chemical system.
 Liquid createLiquidPhase(java.lang.String _label, ChemSpecies _chemSpecies, double _mass)
          Creates and adds a liquid to the chemical system.
 Solid createSolidPhase(ChemSpecies _chemSpecies, double _moles)
          Creates and adds a solid to the chemical system.
 Solid createSolidPhase(java.lang.String _label, ChemSpecies _chemSpecies, double _moles)
          Creates and adds a solid to the chemical system.
 Solution createSolutionPhase(java.lang.String _label, ChemSpecies _solventChemSpecies, ChemSpecies _acidChemSpecies, ChemSpecies _baseChemSpecies, double _Kauto, double _volume)
          Creates and adds a solution to the chemical system.
 Solution createSolutionPhase(java.lang.String _label, ChemSpecies _chemSpecies, double _volume)
          Creates and adds a solution to the chemical system.
 Solution createSolutionPhase(java.lang.String _label, ChemSpecies _chemSpecies, double _Kauto, double _volume)
          Creates and adds a solution to the chemical system.
 ChemSpecies getAnionCounterion()
          Returns the generic X- ChemSpecies, which is used to arbitrarily balance charge.
 ChemSpecies getCationCounterion()
          Returns the generic X+ ChemSpecies, which is used to arbitrarily balance charge.
 HalfReaction getHalfReaction(java.lang.String _label)
          Returns the half-reaction with the indicated label
 HalfReaction[] getHalfReactions()
          Returns an array of the half-reactions in the system
 Hydrogen_Ion getHydrogen_Ion()
          Returns the Hydrogen_Ion ChemSpecies.
 Hydroxide_Ion getHydroxide_Ion()
          Returns the Hydroxide_Ion ChemSpecies.
 java.lang.String getInfo()
          Returns information about this class
 boolean getIsIdeal()
          Returns the isIdeal property.
 boolean getIsIsobaric()
          Returns true if the system is isobaric.
 java.lang.String getLabel()
          Returns the chemical system label
 int getNbrPhases()
          Returns the number of Phases in the Chemical System
 int getNbrReactions()
          Returns the number of Reactions in the Chemical System
 Phase getPhase(int _index)
          Returns the phase at the requested index
 Phase getPhase(java.lang.String _label)
          Returns the phase with the given label
 Phase[] getPhases()
          Returns an array of phases in the system
 double getPotential(Phase _phase)
          Returns the half-cell potential in volts for the indicated electrode at the system temperature.
 double getPotential(Phase _phase1, Phase _phase2)
          Returns the cell potential (potential of electrode1 minus that of electrode2) in volts at the system temperature.
 double getPotential(java.lang.String _phase)
          Returns the half-cell potential in volts for the indicated electrode at the system temperature.
 double getPotential(java.lang.String _phase1, java.lang.String _phase2)
          Returns the cell potential (potential of electrode1 minus that of electrode2) in volts at the system temperature.
 double getPressure()
          Returns the system pressure in atmospheres
 Reaction getReaction(int _index)
          Returns the reaction at the requested index
 Reaction getReaction(java.lang.String _label)
          Returns the reaction with the indicated label
 Reaction[] getReactions()
          Returns an array of the reactions in the system
 Species[] getSpecies()
          Returns an array of species in the system
 Species getSpecies(java.lang.String _label)
          Returns the species in the system with the given label.
 Species getSpecies(java.lang.String _label, java.lang.String _phaseLabel)
          Returns the species in the system and in the indicated phase with the given label.
 double getTemperature()
          Returns the system temperature in Kelvin
 Water getWater()
          Returns the Water chemical species for this chemical system
 boolean removeHalfReaction(HalfReaction _halfReaction)
          Removes the half-reaction from the chemical system.
 boolean removeHalfReaction(java.lang.String _label)
          Removes the half-reaction from the chemical system.
 boolean removePhase(Phase _phase)
          Removes the phase from the chemical system.
 boolean removePhase(java.lang.String _label)
          Removes the phase with the given label from the chemical system
 boolean removeReaction(Reaction _reaction)
          Removes the reaction from the chemical system.
 boolean removeReaction(java.lang.String _label)
          Removes the reaction with the given label from the chemical system
 void setIsIdeal(boolean _isIdeal)
          Sets the isIdeal property.
 void setIsIsobaric(boolean _isIsobaric)
          Sets the isIsobaric property.
 void setLabel(java.lang.String _label)
          Sets the label
 void setPressure(double _pressure)
          Sets the system pressure.
 void setReferenceTemperature(double _temperature)
          Sets the reference temperature for all reactions and half-reactions in the chemical system
 void setTemperature(double _temp)
          Sets the system temperature
 void transferSolution(Phase _solution1, Phase _solution2, double _volume)
          Transfers a volume of _solution1 to _solution2.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ChemSystem

public ChemSystem()
Creates a chemical system using the default parameters


ChemSystem

public ChemSystem(java.lang.String _label)
Creates a chemical system using user-defined parameters

Parameters:
_label - identification string

ChemSystem

public ChemSystem(java.lang.String _label,
                  double _temp,
                  double _pressure)
Creates a chemical system using user-defined parameters

Parameters:
_label - identification string
_temp - temperature in Kelvin
_pressure - pressure in atmospheres
Method Detail

addPhase

public void addPhase(Phase _phase)
Adds a existing phase to the chemical system


addHalfReaction

public void addHalfReaction(HalfReaction _halfReaction)
Adds a half-reaction to the chemical system


addHalfReaction

public HalfReaction addHalfReaction(java.lang.String _rxn,
                                    java.lang.String _label,
                                    double _Eo)
Creates a new half-reaction and adds the half-reaction to the chemical system The reaction is described by a string in the conventional chemical notation. For example

O2 (g) + 4 H+ + 4 e- (Pt) = 2 H2O

The string must contain e-. The phase of "e-" is important only if you wish to measure the potential of the phase.

The + separating terms and the = must have a space on each side.

Phases must be enclosed in () with no enclosed spaces. If a phase is specified, the method will search for a phase with the label inside the parentheses.

If a phase is specified, the method will search for a species with the indicated label in the indicated phase. Otherwise the method searches all phases for a species with the indicated label.

To avoid potential confusion, labels should not begin with a number, space, + or =.

If the user-supplied equation is defective, one or more species or phases does not exist, or the equation is not balanced with respect to charge, the method returns null.

Parameters:
_Eo - standard potential in volts at 298.15 K for the half-reaction
_label - descriptive label for the reaction
Returns:
the newly created half-reaction

addReaction

public void addReaction(Reaction _reaction)
Adds an existing reaction to the chemical system


addReaction

public Reaction addReaction(java.lang.String _rxn,
                            java.lang.String _label,
                            double _K)
Creates a new reaction and adds the reaction to the chemical system The reaction is described by a string in the conventional chemical notation. For example

Fe2O3 + 3 CO = 2 Fe + 3 carbon_monoxide

The + separating terms and the = must have a space on each side.

Phases must be enclosed in () with no enclosed spaces. If a phase is specified, the method will search for a phase with the label inside the parentheses.

If a phase is specified, the method will search for a species with the indicated label in the indicated phase. Otherwise the method searches all phases for a species with the indicated label.

To avoid potential confusion, labels should not begin with a number, space, + or =.

If the user-supplied equation is defective, one or more species or phases does not exist, or the equation is not balanced with respect to charge, the method returns null.

Parameters:
_K - equilibrium constant for the reaction
_label - descriptive label for the reaction
Returns:
the newly created reaction

copyOf

public ChemSystem copyOf(java.lang.String _label)
Returns a new ChemSystem with the indicated label. The method automatically duplicates all Species, Phases, Reactions, and HalfReactions. The labels of all objects are identical, with the possible exception of the ChemSystem itself.


createAcidBaseSpecies

public Species[] createAcidBaseSpecies(Phase _phase,
                                       ChemSpecies[] _chemSpecies,
                                       double[] _moles,
                                       double[] _Ka,
                                       java.lang.String _reactionLabel)
Creates a series of acid-base species and adds the acid-base species to _phase and the acid-base reactions to the chemical system. Element 0 of _chemSpecies must contain the fully deprotonated base; element i contains the ChemSpecies with i protons. Element 0 of _Ka contains Ka1, element 1 contains Ka2, etc.

Parameters:
_moles - array containing amounts of each Species
_reactionLabel - base label, the step number is appended

createComplexationSpecies

public Species[] createComplexationSpecies(Phase _phase,
                                           ChemSpecies[] _chemSpecies,
                                           double[] _moles,
                                           double[] _Kf,
                                           java.lang.String _reactionLabel)
Creates a series of complex species and adds the complex species to _phase and the complexation reactions to the chemical system. Element 0 of _chemSpecies must contain the free ligand; element 1 of _chemSpecies must contain the free metal, and element i must contain the complex with i-1 ligands. Element 0 of _Kf contains Kf1, element 1 contains Kf2, etc.

Parameters:
_moles - array containing amounts of each Species
_reactionLabel - base label, the step number is appended

createAqueousPhase

public AqueousSolution createAqueousPhase(java.lang.String _label,
                                          double _volume)
Creates and adds an aqueous solution to the chemical system. The method returns the aqueous phase.

Parameters:
_label - description of the phase
_volume - volume in liters of the aqueous phase

createGasPhase

public Gas createGasPhase(java.lang.String _label)
Creates and adds a gas to the chemical system. The method returns the gas phase.

Parameters:
_label - label for the gas phase

createGasPhase

public Gas createGasPhase(java.lang.String _label,
                          ChemSpecies _chemSpecies,
                          double _moles)
Creates and adds a gas to the chemical system. The method returns the gas phase. At least one ChemSpecies in the gas must be specified.

Parameters:
_chemSpecies - ChemSpecies in the gas
_label - label for the gas phase
_moles - moles of the ChemSpecies in the gas

createLiquidPhase

public Liquid createLiquidPhase(ChemSpecies _chemSpecies,
                                double _mass)
Creates and adds a liquid to the chemical system. The method returns the liquid phase. The phase has the same label as the ChemSpecies that composes the liquid.

Parameters:
_chemSpecies - ChemSpecies the constitutes the liquid
_mass - mass in grams of the liquid

createLiquidPhase

public Liquid createLiquidPhase(java.lang.String _label,
                                ChemSpecies _chemSpecies,
                                double _mass)
Creates and adds a liquid to the chemical system. The method returns the liquid phase.

Parameters:
_label - descriptive label for the liquid
_chemSpecies - ChemSpecies the constitutes the liquid
_mass - mass in grams of the liquid

createSolidPhase

public Solid createSolidPhase(ChemSpecies _chemSpecies,
                              double _moles)
Creates and adds a solid to the chemical system. The method returns the solid phase. The phase has the same label as the ChemSpecies that composes the solid.

Parameters:
_chemSpecies - ChemSpecies the constitutes the solid
_moles - moles of the solid

createSolidPhase

public Solid createSolidPhase(java.lang.String _label,
                              ChemSpecies _chemSpecies,
                              double _moles)
Creates and adds a solid to the chemical system. The method returns the solid phase.

Parameters:
_label - descriptive label for the solid
_chemSpecies - ChemSpecies the constitutes the solid
_moles - moles of the solid

createSolutionPhase

public Solution createSolutionPhase(java.lang.String _label,
                                    ChemSpecies _chemSpecies,
                                    double _volume)
Creates and adds a solution to the chemical system. The method returns the solution phase. The solvent is assumed to be aprotic.

Parameters:
_chemSpecies - ChemSpecies for the solvent
_label - label for the solution
_volume - volume of the solution in liters

createSolutionPhase

public Solution createSolutionPhase(java.lang.String _label,
                                    ChemSpecies _chemSpecies,
                                    double _Kauto,
                                    double _volume)
Creates and adds a solution to the chemical system. The method returns the solution phase. The solvent is assumed to be protic.

Parameters:
_chemSpecies - ChemSpecies for the solvent
_label - label for the solution
_Kauto - autodissociation constant for the solution
_volume - volume of the solution in liters

createSolutionPhase

public Solution createSolutionPhase(java.lang.String _label,
                                    ChemSpecies _solventChemSpecies,
                                    ChemSpecies _acidChemSpecies,
                                    ChemSpecies _baseChemSpecies,
                                    double _Kauto,
                                    double _volume)
Creates and adds a solution to the chemical system. The method returns the solution phase. The solvent is assumed to be protic.

Parameters:
_solventChemSpecies - ChemSpecies for the solvent
_acidChemSpecies - ChemSpecies for the solvent conjugate acid
_baseChemSpecies - ChemSpecies for the solvent conjugate base
_label - label for the solution
_Kauto - autodissociation constant for the solution
_volume - volume of the solution in liters

getCationCounterion

public ChemSpecies getCationCounterion()
Returns the generic X+ ChemSpecies, which is used to arbitrarily balance charge.


getAnionCounterion

public ChemSpecies getAnionCounterion()
Returns the generic X- ChemSpecies, which is used to arbitrarily balance charge.


getHalfReaction

public HalfReaction getHalfReaction(java.lang.String _label)
Returns the half-reaction with the indicated label


getHalfReactions

public HalfReaction[] getHalfReactions()
Returns an array of the half-reactions in the system


getHydrogen_Ion

public Hydrogen_Ion getHydrogen_Ion()
Returns the Hydrogen_Ion ChemSpecies.


getHydroxide_Ion

public Hydroxide_Ion getHydroxide_Ion()
Returns the Hydroxide_Ion ChemSpecies.


getIsIdeal

public boolean getIsIdeal()
Returns the isIdeal property.


getInfo

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


getIsIsobaric

public boolean getIsIsobaric()
Returns true if the system is isobaric. Otherwise the system is isochoric.


getLabel

public java.lang.String getLabel()
Returns the chemical system label


getNbrPhases

public int getNbrPhases()
Returns the number of Phases in the Chemical System


getNbrReactions

public int getNbrReactions()
Returns the number of Reactions in the Chemical System


getPhase

public Phase getPhase(int _index)
Returns the phase at the requested index


getPhase

public Phase getPhase(java.lang.String _label)
Returns the phase with the given label


getPhases

public Phase[] getPhases()
Returns an array of phases in the system


getPotential

public double getPotential(Phase _phase)
Returns the half-cell potential in volts for the indicated electrode at the system temperature. The electrode is identified by its phase.

Parameters:
_phase - electrode phase

getPotential

public double getPotential(java.lang.String _phase)
Returns the half-cell potential in volts for the indicated electrode at the system temperature. The electrode is identified by its phase.

Parameters:
_phase - label for electrode phase

getPotential

public double getPotential(Phase _phase1,
                           Phase _phase2)
Returns the cell potential (potential of electrode1 minus that of electrode2) in volts at the system temperature. The electrode is identified by its phase.

Parameters:
_phase1 - electrode1 phase
_phase2 - electrode2 phase

getPotential

public double getPotential(java.lang.String _phase1,
                           java.lang.String _phase2)
Returns the cell potential (potential of electrode1 minus that of electrode2) in volts at the system temperature. The electrode is identified by the label of its phase.

Parameters:
_phase1 - label for electrode1 phase
_phase2 - label for electrode2 phase

getPressure

public double getPressure()
Returns the system pressure in atmospheres


getReaction

public Reaction getReaction(int _index)
Returns the reaction at the requested index


getReaction

public Reaction getReaction(java.lang.String _label)
Returns the reaction with the indicated label


getReactions

public Reaction[] getReactions()
Returns an array of the reactions in the system


getSpecies

public Species[] getSpecies()
Returns an array of species in the system


getSpecies

public Species getSpecies(java.lang.String _label)
Returns the species in the system with the given label. To avoid problems, make sure each species in the system has an unique label. Returns null if no species has the given label.


getSpecies

public Species getSpecies(java.lang.String _label,
                          java.lang.String _phaseLabel)
Returns the species in the system and in the indicated phase with the given label. Returns null if the indicated phase or species does not exist.


getTemperature

public double getTemperature()
Returns the system temperature in Kelvin


getWater

public Water getWater()
Returns the Water chemical species for this chemical system


removeHalfReaction

public boolean removeHalfReaction(HalfReaction _halfReaction)
Removes the half-reaction from the chemical system.

Returns:
true if half-reaction is found and removed, false otherwise

removeHalfReaction

public boolean removeHalfReaction(java.lang.String _label)
Removes the half-reaction from the chemical system.

Returns:
true if half-reaction is found and removed, false otherwise

removePhase

public boolean removePhase(Phase _phase)
Removes the phase from the chemical system.

Returns:
true if phase is found and removed, false otherwise

removePhase

public boolean removePhase(java.lang.String _label)
Removes the phase with the given label from the chemical system

Returns:
true if phase found and removed, false otherwise

removeReaction

public boolean removeReaction(Reaction _reaction)
Removes the reaction from the chemical system.

Returns:
true if reaction is found and removed, false otherwise

removeReaction

public boolean removeReaction(java.lang.String _label)
Removes the reaction with the given label from the chemical system

Returns:
true if reaction found and removed, false otherwise

setIsIdeal

public void setIsIdeal(boolean _isIdeal)
Sets the isIdeal property. If true, all activity coefficients are set to unity. If false, the Extended Debye-Huckel equation is used to calculate the activity coefficient for dissolved species; other species have an activity coefficient of unity.


setIsIsobaric

public void setIsIsobaric(boolean _isIsobaric)
Sets the isIsobaric property.


setLabel

public void setLabel(java.lang.String _label)
Sets the label


setPressure

public void setPressure(double _pressure)
Sets the system pressure. If the system is isobaric, the volumes of gas phases are changed when the pressure is changed.

Parameters:
_pressure - pressure in atmospheres

setReferenceTemperature

public void setReferenceTemperature(double _temperature)
Sets the reference temperature for all reactions and half-reactions in the chemical system


setTemperature

public void setTemperature(double _temp)
Sets the system temperature

Parameters:
_temp - temperature in Kelvin

transferSolution

public void transferSolution(Phase _solution1,
                             Phase _solution2,
                             double _volume)
Transfers a volume of _solution1 to _solution2. Both phases must be solutions. The species in the solution are transferred, with new species being created if necessary. The volume transferred must be less than the volume of _solution1. _solution1 and _solution2 must have the same solvent.

The method examines all Reactions that involve only _solution1 solutes (with the exception of the autodissociation reaction). If no corresponding Reaction exists in _solution2, a new Reaction is created.

Parameters:
_volume - volume in liters that is transferred