Core classes

Module pychemcur.core implements several classes in order to represents a vertex of a molecular squeleton and compute geometrical and chemical indicators related to the local curvature around this vertex.

A complete and precise definition of all the quantities computed in the classes of this module can be found in article [JCP2020].

[JCP2020]

(1, 2, 3, 4) Julia Sabalot-Cuzzubbo, Germain Salvato Vallverdu, Didier Bégué and Jacky Cresson Relating the molecular topology and local geometry: Haddon’s pyramidalization angle and the Gaussian curvature, J. Chem. Phys. 152, 244310 (2020). https://aip.scitation.org/doi/10.1063/5.0008368

[POAV2]

Julia Sabalot-Cuzzubbo, Germain Salvato Vallverdu, Didier Bégué and Jacky Cresson Haddon’s POAV2 versus POAV theory for non planar molecules (to be published).

Vertex classes

VertexAtom class

class pychemcurv.core.VertexAtom(a, star_a)

This class represents an atom (or a point) associated to a vertex of the squeleton of a molecule. The used notations are the following. We denote by A a given atom caracterized by its cartesian coordinates corresponding to a vector in \(\mathbb{R}^3\). This atom A is bonded to one or several atoms B. The atoms B, bonded to atoms A belong to \(\star(A)\) and are caracterized by their cartesian coordinates defined as vectors in \(\mathbb{R}^3\). The geometrical object obtained by drawing a segment between bonded atoms is called the skeleton of the molecule and is the initial geometrical picture for a molecule. This class is defined from the cartesian coordinates of atom A and the atoms belonging to \(\star(A)\).

More generally, the classes only considers points in \(\mathbb{R}^3\). The is not any chemical consideration here. In consequence, the class can be used for all cases where a set of point in \(\mathbb{R}^3\) is relevant.

Parameters:

• a (np.ndarray) – cartesian coordinates of point/atom A in \(\mathbb{R}^3\)
• star_a (nd.array) – (N x 3) cartesian coordinates of points/atoms B in \(\star(A)\)

static from_pyramid(length, theta, n_star_A=3, radians=False, perturb=None)

Set up a VertexAtom from an ideal pyramidal structure. Build an ideal pyramidal geometry given the angle theta and randomize the positions by adding a noise of a given magnitude. The vertex of the pyramid is the point A and \(\star(A)\). are the points linked to the vertex. The size of \(\star(A)\). is at least 3.

\(\theta\) is the angle between the normal vector of the plane defined from \(\star(A)\) and the bonds between A and \(\star(A)\). The pyramidalisation angle is defined from \(\theta\) such as

\[pyrA = \theta - \frac{\pi}{2}\]

Parameters:

• length (float) – the bond length
• theta (float) – Angle to define the pyramid
• n_star_A (int) – number of point bonded to A the vertex of the pyramid.
• radian (bool) – True if theta is in radian (default False)
• perturb (float) – Give the width of a normal distribution from which random numbers are choosen and added to the coordinates.

Returns:

A VertexAtom instance

a

Coordinates of atom A

star_a

Coordinates of atoms B belonging to \(\star(A)\)

reg_star_a

Regularized coordinates of atoms/points B in \(\star(A)\) such as all distances between A and points B are equal to unity. This corresponds to \(Reg_{\epsilon}\star(A)\) with \(\epsilon\) = 1.

normal

Unitary vector normal to the plane or the best fitting plane of atoms/points Bi in \(\star(A)\).

reg_normal

Unitary vector normal to the plane or the best fitting plane of atoms/points \(Reg B_i\) in \(\star(A)\).

com

Center of mass of atoms/points B in \(\star(A)\)

distances

Return all distances between atom A and atoms B belonging to \(\star(A)\). Distances are in the same order as the atoms in vertex.star_a.

get_angles(radians=True)

Compute angles theta_ij between the bonds ABi and ABj, atoms Bi and Bj belonging to \(\star(A)\). The angle theta_ij is made by the vectors ABi and ABj in the affine plane defined by this two vectors and atom A. The computed angles are such as bond ABi are in a consecutive order.

Parameters:radians (bool) – if True (default) angles are returned in radians

angular_defect

Compute the angular defect in radians as a measure of the discrete curvature around the vertex, point A.

The calculation first looks for the best fitting plane of points belonging to \(\star(A)\) and sorts that points in order to compute the angles between the edges connected to the vertex (A). See the get_angles method.

pyr_distance

Compute the distance of atom A to the plane define by \(\star(A)\) or the best fitting plane of \(\star(A)\). The unit of the distance is the same as the unit of the coordinates of A and \(\star(A)\).

as_dict(radians=True, list_obj=False)

Return a dict version of all the properties that can be computed using this class. Use list_obj=True to get a valid JSON object.

Parameters:

• radians (bool) – if True, angles are returned in radians (default)
• list_obj (bool) – if True, numpy arrays are converted into list object (default False)

Returns:

A dict

write_file(species='C', filename='vertex.xyz')

Write the coordinates of atom A and atoms \(\star(A)\) in a file in xyz format. You can set the name of species or a list but the length of the list must be equal to the number of atoms. If filename is None, returns the string corresponding to the xyz file.

Parameters:

• species (str, list) – name of the species or list of the species names
• filename (str) – path of the output file or None to get a string

Returns:

None if filename is a path, else, the string corresponding to the xyz file.

TrivalentVertex class

class pychemcurv.core.TrivalentVertex(a, star_a)

This object represents an atom (or a point) associated to a vertex of the squeleton of a molecule bonded to exactly 3 other atoms (or linked to 3 other points). This correspond to the trivalent case.

We denote by A a given atom caracterized by its cartesian coordinates corresponding to a vector in \(\mathbb{R}^3\). This atom A is bonded to 3 atoms B. The atoms B, bonded to atom A belong to \(\star(A)\) and are caracterized by their cartesian coordinates defined as vectors in \(\mathbb{R}^3\). The geometrical object obtained by drawing a segment between bonded atoms is called the skeleton of the molecule and is the initial geometrical picture for a molecule. This class is defined from the cartesian coordinates of atom A and the atoms belonging to \(\star(A)\).

More generally, the classes only considers points in \(\mathbb{R}^3\). The is not any chemical consideration here. In consequence, the class can be used for all cases where a set of point in \(\mathbb{R}^3\) is relevant.

The following quantities are computed according the reference [JCP2020]

pyramidalization angle pyrA

The pyramidalization angle, in degrees. \(pyrA = \theta - \pi/2\) where \(\theta\) is the angle between the normal vector of the plane containing the atoms B of \(\star(A)\) and a vector along a bond between atom A and one B atom.

An exact definition of pyrA needs that A is bonded to exactly 3 atoms in order to be able to define a uniq plane that contains the atoms B belonging to \(\star(A)\). Nevertheless, pyrA is computed if more than 3 atoms are bonded to atom A by computing the best fitting plane of atoms belonging to \(\star(A)\).

pyramidalization angle, pyrA_r

The pyramidalization angle in radians.

improper angle, improper

The improper angle corresponding to the dihedral angle between the planes defined by atoms (i, j, k) and (j, k, l), atom i being atom A and atoms j, k and l being atoms of \(\star(A)\). In consequence, the improper angle is defined only if there are 3 atoms in \(\star(A)\).

The value of the improper angle is returned in radians.

angular defect, angular_defect

The angluar defect is defined as

where \(\alpha_F\) are the angles at the vertex A of the faces \(F\in\star(A)\). The angular defect is computed whatever the number of atoms in \(\star(A)\).

The value of the angular defect is returned in radians.

spherical curvature, spherical_curvature

The spherical curvature is computed as the radius of the osculating sphere of atoms A and atoms belonging to \(\star(A)\). The spherical curvature is computed as

\[\kappa(A) = \frac{1}{\sqrt{\ell^2 + \dfrac{(OA^2 - \ell^2)^2}{4z_A^2}}}\]

where O is the center of the circumbscribed circle of atoms in \(\star(A)\) ; A the vertex atom ; OA the distance between O and A ; \(\ell\) the distance between O and atoms B of \(\star(A)\) ; \(z_A\) the distance of atom A to the plane defined by \(\star(A)\). The spherical curvature is defined only if there are 3 atoms in \(\star(A)\).

pyramidalization distance pyr_distance

Distance of atom A to the plane define by \(\star(A)\) or the best fitting plane of \(\star(A)\).

The value of the distance is in the same unit as the coordinates.

If the number of atoms B in \(\star(A)\) is not suitable to compute some properties, np.nan is returned.

Note that the plane defined by atoms B belonging to \(\star(A)\) is exactly defined only in the case where there are three atoms B in \(\star(A)\). In the case of pyrA, if there are more than 3 atoms in \(\star(A)\), the class use the best fitting plane considering all atoms in \(\star(A)\) and compute the geometrical quantities.

Parameters:

• a (np.ndarray) – cartesian coordinates of point/atom A in \(\mathbb{R}^3\)
• star_a (nd.array) – (N x 3) cartesian coordinates of points/atoms B in \(\star(A)\)

static from_pyramid(length, theta, radians=False, perturb=None)

Set up a VertexAtom from an ideal pyramidal structure. Build an ideal pyramidal geometry given the angle theta and randomize the positions by adding a noise of a given magnitude. The vertex of the pyramid is the point A and \(\star(A)\). are the points linked to the vertex. The size of \(\star(A)\). is 3.

\(\theta\) is the angle between the normal vector of the plane defined from \(\star(A)\) and the bonds between A and \(\star(A)\). The pyramidalisation angle is defined from \(\theta\) such as

\[pyrA = \theta - \frac{\pi}{2}\]

Parameters:

• length (float) – the bond length
• theta (float) – Angle to define the pyramid
• radian (bool) – True if theta is in radian (default False)
• perturb (float) – Give the width of a normal distribution from which random numbers are choosen and added to the coordinates.

Returns:

A TrivalentVertex instance

improper

Compute the improper angle in randians between planes defined by atoms (i, j, k) and (j, k, l). Atom A, is atom i and atoms j, k and l belong to \(\star(A)\).

   l
   |
   i
  /  \
j     k

This quantity is available only if the length of \(\star(A)\) is equal to 3.

pyrA_r

Return the pyramidalization angle in radians.

pyrA

Return the pyramidalization angle in degrees.

spherical_curvature

Compute the spherical curvature associated to the osculating sphere of points A and points B belonging to \(\star(A)\). Here, we assume that there is exactly 3 atoms B in \(\star(A)\).

as_dict(radians=True, list_obj=False)

Return a dict version of all the properties that can be computed using this class. Use list_obj=True to get a valid JSON object.

Parameters:

• radians (bool) – if True, angles are returned in radians (default)
• list_obj (bool) – if True, numpy arrays are converted into list object (default False)

Returns:

A dict.

POAV: Pi-Orbital Axis Vector

POAV stands for \(\pi\)-Orbital Axis Vector. The definition of this vector has its origin in the works of R.C. Haddon. The definitions and the relation between POAV and the local curvature of a molecule using new geometrical object such as the angular defect have been established in our recent work [JCP2020].

Hereafter, the two classes POAV1 and POAV2 aim to compute quantities related to the two definitions of the POAV vector.

POAV1

class pychemcurv.core.POAV1(vertex)

In the case of the POAV1 theory the POAV vector has the property to make a constant angle with each bond connected to atom A.

This class computes indicators related to the POAV1 theory of R.C. Haddon following the link established between pyrA and the hybridization of a trivalent atom in reference [JCP2020].

A chemical picture of the hybridization can be drawn by considering the contribution of the \(p\) atomic oribtals to the system \(\sigma\), or the contribution of the s atomic orbital to the system \(\pi\). This is achieved using the m and n quantities. For consistency with POAV2 class, the attributes, hybridization, sigma_hyb_nbr and pi_hyb_nbr are also implemented but return the same values.

POAV1 is defined from the local geometry of an atom at a vertex of the molecule’s squeleton.

Parameters:vertex (TrivalentVertex) – the trivalent vertex atom

pyrA

Pyramidalization angle in degrees

pyrA_r

Pyramidalization angle in radians

poav

Return a unitary vector along the POAV vector

c_pi

Value of \(c_{\pi}\) in the ideal case of a \(C_{3v}\) geometry. Equation (22), with \(c_{1,2} = \sqrt{2/3}\).

\[c_{\pi} = \sqrt{2} \tan Pyr(A)\]

lambda_pi

value of \(\lambda_{\pi}\) in the ideal case of a \(C_{3v}\) geometry. Equation (23), with \(c^2_{1,2} = 2/3\).

\[\lambda_{\pi} = \sqrt{1 - 2 \tan^2 Pyr (A)}\]

m

value of hybridization number m, see equation (44)

\[m = \left(\frac{c_{\pi}}{\lambda_{\pi}}\right)^2\]

n

value of hybridization number n, see equation (47)

\[n = 3m + 2\]

pi_hyb_nbr

This quantity measure the weight of the s atomic orbital with respect to the p atomic orbital in the \(h_{\pi}\) hybrid orbital along the POAV vector.

This is equal to m.

sigma_hyb_nbr

This quantity measure the weight of the p atomic orbitals with respect to s in the hi hybrid orbitals along the bonds with atom A.

This is equal to n

hybridization

Compute the hybridization such as

\[s p^{(2 + c_{\pi}^2) / (1 - c_{\pi}^2)}\]

This quantity corresponds to the amount of p AO in the system \(\sigma\). This is equal to n and corresponds to the \(\tilde{n}\) value defined by Haddon.

TODO: verifier si cette quantité est égale à n uniquement dans le cas C3v.

as_dict(radians=True, include_vertex=False, list_obj=False)

Return a dict version of all the properties that can be computed with this class. Note that in the case of \(\lambda_{\pi}\) and \(c_{\pi}\) the squared values are returned as they are more meaningfull. Use list_obj= True to obtain a valid JSON object.

Parameters:

• radians (bool) – if True, angles are returned in radians (default)
• include_vertex (bool) – if True, include also vertex data
• list_obj (bool) – if True, numpy arrays are converted into list object (default False)

Returns:

A dict.

POAV2

class pychemcurv.core.POAV2(vertex)

In the case of the POAV2 theory the POAV2 vector on atom A is such as the set of hybrid molecular orbitals \({h_{\pi}, h_1, h_2, h_3}\) is orthogonal ; where the orbitals \(h_i\) are hybrid orbitals along the bonds with atoms linked to atom A and \(h_{\pi}\) is the orbital along the POAV2 \(\vec{u}_{\pi}\) vector.

This class computes indicators related to the POAV2 theory of R.C. Haddon following the demonstrations in the reference [POAV2].

POAV1 is defined from the local geometry of an atom at a vertex of the molecule’s squeleton.

Parameters:vertex (TrivalentVertex) – the trivalent vertex atom

matrix

Compute and return the sigma-orbital hybridization numbers n1, n2 and n3

u_pi

Return vector \(u_{\pi}\) as the basis of the zero space of the matrix M. This unitary vector support the POAV2 vector.

sigma_hyb_nbrs

Compute and return the sigma-orbital hybridization numbers n1, n2 and n3. These quantities measure the weight of the p atomic orbitals with respect to s in each of the \(h_i\) hybrid orbitals along the bonds with atom A.

pi_hyb_nbr

This quantity measure the weight of the s atomic orbital with respect to the p atomic orbital in the \(h_{\pi}\) hybrid orbital along the POAV2 vector.

pyrA_r

Compute the angles between vector \(u_{\pi}\) and all the bonds between atom A and atoms B in \(\star(A)\).

as_dict(radians=True, include_vertex=False, list_obj=False)

Return a dict version of all the properties that can be computed with this class. Use list_obj= True to obtain a valid JSON object.

Parameters:

• radians (bool) – if True, angles are returned in radians (default)
• include_vertex (bool) – if True, include also vertex data
• list_obj (bool) – if True, numpy arrays are converted into list object (default False)

Returns:

A dict.