Property Extraction Usage¶

Installation¶

To use subproptools, first install it using pip:

(.venv) $ pip install subproptools

Get xyz of atoms in sumfile¶

subproptools.qtaim_extract.get_xyz(data: list[str]) → dict[source]¶

Given lines of sumfile, return dicitonary containing xyzcoordinates and atom labels

Parameters:

data – lines of sum file

Returns:

Dictionary: ’xyz’: dataframe of xyz coordinates of nuclei in sum file ‘Atoms’: list of atom labels

Extracting Atomic Properties¶

To retrieve a dictionary of the atomic properties, you can use the subproptools.qtaim_extract.get_atomic_props() function

subproptools.qtaim_extract.get_atomic_props(data: list[str]) → dict[source]¶

Returns a dictionary of atomic properties

Parameters:: data – the string lines of a .sum file
Returns:: A dictionary of atomic properties with one key for each atom label e.g. ‘C1’ Each of those dictionaries has the following keys: xyz, q, K, K_Scaled, Mu_Intra_X, Mu_Intra_Y, Mu_Intra_Z, Mu_Bond_X, Mu_Bond_Y, Mu_Bond_Z, Mu_X, Mu_Y, Mu_Z, |Mu_Intra|, |Mu_Bond|, |Mu|, Q_XX, Q_XY, Q_XZ, Q_YY, Q_YZ, Q_ZZ, R+2, R+1, Vol, quadContrib

Note

Volume is calculated at the 0.001 au isosurface quadContrib is the atomic contribution to the molecular quadrupole moment from Laidig TODO add citation

Convert Atomic Properties to Group Properties¶

subproptools.qtaim_extract.get_sub_props(atomDict: dict, subAtoms: list[int], atomList: list[str])[source]¶

Combine atomic properties together into group properties

Parameters:

atomDict – output from get_atomic_props
subAtoms – list[int] integer labels of atoms in substituent [1, 2,…]
atomList – list[str] string list of atom labels, [‘C1’, ‘H2’…]

Returns:

q,K, K_Scaled, Mu_Intra_X, Mu_Intra_Y, Mu_Intra_Z, Mu_Bond_X, Mu_Bond_Y,Mu_Bond_Z, Mu_X, Mu_Y, Mu_Z, Q_xx, Q_xy, Q_xz, Q_yy,Q_yz,Q_zz,Vol, |Mu_Intra|,``|Mu_Bond|``,``|Mu|``

Return type:

dictionary of group properties with the following keys

Note

in output dictionary, each property is stored as a one element list(to enable pandas later) Access properties as outDict[‘key’][0]

Extracting BCP Properties¶

To retrieve a dictionary of BCP properties for a specific BCP:

subproptools.qtaim_extract.get_bcp_properties(data: list[str], atPair: list[str] = ['C1', 'H2'])[source]¶

Get BCP Properties for BCP between two atoms in list

Parameters:

data – lines of a .sum file
atPair – list of atom labels for which to find BCP, e.g. [‘C1’,’H2’]

Returns:

dictionary containing properties of atPair bcp with keys: ’xyz’ (np array of xyz coords), ‘rho’, lambda1, lambda2, lambda3, DelSqRho, Ellipticity, V, G, H

To get a dictionary of BCP properties for a set of requested BCPs:

subproptools.qtaim_extract.extract_requested_bcp_props(data: list[str], atomList: list[str], bcpId: list[list[int]], subatomLabels: list[str], atomicProps: dict) → dict[source]¶

Get BCP dict for requested bcps

Parameters:

data – lines of .sum file
atomList – list of atom labels in molecule. e.g. [‘C1’,’H2’]
bcpId – list of 2 length lists.
subAtomLabels – list of atoms in the substituent, e.g.[“C1”,”C2”]
atomicProps – dictionary output of get_atomic_props

Returns:

Nested dictionary. First level is the ID of bcp requested of form ‘A1-A2’, second is extracted properties

To find a list of all BCPs in file in a format to use for the above functions:

subproptools.qtaim_extract.find_all_connections(data)[source]¶

Given lines of sumfile, finds all BCPs in file.

Parameters:: data – list[str]: lines of sumfile
Returns:: List of List of BCPs e.g. [[‘C1’,H3’],[‘C1’,’H4’],[‘C1’,’H5’]]

Get DI between a substituent and the rest of the molecule¶

subproptools.qtaim_extract.get_sub_di(data: list[str], subAtomLabels=list[str]) → float[source]¶

Given lines of sum file and labels of atoms in substituent, return DI between substituent and rest of molecule

Parameters:

data – lines of .sum file
subAtomLabels – list of atoms in the substituent, e.g.[“C1”,”C2”]

Returns:

DI between substituent atoms and rest of molecule

Extracting Properties for a set of molecules¶

Gets BCP and group properties

subproptools.qtaim_extract.sub_prop_frame(csvFile: str) → dict[source]¶

Given csv file, extract group properties for all files included and store properties

Parameters:

csvFile – string containing csv file (WITH extension)
structure (example csvFile)
Substituent
subAtoms
label1
label2
...
SubC6H5_CH3 (CH3 1 3 4 5 SubH_CH3) – Substituent: string of substituent subAtoms: string of space separated substituent atoms eg ‘1 3 4’ label1 - contains .sum file with no extension labeli could be e.g. a model chemistry, or substrate that is the column “SubH” would have sum files for the substituents attached to H SubC6H5 would have sum files for substituents attached to C6H5 etc

Returns:

dictionary of dicitonary of data frames containing group properties {‘label1’: {‘Group’: Pandas Data Frame, ‘BCP’: Pandas Data Frame}}

Notes

Group frame has columns: Substituent, q,K, K_Scaled, Mu_Intra_X, Mu_Intra_Y, Mu_Intra_Z, Mu_Bond_X, Mu_Bond_Y,Mu_Bond_Z, Mu_X, Mu_Y, Mu_Z, Q_xx, Q_xy, Q_xz, Q_yy,Q_yz,Q_zz,Vol, |Mu_Intra|,``|Mu_Bond|``,``|Mu|`` BCP frame has columns: Substituent, rho, delsqrho, lambda1, lambda2, lambda3,V,G,H,DI

Charge Concentration Manipulation¶

Find all CCs on an atom

subproptools.qtaim_extract.get_cc_props(filename, atomLabel: str, is_lines_data: bool = False) → dict[source]¶

Gets all charge concentration properties for an atom

Parameters:

filename – sum file name:str with no extension or lines of the desired agpviz file as list[str]
atomLabel – label of atom that we wish to find VSCC for, e.g. ‘N3’
is_lines_data – True if filename is lines of agpviz file, false otherwise

Returns:

Dictionary with one nested dictinoary for each VSCC found {1: {VSCC1 props}, 2::{VSCC2 props} ,…} Sub-dictionary keys include: xyz, rho, delsqrho, distFromNuc

Filter all CCs for VSCCs .. autofunction:: subproptools.qtaim_extract.identify_vscc

Combine those two into one step

subproptools.qtaim_extract.get_atom_vscc(filename, atomLabel: str, atomicProps: dict, is_lines_data: bool = False)[source]¶

Returns a dicitonary of the properties of VSCC for the atom

Parameters:

filename – name of sum file without .sum extension OR lines of atomLabel’s agpviz file if is_lines_data is True
atomLabel – label of atom in molecule, e.g. ‘C1’
atomicProps – return value of a get_atomic_props function
is_lines_data – is filename actually the lines of an agpviz file instead of filename

Returns:

dictionary of dictionaries of all VSCC concentrations for atomLabel.: Keys are integer 1,2…n where n is number of cc Each of those dict[key] is a dictionary as well containing cc properties

Get VSCC for a set of atoms

subproptools.qtaim_extract.extract_requested_cc_props(lapRhoCpAtoms: list[int], sumFileNoExt: str, atomList: list[str], atomicProps: dict) → dict[source]¶

Get VSCC dict for requested atoms

Parameters:

lapRhoCpAtoms – indices of atoms(starting at 1) that you want to find VSCC for
sumFileNoExt – filename of sum file without extension
atomList – list of atom labels in molecule. e.g. [‘C1’,’H2’]
atomicProps – dictionary output of get_atomic_props

Returns:

atomLabel, second layer integer label of VSCC, third layer properties extracted

Return type:

Nested dictionary with first layer keys

Get CC, BCP, Group and Atomic propeties for a substituent¶

subproptools.qtaim_extract.extract_sub_props(data: list[str], subAtoms: list[int], sumFileNoExt: str, groupProps: bool = True, bcpId=[[1, 2]], lapRhoCpAtoms=[])[source]¶

returns a dictionary of all group properties - bcp, group, atomic, and vscc

Parameters:

data – list[str] - lines of a .sum file
subAtoms – indices of atoms in the molecule comprising group - starts at 1
groupProps – do you want to compute group properties
bcpId – list of 2 length lists. Pass empty list if no bcp properties wanted.
for (2 length lists are indices of atoms that you want BCPs)
empty (lapRhoCpAtoms = list of atom indices that you want to find laprhoCPs for. Defaults to)

Returns:

nested dictionaries with keys ‘Group’, ‘Atomic’, ‘BCP’, ‘VSCC’

Notes

vol surface is 0.001 au isodensity