partycls.descriptors package

Structural descriptors.

Submodules

partycls.descriptors.averaged_bo module

class partycls.descriptors.averaged_bo.LocallyAveragedBondOrientationalDescriptor(trajectory, lmin=1, lmax=8, orders=None, accept_nans=True, verbose=False)[source]

Bases: BondOrientationalDescriptor

Locally averaged bond-orientational descriptor.

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) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of orders \(\{ l_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

name = 'locally averaged bond-orientational'

symbol = 'labo'

compute()[source]

Compute the locally averaged bond-orientational correlations for the particles in group=0 for the grid of orders \(\{ l_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with bond-orientational correlations.
Return type: numpy.ndarray

class partycls.descriptors.averaged_bo.LechnerDellagoDescriptor(trajectory, lmin=1, lmax=8, orders=None, accept_nans=True, verbose=False)[source]

Bases: LocallyAveragedBondOrientationalDescriptor

Alias for the class AveragedBondOrientationalDescriptor.

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.

partycls.descriptors.ba module

class partycls.descriptors.ba.BondAngleDescriptor(trajectory, dtheta=3.0, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Bond-angle descriptor.

The empirical distribution of bond angles \(N_i(\theta_n)\) around a central particle \(i\) is obtained by counting, for all the possible pairs of it nearest neighbors \((j,k)\), the number of bond angles \(\theta_{jik}\) between \(\theta_n = n \times \Delta \theta\) and \(\theta_{n+1} = (n+1) \times \Delta \theta\), where \(\Delta \theta\) has the interpration of a bin width in a histogram (see Ref. [1]).

We then consider \(N_i(\theta_n)\) for a set of angles \(\{ \theta_n \}\) that go from \(\theta_0 = 0^\circ\) to \(\theta_{n_\mathrm{max}}=180^\circ\) by steps of \(\Delta \theta\). The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{BA}(i) = (\: N_i(\theta_0) \;\; N_i(\theta_1) \;\; \dots \;\; N_i(\theta_{n_\mathrm{max}}) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of angles \(\{ \theta_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

Parameters

trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.
dtheta (float) – Bin width \(\Delta \theta\) in degrees.
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.

name = 'bond-angle'

symbol = 'ba'

property dtheta: Bin width \(\Delta \theta\) for the grid of angles \(\{ \theta_n \}\).

compute()[source]

Compute the bond-angle correlations for the particles in group=0 for the grid of angles \(\{ \theta_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with bond-angle correlations.
Return type: numpy.ndarray

normalize(distribution, method='sin')[source]

Normalize a bond-angle distribution.

Parameters

distribution (numpy.ndarray) – Distribution to normalize.
method (str, default: "sin") –
Normalization method:
- method='sin': by construction, the probability density of has a sinusoidal enveloppe in 3D for uniformly distributed points on a sphere (default)
- method='pdf' : gives a flat probability density for uniformly distributed points on a sphere ;

Raises

ValueError – If method is invalid.

Returns

Normalized distribution.

Return type

numpy.ndarray

partycls.descriptors.bo module

class partycls.descriptors.bo.BondOrientationalDescriptor(trajectory, lmin=1, lmax=8, orders=None, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Bond-orientational descriptor.

Bond-order parameters [1] are standard measures of structure in the first coordination shell. Let \(\mathbf{r}_i\) be the position of particle \(i\) and define \(\mathbf{r}_{ij} = \mathbf{r}_j - \mathbf{r}_i\) and \(r_{ij} = |\mathbf{r}_{ij}|\). Then consider the weighted microscopic density around particle \(i\):

\[\rho(\mathbf{r}; i) = \sum_{j=1}^{N_b(i)} w_j \delta(\mathbf{r} - \mathbf{r}_{ij})\]

where \(w_j\) is a particle-dependent weight and the sum involves a set of \(N_b(i)\) particles, which defines the coordination shell of interest for particle \(i\).

We project the microscopic density on a unit-radius sphere, that is, \(\hat{\rho}(\hat{\mathbf{r}}; i) = \sum_{j=1}^{N_b(i)} w_j \delta(\mathbf{r} - \hat{\mathbf{r}}_{ij})\), where \(\hat{\mathbf{r}} = \mathbf{r} / |\mathbf{r}|\) and similarly \(\hat{\mathbf{r}}_{ij} = \mathbf{r}_{ij}/|\mathbf{r}_{ij}|\). Expanding in spherical harmonics yields

\[\hat{\rho}(\hat{\mathbf{r}}; i) = \sum_{l=0}^\infty \sum_{m=-l}^l c_{l m}(i) Y_{l m}(\hat{\mathbf{r}}) ,\]

with coefficients

\[c_{l m}(i) = \int d\mathbf{r} \rho(\mathbf{r}; i) Y_{l m}(\hat{\mathbf{r}}) .\]

In the conventional bond-order analysis, one sets the weights \(w_j\) to unity and considers the normalized complex coefficients,

\[\begin{split}\begin{align} q_{lm}(i) & = \frac{1}{N_b(i)} \int d\mathbf{r} \rho(\mathbf{r}; i) Y_{l m}(\hat{\mathbf{r}}) \nonumber \\ & = \frac{1}{N_b(i)} \sum_{j=1}^{N_b(i)} Y_{l m}(\hat{\mathbf{r}}_{ij}) . \end{align}\end{split}\]

The rotational invariants,

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

provide a detailed structural description of the local environment around particle \(i\).

We then consider \(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{BO}(i) = (\: Q_{l_\mathrm{min}}(i) \;\; \dots \;\; Q_{l_\mathrm{max}}(i) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of orders \(\{ l_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

name = 'bond-orientational'

symbol = 'bo'

property orders: Grid of orders \(\{ l_n \}\).

compute()[source]

Compute the bond-orientational correlations for the particles in group=0 for the grid of orders \(\{ l_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with bond-orientational correlations.
Return type: numpy.ndarray

class partycls.descriptors.bo.SteinhardtDescriptor(trajectory, lmin=1, lmax=8, orders=None, accept_nans=True, verbose=False)[source]

Bases: BondOrientationalDescriptor

Alias for the class BondOrientationalDescriptor.

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.

partycls.descriptors.compactness module

class partycls.descriptors.compactness.CompactnessDescriptor(trajectory, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Compactness descriptor.

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.

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

name = 'compactness'

symbol = 'compact'

compute()[source]

Compute the compactness for the particles in group=0. Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with compactness.
Return type: numpy.ndarray

tetrahedra(i, neigh_i, neigh_neigh_i)[source]

Return a 2D numpy array that contains all the tetrahedra around particle i. Each row is a 4-array with the indices of the particles forming the tetrahedron. The first index is i by construction.

Parameters

i (int) – Index of the central particle.
neigh_i (list) – List of neighbors of the central particles.
neigh_neigh_i (list) – Neighbors of the neighbors of the central particle. Each element is a list.

Returns

tetra_i – The array that contains the indices of all the tetrahedra around particle i.

Return type

numpy.ndarray

class partycls.descriptors.compactness.TongTanakaDescriptor(trajectory, accept_nans=True, verbose=False)[source]

Bases: CompactnessDescriptor

Alias for the class CompactnessDescriptor.

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.

partycls.descriptors.coordination module

class partycls.descriptors.coordination.CoordinationDescriptor(trajectory, total=True, partial=False, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Coordination descriptor.

The coordination number \(n_\alpha(i)\) of a particle \(i\) is given by the number of its nearest neighbors whose chemical species is \(\alpha\), where \(\alpha\) is either one of the \(n\) chemical species \(\{ \alpha_i \}_{i=1 \dots n}\) in the trajectory (i.e. partial coordination number, \(\alpha = \alpha_i\)) or all species at once (i.e. total coordination number, \(\alpha = \mathrm{all}\)).

The resulting full feature vector for particle \(i\) is given by

\[X^\mathrm{N}(i) = (\: n_\mathrm{all}(i) \;\; n_{\alpha_1}(i) \;\; \dots \;\; n_{\alpha_n}(i) \:) ,\]

but its size depends on whether the user requests the total coordination number, the partial ones, or both.

Note

By applying a filter on group=1, the total/partial coordination number(s) can also be computed by considering and arbitrary subset of particles (e.g. particles whose radius is smaller than a certain value).

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of chemical species for which the coordination number is computed.

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

Parameters

trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.
total (bool, default: True) – Compute the total coordination number.
partial (bool, default: False) – Compute the coordination number \(n_{\alpha_i}\) for each chemical species \(\alpha_i\) separately.
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.

name = 'coordination'

symbol = 'coord'

property total

property partial

compute()[source]

Compute the coordination number(ss for the particles in group=0. Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with the coordination number(s).
Return type: numpy.ndarray

partycls.descriptors.descriptor module

class partycls.descriptors.descriptor.StructuralDescriptor(trajectory, accept_nans=True, verbose=False)[source]

Bases: object

Base class for any structural descriptor.

The descriptor is computed for the provided Trajectory.

A structural descriptor \(S\) is a collection of \(N\) individual empirical correlation functions \(\{ s_i(\vec{x}) \}\) at the particle level, defined over a grid \(\{ \vec{x}_j \}\) of \(M\) features. These are stored in the features array as a matrix usually refered to as the “data set”.

The features array is None by default and is computed only when the compute method is called.

The correlations can be calculated between two arbitrary subsets of particles called groups:

group 0 is the main group, i.e. particles for which the correlations are being computed
group 1 is the secondary group, i.e. particles that are being considered when computing the correlations

These groups are formed by adding filters on particles’ properties (species, radius, position, etc.).

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of features over which the structural features will be computed.

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 2.0

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

Examples

>>> D = StructuralDescriptor('trajectory.xyz')
>>> D.add_filter("species == 'A'", group=0)
>>> D.add_filter("species == 'B'", group=1)
>>> D.active_filters
[("particle.species == 'A'", 0), ("particle.species == 'B'", 1)]
>>> D.clear_filters(0)
>>> D.active_filters
[("particle.species == 'B'", 1)]

property accept_nans

Boolean property.

If False, discard any row from the array of features that contains a NaN element. Warning: this will delete the selected rows from the array of features! Use the method dismiss_nans() instead to return a filtered copy of the array of features.

If True, keep NaN elements in the array of features.

property n_samples: Total number of particles \(N\) in the descriptor (i.e. in group=0).

property n_features: Number of features \(M\) of the descriptor.

property average: Average feature vector \(\langle s \rangle\) of the descriptor.

add_filter(condition, group=0)[source]

Add a filter on group = group to select the subset of particles that respects the provided condition.

Parameters

condition (str) –
The condition should have the following format: "<attribute> _operator_ <value>", where:
- <attribute> is a particle property (accepts aliases)
- _operator_ is a logical operator ("<", "<=", "==", "!=", ">=", ">")
- <value> is the corresponding value of <attribute> with the proper type
group (int, default: 0) – Index of the group to which the filter must be applied.

Return type

None

Examples

>>> S = StructuralDescriptor('trajectory.xyz')
>>> S.add_filter("particle.radius < 0.5")
>>> S.add_filter("species == 'A'", group=1)
>>> S.add_filter("x < 0", group=0) # particles on the left side of the box

clear_filters(group=0)[source]

Clear all active filters on group = group. All particles are included again in this group.

Parameters: group (int, default: 0) – Index of the group for which to clear the filters.
Return type: None

clear_all_filters()[source]

Clear all active filters in both groups. All particles are included in both groups again.

Return type: None

group_size(group)[source]

Parameters: group (int) – Index of the group (0 or 1) for which to return the size.
Returns: fraction – Number of particles in group = group over the whole trajectory.
Return type: float

group_fraction(group)[source]

Parameters: group (int) – Index of the group (0 or 1) for which to return the fraction.
Returns: fraction – Fraction of particles inside group = group over the whole trajectory.
Return type: float

get_group_property(what, group)[source]

Return a list of numpy arrays with the properties of the particles in group = group. The list size is the number of frames (System) in the trajectory.

Parameters

what (str) –

Requested particle property. what must be a particle property or an alias. The following particle aliases are accepted:

'position' : 'particle.position'
'pos' : 'particle.position'
'position[0]' : 'particle.position[0]'
'pos[0]' : 'particle.position[0]'
'x' : 'particle.position[0]'
'position[1]' : 'particle.position[1]'
'pos[1]' : 'particle.position[1]'
'y' : 'particle.position[1]'
'position[2]' : 'particle.position[2]'
'pos[2]' : 'particle.position[2]'
'z' : 'particle.position[2]'
'species' : 'particle.species'
'spe' : 'particle.species'
'label' : 'particle.label'
'mass' : 'particle.mass'
'radius' : 'particle.radius'
'nearest_neighbors' : 'particle.nearest_neighbors'
'neighbors' : particle.nearest_neighbors'
'neighbours' : 'particle.nearest_neighbors'
'voronoi_signature' : 'particle.voronoi_signature'
'signature' : 'particle.voronoi_signature'

Returns

to_dump – List of numpy arrays of the requested particle property with length equal to the number of frames in the trajectory. Each element of the list is a numpy.ndarray of the requested particle property.

Return type

list

Examples

>>> traj = Trajectory('trajectory.xyz')
>>> D = StructuralDescriptor(traj)
>>> D.get_group_property('position', group=0)
>>> D.get_group_property('x', group=1)
>>> D.get_group_property('energy', group=0)

dump(what, group)[source]: Alias for the method get_group_property.

compute()[source]

Empty compute function to be defined in child classes. Does nothing.

Return type: None

normalize(dist)[source]

Generic normalization function for child classes. Returns the input distribution unchanged.

Parameters: dist (numpy.ndarray) – Distribution to normalize.
Returns: dist – Input distribution unchanged.
Return type: numpy.ndarray

discard_nans()[source]

Return the array of features where each row that contains NaN is filtered out.

Return type: None

class partycls.descriptors.descriptor.DummyDescriptor[source]

Bases: StructuralDescriptor

Dummy descriptor for internal use.

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.

Examples

>>> D = StructuralDescriptor('trajectory.xyz')
>>> D.add_filter("species == 'A'", group=0)
>>> D.add_filter("species == 'B'", group=1)
>>> D.active_filters
[("particle.species == 'A'", 0), ("particle.species == 'B'", 1)]
>>> D.clear_filters(0)
>>> D.active_filters
[("particle.species == 'B'", 1)]

name = 'dummy'

symbol = 'dm'

normalize(dist)[source]

Generic normalization function for child classes. Returns the input distribution unchanged.

Parameters: dist (numpy.ndarray) – Distribution to normalize.
Returns: dist – Input distribution unchanged.
Return type: numpy.ndarray

partycls.descriptors.dscribe module

class partycls.descriptors.dscribe.DscribeDescriptor(trajectory, backend, *args, **kwargs)[source]

Bases: StructuralDescriptor

Adapter for generic DScribe descriptors, without chemical species information. Essentially, all the particles are considered as hydrogen atoms.

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.

Examples

>>> D = StructuralDescriptor('trajectory.xyz')
>>> D.add_filter("species == 'A'", group=0)
>>> D.add_filter("species == 'B'", group=1)
>>> D.active_filters
[("particle.species == 'A'", 0), ("particle.species == 'B'", 1)]
>>> D.clear_filters(0)
>>> D.active_filters
[("particle.species == 'B'", 1)]

compute()[source]

Empty compute function to be defined in child classes. Does nothing.

Return type: None

normalize(dist)[source]

Generic normalization function for child classes. Returns the input distribution unchanged.

Parameters: dist (numpy.ndarray) – Distribution to normalize.
Returns: dist – Input distribution unchanged.
Return type: numpy.ndarray

class partycls.descriptors.dscribe.DscribeChemicalDescriptor(trajectory, backend, *args, **kwargs)[source]

Bases: DscribeDescriptor

Adapter for generic DScribe descriptors, with chemical species information.

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.

Examples

>>> D = StructuralDescriptor('trajectory.xyz')
>>> D.add_filter("species == 'A'", group=0)
>>> D.add_filter("species == 'B'", group=1)
>>> D.active_filters
[("particle.species == 'A'", 0), ("particle.species == 'B'", 1)]
>>> D.clear_filters(0)
>>> D.active_filters
[("particle.species == 'B'", 1)]

partycls.descriptors.radial module

class partycls.descriptors.radial.RadialDescriptor(trajectory, dr=0.1, n_shells=3, bounds=None, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Radial descriptor.

Let \(\mathbf{r}_i\) be the position of particle \(i\) and define \(r_{ij} = |\mathbf{r}_j - \mathbf{r}_i|\) as the distance between particle \(i\) and its neighbors \(j\).

We define \(n_i(r_m)\) as the number of neighbors \(j\) of particle \(i\) for which \(r_{ij}\) is between \(r_m = r_\mathrm{min} + m \times \Delta r\) and \(r_{m+1} = r_\mathrm{min} + (m+1) \times \Delta r\) [1]. Here, \(\Delta r\) has the interpration of a bin width in a histogram.

We then consider \(n_i(r_m)\) for a set of distances \(\{ d_n \}\) separated by \(\Delta r\), \(\{ d_n \} = \{ r_0, r_1, \dots, r_{n_\mathrm{max}} \}\). The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{R}(i) = (\: n_i(r_0) \;\; n_i(r_1) \;\; \dots \;\; n_i(r_{n_\mathrm{max}}) \:) .\]

See tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of distances \(\{ d_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

Parameters

trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.
dr (float) – Bin width \(\Delta r\).
n_shells (int, default: 3) – Number of coordination shells (based on the \(g(r)\) of group=0). This sets the upper bound \(r_\mathrm{max}\) for the distance grid \(\{d_n\}\) up to which correlations are computed.
bounds (tuple, default: None) – Lower and upper bounds \((r_\mathrm{min},r_\mathrm{max})\) to describe the radial correlations. If set, this has the priority over n_shells.
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.

name = 'radial'

symbol = 'gr'

property n_shells: Upper bound in the grid of distances \(\{d_n\}\) expressed in number of coordinations shells.

property bounds: Lower and upper bounds \((r_\mathrm{min},r_\mathrm{max})\) to describe the radial correlations.

property dr: Grid spacing \(\Delta r\) for the grid of distances \(\{ d_n \}\).

compute()[source]

Compute the radial correlations for the particles in group=0 for the grid of distances \(\{ d_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with radial correlations.
Return type: numpy.ndarray

normalize(distribution, method='r2')[source]

Normalize a radial distribution.

Parameters

distribution (numpy.ndarray) – Distribution to normalize.
method (str, default: "r2") –
Normalization method:
- method='r2': returns math:r^2 times g(r) (default);
- method='gr' : returns the standard \(g(r)\) ;

Raises

ValueError – If method is invalid.

Returns

Normalized distribution.

Return type

numpy.ndarray

partycls.descriptors.radial_bo module

class partycls.descriptors.radial_bo.RadialBondOrientationalDescriptor(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]

Bases: BondOrientationalDescriptor

Radial bond-orientational descriptor.

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) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of bond orientational orders \(\{l_m\}\) and distances \(\{d_n\}\) over which the descriptor will be computed. It takes the form a of a list of tuples [(l0,d0), (l0,d1), ..., (ln,dn), ...].

Type: list

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

name = 'radial bond-orientational'

symbol = 'rbo'

property orders: Grid of orders \(\{ l_m \}\).

property bounds: Lower and upper bounds of the distance grid \(\{ d_n \}\).

property dr: Grid spacing \(\Delta r\) to define the distance grid \(\{ d_n \}\).

property distance_grid: Grid of distances \(\{ d_n \}\).

compute()[source]

Compute the radial bond-orientational correlations for the particles in group=0 for the grid of orders \(\{ l_m \}\) and grid of distances \(\{ d_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with radial bond-orientational correlations.
Return type: numpy.ndarray

class partycls.descriptors.radial_bo.BoattiniDescriptor(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]

Bases: RadialBondOrientationalDescriptor

Alias for the class RadialBondOrientationalDescriptor.

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.

partycls.descriptors.smoothed_ba module

class partycls.descriptors.smoothed_ba.SmoothedBondAngleDescriptor(trajectory, dtheta=3.0, cutoff_enlargement=1.3, exponent=8, accept_nans=True, verbose=False)[source]

Bases: BondAngleDescriptor

Smoothed bond-angle descriptor.

This is a smooth version of the bond-angle descriptor in which the bond angles \(\theta_{jik}\) are multiplied by a weighting function \(f(r_{ij}, r_{ik})\) that depends on the radial distances \(r_{ij}\) and \(r_{ik}\) between \((i,j)\) and \((i,k)\) respectively, where \(j\) and \(k\) can be any particle in the system (i.e. not necessarily a nearest neighbors of \(i\)).

Essentially, we define the smoothed number of bond angles around particle \(i\) as

\[N_i^S(\theta_n) = \sum_{j=1}^N \sum_{\substack{k=1 \ k \neq j}}^N f(r_{ij}, r_{ik}) \delta(\theta_n - \theta_{jik}) ,\]

where the superscript \(S\) indicates the smooth nature of the descriptor, and \(f(r_{ij}, r_{ik})\) is the following smoothing function:

\[f(r_{ij}, r_{ik}) = \exp \left[ - \left[ ( r_{ij} / r_{\alpha\beta}^c )^\gamma + ( r_{ik} / r_{\alpha\beta'}^c )^\gamma \right] \right] H( R_\mathrm{max}^c - r_{ij} ) H( R_\mathrm{max}^c - r_{ik}) ,\]

where:

\(r_{\alpha\beta}^c\) and \(r_{\alpha\beta'}^c\) are the first minima of the corresponding partial radial distribution functions for the pairs \((i,j)\) and \((i,k)\).
\(\gamma\) is an integer.
\(R_\mathrm{max}^c = \xi \times \max(\{ r_{\alpha\beta}^c \})\) is the largest nearest neighbor cutoff rescaled by \(\xi > 1\).
\(H\) is the Heavide step function, which ensures for efficiency reasons, that the descriptor only has contributions from particles within a distance \(R_\mathrm{max}^c\).

We then consider \(N_i^S(\theta_n)\) for a set of angles \(\{ \theta_n \}\) that go from \(\theta_0 = 0^\circ\) to \(\theta_{n_\mathrm{max}}=180^\circ\) by steps of \(\Delta \theta\). The resulting feature vector for particle \(i\) is given by

\[X^\mathrm{SBA}(i) = (\: N_i^S(\theta_0) \;\; N_i^S(\theta_1) \;\; \dots \;\; N_i^S(\theta_{n_\mathrm{max}}) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of angles \(\{ \theta_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

Parameters

trajectory (Trajectory) – Trajectory on which the structural descriptor will be computed.
dtheta (float) – Bin width \(\Delta \theta\) in degrees.
cutoff_enlargement (float, default: 1.3) – Scaling factor \(\xi\) for the largest nearest neighbors cutoff \(\max(\{ r_\mathrm{\alpha\beta}^c \})\) to consider neighbors \(j\) a distance \(R_\mathrm{max}^c = \xi \times \max(\{r_{\alpha\beta}^c\})\) away from the central particle \(i\).
exponent (int, default: 8) – Exponent \(\gamma\) in the smoothing function \(f(r_{ij},r_{ik})\).
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.

name = 'smoothed-bond-angle'

symbol = 'sba'

compute()[source]

Compute the smoothed bond-angle correlations for the particles in group=0 for the grid of angles \(\{ \theta_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with smoothed bond-angle correlations.
Return type: numpy.ndarray

partycls.descriptors.smoothed_bo module

class partycls.descriptors.smoothed_bo.SmoothedBondOrientationalDescriptor(trajectory, lmin=1, lmax=8, orders=None, cutoff_enlargement=1.3, exponent=8, accept_nans=True, verbose=False)[source]

Bases: BondOrientationalDescriptor

Smoothed bond-orientational descriptor.

This is a smooth version of the bond-orientational descriptor, in which the coefficients \(q_{lm}(i)\) are multiplied by a weighting function \(f(r)\) that depends on the radial distance \(r\) between the central particle \(i\) and other surrounding particles \(j\), where \(j\) can be any particle in the system (i.e. not necessarily a nearest neighbors of \(i\)).

The smoothed complex coefficients are given by

\[q_{lm}^{S}(i) = \frac{1}{Z(i)} \sum_{j=1}^{N} f({r}_{ij}) Y_{lm}(\hat{\mathbf{r}}_{ij}) ,\]

where \(Z(i)=\sum_{j=1}^{N} f({r}_{ij})\) is a normalization constant and the superscript \(S\) indicates the smooth nature of the descriptor. We use

\[f(r_{ij}) = \exp \left[- (r_{ij} / r_{\alpha\beta}^c)^\gamma \right] H(R_{\alpha\beta}^c - r_{ij}) ,\]

where \(r_{\alpha\beta}^c\) is the first minimum of the corresponding partial radial distribution function for the pair \((i,j)\) and \(\gamma\) is an integer. Also, \(H\) is the Heaviside step function, which ensures, for efficiency reasons, that the descriptor only has contributions from particles within a distance \(R_{\alpha\beta}^c = \xi \times r_{\alpha\beta}^c\) from the central one, where \(\xi > 1\) is a scaling factor.

The rotational invariants are defined similarly to the bond-orientational descriptor.

We then consider \(Q_l^S(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{SBO}(i) = (\: Q_{l_\mathrm{min}}^S(i) \;\; \dots \;\; Q_{l_\mathrm{max}}^S(i) \:) .\]

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

grid

Grid of orders \(\{ l_n \}\).

Type: numpy.ndarray

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.
cutoff_enlargement (float, default: 1.3) – Scaling factor \(\xi\) for the nearest neighbors cutoffs \(r_{\alpha\beta}^c\) to consider neighbors \(j\) a distance \(R_{\alpha\beta}^c = \xi \times r_{\alpha\beta}^c\) away from the central particle \(i\).
exponent (int, default: 8) – Exponent \(\gamma\) in the smoothing function \(f(r_{ij})\).
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.

name = 'smoothed bond-orientational'

symbol = 'sbo'

compute()[source]

Compute the smoothed bond-orientational correlations for the particles in group=0 for the grid of orders \(\{ l_n \}\). Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with bond-orientational correlations.
Return type: numpy.ndarray

partycls.descriptors.tetrahedrality module

class partycls.descriptors.tetrahedrality.TetrahedralDescriptor(trajectory, accept_nans=True, verbose=False)[source]

Bases: StructuralDescriptor

Tetrahedral descriptor.

The degree of tetrahedrality of a particle \(i\) is the average deviation of the bond angles \(\{ \theta_{jik} \}\) between \(i\) and all the possible pairs of its nearest neighbors \((j,k)\) from the ideal angle in a tetrahedron, \(\theta_\mathrm{tetra} = 109.5^\circ\):

\[T(i) = \frac{1}{N_\mathrm{ba}(i)} \sum_{j=1}^{N_b(i)} \sum_{\substack{k=1 \ k \neq j}}^{N_b(i)} | \cos(\theta_{jik}) - \cos(\theta_\mathrm{tetra}) | ,\]

where \(N_\mathrm{ba}(i)\) is the total number of bond angles (i.e. the number of pairs) around particle \(i\) and \(N_b(i)\) is the number of its nearest neighbors. The resulting feature vector for particle \(i\) is given by

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

Note

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

See the tutorials for more details.

trajectory

Trajectory on which the structural descriptor will be computed.

Type: Trajectory

active_filters

All the active filters on both groups prior to the computation of the descriptor.

Type: list

dimension

Spatial dimension of the descriptor (2 or 3).

Type: int

features

Array of all the structural features for the particles in group=0 in accordance with the defined filters (if any). This attribute is initialized when the method compute is called (default value is None).

Type: numpy.ndarray

groups

Composition of the groups: groups[0] and groups[1] contain lists of all the Particle instances in groups 0 and 1 respectively. Each element of the tuple is a list of Particle in trajectory, e.g. groups[0][0] is the list of all the particles in the first frame of trajectory that belong to group=0.

Type: tuple

verbose

Show progress information and warnings about the computation of the descriptor when verbose is True, and remain silent when verbose is False.

Type: bool

neighbors_boost

Scaling factor to estimate the number of neighbors relative to a an ideal gas with the same density. This is used internally to set the dimensions of lists of neighbors. A too small number creates a risk of overfilling the lists of neighbors, and a too large number increases memory usage. This only works if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. This sets the value of the max_num_neighbors attribute during the computation of the descriptor.

Type: float, default: 1.5

max_num_neighbors

Maximum number of neighbors. This is used internally to set the dimensions of lists of neighbors. This number is automatically adjusted to limit memory usage if the associated Trajectory has valid cutoffs in the Trajectory.nearest_neighbors_cutoffs list attribute. The default value 100 is used if no cutoffs can be used to estimate a better value. The default value is sufficient in most cases, otherwise this number can manually be increased before computing the descriptor.

Type: int, default: 100

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.

name = 'tetrahedral'

symbol = 'tetra'

compute()[source]

Compute the tetrahedrality for the particles in group=0. Returns the data matrix and also overwrites the features attribute.

Returns: features – Data matrix with the degree of tetrahedrality.
Return type: numpy.ndarray