shape_measure
Continuous shape measures of coordination polyhedra.
How far a set of ligand positions is from an ideal polyhedron (Pinsky and Avnir, Inorg. Chem. 37, 5575 (1998); Alvarez et al., Coord. Chem. Rev. 249, 1693 (2005)):
S(Q, P) = 100 min over R, s, pi of sum_i |q_i - s R p_pi(i)|^2 / sum_i |q_i|^2
over rotations R, scales s and assignments pi of ligands to vertices, with the ligands Q and the vertices P each centred on their own centroid. S is 0 for the ideal shape and at most 100. Only the ligands count: the central atom is not a vertex, so where it sits plays no part.
With the optimal scale the measure is 100 (1 - c^2), where c is the
largest correlation sum q . R p / (|Q| |P|) over R and pi. So S(Q, P) is
symmetric in Q and P, and for a fixed assignment the best rotation is Kabsch's,
one 3x3 SVD. Up to EXACT_MAX vertices every assignment is tried. Beyond, the
assignment is the linear assignment problem for a fixed rotation, so the
two are alternated to a local optimum from many random rotations.
The ideal shapes in IDEAL_SHAPES are centred and scaled to a mean vertex
distance of 1, and named as in SHAPE where they are the same shape. Johnson
solids (names starting with J) have all their edges equal.
shape_match also returns the fit itself (which vertex each ligand goes to,
the rotation and scale), and coordination_shapes measures every site of a
crystal or molecule from its bonded (or nearest) neighbours.
ShapeMatch
Bases: NamedTuple
The best fit of an ideal polyhedron to a set of ligands.
Attributes:
| Name | Type | Description |
|---|---|---|
measure |
float
|
S, from 0 (the ideal shape) to 100 |
vertices |
ndarray
|
(n, 3) the ideal shape's vertices, centred |
assignment |
ndarray
|
(n,) the vertex each ligand is matched to |
rotation |
ndarray
|
(3, 3) proper rotation taking the vertices onto the ligands |
scale |
float
|
the factor scaling the rotated vertices to the ligands |
centre |
ndarray
|
(3,) the ligands' centroid |
Source code in chmpy/descriptors/shape_measure.py
ideal
property
(n, 3) the closest ideal polyhedron, one vertex for each ligand
continuous_shape_measure(ligands, shape, **kwargs)
The continuous shape measure of ligands against an ideal polyhedron.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ligands
|
(n, 3) ligand positions |
required | |
shape
|
a name from |
required | |
**kwargs
|
passed to |
{}
|
Returns:
| Type | Description |
|---|---|
float
|
S, from 0 (the ideal shape) to 100 |
Source code in chmpy/descriptors/shape_measure.py
coordination_shapes(structure, *, sites=None, n=None, tolerance=0.4, **kwargs)
The shape measures of each site's coordination polyhedron.
The ligands are a site's bonded neighbours (covalent radii plus
tolerance), or its n nearest neighbours when n is given.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
structure
|
a |
required | |
sites
|
which sites to measure, by index; by default every site with an ideal shape for its coordination number |
None
|
|
n
|
use the n nearest neighbours instead of the bonded ones |
None
|
|
tolerance
|
float
|
bonding tolerance, Angstroms |
0.4
|
**kwargs
|
passed to |
{}
|
Returns:
| Type | Description |
|---|---|
dict[int, dict[str, float]]
|
{site: {shape: S}}, each site's shapes best first. Requested sites |
dict[int, dict[str, float]]
|
with no ideal shape for their coordination number are refused. |
Source code in chmpy/descriptors/shape_measure.py
shape_match(ligands, shape, *, exact_max=EXACT_MAX, starts=STARTS, seed=0)
The best fit of an ideal polyhedron to a set of ligands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ligands
|
(n, 3) ligand positions, e.g. relative to the central atom; any origin, orientation and scale give the same measure |
required | |
shape
|
a name from |
required | |
exact_max
|
int
|
try every assignment up to this many vertices |
EXACT_MAX
|
starts
|
int
|
random starting rotations for the heuristic beyond that |
STARTS
|
seed
|
for the starting rotations |
0
|
Returns:
| Type | Description |
|---|---|
ShapeMatch
|
ShapeMatch |
Source code in chmpy/descriptors/shape_measure.py
shape_measures(ligands, **kwargs)
The measure against every ideal shape with as many vertices, best first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ligands
|
(n, 3) ligand positions |
required | |
**kwargs
|
passed to |
{}
|