API Reference

Top-level package

`HEACalculator`

General class for high entropy alloy calculations.

Composes AlloyComposition, HEAThermodynamics, and SolidSolutionPredictor to provide a single entry point for HEA calculations. All properties are computed lazily on first access via the thermo and predictor sub-objects.

Parameters:

Name	Type	Description	Default
`formula`	`str`	Alloy formula.	required

Attributes:

Name	Type	Description
`formula`	`str`	The original formula string.
`thermo`	`HEAThermodynamics`	Thermodynamic properties of the alloy.
`predictor`	`SolidSolutionPredictor`	Solid-solution formation predictions.

References

Zhang, Y.; Zuo, T.T.; Tang, Z.; Gao, M.C.; Dahmen, K.A.; Liaw, P.K.; Lu, Z.P. Prog. Mater. Sci. 2014, 61, 1-93.
Troparevsky, M.C.; Morris, J.R.; Kent, P.R.C.; Lupini, A.R.; Stocks, G.M. Phys. Rev. X 2015, 5(1), 011041.
Guo, S.; Ng, C.; Lu, J.; Liu, C.T. J. Appl. Phys. 2011, 109, 103505.
Fang, S.S.; Xiao, X.S.; Xia, L.; Li, W.H.; Dong, Y.D. J. Non-Cryst. Solids 2003, 321, 120-125.
Yang, X.; Zhang, Y. Mater. Chem. Phys. 2012, 132, 233-238.
Wang, Z.; Huang, Y.; Yang, Y.; Wang, J.; Liu, C.T. Scr. Mater. 2015, 94, 28-31.
Singh, A.K.; Kumar, N.; Dwivedi, A.; Subramaniam, A. Intermetallics 2014, 53, 112-119.
Guo, S.; Hu, Q.; Ng, C.; Liu, C.T. Intermetallics 2013, 41, 96-103.
Ye, Y.F.; Wang, Q.; Lu, J.; Liu, C.T.; Yang, Y. Scr. Mater. 2015, 104, 53-55.
Senkov, O.N.; Miracle, D.B. J. Alloys Compd. 2016, 658, 603-607.
King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179.

`init(formula: str) -> None`

Initialize with formula. All properties are computed lazily via thermo and predictor.

`str() -> str`

Return a human-readable summary of all calculated properties.

Returns:

Type	Description
`str`	Multi-line report of thermodynamic values and model predictions.

`get_dict() -> dict`

Return all calculated properties as a dict with raw numeric values.

NaN values are returned as None for JSON compatibility.

Returns:

Type	Description
`dict`	Mapping of property names to raw numeric or string values.

`get_headers() -> list[str]` `classmethod`

Return the tabular result headers in the same order as get_list().

`get_list() -> list`

Return all calculated properties as a formatted list.

Returns:

Type	Description
`list`	Formula, thermodynamic values, and model predictions formatted for tabular output.

`screen(compositions: Sequence[str] | tuple[dict[str, int | float], set[tuple[float, ...]]], n_workers: int | None = None) -> Iterator[HEACalculator]` `staticmethod`

Calculate many alloys in parallel, yielding results in input order.

Parameters:

Name	Type	Description	Default
`compositions`	`Sequence[str] \| tuple[dict[str, int \| float], set[tuple[float, ...]]]`	Alloy formulas, or the output of `find_all_comps`.	required
`n_workers`	`int \| None`	Number of worker processes. Defaults to the CPU count.	`None`

Returns:

Type	Description
`Iterator[HEACalculator]`	A fully calculated `HEACalculator` per alloy. As with a single alloy, an alloy that cannot be calculated raises when its properties are accessed.

Core

Composition

`AlloyComposition`

Parses a chemical formula and exposes composition data needed for calculations.

Parameters:

Name	Type	Description	Default
`formula`	`str`	Alloy formula string (e.g. `"FeCoCrNi"` or `"Fe25Co25Cr25Ni25"`).	required

Attributes:

Name	Type	Description
`formula`	`str`	The original formula string.

`allen_electronegativity_list: list[float]` `cached` `property`

Allen electronegativity for each element in the same order as alloy.

Returns:

Type	Description
`list[float]`	Allen electronegativities in Pauling units aligned with the alloy element order.

`alloy: dict[str, float]` `cached` `property`

Mapping of element symbol to raw atom count.

Returns:

Type	Description
`dict[str, float]`	Parsed element counts from the input formula.

`atomic_percentage: dict[str, float]` `cached` `property`

Mapping of element symbol to atomic fraction (values sum to 1).

Returns:

Type	Description
`dict[str, float]`	Atomic fractions keyed by element symbol.

`atomic_radius_cn12_list: list[float]` `cached` `property`

Goldschmidt CN12 atomic radius for each element in the same order as alloy.

Returns:

Type	Description
`list[float]`	CN12 radii in pm aligned with the alloy element order.

`atomic_radius_list: list[float]` `cached` `property`

Atomic radius for each element in the same order as alloy.

Returns:

Type	Description
`list[float]`	Atomic radii in pm aligned with the alloy element order.

`average_allen_electronegativity: float` `cached` `property`

Composition-weighted average Allen electronegativity.

Returns:

Type	Description
`float`	Composition-weighted average Allen electronegativity in Pauling units.

`average_atomic_radius: float` `cached` `property`

Weighted average atomic radius using atomic fractions.

Returns:

Type	Description
`float`	Composition-weighted average atomic radius in pm.

`average_atomic_radius_cn12: float` `cached` `property`

Composition-weighted average Goldschmidt CN12 atomic radius.

Returns:

Type	Description
`float`	Composition-weighted average CN12 radius in pm.

`average_ea: float` `cached` `property`

Composition-weighted average Hume-Rothery e/a.

Returns:

Type	Description
`float`	Composition-weighted average outer s+p electrons per atom.

`average_pauling_electronegativity: float` `cached` `property`

Composition-weighted average Pauling electronegativity.

Returns:

Type	Description
`float`	Composition-weighted average Pauling electronegativity.

`ea_list: list[float]` `cached` `property`

Hume-Rothery e/a for each element in the same order as alloy.

Returns:

Type	Description
`list[float]`	Outer s+p electron counts aligned with the alloy element order.

`elements: dict[str, _Element]` `cached` `property`

Cached element data keyed by element symbol.

Returns:

Type	Description
`dict[str, _Element]`	Element records for each symbol in the alloy.

`pair_list: list[tuple[str, str]]` `cached` `property`

All unique binary element pairs.

Returns:

Type	Description
`list[tuple[str, str]]`	Unique unordered element pairs from the alloy.

`pair_percentage: list[float]` `cached` `property`

Probability of each pair (product of the two atomic fractions).

Returns:

Type	Description
`list[float]`	Pair probabilities aligned with `pair_list`.

`pauling_electronegativity_list: list[float]` `cached` `property`

Pauling electronegativity for each element in the same order as alloy.

Returns:

Type	Description
`list[float]`	Pauling electronegativities aligned with the alloy element order.

`init(formula: str) -> None`

Initialize with formula; all derived properties are computed lazily on first access.

Raises:

Type	Description
`KeyError`	If any element symbol in the formula is not in the element database.

Thermodynamics

`HEAThermodynamics`

Calculates thermodynamic and structural parameters for an HEA.

All properties are computed lazily on first access and cached.

Parameters:

Name	Type	Description	Default
`composition`	`AlloyComposition`	Parsed alloy composition to calculate properties for.	required

`allen_electronegativity_difference: float` `cached` `property`

Allen electronegativity difference (delta_chi_Allen) of the alloy in %.

Returns:

Type	Description
`float`	Allen electronegativity mismatch in percent.

References

Mann, J.B.; Meek, T.L.; Allen, L.C. J. Am. Chem. Soc. 2000, 122, 2780-2783.
Mann, J.B.; Meek, T.L.; Knight, E.T.; Capitani, J.F.; Allen, L.C. J. Am. Chem. Soc. 2000, 122, 5132-5137.

`atomic_size_difference: float` `cached` `property`

Atomic size difference computed with atomic_radius.

Returns:

Type	Description
`float`	Atomic size difference in percent.

References

Fang, S.S.; Xiao, X.S.; Xia, L.; Li, W.H.; Dong, Y.D. J. Non-Cryst. Solids 2003, 321, 120-125.
Senkov, O.N.; Miracle, D.B. Mater. Res. Bull. 2001, 36, 2183-2198.

`atomic_size_difference_cn12: float` `cached` `property`

Atomic size difference (\(\delta\)) of the alloy, computed with Goldschmidt CN12 radii.

Returns:

Type	Description
`float`	Atomic size difference in percent using CN12 radii.

References

Fang, S.S.; Xiao, X.S.; Xia, L.; Li, W.H.; Dong, Y.D. J. Non-Cryst. Solids 2003, 321, 120-125.
King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179.

`critical_temperature: float` `cached` `property`

Critical temperature \(T_crit = 0.55 * T_m\), used by Models 6 and 7.

Returns:

Type	Description
`float`	55% of the composition-weighted melting temperature in Kelvin.

`delta_g_max: float` `cached` `property`

\(\Delta G_{\text{max}}\): largest-magnitude binary intermetallic energy scaled to alloy stoichiometry, in kJ/mol.

The binary intermetallic enthalpy is computed from the Miedema model (Eq. S9). The largest-magnitude binary value is scaled by j/2 (half the number of elements) to account for the maximum number of binary intermetallic pairs that can form from j elements while maintaining stoichiometry.

Returns:

Type	Description
`float`	Largest-magnitude ordered intermetallic energy contribution in kJ/mol.

References

King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179.

`delta_g_ss: float` `cached` `property`

Gibbs free energy of the disordered solid solution in kJ/mol.

Returns:

Type	Description
`float`	Disordered solid-solution Gibbs free energy in kJ/mol.

References

King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179.

`density: float` `cached` `property`

Approximate density of the alloy in g/cm\(^3\).

Returns:

Type	Description
`float`	Estimated alloy density in g/cm\(^3\).

`ea_ratio: float` `cached` `property`

Hume-Rothery electron-to-atom (e/a) ratio of the alloy.

Counts only outer s+p electrons per atom; d and f electrons are excluded. Noble gases and elements with undefined configurations contribute NaN.

Returns:

Type	Description
`float`	Dimensionless composition-weighted Hume-Rothery e/a ratio.

`excess_entropy: float` `cached` `property`

Excess configurational entropy \(S_E\) in J/K.mol, averaged over BCC and FCC packing.

Always negative or zero. Zero when all atomic radii are identical.

Returns:

Type	Description
`float`	Excess configurational entropy in J/K.mol.

References

Ye, Y.F. et al. Intermetallics 2015, 59, 75-80. (Appendix, eqs. 3A-4B)
Mansoori, G.A.; Carnahan, N.F.; Starling, K.E.; Leland, T.W., Jr. J. Chem. Phys. 1971, 54, 1523-1525.

`f_parameter: float` `property`

Deprecated alias for phi_king.

Returns:

Type	Description
`float`	The Model 8 \(\varPhi\) parameter.

`formation_enthalpy: float` `cached` `property`

Formation enthalpy of the alloy in meV/atom.

Returns:

Type	Description
`float`	Configurational formation enthalpy in meV/atom.

References

Troparevsky, M.C.; Morris, J.R.; Kent, P.R.C.; Lupini, A.R.; Stocks, G.M. Phys. Rev. X 2015, 5(1), 011041.

`gamma: float` `cached` `property`

Gamma parameter (solid-angle ratio of smallest/largest atoms).

Returns:

Type	Description
`float`	Dimensionless gamma parameter from the alloy radius distribution.

References

Wang, Z.; Huang, Y.; Yang, Y.; Wang, J.; Liu, C.T. Scr. Mater. 2015, 94, 28-31.

`lambda_: float` `cached` `property`

Lambda parameter (entropy / atomic-size-difference ratio).

Uses atomic_radius, matching Singh et al..

Returns:

Type	Description
`float`	Dimensionless lambda parameter, or `math.inf` when the delta is zero.

References

Singh, A.K.; Kumar, N.; Dwivedi, A.; Subramaniam, A. Intermetallics 2014, 53, 112-119.

`max_formation_enthalpy: float` `cached` `property`

Maximum binary formation enthalpy in meV/atom.

Returns:

Type	Description
`float`	Highest binary formation enthalpy among all alloy pairs.

`melting_temperature: int | float` `cached` `property`

Approximate melting temperature of the alloy in Kelvin.

Returns:

Type	Description
`int \| float`	Estimated melting temperature rounded up when finite.

`min_formation_enthalpy: float` `cached` `property`

Minimum binary formation enthalpy in meV/atom.

Returns:

Type	Description
`float`	Lowest binary formation enthalpy among all alloy pairs.

`mixing_enthalpy: float` `cached` `property`

Enthalpy of mixing of the alloy in kJ/mol.

Returns:

Type	Description
`float`	Configurational mixing enthalpy in kJ/mol.

References

Zhang, Y.; Zuo, T.T.; Tang, Z.; Gao, M.C.; Dahmen, K.A.; Liaw, P.K.; Lu, Z.P. Prog. Mater. Sci. 2014, 61, 1-93.

`mixing_enthalpy_miedema: float` `cached` `property`

Model 8 solid-solution formation enthalpy in kJ/mol from the Miedema model.

Returns:

Type	Description
`float`	Miedema-model solid-solution enthalpy in kJ/mol.

References

King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179. Supplementary Eqs. S1-S8.
de Boer, F.R.; Boom, R.; Mattens, W.C.M.; Miedema, A.R.; Niessen, A.K. Cohesion in Metals: Transition Metal Alloys. North-Holland, Amsterdam, 1988.

`mixing_entropy: float` `cached` `property`

Configurational mixing entropy of the alloy in J/K.mol.

Returns:

Type	Description
`float`	Configurational mixing entropy in J/K.mol.

`omega: float` `cached` `property`

Omega stability parameter evaluated at the alloy's melting temperature.

Returns:

Type	Description
`float`	Dimensionless omega stability parameter at `melting_temperature`.

References

Yang, X.; Zhang, Y. Mater. Chem. Phys. 2012, 132, 233-238.

`pauling_electronegativity_difference: float` `cached` `property`

Pauling electronegativity difference (delta_chi_Pauling) of the alloy in %.

Returns:

Type	Description
`float`	Pauling electronegativity mismatch in percent.

References

Haynes, W.M. CRC Handbook of Chemistry and Physics, 95th ed.; CRC Press: Boca Raton, FL, 2014. ISBN 9781482208689.

`phi: float` `cached` `property`

\(\phi\) parameter: \((S_c - S_H) / |S_E|\).

\(S_H = |H_a| / T_m\) is the complementary entropy derived from the mixing enthalpy. H_a uses the Takeuchi & Inoue (2005) binary mixing enthalpy table, as cited by Ye et al. (2015) refs [5,14]. \(S_E\) uses the MCSL hard-sphere model with atomic_radius, averaged over the BCC and FCC packing fractions before entering the ratio.

Returns:

Type	Description
`float`	Dimensionless phi parameter, or `math.inf` when \(T_m\) or the averaged \(S_E\) is zero.

References

Ye, Y.F.; Wang, Q.; Lu, J.; Liu, C.T.; Yang, Y. Scr. Mater. 2015, 104, 53-55.
Ye, Y.F. et al. Intermetallics 2015, 59, 75-80.
Takeuchi, A.; Inoue, A. Mater. Trans. JIM 2000, 41, 1372-1378.
Takeuchi, A.; Inoue, A. Mater. Trans. 2005, 46(12), 2817-2829.

`phi_bcc: float` `cached` `property`

Model 5 phi parameter using the BCC packing fraction reported in the supplement.

Returns:

Type	Description
`float`	Dimensionless phi value evaluated at BCC packing.

`phi_fcc: float` `cached` `property`

Model 5 phi parameter using the FCC packing fraction reported in the supplement.

Returns:

Type	Description
`float`	Dimensionless phi value evaluated at FCC packing.

`phi_king: float` `cached` `property`

Model 8 \(\varPhi\) parameter: \(\varPhi = \Delta G_{SS} / (-|\Delta G_{\text{max}}|)\).

Returns:

Type	Description
`float`	Dimensionless model 8 \(\varPhi\) parameter, or `math.inf` when `\Delta G_{\text{max}}` is zero.

`valence_electron_concentration: float` `cached` `property`

Valence electron concentration (VEC) of the alloy.

Returns:

Type	Description
`float`	Dimensionless composition-weighted valence electron concentration.

References

Guo, S.; Ng, C.; Lu, J.; Liu, C.T. J. Appl. Phys. 2011, 109, 103505.

`init(composition: AlloyComposition) -> None`

Initialize with a parsed alloy composition.

`omega_at(temperature: float) -> float`

Omega stability parameter evaluated at temperature.

Parameters:

Name	Type	Description	Default
`temperature`	`float`	Temperature in Kelvin.	required

Returns:

Type	Description
`float`	Dimensionless omega stability parameter at the supplied temperature.

References

Yang, X.; Zhang, Y. Mater. Chem. Phys. 2012, 132, 233-238.

Prediction Models

`SolidSolutionPredictor`

Applies published solid-solution formation criteria to an HEA composition.

Each property independently computes the required thermodynamic parameters via the provided HEAThermodynamics instance and returns "Solid Solution", "Intermetallic" or "Multiple Phases".

Parameters:

Name	Type	Description	Default
`composition`	`AlloyComposition`	Parsed alloy composition.	required
`thermodynamics`	`HEAThermodynamics`	Thermodynamics calculator for the same composition.	required

`microstructure: str` `cached` `property`

Expected crystal structure based on VEC.

Returns:

Type	Description
`str`	One of `"FCC"`, `"BCC"`, `"HCP"`, or `"BCC+FCC"`.

References

Guo, S.; Ng, C.; Lu, J.; Liu, C.T. J. Appl. Phys. 2011, 109, 103505.

`model_1: str` `cached` `property`

Yang & Zhang criteria: \(\Omega\) >= 1.1 and \(\delta\) <= 6.6.

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Intermetallic"`.

References

Yang, X.; Zhang, Y. Mater. Chem. Phys. 2012, 132, 233-238.

`model_2: str` `cached` `property`

Guo et al. criteria: -11.6 < \(\Delta H_{\text{mix}}\) < 3.2 and \(\delta\) < 6.6.

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Intermetallic"`.

References

Guo, S.; Hu, Q.; Ng, C.; Liu, C.T. Intermetallics 2013, 41, 96-103.

`model_3: str` `cached` `property`

Wang et al. criteria: \(\gamma\) < 1.175.

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Intermetallic"`.

References

Wang, Z.; Huang, Y.; Yang, Y.; Wang, J.; Liu, C.T. Scr. Mater. 2015, 94, 28-31.

`model_4: str` `cached` `property`

Singh et al. criteria: \(\lambda\) > 0.96 (DSS), 0.24 <= \(\lambda\) <= 0.96 (DSS + Compound), \(\lambda\) < 0.24 (Compound).

Returns:

Type	Description
`str`	`"Solid Solution"`, `"Multiple Phases"`, or `"Intermetallic"`.

References

Singh, A.K.; Kumar, N.; Dwivedi, A.; Subramaniam, A. Intermetallics 2014, 53, 112-119.

`model_5: str` `cached` `property`

Ye et al. criteria: \(\phi = (S_c - S_H) / |S_E| >= 20\).

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Multiple Phases"`.

References

Ye, Y.F.; Wang, Q.; Lu, J.; Liu, C.T.; Yang, Y. Scr. Mater. 2015, 104, 53-55.

`model_6: str` `cached` `property`

Troparevsky et al. criteria: all binary \(\Delta H_f\) within [\(-T_{crit}*\Delta S_{\text{mix}}\), 37 meV/atom].

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Multiple Phases"`.

References

Troparevsky, M.C.; Morris, J.R.; Kent, P.R.C.; Lupini, A.R.; Stocks, G.M. Phys. Rev. X 2015, 5(1), 011041.

`model_8: str` `cached` `property`

King et al. criteria: \(\varPhi = \Delta G_{SS} / (-|\Delta G_{\text{max}}|) >= 1\).

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Multiple Phases"`.

References

King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179.

`init(composition: AlloyComposition, thermodynamics: HEAThermodynamics) -> None`

Initialize with parsed composition and a thermodynamics calculator.

`model_7(k_2: float = 0.6, annealing_temperature: float | None = None) -> str`

Senkov & Miracle criteria.

Parameters:

Name	Type	Description	Default
`k_2`	`float`	Ratio of intermetallic and mixing entropies. Defaults to 0.6.	`0.6`
`annealing_temperature`	`float`	Temperature in Kelvin for the Omega calculation. Defaults to 55% of \(T_m\).	`None`

Returns:

Type	Description
`str`	`"Solid Solution"` or `"Intermetallic"`.

References

Senkov, O.N.; Miracle, D.B. J. Alloys Compd. 2016, 658, 603-607.

`model_7_k1() -> float`

Model 7 \(k_1 = \Delta H_{\text{IM}}\) / \(\Delta H_{\text{mix}}\).

Returns:

Type	Description
`float`	The dimensionless `k1` ratio, or `math.inf` when `deltaH_mix` is zero,
`float`	or `math.nan` when formation enthalpy data is unavailable.

`model_7_k1_critical(k_2: float = 0.6, annealing_temperature: float | None = None) -> float`

Model 7 critical \(k_1\) threshold at the given annealing temperature.

Returns:

Type	Description
`float`	Dimensionless critical `k1` threshold for the supplied annealing condition.

Batch Converter

`BatchCalculator`

Converts alloy compositions between atomic, weight, and volume percentages.

Parameters:

Name	Type	Description	Default
`selected_elements`	`dict`	A dictionary mapping element symbols to atomic percents.	required

`init(selected_elements: dict[str, float]) -> None`

Initialize with a dict of element symbols to atomic percents.

`at_to_vol() -> np.ndarray`

Convert from atomic percent to volume percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Volume percentages in the same element order as the input.

`at_to_wt() -> np.ndarray`

Convert from atomic percent to weight percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Weight percentages in the same element order as the input.

`vol_to_at() -> np.ndarray`

Convert from volume percent to atomic percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Atomic percentages in the same element order as the input.

`vol_to_wt() -> np.ndarray`

Convert from volume percent to weight percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Weight percentages in the same element order as the input.

`wt_to_at() -> np.ndarray`

Convert from weight percent to atomic percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Atomic percentages in the same element order as the input.

`wt_to_vol() -> np.ndarray`

Convert from weight percent to volume percent.

Returns:

Type	Description
`ndarray`	numpy.ndarray: Volume percentages in the same element order as the input.

Helpers

`helpers`

Chemical formula parsing utilities.

`nested_formula_parser(formula: str, check: bool = True) -> dict[str, int | float]`

Parse a chemical formula string into a dict of element counts.

Handles nested round or square brackets and their multipliers, as well as rational element counts. Accepts repeated chemical units and drops elements with a zero count. Performs no sanity checking that elements are actually elements. Implemented from the Chemicals library.

Parameters:

Name	Type	Description	Default
`formula`	`str`	Formula string, simple formats only.	required
`check`	`bool`	If `True`, a simple check will be performed to determine if the input is a valid formula, and an exception will be raised if it is not. Defaults to True.	`True`

Returns:

Type	Description
`dict[str, int \| float]`	Dictionary of counts of individual atoms, indexed by symbol with proper capitalization.

Raises:

Type	Description
`ValueError`	If brackets are unbalanced, a count has no element or bracket before it, no element has a nonzero count, or (with `check`) the formula contains anything besides symbols, counts, brackets and spaces.

References

Bell, C.; Cortes-Pena, Y.R.; and Contributors. Chemicals: Chemical Engineering Design Library (ChEDL). 2016-2021. https://github.com/CalebBell/chemicals.

Utils

`find_all_comps(alloy: str, start: float, end: float, step: float) -> tuple[dict[str, int | float], set[tuple[float, ...]]]`

Find all valid composition combinations for the given elements and range.

Parameters:

Name	Type	Description	Default
`alloy`	`str`	Alloy formula string defining the elements to screen.	required
`start`	`float`	Lowest atomic percent for each element (inclusive).	required
`end`	`float`	Highest atomic percent for each element (inclusive).	required
`step`	`float`	Composition screening step size.	required

Returns:

Type	Description
`tuple[dict[str, int \| float], set[tuple[float, ...]]]`	The parsed formula dict and a set of valid composition tuples. Pure single-element compositions are always excluded, even when the range includes both 0 and 100.

Data

Element Database

`Element(name: str) -> _Element`

Return an element object containing its physical and chemical properties.

Parameters:

Name	Type	Description	Default
`name`	`str`	The element symbol, e.g. `"Fe"`.	required

Returns:

Type	Description
`_Element`	Frozen dataclass containing the element's properties.

Raises:

Type	Description
`TypeError`	If the input is not a string.
`ElementNotFoundError`	If the requested element does not exist in the database.

Mixing Enthalpy Database

`MixingEnthalpy(pair: tuple[str, str] | list[str]) -> float`

Return the pair mixing enthalpy of an element pair in kJ/mol.

Parameters:

Name	Type	Description	Default
`pair`	`tuple or list`	The element pair, e.g. `("Fe", "Co")`.	required

Returns:

Type	Description
`float`	The pair mixing enthalpy in kJ/mol.

Raises:

Type	Description
`TypeError`	If the input is not a tuple or list.
`MissingMixingEnthalpyError`	If the requested pair does not exist in the database.

References

Takeuchi, A.; Inoue, A. Mater. Trans. 2005, 46(12), 2817-2829. Table 1 and 2.

Formation Enthalpy Database

`FormationEnthalpy(pair: tuple[str, str] | list[str]) -> float`

Return the pair formation enthalpy of an element pair in meV/atom.

Parameters:

Name	Type	Description	Default
`pair`	`tuple or list`	The element pair, e.g. `("Fe", "Co")`.	required

Returns:

Type	Description
`float`	The pair formation enthalpy in meV/atom.

Raises:

Type	Description
`TypeError`	If the input is not a tuple or list.
`MissingFormationEnthalpyError`	If the requested pair does not exist in the database.

References

Troparevsky, M.C.; Morris, J.R.; Kent, P.R.C.; Lupini, A.R.; Stocks, G.M. Phys. Rev. X 2015, 5(1), 011041.

Miedema Enthalpy

`MiedemaEnthalpy(pair: tuple[str, str] | list[str], c_a: float = 0.5, c_b: float = 0.5) -> float`

Binary interaction parameter \(H_{ij}\) in kJ/mol from the Miedema macroscopic atom model.

Parameters:

Name	Type	Description	Default
`pair`	`tuple or list`	Element pair, e.g. `("Fe", "Ni")`.	required
`c_a`	`float`	Fraction of the first element in the binary subsystem before normalization.	`0.5`
`c_b`	`float`	Fraction of the second element in the binary subsystem before normalization.	`0.5`

Returns:

Type	Description
`float`	\(H_{ij}\) in kJ/mol.

Raises:

Type	Description
`TypeError`	If pair is not a tuple or list.
`MissingMiedemaDataError`	If Miedema parameters are unavailable for either element.

References

de Boer, F.R.; Boom, R.; Mattens, W.C.M.; Miedema, A.R.; Niessen, A.K. Cohesion in Metals: Transition Metal Alloys. North-Holland, Amsterdam, 1988. Tables V-1.1 and V-3.
King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179. Supplementary Eqs. S4-S7.
Niessen, A.K.; Miedema, A.R. Ber. Bunsenges. Phys. Chem. 1983, 87, 717-725. Eq. 9 and Table I.

`MiedemaIntEnthalpy(pair: tuple[str, str] | list[str], c_a: float = 0.5, c_b: float = 0.5) -> float`

Binary intermetallic interaction parameter \(H_{int}\) in kJ/mol (chemical term only).

Computes the chemical/interface term \(H_{chem}\) only, without the elastic mismatch correction. Used for the ordered intermetallic reference energy \(\Delta G_{\text{max}}\) in King et al. (2016) Eq. S.9.

Parameters:

Name	Type	Description	Default
`pair`	`tuple or list`	Element pair, e.g. `("Fe", "Ni")`.	required
`c_a`	`float`	Fraction of the first element in the binary subsystem before normalization.	`0.5`
`c_b`	`float`	Fraction of the second element in the binary subsystem before normalization.	`0.5`

Returns:

Type	Description
`float`	\(H_{int}\) in kJ/mol.

Raises:

Type	Description
`TypeError`	If pair is not a tuple or list.
`MissingMiedemaDataError`	If Miedema parameters are unavailable for either element.

References

King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172-179. Supplementary Eq. S.9.

Exceptions

`exceptions`

Package-level exceptions for HEACalculator.

`ElementNotFoundError`

Raised when an element symbol has no entry in the element database.

`MissingFormationEnthalpyError`

Raised when a binary element pair has no formation enthalpy entry.

`MissingMiedemaDataError`

Raised when Miedema parameters are unavailable for a requested element.

`MissingMixingEnthalpyError`

Raised when a binary element pair has no mixing enthalpy entry.

`MissingPairDataError`

Raised when a binary element pair has no entry in a data database.

API Reference

Top-level package

HEACalculator

formula

__init__(formula: str) -> None

__str__() -> str

get_dict() -> dict

get_headers() -> list[str] classmethod

get_list() -> list

screen(compositions: Sequence[str] | tuple[dict[str, int | float], set[tuple[float, ...]]], n_workers: int | None = None) -> Iterator[HEACalculator] staticmethod

compositions

n_workers

Core

Composition

AlloyComposition

formula

allen_electronegativity_list: list[float] cached property

alloy: dict[str, float] cached property

atomic_percentage: dict[str, float] cached property

atomic_radius_cn12_list: list[float] cached property

atomic_radius_list: list[float] cached property

average_allen_electronegativity: float cached property

average_atomic_radius: float cached property

average_atomic_radius_cn12: float cached property

average_ea: float cached property

average_pauling_electronegativity: float cached property

ea_list: list[float] cached property

elements: dict[str, _Element] cached property

pair_list: list[tuple[str, str]] cached property

pair_percentage: list[float] cached property

pauling_electronegativity_list: list[float] cached property

__init__(formula: str) -> None

Thermodynamics

HEAThermodynamics

composition

allen_electronegativity_difference: float cached property

atomic_size_difference: float cached property

atomic_size_difference_cn12: float cached property

critical_temperature: float cached property

delta_g_max: float cached property

delta_g_ss: float cached property

density: float cached property

ea_ratio: float cached property

excess_entropy: float cached property

f_parameter: float property

formation_enthalpy: float cached property

gamma: float cached property

lambda_: float cached property

max_formation_enthalpy: float cached property

melting_temperature: int | float cached property

min_formation_enthalpy: float cached property

mixing_enthalpy: float cached property

mixing_enthalpy_miedema: float cached property

mixing_entropy: float cached property

omega: float cached property

pauling_electronegativity_difference: float cached property

phi: float cached property

phi_bcc: float cached property

phi_fcc: float cached property

phi_king: float cached property

valence_electron_concentration: float cached property

__init__(composition: AlloyComposition) -> None

omega_at(temperature: float) -> float

temperature

Prediction Models

SolidSolutionPredictor

composition

thermodynamics

microstructure: str cached property

model_1: str cached property

model_2: str cached property

model_3: str cached property

model_4: str cached property

model_5: str cached property

model_6: str cached property

model_8: str cached property

__init__(composition: AlloyComposition, thermodynamics: HEAThermodynamics) -> None

model_7(k_2: float = 0.6, annealing_temperature: float | None = None) -> str

k_2

annealing_temperature

`HEACalculator`

`formula`

`init(formula: str) -> None`

`str() -> str`

`get_dict() -> dict`

`get_headers() -> list[str]` `classmethod`

`get_list() -> list`

`screen(compositions: Sequence[str] | tuple[dict[str, int | float], set[tuple[float, ...]]], n_workers: int | None = None) -> Iterator[HEACalculator]` `staticmethod`

`compositions`

`n_workers`

`AlloyComposition`

`formula`

`allen_electronegativity_list: list[float]` `cached` `property`

`alloy: dict[str, float]` `cached` `property`

`atomic_percentage: dict[str, float]` `cached` `property`

`atomic_radius_cn12_list: list[float]` `cached` `property`

`atomic_radius_list: list[float]` `cached` `property`

`average_allen_electronegativity: float` `cached` `property`

`average_atomic_radius: float` `cached` `property`

`average_atomic_radius_cn12: float` `cached` `property`

`average_ea: float` `cached` `property`

`average_pauling_electronegativity: float` `cached` `property`

`ea_list: list[float]` `cached` `property`

`elements: dict[str, _Element]` `cached` `property`

`pair_list: list[tuple[str, str]]` `cached` `property`

`pair_percentage: list[float]` `cached` `property`

`pauling_electronegativity_list: list[float]` `cached` `property`

`init(formula: str) -> None`

`HEAThermodynamics`

`composition`

`allen_electronegativity_difference: float` `cached` `property`

`atomic_size_difference: float` `cached` `property`

`atomic_size_difference_cn12: float` `cached` `property`

`critical_temperature: float` `cached` `property`

`delta_g_max: float` `cached` `property`

`delta_g_ss: float` `cached` `property`

`density: float` `cached` `property`

`ea_ratio: float` `cached` `property`

`excess_entropy: float` `cached` `property`

`f_parameter: float` `property`

`formation_enthalpy: float` `cached` `property`

`gamma: float` `cached` `property`

`lambda_: float` `cached` `property`

`max_formation_enthalpy: float` `cached` `property`

`melting_temperature: int | float` `cached` `property`

`min_formation_enthalpy: float` `cached` `property`

`mixing_enthalpy: float` `cached` `property`

`mixing_enthalpy_miedema: float` `cached` `property`

`mixing_entropy: float` `cached` `property`

`omega: float` `cached` `property`

`pauling_electronegativity_difference: float` `cached` `property`

`phi: float` `cached` `property`

`phi_bcc: float` `cached` `property`

`phi_fcc: float` `cached` `property`

`phi_king: float` `cached` `property`

`valence_electron_concentration: float` `cached` `property`

`init(composition: AlloyComposition) -> None`

`omega_at(temperature: float) -> float`

`temperature`

`SolidSolutionPredictor`

`composition`

`thermodynamics`

`microstructure: str` `cached` `property`

`model_1: str` `cached` `property`

`model_2: str` `cached` `property`

`model_3: str` `cached` `property`

`model_4: str` `cached` `property`

`model_5: str` `cached` `property`

`model_6: str` `cached` `property`

`model_8: str` `cached` `property`

`init(composition: AlloyComposition, thermodynamics: HEAThermodynamics) -> None`

`model_7(k_2: float = 0.6, annealing_temperature: float | None = None) -> str`

`k_2`

`annealing_temperature`

`model_7_k1() -> float`

`model_7_k1_critical(k_2: float = 0.6, annealing_temperature: float | None = None) -> float`

`BatchCalculator`

`selected_elements`

`init(selected_elements: dict[str, float]) -> None`

`at_to_vol() -> np.ndarray`