httk.analyse.matsci.phase_diagrams¶

Materials-science phase diagrams built on generic lower convex hulls.

Classes¶

`PhaseDiagram`	A normalized float convex-hull phase diagram.
`PhaseDiagramBuilder`	Mutable, not-thread-safe accumulator for incrementally building a phase diagram.

Module Contents¶

class httk.analyse.matsci.phase_diagrams.PhaseDiagram(elements, ids, compositions, energies_per_atom, tolerance, unknown_ids, unknown_compositions)¶

A normalized float convex-hull phase diagram.

Construct with from_compositions() or from_structures(). Energies supplied to either factory are total formula-unit or unit-cell energies and are divided by the corresponding atom count. An energy of None marks an unknown-energy phase, which is retained in the separate unknown_ids/unknown_compositions channel and contributes elements to elements, potentially widening the composition space, but takes no part in hull construction or the indexed hull API. At least one supplied phase must have a known energy; an input whose energies are all None is rejected. All exposed compositions and energies are plain floats.

Hull membership is delegated to LowerConvexHull. At duplicated compositions only the lower-energy polymorph is stable, except that every polymorph tied within the requested energy tolerance is stable. None decompositions identify stable phases, including uncontested phases outside the convex hull of every other input.

Parameters:

elements (tuple[str, Ellipsis]) – Element-coordinate labels in sorted order.
ids (tuple[str, Ellipsis]) – Identifiers for energy-known phases in input order.
compositions (tuple[tuple[float, Ellipsis], Ellipsis]) – Normalized composition rows for energy-known phases.
energies_per_atom (tuple[float, Ellipsis]) – Per-atom energies for energy-known phases.
tolerance (float) – Maximum energy excess treated as stable.
unknown_ids (tuple[str, Ellipsis]) – Identifiers for phases without known energy.
unknown_compositions (tuple[tuple[float, Ellipsis], Ellipsis]) – Normalized composition rows for phases without known energy.

classmethod from_compositions(compositions, energies, ids=None, *, tolerance=1e-08)¶

Build a diagram from formula-unit compositions and total energies.

Each composition maps an element label to its count in the formula unit to which the matching total energy refers. An energy of None retains the phase in the unknown-energy channel without including it in the hull or indexed hull API. Counts must be finite and non-negative, with a strictly positive total atom count. Elements are sorted independently of mapping insertion order before rows are normalized to atomic fractions. At least one energy must be known; inputs whose energies are all None are rejected. ids entries may individually be None to derive the default formula label for that phase.

Parameters:

compositions (collections.abc.Sequence[collections.abc.Mapping[str, int | float | fractions.Fraction]]) – Formula-unit element counts for each phase.
energies (collections.abc.Sequence[float | None]) – Total formula-unit energies corresponding to compositions.
ids (collections.abc.Sequence[str | None] | None) – Optional phase identifiers, with None entries using formula labels.
tolerance (float) – Maximum energy excess treated as stable.

Returns:

The normalized phase diagram.

Raises:

ValueError – If the phase data, energies, identifiers, or tolerance are invalid.

Return type:

Self

classmethod from_structures(structures, energies, ids=None, *, tolerance=1e-08)¶

Build a diagram from structures and their total unit-cell energies.

Each site contributes its named species’ chemical_symbols weighted by concentration. "vacancy" contributes no atoms; "X" is rejected because an unknown element cannot define a composition coordinate. An energy of None retains the phase in the unknown-energy channel without including it in the hull or indexed hull API. Default identifiers are deterministic alphabetically sorted labels using the (possibly fractional) unit-cell counts without reducing them, and ids entries may individually be None to derive that default label. At least one energy must be known; inputs whose energies are all None are rejected.

Parameters:

structures (collections.abc.Sequence[httk.atomistic.StructureLike]) – Structures supplying the phase compositions.
energies (collections.abc.Sequence[float | None]) – Total unit-cell energies corresponding to structures.
ids (collections.abc.Sequence[str | None] | None) – Optional phase identifiers, with None entries using formula labels.
tolerance (float) – Maximum energy excess treated as stable.

Returns:

The normalized phase diagram.

Raises:

ValueError – If the structures, energies, identifiers, or tolerance are invalid.

Return type:

Self

property elements: tuple[str, Ellipsis]¶

Return the element-coordinate order used by compositions.

Returns:: The immutable element labels.
Return type:: tuple[str, Ellipsis]

property ids: tuple[str, Ellipsis]¶

Return identifiers of energy-known phases in input order.

Returns:: The immutable phase identifiers.
Return type:: tuple[str, Ellipsis]

property unknown_ids: tuple[str, Ellipsis]¶

Return identifiers for phases without known energy in input order.

Returns:: The immutable unknown-energy phase identifiers.
Return type:: tuple[str, Ellipsis]

property compositions: tuple[tuple[float, Ellipsis], Ellipsis]¶

Return composition-fraction rows for energy-known phases in elements order.

Returns:: The immutable normalized composition rows.
Return type:: tuple[tuple[float, Ellipsis], Ellipsis]

property unknown_compositions: tuple[tuple[float, Ellipsis], Ellipsis]¶

Return composition-fraction rows for phases without known energy in elements order.

Returns:: The immutable normalized composition rows.
Return type:: tuple[tuple[float, Ellipsis], Ellipsis]

property energies_per_atom: tuple[float, Ellipsis]¶

Return energies per atom for energy-known phases in input order.

Returns:: The immutable per-atom energies.
Return type:: tuple[float, Ellipsis]

property hull_indices: tuple[int, Ellipsis]¶

Return stable phase indices in input order.

Returns:: The immutable stable phase indices.
Return type:: tuple[int, Ellipsis]

property energy_above_hull: tuple[float, Ellipsis]¶

Return non-negative energy distances from the lower hull in per-atom units.

Returns:: The immutable energy distances in input order.
Return type:: tuple[float, Ellipsis]

property phase_lines: tuple[tuple[int, int], Ellipsis]¶

Return sorted midpoint-supported stable tie-lines as (smaller, larger) indices.

Returns:: The immutable stable phase-index pairs.
Return type:: tuple[tuple[int, int], Ellipsis]

decomposition(index)¶

Return optimal stable-phase (index, weight) pairs, or None when stable.

Parameters:: index (int) – Energy-known phase index.
Returns:: The stable-phase mixture, or None when the phase is stable.
Return type:: tuple[tuple[int, float], Ellipsis] | None

is_stable(index)¶

Return whether the phase at index is stable within the energy tolerance.

Parameters:: index (int) – Energy-known phase index.
Returns:: Whether the phase is stable.
Return type:: bool

plot(*, ax=None, show_unstable=True, label_stable=True, show_unknown=True)¶

Plot the phase diagram and return its matplotlib Axes.

Binary diagrams use the fraction of the second element on the x axis. The y axis is formation energy relative to the lowest stable pure-element endpoints when both are present, and raw energy per atom otherwise. One-element diagrams use raw energy at a single composition point. Unknown-energy phases are shown as open gray squares at y=0.0 in binary diagrams (including raw-energy mode) when show_unknown is true; they do not affect the energy reference or hull geometry.

Diagrams with three or more elements use a regular composition polygon whose corner k is at angle 2*pi*k/N. Phase lines are drawn individually in black; stable phases are filled, unstable phases are open, and unknown-energy phases are open gray squares. Matplotlib is imported only here and this method never calls show or writes a file.

Parameters:

ax (Any) – Matplotlib axes to draw on, or None to create one.
show_unstable (bool) – Whether to plot unstable energy-known phases.
label_stable (bool) – Whether to label stable and unknown-energy phases.
show_unknown (bool) – Whether to plot phases without known energy.

Returns:

The matplotlib.axes.Axes containing the diagram.

Raises:

ImportError – If Matplotlib is unavailable.

Return type:

Any

class httk.analyse.matsci.phase_diagrams.PhaseDiagramBuilder(*, tolerance=1e-08)¶

Mutable, not-thread-safe accumulator for incrementally building a phase diagram.

Parameters:: tolerance (float) – Maximum energy excess treated as stable when building the diagram.

add_phase(composition, energy, id=None)¶

Add a formula-unit composition and return this builder for chaining.

Parameters:

composition (collections.abc.Mapping[str, int | float | fractions.Fraction]) – Formula-unit element counts for the phase.
energy (float | None) – Total formula-unit energy, or None when unknown.
id (str | None) – Optional phase identifier.

Returns:

This builder.

Raises:

TypeError – If composition is not a mapping.

Return type:

Self

add_structure(structure, energy, id=None)¶

Convert and add a structure, returning this builder for chaining.

Parameters:

structure (httk.atomistic.StructureLike) – Structure supplying the phase composition.
energy (float | None) – Total unit-cell energy, or None when unknown.
id (str | None) – Optional phase identifier.

Returns:

This builder.

Return type:

Self

build()¶

Build an independent snapshot, requiring at least one known phase energy.

The builder may contain unknown-energy phases, but an all-None energy collection is rejected by the factory validation used to create the snapshot.

Returns:: An independent phase-diagram snapshot.
Raises:: ValueError – If no phase has a known energy or the phase data is invalid.
Return type:: PhaseDiagram