# How to Use ChemApp

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

- initialise the interface, read a thermodynamic data-file, and adjust the chemical system
- set initial conditions for the equilibrium calculation
- 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 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 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 streams**A 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.

A *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 andstreams 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 web site. 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 web site, seminars, publications, and various other topics.

And if you still have any questions regarding ChemApp please contact us: *info@gtt-technologies.de*