Compactness descriptor

Definition

The compactness descriptor quantifies the local packing efficiency of a particle \(i\) by comparing it to a reference ideal packing configuration of its nearest neighbors [2].

We consider a central particle \(i\) surrounded by \(N_b(i)\) nearest neighbors, usually identified by means of a radical Voronoi tessellation [3]. We then consider triplets \((j,k,m)\) of neighboring particles, for which all particles are simultaneously nearest neighbors of each other and of particle \(i\). Such a triplet is identified with the central particle \(i\) to be a tetrahedron.

Particles in the tetrahedron \(\langle ijkm \rangle\) have radii \((r_i, r_j, r_k, r_m)\) respectively, and the triplet \((j,k,m)\) are at distances \((r_{ij},r_{ik},r_{ik})\) from the central particle \(i\), which are the lengths of each edge of the tetrahedron \(\langle ijkm \rangle\).

The reference tetrahedron for these four particles is the configuration in which they are all perfectly in touch, i.e. the edge lengths \((\sigma_{ij},\sigma_{ik},\sigma_{im})\) of this reference tetrahedron are the sums of the corresponding particle radii, \(\sigma_{ij} = r_i + r_j\), etc.

The irregularity of the tetrahedron \(\langle ijkm \rangle\) in the original configuration is measured as

\[\omega_{\langle ijkm \rangle} = \frac{ \sum_{\langle ab \rangle} | r_{ab} - \sigma_{ab} |}{\sum_{\langle ab \rangle} \sigma_{ab}} ,\]

where \(\langle a b \rangle\) runs over the six edges of the tetrahedron \(\langle ijkm \rangle\). Finally, the compactness of particle \(i\) is given by

\[\Omega(i) = \frac{1}{N_\mathrm{tetra}(i)} \sum_{\langle ijkm \rangle} \omega_{\langle ijkm \rangle} ,\]

where \(N_\mathrm{tetra}(i)\) is the total number of tetrahedra surrounding particle \(i\) and the summation is performed over all these tetrahedra. The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{C}(i) = (\: \Omega(i) \:) .\]

Note

Unlike most descriptors, this descriptor is scalar. Its feature vector \(X^\mathrm{C}(i)\) is thus composed of a single feature, and the inherited grid attribute is therefore not relevant.

Setup

Warning

This descriptor uses particles’ radii. They must either be read from the input trajectory file using the additional_fields parameter or set using the method Trajectory.set_property. Otherwise, default values will be used.

Instantiating this descriptor on a Trajectory can be done as follows:

from partycls import Trajectory
from partycls.descriptors import CompactnessDescriptor

traj = Trajectory("trajectory.xyz")
D = CompactnessDescriptor(traj)

The constructor takes the following parameters:

CompactnessDescriptor.__init__(trajectory, accept_nans=True, verbose=False)[source]

Parameters

trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.
accept_nans (bool, default: True) – If False, discard any row from the array of features that contains a NaN element. If True, keep NaN elements in the array of features.
verbose (bool, default: False) – Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Hint

The alias TongTanakaDescriptor can be used in place of CompactnessDescriptor.

Requirements

The computation of this descriptor relies on:

Lists of nearest neighbors. These can either be read from the input trajectory file, computed in the Trajectory, or computed from inside the descriptor using a default method.

Demonstration

We consider an input trajectory file trajectory.xyz in XYZ format that contains two particle types "A" and "B". We set the particle radii manually (0.5 and 0.4 for type-A and type-B particles, respectively) and compute the lists of nearest neighbors using the radical Voronoi tessellation method:

from partycls import Trajectory

# open the trajectory
traj = Trajectory("trajectory.xyz")

# set the particles radii
traj.set_property("radius", 0.5, subset="species == 'A'")
traj.set_property("radius", 0.4, subset="species == 'B'")

# compute the neighbors using Voronoi tessellation
traj.compute_nearest_neighbors(method='voronoi')
nearest_neighbors = traj.get_property("nearest_neighbors")

# print the first three neighbors lists for the first trajectory frame
print("neighbors:\n",nearest_neighbors[0][0:3])

Output:

neighbors:
 [list([323, 113, 322, 276, 767, 332, 980, 425, 16, 171, 258, 801, 901, 436, 241])
  list([448, 951, 706, 337, 481, 536, 14, 16, 258, 241, 496, 574, 502, 447, 860])
  list([639, 397, 799, 578, 230, 913, 636, 796, 640, 772, 500, 270, 354, 123, 874, 608, 826, 810])]

We now instantiate a CompactnessDescriptor on this trajectory and restrict the analysis to type-B particles only:

from partycls.descriptors import CompactnessDescriptor

# instantiation
D = CompactnessDescriptor(traj)

# restrict the analysis to type-B particles
D.add_filter("species == 'B'", group=0)

# compute the descriptor's data matrix
X = D.compute()

# print the first three feature vectors
print("feature vectors:\n", X[0:3])

Output:

feature vectors:
 [[1.38606558]
  [2.62615932]
  [1.71241472]]

feature vectors shows the first three feature vectors \(X^\mathrm{C}(1)\), \(X^\mathrm{C}(2)\) and \(X^\mathrm{C}(3)\).

References

1: B. J. Gellatly and J. L. Finney. Characterisation of models of multicomponent amorphous metals: the radical alternative to the voronoi polyhedron. J. Non-Cryst. Solids, 50(3):313–329, 1982. doi:10.1016/0022-3093(82)90093-X.
2: Hua Tong and Hajime Tanaka. Revealing Hidden Structural Order Controlling Both Fast and Slow Glassy Dynamics in Supercooled Liquids. Phys. Rev. X, 8:011041, 2018. doi:10.1103/PhysRevX.8.011041.