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(1,2)
Julia Sabalot-Cuzzubbo, N. Cresson, Germain Salvato Vallverdu, Didier Bégué and Jacky Cresson Haddon’s POAV2 vs POAV theory for non-planar molecules, J. Chem. Phys. 159, 174109 (2023). https://aip.scitation.org/doi/10.1063/5.0170800
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
- property a¶
Coordinates of atom A
- property star_a¶
Coordinates of atoms B belonging to \(\star(A)\)
- property 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.
- property normal¶
Unitary vector normal to the plane or the best fitting plane of atoms/points Bi in \(\star(A)\).
- property reg_normal¶
Unitary vector normal to the plane or the best fitting plane of atoms/points \(Reg B_i\) in \(\star(A)\).
- property com¶
Center of mass of atoms/points B in \(\star(A)\)
- property 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
- property 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.
- property 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)[source]¶
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')[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
- property 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.
- property pyrA_r¶
Return the pyramidalization angle in radians.
- property pyrA¶
Return the pyramidalization angle in degrees.
- property 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)[source]¶
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.
- pyramidalization angle
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]. An discussion on the two POAV1 and POAV2 quantities is published in the work [POAV2].
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
- property pyrA¶
Pyramidalization angle in degrees
- property pyrA_r¶
Pyramidalization angle in radians
- property poav¶
Return a unitary vector along the POAV vector
- property 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)\]
- property 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)}\]
- property m¶
value of hybridization number m, see equation (44)
\[m = \left(\frac{c_{\pi}}{\lambda_{\pi}}\right)^2\]
- property n¶
value of hybridization number n, see equation (47)
\[n = 3m + 2\]
- property 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.
- property 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
- property 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)[source]¶
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)[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
- property matrix¶
Compute and return the sigma-orbital hybridization numbers n1, n2 and n3
- property u_pi¶
Return vector \(u_{\pi}\) as the basis of the zero space of the matrix M. This unitary vector support the POAV2 vector.
- property 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.
- property 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.
- property 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)[source]¶
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.