Документ взят из кэша поисковой машины. Адрес оригинального документа : http://www.geol.msu.ru/deps/geochems/soft/en/GibbsExt.doc Дата изменения: Tue Feb 11 19:24:54 2014 Дата индексирования: Thu Feb 27 23:37:45 2014 Кодировка:

External modules for the Gibbs program

The Gibbs program has several built-in non-ideality models which can be
used for the calculation of activity coefficients for real solutions: the
extended Debye-HЭckel model for aqueous solutions, the modified Peng-
Robinson model for gaseous (or liquid) solutions, the Non-Random-Two-Liquid
model for liquid solutions, the Mixing-on-Sites model for solid solutions,
Subregular and Redlich-Kister models for solid and liquid solutions.
These models can be used while minimizing the free energy of a system
without special efforts. If you wish to use different models of non-
ideality in your work, you can attach to Gibbs special programs that are
called "external modules". You can use existing external modules for Gibbs
or write your own.


How to attach external modules to Gibbs


All external modules for Gibbs (Windows version) are regular DLLs. All
of them have the same structure and interact with Gibbs in the same manner;
the only visible differences between them are their names and sizes.
First you need to put all required modules into the HCh home folder
(usually, C:\HCh_Win\Main). Note, that this action will not automatically
attach them to Gibbs. Adding these modules to Gibbs' runs is still
optional, and you need to do some additional operations to actually use
them.
If you decide to use your external modules for every project you are
working with, go to the folder where your project resides and create there
a text file named Modules.txt. This file will describe which modules should
be used for specified real solutions in your System files. All the lines in
Modules.txt file have the same simple structure: ":
". Here is the name of one of your external
modules without the .dll extension (case insensitive; this name should not
exceed 8 characters in length); is the name of a solution
written exactly as it appears in your System files (thus it is case
sensitive). For example, "Pitzer: Aqueous solution" (without quotes) is a
valid line. You can write any number of lines with the same module name,
but you should not assign two or more modules to the same solution. Note,
that presence of the file Modules.txt in your working folder still does not
attach your modules to Gibbs. This file only lists which solutions of your
project external modules can serve and which modules are used for this.
You actually attach external modules to Gibbs when you start it with
/em option. If you plan to run Gibbs in the dialog mode (with either Blank
or Input file as the source), use the menu of the Main program (Gibbs >
Gibbs options > Computing. > Attach external modules). If you run Gibbs
with a Control file as the source, this option must be present in this
Control file (you can set it during editing the Control file). If you call
Gibbs from your own application or a macro, the option /em must be present
in the string passed to the Gibbs object through its property GibbsOptions
before opening your System file.
You can make sure that an external module has been used for the
calculation of activity coefficients of a particular solution by looking at
the Gibbs' listing (*.lst file): if a module is used, its name is present
here immediately below the solution name.


How Gibbs interacts with external modules


You must define the runtime options before Gibbs opens the System file.
When the program Main invokes Gibbs, it ensures the correct sequencing. If
you run Gibbs from your own code, it is your responsibility to send to
Gibbs its options before you make it open the System file. This sequence is
important when the string with options contains "/em" - in this case Gibbs
must read the file Modules.txt before opening the System file. If the
option /em is not set (or you pass options to Gibbs after opening the
System file), Gibbs does not read that list and thus in subsequent
calculations uses only built-in models of non-ideality (if they are defined
in the System file).
If the option /em is set and you passed it to Gibbs properly (we will
always assume this is the case hereafter), then before opening the System
file Gibbs reads the file Modules.txt (from the same folder) and, while
reading the System file, checks that every solution in the system is
present in the list. If a solution is found there, Gibbs loads the
corresponding DLL (if it is not already loaded) into memory, calls that
module and passes to it the information about this solution (its number and
the full list of its components), enabling the modules to prepare their
computational environments. This type of call is named "Primary"; it is
performed only once for each solution.
Next, Gibbs calls the external modules each time it calculates the
standard free energies of species (e.g. when temperature and pressure are
set or changed), and passes energies for solution species to the
corresponding modules. This is done just in case the model of non-ideality
needs these data or wants to replace them by its own values. In the last
case (i.e. if energies have been altered by a module) Gibbs remembers the
returned values and uses them in future calculations instead of the
original ones.
During equilibrium calculations Gibbs calls external modules each time
it needs activity coefficients for a specific solution. At this point Gibbs
passes the current mole quantities of the species of the specified solution
to a module and expects to get back from that module the logarithms of
activity coefficients of these species. Both of these calls are of
"Secondary" type; they can be repeated as many times as required, and in
any order.
Before the process completes Gibbs calls the external modules to give
them opportunity to prepare themselves for unloading (e.g. to free memory
if it was allocated). This type of call is named "Final", and it is
performed once for each solution.
Any error occurring while calling external modules is critical - in the
case of an error Gibbs informs the user about it and terminates its work.
The table below contains error messages that Gibbs generates when it finds
a problem with external modules.


|Error message |Meaning |
|File Modules.txt |Option /em is set, but the file Modules.txt is absent|
|not found |from the working folder. Create the file Modules.txt |
|Module could|Gibbs could not load the specified DLL. Check the |
|not be loaded |module name in the Modules.txt file and its presence |
| |in the HCh home folder |
|Could not unload |An error occurred while attempt to unload the |
|module |specified module. A possible reason: the module may |
| |be used by another process |


Modules can also detect errors when they are being called. By design
external modules do not return error messages; instead, they return only an
integer number that assigned to an error. Gibbs assumes the following
rules: if no error detected, a module returns 0; if a module detects an
error, it returns a positive number (see the documentation to a particular
module for interpreting that number); if an error is detected by HCh
software, the returned number is negative. If a module returns an error
code (non-zero), Gibbs shows the error message with the name of the module
(DLL), the call type (Primary/Secondary/Final) and the value returned. The
table below shows possible negative error codes, generated by the HCh
software.

|Error |Type of |Meaning |
|code |call | |
|-5 |Primary |Incorrect or duplicated solution number (Gibbs |
| | |error) |
|-4 |Primary |DLL does not contain Final entry point |
|-3 |Primary |DLL does not contain Secondary entry point |
|-2 |Primary |DLL does not contain Primary entry point |
|-1 |Secondary |Incorrect solution number or DLL is not |
| | |initialized (Gibbs error) |
|-1 |Final |Incorrect solution number (Gibbs error) |


If you receive an error message marked "(Gibbs error)" above, please
let me know.

How to write external modules for Gibbs


If you want to create your own external module, write it in the
programming language C. The appendix contains an example of a simple
external module. This section provides some details, comments and rules you
have to follow while writing your external modules for Gibbs.
Any DLL you create should have three entry points: Primary, Secondary
and Final.
The Primary function is called only once for each solution. Here the
module can prepare its computational environment for the solution, e.g.
allocate memory (if required). Your module must check whether it can
service the solution provided, and return an error code if it cannot. If
your module agrees to service the solution, it should return "0".
The parameter 'NameForm' is the array of strings representing the names
of all the solution components (14 symbols each). It is possible that in
the future there will appear additional characters representing their
chemical formulas after the component names; thus you need to determine
ends of strings not by the number of characters, but by the character \0.
When analyzing component names, you should not expect them to appear in any
particular order; the order is determined by the Unitherm list of items (a
user of your module can have a different database).
The value of the 'mode' parameter in the entry can be an integer from 0
to 255; it sets the working mode of your module. Only you (and, possibly,
your user) know what it means. Gibbs takes this number from the file
Modules.txt if a string ": | " appears
there. The default value of 'mode' is 0. On exit from the Primary function
your module should set one of these values in the parameter 'mode': 0 -
besides activity coefficients the module calculates the exact volume of the
solution (in J/bar), 1 - it calculates an estimation of volume, 2 - it does
not calculate the volume.
The Secondary function can be called as many times as Gibbs requires.
There are two subtypes of this call: Gibbs can pass to your module either
the standard free energies of components, or their mole quantities. In the
first case the module can modify the energies if it wants Gibbs to use the
altered values instead of original ones. In the second case the module must
return natural logarithms of activity coefficients (rational scale). The
parameters are described below.
|Paramete|Type |Description |
|r | | |
|sn |short|The solution number. Make sure the Primary call was made |
| | |for this solution |
|tK |float|Temperature (Kelvins). Check whether the value is valid |
| | |for your model |
|pB |float|Pressure (bars). Check whether the value is valid for |
| | |your model |
|nn[ ] |short|Actual list of sequential numbers (1-based) of solution |
| | |components. Do not expect that all of the components from|
| |(arra|the System file to be present here (as it was on the |
| |y) |Primary call) - some of them can be omitted; however |
| | |their sequential numbers (nn[1], nn[2], .) always go in |
| | |ascending order. The actual number of the solution |
| | |components is shown in nn[0] |
|n[ ] |doubl|Reduced standard free energies (G/RT) or mole quantities |
| |e |(depending on the value of d parameter, see below) of |
| |(arra|components listed in nn[ ]; they are stored in n[1], |
| |y) |n[2], . The module can alter the reduced free energies |
| | |in this array (subtype 1) or calculate natural logarithms|
| | |of activity coefficients and store them into the same |
| | |array (subtype 2). If you calculate the volume of the |
| | |solution, save it into n[0] |
|d |float|On entry - switch of subtype: if d < 0, the array n[ ] |
| | |contains energies, otherwise - quantities. |
| | |On exit d should be set to 1.0 or greater. The value of |
| | |1.0 means that the solution is close to ideal; a greater |
| | |number means that activities of components can vary |
| | |faster than their mole fractions. For example, |
| | |if ln a ~ 4 ln x, a good value for d will be 4.0 |


The Final function is called only once for each solution. Reset your
module here.

Appendix. Example of an external module for Gibbs (Microsoft C/C++
compiler)


/*********************************************************************/
/* Electrum.dll */
/* This DLL calculates activity coefficients of Gold-Silver alloys */
/* according to the White J.L. et al. [1957] model */
/* */
/* Developed by Yuri Shvarov in March 2004 */
/*********************************************************************/

#include

extern short __stdcall Primary(short,short,char*,short*);
extern short __stdcall Secondary(short,float,float,short*,double*,float*);
extern short __stdcall Final(short);

/*--------------------------- Global data ---------------------------*/

static short sN=0; /* solution number (1..255) */
static short iGold, iSilv; /* sequential numbers (1-based) in the solution
*/

/*-------------------------- Primary call ---------------------------*/

short __stdcall Primary(short sn, short nc, char* NameForm, short* mode)
/* Saves information about gold-silver alloy.
Parameters:
sn: solution number (Gibbs numeration),
nc: total number of components in the solution (should be 2),
NameForm: nc strings (name(14 chars)[+formula(? chars)]+'\0'),
mode: a value from 0 to 255 on entry; 2 on exit (no volume).
Returns:
-1: incorrect solution number or second Primary call (Gibbs error),
0: success,
1: non-binary solution,
2: incorrect component name. */
{
short i; char *vp, c;
if (sN!=0||sn<1||sn>255) return -1; /* not the first call or wrong
number*/
if (nc!=2) return 1; /* only binary solution supported by this module */
vp=NameForm; c=tolower(*vp++); iGold=iSilv=0;
if (c=='g') iSilv=2; else if (c=='s') iGold=2; else return 2;
for (i=1;i<4;i++) if (tolower(*vp++)!=(iSilv?"gold"[i]:"silv"[i])) return
2;
for (;*vp++;); /* jump to the second component */
for (i=0;i<4;i++) if (tolower(*vp++)!=(iGold?"gold"[i]:"silv"[i])) return
2;
if (iGold) iSilv=1; else iGold=1; sN=sn; *mode=2;
return 0; /* iGold and iSilv are sequential numbers of Gold and Silver
(1|2) */
}

/*------------------------- Secondary call --------------------------*/

short __stdcall Secondary(short sn,float tK,float
pB,short*nn,double*n,float*d)
/* Calculates logarithms of activity coefficients.
Parameters:
short sn: solution number (Gibbs numeration),
float tK: current temperature (K),
float pB: current pressure (bar),
short nn[]: components sequential numbers,
double n[]: their energies or quantities (moles) depending on d,
float d: switch: if d<0 n[] contains energies, otherwise quantities.
Returns:
-1: incorrect solution (Gibbs error),
0: success,
1: phase is absent (<1.66E-24 moles) (Gibbs error).
On exit (if d>=0 and success):
n[0]: 0 (volume is not calculated),
n[j]: logarithms of activity coefficients,
d: 1.0 */

{
short i; double x,y,z,xGold,xSilv;
if (sn!=sN) return -1; /* wrong solution number */
if (*d<0) return 0; /* do nothing with energies */
*d=1.F; n[0]=0; i=nn[0]; if (i<1||i>2) return 1;
if (i==1) {n[1]=0; return 0;}
x=n[iGold]; y=n[iSilv]; if (x<0||y<0||(z=x+y)<1.66e-24) return 1;
xGold=x/z; xSilv=y/z; /* mole fractions */
x=xGold; y=1.-x; z=1600.*x+1.375*tK;
xSilv=(z-5650.)*x*x;
xGold=(z-4850.)*y*y;
z=1.987192*tK; /* RT; R in cal/mol*K */
n[iGold]=xGold/z;
n[iSilv]=xSilv/z;
return 0;
}

/*---------------------------- Final call ---------------------------*/

short __stdcall Final(short sn)
{
sN=0; return 0;
}

/* End of code */