Skip to content

shape_descriptors

Shape descriptor calculations for Crystal structures.

atom_group_shape_descriptors(crystal, atoms, l_max=5, radius=6.0)

Calculate the shape descriptors[1,2] for the given atomic group in this crystal.

Parameters:

Name Type Description Default
crystal

Crystal instance

 required
atoms Tuple

atoms to include in the as the 'inside' of the shape description.

 required
l_max int

maximum level of angular momenta to include in the spherical harmonic transform of the molecular shape function.

 5
radius float

maximum distance (Angstroms) to include surroundings in the shape description

 6.0

Returns:

Type Description
ndarray

shape description vector

References: 

[1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
    https://dx.doi.org/10.1038/srep22204
[2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
    https://dx.doi.org/10.1002/anie.201906602

Source code in chmpy/crystal/shape_descriptors.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
def atom_group_shape_descriptors(crystal, atoms, l_max=5, radius=6.0) -> np.ndarray:
    """Calculate the shape descriptors[1,2] for the given atomic
    group in this crystal.

    Args:
        crystal: Crystal instance
        atoms (Tuple): atoms to include in the as the 'inside'
            of the shape description.
        l_max (int, optional): maximum level of angular momenta to include
            in the spherical harmonic transform of the molecular shape function.
        radius (float, optional): maximum distance (Angstroms) to include
            surroundings in the shape description

    Returns:
        shape description vector

    References:
    ```
    [1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
        https://dx.doi.org/10.1038/srep22204
    [2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
        https://dx.doi.org/10.1002/anie.201906602
    ```
    """
    from chmpy.shape import SHT, stockholder_weight_descriptor

    sph = SHT(l_max)
    inside, outside = crystal.atom_group_surroundings(atoms, radius=radius)
    m = Molecule.from_arrays(*inside)
    c = np.array(m.centroid, dtype=np.float32)
    dists = np.linalg.norm(m.positions - c, axis=1)
    bounds = np.min(dists) / 2, np.max(dists) + 10.0
    return np.asarray(
        stockholder_weight_descriptor(
            sph, *inside, *outside, origin=c, bounds=bounds
        )
    )

atomic_shape_descriptors(crystal, l_max=5, radius=6.0, return_coefficients=False, with_property=None)

Calculate the shape descriptors[1,2] for all symmetry unique atoms in this crystal.

Parameters:

Name Type Description Default
crystal

Crystal instance

 required
l_max int

maximum level of angular momenta to include in the spherical harmonic transform of the molecular shape function.

 5
radius float

maximum distance (Angstroms) to include surroundings in the shape description

 6.0
with_property str

name of the surface property to include in the shape description

 None
return_coefficients bool

also return the spherical harmonic coefficients

 False

Returns:

Type Description
ndarray

shape description vector

References: 

[1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
    https://dx.doi.org/10.1038/srep22204
[2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
    https://dx.doi.org/10.1002/anie.201906602

Source code in chmpy/crystal/shape_descriptors.py 
180
181
182
183
184
185
186
187
188
189
190
191
192
193
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
235
236
237
238
239
def atomic_shape_descriptors(
    crystal, l_max=5, radius=6.0, return_coefficients=False, with_property=None
) -> np.ndarray:
    """
    Calculate the shape descriptors[1,2] for all symmetry unique
    atoms in this crystal.

    Args:
        crystal: Crystal instance
        l_max (int, optional): maximum level of angular momenta to include
            in the spherical harmonic transform of the molecular shape function.
        radius (float, optional): maximum distance (Angstroms) to include
            surroundings in the shape description
        with_property (str, optional): name of the surface property to include
            in the shape description
        return_coefficients (bool, optional): also return the spherical
            harmonic coefficients

    Returns:
        shape description vector

    References:
    ```
    [1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
        https://dx.doi.org/10.1038/srep22204
    [2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
        https://dx.doi.org/10.1002/anie.201906602
    ```
    """
    descriptors = []
    coeffs = []
    from chmpy.shape import SHT, stockholder_weight_descriptor

    sph = SHT(l_max)
    for surrounds in crystal.atomic_surroundings(radius=radius):
        n = surrounds["centre"]["element"]
        pos = surrounds["centre"]["cart_pos"]
        neighbour_els = surrounds["neighbours"]["element"]
        neighbour_pos = surrounds["neighbours"]["cart_pos"]

        ubound = Element[n].vdw_radius * 3 + 2.0
        desc = stockholder_weight_descriptor(
            sph,
            [n],
            [pos],
            neighbour_els,
            neighbour_pos,
            bounds=(0.15, ubound),
            coefficients=return_coefficients,
            with_property=with_property,
        )
        if return_coefficients:
            descriptors.append(desc[1])
            coeffs.append(desc[0])
        else:
            descriptors.append(desc)
    if return_coefficients:
        return np.asarray(coeffs), np.asarray(descriptors)
    else:
        return np.asarray(descriptors)

functional_group_shape_descriptors(crystal, l_max=5, radius=6.0, kind='carboxylic_acid')

Calculate the shape descriptors [1,2] for the all atoms in the functional group given for all symmetry unique molecules in this crystal.

Parameters:

Name Type Description Default
crystal

Crystal instance

 required
l_max int

maximum level of angular momenta to include in the spherical harmonic transform of the molecular shape function. (default: 5)

 5
radius float

maximum distance (Angstroms) of neighbouring atoms to include in stockholder weight calculation (default: 5)

 6.0
kind str

Identifier for the functional group type (default: 'carboxylic_acid')

 'carboxylic_acid'

Returns:

Type Description
ndarray

shape description vector

References: 

[1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
    https://dx.doi.org/10.1038/srep22204
[2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
    https://dx.doi.org/10.1002/anie.201906602

Source code in chmpy/crystal/shape_descriptors.py 
 9
10
11
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def functional_group_shape_descriptors(
    crystal, l_max=5, radius=6.0, kind="carboxylic_acid"
) -> np.ndarray:
    """
    Calculate the shape descriptors `[1,2]` for the all atoms in
    the functional group given for all symmetry unique molecules in this crystal.

    Args:
        crystal: Crystal instance
        l_max (int, optional): maximum level of angular momenta to include
            in the spherical harmonic transform of the molecular shape function.
            (default: 5)
        radius (float, optional): maximum distance (Angstroms) of neighbouring
            atoms to include in stockholder weight calculation (default: 5)
        kind (str, optional): Identifier for the functional group
            type (default: 'carboxylic_acid')

    Returns:
        shape description vector

    References:
    ```
    [1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
        https://dx.doi.org/10.1038/srep22204
    [2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
        https://dx.doi.org/10.1002/anie.201906602
    ```
    """
    descriptors = []
    from chmpy.shape import SHT, stockholder_weight_descriptor

    sph = SHT(l_max)
    for (
        in_els,
        in_pos,
        neighbour_els,
        neighbour_pos,
    ) in crystal.functional_group_surroundings(kind=kind, radius=radius):
        masses = np.asarray([Element[x].mass for x in in_els])
        c = np.sum(in_pos * masses[:, np.newaxis] / np.sum(masses), axis=0).astype(
            np.float32
        )
        dists = np.linalg.norm(in_pos - c, axis=1)
        bounds = np.min(dists) / 2, np.max(dists) + 10.0
        descriptors.append(
            stockholder_weight_descriptor(
                sph,
                in_els,
                in_pos,
                neighbour_els,
                neighbour_pos,
                origin=c,
                bounds=bounds,
            )
        )
    return np.asarray(descriptors)

molecular_shape_descriptors(crystal, l_max=5, radius=6.0, with_property=None, return_coefficients=False)

Calculate the molecular shape descriptors[1,2] for all symmetry unique molecules in this crystal.

Parameters:

Name Type Description Default
crystal

Crystal instance

 required
l_max int

maximum level of angular momenta to include in the spherical harmonic transform of the molecular shape function.

 5
radius float

maximum distance (Angstroms) to include surroundings in the shape description

 6.0
with_property str

name of the surface property to include in the shape description

 None
return_coefficients bool

also return the spherical harmonic coefficients

 False

Returns:

Type Description
ndarray

shape description vector

References: 

[1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
    https://dx.doi.org/10.1038/srep22204
[2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
    https://dx.doi.org/10.1002/anie.201906602

Source code in chmpy/crystal/shape_descriptors.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
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
167
168
169
170
171
172
173
174
175
176
177
def molecular_shape_descriptors(
    crystal, l_max=5, radius=6.0, with_property=None, return_coefficients=False
) -> np.ndarray:
    """
    Calculate the molecular shape descriptors[1,2] for all symmetry unique
    molecules in this crystal.

    Args:
        crystal: Crystal instance
        l_max (int, optional): maximum level of angular momenta to include
            in the spherical harmonic transform of the molecular shape function.
        radius (float, optional): maximum distance (Angstroms) to include
            surroundings in the shape description
        with_property (str, optional): name of the surface property to include
            in the shape description
        return_coefficients (bool, optional): also return the spherical
            harmonic coefficients

    Returns:
        shape description vector

    References:
    ```
    [1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
        https://dx.doi.org/10.1038/srep22204
    [2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
        https://dx.doi.org/10.1002/anie.201906602
    ```
    """
    descriptors = []
    coeffs = []
    from chmpy.shape import SHT, stockholder_weight_descriptor

    sph = SHT(l_max)
    for mol, neighbour_els, neighbour_pos in crystal.molecule_environments(
        radius=radius
    ):
        c = np.array(mol.centroid, dtype=np.float32)
        dists = np.linalg.norm(mol.positions - c, axis=1)
        bounds = np.min(dists) / 2, np.max(dists) + 10.0
        descriptor = stockholder_weight_descriptor(
            sph,
            mol.atomic_numbers,
            mol.positions,
            neighbour_els,
            neighbour_pos,
            origin=c,
            bounds=bounds,
            with_property=with_property,
            coefficients=return_coefficients,
        )

        if return_coefficients:
            coeffs.append(descriptor[0])
            descriptors.append(descriptor[1])
        else:
            descriptors.append(descriptor)
    if return_coefficients:
        return np.asarray(coeffs), np.asarray(descriptors)
    else:
        return np.asarray(descriptors)

molecule_shape_descriptors(crystal, mol, l_max=5, radius=6.0, with_property=None)

Calculate the molecular shape descriptors [1,2] for the provided molecule in the crystal.

Parameters:

Name Type Description Default
crystal

Crystal instance

 required
mol

Molecule instance

 required
l_max int

maximum level of angular momenta to include in the spherical harmonic transform of the molecular shape function.

 5
radius float

maximum distance (Angstroms) to include surroundings in the shape description

 6.0
with_property str

name of the surface property to include in the shape description

 None

Returns:

Type Description
ndarray

shape description vector

References: 

[1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
    https://dx.doi.org/10.1038/srep22204
[2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
    https://dx.doi.org/10.1002/anie.201906602

Source code in chmpy/crystal/shape_descriptors.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def molecule_shape_descriptors(
    crystal, mol, l_max=5, radius=6.0, with_property=None
) -> np.ndarray:
    """
    Calculate the molecular shape descriptors `[1,2]` for
    the provided molecule in the crystal.

    Args:
        crystal: Crystal instance
        mol: Molecule instance
        l_max (int, optional): maximum level of angular momenta to include
            in the spherical harmonic
            transform of the molecular shape function.
        radius (float, optional): maximum distance (Angstroms) to include
            surroundings in the shape description
        with_property (str, optional): name of the surface property to include
            in the shape description

    Returns:
        shape description vector

    References:
    ```
    [1] PR Spackman et al. Sci. Rep. 6, 22204 (2016)
        https://dx.doi.org/10.1038/srep22204
    [2] PR Spackman et al. Angew. Chem. 58 (47), 16780-16784 (2019)
        https://dx.doi.org/10.1002/anie.201906602
    ```
    """
    from chmpy.shape import SHT, stockholder_weight_descriptor

    sph = SHT(l_max)
    mol, neighbour_els, neighbour_pos = crystal.molecule_environment(
        mol, radius=radius
    )
    c = np.array(mol.centroid, dtype=np.float32)
    dists = np.linalg.norm(mol.positions - c, axis=1)
    bounds = np.min(dists) / 2, np.max(dists) + 10.0
    return stockholder_weight_descriptor(
        sph,
        mol.atomic_numbers,
        mol.positions,
        neighbour_els,
        neighbour_pos,
        origin=c,
        bounds=bounds,
        with_property=with_property,
    )