pycalphad package

Subpackages

Submodules

pycalphad.model module

The model module provides support for using a Database to perform calculations under specified conditions.

class pycalphad.model.Model(*args, **kwargs)[source]

Bases: object

Models use an abstract representation of the function for calculation of values under specified conditions.

Parameters:

  • dbe (Database) – Database containing the relevant parameters.

  • comps (list) – Names of components to consider in the calculation.

  • phase_name (str) – Name of phase model to build.

  • parameters (dict or list) – Optional dictionary of parameters to be substituted in the model. A list of parameters will cause those symbols to remain symbolic. This will overwrite parameters specified in the database

constituents

A list of sublattices containing the sets of species on each sublattice.

Type:

List[Set[Species]]

None yet.

Examples

None yet.

Notes

The two sublattice ionic liquid model has several special cases compared to typical models within the compound energy formalism. A few key differences arise. First, variable site ratios (modulated by vacancy site fractions) are used to charge balance the phase. Second, endmembers for neutral species and interactions among only neutral species should be specified using only one sublattice (dropping the cation sublattice). For understanding the special cases used throughout this class, users are referred to: Sundman, “Modification of the two-sublattice model for liquids”, Calphad 15(2) (1991) 109-119 https://doi.org/d3jppb

BMAG = 0
property CPM
property CPM_MIX
property DOO
property G
property GM
property GM_MIX
property H
property HM
property HM_MIX
NT = 0
property SM
property SM_MIX
TC = 0
property ast

Return the full abstract syntax tree of the model.

atomic_ordering_energy(dbe)[source]

Return the atomic ordering contribution in symbolic form.

If the current phase is anything other than the ordered phase in a paritioned order/disorder Gibbs energy model, this method will return zero. If the current phase is the ordered phase, ordering energy is computed by equation (18) of Connetable et al. [1]: \(\Delta G^\mathrm{ord}(y_i) = G^\mathrm{ord}(y_i) - G^\mathrm{ord}(y_i = x_i)\)

This method must be the last energy contribution called because it plays several roles that require all other contributions to be defined:

1. The current AST in self.models represents the ordered energy \(G^\mathrm{ord}(y_i)\). To compute the ordering energy, all contributions to the ordered energy must have already been counted.

2. The true energy of the phase should be the sum of the disordered phase’s energy and the ordering energy. That is, \(G = G^\mathrm{dis} + \Delta G^\mathrm{ord}(y_i)\). This method not only computes the ordering energy, but also replaces the other model contributions by the disordered phase’s energy.

3. Physical properties are partitioned in the same way as the energy. See Section 5.8.6 of Lukas, Fries and Sundman [2].

Notes

Caution

This method overwrites the self.models dictionary with the model contributions for the disordered phase.

This method assumes that the first sublattice of the disordered phase is the substitutional sublattice and all other sublattices are interstitial. In the ordered phase, all sublattices with constituents that match the disordered substitutional sublattice will be treated as disordered (with site fractions replaced by quasi mole fractions in the ordered sublattices) and the interstitial sublattices will not have any site fractions substituted.

References

beta = 0
build_phase(dbe)[source]

Generate the symbolic form of all the contributions to this phase.

Parameters:

dbe (Database)

contributions = [('ref', 'reference_energy'), ('idmix', 'ideal_mixing_energy'), ('xsmix', 'excess_mixing_energy'), ('mag', 'magnetic_energy'), ('2st', 'twostate_energy'), ('ein', 'einstein_energy'), ('vol', 'volume_energy'), ('ord', 'atomic_ordering_energy')]
curie_temperature = 0
property degree_of_ordering
einstein_energy(dbe)[source]

Return the energy based on the Einstein model. Note that THETA parameters are actually LN(THETA). All Redlich-Kister summation is done in log-space, then exp() is called on the result.

property endmember_reference_model

Return a Model containing only energy contributions from endmembers.

Return type:

Model

Notes

The endmember_reference_model is used for _MIX properties of Model objects. It is defined such that subtracting it from the model will set the energy of the endmembers to zero. The endmember_reference_model AST can be modified in the same way as any Model.

Partitioned models have energetic contributions from the ordered compound energies/interactions and the disordered compound energies/interactions. The endmembers to choose as the reference is ambiguous. If the current model has an ordered energy as part of a partitioned model, then the model energy contributions are set to nan.

The endmember reference model is built lazily and stored for later re-use because it needs to copy the Database and instantiate a new Model.

property energy
property enthalpy
property entropy
excess_mixing_energy(dbe)[source]

Build the binary, ternary and higher order interaction term Here we use Redlich-Kister polynomial basis by default Here we use the Muggianu ternary extension by default Replace y_i -> y_i + (1 - sum(y involved in parameter)) / m, where m is the arity of the interaction parameter

extrapolate_temperature_bounds = True
property formulaenergy
property formulaenthalpy
get_internal_constraints()[source]
gradient = None
property heat_capacity
ideal_mixing_energy(dbe)[source]

Returns the ideal mixing energy in symbolic form.

kohler_toop_excess_sum(dbe)[source]
magnetic_energy(dbe)[source]

Return the energy from magnetic ordering in symbolic form. The implemented model is the Inden-Hillert-Jarl formulation. The approach follows from the background of W. Xiong et al, Calphad, 2012.

property mixing_energy
property mixing_enthalpy
property mixing_entropy
property mixing_heat_capacity
moles(species, per_formula_unit=False)[source]

Number of moles of species or elements.

neel_temperature = 0
redlich_kister_sum(phase, param_search, param_query)[source]

Construct parameter in Redlich-Kister polynomial basis, using the Muggianu ternary parameter extension.

reference_energy(dbe)[source]

Returns the weighted average of the endmember energies in symbolic form.

shift_reference_state(reference_states, dbe, contrib_mods=None, output=('GM', 'HM', 'SM', 'CPM'), fmt_str='{}R')[source]

Add new attributes for calculating properties w.r.t. an arbitrary pure element reference state.

Parameters:

  • reference_states (Iterable of pycalphad.model.ReferenceState) – Pure element ReferenceState objects. Must include all the pure elements defined in the current model.

  • dbe (Database) – Database containing the relevant parameters.

  • output (Iterable, optional) – Parameters to subtract the ReferenceState from, defaults to (‘GM’, ‘HM’, ‘SM’, ‘CPM’).

  • contrib_mods (Mapping, optional) – Map of {model contribution: new value}. Used to adjust the pure reference model contributions at the time this is called, since the models attribute of the pure element references are effectively static after calling this method.

  • fmt_str (str, optional) – String that will be formatted with the output parameter name. Defaults to “{}R”, e.g. the transformation of ‘GM’ -> ‘GMR’

classmethod symbol_replace(obj, symbols)[source]

Substitute values of symbols into ‘obj’.

Parameters:

  • obj (SymEngine object)

  • symbols (dict mapping symengine.Symbol to SymEngine object)

Return type:

SymEngine object

twostate_energy(dbe)[source]

Return the energy from liquid-amorphous two-state model.

classmethod unwrap_piecewise(graph)[source]
property variables

Return state variables in the model.

volume_energy(dbe)[source]

Return the volumetric contribution in symbolic form. Follows the approach by Lu, Selleby, and Sundman [1].

Parameters:

dbe (Database) – Database containing the relevant parameters.

Notes

The high-pressure portion of the model is not currently implemented. The parameters needed for it are queried from the database; however, calculations are reserved for future implementation.

References

[1] Lu, Selleby, and Sundman, Calphad, Vol. 29, No. 1, 2005, doi:10.1016/j.calphad.2005.04.001.

xiong_magnetic_energy(dbe)[source]

Return the energy from magnetic ordering in symbolic form. The approach follows W. Xiong et al, Calphad, 2012.

class pycalphad.model.ReferenceState(species, reference_phase, fixed_statevars=None)[source]

Bases: object

Define the phase and any fixed state variables as a reference state for a component.

fixed_statevars

Dictionary of {StateVariable: value} that will be fixed, e.g. {v.T: 298.15, v.P: 101325}

Type:

dict

phase_name

Name of phase

Type:

str

species

pycalphad Species variable

Type:

Species

class pycalphad.model.TestModel(*args, **kwargs)[source]

Bases: Model

Test Model object for global minimization.

Equation 15.2 in: P.M. Pardalos, H.E. Romeijn (Eds.), Handbook of Global Optimization, vol. 2. Kluwer Academic Publishers, Boston/Dordrecht/London (2002)

Parameters:

  • dbf (Database) – Ignored by TestModel but retained for API compatibility.

  • comps (sequence) – Names of components to consider in the calculation.

  • phase (str) – Name of phase model to build.

  • solution (sequence, optional) – Float array locating the true minimum. Same length as ‘comps’. If not specified, randomly generated and saved to self.solution

None yet.

Examples

None yet.

class pycalphad.model.classproperty(f)[source]

Bases: object

pycalphad.variables module

Classes and constants for representing thermodynamic variables.

class pycalphad.variables.ChemicalPotential(species)[source]

Bases: StateVariable

Chemical potentials are symbols with built-in assumptions of being real.

compute_property(compsets, cur_conds, chemical_potentials)[source]
property display_name
display_units = 'J / mol'
expand_wildcard(components)[source]
implementation_units = 'J / mol'
jansson_deltas(spec, state) → JanssonDerivativeDeltas[source]
jansson_derivative(compsets, cur_conds, chemical_potentials, deltas: JanssonDerivativeDeltas)[source]

Compute Jansson derivative with self as numerator, with the given deltas

class pycalphad.variables.Component(name, constituents=None)[source]

Bases: object

A chemical component, either a pure element or a linear combination of pure elements.

name

Name of the component

Type:

string

constituents

Dictionary of {element: quantity} where the element is a string and the quantity a float.

Type:

dict

classmethod cast_from(s: str) → Component[source]
property escaped_name

Name safe to embed in the variable name of complex arithmetic expressions.

property number_of_atoms

Number of atoms per formula unit. Vacancies do not count as atoms.

class pycalphad.variables.IndependentPotential(name)[source]

Bases: StateVariable

pycalphad.variables.MU

alias of ChemicalPotential

class pycalphad.variables.MassFraction(*args)[source]

Bases: StateVariable

Weight fractions are symbols with built-in assumptions of being real and nonnegative.

compute_property(compsets, cur_conds, chemical_potentials)[source]
display_units = 'fraction'
implementation_units = 'fraction'
class pycalphad.variables.MoleFraction(*args)[source]

Bases: StateVariable

MoleFractions are symbols with built-in assumptions of being real and nonnegative.

compute_per_phase_property(compset, cur_conds)[source]
compute_property(compsets, cur_conds, chemical_potentials)[source]
compute_property_gradient(compsets, cur_conds, chemical_potentials)[source]

Compute partial derivatives of property with respect to degrees of freedom of given CompositionSets

display_units = 'fraction'
expand_wildcard(phase_names=None, components=None)[source]
implementation_units = 'fraction'
jansson_deltas(spec, state) → JanssonDerivativeDeltas[source]
jansson_derivative(compsets, cur_conds, chemical_potentials, deltas: JanssonDerivativeDeltas)[source]

Compute Jansson derivative with self as numerator, with the given deltas

pycalphad.variables.NP

alias of PhaseFraction

class pycalphad.variables.PhaseFraction(phase_name)[source]

Bases: StateVariable

Phase fractions are symbols with built-in assumptions of being real and nonnegative. The constructor handles formatting of the name.

compute_property(compsets, cur_conds, chemical_potentials)[source]
display_units = 'fraction'
expand_wildcard(phase_names)[source]
implementation_units = 'fraction'
jansson_derivative(compsets, cur_conds, chemical_potentials, deltas: JanssonDerivativeDeltas)[source]

Compute Jansson derivative with self as numerator, with the given deltas

class pycalphad.variables.PressureType[source]

Bases: IndependentPotential

display_name = 'Pressure'
display_units = 'pascal'
implementation_units = 'pascal'
class pycalphad.variables.SiteFraction(phase_name, subl_index, species)[source]

Bases: StateVariable

Site fractions are symbols with built-in assumptions of being real and nonnegative. The constructor handles formatting of the name.

compute_property(compsets, cur_conds, chemical_potentials)[source]
display_units = 'fraction'
expand_wildcard(phase_names=None, components=None, sublattice_indices=None)[source]
implementation_units = 'fraction'
class pycalphad.variables.Species(name, constituents=None, charge=0)[source]

Bases: object

A chemical species.

name

Name of the specie

Type:

string

constituents

Dictionary of {element: quantity} where the element is a string and the quantity a float.

Type:

dict

charge

Integer charge. Can be positive or negative.

Type:

int

classmethod cast_from(s: str) → Species[source]
property escaped_name

Name safe to embed in the variable name of complex arithmetic expressions.

property number_of_atoms

Number of atoms per formula unit. Vacancies do not count as atoms.

property weight

Number of grams per formula unit.

class pycalphad.variables.StateVariable(name)[source]

Bases: Symbol

State variables are symbols with built-in assumptions of being real.

compute_property(compsets, cur_conds, chemical_potentials)[source]
property display_name
display_units = ''
filtered(input_compsets)[source]

Return a generator of CompositionSets applicable to the current property

implementation_units = ''
property is_global_property
jansson_deltas(spec, state) → JanssonDerivativeDeltas[source]
jansson_derivative(compsets, cur_conds, chemical_potentials, deltas: JanssonDerivativeDeltas)[source]

Compute Jansson derivative with self as numerator, with the given deltas

property multiplicity
property phase_name_without_suffix
property shape
class pycalphad.variables.SystemMolesType[source]

Bases: StateVariable

display_name = 'No. Moles'
display_units = 'mol'
implementation_units = 'mol'
class pycalphad.variables.TemperatureType[source]

Bases: IndependentPotential

display_name = 'Temperature'
display_units = 'kelvin'
implementation_units = 'kelvin'
pycalphad.variables.W

alias of MassFraction

pycalphad.variables.X

alias of MoleFraction

pycalphad.variables.Y

alias of SiteFraction

pycalphad.variables.get_mass_fractions(mole_fractions, dependent_species, pure_element_mass_dict)[source]

Return a mapping of MassFractions for a point composition.

Parameters:

  • mass_fractions (Mapping[MoleFraction, float])

  • dependent_species (Union[Component, str]) – Dependent species not appearing in the independent mass fractions.

  • pure_element_mass_dict (Union[Mapping[str, float], pycalphad.Database]) – Either a mapping from pure elements to their mass, or a Database from which they can be retrieved.

Return type:

Dict[MassFraction, float]

pycalphad.variables.get_mole_fractions(mass_fractions, dependent_species, pure_element_mass_dict)[source]

Return a mapping of MoleFractions for a point composition.

Parameters:

  • mass_fractions (Mapping[MassFraction, float])

  • dependent_species (Union[Component, str]) – Dependent species not appearing in the independent mass fractions.

  • pure_element_mass_dict (Union[Mapping[str, float], pycalphad.Database]) – Either a mapping from pure elements to their mass, or a Database from which they can be retrieved.

Return type:

Dict[MoleFraction, float]

pycalphad.variables.site_fraction

alias of SiteFraction

pycalphad.variables.unpack_components(components: Sequence[Component | Species | str], dbf: Database | None = None)[source]

Build a set of Components from ones provided by the caller.

The components can be given as: 1. Component objects, which are directly used 2. Species objects, which will be converted to Component objects 3. str objects, which will be resolved to a Component by:

  1. matching with the name of a Species object present in the Database, or

  2. by parsing the string via the Component constructor

Parameters:

  • comps (Sequence[Component | Species | str]) – Names of components to consider in the calculation.

  • dbf (Optional[Database]) – Thermodynamic database containing elements and species. If no database is passed, constructing Component objects via pattern matching to Species defined in the Database (3a) will not be possible.

Returns:

Set of Component objects

Return type:

set

Examples

>>> from pycalphad import Database, variables as v
>>> dbf = Database()
>>> dbf.species.add(v.Species("WCL4", {"W": 1, "CL": 4}))
>>> dbf.species.add(v.Species("H+", {"H": 1.0}, charge=1.0))
>>> unpack_components([v.Component("NACL"), v.Species("H2O"), "SIO2", "K1CL1", "WCL4", "H+"], dbf)

Module contents