StabilityMap¶

Optional dependency

StabilityMap requires calphad. CoherentStabilityMap additionally requires sqsgen. Plotting/visualization support additionally requires plots.

uvpip

# StabilityMap
uv add "materialsframework[calphad]"

# CoherentStabilityMap
uv add "materialsframework[calphad,sqsgen]"

# For plotting/visualization support
uv add "materialsframework[calphad,plots]"

# StabilityMap
pip install "materialsframework[calphad]"

# CoherentStabilityMap
pip install "materialsframework[calphad,sqsgen]"

# For plotting/visualization support
pip install "materialsframework[calphad,plots]"

StabilityMap ¶

StabilityMap(
    db: Database | str,
    elements: list[str] | None = None,
    phase: str | None = None,
    step: float = 0.05,
    temperature: int | float = 1500,
    pressure: int | float = 101325,
    nb_workers: int | None = None,
)

Class to generate a stability map for a given set of elements and phase.

Attributes:

Name	Type	Description
`dbf`	`Database`	The thermodynamic database.
`elements`	`list`	List of elements to include in the stability map.
`phase`	`str`	The phase to include in the stability map.
`compositions`	`DataFrame`	DataFrame containing all valid compositions.
`temperature`	`float`	Temperature in Kelvin.
`pressure`	`float`	Pressure in Pascals.

Methods:

Name	Description
`fit`	Fit the stability map by calculating eigenvalues and determining sections.
`plot`	Plot the stability map.

Notes

The stability map is generated by calculating the eigenvalues of the Hessian of the Gibbs energy with respect to the chemical potentials of the components.

Initialize the StabilityMap class.

Parameters:

Name	Type	Description	Default
`db`	`Database \| str`	pycalphad Database object or path to the thermodynamic database file.	required
`elements`	`list[str] \| None`	List of elements to include in the stability map. If not provided, all elements in the database will be used.	`None`
`phase`	`str \| None`	The phase to include in the stability map. If not provided, the phase in the database will be used.	`None`
`step`	`float`	Step size for generating compositions. Default is 0.05, i.e., 5%.	`0.05`
`temperature`	`int \| float`	Temperature in Kelvin. Default is 1500 K.	`1500`
`pressure`	`int \| float`	Pressure in Pascals. Default is 101325 Pa.	`101325`
`nb_workers`	`int \| None`	Number of worker processes used to parallelize `fit()` across compositions. Default is None, which uses all available cores.	`None`

Raises:

Type	Description
`ValueError`	If multiple phases are found in the database and phase is not specified.

fit ¶

fit()

Fit the stability map by calculating the Hessian eigenvalues for each composition and determining its stability section.

plot ¶

plot(
    show: bool = True,
    save: bool = False,
    column: str = "negative_eigenvalues",
    discrete: bool = False,
) -> tuple

Plot the stability map.

Parameters:

Name	Type	Description	Default
`show`	`bool`	Whether to display the plot. Default is True.	`True`
`save`	`bool`	Whether to save the plot to current directory. Default is False.	`False`
`column`	`str`	Name of the negative-eigenvalue-count column to color points by. Default is "negative_eigenvalues".	`'negative_eigenvalues'`
`discrete`	`bool`	If True, color points by discrete stability category (one color per negative-eigenvalue count, sampled from the "RdBu_r" colormap) instead of the default continuous "viridis" colorbar. Default is False.	`False`

Returns:

Name	Type	Description
`tuple`	`tuple`	Figure and axis objects.

Raises:

Type	Description
`ValueError`	If the number of elements is not 4.
`KeyError`	If `column` is missing.

CoherentStabilityMap ¶

CoherentStabilityMap(
    db: Database | str,
    elements: list[str] | None = None,
    phase: str | None = None,
    crystal_structure: str = "bcc",
    step: float = 0.1,
    temperature: int | float = 1500,
    pressure: int | float = 101325,
    nb_workers: int | None = None,
    calculator: BaseCalculator | None = None,
    sqs_generator: SqsGenerator | None = None,
    supercell_size: tuple[int, int, int] = (5, 5, 5),
    elastic_constants_analyzer: ElasticConstantsAnalyzer
    | None = None,
    finite_diff_step: float = 0.02,
    atoms_per_cell: int = 2,
)

Extends StabilityMap with a coherent-elastic correction to the Gibbs energy Hessian.

At each composition grid point, generates an SQS structure, relaxes it and computes its elastic constants with a BaseCalculator, and adds a coherent-elastic Hessian term (Cahn-type, built from the lattice-parameter/composition gradient and the nonisotropic biaxial modulus) to the chemical Hessian computed the same way StabilityMap does.

Per-composition-point cost is much higher than plain StabilityMap (an SQS optimization plus a relaxation per independent composition direction, plus one elastic-constants calculation), so fit() processes rows sequentially rather than in parallel: MLIP calculators often hold GPU/PyTorch state that does not pickle cleanly across worker processes, and GPU-bound work generally does not parallelize well across processes anyway.

Initialize the CoherentStabilityMap class.

Parameters:

Name	Type	Description	Default
`db`	`Database \| str`	pycalphad Database object or path to the thermodynamic database file.	required
`elements`	`list[str] \| None`	List of elements to include in the stability map. If not provided, all elements in the database will be used.	`None`
`phase`	`str \| None`	The phase to include in the stability map. If not provided, the phase in the database will be used.	`None`
`crystal_structure`	`str`	Crystal structure passed to `SqsGenerator.generate` (e.g. "bcc", "fcc", "hcp"), independent of the CALPHAD `phase` string. Defaults to "bcc". It is the caller's responsibility to keep this physically consistent with `phase` and with `atoms_per_cell`.	`'bcc'`
`step`	`float`	Step size for generating compositions. Default is 0.1 (10%), coarser than `StabilityMap`'s default, since each grid point here is far more expensive (SQS generation + relaxation + elastic constants, not just a CALPHAD equilibrium solve).	`0.1`
`temperature`	`int \| float`	Temperature in Kelvin. Default is 1500 K.	`1500`
`pressure`	`int \| float`	Pressure in Pascals. Default is 101325 Pa.	`101325`
`nb_workers`	`int \| None`	Unused by `CoherentStabilityMap` (row processing is sequential, not process-pooled); kept for constructor-signature compatibility with `StabilityMap`.	`None`
`calculator`	`BaseCalculator \| None`	Calculator used to relax SQS structures and (via `elastic_constants_analyzer`) compute elastic constants. Defaults to a lazily constructed default calculator.	`None`
`sqs_generator`	`SqsGenerator \| None`	Generator used to build an SQS structure for each composition. Defaults to a lazily constructed `SqsGenerator()`.	`None`
`supercell_size`	`tuple[int, int, int]`	Supercell size passed to `SqsGenerator.generate`. Defaults to (5, 5, 5).	`(5, 5, 5)`
`elastic_constants_analyzer`	`ElasticConstantsAnalyzer \| None`	Analyzer used to compute C11/C12/C44 from the relaxed SQS structure. Defaults to a lazily constructed `ElasticConstantsAnalyzer(calculator=self.calculator)`.	`None`
`finite_diff_step`	`float`	Mole-fraction perturbation used to estimate the lattice-parameter composition gradient (`eta`) via forward finite differences. Defaults to 0.02.	`0.02`
`atoms_per_cell`	`int`	Number of atoms in the conventional unit cell implied by `crystal_structure` (2 for BCC, 4 for FCC, ...). Defaults to 2 (BCC).	`2`

Raises:

Type	Description
`ValueError`	If multiple phases are found in the database and phase is not specified.

calculator ¶

calculator() -> BaseCalculator

Returns the calculator used to relax SQS structures and compute elastic constants.

Returns:

Name	Type	Description
`BaseCalculator`	`BaseCalculator`	The calculator object, lazily defaulted if not supplied.

sqs_generator ¶

sqs_generator() -> SqsGenerator

Returns the generator used to build an SQS structure for each composition.

Returns:

Name	Type	Description
`SqsGenerator`	`SqsGenerator`	The SQS generator object, lazily defaulted if not supplied.

elastic_constants_analyzer ¶

elastic_constants_analyzer() -> ElasticConstantsAnalyzer

Returns the analyzer used to compute elastic constants from a relaxed structure.

Returns:

Name	Type	Description
`ElasticConstantsAnalyzer`	`ElasticConstantsAnalyzer`	The analyzer object, lazily defaulted if not supplied.

fit ¶

fit()

Fit the coherent stability map.

For each composition, computes both the chemical-only and the chemical+coherent Hessian eigenvalues, and the corresponding negative-eigenvalue counts. Row processing is sequential (see class docstring for why), not process-pooled like StabilityMap.fit().