Skip to content

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
class ShapeMatch(NamedTuple):
    """The best fit of an ideal polyhedron to a set of ligands.

    Attributes:
        measure: S, from 0 (the ideal shape) to 100
        vertices: (n, 3) the ideal shape's vertices, centred
        assignment: (n,) the vertex each ligand is matched to
        rotation: (3, 3) proper rotation taking the vertices onto the ligands
        scale: the factor scaling the rotated vertices to the ligands
        centre: (3,) the ligands' centroid
    """

    measure: float
    vertices: np.ndarray
    assignment: np.ndarray
    rotation: np.ndarray
    scale: float
    centre: np.ndarray

    @property
    def ideal(self) -> np.ndarray:
        "(n, 3) the closest ideal polyhedron, one vertex for each ligand"
        moved = self.vertices[self.assignment] @ self.rotation.T
        return self.scale * moved + self.centre

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 IDEAL_SHAPES, or (n, 3) vertices

required
**kwargs

passed to shape_match

{}

Returns:

Type Description
float

S, from 0 (the ideal shape) to 100

Source code in chmpy/descriptors/shape_measure.py
def continuous_shape_measure(ligands, shape, **kwargs) -> float:
    """The continuous shape measure of ligands against an ideal polyhedron.

    Args:
        ligands: (n, 3) ligand positions
        shape: a name from `IDEAL_SHAPES`, or (n, 3) vertices
        **kwargs: passed to `shape_match`

    Returns:
        S, from 0 (the ideal shape) to 100
    """
    return shape_match(ligands, shape, **kwargs).measure

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 Crystal (one site per asymmetric unit atom) or a Molecule (one per atom)

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 shape_match

{}

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
def coordination_shapes(
    structure, *, sites=None, n=None, tolerance: float = 0.4, **kwargs
) -> dict[int, dict[str, float]]:
    """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.

    Args:
        structure: a `Crystal` (one site per asymmetric unit atom) or a
            `Molecule` (one per atom)
        sites: which sites to measure, by index; by default every site with
            an ideal shape for its coordination number
        n: use the n nearest neighbours instead of the bonded ones
        tolerance: bonding tolerance, Angstroms
        **kwargs: passed to `shape_match`

    Returns:
        {site: {shape: S}}, each site's shapes best first. Requested sites
        with no ideal shape for their coordination number are refused.
    """
    ligands = _ligand_vectors(structure, n, tolerance)
    counts = {len(v) for v in IDEAL_SHAPES.values()}
    if sites is None:
        sites = [k for k, v in enumerate(ligands) if len(v) in counts]
    return {int(k): shape_measures(ligands[k], **kwargs) for k in sites}

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 IDEAL_SHAPES, or (n, 3) vertices

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
def shape_match(
    ligands, shape, *, exact_max: int = EXACT_MAX, starts: int = STARTS, seed=0
) -> ShapeMatch:
    """The best fit of an ideal polyhedron to a set of ligands.

    Args:
        ligands: (n, 3) ligand positions, e.g. relative to the central atom;
            any origin, orientation and scale give the same measure
        shape: a name from `IDEAL_SHAPES`, or (n, 3) vertices
        exact_max: try every assignment up to this many vertices
        starts: random starting rotations for the heuristic beyond that
        seed: for the starting rotations

    Returns:
        ShapeMatch
    """
    q, p, centre = _centred(ligands, shape)
    if len(q) <= exact_max:
        assignment = _best_exact(q, p)
    else:
        assignment = _best_heuristic(q, p, starts, seed)
    rotation = _rotation(p[assignment], q)
    overlap = float(np.sum(q * (p[assignment] @ rotation.T)))
    c = overlap / (np.linalg.norm(q) * np.linalg.norm(p))
    return ShapeMatch(
        measure=float(100 * (1 - min(c, 1.0) ** 2)),
        vertices=p,
        assignment=assignment,
        rotation=rotation,
        scale=overlap / float(np.sum(p * p)),
        centre=centre,
    )

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 shape_match

{}
Source code in chmpy/descriptors/shape_measure.py
def shape_measures(ligands, **kwargs) -> dict[str, float]:
    """The measure against every ideal shape with as many vertices, best first.

    Args:
        ligands: (n, 3) ligand positions
        **kwargs: passed to `shape_match`
    """
    n = len(ligands)
    measures = {
        name: continuous_shape_measure(ligands, vertices, **kwargs)
        for name, vertices in IDEAL_SHAPES.items()
        if len(vertices) == n
    }
    if not measures:
        raise ValueError(f"no ideal shape has {n} vertices")
    return dict(sorted(measures.items(), key=lambda item: item[1]))