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.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.