Essentially, only three stages of programming are required to proceed from the initialisation of ChemApp to the collection of results; these are
In the simplest case, each stage can be accomplished by calling one or two subroutines. Naturally, each extra condition set, or result to be retrieved, increases the number of required subroutine calls.
A thermodynamic system consists of a number of phases, where some may have a composition expressed as amounts of a number of phase constituents, and others can have an invariant composition. Phases are divided into three groups in ChemApp - the gaseous phase, condensed mixtures, and condensed stoichiometric phases.
Phases and phase constituents always have thermochemical properties (activities, chemical potentials, enthalpies, volumes, etc.). Phase constituents have compositions expressed as amounts (i.e. stoichiometric coefficients) of a number of components. A component is a system-wide entity. Sometimes this is stressed by calling it a system component. Usually components are elements, but it is also possible for them to be stoichiometric combinations of elements. For example, in an oxide system based on calcia and silica, CaO and SiO2 may be used, as well as Ca, Si, and O. Caution: In the more general case, it is necessary to ensure that the stoichiometric formulae are linearly independent.
Note: In a ChemApp data-file, the total number of components of a defined system includes phase-internal electrons; for example, when an aqueous phase is present. However, they are not counted when the maximum number of possible phases in the system is determined according to Gibbs' phase rule.
At chemical equilibrium, the absolute activities (chemical potentials) of the components are the same in the entire system. Internally in ChemApp, the actual number of system components is calculated as the rank of the stoichiometry matrix (see Appendix E). This number may vary during the course of the Gibbs energy minimisation when only constituents with amounts greater than zero are considered. Should a complete reaction have taken place between two or more of the entered system components at equilibrium, it might not always be possible to calculate their absolute activities. For example, if in the system Mg-Si 2 mol of Mg and 1 mol of Si are entered, the stoichiometric condensed phase Mg2Si forms at low temperatures.
In order to calculate the thermochemical properties for the components, their respective reference state has to be selected. As this cannot be done in a general way, calculation of these properties is not included in ChemApp.
ChemApp maintains a list of components. These are numbered sequentially from 1 up to the total number of components. This sequence of numbers will never change, even if only a subset is included in the input amounts of a calculation. Several subroutines are available for obtaining information on the components and how to manipulate them:
ChemApp maintains a list of phases. These are numbered sequentially from 1 up to the total number of phases. This sequential number does not change, even if phases are eliminated or set dormant.
ChemApp maintains a list of the constituents of each phase. These are numbered sequentially from 1 up to the total number of constituents of each phase. This sequential number does not change, even if constituents are eliminated or set dormant. The number of constituents may be different in each phase. Stoichiometric condensed phases are considered to consist of one constituent only.
ChemApp provides a number of subroutines to retrieve information on sublattices and their constituents.
In this section, several concepts are introduced which are important to the ChemApp application programmer. They include a description of the two ways initial conditions can be defined (global conditions and streams), and a short introduction to two calculational methods: target calculations and one-dimensional phase mapping.
ChemApp offers considerable flexibility for defining initial conditions of a chemical equilibrium calculation. Two different methods are available that will cover most cases experienced in practice. Note, however, that you can only use one of these methods at a time; they cannot be used simultaneously.
Using this method, you merely need to set single conditions for pressure and temperature, and enter incoming species to define the composition of the system. For example, if you wish to calculate the thermodynamic equilibrium for the system SiO2-CaO, using a ChemSage-compatible data-file that among others contains the elements Ca, Si, and O, you would only need to define the temperature and pressure of the system, and the total amounts of SiO2 and CaO present.
Conditions are set using the subroutine TQSETC and can be removed subsequently with the subroutine TQREMC. It is also possible to choose a number of other variables of state (see Table 13).
A stream is a means for transferring non-reacted matter (see also the notes in Appendix B.1) to a reaction zone. It has constant temperature and pressure, and contains one or more phases of fixed composition. When using this method, you set the three variables - composition, temperature and pressure - for one or more input streams. For example, one stream entering a reaction zone may comprise O2(g) pre-heated to a temperature of 1500 K, and the other may consist of CO(g) at room temperature.
The streams method must be used for calculation of the extensive properties of reactions; for example, those involving the heat balance or the adiabatic temperature of a combustion process. It is also convenient to use it for reactor calculations, where you know what is entering the system and wish to calculate results at various stages during and at the end of the process. Streams are defined using the subroutine TQSTTP and can be removed again by using the subroutine TQSTRM.
The composition of a stream (see TQSTCA) must be entered using phases and phase constituents only. If one wants to enter the incoming amounts for a stream in terms of the system components (i.e. usually the elements), one has to perform an intermediate calculation. This is discussed in Appendix B.2.
ChemApp is able to perform two types of target calculations:
An extension of the second type are one-dimensional phase-mapping calculations, see below.
Target calculations are those in which certain conditions (targets) are set, for instance the value of a heat balance or the presence of a phase at equilibrium. These conditions can only be satisfied when the value of some other variable, i.e. the target variable, is adjusted accordingly. When programming a target calculation with ChemApp, the target is set using TQSETC/TQSTEC, while the target variable is set when calling TQCE/TQCEL.
When performing an extensive property target calculation with ChemApp, one of the following five extensive properties of the system can be selected as target: Heat capacity, enthalpy, entropy, Gibbs energy, or volume.
A phase target calculation enables conditions to be determined when a selected phase is present at equilibrium (formation phase target), or when an unspecified phase is precipitated from a specified solution phase (precipitation phase target).
For examples on how target calculations are performed, see the code example for TQCE and the worked examples Phase equilibria and phase target calculations (see Appendix C.3) and A simple process using streams (see Appendix C.4).
Note that ChemApp light is not able to perform target calculations.
One-dimensional phase-mapping is used to search for all phase transitions within a given interval of a search variable. The search variable can be either total pressure, temperature, or incoming amount.
For examples on how one-dimensional phase-mapping calculations are performed, see the code example for TQMAP and the worked example One-dimensional phase mapping (see Appendix C.5).
The regular version of ChemApp is supplied on disks or on CD, or is in special cases installed directly on your computer. In both cases, the code is in the form of readily usable libraries that can be linked to your application code with your own compiler. Please contact GTT-Technologies if you have any questions concerning the installation and use of ChemApp.
ChemApp light and its manual, on the other hand, are only available from GTT's Technical Thermochemistry Web Page, though it might be distributed through other selected channels in the future. This manual of ChemApp light is only available in online form, not as a printed version.
ChemApp is programmed in FORTRAN, as most large packages for fluid flow, process simulation, etc. were originally developed in this language. However, other languages can be used for the application program which links to ChemApp. In the present manual for instance, the use of C is demonstrated along with FORTRAN examples. For other supported languages like Delphi and Visual Basic, the distribution contains a port of the program CADEMO1, plus language specific application notes (see also below).
Starting with version 5.0.0, all Windows distributions of ChemApp require a hardware key (dongle). This is the same type of hardware key that is also required to run FactSage. In fact, ChemApp and FactSage can share the same physical dongle. If you are already a user of FactSage, you thus have the option of having your FactSage dongle(s) updated for use with ChemApp. Alternatively, or in case you are not already a user of FactSage, you also have the option of receiving separate dongles for use with ChemApp.
The ChemApp library was designed to be strict and unambiguous in its use. Its purpose is to transfer information between the calling code and the internal calculation kernel, and to allow for the retrieval of results in a straightforward manner.
If ChemApp will be used with a language other than FORTRAN, please make sure you read the programming notes relating to that language. For your convenience these notes are included below (see Chapter 1.9). Please also read the notes on file that came with your ChemApp distribution, as they might contain more recent information.
In the main part of this manual, all subroutines of the ChemApp library are described. Each subroutine contains a list of input and output variables or arrays as arguments. These are declared as either of type character, integer, double precision, or arrays thereof, and have to be passed or returned as one of these.
Character variables can be of any length in the application program, but are restricted to 24 characters in ChemApp. The exceptions are the subroutines TQERR, TQGTRH, TQGTID, TQGTNM, and TQGTPI, which all return character strings longer than 24 characters. Character options are case-insensitive. They can be entered preferably as arguments, but then may need to end with a blank space, depending on the compiler used. Both names and options can be uniquely abbreviated. When a character variable is output, it does not contain any leading blanks.
Entries for names of components, phases and constituents of a phase present in the thermodynamic data-file in use must be unambiguous. Names are case-sensitive and can consist of a string of letters up to 24 characters in length. For example, 'CO' and 'Co' can be two different phase constituents, and a component can be named 'My_favourite_component'.
Whenever a syntax error in the call of a subroutine or a run-time error occurs, ChemApp returns an error number greater than zero via the last parameter of each ChemApp subroutine. It also writes an error message to the standard output unit. This destination unit, and thus also the file associated with it, can be changed using TQCIO, or turned off altogether. This is useful for application programs which make use of a graphical user interface (GUI), in which case the error messages can instead be selectively retrieved using TQERR.
It is strongly recommended to check the error number frequently and, if possible, to have the error message being displayed directly on screen whenever an error occurs (see for instance the FORTRAN and C versions of the demo program CADEMO1 in Appendix F and G).
The next sections contain language specific notes for ChemApp. They are also part of your ChemApp distribution. Please make sure you consult them, in case they contain more recent additions.
In the main part of the manual describing the ChemApp subroutines, reference is made not only to FORTRAN as a programming language, but also to C whenever possible. For readability purposes any specific C terms may have been omitted from the text, if the FORTRAN term used is unambiguous. For instance, when the FORTRAN term 'DOUBLE PRECISION' is used, it is understood that in C programming, 'double' is meant. The corresponding data types in all supported application languages are summarised in Table 1.
Table 1: Data types used in ChemApp. For examples on how these data types are used, please refer to the example programs, especially in terms of the use of the various character/string data types and arrays consisting of any of those data types.
FORTRAN | C/C++ | Delphi/Pascal | Visual Basic |
INTEGER | long int | LongInt | Long |
DOUBLE PRECISION | double | Double | Double |
CHARACTER | char | String | String |
CS
and TQ
, as these might
interfere with names used within ChemApp. If your compiler still
produces warnings or errors that relate to variable and common block
names starting with CS
and TQ
, your FORTRAN system
libraries might make use of such names. In this case, please contact
GTT-Technologies.
Exceptions are the subroutine tqerr
, as well as the
subroutines tqgtrh
, tqgtid
, tqgtnm
, tqgtpi
,
and tqwstr
, which all pass or return strings longer than 24
characters.
While ChemApp itself is written in FORTRAN77, the use of C/C++ for application programming is also possible on most platforms.
Most C/C++ compilers require an interface library for this purpose, in order to properly link to the ChemApp library. This interface consists of
libChemAppC.a
), or
a source code file (e.g. cacint.c
), depending on your
particular distribution, which you add to your projects,
cacint.h
).
Please refer to the C example supplied with this distribution for information on how to use these files. The header file needs to be included by your C/C++ files, and the library needs to specified during the link process.
Here is a list of points to be aware of when using ChemApp with C/C++:
tqini
, not TQINI
).
tqcsc
(Change-System-Components). Due to the
differences between the FORTRAN and C/C++ parameter passing and
string handling, C/C++ code has to provide a slightly different
string array at this point than FORTRAN code. Whereas in FORTRAN
this array has to consist of as many strings as there are system
components, in C/C++ it has to have one extra string element, which
has to be empty. Please see the C program provided for an example
usage of tqcsc
.
All character variables for use with ChemApp, e.g. variables that hold names of system components, phases, phase constituents as well as for other purposes like identifiers for the status of a phase, should be 24 characters in length (this means 25 characters in C/C++, taking the trailing null character into account).
Exceptions are the subroutine tqerr
, for which a variable
TQERRMSG
is declared in cacint.h
, as well as the
subroutines tqgtrh
, tqgtid
, tqgtnm
, tqgtpi
,
and tqwstr
, which all pass or return strings longer than 24
characters.
INTEGER
variable is different
in size from a C/C++ int
variable. The same is possible for
FORTRAN's DOUBLE PRECISION
and C/C++'s float
. On most
platforms, INTEGER
corresponds to long int
and
DOUBLE PRECISION
corresponds to double
. To avoid
compiler error messages due to these differences, please use the
type LI
when declaring an integer variable for use with
ChemApp in C/C++, and DB
when declaring a float variable for
use with ChemApp. These two types are defined in cacint.h
specific to your platform. See the C program provided for examples.
&
) properly when passing variables to
ChemApp functions. All variables through which values are
returned, and which are not considered arrays by C/C++, need the
address operator.
tqrfil
(Read-File), tqrbin
(Read-Binary-Data-File), and tqrcst
(Read-Transparent-Data-File) expect the file from which the
thermodynamic data should be read to be open. In FORTRAN, the
standard statement OPEN
is used to open a file using the
correct unit number. In non-FORTRAN programs, there is no way to
make sure a file opened with functions such as fopen
gets
associated with a certain unit number so that a FORTRAN subroutine
can access it. To overcome this problem, special FORTRAN routines
are provided which open and close a file using C/C++ under a
specific FORTRAN unit number. Refer to the C program provided and
the documentation to see how these functions (tqopna
,
tqopnb
, tqopnt
, tqopen
and tqclos
) are used.
Note that tqopen
does not check whether the file to be
opened already exists or not, since tqopen
can be used both
for opening existing files for reading, and new files for writing
(tqcel
, tqshow
). Whether the file to be opened already
exists should be checked prior to a call to tqopen
. Also, the
use of tqopna
, tqopnb
, and tqopnt
instead of
tqopen
is strongly recommended to open thermochemical
data-files for reading.
While ChemApp itself is written in FORTRAN77, the use of Borland Delphi® for application programming is possible by using the ChemApp DLL for Borland Delphi.
Please note that the DLL versions of ChemApp are usually not interchangeable between the compilers. To utilise ChemApp with your Delphi projects, you need to make sure that you are using the ChemApp DLL for Borland Delphi, a ChemApp DLL for another compiler (e.g. Microsoft Visual C++®) will likely not work.
To make use of ChemApp from within your Delphi projects, you need to
cadint.pas
in your projects (this file
contains the Delphi interface to ChemApp and is part of the
distribution),
If you would like to use the standard version of ChemApp, use
the conditional CA_DEL_S
. This will result in your
application making use of ca_del_s.dll.
If you would like to use the extended version of ChemApp, use
the conditional CA_DEL_E
. This will result in your
application making use of ca_del_e.dll.
If you would like to use the light version of ChemApp, use
the conditional CA_DEL_L
. This will result in your
application making use of ca_del_l.dll. This is also the default,
i.e. the light version is used when none of the other
conditionals is defined.
ChemAppDLL
in the file cadint.pas
(depending
on the distribution you are using, ChemApp comes in a "standard",
"extended", or "light" version, which are named differently to
avoid ambiguity).
Please use the Delphi example program supplied with this distribution
as a test case to determine whether you set up your projects
correctly. Compare the results this program generates to the master
results in the files cademo1.rst
and result
. If you have
any problems reproducing these results, please contact GTT-Technologies.
Here is a list of points to be aware of when using ChemApp with Delphi:
tqcsc
(Change-System-Components). Due to the
differences between the FORTRAN and Delphi parameter passing and
string handling, Delphi code has to provide a slightly different
string array at this point than FORTRAN code. Whereas in FORTRAN
this array has to consist of as many strings as there are system
components, in Delphi this array has to have one extra string
element, which has to be empty. Please see the Delphi program
provided for an example usage of tqcsc
.
In contrast to other languages, Pascal is strict in terms of
parameter type matching, which makes it difficult to use a type like
string[24]
for this purpose (as is done in the C/C++ interface
to ChemApp).
Thus, all strings used in the Delphi interface to ChemApp
(cadint.pas
) are of type string
, which means that all
strings declared in an application program and used as parameters
for ChemApp procedure calls should be of type string
, or
otherwise properly typecast/converted. It is important to realize
that for names like system components, phases, phase constituents,
etc., ChemApp itself does only make use of the first 24 characters of
a string passed to it, and only returns a maximum of 24 characters
to the calling code.
Exceptions are the subroutine tqerr
, for which the type
Terrmsg
is declared in cadint.pas
, as well as the
subroutines tqgtrh
, tqgtid
, tqgtnm
, tqgtpi
,
and tqwstr
, which all pass or return strings longer than 24
characters.
longint
, every floating point variable of
type double
. To simplify the declaration of those variables,
and to make the Delphi version of the interface to ChemApp
consistent with that in other languages, several "type"s have been
declared in cadint.pas
, like LI
(for longint
) and
DB
(for double
), which you are encouraged to use. Please
see the type declaration section in cadint.pas
for a list of
these types.
tqrfil
(Read-File), tqrbin
(Read-Binary-Data-File), and tqrcst
(Read-Transparent-Data-File) expect the file from which the
thermodynamic data should be read to be open. In FORTRAN, the
standard statement OPEN
is used to open the file using the
correct unit number. In Delphi, there is no way to make sure a file
opened with functions such as AssignFile
gets associated with
a certain unit number so that a FORTRAN subroutine can access it. To
overcome this problem, special FORTRAN routines are provided which
open and close a file using Delphi under a specific FORTRAN unit
number. Refer to the Delphi example program provided to see how
these functions (tqopen
, tqopna
, tqopnb
,
tqopnt
, and tqclos
) are used.
Note that tqopen
does not check whether the file to be
opened already exists or not, since tqopen
can be used both
for opening existing files for reading, and new files for writing
(tqcel
, tqshow
). Whether the file to be opened already
exists should be checked prior to a call to tqopen
,
tqopna
, tqopnb
, and tqopnt
. For further details,
see the manual section on tqopen
.
While ChemApp itself is written in FORTRAN77, the use of Microsoft Visual Basic® for application programming is possible by using the ChemApp DLL for Microsoft Visual Basic.
Please note that the DLL versions of ChemApp are usually not interchangeable between the compilers. To utilise ChemApp with your Visual Basic projects, you need to make sure that you are using the ChemApp DLL for Microsoft Visual Basic, a ChemApp DLL for another compiler (e.g. Microsoft Visual C++®) will likely not work.
To make use of ChemApp from within your Visual Basic projects, you need to
cavbint.pas
in your projects (this file
contains the Visual Basic interface to ChemApp and is part of the
distribution),
conChemAppStandard
,
conChemAppExtended
, or conChemAppLight
) is set to
1
in the file cavbint.pas
(ChemApp is supplied in
"standard", "extended", and "light" versions, which are named
differently to avoid ambiguity).
Please use the Visual Basic example project cademo1
supplied
with this distribution as a test case to determine whether you set up
your projects correctly. Compare the results this program generates to
the master results in the files cademo1.rst
and result
. If
you have any problems reproducing these results, please contact
GTT-Technologies.
Here is a list of points to be aware of when using ChemApp with Visual Basic:
conChemAppStandard
, conChemAppExtended
,
or conChemAppLight
) can either be set through cavbint.bas
(as described above), or by conditional compilation directives
specified in the Project Properties dialog box, or on the command line.
For more information on this topic, see the section "Using Conditional Compilation" in the "More About Programming" section of the "Visual Basic Programmer's Guide".
tqcsc
(Change-System-Components). Due to the
differences between the FORTRAN and Visual Basic parameter passing and
string handling, Visual Basic code has to provide a slightly different
string array at this point than FORTRAN code. Whereas in FORTRAN
this array has to consist of as many strings as there are system
components, in Visual Basic this array has to have one extra string
element, which has to be empty. Please see the Visual Basic program
provided for an example usage of tqcsc
.
FORTRAN77 only knows strings of fixed length. Using the same type of
strings on the Visual Basic side of the interface is unpractical,
since every string variable returned by ChemApp would be padded with
blanks. Thus, all strings used in the Visual Basic interface to
ChemApp are variable-length strings (Dim As String
), with
trailing blanks properly removed when returning from ChemApp. It is
important to realize that ChemApp itself does only make use of the
first 24 characters of a string passed to it, and only returns a
maximum of 24 characters to the calling code.
Exceptions are the subroutine tqerr
, for which a variable
TQErrMsg
is declared in cavbint.pas
, as well as the
subroutines tqgtrh
, tqgtid
, tqgtnm
, tqgtpi
,
and tqwstr
, which all pass or return strings longer than 24
characters.
Long
. Similarly, every
real variable for use with ChemApp subroutines has to be of type
Double
.
tqrfil
(Read-File), tqrbin
(Read-Binary-Data-File), and tqrcst
(Read-Transparent-Data-File) expect the file from which the
thermodynamic data should be read to be open. In FORTRAN, the
standard statement OPEN
is used to open the file using the
correct unit number. In non-FORTRAN programs, there is no way to
make sure a file opened with functions such as fopen
gets
associated with a certain unit number so that a FORTRAN subroutine
can access it. To overcome this problem, special FORTRAN routines
are provided which open and close a file using C/C++ under a
specific FORTRAN unit number. Refer to the C program provided and
the documentation to see how these functions (tqopna
,
tqopnb
, tqopnt
, tqopen
and tqclos
) are used.
Note that tqopen
does not check whether the file to be
opened already exists or not, since tqopen
can be used both
for opening existing files for reading, and new files for writing
(tqcel
, tqshow
). Whether the file to be opened already
exists should be checked prior to a call to tqopen
. Also, the
use of tqopna
, tqopnb
, and tqopnt
instead of
tqopen
is strongly recommended to open thermochemical
data-files for reading.
Like any other tool, software or otherwise, ChemApp can be used in a good way, and in a better way. The following section intends to familarize you with guidelines to help you write better code with ChemApp, and in doing so should aid you in achieving your objectives wasting not only less time, but also less nerves.
If you encounter a problem in your work with ChemApp, and would like to contact GTT-Technologies' support in order to help you track down a problem in your code, or find out whether the problem might lie in ChemApp itself, this section is recommended reading. The points below are the result of several years of experience with many support issues, and we thus strongly recommend checking your code as to whether these best practises are implemented before you send it to us.
In fact, we have found that many apparent problems turn out to be "false alarms" on the user's side, and become obvious once they follow these best practices. Due to the time constraints and the workload of GTT-Technologies' support team, we might have to refrain from debugging users' code if these best practices are not implememted. (A typical example is that the error code which every ChemApp subroutine returns is only checked when calculating the equilibrium with TQCE, thus overlooking the fact that the actual reason why an equilibrium calculations fails actually results from an earlier call, for instance to TQINP with a phase name that doesn't exist.)
If your program produes any kind of textual output, make sure it includes the ChemApp version number. This is especially useful if you store the output for documentation purposes: if you re-run the program later, potentially with another version of ChemApp, and discover differences in the output, you will be glad you stored this piece of information.
Before you contact GTT's support: Every output sent to GTT-Technologies' technical support should include the ChemApp version number, as returned by your program at run-time using TQVERS.
With almost all distributions of ChemApp, the ChemApp library comes
in more than one version. All distributions contain at least a
standard and an extended version. They differ in the
maximum size of the chemical system they can handle. Make sure you
don't use the standard version, when your data-file is too large for
it and actually requires the extended version. See the file
version.txt
for details, it is part of your ChemApp
distribution.
If you have been using a version of ChemApp light before you switched to the regular version, make sure you are not still using the "light" version.
Some distributions also include other versions of the ChemApp library. In case you are using a special version of ChemApp that allows you to add your own user models, make sure you don't use a regular version of the ChemApp library for linking instead.
If you are using a compiler-optimized version of ChemApp and you have doubts about the validity of your results, run your program with the non-optimized version too and see if the results are different. If they are, contact GTT-Technologies' technical support.
Before you contact GTT's support: If you have a problem with ChemApp and send your code to GTT-Technologies' technical support, make sure you have double-checked whether you are using the suitable library version. In case you are normally working with the standard version of ChemApp, make sure you have tested your program also with the extended version. In case you are normally working with a compiler-optimized version of ChemApp, make sure you first re-run your program using the non-optimized version of ChemApp, then check for differences.
Every ChemApp subroutine has an error variable as its last
parameter. Make sure your code checks this error variable after each
call to a ChemApp subroutine. For examples on how to do this, see
the cademo1
program. (Note that the short ChemApp example
programs that are part of the reference section describing the
various ChemApp subroutimes do purposely not follow this convention:
to keep these code examples short and easy to read, error handling
has usually been neglected.)
This is especially true when developing programs that have a graphical user interface (GUI): if you do not check the error variable after each call to a ChemApp subroutine, errors might go unnoticed until much later in your code, at which point they might result in an error which is misleading with respect to the reason why it occured.
The same is true for command line applications, if you use TQCIO to redirect your error messages to unit 0. This effectively hides the otherwise automatic reporting of errors.
Before you contact GTT's support: If you have a problem with ChemApp and send your code to GTT-Technologies' technical support, make sure your code has been written and run in a way so that any errors that ChemApp reports through this error variable were caught, reported, and didn't go unnoticed!
See also: TQERR.
Whenever possible, use ChemApp subroutines to open and close ChemSage data-files.
By selecting the proper ChemApp subroutine to open your ChemSage data-file which matches the format of your data-file (TQOPNA for ASCII data-files, TQOPNB for binary data-files, TQOPNT for transparent data-files), you make sure that your data-file is opened correctly.
Before you contact GTT's support: Make sure that the error you encountered is not related to the way you open the thermochemical data-file.
It is especially important to check the error variable when opening and reading ChemSage data-files.
Before you actually open a data-file, add appropriate code to your program that first makes sure this data-file really exists, and is found in the directory where you expect it.
Before you contact GTT's support: If you have a problem with ChemApp and send your code to GTT-Technologies' technical support, make sure you always add the data-file that you used when encountering the problem. Make sure the source of your problem is not the fact that you by accident try to load a data-file under a different name, or from another directory.
Make sure that after opening and reading your data-file, you close it again. Otherwise problems might occur if you try to read the same data-file more than once, because then the file pointer is not located at the very beginning of the file.
If you are using transparent data-files, ChemApp might refuse to load the data-file if certain conditions are not met. For instance, you might not be authorized to read the data-file because it was created with FactSage under a user id that doesn't match your ChemApp user id.
To catch these cases early on, have your ChemApp program report and log your user id (TQGTID) and optionally your user name (TQGTNM). After reading a transparent data-file successfully, consider reporting and logging information returned by TQGTRH.
Before you contact GTT's support: If you have a problem with reading a transparent data-file created with FactSage and send your code and transparent data-file to GTT-Technologies' technical support, make sure you understand the error message ChemApp reports. Double-check if the transparent data-file was created under a FactSage user id that matches your ChemApp user id.
Don't try to save time by hard-wiring index numbers for system components, phases, phase constituents, and the like, unless you're still in the prototyping phase. Always let ChemApp tell you these index numbers based on the name of the entity that you're interested in. If your data-file ever gets changed, whether on purpose or by mistake, you might find yourself having to change these hard-wired portions of your code. The worst case is if you don't even notice that the data has changed, and you end up calculating something very different without realizing it.
For this reason, as well as for documentation purposes, you should consider having your program include a short table of contents of the data-file in your results or your log file. Have a look at worked example 1 in the ChemApp Programmer's Manual for suggestions.
Before you contact GTT's support: Make sure you do not use hard-wired index numbers in your code, but for instance always use the appropriate ChemApp subroutines to retrieve these numbers at run-time.
If you want to or have to store results from your program for archival purposes (for instance by backing them up to tape or CD), don't forget to also store the thermochemical data-files you used to create them. From a ChemApp point of view, you should archive the following things:
When writing customized programs based on ChemApp, especially those that either have a GUI, or those which are add-ons or modules for third-party programs, one is often tempted to exclusively rely on TQGETR to retrieve results from an equilibrium calculation.
While TQGETR gives you access to almost every piece of information you could want from an equilibrium calculation, it generally has one disadvantage: you will naturally only see the results you asked for. This can be a problem if you're still in the early stages of program development or of using a particular data-file, or when you are looking for reasons why your calculations don't give you the results you expected.
In these cases, a concise view of the whole equilibrium state is much more useful. This is exactly what a ChemSage result table provides, it gives you an overview of what your inputs were, what conditions you used, and what the equilibrium of your whole system looks like, all in an easy-to-read table.
Make use of these tables, which are produced when TQCEL, TQMAPL, or TQCENL are called. If your code has a GUI or is part of another program, consider sending this output to a log file. Consider using TQWSTR to add instructive comments to the same log file.
If you also have FactSage available, you might find it helpful to run a FactSage calculation with the same incoming amounts and conditions, since it gives you more interactive tools to explore a particular equilibrium calculation.
Before you contact GTT's support: If you have doubts about particular results you get from TQGETR, make sure you have also looked at the bigger picture, i.e. at other results that together describe the overall equilibrium state, for instance using the ChemSage result table output from subroutines like TQCEL.
In many programs, especially simpler ones, you likely know rather well what your incoming amounts are, because you often set the conditions for your equilibrium calculation yourself, or a user inputs them at run-time.
But there are types of programs where you don't necessarily always know what is input, and easily loose track of it:
In both cases, you should provide means to make sure that the incoming conditions are still valid for the chemical system and the thermochemical data you are using. For instance, a temperature or an incoming amount might exceed an upper limit specified for the data you are using, thus potentially rendering the equilibrium results doubtful or even useless, or causing ChemApp not being able to calculate the equilibrium. The output from both TQSHOW and TQCEL, as well as calls to TQSETC with the "ia" option can help keeping track of incoming amounts.
Before you contact GTT's support: If you need help with an equilibrium results that looks doubtful, especially if your code is is iterative, make sure you carefully double-checked that the incoming amounts for this equilibrium calculation are what you intended them to be, and are valid with respect to the thermochemical data you are using.
Suboutines used to define incoming amounts (e.g. TQSETC), as well as those used to retrieve results (e.g. TQGETR) only return the values, but not the associated units for temperature, pressure, energy, volume, or amount. The units used by ChemApp are always those which are currently active, and can be retrieved using TQGSU.
Don't automatically assume, especially in more complex programs, that you always know what the currently active system components are. Instead of hard-wiring the output of particular units, retrieve them at run-time using TQGSU.
As an example, do not hard-wire amount units in your output. You might think you're using the default value of "mol". But if you, somewhere in your code, retrieved molecular masses for phase constituents or stoichiometric compounds, you will likely have switched to unit "gram", in order to get the molecular masses in "gram/mol", which are generally expressed as "[current amount unit/mol]". If you forgot to switch back from "gram" after that, you might be confused by the results, if you hard-wired "mol" in your output. The same can happen if you hard-wire "gram/mol" in your output of the molecular masses, and are suprised that you get "1.0 gram/mol" for every phase constituents and stoichiometric compound. The reason is most likely that your amount unit is "mol", which gives you "mol/mol" as unit for the molecular masses. Retrieving the current amount unit at run-time to print the unit as "[current amount unit/mol]" makes this condition immediately obvious.
In terms of ChemApp and what it calculates, good support for debugging basically means providing some features in your program that can help you look more closely at calculations that do not produce the results you expected. One way is to store the TQCEL output to a log file (see above).
If you really encounter problems with equilibrium calculations (ChemApp doesn't find an answer, ChemApp takes too long, etc.), you might not get an output from TQCEL, because the equilibrium calculation did not produce a result. In these cases, output from TQSHOW, called immediately before the equilibrium calculation with TQCE or TQCEL, can help tremendously. In fact, the output from TQSHOW, together with the thermochemical data-file you are using, and information about the target variable (if you are performing a target calculation) are the most helpful pieces of information for GTT-Technologies' technical support when trying to find the reasons for problems with individual equilibrium calculations that do not converge.
Instead of simply calling TQCE to calculate the equilibrium in your program, consider implementing the following code in order to quickly switch to "debug" mode, when need arises (this code is outlined in "pseudo code" and can be easily implemented in any programming language):
if DEBUGMODE NoOfEquilCalcs = NoOfEquilCalcs + 1 ErrorLog = "ERRLOG" + NoOfEquilCalcs + ".TXT" call TQCIO to redirect "LIST" output to ErrorLog call TQCIO to redirect "ERROR" output to ErrorLog open ErrorLog for writing call TQSHOW close ErrorLog open ErrorLog call TQCEL if NOERR from TQCEL is NOT zero call TQWSTR to store any additional useful information to ErrorLog close ErrorLog else close ErrorLog delete ErrorLog endif call TQCIO to redirect "LIST" and "ERROR" to their original units, if necessary else call TQCE endif
This simple code (which can still be improved) does the following things:
ErrorLog
), which is given a unique name (in
this example it is suggested that the number of equilibrium
calculations performed this far is used to build a unique filename).
ErrorLog
.
ErrorLog
to make sure that this
info is physically written to disk, in case your program hangs or
crashes before TQCEL can produce output. This part of the code
can be optimized, depending on which programming language you are
using. For instance, instead of closing and reopening ErrorLog
,
you can also "flush" the write buffers of this file to disk, if
the programming language you are using offers support for this.
ErrorLog
.
ErrorLog
file is deleted. If TQCEL reports an error,
ErrorLog
contains all necessary information about the
problematic equilibrium calculation. Note that even if your
program hangs or crashes, ErrorLog
still contains the TQSHOW
output, which is often enough for GTT-Technologies' technical
support to trace the problem, provided the thermochemical
data-file is supplied too.
Before you contact GTT's support: If ChemApp encountered any problematic equilibrium calculations, all necessary information is thus stored to log files, one file for each problem. If you have problems with particular equilibrium calculations and would like to contact GTT-Technologies' technical support, this is what should be included with your email: The TQSHOW output and the section of the source code that performs the equilibrium calculations (always), the TQCEL output (if possible), and the data-file you used (always).
All thermochemical data that ChemApp needs for its calculations are loaded from data-files, where each data-file contains the thermochemical data for a more or less complex chemical system.
A comprehensive list of readily available standard data-files that are adequate for many applications can be obtained from GTT-Technologies or accessed through our World Wide Web page. Customised data-files can also be prepared to meet a user's specific requirements.
The data-files for ChemSage and ChemApp come in a number of forms: ASCII, binary, or transparent. It is necessary for every user of ChemApp (where the user is usually the programmer, or, depending on the application, the end user) to know which of these formats are used for his or her data-files. The reason is that each of these formats requires a slightly different code to be loaded into ChemApp. The details are described below (see Chapters 1.11.2, 1.11.3, and 1.11.4).
A data-file contains the following information:
Components
Phases
Constituents
ChemApp can only read data stored in data-files in the various ChemSage formats (see Chapters 1.11.2, 1.11.3, and 1.11.4). Data stored in a database or a database file must be read with a database management system, for example ChemAccess (the thermochemical database module of ChemSage) or FactSage, which in turn produces ChemSage data-files.
It is not possible to change any thermochemical data using ChemApp, or to add phases and constituents to a system. However, the default system components, as well as the default status of phases and constituents may be changed (see Chapter 3).
More information on the structure and handling of thermochemical data-files can be obtained from Appendix E.
A significant feature of ChemApp is that it includes a comprehensive library of excess Gibbs energy models for various types of non-ideal solution phases. A list of these and typical areas for their application are summarised in Table 2. Additional 'customer-specified' models can be added upon request, and it is also possible for users to add their own solution models to ChemApp, as long as these models fulfill some specific requirements.
For users who develop their own solution models, a special version of ChemApp is available that might allow for the addition of these models. This would then be a three-step process, which can be summarised as follows:
USERGP
, USERGX
, and
USERGG
which are supplied together with the special version of
ChemApp.
If you are interested in adding your own solution models to ChemApp, please contact GTT-Technologies for further details.
Table 2: List of available solution models in ChemApp. Magnetic contributions are not permitted for phase models marked with an asterisk (*)
Model | Application area |
Redlich-Kister-Muggianu [Red48] Kohler-Toop [Pel88] Hoch-Arpshofen [Hoc84] [Hoc84b] [Hoc87] |
For general use with substitutional
or associated solution phases |
Compound energy formalism [Sun81] [Zha81] [Hil85] Two-sublattice order/disorder formalism* [Lac91] Species chemical potential/bond energy formalism* [Oat95] Extended compound energy formalism [Oat99] |
Solid phases with sublattice descriptions |
Two-sublattice ionic formalism* [Sun91] | Ionic liquids |
Two-sublattice equivalent fraction formalism [Pel88] Two-sublattice equivalent fraction formalism as a polynomial [Des91] Guts formalism [Pel] |
Molten salts |
Gaye-Kapoor-Frohberg cell model* [Gay92] Modified quasichemical formalism* [Pel86] [Bla87] [Pel93] |
Ionic oxidic mixtures with or without non-oxidic solutes |
Quadruplet quasichemical model [Pel01] | Condensed non-aqueous solutions |
Binary defect formalism* [Pel] | Binary condensed phases with a narrow stoichiometry range |
Wagner [Pel86b] | Metallic dilute solutions |
Davies formalism* [Dav62] Helgeson-Tanger-Shock formalism (ideal)* [Tan88] Helgeson-Tanger-Shock formalism (Debye-Hückel)* [Tan88] Helgeson-Tanger-Shock formalism (Davies)* [Tan88] |
Dilute aqueous solutions |
Pitzer formalism* [Har84] Pitzer formalism without E-theta and E-theta'* [Har84] Specific ion-interaction formalism* [Gre97] Helgeson-Tanger-Shock formalism (Pitzer)* [Tan88] |
Concentrated aqueous solutions |
Revised Helgeson-Kirkham-Flowers (HKF) model* [Hel81] | Aqueous solutions up to 5 kbar and 1300K |
C-H-O-S-N-Ar multicomponent fluid model* [Bel92] | Fluid mixtures up to 1 Mbar and 6000K; important for
many geological and environmental systems |
Virial equation with Tsonopoulos' second virial coefficient correlation* [Tso74] | Non-ideal gas phases |
The ASCII (plain text) data-file format is the traditional format for thermochemical data-files for ChemSage and ChemApp. Every user of ChemSage and ChemApp has probably seen several of these, since each distribution of ChemSage and ChemApp contains example data-files in this format. See for instance below and Appendix H for an overview on the data-files in ASCII format included with ChemApp.
The most common and recommended file extension for thermochemical data-files in ASCII format is .DAT. ASCII data-files are portable among platforms, the only detail that needs to be observed is that DOS/Windows and Unix systems use different line endings for text files. The failure to do a proper conversion is one common reason for TQRFIL to report error number 103.
Table 3: Overview on the different data-file formats
ASCII | Binary | Transparent |
|
How do I recognize it? | Plain text, can be viewed and edited with an ASCII editor | When viewed, does not contain readable data | When viewed, the first four readable characters of the file are 'CSTR' |
Typical file extension | .DAT |
.BIN |
.CST |
Minimum version of ChemApp required to read the file | V1.0.0 | FORTRAN: V2.1.4 Other: V3.3.0 |
V4.0.0 |
Are the files portable across compilers and/or platforms? | Yes | No | Partially |
Can I edit the data? | Yes, but the use of a program like ChemSage or FactSage is strongly recommended | No, do not attempt to edit, it will render the file useless | No, do not attempt to edit, it will render the file useless |
How do I open it? | FORTRAN: TQOPNA or OPEN Other: TQOPNA |
FORTRAN: TQOPNB or OPEN Other: TQOPNB |
FORTRAN: TQOPNT Other: TQOPNT |
How do I read it? | TQRFIL |
TQRBIN |
TQRCST |
How do I close it? | FORTRAN: TQCLOS or CLOSE Other: TQCLOS |
FORTRAN: TQCLOS or CLOSE Other: TQCLOS |
FORTRAN: TQCLOS Other: TQCLOS |
More information | Chapter 1.11.2 | Chapter 1.11.3 | Chapter 1.11.4 |
The FORTRAN concept of unit numbers is not supported by other
programming languages, thus the thermochemical data-files to be used
by ChemApp cannot be opened with the standard file-opening subroutines
of these languages. Even in cases where the application program is
written in FORTRAN, it is still possible that the standard FORTRAN
statements to open and close files (OPEN
and CLOSE
) cannot be
used, for instance when using ChemApp in form of a DLL from a FORTRAN
application program.
To both simplify and unify access to thermochemical data-files for all application programs and across all programming languages, a set of ChemApp subroutines is provided. This set of subroutines includes TQOPEN, TQOPNA, and TQCLOS.
The subroutine TQOPEN has been part of ChemApp since the earliest versions. It can both be used to open existing files for reading (e.g. thermochemical data-files), as well as to create new files for writing (e.g. files that are used to store the output of TQCEL, the ChemSage result tables). This flexibility, on the other hand, also comes with a disadvantage: If you try to open a data-file for reading, but the file is not where you or the program expects it to be, a new file of zero bytes length will be created instead. This effect is also mentioned in the description of TQOPEN.
Mainly because of this effect, another ChemApp subroutine has been
added, which is available since version V3.3.0: TQOPNA. This
subroutine opens the specified file only if it already exists. If it
doesn't, or if any other error occurs during the file-opening process,
it returns with error number 107. As a note for users familiar
with FORTRAN: TQOPNA opens the file with STATUS='OLD'
.
It is thus recommended that TQOPNA be used instead of TQOPEN for opening thermochemical data-files which are in ASCII format. TQOPEN should be used when opening output files for writing, for instance for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).
As of ChemApp V4.0.0, the subroutines TQOPEN, TQOPNA, and
TQCLOS have been made part of the core code of ChemApp, and are
thus available to all application languages, both FORTRAN and
non-FORTRAN. We recommend using these subroutines also in FORTRAN
application programs, instead of calling the standard FORTRAN
statements OPEN
and CLOSE
, if you are using ChemApp version
4.0.0 or later.
Using FORTRAN as an example, a thermodynamic data-file in ASCII format could be opened with the following code:
C Open thermochemical data-file in ASCII format for reading CALL TQOPNA('cosi.dat', 10, NOERR)
In case the attempt to open the data-file fails, TQOPNA will return with a NOERR value of 107, otherwise the data-file can now be loaded with TQRFIL and closed with TQCLOS:
C Read thermochemical data-file in ASCII format CALL TQRFIL(NOERR) C Close data-file CALL TQCLOS(10, NOERR)
By default, TQRFIL expects the data-file to be opened with unit
number 10, this being the reason for both the OPEN
and CLOSE
statements above referring to this particular unit number. It is also
possible to use a non-default unit number for this purpose, in which
case ChemApp needs to be told about this using TQCIO. ChemApp will
accept unit numbers less then 11 and larger than 19. If ChemApp is
part of a larger FORTRAN program, it is important to make sure that
the unit number used to open the data-file is free, be it unit number
10 or a non-default value. The FORTRAN subroutine INQUIRE
is
helpful in this case.
This basic sequence of opening and loading a thermochemical data-file is used in virtually all example programs listed in this manual.
In FORTRAN terms, ASCII data-files are usually called text files
or formatted sequential files and may be opened with the standard
FORTRAN OPEN
statement by the application program if this is
written in FORTRAN and uses ChemApp in form of a static
library. In case ChemApp is used as a DLL in conjunction with a FORTRAN
application program, this might not work. For this reason the use of
the subroutines TQOPNA and TQCLOS, as explained above, is
recommended even for FORTRAN programs.
If the standard FORTRAN OPEN
and CLOSE
statements are to be
used, the code segment dealing with loading an ASCII data-file
might be similar to the following:
C Open thermochemical data-file in ASCII format for reading OPEN(10, FILE='cosi.dat', STATUS='OLD', IOSTAT=NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' ... ENDIF
Note that the specifiers FORM=
and ACCESS=
can be omitted for
ASCII data-files since their default values FORM='FORMATTED'
and
ACCESS='SEQUENTIAL'
are the correct ones in this case.
Another point to note in the code example above is that if the
OPEN
statement fails, NOERR does not contain a ChemApp error
number (see Appendix A), but one returned directly by
the FORTRAN run time library. For details, please see your FORTRAN
compiler's manual.
The syntax introduced above for opening a thermochemical data-file in ASCII format should be valid for all FORTRAN compilers on all platforms, as long as the data-file to be loaded has the correct line endings for text files on the platform in question. As already mentioned, this is an import detail to be aware of when transferring data-files between different computing platforms.
To make the process of opening data-files even safer, the use of an
appropriate call to the FORTRAN statement INQUIRE
prior to the
OPEN
statements is recommended.
The opened file can then subsequently be loaded into ChemApp with
TQRFIL, and closed with CLOSE
:
C Read thermochemical data-file in ASCII format CALL TQRFIL(NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR loading data-file.' ... ENDIF C Close data-file CLOSE(10)
In terms of the FORTRAN unit number, the same notes apply as above: By
default, TQRFIL expects the data-file to be opened with unit
number 10, this being the reason for both the OPEN
and CLOSE
statements above referring to this particular unit number. It is also
possible to use a non-default unit number for this purpose, in which
case ChemApp needs to be told about this using TQCIO. ChemApp will
accept unit numbers less then 11 and larger than 19. If ChemApp is
part of a larger program, it is important to make sure that the unit
number used to open the data-file is free, be it unit number 10 or a
non-default value. Again, the FORTRAN subroutine INQUIRE
is
helpful in this case.
Binary thermochemical data-files for use with ChemSage and ChemApp are stored in a way which does not permit the end user to extract or change thermochemical data from the file. This is mainly done in cases where a license agreement with the supplier of the data does not permit the distribution in plain text format.
Due to the nature of the FORTRAN standard for writing binary data to files, or rather, the lack thereof, binary data-files are usually not portable across platforms, and in many case are not even portable between different compilers on the same platform (this problem is partially solved by using data-files in transparent format, see below). For the suppliers of binary data-files (in most cases this is GTT-Technologies), this means that the data-file has to be supplied for the very compiler and/or platform that the ChemApp customer uses. For the ChemApp user it means that care has to taken that the binary data-file supplied is only used with the proper compiler. If you try to load a binary data-file into ChemApp that was actually made for a different compiler, you typically will receive error number 103 from TQRBIN.
The most common and recommended file extension for thermochemical data-files in binary format is .BIN. They are otherwise recognized by the fact that when inspected with a file-viewer, their contents are not humanly readable. It is important to realise that a binary data-file should never be edited manually, as it will render the file useless.
Due to the lack of portability of binary files across platforms and compilers, the support of thermochemical data-files in binary format will be discontinued in future versions of ChemApp. As of ChemApp version 4.0.0 the binary file format is superceded by the transparent file format (see Chapter 1.11.4). If you are using ChemApp versions 4.0.0 and later with binary data-files, please contact GTT-Technologies to receive help in converting these data-files to the transparent format.
For the same reasons as mentioned above (see Chapter 1.11.2), a set of subroutines is provided to open and close binary data-files from FORTRAN and non-FORTRAN programs. These subroutines are TQOPNB and TQCLOS. It is important to realise that TQOPEN cannot be used to open binary data-files, as it will always open the data-file specified in ASCII mode. This of course does not affect the use of TQOPEN to create new ASCII files for writing, for instance for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).
As of ChemApp V4.0.0, the subroutines TQOPNB, and TQCLOS have
been made part of the core code of ChemApp, and are thus available to
all application languages, both FORTRAN and non-FORTRAN. We recommend
using these subroutines also in FORTRAN application programs instead of
calling the standard FORTRAN statements OPEN
and CLOSE
, if
you are using ChemApp version 4.0.0 or later.
Using FORTRAN as an example, a thermodynamic data-file in ASCII format could be opened with the following code:
C Open thermochemical data-file in binary format for reading CALL TQOPNB('cosi.bin', 10, NOERR)
In case the opening of the data-file fails, TQOPNB will return with a NOERR value of 107, otherwise the data-file can now be loaded with TQRBIN and closed with TQCLOS:
C Read thermochemical data-file in binary format CALL TQRBIN(NOERR) C Close data-file CALL TQCLOS(10, NOERR)
Note especially that for binary data-files, TQRBIN needs to be used to load the data-file, not TQRFIL or TQRCST.
With respect to the unit numbers, please see the previous section (Chapter 1.11.2) for explanatory notes, they apply equally to binary data-files.
In FORTRAN terms, binary data-files are usually called unformatted
sequential files, and are opened with the standard FORTRAN OPEN
statement, for instance with a sequence similar to the following:
C Open thermochemical data-file in binary format for reading OPEN(10, FILE='cosi.bin', STATUS='OLD', FORM='UNFORMATTED', * IOSTAT=NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' ... ENDIF
Note that the specifier ACCESS=
can be omitted, since its default
value ACCESS='SEQUENTIAL'
is the correct one in this case.
Another point to note in the code example above is that if the
OPEN
statement fails, NOERR does not contain a ChemApp error
number (see Appendix A), but one returned directly by
the FORTRAN run time library. For details, please see your FORTRAN
compiler's manual.
The syntax introduced above for opening thermochemical data-files in binary format should be valid for all FORTRAN compilers on all platforms, but it is important to realise that the binary data-files themselves are usually not portable across platforms, and in many case not even among different compilers on the same platform.
To make the process of opening data-files even safer, the use of an
appropriate call to the FORTRAN subroutine INQUIRE
prior to the
OPEN
statement is recommended.
The opened file can then subsequently be loaded into ChemApp with
TQRBIN, and closed with CLOSE
:
C Read thermochemical data-file in binary format CALL TQRBIN(NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR loading data-file.' ... ENDIF C Close data-file CLOSE(10)
Note especially that for binary data-files, TQRBIN needs to be used to load the data-file, not TQRFIL or TQRCST.
With respect to the unit numbers, please see the previous section (1.11.2) for explanatory notes, they apply equally to binary data-files.
A drawback of the FORTRAN language is the lack of a standard for binary files. This is the main reason why ChemSage data-files in binary format are not portable (see above). To at least partially overcome this problem, the transparent data-file format has been created. Using transparent data-files, approximately 90% of the portability problems on Windows platforms can be overcome.
Transparent data-files differ from data-files in ASCII and binary format in that they have a header which precedes the actual thermochemical data, and which for instance contains information about the data itself, as well as the creator and user of the data-file (see TQGTRH).
On systems running Microsoft Windows, transparent data-files can be used by programs which contain a version of ChemApp that was compiled with any of the following compilers:
Since these compilers are also used to produce ChemSage, FactSage, and all ChemApp DLLs for the Windows platforms (ChemApp DLLs for use with Microsoft Visual Basic and Visual C++, as well as Borland Delphi), this for instance enables a transparent data-file written by FactSage to be read by ChemSheet without modification.
While transparent data-files can be created by GTT-Technologies for every platform for which ChemApp is available, one thing to remember is that transparent data-files created for the Windows-based compilers listed above will very likely not be directly usable on a Unix system, for instance. If you attempt to read a transparent data-file under such a condition, you will typically get error 161. These portability issues will be solved with the future portable data-file format.
Transparent data-files, like binary data-files, are stored in a way that does not permit the end user to extract or change thermochemical data from the data-file. This is mainly done in cases where a license agreement with the supplier of the data does not permit the distribution in plain text format.
The most common and recommended file extension for thermochemical
data-files in transparent format is .CST. They are otherwise
recognized by the fact that when inspected with a file-viewer, their
contents are not humanly readable, apart from a comment in the file
header: This is a ChemSage transparent data file
... . It is
important to realise that a transparent data-file should never be
edited manually, since ChemApp will refuse to load a modified
transparent data-file.
On Windows systems, transparent data-files created for use with any of
the compilers listed above can also be identified by examining the
very first four characters, the magic bytes, of the file, which are
always CSTR
.
As with data-files in ASCII (see Chapter 1.11.2) and binary (see Chapter 1.11.3) formats, the use of a set of subroutines is provided to open and close transparent data-files from FORTRAN and non-FORTRAN programs. These subroutines are TQOPNT and TQCLOS. It is important to realise that TQOPEN cannot be used to open transparent data-files, as it will always open the data-file specified in ASCII mode. This of course does not affect the use of TQOPEN to create new ASCII files for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).
Using FORTRAN as an example, opening a thermodynamic data-file in transparent format would thus be similar to the following piece of code:
C Open thermochemical data-file in transparent format for reading CALL TQOPNT('cosi.cst', 10, NOERR)
In case the opening of the data-file fails, TQOPNT will return with a NOERR value of 107, otherwise the data-file can now be loaded with TQRCST and closed with TQCLOS:
C Read thermochemical data-file in transparent format CALL TQRCST(NOERR) C Close data-file CALL TQCLOS(10, NOERR)
Note especially that for transparent data-files, TQRCST needs to be used to load the data-file, not TQRFIL or TQRBIN.
With respect to the unit numbers, please see the previous section (Chapter 1.11.2) for explanatory notes, they apply equally to transparent data-files.
In FORTRAN programs, transparent data-files can be both opened using
the ChemApp subroutine TQOPNT as described above, as well as using
the standard FORTRAN OPEN
statement. While the use of the FORTRAN
statement OPEN
may be more flexible for this purpose, its calling
syntax when used to open a transparent data-file is
compiler-dependent. Note also that as with opening data-files in ASCII
and binary format, using FORTRAN's OPEN
may not work if you are
using ChemApp in the form of a DLL. Unless you need the added
flexibility of the OPEN
statement, we thus recommend using
TQOPNT as described above.
Here are some examples of how to open a transparent data-file using
the OPEN
statement on various compilers. See below for a
compiler-independent version that uses TQOPNT.
Note that if any of the OPEN
statement fails in the examples
below, the error code returned in NOERR does not contain a ChemApp
error number (see Appendix A), but an error code
returned directly by the FORTRAN run time library. For details, please
see your FORTRAN compiler's manual.
To make the process of opening data-files even safer, the use of an
appropriate call to the FORTRAN statement INQUIRE
prior to the
OPEN
statement is recommended.
Lahey FORTRAN
Under Lahey FORTRAN, the specifier ACCESS='TRANSPARENT'
is used to
open ChemSage transparent data-files, hence we named these
files transparent data-files.
C Open thermochemical data-file in transparent format for reading C (Lahey version) OPEN(10,FILE='cosi.cst', STATUS='OLD', ACCESS='TRANSPARENT', * IOSTAT=NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' ... ENDIF
Note that there is no FORM='...'
specifier used.
The data-file is then subsequently read using TQRCST and closed
using CLOSE
(see below).
Microsoft PowerStation FORTRAN, Digital Visual FORTRAN,
and Compaq Visual FORTRAN
Under these compilers, ChemSage transparent data-files are opened with
the specifier FORM='BINARY'
.
C Open thermochemical data-file in transparent format for reading C (MS PowerStation, DVF, CVF version) OPEN(10,FILE='cosi.cst', STATUS='OLD', FORM='BINARY' * IOSTAT=NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' ... ENDIF
Note that there is no ACCESS='...'
specifier used.
The data-file is then subsequently read using TQRCST and closed
using CLOSE
(see below).
Unix FORTRAN and other FORTRAN compilers
The ACCESS='TRANSPARENT'
and FORM='BINARY'
specifiers
described above are not standard FORTRAN, so many compilers do not
implement them. This is the case for many, if not all, FORTRAN
compilers on Unix systems, and includes for instance the Gnu g77
FORTRAN compiler on Linux systems. You thus cannot use transparent
data-files with these non-Windows compilers, unless they have been
specially created for use with them. In most cases this is done by
GTT-Technologies.
If you were supplied with such a data-file, open it using
FORM='UNFORMATTED'
, just like a binary data-file:
C Open thermochemical data-file in transparent format for reading C (Version for Unix FORTRAN and other FORTRAN compilers, e.g. g77) OPEN(10, FILE='cosi.cst', STATUS='OLD', FORM='UNFORMATTED', * IOSTAT=NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' ... ENDIF
The data-file is then subsequently read using TQRCST and closed
using CLOSE
(see below).
All FORTRAN compilers: TQOPNT
If you need your FORTRAN programs to compile under various compilers
and/or platforms, and do not need the added flexibility of the generic
FORTRAN OPEN
statement, you avoid any compiler-dependent code by
using the ChemApp subroutine TQOPNT.
C Open thermochemical data-file in transparent format for reading C (Version for all FORTRAN compilers using TQOPNT) CALL TQOPNT('cosi.cst', 10, NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot open data-file.' STOP ENDIF
Again, the syntax introduced above for opening thermochemical data-files in transparent format using TQOPNT is valid for all FORTRAN compilers on all platforms, but it is important to realise that the transparent data-files themselves are usually not fully portable across platforms, and in many case not even among different compilers on the same platform, with the notable exception of the Lahey FORTRAN, Microsoft PowerStation FORTRAN, Digital Visual FORTRAN, and Compaq Visual FORTRAN compilers on Windows platforms.
With the respect to the unit numbers, please see the previous chapter (1.11.2) for explanatory notes, they apply equally to transparent data-files.
The opened transparent data-file can then subsequently be loaded into ChemApp with TQRCST, and closed with TQCLOS:
C Read thermochemical data-file in transparent format CALL TQRCST(NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR loading data-file.' ... ENDIF C Close data-file CALL TQCLOS(10, NOERR) IF (NOERR .NE. 0) THEN WRITE(*,*) 'ERROR: Cannot close data-file.' STOP ENDIF
Note especially that for transparent data-files, TQRCST needs to be used to load the data-file, not TQRFIL or TQRBIN.
ChemApp comes with a set of example data-files. This should enable you to start programming with ChemApp right away, even if you do not already have specific thermochemical data-files for your particular application. Some of the example data-files included in the ChemApp distribution are also used by the example programs which are part of this documentation. Below you find a description of all the example data-files included, together with their potential applications, as well as relevant temperature and composition application ranges.
Please note that this sample data-file is not a comprehensive data-file for the system Co-Cr-Fe. Phases such as FCC and HCP have been omitted to keep it short.
ChemApp Programmer's Manual, Edition 3.6 | © GTT-Technologies, 2003 |