How to Use ChemApp

Only three stages of simple programming are necessary to proceed from initialisation of the ChemApp routine to collection of results:

  1. initialise the interface, read a thermodynamic data-file, and adjust the chemical system
  2. set initial conditions for the equilibrium calculation
  3. perform the calculation and collect results.

In the simplest cases, each programming step requires calling only one or two of the ChemApp interface routines. For more complicated applications, the number of routines called in each step increases; however, the demands on programming capabilities are never particularly difficult. Error reporting is flexible and easy.

1. Initialise the interface and read a thermodynamic data-file

The subroutines shown in Table 2 are used for programming in this stage, which entails initialising the interface, reading a thermodynamic data-file into the program, and changing default units, if necessary.

Table 2: 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
TQSIZE Gets the internal array dimensions of ChemApp
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
TQOPEN Opens a file (for non-FORTRAN applications only)
TQCLOS Closes a file (for non-FORTRAN applications only)
TQGSU Gets a system unit
TQCSU Changes a system unit

Adjust the chemical system

A further series of programming subroutines enable the chemical system to be adjusted to match the requirements of the calculation:

  • identification of phases, phase constituents, and system components Table 3
  • delete or activate phases and/or constituents from a calculation Table 4.

Table 3: 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
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

Table 4: 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

2. Set the initial conditions for the equilibrium calculation

ChemApp code offers you considerable flexibility for defining initial conditions for a chemical equilibrium calculation. Two different methods are available that will cover most cases experienced in practice.

  • by defining the global conditions of the systemUsing this method, you merely need to set single conditions for pressure and temperature, and enter incoming species to define the composition of the system. For example, if you wish to calculate the thermodynamic equilibrium for the system SiO2-CaO, using a ChemSage – compatible data-file that 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 routine TQSETC and can be removed subsequently with the subroutine TQREMC Table 5. Note that instead of temperature and pressure you can also choose other variables of state Table 6.
  • by defining streamsA stream is considered as a non-reactive medium for transferring matter to a reaction zone. It has constant temperature and pressure, and contains one or more phases of fixed composition. Hence, when using this method, you need to define the conditions for the three variables – composition, temperature and pressure – for one or more input streams.Streams are defined using the subroutine TQSTTP Table 5 and can be switched off again by using the subroutine TQSTRM.This 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.

Note that you can only use one of these methods at a time; they cannot be both used simultaneously.

Table 5: 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

Table 6: 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.
T Temperature Default value is 1000 K.
A Amount of phase A positive value defines a formation target calculation, a negative one a precipitation target calculation.
IA Incoming amount For any number of constituents or components.
MU Chemical potential Valid only for phase constituents.
AC Relative activity
CP
H
S
G
V
Heat capacity
Enthalpy
Entropy
Gibbs energy
Volume
Valid for the entire system or for a phase.

3. Perform the calculations and collect the results

The subroutines used to calculate and collect results are summarised in Table 7.

Apart from standard equilibrium calculations, ChemApp is able to perform two types of calculations which enhance its abilities significantly:target calculations and one-dimensional phase-mapping.

Target calculations

ChemApp is able to perform two types of target calculations:

  • Extensive property target calculations
  • Phase target calculations

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, the change in one of the following five extensive properties of the system can be selected as target: Heat capacity, enthalpy, entropy, Gibbs energy, or volume.

phase target calculation enables conditions to be determined for a selected phase to be present at equilibrium (formation phase target), or the precipitation of another, unspecified phase, from a specified solution phase (precipitation phase target).

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

One-dimensional phase-mapping

One-dimensional phase-mapping calculations are an extension of the phase target calculations described above. 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 an example on how one-dimensional phase-mapping calculations are performed, see the code example One-dimensional phase mapping.

Table 7: 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)
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
TQERR Gets an error message

Only one subroutine (TQCE) needs to be called to execute phase equilibrium calculations defined by pressure, temperature, and input composition. If, in the previous step, you defined other conditions for a target calculation, for example, enthalpy or the amount of a phase at equilibrium, it is necessary to enter the appropriate variable (see Table 8) when calling TQCE. Note that the subroutine TQGPDC also lets you calculate the thermodynamic properties, Cp, H, S, and G, of a phase consituent.

Results from a phase equilibrium calculation are retrieved by using the subroutine TQGETR for the following variables:

  • Total pressure, total volume, temperature
  • Equilibrium amount of phases, phase constituents, and system components
  • Chemical potential and activity
  • Heat capacity, enthalpy, entropy, and Gibbs energy of the equilibrium state
  • Mass or mole fraction of a system component or phase constituent

ChemApp can also calculate the thermodynamic properties, Cp, H, S, and G, of a phase and its constituents.

Table 9 lists all the variables for which results can be obtained.

Table 8: State variables for defining targets when calling TQCE/TQCEL

Option Variable Comment
P Total pressure Pressure is a target variable.
V Total volume Volume is a target variable.
T Temperature Temperature is a target variable.
IA, IA0
MU
Incoming amount
Chemical potential
Incoming amount is a target variable.
Blank Calculate without any target variable.

As a convenient means of checking your progress during programing, a further subroutine (TQCEL) enables you to print out the results from calculations in typical ChemSage format on screen. Otherwise, of course, you can program ChemApp to handle the results in any manner you most prefer.

Table 9: 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.
CP
H
S
G
V
Heat capacity
Enthalpy
Entropy
Gibbs energy
Volume
Not valid for 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 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

Obtaining further information

The easiest way to learn more about ChemApp is to download ChemApp light and start programming right away! ChemApp light is the free version of ChemApp, and although it is restricted in two ways compared to the regular version, it gives you almost the same functionality.

The ChemApp FAQ also provides answers to many questions that you might have about ChemApp.

GTT’s Technical Thermochemistry Web Page will be continuously updated with more descriptions of applications that have been developed using ChemApp. Drop in once in a while to read about additional practical applications of ChemApp.

To keep up-to-date with what happens around ChemApp, join our GTT-News newsletter mailing list: This newsletter is distributed mainly electronically by e-mail, and also posted to our website. It contains announcements of new versions of our various software programs, information on new features and enhancements, ongoing projects, new thermochemical data, additions to our website, seminars, publications, and various other topics.

And if you still have any questions regarding ChemApp please contact us by visiting our contact page here!