edu.davidson.chm.equilibria
Class ChemSystem

java.lang.Object
  |
  +--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.
protected java.lang.String	getChar(java.lang.String _str, int pos) Returns a string containing character at position pos
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
protected boolean	parse(java.lang.String _rxn) Parses a string describing a reaction.
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

clone, equals, finalize, 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

parse

protected boolean parse(java.lang.String _rxn)

Parses a string describing a reaction. Returns true if no errors were encountered

getChar

protected java.lang.String getChar(java.lang.String _str,
                                   int pos)

Returns a string containing character at position pos