ChemApp for Python's ``friendly`` vs ``basic`` Module
-----------------------------------------------------

The ``friendly`` module differs from the ``basic`` module in the following
ways, which are discussed further below:

* Descriptive naming
* Groups of functions
* More specific functions
* More powerful functions
* Sophisticated data types


Descriptive Naming
******************

This aspect is explained in the :ref:`ch-introduction` chapter of this manual,
and it is especially relevant to the ``friendly`` module. We use clear names for
function groups, and clearly defined abbreviations to create function, parameter
and variable names. This makes the code that you write with ChemApp for Python
much easier to read and understand than code written with ChemApp, or with the
ChemApp for Python's ``basic`` module.


Functions Organised into Groups
*******************************

The ChemApp API consists of 75 functions that can be used for a variety of
tasks related to doing thermochemical calculations. It may be a daunting
prospect to get started with this interface.

The ``friendly`` module organises functions into groups. Each group contains
functions related to a specific aspect of thermochemical calculations. This
makes them easier to find, learn, and remember. The groups are listed and
explained in the :ref:`sec-function-groups` section.


More Specific Functions
***********************

Many of ChemApp's ``tq*`` functions can be used to accomplish a variety of
different tasks. They are very compact, but this can make them more difficult
to decipher and use. As an example, the ``tqsetc`` function can be used for 21
different things.

The ``friendly`` module takes a different approach. Rather than having a small
number of functions that can each do many things, we create more functions that
each does one specific thing. This makes it easier to learn and understand what
a function does and how to use it. It also makes the code you write easier to
read.


More Powerful Functions
***********************

The ``friendly`` module also provides functions that do more work with less
coding. For example, to open, read, and close a thermochemical data file with
ChemApp requires at least three lines of code. With ``friendly`` you can do
this with one.

There are also functions in the ``friendly`` module that help you to print
lists of system components, phases, phases constituents, etc. with a single
line of code. With ChemApp this would requires more effort.


Using Sophisticated Data Types
******************************

The ``friendly`` module uses the sophisticated data types provided by
:ref:`ch-core-module`. This means that you can access objects like system
components, phases, and phase constituents, knowing that these objects contain
all their relevant information. Here are two examples illustrating the benefits.
They both print out the details of a specific system component. The first uses
only primitive data types, and the second uses a ``core`` module class.

.. code-block:: python

  from chemapp.friendly import ThermochemicalSystem as cats

  # load a thermochemical data file
  cats.load("fec.dat")

  # get the configuration details of a system component
  index = 0
  name = cats.get_name_sc(index)
  mm = cats.get_mm_sc(index)

  # print the system component configuration
  print("================")
  print("SYSTEM COMPONENT")
  print("================")
  print(f"Index:      {index}")
  print(f"Name:       {name}")
  print(f"Molar mass: {mm}")
  print("================")

When executing this code, the output is as follows:

.. code-block:: none

  ================
  SYSTEM COMPONENT
  ================
  Index:      0
  Name:       Fe
  Molar mass: 55.847
  ================

Here is the alternative, employing the ``SystemComponentConfig`` class. When
calling the ``ThermochemicalSystem.get_config_sc`` function, a
``SystemComponentConfig`` object is returned.

.. code-block:: python

  from chemapp.friendly import ThermochemicalSystem as cats

  # load a thermochemical data file
  cats.load("fec.dat")

  # get the configuration of a system component
  sc = cats.get_config_sc("Fe")

  # print the system component configuration
  print(sc)

The output of the second example is:

.. code-block:: none

  =========================================================================
  System Component Configuration
  -------------------------------------------------------------------------
  Class:      SystemComponentConfig
  Index:      0
  Name:       Fe
  Molar mass: 55.847
  =========================================================================

With the ``core`` module classes you get more done with less effort. The same
principle demonstrated here for system components applies to phases and phase
constituents, and to the thermochemical system as a whole as well.