# cctk.helper_functions¶

Miscellaneous helper functions.

Functions

 `align_matrices`(P_partial, P_full, Q_partial) Rotates one set of points onto another using the Kabsch algorithm. `bytes_to_numpy`(arr_bytes) Utility function for unpickling numpy arrays `compute_RMSD`(geometry1, geometry2[, checks]) Computes the root mean squared difference between two geometries. `compute_angle_between`(v1, v2[, unit]) Computes the angle between two vectors. `compute_chirality`(v1, v2, v3, v4) Given 4 bond vectors, returns 1 or -1 based on chirality. `compute_dihedral_between`(p0, p1, p2, p3[, unit]) Computes the dihedral angle between four points. `compute_distance_between`(v1, v2[, _norm]) Computes the L2 distance between two vectors. `compute_mass_spectrum`(formula_dict, **kwargs) Computes the expected low-res mass spec ions for a given formula. `compute_rotation_matrix`(axis, theta) Return the rotation matrix for rotation around `axis` by `theta` degrees. `compute_unit_vector`(vector) Normalizes a vector, returning a unit vector pointing in the same direction. For an element with number `z`, return a weighted random atomic mass (so will return 12 99% of the time and 13 1% of the time for carbon). `formula_dict_from_string`(formula_string) Eugene challenged me to code golf, this isn’t my fault. For an element with number `z`, return average mass of that element. `get_corrected_free_energy`(free_energy, …) Computes the free energy by moving all positive frequencies below `frequency_cutoff` to the cutoff. `get_covalent_radius`(atomic_number) Gets the covalent radius for a given element. `get_entropy`(frequencies, temperature) Computes the total entropy of a given set of frequencies. For an element with number `z`, returns two `np.ndarray` objects containing that element’s weights and relative abundances. `get_number`(atomic_symbol) Gets atomic number from a given element symbol (converted to titlecase using `string.title()`). `get_symbol`(atomic_number) Gets element symbol from a given atomic number. `get_vdw_radius`(atomic_number) Gets the van der Waals radius for a given element. `get_z_from_mass`(desired_mass[, tolerance]) For an element with atomic mass `desired_mass`, return the element’s atomic number. Utility function for pickling numpy arrays `scale_nmr_shifts`(ensemble[, …]) Apply linear scaling to isotropic shieldings to get chemical shifts.
`cctk.helper_functions.``align_matrices`(P_partial, P_full, Q_partial, return_matrix=False)[source]

Rotates one set of points onto another using the Kabsch algorithm. The rotation that best aligns P_partial into Q_partial will be found and then applied to P_full.

Parameters
• P_partial (matrix) – atoms of P that correspond to Q

• P_full (matrix) – full matrix to rotate

• Q (matrix) – matrix to align to

Returns

rotated P matrix

`cctk.helper_functions.``bytes_to_numpy`(arr_bytes)[source]

Utility function for unpickling numpy arrays

`cctk.helper_functions.``compute_RMSD`(geometry1, geometry2, checks=True)[source]

Computes the root mean squared difference between two geometries.

Parameters
• (np.array (dimensions (geometry2) – n atoms x 3): geometry

• (np.array (dimensions – n atoms x 3): geometry

• checks (bool) – whether to check that the inputs make sense (True by default)

Returns

the root-mean-square distance between the two geometries

`cctk.helper_functions.``compute_angle_between`(v1, v2, unit='degree')[source]

Computes the angle between two vectors.

Parameters
• v1 (ndarray) – first vector

• v2 (ndarray) – second vector

• unit (str) – ‘degree’ or ‘radian’

Returns

the angle between the two vectors

`cctk.helper_functions.``compute_chirality`(v1, v2, v3, v4)[source]

Given 4 bond vectors, returns 1 or -1 based on chirality. For proper Cahn–Ingold–Prelog results, vectors should be passed from highest to lowest priority; however, any predictable order will give meaningful results.

Parameters
• v1 (np.ndarray) – 3D bond vector

• v2 (np.ndarray) – 3D bond vector

• v3 (np.ndarray) – 3D bond vector

• v4 (np.ndarray) – 3D bond vector

Returns

value of 1 (R by CIP) or -1 (S by CIP)

`cctk.helper_functions.``compute_dihedral_between`(p0, p1, p2, p3, unit='degree')[source]

Computes the dihedral angle between four points.

`cctk.helper_functions.``compute_distance_between`(v1, v2, _norm=<function norm>)[source]

Computes the L2 distance between two vectors.

(preloading `_norm` speeds repeated calls, since Python doesn’t have to look up the function every time)

`cctk.helper_functions.``compute_mass_spectrum`(formula_dict, **kwargs)[source]

Computes the expected low-res mass spec ions for a given formula.

Parameters

dict (formula) – e.g. {“C”: 6, “H”: 6}

Returns

list of m/z ions list of relative weights (out of 1 total)

`cctk.helper_functions.``compute_rotation_matrix`(axis, theta)[source]

Return the rotation matrix for rotation around `axis` by `theta` degrees.. Adapted from user “unutbu” on StackExchange.

Parameters
• axis (np.ndarray) – the vector to rotate about

• theta (float) – how much to rotate (in degrees)

Returns

the 3x3 rotation matrix

`cctk.helper_functions.``compute_unit_vector`(vector)[source]

Normalizes a vector, returning a unit vector pointing in the same direction. Returns the zero vector if the zero vector is given.

`cctk.helper_functions.``draw_isotopologue`(z)[source]

For an element with number `z`, return a weighted random atomic mass (so will return 12 99% of the time and 13 1% of the time for carbon).

`cctk.helper_functions.``formula_dict_from_string`(formula_string)[source]

Eugene challenged me to code golf, this isn’t my fault.

Parameters

formula_string (str) – the formula as a string, e.g. C10H12N2O1. you need the “1” explicitly

Returns

e.g. {‘C’: 10, ‘H’: 12, ‘N’: 2, ‘O’: 1}

Return type

formula_dict (dict)

`cctk.helper_functions.``get_avg_mass`(z)[source]

For an element with number `z`, return average mass of that element.

`cctk.helper_functions.``get_corrected_free_energy`(free_energy, frequencies, frequency_cutoff=100.0, temperature=298.15)[source]

Computes the free energy by moving all positive frequencies below `frequency_cutoff` to the cutoff. See Cramer/Truhlar, J. Phys. Chem. B, 2011, 115, 14556.

Parameters
• free_energy (float) – in hartree

• frequencies (list) – in cm-1

• frequency_cutoff (float) – in cm-1

• temperature (float) – in K

Returns

in hartree

Return type

corrected_free_energy (float)

`cctk.helper_functions.``get_covalent_radius`(atomic_number)[source]

Gets the covalent radius for a given element.

Parameters

atomic_number (int) – the number of the given element

Returns

the covalent radius in Angstroms (float)

`cctk.helper_functions.``get_entropy`(frequencies, temperature)[source]

Computes the total entropy of a given set of frequencies.

Parameters
• frequencies (list) – in cm-1

• temperature (float) – in K

Returns

in hartree

Return type

entropy (float)

`cctk.helper_functions.``get_isotopic_distribution`(z)[source]

For an element with number `z`, returns two `np.ndarray` objects containing that element’s weights and relative abundances.

Parameters

z (int) – atomic number

Returns

list of isotope masses weights (np.ndarray): list of weights (relative to 1.00 for largest)

Return type

masses (np.ndarray)

`cctk.helper_functions.``get_number`(atomic_symbol)[source]

Gets atomic number from a given element symbol (converted to titlecase using `string.title()`).

Parameters

atomic_symbol (str) – the two-character symbol

Returns

the atomic number

`cctk.helper_functions.``get_symbol`(atomic_number)[source]

Gets element symbol from a given atomic number.

Parameters

atomic_number (int) – the number of the given element

Returns

the two-character atomic symbol string

`cctk.helper_functions.``get_vdw_radius`(atomic_number)[source]

Gets the van der Waals radius for a given element.

Parameters

atomic_number (int) – the number of the given element

Returns

the van der Waals radius in Angstroms (float)

`cctk.helper_functions.``get_z_from_mass`(desired_mass, tolerance=0.001)[source]

For an element with atomic mass `desired_mass`, return the element’s atomic number.

Returns `None` if no mass within `tolerance` is found.

`cctk.helper_functions.``numpy_to_bytes`(arr)[source]

Utility function for pickling numpy arrays

`cctk.helper_functions.``scale_nmr_shifts`(ensemble, symmetrical_atom_numbers=None, scaling_factors='default', property_name='isotropic_shielding')[source]

Apply linear scaling to isotropic shieldings to get chemical shifts. Shifts are calculated as (intercept-shielding)/slope. If there are no shifts available for a structure, None will be placed in both return lists.

Parameters
• ensemble – an `Ensemble` with calculated nmr shifts

• symmetrical_atom_numbers – None to perform no symmetry-averaging, a list of lists of 1-indexed atom numbers (e.g. [ [2,4,5], [7,8] ]) for a ConformationalEnsemble, or triply-nested lists for an Ensemble, where the outer index refers to the index of the Ensemble.

• scaling_factors – “default” to use DEFAULT_NMR_SCALING_FACTORS or a dict (atomic symbol –> (slope,intercept)). Elements for which scaling factors are not provided will be ignored.

• property_name – the key in properties_dict to use to locate the predicted isotropic shieldings (default=”isotropic_shielding”)

Returns

np.array (matching the shape of the original shieldings minus symmetry averaging) shift_labels: np.array (also matches shape)

Return type

scaled_shifts