Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://www.geol.msu.ru/deps/geochems/soft/en/GibbsLib.doc
Äàòà èçìåíåíèÿ: Mon Dec 28 17:50:08 2015
Äàòà èíäåêñèðîâàíèÿ: Sun Apr 10 01:26:36 2016
Êîäèðîâêà:

Using GibbsLib.dll in user's applications



Contents

Introduction 2
Creating and deleting the object Gibbs 2
Gibbs object properties 3
Common Gibbs properties 3
Special Gibbs properties 4
Gibbs object methods 6
Common Gibbs methods 6
CallGibbs 6
ReCallGibbs 7
SetFugacities 8
CancelGibbs 9
ShutDown 9
Special Gibbs methods 9
SetFreeEnergy 10
ClearEnergies 10
SetBinParm 11
ClearBinParms 12
Warning on using special methods 12
Gibbs options 13


Introduction

GibbsLib.dll is an ActiveX component that allows user to create an object
Gibbs and call its properties and methods from the applications supporting
the OLE (Object Linking and Embedding) system. For example, you can call
Gibbs methods and properties from the MS Office applications or MatLab.

The object Gibbs is intended for calculation of chemical equilibria in
isobaric-isothermic systems. The present document describes how you can use
this object. We assume that, on top of the installed component
GibbsLib.dll, you have the Unitherm database of thermodynamic properties
and a tool for preparation of files defining chemical systems - either the
HCh package, or the program UT2K.

The examples of creating of the Gibbs object and calling its properties and
methods are provided in MS VBA (Visual Basic for Applications). Users of
other languages and programming tools have to find equivalents of these
examples in their programming environments by themselves.


Creating and deleting the object Gibbs

Note: Prior to starting your coding, make sure that the component
GibbsLib.dll is registered in your system, and the reference to
GibbsLib.dll is active (see menu References of your compiler).

The object Gibbs is created with the keyword New.

Example 1: Automatic creation (not recommended):
Dim GB As New Gibbs
Example 2: Explicit creation using an assignment operator:
Dim GB As Gibbs
.
Set GB = New Gibbs
The second method is preferable as it allows you to explicitly create the
object when it is needed and provides a fuller control over the object
instances.

When you do not need the object any more, it must be deleted. We also
recommend you to do it explicitly to avoid wasting the computer memory.
Before killing the object, you must prepare it for this operation by
calling the special ShutDown method.

Example 3: Deleting the Gibbs object:
GB.ShutDown
Set GB = Nothing
Gibbs object properties

The properties of an object are data that can be passed to the object or
received from it without requesting the object to complete any essential
job. Normally, when passing the data to the object, we set the mode of its
subsequent action, or pass the data that will be required subsequently. We
request object properties to receive results of its job or to get the
information about its current state.

Common Gibbs properties




|Property |Attribute |Data |Comments and examples |
| | |type | |
|LibVersion |read-only |Integer|GibbsLib.dll version number: Print Hex$(GB.LibVersion) 'point is |
| | | |assumed |
|UnithermLocation|read/write*|String |a) set property: GB.UnithermLocation = "C:\HCh_Win\Unitherm" |
| | | |b) get property: Print GB.UnithermLocation |
|GibbsOptions |read/write*|String |a) set property: GB.GibbsOptions = "/s/em/t=10" |
| | | |b) get property: Print GB.GibbsOptions |
|SystemFile |read/write*|String |a) set property: GB.SystemFile = "C:\Tests\System1.st" |
| | | |b) get property: Print GB.SystemFile |
|GibbsExitWords |read-only**|String |Gibbs' report on the results of the last call: |
| | | |If GB.GibbsExitWords <> "OK" Then Error 1 |
|GibbsResult_n(i)|read-only**|Double |Number of moles of i-th species at equilibrium: |
| |* | |For i = 1 To n: mole(i) = GB.GibbsResult_n(i): Next i |
|GibbsResult_g(i)|read-only**|Double |Chemical potential, activity or activity coefficient (depending on |
| |* | |/mode option) of i-th species: |
| | | |For i = 1 To n: chem(i) = GB.GibbsResult_g(i): Next i |
* The properties UnithermLocation and SystemFile must be set prior to
starting equilibrium calculations (which are performed by executing the
CallGibbs or ReCallGibbs methods, see below). Setting GibbsOptions property
is optional. If used, this property must be set before SystemFile, as some
options affect the way System files are read (see "Gibbs options" below).

** Not each Gibbs call generates the GibbsExitWords string. This property
is intended mainly for error reports. If there is an error calling a Gibbs'
method or setting its property, its brief description can be found in the
GibbsExitWords string.
If calling a Gibbs' method or setting its property is successful, the
GibbsExitWords property is set only in two cases:
1) String "OK" - on successful completion of the job by either of the
Gibbs calculation methods (CallGibbs or ReCallGibbs)
2) String "System file accepted" - on successful setting of the
SystemFile property

*** GibbsResult_n and GibbsResult_g allow you to retrieve results of
equilibrium calculations one by one. Use these properties if your
programming system does not support return of arrays (these properties are
not needed for fully OLE-compatible systems). Values returned by these
properties are correct only if GibbsExitWords = "OK" after calculations (or
functions CallGibbs or ReCallGibbs have returned the value of 0).


Special Gibbs properties

You can use these properties in conjunction with the Special Gibbs methods
intended for inverse modelling (see SetFreeEnergy, ClearEnergies,
SetBinParm, ClearBinParms). These properties are useful for control
purposes when debugging your application.

|Property |Attribute |Data |Comments and examples |
| | |type | |
|FreeEnergy(i) |Read-only |Single |User-substituted value of the apparent free energy of the i-th |
| | | |species, or the 1E+35 flag value if there was no substitution. |
|BinParm |Read-only |String |User-substituted value of a binary cross-interaction parameter, or |
|(s,i,j,k) | |Integer|the 1E+35 flag value if there was no substitution. Another numerical|
| | | |flag, |
| | |Integer|-1E+35, identifies an error during the function call. |
| | | |The property parameters have the following meaning: |
| | |Integer|s - The exact name of the solution from the appropriate *.st file |
| | | |i,j - Relative sequential numbers (indexes) of the solution species |
| | | |associated with the binary interaction parameter (i | | | |k - The sequential number of the substituted parameter of the |
| | | |solution model as in the *.st file: |
| | | |For the PRSV model: 1 - k(i-j); 2 - k(j-i) |
| | | |For the NRTL model: 1 - tau(i-j); 2 - tau(j-i); 3 - alpha |
| | | |For the Subregular model: 1 - W(i-j); 2 - W(j-i) |
| | | |For the Redlich-Kister model: 1 - A0(i-j); 2 - A1(i-j); 3 - A2(i-j);|
| | | | |
| | | |4 - T(A0); 5 - T(A1); 6 - T(A2); 7 - P(A0); 8 - P(A1); 9 - P(A2) |
Gibbs object methods




Common Gibbs methods



CallGibbs

The main (basic) method of the object Gibbs is the method CallGibbs that
calculates the equilibrium composition of the specified chemical system.
Prior to calling this method you must specify the location of the Unitherm
database, the Gibbs calculation options, and the definition file of the
chemical system (*.st). These are set using Gibbs properties as described
above.

To calculate an equilibrium composition of your system, you have to call
the function CallGibbs as follows:

.CallGibbs(t, p, fug(), tot(), specs(), lna())

The parameters of this function have the following meanings and formats.

|Paramete|Data type |Called|Meaning |
|r | | | |
|T |Single |ByVal |Temperature in œC |
|P |Single |ByVal |Pressure in bars (0 = Psat) |
|fug() |Double |ByRef |Fugacities of the perfectly mobile |
| |(array) | |components (p.m.c.) in bars |
|tot() |Double |ByRef |The bulk chemical composition of the |
| |(array) | |system in terms of elements in moles |
|specs() |Double |ByRef |Quantities of components (species) in |
| |(array) | |moles |
|lna() |Double |ByRef |Depends on the value of the option |
| |(array) | |/mode (see further) |

Notes:
All the arrays are one-dimensional; the lower index of all the arrays is
equal to zero.

|fug() |Input parameter. The fugacities of the p.m.c. must be written |
| |sequentially starting from the index 1 in the order specified |
| |by the System (*.st) file. This parameter is required even if |
| |the system is closed. |
|tot() |Input parameter. The bulk quantities of all the chemical |
| |elements of your system are represented sequentially starting |
| |from the index 1. The required order is specified by the |
| |System (*.st) file. We recommend you not to include water in |
| |the bulk element composition of your system. Instead, you can |
| |specify the quantity of water in the element tot(0); otherwise|
| |make sure that tot(0)=0. |
|specs(|Output parameter. Quantities of components (species) in moles |
|) |are represented sequentially starting from the index 1 |
| |according to the order specified by the System (*.st) file |
| |(not counting p.m.c.). Note: the elements of this array can |
| |also be used by Gibbs as input values for calculations (see |
| |also /si option). |
|lna() |Output parameter. Depending on the value specified by the |
| |Gibbs option /mode={0|1|2|3}, this array will contain values |
| |of different thermodynamic parameters of system components |
| |(species) at equilibrium: |
| |0 - reduced (dimensionless) chemical potentials, µ/RT (the |
| |default value of the option /mode) |
| |1 - natural logarithms of activities of species (rational |
| |scale) |
| |2 - natural logarithms of activity coefficients of species |
| |(rational scale) |
| |3 - partial molal volumes of species (J/bar) |
| |The components (species) will be represented in the same order|
| |as in the array specs(). |

The method CallGibbs returns the zero value of the type Integer for the
successful completion of the computations, and a non-zero value in case of
an error. In the first case, the value of the property GibbsExitWords will
be the string "OK", in the second case - a string with a brief description
of the error.


ReCallGibbs

The method CallGibbs is convenient (and necessary) when you do not know
anything about the equilibrium composition of the system. In other words,
when you have only a set of equilibrium factors - the bulk composition of
the system and the fugacities of the perfectly mobile components.

However, in practice of geochemical modelling, you often face problems that
require a number of sequential calculations when compositions of the system
consistently change (often, non-substantially), and chemical potentials of
the p.m.c. remain constant (e.g., a titration process). In this type of
problems you can still use the method CallGibbs, though it is not very
convenient. This inconvenience stems from the necessity to calculate the
bulk composition of the system for each subsequent step of the modeling
based on the results of the preceding step. The object Gibbs allows you to
significantly simplify programming of the repetitive calculations by
providing an alternative method ReCallGibbs ("Repeated Call") that does not
require calculation of the bulk composition of the system:

.ReCallGibbs(t, p, specs())

The parameters of this function have the following meanings and formats.

|Paramete|Data type |Called|Meaning |
|r | | | |
|T |Single |ByVal |Temperature in œC |
|P |Single |ByVal |Pressure in bars (0 = Psat) |
|specs() |Double |ByRef |Quantities of components (species) in |
| |(array) | |moles |

Notes:
The parameters of this function have the same format and meaning as the
similar parameters of the function CallGibbs. The difference is that the
object Gibbs calculates the bulk composition of the system itself from the
input values of the elements of the array specs(). The results of the
calculations will be returned by Gibbs in the same array. As thermodynamic
properties of species at equilibrium are normally not required for each
calculation, the output array lna() is excluded from the parameters of this
function. If necessary, these data can be obtained from the object using
its property GibbsResult_g.

Another excluded parameter is the array fug() that specifies fugacities of
the p.m.c. (thus, another meaning of ReCallGibbs is a "Reduced Call"). If
the chemical system is closed in respect with p.m.c. this is even
convenient. If the system is open in respect with p.m.c., the object Gibbs
will use the values of p.m.c. kept from the last execution of methods
CallGibbs or SetFugacities (see below).

The function ReCallGibbs returns the zero value of the type Integer for the
successful completion of the computations, and a non-zero value in case of
an error. In the first case, the value of the property GibbsExitWords will
be the string "OK", in the second case - a string with a brief description
of the error.


SetFugacities

If modelling your problems using the ReCallGibbs method you have to change
the values of p.m.c. (for open systems) between calls to Gibbs, you can use
a special method SetFugacities:

.SetFugacities(fug())

The only parameter of this fuction is the array fug(). It has the same
format and meaning as the similar parameter of the function CallGibbs.

The function SetFugacities returns the zero value of the type Integer if
the operation is successful and a non-zero value in case of an error.


CancelGibbs

The methods described in this chapter are intended exclusively for
calculations initiated by a user's application and do not have any user
interface. The absence of the user interface creates one specific problem:
after the control has been passed to the object, you cannot stop the
launched execution of the method if required. This problem is solved with a
special method CancelGibbs that makes one of keyboard key combinations
"a cancel button" for methods CallGibbs and ReCallGibbs:

.CancelGibbs Key, Shift

This method has the following parameters:

|Paramete|Data |Called|Meaning |
|r |type | | |
|Key |Integer |ByVal |Virtual key code (e.g. 27=Esc key, 13=Enter|
| | | |key, etc) |
|Shift |Integer |ByVal |0=No shift keys, 1=Shift key, 2=Ctrl key, |
| | | |4=Alt key |

Note: The method CancelGibbs must be executed for an already existing
object before you start calculations using the CallGibbs or ReCallGibbs
methods. The specified keyboard key combination will be active till you
kill the object or redefine this combination using the same (CancelGibbs)
method.
To cancel the "hot key", execute the same method with the parameter Key =
0.
The method CancelGibbs does not return any values and does not affect the
GibbsExitWords property.


ShutDown

The last of the methods of the object Gibbs - ShutDown - was already
discussed in the Section "Creating and deleting.". This method does not
have any parameters:

.ShutDown

Always use this method before killing the object Gibbs to avoid wasting the
computer memory.


Special Gibbs methods

The following 4 methods can be used for specific purposes of inverse
modelling. For example, you can fit free energies of formation of species
(SetFreeEnergy, ClearEnergies), or binary interaction parameters of non-
ideal solutions (SetBinParm, ClearBinParms) to experimental data.


SetFreeEnergy

Modelling your problems using the CallGibbs and ReCallGibbs methods, you
might want to replace the internally calculated default values of the
apparent free energies of species (i.e., consistent with Unitherm) with
your own optional values. To this end, you can use a special method
SetFreeEnergy:

.SetFreeEnergy index, value

The parameters of this function have the following meanings and formats.

|Paramete|Data type |Called|Meaning |
|r | | | |
|Index |Integer |ByVal |Absolute index of species in the System|
| | | |file. Note: You can look up the indexes|
| | | |using the Main program of the HCh |
| | | |package; just press "A" when viewing |
| | | |your System file. |
|Value |Single |ByVal |Energy of the species in kJ/mol |

The function will not work if you have not already set the System (*.st)
file. If the System file has been changed after you invoked this function,
all the substituted values will be erased.
To substitute free energies for a number of species, you can call this
function the appropriate number of times in a loop.
Note: All the substituted energies will be used "as is" for any
temperatures and pressures specified for the CallGibbs and RecallGibbs
functions. Please pay attention to structure your program to ensure the
consistency of your optional energy values and appropriate temperatures and
pressures.
Note: Please keep in mind that this method uses absolute indexes of
species. Thus, it is your responsibility to substitute energies of a
component in all instances of duplicated solutions (if any).
Note: To revert to the default mode of calculation of the apparent free
energies of a specified species, you can use the same function with the
value set to the 1E+35 flag.


ClearEnergies

This function clears all the apparent free energies of species set by the
user and reverts the program to their internal default calculation. This
method does not have any parameters:

.ClearEnergies


SetBinParm

This method allows you to specify any parameter of binary interaction for
non-ideal solution models for gaseous (PRSV) and liquid (NRTL) mixtures and
solid or liquid (Subregular and Redlich-Kister) solutions.
.SetBinParm s, i, j, k, value

|Paramete|Data type |Called|Meaning |
|r | | | |
|s |String |ByVal |The exact name of the solution from the|
| | | |appropriate *.st file |
|i, j |Integer |ByVal |Relative sequential numbers (indexes) |
| | | |of the solution species associated with|
| | | |the binary interaction parameter |
|k |Integer |ByVal |The sequential number of the |
| | | |substituted parameter |
| | | |of the solution model as in the *.st |
| | | |file. |
| | | |For the PRSV model: |
| | | |1 - k(i-j) |
| | | |2 - k(j-i) |
| | | |For the NRTL model: |
| | | |1 - tau(i-j) |
| | | |2 - tau(j-i) |
| | | |3 - alpha |
| | | |For the Subregular model: |
| | | |1 - W(i-j) |
| | | |2 - W(j-i) |
| | | |For the Redlich-Kister model: |
| | | |1 - A0(i-j) |
| | | |2 - A1(i-j) |
| | | |3 - A2(i-j) |
| | | |4 - T term for A0(i-j) |
| | | |5 - T term for A1(i-j) |
| | | |6 - T term for A2(i-j) |
| | | |7 - P term for A0(i-j) |
| | | |8 - P term for A1(i-j) |
| | | |9 - P term for A2(i-j) |
|value |Single |ByVal |The custom value of the the binary |
| | | |interaction parameter |


To substitute a number of parameters for a number of species, you can call
this function the approproiate number of times in a loop.

Note: As this method uses relative species numbers and solution names, you
do not need to repeate your setting for all instances of duplicated
solutions.
Note: To remove a previously set binary interaction parameter, you can use
the same function with the value set to the 1E+35 flag.


ClearBinParms

This function clears all the binary interaction parameters set by the user
and reverts the program to using their default values specified in the
chemical system (*.st) file. This method does not have any parameters:

.ClearBinParms


Warning on using special methods

None of the above four functions (SetFreeEnergy, ClearEnergies, SetBinParm,
and ClearBinParms) set any return codes or generate any messages. We
recommend you to use the FreeEnergy and BinParm properties to check whether
your values are passed to Gibbs correctly.

Nevertheless, you must pay special attention to the setting of your problem
when programming your substitution routines. For example, if the solution
for which you want to set the custom interaction parameters is specified in
the system (*.st) file as ideal, there is no provision for the binary
interaction parameters at all. Nevertheless, the BinParm property will
return the correct values - they will be simply ignored durung
calculations. Similarly, if you incorrectly specify the name of the
solution, the parameters passed to Gibbs will be also ignored during
calculations.


Gibbs options

The property GibbsOptions allows you to set different modes for calculating
chemical equilibria. The list of the possible options and the appropriate
modes are defined below. A few options can be combined together in the same
string variable.

|Option |Description |
|/s |Sets the mode "compute sequentially". When you set this|
| |option, the program uses the equilibrium composition |
| |obtained at the previous step as an initial |
| |approximation for the next step. This makes |
| |computations faster if the differences between total |
| |system compositions are small. Without this option all |
| |the compositions are processed independently. Do not |
| |set this option if the compositional differences |
| |between computation steps are significant |
|/g |Sets the mode of substitution of the internally |
| |calculated free energies and/or activity coefficients |
| |of specified components by the values specified in an |
| |*.stg file. If the *.stg file is not found in the same |
| |directory as the corresponding *.st file, the /g option|
| |will be ignored without any warning messages |
|/em |Specifies that the program must use external modules |
| |for calculation of activity coefficients for some of |
| |the solutions of your chemical system |
|/v |Calculate system volume. If this option is set, the |
| |program returns the volume of the system (in J/bar) in |
| |spec(0) |
|/si |Sets the mode for calculation of saturation indecies of|
| |individual phases. Logarithms of saturation indecies |
| |are returned in spec() only for undersaturated phases, |
| |thus these values are always negative |
|/t= |Sets an allowed time limit (in seconds) for calculation|
| |of an equilibrium composition. The permitted range of |
| |values is 0.1 to 3600. The option /t=0 (or any t value|
| |outside of the permitted range) switches the timer off.|
| |Note: the program uses the system clock to track the |
| |elapsed time, so be careful when running your |
| |application in a background (non-priority) mode |
|/mode={0|1|2|3|Specifies the type of the data returned by the method |
|} |CallGibbs in the lna() array and by the property |
| |GibbsResult_g. Setting the following numbers will |
| |return the values for the following properties of the |
| |system components (species): |
| |0 - reduced (dimensionless) chemical potentials, µ/RT |
| |1 - natural logarithms of activities of species |
| |(rational scale) |
| |2 - natural logarithms of activity coefficients |
| |(rational scale) |
| |3 - partial molal volumes of species (J/bar) |
|/ie |Allows to ignore T-P-( limits on calculation of the |
| |properties of aqueous species imposed by the HKF model |
|Gibbs options continued |
|Option |Description |
|/wp |Forces usage of the Wagner-Pruss model for the pure |
| |water properties instead of the Haar-Gallagher-Kell |
| |(default) model |
|/bl |Forces usage of the Bandera-Lvov model for the water |
| |dissociation constant instead of the Marshall-Franck |
| |(default) model |
|/ew |Forces usage of the Fernandez et al. model for the |
| |dielectric constant of water instead of the |
| |Johnson-Norton (default) model |
|/b= |Sets the common SetchÈnow coefficient for all the |
| |neutral species equal to . Incompatible with the|
| |option /b=#{0|1|2|3} |
|/b=#{0|1|2|3} |Specifies the algorithm for reading and/or calculation |
| |of SetchÈnow coefficients of neutral aqueous species. |
| |See Appendix 3 of the initial (DOS) documentation for |
| |details. Setting /b=#0 specifies b-SetchÈnow = b-dot. |
| |Incompatible with the option /b= |
| |You can still specify this option in the old format |
| |/b=@{0|1|2|3} |
|/c= |Set the extended parameter of the Debye-HÝckel equation|
| |equal to . Incompatible with the option |
| |/c=#{1|2|3|4} |
|/c=#{1|2|3|4} |Sets the extended term parameter of the Debye-HÝckel |
| |equation equal to b-gamma value for the specified |
| |background electrolyte (Oelkers and Helgeson, 1990) |
| |(1=NaCl, 2=NaOH, 3=KOH, 4=KCl) and to replace all the |
| |default ion size parameters (Å) with the ion size |
| |parameters calculated for the given electrolyte (Shock |
| |et al., 1992). See Appendix 3 of the initial (DOS) |
| |documentation for details. |
| |You can still specify this option in the old format |
| |/c=@{|1|2|3|4} |
|"Experimental" options that are not recommended for general use |
|/w |Requires calculation of the activity coefficient of |
| |water according to the revised HKF model (Helgeson et |
| |al., 1981). This option is ignored without the |
| |/ñ=#{1|2|3|4} option |
|/steam |Requires usage of the properties of overcooled steam |
| |instead of the properties of liquid water |
|/{3|4|5|6|7|8||Specifies the number of digits of the required accuracy|
|9} |of calculations (the value is used by the program as a |
| |control condition to terminate iterations). The default|
| |value is 6. |
| |Use this option only if the default setting causes |
| |calculation problems |
|/la |Sets the Low Accuracy mode. |
| |Use this option only for experimentation when you have |
| |convergence (calculation time) problems |