amd.calculate module
Functions for calculating AMDs and PDDs (and SDDs) of periodic and finite sets.
- amd.calculate.AMD(periodic_set: Union[amd.periodicset.PeriodicSet, Tuple[numpy.ndarray, numpy.ndarray]], k: int) numpy.ndarray
The AMD up to k of a periodic set.
- Parameters
periodic_set (
periodicset.PeriodicSet
or tuple of ndarrays) – A periodic set represented by aperiodicset.PeriodicSet
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, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001) numpy.ndarray
The PDD up to k of a periodic set.
- Parameters
periodic_set (
periodicset.PeriodicSet
or tuple of ndarrays) – A periodic set represented by aperiodicset.PeriodicSet
or by a tuple (motif, cell) with coordinates in Cartesian form.k (int) – Number of columns in the PDD (the returned matrix has an additional first column containing weights).
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'): # 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 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.AMD_finite(motif: numpy.ndarray) numpy.ndarray
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.AMD_finite(trapezium) kite_amd = amd.AMD_finite(kite) dist = amd.AMD_pdist(trap_amd, kite_amd)
- amd.calculate.PDD_finite(motif: numpy.ndarray, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001) numpy.ndarray
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)
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.PDD_finite(trapezium) kite_pdd = amd.PDD_finite(kite) dist = amd.emd(trap_pdd, kite_pdd)
- amd.calculate.SDD(motif: numpy.ndarray, order: int = 1, lexsort: bool = True, collapse: bool = True, collapse_tol: float = 0.0001)
The SSD (simplex-wise distance distribution) of a finite point set, with len(motif) - 1 columns. The SDD with order h considers h-sized collection of points in the motif; the first-order SDD is equivalent to the PDD for finite sets.
- Parameters
motif (ndarray) – Cartesian coordinates of points in a set. Shape (n_points, dimensions)
order (int) – Order of the SDD, default 1. See papers for a description of higher-order SDDs.
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
The h-order SDD of
motif
. A tuple of 3 arrays is returned,weights
,dist
andsdd
. If order=1, dist is None.- Return type
tuple of ndarrays
Examples
Find the SDD of the 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_sdd = amd.SDD(trapezium, order=2) kite_sdd = amd.SDD(kite)
- 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
or tuple of ndarrays) – A periodic set represented by aperiodicset.PeriodicSet
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'): # 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.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 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.