.. _ch-core-module: 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. Approach -------- 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. Errors ****** 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. Enumerations ************ 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. +------------------------------+----------------------------------------------+ | Enumeration | ``basic`` Module Functions | +==============================+==============================================+ | ``IoOption`` | ``tqgio``, ``tqcio``, ``tqwstr`` | +------------------------------+----------------------------------------------+ | ``Status`` | ``tqgsp``, ``tqcsp``, ``tqgspc``, ``tqcspc`` | +------------------------------+----------------------------------------------+ | ``Quantity`` | ``tqgsu``, ``tqcsu`` | +------------------------------+----------------------------------------------+ | ``PressureUnit`` | ``tqcsu``, ``tqgsu`` | +------------------------------+----------------------------------------------+ | ``VolumeUnit`` | ``tqcsu``, ``tqgsu`` | +------------------------------+----------------------------------------------+ | ``TemperatureUnit`` | ``tqcsu``, ``tqgsu`` | +------------------------------+----------------------------------------------+ | ``EnergyUnit`` | ``tqcsu``, ``tqgsu`` | +------------------------------+----------------------------------------------+ | ``AmountUnit`` | ``tqcsu``, ``tqgsu`` | +------------------------------+----------------------------------------------+ | ``ConditionVariable`` | ``tqsetc``, ``tqstec`` | +------------------------------+----------------------------------------------+ | ``TargetVariable`` | ``tqce``, ``tqcel``, ``tqcen``, ``tqcenl`` | +------------------------------+----------------------------------------------+ | ``PhaseMapVariable`` | ``tqmap``, ``tqmapl`` | +------------------------------+----------------------------------------------+ | ``ResultVariable`` | ``tqgetr`` | +------------------------------+----------------------------------------------+ | ``PhaseConstituentVariable`` | ``tqgdpc`` | +------------------------------+----------------------------------------------+ | ``StreamVariable`` | ``tqstxp`` | +------------------------------+----------------------------------------------+ | ``PhaseConstituentData`` | ``tqgdat`` | +------------------------------+----------------------------------------------+ | ``InteractionVariable`` | ``tqlpar``, ``tqgpar``, ``tqwstr`` | +------------------------------+----------------------------------------------+ | ``LimitVariable`` | ``tqclim`` | +------------------------------+----------------------------------------------+ | ``FunctionSumVariable`` | ``tqcsum``, ``tqgsum`` | +------------------------------+----------------------------------------------+ | ``FunctionData`` | ``tqcfct``, ``tqgfct`` | +------------------------------+----------------------------------------------+ .. tabularcolumns:: |p{6cm}p{9cm}| +------------------------------+----------------------------------------------------------------+ | Enumeration | ``friendly`` Module Functions | +==============================+================================================================+ | ``Status`` | ThermochemicalSystem class: | | | ``get_status_ph(s)``, | | | ``set_status_ph(s)``, | | | ``set_status_pc(s)``, | | | ``get_status_pcs_in_ph`` | | | ``set_status_pcs_in_ph`` | +------------------------------+----------------------------------------------------------------+ | ``PressureUnit`` | Units class: | | | ``set``, ``get_P_unit`` | +------------------------------+----------------------------------------------------------------+ | ``VolumeUnit`` | Units class: | | | ``set``, ``get_V_unit`` | +------------------------------+----------------------------------------------------------------+ | ``TemperatureUnit`` | Units class: | | | ``set``, ``get_T_unit`` | +------------------------------+----------------------------------------------------------------+ | ``EnergyUnit`` | Units class: | | | ``set``, ``get_E_unit`` | +------------------------------+----------------------------------------------------------------+ | ``AmountUnit`` | Units class: | | | ``set``, ``get_A_unit`` | +------------------------------+----------------------------------------------------------------+ Classes ******* 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 """"""""""""" .. _ch-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.