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(defects_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 = True) → dict[source]#

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

Parameters:

  • defects_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).

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 = True) → Figure | None[source]#

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).

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 = True) → Figure | None[source]#

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[source]#

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