1.4: ChemApp is easy to program

Essentially, only three stages of programming are required to proceed from the initialisation of ChemApp to the collection of results; these are

  1. Initialisation of the interface and reading a thermodynamic data-file.
  2. Setting conditions for the calculation.
  3. Performing the calculation and collecting the results for further use.

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.



1.5: Definition of terms

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.

Components

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:

TQNOSC:
gets the total number of components
TQINSC:
gets the index number for a component
TQGNSC:
gets a component name
TQSTSC:
gets the stoichiometry and molecular mass of a component
TQCSC:
enables substitution of one set of components by another.

Phases

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.

TQNOP:
gets the total number of phases.
TQINP:
gets the index number for a phase
TQGNP:
gets a phase name
TQMODL:
gets the model name for a phase

Constituents

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.

TQNOPC:
gets the total number of constituents of a phase
TQINPC:
gets the index number for a phase constituent
TQGNPC:
gets the name of a phase constituent
TQSTPC:
gets the stoichiometry of a constituent expressed in terms of the (presently defined) components, and its molecular mass
TQPCIS:
checks whether a phase constituent is permitted to be used as incoming species

Sublattices

ChemApp provides a number of subroutines to retrieve information on sublattices and their constituents.

TQNOSL:
gets the number of sublattices of a phase
TQNOLC:
gets the number of sublattice constituents of a sublattice
TQINLC:
gets the index number of a sublattice constituent
TQGNLC:
gets the name of a sublattice constituent
TQGTLC:
gets the calculated equilibrium sublattice site fraction



1.6: Introduction of concepts

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.

1.6.1: Setting initial conditions

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.

1.6.2: Target calculations

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.

1.6.3: One-dimensional phase-mapping

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).



1.7: Installation and use

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.



1.8: Practical aspects

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.

Subroutine arguments

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'.

Error messages

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).



1.9: Language specific notes

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

1.9.1: FORTRAN

  1. Avoid using names of variables, common blocks, subroutines, and functions starting with 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.

  2. All character variables for use with ChemApp which are supposed to hold names of system components, phases, phase constituents should be 24 characters in length.

    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.

1.9.2: C/C++

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

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++:

  1. C/C++ is case-sensitive in contrast to FORTRAN. When calling ChemApp functions, please make sure you use lowercase function names (e.g. use tqini, not TQINI).

  2. There is one ChemApp function which takes an array of strings as input parameter: 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.

  3. Please keep in mind that in C/C++, arrays start with element number 0, whereas in FORTRAN, they normally start with 1. This often needs to be taken into account when arrays are involved in loops which contain ChemApp routines to access a range of index numbers or names of system components, phases, and phase constituents.

  4. As opposed to FORTRAN77 character variables, which are fixed in length and padded with trailing blanks if necessary, strings in C/C++ are null-terminated. The C interface routines delete trailing blanks from strings returned by ChemApp routines and add a null character at the end, before passing them back to the calling C/C++ program. Similarly, they process a C/C++ string passed to ChemApp in order to constitute a proper FORTRAN character variable of the right size before passing it on to the ChemApp subroutines. In order to do this without flaws, please make sure you declare the C string variables and arrays in your C/C++ programs correctly, i.e. giving them the right length. The C example program provided demonstrates several ways how to do this safely.

    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.

  5. On some platforms, a FORTRAN 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.

  6. If you get warnings like "... makes pointer from integer without a cast" when compiling your C/C++ code, check whether you specified the address operator (&) 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.

  7. The ChemApp subroutines 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.

1.9.3: Delphi

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

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:

  1. There is one ChemApp function which takes an array of strings as input parameter: 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.

  2. Every "name" used in conjuction with ChemApp, whether it is the name of a phase, a system component, a phase constituent, or a stream, can be up to 24 characters in length.

    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.

  3. Every integer variable to be used for ChemApp procedure calls needs to be of type 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.

  4. The ChemApp subroutines 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.

1.9.4: Visual Basic

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

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:

  1. Which version of the ChemApp DLL ("Standard", "Extended", or "Light") is to be used when a program is compiled and run is determined using conditional compilation directives. The proper directive (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".

  2. There is one ChemApp function which takes an array of strings as input parameter: 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.

  3. Every "name" used in conjuction with ChemApp, whether it is the name of a phase, a system component, a phase constituent, or a stream, can be up to 24 characters in length.

    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.

  4. Every integer variable that is to be used in an invocation of a ChemApp subroutine has to be of type Long. Similarly, every real variable for use with ChemApp subroutines has to be of type Double.

  5. The ChemApp subroutines 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.



1.10: ChemApp best practices

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.)

Log the ChemApp version number

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.

Make sure you're using the correct version of the ChemApp library

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.

See also: TQSIZE, TQLITE.

Always check the error code every ChemApp subroutine returns

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.

Use ChemApp subroutines to open and close ChemSage data-files

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.

Make sure your ChemSage data-file exists and is loaded correctly

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 you close your data-file

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.

Check the user id of data-files in transparent format

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.

Know your data and don't hard-wire index numbers

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.

Archive your calculation results

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:

Make use of ChemSage result tables

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.

Keep a watchful eye on your incoming amounts

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.

Make sure you know which system units 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.

Facilitate debugging

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:

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).



1.11: Thermodynamic data

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.

1.11.1: User-defined solution models

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:

  1. The user-defined solution model needs to be coded in Fortran and added to the skeleton subroutines USERGP, USERGX, and USERGG which are supplied together with the special version of ChemApp.

  2. In the second stage, this user code is compiled and either linked statically to the application program together with ChemApp, or made available as a DLL.

  3. The solution data need to be added to a thermochemical data-file. The input of such data is usually easiest using the Input from Keyboard function of ChemSage.

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

1.11.2: ASCII data-files

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

Using ASCII data-files (all programming languages)

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.

Using ASCII data-files (FORTRAN programs)

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.

1.11.3: Binary data-files

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.

Using binary data-files (all programming languages)

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.

Using binary data-files (FORTRAN programs)

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.

1.11.4: Transparent 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.

Using transparent data-files (all programming languages)

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.

Using transparent data-files (FORTRAN programs)

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.



1.12: Example thermochemical data-files

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.

1.12.1: COSI.DAT (System C-O-Si)

Chemical system:
C-O-Si

Potential applications:
Phase equilibria and thermodynamic properties, for instance relating to Si production in a Si-arc furnace.

Temperature range:
RT - 3500K

Composition range:
All

Comments:
COSI.DAT is the file most widely used for the code examples in this manual. It contains a gaseous mixture phase and several pure stoichiometric phases.

View directory of data-file

View data-file

1.12.2: CNO.DAT (System C-N-O)

Chemical system:
C-N-O

Potential applications:
Combustion equilibria and thermodynamic properties of the gas species and condensed phases.

Temperature range:
All

Composition range:
All

Comments:
This data-file contains 28 gas constituents as well as solid carbon and diamond.

View directory of data-file

View data-file

1.12.3: FEC.DAT (System Fe-C)

Chemical system:
Fe-C

Potential applications:
Phase equilibria; phase diagram, also metastable with cementite; thermodynamic properties of the phases and their constituents.

Temperature range:
RT - 2500K

Composition range:
All

Comments:
See comment section at the end of the data-file (Appendix H.3)

View directory of data-file

View data-file

1.12.4: FEMGSIO4.DAT (System Fe2SiO4-Mg2SiO4)

Chemical system:
System Fe2SiO4-Mg2SiO4

Potential applications:
Solid T-P-composition equilibria and thermal properties in the system Fe2SiO4-Mg2SiO4 for pressures between 1 bar and 300 kbar.

Temperature range:
Below liquidus

Composition range:
All

Comments:
This data-file contains pressure-dependent Gibbs energy terms.

View directory of data-file

View data-file

1.12.5: PBSN.DAT (System Pb-Sn)

Chemical system:
Pb-Sn

Potential applications:
Phase equilibria and all thermodynamic properties in the binary system Pb-Sn.

Temperature range:
RT - 1500 K

Composition range:
All

Comments:
This data-file can be used to calculate the Pb-Sn binary phase diagram, as it is valid over the whole composition range and contains the descriptions of all necessary condensed phases. Due to the inherent metastable miscibility gap, the BCT_A5 phase (Sn-terminal solution) is present twice.

View directory of data-file

View data-file

1.12.6: PITZER.DAT (System Na-Cl-C-O-H)

Chemical system:
Na-Cl-C-O-H

Potential applications:
Chemical equilibria in natural waters with sodium.

Temperature range:
298.15 K

Composition range:
Aqueous solutions with up to 10 molal dissolved salts.

Comments:
This data-file contains an aqueous phase modelled according to the Pitzer formalism. It contains charged species in the aqueous phase, which is the reason why this data-file actually has a sixth system component, the electron.

View directory of data-file

View data-file

1.12.7: SUBL-EX.DAT (System Co-Cr-Fe)

Chemical system:
Co-Cr-Fe (incomplete)

Potential applications:
SIGMA-BCC equilibria

Temperature range:
900 - 1200 K

Composition range:
Iron-rich or chromium-rich.

Comments:
This file serves as an example of input for substitutional solutions (BCC) described with the RKMP model (see Table 2) and for a multi-sublattice phase (SIGMA) with three sublattices and 30 atoms of the unit cell.

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.

View directory of data-file

View data-file


ChemApp Programmer's Manual, Edition 3.6 © GTT-Technologies, 2003