1.1   About this manual

Before starting to work with this manual, make sure the version of ChemApp you have matches the version of this documentation. This manual describes the use of ChemApp versions 2.0.2 through 5.0.2. If you are in doubt whether this is the right one in your case, please contact GTT-Technologies.

This documentation describes the regular, commercial version of ChemApp. A manual for our restricted, free version of ChemApp, called ChemApp light, is also available. This is referenced in About ChemApp and ChemApp light.

The next sections of the first chapter (ChemApp is easy to program to Language specific notes) deal mainly with the definition of terms, the introduction into concepts which are important to understand when using ChemApp, and some practical aspects in using the ChemApp library, including language-specific notes.

Section ChemApp best practices, is recommended reading for everbody who is looking at implementing anything but the simplest projects with ChemApp. It lists a number of very important programming issues to consider, which should be implemented as early in the stage of a ChemApp project as possible. If you encounter problems in your ChemApp programs and would like to contact GTT-Technologies' support, please make sure your code implements all of the "best pratices" outlined in this chapter before you send your code to GTT-Technologies' support.

The last parts of this chapter (Thermodynamic data and Example thermochemical data-files) describe which thermochemical data can be used with ChemApp and introduce the various example data-files that are supplied with ChemApp.

The actual ChemApp subroutines are described in Initialising the Interface and Reading a Data-file through Data Manipulation Subroutines, along with several dozen code examples in both FORTRAN and C, demonstrating their use.

A list of ChemApp error messages and their associated numbers is given in List of Error Messages.

Some advanced topics are discussed in the chapter Advanced topics. While the issues mentioned might not be vital for ChemApp programmers taking their first steps, anybody who is seriously interested in application programming using ChemApp should not omit reading it.

The chapter Worked examples presents a list of worked examples. Each example focuses on a different aspect of ChemApp and provides a good way to learn how ChemApp is used to solve a thermochemical problem.

Thermodynamic data and the handling of thermochemical data-files are treated in Thermodynamic Data - Sources and Quality Considerations and Thermochemical Data-files - Structure and Handling.

The next two sections contain the documented source as both FORTRAN (FORTRAN example code (cademo1.f)) and C (C example code (cademo1.c)) codes of a ChemApp example program which demonstrates the use of practically every ChemApp subroutine.

Finally, the chapter Example data-files and their contents lists the contents of all example data-files supplied with ChemApp, the section Revision history provides a revision history of this manual, and Alphabetical list of ChemApp subroutines contains a useful alphabetical reference of all ChemApp subroutines, to which the literature references (Bibliography) are added.

1.2   Code examples

This manual contains several dozen code examples to illustrate the use of the ChemApp subroutines and to support the method of learning-by-changing. Virtually all example codes are part of the distribution of the online manual, and you should feel encouraged to take these examples and start changing and editing them to take your own steps in programming with ChemApp. After receiving your distribution of ChemApp, it is reommended though to first run the program CADEMO1 and compare the results it produces on your computer with the master results which are normally included in the distribution. If you are using a FORTRAN or C distribution of ChemApp, you might also want to have a look at FORTRAN example code (cademo1.f) and C example code (cademo1.c) for that purpose.

The code examples have been designed to be both concise and easy to understand in terms of the ChemApp features involved. In terms of the application language used (FORTRAN and C), they require only basic knowledge. To keep these code examples short and easy to read, error handling has usually been neglected. In your own ChemApp programs, you should as early as possible adopt the policy to check the value of the error variable that every ChemApp subroutine returns.

The code examples used throughout this manual and the results they produce are not simply copied and pasted into the document. When the manual is produced, each code example is automatically compiled, linked to ChemApp, run, and checked for runtime errors reported by ChemApp. Only if no error occurred the code is mixed with the output produced during runtime, syntax-highlighted, and included into the manual. This guarantees that all example programs compile and run without problems with the ChemApp version that has been used to produce the manual. For the production of this edition of the manual Version 6.4.0 of ChemApp was used.

1.3   About ChemApp and ChemApp light

This is the documentation of the regular version of ChemApp. The use of your copy of ChemApp and its documentation is governed by the license agreement which you received with the object code, and which needs to be signed and returned to GTT-Technologies before you are permitted to start working with ChemApp.

A similar version of this documentation is also available for ChemApp light. This is a restricted version of ChemApp, which is distributed free of charge through GTT's Technical Thermochemistry Web Page.

One of the major reasons to produce ChemApp light was to provide potential users with an easy way to find out whether ChemApp can be linked to their own or third-party software. If you would like to introduce ChemApp to others, please refer them to ChemApp light, which can be downloaded from our web page.

If you have any questions regarding ChemApp, ChemApp light, this documentation, the code examples, or the example data-files, feel free to contact GTT-Technologies.

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 SiO₂ 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 Thermochemical Data-files - Structure and Handling). 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 Mg₂Si 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.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 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 Language specific notes). 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 FORTRAN example code (cademo1.f) and C example code (cademo1.c)).

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 Data types used in ChemApp.

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 are 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 ChemApp data-files

Whenever possible, use ChemApp subroutines to open and close ChemApp data-files.

By selecting the proper ChemApp subroutine to open your ChemApp 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 ChemApp data-file exists and is loaded correctly

It is especially important to check the error variable when opening and reading ChemApp 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 do not 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 Print data-file contents 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:

• The results of your calculations, of course.
• All source code of your program (don't forget to include auxiliary files like Makefile, configuraton files, or other instructions on how to build the program).
• An executable version of your program. If you have both static and shared libraries/DLLs of ChemApp available, compile a statically linked version of your program.
• The thermochemical data-files used.
• The ChemApp library itself, especially when you're using ChemApp as a DLL or shared library.

Make use of ChemSage/ChemApp 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/ChemApp 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/ChemApp 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:

• When your code is iterative, or contains a number of equilibrium calculations that are connected (i.e. incoming conditions for one equilibrium calculation are based on the results of an earlier one).
• When your code is part of another program, and the incoming conditions are supplied at run-time by other parts of the program, or are read from a file.

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:

• If "DEBUGMODE" has been activated, it directs output to a dedicated log file (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).
• It calls TQSHOW to log all current conditions (incoming amounts, pressure, temperature, etc.) to ErrorLog.
• It closes and reopens 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.
• Only then is TQCEL called, which stores its output also to ErrorLog.
• If ChemApp has no problems calculating the equilibrium, the 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.
• If necessary (e.g. if other parts of your code depend on "ERROR" and "LIST" output being stored elsewhere), call TQCIO to restore the output destinations to their original values.

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. Customised data-files can also be prepared to meet a user's specific requirements.

The data-files for ChemApp come in a number of forms: ASCII, transparent, and binary (the latter now being deprecated). 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 (ASCII data-files, Binary data-files (DEPRECATED), and Transparent data-files).

A data-file contains the following information:

• Components

  • names of the default set
  • molecular masses of the default set

• Phases

  • names
  • list of constituents (one constituent in fixed composition phases)
  • solution model parameters
  • default status

• Constituents

  • names
  • stoichiometries with respect to the default system components
  • thermochemical data
  • default status.

ChemApp can only read data stored in data-files in the various ChemApp formats (ASCII data-files, Binary data-files (DEPRECATED), and Transparent data-files). Data stored in a database or a database file must be read with a database management system (usually FactSage) which in turn produces ChemApp data-files.

Once the thermochemical data was loaded from the data-file, it is not possible to add phases or phase constituents to the chemical system. It is however possible to modify the thermochemical data, provided that the data-file loaded is in ASCII format (see Data Manipulation Subroutines). Also, the default system components, as well as the default status of phases and constituents may be changed (see Handling System Data in ChemApp), independent of the data-file format.

More information on the structure and handling of thermochemical data-files can be obtained from Thermochemical Data-files - Structure and Handling.

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 List of available solution models in ChemApp. 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.

C Open thermochemical data-file in ASCII format for reading
          CALL TQOPNA('cosi.dat', 10, NOERR)

C Read thermochemical data-file in ASCII format
          CALL TQRFIL(NOERR)

C Close data-file
          CALL TQCLOS(10, NOERR)

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

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)

C Open thermochemical data-file in binary format for reading
          CALL TQOPNB('cosi.bin', 10, NOERR)

C Read thermochemical data-file in binary format
          CALL TQRBIN(NOERR)

C Close data-file
          CALL TQCLOS(10, NOERR)

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

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)

C Open thermochemical data-file in transparent format for reading
          CALL TQOPNT('cosi.cst', 10, NOERR)

C Read thermochemical data-file in transparent format
          CALL TQRCST(NOERR)

C Close data-file
          CALL TQCLOS(10, NOERR)

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

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

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

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

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.

2.1   TQINI

INITIALISE-INTERFACE

Use TQINI to initialise ChemApp.

Synopsis

FORTRAN:

CALL TQINI(NOERR)

C:

tqini(&noerr);

Pascal:

tqini(noerr);

Basic:

Call tqini(noerr)

TQINI must be called before any other ChemApp subroutine, or whenever you wish to reinstate the complete set of default values and units (see Table 4), and read a thermodynamic data-file.

See also

TQREMC

! The shortest possible (but very useless) ChemApp program
      PROGRAM CAF1
      IMPLICIT NONE

      INTEGER NOERR

! Initialise ChemApp
      CALL TQINI(NOERR)

      END

/* Program cac1 */
/* The shortest possible (but very useless) ChemApp program */

#include "cacint.h"

int main()
{
  LI noerr;

  /* Initialise ChemApp */
  tqini(&noerr);

  return 0;

}

2.2   TQCPRT

GET-COPYRIGHT-MESSAGE

Use TQCPRT to get the copyright message for ChemApp

Added for ChemApp version 1.1.3

Synopsis

FORTRAN:

CALL TQCPRT(NOERR)

C:

tqcprt(&noerr);

Pascal:

tqcprt(noerr);

Basic:

Call tqcprt(noerr)

TQCPRT provides the programmer with a copyright message for inclusion in application programs utilising ChemApp. The message itself is retrieved like an error message, with a subsequent call to TQERR.

See also

TQERR

! Retrieving and displaying the ChemApp copyright notice
      PROGRAM CAF2
      IMPLICIT NONE

      INTEGER NOERR
      CHARACTER MESS(3)*80

! Initialise ChemApp
      CALL TQINI(NOERR)

! Retrieve the copyright string with TQCPRT
      CALL TQCPRT(NOERR)

! Then call tqerr to retrieve it
      CALL TQERR(MESS,NOERR)

! To print out the message, print all three strings of MESS :
      WRITE(UNIT=*,FMT='(3(A,/))') MESS(1), MESS(2), MESS(3)


      END

This program contains ChemApp
Copyright GTT-Technologies, Kaiserstrasse 100, D-52134 Herzogenrath, Germany
http://www.gtt-technologies.de

/* Program cac2 */
/* Retrieving and displaying the ChemApp copyright notice */

#include "cacint.h"

int main()
{
  LI noerr;
  int i;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Retrieve the copyright string with tqcprt */
  tqcprt(&noerr);

  /* Then call tqerr to retrieve it. The variable TQERRMSG is declared in
     cacint.c as TQERRMSG[3][80] for this purpose:*/
  tqerr((CHP)TQERRMSG,&noerr);
  /* Note that an explicit typecast has been used in the above call to
     tqerr to avoid potential compiler warnings about TQERRMSG being
     an incompatible pointer type */

  /* To print out the message, loop over the three strings of
     TQERRMSG: */
  for(i=0;i<3;i++)
    printf("%s\n",TQERRMSG[i]);


  return 0;

}

This program contains ChemApp
Copyright GTT-Technologies, Kaiserstrasse 100, D-52134 Herzogenrath, Germany
http://www.gtt-technologies.de

2.3   TQVERS

GET-VERSION-NUMBER

Use TQVERS to get the version number of ChemApp

Added for ChemApp version 1.1.3

Synopsis

FORTRAN:

CALL TQVERS(NVERS,NOERR)

C:

tqvers(&nvers,&noerr);

Pascal:

tqvers(nvers,noerr);

Basic:

Call tqvers(nvers,noerr)

NVERS is returned as an integer value, e.g. 213 for version 2.1.3 of ChemApp.

! Display the version number of ChemApp
      PROGRAM CAF3
      IMPLICIT NONE

      INTEGER NOERR, NVERS

! Initialise ChemApp
      CALL TQINI(NOERR)

! Get version number of ChemApp
      CALL TQVERS(NVERS,NOERR)

      WRITE(UNIT=*,FMT='(A,I4)') 'This program has been compiled '//
     *     'with ChemApp version ', NVERS


      END

This program has been compiled with ChemApp version  645

/* Program cac3 */
/* Display the version number of ChemApp */

#include "cacint.h"

int main()
{
  LI noerr, version;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Get version number of ChemApp*/
  tqvers(&version,&noerr);

  printf("This program has been compiled "
        "with ChemApp version %li\n", version);


  return 0;

}

This program has been compiled with ChemApp version 645

2.4   TQLITE

CHECK-IF-CHEMAPP-LIGHT

Use TQLITE to check whether the type of ChemApp currently used is ChemApp light.

Added for ChemApp version 2.0.1

Synopsis

FORTRAN:

CALL TQLITE(ISLITE,NOERR)

C:

tqlite(&islite,&noerr);

Pascal:

tqlite(islite,noerr);

Basic:

Call tqlite(islite,noerr)

TQLITE can be used to distinguish between the regular version of the ChemApp library, and ChemApp light.

ChemApp and ChemApp light differ in a couple of ways (see About ChemApp and ChemApp light). If TQLITE returns a 0 through ISLITE, the regular version of ChemApp is linked to the calling program. If a 1 is returned, ChemApp light is used.

The code examples of the manual make use of this subroutine primarily to determine whether target calculations can be performed.

! Testing for the presence of ChemApp "light"

      PROGRAM CAF23
      IMPLICIT NONE

      INTEGER NOERR, ISLITE

! Initialise ChemApp
      CALL TQINI(NOERR)

 20   FORMAT(1X,A)

! Find out whether we are working with the regular or the "light"
! version
      CALL TQLITE(ISLITE, NOERR)
      WRITE(*,FMT=20)
     *     'This application program has been linked against'
      IF (ISLITE .EQ. 1) THEN
         WRITE(*,FMT=20)
     *        'ChemApp "light".'
      ELSE
         WRITE(*,FMT=20)
     *        'the regular version of ChemApp.'
      ENDIF


      END

This application program has been linked against
the regular version of ChemApp.

/* Program cac23 */
/* Testing for the presence of ChemApp "light" */

#include "cacint.h"

int main()
{
  LI noerr, islite;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Find out whether we are working with the regular or the "light"
     version */
  tqlite(&islite, &noerr);
  printf("This application program has been linked against\n");
  if (islite)
    printf("ChemApp \"light\".\n");
  else
    printf("the regular version of ChemApp.\n");


  return 0;
}

This application program has been linked against
the regular version of ChemApp.

2.5   TQGTID

GET-USER-ID

Use TQGTID to get the user ID of the license holder of the ChemApp library.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQGTID(ID,NOERR)

C:

tqgtid(id,&noerr);

Pascal:

tqgtid(id,noerr);

Basic:

Call tqgtid(id,noerr)

TQGTID returns the user ID of the license holder of ChemApp.

Note that the user ID which is returned can be up to 255 characters long, the variable ID should thus be declared large enough to hold a character string of this length.

See also

TQGTNM , TQGTPI

! Retrieving and displaying the user ID and the name of the ChemApp
! license holder, the program ID, HASP dongle information, plus the
! expiration date of the ChemApp license.

! If the ChemApp version used requires a HASP dongle, and the ChemApp
! license is expired, or about to expire, and is to be extended, the
! information printed by this program is needed by GTT-Technologies to
! update the dongle.

! The support function STRLEN returns the total number of characters in
! a string, not counting trailing blanks
      INTEGER FUNCTION STRLEN(INSTR)
      CHARACTER INSTR*(*)

      STRLEN = LEN(INSTR)
      DO WHILE(INSTR(STRLEN:STRLEN) .EQ. ' ')
         STRLEN = STRLEN - 1
         IF (STRLEN .EQ. 1) RETURN
      ENDDO
      RETURN
      END


      PROGRAM CAF30
      IMPLICIT NONE

      INTEGER NOERR, STRLEN, HASPID, EDMON, EDYEAR
      CHARACTER ID*255, NAME*80, PID*24, HASPT*5

! Initialise ChemApp
      CALL TQINI(NOERR)

! Retrieve the licensee's user ID
      CALL TQGTID(ID,NOERR)

! Retrieve the licensee's name
      CALL TQGTNM(NAME,NOERR)

! Retrieve the program ID
      CALL TQGTPI(PID,NOERR)

! Print all three
      WRITE(UNIT=*,FMT=*) 'Licensee''s user ID: ', ID(1:STRLEN(ID))
      WRITE(UNIT=*,FMT=*) 'Licensee''s name   : ', NAME(1:STRLEN(NAME))
      WRITE(UNIT=*,FMT=*) 'Program ID        : ', PID(1:STRLEN(PID))


! The following pieces of information are only meaningful if a version
! of ChemApp is used that requires a dongle (hardware key).
! Get the HASP dongle type and id
      CALL TQGTHI(HASPT, HASPID, NOERR)

! Get the ChemApp license expiration date (month and year)
      CALL TQGTED(EDMON, EDYEAR, NOERR)

! Print info if HASP dongle is used:
      IF (HASPID .NE. 0) THEN
        WRITE(UNIT=*,FMT=*) 'HASP dongle type : ' //
     *       HASPT(1:STRLEN(HASPT))
        WRITE(UNIT=*,FMT=*) 'HASP dongle id   : ', HASPID

        WRITE(UNIT=*,FMT=*) 'ChemApp license expiration date ' //
     *       '(month/year): ', EDMON, '/', EDYEAR
      ELSE
        WRITE(UNIT=*,FMT=*) 'This ChemApp version does not ' //
     *        'require a HASP hardware key (dongle)'
      ENDIF


      END

Licensee's user ID: 5001
Licensee's name   : GTT - Technologies
Program ID        : CAFU
This ChemApp version does not require a HASP hardware key (dongle)

/* Program cac30 */
/* Retrieving and displaying the user ID and the name of the ChemApp
   license holder, as well as the program ID */

/* If the ChemApp version used requires a HASP dongle, and the ChemApp
   license is expired, or about to expire, and is to be extended, the
   information printed by this program is needed by GTT-Technologies
   to update the dongle. */

#include "cacint.h"

int main()
{
  LI noerr, haspid, edmon, edyear;

  char id[255], name[80], pid[TQSTRLEN], haspt[TQSTRLEN];

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Retrieve the licensee's user ID */
  tqgtid(id, &noerr);

  /* Retrieve the licensee's name */
  tqgtnm(name, &noerr);

  /* Retrieve the program ID */
  tqgtpi(pid, &noerr);

  /* Print all three */
  printf("Licensee's user ID: %s\n", id);
  printf("Licensee's name   : %s\n", name);
  printf("Program ID        : %s\n", pid);


  /* The following pieces of information are only meaningful if a
      version of ChemApp is used that requires a dongle (hardware
      key).  Get the HASP dongle type and id */
  tqgthi(haspt, &haspid, &noerr);

  /* Get the ChemApp license expiration date (month and year) */
  tqgted(&edmon, &edyear, &noerr);

  /* Print info if HASP dongle is used: */
  if (haspid) {
    printf("HASP dongle type : %s\n", haspt);
    printf("HASP dongle id   : %li\n", haspid);
    printf("ChemApp license expiration date (month/year): %li/%li\n",
          edmon, edyear);
  } else {
    printf("This ChemApp version does not require a "
          "HASP hardware key (dongle)\n");
  }


  return 0;

}

Licensee's user ID: 5001
Licensee's name   : GTT - Technologies
Program ID        : CAFU
This ChemApp version does not require a HASP hardware key (dongle)

2.6   TQGTNM

GET-USER-NAME

Use TQGTNM to get the name of the license holder of the ChemApp library.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQGTNM(NAME,NOERR)

C:

tqgtnm(name,&noerr);

Pascal:

tqgtnm(name,noerr);

Basic:

Call tqgtnm(name,noerr)

TQGTNM returns the name of the license holder of ChemApp.

Note that the name which is returned can be up to 80 characters long, the variable NAME should thus be declared large enough to hold a character string of this length.

See also

TQGTID, TQGTPI

See

TQGTID

2.7   TQGTPI

GET-PROGRAM-ID

Use TQGTPI to get the ID of the program.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQGTPI(NAME,NOERR)

C:

tqgtpi(name,&noerr);

Pascal:

tqgtpi(name,noerr);

Basic:

Call tqgtpi(name,noerr)

TQGTPI returns the ID of the program. Every program that is able to read ChemApp transparent data-files is identified with a 4-letter mnemonic ID that is retrieved using TQGTPI. In case of a program that is linked against the full version of ChemApp, the program ID would be CAFU, if it is linked against ChemApp light instead, the program ID is CALI.

See also

TQGTID, TQGTNM

See

TQGTID

2.8   TQGTHI

GET-HASP-INFO

Use TQGTHI to get the HASP dongle type and id.

Added for ChemApp version 4.1.4

Synopsis

FORTRAN:

CALL TQGTHI(HASPT,HASPID,NOERR)

C:

tqgthi(haspt,&haspid,&noerr);

Pascal:

tqgthi(haspt,haspid,noerr);

Basic:

Call tqgthi(haspt,haspid,noerr)

If a version of ChemApp is used that requires a dongle (HASP hardware key), the dongle contains the necessary licensing information. In this case, TQGTHI can be used to retrieve information on the dongle type and the dongle id. This information, together with the information retrieved by TQGTED, TQGTPI, TQGTNM,and TQGTID is necessary if GTT-Technologies is contacted regarding an update of the license.

See also

TQGTED

See

TQGTID

2.9   TQGTED

GET-EXPIRATION-DATE

Use TQGTED to get the expiration date of the ChemApp license.

Added for ChemApp version 4.1.4

Synopsis

FORTRAN:

CALL TQGTED(EDMON,EDYEAR,NOERR)

C:

tqgted(&edmon,&edyear,&noerr);

Pascal:

tqgted(edmon,edyear,noerr);

Basic:

Call tqgted(edmon,edyear,noerr)

If a version of ChemApp is used that requires a dongle (HASP hardware key), the dongle contains the necessary licensing information. In this case, TQGTED can be used to retrieve the expiration date of the ChemApp license. This information, together with the information retrieved by TQGTHI, TQGTPI, TQGTNM,and TQGTID is necessary if GTT-Technologies is contacted regarding an update of the license.

In case the ChemApp version used does not require a dongle, or if ChemApp is used under a perpetual license, a default date of 12/2025 (December 2025) or later is used.

See also

TQGTHI

See

TQGTID

2.10   TQCONF

SET-CONFIGURATION-OPTION

Use TQCONF to set a configuration option.

Added for ChemApp version 6.3.4

Synopsis

FORTRAN:

CALL TQCONF(OPTION,VALUEA,VALUEB,VALUEC,NOERR)

C:

tqconf(option,valuea,valueb,valuec,&noerr);

Pascal:

tqconf(option,valuea,valueb,valuec,noerr);

Basic:

Call tqconf(option,valuea,valueb,valuec,noerr)

TQCONF is used to set configuration options, the following options are currently available (for details please see Table TQCONF option):

Semi-automatic charge balance correction (option E)

In iterative calculations, where the input to an equilibrium calculation is based on the output of a previous equilibrium calculation, electroneutrality in phases with phase-internal electrons might not be given. A typical reason for this are rounding errors.

When global conditions are used (see Setting initial conditions), this is not difficult to fix, since the amount of system components, and thus also the amounts of the electron(s), can be directly set with TQSETC. When streams are used, this is not as easily done, for this reason the option of a semi-automatic charge balance correction was included.

Calling TQCONF with the option E instructs ChemApp to set the amount of electrons before every subsequent equilibrium calculation to zero. This can be done either on a per-electron basis by referencing them using their system component index number, or for all electrons by passing a zero for the system component index number (see Table TQCONF option).

Note that the prerequisite for semi-automatic charge balance correction is that the electron(s) in question explicitely appear as system components in the data-file.

Calling TQREMC with a value of -1 or -2 removes any configuration option set previously.

! Using TQCONF to set up semi-automatic charge balance correction

      PROGRAM CAF34
      IMPLICIT NONE

      INTEGER NOERR, IAQU, IGAS, IPC, IEA
      DOUBLE PRECISION TPAQU(2), VALS(2)


! Initialise ChemApp
      CALL TQINI(NOERR)

! Open data-file for reading
      CALL TQOPNA('water.dat', 10, NOERR)

! Read data-file
      CALL TQRFIL(NOERR)

! Close data-file
      CALL TQCLOS(10, NOERR)

! Set temperature and pressure units
      CALL TQCSU('T ', 'C ', NOERR)
      CALL TQCSU('p ', 'atm ', NOERR)

! Define an input stream 'STREAM_AQUEOUS' at 25 C and 1 atm
      TPAQU(1) = 25.D0
      TPAQU(2) = 1.D0
      CALL TQSTTP('STREAM_AQUEOUS', TPAQU, NOERR)

! Define content of this stream: 1 liter (55.508 mole) of water
      CALL TQINP('aqueous ', IAQU, NOERR)
      CALL TQINPC('H2O_liquid ', IAQU, IPC, NOERR)
      CALL TQSTCA('STREAM_AQUEOUS ', IAQU, IPC, 55.508D0, NOERR)

! Set temperature and total pressure to 25 C and 1 atm
      CALL TQSTEC('P ', 0, 1.D0, NOERR)
      CALL TQSTEC('T ', 0, 105.D0, NOERR)

! Perform a formation phase target calculation with the gas phase as
! the target phase. Note that the gas phase is always the phase with
! index number 1, irrespective of whether it is called 'GAS',
! 'gas_ideal', or, as in this case, 'gas_real'
      CALL TQSTEC('A ', 1, 0.D0, NOERR)

! Display what we have set so far
      CALL TQSHOW(NOERR)

SYSTEM UNITS:
Pressure     : atm
Volume       : dm3
Temperature  : C
Energy       : J
Amount       : mol

T =  105.00000000 C
P = 1 atm

STREAM NAME             STREAM NUMBER   TEMPERATURE/C   PRESSURE/atm
STREAM_AQUEOUS
                              1              25.00       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       H2O_liquid/aqueous/
              AMOUNT/mol    =  5.55080000000000E+01

INACTIVE ELECTRON CONSTRAINT

FORMATION TARGET PHASE: gas_real
EQUILIBRIUM AMOUNT/mol = 0.0000E+00

! In the above output, note the line 'INACTIVE ELECTRON
! CONSTRAINT', i.e. no charge balance correction by default.

! Calculate the equilibrium, specifying temperature as the target
! variable
      CALL TQCEL('T ', 0, 0, VALS, NOERR)

*T = 100.00 C
P = 1 atm
V = 0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        0.0000E+00     1.0000E+00     9.8754E-01
H2                         0.0000E+00     1.1802E-21     1.1950E-21
O2                         0.0000E+00     6.1055E-22     6.1591E-22
OH                         0.0000E+00     2.0291E-26     2.0038E-26
HOOH                       0.0000E+00     3.4804E-29     3.4371E-29
HOO                        0.0000E+00     7.4430E-35     7.3502E-35
H                          0.0000E+00     4.0975E-39     4.0464E-39
O                          0.0000E+00     3.8151E-43     3.7675E-43
O3                         0.0000E+00     4.1347E-56     4.1475E-56
TOTAL:                     0.0000E+00     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 5.5508E+01     5.5508E+01     1.0000E+00
H[+]                       7.3345E-07     7.3346E-07     7.3346E-07
H2                         1.0812E-24     1.0812E-24     1.0812E-24
O2                         5.2886E-25     5.2886E-25     5.2886E-25
OH[-]                      7.3345E-07     7.3346E-07     7.3346E-07
HO2[-]                     4.4778E-31     4.4778E-31     4.4778E-31
HOOH                       2.3471E-26     2.3471E-26     2.3471E-26
TOTAL:                     5.5508E+01                    1.0000E+00
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    4.0025E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 3.43097E+01   3.14178E+05   9.39802E+02  -3.27709E+05   0.00000E+00

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 4.21825E+03  -1.55517E+07   4.82259E+03  -1.73512E+07   0.00000E+00

Properties for aqueous:
pH = 6.1346
Eh/V = 0.32014
Total solute molality = 1.4669E-06
Ionic strength = 7.3346E-07
Osmotic coefficient = 1

Mole fraction of system components:
             gas_real     aqueous
O            0.33333      0.33333
H            0.66667      0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

! As seen in the previous table, the gas phase over pure water reaches
! a pressure of 1 atm at 100 degrees Celsius. The gas phase amount is
! still zero, as this is the condition for a standard formation phase
! target calculation: the activity (or, in case of a gas phase, the
! fugacity) of the target phase is unity, the phase amount is
! zero. Just like any other phase, a gas phase with an
! activity/fugacity less then unity is not considered stable and thus
! does not have a positive amount.

! Set the equilibrium temperature to 105 degrees Celsius
      CALL TQSTEC('T ', 0, 105.D0, NOERR)

! Calculate the equilibrium
      CALL TQCEL(' ', 0, 0, VALS, NOERR)

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
H2                         1.3219E-19     2.3814E-21     2.4098E-21
O2                         6.6093E-20     1.1907E-21     1.2005E-21
OH                         2.6353E-24     4.7476E-26     4.6918E-26
HOOH                       4.2286E-27     7.6180E-29     7.5284E-29
HOO                        1.1498E-32     2.0714E-34     2.0470E-34
H                          8.1923E-37     1.4759E-38     1.4585E-38
O                          8.5669E-41     1.5434E-42     1.5252E-42
O3                         1.1464E-53     2.0654E-55     2.0713E-55
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 0.0000E+00     5.5508E+01     8.4106E-01
H[+]                       0.0000E+00     8.7350E-07     7.3467E-07
H2                         0.0000E+00     2.6604E-24     2.2376E-24
O2                         0.0000E+00     1.2340E-24     1.0378E-24
OH[-]                      0.0000E+00     8.7350E-07     7.3467E-07
HO2[-]                     0.0000E+00     9.2402E-31     7.7716E-31
HOOH                       0.0000E+00     4.5929E-26     3.8629E-26
TOTAL:                     0.0000E+00                    8.4106E-01
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Mole fraction of system components:
             gas_real
O            0.33333
H            0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

! At 5 degrees above the boiling point of water at standard
! conditions, only the gas phase is stable.

! Artificially add an excess amount of OH[-] to the water, this will
! make it impossible for ChemApp to satisfy the electroneutrality
! condition. Note that this is an effect that might occur due to
! rounding errors in iterative calculations.
      CALL TQINPC('OH[-] ', IAQU, IPC, NOERR)
      CALL TQSTCA('STREAM_AQUEOUS ', IAQU, IPC, 1.D-7, NOERR)


! Calculate the equilibrium
      CALL TQCEL(' ', 0, 0, VALS, NOERR)

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1
OH[-]/aqueous/             1.0000E-07        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
H2                         1.3219E-19     2.3814E-21     2.4098E-21
O2                         6.6093E-20     1.1907E-21     1.2005E-21
OH                         2.6353E-24     4.7476E-26     4.6918E-26
HOOH                       4.2286E-27     7.6180E-29     7.5284E-29
HOO                        1.1498E-32     2.0714E-34     2.0470E-34
H                          8.1923E-37     1.4759E-38     1.4585E-38
O                          8.5669E-41     1.5434E-42     1.5252E-42
O3                         1.1464E-53     2.0654E-55     2.0713E-55
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 5.7773E-07     5.5508E+01     8.4106E-01
H[+]                       5.8467E-22     5.6175E-14     5.6175E-14
H2                         2.3289E-32     2.2376E-24     2.2376E-24
O2                         1.0802E-32     1.0378E-24     1.0378E-24
OH[-]                      1.0000E-07     9.6080E+00     9.6080E+00
HO2[-]                     1.0578E-31     1.0164E-23     1.0164E-23
HOOH                       4.0205E-34     3.8629E-26     3.8629E-26
TOTAL:                     6.7773E-07                    1.0000E+00
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Properties for aqueous:
pH = 13.250
Eh/V =-0.22092
Total solute molality = 9.6080
Ionic strength = 4.8040
Osmotic coefficient = 1

Mole fraction of system components:
             gas_real     aqueous
O            0.33333      0.33333
H            0.66667      0.61748
EA           0            4.9184E-02

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

! The results from the equilibrium calculation now show that liquid
! water is stable, which is definitely incorrect at 105 C. Due to the
! artificially introduced excess amount of OH[-], the Gibbs energy
! minimizer has no choice but to add the water phase to the set of
! stable phases, otherwise the mass balance cannot be satisfied.  Note
! also that the excess electrons ('EA') are documented in the table
! "Mole fraction of system components" at the bottom of the output
! above.

! ChemApp can resolve such cases semi-automatically, if it is
! instructed via the subroutine TQCONF to apply a charge balance
! correction.

! OPTION 1: Configure ChemApp to perform semi-automatic charge balance
! correction for one electron spcifically:
!
! Get the system component index number for the aqueous electron
! 'EA'
      CALL TQINSC('EA ', IEA, NOERR)

! Configure ChemApp to perform semi-automatic charge balance
! correction for this electron
      CALL TQCONF('E ', IEA, 0, 0, NOERR)


! OPTION 2: Configure ChemApp to perform semi-automatic charge balance
! correction for *all* electrons:
!
! ChemApp can easily be configured to perform the charge balance
! correction for all electrons, in case the data-file contains more
! than one phase-internal electron.
      CALL TQCONF('E ', 0, 0, 0, NOERR)

! Display what we have set so far
      CALL TQSHOW(NOERR)

SYSTEM UNITS:
Pressure     : atm
Volume       : dm3
Temperature  : C
Energy       : J
Amount       : mol

T =  105.00000000 C
P = 1 atm

STREAM NAME             STREAM NUMBER   TEMPERATURE/C   PRESSURE/atm
STREAM_AQUEOUS
                              1              25.00       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       H2O_liquid/aqueous/
              AMOUNT/mol    =  5.55080000000000E+01
      1       OH[-]/aqueous/
              AMOUNT/mol    =  1.00000000000000E-07

ACTIVE ELECTRON CONSTRAINT

! In the above output, note that the line 'ACTIVE ELECTRON CONSTRAINT'
! is now present

! Calculate the equilibrium
      CALL TQCEL(' ', 0, 0, VALS, NOERR)

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1
OH[-]/aqueous/             1.0000E-07        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
O2                         2.5000E-08     4.5039E-10     4.5409E-10
HOOH                       2.6007E-21     4.6853E-23     4.6302E-23
OH                         2.0667E-21     3.7232E-23     3.6794E-23
HOO                        5.5456E-24     9.9906E-26     9.8731E-26
H2                         2.1493E-25     3.8720E-27     3.9182E-27
O                          5.2689E-35     9.4921E-37     9.3805E-37
O3                         2.6670E-36     4.8048E-38     4.8185E-38
H                          1.0446E-39     1.8819E-41     1.8598E-41
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 0.0000E+00     5.5508E+01     8.4106E-01
H[+]                       0.0000E+00     8.7350E-07     7.3467E-07
H2                         0.0000E+00     4.3257E-30     3.6382E-30
O2                         0.0000E+00     4.6675E-13     3.9256E-13
OH[-]                      0.0000E+00     8.7350E-07     7.3467E-07
HO2[-]                     0.0000E+00     5.6830E-25     4.7797E-25
HOOH                       0.0000E+00     2.8248E-20     2.3758E-20
TOTAL:                     0.0000E+00                    8.4106E-01
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Mole fraction of system components:
             gas_real
O            0.33333
H            0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

! Note that liquid water is no longer stable.
      END

/* Program cac34 */
/* Using TQCONF to set up semi-automatic charge balance correction */

#include "cacint.h"

int main()
{
  LI noerr, iAQU, iGAS, iPC, iEA;
  DB TP_AQU[2], vals[2];


  /* Initialise ChemApp */
  tqini(&noerr);

  /* Open data-file for reading */
  tqopna("water.dat",10,&noerr);

  /* Read data-file */
  tqrfil(&noerr);

  /* Close data-file */
  tqclos(10,&noerr);

  /* Set temperature and pressure units */
  tqcsu("T ", "C ", &noerr);
  tqcsu("p ", "atm ", &noerr);

  /* Define an input stream "STREAM_AQUEOUS" at 25 C and 1 atm */
  TP_AQU[0] = 25.0;
  TP_AQU[1] = 1.0;
  tqsttp("STREAM_AQUEOUS", TP_AQU, &noerr);

  /* Define content of this stream: 1 liter (55.508 mole) of water */
  tqinp("aqueous ", &iAQU, &noerr);
  tqinpc("H2O_liquid ", iAQU, &iPC, &noerr);
  tqstca("STREAM_AQUEOUS ", iAQU, iPC, 55.508, &noerr);

  /* Set temperature and total pressure to 25 C and 1 atm */
  tqstec("P ", 0, 1.0, &noerr);
  tqstec("T ", 0, 105.0, &noerr);

  /* Perform a formation phase target calculation with the gas phase as the
     target phase. Note that the gas phase is always the phase with index
     number 1, irrespective of whether it is called 'GAS', 'gas_ideal', or, as
     in this case, 'gas_real' */
  tqstec("A ", 1, 0.0, &noerr);

  /* Display what we have set so far */
  tqshow(&noerr);

SYSTEM UNITS:
Pressure     : atm
Volume       : dm3
Temperature  : C
Energy       : J
Amount       : mol

T =  105.00000000 C
P = 1 atm

STREAM NAME             STREAM NUMBER   TEMPERATURE/C   PRESSURE/atm
STREAM_AQUEOUS
                              1              25.00       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       H2O_liquid/aqueous/
              AMOUNT/mol    =  5.55080000000000E+01

INACTIVE ELECTRON CONSTRAINT

FORMATION TARGET PHASE: gas_real
EQUILIBRIUM AMOUNT/mol = 0.0000E+00

/* In the above output, note the line 'INACTIVE ELECTRON
   CONSTRAINT', i.e. no charge balance correction by default.

   Calculate the equilibrium, specifying temperature as the target
   variable */
tqcel("T ", 0, 0, vals, &noerr);

*T = 100.00 C
P = 1 atm
V = 0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        0.0000E+00     1.0000E+00     9.8754E-01
H2                         0.0000E+00     1.1802E-21     1.1950E-21
O2                         0.0000E+00     6.1055E-22     6.1591E-22
OH                         0.0000E+00     2.0291E-26     2.0038E-26
HOOH                       0.0000E+00     3.4804E-29     3.4371E-29
HOO                        0.0000E+00     7.4430E-35     7.3502E-35
H                          0.0000E+00     4.0975E-39     4.0464E-39
O                          0.0000E+00     3.8151E-43     3.7675E-43
O3                         0.0000E+00     4.1347E-56     4.1475E-56
TOTAL:                     0.0000E+00     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 5.5508E+01     5.5508E+01     1.0000E+00
H[+]                       7.3345E-07     7.3346E-07     7.3346E-07
H2                         1.0812E-24     1.0812E-24     1.0812E-24
O2                         5.2886E-25     5.2886E-25     5.2886E-25
OH[-]                      7.3345E-07     7.3346E-07     7.3346E-07
HO2[-]                     4.4778E-31     4.4778E-31     4.4778E-31
HOOH                       2.3471E-26     2.3471E-26     2.3471E-26
TOTAL:                     5.5508E+01                    1.0000E+00
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    4.0025E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 3.43097E+01   3.14178E+05   9.39802E+02  -3.27709E+05   0.00000E+00

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 4.21825E+03  -1.55517E+07   4.82259E+03  -1.73512E+07   0.00000E+00

Properties for aqueous:
pH = 6.1346
Eh/V = 0.32014
Total solute molality = 1.4669E-06
Ionic strength = 7.3346E-07
Osmotic coefficient = 1

Mole fraction of system components:
             gas_real     aqueous
O            0.33333      0.33333
H            0.66667      0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

/* As seen in the previous table, the gas phase over pure water reaches
   a pressure of 1 atm at 100 degrees Celsius. The gas phase amount is
   still zero, as this is the condition for a standard formation phase
   target calculation: the activity (or, in case of a gas phase, the
   fugacity) of the target phase is unity, the phase amount is
   zero. Just like any other phase, a gas phase with an
   activity/fugacity less then unity is not considered stable and thus
   does not have a positive amount. */

/* Set the equilibrium temperature to 105 degrees Celsius */
tqstec("T ", 0, 105.0, &noerr);

/* Calculate the equilibrium */
tqcel(" ", 0, 0, vals, &noerr);

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
H2                         1.3219E-19     2.3814E-21     2.4098E-21
O2                         6.6093E-20     1.1907E-21     1.2005E-21
OH                         2.6353E-24     4.7476E-26     4.6918E-26
HOOH                       4.2286E-27     7.6180E-29     7.5284E-29
HOO                        1.1498E-32     2.0714E-34     2.0470E-34
H                          8.1923E-37     1.4759E-38     1.4585E-38
O                          8.5669E-41     1.5434E-42     1.5252E-42
O3                         1.1464E-53     2.0654E-55     2.0713E-55
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 0.0000E+00     5.5508E+01     8.4106E-01
H[+]                       0.0000E+00     8.7350E-07     7.3467E-07
H2                         0.0000E+00     2.6604E-24     2.2376E-24
O2                         0.0000E+00     1.2340E-24     1.0378E-24
OH[-]                      0.0000E+00     8.7350E-07     7.3467E-07
HO2[-]                     0.0000E+00     9.2402E-31     7.7716E-31
HOOH                       0.0000E+00     4.5929E-26     3.8629E-26
TOTAL:                     0.0000E+00                    8.4106E-01
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Mole fraction of system components:
             gas_real
O            0.33333
H            0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

/* At 5 degrees above the boiling point of water at standard
   conditions, only the gas phase is stable. */

/* Artificially add an excess amount of OH[-] to the water, this will
   make it impossible for ChemApp to satisfy the electroneutrality
   condition. Note that this is an effect that might occur due to
   rounding errors in iterative calculations. */
tqinpc("OH[-] ", iAQU, &iPC, &noerr);
tqstca("STREAM_AQUEOUS ", iAQU, iPC, 1.0E-7, &noerr);

/* Calculate the equilibrium */
tqcel(" ", 0, 0, vals, &noerr);

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1
OH[-]/aqueous/             1.0000E-07        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
H2                         1.3219E-19     2.3814E-21     2.4098E-21
O2                         6.6093E-20     1.1907E-21     1.2005E-21
OH                         2.6353E-24     4.7476E-26     4.6918E-26
HOOH                       4.2286E-27     7.6180E-29     7.5284E-29
HOO                        1.1498E-32     2.0714E-34     2.0470E-34
H                          8.1923E-37     1.4759E-38     1.4585E-38
O                          8.5669E-41     1.5434E-42     1.5252E-42
O3                         1.1464E-53     2.0654E-55     2.0713E-55
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 5.7773E-07     5.5508E+01     8.4106E-01
H[+]                       5.8467E-22     5.6175E-14     5.6175E-14
H2                         2.3289E-32     2.2376E-24     2.2376E-24
O2                         1.0802E-32     1.0378E-24     1.0378E-24
OH[-]                      1.0000E-07     9.6080E+00     9.6080E+00
HO2[-]                     1.0578E-31     1.0164E-23     1.0164E-23
HOOH                       4.0205E-34     3.8629E-26     3.8629E-26
TOTAL:                     6.7773E-07                    1.0000E+00
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Properties for aqueous:
pH = 13.250
Eh/V =-0.22092
Total solute molality = 9.6080
Ionic strength = 4.8040
Osmotic coefficient = 1

Mole fraction of system components:
             gas_real     aqueous
O            0.33333      0.33333
H            0.66667      0.61748
EA           0            4.9184E-02

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

/* The results from the equilibrium calculation now show that liquid
   water is stable, which is definitely incorrect at 105 C. Due to the
   artificially introduced excess amount of OH[-], the Gibbs energy
   minimizer has no choice but to add the water phase to the set of
   stable phases, otherwise the mass balance cannot be satisfied.  Note
   also that the excess electrons ('EA') are documented in the table
   "Mole fraction of system components" at the bottom of the output
   above.  */

/* ChemApp can resolve such cases semi-automatically, if it is
   instructed via the subroutine TQCONF to apply a charge balance
   correction. */

/* OPTION 1: Configure ChemApp to perform semi-automatic charge balance
   correction for one electron spcifically:

   Get the system component index number for the aqueous electron
   'EA' */
tqinsc("EA ", &iEA, &noerr);

/* Configure ChemApp to perform semi-automatic charge balance
   correction for this electron */
tqconf("E ", iEA, 0, 0, &noerr);


/* OPTION 2: Configure ChemApp to perform semi-automatic charge balance
   correction for *all* electrons:

   ChemApp can easily be configured to perform the charge balance
   correction for all electrons, in case the data-file contains more
   than one phase-internal electron. */
tqconf("E ", 0, 0, 0, &noerr);

/* Display what we have set so far */
tqshow(&noerr);

SYSTEM UNITS:
Pressure     : atm
Volume       : dm3
Temperature  : C
Energy       : J
Amount       : mol

T =  105.00000000 C
P = 1 atm

STREAM NAME             STREAM NUMBER   TEMPERATURE/C   PRESSURE/atm
STREAM_AQUEOUS
                              1              25.00       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       H2O_liquid/aqueous/
              AMOUNT/mol    =  5.55080000000000E+01
      1       OH[-]/aqueous/
              AMOUNT/mol    =  1.00000000000000E-07

ACTIVE ELECTRON CONSTRAINT

/* In the above output, note that the line 'ACTIVE ELECTRON CONSTRAINT'
   is now present */

/* Calculate the equilibrium */
tqcel(" ", 0, 0, vals, &noerr);

T = 105 C
P = 1 atm
V = 1702.0 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/C   PRESSURE/atm STREAM
H2O_liquid/aqueous/        5.5508E+01        25.00       1.0000E+00     1
OH[-]/aqueous/             1.0000E-07        25.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: gas_real               mol                           atm
H2O                        5.5508E+01     1.0000E+00     9.8824E-01
O2                         2.5000E-08     4.5039E-10     4.5409E-10
HOOH                       2.6007E-21     4.6853E-23     4.6302E-23
OH                         2.0667E-21     3.7232E-23     3.6794E-23
HOO                        5.5456E-24     9.9906E-26     9.8731E-26
H2                         2.1493E-25     3.8720E-27     3.9182E-27
O                          5.2689E-35     9.4921E-37     9.3805E-37
O3                         2.6670E-36     4.8048E-38     4.8185E-38
H                          1.0446E-39     1.8819E-41     1.8598E-41
TOTAL:                     5.5508E+01     1.0000E+00     1.0000E+00
PHASE: aqueous                mol          MOLALITY       ACTIVITY
H2O_liquid                 0.0000E+00     5.5508E+01     8.4106E-01
H[+]                       0.0000E+00     8.7350E-07     7.3467E-07
H2                         0.0000E+00     4.3257E-30     3.6382E-30
O2                         0.0000E+00     4.6675E-13     3.9256E-13
OH[-]                      0.0000E+00     8.7350E-07     7.3467E-07
HO2[-]                     0.0000E+00     5.6830E-25     4.7797E-25
HOOH                       0.0000E+00     2.8248E-20     2.3758E-20
TOTAL:                     0.0000E+00                    8.4106E-01
                              mol                         ACTIVITY
H2O_Ice(s)               T 0.0000E+00                    3.2254E-01
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
-2.18727E+03   2.58330E+06   7.02064E+03  -3.82181E+05   1.70205E+03

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.99667E+03  -1.32826E+07   1.09034E+04  -1.74057E+07   1.70205E+03

Mole fraction of system components:
             gas_real
O            0.33333
H            0.66667

Data on 1 constituent marked with 'T' are extrapolated outside their valid
temperature range

  /* Note that liquid water is no longer stable. */

  return 0;

}

2.11   TQSIZE

GET-ARRAY-SIZES

Use TQSIZE to get the internal array dimensions of ChemApp.

Added for ChemApp version 1.1.3

Synopsis

FORTRAN:

CALL TQSIZE(NA,NB,NC,ND,NE,NF,NG,NH,NI,NJ,NK,NOERR)

C:

tqsize(&na,&nb,&nc,&nd,&ne,&nf,&ng,&nh,&ni,&nj,&nk,&noerr);

Pascal:

tqsize(na,nb,nc,nd,ne,nf,ng,nh,ni,nj,nk,noerr);

Basic:

Call tqsize(na,nb,nc,nd,ne,nf,ng,nh,ni,nj,nk,noerr)

TQSIZE returns the dimensions of a number of internal arrays. Among other purposes, it can be used to verify whether one is working with the standard or extended version of ChemApp.

See also

TQUSED

! Display the sizes of selected ChemApp internal arrays

      PROGRAM CAF4
      IMPLICIT NONE

      INTEGER NOERR
      INTEGER LA,LB,LC,LD,LE,LF,LG,LH,LI,LJ,LK

! Initialise ChemApp
      CALL TQINI(NOERR)

! Get array sizes
      CALL TQSIZE(LA,LB,LC,LD,LE,LF,LG,LH,LI,LJ,LK,NOERR)

 50   FORMAT(1X,A,I3)

      WRITE(UNIT=*,FMT=50) 'Maximum number of constituents: ',LA
      WRITE(UNIT=*,FMT=50) 'Maximum number of system components: ',LB
      WRITE(UNIT=*,FMT=50) 'Maximum number of mixture phases: ',LC
      WRITE(UNIT=*,FMT=50) 'Maximum number of sublattices for a '//
     *                     'mixture phase: ',LF


      END

Maximum number of constituents: ***
Maximum number of system components:  48
Maximum number of mixture phases:  44
Maximum number of sublattices for a mixture phase:   5

/* Program cac4 */
/* Display the sizes of selected ChemApp internal arrays */

#include "cacint.h"

int main()
{
  LI noerr,
    la,lb,lc,ld,le,lf,lg,lh,li,lj,lk;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Get array sizes */
  tqsize(&la,&lb,&lc,&ld,&le,&lf,&lg,&lh,&li,&lj,&lk,&noerr);

  printf("Internal array sizes of this version of ChemApp:\n"
        "Maximum number of constituents: %li\n"
        "Maximum number of system components: %li\n"
        "Maximum number of mixture phases: %li\n"
        "Maximum number of sublattices for a mixture phase: %li\n",
        la,lb,lc,lf);


  return 0;

}

Internal array sizes of this version of ChemApp:
Maximum number of constituents: 1600
Maximum number of system components: 48
Maximum number of mixture phases: 44
Maximum number of sublattices for a mixture phase: 5

2.12   TQUSED

GET-CURRENTLY-USED-DIMENSIONS

Use TQUSED to get the dimensions of the currently loaded thermochemical system.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQUSED(NA,NB,NC,ND,NE,NF,NG,NH,NI,NJ,NK,NOERR)

C:

tqused(&na,&nb,&nc,&nd,&ne,&nf,&ng,&nh,&ni,&nj,&nk,&noerr);

Pascal:

tqused(na,nb,nc,nd,ne,nf,ng,nh,ni,nj,nk,noerr);

Basic:

Call tqused(na,nb,nc,nd,ne,nf,ng,nh,ni,nj,nk,noerr)

TQUSED resembles TQSIZE and mirrors its parameters. The difference is that TQUSED returns the values for the currently loaded thermochemical system, whereas TQSIZE returns the maximum values for these parameters, and thus indicates the size of the internal arrays in ChemApp.

TQUSED was introduced as a support subroutine for transparent data-files, but might be used by a ChemApp programmer to check how much larger a thermochemical system contained in a data-file can be before the internal limits of the ChemApp library used (light, standard, or extended) are reached. In this case the parameters NA through NK returned by TQUSED would be compared to the parameters of the same name TQSIZE returns.

See also

TQSIZE

See

TQSIZE

2.13   TQGIO

GET-VALUE-OF-INPUT-OUTPUT-OPTION

Use TQGIO to get the unit number and language used for error messages, and the unit number for the thermodynamic data-file and optional output lists, respectively.

Synopsis

FORTRAN:

CALL TQGIO(OPTION,IVAL,NOERR)

C:

tqgio(option,&ival,&noerr);

Pascal:

tqgio(option,ival,noerr);

Basic:

Call tqgio(option,ival,noerr)

OPTION is character input identifying the input/output option. Legal values for OPTION are given in Table Legal input/output options used by TQGIO and TQCIO. IVAL is output and equal to the current unit number or to the index for the language used for error messages (see Table Legal input/output options used by TQGIO and TQCIO).

See also

TQCIO

! Get values for input/output options
      PROGRAM CAF5
      IMPLICIT NONE

      INTEGER NOERR, NVALUE

! Initialise ChemApp
      CALL TQINI(NOERR)

! Get values for input/output options

! Determine which FORTRAN unit is used by TQRFIL for reading the
! thermochemical data-file
      CALL TQGIO('FILE ', NVALUE, NOERR)

 50   FORMAT(1X,A,I3)

      WRITE(UNIT=*,FMT=50) 'The thermochemical data will be read '//
     *     'from the file associated with unit ',NVALUE


      END

The thermochemical data will be read from the file associated with unit  10

/* Program cac5 */
/* Get values for input/output options */

#include "cacint.h"

int main()
{
  LI noerr, iovalue;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Get values for input/output options

     Determine which FORTRAN unit is used by tqrfil for reading the
     thermochemical data-file */

  tqgio("FILE", &iovalue, &noerr);

  printf("The thermochemical data will be read from the file "
          "associated with unit %li\n", iovalue);


  return 0;

}

The thermochemical data will be read from the file associated with unit 10

2.14   TQCIO

CHANGE-VALUE-OF-INPUT-OUTPUT-OPTION

Using TQCIO, input and output from ChemApp can be redirected to another unit than the default, or a different language be selected for the error messages than the default (see Table Legal input/output options used by TQGIO and TQCIO ).

Synopsis

FORTRAN:

CALL TQCIO(OPTION,IVAL,NOERR)

C:

tqcio(option,ival,&noerr);

Pascal:

tqcio(option,ival,noerr);

Basic:

Call tqcio(option,ival,noerr)

OPTION and IVAL are both input, and are used to identify the input/output option (see Table Legal input/output options used by TQGIO and TQCIO). Unit numbers entered must be <= 10 or >= 20 to be valid. Error messages will not be output if IVAL is set to zero for option ERROR.

A file has to be opened under this new unit number in the application program if default values are changed for the options ERROR and LIST. TQOPEN and TQCLOS should be used for this purpose.

See also

TQGIO

! Change values of input/output options

      PROGRAM CAF6
      IMPLICIT NONE

      INTEGER NOERR, NPHASE

! Initialise ChemApp
      CALL TQINI(NOERR)

! Change the language for error messages to Swedish
      CALL TQCIO('LANGUAGE ', 4, NOERR)

! Trigger a ChemApp error by trying to get the number of phases
! before even having read a thermochemical data-file
      CALL TQNOP(NPHASE, NOERR)


      END

Fel nummer: 104
En fil med termodynamiska data maste foerst inlaesas
Felet upptraedde sedan "TQNOP " anropats

/* Program cac6 */
/* Change values of input/output options */

#include "cacint.h"

int main()
{
  LI noerr, nphase;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Change the language for error messages to Swedish */
  tqcio("LANGUAGE", 4, &noerr);

  /* Trigger a ChemApp error by trying to get the number of phases
     before even having read a thermochemical data-file */
  tqnop(&nphase, &noerr);


  return 0;

}

Fel nummer: 104
En fil med termodynamiska data maste foerst inlaesas
Felet upptraedde sedan "TQNOP " anropats

2.15   TQRFIL

READ-DATA-FILE

Reads a thermodynamic data-file in ASCII format.

Synopsis

FORTRAN:

CALL TQRFIL(NOERR)

C:

tqrfil(&noerr)

Pascal:

tqrfil(noerr)

Basic:

Call tqrfil(noerr)

The thermodynamic data-file in ASCII format to be read must be opened in the application program using default unit 10 (see Table Legal input/output options used by TQGIO and TQCIO), unless this has been changed using TQCIO.

For non-FORTRAN programs, TQOPNA and TQCLOS have to be used for opening and closing the data-file.

If the data-file to load is in binary format, use TQRBIN instead; if it is in transparent format, use TQRCST.

See also

TQOPNA, TQCLOS, Thermodynamic data

! Read a thermochemical data-file in ASCII format

      PROGRAM CAF7
      IMPLICIT NONE

      INTEGER NOERR

! Initialise ChemApp
      CALL TQINI(NOERR)

! Open data-file for reading
      CALL TQOPNA('cosi.dat', 10, NOERR)

! Read data-file
      CALL TQRFIL(NOERR)

! Close data-file
      CALL TQCLOS(10, NOERR)

      END

/* Program cac7 */
/* Read a thermochemical data-file in ASCII format*/

#include "cacint.h"

int main()
{
  LI noerr;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Note that tqopna is used to open the thermochemical data-file,
     instead of a standard C library routine like fopen. The reason
     is that it is necessary to associate the data-file with a
     particular FORTRAN unit number (10 by default, see tqgio) so
     that the FORTRAN subroutine tqrfil can read from the correct
     file */
  tqopna("cosi.dat",10,&noerr);
  if (noerr) {
    printf("ERROR: Cannot open data-file.");
    exit(noerr);
  }

  /* Read data-file */
  tqrfil(&noerr);

  /* Close data-file */
  /* Again, the routine for closing the data-file is not a standard
     C library routine like fclose, but a special one to make sure the
     file that was previously opened under the unit number specified
     is closed. */
  tqclos(10,&noerr);

  return 0;

}

2.16   TQRBIN

READ-BINARY-DATA-FILE

Reads a thermodynamic data-file in binary format.

Added for ChemApp version 2.1.4

Synopsis

FORTRAN:

CALL TQRBIN(NOERR)

C:

tqrbin(&noerr);

Pascal:

tqrbin(noerr);

Basic:

Call tqrbin(noerr)

TQRBIN must be used to read a thermodynamic data-file in binary format. Binary data-files are usually either supplied by GTT-Technologies directly, or created using other software programs (e.g. FACT-Win).

The thermodynamic data-file to be read must be opened in the application program using default unit 10 (see Table Legal input/output options used by TQGIO and TQCIO), unless this has been changed using TQCIO.

For non-FORTRAN programs, TQOPNB and TQCLOS have to be used for opening and closing the data-file.

If the data-file to load is in ASCII (i.e. plain text) format, use TQRFIL instead; if it is in transparent format, use TQRCST.

See also

TQOPNB, TQCLOS, Thermodynamic data

! Read a thermochemical data-file in BINARY format

! NOTE: This example program requires a data-file in binary format
!       to run, which is not part of a regular distribution of ChemApp
!       or ChemApp "light".

      PROGRAM CAF29
      IMPLICIT NONE

      INTEGER NOERR

! Initialise ChemApp
      CALL TQINI(NOERR)

! Open binary data-file for reading.
      CALL TQOPNB('cosi.bin', 10, NOERR)

! Read data-file
      CALL TQRBIN(NOERR)

! Close data-file
      CALL TQCLOS(10, NOERR)

      END

/* Program cac29 */
/* Read a thermochemical data-file in BINARY format*/

/* NOTE: This example program requires a data-file in binary format
         to run, which is not part of a regular distribution of ChemApp
         or ChemApp "light". */

#include "cacint.h"

int main()
{
  LI noerr;

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Note that tqopnb is used to open the thermochemical data-file,
     instead of a standard C library routine like fopen. The reason
     is that it is necessary to associate the data-file with a
     particular FORTRAN unit number (10 by default, see tqgio) so
     that the FORTRAN subroutine tqrbin can read from the correct
     file */
  tqopnb("cosi.bin",10,&noerr);

  /* Read data-file */
  tqrbin(&noerr);

  /* Close data-file */
  /* Again, the routine for closing the data-file is not a standard
     C library routine like fclose, but a special one to make sure the
     file that was previously opened under the unit number specified
     is closed. */
  tqclos(10,&noerr);

  return 0;

}

2.17   TQRCST

READ-TRANSPARENT-DATA-FILE

Reads a thermodynamic data-file in transparent format.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQRCST(NOERR)

C:

tqrcst(&noerr);

Pascal:

tqrcst(noerr);

Basic:

Call tqrcst(noerr)

TQRCST must be used to read a thermodynamic data-file in transparent format. Transparent data-files are usually either supplied by GTT-Technologies directly, or created using other software programs (e.g. FactSage).

The thermodynamic data-file to be read must be opened in the application program using default unit 10 (see Table Legal input/output options used by TQGIO and TQCIO), unless this has been changed using TQCIO.

For both FORTRAN and non-FORTRAN programs, TQOPNT and TQCLOS have to be used for opening and closing the data-file.

If the data-file to load is in ASCII (i.e. plain text) format, use TQRFIL instead; if it is in binary format, use TQRBIN.

See also

TQOPNT, TQCLOS, Thermodynamic data, TQGTRH

! Read a thermochemical data-file in TRANSPARENT format, then
! retrieves information on the transparent file header.

! NOTE: This example program requires a data-file in transparent format
!       to run, which is not part of a regular distribution of ChemApp
!       or ChemApp "light".

! The support function STRLEN returns the total number of characters in
! a string, not counting trailing blanks
      INTEGER FUNCTION STRLEN(INSTR)
      CHARACTER INSTR*(*)

      STRLEN = LEN(INSTR)
      DO WHILE(INSTR(STRLEN:STRLEN) .EQ. ' ')
         STRLEN = STRLEN - 1
         IF (STRLEN .EQ. 1) RETURN
      ENDDO
      RETURN
      END


      PROGRAM CAF31
      IMPLICIT NONE

      INTEGER NOERR, STRLEN

! Variables to store information from various transparent file
! header (TFH) fields
      CHARACTER TFHID*255, TFHUSR*80,TFHNWP*40,TFHNRP*40,TFHREM*80
      INTEGER TFHVER, TFHVNW(3), TFHVNR(3), TFHDTC(6), TFHDTE(6)


 10   FORMAT(1X,A,I4.4,5(A1,I2.2))

! Initialise ChemApp
      CALL TQINI(NOERR)

! Open transparent data-file for reading.
      CALL TQOPNT('cosiex.cst', 10, NOERR)

! Read data-file
      CALL TQRCST(NOERR)

! Close data-file
      CALL TQCLOS(10, NOERR)

! Once the transparent data-file has been read, information on its
! header can be retrieved.
      CALL TQGTRH(TFHVER, TFHNWP, TFHVNW, TFHNRP, TFHVNR, TFHDTC,
     *     TFHDTE, TFHID, TFHUSR, TFHREM, NOERR)

      WRITE(UNIT=*, FMT=*) 'Version number of the transparent file ' //
     *     'header format:', TFHVER
      WRITE(UNIT=*, FMT=*) 'Name of the program which wrote the ' //
     *     'data-file: ', TFHNWP(1:STRLEN(TFHNWP))
      WRITE(UNIT=*, FMT=*) 'Version number of the writing program: ',
     *     TFHVNW(1), '.', TFHVNW(2), '.', TFHVNW(3)
      WRITE(UNIT=*, FMT=*) 'Programs which are permitted to read ' //
     *     'the data-file: ', TFHNRP(1:STRLEN(TFHNRP))
      WRITE(UNIT=*, FMT=*) 'Min. version number of the reading ' //
     *     'program: ', TFHVNR(1), '.', TFHVNR(2), '.', TFHVNR(3)
      WRITE(UNIT=*, FMT=10) 'File was created on ',
     *     TFHDTC(1),'/', TFHDTC(2),'/',TFHDTC(3),' ',
     *     TFHDTC(4),':',TFHDTC(5),':',TFHDTC(6)
      WRITE(UNIT=*, FMT=10) 'File will expire on ',
     *     TFHDTE(1),'/', TFHDTE(2),'/',TFHDTE(3),' ',
     *     TFHDTE(4),':',TFHDTE(5),':',TFHDTE(6)
      WRITE(UNIT=*, FMT=*) 'Licensee''s user ID(s): ',
     *     TFHID(1:STRLEN(TFHID))
      WRITE(UNIT=*, FMT=*) 'Licensee''s name: ',
     *     TFHUSR(1:STRLEN(TFHUSR))
      WRITE(UNIT=*, FMT=*) 'Remarks: ',
     *     TFHREM(1:STRLEN(TFHREM))


      END

Version number of the transparent file header format:           1
Name of the program which wrote the data-file: FactSage
Version number of the writing program:            5 .           0 .           0
Programs which are permitted to read the data-file: CAFU,CALI
Min. version number of the reading program:           -1 .          -1 .          -1
File was created on 2015/09/09 15:13:52
File will expire on 2036/12/31 12:00:00
Licensee's user ID(s): ????
Licensee's name: GTT - Technologies
Remarks: For use with ChemApp example programs

         /* Program cac31 */
/* Read a thermochemical data-file in TRANSPARENT format, then
   retrieves information on the transparent file header. */

/* NOTE: This example program requires a data-file in transparent format
         to run, which is not part of a regular distribution of ChemApp
         or ChemApp "light". */

#include "cacint.h"

int main()
{
  LI noerr;

  /* Variables to store information from various transparent file
     header (TFH) fields */
  char tfhid[255], tfhusr[80],tfhnwp[40],tfhnrp[40],tfhrem[80];
  LI tfhver, tfhvnw[3], tfhvnr[3], tfhdtc[6], tfhdte[6];

  /* Initialise ChemApp */
  tqini(&noerr);

  /* Note that tqopnt is used to open the thermochemical data-file,
     instead of a standard C library routine like fopen. The reason
     is that it is necessary to associate the data-file with a
     particular FORTRAN unit number (10 by default, see tqgio) so
     that the FORTRAN subroutine tqrcst can read from the correct
     file */
  tqopnt("cosiex.cst",10,&noerr);

  /* Read data-file */
  tqrcst(&noerr);

  /* Close data-file */
  /* Again, the routine for closing the data-file is not a standard
     C library routine like fclose, but a special one to make sure the
     file that was previously opened under the unit number specified
     is closed. */
  tqclos(10,&noerr);

  /* Once the transparent data-file has been read, information on its
     header can be retrieved.*/
  tqgtrh(&tfhver, tfhnwp, tfhvnw, tfhnrp, tfhvnr, tfhdtc, tfhdte,
        tfhid, tfhusr, tfhrem, &noerr);

  printf("Version number of the transparent file header format: %li\n",
        tfhver);
  printf("Name of the program which wrote the data-file: %s\n", tfhnwp);
  printf("Version number of the writing program: %li.%li.%li\n",
        tfhvnw[0],tfhvnw[1],tfhvnw[2]);
  printf("Programs which are permitted to read the data-file: %s\n", tfhnrp);
  printf("Min. version number of the reading program: %li.%li.%li\n",
        tfhvnr[0],tfhvnr[1],tfhvnr[2]);
  printf("File was created on %li/%02li/%02li %02li:%02li:%02li \n",
        tfhdtc[0],tfhdtc[1],tfhdtc[2],tfhdtc[3],tfhdtc[4],tfhdtc[5]);
  printf("File will expire on %li/%02li/%02li %02li:%02li:%02li \n",
        tfhdte[0],tfhdte[1],tfhdte[2],tfhdte[3],tfhdte[4],tfhdte[5]);
  printf("Licensee's user ID(s): %s\n", tfhid);
  printf("Licensee's name: %s\n", tfhusr);
  printf("Remarks : %s\n", tfhrem);


  return 0;

}

Version number of the transparent file header format: 1
Name of the program which wrote the data-file: FactSage
Version number of the writing program: 5.0.0
Programs which are permitted to read the data-file: CAFU,CALI
Min. version number of the reading program: 4294967295.4294967295.4294967295
File was created on 2015/09/09 15:13:140720308486196
File will expire on 2036/12/31 12:00:140720308486144
Licensee's user ID(s): ????
Licensee's name: GTT - Technologies
Remarks : For use with ChemApp example programs

2.18   TQOPEN

OPEN-FILE

Use TQOPEN to open a file for reading or writing by ChemApp.

TQOPEN has been partially superceded by TQOPNA and TQOPNB in ChemApp versions V3.3.0 and later, see the note below.

Synopsis

FORTRAN:

CALL TQOPEN(NAME,UNIT,NOERR)

C:

tqopen(name,unit,&noerr);

Pascal:

tqopen(name,unit,noerr);

Basic:

Call tqopen(name,unit,noerr)

This routine is used to open files under a specific FORTRAN unit number. Starting with ChemApp V3.3.0, it should only be used to open files for writing. FORTRAN programmers may use the standard OPEN statement instead, if ChemApp is used as a static library.

There are three standard cases where ChemApp application programs need to open files using TQOPEN:

1. TQRFIL and TQRBIN, which read a thermochemical data-file, expect this file to be opened under a specific unit number (10 by default, see Table Legal input/output options used by TQGIO and TQCIO). If you are using ChemApp V3.3.0 or later, you should use TQOPNA and TQOPNB instead to open ASCII and binary thermochemical data-files.
2. TQCEL, TQMAPL, and TQSHOW write by default to standard output. If the output from these subroutines should be written to a file instead, the file has to be opened using TQOPEN with the proper unit number (see TQCIO and Table Legal input/output options used by TQGIO and TQCIO).
3. Error messages from ChemApp are by default written to standard output as the errors occur. If this is not desired (for instance when the application program has a graphical user interface), the error messages can be redirected to a file, and/or retrieved individually using TQERR. The file to which the error messages would be written in such a case needs to be opened using TQOPEN.

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. Whether the file to be opened already exists should be checked prior to a call to TQOPEN.

If you receive an Error code 102 or Error code 103 when reading the data-file with TQRFIL, and you find a file of zero bytes length under the name you passed to TQOPEN, this means that this file has just been created with the call to TQOPEN. It didn't exist before, and didn't get shortened, but created instead. It usually means that either the wrong filename was passed to TQOPEN, or the file was not located in the directory where the program expected it. The reason for this behaviour is that TQOPEN can both be used to open existing files for reading, as well as new files for writing.

Both problems mentioned above are resolved if TQOPNA is used instead of TQOPEN to open thermochemical data-files in ASCII format, TQOPNB to open binary data-files, and TQOPNT to open transparent data-files.

A file that has been opened using TQOPEN should subsequently be closed only with TQCLOS.

See also

TQOPNA, TQOPNB, TQOPNT

See

TQWSTR

2.19   TQWSTR

WRITE-STRING

Use TQWSTR to write a character string to the Fortran units associated with 'LIST' and 'ERROR'.

Synopsis

FORTRAN:

CALL TQWSTR(OPTION,TEXT,NOERR)

C:

tqwstr(option,text,&noerr);

Pascal:

tqwstr(option,text,noerr);

Basic:

Call tqwstr(option,text,noerr)

This subroutine can be used to write user-defined textual output to the Fortran units associated with 'LIST' and 'ERROR'.

The output of subroutines such as TQCEL, TQMAPL, and TQSHOW, as well as ChemApp error messages can be redirected to files, using TQCIO. Unless the application program is written in Fortran and ChemApp is used as a static library, it is difficult or even impossible to write arbitrary user-defined text to the same file, since it needs to be addressed under a specific Fortran unit number.

For this purpose, TQWSTR may be used, which allows a character string to be written to the Fortran units associated with 'LIST' and 'ERROR'.

The maximum length of the string is determined by the character length conventions of the language in which the application program is written. A length of 255 characters should pose no problem for any application language.

See also

TQOPEN, TQCIO, TQGIO

! Redirecting ChemApp output and user-defined text to the same file

      PROGRAM CAF32
      IMPLICIT NONE

      INTEGER NOERR, FUNIT, LUNIT, IPC, NUMCON
      CHARACTER LOGTXT*80
      DOUBLE PRECISION CO2AMT, DARR2(2)

! Initialise ChemApp
      CALL TQINI(NOERR)

! Get the unit number from which the thermochemical data-file
! will be read
      CALL TQGIO('FILE ', FUNIT, NOERR)

! Open the thermochemical data-file cosi.dat (system C-O-Si)
! for reading
      CALL TQOPNA('cosi.dat', FUNIT, NOERR)

! Read data-file
      CALL TQRFIL(NOERR)

! Close data-file
      CALL TQCLOS(FUNIT, NOERR)

! Input 3 mol of CO2/GAS/
      CO2AMT = 3.D0
      CALL TQINPC('CO2', 1, IPC, NOERR)
      CALL TQSETC('IA ', 1, IPC, CO2AMT, NUMCON, NOERR)

! Redirect 'LIST' output (e.g. output from TQCEL) to a different
! unit number
      LUNIT = 21
      CALL TQCIO('LIST ', LUNIT, NOERR)

! Open a file under this unit number
      CALL TQOPEN('caf32.rst', LUNIT, NOERR)

! Write a descriptive text to file 'result'
      CALL TQWSTR('LIST ', 'Output from TQCEL (ChemSage result table)',
     *     NOERR)

 100  FORMAT(A,G8.3)
      WRITE(LOGTXT, FMT=100) 'Incoming amount of CO2 in mol: ', CO2AMT

      CALL TQWSTR('LIST ', LOGTXT, NOERR)

! Write ChemSage result table to file 'result'
      CALL TQCEL(' ',0,0,DARR2,NOERR)

! Direct 'LIST' output back to the standard output unit
      CALL TQCIO('LIST ', 6, NOERR)

! Close the file 'result'
      CALL TQCLOS(LUNIT, NOERR)

      END

/* Program cac32 */
/* Redirecting ChemApp output and user-defined text to the same file */

#include "cacint.h"

int main()
{
  LI noerr, funit, lunit, ipc, numcon;
  char logtxt[80];
  DB co2amt, darray2[2];


  /* Initialise ChemApp */
  tqini(&noerr);

  /* Get the unit number from which the thermochemical data-file
     will be read */
  tqgio("file", &funit, &noerr);

  /* Open the thermochemical data-file cosi.dat (system C-O-Si)
     for reading */
  tqopna("cosi.dat", funit, &noerr);

  /* Read data-file */
  tqrfil(&noerr);

  /* Close data-file */
  tqclos(funit,&noerr);

  /* Input 3 mol of CO2/GAS/ */
  co2amt = 3.0;
  tqinpc("CO2", 1, &ipc, &noerr);
  tqsetc("ia ", 1, ipc, co2amt, &numcon, &noerr);

  /* Redirect "list" output (e.g. output from tqcel) to a different
     unit number */
  lunit = 21;
  tqcio("list", lunit, &noerr);

  /* Open a file under this unit number */
  tqopen("cac32.rst", lunit, &noerr);

  /* Write a descriptive text to file "result" */
  tqwstr("list", "Output from tqcel (ChemSage result table)", &noerr);

  sprintf(logtxt, "Incoming amount of CO2 in mol: %li", co2amt);

  tqwstr("list", logtxt, &noerr);

  /* Write ChemSage result table to file "result" */
  tqcel(" ", 0, 0, darray2, &noerr);

  /* Direct "list" output back to the standard output unit */
  tqcio("list", 6, &noerr);

  /* Close the file "result" */
  tqclos(lunit, &noerr);

  return 0;

}

2.20   TQOPNA

OPEN-ASCII-DATA-FILE

Use TQOPNA to open a thermochemical data-file in ASCII format for reading by ChemApp.

Added for ChemApp version 3.3.0

Synopsis

FORTRAN:

CALL TQOPNA(NAME,UNIT,NOERR)

C:

tqopna(name,unit,&noerr);

Pascal:

tqopna(name,unit,noerr);

Basic:

`` Call tqopna(name,unit,noerr)``

Use TQOPNA to open a thermochemical data-file in ASCII format for reading. If you are using ChemApp V3.3.0 or above, it is recommended that you use TQOPNA instead of TQOPEN. The advantage of TQOPNA over TQOPEN is that TQOPNA only opens the data-file if it already exists, otherwise it reports Error Code 107.

The unit number under which the data-file needs to be opened should normally be determined in advance using a call to TQGIO with the option 'FILE'.

A file that has been opened using TQOPNA should subsequently be closed only with TQCLOS.

FORTRAN programmers may use the standard OPEN statement instead of TQOPNA, if ChemApp is used as a static library.

TQOPNA cannot be used to open binary thermochemical data-files. For this purpose, use TQOPNB instead. To open ASCII files for writing, for instance to store the output of TQCEL, TQMAPL, and TQSHOW, use TQOPEN instead.

Please also see Thermodynamic data for details and differences of thermochemical data-files formats.

See also

TQOPNB, TQOPNT, TQCLOS, TQRFIL, TQOPEN, Thermodynamic data

See

TQRFIL

2.21   TQOPNB

OPEN-BINARY-DATA-FILE

Use TQOPNB to open a binary thermochemical data-file for reading by ChemApp.

Added for ChemApp version 3.3.0

Synopsis

FORTRAN:

CALL TQOPNB(NAME,UNIT,NOERR)

C:

tqopnb(name,unit,&noerr);

Pascal:

tqopnb(name,unit,noerr);

Basic:

Call tqopnb(name,unit,noerr)

Use TQOPNB to open a thermochemical data-file in binary format for reading. If you are using ChemApp V3.3.0 or above, it is recommended that you use TQOPNB instead of TQOPEN. The advantage of TQOPNB over TQOPEN is that TQOPNB only opens the data-file if it already exists, otherwise it reports Error Code 107.

The unit number under which the data-file needs to be opened should normally be determined in advance using a call to TQGIO with the option 'FILE'.

A file that has been opened using TQOPNB should subsequently be closed only with TQCLOS.

FORTRAN programmers may use the standard OPEN statement instead of TQOPNB, if ChemApp is used as a static library.

TQOPNB cannot be used to open ASCII thermochemical data-files. For this purpose, use TQOPNA instead.

Please see also Thermodynamic data for details and differences of thermochemical data-files formats.

See also

TQOPNA, TQOPNT, TQCLOS, TQRBIN, TQOPEN, Thermodynamic data

See

TQRBIN

2.22   TQOPNT

OPEN-TRANSPARENT-DATA-FILE

Use TQOPNT to open a transparent thermochemical data-file for reading by ChemApp.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQOPNT(NAME,UNIT,NOERR)

C:

tqopnt(name,unit,&noerr);

Pascal:

tqopnt(name,unit,noerr);

Basic:

Call tqopnt(name,unit,noerr)

Use TQOPNT to open a thermochemical data-file in transparent format for reading.

The unit number under which the data-file needs to be opened should normally be determined in advance using a call to TQGIO with the option 'FILE'.

A file that has been opened using TQOPNT should subsequently be closed only with TQCLOS.

FORTRAN programmers may use the standard OPEN statement instead of TQOPNT, if ChemApp is used as a static library. This is not recommended though, because the specifiers needed in calls to OPEN when opening transparent data-files are compiler-dependent.

TQOPNT cannot be used to open ASCII or binary thermochemical data-files. For this purpose, use TQOPNA/TQOPNB instead.

Please see also Thermodynamic data for details and differences of thermochemical data-files formats.

See also

TQRCST, TQGTRH, TQCLOS, TQOPNA, TQOPNB, Thermodynamic data

See

TQRCST

2.23   TQCLOS

CLOSE-FILE

Use TQCLOS to close a file that has been previously opened using TQOPNA, TQOPNB, TQOPNT, or TQOPEN.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQCLOS(UNIT,NOERR)

C:

tqclos(unit,&noerr);

Pascal:

tqclos(unit,noerr);

Basic:

Call tqclos(unit,noerr)

TQCLOS is used to make sure that a file previously opened with TQOPNA, TQOPNB, TQOPNT, or TQOPEN is closed correctly through its associated FORTRAN unit number.

FORTRAN programmers may use the standard CLOSE statement instead of TQCLOS, if ChemApp is used as a static library.

See also

TQOPNA, TQOPNB, TQOPNT, TQOPEN

See

TQRFIL

2.24   TQGTRH

GET-TRANSPARENT-FILE-HEADER-INFO

Use TQGTRH to retrieve information stored in the header of a transparent file.

Added for ChemApp version 4.0.0

Synopsis

FORTRAN:

CALL TQGTRH(VER,NWP,VNW,NRP,VNR,DTC,DTE,ID,USR,REM,NOERR)

C:

tqgtrh(&ver,nwp,&vnw,nrp,&vnr,&dtc,&dte,id,usr,rem,&noerr);

Pascal:

tqgtrh(ver,nwp,vnw,nrp,vnr,dtc,dte,id,usr,rem,noerr);

Basic:

Call tqgtrh(ver,nwp,vnw,nrp,vnr,dtc,dte,id,usr,rem,noerr)

Note that the lengths of the various character strings returned by TQGTRH are greater than regular ChemApp character strings, which is 24. It needs to be made sure that the character variables in the application program which are used with TQGTRH are of sufficient length. Their required lengths are indicated in the table above.

As mentioned in Thermodynamic data, transparent data-files all have a header which precedes the actual thermochemical data. This header contains a number of fields which can be retrieved using TQGTRH:

Note that in order for TQGTRH to be able to access and retrieve the various transparent file header fields, a transparent data-file needs to be read successfully first.

See also

TQOPNT, TQRCST, Thermodynamic data

See

TQRCST

2.25   TQGSU

GET-SYSTEM-UNIT

Use TQGSU to find out what unit is currently in use for a specified quantity.

Synopsis

FORTRAN:

CALL TQGSU(OPTION,UNIT,NOERR)

C:

tqgsu(option,unit,&noerr);

Pascal:

tqgsu(option,unit,noerr);

Basic:

Call tqgsu(option,unit,noerr)

OPTION is character input identifying the quantity. UNIT is character output with values as shown in Table Units permitted in ChemApp . The quantities and units available are those also available in FactSage.

See also

TQCSU

! Get and display the system units

      PROGRAM CAF8
      IMPLICIT NONE

      INTEGER NOERR
      CHARACTER UNIT*24

! Initialise ChemApp
      CALL TQINI(NOERR)

! Get default system units
      WRITE(UNIT=*,FMT='(A)') 'Default system units:'

      CALL TQGSU('Pressure ',UNIT,NOERR)
      WRITE(UNIT=*,FMT='(A)') 'Pressure unit: ' // UNIT

      CALL TQGSU('Volume ',UNIT,NOERR)
      WRITE(UNIT=*,FMT='(A)') 'Volume unit: ' // UNIT

      CALL TQGSU('Temperature ',UNIT,NOERR)
      WRITE(UNIT=*,FMT='(A)') 'Temperature unit: ' // UNIT

      CALL TQGSU('Energy ',UNIT,NOERR)
      WRITE(UNIT=*,FMT='(A)') 'Energy unit: ' // UNIT

      CALL TQGSU('Amount ',UNIT, NOERR)
      WRITE(UNIT=*,FMT='(A)') 'Amount unit: ' // UNIT


      END