Release Notes

Notes on versions: ChemApp for Python has been provided for a period from 2023-2024 for free as a component of the FactSage Software package under the name ChemApp for FactSage. That version stopped working in August 2024. Users who wish to continue using ChemApp need to use the ChemApp for Python packages provided by GTT-Technologies. Please contact GTT-Technologies for further information.

If you previously used ChemApp for FactSage, ChemApp for Python can be installed following the same installation process using the GUI tools provided with Equilib. The installation program offers to install ChemApp for Python, which you can use to override an existing ChemApp for FactSage installation. Note that you need a valid license for ChemApp for Python to run it.

Equi2Py is a companion Python package that is distributed along with ChemApp for Python. It requires a ChemApp for Python license. As it provides the ability to convert Equilib Save files to Python scripts, its main usage is through the GUI tools provided with FactSage. However, it is possible to use it without a FactSage license or installation.

A brief user guide for Equi2Py is provided in the documentation.

If not mentioned otherwise, all updates apply to the ‘light’ version, too.

ChemApp for Python Release 834.0.7

  • General

    • Fix: An issue occured that an exception that was properly raised when loading a cst file had it’s errno property overwritten with “0” during the re-raise, which let to inconsistent results in Equi2Py in some configurations.

ChemApp for Python Release 834.0.6

  • General

    • The functions enable_logging and disable_logging in the chemapp.basic module have been refactored to use the standard Python logging module without re-initializing it. This allows users to configure logging handlers and formats as desired, while still being able to use the chemapp.basic.enable_logging() and chemapp.basic.disable_logging() functions to control logging output.

      This change includes an update to the signatures of

    • A requirement for numpy<2.0 has been added to the package dependencies to ensure compatibility with existing code.

ChemApp for Python Release 834.0.5

  • General

    • A bug that could wrongly raise “Invalid calculation function” or “Invalid setter function” when using StreamCalculation.reaction(...) with methods like calculate_eq_T has been fixed. The check now correctly recognizes these methods.

ChemApp for Python Release 834.0.4

  • General

    • A minor bugfix around identification of phase internal electrons has been implemented to increase compatibility with older ChemSage.dat files.

    • Some builds contained an outdated file indicating an older-than-actual version number. This has been corrected.

ChemApp for Python Release 834.0.3

  • General

    • ChemApp has been updated to version 8.3.4, which includes several bug fixes and improvements in the underlying ChemApp library.

    • ChemApp for Python is now available for Python 3.13, 3.12, and 3.11. Support for older Python versions has been dropped.

    • Density estimation functionality has been added The density preference is controlled through chemapp.friendly.Info.set_density_config() and read with chemapp.friendly.Info.read_density_config().

      The enum chemapp.core.VolumeEstimateSetting defines three modes:

      • ALWAYS - Always use estimation module volume/density data, overriding datafile data.

      • NEVER - Never use estimation results, rely only on datafile values.

      • IFMISSING - Use estimation only when the datafile lacks volume/density entries.

    • New routines for Stream handling have been added New routines for stream handling have been introduced, including:

      • create_streams_by_density

      • split_by_density

      • StreamCalculation.reaction, reaction_isothermal, reaction_adiabatic, reaction_diathermal

      For more information, see Stream Functionalities.

    • Persistent configuration & density settings

      Note

      This requires an internet connection to to contact https://python.gtt-technologies.de.

      A new persistent configuration file chemapp_python.cfg (located in the user home directory) stores:

      • Update check parameters: cooldown (days), notification level, enable flag

      • Timestamp of the last non-forced update check

      • Density / volume estimation preference

      To change the setting permanently:

      from chemapp.friendly import Info

# Configure update check settings (each optional)
Info.set_update_check_config(
    cooldown_days=7,           # Check every 7 days
    notify_level='major',      # Only notify for major updates
                               # (other levels: 'minor', 'patch')
    disable_update_check=False # Permanently enable/disable update checks
)

# Force an immediate check
Info.check_for_updates(force=True)

# Get current configuration
config = Info.get_update_check_config()

from chemapp.friendly import Info
from chemapp.core import VolumeEstimateSetting

Info.set_density_config(new_setting=VolumeEstimateSetting.IFMISSING)
print("Current:", Info.read_density_config())

      See Update checks and persistent configuration for full details.

    • New function argument chemapp.friendly.ThermochemicalSystem.get_name_scs() has a new keyword argument include_electrons (default: True). When set to False the electron pseudo system component entry e(<Phase>) that is normally part of the returned list is omitted, so only the actual chemical system components are listed. This is convenient when iterating over components where the bookkeeping electron should not be treated like a regular component.

      Example:

      from chemapp.friendly import ThermochemicalSystem

# Default behaviour (include_electrons=True)
scs_with_e = ThermochemicalSystem.get_name_scs()
print("With electrons:", scs_with_e)

# Excluding the electron pseudo component
scs_no_e = ThermochemicalSystem.get_name_scs(include_electrons=False)
print("Without electrons:", scs_no_e)

# Example output (abridged):
# With electrons: ['Al', 'O', 'e(...)', ...]
# Without electrons: ['Al', 'O', ...]

Equi2Py Release 1.0.11

  • General

    • A bug fix was implemented for handling partially set initial conditions in equi files that result from certain operations in Equilib. While this is primarily considered an issue in the Equilib software, a workaround has been added to Equi2Py to properly handle these cases, ensuring that file conversion processes complete successfully regardless of these artifacts.

Equi2Py Release 1.0.10

  • General

    • Stub files to support Pylance and other type checkers have been added to the package. This allows for better code completion and type checking in IDEs when importing equi2py as a module and using the convert function.

ChemApp for Python Release 831.2.0

  • General

    • A better handling of license errors that occur when an expired license or an expired database file is used has been implemented. Previously the validity of the user license was only checked when the datafile was loaded, and subsequently a database file read error was reported. Now, a more clear error message that reports the expired user license is shown.

ChemApp for Python Release 831.1.0

  • General

    • A bug concerning volume calculations in ChemApp has been fixed.

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(<pcname>#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, 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 version number of the ChemApp for FactSage package itself. The version number of the embedded ChemApp library can be retrieved using tqvers().

    • Due to the changes above, 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.