pyfrag_plotter package#

Subpackages#

Submodules#

pyfrag_plotter.errors module#

exception pyfrag_plotter.errors.PyFragConfigError(message, key: str | None = None)[source]#

Bases: PyFragError

An error that occurs when the PyFrag configuration is invalid.

exception pyfrag_plotter.errors.PyFragConfigValidationError(message, key: str | None = None)[source]#

Bases: PyFragError

An error that occurs when the PyFrag config is invalid.

exception pyfrag_plotter.errors.PyFragError(message, key: str | None = None)[source]#

Bases: ValueError

exception pyfrag_plotter.errors.PyFragInputError(message, key: str | None = None)[source]#

Bases: ValueError

An error that occurs when the PyFrag input is invalid.

exception pyfrag_plotter.errors.PyFragInterpolationError(message, key: str | None = None)[source]#

Bases: PyFragError

An error that occurs when interpolating data.

exception pyfrag_plotter.errors.PyFragResultsObjectError(message, key: str | None = None)[source]#

Bases: PyFragError

An error that occurs when a PyFrag results object is invalid.

exception pyfrag_plotter.errors.PyFragResultsProcessingError(message, key: str | None = None)[source]#

Bases: PyFragError

An error that occurs when processing PyFrag results.

exception pyfrag_plotter.errors.PyFragResultsProcessingWarning(message, section: str)[source]#

Bases: Warning

An error that occurs when processing PyFrag results.

pyfrag_plotter.interpolate module#

Module that contains functions for interpolating data

pyfrag_plotter.interpolate.interpolate_data(input_data: PyFragResultsObject | DataFrame, irc_coord: str, point: float) → DataFrame[source]#

Interpolates data that can be in the format of a PyFragResultsObject or a pandas DataFrame.

This function takes input data in the format of a PyFragResultsObject or a pandas DataFrame and interpolates the data at a specified point along the x-axis.

Parameters:

  • input_data (Union[PyFragResultsObject, pd.DataFrame]) – The input data to interpolate.

  • irc_coord (str) – The name of the x-axis coordinate to interpolate along.

  • point (float) – The point along the x-axis to interpolate at.

Raises:

TypeError – If the input data is not a PyFragResultsObject or a pandas DataFrame.

Returns:

A pandas DataFrame containing the interpolated data.

Return type:

pandas DataFrame

pyfrag_plotter.interpolate.interpolate_plot(x_axis: ndarray, y_axis: ndarray, x_range: Sequence[float] | None = None) → Tuple[ndarray, BSpline] | Tuple[ndarray, ndarray][source]#

Interpolates the data to a finer grid for plotting purposes using the scipy spline library.

Parameters:

  • x_axis (np.ndarray) – The x-axis data to interpolate.

  • y_axis (np.ndarray) – The y-axis data to interpolate.

  • x_range (Optional[Sequence[float]], optional) – The range of x-axis values to interpolate over. Defaults to None.

Returns:

The interpolated x-axis and y-axis data.

Return type:

Tuple[np.ndarray, BSpline]

pyfrag_plotter.interpolate.remove_duplicate_x_values(x: ndarray, y: ndarray) → Tuple[ndarray, ndarray][source]#

Removes duplicate x-axis values from the input arrays.

Parameters:

  • x (np.ndarray) – The x-axis data.

  • y (np.ndarray) – The y-axis data.

Returns:

The modified x-axis and y-axis data with duplicates removed.

Return type:

Tuple[np.ndarray, np.ndarray]

pyfrag_plotter.processing_funcs module#

pyfrag_plotter.processing_funcs.process_results_file(df: DataFrame, trim_option: str | float | int | Sequence | None = None, trim_key: str | None = None, outlier_threshold: float | None = None) → DataFrame[source]#

Processes the results file data.

Parameters:

  • df – A pandas DataFrame containing the results file data.

  • trim_option – An optional argument specifying how to trim the data. Can be “max”, “min”, “x_limits”, or None.

  • trim_key – An optional argument specifying the key to use for trimming the data. Can be “EnergyTotal” or None.

  • outlier_threshold – An optional argument specifying the threshold for removing outliers. Can be a float or None.

Returns:

A pandas DataFrame containing the processed results file data.

Raises:

PyFragResultsProcessingError – If an error occurs during processing.

pyfrag_plotter.processing_funcs.remove_dispersion_term(df: DataFrame) → DataFrame[source]#

Removes the dispersion term from the dataframe if it is 0.0 everywhere.

This function takes a pandas DataFrame containing the results file data and removes the dispersion term if it is 0.0 everywhere. The function returns the modified DataFrame.

Parameters:

df (pd.DataFrame) – The DataFrame containing the results file data.

Returns:

The modified DataFrame without the dispersion term if it is 0.0 everywhere.

Return type:

pd.DataFrame

pyfrag_plotter.processing_funcs.remove_duplicate_x_values_dataframe(df: DataFrame) → DataFrame[source]#

Removes rows with duplicate x-axis values from a pandas DataFrame. This is necessary since otherwise the interpolation will fail.

Parameters:

  • df (pd.DataFrame) – The DataFrame to remove duplicates from.

  • x_axis_key (str) – The name of the column containing the x-axis values.

  • y_axis_key (str) – The name of the column containing the y-axis values.

Returns:

The modified DataFrame with duplicates removed.

Return type:

pd.DataFrame

pyfrag_plotter.processing_funcs.remove_outliers(df: DataFrame, outlier_threshold: float | None = None) → DataFrame[source]#

Removes outliers from the dataframe.

This function takes a pandas DataFrame containing the results file data and removes outliers from the dataframe. The function returns the modified DataFrame.

Parameters:

df (pd.DataFrame) – The DataFrame containing the results file data.

Returns:

The modified DataFrame without outliers.

Return type:

pd.DataFrame

pyfrag_plotter.processing_funcs.trim_data(df: DataFrame, trim_option: str | float | int | Sequence | None = None, trim_key: str | None = None) → DataFrame[source]#

‘Overloaded’ function to trim the dataframe based on the type of the trim_option.

This function trims the given dataframe based on the type of the trim_option. The trim_option is read from the configuration file and can be either a string (“min”, “max”), integer (IRC point), float (energy func), or a sequence (x_limits such as (1.0, 3.0))). The function returns the trimmed dataframe.

Parameters:

  • df (pd.DataFrame) – The dataframe to trim.

  • trim_parameter (Optional[Union[str, float, int]]) – The parameter to use for trimming. Defaults to None.

  • trim_key (Optional[str]) – The key to use for reading the trim_parameter from the configuration file. Defaults to None.

Raises:

PyFragResultsProcessingError – If the trim_option is not a valid type.

Returns:

The trimmed dataframe.

Return type:

pd.DataFrame

pyfrag_plotter.pyfrag_object module#

Module that combines the data from inputfile and outputfile into a PyFragResultsObject object

class pyfrag_plotter.pyfrag_object.AvailableTerms[source]#

Bases: object

Class containing the available terms for the PyFragResultsObject.

ANGLE = 'angle'#
BONDLENGTH = 'bondlength'#
DIHEDRAL = 'dihedral'#
DISP = 'Disp'#
ELSTAT = 'Elstat'#
ENERGY_TOTAL = 'EnergyTotal'#
FRAG1_STRAIN = 'frag1Strain'#
FRAG2_STRAIN = 'frag2Strain'#
INT = 'Int'#
IRREPOI = 'irrepOI'#
OI = 'OI'#
ORBITALENERGY = 'orbitalenergy'#
OVERLAP = 'overlap'#
PAULI = 'Pauli'#
POPULATION = 'population'#
STRAIN_TOTAL = 'StrainTotal'#
VDD = 'vdd'#
class pyfrag_plotter.pyfrag_object.BondAngle(atom1: int, atom2: int, bondangle: float)[source]#

Bases: object

Attrs class for the bond angle property containing the atoms indices and the bond angle.

atom1: int#
atom2: int#
bondangle: float#
label() → str[source]#

Returns the label for the bond angle property.

class pyfrag_plotter.pyfrag_object.Bondlength(atom1: int, atom2: int, bondlength: float)[source]#

Bases: object

Attrs class for the bond length property containing the atoms indices and the bond length.

atom1: int#
atom2: int#
bondlength: float#
label() → str[source]#

Returns the label for the bond length property.

class pyfrag_plotter.pyfrag_object.DihedralAngle(atom1: int, atom2: int, atom3: int, dihedralangle: float)[source]#

Bases: object

Attrs class for the dihedral angle property containing the atoms indices and the dihedral angle.

atom1: int#
atom2: int#
atom3: int#
dihedralangle: float#
label() → str[source]#

Returns the label for the bond length property.

class pyfrag_plotter.pyfrag_object.Irrep(irrep: str)[source]#

Bases: object

irrep: str#
label() → str[source]#

Returns the label for the irrep property.

class pyfrag_plotter.pyfrag_object.OrbitalEnergy(orbital: float, frag: int, irrep: str | None = None)[source]#

Bases: object

Attrs class for the orbital energy property containing the orbitals and irreps of the two fragments.

frag: int#
irrep: str | None#
label() → str[source]#

Returns the label for the orbital energy property.

orbital: float#
class pyfrag_plotter.pyfrag_object.Overlap(frag1_orb: str, frag2_orb: str, frag1_irrep: str | None = None, frag2_irrep: str | None = None)[source]#

Bases: object

Attrs class for the overlap property containing the orbitals and irreps of the two fragments.

frag1_irrep: str | None#
frag1_orb: str#
frag2_irrep: str | None#
frag2_orb: str#
label() → str[source]#

Returns the label for the overlap property.

class pyfrag_plotter.pyfrag_object.Population(orbital: float, frag: int, irrep: str | None = None)[source]#

Bases: object

Attrs class for the population property containing the orbitals and irreps of the two fragments.

frag: int#
irrep: str | None#
label() → str[source]#

Returns the label for the population property.

orbital: float#
class pyfrag_plotter.pyfrag_object.Property(*args, **kwargs)[source]#

Bases: Protocol

Base class for all properties using the Protocol functionality of python. “Properties” are classes that inheret from this class, which are:

  • Bondlength

  • BondAngle

  • DihedralAngle

  • Overlap

  • Population

  • OrbitalEnergy

  • VDD

  • Irrep

property label: str#

Abstract method to be further specified in the individual classes. Returns the label for the property.

class pyfrag_plotter.pyfrag_object.PyFragResultsObject(name: str, dataframe: DataFrame, extra_strain: OrderedDict[str, Annotated[ndarray[tuple[Any, ...], dtype[float64]], Literal[1]]] = NOTHING, bondlength: List[Bondlength] = NOTHING, angle: List[BondAngle] = NOTHING, dihedral: List[DihedralAngle] = NOTHING, overlap: List[Overlap] = NOTHING, population: List[Population] = NOTHING, orbitalenergy: List[OrbitalEnergy] = NOTHING, vdd: List[VDD] = NOTHING, irrep: List[Irrep] = NOTHING)[source]#

Bases: object

Attrs class containing all the data of one pyfrag calculation.

It combines the data from the output file (i.e., the pyfrag_*.txt file) through binding a pandas DataFrame to the class, and the data from the input file through binding specific attributes. Examples of the specific attributes are bond lengths, bond angles, dihedral angles, overlaps, populations, orbital energies, VDD, and irreps.

name#

The name of the PyFrag calculation.

Type:

str

dataframe#

The data from the output file (i.e., the pyfrag_*.txt file).

Type:

pd.DataFrame

extra_strain#

The extra strain data for the PyFrag calculation.

Type:

OrderedDict[str, Array1D[np.float64]]

bondlength#

The bond length data for the PyFrag calculation.

Type:

List[Bondlength]

angle#

The bond angle data for the PyFrag calculation.

Type:

List[BondAngle]

dihedral#

The dihedral angle data for the PyFrag calculation.

Type:

List[DihedralAngle]

overlap#

The overlap data for the PyFrag calculation.

Type:

List[Overlap]

population#

The population data for the PyFrag calculation.

Type:

List[Population]

orbitalenergy#

The orbital energy data for the PyFrag calculation.

Type:

List[OrbitalEnergy]

vdd#

The VDD data for the PyFrag calculation.

Type:

List[VDD]

irrep#

The irrep data for the PyFrag calculation.

Type:

List[Irrep]

angle: List[BondAngle]#
bondlength: List[Bondlength]#
dataframe: DataFrame#
dihedral: List[DihedralAngle]#
extra_strain: OrderedDict[str, Annotated[ndarray[tuple[Any, ...], dtype[float64]], Literal[1]]]#
get_calculation_index_closest_to_irc_point(irc_coord: str, irc_point: float) → int[source]#

Returns the index of the calculation closest to the specified IRC point.

get_data_of_key(key: str) → Annotated[ndarray[tuple[Any, ...], dtype[float64]], Literal[1]][source]#

Returns the data found in the dataframe (from the .txt file) of the specified key.

get_peak_index(peak: str = 'max') → int[source]#

Determines the peak of the “EnergyTotal” data en returns the index. The peak can be either the maximum or minimum value.

get_plot_labels(keys: Sequence[str] | str) → Sequence[str][source]#

Returns the labels of the specified keys. There are two types of keys that should be handled differently: 1. Standard terms such as “Int”, “EnergyTotal”, “StrainTotal”, “Elstat”, “Pauli”, “OI”, and “Disp” 2. Non-standard terms such as “bondlength”, “overlap”, “orbitalenergy”, and more.

The former ones are handled by the TERM_LABELS dictionary, while the latter ones are handled by the label() method of the corresponding class.

get_x_axis(irc_coord: str) → Annotated[ndarray[tuple[Any, ...], dtype[float64]], Literal[1]][source]#

Returns the x-axis data for the specified IRC coordinate.

irrep: List[Irrep]#
name: str#
orbitalenergy: List[OrbitalEnergy]#
overlap: List[Overlap]#
population: List[Population]#
vdd: List[VDD]#
class pyfrag_plotter.pyfrag_object.VDD(atom: int)[source]#

Bases: object

atom: int#
label() → str[source]#

Returns the label for the VDD property.

pyfrag_plotter.pyfrag_object.create_pyfrag_object_from_dir(results_dir: str, **kwargs) → PyFragResultsObject[source]#

Creates a PyFragResultsObject from the results in a directory. This function provides a shortcut for creating a PyFragResultsObject from the results in a directory by processing and creating the PyFragResultsObject in one function.

Parameters:

  • results_dir (str) – The path to the directory containing the PyFrag results files.

  • **kwargs – Additional keyword arguments to pass to the process_results_file function. These are: trim_parameter (Optional[Union[str, float, int]]): The parameter to use for trimming. Defaults to none. trim_key (Optional[str]): The key to use for reading the trim_parameter from the configuration file. Defaults to the “EnergyTotal” column. outlier_threshold: (Optional[float]): The threshold to use for removing outliers. If none is specified, the threshold from the configuration file is used. Defaults to None.

Returns:

A PyFragResultsObject containing the processed PyFrag results.

Return type:

PyFragResultsObject

This function reads the PyFrag input and output files from the given directory, processes the output file using the process_results_file function with any additional keyword arguments provided. Creates a PyFragResultsObject from the processed results and input data using the create_pyfrag_object_from_processed_files function.

pyfrag_plotter.pyfrag_object.create_pyfrag_object_from_processed_files(results_data: DataFrame, inputfile_data: Dict[str, Any]) → PyFragResultsObject[source]#

Creates a PyFragResultsObject from the given results data and input file data.

This function takes a pandas DataFrame containing the results file data and a dictionary containing the input file data and creates a PyFragResultsObject. The PyFragResultsObject contains data for various properties such as EDA, ASM, extra strain, bond lengths, bond angles, dihedral angles, overlaps, populations, orbital energies, VDD, and irreps.

Parameters:

  • results_data (pd.DataFrame) – The data from the output file (i.e., the pyfrag_*.txt file).

  • inputfile_data (Dict[str, Any]) – The keys from the input file such as bondlength, overlap, orbitalenergy, and more.

Returns:

The dataclass containing all the data of one PyFrag calculation.

Return type:

PyFragResultsObject

Note: standard terms such “Int”, “EnergyTotal”, “StrainTotal”, “Elstat”, “Pauli”, “OI”, and “Disp” are automatically added to the PyFragResultsObject. Non-standard terms such as “bondlength”, “overlap”, “orbitalenergy”, and more are added to the PyFragResultsObject by using the key_to_func_mapping dictionary.

Module contents#

pyfrag_plotter.initialize_pyfrag_plotter(user_config_file: str | None = None) → None[source]#

Initializes the PyFrag plotter configuration.

This function reads the standard configuration file provided in the module and sets the config as a global variable that is read throughout the program. The standard configuration can be overwritten by providing a custom configuration file.

Parameters:

  • user_config_file (Optional[str]) – The path to a custom configuration file. If provided, the settings in this file

  • None. (will overwrite the standard configuration. Defaults to)

Returns:

None

Raises:

ValueError – If the log level specified in the configuration is invalid.

On this page

This Page