visualization

This module contains utility functions for visualization used across the package and which may be useful also for external applications.

clusterx.visualization.juview(plat, n=None)

Visualize structure object in Jupyter notebook

Parameters:
platany of Atoms(ASE), ParentLattice, Supercell, Structure, StructureSet

structure object to be plotted

nint or list of int

If integer, plot the first n structures. If list, plot range of structures. If None, return all structures.

Returns:
nglview display object
clusterx.visualization.plot_histograms_wang_landau(cdos_object, index=-1)

Plot histograms for Wang-Landau

clusterx.visualization.plot_optimization_vs_number_of_clusters(clsel, xmin=None, xmax=None, ymin=None, ymax=None, yfactor=1.0, show_yzero_axis=True, show_plot=True, save_plot=True, yaxis_label='Errors', fname='plot_optimization_vs_nclusters.png', data_fname=None)

Plot cluster optimization with matplotlib

The plot shows the prediction and fitting errors as a function of the clusters pool size resulting from a cluster optimization done with a ClustersSelector object.

The range of cluster pool sizes in the x-axis is determined by nclmin (minimum size) and nclmax (maximum size)

Parameters:
clselClustersSelector

The ClustersSelector oject which was used for the cluster optimization.

xminint, default None

Minimum cluster size in x-axis.

xmaxint, default None

Maximum cluster size in x-axis.

yfactorfloat, default 1.0

Multipliplicative factor for y-values. Useful to pass unit conversion factors.

scalefloat, default 1.0

Adjust this parameter to change font size, axes line width, and other details of the plot.

yaxis_labelstr, default “Errors”

Label for the y-axis of the plot

show_plotbool, default True

If True, show the plot in a new window.

save_plotbool, default True

If True, save the plot to file.

fnamestr, default “plot_optimization_vs_nclusters.png”

Filepath to save the plot at.

clusterx.visualization.plot_optimization_vs_sparsity(clsel, xmin=None, xmax=None, ymin=None, ymax=None, xaxis_label='Sparsity', yaxis_label='Energy [arb. units]', show_plot: bool = True, save_plot: bool = True, fname='plot_optimization_vs_sparsity.png')

Plot cluster optimization with matplotlib

The plot shows the prediction and fitting errors as a function of the sparsity parameter when the LASSO method is used.

Parameters:
clselClustersSelector

The ClustersSelector oject which was used for the optimization to be plotted.

show_plotbool, default True

If True, show the plot in a new window.

save_plotbool, default True

If True, save the plot to file.

fnamestr, default “plot_optimization_vs_sparsity.png”

Filepath to save the plot at.

clusterx.visualization.plot_predictions_vs_target(sset: StructuresSet, cemodel: Model, prop_name: str, scale: float = 1.0, xaxis_label: str = 'Calculated energy [arb. units]', yaxis_label: str = 'Predicted energy [arb. units]', show_plot: bool = True, save_plot: bool = True, fname: str = 'plot_predictions_vs_target.png')

Plot predictions versus target with matplotlib

The plot shows the prediction versus the target

Parameters:
ssetStructuresSet
cemodelModel
prop_name

name of the property to be plotted. Must be present in sset, and, if cemodel is for multiple properties, must match one of the properties in cemodel.property_name

show_plotbool, default True

If True, show the plot in a new window.

save_plotbool, default True

If True, save the plot to file.

fnamestr, default “plot_predictions_vs_target.png”

Filepath to save the plot at.

clusterx.visualization.plot_property(xvalues, yvalues, prop_name=None, xaxis_label=None, yaxis_label=None, show_plot=True, save_plot=False, scale=1.0)

yvalues versus xvalues

clusterx.visualization.plot_property_persistent(xvalues, yvalues, prop_name=None, xaxis_label=None, yaxis_label=None, show_plot=True, scale=1.0)

Persistent, updating plot of yvalues versus xvalues.

clusterx.visualization.plot_property_vs_concentration(sset: StructuresSet, property_name: str, site_type: int = 0, sigma: int = 1, cemodel: Model | None = None, show_loo_predictions: bool = True, sset_enum: StructuresSet | None = None, properties_enum: ndarray | None = None, concentrations_enum: ndarray | None = None, sset_gss: StructuresSet | None = None, show_plot: bool = True, save_plot: bool = True, refs: List[float] | NDArray[float64] = [0.0, 0.0], yaxis_label: str | None = None, ymin: float | None = None, ymax: float | None = None, show_yzero_axis: bool = True, data_fname: str | None = None, fname: str = 'property_vs_concentration.png') → Dict[str, ndarray | str]

Plot property values versus concentration and return dictionary with data

The call to this functions generates a plot with matplotlib. It also returns a dictionary with the data used to generate the plot. This is useful in the case that the user wants to format the plot in a different way, or to write the data to a file for postprocessing (in the case that only the data is neeed, set show_plot to False).

Parameters:
ssetStructuresSet

The property values will be plotted for structures in sset.

property_namestr

The calculated property property_name will be extracted from the sset and depicted in the plot. If cemodel is not None as well, then both predicted and calculated data are plot.

site_typeint

The x axis of the plot will indicate the fractional concentration for site type site_type

sigmaint

The x axis of the plot will indicate the fractional concentration for the atomic species sigma in site type site_type

cemodelModel

If not None, the property values as predicted by cemodel will be depicted.

refs1D Array containing two float, default None

the values of a reference energy at concentrations 0 and 1.

show_loo_predictionsbool

If true, show predicted properties corresponding to leave-one-out CV. That is, the predictions for the left-out samples in the CV procedure are also plotted.

show_plotbool, default True

If True, show the plot in a new window.

save_plotbool, default True

If True, save the plot to file.

fnamestr, default “property_vs_concentration.png”

Filepath to save the plot at.

Returns:
dict

Returns a dictionary with the data used to build the plot, with the following elements:

  • data["concentration"]: Array of floats. The x-axis of the plot, containing the concentration of the substitutional species.

  • data["property"]: Array of floats, same lenght as data["concentration"]. Contains the values returned by sset.get_property_values(property_name = property_name).

  • data["predicted-property"]: The prediced properties with cemodel.

  • data["predicted-property-cv"]: The prediced properties with cemodel on CV.

  • data["concentration-enum"]: Concentrations for enumeration.

  • data["predicted-property-enum"]: Predicted values for enumeration.

  • data["concentration-gss"]: Concentrations for ground-state search.

  • data["predicted-property-gss"]: Predicted values for ground-state-search.

Depending on the arguments to the call to plot_property_vs_concentration, some of the returned dictionary elements may be missing.