shakenbreak.plotting module

Module containing functions to plot distorted defect relaxation outputs and identify energy-lowering distortions.

The main plotting functions are:

shakenbreak.plotting.plot_all_defects(defect_charges_dict: dict, output_path: str = '.', add_colorbar: bool = False, metric: str = 'max_dist', max_energy_above_unperturbed: float = 0.5, units: str = 'eV', min_e_diff: float = 0.05, line_color: str | None = None, add_title: bool | None = True, save_plot: bool = True, save_format: str = 'png', verbose: bool = False, close_figures: bool = False) → dict

Convenience function to quickly analyse a range of defects and identify those which undergo energy-lowering distortions.

Parameters:

• defect_charges_dict (dict) – Dictionary matching defect names to lists of their charge states. (e.g {“Int_Sb_1”: [0,+1,+2]} etc)

• output_path (str) – Path to top-level directory with your distorted defect calculations and distortion_metadata.json file. (Default: current directory)

• add_colorbar (bool) – Whether to add a colorbar indicating structural similarity between each structure and the unperturbed one. (Default: False)

• metric (str) – If add_colorbar is set to True, metric defines the criteria for structural comparison. Can choose between root-mean-squared displacement for all sites (‘disp’) or the maximum distance between matched sites (‘max_dist’, default). (Default: “max_dist”)

• max_energy_above_unperturbed (float) – Maximum energy (in chosen units), relative to the unperturbed structure, to show on the plot. (Default: 0.5 eV)

• units (str) – Units for energy, either “eV” or “meV”. (Default: “eV”)

• min_e_diff (float) – Minimum energy difference (in eV) between the ground-state defect structure and the Unperturbed structure to generate the distortion plot. (Default: 0.05 eV)

• line_color (str) – Color of the line connecting points. (Default: ShakeNBreak base style)

• add_title (bool) – Whether to add a title to the plot. By default, the title is the formatted defect name (i.e. V$_{Cd}^{0}$). (Default: True)

• save_plot (bool) – Whether to plot the results or not. (Default: True)

• save_format (str) – Format to save the plot as. (Default: ‘png’)

• verbose (bool) – Whether to print information about the plots (warnings and where they’re saved).

• close_figures (bool) – Whether to close matplotlib figures after saving them, to reduce memory usage. Recommended to use if plotting many defects at once, in which case figures will be saved to disk and not displayed. (Default: False)

Returns:

Dictionary of {Defect Species (Name & Charge): Energy vs Distortion Plot}

Return type:

dict

shakenbreak.plotting.plot_defect(defect_species: str, energies_dict: dict, output_path: str | None = '.', neighbour_atom: str | None = None, num_nearest_neighbours: int | None = None, add_colorbar: bool | None = False, metric: str | None = 'max_dist', max_energy_above_unperturbed: float | None = 0.5, include_site_info_in_name: bool | None = False, y_label: str | None = 'Energy (eV)', add_title: bool | None = True, line_color: str | None = None, units: str | None = 'eV', save_plot: bool | None = True, save_format: str | None = 'png', verbose: bool = False, close_figure: bool = False) → Figure | None

Convenience function to plot energy vs distortion for a defect, to identify any energy-lowering distortions.

Parameters:

• defect_species (str) – Defect name including charge (e.g. ‘vac_1_Cd_0’)

• energies_dict (dict) – Dictionary matching distortion to final energy (eV), as produced by _organize_data() or analysis.get_energies())

• output_path (str) – Path to top-level directory with your distorted defect calculations (to calculate structure comparisons and save plots) (Default: current directory)

• neighbour_atom (str) – Name(s) of distorted neighbour atoms (e.g. ‘Cd’). If not specified, will be parsed from distortion_metadata.json file. (Default: None)

• num_nearest_neighbours (int) – Number of distorted neighbour atoms (e.g. 2). If not specified, will be parsed from distortion_metadata.json file. (Default: None)

• add_colorbar (bool) – Whether to add a colorbar indicating structural similarity between each structure and the unperturbed one. (Default: False)

• metric (str) – If add_colorbar is True, determines the criteria used for the structural comparison. Can choose between the summed of atomic displacements (‘disp’) or the maximum distance between matched sites (‘max_dist’, default). (Default: “max_dist”)

• max_energy_above_unperturbed (float) – Maximum energy (in chosen units), relative to the unperturbed structure, to show on the plot. (Default: 0.5 eV)

• units (str) – Units for energy, either “eV” or “meV”. (Default: “eV”)

• include_site_info_in_name (bool) – Whether to include the site info (i.e. point group symbol and possibly nearest neighbour info, as generated by doped) in the defect name. Useful for materials with many symmetry-inequivalent sites. (Default: False)

• y_label (str) – Y axis label (Default: “Energy (eV)”)

• add_title (bool) – Whether to add a title to the plot. By default, the title is the formatted defect name (i.e. V$_{Cd}^{0}$). (Default: True)

• line_color (str) – Color of the line connecting points. (Default: ShakeNBreak base style)

• save_plot (bool) – Whether to save the plot as an SVG file. (Default: True)

• save_format (str) – Format to save the plot as. (Default: “png”)

• verbose (bool) – Whether to print information about the plot (warnings and where it’s saved).

• close_figure (bool) – Whether to close matplotlib figure after saving, to reduce memory usage. Recommended to use if plotting many defects at once, in which case figure will be saved to disk and not displayed. (Default: False)

Returns:

Energy vs distortion plot, as a mpl.figure.Figure object

Return type:

mpl.figure.Figure

Which rely on:

shakenbreak.plotting.plot_colorbar(energies_dict: dict, disp_dict: dict, defect_species: str, include_site_info_in_name: bool | None = False, num_nearest_neighbours: int | None = None, neighbour_atom: str = 'NN', title: str | None = None, legend_label: str = 'SnB', metric: str | None = 'max_dist', max_energy_above_unperturbed: float | None = 0.5, save_plot: bool | None = False, output_path: str | None = '.', y_label: str | None = 'Energy (eV)', line_color: str | None = None, save_format: str | None = 'png', verbose: bool | None = False) → Figure | None

Plot energy versus bond distortion, adding a colorbar to show structural similarity between different final configurations.

Parameters:

• energies_dict (dict) – Dictionary matching distortion to final energy (eV), as produced by analysis.get_energies() or analysis._organize_data().

• disp_dict (dict) – Dictionary matching bond distortions to structure comparison metric (metric = ‘disp’ or ‘max_dist’), as produced by analysis.calculate_struct_comparison().

• defect_species (str) –

  Specific defect name that will appear in plot labels (in LaTeX form)

  and file names (e.g ‘vac_1_Cd_0’)

• include_site_info_in_name (bool) – Whether to include the site info (i.e. point group symbol and possibly nearest neighbour info, as generated by doped) in the defect name. Useful for materials with many symmetry-inequivalent sites. (Default: False)

• num_nearest_neighbours (int) – Number of distorted neighbour atoms (e.g. 2) (Default: None)

• neighbour_atom (str, optional) – Name(s) of distorted neighbour atoms (e.g. ‘Cd’) (Default: “NN”)

• title (str, optional) – Plot title (Default: None)

• legend_label (str) – Label for plot legend (Default: ‘SnB’)

• metric (str) – Defines the criteria for structural comparison, used for the colorbar. Can choose between root-mean-squared displacement for all sites (‘disp’) or the maximum distance between matched sites (‘max_dist’, default). (Default: “max_dist”)

• max_energy_above_unperturbed (float) – Maximum energy (in chosen units), relative to the unperturbed structure, to show on the plot. (Default: 0.5 eV)

• line_color (str) – Color of the line conneting points. (Default: ShakeNBreak base style)

• save_plot (bool) – Whether to save the plot as an SVG file. (Default: True)

• output_path (str) – Path to top-level directory containing the defect directory (in which to save the plot). (Default: “.”)

• y_label (str) – Y axis label (Default: ‘Energy (eV)’)

• save_format (str) – Format to save the plot as. (Default: ‘png’)

• verbose (bool) – Whether to print information about the plot (warnings and where it’s saved).

Returns:

Energy vs distortion plot with colorbar for structural similarity, as a mpl.figure.Figure object

Return type:

mpl.figure.Figure

shakenbreak.plotting.plot_datasets(datasets: list, dataset_labels: list | None = None, defect_species: str = 'defect', include_site_info_in_name: bool | None = False, title: str | None = None, neighbour_atom: str | None = None, num_nearest_neighbours: int | None = None, max_energy_above_unperturbed: float | None = 0.5, y_label: str = 'Energy (eV)', markers: list | None = None, linestyles: list | None = None, colors: list | None = None, markersize: float | None = None, linewidth: float | None = None, save_plot: bool | None = False, output_path: str | None = '.', save_format: str | None = 'png', verbose: bool | None = True) → Figure

Generate energy versus bond distortion plots for multiple datasets.

Parameters:

• datasets (list) – List of {distortion: energy} dictionaries to plot (each dictionary matching distortion to final energy (eV), as produced by analysis._organize_data() or analysis.get_energies())

• dataset_labels (list) – Labels for each dataset plot legend. If None, defaults to [“Distortions”]*len(datasets).

• defect_species (str) –

  Specific defect name that will appear in plot labels (in LaTeX form)

  and file names (e.g ‘vac_1_Cd_0’). Defaults to ‘defect’.

• include_site_info_in_name (bool) – Whether to include the site info (i.e. point group symbol and possibly nearest neighbour info, as generated by doped) in the defect name. Useful for materials with many symmetry-inequivalent sites. (Default: False)

• neighbour_atom (str) – Name(s) of distorted neighbour atoms (e.g. ‘Cd’)

• title (str, optional) – Plot title (Default: None)

• num_nearest_neighbours (int) – Number of distorted neighbour atoms (e.g. 2)

• max_energy_above_unperturbed (float) – Maximum energy (in chosen units), relative to the unperturbed structure, to show on the plot. (Default: 0.5 eV)

• y_label (str) – Y axis label (Default: ‘Energy (eV)’)

• colors (list) – List of color codes to use for each dataset (e.g [“C1”, “C2”]) (Default: None)

• markers (list) – List of markers to use for each dataset (e.g [“o”, “d”]) (Default: None)

• linestyles (list) – List of line styles to use for each dataset (e.g [“-”, “-.”]) (Default: None)

• markersize (float) – Marker size to use for plots (single value, or list of values for each dataset) (Default: None)

• linewidth (float) – Linewidth to use for plots (single value, or list of values for each dataset) (Default: None)

• save_plot (bool) – Whether to save the plots. (Default: True)

• output_path (str) – Path to top-level directory containing the defect directory (in which to save the plot). (Default: “.”)

• save_format (str) – Format to save the plot as. (Default: ‘png’)

• verbose (bool) – Whether to print information about the plot (warnings and where it’s saved).

Returns:

Energy vs distortion plot for multiple datasets, as a mpl.figure.Figure object

Return type:

mpl.figure.Figure