amd.calculate module

Functions for calculating the average minimum distance (AMD) and point-wise distance distribution (PDD) isometric invariants of periodic crystals and finite sets.

amd.calculate.AMD(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]], k: int) → numpy.ndarray

The AMD of a periodic set (crystal) up to k.

Parameters

  • periodic_set (periodicset.PeriodicSet or tuple of numpy.ndarray s) – A periodic set represented by a periodicset.PeriodicSet or by a tuple (motif, cell) with coordinates in Cartesian form and a square unit cell.

  • k (int) – Length of the AMD returned; the number of neighbours considered for each atom in the unit cell to make the AMD.

Returns

A numpy.ndarray shape (k, ), the AMD of periodic_set up to k.

Return type

numpy.ndarray

Examples

Make list of AMDs with k = 100 for crystals in data.cif:

amds = []
for periodic_set in amd.CifReader('data.cif'):
    amds.append(amd.AMD(periodic_set, 100))

Make list of AMDs with k = 10 for crystals in these CSD refcode families:

amds = []
for periodic_set in amd.CSDReader(['HXACAN', 'ACSALA'], families=True):
    amds.append(amd.AMD(periodic_set, 10))

Manually pass a periodic set as a tuple (motif, cell):

# simple cubic lattice
motif = np.array([[0,0,0]])
cell = np.array([[1,0,0], [0,1,0], [0,0,1]])
cubic_amd = amd.AMD((motif, cell), 100)
amd.calculate.PDD(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]], k: int, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001, return_row_groups: bool = False) → numpy.ndarray

The PDD of a periodic set (crystal) up to k.

Parameters

  • periodic_set (periodicset.PeriodicSet tuple of numpy.ndarray s) – A periodic set represented by a periodicset.PeriodicSet or by a tuple (motif, cell) with coordinates in Cartesian form and a square unit cell.

  • k (int) – The returned PDD has k+1 columns, an additional first column for row weights. k is the number of neighbours considered for each atom in the unit cell to make the PDD.

  • lexsort (bool, default True) – Lexicographically order the rows. Default True.

  • collapse (bool, default True) – Collapse repeated rows (within the tolerance collapse_tol). Default True.

  • collapse_tol (float, default 1e-4) – If two rows have all elements closer than collapse_tol, they are merged and weights are given to rows in proportion to the number of times they appeared. Default is 0.0001.

  • return_row_groups (bool, default False) – Return data about which PDD rows correspond to which points. If True, a tuple is returned (pdd, groups) where groups[i] contains the indices of the point(s) corresponding to pdd[i]. Note that these indices are for the asymmetric unit of the set, whose indices in periodic_set.motif are accessible through periodic_set.asymmetric_unit.

Returns

A numpy.ndarray with k+1 columns, the PDD of periodic_set up to k. The first column contains the weights of rows. If return_row_groups is True, returns a tuple (numpy.ndarray, list).

Return type

numpy.ndarray

Examples

Make list of PDDs with k=100 for crystals in data.cif:

pdds = []
for periodic_set in amd.CifReader('data.cif'):
    # do not lexicographically order rows
    pdds.append(amd.PDD(periodic_set, 100, lexsort=False))

Make list of PDDs with k=10 for crystals in these CSD refcode families:

pdds = []
for periodic_set in amd.CSDReader(['HXACAN', 'ACSALA'], families=True):
    # do not collapse rows
    pdds.append(amd.PDD(periodic_set, 10, collapse=False))

Manually pass a periodic set as a tuple (motif, cell):

# simple cubic lattice
motif = np.array([[0,0,0]])
cell = np.array([[1,0,0], [0,1,0], [0,0,1]])
cubic_amd = amd.PDD((motif, cell), 100)
amd.calculate.PDD_to_AMD(pdd: numpy.ndarray) → numpy.ndarray

Calculates an AMD from a PDD. Faster than computing both from scratch.

Parameters

pdd (numpy.ndarray) – The PDD of a periodic set.

Returns

The AMD of the periodic set.

Return type

numpy.ndarray

amd.calculate.AMD_finite(motif: numpy.ndarray) → numpy.ndarray

The AMD of a finite m-point set up to k = m-1.

Parameters

motif (numpy.ndarray) – Coordinates of a set of points.

Returns

A vector length m-1 (where m is the number of points), the AMD of motif.

Return type

numpy.ndarray

Examples

The AMD distance (L-infinity) between finite trapezium and kite point sets:

trapezium = np.array([[0,0],[1,1],[3,1],[4,0]])
kite      = np.array([[0,0],[1,1],[1,-1],[4,0]])

trap_amd = amd.AMD_finite(trapezium)
kite_amd = amd.AMD_finite(kite)

l_inf_dist = np.amax(np.abs(trap_amd - kite_amd))
amd.calculate.PDD_finite(motif: numpy.ndarray, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001, return_row_groups: bool = False) → numpy.ndarray

The PDD of a finite m-point set up to k = m-1.

Parameters

  • motif (numpy.ndarray) – Coordinates of a set of points.

  • lexsort (bool, default True) – Whether or not to lexicographically order the rows. Default True.

  • collapse (bool, default True) – Whether or not to collapse repeated rows (within the tolerance collapse_tol). Default True.

  • collapse_tol (float, default 1e-4) – If two rows have all elements closer than collapse_tol, they are merged and weights are given to rows in proportion to the number of times they appeared. Default is 0.0001.

  • return_row_groups (bool, default False) – Whether to return data about which PDD rows correspond to which points. If True, a tuple is returned (pdd, groups) where groups[i] contains the indices of the point(s) corresponding to pdd[i].

Returns

A numpy.ndarray with m columns (where m is the number of points), the PDD of motif. The first column contains the weights of rows.

Return type

numpy.ndarray

Examples

Find PDD distance between finite trapezium and kite point sets:

trapezium = np.array([[0,0],[1,1],[3,1],[4,0]])
kite      = np.array([[0,0],[1,1],[1,-1],[4,0]])

trap_pdd = amd.PDD_finite(trapezium)
kite_pdd = amd.PDD_finite(kite)

dist = amd.EMD(trap_pdd, kite_pdd)
amd.calculate.PDD_reconstructable(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]], lexsort: bool = True) → numpy.ndarray

The PDD of a periodic set with k (no of columns) large enough such that the periodic set can be reconstructed from the PDD.

Parameters

  • periodic_set (periodicset.PeriodicSet tuple of numpy.ndarray s) – A periodic set represented by a periodicset.PeriodicSet or by a tuple (motif, cell) with coordinates in Cartesian form and a square unit cell.

  • lexsort (bool, default True) – Whether or not to lexicographically order the rows. Default True.

Returns

An ndarray, the PDD of periodic_set with enough columns to be reconstructable.

Return type

numpy.ndarray

amd.calculate.PPC(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]]) → float

The point packing coefficient (PPC) of periodic_set.

The PPC is a constant of any periodic set determining the asymptotic behaviour of its AMD and PDD. As \(k \rightarrow \infty\), the ratio \(\text{AMD}_k / \sqrt[n]{k}\) converges to the PPC, as does any row of its PDD.

For a unit cell \(U\) and \(m\) motif points in \(n\) dimensions,

\[\text{PPC} = \sqrt[n]{\frac{\text{Vol}[U]}{m V_n}}\]

where \(V_n\) is the volume of a unit sphere in \(n\) dimensions.

Parameters

periodic_set (periodicset.PeriodicSet or tuple of) – numpy.ndarray s (motif, cell) representing the periodic set in Cartesian form.

Returns

The PPC of periodic_set.

Return type

float

amd.calculate.AMD_estimate(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]], k: int) → numpy.ndarray

Calculates an estimate of AMD based on the PPC, using the fact that

\[\lim_{k\rightarrow\infty}\frac{\text{AMD}_k}{\sqrt[n]{k}} = \sqrt[n]{\frac{\text{Vol}[U]}{m V_n}}\]

where \(U\) is the unit cell, \(m\) is the number of motif points and \(V_n\) is the volume of a unit sphere in \(n\)-dimensional space.