Skip to content

Shape descriptors

This module contains functions to compute descriptors of the shape of a nanoparticle. These are generally derived from either the inertia tensor or the gyration tensor.

snow.descriptors.shape_descriptors

eccentricity(coords, round_step=None)

Compute the eccentricity (smallest/largest bounding box dimension), a measure of shape anisotropy.

Parameters:

Name Type Description Default
coords

Coordinates of the atoms in your systems.

 required
round_step

precision for rounding - optional

 None

Returns:

Name Type Description
ratio float

computed eccentricity
Source code in snow/descriptors/shape_descriptors.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def eccentricity(coords, round_step=None):
    """
    Compute the eccentricity (smallest/largest bounding box dimension), a measure of shape anisotropy.

    Parameters
    -----------
    coords: ndarray(n_atoms, 3) 
        Coordinates of the atoms in your systems.
    round_step: float, optional
        precision for rounding - optional

    Returns
    -------
    ratio : float
        computed eccentricity
    """

    frame_coords = np.atleast_2d(coords)  # ensures array 2D

    if frame_coords.shape[0] < 2:
        # too few atoms to compute the bounding box
        return np.nan

    min_values = frame_coords.min(axis=0)
    max_values = frame_coords.max(axis=0)

    length_x = max_values[0] - min_values[0]
    length_y = max_values[1] - min_values[1]
    length_z = max_values[2] - min_values[2]

    largest_dimension = max(length_x, length_y, length_z)
    smallest_dimension = min(length_x, length_y, length_z)

    ratio = smallest_dimension / largest_dimension

    if round_step is not None:
        ratio = round(ratio / round_step) * round_step

    return ratio

center_of_mass(elements, coords)

Calculate the center of mass for a given frame of coordinates.

Atomic masses are read from snow.misc.constants and used as weights for the weighted average of positions.

Parameters:

Name Type Description Default
elements list or ndarray

List of element symbols corresponding to the atoms, for weighted sum on masses

 required
coords ndarray

Array of atomic coordinates of shape ( n_atoms, 3).

 required

Returns:

Name Type Description
com ndarray

The center of mass as a 3D vector (x_{com}, y_{com}, z_{com}).
Source code in snow/descriptors/shape_descriptors.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def center_of_mass(elements: list[str], coords: np.ndarray) -> np.ndarray:
    """
    Calculate the center of mass for a given frame of coordinates.

    Atomic masses are read from `snow.misc.constants` and used as weights for the 
    weighted average of positions.

    Parameters
    ----------
    elements : list or np.ndarray
        List of element symbols corresponding to the atoms, for weighted sum on masses
    coords : np.ndarray
        Array of atomic coordinates of shape ( n_atoms, 3).

    Returns
    -------
    com : np.ndarray 
        The center of mass as a 3D vector (x_{com}, y_{com}, z_{com}).
    """

    # Get the masses of the elements
    masses = np.array([mass[e] for e in elements])

    # Compute the total mass
    total_mass = np.sum(masses)

    # Calculate the weighted average of coordinates
    com = np.sum(coords * masses[:, None], axis=0) / total_mass

    return com

geometric_com(coords)

Computes the geometric center of mass (average of the coordinates)

Computes the average of the coordinates, which is the geometrical center of mass (thus, not considering different weights due to different atomic masses)

Parameters:

Name Type Description Default
coords ndarray

Array of atomic coordinates of shape ( n_atoms, 3).

 required

Returns:

Name Type Description
gcom ndarray

The geometric center of mass as a 3D vector (x_{com}, y_{com}, z_{com}).
Source code in snow/descriptors/shape_descriptors.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def geometric_com(coords: np.ndarray):
    """
    Computes the geometric center of mass (average of the coordinates)

    Computes the average of the coordinates, which is the geometrical center of mass
    (thus, not considering different weights due to different atomic masses)

    Parameters
    ----------
    coords : np.ndarray
        Array of atomic coordinates of shape ( n_atoms, 3).

    Returns
    -------
    gcom : np.ndarray 
        The geometric center of mass as a 3D vector (x_{com}, y_{com}, z_{com}).
    """

    gcom = np.mean(coords, axis=0)
    return gcom

gyr_tensor(positions)

Computes the gyration tensor for a given set of coordinates. This is done in the center of positions reference system.

Parameters:

Name Type Description Default
positions ndarray

(n,3) Array of the coordinates of the atoms forming the system.

 required

Returns:

Name Type Description
tensor ndarray

3x3 gyration tensor
Source code in snow/descriptors/shape_descriptors.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def gyr_tensor(positions):
    """ 
    Computes the gyration tensor for a given set of coordinates.
    This is done in the center of positions reference system.

    Parameters
    ----------
    positions : ndarray
        (n,3) Array of the coordinates of the atoms forming the system.

    Returns
    -------
    tensor : np.ndarray
        3x3 gyration tensor
    """

    centered = positions - geometric_com(positions)

    Sxx = np.average(centered[:,0]*centered[:,0])
    Syy = np.average(centered[:,1]*centered[:,1])
    Szz = np.average(centered[:,2]*centered[:,2])
    Sxy = np.average(centered[:,0]*centered[:,1])
    Sxz = np.average(centered[:,0]*centered[:,2])
    Syz = np.average(centered[:,1]*centered[:,2])

    return np.array([[Sxx, Sxy, Sxz], [Sxy, Syy, Syz], [Sxz, Syz, Szz]])

gyr_desc_from_tensor(gyration_tensor)

Computes general shape descriptors (asphericity, acylindricity, relative shape anisotropy) from the gyration tensor.

Parameters:

Name Type Description Default
gyration_tensor ndarray

3x3 gyration tensor

 required

Returns:

Name Type Description
b float

asphericity
c float

acylindricity
k float

relative shape anisotropy
Source code in snow/descriptors/shape_descriptors.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def gyr_desc_from_tensor(gyration_tensor):
    """ 
    Computes general shape descriptors (asphericity, acylindricity, relative shape anisotropy) from the gyration tensor.

    Parameters
    ----------
    gyration_tensor : ndarray
        3x3 gyration tensor

    Returns
    -------
    b : float
        asphericity
    c : float
        acylindricity
    k : float
        relative shape anisotropy
    """

    eigenvalues, eigenvectors = np.linalg.eig(gyration_tensor)
    eigenvalues = np.sort(eigenvalues)

    l1 = eigenvalues[0]
    l2 = eigenvalues[1]
    l3 = eigenvalues[2]

    b = l3 - (l1 + l2)/2.   #asphericity
    c = l2 - l1             #acilindricity
    k = 3.*(l1*l1 + l2*l2 + l3*l3)/2./((l1 + l2 + l3)**2.) -0.5   #relative shape anisotropy

    return b, c, k

gyr_desc(positions)

Computes general shape descriptors obtained from the gyration tensor.

Computes asphericity, acylindricity, and relative shape anisotropy from the provided atomic positions.

Parameters:

Name Type Description Default
positions ndarray

(n,3) Array of the coordinates of the atoms forming the system.

 required

Returns:

Name Type Description
b float

asphericity
c float

acylindricity
k float

relative shape anisotropy
Source code in snow/descriptors/shape_descriptors.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def gyr_desc(positions):
    """ 
    Computes general shape descriptors obtained from the gyration tensor.

    Computes asphericity, acylindricity, and relative shape anisotropy from the provided atomic positions.

    Parameters
    ----------
    positions : ndarray
        (n,3) Array of the coordinates of the atoms forming the system.

    Returns
    -------
    b : float
        asphericity
    c : float
        acylindricity
    k : float
        relative shape anisotropy
    """

    return gyr_desc_from_tensor(gyr_tensor(positions))

inertia_tensor(positions, masses=None, COM=True)

Computes the inertia tensor for a given set of coordinates.

This can be done in the center of mass reference system or in the raw provided coordinates - switch with the boolean COM variable

Parameters:

Name Type Description Default
positions ndarray

Nx3 Array of the coordinates of the atoms in the system.

 required
masses ndarray

Masses of the atoms, shape (n_atoms,). If None (default), all masses are set to 1 (equal masses).

 None
COM bool

if True, the calculation is performed in the center of mass reference system. Otherwise, it is performed with the raw coordinates provided by the user

 True

Returns:

Name Type Description
tensor ndarray

3x3 inertia tensor
Source code in snow/descriptors/shape_descriptors.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
def inertia_tensor(positions, masses=None, COM=True):

    """ 
    Computes the inertia tensor for a given set of coordinates.

    This can be done in the center of mass reference system or in the raw provided 
    coordinates - switch with the boolean `COM` variable

    Parameters
    ----------
    positions : ndarray
        Nx3 Array of the coordinates of the atoms in the system.
    masses : ndarray, optional
        Masses of the atoms, shape (n_atoms,). If None (default), all masses
        are set to 1 (equal masses).
    COM : bool
        if True, the calculation is performed in the center of mass reference system. Otherwise, it 
        is performed with the raw coordinates provided by the user

    Returns
    -------
    tensor : np.ndarray
        3x3 inertia tensor
    """

    if masses is None:
        masses = np.ones(positions.shape[0])

    if COM:
        centered = positions - np.average(positions, axis=0, weights=masses)
    else:
        centered = positions

    Ixx = np.sum(masses * (centered[:, 1]**2 + centered[:, 2]**2))
    Iyy = np.sum(masses * (centered[:, 0]**2 + centered[:, 2]**2))
    Izz = np.sum(masses * (centered[:, 0]**2 + centered[:, 1]**2))
    Ixy = np.sum(-masses*centered[:,0]*centered[:,1])
    Ixz = np.sum(-masses*centered[:,0]*centered[:,2])
    Iyz = np.sum(-masses*centered[:,1]*centered[:,2])

    return np.array([[Ixx, Ixy, Ixz], [Ixy, Iyy, Iyz], [Ixz, Iyz, Izz]])

aspect_ratio_from_tensor(inertia_tensor)

Computes the aspect ratio, a shape descriptor obtained from the inertia tensor.

Parameters:

Name Type Description Default
inertia_tensor ndarray

3x3 inertia tensor

 required

Returns:

Name Type Description
ar float

aspect ratio
Source code in snow/descriptors/shape_descriptors.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
def aspect_ratio_from_tensor(inertia_tensor):
    """
    Computes the aspect ratio, a shape descriptor obtained from the inertia tensor.

    Parameters
    ----------
    inertia_tensor : ndarray
        3x3 inertia tensor

    Returns
    -------
    ar : float
        aspect ratio
    """

    eigenvalues, eigenvectors = np.linalg.eig(inertia_tensor)
    eigenvalues = np.sort(eigenvalues)

    return  eigenvalues[0]/eigenvalues[2]

aspect_ratio(positions, masses=None, COM=True)

Computes the aspect ratio, a shape descriptor derived from the inertia tensor, for a given set of coordinates.

This can be done in the center of mass reference system or in the raw provided coordinates (switch with the COM boolean variable).

Parameters:

Name Type Description Default
positions ndarray

Nx3 Array of the coordinates of the atoms in the system.

 required
masses ndarray

array of the masses of the atoms in the system. Default to all equal masses.

 None
COM bool

if True, the calculation is performed in the center of mass reference system. Otherwise, it is performed with the raw coordinates provided by the user

 True

Returns:

Name Type Description
ar float

aspect ratio
Source code in snow/descriptors/shape_descriptors.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
def aspect_ratio(positions, masses=None, COM=True):
    """ 
    Computes the aspect ratio, a shape descriptor derived from the inertia tensor, for a given set of coordinates. \n

    This can be done in the center of mass reference system or in the raw provided coordinates (switch with the COM
    boolean variable).

    Parameters
    ----------
    positions : ndarray
        Nx3 Array of the coordinates of the atoms in the system.
    masses : ndarray
        array of the masses of the atoms in the system. Default to all equal masses.
    COM : bool
        if True, the calculation is performed in the center of mass reference system. Otherwise, it 
        is performed with the raw coordinates provided by the user

    Returns
    -------
    ar : float
        aspect ratio
    """

    return aspect_ratio_from_tensor(inertia_tensor(positions, masses, COM))

gyr_rad(positions, masses=None)

Computes the gyration radius, which corresponds to the average weighted by the masses of

atoms in the system.

Parameters:

Name Type Description Default
positions ndarray

Nx3 Array of the coordinates of the atoms in the system.

 required
masses ndarray

array of the masses of the atoms in the system. Default to all equal masses

 None

Returns:

Name Type Description
gr float

Gyration radius
Source code in snow/descriptors/shape_descriptors.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
def gyr_rad(positions, masses=None):
    """
    Computes the gyration radius, which corresponds to the average <r^2> weighted by the masses of\n
    atoms in the system.

    Parameters
    ----------
    positions : ndarray
        Nx3 Array of the coordinates of the atoms in the system.
    masses : ndarray
        array of the masses of the atoms in the system. Default to all equal masses

    Returns
    -------
    gr : float
        Gyration radius
    """

    if(masses is None):
        masses=np.ones(positions.shape[0])

    centered = positions - np.average(positions, axis=0, weights=masses)

    return np.sqrt( np.average( np.sum(centered**2, axis=1), weights=masses ) )