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: Optional[str] = None, add_title: Optional[bool] = 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: Optional[str] = '.', neighbour_atom: Optional[str] = None, num_nearest_neighbours: Optional[int] = None, add_colorbar: Optional[bool] = False, metric: Optional[str] = 'max_dist', max_energy_above_unperturbed: Optional[float] = 0.5, include_site_num_in_name: Optional[bool] = False, y_label: Optional[str] = 'Energy (eV)', add_title: Optional[bool] = True, line_color: Optional[str] = None, units: Optional[str] = 'eV', save_plot: Optional[bool] = True, save_format: Optional[str] = 'png', verbose: bool = True) Optional[Figure] [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_num_in_name (
bool
) – Whether to include the site number (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_num_in_name: Optional[bool] = False, num_nearest_neighbours: Optional[int] = None, neighbour_atom: str = 'NN', title: Optional[str] = None, legend_label: str = 'SnB', metric: Optional[str] = 'max_dist', max_energy_above_unperturbed: Optional[float] = 0.5, save_plot: Optional[bool] = False, output_path: Optional[str] = '.', y_label: Optional[str] = 'Energy (eV)', line_color: Optional[str] = None, save_format: Optional[str] = 'png', verbose: Optional[bool] = True) Optional[Figure] [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_num_in_name (
bool
) – Whether to include the site number (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, defect_species: str, include_site_num_in_name: Optional[bool] = False, title: Optional[str] = None, neighbour_atom: Optional[str] = None, num_nearest_neighbours: Optional[int] = None, max_energy_above_unperturbed: Optional[float] = 0.5, y_label: str = 'Energy (eV)', markers: Optional[list] = None, linestyles: Optional[list] = None, colors: Optional[list] = None, markersize: Optional[float] = None, linewidth: Optional[float] = None, save_plot: Optional[bool] = False, output_path: Optional[str] = '.', save_format: Optional[str] = 'png', verbose: Optional[bool] = 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.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_num_in_name (
bool
) – Whether to include the site number (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