Locally averaged bond-orientational descriptor

Important

See Bond-orientational descriptor first.

Definition

The complex coefficients \(q_{lm}(i)\) of particle \(i\) can be averaged over its \(N_b(i)\) nearest neighbors, as suggested by Lechner and Dellago [1],

\[\bar{q}_{lm}(i) = \frac{1}{N_b(i)+1} \left[ q_{l m}(i) + \sum_{j=1}^{N_b(i)} q_{l m}(j) \right],\]

and then made invariant,

\[\bar{Q}_{l}(i) = \sqrt{ \frac{4\pi}{2l + 1}\sum_{m=-l}^l |\bar{q}_{lm(i)}|^2 } ,\]

to provide an improved descriptor for crystal structure detection.

We then consider \(\bar{Q}_l(i)\) for a sequence of orders \(\{ l_n \} = \{ l_\mathrm{min}, \dots, l_\mathrm{max} \}\). The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{LABO}(i) = (\: \bar{Q}_{l_\mathrm{min}}(i) \;\; \dots \;\; \bar{Q}_{l_\mathrm{max}}(i) \:) .\]

Setup

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

from partycls import Trajectory
from partycls.descriptors import LocallyAveragedBondOrientationalDescriptor

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

The constructor takes the following parameters:

LocallyAveragedBondOrientationalDescriptor.__init__(trajectory, lmin=1, lmax=8, orders=None, 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_n \}\).

  • 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_n\}\) of specific orders to compute, e.g. orders=[4,6]. This has the priority over lmin and lmax.

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

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 compute the lists of nearest neighbors using the fixed-cutoffs method:

from partycls import Trajectory

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

# compute the neighbors using pre-computed cuttofs
traj.nearest_neighbors_cuttofs = [1.45, 1.35, 1.35, 1.25]
traj.compute_nearest_neighbors(method='fixed')
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([16, 113, 171, 241, 258, 276, 322, 323, 332, 425, 767, 801, 901, 980])
  list([14, 241, 337, 447, 448, 481, 496, 502, 536, 574, 706, 860, 951])
  list([123, 230, 270, 354, 500, 578, 608, 636, 639, 640, 796, 799, 810, 826, 874, 913])]

We now instantiate a LocallyAveragedBondOrientationalDescriptor on this trajectory and restrict the analysis to type-B particles only. We set set the grid of orders \(\{l_n\} = \{2,4,6,8\}\):

from partycls.descriptors import LocallyAveragedBondOrientationalDescriptor

# instantiation
D = LocallyAveragedBondOrientationalDescriptor(traj, orders=[2,4,6,8])

# print the grid of orders
print("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:
grid:
 [2 4 6 8]
feature vectors:
 [[0.03366521 0.04034078 0.08648078 0.1120834 ]
  [0.01483751 0.03889963 0.16849717 0.11150705]
  [0.02312734 0.02640117 0.11722934 0.11053876]]

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

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

References

1

Wolfgang Lechner and Christoph Dellago. Accurate determination of crystal structures based on averaged local bond order parameters. J. Chem. Phys., 129(11):114707, 2008. arXiv:0806.3345, doi:10.1063/1.2977970.