.. _sec-function-groups:

Function Groups
---------------

ChemApp for Python uses Python static classes to divide all its functions into
easy-to-understand groups, so that they are easier to find and use. The
following groups are available:

* ``Info``
* ``Units``
* ``ThermochemicalSystem``
* ``EquilibriumCalculation``
* ``PhaseMapCalculation``
* ``StreamCalculation``

Each group is explained briefly below. For more information about the functions
and how to use them, please consult the ``friendly`` module's reference
documentation, which forms part of the :ref:`ch-package-reference` chapter.


``Info`` Group
**************

The purpose of this group is to provide you with functions to get information
about ChemApp itself. This includes things like a copyright message, version
number, the user that ChemApp is licensed to, and the sizes of arrays that
ChemApp uses.


``Units`` Group
***************

The ``Units`` group is used to manage the units of measure used in
thermochemical calculations. It contains functions to get the current units,
change units, and print out the set of units currently in use as nicely
formatted strings.

Upon loading ChemApp for Python, the default units will be the same as the
default units of ChemApp:

* Temperature - K
* Pressure - bar
* Amount - mol
* Energy - J
* Volume - dm3

``ThermochemicalSystem`` Group
******************************

This group is used to load and interact with thermochemical systems. A
thermochemical system is described by a thermochemical data file, which can be
in text format with a ``.dat`` extension, or in encrypted format with a
``.cst`` extension. The encrypted files are also called transparent data files.

The functions in this group are used to get information about system
components, phases, phase constituents, etc. It is also used to extract
configuration objects from the thermochemical system if you want to work with
the more sophisticated class data types provided by the ``core`` module.


``EquilibriumCalculation`` Group
********************************

This group is used to do **absolute** equilibrium calculations that provide
extensive property results as :math:`\text{C}_p`,
:math:`\text{H}`, :math:`\text{S}`, :math:`\text{G}`, rather than as
:math:`\Delta\text{C}_p`, :math:`\Delta\text{H}`, :math:`\Delta\text{S}`, and
:math:`\Delta\text{G}`.


``StreamCalculation`` Group
***************************

This group is used to do **relative** equilibrium calculations that can provide
extensive property results as both absolute (e.g. :math:`\text{H}`) and
relative values (:math:`\Delta\text{H}`). This is achieved by defining streams
that enter an equilibrium calculation. The final extensive properties of the
system are then calculated relative to those of the incoming streams.


``PhaseMapCalculation`` Group
*****************************

This group allows one-dimensional phase map calculations, which is another
type of **absolute** equilibrium calculation. You can use these calculations to
search for phase boundaries as a function of temperature, pressure,
composition, chemical potential, etc. You can even use it to construct binary
and pseudo-binary phase diagrams.


Base Classes
************

When you look a bit deeper into the ``friendly`` module, you will find more
static classes that represent function groups. They are
``EquilibriumCalculationBase`` and ``AbsoluteEquilibriumCalculationBase``. The
word ``Base`` at the end of the names indicates that they are base classes that
we use internally in ChemApp for Python. You should not use them in your code,
not even import them. They are only used internally in ChemApp for Python.