Database

The Database object is the fundamental representation of CALPHAD data in pycalphad. It can be considered as the in-memory analogue to a thermodynamic database (TDB) file, and in fact pycalphad supports reading and writing a large subset of the TDB file format through the from_file() and to_file() methods of the Database object. For convenience, calling the Database constructor, e.g., Database(’example.tdb’), will automatically call the appropriate parsing function. Database files can also be passed as multi-line strings; this is convenient for embedding TDB files in short Python scripts. The current version of pycalphad (0.4.2) only supports TDB files, but new file formats could be easily implemented without modifying any other code dependent on a Database since the objects are not coupled to any particular file format. Using this scheme it is unnecessary for the rest of pycalphad to know anything about how CALPHAD data is represented on disk.

Database exposes a phases attribute containing a Python dictionary mapping the name of a phase to an object which contains information about the sublattice model and phase constituents. It also exposes a search() function for finding model parameters satisfying certain criteria. These are the primary features used by the Model object to build the symbolic representation of a phase’s thermodynamic model.

Model

A Model is an abstract representation of the molar Gibbs energy function of a phase. This representation is built around the computer algebra library SymPy [9], allowing the variables and arithmetic functions required by the CEF to be represented as an abstract graph of Python objects. For example, the operation 2 + 3x might internally be represented as Add(2,Mul(3,x)), with larger structures for more complicated models. For convenience, the library Model class defines several thermodynamic properties. By default, attributes are defined for the following, with Thermo-Calc-style abbreviations listed in parentheses (either are allowed): energy (GM), entropy (SM), enthalpy (SM), heat capacity (CPM), mixing energy (MIX GM), mixing entropy (MIX SM), mixing enthalpy (MIX HM), mixing heat capacity (MIX CPM), curie temperature (TC), and degree of ordering (DOO). It is also possible for users to define custom properties for particular purposes. These SymPy-based abstract graphs, as well as their exact first and second derivatives, are compiled to machine code on demand for computational efficiency. SymPy’s automatic code generation feature is used to provide users maximum flexibility since it offers the ease-of-use of working in Python without having to make a significant performance tradeoff, compared to working only in C, Fortran, or another low-level programming language.

By default the library Model class is used for all phases. It includes support for multi-component Redlich-Kister polynomials using the Muggianu ternary extension [10], the Inden-Hillert-Jarl magnetic model [11, 12], and the order-disorder model for atomic ordering [13, 14]

For parametric model contributions, users can use the param_search argument defined in the function signature of every energetic contribution to query a Database for parameters satisfying some criteria. The Model class defines a redlich_kister_sum() convenience function to allow users to easily build multi-component Redlich-Kister polynomials using parameters defined in a Database. For example, to construct the symbolic form of the mean magnetic moment of a phase in Redlich-Kister form, inside custom_energy() one could write

from tinydb import where
bm_param_query = (
           (where(’phase_name’) == phase.name) & \
           (where(’parameter_type’) == ’BMAGN’) & \
           (where(’constituent_array’).
           test(self._array_validity))
)
mean_magnetic_moment = \
          self.redlich_kister_sum(phase, param_search,
          bm_param_query)

This code snippet will pull all the relevant magnetic parameters from the database, filtered by self._array_validity to include only the declared components in our model.

calculate()

The calculate() function is the core property calculation routine of pycalphad. It does not concern itself with equilibrium at all – that is the responsibility of equilibrium() – but instead performs calculations for the case when all independent degrees of freedom, i.e., temperature, pressure, sublattice site fractions, are specified. The most important arguments of calculate() are

def calculate(dbf, comps, phases, output=’GM’,
                       model=None, points=None,
                       T=None, P=None, **kwargs)

dbf is the Database containing the relevant parameters, comps is a list of desired components for the calculation, and phases is a list of desired phases. (Users can get a list of all phases using list(dbf.phases.keys()).) By default calculate() will compute the GM property of all phases, but users can specify any property defined by the phase model, including properties defined in custom models. By default the library Model class is used for all phases.

Custom models can be specified via the model keyword argument. For example, calculate(dbf, comps, phases, model=CustomModel) overrides the default model for all phases in that energy calculation. To override only a specific phase’s model, we write model={’FCC_A1’: CustomModel} to override the model for the FCC_A1 phase. More sophisticated formulations are also possible. We can use model=[{’FCC_A1’: CustomModel, ’LIQUID’: Model}, YetAnotherModel] for the FCC_A1 phase to use CustomModel, the liquid phase to use the library Model, and all other phases in the calculation to use YetAnotherModel (not defined here). The output keyword argument specifies the property to calculate; this is a string corresponding to an attribute of the library Model or a user-defined subclass of Model, as discussed above. For example, we write output=’CPM’ to indicate the molar heat capacity should be computed. If output is not specified, by default only the molar Gibbs energy is calculated.

The points keyword argument accepts a multi-dimensional array of shape (P, T, y), where P and T are pressures and temperatures at which to perform the calculation, and y is the number of sublattice site fractions. Site fractions are ordered by sublattice number, then alphabetically within a sublattice, e.g., $y_{Al}^0,y_{Ni}^0,y_{Cr}^0,y_{Mo}^0,y_{Ni}^1,y_{Nb}^1$M1 \documentclass[10pt]{article} \usepackage{wasysym} \usepackage[substack]{amsmath} \usepackage{amsfonts} \usepackage{amssymb} \usepackage{amsbsy} \usepackage[mathscr]{eucal} \usepackage{mathrsfs} \usepackage{pmc} \usepackage[Euler]{upgreek} \pagestyle{empty} \oddsidemargin -1.0in \begin{document} \[ y_{Al}^0,{\rm{ }}y_{Ni}^0,{\rm{ }}y_{Cr}^0,{\rm{ }}y_{Mo}^0,{\rm{ }}y_{Ni}^1,{\rm{ }}y_{Nb}^1 \] \end{document} . If the same site fractions are meant to be used for all temperatures and pressures in the calculation, the P and T dimensions can be omitted from the array. For multi-phase calculations, users can pass a Python dictionary mapping the name of a phase to an array of site fractions.

The T and P keyword arguments are the temperatures and pressures in Kelvin and pascals, respectively, for the calculation. (Specifically the units are whatever T and P mean in the phase model but, in the default Model, SI units are used.) Valid arguments are either a scalar or a one-dimensional array. **kwargs is a placeholder for other, less commonly used or experimental options; these are discussed in the pycalphad documentation linked from the GitHub repository. The return value of calculate() is a multi-dimensional labeled array.

equilibrium()

The equilibrium() function is responsible for equilibrium property calculation in pycalphad. Its key arguments are

def equilibrium(dbf, comps, phases, conditions,
                            output=None, model=None, **kwargs)

dbf, comps, phases, output, model, and **kwargs all have the same meaning as in the calculate() function, with the additional feature that output can be either a string or a list of strings. conditions is a Python dictionary mapping state variables to values. Valid arguments for a condition are a scalar, one-dimensional array, or tuple with the form (start, stop, step). For example, an isothermal step calculation might have a conditions argument of the form {v.X(’AL’): (0,1, 0.01), v.T: 600}, where v is defined as a shortcut to pycalphad.variables, a library module where all standard symbols are defined.

The return value of equilibrium() is a multi-dimensional labeled array. Regardless of the value of output, the result array will always include the equilibrium values of the molar Gibbs energy and chemical potentials since they are necessary to compute the solution.

Quality control

Even as a relatively small project, pycalphad is sufficiently complex that it is necessary to implement strategies to avoid the regression, or accidental breakage, of features. The key concepts to understand when managing and developing a complex software project are source code control (SCC) and continuous integration (CI). SCC is critical to verify the integrity of the project over time when admitting changes from multiple, scattered contributors, but it is useful even in single-contributor projects because SCC systems serve as a semi-automated project journal and backup system. This project uses the popular Git SCC system [16] to manage its source code. This allows the complete history of changes to be recorded for all released and unreleased versions of the software. Git also allows different versions of the software to be stored in separate “branches,” allowing concurrent work on, e.g., new major features and bug fixes to existing versions. The Git repository is publicly available online at GitHub (see section 2). Git also extends into pycalphad’s versioning system: major.minor.rev+N.gHASH, where HASH is the Git commit identifier of the latest commit in the master branch of the repository, and N is the number of commits ahead of the last public release. For public releases, everything after the + is omitted. For modifications which have not yet been committed, i.e., in a developer’s local Git repository, the version identifier will be appended with dirty.

CI is the approach of a project to simplify the software release process by testing code incrementally, i.e., every time a revision is made. This makes releasing new versions easier because the release manager can have some confidence that the quality of the code is above some automatically verified baseline. The pycalphad package has a suite of CI tests designed to verify that a revision to the code does not cause unintended behavior. These tests are run automatically every time a new revision is pushed to the Git repository on GitHub. If a test fails for any reason, a report is generated including all the error information. For example, there are tests to ensure that computed values of properties for several known systems do not change. The equilibrium solver, TDB reading and writing, and phase model construction code are also tested for consistency and accuracy. When a bug is reported and fixed in pycalphad, a minimal test case is added to the suite whenever possible to prevent the problem from appearing again in a future release. In total, about 80% of pycalphad, measured by lines of code, is currently tested, with the remainder involving unreachable or experimental code, or code which is difficult to test in an automated fashion, e.g., plotting code.

Archive

Name: Figshare

Persistent identifier: https://dx.doi.org/10.6084/m9.figshare.4213689

Licence: MIT

Publisher: Richard Otis

Version published: 0.4.2

Date published: 07/11/16