ChemApp© - The Thermochemistry Library for your Software

© GTT-Technologies, Herzogenrath, Germany, 1996-2016

Programmer's Manual Edition 4.00 for ChemApp Versions 2.0.2 through 6.4.0

img/chemapp.png
Authors:

Gunnar Eriksson, Stephan Petersen

Address:
GTT-Technologies
Kaiserstraße 103
52134 Herzogenrath, Germany
Telephone:

+49-2407-59533

Telefax:

+49-2407-59661

E-mail:

info@gtt-technologies.de

Web:

http://www.gtt-technologies.de/

Company:

GTT-Technologies

Date:

March 23, 2016

Edition:

4.00

Copyright:
ChemApp© was developed by Gunnar Eriksson, based in part on work done in the framework of a European Science project when at the Lehrstuhl für Theoretische Hüttenkunde at the RWTH Aachen, Germany ([Eri94], [Eri95], [Eri97], [Pet07]).
This manual is Copyright © GTT-Technologies, 1996-2016. Unauthorised duplication and distribution both in printed and online form is prohibited. Original version by Gunnar Eriksson. Subsequent, extended editions by Stephan Petersen.



Table of Contents



1   Introduction to the ChemApp Library

ChemApp is a programmer's library consisting of a comprehensive set of subroutines, based on the thermodynamic phase equilibrium calculation module of ChemSage. It permits the calculation of complex, multicomponent, multiphase chemical equilibria and their associated extensive property balances. ChemApp is available as object code for a wide range of platforms and as a Dynamic Link Library (DLL) on Windows systems.

Potential applications for the use of ChemApp are almost limitless and can cover an extremely diverse range of applications. Two distinctly different groups of applications of ChemApp are possible:

By embedding it in appropriate code, ChemApp can be employed to investigate time-dependent and kinetic effects using the concept of "local equilibria".


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 SiO2 may be used, as well as Ca, Si, and O. Caution: In the more general case, it is necessary to ensure that the stoichiometric formulae are linearly independent.

Note: In a ChemApp data-file, the total number of components of a defined system includes phase-internal electrons; for example, when an aqueous phase is present. However, they are not counted when the maximum number of possible phases in the system is determined according to Gibbs' phase rule.

At chemical equilibrium, the absolute activities (chemical potentials) of the components are the same in the entire system. Internally in ChemApp, the actual number of system components is calculated as the rank of the stoichiometry matrix (see 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 Mg2Si forms at low temperatures.

In order to calculate the thermochemical properties for the components, their respective reference state has to be selected. As this cannot be done in a general way, calculation of these properties is not included in ChemApp.

Components

ChemApp maintains a list of components. These are numbered sequentially from 1 up to the total number of components. This sequence of numbers will never change, even if only a subset is included in the input amounts of a calculation. Several subroutines are available for obtaining information on the components and how to manipulate them:

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

Phases

ChemApp maintains a list of phases. These are numbered sequentially from 1 up to the total number of phases. This sequential number does not change, even if phases are eliminated or set dormant.

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

Constituents

ChemApp maintains a list of the constituents of each phase. These are numbered sequentially from 1 up to the total number of constituents of each phase. This sequential number does not change, even if constituents are eliminated or set dormant. The number of constituents may be different in each phase. Stoichiometric condensed phases are considered to consist of one constituent only.

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

Sublattices

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

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

1.6   Introduction of concepts

In this section, several concepts are introduced which are important to the ChemApp application programmer. They include a description of the two ways initial conditions can be defined (global conditions and streams), and a short introduction to two calculational methods: target calculations and one-dimensional phase mapping.

1.6.1   Setting initial conditions

ChemApp offers considerable flexibility for defining initial conditions of a chemical equilibrium calculation. Two different methods are available that will cover most cases experienced in practice. Note, however, that you can only use one of these methods at a time; they cannot be used simultaneously.

  • Defining the global conditions of the system Using this method, you merely need to set single conditions for pressure and temperature, and enter incoming species to define the composition of the system. For example, if you wish to calculate the thermodynamic equilibrium for the system SiO2-CaO, using an appropriate thermochemical data-file that among others contains the elements Ca, Si, and O, you would only need to define the temperature and pressure of the system, and the total amounts of SiO2 and CaO present.

    Conditions are set using the subroutine TQSETC and can be removed subsequently with the subroutine TQREMC. It is also possible to choose a number of other variables of state (see Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC).

  • Defining streams A stream is a means for transferring non-reacted matter (see also the notes in Extensive properties of streams) to a reaction zone. It has constant temperature and pressure, and contains one or more phases of fixed composition. When using this method, you set the three variables - composition, temperature and pressure - for one or more input streams. For example, one stream entering a reaction zone may comprise O2(g) pre-heated to a temperature of 1500 K, and the other may consist of CO(g) at room temperature.

    The streams method must be used for calculation of the extensive properties of reactions; for example, those involving the heat balance or the adiabatic temperature of a combustion process. It is also convenient to use it for reactor calculations, where you know what is entering the system and wish to calculate results at various stages during and at the end of the process. Streams are defined using the subroutine TQSTTP and can be removed again by using the subroutine TQSTRM.

    The composition of a stream (see TQSTCA) must be entered using phases and phase constituents only. If one wants to enter the incoming amounts for a stream in terms of the system components (i.e. usually the elements), one has to perform an intermediate calculation. This is discussed in When phase constituents are not elements.

1.6.2   Target calculations

ChemApp is able to perform two types of target calculations:

  • Extensive property target calculations
  • Phase target calculations

An extension of the second type are one-dimensional phase-mapping calculations, see below.

Target calculations are those in which certain conditions (targets) are set, for instance the value of a heat balance or the presence of a phase at equilibrium. These conditions can only be satisfied when the value of some other variable, i.e. the target variable, is adjusted accordingly. When programming a target calculation with ChemApp, the target is set using TQSETC/TQSTEC, while the target variable is set when calling TQCE/TQCEL.

When performing an extensive property target calculation with ChemApp, one of the following five extensive properties of the system can be selected as target: Heat capacity, enthalpy, entropy, Gibbs energy, or volume.

A phase target calculation enables conditions to be determined when a selected phase is present at equilibrium (formation phase target), or when an unspecified phase is precipitated from a specified solution phase (precipitation phase target).

For examples on how target calculations are performed, see the code example for TQCE and the worked examples: Phase equilibria and phase target calculations and A simple process using streams.

Note that ChemApp light is not able to perform phase target calculations.

1.6.3   One-dimensional phase-mapping

One-dimensional phase-mapping is used to search for all phase transitions within a given interval of a search variable. The search variable can be either total pressure, temperature, or incoming amount.

For examples on how one-dimensional phase-mapping calculations are performed, see the code example for TQMAP and the worked example One-dimensional phase mapping.

Note that ChemApp light is not able to perform 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.

Data types used in ChemApp. For examples on how these data types are used, please refer to the example programs, especially in terms of the use of the various character/string data types and arrays consisting of any of those data types.
FORTRAN C/C++ Delphi/Pascal Visual Basic
INTEGER long int LongInt Long
DOUBLE PRECISION double Double Double
CHARACTER char String String

1.9.1   FORTRAN

  1. Avoid using names of variables, common blocks, subroutines, and functions starting with CS and TQ, as these might interfere with names used within ChemApp. If your compiler still produces warnings or errors that relate to variable and common block names starting with CS and TQ, your FORTRAN system libraries might make use of such names. In this case, please contact GTT-Technologies.
  2. All character variables for use with ChemApp which are supposed to hold names of system components, phases, phase constituents should be 24 characters in length.
Exceptions are the subroutine tqerr, as well as the subroutines tqgtrh, tqgtid, tqgtnm, tqgtpi, and tqwstr, which all pass or return strings longer than 24 characters.

1.9.2   C/C++

While ChemApp itself is written in FORTRAN77, the use of C/C++ for application programming is also possible on most platforms.

Most C/C++ compilers require an interface library for this purpose, in order to properly link to the ChemApp library. This interface consists of

  • either a readily compiled library (e.g. libChemAppC.a), or a source code file (e.g. cacint.c), depending on your particular distribution, which you add to your projects,
  • a header file (e.g. cacint.h).

Please refer to the C example supplied with this distribution for information on how to use these files. The header file needs to be included by your C/C++ files, and the library needs to specified during the link process.

Here is a list of points to be aware of when using ChemApp with C/C++:

  1. C/C++ is case-sensitive in contrast to FORTRAN. When calling ChemApp functions, please make sure you use lowercase function names (e.g. use tqini, not TQINI).
  2. There is one ChemApp function which takes an array of strings as input parameter: tqcsc (Change-System-Components). Due to the differences between the FORTRAN and C/C++ parameter passing and string handling, C/C++ code has to provide a slightly different string array at this point than FORTRAN code. Whereas in FORTRAN this array has to consist of as many strings as there are system components, in C/C++ it has to have one extra string element, which has to be empty. Please see the C program provided for an example usage of tqcsc.
  3. Please keep in mind that in C/C++, arrays start with element number 0, whereas in FORTRAN, they normally start with 1. This often needs to be taken into account when arrays are involved in loops which contain ChemApp routines to access a range of index numbers or names of system components, phases, and phase constituents.
  4. As opposed to FORTRAN77 character variables, which are fixed in length and padded with trailing blanks if necessary, strings in C/C++ are null-terminated. The C interface routines delete trailing blanks from strings returned by ChemApp routines and add a null character at the end, before passing them back to the calling C/C++ program. Similarly, they process a C/C++ string passed to ChemApp in order to constitute a proper FORTRAN character variable of the right size before passing it on to the ChemApp subroutines. In order to do this without flaws, please make sure you declare the C string variables and arrays in your C/C++ programs correctly, i.e. giving them the right length. The C example program provided demonstrates several ways how to do this safely.

All character variables for use with ChemApp, e.g. variables that hold names of system components, phases, phase constituents as well as for other purposes like identifiers for the status of a phase, should be 24 characters in length (this means 25 characters in C/C++, taking the trailing null character into account).

Exceptions are the subroutine tqerr, for which a variable TQERRMSG is declared in cacint.h, as well as the subroutines tqgtrh, tqgtid, tqgtnm, tqgtpi, and tqwstr, which all pass or return strings longer than 24 characters.

  1. On some platforms, a FORTRAN INTEGER variable is different in size from a C/C++ int variable. The same is possible for FORTRAN's DOUBLE PRECISION and C/C++'s float. On most platforms, INTEGER corresponds to long int and DOUBLE PRECISION corresponds to double. To avoid compiler error messages due to these differences, please use the type LI when declaring an integer variable for use with ChemApp in C/C++, and DB when declaring a float variable for use with ChemApp. These two types are defined in cacint.h specific to your platform. See the C program provided for examples.
  2. If you get warnings like "... makes pointer from integer without a cast" when compiling your C/C++ code, check whether you specified the address operator (&) properly when passing variables to ChemApp functions. All variables through which values are returned, and which are not considered arrays by C/C++, need the address operator.
  3. The ChemApp subroutines tqrfil (Read-File), tqrbin (Read-Binary-Data-File), and tqrcst (Read-Transparent-Data-File) expect the file from which the thermodynamic data should be read to be open. In FORTRAN, the standard statement OPEN is used to open a file using the correct unit number. In non-FORTRAN programs, there is no way to make sure a file opened with functions such as fopen gets associated with a certain unit number so that a FORTRAN subroutine can access it. To overcome this problem, special FORTRAN routines are provided which open and close a file using C/C++ under a specific FORTRAN unit number. Refer to the C program provided and the documentation to see how these functions (tqopna, tqopnb, tqopnt, tqopen and tqclos) are used.
Note that tqopen does not check whether the file to be opened already exists or not, since tqopen can be used both for opening existing files for reading, and new files for writing (tqcel, tqshow). Whether the file to be opened already exists should be checked prior to a call to tqopen. Also, the use of tqopna, tqopnb, and tqopnt instead of tqopen is strongly recommended to open thermochemical data-files for reading.

1.9.3   Delphi

While ChemApp itself is written in FORTRAN77, the use of Borland Delphi® for application programming is possible by using the ChemApp DLL for Borland Delphi.

Please note that the DLL versions of ChemApp are usually not interchangeable between the compilers. To utilise ChemApp with your Delphi projects, you need to make sure that you are using the ChemApp DLL for Borland Delphi, a ChemApp DLL for another compiler (e.g. Microsoft Visual C++®) will likely not work.

To make use of ChemApp from within your Delphi projects, you need to

  • include the file cadint.pas in your projects (this file contains the Delphi interface to ChemApp and is part of the distribution),

  • For ChemApp versions 5.0.0 and later: make sure that in the project options of your application, you use one of the following conditional defines to indicate which version of the ChemApp DLL your application should use.

    If you would like to use the standard version of ChemApp, use the conditional CA_DEL_S. This will result in your application making use of ca_del_s.dll.

    If you would like to use the extended version of ChemApp, use the conditional CA_DEL_E. This will result in your application making use of ca_del_e.dll.

    If you would like to use the light version of ChemApp, use the conditional CA_DEL_L. This will result in your application making use of ca_del_l.dll. This is also the default, i.e. the light version is used when none of the other conditionals is defined.

  • For ChemApp versions less than 5.0.0: make sure that the ChemApp DLL for Delphi is available, and its name is assigned to the constant ChemAppDLL in the file cadint.pas (depending on the distribution you are using, ChemApp comes in a "standard", "extended", or "light" version, which are named differently to avoid ambiguity).

Please use the Delphi example program supplied with this distribution as a test case to determine whether you set up your projects correctly. Compare the results this program generates to the master results in the files cademo1.rst and result. If you have any problems reproducing these results, please contact GTT-Technologies.

Here is a list of points to be aware of when using ChemApp with Delphi:

  1. There is one ChemApp function which takes an array of strings as input parameter: tqcsc (Change-System-Components). Due to the differences between the FORTRAN and Delphi parameter passing and string handling, Delphi code has to provide a slightly different string array at this point than FORTRAN code. Whereas in FORTRAN this array has to consist of as many strings as there are system components, in Delphi this array has to have one extra string element, which has to be empty. Please see the Delphi program provided for an example usage of tqcsc.
  2. Every "name" used in conjuction with ChemApp, whether it is the name of a phase, a system component, a phase constituent, or a stream, can be up to 24 characters in length.

In contrast to other languages, Pascal is strict in terms of parameter type matching, which makes it difficult to use a type like string[24] for this purpose (as is done in the C/C++ interface to ChemApp).

Thus, all strings used in the Delphi interface to ChemApp (cadint.pas) are of type string, which means that all strings declared in an application program and used as parameters for ChemApp procedure calls should be of type string, or otherwise properly typecast/converted. It is important to realize that for names like system components, phases, phase constituents, etc., ChemApp itself does only make use of the first 24 characters of a string passed to it, and only returns a maximum of 24 characters to the calling code.

Exceptions are the subroutine tqerr, for which the type Terrmsg is declared in cadint.pas, as well as the subroutines tqgtrh, tqgtid, tqgtnm, tqgtpi, and tqwstr, which all pass or return strings longer than 24 characters.

  1. Every integer variable to be used for ChemApp procedure calls needs to be of type longint, every floating point variable of type double. To simplify the declaration of those variables, and to make the Delphi version of the interface to ChemApp consistent with that in other languages, several "type"s have been declared in cadint.pas, like LI (for longint) and DB (for double), which you are encouraged to use. Please see the type declaration section in cadint.pas for a list of these types.
  2. The ChemApp subroutines tqrfil (Read-File), tqrbin (Read-Binary-Data-File), and tqrcst (Read-Transparent-Data-File) expect the file from which the thermodynamic data should be read to be open. In FORTRAN, the standard statement OPEN is used to open the file using the correct unit number. In Delphi, there is no way to make sure a file opened with functions such as AssignFile gets associated with a certain unit number so that a FORTRAN subroutine can access it. To overcome this problem, special FORTRAN routines are provided which open and close a file using Delphi under a specific FORTRAN unit number. Refer to the Delphi example program provided to see how these functions (tqopen, tqopna, tqopnb, tqopnt, and tqclos) are used.
Note that tqopen does not check whether the file to be opened already exists or not, since tqopen can be used both for opening existing files for reading, and new files for writing (tqcel, tqshow). Whether the file to be opened already exists should be checked prior to a call to tqopen, tqopna, tqopnb, and tqopnt. For further details, see the manual section on tqopen.

1.9.4   Visual Basic

While ChemApp itself is written in FORTRAN77, the use of Microsoft Visual Basic® for application programming is possible by using the ChemApp DLL for Microsoft Visual Basic.

Please note that the DLL versions of ChemApp are usually not interchangeable between the compilers. To utilise ChemApp with your Visual Basic projects, you need to make sure that you are using the ChemApp DLL for Microsoft Visual Basic, a ChemApp DLL for another compiler (e.g. Microsoft Visual C++®) will likely not work.

To make use of ChemApp from within your Visual Basic projects, you need to

  • include the module cavbint.pas in your projects (this file contains the Visual Basic interface to ChemApp and is part of the distribution),
  • make sure that the version of the ChemApp DLL for Visual Basic you intend to use is available, and the matching conditional compilation directive (conChemAppStandard, conChemAppExtended, or conChemAppLight) is set to 1 in the file cavbint.pas (ChemApp is supplied in "standard", "extended", and "light" versions, which are named differently to avoid ambiguity).

Please use the Visual Basic example project cademo1 supplied with this distribution as a test case to determine whether you set up your projects correctly. Compare the results this program generates to the master results in the files cademo1.rst and result. If you have any problems reproducing these results, please contact GTT-Technologies.

Here is a list of points to be aware of when using ChemApp with Visual Basic:

  1. Which version of the ChemApp DLL ("Standard", "Extended", or "Light") is to be used when a program is compiled and run is determined using conditional compilation directives. The proper directive (conChemAppStandard, conChemAppExtended, or conChemAppLight) can either be set through cavbint.bas (as described above), or by conditional compilation directives specified in the Project Properties dialog box, or on the command line.
For more information on this topic, see the section "Using Conditional Compilation" in the "More About Programming" section of the "Visual Basic Programmer's Guide".
  1. There is one ChemApp function which takes an array of strings as input parameter: tqcsc (Change-System-Components). Due to the differences between the FORTRAN and Visual Basic parameter passing and string handling, Visual Basic code has to provide a slightly different string array at this point than FORTRAN code. Whereas in FORTRAN this array has to consist of as many strings as there are system components, in Visual Basic this array has to have one extra string element, which has to be empty. Please see the Visual Basic program provided for an example usage of tqcsc.
  2. Every "name" used in conjuction with ChemApp, whether it is the name of a phase, a system component, a phase constituent, or a stream, can be up to 24 characters in length.

FORTRAN77 only knows strings of fixed length. Using the same type of strings on the Visual Basic side of the interface is unpractical, since every string variable returned by ChemApp would be padded with blanks. Thus, all strings used in the Visual Basic interface to ChemApp are variable-length strings (Dim As String), with trailing blanks properly removed when returning from ChemApp. It is important to realize that ChemApp itself does only make use of the first 24 characters of a string passed to it, and only returns a maximum of 24 characters to the calling code.

Exceptions are the subroutine tqerr, for which a variable TQErrMsg is declared in cavbint.pas, as well as the subroutines tqgtrh, tqgtid, tqgtnm, tqgtpi, and tqwstr, which all pass or return strings longer than 24 characters.

  1. Every integer variable that is to be used in an invocation of a ChemApp subroutine has to be of type Long. Similarly, every real variable for use with ChemApp subroutines has to be of type Double.
  2. The ChemApp subroutines tqrfil (Read-File), tqrbin (Read-Binary-Data-File), and tqrcst (Read-Transparent-Data-File) expect the file from which the thermodynamic data should be read to be open. In FORTRAN, the standard statement OPEN is used to open the file using the correct unit number. In non-FORTRAN programs, there is no way to make sure a file opened with functions such as fopen gets associated with a certain unit number so that a FORTRAN subroutine can access it. To overcome this problem, special FORTRAN routines are provided which open and close a file using C/C++ under a specific FORTRAN unit number. Refer to the C program provided and the documentation to see how these functions (tqopna, tqopnb, tqopnt, tqopen and tqclos) are used.
Note that tqopen does not check whether the file to be opened already exists or not, since tqopen can be used both for opening existing files for reading, and new files for writing (tqcel, tqshow). Whether the file to be opened already exists should be checked prior to a call to tqopen. Also, the use of tqopna, tqopnb, and tqopnt instead of tqopen is strongly recommended to open thermochemical data-files for reading.

1.10   ChemApp best practices

Like any other tool, software or otherwise, ChemApp can be used in a good way, and in a better way. The following section intends to familarize you with guidelines to help you write better code with ChemApp, and in doing so should aid you in achieving your objectives wasting not only less time, but also less nerves.

If you encounter a problem in your work with ChemApp, and would like to contact GTT-Technologies' support in order to help you track down a problem in your code, or find out whether the problem might lie in ChemApp itself, this section is recommended reading. The points below are the result of several years of experience with many support issues, and we thus strongly recommend checking your code as to whether these best practises are implemented before you send it to us.

In fact, we have found that many apparent problems turn out to be "false alarms" on the user's side, and become obvious once they follow these best practices. Due to the time constraints and the workload of GTT-Technologies' support team, we might have to refrain from debugging users' code if these best practices are not implememted. (A typical example is that the error code which every ChemApp subroutine returns is only checked when calculating the equilibrium with TQCE, thus overlooking the fact that the actual reason why an equilibrium calculations fails actually results from an earlier call, for instance to TQINP with a phase name that doesn't exist.)

Log the ChemApp version number

If your program produes any kind of textual output, make sure it includes the ChemApp version number. This is especially useful if you store the output for documentation purposes: if you re-run the program later, potentially with another version of ChemApp, and discover differences in the output, you will be glad you stored this piece of information.

Before you contact GTT's support: Every output sent to GTT-Technologies' technical support should include the ChemApp version number, as returned by your program at run-time using TQVERS.

Make sure you 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.

1.11.1   User-defined solution models

For users who develop their own solution models, a special version of ChemApp is available that might allow for the addition of these models. This would then be a three-step process, which can be summarised as follows:

  1. The user-defined solution model needs to be coded in Fortran and added to the skeleton subroutines USERGP, USERGX, and USERGG which are supplied together with the special version of ChemApp.
  2. In the second stage, this user code is compiled and either linked statically to the application program together with ChemApp, or made available as a DLL.
  3. The solution data need to be added to a thermochemical data-file.

If you are interested in adding your own solution models to ChemApp, please contact GTT-Technologies for further details.

List of available solution models in ChemApp. Magnetic contributions are not permitted for phase models marked with an asterisk (*)
Model Application area
For general use with substitutional or associated solution phases
Solid phases with sublattice descriptions
  • Two-sublattice ionic formalism* [Sun91]
Ionic liquids
  • Two-sublattice equivalent fraction formalism [Pel88]
  • Two-sublattice equivalent fraction formalism as a polynomial [Des91]
Molten salts
Ionic oxidic mixtures with or without non-oxidic solutes
  • Modified quasichemical model in the quadruplet approximation [Cha01] [Pel01]
Condensed non-aqueous solutions
  • Binary defect formalism* [Pel]
Binary condensed phases with a narrow stoichiometry range
Metallic dilute solutions
  • Davies formalism* [Dav62]
  • Helgeson-Tanger-Shock formalism (ideal)* [Tan88]
  • Helgeson-Tanger-Shock formalism (Debye-Hückel)* [Tan88]
  • Helgeson-Tanger-Shock formalism (Davies)* [Tan88]
Dilute aqueous solutions
  • Pitzer formalism* [Har84]
  • Pitzer formalism with fixed alpha-1 and alpha-2* [Har84]
  • Pitzer formalism without E-theta and E-theta'* [Har84]
  • Specific ion-interaction formalism* [Gre97]
  • Helgeson-Tanger-Shock formalism (Pitzer)* [Tan88]
Concentrated aqueous solutions
  • Revised Helgeson-Kirkham-Flowers (HKF) model* [Hel81]
Aqueous solutions up to 5 kbar and 1300K
  • C-H-O-S-N-Ar multicomponent fluid model* [Bel92]
Fluid mixtures up to 1 Mbar and 6000K; important for many geological and environmental systems
  • Virial equation with Tsonopoulos' second virial coefficient correlation* [Tso74]
Non-ideal gas phases

1.11.2   ASCII data-files

The ASCII (plain text) data-file format is the traditional format for thermochemical data-files for ChemApp. Every user of ChemApp has probably seen several of these, since each distribution of ChemApp contains example data-files in this format. See for instance below and Example data-files and their contents for an overview on the data-files in ASCII format included with ChemApp.

The most common and recommended file extension for thermochemical data-files in ASCII format is .DAT. ASCII data-files are portable among platforms, the only detail that needs to be observed is that DOS/Windows and Unix systems use different line endings for text files. The failure to do a proper conversion is one common reason for TQRFIL to report Error code 103.

Overview of the different data-file formats
  ASCII Binary Transparent
How do I recognize it? Plain text, can be viewed and edited with an ASCII editor When viewed, does not contain readable data When viewed, the first four readable characters of the file are 'CSTR'
Typical file extension .DAT .BIN .CST
Minimum version of ChemApp required to read the file V1.0.0
FORTRAN: V2.1.4
Other: V3.3.0
V4.0.0
Are the files portable across compilers and/or platforms? Yes No Partially
Can I edit the data? Yes, but the use of a program such as CSFAP is strongly recommended No, do not attempt to edit, it will render the file useless No, do not attempt to edit, it will render the file useless
How do I open it?
FORTRAN: TQOPNA or OPEN
Other: TQOPNA
FORTRAN: TQOPNB or OPEN
Other: TQOPNB
FORTRAN: TQOPNT
Other: TQOPNT
How do I read it? TQRFIL TQRBIN TQRCST
How do I close it?
FORTRAN: TQCLOS or CLOSE
Other: TQCLOS
FORTRAN: TQCLOS or CLOSE
Other: TQCLOS
FORTRAN: TQCLOS
Other: TQCLOS
More information ASCII data-files Binary data-files (DEPRECATED) Transparent data-files

Using ASCII data-files (all programming languages)

The FORTRAN concept of unit numbers is not supported by other programming languages, thus the thermochemical data-files to be used by ChemApp cannot be opened with the standard file-opening subroutines of these languages. Even in cases where the application program is written in FORTRAN, it is still possible that the standard FORTRAN statements to open and close files (OPEN and CLOSE) cannot be used, for instance when using ChemApp in form of a DLL from a FORTRAN application program.

To both simplify and unify access to thermochemical data-files for all application programs and across all programming languages, a set of ChemApp subroutines is provided. This set of subroutines includes TQOPEN, TQOPNA, and TQCLOS.

The subroutine TQOPEN has been part of ChemApp since the earliest versions. It can both be used to open existing files for reading (e.g. thermochemical data-files), as well as to create new files for writing (e.g. files that are used to store the output of TQCEL, the ChemSage/ChemApp result tables). This flexibility, on the other hand, also comes with a disadvantage: If you try to open a data-file for reading, but the file is not where you or the program expects it to be, a new file of zero bytes length will be created instead. This effect is also mentioned in the description of TQOPEN.

Mainly because of this effect, another ChemApp subroutine has been added, which is available since version V3.3.0: TQOPNA. This subroutine opens the specified file only if it already exists. If it doesn't, or if any other error occurs during the file-opening process, it returns with Error code 107. As a note for users familiar with FORTRAN: TQOPNA opens the file with STATUS='OLD'.

It is thus recommended that TQOPNA be used instead of TQOPEN for opening thermochemical data-files which are in ASCII format. TQOPEN should be used when opening output files for writing, for instance for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).

As of ChemApp V4.0.0, the subroutines TQOPEN, TQOPNA, and TQCLOS have been made part of the core code of ChemApp, and are thus available to all application languages, both FORTRAN and non-FORTRAN. We recommend using these subroutines also in FORTRAN application programs, instead of calling the standard FORTRAN statements OPEN and CLOSE, if you are using ChemApp version 4.0.0 or later.

Using FORTRAN as an example, a thermodynamic data-file in ASCII format could be opened with the following code:

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

In case the attempt to open the data-file fails, TQOPNA will return with Error code 107, otherwise the data-file can now be loaded with TQRFIL and closed with TQCLOS:

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

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

By default, TQRFIL expects the data-file to be opened with unit number 10, this being the reason for both the OPEN and CLOSE statements above referring to this particular unit number. It is also possible to use a non-default unit number for this purpose, in which case ChemApp needs to be told about this using TQCIO. ChemApp will accept unit numbers less then 11 and larger than 19. If ChemApp is part of a larger FORTRAN program, it is important to make sure that the unit number used to open the data-file is free, be it unit number 10 or a non-default value. The FORTRAN subroutine INQUIRE is helpful in this case.

This basic sequence of opening and loading a thermochemical data-file is used in virtually all example programs listed in this manual.

Using ASCII data-files (FORTRAN programs)

In FORTRAN terms, ASCII data-files are usually called text files or formatted sequential files and may be opened with the standard FORTRAN OPEN statement by the application program if this is written in FORTRAN and uses ChemApp in form of a static library. In case ChemApp is used as a DLL in conjunction with a FORTRAN application program, this might not work. For this reason the use of the subroutines TQOPNA and TQCLOS, as explained above, is recommended even for FORTRAN programs.

If the standard FORTRAN OPEN and CLOSE statements are to be used, the code segment dealing with loading an ASCII data-file might be similar to the following:

C Open thermochemical data-file in ASCII format for reading
          OPEN(10, FILE='cosi.dat', STATUS='OLD', IOSTAT=NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot open data-file.'
             ...
          ENDIF

Note that the specifiers FORM= and ACCESS= can be omitted for ASCII data-files since their default values FORM='FORMATTED' and ACCESS='SEQUENTIAL' are the correct ones in this case.

Another point to note in the code example above is that if the OPEN statement fails, NOERR does not contain a ChemApp error number (see List of Error Messages), but one returned directly by the FORTRAN run time library. For details, please see your FORTRAN compiler's manual.

The syntax introduced above for opening a thermochemical data-file in ASCII format should be valid for all FORTRAN compilers on all platforms, as long as the data-file to be loaded has the correct line endings for text files on the platform in question. As already mentioned, this is an import detail to be aware of when transferring data-files between different computing platforms.

To make the process of opening data-files even safer, the use of an appropriate call to the FORTRAN statement INQUIRE prior to the OPEN statements is recommended.

The opened file can then subsequently be loaded into ChemApp with TQRFIL, and closed with CLOSE:

C Read thermochemical data-file in ASCII format
          CALL TQRFIL(NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR loading data-file.'
             ...
          ENDIF

C Close data-file
          CLOSE(10)

In terms of the FORTRAN unit number, the same notes apply as above: By default, TQRFIL expects the data-file to be opened with unit number 10, this being the reason for both the OPEN and CLOSE statements above referring to this particular unit number. It is also possible to use a non-default unit number for this purpose, in which case ChemApp needs to be told about this using TQCIO. ChemApp will accept unit numbers less then 11 and larger than 19. If ChemApp is part of a larger program, it is important to make sure that the unit number used to open the data-file is free, be it unit number 10 or a non-default value. Again, the FORTRAN subroutine INQUIRE is helpful in this case.

1.11.3   Binary data-files (DEPRECATED)

Note:The binary data-file format is a legacy format that has been superceded by the transparent file format (see Transparent data-files below). If you still have files in this format, please contact GTT-Technologies to help you convert these files to the transparent file format, if necessary.

Binary thermochemical data-files for use with ChemApp are stored in a way which does not permit the end user to extract or change thermochemical data from the file. This is mainly done in cases where a license agreement with the supplier of the data does not permit the distribution in plain text format.

Due to the nature of the FORTRAN standard for writing binary data to files, or rather, the lack thereof, binary data-files are usually not portable across platforms, and in many case are not even portable between different compilers on the same platform (this problem is partially solved by using data-files in transparent format, see below). For the suppliers of binary data-files (in most cases this is GTT-Technologies), this means that the data-file has to be supplied for the very compiler and/or platform that the ChemApp customer uses. For the ChemApp user it means that care has to taken that the binary data-file supplied is only used with the proper compiler. If you try to load a binary data-file into ChemApp that was actually made for a different compiler, you typically will receive Error code 103 from TQRBIN.

The most common and recommended file extension for thermochemical data-files in binary format is .BIN. They are otherwise recognized by the fact that when inspected with a file-viewer, their contents are not humanly readable. It is important to realise that a binary data-file should never be edited manually, as it will render the file useless.

Due to the lack of portability of binary files across platforms and compilers, the support of thermochemical data-files in binary format will be discontinued in future versions of ChemApp. As of ChemApp version 4.0.0 the binary file format is superceded by the transparent file format (see Transparent data-files). If you are using ChemApp versions 4.0.0 and later with binary data-files, please contact GTT-Technologies to receive help in converting these data-files to the transparent format.

Using binary data-files (all programming languages)

For the same reasons as mentioned above (see ASCII data-files), a set of subroutines is provided to open and close binary data-files from FORTRAN and non-FORTRAN programs. These subroutines are TQOPNB and TQCLOS. It is important to realise that TQOPEN cannot be used to open binary data-files, as it will always open the data-file specified in ASCII mode. This of course does not affect the use of TQOPEN to create new ASCII files for writing, for instance for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).

As of ChemApp V4.0.0, the subroutines TQOPNB, and TQCLOS have been made part of the core code of ChemApp, and are thus available to all application languages, both FORTRAN and non-FORTRAN. We recommend using these subroutines also in FORTRAN application programs instead of calling the standard FORTRAN statements OPEN and CLOSE, if you are using ChemApp version 4.0.0 or later.

Using FORTRAN as an example, a thermodynamic data-file in ASCII format could be opened with the following code:

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

In case the opening of the data-file fails, TQOPNB will return with Error code 107, otherwise the data-file can now be loaded with TQRBIN and closed with TQCLOS:

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

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

Note especially that for binary data-files, TQRBIN needs to be used to load the data-file, not TQRFIL or TQRCST.

With respect to the unit numbers, please see the previous section (Chapter ASCII data-files) for explanatory notes, they apply equally to binary data-files.

Using binary data-files (FORTRAN programs)

In FORTRAN terms, binary data-files are usually called unformatted sequential files, and are opened with the standard FORTRAN OPEN statement, for instance with a sequence similar to the following:

C Open thermochemical data-file in binary format for reading
         OPEN(10, FILE='cosi.bin', STATUS='OLD', FORM='UNFORMATTED',
        *         IOSTAT=NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot open data-file.'
             ...
          ENDIF

Note that the specifier ACCESS= can be omitted, since its default value ACCESS='SEQUENTIAL' is the correct one in this case.

Another point to note in the code example above is that if the OPEN statement fails, NOERR does not contain a ChemApp error number (see List of Error Messages), but one returned directly by the FORTRAN run time library. For details, please see your FORTRAN compiler's manual.

The syntax introduced above for opening thermochemical data-files in binary format should be valid for all FORTRAN compilers on all platforms, but it is important to realise that the binary data-files themselves are usually not portable across platforms, and in many case not even among different compilers on the same platform.

To make the process of opening data-files even safer, the use of an appropriate call to the FORTRAN subroutine INQUIRE prior to the OPEN statement is recommended.

The opened file can then subsequently be loaded into ChemApp with TQRBIN, and closed with CLOSE:

C Read thermochemical data-file in binary format
          CALL TQRBIN(NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR loading data-file.'
             ...
          ENDIF

C Close data-file
          CLOSE(10)

Note especially that for binary data-files, TQRBIN needs to be used to load the data-file, not TQRFIL or TQRCST.

With respect to the unit numbers, please see the previous section (ASCII data-files) for explanatory notes, they apply equally to binary data-files.

1.11.4   Transparent data-files

A drawback of the FORTRAN language is the lack of a standard for binary files. This is the main reason why ChemApp data-files in binary format are not portable (see above). To at least partially overcome this problem, the transparent data-file format has been created. Using transparent data-files, approximately 90% of the portability problems on Windows platforms can be overcome.

Transparent data-files differ from data-files in ASCII and binary format in that they have a header which precedes the actual thermochemical data, and which for instance contains information about the data itself, as well as the creator and user of the data-file (see TQGTRH).

On systems running Microsoft Windows, transparent data-files can be used by programs which contain a version of ChemApp that was compiled with any of the following compilers:

  • Lahey FORTRAN
  • Microsoft PowerStation FORTRAN
  • Digital Visual FORTRAN
  • Compaq Visual FORTRAN
  • Intel Visual FORTRAN

Since these compilers are also used to produce FactSage, and all ChemApp DLLs for the Windows platforms (ChemApp DLLs for use with Microsoft Visual Basic and Visual C++, as well as Borland Delphi), this for instance enables a transparent data-file written by FactSage to be read by ChemSheet without modification.

While transparent data-files can be created by GTT-Technologies for every platform for which ChemApp is available, one thing to remember is that transparent data-files created for the Windows-based compilers listed above will very likely not be directly usable on a Unix system, for instance. If you attempt to read a transparent data-file under such a condition, you will typically get Error code 161. These portability issues will be solved with the future portable data-file format.

Transparent data-files, like binary data-files, are stored in a way that does not permit the end user to extract or change thermochemical data from the data-file. This is mainly done in cases where a license agreement with the supplier of the data does not permit the distribution in plain text format.

The most common and recommended file extension for thermochemical data-files in transparent format is .CST. They are otherwise recognized by the fact that when inspected with a file-viewer, their contents are not humanly readable, apart from a comment in the file header: This is a ChemSage transparent data file... . It is important to realise that a transparent data-file should never be edited manually, since ChemApp will refuse to load a modified transparent data-file.

On Windows systems, transparent data-files created for use with any of the compilers listed above can also be identified by examining the very first four characters, the magic bytes, of the file, which are always CSTR.

Using transparent data-files (all programming languages)

As with data-files in ASCII (see ASCII data-files) and binary (see Binary data-files (DEPRECATED)) formats, the use of a set of subroutines is provided to open and close transparent data-files from FORTRAN and non-FORTRAN programs. These subroutines are TQOPNT and TQCLOS. It is important to realise that TQOPEN cannot be used to open transparent data-files, as it will always open the data-file specified in ASCII mode. This of course does not affect the use of TQOPEN to create new ASCII files for redirecting error messages, as well as for storing the output of TQSHOW, TQCEL, and TQMAPL to files (see TQCIO).

Using FORTRAN as an example, opening a thermodynamic data-file in transparent format would thus be similar to the following piece of code:

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

In case the opening of the data-file fails, TQOPNT will return with Error code 107, otherwise the data-file can now be loaded with TQRCST and closed with TQCLOS:

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

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

Note especially that for transparent data-files, TQRCST needs to be used to load the data-file, not TQRFIL or TQRBIN.

With respect to the unit numbers, please see the previous section (ASCII data-files) for explanatory notes, they apply equally to transparent data-files.

Using transparent data-files (FORTRAN programs)

In FORTRAN programs, transparent data-files can be both opened using the ChemApp subroutine TQOPNT as described above, as well as using the standard FORTRAN OPEN statement. While the use of the FORTRAN statement OPEN may be more flexible for this purpose, its calling syntax when used to open a transparent data-file is compiler-dependent. Note also that as with opening data-files in ASCII and binary format, using FORTRAN's OPEN may not work if you are using ChemApp in the form of a DLL. Unless you need the added flexibility of the OPEN statement, we thus recommend using TQOPNT as described above.

Here are some examples of how to open a transparent data-file using the OPEN statement on various compilers. See below for a compiler-independent version that uses TQOPNT.

Note that if any of the OPEN statement fails in the examples below, the error code returned in NOERR does not contain a ChemApp error number (see List of Error Messages), but an error code returned directly by the FORTRAN run time library. For details, please see your FORTRAN compiler's manual.

To make the process of opening data-files even safer, the use of an appropriate call to the FORTRAN statement INQUIRE prior to the OPEN statement is recommended.

Lahey FORTRAN

Under Lahey FORTRAN, the specifier ACCESS='TRANSPARENT' is used to open ChemApp transparent data-files, hence we named these files transparent data-files.

C Open thermochemical data-file in transparent format for reading
C (Lahey version)
         OPEN(10,FILE='cosi.cst', STATUS='OLD', ACCESS='TRANSPARENT',
        *         IOSTAT=NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot open data-file.'
             ...
          ENDIF

Note that there is no FORM='...' specifier used.

The data-file is then subsequently read using TQRCST and closed using CLOSE (see below).

Unix FORTRAN and other FORTRAN compilers

The ACCESS='TRANSPARENT' and FORM='BINARY' specifiers described above are not standard FORTRAN, so many compilers do not implement them. This is the case for many, if not all, FORTRAN compilers on Unix systems, and includes for instance the Gnu g77 FORTRAN compiler on Linux systems. You thus cannot use transparent data-files with these non-Windows compilers, unless they have been specially created for use with them. In most cases this is done by GTT-Technologies.

If you were supplied with such a data-file, open it using FORM='UNFORMATTED', just like a binary data-file:

C Open thermochemical data-file in transparent format for reading
C (Version for Unix FORTRAN and other FORTRAN compilers, e.g. g77)
         OPEN(10, FILE='cosi.cst', STATUS='OLD', FORM='UNFORMATTED',
        *         IOSTAT=NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot open data-file.'
             ...
          ENDIF

The data-file is then subsequently read using TQRCST and closed using CLOSE (see below).

All FORTRAN compilers: TQOPNT

If you need your FORTRAN programs to compile under various compilers and/or platforms, and do not need the added flexibility of the generic FORTRAN OPEN statement, you avoid any compiler-dependent code by using the ChemApp subroutine TQOPNT.

C Open thermochemical data-file in transparent format for reading
C (Version for all FORTRAN compilers using TQOPNT)
          CALL TQOPNT('cosi.cst', 10, NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot open data-file.'
             STOP
          ENDIF

Again, the syntax introduced above for opening thermochemical data-files in transparent format using TQOPNT is valid for all FORTRAN compilers on all platforms, but it is important to realise that the transparent data-files themselves are usually not fully portable across platforms, and in many case not even among different compilers on the same platform, with the notable exception of the Lahey FORTRAN, Microsoft PowerStation FORTRAN, Digital Visual FORTRAN, and Compaq Visual FORTRAN compilers on Windows platforms.

With the respect to the unit numbers, please see the previous chapter (ASCII data-files) for explanatory notes, they apply equally to transparent data-files.

The opened transparent data-file can then subsequently be loaded into ChemApp with TQRCST, and closed with TQCLOS:

C Read thermochemical data-file in transparent format
          CALL TQRCST(NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR loading data-file.'
             ...
          ENDIF

C Close data-file
          CALL TQCLOS(10, NOERR)
          IF (NOERR .NE. 0) THEN
             WRITE(,) 'ERROR: Cannot close data-file.'
             STOP
          ENDIF

Note especially that for transparent data-files, TQRCST needs to be used to load the data-file, not TQRFIL or TQRBIN.


1.12   Example thermochemical data-files

ChemApp comes with a set of example data-files. This should enable you to start programming with ChemApp right away, even if you do not already have specific thermochemical data-files for your particular application. Some of the example data-files included in the ChemApp distribution are also used by the example programs which are part of this documentation. Below you find a description of all the example data-files included, together with their potential applications, as well as relevant temperature and composition application ranges.

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

Chemical system:
 C-O-Si
Potential applications:
 Phase equilibria and thermodynamic properties, for instance relating to Si production in a Si-arc furnace.
Temperature range:
 RT - 3500K
Composition range:
 All
Comments:COSI.DAT is the file most widely used for the code examples in this manual. It contains a gaseous mixture phase and several pure stoichiometric phases.

View directory of data-file

View data-file

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

Chemical system:
 C-N-O
Potential applications:
 Combustion equilibria and thermodynamic properties of the gas species and condensed phases.
Temperature range:
 All
Composition range:
 All
Comments:This data-file contains 28 gas constituents as well as solid carbon and diamond.

View directory of data-file

View data-file

1.12.3   FEC.DAT (System Fe-C)

Chemical system:
 Fe-C
Potential applications:
 Phase equilibria; phase diagram, also metastable with cementite; thermodynamic properties of the phases and their constituents.
Temperature range:
 RT - 2500K
Composition range:
 All
Comments:See comment section at the end of the data-file (FEC.DAT data-file )

View directory of data-file

View data-file

1.12.4   FEMGSIO4.DAT (System Fe2SiO4-Mg2SiO4)

Chemical system:
 System Fe2SiO4-Mg2SiO4
Potential applications:
 Solid T-P-composition equilibria and thermal properties in the system Fe2SiO4-Mg2SiO4 for pressures between 1 bar and 300 kbar.
Temperature range:
 Below liquidus
Composition range:
 All
Comments:This data-file contains pressure-dependent Gibbs energy terms.

View directory of data-file

View data-file

1.12.5   PBSN.DAT (System Pb-Sn)

Chemical system:
 Pb-Sn
Potential applications:
 Phase equilibria and all thermodynamic properties in the binary system Pb-Sn.
Temperature range:
 RT - 1500 K
Composition range:
 All
Comments:This data-file can be used to calculate the Pb-Sn binary phase diagram, as it is valid over the whole composition range and contains the descriptions of all necessary condensed phases. Due to the inherent metastable miscibility gap, the BCT_A5 phase (Sn-terminal solution) is present twice.

View directory of data-file

View data-file

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

Chemical system:
 Na-Cl-C-O-H
Potential applications:
 Chemical equilibria in natural waters with sodium.
Temperature range:
 298.15 K
Composition range:
 Aqueous solutions with up to 10 molal dissolved salts.
Comments:This data-file contains an aqueous phase modelled according to the Pitzer formalism. It contains charged species in the aqueous phase, which is the reason why this data-file actually has a sixth system component, the electron.

View directory of data-file

View data-file

1.12.7   WATER.DAT (System O-H-EA)

Chemical system:
 O-H-EA
Potential applications:
 Gas-Liquid-Solid equilibria of water with non-ideal gas and liquid with phase internal equilibria.
Temperature range:
 From approx. 270 K to about 3000 K
Composition range:
 Aqueous phase with gas and solid.
Comments:This file serves as an example of input for non-ideal gas using Tsonopoulos data (Tc,Pc,Vc, acentric factor and dipol moment) as well as Ideal Water solution with neutral and ionic species.

View directory of data-file

View data-file

1.12.8   SUBL-EX.DAT (System Co-Cr-Fe)

Chemical system:
 

Co-Cr-Fe (incomplete)

Potential applications:
 

SIGMA-BCC equilibria

Temperature range:
 

900 - 1200 K

Composition range:
 

Iron-rich or chromium-rich.

Comments:

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

Please note that this sample data-file is not a comprehensive data-file for the system Co-Cr-Fe. Phases such as FCC and HCP have been omitted to keep it short.

View directory of data-file

View data-file


2   Initialising the Interface and Reading a Data-file

The first steps when programming ChemApp are

Initialisation of the interface is done with a call to TQINI. The subroutine TQRFIL enables a thermodynamic data-file in ASCII format to be read. In case you have data-files supplied in binary or transparent format, use TQRBIN or TQRCST, respectively, instead. After loading a transparent data-file, TQGTRH retrieves information from the transparent file header.

TQCPRT retrieves a copyright message for ChemApp, while TQVERS gets its version number. TQLITE can be used to determine whether the ChemApp library used is ChemApp light or the regular version of ChemApp. TQSIZE retrieves a number of parameters which indicate the sizes of a number of internal arrays of the version of ChemApp used, while TQUSED returns a similar set of values for the currently loaded thermochemical system.

The subroutines TQCIO and/or TQCSU need to be called if any default settings relating to input/output or system units are to be modified. Similarly, TQGIO and TQGSU are used to determine the current values of these options.

TQOPNA, TQOPNB, TQOPNT, TQCLOS, and TQOPEN make sure that when programming in a language other than FORTRAN, files used by ChemApp are opened and closed using the correct FORTRAN unit numbers. Even when programming in FORTRAN, the use of these subroutines over FORTRAN's OPEN and CLOSE is still strongly recommended.

When opening an ASCII output file for writing with TQOPEN, for instance to store ChemSage/ChemApp result tables, TQWSTR can be used to write user-defined text to the same file.

As of Version 4.0.0, each ChemApp library contains information on the license holder (see TQGTID and TQGTNM), and can be identified via a short signature string (see TQGTPI).

TQCONF was added in version 6.3.4 to allow certain configuration options to be set.

All the subroutines used in these procedures are summarised in Table ChemApp subroutines for the initialisation stage, and described in more detail below.

ChemApp subroutines for the initialisation stage
Subroutine Function
TQINI Initialises ChemApp
TQCPRT Gets copyright message
TQVERS Gets the ChemApp version number
TQLITE Checks whether ChemApp light is used
TQGTID Gets the user ID of the license holder of ChemApp
TQGTNM Gets the name of the license holder of ChemApp
TQGTPI Gets the ID of the program
TQGTHI Gets the HASP dongle type and id
TQGTED Gets the expiration date of the ChemApp license
TQCONF Sets a configuration option
TQSIZE Gets the internal array dimensions of ChemApp
TQUSED Gets the dimensions of the currently loaded thermochemical system
TQGIO Gets the value of an output option
TQCIO Changes the value of an output option
TQRFIL Reads a thermodynamic data-file in ASCII format
TQRBIN Reads a thermodynamic data-file in binary format
TQRCST Reads a thermodynamic data-file in transparent format
TQOPEN Opens a file
TQWSTR Writes a character string to the units associated with 'LIST' or 'ERROR'
TQOPNA Opens a thermochemical data-file in ASCII format
TQOPNB Opens a thermochemical data-file in binary format
TQOPNT Opens a thermochemical data-file in transparent format
TQCLOS Closes a file
TQGTRH Retrieves information stored in the header of a transparent file
TQGSU Gets a system unit
TQCSU Changes a system unit

Default values and units
Subroutine Function
Temperature 1000 K
Pressure 1 bar
Composition No incoming amounts, no streams
System units bar, dm3, Kelvin, Joule, mol

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)

Name Type Value set on call or returned
NOERR INTEGER Returns an error number

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

Example

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

      INTEGER NOERR

! Initialise ChemApp
      CALL TQINI(NOERR)

      END


C:
/* 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)

Name Type Value set on call or returned
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
This program contains ChemApp
Copyright GTT-Technologies, Kaiserstrasse 100, D-52134 Herzogenrath, Germany
http://www.gtt-technologies.de


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
NVERS INTEGER Returns the version number of ChemApp
NOERR INTEGER Returns an error number

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


Example

Fortran:
! 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
Output:
This program has been compiled with ChemApp version  645


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
ISLITE INTEGER Returns 1 for ChemApp light, 0 for ChemApp
NOERR INTEGER Returns an error number

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.


Example

Fortran:
! 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
Output:
This application program has been linked against
the regular version of ChemApp.


C:
/* 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;
}
Output:
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)

Name Type Value set on call or returned
ID CHARACTER Returns the user ID (255 chars)
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
Licensee's user ID: 5001
Licensee's name   : GTT - Technologies
Program ID        : CAFU
This ChemApp version does not require a HASP hardware key (dongle)


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
NAME CHARACTER Returns the name (80 chars)
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
NAME CHARACTER Returns the program ID
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
HASPT CHARACTER Returns the HASP dongle type
HASPID INTEGER Returns the HASP dongle id
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
EDMON INTEGER Returns the month part of the expiration date
EDYEAR INTEGER Returns the year part of the expiration date
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
OPTION CHARACTER Sets configuration option
VALUEA INTEGER Sets configuration value A
VALUEB INTEGER Sets configuration value B
VALUEC INTEGER Sets configuration value C
NOERR INTEGER Returns an error number

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.


Example

Fortran:
! 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)
Output:
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)
Output:
*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)
Output:
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)
Output:
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)
Output:
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)
Output:
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


C:
/* 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);
Output:
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);
Output:
*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);
Output:
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);
Output:
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);
Output:
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);
Output:
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;

}

Possible options for TQCONF
Option Meaning Comment
E Semi-automatic charge balance correction In order to have ChemApp set the amount of a specific electron to zero before every equilibrium calculation, set VALUEA to the electron's system component index number. In order to set the amount of all electrons to zero, set VALUEA to zero. This will affect all system components with names starting with 'e(', 'E(', or 'EA'

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)

Name Type Value set on call or returned
NA INTEGER Returns the maximum number of constituents
NB INTEGER Returns the maximum number of system components
NC INTEGER Returns the maximum number of mixture phases
ND INTEGER Returns the maximum number of excess Gibbs energy coefficients for a mixture phase
NE INTEGER Returns the maximum number of excess magnetic coefficients for a mixture phase
NF INTEGER Returns the maximum number of sublattices for a mixture phase
NG INTEGER Returns the maximum number of constituents of a sublattice
NH INTEGER Returns the maximum number of oxide constituents of a phase described by the Gaye-Kapoor-Frohberg or modified quasichemical formalisms
NI INTEGER Returns the maximum number of Gibbs energy/heat capacity equations for a constituent
NJ INTEGER Returns the maximum number of Gibbs energy/heat capacity equations
NK INTEGER Returns the maximum number of constituents with P,T-dependent molar volumes
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
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


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
NA INTEGER Returns the maximum number of constituents
NB INTEGER Returns the maximum number of system components
NC INTEGER Returns the maximum number of mixture phases
ND INTEGER Returns the maximum number of excess Gibbs energy coefficients for a mixture phase
NE INTEGER Returns the maximum number of excess magnetic coefficients for a mixture phase
NF INTEGER Returns the maximum number of sublattices for a mixture phase
NG INTEGER Returns the maximum number of constituents of a sublattice
NH INTEGER Returns the maximum number of oxide constituents of a phase described by the Gaye-Kapoor-Frohberg or modified quasichemical formalisms
NI INTEGER Returns the maximum number of Gibbs energy/heat capacity equations for a constituent
NJ INTEGER Returns the maximum number of Gibbs energy/heat capacity equations
NK INTEGER Returns the maximum number of constituents with P,T-dependent molar volumes
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Legal input/output options used by TQGIO and TQCIO
IVAL INTEGER Returns the current unit number or the index for the language used
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
The thermochemical data will be read from the file associated with unit  10


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Legal input/output options used by TQGIO and TQCIO
IVAL INTEGER Set to a legal unit number, or to a language index
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
Fel nummer: 104
En fil med termodynamiska data maste foerst inlaesas
Felet upptraedde sedan "TQNOP " anropats


C:
/* 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;

}
Output:
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)

Name Type Value set on call or returned
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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


C:
/* 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)

Name Type Value set on call or returned
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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


C:
/* 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)

Name Type Value set on call or returned
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
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


C:
         /* 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;

}
Output:
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)

Name Type Value set on call or returned
NAME CHARACTER Set to the filename of the data-file to open
UNIT CHARACTER Set to the unit number under which it should be opened
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
OPTION CHARACTER Set to either 'LIST' or 'ERROR'
TEXT CHARACTER Set to a character string
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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


C:
/* 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)``

Name Type Value set on call or returned
NAME CHARACTER Set to the filename of the ASCII data-file to open
UNIT CHARACTER Set to the unit number under which it should be opened
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
NAME CHARACTER Set to the filename of the binary data-file to open
UNIT CHARACTER Set to the unit number under which it should be opened
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
NAME CHARACTER Set to the filename of the transparent data-file to open
UNIT CHARACTER Set to the unit number under which it should be opened
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
UNIT CHARACTER Set to the unit number under which the data-file was previously opened using TQOPEN
NOERR INTEGER Returns an error number

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

Example

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)

Name Type Value set on call or returned
VER INTEGER Returns the version number of the transparent file header format
NWP CHARACTER Returns the name of the program which wrote the data-file (40 chars)
VNW Array of 3 of INTEGER Returns the version number of the program which wrote the data-file
NRP CHARACTER Returns the ID(s) of the programs which are permitted to read the data-file (40 chars)
VNR Array of 3 of INTEGER Returns the minimum version number of the reading program necessary to load the data-file
DTC Array of 6 of INTEGER Returns the creation date of the data-file
DTE Array of 6 of INTEGER Retuns the expiry date of the data-file
ID CHARACTER Returns the user ID(s) of the license holder(s) who are permitted to read this data-file (255 chars)
USR CHARACTER Returns the name(s) of the license holder(s) who are permitted to read this data-file (80 chars)
REM CHARACTER Returns the remark (80 chars)
NOERR INTEGER Returns an error number

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:

VER:

This single integer indicates the version number of the transparent file header format. It can usually be ignored by the programmer.

NWP:

This string (40 characters long) contains the name of the program that wrote the data-file. It can consist of one of the 4-letter identifiers used in the NRP field below, or a real name like "FactSage".

VNW:

This array of 3 integers is used to pass the version number of the program that wrote the data-file. In the case of FactSage 5.0, the three integers in this array would be 5, 0, and 0.

NRP:

This string (40 characters long) contains one or more program IDs and is used to determine which programs are capable and authorized to read the data-file. The program IDs used are 4-letter mnemonic codes that identify a particular program or library (i.e. ChemApp). For instance, if a data-file is meant to be used with the full version of ChemApp, NRP would be set to CAFU, if it is intended for ChemApp light instead, it would be set to CALI. NRP can also contain more than one program IDs, and also program IDs which contain wildcards, in order to make the data-file available to more than one kind of program or library.

This field can usually be ignored by the programmer, as ChemApp itself determines whether it is able and authorized to read a particular data-file.

VNR:

If applicable, this array of 3 integers contains the required minimum version number of the program that the data-file is intended for. If, for instance, a data-file contains thermochemical data for a mixture phase that requires a solution model only present in ChemApp version V3.5.0 and later, the three integers would be 3, 5, and 0. This array can usually be ignored by the programmer, as ChemApp itself determines whether it is able to read the data-file based on this version number. If the first integer has a value of -1, NRP can be ignored altogether.

DTC:

This array of 6 integers contains the creation date and time of the data-file. The 6 integers indicate the year, month, day, hour, minute, and second of the creation of the data-file. Note that this information is independent of the particular time stamp of the data-file as reported by the operating system.

DTE:

The 6 integers in this array (same format as DTC) indicate the expiry date of the data-file.

ID:

This string (255 characters long) contains one or more user IDs and is used to determine whether ChemApp is authorized to load the data-file. There are three typical scenarios as to what ID contains and how it is interpreted:

  1. The most common case is that a user has a license for a program like FactSage, which can be used to create transparent data-files. When he creates such a data-file, his user ID, which is stored in the FactSage program, is transferred to the ID field of the transparent file. If this user also has a license for ChemApp, he can read this transparent data-file with all programs he creates using his version of ChemApp. The same transparent data-file on the other hand cannot be read by a ChemApp version which operates under a different license, and thus a different user id. Likewise, he will normally be unable to read a transparent data-file created by a FactSage user with a different user ID.
  2. For users who do not create their own transparent data-files using FactSage or similar programs, but need to be supplied with a transparent customised data-file for use with ChemApp, GTT-Technologies will create such a file, in which case ID will contain the user ID of the ChemApp customer.
  3. As with the NRP field, this field may also contain several user IDs and user IDs with wildcards. This is used to grant a group of users who have different IDs access to the same particular data-file. This will also enable a group of users, who might work jointly on data assessment, to create transparent data-files and share them within the group.
USR:

This string (80 characters long) contains the user name associated with the user ID stored in the previous field (ID). Other than THFID, it is not used to for authorisation checks, but only for information purposes.

REM:

This string (80 characters long) contains text that the program writing the transparent data-file may use to store any kind of remark.

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

Example

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)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Units permitted in ChemApp
UNIT CHARACTER Returns a string as shown in Table Units permitted in ChemApp
NOERR INTEGER Returns an error number

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

Example

Fortran:
! 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
Output:
Default system units:
Pressure unit: bar
Volume unit: dm3
Temperature unit: K
Energy unit: J
Amount unit: mol


C:
/* Program cac8 */
/* Get and display the system units */

#include "cacint.h"

int main()
{
  LI noerr;
  char unit[TQSTRLEN];

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

  /* Get default system units */
  printf("Default system units:\n");

  tqgsu("Pressure",unit,&noerr);
  printf("Pressure unit: %s\n", unit);

  tqgsu("Volume",unit,&noerr);
  printf("Volume unit: %s\n", unit);

  tqgsu("Temperature",unit,&noerr);
  printf("Temperature unit: %s\n", unit);

  tqgsu("Energy",unit,&noerr);
  printf("Energy unit: %s\n", unit);

  tqgsu("Amount",unit, &noerr);
  printf("Amount unit: %s\n", unit);


  return 0;

}
Output:
Default system units:
Pressure unit: bar
Volume unit: dm3
Temperature unit: K
Energy unit: J
Amount unit: mol

2.26   TQCSU

CHANGE-SYSTEM-UNIT

Use TQCSU to change the default or selected system unit for a specified quantity.

Synopsis

FORTRAN:
CALL TQCSU(OPTION,UNIT,NOERR)
C:
tqcsu(option,unit,&noerr);
Pascal:
tqcsu(option,unit,noerr);
Basic:
Call tqcsu(option,unit,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Units permitted in ChemApp
UNIT CHARACTER Returns a string as shown in Table Units permitted in ChemApp
NOERR INTEGER Returns an error number

OPTION and UNIT are both character inputs identifying a quantity and a unit, respectively. The selected units remain as they are until changed again using TQCSU, or reset to their defaults using TQINI or TQREMC. The first unit mentioned within each group in Table Units permitted in ChemApp is the default unit for a quantity.

See also
TQGSU

Example

Fortran:
! Change system units

      PROGRAM CAF9
      IMPLICIT NONE

      INTEGER NOERR

! Initialise ChemApp
      CALL TQINI(NOERR)

! Change system units
! Changing pressure unit to torr
      CALL TQCSU('Pressure ','torr ', NOERR)

! Changing volume unit to cubic feet
      CALL TQCSU('Volume ','ft3 ', NOERR)

! Changing temperature unit to Fahrenheit
      CALL TQCSU('Temperature ','F ', NOERR)

! Changing energy unit to Btu
      CALL TQCSU('Energy ','Btu ', NOERR)

! Changing amount unit to pound
      CALL TQCSU('Amount ','pound ', NOERR)

      END


C:
/* Program cac9 */
/* Change system units */

#include "cacint.h"

int main()
{
  LI noerr;

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

  /* Change units */
  /* Changing pressure unit to torr */
  tqcsu("Pressure","torr", &noerr);

  /* Changing volume unit to cubic feet */
  tqcsu("Volume","ft3", &noerr);

  /* Changing temperature unit to Fahrenheit */
  tqcsu("Temperature","F", &noerr);

  /* Changing energy unit to Btu */
  tqcsu("Energy","Btu", &noerr);

  /* Changing amount unit to pound */
  tqcsu("Amount","pound", &noerr);

  return 0;

}

Units permitted in ChemApp (TQGSU and TQCSU)
Quantity Unit Comment
Pressure bar P/bar
  atm P/atm = P/bar/1.01325
  Pa P/Pa = P/bar/0.00001
  kPa P/kPa = P/bar/0.01
  psi P/psi = P/bar/0.06894757
  torr P/torr = P/bar x 1.01325/760
Volume dm3 V/dm3
  cm3 V/cm3 = V/dm3/0.001
  m3 V/m3 = V/dm3/1000
  ft3 V/ft3 = V/dm3/28.316846592
  in3 V/in3 = V/dm3/0.016387064
Temperature K T/K
  C T/C = (T/K - 273.15)
  F T/F = 1.8 x (T/K - 273.15)+32
Energy J E/J
  cal E/cal = E/J/4.184
  Btu E/Btu = E/J/1055.06
  kWh E/kWh = E/J/3,600,000
Amount mol M/mol
  gram M/gram
  kg M/gram/1,000
  tonne M/gram/1,000,000
  pound M/gram/453.59237

3   Handling System Data in ChemApp

Two aspects related to system data have to be considered when programming ChemApp:


3.1   Identifying phases, constituents, and components

In ChemApp, phases, phase constituents, and system components in a thermodynamic data-file are automatically numbered sequentially (see also Definition of terms). Phases are numbered in the order gas, condensed mixtures, and finally stoichiometric condensed phases. Phase constituents are numbered starting from one for each phase.

Internally, ChemApp handles phases, phase constituents, and system components using these index numbers, not their names. For this purpose, ChemApp provides a number of subroutines which let you determine the index number associated with a name, and vice versa. Most routines in this group fall into this category.

The total number of components and phases in the system, or constituents in a phase can be obtained by calling TQNOSC, TQNOP, and TQNOPC, respectively. The index number of each system component, phase, and phase constituent can be found by calling TQINSC, TQINP, and TQINPC, and these numbers can be converted back to corresponding names using TQGNSC, TQGNP, and TQGNPC, respectively.

TQSTSC retrieves the stoichiometry of a system component, while TQSTPC does the same for a phase constituent. TQMODL gets the model name of a phase, and TQPCIS checks whether a phase constituent is permitted to be used as an incoming species. TQCSC is used to define a new set of system components.

ChemApp provides four subroutines that retrieve information about sublattices and sublattice constiuents of phases that are modelled according to the sublattice formalism. TQINLC gets the index number of a specified sublattice constituent name, whereas TQGNLC does the opposite, it gets the name for a specified sublattice constituent from its index number. TQNOSL retrieves the number of sublattices for a specified phase, and TQNOLC the number of sublattice constituents for a specified sublattice.

The ChemApp subroutines for obtaining index numbers and other system data are presented in Table ChemApp subroutines for identifying system data.


ChemApp subroutines for identifying system data
Subroutine Function
TQINSC Gets the index number for a system component
TQGNSC Gets the name for a system component
TQCNSC Changes the name of a system component
TQNOSC Gets the number of system components
TQSTSC Gets the stoichiometry of a system component
TQCSC Changes the system components
TQINP Gets the index number for a phase
TQGNP Gets the name for a phase
TQMODL Gets the model name for a phase
TQNOP Gets the number of phases
TQINPC Gets the index number for a phase constituent
TQGNPC Gets the name for a phase constituent
TQPCIS Checks if a phase constituent is permitted as incoming species
TQNOPC Gets the number of phase constituents
TQSTPC Gets the stoichiometry of a phase constituent
TQCHAR Gets the charge of a phase constituent
TQINLC Gets the index number for a sublattice constituent
TQGNLC Gets the name for a sublattice constituent
TQNOSL Gets the number of sublattices
TQNOLC Gets the number of sublattice constituents

3.2   TQINSC

GET-INDEX-NUMBER-OF-SYSTEM-COMPONENT

Use TQINSC to get the index number of a specified system component.

Synopsis

FORTRAN:
CALL TQINSC(NAME,INDEXS,NOERR)
C:
tqinsc(name,&indexs,&noerr);
Pascal:
tqinsc(name,indexs,noerr);
Basic:
Call tqinsc(name,indexs,noerr)

Name Type Value set on call or returned
NAME CHARACTER Set to a component name
INDEXS INTEGER Returns the index number for the component
NOERR INTEGER Returns an error number

The input variable NAME is permitted to have a maximum length of 24 characters. The returned value for INDEXS is normally used as input to other ChemApp subroutines. The index number stays the same for a specific component as long as the system components remain unchanged (see TQCSC).

See also
TQNOSC, TQGNSC, TQSTSC, TQCSC, TQCNSC

Example

Fortran:
! Handling system components

      PROGRAM CAF10
      IMPLICIT NONE

      INTEGER NOERR, NSCOM, I
      CHARACTER FNAME*12, SCNAME*24


! Initialise ChemApp
      CALL TQINI(NOERR)

      FNAME = 'cosi.dat'

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

! Read data-file
      CALL TQRFIL(NOERR)

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

! Get the number of system components
      CALL TQNOSC(NSCOM, NOERR)

      WRITE(*,FMT='(A,I3)') 'Number of system components ' //
     *                      'in file ' // FNAME // ':', NSCOM
Output:
Number of system components in file cosi.dat    :  3

! Print the names of all system components
      WRITE(*,FMT='(A)') 'Names of system components:'

      DO I=1, NSCOM
         CALL TQGNSC(I, SCNAME, NOERR)
         WRITE(*,FMT='(I2,A)') I, ': ' // SCNAME
      ENDDO
Output:
Names of system components:
 1: C
 2: O
 3: Si

! Change the names of the system components

      CALL TQCNSC(1, 'Carbon ', NOERR)
      CALL TQCNSC(2, 'Oxygen ', NOERR)
      CALL TQCNSC(3, 'Silicon ', NOERR)

! Print the new names of all system components
      WRITE(*,FMT='(A)') 'New names of system components:'

      DO I=1, NSCOM
         CALL TQGNSC(I, SCNAME, NOERR)
         WRITE(*,FMT='(I2,A)') I, ': ' // SCNAME
      ENDDO
Output:
New names of system components:
 1: Carbon
 2: Oxygen
 3: Silicon

! Get the index number of a system component
      CALL TQINSC('Carbon ', I, NOERR)
      WRITE(*,FMT='(A,I2,A)') 'Carbon is system component no. ',
     *                        I, ' in file ' // FNAME


      END
Output:
Carbon is system component no.  1 in file cosi.dat


C:
/* Program cac10 */
/* Handling system components */

#include "cacint.h"

int main()
{
  LI noerr, nscom, i;
  char fname[13], scname[TQSTRLEN];


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

  strcpy(fname,"cosi.dat");

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

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

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

  /* Get the number of system components */
  tqnosc(&nscom, &noerr);

  printf("Number of system component in file %s: %li\n", fname, nscom);
Output:
Number of system component in file cosi.dat: 3

/* Print the names of all system components */
printf("Names of system components:\n");

for (i = 1; i <= nscom; i++) {
  tqgnsc(i, scname, &noerr);
  printf("%li: %s\n", i, scname);
}
Output:
Names of system components:
1: C
2: O
3: Si

/* Change the names of the system components */
tqcnsc(1, "Carbon", &noerr);
tqcnsc(2, "Oxygen", &noerr);
tqcnsc(3, "Silicon", &noerr);

/* Print the new names of all system components */
printf("New names of system components:\n");

for (i = 1; i <= nscom; i++) {
  tqgnsc(i, scname, &noerr);
  printf("%li: %s\n", i, scname);
}
Output:
New names of system components:
1: Carbon
2: Oxygen
3: Silicon

  /* Get the index number of a system component */
  tqinsc("Carbon", &i, &noerr);
  printf("Carbon is system component no. %li in file %s\n",
        i, fname);


  return 0;

}
Output:
Carbon is system component no. 1 in file cosi.dat

3.3   TQGNSC

GET-NAME-OF-SYSTEM-COMPONENT

Use TQGNSC to get the name for a specified system component.

Synopsis

FORTRAN:
CALL TQGNSC(INDEXS,NAME,NOERR)
C:
tqgnsc(indexs,name,&noerr);
Pascal:
tqgnsc(indexs,name,noerr);
Basic:
Call tqgnsc(indexs,name,noerr)

Name Type Value set on call or returned
INDEXS INTEGER Set to the index number for a component
NAME CHARACTER Returns the component name
NOERR INTEGER Returns an error number

INDEXS is integer input. The output variable NAME cannot exceed a maximum length of 24 characters.

See also
TQCNSC, TQNOSC, TQINSC, TQSTSC, TQCSC

Example

See
TQINSC

3.4   TQCNSC

CHANGE-NAME-OF-SYSTEM-COMPONENT

Use TQCNSC to change the name of a specified system component.

Added for ChemApp version 5.4.4

Synopsis

FORTRAN:
CALL TQCNSC(INDEXS,NAME,NOERR)
C:
tqcnsc(indexs,name,&noerr);
Pascal:
tqcnsc(indexs,name,noerr);
Basic:
Call tqcnsc(indexs,name,noerr)

Name Type Value set on call or returned
INDEXS INTEGER Set to the index number for a system component
NAME CHARACTER Set to the new system component name
NOERR INTEGER Returns an error number

INDEXS is integer input. The input character variable NAME cannot exceed a maximum length of 24 characters.

See also
TQGNSC, TQCHAR

Example

See
TQINSC

3.5   TQNOSC

GET-NUMBER-OF-SYSTEM-COMPONENTS

Use TQNOSC to get the total number of system components.

Synopsis

FORTRAN:
CALL TQNOSC(NSCOM,NOERR)
C:
tqnosc(&nscom,&noerr);
Pascal:
tqnosc(nscom,noerr);
Basic:
Call tqnosc(nscom,noerr)

Name Type Value set on call or returned
NSCOM INTEGER Returns the total number of components
NOERR INTEGER Returns an error number

NSCOM is normally used as an upper limit in loops over all system components. Note that NSCOM may be different from the total number of chemical elements in the system. It can be less when compounds are chosen as components, and greater when the system includes phase-internal electrons.

See also
TQINSC, TQGNSC, TQSTSC, TQCSC

Example

See
TQINSC

3.6   TQSTSC

GET-STOICHIOMETRY-OF-SYSTEM-COMPONENT

Use TQSTSC to get the stoichiometry and molecular mass of a system component.

Synopsis

FORTRAN:
CALL TQSTSC(INDEXS,STOI,WMASS,NOERR)
C:
tqstsc(indexs,&stoi,&wmass,&noerr);
Pascal:
tqstsc(indexs,stoi,wmass,noerr);
Basic:
Call tqstsc(indexs,stoi,wmass,noerr)

Name Type Value set on call or returned
INDEXS INTEGER Set to the index number for a component
STOI Array of DOUBLE PRECISION Returns the stoichiometry of the component
WMASS DOUBLE PRECISION Returns the molecular mass of the component
NOERR INTEGER Returns an error number

INDEXS is integer input. The array STOI needs to be declared large enough to hold at least as much DOUBLE PRECISION values as there are system components, see parameter NSCOM in TQNOSC. The component's full stoichiometry matrix is always returned through STOI, even if known from the component's index number. WMASS is the molecular mass of a component with index number INDEXS.

The contents of the array STOI are fairly trivial: The array is filled with zeros except for the element no. INDEXS, which has a value of 1.0. The reason for TQSTSC to return this array despite its redundant contents is to keep its calling syntax similar to that of TQSTPC. For more information on the stoichiometry matrix, see Definition of a stoichiometry matrix.

Note that the value for the molecular mass is returned in the current amount unit per mol. Since the default amount unit is also mol (see Table Units permitted in ChemApp), the result will always be 1.0, unless the amount unit is changed, for instance to gram.

See also
TQNOSC, TQINSC, TQGNSC, TQCSC

Example

See
TQCSC

3.7   TQCSC

CHANGE-SYSTEM-COMPONENTS

Use TQCSC to define a new set of system components.

Synopsis

FORTRAN:
CALL TQCSC(NAME,NOERR)
C:
tqcsc(name,&noerr);
Pascal:
tqcsc(name,noerr);
Basic:
Call tqcsc(name,noerr)

Name Type Value set on call or returned
NAME Vector (1-dim. array) of CHARACTER Set to component names
NOERR INTEGER Returns an error number

NAME is a character array input including the NSCOM names (see TQNOSC) of the new set of linearly independent system components. The array may contain names of previous components and of phase constituents, each with a maximum length of 24 characters. The new components are numbered in the order in which they are supplied in this call. Note that NSCOM can be different from the total number of chemical elements in the system. Components may include, for example, oxides only, or phase-internal electrons.

Note that defining a new set of system components is not possible for a system that contains one or more phases modeled using the SUBO (Two-sublattice order/disorder) formalism.

See also
TQNOSC, TQINSC, TQGNSC, TQSTSC

Example

Fortran:
! Changing system components

      PROGRAM CAF11
      IMPLICIT NONE

      INTEGER NOERR, ISIO2
      CHARACTER SCNAME*24, NEWSC(3)*24
      DOUBLE PRECISION WMASS, STOI(3)


! Initialise ChemApp
      CALL TQINI(NOERR)

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

! Read data-file
      CALL TQRFIL(NOERR)

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

! Set amount unit to gram, so we get the molecular mass in g/mol
      CALL TQCSU('Amount ', 'gram ', NOERR)

! Get the name of the first system component
      CALL TQGNSC(1, SCNAME, NOERR)

! Get its molecular mass
      CALL TQSTSC(1,STOI,WMASS,NOERR)

      WRITE(*,FMT='(A)') 'Name of first system component: ' // SCNAME
      WRITE(*,FMT='(A,G12.5)') 'Molecular mass in g/mol: ', WMASS
Output:
Name of first system component: C
Molecular mass in g/mol:   12.011

! Get the stoichiometry matrix of SiO2(quartz)
      CALL TQINP('SiO2(quartz) ',ISIO2,NOERR)
      CALL TQSTPC(ISIO2,1,STOI,WMASS,NOERR)

! Show the stoichiometry matrix of SiO2(quartz)
      WRITE(*,'(A)') 'Stoichiometry matrix of SiO2 ' //
     *     'in terms of system components C-O-Si:'
      WRITE(*,'(3G12.5)') STOI
Output:
Stoichiometry matrix of SiO2 in terms of system components C-O-Si:
  0.0000      2.0000      1.0000

! Change system components from C-O-Si to SiO-Si2C-CO2. Note that
! SiO-Si2C-CO2 form a system of three linearly independent components,
! just as the three elements C-O-Si do.
      NEWSC(1) = 'SiO'
      NEWSC(2) = 'Si2C'
      NEWSC(3) = 'CO2'

      CALL TQCSC(NEWSC,NOERR)

! Now get the name and molecular mass of the first system
! component again
      WRITE(*,FMT='(A)') 'After changing the system components:'

! Get the name of the first system component
      CALL TQGNSC(1, SCNAME, NOERR)

! Get its molecular mass
      CALL TQSTSC(1,STOI,WMASS,NOERR)
      WRITE(*,FMT='(A)') 'Name of first system component: ' // SCNAME
      WRITE(*,FMT='(A,G12.5)') 'Molecular mass in g/mol: ', WMASS
Output:
After changing the system components:
Name of first system component: SiO
Molecular mass in g/mol:   44.085

! Get and display the new stoichiometry matrix for SiO2(quartz):
      CALL TQSTPC(ISIO2,1,STOI,WMASS,NOERR)
      WRITE(*,'(A)') 'Stoichiometry matrix of SiO2 ' //
     *     'in terms of system components SiO-Si2C-CO2:'
      WRITE(*,'(3G12.5)') STOI


      END
Output:
Stoichiometry matrix of SiO2 in terms of system components SiO-Si2C-CO2:
  1.5000    -0.25000     0.25000


C:
/* Program cac11 */
/* Changing system components */

#include "cacint.h"

int main()
{
  LI noerr, iSiO2;
  char scname[TQSTRLEN], newsc[4][TQSTRLEN];
  DB wmass, stoi[3];


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

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

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

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

  /* Set amount unit to gram, so we get the molecular mass in g/mol */
  tqcsu("Amount", "gram", &noerr);

  /* Get the name of the first system component */
  tqgnsc(1, scname, &noerr);

  /* Get its molecular mass */
  tqstsc(1, stoi, &wmass, &noerr);

  printf("Name of first system component: %s\n", scname);
  printf("Molecular mass in g/mol: %g\n", wmass);
Output:
Name of first system component: C
Molecular mass in g/mol: 12.011

/* Get the stoichiometry matrix of SiO2(quartz) */
tqinp("SiO2(quartz)",&iSiO2,&noerr);
tqstpc(iSiO2,1,stoi,&wmass,&noerr);

/* Show the stoichiometry matrix of SiO2(quartz) */
printf("Stoichiometry matrix of SiO2 "
      "in terms of system components C-O-Si:\n");
printf("%6.3f  %6.3f  %6.3f\n",
      stoi[0], stoi[1], stoi[2]);
Output:
Stoichiometry matrix of SiO2 in terms of system components C-O-Si:
 0.000   2.000   1.000

/* Change system components from C-O-Si to SiO-Si2C-CO2. Note that
   SiO-Si2C-CO2 form a system of three linearly independent
   components, just as the three elements C-O-Si do. */

/* Note that when using C/C++ in contrast to FORTRAN (see above),
   the array of chars which is passed to tqcsc ("newsc" below) has
   to consist of one more string than there are system components,
   and this one extra string has to be empty. This is needed by
   ChemApp's C/C++ Interface to properly pass arrays of chars to
   FORTRAN */
strcpy(newsc[0],"SiO");
strcpy(newsc[1],"Si2C");
strcpy(newsc[2],"CO2");
strcpy(newsc[3],"");

tqcsc((CHP)newsc,&noerr);
/* Note that an explicit typecast has been used in the above call to
   tqcsc to avoid potential compiler warnings about newsc being an
   incompatible pointer type */

/* Now get the name and molecular mass of the first system
   component again */
printf("After changing the system components:\n");

/* Get the name of the first system component */
tqgnsc(1, scname, &noerr);

/* Get its molecular mass */
tqstsc(1, stoi, &wmass, &noerr);

printf("Name of first system component: %s\n", scname);
printf("Molecular mass in g/mol: %g\n", wmass);
Output:
After changing the system components:
Name of first system component: SiO
Molecular mass in g/mol: 44.0854

  /* Get and display the new stoichiometry matrix for SiO2(quartz): */
  tqstpc(iSiO2,1,stoi,&wmass,&noerr);
  printf("Stoichiometry matrix of SiO2 "
        "in terms of system components SiO-Si2C-CO2:\n");
  printf("%6.3f  %6.3f  %6.3f\n",
        stoi[0], stoi[1], stoi[2]);


  return 0;

}
Output:
Stoichiometry matrix of SiO2 in terms of system components SiO-Si2C-CO2:
 1.500  -0.250   0.250

3.8   TQINP

GET-INDEX-NUMBER-OF-PHASE

Use TQINP to get the index number for a specified phase.

Synopsis

FORTRAN:
CALL TQINP(NAME,INDEXP,NOERR)
C:
tqinp(name,&indexp,&noerr);
Pascal:
tqinp(name,indexp,noerr);
Basic:
Call tqinp(name,indexp,noerr)

Name Type Value set on call or returned
NAME CHARACTER Set to a phase name
INDEXP INTEGER Returns the index number for the phase
NOERR INTEGER Returns an error number

The input variable NAME cannot exceed 24 characters in length. For a mixture phase that might de-mix and is included twice in the data-file, '#1' and '#2' are automatically added to its name. The value of INDEXP returned is normally used as input to other ChemApp subroutines. The index number of a phase remains the same throughout an application.

See also
TQNOP, TQGNP, TQMODL

Example

Fortran:
! Handling phases

      PROGRAM CAF12
      IMPLICIT NONE

      INTEGER NOERR, NPHASE, I
      CHARACTER PNAME*24, MNAME*24


! Initialise ChemApp
      CALL TQINI(NOERR)

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

! Read data-file
      CALL TQRFIL(NOERR)

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

! Get the number of phases
      CALL TQNOP(NPHASE, NOERR)

      WRITE(*,FMT='(A,I3)') 'Number of phases in file cosi.dat: ',
     *     NPHASE
Output:
Number of phases in file cosi.dat:   8

! Print the names and models of all phases
      WRITE(*,FMT='(A)')
     *     'No.      Name of phase           Model'

      DO I=1, NPHASE
         CALL TQGNP(I, PNAME, NOERR)
         CALL TQMODL(I, MNAME, NOERR)
         WRITE(*,FMT='(I3,A30,A6)') I, PNAME, MNAME
      ENDDO
Output:
No.      Name of phase           Model
  1      GAS                     IDMX
  2      C                       PURE
  3      Si                      PURE
  4      SiC                     PURE
  5      SiO2(quartz)            PURE
  6      SiO2(tridymite)         PURE
  7      SiO2(cristobali)        PURE
  8      SiO2(liquid)            PURE

! Get the index number of a phase
      CALL TQINP('SiC ', I, NOERR)
      WRITE(*,FMT='(A,I2,A)') 'SiC is phase no. ', I,
     *     ' in file cosi.dat'


      END
Output:
SiC is phase no.  4 in file cosi.dat


C:
/* Program cac12 */
/* Handling phases */

#include "cacint.h"

int main()
{
  LI noerr, nphase, i;
  char pname[TQSTRLEN], mname[TQSTRLEN];


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

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

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

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

  /* Get the number of phases */
  tqnop(&nphase, &noerr);

  printf("Number of phases in file cosi.dat: %li\n", nphase);
Output:
Number of phases in file cosi.dat: 8

/* Print the names and models of all phases */
printf("No.  Name of phase            Model\n");

for (i = 1; i <= nphase; i++) {
  tqgnp(i, pname, &noerr);
  tqmodl(i, mname, &noerr);
  printf("%3li  %-24s %-6s\n", i, pname, mname);
}
Output:
No.  Name of phase            Model
  1  GAS                      IDMX
  2  C                        PURE
  3  Si                       PURE
  4  SiC                      PURE
  5  SiO2(quartz)             PURE
  6  SiO2(tridymite)          PURE
  7  SiO2(cristobali)         PURE
  8  SiO2(liquid)             PURE

  /* Get the index number of a phase */
  tqinp("SiC", &i, &noerr);
  printf("SiC is phase no. %li in file cosi.dat\n", i);


  return 0;

}
Output:
SiC is phase no. 4 in file cosi.dat

3.9   TQGNP

GET-NAME-PHASE

Use TQGNP to get the name for a specified phase.

Synopsis

FORTRAN:
CALL TQGNP(INDEXP,NAME,NOERR)
C:
tqgnp(indexp,name,&noerr);
Pascal:
tqgnp(indexp,name,noerr);
Basic:
Call tqgnp(indexp,name,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
NAME CHARACTER Returns the phase name
NOERR INTEGER Returns an error number

INDEXP is integer input. The output variable NAME cannot exceed 24 characters in length.

See also
TQNOP, TQINP, TQMODL

Example

See
TQINP

3.10   TQMODL

GET-MODEL-NAME-OF-PHASE

Use TQMODL to get the model name for a phase

Added for ChemApp version 1.1.3

Synopsis

FORTRAN:
CALL TQMODL(INDEXP,NAME,NOERR)
C:
tqmodl(indexp,name,&noerr);
Pascal:
tqmodl(indexp,name,noerr);
Basic:
Call tqmodl(indexp,name,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
NAME CHARACTER Returns the model name (see Table Identifiers of phase model names as returned by TQMODL)
NOERR INTEGER Returns an error number

TQMODL returns the model name of the phase INDEXP. If the phase INDEXP is not a mixture phase, the string 'PURE' is returned in variable NAME. Table Identifiers of phase model names as returned by TQMODL contains a list of all possible model names.

See also
TQNOP, TQINP, TQGNP

Example

See
TQINP


Identifiers of phase model names as returned by TQMODL. An 'M' as 5th character is added if magnetic contributions are considered (not valid for models marked with an asterisk(*)).
Condensed phase models  
PURE* Stoichiometric condensed phase
IDMX* Ideal mixing
RKMP Redlich-Kister-Muggianu polynomial [Red48]
QKTO General polynomial Kohler/Toop formalism [Pel88]
SUBL Compound energy formalism [Sun81] [Zha81] [Hil85]
SUBO* Two-sublattice order/disorder formalism [Lac91]
SUBS* Species chemical potential/bond energy formalism [Oat95]
SUBI* Two-sublattice ionic formalism [Sun91]
SUBM Two-sublattice equivalent fraction formalism [Pel88]
SUBE Extended compound energy formalism [Oat]
BDEF* Binary defect formalism [Pel]
QUSL Two-sublattice equivalent fraction formalism as a polynomial [Des91]
GAYE* Gaye-Kapoor-Frohberg cell formalism with or without non-oxidic solutes [Gay92]
QUAS* Modified quasichemical formalism [Pel86] [Bla87] [Pel93]
QSOL* Modified quasichemical formalism with nonoxidic solutes [Pel86] [Bla87] [Pel93]
SUBG Quadruplet quasichemical model [Cha01] [Pel01]
HOCH Hoch-Arpshofen formalism [Hoc84] [Hoc84b] [Hoc87]
WAGN Unified interaction parameter formalism [Pel86b]
Aqueous models  
IDWZ* Ideal aqueous mixing
IDDZ* Davies formalism [Dav62]
PIMZ* Pitzer formalism [Har84]
PITZ* Pitzer formalism with fixed alpha-1 and alpha-2 [Har84]
PIWZ* Pitzer formalism without E-theta and E-theta' [Har84]
HELZ* Revised Helgeson-Kirkham-Flowers formalism [Hel81]
HTSZ* Helgeson-Tanger-Shock formalism (ideal) [Tan88]
HTWZ* Helgeson-Tanger-Shock formalism (Debye-Hückel) [Tan88]
HTDZ* Helgeson-Tanger-Shock formalism (Davies) [Tan88]
PIHZ* Helgeson-Tanger-Shock formalism (Pitzer) [Tan88]
SITZ* Specific ion-interaction formalism [Gre97]
Gaseous models  
IDVT* Virial equation with Tsonopoulos second virial coefficient correlation [Tso74]
IDBS* C-H-O-S-N-Ar superfluid formalism [Bel92]
User-defined models  
USP? Nonaqueous model with excess partial Gibbs energies supplied by user
US?Z* Aqueous model with excess partial Gibbs energies supplied by user
USX? Model with partial derivatives dG/dx supplied by user
USG?* Gaseous model with second virial coefficients supplied by user

3.11   TQNOP

GET-NUMBER-OF-PHASES

Use TQNOP to get the total number of phases.

Synopsis

FORTRAN:
CALL TQNOP(NPHASE,NOERR)
C:
tqnop(&nphase,&noerr);
Pascal:
tqnop(nphase,noerr);
Basic:
Call tqnop(nphase,noerr)

Name Type Value set on call or returned
NPHASE INTEGER Returns the total number of phases
NOERR INTEGER Returns an error number

NPHASE is normally used as upper limit in loops over all phases. A loop over all condensed phases would start from index number 2, since the index number 1 is reserved for the gas phase.

See also
TQINP, TQGNP, TQMODL

Example

See
TQINP

3.12   TQINPC

GET-INDEX-NUMBER-OF-PHASE-CONSTITUENT

Use TQINPC to get the index number for a specified phase constituent.

Synopsis

FORTRAN:
CALL TQINPC(NAME,INDEXP,INDEXC,NOERR)
C:
tqinpc(name,indexp,&indexc,&noerr);
Pascal:
tqinpc(name,indexp,indexc,noerr);
Basic:
Call tqinpc(name,indexp,indexc,noerr

Name Type Value set on call or returned
NAME CHARACTER Set to a phase constituent name
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Returns the index number for the constituent
NOERR INTEGER Returns an error number

NAME and INDEXP are input. NAME cannot exceed 24 characters in length. The value of INDEXC returned is normally used as input to other subroutines of the interface. The number remains the same throughout the application.

See also
TQNOPC, TQGNPC, TQSTPC, TQPCIS, TQGDPC

Example

Fortran:
! Handling phase constituents

      PROGRAM CAF13
      IMPLICIT NONE

      INTEGER NOERR, NPCON, NSCOM, I
      CHARACTER PCNAME*24, SCNAME(3)*24
      DOUBLE PRECISION WMASS, STOI(3)


! Initialise ChemApp
      CALL TQINI(NOERR)

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

! Read data-file
      CALL TQRFIL(NOERR)

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

! Get the number of phase constituents of the first phase in
! cosi.dat, which is the gaseous mixture phase
      CALL TQNOPC(1, NPCON, NOERR)

      WRITE(*,FMT='(A,I3)') 'Number of phase constituents of ' //
     *     'the gas phase in cosi.dat: ', NPCON
Output:
Number of phase constituents of the gas phase in cosi.dat:  15

! Print the names of all phase constituents of the gas phase,
! their stoichiometry in terms of the system components,
! and their molecular mass

! Get names of the system components
      CALL TQNOSC(NSCOM, NOERR)
      DO I=1, NSCOM
         CALL TQGNSC(I, SCNAME(I), NOERR)
      ENDDO

! Print header
      WRITE(*,FMT='(A)') '                                ' //
     *     'Stoichiometry      Mol. mass'
      WRITE(*,FMT='(A)') 'No.  Name of phase const.       ' //
     *     SCNAME(1)(1:6) //
     *     SCNAME(2)(1:6) //
     *     SCNAME(3)(1:6) //
     *     ' g/mol'

! Set amount unit to gram, so we get the molecular mass in g/mol
      CALL TQCSU('Amount ', 'gram ', NOERR)

! Get the information on all phase constituents of
! the gas phase
      DO I=1, NPCON
         CALL TQGNPC(1, I, PCNAME, NOERR)
         CALL TQSTPC(1, I, STOI, WMASS, NOERR)
         WRITE(*,FMT='(I3,A26,3F6.1,2X,G12.5)')
     *        I, PCNAME, STOI(1), STOI(2), STOI(3),
     *        WMASS
      ENDDO
Output:
                                Stoichiometry      Mol. mass
No.  Name of phase const.       C     O     Si     g/mol
  1  C                          1.0   0.0   0.0    12.011
  2  C2                         2.0   0.0   0.0    24.022
  3  C3                         3.0   0.0   0.0    36.033
  4  CO                         1.0   1.0   0.0    28.010
  5  CO2                        1.0   2.0   0.0    44.010
  6  O                          0.0   1.0   0.0    15.999
  7  O2                         0.0   2.0   0.0    31.999
  8  O3                         0.0   3.0   0.0    47.998
  9  Si                         0.0   0.0   1.0    28.086
 10  Si2                        0.0   0.0   2.0    56.172
 11  Si2C                       1.0   0.0   2.0    68.183
 12  Si3                        0.0   0.0   3.0    84.258
 13  SiC                        1.0   0.0   1.0    40.097
 14  SiO                        0.0   1.0   1.0    44.085
 15  SiO2                       0.0   2.0   1.0    60.085

! Get the index number of a phase constituent,
! in this case, CO2 in the gas phase
      CALL TQINPC('CO2 ', 1, I, NOERR)
      WRITE(*,FMT='(A,I2,A)') 'CO2 is phase constituent no. ',I,
     *     ' in the gas phase in file cosi.dat'


      END
Output:
CO2 is phase constituent no.  5 in the gas phase in file cosi.dat


C:
/* Program cac13 */
/* Handling phase constituents*/

#include "cacint.h"

int main()
{
  LI noerr, npcon, nscom, i;
  char pcname[TQSTRLEN], scname[3][TQSTRLEN];
  DB wmass, stoi[3];


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

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

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

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

  /* Get the number of phase constituents of the first phase in
     cosi.dat, which is the gaseous mixture phase */
  tqnopc(1, &npcon, &noerr);

  printf("Number of phase constituents of "
        "the gas phase in cosi.dat: %li\n", npcon);
Output:
Number of phase constituents of the gas phase in cosi.dat: 15

/* Print the names of all phase constituents of the gas phase,
   their stoichiometry in terms of the system components,
   and their molecular masses */

/* Get names of the system components */
tqnosc(&nscom, &noerr);
for (i = 1; i <= nscom; i++) {
  tqgnsc(i, scname[i-1], &noerr);
}

/* Print header */
printf("                                 "
      "Stoichiometry    Mol. mass\n");
printf("No. Name of phase const.    %6s%6s%6s    g/mol\n",
      scname[0],scname[1],scname[2]);

/* Set amount unit to gram, so we get the molecular mass in g/mol */
tqcsu("Amount", "gram", &noerr);

/* Get the information on all phase constituents of
   the gas phase */
for (i = 1; i <= npcon; i++) {
  tqgnpc(1, i, pcname, &noerr);
  tqstpc(1, i, stoi, &wmass, &noerr);
  printf("%3li %-26s%6.1f%6.1f%6.1f  %g\n",
        i, pcname, stoi[0], stoi[1], stoi[2], wmass);
}
Output:
                                 Stoichiometry    Mol. mass
No. Name of phase const.         C     O    Si    g/mol
  1 C                            1.0   0.0   0.0  12.011
  2 C2                           2.0   0.0   0.0  24.022
  3 C3                           3.0   0.0   0.0  36.033
  4 CO                           1.0   1.0   0.0  28.0104
  5 CO2                          1.0   2.0   0.0  44.0098
  6 O                            0.0   1.0   0.0  15.9994
  7 O2                           0.0   2.0   0.0  31.9988
  8 O3                           0.0   3.0   0.0  47.9982
  9 Si                           0.0   0.0   1.0  28.086
 10 Si2                          0.0   0.0   2.0  56.172
 11 Si2C                         1.0   0.0   2.0  68.183
 12 Si3                          0.0   0.0   3.0  84.258
 13 SiC                          1.0   0.0   1.0  40.097
 14 SiO                          0.0   1.0   1.0  44.0854
 15 SiO2                         0.0   2.0   1.0  60.0848

  /* Get the index number of a phase constituent,
     in this case, CO2 in the gas phase */
  tqinpc("CO2", 1, &i, &noerr);
  printf("CO2 is phase constituent no. %li "
        "in the gas phase in file cosi.dat\n", i);


  return 0;

}
Output:
CO2 is phase constituent no. 5 in the gas phase in file cosi.dat

3.13   TQGNPC

GET-NAME-OF-PHASE-CONSTITUENT

Use TQGNPC to get the name for a specified phase constituent.

Synopsis

FORTRAN:
CALL TQGNPC(INDEXP,INDEXC,NAME,NOERR)
C:
tqgnpc(indexp,indexc,name,&noerr);
Pascal:
tqgnpc(indexp,indexc,name,noerr);
Basic:
Call tqgnpc(indexp,indexc,name,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
NAME CHARACTER Returns the constituent name
NOERR INTEGER Returns an error number

INDEXP and INDEXC are integer input. The output variable NAME cannot exceed 24 characters in length.

See also
TQNOPC, TQINPC, TQSTPC, TQPCIS, TQGDPC

Example

See
TQINPC

3.14   TQPCIS

CHECK-IF-PHASE-CONSTITUENT-IS-PERMITTED-AS-INCOMING-SPECIES

Use TQPCIS to check if a phase constituent is permitted as incoming species.

Added for ChemApp version 3.1.0

Synopsis

FORTRAN:
CALL TQPCIS(INDEXP,INDEXC,INPCIS,NOERR)
C:
tqpcis(indexp,indexc,&inpcis,&noerr);
Pascal:
tqpcis(indexp,indexc,inpcis,noerr);
Basic:
Call tqpcis(indexp,indexc,inpcis,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
INPCIS INTEGER Returns 1 if permitted, 0 if not
NOERR INTEGER Returns an error number

INDEXP and INDEXC are input. If the specified phase constituent can be used as an incoming species using TQSETC/TQSTCA, INPCIS returns 1, otherwise it returns 0.

Note that only for the sparsely used solution model SUBS (see Tables List of available solution models in ChemApp and Identifiers of phase model names as returned by TQMODL) can INPCIS take values equal to zero.

See also
TQNOPC, TQINPC, TQGNPC, TQSTPC, TQGDPC

Example

Fortran:
! Determining whether phase constituents are permitted as incoming
! species

      PROGRAM CAF25
      IMPLICIT NONE

      INTEGER NOERR, NPHASE, NPCON, I, J, INPCIS, NNPERM
      CHARACTER PNAME*24, PCNAME*24

! Initialise the number of phase constituents which cannot be used as
! incoming species to 0
      NNPERM = 0

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

! Check whether the data-file contains any phase constituents that
! cannot be used as incoming species.

! Get the number of phases
      CALL TQNOP(NPHASE, NOERR)

 100  FORMAT(1X,A,T26,A,T51,A)

! Print a table header
      WRITE(*,FMT=100) 'PHASE', 'PHASE CONSTITUENT',
     *     'O.K./NOT PERMITTED'

! Loop over all phases
      DO I=1, NPHASE
         CALL TQGNP(I, PNAME, NOERR)
         CALL TQNOPC(I, NPCON, NOERR)

! We only need to check mixture phases
         IF (NPCON .GT. 1) THEN
! Loop over all constituents
            DO J=1, NPCON
               CALL TQGNPC(I, J, PCNAME, NOERR)
! Check whether the current constituent is permitted to be used as
! incoming species
               CALL TQPCIS(I, J, INPCIS, NOERR)

! Print a table entry, and if it is not permitted, increase the total
! number of such phase constituents by 1
               IF (INPCIS .EQ. 0) THEN
                  NNPERM = NNPERM + 1
                  WRITE(*,FMT=100) PNAME, PCNAME, 'not permitted'
               ELSE
                  WRITE(*,FMT=100) PNAME, PCNAME, 'o.k.'
               ENDIF
            ENDDO
         ENDIF
      ENDDO

! If there were phase constituents which cannot be used as incoming
! species, print a note.
      IF (NNPERM .GT. 0) THEN
         WRITE(*,FMT='(1X,A,I3,A)') 'Note: ', NNPERM, ' phase ' //
     *        'constituent(s) is/are not permitted '
         WRITE(*,FMT='(1X,A)') '        as incoming species.'
      ENDIF



      END
Output:
PHASE                   PHASE CONSTITUENT        O.K./NOT PERMITTED
GAS                     C                        o.k.
GAS                     C2                       o.k.
GAS                     C3                       o.k.
GAS                     CO                       o.k.
GAS                     CO2                      o.k.
GAS                     O                        o.k.
GAS                     O2                       o.k.
GAS                     O3                       o.k.
GAS                     Si                       o.k.
GAS                     Si2                      o.k.
GAS                     Si2C                     o.k.
GAS                     Si3                      o.k.
GAS                     SiC                      o.k.
GAS                     SiO                      o.k.
GAS                     SiO2                     o.k.


C:
/* Program cac25 */
/* Determining whether phase constituents are permitted as incoming
   species */

#include "cacint.h"

int main()
{
  LI noerr, nphase, npcon, i, j, inpcis, nnperm;
  char pname[TQSTRLEN], pcname[TQSTRLEN];

  /* Initialise the number of phase constituents which cannot be used as
     incoming species to 0 */
  nnperm = 0;

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

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

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

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

  /* Check whether the data-file contains any phase constituents that
     cannot be used as incoming species. */

  /* Get the number of phases */
  tqnop(&nphase, &noerr);

  /* Print a table header */
  printf("%-25s%-25s%-19s\n", "PHASE", "PHASE CONSTITUENT",
        "O.K./NOT PERMITTED");

  /* Loop over all phases */
  for (i=1; i<=nphase; i++) {
    tqgnp(i, pname, &noerr);
    tqnopc(i, &npcon, &noerr);

    /* We only need to check mixture phases */
    if (npcon > 1) {
      /* Loop over all constituents */
      for (j=1; j<=npcon; j++) {
       tqgnpc(i, j, pcname, &noerr);
       /* Check whether the current constituent is permitted to be
          used as incoming species */
       tqpcis(i, j, &inpcis, &noerr);

       /* Print a table entry, and if it is not permitted, increase the total
          number of such phase constituents by 1 */
       if (inpcis == 0) {
         nnperm++;
         printf("%-25s%-25s%-19s\n", pname, pcname, "not permitted");
       } else {
         printf("%-25s%-25s%-19s\n", pname, pcname, "o.k.");
       }
      }
    }
  }

  /* If there were phase constituents which cannot be used as incoming
     species, print a note. */
  if (nnperm > 0) {
    printf("Note: %li phase constituent(s) is/are not permitted\n"
          "      as incoming species.\n", nnperm);
  }



  return 0;

}
Output:
PHASE                    PHASE CONSTITUENT        O.K./NOT PERMITTED
GAS                      C                        o.k.
GAS                      C2                       o.k.
GAS                      C3                       o.k.
GAS                      CO                       o.k.
GAS                      CO2                      o.k.
GAS                      O                        o.k.
GAS                      O2                       o.k.
GAS                      O3                       o.k.
GAS                      Si                       o.k.
GAS                      Si2                      o.k.
GAS                      Si2C                     o.k.
GAS                      Si3                      o.k.
GAS                      SiC                      o.k.
GAS                      SiO                      o.k.
GAS                      SiO2                     o.k.

3.15   TQNOPC

GET-NUMBER-OF-PHASE-CONSTITUENTS

Use TQNOPC to get the total number of constituents in a specified phase.

Synopsis

FORTRAN:
CALL TQNOPC(INDEXP,NPCON,NOERR)
C:
tqnopc(indexp,&npcon,&noerr);
Pascal:
tqnopc(indexp,npcon,noerr);
Basic:
Call tqnopc(indexp,npcon,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
NPCON INTEGER Returns the total number of constituents in a phase
NOERR INTEGER Returns an error number

NPCON is integer output normally used as upper limit in loops over all constituents of phase number INDEXP.

See also
TQINPC, TQGNPC, TQSTPC, TQPCIS, TQGDPC

Example

See
TQINPC

3.16   TQSTPC

GET-STOICHIOMETRY-OF-PHASE-CONSTITUENT

Use TQSTPC to get the stoichiometry and molecular mass of a specified phase constituent.

Synopsis

FORTRAN:
CALL TQSTPC(INDEXP,INDEXC,STOI,WMASS,NOERR)
C:
tqstpc(indexp,indexc,&stoi,&wmass,&noerr);
Pascal:
tqstpc(indexp,indexc,stoi,wmass,noerr);
Basic:
Call tqstpc(indexp,indexc,stoi,wmass,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
STOI Array of DOUBLE PRECISION Returns the stoichiometry of the constituent
WMASS DOUBLE PRECISION Returns the molecular mass of the constituent
NOERR INTEGER Returns an error number

INDEXP and INDEXC are integer input. The array STOI needs to be declared large enough to hold at least as much DOUBLE PRECISION values as there are system components, see parameter NSCOM in TQNOSC. The stoichiometry of constituent INDEXC in phase INDEXP returned through STOI depends on the current set of system components. WMASS is the molecular mass of the same phase constituent.

For more information on the stoichiometry matrix, see Definition of a stoichiometry matrix.

Note that the value for the molecular mass is returned in the current amount unit per mol. Since the default amount unit is also mol (see Table Units permitted in ChemApp), the result will always be 1.0, unless the amount unit is changed, for instance to gram.

See also
TQNOPC, TQINPC, TQGNPC, TQPCIS, TQGDPC, TQCHAR

Example

See
TQINPC

3.17   TQCHAR

GET-CHARGE-OF-PHASE-CONSTITUENT

Use TQCHAR to get the charge of a phase constituent.

Added for ChemApp version 5.4.1

Synopsis

FORTRAN:
CALL TQCHAR(INDEXP,INDEXC,VAL,NOERR)
C:
tqchar(indexp,indexc,&val,&noerr);
Pascal:
tqchar(indexp,indexc,val,noerr);
Basic:
Call tqchar(indexp,indexc,val,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
VAL DOUBLE PRECISION Returns the charge
NOERR INTEGER Returns an error number

INDEXP and INDEXC are integer input. The output variable VAL is of type DOUBLE PRECISION and contains the charge. Except for aqueous solutions, the output will be correct only if the system component name for a phase-specific electron is of the type 'e(PHASE_NAME)'. Use TQCNSC to rename the system component for a phase-specific electron, if necessary.

See also
TQGNSC, TQCNSC

3.18   TQINLC

GET-INDEX-NUMBER-OF-SUBLATTICE-CONSTITUENT

Use TQINLC to get the index number of a specified sublattice constituent.

Added for ChemApp version 3.3.1

Synopsis

FORTRAN:
CALL TQINLC(NAME,INDEXP,INDEXL,INDEXC,NOERR)
C:
tqinlc(name,indexp,indexl,&indexc,&noerr);
Pascal:
tqinlc(name,indexp,indexl,indexc,noerr);
Basic:
Call tqinlc(name,indexp,indexl,indexc,noerr)

Name Type Value set on call or returned
NAME CHARACTER Set to a sublattice constituent name
INDEXP INTEGER Set to the index number for a phase
INDEXL INTEGER Set to the index number for a sublattice
INDEXC INTEGER Returns the index number of the sublattice constituent
NOERR INTEGER Returns an error number

The input variable NAME is permitted to have a maximum length of 24 characters. INDEXL has to be set to the index number of the sublattice in the phase INDEXP of which NAME is a constituent. The returned value for INDEXC is normally used as input to other ChemApp subroutines and stays the same throughout an application, or until a different thermochemical data-file is loaded. All solution phases are considered to be modelled with one or several sublattices. For phases with one sublattice, the subroutines TQINLC and TQINPC are equivalent.

See also
TQGNLC, TQNOSL, TQNOLC, TQGTLC

Example

See
TQGNLC

3.19   TQGNLC

GET-NAME-OF-SUBLATTICE-CONSTITUENT

Use TQGNLC to get the name for a specified sublattice constituent.

Added for ChemApp version 3.3.1

Synopsis

FORTRAN:
CALL TQGNLC(INDEXP,INDEXL,INDEXC,NAME,NOERR)
C:
tqgnlc(indexp,indexl,&indexc,name,&noerr);
Pascal:
tqgnlc(indexp,indexl,indexc,name,noerr);
Basic:
Call tqgnlc(indexp,indexl,indexc,name,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXL INTEGER Set to the index number for a sublattice
INDEXC INTEGER Set to the index number for a sublattice constituent
NAME CHARACTER Returns the sublattice constituent name
NOERR INTEGER Returns an error number

INDEXP, INDEXL, and INDEXC are all integer input and have to be set to the index numbers of a phase, a sublattice in that phase, and a sublattice constituent on that sublattice. The output variable NAME cannot exceed 25 characters in length. All solution phases are considered to be modelled with one or several sublattices. For phases with one sublattice, the subroutines TQGNLC and TQGNPC are equivalent.

If the variable NAME contains a name for the sublattice constituent like Comp 1, 1 this usually means that the thermochemical data-file used has been converted from ChemSage version 3.x to 4.x format using the utility ChemFile. Sublattice constituent names were not part of the ChemSage V3.x data-file format, thus ChemFile can only use generic names for them if a data-file is converted that contains a sublattice phase. If the data-file in use is in ASCII format, these generic names can be manually edited in the file using a text editor. Alternatively, the programm CSFAP offered by GTT-Technologies can be used for this purpose. In case binary or transparent data-files are used, please contact GTT-Technologies.

See also
TQINLC, TQNOSL, TQNOLC, TQGTLC

Example

Fortran:
! Handling sublattice constituents

      PROGRAM CAF26
      IMPLICIT NONE

      INTEGER NOERR, NPHASE, NSL, NSLCON, INDEXP, INDEXL, INDEXC, I
      CHARACTER PNAME*24, CNAME*24


! Initialise ChemApp
      CALL TQINI(NOERR)

! Open the thermochemical data-file subl-ex.dat for reading. It contains
! an extract of the system Co-Cr-Fe: the phase SIGMA:30, which is
! modelled according to the sublattice formalism, and the BCC phase,
! described by a Redlich-Kister polynomial. Both phases are each
! included twice, to account for miscibility gaps.
      CALL TQOPNA('subl-ex.dat', 10, NOERR)

! Read data-file
      CALL TQRFIL(NOERR)

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

! The first of the two identical copies of the SIGMA:30 phase, which
! ChemApp calls SIGMA:30#1, will be investigated with respect to the
! number of sublattices, the number of sublattice constituents on each
! sublattice, and the names of the sublattice constituents.

! Get the index number for the phase SIGMA:30#1
      PNAME = 'SIGMA:30#1'
      CALL TQINP(PNAME, INDEXP, NOERR)

! Get the number of sublattices
      CALL TQNOSL(INDEXP, NSL, NOERR)
      WRITE(*,*) PNAME, ' has ', NSL, ' sublattices'
Output:
SIGMA:30#1               has            3  sublattices

! Loop over all sublattices
      DO INDEXL=1, NSL

! Get the number of sublattice constituents
         CALL TQNOLC(INDEXP, INDEXL, NSLCON, NOERR)
         WRITE(*,*) 'Sublattice ', INDEXL, ' has ', NSLCON,
     *        ' constituents with the following names:'

! Get the name of each sublattice constituent
         DO INDEXC=1, NSLCON
            CALL TQGNLC(INDEXP, INDEXL ,INDEXC, CNAME, NOERR)

! The reverse (getting the index number for the name of the sublattice
! constituent just retrieved), is rather superfluous here, and only used
! to demonstrate the call to TQINLC:
            CALL TQINLC(CNAME, INDEXP, INDEXL, I, NOERR)
            WRITE(*,*) '  ',I,':', CNAME
         ENDDO
      ENDDO


      END
Output:
Sublattice            1  has            2  constituents with the following names:
             1 :Co
             2 :Fe
Sublattice            2  has            1  constituents with the following names:
             1 :Cr
Sublattice            3  has            3  constituents with the following names:
             1 :Co
             2 :Cr
             3 :Fe


C:
/* Program cac26 */
/* Handling sublattice constituents */

#include "cacint.h"

int main()
{


  LI noerr, nphase, nsl, nslcon, indexp, indexl, indexc, i;
  char pname[TQSTRLEN], cname[TQSTRLEN];


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

  /* Open the thermochemical data-file subl-ex.dat for reading. It
     contains an extract of the system Co-Cr-Fe: the phase SIGMA:30,
     which is modelled according to the sublattice formalism, and the
     BCC phase, described by a Redlich-Kister polynomial. Both phases
     are each included twice, to account for miscibility gaps. */
  tqopna("subl-ex.dat",10,&noerr);

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

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

  /* The first of the two identical copies of the SIGMA:30 phase,
     which ChemApp calls SIGMA:30#1, will be investigated with respect
     to the number of sublattices, the number of sublattice
     constituents on each sublattice, and the names of the sublattice
     constituents. */

  /* Get the index number for the phase SIGMA:30#1 */
  strcpy(pname, "SIGMA:30#1");
  tqinp(pname, &indexp, &noerr);

  /* Get the number of sublattices */
  tqnosl(indexp, &nsl, &noerr);
  printf("%s has %li sublattices\n",pname, nsl);
Output:
SIGMA:30#1 has 3 sublattices

  /* Loop over all sublattices */
  for (indexl = 1; indexl<=nsl; indexl++) {

    /* Get the number of sublattice constituents */
    tqnolc(indexp, indexl, &nslcon, &noerr);
    printf("Sublattice %li has %li constituents with the following names:\n",
          indexl, nslcon);

    /* Get the name of each sublattice constituent */
    for (indexc = 1; indexc<=nslcon; indexc++) {
      tqgnlc(indexp, indexl ,indexc, cname, &noerr);

      /* The reverse (getting the index number for the name of the
        sublattice constituent just retrieved), is rather superfluous
        here, and only used to demonstrate the call to tqinlc: */
      tqinlc(cname, indexp, indexl, &i, &noerr);
      printf("   %li: %s\n", i, cname);
    }
  }


  return 0;

}
Output:
Sublattice 1 has 2 constituents with the following names:
   1: Co
   2: Fe
Sublattice 2 has 1 constituents with the following names:
   1: Cr
Sublattice 3 has 3 constituents with the following names:
   1: Co
   2: Cr
   3: Fe

3.20   TQNOSL

GET-NUMBER-OF-SUBLATTICES

Use TQNOSL to get the number of sublattices for a specified phase.

Added for ChemApp version 3.3.1

Synopsis

FORTRAN:
CALL TQNOSL(INDEXP,NSUBL,NOERR)
C:
tqnosl(indexp,&nsubl,&noerr);
Pascal:
tqnosl(indexp,nsubl,noerr);
Basic:
Call tqnosl(indexp,nsubl,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
NSUBL INTEGER Returns the number of sublattices
NOERR INTEGER Returns an error number

While all solution models are considered to be modelled with one or more sublattices, INDEXP is normally set to the index number of a phase modelled according to a sublattice formalism (see TQMODL). The number of sublattices in this phase returned in NSUBL is normally used as upper limit in loops over all sublattices of phase INDEXP.

See also
TQINLC, TQGNLC, TQNOLC, TQGTLC

Example

See
TQINLC, TQGNLC

3.21   TQNOLC

GET-NUMBER-OF-SUBLATTICE-CONSTITUENTS

Use TQNOLC to get the number of sublattice constituents for a specified sublattice.

Added for ChemApp version 3.3.1

Synopsis

FORTRAN:
CALL TQNOLC(INDEXP,INDEXL,NSLCON,NOERR)
C:
tqnolc(indexp,indexl,&nslcon,&noerr);
Pascal:
tqnolc(indexp,indexl,nslcon,noerr);
Basic:
Call tqnolc(indexp,indexl,nslcon,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXL INTEGER Set to the index number for a sublattice
NSLCON INTEGER Returns the number of sublattice constituents
NOERR INTEGER Returns an error number

INDEXP has to be set to the index number of a solution phase, INDEXL to the index number of a sublattice in that phase. The number of sublattice constituents in that sublattice returned in NSLCON is normally used as upper limit in loops over all sublattices constituents of sublattice INDEXL in phase INDEXP. All solution phases are considered to be modelled with one or several sublattices.

See also
TQINLC, TQGNLC, TQNOSL, TQGTLC

Example

See
TQINLC, TQGNLC

3.22   Changing the status of phases and constituents

ChemApp contains subroutines that enable the status of phases or constituents to be changed; that is, to be either excluded from or re-entered into an equilibrium calculation (see Table ChemApp subroutines for changing the status of phases and constituents). The default status is that stored in the thermodynamic data-file. The status for a phase can be changed implicitly, dependent on the explicit changes of the statuses of its constituents. For example, if all constituents of a phase are made dormant, the phase will also be dormant.

Whereas complete phases can always be set ENTERED, DORMANT or ELIMINATED, some restrictions apply for phase constituents (see the notes for TQCSPC).

A common reason for changing the status of a phase is for instance the desire to calculate a metastable equilibrium (see TQGSP) or to increase the computational speed in systems containing miscibility gaps (see Data-files with preset suppression of species).

ChemApp subroutines for changing the status of phases and constituents
Subroutine Function
TQGSP Gets the status of a phase
TQCSP Changes the status of a phase
TQGSPC Gets the status of a phase constituent
TQCSPC Changes the status of a phase constituent

Possible statuses for phases and constituents
Option Comment
ENTERED The phase or constituent is included in the equilibrium calculation. An included phase is not necessarily stable at equilibrium.
DORMANT The phase or constituent is excluded from the mass balances (it will appear with zero amount at equilibrium), but its activity is calculated. If the calculated activity for a phase is greater than one, it would be stable if entered.
ELIMINATED The phase or constituent is ignored in the equilibrium calculation

3.23   TQGSP

GET-STATUS-OF-PHASE

Use TQGSP to get the status of a specified phase.

Synopsis

FORTRAN:
CALL TQGSP(INDEXP,OPTION,NOERR)
C:
tqgsp(indexp,option,&noerr);
Pascal:
tqgsp(indexp,option,noerr);
Basic:
Call tqgsp(indexp,option,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
OPTION CHARACTER Returns a string as shown in Table Possible statuses for phases and constituents
NOERR INTEGER Returns an error number

INDEXP is integer input and OPTION is character output identifying the status (see Table Possible statuses for phases and constituents).

See also
TQCSP, TQGSPC, TQCSPC

Example

Fortran:
! Changing the status of phases

      SUBROUTINE TABLE
      IMPLICIT NONE

      INTEGER I, NOERR, NPHASE
      DOUBLE PRECISION AMOUNT, ACT
      CHARACTER NAME*24

! Retrieve and display the activities and equilibrium
! amounts of all phases

! Get number of phases
      CALL TQNOP(NPHASE, NOERR)

! Print table header
         write(*,FMT='(A10,17X,A14,2X,A14)') 'Phase name',
     *     'amount/mol',
     *     'activity'

      DO I=1, NPHASE
! Get the phase name
         CALL TQGNP(I, NAME, NOERR)

! Get its equilibrium amount
         CALL TQGETR('A ',  I, 0, AMOUNT, NOERR)

! Get its activity
         CALL TQGETR('AC ', I, 0, ACT, NOERR)
         write(*,FMT='(A24,2X,F14.5,2X,F14.5)') NAME,AMOUNT,ACT
      ENDDO
      RETURN
      END


      PROGRAM CAF14
      IMPLICIT NONE

      INTEGER NOERR, NUMCON
      INTEGER ISIC, ISIO2, IC
      DOUBLE PRECISION VALS(2)
      CHARACTER STATUS*24


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

! Get the phase index number of SiC
      CALL TQINP('SiC ', ISIC, NOERR)

! Get the status of this phase
      CALL TQGSP(ISIC, STATUS, NOERR)

      WRITE(*,FMT='(A)') 'The status of SiC is currently ' //
     *     STATUS
Output:
The status of SiC is currently ENTERED

! Unless a phase is marked "dormant" or "eliminated" in the data-file
! itself, the status is by default always "entered". This means it is
! considered in the subsequent equilibrium calculations and is included
! in the mass balance.

! Set some conditions and perform a simple calculation to
! demonstrate the effect of the different statuses

! Set temperature to 1900 K
      CALL TQSETC('T ', 0, 0, 1900.D0, NUMCON, NOERR)

! Set incoming amount to 1 mol SiO2(quartz) and 2 mol C
      CALL TQINP('SiO2(quartz)', ISIO2, NOERR)
      CALL TQSETC('IA ', ISIO2, 0, 1.D0, NUMCON, NOERR)

      CALL TQINP('C ', IC, NOERR)
      CALL TQSETC('IA ', IC, 0, 2.D0, NUMCON, NOERR)

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

! Print a table containing the phase names, their
! equilibrium amounts, and activities
      CALL TABLE
Output:
Phase name                     amount/mol        activity
GAS                              1.39778         1.00000
C                                0.00000         0.43860
Si                               0.00000         0.07912
SiC                              0.65059         1.00000
SiO2(quartz)                     0.00000         0.90635
SiO2(tridymite)                  0.00000         0.99918
SiO2(cristobali)                 0.30105         1.00000
SiO2(liquid)                     0.00000         0.97125

! From the above table it can be seen that SiC is stable
! under those conditions. Its activity is unity and its
! equilibrium amount is approx. 0.65 mol

! Now change the status of SiC to "dormant" and rerun the
! calculation

      CALL TQCSP(ISIC, 'DORMANT ', NOERR)
      CALL TQCE(' ', 0, 0, VALS, NOERR)
      CALL TABLE
Output:
Phase name                     amount/mol        activity
GAS                              0.00000         0.74210
C                                2.00000         1.00000
Si                               0.00000         1.00000
SiC                              0.00000        28.81864
SiO2(quartz)                     0.00000         0.90635
SiO2(tridymite)                  0.00000         0.99918
SiO2(cristobali)                 1.00000         1.00000
SiO2(liquid)                     0.00000         0.97125

! Setting a phase to "dormant" tells ChemApp to exclude it from the mass
! balance, but still calculate its activity.  This offers the
! possibility to consider a phase to be metastable, while still
! obtaining information about its activity. It can be seen from the
! above table that ChemApp sets the equilibrium amount of SiC to zero,
! and calculated its activity to be almost 30. Instead of SiC, ChemApp
! now calculates Si to be stable.

! If a phase is to be completely ignored during the equilibrium
! calculations, its status should be set to "eliminated", as in the
! following example.

      CALL TQCSP(ISIC, 'ELIMINATED ', NOERR)
      CALL TQCE(' ', 0, 0, VALS, NOERR)
      CALL TABLE


! Now ChemApp ignored SiC during the equilibrium calculations, as if it
! were not even included in the data-file. The status "eliminated"
! allows one to selectively delete phases from equilibrium calculations,
! for instance to increase computational efficiency.

      END
Output:
Phase name                     amount/mol        activity
GAS                              0.00000         0.74210
C                                2.00000         1.00000
Si                               0.00000         1.00000
SiC                              0.00000         0.00000
SiO2(quartz)                     0.00000         0.90635
SiO2(tridymite)                  0.00000         0.99918
SiO2(cristobali)                 1.00000         1.00000
SiO2(liquid)                     0.00000         0.97125


C:
/* Program cac14 */
/* Changing the Status of Phases */

#include "cacint.h"

void table()
{

  LI i, noerr, nphase;
  DB amount, act;
  char name[TQSTRLEN];

  /* Retrieve and display the activities and equilibrium
     amounts of all phases */

  /* Get number of phases */
  tqnop(&nphase, &noerr);

  /* Print table header */
  printf("%-27s%-16s%-16s\n", "Phase name", "amount/mol", "activity");

  for(i = 1; i <= nphase; i++) {

    /* Get the phase name */
    tqgnp(i, name, &noerr);

    /* Get its equilibrium amount */
    tqgetr("a",  i, 0, &amount, &noerr);

    /*  Get its activity */
    tqgetr("ac",  i, 0, &act, &noerr);

    printf("%-24s%14.5f%14.5f\n", name, amount, act);

  }
}


int main()
{

  LI noerr, numcon;
  LI iSiC, iSiO2, iC;
  DB vals[2];
  char status[TQSTRLEN];


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

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

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

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

  /* Get the phase index number of SiC */
  tqinp("SiC", &iSiC, &noerr);

  /* Get the status of this phase */
  tqgsp(iSiC, status, &noerr);

  printf("The status of SiC is currently %s\n", status);
Output:
The status of SiC is currently ENTERED

/* Unless a phase is marked "dormant" or "eliminated" in the data-file
   itself, the status is by default always "entered". This means it is
   considered in the subsequent equilibrium calculations and is included
   in the mass balance. */

/* Set some conditions and perform a simple calculation to
   demonstrate the effect of the different statuses */

/* Set temperature to 1900 K */
tqsetc("T", 0, 0, 1900.0, &numcon, &noerr);

/* Set incoming amount to 1 mol SiO2(quartz) and 2 mol C */
tqinp("SiO2(quartz)", &iSiO2, &noerr);
tqsetc("ia", iSiO2, 0, 1.0, &numcon, &noerr);

tqinp("C", &iC, &noerr);
tqsetc("ia", iC, 0, 2.0, &numcon, &noerr);

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

/* Print a table containing the phase names, their
   equilibrium amounts, and activities */
table();
Output:
Phase name                 amount/mol      activity
GAS                            1.39778       1.00000
C                              0.00000       0.43860
Si                             0.00000       0.07912
SiC                            0.65059       1.00000
SiO2(quartz)                   0.00000       0.90635
SiO2(tridymite)                0.00000       0.99918
SiO2(cristobali)               0.30105       1.00000
SiO2(liquid)                   0.00000       0.97125

/* From the above table it can be seen that SiC is stable
   under those conditions. Its activity is unity and its
   equilibrium amount is approx. 0.65 mol */

/* Now change the status of SiC to "dormant" and rerun the
   calculation */

tqcsp(iSiC, "dormant", &noerr);
tqce(" ", 0, 0, vals, &noerr);
table();
Output:
Phase name                 amount/mol      activity
GAS                            0.00000       0.74210
C                              2.00000       1.00000
Si                             0.00000       1.00000
SiC                            0.00000      28.81864
SiO2(quartz)                   0.00000       0.90635
SiO2(tridymite)                0.00000       0.99918
SiO2(cristobali)               1.00000       1.00000
SiO2(liquid)                   0.00000       0.97125

  /* Setting a phase to "dormant" tells ChemApp to exclude it from the
     mass balance, but still calculate its activity.  This offers the
     possibility to consider a phase to be metastable, while still
     obtaining information about its activity. It can be seen from
     the above table that ChemApp sets the equilibrium amount of SiC
     to zero, and calculated its activity to be almost 30. Instead of
     SiC, ChemApp now calculates Si to be stable. */

  /* If a phase is to be completely ignored during the equilibrium
     calculations, its status should be set to "eliminated", as in the
     following example. */

  tqcsp(iSiC, "eliminated", &noerr);
  tqce(" ", 0, 0, vals, &noerr);
  table();


  /* Now ChemApp ignored SiC during the equilibrium calculations, as
     if it were not even included in the data-file. The status
     "eliminated" allows one to selectively delete phases from
     equilibrium calculations, for instance to increase computational
     efficiency. */

  return 0;
}
Output:
Phase name                 amount/mol      activity
GAS                            0.00000       0.74210
C                              2.00000       1.00000
Si                             0.00000       1.00000
SiC                            0.00000       0.00000
SiO2(quartz)                   0.00000       0.90635
SiO2(tridymite)                0.00000       0.99918
SiO2(cristobali)               1.00000       1.00000
SiO2(liquid)                   0.00000       0.97125

3.24   TQCSP

CHANGE-STATUS-OF-PHASE

Use TQCSP to change the status of a specified phase.

Synopsis

FORTRAN:
CALL TQCSP(INDEXP,OPTION,NOERR)
C:
tqcsp(indexp,option,&noerr);
Pascal:
tqcsp(indexp,option,noerr);
Basic:
Call tqcsp(indexp,option,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
OPTION CHARACTER Set to a string as shown in Table Possible statuses for phases and constituents
NOERR INTEGER Returns an error number

INDEXP is integer input and OPTION is character input identifying the status (see Table Possible statuses for phases and constituents ).

See also
TQGSP, TQGSPC, TQCSPC

Example

See
TQGSP

3.25   TQGSPC

GET-STATUS-OF-PHASE-CONSTITUENT

Use TQGSPC to get the status of a specified phase constituent.

Synopsis

FORTRAN:
CALL TQGSPC(INDEXP,INDEXC,OPTION,NOERR)
C:
tqgspc(indexp,indexc,option,&noerr);
Pascal:
tqgspc(indexp,indexc,option,noerr);
Basic:
Call tqgspc(indexp,indexc,option,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
OPTION CHARACTER Returns a string as shown in Table Possible statuses for phases and constituents
NOERR INTEGER Returns an error number

INDEXP and INDEXC are integer input and OPTION is character output identifying the status (see Table Possible statuses for phases and constituents).

See also
TQCSPC, TQGSP, TQCSP

Example

Fortran:
! Changing the status of phase constituents

      SUBROUTINE TABLE
      IMPLICIT NONE

      INTEGER I, NOERR, NPCON
      DOUBLE PRECISION AMOUNT, FUG
      CHARACTER NAME*24, STATUS*24

! Retrieve and display the fugacities, equilibrium
! amounts, and statuses of all phase constituents in the gas phase

! Get number of gas phase constituents
      CALL TQNOPC(1, NPCON, NOERR)

! Print table header
         WRITE(*,FMT='(A17,9X,A14,2X,A14,3X,A6)')
     *     'Phase const. name',
     *     'amount/mol',
     *     'fugacity',
     *     'status'

      DO I=1, NPCON
! Get the phase constituent name
         CALL TQGNPC(1, I, NAME, NOERR)

! Get its equilibrium amount
         CALL TQGETR('A ',  1, I, AMOUNT, NOERR)

! Get its fugacity
         CALL TQGETR('AC ', 1, I, FUG, NOERR)

! Get its status
         CALL TQGSPC(1, I, STATUS, NOERR)
         WRITE(*,FMT='(A24,2X,G14.5,2X,G14.5,2X,A10)')
     *        NAME, AMOUNT, FUG, STATUS
      ENDDO
      RETURN
      END

      PROGRAM CAF15
      IMPLICIT NONE

      INTEGER I, NOERR, NUMCON, NPCON
      INTEGER ISIO2, IC, ISI
      DOUBLE PRECISION VALS(2), STOI(3), WMASS


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

! Unless a phase constituent is marked "dormant" or "eliminated" in the
! data-file itself, the status is by default always "entered". This
! means it is considered in the subsequent equilibrium calculation and
! is included in the mass balances.

! Set some conditions and perform a simple calculation to
! demonstrate the effect of the different statuses

! Set temperature to 1900 K
      CALL TQSETC('T ', 0, 0, 1900.D0, NUMCON, NOERR)

! Set incoming amount to 1 mol SiO2(quartz) and 2 mol C
      CALL TQINP('SiO2(quartz)', ISIO2, NOERR)
      CALL TQSETC('IA ', ISIO2, 0, 1.D0, NUMCON, NOERR)

      CALL TQINP('C ', IC, NOERR)
      CALL TQSETC('IA ', IC, 0, 2.D0, NUMCON, NOERR)

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

! Print a table containing the phase constituent names, their
! equilibrium amounts, activities, and status
      CALL TABLE
Output:
Phase const. name             amount/mol        fugacity   status
C                            0.19355E-11     0.13847E-11  ENTERED
C2                           0.42921E-13     0.30707E-13  ENTERED
C3                           0.29728E-12     0.21268E-12  ENTERED
CO                            1.3493         0.96531      ENTERED
CO2                          0.12171E-03     0.87076E-04  ENTERED
O                            0.21225E-10     0.15185E-10  ENTERED
O2                           0.35711E-14     0.25548E-14  ENTERED
O3                           0.60783E-29     0.43486E-29  ENTERED
Si                           0.13427E-05     0.96060E-06  ENTERED
Si2                          0.94642E-09     0.67709E-09  ENTERED
Si2C                         0.23037E-07     0.16481E-07  ENTERED
Si3                          0.16040E-10     0.11475E-10  ENTERED
SiC                          0.74337E-11     0.53182E-11  ENTERED
SiO                          0.48362E-01     0.34599E-01  ENTERED
SiO2                         0.55877E-07     0.39975E-07  ENTERED

! To demonstrate the effect of assigning a different status to phase
! constituents, set the status of all those phase constituents of the
! gas phase to "dormant" which contain Si.

! Get number of gas phase constituents
      CALL TQNOPC(1, NPCON, NOERR)

! Get the index number of system component Si
      CALL TQINSC("Si", ISI, NOERR)

! Use TQSTPC to determine for each phase constituent whether it
! contains Si, and set its status to "dormant" if it does
      DO I=1, NPCON
         CALL TQSTPC(1, I, STOI, WMASS, NOERR)
         IF (STOI(ISI) .GT. 0.D0) THEN
            CALL TQCSPC(1, I, 'DORMANT ', NOERR)
         ENDIF
      ENDDO

! Calculate the equilibrium and print the table again
      CALL TQCE(' ', 0, 0, VALS, NOERR)
      CALL TABLE


! As can be seen from the table above, all phase constituents of the gas
! phase that contain Si have been set to "dormant". ChemApp considers
! them in the activity calculation, but does not include them in the
! mass balances: their equilibrium amount is always zero. Since this
! forces ChemApp to keep the gas phase free of Si compounds, the 1 mol
! of Si input into the system can thus only be found in the condensed
! phases.

! Setting the status of these phase constituents to "eliminated" instead
! would cause ChemApp to exclude them completely from the equilibrium
! calculation.

      END
Output:
Phase const. name             amount/mol        fugacity   status
C                            0.18901E-11     0.14176E-11  ENTERED
C2                           0.42909E-13     0.32183E-13  ENTERED
C3                           0.30425E-12     0.22820E-12  ENTERED
CO                            1.3332         0.99991      ENTERED
CO2                          0.12168E-03     0.91262E-04  ENTERED
O                            0.20485E-10     0.15364E-10  ENTERED
O2                           0.34873E-14     0.26155E-14  ENTERED
O3                           0.60057E-29     0.45044E-29  ENTERED
Si                            0.0000         0.93832E-06  DORMANT
Si2                           0.0000         0.64603E-09  DORMANT
Si2C                          0.0000         0.16099E-07  DORMANT
Si3                           0.0000         0.10695E-10  DORMANT
SiC                           0.0000         0.53182E-11  DORMANT
SiO                           0.0000         0.34195E-01  DORMANT
SiO2                          0.0000         0.39975E-07  DORMANT


C:
/* Program cac15 */
/* Changing the status of phase constituents*/

#include "cacint.h"

void table()
{

  LI i, noerr, npcon;
  DB amount, fug;
  char name[TQSTRLEN], status[TQSTRLEN];

  /* Retrieve and display the fugacities, equilibrium
     amounts, and statuses of all phase constituents in the gas phase */

  /* Get number of phase constituents */
  tqnopc(1, &npcon, &noerr);

  /* Print table header */
  printf("%-24s  %-12s  %-12s%s\n", "Phase const. name",
        "amount/mol", "fugacity", "status");

  for(i = 1; i <= npcon; i++) {

    /* Get the phase constituent name */
    tqgnpc(1, i, name, &noerr);

    /* Get its equilibrium amount */
    tqgetr("a", 1, i, &amount, &noerr);

    /* Get its fugacity */
    tqgetr("ac",  1, i, &fug, &noerr);

    /* Get its status */
    tqgspc(1, i, status, &noerr);

    printf("%-24s  %10.5g  %10.5g   %-6s\n",
          name, amount, fug, status);

  }
}

int main()
{
  LI i, noerr, numcon, npcon;
  LI iSiO2, iC, iSi;
  DB vals[2], stoi[3], wmass;


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

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

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

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

  /* Unless a phase constituent is marked "dormant" or "eliminated" in
     the data-file itself, the status is by default always
     "entered". This means it is considered in the subsequent
     equilibrium calculation and is included in the mass balances. */

  /* Set some conditions and perform a simple calculation to
     demonstrate the effect of the different statuses */

  /* Set temperature to 1900 K */
  tqsetc("T", 0, 0, 1900.0, &numcon, &noerr);

  /* Set incoming amount to 1 mol SiO2(quartz) and 2 mol C */
  tqinp("SiO2(quartz)", &iSiO2, &noerr);
  tqsetc("ia", iSiO2, 0, 1.0, &numcon, &noerr);

  tqinp("C", &iC, &noerr);
  tqsetc("ia", iC, 0, 2.0, &numcon, &noerr);

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

  /* Print a table containing the phase constituent names, their
     equilibrium amounts, activities, and status */
  table();
Output:
Phase const. name         amount/mol    fugacity    status
C                         1.9355e-12  1.3847e-12   ENTERED
C2                        4.2921e-14  3.0707e-14   ENTERED
C3                        2.9728e-13  2.1268e-13   ENTERED
CO                            1.3493     0.96531   ENTERED
CO2                       0.00012171  8.7076e-05   ENTERED
O                         2.1225e-11  1.5185e-11   ENTERED
O2                        3.5711e-15  2.5548e-15   ENTERED
O3                        6.0783e-30  4.3486e-30   ENTERED
Si                        1.3427e-06   9.606e-07   ENTERED
Si2                       9.4642e-10  6.7709e-10   ENTERED
Si2C                      2.3037e-08  1.6481e-08   ENTERED
Si3                        1.604e-11  1.1475e-11   ENTERED
SiC                       7.4337e-12  5.3182e-12   ENTERED
SiO                         0.048362    0.034599   ENTERED
SiO2                      5.5877e-08  3.9975e-08   ENTERED

  /* To demonstrate the effect of assigning a different status to phase
     constituents, set the status of all those phase constituents of the
     gas phase to "dormant" which contain Si. */

  /* Get number of gas phase constituents */
  tqnopc(1, &npcon, &noerr);

  /*  Get the index number of system component Si */
  tqinsc("Si", &iSi, &noerr);

  /* Use tqstpc to determine for each phase constituent whether it
     contains Si, and set its status to "dormant" if it does */
  for (i = 1; i <= npcon; i++) {
    tqstpc(1, i, stoi, &wmass, &noerr);
    if (stoi[iSi-1] > 0.0) {
      tqcspc(1, i, "dormant", &noerr);
    }
  }

  /* Calculate the equilibrium and print the table again */
  tqce(" ", 0, 0, vals, &noerr);
  table();


  /* As can be seen from the table above, all phase constituents of the gas
     phase that contain Si have been set to "dormant". ChemApp considers
     them in the activity calculation, but does not include them in the
     mass balances: their equilibrium amount is always zero. Since this
     forces ChemApp to keep the gas phase free of Si compounds, the 1 mol
     of Si input into the system can thus only be found in the condensed
     phases. */

  /* Setting the status of these phase constituents to "eliminated"
     instead would cause ChemApp to exclude them completely from the
     equilibrium calculation. */

  return 0;

}
Output:
Phase const. name         amount/mol    fugacity    status
C                         1.8901e-12  1.4176e-12   ENTERED
C2                        4.2909e-14  3.2183e-14   ENTERED
C3                        3.0425e-13   2.282e-13   ENTERED
CO                            1.3332     0.99991   ENTERED
CO2                       0.00012168  9.1262e-05   ENTERED
O                         2.0485e-11  1.5364e-11   ENTERED
O2                        3.4873e-15  2.6155e-15   ENTERED
O3                        6.0057e-30  4.5044e-30   ENTERED
Si                                 0  9.3832e-07   DORMANT
Si2                                0  6.4603e-10   DORMANT
Si2C                               0  1.6099e-08   DORMANT
Si3                                0  1.0695e-11   DORMANT
SiC                                0  5.3182e-12   DORMANT
SiO                                0    0.034195   DORMANT
SiO2                               0  3.9975e-08   DORMANT

3.26   TQCSPC

CHANGE-STATUS-OF-PHASE-CONSTITUENT

Use TQCSPC to change the status of a specified phase constituent.

Synopsis

FORTRAN:
CALL TQCSPC(INDEXP,INDEXC,OPTION,NOERR)
C:
tqcspc(indexp,indexc,option,&noerr);
Pascal:
tqcspc(indexp,indexc,option,noerr);
Basic:
Call tqcspc(indexp,indexc,option,noerr)

Name Type Value set on call or returned
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
OPTION CHARACTER Set to a string as shown in Table Possible statuses for phases and constituents
NOERR INTEGER Returns an error number

INDEXP and INDEXC are integer input, and OPTION is character input identifying the status (see Table Possible statuses for phases and constituents).

Whereas complete phases can always be set ENTERED, DORMANT or ELIMINATED, some restrictions apply for phase constituents.

  1. For phases described by the models SUBS and QUAS, the status for single phase constituents cannot be changed.
  2. For sublattice type phases or for phases which internally are considered to contain sublattices (models SUBL, SUBO, SUBI, SUBM, SUBE, QUSL, GAYE, QSOL), the entered phase constituents must constitute a proper sublattice phase. As an example, if the sublattice setting is (A,B)(C,D), the phase constituents AC and AD, and thus implicitly A, can be removed, but not AC and BD. If there is an error, the error message appears first after a call of TQCE.
See also
TQGSPC, TQGSP, TQCSP

Example

See
TQGSPC

4   Subroutines for Defining Equilibrium Calculations

This section describes the subroutines available for defining the initial conditions for an equilibrium calculation. These are summarised in Table ChemApp subroutines for defining calculations. Global equilibrium conditions are set using the subroutines TQSETC or TQSTEC (see Tables Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC and Definition of the indices in the subroutines TQSETC and TQSTEC). The latter must be applied when using streams, which should preferably be defined when an extensive property of a reaction is wanted as a result, or when incoming amounts of the same constituent are to be entered more than once.

TQREMC is used to remove equilibrium conditions when using global conditions. All remaining subroutines in this group are used for managing streams. They set up a stream (TQSTTP), set its constituent amounts (TQSTCA), and delete a stream (TQSTRM).

ChemApp subroutines for defining calculations
Subroutine Function
TQSETC Sets an equilibrium condition
TQREMC Removes an equilibrium condition
TQSTTP Sets name, temperature, and pressure for a stream
TQSTCA Sets constituent amounts for a stream
TQSTEC Sets an equilibrium condition with input conditions defined by streams
TQSTRM Removes a stream

Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC
Option Variable Comment
P Total pressure Last entered (pressure or volume) takes precedence. Default value is 1 bar.
VT Total volume Last entered (pressure or volume) takes precedence. Note that the use of this option to perform calculations at constant volume is discouraged, see Equilibrium calculations at constant volume for details.
T Temperature Default value is 1000 K.
A Amount of phase VAL >=0 defines a formation target calculation; VAL <0 a precipitation target calculation for a mixture phase. In a formation target calculation, the target variable is varied until unit activity and zero amount of the target phase is achieved. A precipitation target is defined as one where the target phase is the only one formed at equilibrium, and the second most stable phase has unit activity.
IA Incoming amount Valid for phase constituents and system components. Not permitted for TQSTEC.
MU Chemical potential Valid only for phase constituents. Not permitted for TQSTEC.
AC Relative activity Not permitted for TQSTEC.
CP
H
S
G
V
Heat capacity
Enthalpy
Entropy
Gibbs energy
Volume
Valid for the entire system or for a phase. Extensive properties are either calculated for the equilibrium phases and are then dependent on the reference state chosen in the data-file, or for the chemical reaction when streams are defined, in which case they are relative to the state defined by the stream conditions.
AT Relative activity Relative activity of a phase constituent as target.
XT Mole fraction Mole fraction of a phase constituent as target.
XPT Mole fraction Mole fraction of a system component in a phase as target.

Definition of the indices INDEXP (for phases) and INDEX (for components or constituents) in the subroutines TQSETC and TQSTEC. Index numbers are obtained by the appropriate subroutine calls (see TQINSC, TQINP, TQINPC). Indices may be chosen arbitrarily when pressure, volume, or temperature is set. When a number <= 0 is required, this may be chosen freely.
INDEXP INDEX Component, phase, or constituent for which value is entered
>0 >0 Constituent INDEX of phase INDEXP (INDEX=1 or 0 for stoichiometric condensed phases)
>0 <=0 Phase INDEXP
<=0 >0 System component INDEX
0 0 Entire system

4.1   TQSETC

SET-EQUILIBRIUM-CONDITION

Use TQSETC to set a condition for the equilibrium calculation.

Synopsis

FORTRAN:
CALL TQSETC(OPTION,INDEXP,INDEX,VAL,NUMCON,NOERR)
C:
tqsetc(option,indexp,index,val,&numcon,&noerr);
Pascal:
tqsetc(option,indexp,index,val,numcon,noerr);
Basic:
Call tqsetc(option,indexp,index,val,numcon,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEX INTEGER Set to the index number for a constituent or component, if necessary
VAL DOUBLE PRECISION Set to the value of the condition
NUMCON INTEGER Returns a number for the condition
NOERR INTEGER Returns an error number

OPTION, INDEXP, INDEX, and VAL are all input. NUMCON is output. The possible state variables are shown in Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC, and possible values of INDEXP and INDEX in Table Definition of the indices in the subroutines TQSETC and TQSTEC. VAL is entered with the default unit, or a unit set using TQCSU (see Initialising the Interface and Reading a Data-file). Each condition with respect to incoming amount, chemical potential, or relative activity is given a unique number (NUMCON). This number can later be used to remove any of these conditions (see TQREMC).

Normally two state variables, such as temperature and pressure, as well as one condition for the amount of each component of the actual system are necessary to define a calculation. The latter condition can also be fulfilled by defining incoming amounts of any number of constituents. Note that the input amounts entered do not have to include all the elements contained in the data-file. A previous value is replaced if incoming amounts for the same constituent are entered twice.

ChemApp defines a constituent for which chemical potential or relative activity is entered as incoming. The incoming amount (negative or positive) that corresponds to the condition set is calculated and the results can be retrieved using TQGETR. When any other variable than pressure (volume), temperature, or input composition is defined as an equilibrium condition, for example, enthalpy or the amount of a phase, a target variable has to be entered upon calling TQCE, see Subroutines to Perform a Calculation and to Obtain Results. Note that TQSETC and TQSTCA/TQSTEC cannot be used interchangeably for setting conditions.

Note that some solution phase models might not permit the usage of their phase constituents as incoming species. TQPCIS can be used to check for these cases.

See also
TQREMC, TQSTEC

Example

Fortran:
! Set and remove equilibrium conditions

      PROGRAM CAF16
      IMPLICIT NONE

      INTEGER NOERR, NUMCON, ISIO2, IC, ISIC, ISI
      DOUBLE PRECISION VALS(2), RESULT


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

! Set conditions for a simple equilibrium calculation: temperature and
! some incoming amounts.

! Set temperature to 1900 K
      CALL TQSETC('T ', 0, 0, 1900.D0, NUMCON, NOERR)

! Set incoming amounts: 1 mol SiO2(quartz), 2 mol C, and 3 mol SiC

! Get phase index numbers for all phases and set their amounts
      CALL TQINP('SiO2(quartz)', ISIO2, NOERR)
      CALL TQSETC('IA ', ISIO2, 1, 1.D0, NUMCON, NOERR)

      CALL TQINP('C ', IC, NOERR)
      CALL TQSETC('IA ', IC, 0, 2.D0, NUMCON, NOERR)

      CALL TQINP('SiC ', ISIC, NOERR)
      CALL TQSETC('IA ', ISIC, 0, 3.D0, NUMCON, NOERR)

! Use TQSHOW to check which conditions have been set so far, or are
! active by default
      CALL TQSHOW(NOERR)
Output:
T = 1900.00000000 K
P = 1 bar

STREAM CONSTITUENT
SiO2(quartz)
AMOUNT/mol    =  1.00000000000000E+00
C
AMOUNT/mol    =  2.00000000000000E+00
SiC
AMOUNT/mol    =  3.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

! TQSETC returns a variable (called NUMCON in this example) which can be
! used to remove a previously set condition. To do this, pass it to
! TQREMC. Here we remove the last condition set, which are the 3 mol of
! SiC
      CALL TQREMC(NUMCON, NOERR)

! Call TQSHOW again to demonstrate that it has been deleted from the
! list of active conditions
      CALL TQSHOW(NOERR)
Output:
T = 1900.00000000 K
P = 1 bar

STREAM CONSTITUENT
SiO2(quartz)
AMOUNT/mol    =  1.00000000000000E+00
C
AMOUNT/mol    =  2.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

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

! Get the activity of Si
      CALL TQINP('Si ', ISI, NOERR)
      CALL TQGETR('AC ', ISI, 0, RESULT, NOERR)

      WRITE(*,FMT='(1X,A,G12.5)') 'Activity of pure Si is ', RESULT


      END
Output:
Activity of pure Si is  0.79115E-01


C:
/* Program cac16 */
/* Set equilibrium conditions */

#include "cacint.h"

int main()
{
  LI noerr, numcon, iSiO2, iC, iSiC, iSi;
  DB vals[2], result;


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

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

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

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

  /* Set conditions for a simple equilibrium calculation: temperature and
     some incoming amounts. */

  /* Set temperature to 1900 K */
  tqsetc("T", 0, 0, 1900.0, &numcon, &noerr);

  /* Set incoming amounts: 1 mol SiO2(quartz), 2 mol C, and 3 mol SiC */

  /* Get phase index number for both phases and set their amounts */
  tqinp("SiO2(quartz)", &iSiO2, &noerr);
  tqsetc("ia", iSiO2, 0, 1.0, &numcon, &noerr);

  tqinp("C", &iC, &noerr);
  tqsetc("ia", iC, 0, 2.0, &numcon, &noerr);

  tqinp("SiC", &iSiC, &noerr);
  tqsetc("ia", iSiC, 0, 3.0, &numcon, &noerr);

  /* Use tqshow to check which conditions have been set so far, or are
     active by default */
  tqshow(&noerr);
Output:
T = 1900.00000000 K
P = 1 bar

STREAM CONSTITUENT
SiO2(quartz)
AMOUNT/mol    =  1.00000000000000E+00
C
AMOUNT/mol    =  2.00000000000000E+00
SiC
AMOUNT/mol    =  3.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

/* tqsetc returns a variable (called numcon in this example) which can be
   used to remove a previously set condition. To do this, pass it to
   tqremc. Here we remove the last condition set, which are the 3 mol of
   SiC */
tqremc(numcon, &noerr);

/* Call tqshow again to demonstrate that it has been deleted from the
   list of active conditions */
tqshow(&noerr);
Output:
T = 1900.00000000 K
P = 1 bar

STREAM CONSTITUENT
SiO2(quartz)
AMOUNT/mol    =  1.00000000000000E+00
C
AMOUNT/mol    =  2.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

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

  /* Get the activity of Si */
  tqinp("Si", &iSi, &noerr);
  tqgetr("ac", iSi, 0, &result, &noerr);

  printf("Activity of pure Si is %g\n", result);


  return 0;

}
Output:
Activity of pure Si is 0.0791154

4.2   TQREMC

REMOVE-EQUILIBRIUM-CONDITION

Use TQREMC to remove a condition for the equilibrium calculation.

Synopsis

FORTRAN:
CALL TQREMC(NUMCON,NOERR)
C:
tqremc(numcon,&noerr);
Pascal:
tqremc(numcon,noerr);
Basic:
Call tqremc(numcon,noerr)

Name Type Value set on call or returned
NUMCON INTEGER Set the number for the condition
NOERR INTEGER Returns an error number

Replace NUMCON with the name of the variable that was used for setting the condition (TQSETC) to be removed. TQREMC is needed only for the case when a condition with respect to an incoming amount, chemical potential, or relative activity (see Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC) is to be removed. Otherwise, input conditions can be replaced by using another call to TQSETC, TQCE, or TQMAP (see Subroutines to Perform a Calculation and to Obtain Results).

Three special cases for the removal of conditions are provided, which are also accessed through the value of NUMCON passed to TQREMC:

0:Using a zero value for NUMCON removes all input conditions relating to incoming amounts, but no other conditions (e.g. temperature), and no targets.
-1:A value of -1 removes all conditions, targets, and previously set configuration options, plus it resets the system units to their default values.
-2:A value of -2 does the same as the above, except that it does not reset the system units to their default values (new as of version 3.0.0).
See also
TQSETC, TQINI

Example

See
TQSETC

4.3   TQSTTP

SET-NAME-TEMPERATURE-PRESSURE-FOR-A-STREAM

Use TQSTTP to define a stream and set its temperature and pressure.

Synopsis

FORTRAN:
CALL TQSTTP(IDENTS,VALS,NOERR)
C:
tqsttp(idents,vals,&noerr);
Pascal:
tqsttp(idents,vals,noerr);
Basic:
Call tqsttp(idents,vals,noerr)

Name Type Value set on call or returned
IDENTS CHARACTER Set to a name for the stream
VALS Array of DOUBLE PRECISION Set to temperature and pressure for a stream
NOERR INTEGER Returns an error number

The input variable IDENTS can have a maximum length of 150 characters. VALS must be an array of 2 real values, containing the temperature and pressure of the stream. These are entered with the default unit, or a unit set using TQCSU (see Initialising the Interface and Reading a Data-file).

A stream is a means for transferring non-reacted matter (see also the notes in Extensive properties of streams) to a reaction zone. It has constant temperature and pressure, and contains one or more phases of fixed composition. (see also Setting initial conditions). Stream input is required whenever differences in extensive properties between the initial and the equilibrium state are desired; for example, in calculations of the heat evolving from a combustion process, or of the entropy change caused by a phase transition.

The maximum number of streams which are defined must not be greater than the maximum number of constituents permitted in the ChemApp version currently used (see TQSIZE, parameter 'NA').

See also
TQSTCA, TQSTEC, TQSTRM, TQSTXP

Example

Fortran:
! Equilibrium calculations using streams

      PROGRAM CAF17
      IMPLICIT NONE

      INTEGER NOERR, ISIO2, IO2, ICO2, I, NPHASE
      DOUBLE PRECISION TPSOL(2), TPGAS(2), VALS(2), AMOUNT,
     * VALUE
      CHARACTER PNAME*24, SNAME*24, CEU*3, CTU*1, CVU*3, CAU*5


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

! Two input streams will subsequently be defined: The first one,
! labelled 'STREAM_QUARTZ', will be solid SiO2(quartz) at 500 K, the
! second one, labelled 'STREAM_GAS', will consist of a gas phase at room
! temperature consisting of O2 and CO2. By using streams instead of
! global conditions we will be able to get information about the
! extensive property balance of this process.

! Define the first stream ('STREAM_QUARTZ')

! Use the array called TPSOL to pass the information on temperature and
! pressure (500 K and 1 bar) of the stream to TQSTTP
      TPSOL(1) = 500.D0
      TPSOL(2) = 1.D0
      CALL TQSTTP('STREAM_QUARTZ ', TPSOL, NOERR)

! Define the amounts of constituents of this stream (1 mol quartz)
      CALL TQINP('SiO2(quartz)', ISIO2, NOERR)
      CALL TQSTCA('STREAM_QUARTZ ', ISIO2, 0, 1.D0, NOERR)

! Define second stream ('STREAM_GAS')
      TPGAS(1) = 298.15D0
      TPGAS(2) = 1.D0
      CALL TQSTTP('STREAM_GAS ', TPGAS, NOERR)

! Define the amounts of constituents of this stream (0.5 mol O2/GAS/ and
! 0.5 mol CO2/GAS/)
      CALL TQINPC('O2 ', 1, IO2, NOERR)
      CALL TQSTCA('STREAM_GAS ', 1, IO2, 0.5D0, NOERR)

      CALL TQINPC('CO2 ', 1, ICO2, NOERR)
      CALL TQSTCA('STREAM_GAS ', 1, ICO2, 0.5D0, NOERR)

! Set the temperature at which the two streams should react
      CALL TQSTEC('T ', 0, 2500.D0, NOERR)

! Define a third stream for the sole purpose of demonstrating how to
! remove it subsequently
      CALL TQSTTP('DUMMY ', TPGAS, NOERR)
      CALL TQSTCA('DUMMY ', 1, 1, 1.D0, NOERR)

! Display what we have set so far
      CALL TQSHOW(NOERR)
Output:
T = 2500.00000000 K
P = 1 bar

STREAM NAME             STREAM NUMBER   TEMPERATURE/K   PRESSURE/bar
STREAM_QUARTZ
                              1             500.00       1.0000E+00
STREAM_GAS
                              2             298.15       1.0000E+00
DUMMY
                              3             298.15       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       SiO2(quartz)
              AMOUNT/mol    =  1.00000000000000E+00
      2       O2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      2       CO2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      3       C/GAS/
              AMOUNT/mol    =  1.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

! Remove the 'DUMMY' stream
      CALL TQSTRM('DUMMY ', NOERR)

! Call TQSHOW again to demonstrate that the last stream has been removed
      CALL TQSHOW(NOERR)
Output:
T = 2500.00000000 K
P = 1 bar

STREAM NAME             STREAM NUMBER   TEMPERATURE/K   PRESSURE/bar
STREAM_QUARTZ
                              1             500.00       1.0000E+00
STREAM_GAS
                              2             298.15       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       SiO2(quartz)
              AMOUNT/mol    =  1.00000000000000E+00
      2       O2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      2       CO2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01

INACTIVE ELECTRON CONSTRAINT

! Calculate the equilibrium
      CALL TQCEL(' ', 0, 0, VALS, NOERR)
Output:
T = 2500 K
P = 1 bar
V = 211.73 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/K   PRESSURE/bar STREAM
SiO2(quartz)               1.0000E+00       500.00       1.0000E+00     1
O2/GAS/                    5.0000E-01       298.15       1.0000E+00     2
CO2/GAS/                   5.0000E-01       298.15       1.0000E+00     2

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: GAS                    mol                           bar
O2                         5.0755E-01     4.9829E-01     4.9829E-01
CO2                        4.7466E-01     4.6599E-01     4.6599E-01
CO                         2.5340E-02     2.4877E-02     2.4877E-02
O                          1.0519E-02     1.0327E-02     1.0327E-02
SiO                        2.8827E-04     2.8300E-04     2.8300E-04
SiO2                       2.3878E-04     2.3442E-04     2.3442E-04
O3                       T 1.1157E-07     1.0954E-07     1.0954E-07
Si                         2.7197E-12     2.6701E-12     2.6701E-12
C                          8.5771E-16     8.4205E-16     8.4205E-16
Si2                        4.6313E-23     4.5467E-23     4.5467E-23
SiC                        1.0075E-23     9.8915E-24     9.8915E-24
C2                         1.1127E-24     1.0924E-24     1.0924E-24
Si2C                       4.9282E-30     4.8382E-30     4.8382E-30
C3                         4.4137E-32     4.3332E-32     4.3332E-32
Si3                        4.3927E-33     4.3125E-33     4.3125E-33
TOTAL:                     1.0186E+00     1.0000E+00     1.0000E+00
                              mol                         ACTIVITY
SiO2(liquid)               9.9947E-01                    1.0000E+00
SiO2(cristobali)           0.0000E+00                    8.9012E-01
SiO2(tridymite)          T 0.0000E+00                    8.5795E-01
SiO2(quartz)             T 0.0000E+00                    7.4840E-01
C                          0.0000E+00                    5.0218E-09
Si                         0.0000E+00                    5.7669E-10
SiC                        0.0000E+00                    1.3051E-17
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 9.94401E+01   2.72660E+05   2.18581E+02  -8.84766E+05   1.86939E+02

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.92216E+02  -8.24091E+05   5.02347E+02  -2.07996E+06   2.11729E+02

Mole fraction of system components:
             GAS
C            0.19987
O            0.79992
Si           2.1068E-04

Data on 3 constituents marked with 'T' are extrapolated outside their valid
temperature range

 50   FORMAT(1X,A,G12.5,' ',A)


! Get the current system units
      CALL TQGSU('V ', CVU, NOERR)
      CALL TQGSU('T ', CTU, NOERR)
      CALL TQGSU('E ', CEU, NOERR)
      CALL TQGSU('A ', CAU, NOERR)


! Get the list of stable phases
      WRITE(*,FMT='(A)') ' List of stable phases:'
      CALL TQNOP(NPHASE, NOERR)
      DO I=1, NPHASE
         CALL TQGETR('A ', I, 0, AMOUNT, NOERR)
         IF (AMOUNT .GT. 0) THEN
            CALL TQGNP(I, PNAME, NOERR)
            WRITE(*,FMT=50) 'Phase: ' // PNAME //
     *           'amount: ', AMOUNT, CAU
         ENDIF
      ENDDO
Output:
List of stable phases:
Phase: GAS                     amount:   1.0186     mol
Phase: SiO2(liquid)            amount:  0.99947     mol

! Get the changes in the extensive property values in the current units
      WRITE(*,'(A)') ' Changes in extensive properties:'
      CALL TQGETR('CP ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Delta CP: ', VALUE, CEU // '/' // CTU
      CALL TQGETR('H ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Delta H:  ', VALUE, CEU
      CALL TQGETR('S ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Delta S:  ', VALUE, CEU // '/' // CTU
      CALL TQGETR('G ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Delta G:  ', VALUE, CEU
      CALL TQGETR('V ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Delta V:  ', VALUE, CVU
Output:
Changes in extensive properties:
Delta CP:   99.440     J  /K
Delta H:   0.27266E+06 J
Delta S:    218.58     J  /K
Delta G:  -0.88477E+06 J
Delta V:    186.94     dm3

! To retrieve the *total* volume, use the option 'VT'
      CALL TQGETR('VT ', 0, 0, VALUE, NOERR)
      WRITE(*,FMT=50) 'Total volume:  ', VALUE, CVU
Output:
Total volume:    211.73     dm3

! Get the thermodynamic properties of the two streams (note that as
! of version 3.2.0 of ChemApp, TQSTXP can also be called _before_
! the equilibrium calculation)
      SNAME = 'STREAM_GAS'
      CALL TQSTXP(SNAME, 'CP ', VALUE, NOERR)
      WRITE(*,FMT=50) 'Cp of stream '// SNAME // ': ',
     *     VALUE, CEU // '/' // CTU

      CALL TQSTXP(SNAME, 'H ', VALUE, NOERR)
      WRITE(*,FMT=50) 'H  of stream '// SNAME // ': ',
     *     VALUE, CEU

      CALL TQSTXP(SNAME, 'S ', VALUE, NOERR)
      WRITE(*,FMT=50) 'S  of stream '// SNAME // ': ',
     *     VALUE, CEU // '/' // CTU

      CALL TQSTXP(SNAME, 'G ', VALUE, NOERR)
      WRITE(*,FMT=50) 'G  of stream '// SNAME // ': ',
     *     VALUE, CEU

      CALL TQSTXP(SNAME, 'V ', VALUE, NOERR)
      WRITE(*,FMT=50) 'V  of stream '// SNAME // ': ',
     *     VALUE, CVU
Output:
Cp of stream STREAM_GAS              :   33.278     J  /K
H  of stream STREAM_GAS              : -0.19675E+06 J
S  of stream STREAM_GAS              :   215.22     J  /K
G  of stream STREAM_GAS              : -0.26092E+06 J
V  of stream STREAM_GAS              :   24.790     dm3

! Note that the volume of condensed phases is zero, unless
! their thermodynamic data contain molar volumes:
      SNAME = 'STREAM_QUARTZ'
      CALL TQSTXP(SNAME, 'V ', VALUE, NOERR)
      WRITE(*,FMT=50) 'Volume of stream '// SNAME // ': ',
     *     VALUE, CVU
Output:
Volume of stream STREAM_QUARTZ           :   0.0000     dm3

! Change the system units to show that TQSTXP returns values
! in the current system units

      CALL TQCSU('T ', 'F ', NOERR)
      CALL TQCSU('V ', 'FT3 ', NOERR)
      CALL TQCSU('E ', 'CAL ', NOERR)

      CALL TQGSU('V ', CVU, noerr)
      CALL TQGSU('T ', CTU, noerr)
      CALL TQGSU('E ', CEU, noerr)

      SNAME = 'STREAM_GAS'
      CALL TQSTXP(SNAME, 'CP ', VALUE, NOERR)
      WRITE(*,FMT=50) 'Cp of stream '// SNAME // ': ',
     *     VALUE, CEU // '/' // CTU

      CALL TQSTXP(SNAME, 'H ', VALUE, NOERR)
      WRITE(*,FMT=50) 'H  of stream '// SNAME // ': ',
     *     VALUE, CEU

      CALL TQSTXP(SNAME, 'S ', VALUE, NOERR)
      WRITE(*,FMT=50) 'S  of stream '// SNAME // ': ',
     *     VALUE, CEU // '/' // CTU

      CALL TQSTXP(SNAME, 'G ', VALUE, NOERR)
      WRITE(*,FMT=50) 'G  of stream '// SNAME // ': ',
     *     VALUE, CEU

      CALL TQSTXP(SNAME, 'V ', VALUE, NOERR)
      WRITE(*,FMT=50) 'V  of stream '// SNAME // ': ',
     *     VALUE, CVU


      END
Output:
Cp of stream STREAM_GAS              :   4.4187     cal/F
H  of stream STREAM_GAS              :  -47025.     cal
S  of stream STREAM_GAS              :   28.577     cal/F
G  of stream STREAM_GAS              :  -62362.     cal
V  of stream STREAM_GAS              :  0.87544     ft3


C:
/* Program cac17 */
/* Equilibrium calculations using streams */

#include "cacint.h"

int main()
{
  LI noerr, iSiO2, iO2, iCO2, i, nphase;
  DB TP_sol[2], TP_gas[2], vals[2], amount, value;
  char pname[TQSTRLEN], sname[TQSTRLEN];

  char CEU[TQSTRLEN], CTU[TQSTRLEN], CVU[TQSTRLEN], CAU[TQSTRLEN];


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

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

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

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

  /* Two input streams will subsequently be defined: The first one,
     labelled "STREAM_QUARTZ", will be solid SiO2(quartz) at 500 K,
     the second one, labelled "STREAM_GAS", will consist of a gas
     phase at room temperature consisting of O2 and CO2. By using
     streams instead of global conditions we will be able to get
     information about the extensive property balance of this
     process. */

  /* Define the first stream ("STREAM_QUARTZ") */

  /* Use the array called TP_sol to pass the information on temperature and
     pressure (500 K and 1 bar) of the stream to tqsttp */
  TP_sol[0] = 500.0;
  TP_sol[1] = 1.0;
  tqsttp("STREAM_QUARTZ", TP_sol, &noerr);

  /* Define the amounts of constituents of this stream
     (1 mol quartz)*/
  tqinp("SiO2(quartz)", &iSiO2, &noerr);
  tqstca("STREAM_QUARTZ", iSiO2, 0, 1.0, &noerr);

  /* Define second stream ("STREAM_GAS") */
  TP_gas[0] = 298.15;
  TP_gas[1] = 1.0;
  tqsttp("STREAM_GAS", TP_gas, &noerr);

  /* Define the amounts of constituents of this stream (0.5 mol O2/GAS/ and
     0.5 mol CO2/GAS/) */
  tqinpc("O2", 1, &iO2, &noerr);
  tqstca("STREAM_GAS", 1, iO2, 0.5, &noerr);

  tqinpc("CO2", 1, &iCO2, &noerr);
  tqstca("STREAM_GAS", 1, iCO2, 0.5, &noerr);

  /* Set the temperature at which the two streams should react */
  tqstec("T", 0, 2500.0, &noerr);

  /* Define a third stream for the sole purpose of demonstrating how
     to remove it subsequently */
  tqsttp("DUMMY", TP_gas, &noerr);
  tqstca("DUMMY", 1, 1, 1.0, &noerr);

  /* Display what we have set so far */
  tqshow(&noerr);
Output:
T = 2500.00000000 K
P = 1 bar

STREAM NAME             STREAM NUMBER   TEMPERATURE/K   PRESSURE/bar
STREAM_QUARTZ
                              1             500.00       1.0000E+00
STREAM_GAS
                              2             298.15       1.0000E+00
DUMMY
                              3             298.15       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       SiO2(quartz)
              AMOUNT/mol    =  1.00000000000000E+00
      2       O2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      2       CO2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      3       C/GAS/
              AMOUNT/mol    =  1.00000000000000E+00

INACTIVE ELECTRON CONSTRAINT

/* Remove the "DUMMY" stream */
tqstrm("DUMMY", &noerr);

/* Call tqshow again to demonstrate that the last stream has been removed */
tqshow(&noerr) ;
Output:
T = 2500.00000000 K
P = 1 bar

STREAM NAME             STREAM NUMBER   TEMPERATURE/K   PRESSURE/bar
STREAM_QUARTZ
                              1             500.00       1.0000E+00
STREAM_GAS
                              2             298.15       1.0000E+00

STREAM NUMBER STREAM CONSTITUENT
      1       SiO2(quartz)
              AMOUNT/mol    =  1.00000000000000E+00
      2       O2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01
      2       CO2/GAS/
              AMOUNT/mol    =  5.00000000000000E-01

INACTIVE ELECTRON CONSTRAINT

/* Calculate the equilibrium */
tqcel(" ", 0, 0, vals, &noerr);
Output:
T = 2500 K
P = 1 bar
V = 211.73 dm3

STREAM CONSTITUENTS        AMOUNT/mol   TEMPERATURE/K   PRESSURE/bar STREAM
SiO2(quartz)               1.0000E+00       500.00       1.0000E+00     1
O2/GAS/                    5.0000E-01       298.15       1.0000E+00     2
CO2/GAS/                   5.0000E-01       298.15       1.0000E+00     2

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: GAS                    mol                           bar
O2                         5.0755E-01     4.9829E-01     4.9829E-01
CO2                        4.7466E-01     4.6599E-01     4.6599E-01
CO                         2.5340E-02     2.4877E-02     2.4877E-02
O                          1.0519E-02     1.0327E-02     1.0327E-02
SiO                        2.8827E-04     2.8300E-04     2.8300E-04
SiO2                       2.3878E-04     2.3442E-04     2.3442E-04
O3                       T 1.1157E-07     1.0954E-07     1.0954E-07
Si                         2.7197E-12     2.6701E-12     2.6701E-12
C                          8.5771E-16     8.4205E-16     8.4205E-16
Si2                        4.6313E-23     4.5467E-23     4.5467E-23
SiC                        1.0075E-23     9.8915E-24     9.8915E-24
C2                         1.1127E-24     1.0924E-24     1.0924E-24
Si2C                       4.9282E-30     4.8382E-30     4.8382E-30
C3                         4.4137E-32     4.3332E-32     4.3332E-32
Si3                        4.3927E-33     4.3125E-33     4.3125E-33
TOTAL:                     1.0186E+00     1.0000E+00     1.0000E+00
                              mol                         ACTIVITY
SiO2(liquid)               9.9947E-01                    1.0000E+00
SiO2(cristobali)           0.0000E+00                    8.9012E-01
SiO2(tridymite)          T 0.0000E+00                    8.5795E-01
SiO2(quartz)             T 0.0000E+00                    7.4840E-01
C                          0.0000E+00                    5.0218E-09
Si                         0.0000E+00                    5.7669E-10
SiC                        0.0000E+00                    1.3051E-17
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 9.94401E+01   2.72660E+05   2.18581E+02  -8.84766E+05   1.86939E+02

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.92216E+02  -8.24091E+05   5.02347E+02  -2.07996E+06   2.11729E+02

Mole fraction of system components:
             GAS
C            0.19987
O            0.79992
Si           2.1068E-04

Data on 3 constituents marked with 'T' are extrapolated outside their valid
temperature range

/* Get the current system units */
tqgsu("V", CVU, &noerr);
tqgsu("T", CTU, &noerr);
tqgsu("E", CEU, &noerr);
tqgsu("A", CAU, &noerr);

/* Get the list of stable phases */
printf("List of stable phases:\n");
tqnop(&nphase, &noerr);
for (i = 1; i <= nphase; i++) {
  tqgetr("A", i, 0, &amount, &noerr);
  if (amount > 0.0) {
    tqgnp(i, pname, &noerr);
    printf("Phase: %-24s amount: %g %s\n", pname, amount, CAU);
  }
}
Output:
List of stable phases:
Phase: GAS                      amount: 1.0186 mol
Phase: SiO2(liquid)             amount: 0.999473 mol

/* Get the changes in the extensive property values in the current units */
printf("Changes in extensive properties:\n");
tqgetr("CP", 0, 0, &value, &noerr);
printf("Delta CP: %g %s/%s\n", value, CEU, CTU);
tqgetr("H", 0, 0, &value, &noerr);
printf("Delta H : %g %s\n", value, CEU);
tqgetr("S", 0, 0, &value, &noerr);
printf("Delta S : %g  %s/%s\n", value, CEU, CTU);
tqgetr("G", 0, 0, &value, &noerr);
printf("Delta G : %g %s\n", value, CEU);
tqgetr("V", 0, 0, &value, &noerr);
printf("Delta V : %g %s\n", value, CVU);
Output:
Changes in extensive properties:
Delta CP: 99.4401 J/K
Delta H : 272660 J
Delta S : 218.581  J/K
Delta G : -884766 J
Delta V : 186.939 dm3

/* To retrieve the *total* volume, use the option "VT" */
tqgetr("VT", 0, 0, &value, &noerr);
printf("Total volume: %g %s\n", value, CVU);
Output:
Total volume: 211.729 dm3

/* Get the thermodynamic properties of the two streams (note that as
   of version 3.2.0 of ChemApp, tqstxp can also be called _before_
   the equilibrium calculation) */
strcpy(sname,"STREAM_GAS");
tqstxp(sname, "CP", &value, &noerr);
printf("Cp of stream %-24s: %g %s/%s\n", sname, value, CEU, CTU);

tqstxp(sname, "H", &value, &noerr);
printf("H  of stream %-24s: %g %s\n", sname, value, CEU);

tqstxp(sname, "S", &value, &noerr);
printf("S  of stream %-24s: %g %s/%s\n", sname, value, CEU, CTU);

tqstxp(sname, "G", &value, &noerr);
printf("G  of stream %-24s: %g %s\n", sname, value, CEU);

tqstxp(sname, "V", &value, &noerr);
printf("V  of stream %-24s: %g %s\n", sname, value, CVU);
Output:
Cp of stream STREAM_GAS              : 33.278 J/K
H  of stream STREAM_GAS              : -196752 J
S  of stream STREAM_GAS              : 215.221 J/K
G  of stream STREAM_GAS              : -260921 J
V  of stream STREAM_GAS              : 24.7897 dm3

/* Note that the volume of condensed phases is zero, unless
   their thermodynamic data contain molar volumes: */

strcpy(sname,"STREAM_QUARTZ");
tqstxp(sname, "V", &value, &noerr);
printf("Volume of stream %-24s: %g %s\n", sname, value, CVU);
Output:
Volume of stream STREAM_QUARTZ           : 0 dm3

  /* Change the system units to show that tqstxp returns values
     in the current system units */

  tqcsu("T", "F", &noerr);
  tqcsu("V", "FT3", &noerr);
  tqcsu("E", "CAL", &noerr);

  tqgsu("T", CTU, &noerr);
  tqgsu("V", CVU, &noerr);
  tqgsu("E", CEU, &noerr);

  strcpy(sname,"STREAM_GAS");
  tqstxp(sname, "CP", &value, &noerr);
  printf("Cp of stream %-24s: %g %s/%s\n", sname, value, CEU, CTU);

  tqstxp(sname, "H", &value, &noerr);
  printf("H  of stream %-24s: %g %s\n", sname, value, CEU);

  tqstxp(sname, "S", &value, &noerr);
  printf("S  of stream %-24s: %g %s/%s\n", sname, value, CEU, CTU);

  tqstxp(sname, "G", &value, &noerr);
  printf("G  of stream %-24s: %g %s\n", sname, value, CEU);

  tqstxp(sname, "V", &value, &noerr);
  printf("V  of stream %-24s: %g %s\n", sname, value, CVU);


  return 0;

}
Output:
Cp of stream STREAM_GAS              : 4.41869 cal/F
H  of stream STREAM_GAS              : -47025 cal
S  of stream STREAM_GAS              : 28.5773 cal/F
G  of stream STREAM_GAS              : -62361.5 cal
V  of stream STREAM_GAS              : 0.875441 ft3

4.4   TQSTCA

SET-CONSTITUENT-AMOUNTS-FOR-A-STREAM

Use TQSTCA to set the constituent amounts for a stream.

Synopsis

FORTRAN:
CALL TQSTCA(IDENTS,INDEXP,INDEXC,VAL,NOERR)
C:
tqstca(idents,indexp,indexc,val,&noerr);
Pascal:
tqstca(idents,indexp,indexc,val,noerr);
Basic:
Call tqstca(idents,indexp,indexc,val,noerr)

Name Type Value set on call or returned
IDENTS CHARACTER Set to the name of a stream
INDEXP INTEGER Set to the index number for a phase
INDEXC INTEGER Set to the index number for a constituent
VAL DOUBLE PRECISION Set to a stream constituent amount
NOERR INTEGER Returns an error number

IDENTS, INDEXP, INDEXC, and VAL are all input. IDENTS is a name previously defined by calling TQSTTP. VAL must be greater than zero and is entered with the default unit, or a unit set using TQCSU (see Initialising the Interface and Reading a Data-file).

See Extensive properties of streams for details on how ChemApp deals with the extensive properties of streams. Note that the same phase constituent can be a part of several streams.

The total number of all the stream constituents defined in all streams must not be greater than the maximum number of constituents of the version of ChemApp used (see TQSIZE, parameter 'NA'). This implies that this limit is reached when defining one stream with 'NA' constituents, or 'NA' streams with one constituent each.

Note that it is not possible to use TQSETC and TQSTCA/TQSTEC interchangeably for setting conditions.

Note that some solution phase models might not permit the usage of their phase constituents as incoming species. TQPCIS can be used to check for these cases.

See also
TQSTTP, TQSTEC, TQSTRM, TQSTXP

Example

See
TQSTTP

4.5   TQSTEC

SET-EQUILIBRIUM-CONDITION-WHEN-STREAM-INPUT

Use TQSTEC to set an invariant state variable for the equilibrium calculation when the input conditions are defined by streams.

Synopsis

FORTRAN:
CALL TQSTEC(OPTION,INDEXP,VAL,NOERR)
C:
tqstec(option,indexp,val,&noerr);
Pascal:
tqstec(option,indexp,val,noerr);
Basic:
Call tqstec(option,indexp,val,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC
INDEXP INTEGER Set to the index number for a phase, if necessary
VAL DOUBLE PRECISION Set to the value of the condition
NOERR INTEGER Returns an error number

OPTION, INDEXP, and VAL are all input. See Table Possible state variables for setting conditions in the subroutines TQSETC and TQSTEC for the mnemonics of the possible state variables. VAL is entered with a default unit, or a unit set using TQCSU (see Chapter Initialising the Interface and Reading a Data-file).

Note: It is not possible to use TQSETC and TQSTCA/TQSTEC interchangeably for setting conditions.

See also
TQSTTP, TQSTCA, TQSTRM, TQSTXP

Example

See
TQSTTP

4.6   TQSTRM

REMOVE-STREAM

Use TQSTRM to remove a stream.

Synopsis

FORTRAN:
CALL TQSTRM(IDENTS,NOERR)
C:
tqstrm(idents,&noerr);
Pascal:
tqstrm(idents,noerr);
Basic:
Call tqstrm(idents,noerr)

Name Type Value set on call or returned
IDENTS CHARACTER Set to the name of a stream
NOERR INTEGER Returns an error number

IDENTS is a name previously defined by calling TQSTTP.

The maximum number of streams that can be defined is equal to the number of constituents ChemApp can handle (see TQSIZE, parameter 'NA'). In the current version of ChemApp though, removing a previously defined stream does not free the number ChemApp used internally for this stream, i.e. the number of additional streams that can be defined is not increased by one. To remove all streams, assign an empty string (in FORTRAN a single blank) to IDENTS when calling TQSTRM. In this case, ChemApp internally deletes all streams and the next stream defined will be assigned to #1.

See also
TQSTTP, TQSTCA, TQSTEC, TQSTXP

Example

See
TQSTTP

5   Subroutines to Perform a Calculation and to Obtain Results

TQCE and TQCEL are the only subroutines that need to be called to carry out a single equilibrium calculation (TQCEL additionally displays results from a calculation in form of a ChemSage/ChemApp result table). When an equilibrium state variable other than pressure, temperature, or composition is defined as input, a target variable must be defined upon calling TQCE/TQCEL; for example, when defining enthalpy or the amount of a phase as a condition instead of temperature.

As of version 3.0.0, ChemApp is able to perform one-dimensional phase mapping calculations. This type of calculation is done using the subroutines TQMAP/TQMAPL.

TQSHOW displays a table of the present settings. Using TQCLIM it is possible to modify the upper and lower limits of target variables.

Results from an equilibrium calculation are retrieved using the subroutine TQGETR. Thermodynamic data for phase constituents can be obtained using TQGDPC, while thermodynamic properties of streams are accessible through TQSTXP. TQGTLC is used to get calculated equilibrium sublattice site fractions for phases modelled according to the sublattice formalism.

TQERR can be used to retrieve ChemApp error messages after any ChemApp subroutine indicated that an error occurred.

These subroutines are summarised below in Table ChemApp subroutines for calculating and getting results, while Tables State variables for defining targets when calling TQCE/TQCEL to State variables for defining one-dimensional phase mapping calculations using TQMAP/TQMAPL list possible values of variables used as parameters to the various subroutines in this group.


ChemApp subroutines for calculating and getting results
Subroutine Function
TQCE Calculates the chemical equilibrium
TQCEL Calculates the chemical equilibrium and gives a result table (ChemSage format)
TQCEN Calculates the chemical equilibrium, taking results from the previous equilibrium calculation as initial estimates
TQCENL Calculates the chemical equilibrium, taking results from the previous equilibrium calculation as initial estimates, and gives a result tab*e (ChemSage format)
TQMAP Calculates a one-dimensional phase map
TQMAPL Calculates a one-dimensional phase map and gives a result table (ChemSage format)
TQCLIM Changes limits of target variables
TQSHOW Shows present settings
TQGETR Gets calculated equilibrium results
TQGDPC Gets thermodynamic data for a phase constituent
TQSTXP Gets thermodynamic properties of a stream
TQGTLC Gets the calculated equilibrium sublattice site fraction
TQBOND Gets a calculated quadruplet or pair fraction
TQERR Gets an error message

State variables for defining targets when calling TQCE/TQCEL
Option Variable Comment
P Total pressure Pressure is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
V Total volume Volume is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
T Temperature Temperature is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
IA
IA0
MU
Incoming amount
Chemical potential
Incoming amount is a target variable. The values VALS(1) and VALS(2) denote lower and upper limits, respectively. When defining streams, the constituent is included in the last stream considered. If incoming amounts for more then one substance need to be defined, all except the last one have to be called using 'IA0' as option to TQCE/TQCEL. Once 'IA' is passed for the last incoming amount, the first calculation is made.
Blank - Calculate without any target variable, VALS is not used.

Options for modifying upper and lower limits of target variables using TQCLIM
Option Variable Default value
PLOW Low pressure limit 10-50 bar
PHIGH High pressure limit 107 bar
VLOW Low volume limit 10-7 dm3
VHIGH High volume limit 1050 dm3
TLOW Low temperature limit 298.15 K
THIGH High temperature limit 6000 K

Definition of the indices INDEXP (for phases) and INDEX (for components or constituents) in the subroutine TQGETR. Index numbers are obtained by the appropriate subroutine calls (see TQINSC, TQINP, TQINPC). Indices may be chosen arbitrarily when pressure, volume, or temperature is selected. When a negative number is required, this may be chosen freely.
INDEXP INDEX Type of VAL Components, phases, or constituents for which value is returned
>0 >0 DOUBLE PRECISION Constituent INDEX of phase INDEXP (INDEX=1 for stoichiometric condensed phases), or system component INDEX of phase INDEXP
>0 <0 Array of DOUBLE PRECISION All constituents of phase INDEXP, or all system components of phase INDEXP (for options XP and AP)
>0 0 DOUBLE PRECISION Phase INDEXP
<0 0 Array of DOUBLE PRECISION All phases
<= 0 >0 DOUBLE PRECISION System component INDEX
<= 0 <0 Array of DOUBLE PRECISION All system components
0 0 DOUBLE PRECISION Entire system

State variables for which results can be obtained with the subroutine TQGETR
Option Variable Comment
P Total pressure -
VT Total volume -
T Temperature -
A Equilibrium amount -
IA Incoming amount Not valid for phases or for the entire system
MU
AC
Chemical potential
Activity/fugacity
Relative values for phases and constituents; absolute values for system components; fugacities in current pressure unit for gas phase constituents.
pH
Eh
pH
Eh/V
The calculation of pH and Eh/V requires that the constituents H+ in the aqueous phase and H2 in the gas phase be present in the thermochemical data-file. If pH and Eh/V cannot be calculated, the output VAL=0.0 will be returned. In order for ChemApp to recognize H+ and H2 in the data-file, the names of the system components hydrogen and aqueous electron must be 'H' and 'EA', respectively (see TQCNSC).
CP
H
S
G
V
Heat capacity
Enthalpy
Entropy
Gibbs energy
Volume
Not valid for system components. Extensive properties for the equilibrium state dependent on the inherent reference state of the data. However, when the entire system is selected and streams are used, the values represent balances, i.e. the extensive property for the equilibrium state minus the sum of values for all streams. To obtain the total volume in this case, use option 'VT'.
CPM
HM
SM
GM
VM
Heat capacity/amount unit
Enthalpy/amount unit
Entropy/amount unit
Gibbs energy/amount unit
Volume/amount unit
Not valid for system components. Partial values are returned for constituents, integral values for phases. Values are valid for default or selected amount units.
X Fraction Mass or mole fraction of a system component in the system, depending on the default or selected amount unit
XP Fraction Mass or mole fraction of a system component in a phase, depending on the default or selected amount unit
AP Equilibrium amount Equilibrium amount of system component in a phase

Thermodynamic quantities that can be calculated using TQGDPC. Note that the values are returned dimensionless and need to be multiplied by R*T to obtain quantities having dimensions.
Option Variable
CP Heat capacity
H Enthalpy
S Entropy
G Gibbs energy
V Volume
T Temperature (used to retrieve the upper limit of the current temperature interval for a given phase constituent or a stoichiometric condensed phase)

Thermodynamic quantities that can be calculated using TQSTXP
Option Variable Unit
CP Heat capacity [current energy unit]/K
H Enthalpy [current energy unit]
S Entropy [current energy unit]/K
G Gibbs energy [current energy unit]
V Volume [current volume unit]

State variables for defining one-dimensional phase mapping calculations using TQMAP/TQMAPL
Option Variable Comment
PF
PN
Total pressure Pressure is the search variable. The upper and lower bounds of the pressure search interval are in VALS(1) and VALS(2). Use option 'PF' for the first call to TQMAP, 'PN' for all subsequent ones.
TF
TN
Temperature Temperature is the search variable. The upper and lower bounds of the temperature search interval are in VALS(1) and VALS(2). Use option 'TF' for the first call to TQMAP, 'TN' for all subsequent ones.
IA0
IAF
IAN
Incoming amount Incoming amount is the search variable. The upper and lower bounds of the composition search interval are in VALS(1) and VALS(2). If incoming amounts for more than one substance need to be defined, all except the last one have to be called using 'IA0' as option to TQMAP. Once 'IAF' is passed for the last incoming amount, the first calculation is made. Use option 'IAN' for all subsequent ones.

5.1   TQCE

CALCULATE-EQUILIBRIUM

Use TQCE to calculate the equilibrium with current settings of global conditions or streams.

Synopsis

FORTRAN:
CALL TQCE(OPTION,INDEXP,INDEXC,VALS,NOERR)
C:
tqce(option,indexp,indexc,vals,&noerr);
Pascal:
tqce(option,indexp,indexc,vals,noerr);
Basic:
Call tqce(option,indexp,indexc,vals,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining targets when calling TQCE/TQCEL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to an initial estimate of the target variable, or the lower and upper limits of an incoming amount, if necessary
NOERR INTEGER Returns an error number

OPTION, INDEXP, INDEX, and VALS are all input. For a calculation without any target, it is sufficient to enter OPTION as a blank character and the remainder as dummies. See Table State variables for defining targets when calling TQCE/TQCEL for the mnemonics of possible target variables, and for the meaning of VALS.

The constraints when two values of VALS entered are: VALS(1) and VALS(2) must not be equal, and VALS(2) must be greater or equal to zero. VALS is entered with the default unit, or a unit selected using TQCSU (see Initialising the Interface and Reading a Data-file). The estimate of the target variable (see Table State variables for defining targets when calling TQCE/TQCEL) need not be particularly accurate. However, unnecessarily long computing times may result if it is far from the equilibrium value. The limits of the target variable can be changed using TQCLIM. While the target variable is specified using TQCE, the target itself must have been set previously using TQSETC or TQSTEC.

See also
TQCEL, TQSETC, TQCEL, TQSTEC, TQSHOW, TQMAP

Example

Fortran:
! Calculation of different phase equilibria

! Note that this program contains phase target calculations,
! which cannot be performed with the 'light' version of ChemApp

      PROGRAM CAF18
      IMPLICIT NONE

      INTEGER NOERR, ISLITE, IO2, IC, IN2, ITEMP
      DOUBLE PRECISION VALS(2), TP(2), RESULT, TEMP


! Initialise ChemApp
      CALL TQINI(NOERR)

! Open data-file for reading. In this case, a data-file containing the
! thermochemical data for the system carbon-nitrogen-oxygen is selected.
      CALL TQOPNA('cno.dat', 10, NOERR)

! Read data-file
      CALL TQRFIL(NOERR)

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

! Since we will perform an extensive property target calculation later,
! we will do the equilibrium calculations using streams. This way we can
! associate an initial state regarding temperature and pressure to the
! incoming substances, which will be taken into account when ChemApp
! calculates the extensive property (e.g. heat) balance.

! Since we are going to prefer degrees Celsius as temperature unit,
! we will change the unit now
      CALL TQCSU('Temperature ', 'C ', NOERR)

! Define a stream at room temperature and 1 bar
      TP(1) = 20.D0
      TP(2) = 1.D0
      CALL TQSTTP('inputs ', TP, NOERR)

! Set stream constituents: 0.5 mol of oxygen and 10 grams of carbon

! Get the index number of the phase constituent oxygen ('O2') in the gas
! phase. If a thermochemical data-file for ChemApp contains a gas
! phase, it is always the first one:
      CALL TQINPC('O2 ', 1, IO2, NOERR)

! Get the index number of the phase carbon ('C')
      CALL TQINP('C ', IC, NOERR)

! Set the incoming amount of oxygen in the stream (0.5 mol)
      CALL TQSTCA('inputs ', 1, IO2, .5D0, NOERR)

! Change the amount unit to gram and set the incoming amount of carbon
! in the stream (10 gram)
      CALL TQCSU('Amount ', 'gram ', NOERR)
      CALL TQSTCA('inputs ', IC, 0, 10.D0, NOERR)

! Set the temperature for the equilibrium calculation (1500 C)
      CALL TQSTEC('T ', 0, 1500.D0, NOERR)

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

! Alternatively, TQCEL can be used, which does not only calculate the
! equilibrium, but also writes a ChemSage result table to standard output
      CALL TQCEL(' ', 0, 0, VALS, NOERR)
Output:
T = 1500 C
P = 1 bar
V = 122.74 dm3

STREAM CONSTITUENTS       AMOUNT/gram   TEMPERATURE/C   PRESSURE/bar STREAM
O2/GAS/                    1.5999E+01        20.00       1.0000E+00     1
C                          1.0000E+01        20.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: GAS                    mol                           bar
CO                         6.6514E-01     7.9890E-01     7.9890E-01
CO2                        1.6743E-01     2.0110E-01     2.0110E-01
O                          3.0441E-09     3.6562E-09     3.6562E-09
O2                         1.2593E-09     1.5126E-09     1.5126E-09
C2O                        1.6626E-14     1.9970E-14     1.9970E-14
C                          2.8498E-17     3.4229E-17     3.4229E-17
O3                         9.3779E-22     1.1264E-21     1.1264E-21
C2                         2.6273E-22     3.1556E-22     3.1556E-22
C3                         9.1060E-25     1.0937E-24     1.0937E-24
C4                         2.7548E-33     3.3088E-33     3.3088E-33
C5                         2.5090E-36     3.0135E-36     3.0135E-36
TOTAL:                     8.3257E-01     1.0000E+00     1.0000E+00
                              gram                        ACTIVITY
C                          0.0000E+00                    2.7932E-04
C_DIAMOND_A4               0.0000E+00                    1.4585E-04
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.22149E+01  -9.39612E+04   1.16311E+02  -4.58469E+05   1.10558E+02

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 3.38382E+01  -9.40697E+04   2.23251E+02  -4.89928E+05   1.22745E+02

Mass fraction of system components:
             GAS
C            0.38462
O            0.61538

 50   FORMAT(1X,A,G12.5)

! Get the change in volume that takes place
      CALL TQGETR('V ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Change in volume/dm^3 is ', RESULT
Output:
Change in volume/dm^3 is   110.56

! Get the enthalpy change for the process (since its sign is negative,
! energy is released
      CALL TQGETR('H ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Change in enthalpy/J is ', RESULT
Output:
Change in enthalpy/J is  -93961.

! Get the activity of carbon, which, at 1500 C is far from being unity
      CALL TQGETR('AC ', IC, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Activity of carbon is ', RESULT
Output:
Activity of carbon is  0.27932E-03

! Once an equilibrium has been calculated using TQCE/TQCEL, subsequent
! calculations can be performed using TQCEN/TQCENL, which speeds up the
! equilibrium calculation by taking results from the previous
! calculation as initial estimates

      DO ITEMP=1510, 1600, 10

         TEMP = ITEMP

         CALL TQSTEC('T ', 0, TEMP, NOERR)
         CALL TQCEN(' ', 0, 0, VALS, NOERR)
         CALL TQGETR('AC ', IC, 0, RESULT, NOERR)
         WRITE(*,*) 'Activity of carbon at T = ',
     *        TEMP, ' C is ', RESULT

      ENDDO
Output:
Activity of carbon at T =    1510.0000000000000       C is    2.6264470995273015E-004
Activity of carbon at T =    1520.0000000000000       C is    2.4714149363797423E-004
Activity of carbon at T =    1530.0000000000000       C is    2.3272087470949939E-004
Activity of carbon at T =    1540.0000000000000       C is    2.1929686051455182E-004
Activity of carbon at T =    1550.0000000000000       C is    2.0679105085828287E-004
Activity of carbon at T =    1560.0000000000000       C is    1.9513190446012930E-004
Activity of carbon at T =    1570.0000000000000       C is    1.8425408207791832E-004
Activity of carbon at T =    1580.0000000000000       C is    1.7409785770743723E-004
Activity of carbon at T =    1590.0000000000000       C is    1.6460861269141717E-004
Activity of carbon at T =    1600.0000000000000       C is    1.5573627473105856E-004

! Similar to TQCEL, TQCENL also provides a ChemSage output table
      CALL TQCENL(' ', 0, 0, VALS, NOERR)
Output:
T = 1600 C
P = 1 bar
V = 129.67 dm3

STREAM CONSTITUENTS       AMOUNT/gram   TEMPERATURE/C   PRESSURE/bar STREAM
O2/GAS/                    1.5999E+01        20.00       1.0000E+00     1
C                          1.0000E+01        20.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: GAS                    mol                           bar
CO                         6.6514E-01     7.9890E-01     7.9890E-01
CO2                        1.6743E-01     2.0110E-01     2.0110E-01
O                          2.1027E-08     2.5256E-08     2.5256E-08
O2                         9.4832E-09     1.1390E-08     1.1390E-08
C2O                        4.0356E-14     4.8472E-14     4.8472E-14
C                          2.1347E-16     2.5639E-16     2.5639E-16
O3                         3.2996E-20     3.9632E-20     3.9632E-20
C2                         1.6278E-21     1.9551E-21     1.9551E-21
C3                         3.1116E-24     3.7374E-24     3.7374E-24
C4                         1.0919E-32     1.3115E-32     1.3115E-32
C5                         5.9958E-36     7.2015E-36     7.2015E-36
TOTAL:                     8.3257E-01     1.0000E+00     1.0000E+00
                              gram                        ACTIVITY
C                          0.0000E+00                    1.5574E-04
C_DIAMOND_A4               0.0000E+00                    8.1689E-05
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.24040E+01  -9.05677E+04   1.18173E+02  -4.80888E+05   1.17480E+02

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 3.40272E+01  -9.06762E+04   2.25113E+02  -5.12346E+05   1.29667E+02

Mass fraction of system components:
             GAS
C            0.38462
O            0.61538

! Check if we are working with the 'light' version.
! If we do, omit the following phase target calculation(s).
      CALL TQLITE(ISLITE, NOERR)
      IF (ISLITE .EQ. 1) THEN
         WRITE(*,FMT='(3(1X,A,/))')
     *     '*** Phase target calculations have been omitted here,',
     *     '*** since they are not possible with the',
     *     '*** ''light'' version of ChemApp.'

      ELSE

! PERFORMING target calculations
C
! Note that target calculations are not possible with ChemApp "light",
! you need the regular version of ChemApp to run the examples below.
C
! Performing target calculations requires that ChemApp needs to be told
! 2 things:
! - the target itself,
! - the target variable, i.e. which variable ChemApp is allowed to vary
!   to achieve the target.
!
! First we will perform a formation phase target calculation, which is
! used to determine the conditions under which a phase becomes stable,
! using carbon as an example. As a target variable we will use the
! temperature. The result will be the temperature under which solid
! carbon will just become stable (smoke point).

! Define the target: phase C, amount of C = 0
      CALL TQSTEC('A ', IC, 0.D0, NOERR)

! Define the target variable, which is done during the call to TQCE.
! The value passed as VALS(1) will be taken as an initial estimate.
      VALS(1) = 500.D0
      CALL TQCE('T ', 0, 0, VALS, NOERR)

! Get the temperature, which ChemApp determined
      CALL TQGETR('T ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Calculated formation temperature of ' //
     *     'carbon in degrees Celsius: ', RESULT
Output:
Calculated formation temperature of carbon in degrees Celsius:   756.35

! Check whether ChemApp calculated correctly by verifying that the
! activity of carbon is unity.
      CALL TQGETR('AC ', IC, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Activity of carbon is ', RESULT
Output:
Activity of carbon is   1.0000

! The equilibrium amount of carbon should still be zero though, as we
! had ChemApp find the temperature where carbon _just_ gets stable
      CALL TQGETR('A ', IC, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Amount of carbon is ', RESULT
Output:
Amount of carbon is   0.0000

! It is also possible to specify a different amount than zero for the
! phase formation target calculation. To to this, pass a different value
! to TQSTEC when defining the target. As an example, calculate the
! temperature where 1 gram of carbon is stable
      CALL TQSTEC('A ', IC, 1.D0, NOERR)
      CALL TQCE('T ', 0, 0, VALS, NOERR)
      CALL TQGETR('T ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Calculated formation temperature for ' //
     *     '1 gram of carbon in deg. Celsius:',
     *     RESULT
Output:
Calculated formation temperature for 1 gram of carbon in deg. Celsius:  713.05

      ENDIF

! Before performing extensive property target calculations, TQREMC is
! used to remove all conditions and targets set previously.
      CALL TQREMC(-2, NOERR)

! Remove also the stream 'inputs'
      CALL TQSTRM('inputs ', NOERR)

! It is also useful to reset VALS, which now still contains a starting
! value for a temperature in VALS(1)
      VALS(1) = 0

! If it is also desired to reset all units to default units, which would
! in this case reset the amount to mol and the temperature unit to
! Kelvin, call TQREMC with a value of -1
      CALL TQREMC(-1, NOERR)

! Set up a new stream which contains 1 mol of pure oxygen, preheated to
! 400 K at 1 bar
      TP(1) = 400.0
      TP(2) = 1.0
      CALL TQSTTP('oxygen ', TP, NOERR)
      CALL TQSTCA('oxygen ', 1, IO2, 1.D0, NOERR)

! Another stream that contains 1 mol of solid carbon at room
! temperature and 1 bar
      TP(1) = 298.15
      TP(2) = 1.0
      CALL TQSTTP('carbon ', TP, NOERR)
      CALL TQSTCA('carbon ', IC, 0, 1.D0, NOERR)

! Calculate the equilibrium and retrieve the enthalpy released for this
! process
      CALL TQCE(' ', 0, 0, VALS, NOERR)
      CALL TQGETR('H ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Change in enthalpy/J is ', RESULT
Output:
Change in enthalpy/J is -0.36313E+06

! Determine the adiabatic temperature for this process. This would be
! the temperature at which the above mentioned enthalpy is zero

! Define the target: enthalpy, value = 0
      CALL TQSTEC('H ', 0, 0.D0, NOERR)

! Define the target variable, which is done during the call to TQCE.
! The value passed as VALS(1) will be taken as an initial estimate.
      VALS(1) = 1000.D0
      CALL TQCE('T ', 0, 0, VALS, NOERR)

! Get the temperature ChemApp calculated (which is the adiabatic
! temperature in this example)
      CALL TQGETR('T ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Calculated adiabatic temperature/K for ' //
     *     'this process: ', RESULT
Output:
Calculated adiabatic temperature/K for this process:   3290.4

! One can investigate how this temperature changes if one assumes a
! mixture that resembles air, instead of pure O2. Air has an N2/O2 ratio
! of about 4:1. Keeping 1 mol of oxygen, we thus have to add 4 mol of
! N2.
      CALL TQINPC('N2 ', 1, IN2, NOERR)
      CALL TQSTCA('oxygen ', 1, IN2, 4.D0, NOERR)

      CALL TQCE('T ', 0, 0, VALS, NOERR)

      CALL TQGETR('T ', 0, 0, RESULT, NOERR)
      WRITE(*,FMT=50) 'Adiabatic temperature/K for this process ' //
     *     'with an N2/O2 mixture: ', RESULT


      END
Output:
Adiabatic temperature/K for this process with an N2/O2 mixture:   2295.3


C:
/* Program cac18 */
/* Calculation of different phase equilibria */

/* Note that this program contains phase target calculations,
   which cannot be performed with the 'light' version of ChemApp */

#include "cacint.h"

int main()
{
  LI noerr, islite, iO2, iC, iN2;
  DB vals[2], TP[2], result, temp;


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

  /* Open data-file for reading. In this case, a data-file containing
     the thermochemical data for the system carbon-nitrogen-oxygen is
     selected. */
  tqopna("cno.dat",10,&noerr);

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

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


  /* Since we will perform an extensive property target calculation
     later, we will do the equilibrium calculations using
     streams. This way we can associate an initial state regarding
     temperature and pressure to the incoming substances, which will
     be taken into account when ChemApp calculates the extensive
     property (e.g. heat) balance. */

  /* Since we are going to prefer degrees Celsius as temperature unit,
     we will change the unit now */
  tqcsu("Temperature", "C", &noerr);

  /* Define a stream at room temperature and 1 bar */
  TP[0] = 20.0;
  TP[1] = 1.0;
  tqsttp("inputs", TP, &noerr);

  /* Set stream constituents: 0.5 mol of oxygen and 10 grams of carbon */

  /* Get the index number of the phase constituent oxygen ("O2") in
     the gas phase. If a thermochemical data-file for ChemApp
     contains a gas phase, it is always the first one: */
  tqinpc("O2", 1, &iO2, &noerr);

  /* Get the index number of the phase carbon ("C") */
  tqinp("C", &iC, &noerr);

  /* Set the incoming amount of oxygen in the stream (0.5 mol) */
  tqstca("inputs", 1, iO2, .5, &noerr);

  /* Change the amount unit to gram and set the incoming amount of
     carbon in the stream (10 gram) */
  tqcsu("Amount", "gram", &noerr);
  tqstca("inputs", iC, 0, 10.0, &noerr);

  /* Set the temperature for the equilibrium calculation (1500 C) */
  tqstec("T", 0, 1500.0, &noerr);

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

  /* Get the change in volume that takes place */
  tqgetr("V", 0, 0, &result, &noerr);
  printf("Change in volume/dm^3 is %g\n", result);
Output:
Change in volume/dm^3 is 110.558

/* Get the enthalpy change for the process (since its sign is
   negative, energy is released */
tqgetr("H", 0, 0, &result, &noerr);
printf("Change in enthalpy/J is %g\n", result);
Output:
Change in enthalpy/J is -93961.2

/* Get the activity of carbon, which, at 1500 C is far from being
   unity */
tqgetr("ac", iC, 0, &result, &noerr);
printf("Activity of carbon is %g\n", result);
Output:
Activity of carbon is 0.000279325

/* Once an equilibrium has been calculated using tqce/tqcel,
   subsequent calculations can be performed using tqcen/tqcenl,
   which speeds up the equilibrium calculation by taking results
   from the previous calculation as initial estimates */
for (temp = 1510; temp <= 1600; temp +=10) {

  tqstec("T", 0, temp, &noerr);
  tqcen(" ", 0, 0, vals, &noerr);
  tqgetr("ac", iC, 0, &result, &noerr);
  printf("Activity of carbon at T = %g C is %g\n", temp, result);

}
Output:
Activity of carbon at T = 1510 C is 0.000262645
Activity of carbon at T = 1520 C is 0.000247141
Activity of carbon at T = 1530 C is 0.000232721
Activity of carbon at T = 1540 C is 0.000219297
Activity of carbon at T = 1550 C is 0.000206791
Activity of carbon at T = 1560 C is 0.000195132
Activity of carbon at T = 1570 C is 0.000184254
Activity of carbon at T = 1580 C is 0.000174098
Activity of carbon at T = 1590 C is 0.000164609
Activity of carbon at T = 1600 C is 0.000155736

/* Similar to tqcel, tqcenl also provides a ChemSage output table */
tqcenl(" ", 0, 0, vals, &noerr);
Output:
T = 1600 C
P = 1 bar
V = 129.67 dm3

STREAM CONSTITUENTS       AMOUNT/gram   TEMPERATURE/C   PRESSURE/bar STREAM
O2/GAS/                    1.5999E+01        20.00       1.0000E+00     1
C                          1.0000E+01        20.00       1.0000E+00     1

                          EQUIL AMOUNT  MOLE FRACTION     FUGACITY
PHASE: GAS                    mol                           bar
CO                         6.6514E-01     7.9890E-01     7.9890E-01
CO2                        1.6743E-01     2.0110E-01     2.0110E-01
O                          2.1027E-08     2.5256E-08     2.5256E-08
O2                         9.4832E-09     1.1390E-08     1.1390E-08
C2O                        4.0356E-14     4.8472E-14     4.8472E-14
C                          2.1347E-16     2.5639E-16     2.5639E-16
O3                         3.2996E-20     3.9632E-20     3.9632E-20
C2                         1.6278E-21     1.9551E-21     1.9551E-21
C3                         3.1116E-24     3.7374E-24     3.7374E-24
C4                         1.0919E-32     1.3115E-32     1.3115E-32
C5                         5.9958E-36     7.2015E-36     7.2015E-36
TOTAL:                     8.3257E-01     1.0000E+00     1.0000E+00
                              gram                        ACTIVITY
C                          0.0000E+00                    1.5574E-04
C_DIAMOND_A4               0.0000E+00                    8.1689E-05
********************************************************************
  DELTA Cp       DELTA H       DELTA S       DELTA G       DELTA V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 1.24040E+01  -9.05677E+04   1.18173E+02  -4.80888E+05   1.17480E+02

********************************************************************
     Cp             H             S             G             V
    J.K-1           J           J.K-1           J            dm3
********************************************************************
 3.40272E+01  -9.06762E+04   2.25113E+02  -5.12346E+05   1.29667E+02

Mass fraction of system components:
             GAS
C            0.38462
O            0.61538

/* Check if we are working with the 'light' version.
   If we do, omit the following phase target calculation(s). */
tqlite(&islite, &noerr);
if (islite)
  {
    printf("*** Phase target calculations have been omitted here,\n"
           "*** since they are not possible with the\n"
           "*** 'light' version of ChemApp.\n\n");
  }
else
  {


/* Performing target calculations */

/* Note that target calculations are not possible with ChemApp
   "light", you need the regular version of ChemApp to run the
   examples below. */

/* Performing target calculations requires that ChemApp needs to be
   told 2 things:
   - the target itself,
   - the target variable, i.e. which variable ChemApp is allowed to
     vary to achieve the target.

   First we will perform a formation phase target calculation, which
   is used to determine the conditions under which a phase becomes
   stable, using carbon as an example. As a target variable we will
   use the temperature. The result will be the temperature under
   which solid carbon will just become stable (smoke point). */

/* Define the target: phase C, amount of C = 0 */
tqstec("a", iC, 0.0, &noerr);

/* Define the target variable, which is done during the call to
   tqce.  The value passed as vals[0] will be taken as an initial
   estimate. */
vals[0] = 500.0;
tqce("T", 0, 0, vals, &noerr);

/* Get the temperature, which ChemApp determined */
tqgetr("T", 0, 0, &result, &noerr);
printf("Calculated formation temperature of "
      "carbon in degrees Celsius: %g\n", result);
Output:
Calculated formation temperature of carbon in degrees Celsius: 756.345

/* Check whether ChemApp calculated correctly by verifying that the
   activity of carbon is unity. */
tqgetr("ac", iC, 0, &result, &noerr);
printf("Activity of carbon is %g\n", result);
Output:
Activity of carbon is 1

/* The equilibrium amount of carbon should still be zero though, as
   we had ChemApp find the temperature where carbon _just_ gets
   stable */
tqgetr("a", iC, 0, &result, &noerr);
printf("Amount of carbon is %g\n", result);
Output:
Amount of carbon is 0

/* It is also possible to specify a different amount than zero for
   the phase formation target calculation. To to this, pass a
   different value to tqstec when defining the target. As an
   example, calculate the temperature where 1 gram of carbon is
   stable */
tqstec("a", iC, 1.0, &noerr);
tqce("T", 0, 0, vals, &noerr);
tqgetr("T", 0, 0, &result, &noerr);
printf("Calculated formation temperature for "
       "1 gram of carbon in deg. Celsius: %g\n", result);
Output:
Calculated formation temperature for 1 gram of carbon in deg. Celsius: 713.054

}

/* Before performing extensive property target calculations, tqremc
   is used to remove all conditions and targets set previously */
tqremc(-2, &noerr);

/* Remove also the stream "inputs" */
tqstrm("inputs", &noerr);

/* It is also useful to reset vals, which now still contains a
   starting value for a temperature in vals[0] */
vals[0] = 0;

/* If it is also desired to reset all units to default units, which
   would in this case reset the amount to mol and the temperature
   unit to Kelvin, call tqremc with a value of -1 */
tqremc(-1, &noerr);

/* Set up a new stream which contains 1 mol of pure oxygen,
   preheated to 400 K at 1 bar */
TP[0] = 400.0;
TP[1] = 1.0;
tqsttp("oxygen", TP, &noerr);
tqstca("oxygen", 1, iO2, 1.0, &noerr);

/* Another stream that contains 1 mol of solid carbon at room
   temperature and 1 bar */
TP[0] = 298.15;
TP[1] = 1.0;
tqsttp("carbon", TP, &noerr);
tqstca("carbon", iC, 0, 1.0, &noerr);

/* Calculate the equilibrium and retrieve the enthalpy released for
   this process */
tqce(" ", 0, 0, vals, &noerr);
tqgetr("H", 0, 0, &result, &noerr);
printf("Change in enthalpy/J is %g\n", result);
Output:
Change in enthalpy/J is -363127

/* Determine the adiabatic temperature for this process. This would
   be the temperature at which the above mentioned enthalpy is
   zero */

/* Define the target: enthalpy, value = 0 */
tqstec("H", 0, 0.0, &noerr);

/* Define the target variable, which is done during the call to
   tqce. The value passed as vals[0] will be taken as an initial
   estimate. */
vals[0] = 1000.0;
tqce("T", 0, 0, vals, &noerr);

/* Get the temperature ChemApp calculated (which is the adiabatic
   temperature in this example) */
tqgetr("T", 0, 0, &result, &noerr);
printf("Calculated adiabatic temperature/K for "
       "this process: %g\n", result);
Output:
Calculated adiabatic temperature/K for this process: 3290.38

  /* One can investigate how this temperature changes if one assumes a
     mixture that resembles air, instead of pure O2. Air has an N2/O2
     ratio of about 4:1. Keeping 1 mol of oxygen, we thus have to add
     4 mol of N2. */
  tqinpc("N2", 1, &iN2, &noerr);
  tqstca("oxygen", 1, iN2, 4.0, &noerr);

  tqce("T", 0, 0, vals, &noerr);

  tqgetr("T", 0, 0, &result, &noerr);
  printf("Adiabatic temperature/K for this process "
         "with a N2/O2 mixture: %g\n", result);

  return 0;

}
Output:
Adiabatic temperature/K for this process with a N2/O2 mixture: 2295.3

5.2   TQCEL

CALCULATE-EQUILIBRIUM-AND-LIST-RESULTS

Use TQCEL to calculate the equilibrium with current settings of global conditions or streams, and list the results in the form of a ChemSage format output table.

Synopsis

FORTRAN:
CALL TQCEL(OPTION,INDEXP,INDEXC,VALS,NOERR)
C:
tqcel(option,indexp,indexc,vals,&noerr);
Pascal:
tqcel(option,indexp,indexc,vals,noerr);
Basic:
Call tqcel(option,indexp,indexc,vals,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining targets when calling TQCE/TQCEL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to an initial estimate of the target variable, or the lower and upper limits of an incoming amount, if necessary
NOERR INTEGER Returns an error number

The parameters and their conditions are identical to those for TQCE. A result table is produced after finishing the calculations and is written to unit LIST, see Table Legal input/output options used by TQGIO and TQCIO. The amount unit used in the output table is the one which is currently selected (i.e. 'mol' by default).

See also
TQCE, TQSETC, TQCEL, TQSTEC, TQSHOW, TQMAPL

Example

See
TQCE

5.3   TQCEN

CALCULATE-EQUILIBRIUM-NO-ESTIMATION

Use TQCEN to calculate the equilibrium, taking results from the previous equilibrium calculation as initial estimates

Added for ChemApp version 5.0.0

Synopsis

FORTRAN:
CALL TQCEN(OPTION,INDEXP,INDEXC,VALS,NOERR)
C:
tqcen(option,indexp,indexc,vals,&noerr);
Pascal:
tqcen(option,indexp,indexc,vals,noerr);
Basic:
Call tqcen(option,indexp,indexc,vals,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining targets when calling TQCE/TQCEL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to an initial estimate of the target variable, or the lower and upper limits of an incoming amount, if necessary
NOERR INTEGER Returns an error number

Once an equilibrium has been calculated with TQCE or TQCEL, subsequent equilibria can be executed using TQCEN or TQCENL. When the two latter subroutines are called, results from the previous equilibrium calculation are used as initial estimates. This will result in a noticable increase of the computational efficiency, especially when the current settings of global conditions or streams are close to those of the previous calculation.

Error code 516 will result if the status of a phase constituent or a phase has been modified since the last executed phase equilibrium. Thus, after a call to TQCEN, the application programmer is advised to check NOERR for this value, and recalculate the equilibrium using TQCE if it equals 516.

For systems which include mixtures described with the models SUBG, SUBS, or QUAS (see Table Identifiers of phase model names as returned by TQMODL), the use of TQCEN might not necessarily lead to shorter computing times.

If convergence would fail because of poor initial estimates, or if a system component is added or deleted after the last executed equilibrium, then the calculation will be automatically repeated with initial estimates produced by ChemApp.

For a description of the parameters and constraints, see TQCE.

See also
TQCE, TQCENL

Example

See
TQCE

5.4   TQCENL

CALCULATE-EQUILIBRIUM-NO-ESTIMATES-AND-LIST-RESULTS

Use TQCENL to calculate the equilibrium, taking results from the previous equilibrium calculation as initial estimates, and list the results in the form of a ChemSage format output table.

Added for ChemApp version 5.0.0

Synopsis

FORTRAN:
CALL TQCENL(OPTION,INDEXP,INDEXC,VALS,NOERR)
C:
tqcenl(option,indexp,indexc,vals,&noerr);
Pascal:
tqcenl(option,indexp,indexc,vals,noerr);
Basic:
Call tqcenl(option,indexp,indexc,vals,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining targets when calling TQCE/TQCEL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to an initial estimate of the target variable, or the lower and upper limits of an incoming amount, if necessary
NOERR INTEGER Returns an error number

The parameters and their conditions are identical to those for TQCE, TQCEL, and TQCEN. A result table is produced after finishing the calculations and is written to unit LIST, see Table Legal input/output options used by TQGIO and TQCIO. The amount unit used in the output table is the one which is currently selected (i.e. 'mol' by default).

See the description for TQCEN with respect to possible errors messages returned by TQCENL.

See also
TQCE, TQCEN

Example

See
TQCE

5.5   TQMAP

CALCULATE-ONE-DIMENSIONAL-PHASE-MAP

Use TQMAP to perform a one-dimensional phase mapping calculation, giving all phase transitions within a defined interval.

Added for ChemApp version 3.0.0

Synopsis

FORTRAN:
CALL TQMAP(OPTION,INDEXP,INDEXC,VALS,ICONT,NOERR)
C:
tqmap(option,indexp,indexc,vals,&icont,&noerr);
Pascal:
tqmap(option,indexp,indexc,vals,icont,noerr);
Basic:
Call tqmap(option,indexp,indexc,vals,icont,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining one-dimensional phase mapping calculations using TQMAP/TQMAPL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to the lower and upper limits of the search variable
ICONT INTEGER Returns a value indicating whether more calls to TQMAP/TQMAPL are necessary
NOERR INTEGER Returns an error number

OPTION, INDEXP, INDEXC, and VALS are all input, ICONT and NOERR are output. See Table State variables for defining one-dimensional phase mapping calculations using TQMAP/TQMAPL for the mnemonics of possible search variables. VALS is an array of two double precision values which is always used to pass the lower and upper bounds of the search interval to TQMAP.

The constraints for the two values of VALS entered are: VALS(1) and VALS(2) must not be equal, and VALS(2) must be greater than, or, for incoming amount as search variable, equal to zero. VALS is entered with the default unit, or a unit set using TQCSU (see Initialising the Interface and Reading a Data-file).

For every one-dimensional phase map, the first two calls to TQMAP return the equilibrium state of the system at VALS(1) and VALS(2) and not results relating to any phase boundary. Beginning with the third and every subsequent call of TQMAP, the output variable ICONT has to be tested. If it does have a positive value, more calls to TQMAP need to be made.

In case incoming amount is the search variable, and incoming amounts for more than one substance need to be defined, all except the last one have to be called using 'IA0' as option to TQMAP. Once 'IAF' is passed for the last incoming amount, the first calculation is made. Subsequently 'IAN' is used as OPTION for all following calls to TQMAP. See One-dimensional phase mapping for an example of how to use TQMAP with incoming amount as search variable.

See also
TQMAPL, TQCE

Example

Fortran:
! One-dimensional phase mapping calculation

! Note that this program contains phase target calculations,
! which cannot be performed with the 'light' version of ChemApp

      PROGRAM CAF24
      IMPLICIT NONE

      INTEGER NOERR, NUMCON, ISLITE, ISIO2, RESNO, ICONT
      DOUBLE PRECISION VALS(2), RESULT

      RESNO = 0


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

! Check if we are working with the 'light' version.
! If we do, omit the following phase target calculation(s).
      CALL TQLITE(ISLITE, NOERR)
      IF (ISLITE .EQ. 1) THEN
         WRITE(*,FMT='(3(1X,A,/))')
     *     '*** Phase target calculations have been omitted here,',
     *     '*** since they are not possible with the',
     *     '*** ''light'' version of ChemApp.'

      ELSE

! Determine the index number for the phase SiO2(quartz)
      CALL TQINP('SiO2(quartz) ', ISIO2, NOERR)

! Enter one mol of SiO2
      CALL TQSETC('IA ', ISIO2, 0, 1.0D0, NUMCON, NOERR)


! The temperature search interval is supposed to range from 300 to
! 3000 K:
      VALS(1) = 300.D0
      VALS(2) = 3000.D0

! First call to TQMAP, note the 'F' ('First') in the option parameter
      CALL TQMAP('TF ',0,0,VALS,ICONT,NOERR)

! The variable RESNO keeps track of the number of times we called TQMAP:
      RESNO = RESNO + 1

! Retrieve and print the temperature, which we know is VALS(1)
      CALL TQGETR('T ',0,0,RESULT,NOERR)

 100  FORMAT(A,F8.2,A)

      WRITE(*,100) '*** Lower interval boundary:', RESULT, ' K'

   30 CONTINUE

! TQMAP is called again. Note the 'N' ('Next') in the option
! parameter. If we are at the first phase boundary (RESNO is still 2),
! we call TQMAPL for a change to produce a ChemSage output table...

      IF (RESNO .EQ. 2) THEN
         WRITE(*,FMT='(A)')
     *   '*** ChemSage result table for the first phase boundary found:'
         CALL TQMAPL('TN ',0,0,VALS,ICONT,NOERR)
         WRITE(*,*)
! ...otherwise we just call TQMAP:
      ELSE
         CALL TQMAP('TN ',0,0,VALS,ICONT,NOERR)
      ENDIF
      RESNO = RESNO +1

! Get the temperature...
      CALL TQGETR('T ',0,0,RESULT,NOERR)

! ... and print the entry for the result table. If we have called TQMAP
! twice already, we know that we have found a phase boundary. If not, we
! have retrieved the temperature value of the upper interval boundary
! VALS(2):
      IF (RESNO .GT. 2) THEN
         WRITE(*,100) '*** Phase boundary found at ', RESULT, ' K'
      ELSE
         WRITE(*,100) '*** Upper interval boundary: ', RESULT, ' K'
      ENDIF

! For as long as ICONT is positive, we need to make further calls of
! TQMAP
      IF (ICONT .GT. 0) GOTO 30
Output:
*** Lower interval boundary:  300.00 K
*** Upper interval boundary:  3000.00 K
*** ChemSage result table for the first phase boundary found:

 *T = 1140.10 K
 P = 1 bar
 V = 0 dm3

 STREAM CONSTITUENTS        AMOUNT/mol
 SiO2(quartz)               1.0000E+00

                           EQUIL AMOUNT  MOLE FRACTION     FUGACITY
 PHASE: GAS                    mol                           bar
 SiO                        0.0000E+00     6.2502E-01     4.4829E-16
 O2                         0.0000E+00     2.5088E-01     1.7994E-16
 O                          0.0000E+00     1.2327E-01     8.8415E-17
 SiO2                       0.0000E+00     8.3208E-04     5.9681E-19
 Si                         0.0000E+00     4.4651E-15     3.2026E-30
 O3                         0.0000E+00     2.4636E-19     1.7670E-34
 Si2                        0.0000E+00     5.5659E-36     3.9921E-51
 Si3                        0.0000E+00     9.0161E-54     6.4667E-69
 TOTAL:                     0.0000E+00     1.0000E+00     7.1725E-16
                               mol                         ACTIVITY
 SiO2(quartz)               1.0000E+00                    1.0000E+00
 SiO2(tridymite)            0.0000E+00                    1.0000E+00
 SiO2(cristobali)           0.0000E+00                    9.9398E-01
 SiO2(liquid)               0.0000E+00                    6.4439E-01
 Si                         0.0000E+00                    2.5802E-17
 ********************************************************************
      Cp             H             S             G             V
     J.K-1           J           J.K-1           J            dm3
 ********************************************************************
  7.04990E+01  -8.55398E+05   1.25413E+02  -9.98382E+05   0.00000E+00

*** Phase boundary found at  1140.10 K
*** Phase boundary found at  1738.28 K
*** Phase boundary found at  1995.99 K

! With the above example the temperatures of all phase boundaries in a
! system which contains 1 mol of SiO2 have been calculated. Thus the
! phase boundaries determined reflect the stability ranges of the
! various modifications of SiO2. Also note again that the first two
! temperatures determined are _no_ phase boundaries, but the lower and
! upper limit of the search interval (VALS(1) and VALS(2)).
!
! For the first phase boundary found, TQMAPL is called instead of TQMAP,
! thus producing a ChemSage output table. From this ChemSage output
! table it can be seen that at the temperature calculated SiO2
! transforms from the quartz into the tridymite modification.
!
! Refer to the worked example 5 (One-dimensional phase mapping) for a
! further example. This also demonstrates how to obtain information on
! which phases are stable at each of the phase boundaries determined.

      ENDIF
      END


C:
/* Program cac24 */
/* One-dimensional phase mapping calculation */

/* Note that this program contains phase target calculations,
   which cannot be performed with the 'light' version of ChemApp */

#include "cacint.h"

int main()
{
  LI noerr, numcon, islite, iSiO2, resno=0, icont;
  DB vals[2], result;


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

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

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

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

  /* Check if we are working with the 'light' version.
     If we do, omit the following phase target calculation(s). */
  tqlite(&islite, &noerr);
  if (islite)
    {
      printf("*** Phase target calculations have been omitted here,\n"
             "*** since they are not possible with the\n"
             "*** 'light' version of ChemApp.\n\n");
    }
  else
    {


  /* Determine the index number for the phase SiO2(quartz) */
  tqinp("SiO2(quartz)", &iSiO2, &noerr);

  /* Enter one mol of SiO2 */
  tqsetc("IA", iSiO2, 0, 1.0, &numcon, &noerr);


  /* The temperature search interval is supposed to range from 300 to
     3000 K: */
  vals[0] = 300.0;
  vals[1] = 3000.0;

  /* First call to tqmap, note the "f" ("first") in the option
     parameter */
  tqmap("tf", 0, 0, vals, &icont, &noerr);

  /* The variable resno keeps track of the number of times we call
     tqmap: */
  resno++;

  /* Retrieve and print the temperature, which we know is vals[0]: */
  tqgetr("t", 0, 0, &result, &noerr);
  printf("*** Lower interval boundary: %g K\n", result);

  /* For as long as icont is positive, we need to make further calls
     of tqmap */
  while (icont) {

    /* tqmap is called again. Note the "n" ("next") in the option
       parameter. If we are at the first phase boundary (resno is
       still 2), we call tqmapl for a change to produce a ChemSage
       output table... */
    if (resno == 2) {
      printf("*** ChemSage result table "
            "for the first phase boundary found:\n");
      tqmapl("tn", 0, 0, vals, &icont, &noerr);
      printf("\n");

      /* ...otherwise we just call tqmap: */
    } else {
      tqmap("tn", 0, 0, vals, &icont, &noerr);
    }
    resno++;

    /* Get the temperature... */
    tqgetr("t", 0, 0, &result, &noerr);

    /* ...and print the entry for the result table. If we have called
       tqmap twice already, we know that we have found a phase
       boundary. If not, we have retrieved the temperature value of
       the upper interval boundary (vals[1]): */

    if (resno > 2) {
      printf("*** Phase boundary found at %g K\n", result);
    } else {
      printf("*** Upper interval boundary: %g K\n", result);
    }


  }
Output:
*** Lower interval boundary: 300 K
*** Upper interval boundary: 3000 K
*** ChemSage result table for the first phase boundary found:

 *T = 1140.10 K
 P = 1 bar
 V = 0 dm3

 STREAM CONSTITUENTS        AMOUNT/mol
 SiO2(quartz)               1.0000E+00

                           EQUIL AMOUNT  MOLE FRACTION     FUGACITY
 PHASE: GAS                    mol                           bar
 SiO                        0.0000E+00     6.2502E-01     4.4829E-16
 O2                         0.0000E+00     2.5088E-01     1.7994E-16
 O                          0.0000E+00     1.2327E-01     8.8415E-17
 SiO2                       0.0000E+00     8.3208E-04     5.9681E-19
 Si                         0.0000E+00     4.4651E-15     3.2026E-30
 O3                         0.0000E+00     2.4636E-19     1.7670E-34
 Si2                        0.0000E+00     5.5659E-36     3.9921E-51
 Si3                        0.0000E+00     9.0161E-54     6.4667E-69
 TOTAL:                     0.0000E+00     1.0000E+00     7.1725E-16
                               mol                         ACTIVITY
 SiO2(quartz)               1.0000E+00                    1.0000E+00
 SiO2(tridymite)            0.0000E+00                    1.0000E+00
 SiO2(cristobali)           0.0000E+00                    9.9398E-01
 SiO2(liquid)               0.0000E+00                    6.4439E-01
 Si                         0.0000E+00                    2.5802E-17
 ********************************************************************
      Cp             H             S             G             V
     J.K-1           J           J.K-1           J            dm3
 ********************************************************************
  7.04990E+01  -8.55398E+05   1.25413E+02  -9.98382E+05   0.00000E+00

*** Phase boundary found at 1140.1 K
*** Phase boundary found at 1738.28 K
*** Phase boundary found at 1995.99 K

  /* With the above example the temperatures of all phase boundaries in a
     system which contains 1 mol of SiO2 have been calculated. Thus the
     phase boundaries determined reflect the stability ranges of the
     various modifications of SiO2. Also note that the first two
     temperatures determined are _no_ phase boundaries, but the lower and
     upper limit of the search interval (vals[0] and vals[1]).

     For the first phase boundary found, tqmapl is called instead of
     tqmap, thus producing a ChemSage output table. From this ChemSage
     output table it can be seen that at the temperature calculated
     SiO2 transforms from the quartz into the tridymite modification.

     Refer to the worked example 5 (One-dimensional phase mapping) for
     a further example. This also demonstrates how to obtain
     information on which phases are stable at each of the phase
     boundaries determined. */

  }

  return 0;

}

5.6   TQMAPL

CALCULATE-ONE-DIMENSIONAL-PHASE-MAP-AND-LIST-RESULTS

Use TQMAP to perform a one-dimensional phase mapping calculation and list the results in the form of a ChemSage format output table.

Added for ChemApp version 3.0.0

Synopsis

FORTRAN:
CALL TQMAPL(OPTION,INDEXP,INDEXC,VALS,ICONT,NOERR)
C:
tqmapl(option,indexp,indexc,vals,&icont,&noerr);
Pascal:
tqmapl(option,indexp,indexc,vals,icont,noerr);
Basic:
Call tqmapl(option,indexp,indexc,vals,icont,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table State variables for defining one-dimensional phase mapping calculations using TQMAP/TQMAPL
INDEXP INTEGER Set to the index number for a phase, if necessary
INDEXC INTEGER Set to the index number for a constituent, if necessary
VALS Array of 2 of DOUBLE PRECISION Set to the lower and upper limits of the search variable
ICONT INTEGER Returns a value indicating whether more calls to TQMAP / TQMAPL are necessary
NOERR INTEGER Returns an error number

The parameters and their conditions are identical to those for TQMAP, except that a result table is produced after conclusion of the calculation. This output is written to unit LIST, see Table Legal input/output options used by TQGIO and TQCIO. The amount unit used in the output table is the one which is currently selected (i.e. 'mol' by default).

See also
TQMAP, TQCE

Example

See
TQMAP

5.7   TQCLIM

CHANGE-LIMIT-OF-TARGET-VARIABLE

Use TQCLIM to modify the upper and lower limits of the target variables pressure, volume, or temperature.

Synopsis

FORTRAN:
CALL TQCLIM(OPTION,VAL,NOERR)
C:
tqclim(option,val,&noerr);
Pascal:
tqclim(option,val,noerr);
Basic:
Call tqclim(option,val,noerr)

Name Type Value set on call or returned
OPTION CHARACTER Set to a string as shown in Table Options for modifying upper and lower limits of target variables using TQCLIM
VAL DOUBLE PRECISION Set to a limit in the default unit
NOERR INTEGER Returns an error number

OPTION is a character variable identifying the limit to be changed. VAL is entered with a default unit (bar/dm3/K), irrespective of which system units have been set with TQCSU. In a target calculation, the lower and upper limits of a target variable are never exceeded. One specific solution of several possible ones can be found by changing the default numbers in Table Options for modifying upper and lower limits of target variables using TQCLIM, such that the interval is reduced. By reducing TLOW, a calculated temperature can have a value below room temperature. When composition is the target variable, the range can only be changed by modifying VALS(1) and VALS(2) using TQCE/TQCEL, see Table State variables for defining targets when calling TQCE/TQCEL.


Example

Fortran:
! Change the limits of target variables

! Note that this program contains phase target calculations,
! which cannot be performed with the 'light' version of ChemApp

      PROGRAM CAF22
      IMPLICIT NONE

      INTEGER NOERR, ISLITE, NUMCON, IPB, ISN, ILIQ, IFCC
      DOUBLE PRECISION TEMP, ACT, VALS(2)


! Initialise ChemApp
      CALL TQINI(NOERR)

! Check if we are working with the 'light' version.
! If we do, omit the following phase target calculation(s).
      CALL TQLITE(ISLITE, NOERR)
      IF (ISLITE .EQ. 1) THEN
         WRITE(*,FMT='(3(1X,A,/))')