amd.calculate module

Functions to calculate AMDs and PDDs.

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

Computes an AMD vector up to k from a periodic set.

Parameters

periodic_set (periodicset.PeriodicSet or tuple of ndarrays) – A periodic set represented by a periodicset.PeriodicSet object or by a tuple (motif, cell) with coordinates in Cartesian form.
k (int) – Length of AMD returned.

Returns

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

Return type

ndarray

Examples

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

amds = []
for periodic_set in amd.CifReader('mycif.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, order: int = 1, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001) → numpy.ndarray

Computes a PDD up to k from a periodic set.

Parameters

periodic_set (periodicset.PeriodicSet or tuple of ndarrays) – A periodic set represented by a periodicset.PeriodicSet object or by a tuple (motif, cell) with coordinates in Cartesian form.
k (int) – Number of columns in the PDD, plus one for the first column of weights.
order (int) – Order of the PDD, default 1. See papers for a description of higher-order PDDs.
lexsort (bool, optional) – Whether or not to lexicographically order the rows. Default True.
collapse (bool, optional) – Whether or not to collapse identical rows (within a tolerance). Default True.
collapse_tol (float) – If two rows have all entries closer than collapse_tol, they get collapsed. Default is 1e-4.

Returns

An ndarray with k+1 columns, the PDD of periodic_set up to k.

Return type

ndarray

Examples

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

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

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):
    pdds.append(amd.PDD(periodic_set, 10, collapse=False))  # do not collapse rows

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.finite_AMD(motif: numpy.ndarray)

Computes the AMD of a finite point set (up to k = len(motif) - 1).

Parameters: motif (ndarray) – Cartesian coordinates of points in a set. Shape (n_points, dimensions)
Returns: An vector length len(motif) - 1, the AMD of motif.
Return type: ndarray

Examples

Find AMD 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_amd = amd.finite_AMD(trapezium)
kite_amd = amd.finite_AMD(kite)

dist = amd.AMD_pdist(trap_amd, kite_amd)

amd.calculate.finite_PDD(motif: numpy.ndarray, order: int = 1, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001)

Computes the PDD of a finite point set (up to k = len(motif) - 1).

Parameters

motif (ndarray) – Cartesian coordinates of points in a set. Shape (n_points, dimensions)
order (int) – Order of the PDD, default 1. See papers for a description of higher-order PDDs.
lexsort (bool, optional) – Whether or not to lexicographically order the rows. Default True.
collapse (bool, optional) – Whether or not to collapse identical rows (within a tolerance). Default True.
collapse_tol (float) – If two rows have all entries closer than collapse_tol, they get collapsed. Default is 1e-4.

Returns

An ndarray with len(motif) columns, the PDD of motif.

Return type

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.finite_PDD(trapezium)
kite_pdd = amd.finite_PDD(kite)

dist = amd.emd(trap_pdd, kite_pdd)

amd.calculate.PDD_to_AMD(pdd: numpy.ndarray) → numpy.ndarray

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

Parameters: pdd (np.ndarray) – The PDD of a periodic set.
Returns: The AMD of the periodic set.
Return type: ndarray

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

Calculate the point packing coefficient (PPC) of periodic_set.

The PPC is a constant of any periodic set determining the asymptotic behaviour of its AMD or PDD as \(k \rightarrow \infty\).

As \(k \rightarrow \infty\), the ratio \(\text{AMD}_k / \sqrt[n]{k}\) approaches 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) – ndarrays (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.