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 SabalotCuzzubbo, 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 SabalotCuzzubbo, 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Return a dict version of all the properties that can be computed using this class.
Parameters: radians (bool) – if True, angles are returned in radians (default)

write_file
(species='C', filename='vertex.xyz')[source]¶ 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)[source]¶ 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)[source]¶ 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)\).
 pyramidalization angle
POAV: PiOrbital 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)[source]¶ 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
andpi_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.

POAV2¶

class
pychemcurv.core.
POAV2
(vertex)[source]¶ 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 sigmaorbital 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 sigmaorbital 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)\).
