arc.plotter

A module for plotting and saving output files such as RMG libraries.

arc.plotter.augment_arkane_yml_file_with_mol_repr(species: ARCSpecies, output_directory: str) → None

Add a Molecule representation to an Arkane YAML file.

Parameters:

• species (ARCSpecies) – The species to process.

• output_directory (str) – The base path to the project’s output directory.

arc.plotter.auto_label(rects, ts_results, ax)

Attach a text label above each bar in rects, displaying its height.

arc.plotter.check_xyz_species_for_drawing(xyz=None, species=None)

A helper function for checking the coordinates before drawing them. Either xyz or species must be given. If both are given, xyz gets precedence. If species is given, xys will be taken from it or cheaply generated for it.

Parameters:

• xyz (dict, str, optional) – The 3D coordinates in any form.

• species (ARCSpecies, optional) – A species to take the coordinates from.

Raises:

• InputError – If neither xyz nor species are given.

• TypeError – If species is of wrong type.

Returns: dict

The coordinates to plot.

arc.plotter.clean_scan_results(results: dict) → dict

Filter noise of high energy points if the value distribution is such that removing the top 10% points results in values which are significantly lower. Useful for scanning methods which occasionally give extremely high energies by mistake.

Parameters:

results (dict) – The directed snan results dictionary. Keys are dihedral tuples, values are energies.

Returns:

A filtered results dictionary.

Return type:

dict

arc.plotter.delete_multi_species_output_file(species_list: List[ARCSpecies], label: str, multi_species_path_dict: dict)

Delete all the individual multi species output file sliced fromthe the big cluster output file.

Parameters:

• species_list – The species list to be processed.

• label (str) – The multi_species label.

• multi_species_path – The dict of all the paths to the relevant species.

arc.plotter.draw_3d(xyz=None, species=None, project_directory=None, save_only=False)

Draws the molecule in a “3D-balls” style. Saves an image if a species and project_directory are provided.

Parameters:

• xyz (str, dict, optional) – The coordinates to display.

• species (ARCSpecies, optional) – xyz coordinates will be taken from the species.

• project_directory (str) – ARC’s project directory to save the image in.

• save_only (bool) – Whether to only save an image without plotting it, True to only save.

arc.plotter.draw_kinetics_plots(rxn_list, T_min, T_max, T_count=50, path=None)

Draws plots of calculated rate coefficients and RMG’s estimates. rxn_list has a .kinetics attribute calculated by ARC and an .rmg_reactions list with RMG rates.

Parameters:

• rxn_list (list) – Reactions with a .kinetics attribute calculated by ARC and an .rmg_reactions list with RMG rates.

• T_min (tuple) – The minimum temperature to consider, e.g., (500, ‘K’).

• T_max (tuple) – The maximum temperature to consider, e.g., (3000, ‘K’).

• T_count (int, optional) – The number of temperature points between T_min and T_max.

• path (str, optional) – The path to the project’s output folder.

arc.plotter.draw_parity_plot(var_arc, var_rmg, labels, var_label, var_units, pp=None)

Draw a parity plot.

Parameters:

• var_arc (list) – The variable calculated by ARC.

• var_rmg (list) – The variable estimated by RMG.

• labels (list) – Species labels corresponding to the data in var_arc and var_rmg.

• var_label (str) – The variable name.

• var_units (str) – The variable units.

• pp (PdfPages, optional) – Used for storing the image as a multi-page PFD file.

arc.plotter.draw_structure(xyz=None, species=None, project_directory=None, method='show_sticks', show_atom_indices=False)

A helper function for drawing a molecular structure using either show_sticks or draw_3d.

Parameters:

• xyz (str, optional) – The xyz coordinates to plot in string format.

• species (ARCSpecies, optional) – A species from which to extract the xyz coordinates to plot.

• project_directory (str, optional) – A directory for saving the image (only supported for draw_3d).

• method (str, optional) – The method to use, either ‘show_sticks’, ‘draw_3d’, or ‘scatter’.

• show_atom_indices (bool) – whether to display atom indices on the 3D image.

arc.plotter.draw_thermo_parity_plots(species_list: list, path: Optional[str] = None)

Draws parity plots of calculated thermo and RMG’s estimates. Saves a thermo.info file if a path is specified.

Parameters:

• species_list (list) – Species to compare.

• path (str, optional) – The path to the project’s output folder.

arc.plotter.get_text_positions(x_data, y_data, txt_width, txt_height)

Get the positions of plot annotations to avoid overlapping. Source: stackoverflow.

arc.plotter.log_bde_report(path, bde_report, spc_dict)

Prettify the report for bond dissociation energies. Log and save to file.

Parameters:

• path (str) – The file path.

• bde_report (dict) – The BDE report dictionary. Keys are species labels, values are species BDE dictionaries. In the second level dict, keys are pivot tuples, values are energies in kJ/mol.

• spc_dict (dict) – The species dictionary.

arc.plotter.log_kinetics(label, path)

Logging kinetics from an Arkane output file.

Parameters:

• label (str) – The species label.

• path (str) – The path to the folder containing the relevant Arkane output file.

arc.plotter.log_thermo(label, path)

Logging thermodata from an Arkane output file.

Parameters:

• label (str) – The species label.

• path (str) – The path to the folder containing the relevant Arkane output file.

arc.plotter.make_multi_species_output_file(species_list: List[ARCSpecies], label: str, path: str, software: Optional[str] = 'gaussian') → dict

Slice the big cluster output file down to individual multi species output file.

Parameters:

• species_list – The species list to be processed.

• label (str) – The multi_species label.

• path – The path to the job object.

• software – The software used for the calculation.

Returns:

path to each of the individual species.

Return type:

dict

arc.plotter.plot_1d_rotor_scan(angles: Optional[Union[list, tuple, array]] = None, energies: Optional[Union[list, tuple, array]] = None, results: Optional[dict] = None, path: Optional[str] = None, scan: Optional[Union[list, tuple]] = None, comment: str = '', units: str = 'degrees', original_dihedral: Optional[float] = None, label=None)

Plots a 1D rotor PES for energy vs. angles. Either angles and energies or results must be given.

Parameters:

• angles (Union[list, tuple, np.array], optional) – Dihedral angles.

• energies (Union[list, tuple, np.array], optional) – The energies in kJ/mol.

• results (dict, optional) – The results dictionary, dihedrals are assumed to be in degrees (not radians).

• path (str, optional) – The folder path for saving the rotor scan image and comments.

• scan (Union[list, tuple], optional) – The pivotal atoms of the scan.

• comment (str, optional) – Reason for invalidating this rotor.

• units (str, optional) – The angle units, either ‘degrees’ or ‘radians’.

• original_dihedral (float, optional) – The actual dihedral angle of this torsion before the scan.

• label (str, optional) – The species label.

Raises:

InputError – If neither angles` and energies nor results were given.

arc.plotter.plot_2d_rotor_scan(results: dict, path: Optional[str] = None, label: str = '', cmap: str = 'Blues', resolution: int = 90, mark_lowest_conformations: bool = False, original_dihedrals: Optional[List[float]] = None)

Plot a 2D rotor scan.

Parameters:

• results (dict) –

  The results dictionary, dihedrals are assumed to be in degrees (not radians). This dictionary has the following structure:

  {'directed_scan_type': <str, used for the fig name>,
   'scans': <list, entries are lists of torsion indices>,
   'directed_scan': <dict>, keys are tuples of '{0:.2f}' formatted dihedrals,
                    values are dictionaries with the following keys and values:
                    {'energy': <float, energy in kJ/mol>,  # only this is used here
                     'xyz': <dict>,
                     'is_isomorphic': <bool>,
                     'trsh': <list, job.ess_trsh_methods>}>,
  }
  

• path (str, optional) – The folder path to save this 2D image.

• label (str, optional) – The species label.

• cmap (str, optional) – The color map to use. See optional arguments below.

• resolution (int, optional) – The image resolution to produce.

• mark_lowest_conformations (bool, optional) – Whether to add a marker at the lowest conformers. True to add, default is True.

• original_dihedrals (list, optional) – Entries are dihedral degrees of the conformer used for the scan. If given, the conformer will be marked on the plot with a red dot.

Raises:

• TypeError – If results if of wrong type.

• InputError – If results does not represent a 2D rotor.

Optional arguments for cmap:

Accent, Accent_r, Blues, Blues_r, BrBG, BrBG_r, BuGn, BuGn_r, BuPu, BuPu_r, CMRmap, CMRmap_r, Dark2, Dark2_r,
GnBu, GnBu_r, Greens, Greens_r, Greys, Greys_r, OrRd, OrRd_r, Oranges, Oranges_r, PRGn, PRGn_r, Paired,
Paired_r, Pastel1, Pastel1_r, Pastel2, Pastel2_r, PiYG, PiYG_r, PuBu, PuBuGn, PuBuGn_r, PuBu_r, PuOr, PuOr_r,
PuRd, PuRd_r, Purples, Purples_r, RdBu, RdBu_r, RdGy, RdGy_r, RdPu, RdPu_r, RdYlBu, RdYlBu_r, RdYlGn, RdYlGn_r,
Reds, Reds_r, Set1, Set1_r, Set2, Set2_r, Set3, Set3_r, Spectral, Spectral_r, Wistia, Wistia_r, YlGn, YlGnBu,
YlGnBu_r, YlGn_r, YlOrBr, YlOrBr_r, YlOrRd, YlOrRd_r, afmhot, afmhot_r, autumn, autumn_r, binary, binary_r,
bone, bone_r, brg, brg_r, bwr, bwr_r, cividis, cividis_r, cool, cool_r, coolwarm, coolwarm_r, copper, copper_r,
cubehelix, cubehelix_r, flag, flag_r, gist_earth, gist_earth_r, gist_gray, gist_gray_r, gist_heat, gist_heat_r,
gist_ncar, gist_ncar_r, gist_rainbow, gist_rainbow_r, gist_stern, gist_stern_r, gist_yarg, gist_yarg_r, gnuplot,
gnuplot2, gnuplot2_r, gnuplot_r, gray, gray_r, hot, hot_r, hsv, hsv_r, inferno, inferno_r, jet, jet_r, magma,
magma_r, nipy_spectral, nipy_spectral_r, ocean, ocean_r, pink, pink_r, plasma, plasma_r, prism, prism_r,
rainbow, rainbow_r, seismic, seismic_r, spring, spring_r, summer, summer_r, tab10, tab10_r, tab20, tab20_r,
tab20b, tab20b_r, tab20c, tab20c_r, terrain, terrain_r, viridis, viridis_r, winter, winter_r

arc.plotter.plot_2d_scan_bond_dihedral(results: dict, path: Optional[str] = None, label: str = '', cmap: str = 'Blues', resolution: int = 90, font_size: float = 15, figsize: Tuple[float, float] = (12, 8), original_dihedrals: Optional[List[float]] = None)

Plot a 2D scan where one coordinate is bond length and another is a dihedral angle.

Parameters:

• results (dict) –

  The results dictionary, dihedrals are assumed to be in degrees (not radians). This dictionary has the following structure:

  {'directed_scan_type': <str, used for the fig name>,
   'scans': <list, entries are lists of torsion indices>,
   'directed_scan': <dict>, keys are tuples of '{0:.2f}' formatted dihedrals,
                    values are dictionaries with the following keys and values:
                    {'energy': <float, energy in kJ/mol>,  # only this is used here
                     'xyz': <dict>,
                     'is_isomorphic': <bool>,
                     'trsh': <list, job.ess_trsh_methods>}>,
  }
  

• path (str, optional) – The folder path to save this 2D image.

• label (str, optional) – The species label.

• cmap (str, optional) – The color map to use. See optional arguments below.

• resolution (int, optional) – The image resolution to produce.

• font_size (float, optional) – The sfont size for the figure.

• figsize (tuple, optional) – The size (width, height) of the resulting figure.

• original_dihedrals (list, optional) – Entries are dihedral degrees of the conformer used for the scan. If given, the conformer will be marked on the plot with a red dot.

Raises:

• TypeError – If results if of wrong type.

• InputError – If results does not represent a 2D rotor.

Optional arguments for cmap::

Accent, Accent_r, Blues, Blues_r, BrBG, BrBG_r, BuGn, BuGn_r, BuPu, BuPu_r, CMRmap, CMRmap_r, Dark2, Dark2_r, GnBu, GnBu_r, Greens, Greens_r, Greys, Greys_r, OrRd, OrRd_r, Oranges, Oranges_r, PRGn, PRGn_r, Paired, Paired_r, Pastel1, Pastel1_r, Pastel2, Pastel2_r, PiYG, PiYG_r, PuBu, PuBuGn, PuBuGn_r, PuBu_r, PuOr, PuOr_r, PuRd, PuRd_r, Purples, Purples_r, RdBu, RdBu_r, RdGy, RdGy_r, RdPu, RdPu_r, RdYlBu, RdYlBu_r, RdYlGn, RdYlGn_r, Reds, Reds_r, Set1, Set1_r, Set2, Set2_r, Set3, Set3_r, Spectral, Spectral_r, Wistia, Wistia_r, YlGn, YlGnBu, YlGnBu_r, YlGn_r, YlOrBr, YlOrBr_r, YlOrRd, YlOrRd_r, afmhot, afmhot_r, autumn, autumn_r, binary, binary_r, bone, bone_r, brg, brg_r, bwr, bwr_r, cividis, cividis_r, cool, cool_r, coolwarm, coolwarm_r, copper, copper_r, cubehelix, cubehelix_r, flag, flag_r, gist_earth, gist_earth_r, gist_gray, gist_gray_r, gist_heat, gist_heat_r, gist_ncar, gist_ncar_r, gist_rainbow, gist_rainbow_r, gist_stern, gist_stern_r, gist_yarg, gist_yarg_r, gnuplot, gnuplot2, gnuplot2_r, gnuplot_r, gray, gray_r, hot, hot_r, hsv, hsv_r, inferno, inferno_r, jet, jet_r, magma, magma_r, nipy_spectral, nipy_spectral_r, ocean, ocean_r, pink, pink_r, plasma, plasma_r, prism, prism_r, rainbow, rainbow_r, seismic, seismic_r, spring, spring_r, summer, summer_r, tab10, tab10_r, tab20, tab20_r, tab20b, tab20b_r, tab20c, tab20c_r, terrain, terrain_r, viridis, viridis_r, winter, winter_r

arc.plotter.plot_3d_mol_as_scatter(xyz, path=None, plot_h=True, show_plot=True, name='', index=0)

Draws the molecule as scattered balls in space according to the supplied xyz coordinates.

Parameters:

• xyz (dict, str) – The xyz coordinates.

• path (str, optional) – A directory path to save the generated figure in.

• plot_h (bool, optional) – Whether to plot hydrogen atoms as well. True to plot them.

• show_plot (bool, optional) – Whether to show the plot. True to show.

• name (str, optional) – A name to be added to the saved file name.

• index (int, optional) – The index type (0 or 1) for printing atom numbers. Pass None to avoid printing numbers.

arc.plotter.plot_torsion_angles(torsion_angles, torsions_sampling_points=None, wells_dict=None, e_conformers=None, de_threshold=5.0, plot_path=None)

Plot the torsion angles of the generated conformers.

Parameters:

• torsion_angles (dict) – Keys are torsions, values are lists of corresponding angles.

• torsions_sampling_points (dict, optional) – Keys are torsions, values are sampling points.

• wells_dict (dict, optional) – Keys are torsions, values are lists of wells. Each entry in such a list is a well dictionary with the following keys: start_idx, end_idx, start_angle, end_angle, and angles.

• e_conformers (list, optional) – Entries are conformers corresponding to the sampling points with FF energies.

• de_threshold (float, optional) – Energy threshold, plotted as a dashed horizontal line.

• plot_path (str, optional) – The path for saving the plot.

arc.plotter.plot_ts_guesses_by_e_and_method(species: ARCSpecies, path: str)

Save a figure comparing all TS guesses by electronic energy and imaginary frequency.

Parameters:

• species (ARCSpecies) – The TS Species to consider.

• path (str) – The path for saving the figure.

arc.plotter.save_conformers_file(project_directory: str, label: str, xyzs: List[dict], level_of_theory: Union[Level, str], multiplicity: Optional[int] = None, charge: Optional[int] = None, is_ts: bool = False, energies: Optional[List[float]] = None, ts_methods: Optional[List[str]] = None, im_freqs: Optional[List[List[float]]] = None, log_content: bool = False, before_optimization: bool = True, sp_flag=False)

Save the conformers before or after optimization. If energies are given, the conformers are considered to be optimized.

Parameters:

• project_directory (str) – The path to the project’s directory.

• label (str) – The species label.

• xyzs (list) – Entries are dict-format xyz coordinates of conformers.

• level_of_theory (Union[Level, str]) – The level of theory used for the conformers’ optimization.

• multiplicity (int, optional) – The species multiplicity, used for perceiving the molecule.

• charge (int, optional) – The species charge, used for perceiving the molecule.

• is_ts (bool, optional) – Whether the species represents a TS. True if it does.

• energies (list, optional) – Entries are energies corresponding to the conformer list in kJ/mol. If not given (None) then the Species.conformer_energies are used instead.

• ts_methods (list, optional) – Entries are method names used to generate the TS guess.

• im_freqs (list, optional) – Entries lists of imaginary frequencies.

• log_content (bool) – Whether to log the content of the conformers file. True to log, default is False.

• before_optimization (bool) – Whether the conformers are before DFT optimization. True for before, default is True.

• sp_flag (bool) – Whether the conformers are single point calculations. True for single point, default is False.

arc.plotter.save_geo(species: Optional[ARCSpecies] = None, xyz: Optional[dict] = None, project_directory: Optional[str] = None, path: Optional[str] = None, filename: Optional[str] = None, format_: str = 'all', comment: Optional[str] = None)

Save a geometry file. If species is given, .final_xyz will be saved if it is not None, otherwise .initial_xyz will be used. If xyz is given, it gets precedence over species. Either species or xyz must be specified. Either project_directory or path must be specified.

Parameters:

• species (ARCSpecies) – The species with the geometry attributes.

• xyz (dict, optional) – The xyz coordinates to save in a string format.

• project_directory (str, optional) – The project directory where the species folder is located.

• path (str, optional) – A specific directory path for saving the files.

• filename (str, optional) – A name for the file to save (without suffix).

• format (str, optional) – The format to save. Either ‘xyz’, ‘gjf’ or ‘all’ for both.

• comment (str, optional) – A comment to be stored in the XYZ file after the number of atoms line.

Raises:

InputError – If neither species nor xyz were given. Or if neither project_directory nor path were given.

arc.plotter.save_irc_traj_animation(irc_f_path, irc_r_path, out_path)

Save an IRC trajectory animation file showing the entire reaction coordinate.

Parameters:

• irc_f_path (str) – The forward IRC computation.

• irc_r_path (str) – The reverse IRC computation.

• out_path (str) – The path to the output file.

arc.plotter.save_kinetics_lib(rxn_list, path, name, lib_long_desc)

Save an RMG kinetics library of all reactions in rxn_list in the supplied path. rxn_list is a list of ARCReaction objects. name is the library’s name (or project’s name). long_desc is a multiline string with level of theory description.

arc.plotter.save_nd_rotor_yaml(results, path)

Save a text file summarizing a rotor scan, useful for brute force scans.

Parameters:

• results (dict) – The respective scan dictionary to save.

• path (str) – The path of the file to be saved.

arc.plotter.save_rotor_text_file(angles, energies, path)

Save a text file summarizing a rotor scan, useful for brute force scans.

Parameters:

• angles (list) – The dihedral angles in degrees.

• energies (list) – The respective scan energies in kJ/mol.

• path (str) – The path of the file to be saved.

Raises:

InputError – If energies and angles are not the same length.

arc.plotter.save_thermo_lib(species_list: list, path: str, name: str, lib_long_desc: str) → None

Save an RMG thermo library of all species

Parameters:

• species_list (list) – Entries are ARCSpecies objects to be saved in the library.

• path (str) – The file path where the library should be created.

• name (str) – The library’s name (or project’s name).

• lib_long_desc (str) – A multiline string with level of theory description.

arc.plotter.save_transport_lib(species_list, path, name, lib_long_desc='')

Save an RMG transport library of all species in species_list in the supplied path. name is the library’s name (or project’s name). long_desc is a multiline string with level of theory description.

arc.plotter.show_sticks(xyz=None, species=None, project_directory=None, show_atom_indices=False)

Draws the molecule in a “sticks” style according to the supplied xyz coordinates. Returns whether successful of not. If successful, saves the image using draw_3d. Either xyz or species must be specified.

Parameters:

• xyz (str, dict, optional) – The coordinates to display.

• species (ARCSpecies, optional) – xyz coordinates will be taken from the species.

• project_directory (str) – ARC’s project directory to save a draw_3d image in.

• show_atom_indices (bool) – whether to display atom indices on the 3D image.

Returns: bool

Whether the show_sticks drawing was successful. True if it was.

arc.plotter.text_plotter(x_data, y_data, labels, text_positions, axis, txt_width, txt_height)

Annotate a plot and add an arrow. Source: stackoverflow.