The core Module

This chapter explains the purpose and approach of ChemApp for Python’s core module, and provides an overview of its contents. The purpose of the core module is to provide software components that can be used in ChemApp for Python’s basic and friendly modules.


The core module provides a set of data types that make your life easier. ChemApp only uses primitive data types like integers, floating point numbers, strings, and lists. Working with these usually requires that you need to write many lines of code to get things done.

ChemApp for Python uses Python’s ability to create more sophisticated data types. These are called classes. These classes can represent things that we think about and talk about when we are doing thermochemical calculations. This makes them easy to understand and use. A phase, for example, is something that can have many pieces of data associated with it, like a name, amount, volume, entropy, Gibbs energy, a list of phase constituents, etc. Accessing all this information with ChemApp requires much effort. The core module has two classes to describe phases, namely PhaseConfig and PhaseState. These classes keep all the information about a phase together, making it easier to work with.

Content Overview

The core module contains classes that represent errors, enumerations, and thermochemical data items. They are explained below.


These data types are used to classify the errors that can occur when using ChemApp for Python. Here is a summary:

  • chemapp.core.ChemAppPyError

    This is ChemApp for Python’s base error type. It is rarely used as-is, but it is rather used to define the more specific error types explained below. If needed, you can use this type to catch and handle any type of error related to ChemApp for Python, rather than a more specific type.

  • chemapp.core.ChemAppError

    This type is used to inform you of errors generated by ChemApp itself. ChemApp for Python simply relays this information to you in a Python-friendly way. It has a property .errno which gives you the ChemApp error code, if desired.

  • chemapp.core.ChemAppLightError

    This type represents errors specifically related to the Light edition of ChemApp. This edition’s behaviour is different from that of the other ChemApp editions, since it has limited functionality.


The core module provides a set of enumerations that prevents the use of hard-coded strings and values, which is bad programming practice. Here are lists of all the enumerations, and the basic and friendly module functions that use them. Please use Python’s pydoc utility or help function to get a description of each enumeration.


basic Module Functions


tqgio, tqcio, tqwstr


tqgsp, tqcsp, tqgspc, tqcspc


tqgsu, tqcsu


tqcsu, tqgsu


tqcsu, tqgsu


tqcsu, tqgsu


tqcsu, tqgsu


tqcsu, tqgsu


tqsetc, tqstec


tqce, tqcel, tqcen, tqcenl


tqmap, tqmapl










tqlpar, tqgpar, tqwstr




tqcsum, tqgsum


tqcfct, tqgfct


friendly Module Functions


ThermochemicalSystem class: get_status_ph(s), set_status_ph(s), set_status_pc(s), get_status_pcs_in_ph set_status_pcs_in_ph


Units class: set, get_P_unit


Units class: set, get_V_unit


Units class: set, get_T_unit


Units class: set, get_E_unit


Units class: set, get_A_unit


The core module provides several classes, and we group them as follows:

  • Utility classes

  • Base classes

  • Information classes

  • Configuration classes

  • State classes

The concepts of ‘configuration’ and ‘state’ are important to understand. Configuration data describes the thermochemical characteristics of a system, and it is contained in a thermochemical data file. The data is usually fixed, and you cannot change it. State data describes the state of a system at equilibrium, after an equilibrium calculation was done.

Utility Classes

Utility classes perform useful tasks in ChemApp for Python, but you do not need to take notice of them. They are used ‘under the hood’. Currently there is only one utility class, namely chemapp.core.Event, which enables some of the ChemApp for Python tools to raise events that you can subscribe to in your code to perform custom tasks.

Base Classes

You should never use these classes in your code. They help us write less code, and better code in ChemApp for Python. They include:

  • chemapp.core.Object

  • chemapp.core.ObjectDescriptor

  • chemapp.core.ConvertableObject

Information Classes

These data types provide information. There is currently only one, namely ChemAppInfo. It is used to store information about the ChemApp library itself, and make it easy for you to work with this information.

Configuration Classes

These data types store configuration information about objects like phases, system components, etc. The information is read from a thermodynamic data file (.cst or .dat), and it does not change while doing calculations with ChemApp for Python. The classes include:

  • chemapp.core.ThermochemicalSystem

    This class describes an entire thermochemical system read from a thermochemical data files (.cst or .dat). It contains system components, phases, and phases constituents described by the other configuration classes listed below.

  • chemapp.core.SystemComponentConfig

    This class describes a single system component’s configuration.

  • chemapp.core.PhaseConfig

    This class describes a single phase’s configuration. It also contains all the phase’s constituents with their configuration information.

  • chemapp.core.PhaseConstituentConfig

    This class describes a single phase constituents’s configuration.

State Classes

These data types store state information about phases, system components, etc. State information can change as your Python program runs, and is therefore not static like configuration information. The classes include:

  • chemapp.core.EquilibriumCalculationResult and chemapp.core.StreamCalculationResult

    These classes describes equilibrium calculation and stream calculation results in their entirety. It contains data to describe the inputs specified for the calculation, and the equilibrium state of the system, system components, phases and phase constituents.

  • chemapp.core.SystemComponentIncomingAmountState, chemapp.core.PhaseConstituentIncomingAmountState, chemapp.core.ChemicalFormulaIncomingAmountState and chemapp.core.StreamState

    These classes describe the material inputs provided to equilibrium calculations and stream calculations. Normal equilibrium calcluations allow system component and phase constituent masses as inputs, and stream calculations require material streams to be specified. The ChemicalFormulaIncomingAmountState allows the input of arbitrary chemical formulas that are possible to express using the present system components.

  • chemapp.core.SystemComponentState

    This class describes a single system component’s state.

  • chemapp.core.PhaseState

    This class describes a single phase’s state. It also contains all the phase’s constituents with their state information.

  • chemapp.core.PhaseConstituentState

    This class describes a single phase constituents’s state.