Radial bond-orientational descriptor

Important

See Bond-orientational descriptor first.

Definition

The radial bond-order descriptor captures the radial dependence of bond order in the most straightforward way [1]. It uses a radial basis of Gaussian functions of width \(\delta\) centered on a grid of points \(\{d_n\}_{n=1 \dots n_\mathrm{max}}\),

\[G_n(r) = \exp{\left(-\frac{(d_n - r)^2}{2\delta^2}\right)} .\]

The complex radial bond-order coefficients are defined as

\[q_{l m n}^{R}(i) = \frac{1}{Z(i)} \sum_{j=1}^{N} G_n(r_{ij}) Y_{l m}(\hat{\mathbf{r}}_{ij}) ,\]

where \(Z(i) = \sum_{j=1}^N G_n(r_{ij})\) is a normalization constant and the superscript \(R\) indicates the radial dependence of the descriptor. In the following, we actually use

\[G_n(r_{ij}) = \exp{\left(-\frac{(d_n - r_{ij})^\gamma}{2\delta^2}\right)} H(R_\mathrm{max} - r_{ij}) ,\]

where \(\gamma\) is an integer, \(H\) is the Heaviside step function, which allows to neglect the contributions of particles further than a distance \(R_\mathrm{max} = d_{n_\mathrm{max}} + \sigma \times \delta\) from the central particle, where \(d_{n_\mathrm{max}}\) is the largest distance in the grid of points \(\{ d_n \}\) and \(\sigma\) is a skin distance. Then, only the diagonal coefficients of the power spectrum, namely

\[Q_{l,n}^R(i) = \sqrt{ \frac{4\pi}{2l + 1} \sum_{m=-l}^l |q_{l m n}^R(i)|^2 } ,\]

are retained to form the descriptor of particle \(i\).

We then consider \(Q^R_{l,n}(i)\) for a sequence of orders \(\{ l_m \} = \{ l_\mathrm{min}, \dots, l_\mathrm{max} \}\) and for a grid of distances \(\{ d_n \}\). The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{RBO}(i) = (\: \dots \;\; Q^R_{l,n}(i) \;\; Q^R_{l, n+1}(i) \;\; \dots \;\; Q^R_{l_\mathrm{max}, n_\mathrm{max}}(i) \:) .\]

Setup

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

from partycls import Trajectory
from partycls.descriptors import RadialBondOrientationalDescriptor

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

The constructor takes the following parameters:

RadialBondOrientationalDescriptor.__init__(trajectory, lmin=1, lmax=8, orders=None, bounds=(1, 1.5), dr=0.1, distance_grid=None, delta=0.1, skin=2.5, exponent=2, accept_nans=True, verbose=False)[source]
Parameters

  • trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.

  • lmin (int, default: 1) – Minimum order \(l_\mathrm{min}\). This sets the lower bound of the grid \(\{ l_m \}\).

  • lmax (int, default: 8) – Maximum order \(l_\mathrm{max}\). This sets the upper bound of the grid \(\{ l_n \}\). For numerical reasons, \(l_\mathrm{max}\) cannot be larger than 16.

  • orders (list, default: None) – Sequence \(\{l_m\}\) of specific orders to compute, e.g. orders=[4,6]. This has the priority over lmin and lmax.

  • bounds (tuple, default: (1, 1.5)) – Lower and upper bounds \((d_{n_\mathrm{min}}, d_{n_\mathrm{max}})\) to define the grid of distances \(\{ d_n \}\), where consecutive points in the the grid are separated by \(\Delta r\).

  • dr (float, default: 0.1) – Grid spacing \(\Delta r\) to define the grid of distances \(\{ d_n \}\) in the range \((d_{n_\mathrm{min}}, d_{n_\mathrm{max}})\) by steps of size \(\Delta r\).

  • distance_grid (list, default: None) – Manually defined grid of distances \(\{ d_n \}\). If different from None, it overrides the linearly-spaced grid defined by bounds and dr.

  • delta (float, default: 0.1) – Shell width \(\delta\) to probe the local density at a distances \(\{d_n\}\) from the central particle.

  • skin (float, default: 2.5) – Skin width \(\sigma\) (in units of delta) to consider neighbors further than the upper bound \(d_{n_\mathrm{max}}\) of the grid of distances. Neighbors will then be identified up to \(d_{n_\mathrm{max}} + \sigma \times \delta\)

  • 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 BoattiniDescriptor can be used in place of RadialBondOrientationalDescriptor.

Demonstration

We consider an input trajectory file trajectory.xyz in XYZ format that contains two particle types "A" and "B":

from partycls import Trajectory

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

We now instantiate a RadialBondOrientationalDescriptor on this trajectory and restrict the analysis to type-B particles only. We set set the grid of orders \(\{l_m\} = \{4,6\}\), the grid of distances \(\{d_n\} = \{1.0, 1.25, 1.50\}\), the Gaussian shell width \(\delta=0.2\) and the skin width \(\sigma = 2.5\):

from partycls.descriptors import RadialBondOrientationalDescriptor

# instantiation
D = RadialBondOrientationalDescriptor(traj,
                                      orders=[4,6],
                                      distance_grid=[1.0, 1.25, 1.50],
                                      delta=0.2,
                                      skin=2.5)

# print the grid of orders
print("orders:\n", D.orders)
# print the grid of distances
print("distances:\n", D.distance_grid)
# print the mixed grid of orders and distances
print("mixed grid:\n", D.grid)

# 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:
orders:
 [4 6]
distances:
 [1.   1.25 1.5 ]
mixed grid:
 [(4, 1.0), (4, 1.25), (4, 1.5), (6, 1.0), (6, 1.25), (6, 1.5)]
feature vectors:
 [[0.10876497 0.08802174 0.08958731 0.41008552 0.18769869 0.17186267]
  [0.09036718 0.05933577 0.07556535 0.49122192 0.2396785  0.17942327]
  [0.09049389 0.11888597 0.06950139 0.3981864  0.18440161 0.18568249]]

  • orders shows the grid of orders \(\{ l_m \}\).

  • distances shows the grid of distances \(\{ d_n \}\).

  • mixed grid shows the mixed grid of orders and distances.

  • feature vectors shows the first three feature vectors \(X^\mathrm{RBO}(1)\), \(X^\mathrm{RBO}(2)\) and \(X^\mathrm{RBO}(3)\) corresponding to the (mixed) grid.

References

1

Emanuele Boattini, Frank Smallenburg, and Laura Filion. Averaging local structure to predict the dynamic propensity in supercooled liquids. Phys. Rev. Letters, 127(8):088007, 2021. doi:10.1103/PhysRevLett.127.088007.