plot

Generalized phase-diagram rendering

The generalized renderer consumes an already evaluated PhaseDiagramResult. It does not construct a thermodynamic state, reevaluate energies, select a different stable phase, show a GUI window, or save a file. It returns the Matplotlib figure, axes, and color guide so applications retain control of presentation and output.

By default, the renderer uses a continuous atomic-fraction gradient for the first independent component retained by the numerical result. Independent component order follows the model’s declared component order, making this choice deterministic. Pass coloring="phase_identity" to color each deterministic representative by its qualified dataset_id:phase_id identity. At a numerical tie, either rendering uses the first phase in declared input order, while the source result’s complete stable_phase_mask remains unchanged.

Composition coloring uses a continuous colorbar. Phase-identity coloring is categorical and therefore uses a legend titled Stable phase containing only phases present in the evaluated domain. Both guides are returned as the third item from plot_phase_diagram(), so Python users can customize them with the normal Matplotlib interface. A selected colormap controls the phase swatches but does not change the categorical legend into a continuous colorbar.

Axis text comes only from each DiagramAxis label and unit. Optional axis inversion changes presentation only and does not mutate coordinates or thermodynamic results.

Thin black boundaries between differently rendered representative phases are enabled by default. They follow the cell edges of the same nearest-shaded representative field used for the colors, so phases with nonconsecutive internal indices remain unambiguous. boundary_color accepts a Matplotlib color, and boundary_linewidth sets its width in points. Pass boundary_color=None to draw only the colored mesh. These are presentation choices: boundary construction neither changes the energy tensor nor discards the complete tie-preserving stability mask.

surface_pd.plot.plot_phase_diagram(result: PhaseDiagramResult, *, coloring: CompositionColoring | Literal['phase_identity'] | None = None, ax: Axes | None = None, cmap: str | None = None, invert_x_axis: bool = False, invert_y_axis: bool = False, boundary_color: tuple[float, float, float] | str | tuple[float, float, float, float] | tuple[tuple[float, float, float] | str, float] | tuple[tuple[float, float, float, float], float] | None = 'black', boundary_linewidth: float = 1.0) → tuple[Figure, Axes, Colorbar | Legend][source]

Render an already evaluated generalized phase diagram.

Parameters:

result (PhaseDiagramResult) – Complete numerical result. Rendering does not reevaluate it.
coloring (CompositionColoring, {"phase_identity"}, or None, optional) – Explicit continuous composition scale. None uses the atomic fraction of the first independent component. "phase_identity" uses discrete qualified phase identities.
ax (matplotlib.axes.Axes or None, optional) – Existing axes to draw into. New figure and axes are created when omitted.
cmap (str or None, optional) – Matplotlib colormap name. Defaults to "tab20" for phase identity and "viridis" for composition values.
invert_x_axis (bool, optional) – If true, present the x-axis in decreasing screen order.
invert_y_axis (bool, optional) – If true, present the y-axis in decreasing screen order.
boundary_color (color-like or None, optional) – Matplotlib color for boundaries between representative stable phases. Defaults to black. None disables the boundary overlay.
boundary_linewidth (float, optional) – Positive finite phase-boundary width in points. This option is ignored when boundary_color is None.

Returns:

Matplotlib (figure, axes, color_guide) objects. The color guide is a categorical matplotlib.legend.Legend for phase-identity coloring and a continuous matplotlib.colorbar.Colorbar for composition coloring. The function neither displays nor saves the figure.

Return type:

tuple

Explicit composition coloring

CompositionColoring supports two explicit, chemistry-independent normalizations. Atomic-fraction coloring uses

\[x_i = \frac{n_i}{\sum_j n_j},\]

where the denominator includes every component in the phase basis. Component-ratio coloring instead uses

\[r_{i/k} = \frac{n_i}{n_k},\]

where both numerator component \(i\) and denominator component \(k\) are named by the user. A zero denominator is rejected. The renderer never infers a host species, transition metal, occupancy scale, or grouping from row positions.

The named constructors keep common Python calls concise:

li_fraction = CompositionColoring.atomic_fraction("Li")
oxygen_fraction = CompositionColoring.atomic_fraction("O")
li_per_ni = CompositionColoring.component_ratio("Li", "Ni")

Custom labels remain available through the constructors or full dataclass initialization. Atomic fraction is the general default because it requires no inferred host component. A component ratio is preferable when the user has an explicit, scientifically justified invariant reference such as Ni.

Composition coloring follows the same first-in-order representative policy at ties. The numerical result continues to retain all co-stable phases and the complete energy tensor.

class surface_pd.plot.CompositionColoring(component: str, normalization: Literal['atomic_fraction', 'component_ratio'], reference_component: str | None, label: str, unit: str)[source]

Define an explicit phase-composition color scale.

Parameters:

component (str) – Composition component used as the numerator.
normalization ({"atomic_fraction", "component_ratio"}) – "atomic_fraction" calculates the component count divided by the sum of all component counts. "component_ratio" divides by the explicitly selected reference_component count.
reference_component (str or None) – Denominator component for "component_ratio"; it must be None for "atomic_fraction".
label (str) – Nonempty, single-line colorbar label without units.
unit (str) – Nonempty, single-line display unit.

classmethod atomic_fraction(component: str, *, label: str | None = None) → CompositionColoring[source]: Return atomic-fraction coloring for one explicit component.

classmethod component_ratio(component: str, reference_component: str, *, label: str | None = None) → CompositionColoring[source]: Return component-ratio coloring for an explicit numerator pair.

phase_values(result: PhaseDiagramResult) → ndarray[source]

Return one composition value per phase in result order.

Parameters:: result (PhaseDiagramResult) – Numerical diagram whose candidate phase compositions are used.
Returns:: Read-only values in the same order as result.phase_ids.
Return type:: numpy.ndarray