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(pset: amd.periodicset.PeriodicSet, k: int) numpy.ndarray[Any, numpy.dtype[numpy.floating]] ¶
Return the average minimum distance (AMD) of a periodic set (crystal).
The AMD of a periodic set is a geometry based descriptor independent of choice of motif and unit cell. It is a vector, the (weighted) average of the
PDD
matrix, which has one row for each (unique) point in the unit cell containing distances to k nearest neighbors.- Parameters
pset (
amd.PeriodicSet
) – A periodic set (crystal) consisting of a unit cell and motif of points.k (int) – The number of neighboring points (atoms) considered for each point in the unit cell.
- Returns
A
numpy.ndarray
shape(k, )
, the AMD ofpset
up to k.- Return type
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 create 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]]) periodic_set = amd.PeriodicSet(motif, cell) cubic_amd = amd.AMD(periodic_set, 100)
- amd.calculate.PDD(pset: amd.periodicset.PeriodicSet, k: int, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001, return_row_groups: bool = False) Union[numpy.ndarray[Any, numpy.dtype[numpy.floating]], Tuple[numpy.ndarray[Any, numpy.dtype[numpy.floating]], list]] ¶
Return the point-wise distance distribution (PDD) of a periodic set (crystal).
The PDD of a periodic set is a geometry based descriptor independent of choice of motif and unit cell. It is a matrix where each row corresponds to a point in the motif, containing a weight followed by distances to the k nearest neighbors of the point.
- Parameters
pset (
amd.PeriodicSet
) – A periodic set (crystal) consisting of a unit cell and motif of points.k (int) – The number of neighbors considered for each atom (point) in the unit cell. The returned matrix has k + 1 columns, the first column for weights of rows.
lexsort (bool, default True) – Lexicographically order the rows.
collapse (bool, default True) – Collapse repeated rows (within tolerance
collapse_tol
).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.return_row_groups (bool, default False) – If True, return a tuple
(pdd, groups)
wheregroups
contains information about which rows inpdd
correspond to which points. Ifpset.asym_unit
is None, thengroups[i]
contains indices of points inpset.motif
corresponding topdd[i]
. Otherwise, PDD rows correspond to points in the asymmetric unit, andgroups[i]
contains indices of points inpset.motif[pset.asym_unit]
.
- Returns
pdd – A
numpy.ndarray
with k+1 columns, the PDD ofpset
up to k. The first column contains the weights of rows. Ifreturn_row_groups
is True, returns a tuple with types (numpy.ndarray
, list).- Return type
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 create 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]]) periodic_set = amd.PeriodicSet(motif, cell) cubic_amd = amd.PDD(periodic_set, 100)
- amd.calculate.PDD_to_AMD(pdd: numpy.ndarray[Any, numpy.dtype[numpy.floating]]) numpy.ndarray[Any, numpy.dtype[numpy.floating]] ¶
Calculate an AMD from a PDD. Faster than computing both from scratch.
- Parameters
pdd (
numpy.ndarray
) – The PDD of a periodic set, soamd.PDD_to_AMD(amd.PDD(pset))
equalsamd.AMD(pset)
.- Returns
The AMD of the periodic set.
- Return type
- amd.calculate.AMD_finite(motif: numpy.ndarray[Any, numpy.dtype[numpy.floating]]) numpy.ndarray[Any, numpy.dtype[numpy.floating]] ¶
Return the AMD of a finite m-point set up to k = m - 1.
- Parameters
motif (
numpy.ndarray
) – Collection of points.- Returns
A vector shape (motif.shape[0] - 1, ), the AMD of
motif
.- Return type
Examples
The (L-infinity) 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.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[Any, numpy.dtype[numpy.floating]], lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001, return_row_groups: bool = False) Union[numpy.ndarray[Any, numpy.dtype[numpy.floating]], Tuple[numpy.ndarray[Any, numpy.dtype[numpy.floating]], list]] ¶
Return 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.
collapse (bool, default True) – Whether or not to collapse repeated rows (within tolerance
collapse_tol
).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.return_row_groups (bool, default False) – If True, return a tuple
(pdd, groups)
wheregroups[i]
contains indices of points inmotif
corresponding topdd[i]
.
- Returns
pdd – A
numpy.ndarray
with m columns (where m is the number of points), the PDD ofmotif
. The first column contains the weights of rows.- Return type
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(pset: amd.periodicset.PeriodicSet, lexsort: bool = True) numpy.ndarray[Any, numpy.dtype[numpy.floating]] ¶
Return the PDD of a periodic set with k (number of columns) large enough such that the periodic set can be reconstructed from the PDD.
- Parameters
pset (
amd.PeriodicSet
) – A periodic set (crystal) consisting of a unit cell and motif of points.lexsort (bool, default True) – Whether or not to lexicographically order the rows.
- Returns
pdd – The PDD of
pset
with enough columns to reconstructpset
usingamd.reconstruct.reconstruct()
.- Return type
- amd.calculate.PPC(pset: amd.periodicset.PeriodicSet) float ¶
Return the point packing coefficient (PPC) of
pset
.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
pset (
amd.PeriodicSet
) – A periodic set (crystal) consisting of a unit cell and motif of points.- Returns
ppc – The PPC of
pset
.- Return type
float
- amd.calculate.AMD_estimate(pset: amd.periodicset.PeriodicSet, k: int) numpy.ndarray[Any, numpy.dtype[numpy.floating]] ¶
Calculate an estimate of AMD based on the PPC.
- Parameters
pset (
amd.PeriodicSet
) – A periodic set (crystal) consisting of a unit cell and motif of points.- Returns
amd_est – An array shape (k, ), where
amd_est[i]
\(= \text{PPC} \sqrt[n]{k}\) in n dimensions.- Return type