.. _ch-advanced_features: Advanced features ================= This chapter explains the advanced features that ChemApp for Python has beyond the abilities of the C/Fortran ChemApp, such as using the state functions and object oriented approach to model processes. Content Overview ---------------- * Result objects ``chemapp.core.EquilibriumCalculationResult`` and ``chemapp.core.StreamCalculationResult`` * ChemApp logging * ``chemapp.core.Object`` * Input using chemical formulae using ``chemapp.friendly.EquilibriumCalculation.set_IA_cf`` One of the core features of ChemApp for Python is taking advantage of object oriented structures to allow using calculation results of previous calculations as input for further calculations, and therefore allowing e.g. process models to be rapidly deployed without much tedious setup processes. This takes advantage of the ``State`` classes and ``EquilibriumCalculationResult`` as well as ``StreamCalculationResult`` objects mentioned in :ref:`the core section `. The practical use of the logging abilities of ChemApp for Python is another feature that allows quickly generating helpful information to debug and analyze your program code. Furthermore, a convenient way to enter incoming amounts using chemical formula instead of phase constituents or system components is introduced, using the ``set_IA_cf`` routine of the ``EquilibriumCalculation`` classes. Result Objects -------------- Most thermochemical calculations related to process manages are using multiple calculation steps to describe. With ChemApp for Python, it is possible to easily use results of previous calculations not only to store and investigate the calculation results, but also as input for following calculations. To work with calculation results as inputs for new calculations, they have to be converted into ``StreamState`` objects, which are objects that are defining input streams in ChemApp. They do carry an initial temperature, initial pressure and phase (constituent) amounts, all of which is necessary to define an input stream into ChemApp for Python. One of the main applications of stream or initial conditions based calculations are in process modelling and in designing of material flow in multistage reaction schemes. Functions to split, separate and combine ``StreamState`` objects are available, as well as directly creating streams from equilibrium results filtered by e.g. matter of state, phase or constituents. Creation of result objects ^^^^^^^^^^^^^^^^^^^^^^^^^^ After executing a calculation, a ``EquilibriumCalculationResult`` and ``StreamCalculationResult`` can be created using the class routine ``get_result_object`` of ``EquilibriumCalculation`` or ``StreamCalculation``. The result objects are relatively rich data container classes, that expose reasonable information of the calculation as properties, such as the conditions and inputs, as well as e.g. the units in which the results are stored. All fetchable thermodynamic data is stored in the object for all phases and constituents. Most of the properties are constructed of the various data structures that ChemApp for Python provides, such as ``PhaseState`` classes. It is recommended to always create a result object from a calculation, if any type of aggregating or deeper analysis of certain results is planned. The computational cost of collecting the data is relatively low. However, each calculation result object size can quickly become large for large datafiles. .. TODO: maybe talk about the _convert_to_indexed_primitive_doc, or better even, make creation of DataFrame available! Creation of stream objects ^^^^^^^^^^^^^^^^^^^^^^^^^^ From these objects, the following routines can be used to create ``StreamState`` classes, which then can be used as inputs for new calculations: * ``create_stream`` * ``create_stream_by_state`` * ``create_gas_stream`` * ``create_liquid_stream`` * ``create_solid_stream`` Of these routines, ``create_stream`` is the most versatile and allows for various types of filters and selections, namely by specifically including or excluding certain phases, as well as including or excluding certain elements. It also allows to set a certain threshold to ignore residual amounts of phase constituents. ChemApp Logging --------------- A debugging functionality has been added to ChemApp for Python that allows to output the ChemApp library calls in the original FORTRAN language calls to the ChemAPP API. It allows for users to generate a complete stream of the setup that was used in calculations, which can be very helpful to guide through e.g. presumed bugs in ChemApp, in some library code or to check if the program does indeed do as intended. If a function returns a result, this result is printed directly after the function. Therefore it can also be used to quickly find off-by-one errors or other typical programming mishaps. It can be enabled by using .. code-block:: python from chemapp.basic import enable_logging, disable_logging # enable logging to 'calls.log' enable_logging() # and can subsequently deactivated using disable_logging() The output is appended to the file 'calls.log' in the current working directory, and together with the datafile used in the calculation should be a valuable debugging ressource, especially if you consider contacting GTT for maintenance or support. Input of complex chemical formulae ---------------------------------- dolor dolor