Release Notes ============= Notes on versions: There exist two separate 'flavors' of ChemApp for Python, as there are two ways of distribution. `ChemApp for Python` is the standalone version of the ChemApp for Python interface, whereas `ChemApp for FactSage` is the version of the ChemApp for Python interface that is distributed with FactSage. The two versions are identical in functionality, but the standalone version has some differences in the way it authenticates the user and the licensing. We strive to align both of these versions as much as possible. The leading version number of ChemApp (for Python/FactSage) is the version of the underlying ChemApp library. The second version number is the associated 'major' version number of the Python interface and is increased with feature updates, and the third version number is reserved for bugfixes and minor alignments. `Equi2Py` is a companion Python package that is distributed along with ChemApp for FactSage. It's main usage is through the GUI tools provided with FactSage. However, it is possible to use it with a ChemApp for Python installation just as well. For simplicity reasons, there is no separate documentation channel or API reference, as it has a relatively self-explanatory CLI, and using the CLI interface is 'off-label' use. However, feature updates and bugfixes are listed here. Versions prior to the ChemApp for FactSage 8.2.6 release are listed here, however their names and versions are deprecated. Currently, no further updates are planned for any of these versions. Equi2Py Release 1.0.9 --------------------- * Bugfixes - A bug was resolved that incorrectly transferred some partial pressure values to the script. It affected conditions that were of the type of a floating point number logarithmic exponent. No other conditions are affected or wrong. * Known Issues - As in previous releases. ChemApp for FactSage Release 826.2.0 ------------------------------------ * General - A different way to deal with duplicate phase constituent names has been implemented, which allows to have a phase with multiple phase constituents of the same name, and work with this. As a result, any phase constituent that has a name that already exists in the phase, will have a "#2" (or #3 or higher) appended to its name. This is done automatically, and the user does not need to take any action. However, since this change is only implemented 'on top' of the data file, the ChemApp results that can be printed do not disambiguate the duplicates this way. All result functions will contain the modified constituent names. Inconsistencies may arise from mixing the `friendly` and `basic` modules, as the association of phase constituent names and indices is not fully transitive anymore. Using e.g. `tqinpc` to get the index of a phase constituent based on its name will only yield the index of the first of the ambiguous phase constituents. Indexes of the '#2' can not be retrieved with this method, and a call to `tqinpc(#2)` will fail. Equi2Py Release 1.0.8 --------------------- * Bugfixes - Now, using a phase as formation or precipitation target that have additional database information in the status table can be used. This was previously not possible, it only affects commercially distributed databases such as FTOxid or FSSteel. * Known Issues - As in previous releases. Equi2Py Release 1.0.7 --------------------- * Bugfixes - A bug was fixed that broke conversions for Equi files that include a logarithmic activity condition for a gas species. * Known Issues - Examples when using two variables (A, B) are not adequately adapted to use both variables, and may fail to execute correctly. It is recommended to not include the examples when using both variables. - Some reference phase selections are possible in Equilib, but are not correctly added to the cst database file. This can not be resolved from Equi2Py solely. A patch for Equilib is in the works to resolve this issue. Equi2Py Release 1.0.6 --------------------- * Bugfixes - A bug was fixed that 'initial conditions could not be read' appears when a reactant is selected for which no adequate reference phase is available, which was independent of whether the calculation was supposed to be run with initial conditions, or not. * Known Issues - Examples when using two variables (A, B) are not adequately adapted to use both variables, and may fail to execute correctly. It is recommended to not include the examples when using both variables. - Some reference phase selections are possible in Equilib, but are not correctly added to the cst database file. This can not be resolved from Equi2Py solely. A patch for Equilib is in the works to resolve this issue. ChemApp for FactSage Release 826.1.1 ------------------------------------ * General - The `Electron Constraint` option that determines whether a phase internal electron is recognized for a solution phase internal charge equilibrium is now turned 'on', if any such phase is part of the loaded datafile. This mirrors the behavior of calculations in Equilib, for which, due to the Equi2Py module, aligning the behavior is desirable. As was possible previously, :py:func:`~chemapp.basic.tqconf` can be used to change this option. * friendly - The ``Info`` class previously reported the version number of the ChemApp library which is embedded in the package. This has been changed to report the versioin number of the ChemApp for FactSage package itself. The version number of the embedded ChemApp library can be retrieved using :py:func:`~chemapp.basic.tqvers`. - Due to the changes above, :py:func:`~chemapp.friendly.Info.get_version_number` now returns a ``str`` for the version number, instead of the ``int`` returned by ``tqvers()``. - The description of the function `~chemapp.friendly.StreamCalculation.set_st` has been improved to more clearly indicate what is done internally. It clarifies that when a stream with a given name is added using set_st, already existing incoming amounts for that stream may not be removed, if the stream object does not set these explicitly. Equi2Py Release 1.0.4 --------------------- * Bugfixes - A bug when using 2 iterating variables has been fixed. - A bug with selection of a phase that has multiple phase copies added to the database has been fixed. - In some calculations of iterating over temperature, setting a phase specific equilibrium condition would be missing from the script. This has been fixed. * Known Issues - Examples when using two variables (A, B) are not adequately adapted to use both variables, and may fail to execute correctly. It is recommended to not include the examples when using both variables. - Some reference phase selections are possible in Equilib, but are not correctly added to the cst database file. This can not be resolved from Equi2Py solely. A patch for Equilib is in the works to resolve this issue. ChemApp for FactSage Release 826.1 ---------------------------------- * General - Supported versions of Python are 3.9, 3.10, 3.11. The requirement for minor version matching with Python has been dropped. * friendly - Routines ``get_eq_dH``, ``get_eq_dS``, ``get_eq_dG``, ``get_eq_dV``, ``get_eq_dCp`` have been added to the ``StreamCalculation`` class. These allow to retrieve the respective `reaction` enthalpy, entropy, Gibbs energy, volume and heat capacity. Previously, those _reaction_ values were available through ``get_eq_H``, ``get_eq_S``, ``get_eq_G``, ``get_eq_V``, ``get_eq_Cp``. These are updated to now return the `system total` values, aligned with the respective functions in the ``EquilibriumCalculation`` class. ``DeprecationWarnings`` are issued for the old functions. - A bug in the function ``create_stream`` for ``EquilibriumCalculation`` and ``StreamCalculation`` has been fixed, which resulted in ``StreamState`` classes having 'NAN' values for extensive stream properties, due to incorrect collection of those properties. ``StreamState`` objects created with ``create_stream`` should now be able to provide correct extensive properties in all cases of a successful equilibrium calculation. - The ``print_result`` parameter of ``calculate_eq_X`` was ineffective when using ChemApp in Jupyter notebooks. This has been fixed. ChemApp Release 8.2.6 --------------------- * friendly - The ``calculate_eq`` routine of ``EquilibriumCalculation`` and ``StreamCalculation`` have a new keyword argument `return_result`, that if set to `True` will make ``calculate_eq`` return the respective result object. This removes the sometimes clumsy immediate call to ``get_result_object`` immediately after a calculation call. ChemApp Release 8.2.5 --------------------- * General - The memory management of string allocations has been reworked, removing a few unnecessary allocations. - The ``Assay`` class has been removed from ChemApp for Python, as have all the routines that refer to this class, e.g. ``set_IA_pcs_with_assay`` of the ``EquilibriumCalculationBase`` class, which removes it also from all the derived equilibrium calculation classes. * basic - ``tqcsc`` (Change the set of system components) has been removed due to inconsistent behavior and cache implications for the ``friendly`` module. * friendly - The calculation of the system size in molar units has been corrected in case of phases with divergent mol-formula and mol-atom weight. This also affects the calculation of relative amounts (``.X`` property of e.g. ``SystemComponentState``). ChemApp Release 8.2.3 --------------------- * General - ChemSage.dat files with functions are now supported, if these files are exported from FactSage 8.2+. ChemSage.dat files without functions can be read in all versions exported from FactSage. - Python 3.10, 3.9 and 3.8 are now the supported python versions. - A bug with the ``EquilibriumCalculationResult`` and ``StreamCalculationResult`` string representation templates has been resolved. - Exceptions of type ``ChemAppError`` have an attribute ``errno`` which yields the ChemApp error code, allowing for different error handling routines. * ``basic`` - The memory allocation method has been refactored and is now quicker. - Some function documentations were amended to reflect proper usage of indexes. - ``tqefct`` available to inquire the number of temperature ranges for a function. ChemApp Release 8.1.6 --------------------- * General - ChemAppPy has been split between GTT and Ex Mente. ``basic`` and ``friendly`` modules are transferred in ownership to GTT, whereas the ``tools`` module will be available separately by Ex-Mente. - The package name is changed to ``chemapp`` instead of ``chemapppy``. In cases where a distinction is needed, it will be referred to as ``ChemApp for Python``, but generally only ``ChemApp`` is used for the functionality, and ``chemapp`` to refer to the python module. - Version numbers will be aligned with the underlying ChemApp version number. Therefore, the current version number jumps to 8.1.6. Purely iterative releases of ``chemapp`` will get a fourth-level letter, such as ``8.1.6.a``. - ChemSage.dat files with functions are now supported, if these files are exported from FactSage 8.2+. ChemSage.dat files exported from FactSage 8.1 can not be read. ChemSage.dat files without functions can be read in all versions exported from FactSage. * ``basic`` - routines ``tqifct``, ``tqnfct``, ``tqcfct``, ``tqgfct``, ``tqgsum``, ``tqcsum`` have been added. ChemAppPy Release 1.6.2 ----------------------- * General - The ChemApp binaries have been updated to verion 7.5.6 which now allows ChemAppPy to run in Ubuntu 20.04. * ``friendly`` - The ``set_IA_pc`` function has been updated to allow using an empty string or ``-`` when defining the amount for a pure phase. * ``tools`` - The ``DistributionPlotter`` has been updated to save the ``matplotlib .figure`` object in a member variable of the parent ``Plotter`` class. This allows the user to customise the plots beyond what is natively possible in the derived ``DistributionPlotter`` classes by directly manipulating and manually redrawing the figure. - Additional split compounds have been added in the ``FactSageViscosityTabulator``. ChemAppPy Release 1.4 --------------------- * ``tools`` - The ``MassDistributionPlotter`` class has been added that provides more descriptive function names for creating different kinds of mass distribution plots. - The ``StreamCalculator`` errors that occurred when using the recycle functionality have been resolved. ChemAppPy Release 1.4 --------------------- * General - The ChemApp libraries have been upgraded to the new ChemApp verion 7.4.0. ChemAppPy Release 1.3 --------------------- * General - The ChemAppPy package structure has been modified to not only make the import process more intuitive but also to allow the user to easily distinguish between the development and light versions. The package name for the development edition is ``chemapppy`` and its four modules are ``chemapp.core``, ``chemapp.basic``, ``chemapp.friendly`` and ``chemapppy.tools``. The package name for the light edition is ``chemapppylight`` and its four modules are ``chemapppylight.core``, ``chemapppylight.basic``, ``chemapppylight.friendly`` and ``chemapppylight.tools``. Note that you no longer need to specify ``development`` or ``light`` to access the ``basic``, ``friendly`` and ``tools`` module as in the previous version. * ``tools`` - The error that occurred when connecting more than one callback to a ``StreamCalculator`` event has been resolved. - The font size and grid line settings for the distribution plots can now be modified when instantiating a ``DistributionPlotter`` object. * ``core`` - The ``file_path`` argument in the ``AssayTable.read`` function can now accept either a ``str`` or a ``Path`` object. ChemAppPy Release 1.2 --------------------- Additions, Changes and Fixes ############################ * General - ChemAppPy is now built with the updated ChemApp 7.3. The new ChemApp brings added stability to the calculation engine. - More examples were added for the ``tools`` and ``friendly`` module. * ``tools`` - The ``manual-segment-settings`` argument was added to the ``DistributionPlotter.run`` function. This allows you to manually set the labels and colours of the different segments in a distribution plot. See the ``tools`` section for an example of how to use it. - The issue with certain segment causing errors with the ``MongoDbDataCollector`` has been fixed in the ``ListDataCollector`` as well. ChemAppPy Release 1.1 --------------------- Additions, Changes and Fixes ############################ * General - ChemAppPy is now compatible with Python 3.7. * ``tools`` - The ``DistributionPlotter.run`` function has an extra boolean argument ``export_to_csv`` that, when set to ``True``, will export the values used for plotting to a csv file. - The ``DistributionPlotter.run`` function has two extra arguments that allow changing the minimum amount for species to be considered when creating a plot. Phases/phase constituents/components with an amount less than ``occurrence_min`` will be ignored. ``occurrence_fraction`` indicates whether this minimum value is an absolute value or a fraction of the total amount. - A ``FactSageViscosityTabulator`` class has been added. It creates a csv file in the format required by FactSage to calculate viscosity. An example has been added on how to use this class. - All ``PostProcessor`` sub-classes in the ``tools`` module (``Plotters``, ``Calculators`` and ``Tabulators``) perform type checking on the keyword arguments used in the ``run`` function. - Errors that occurred on specie names with non-alphanumerical characters (such as [,],#,+,-) have been fixed. - An example on how to use the ``OccurrenceCalculator`` sub-classes with a result set has been added. - Examples on how to use both the ``ListDataCollector`` and the ``MongoDbDataCollector`` have been added. - The solution to the MongoDB error that occurs on large result sets has been addressed in the ``40-tools/DistributionPlotter/02-store-results-in-mongodb.py`` example. * ``friendly`` - An example on how to use the ``PhaseMapCalculation`` class has been added. Known Issues ############ We are aware of the following issues: * General - PyCharm displays an extra parameter ``cls_1`` when displaying the signature of some ChemAppPy functions. ChemAppPy Release 1.0 --------------------- Additions, Changes and Fixes ############################ * General - ChemAppPy is now compatible with a bare Python installation as well Python virtual environments. - All functions that take a file or a directory as an argument is now compatible with both strings and ``Path`` objects from the Python ``pathlib`` package. - Tests that failed with the Light version in previous releases have been fixed. - PyCharm is now able to display the actual argument and keyword argument names of ChemAppPy functions. * ``core`` - All calculation results now contain the ChemApp ``tqshow`` string. ChemAppPy Light 0.3.7 (Beta 3) -------------------------------- Additions, Changes and Fixes ############################ The following changes were made in the Beta 3 release: * General - The ``examples`` directory now has a sub-directory for each ChemApp edition, so that you don't need to rename ``light`` to ``development`` and vice versa. - The Python version of the Windows distribution was updated from 3.6.2 to 3.6.5. - CFP-43: The Git working structure was checked and appears to be working. * User Manual - The Linux installation procedure was updated to include a step to install ``libgfortran3``. - Several errors in the worked examples of the ``basic`` and ``friendly`` modules were fixed. They now discover the location of the data files automatically, and should run without problems. * ``core`` Module - CFP-7: The AssayTable.read method was improved to make it more robust, and less error-prone. - Most of the data types in this module now have formatted ``__str__`` methods. You can now print them nicely to the console. - The classes ``PhaseConstituentIncomingAmountState`` and ``SystemComponentIncomingAmountState`` in place of``IncomingAmountState``, which is now the abstract base class of the other two classes. * ``basic`` Module * ``friendly`` Module - CFP-21: When using the module as the back-end for a process modelling framework, the performance was very slow. All thermochemical system details are now cached immediately upon load. This reduces round-trips between Python and ChemApp. - CFP-24: Getting calculation results had some performance problems. These were fixed, so the operations are significantly faster than before. - CFP-26: The string result returned by ``ThermochemicalSystem.get_str_phs_pcs`` was poorly formatted before, which was corrected. - ``ThermochemicalSystem`` now provides a clear error message when Light users try to read ``.cst`` files, which is not supported. - ``ThermochemicalSystem`` now detects duplicate system components, phases, and phase constituents when loading data files. If such a problem is detected, it will not be possible to use the data file with the ``friendly`` and ``tools`` modules. The ``basic`` module is still able to use it. * ``tools`` Module - The ``StreamCalculator`` and ``ListStreamBuilder`` objects are now more flexible regarding input data types. Only ``float`` and ``list`` were accepted before. Now you can also use ``int`` and ``numpy.ndarray``. - The ``StreamCalculator.run`` method now provides a set of events that can be used to get information, monitor, and intervene during the calculation process. This provides significantly more flexibility than before. + on_run_start + on_calc_start + on_calc_eq_start + on_calc_eq_end + on_calc_error + on_calc_end + on_run_abort + on_run_end - CFP-22: Labels were not tranferred when converting ``EquilibriumCalculationResult`` objects to indexed primitive representations. This conversion is done so that the objects can be stored in, for example, a MongoDB database. The labels now transfer successfully. ChemAppPy Light 0.3.5 (Beta 2.1) -------------------------------- The following changes have been made in the Beta 2.1 release: * General - The ``tools`` module is now available in the ``light`` edition of ChemAppPy. It was excluded in version 0.3.4 by mistake. * User Manual - There was an error in the documentation where the ``core`` module was imported as ``from chemapp import core``. This is now ``from chemapppy import core``. ChemAppPy Light 0.3.4 (Beta 2) ------------------------------ The following changes have been made in the Beta 2 release: * General - ChemAppPy is no longer compatible with Python 3.5 and earlier. We started using f-strings internally, which requires at least Python 3.6. - We introduced the *mm* abbreviation into the interface to replace *molarmass* and *molar_mass*. This makes the function names shorter, while retaining readability. - Several function now return their results as dictionaries rather than lists. This means that strings and indexes can be called from results instead of only indexes. - Code was included in the non-light editions to verify that the user holds a valid ChemAppPy license. * User Manual - Blank pages were removed. - Content was added, revised and removed. - Worked examples 3, 4, and 5 were added to the basic and friendly modules. * ``core`` Module - The class ``ChemApplightError`` was renamed to ``ChemAppLightError`` for the sake of naming consistency. - The classes ``PythonApiError`` and ``Error`` were removed, since they were remnants of ChemAppPy when it was still implemented with C. - A new class ``ChemAppInfo`` was added to store all information that can be retrieved via ``friendly.Info`` group of functions. - The function ``friendly.Info.get_object`` was added to retrieve all ChemApp-related information into a ``ChemAppInfo`` object in a single step. - The ``pcs`` property was added to the ``PhaseConfig`` class. - The ``EquilibriumCalculationResult`` ``IA`` property's name was changed to ``IAs`` to indicate the plural. - The ``Assay`` class now uses named tuples for dictionary keys and values. These are ``Assay.ItemKey``, ``Assay.ItemData``, and ``Assay.ItemValues``. - A ``StreamState`` class that represents the state of a stream that is used as input to a stream equilibrium calculation was added. - A ``StreamCalculationResult`` class was created. It includes stream states. * ``basic`` Module - Small bug fixes were made. * ``friendly`` Module - A short description of all of the static classes was provided. - Test code improved. - Several errors were fixed. - A ``get_object`` function was added to the ``Info`` class. This returns all the information that could possibly be obtained from the ``Info`` class. - ``get_config`` functions were created. These functions provide full configuration details of the specified system component(s), phase or phase constituents. - The ``create_empty_assay_table`` function's name was changed to ``create_assay``. - A function ``create_assay_table`` that creates an empty assay table object from the currently loaded thermochemical system was created. - The function ``get_result_object`` was added to the ``StreamCalculation`` and ``AbsoluteEquilibriumCalculationBase`` classes. These extract all of the equilibrium calculation results into the form of a ``chemapp.core.EquilibriumCalculationResult`` object. * ``tools`` Module - The ``StreamCalculator`` class is now available for doing series of stream calculations. - The concept of a stream builder was introduced in the form of the ``StreamBuilder`` abstract class, and the ``ListStreamBuilder`` that creates streams based on input parameter lists. * examples - A set of examples is now included in the distribution file.