API

Overview

BOOSOP	Compute the point group symmetry order for bond orientational order diagram.
PGOP	Compute the point group symmetry order for a given point cloud.

Details

Package contains methods for computing symmetry order parameters.

class spatula.BOOSOP(dist, symmetries, optimizer, max_l=10, kappa=10, max_theta=0.61)

Compute the point group symmetry order for bond orientational order diagram.

This class implements the method described in [But24]. It detects the point group symmetry of the modified bond order diagram of a particles. Rather than treating the neighbor vectors as delta functions, this class treats these vectors as the mean of a distribution on the surface of the sphere (e.g. von-Mises-Fisher or uniform distributions).

__init__(dist, symmetries, optimizer, max_l=10, kappa=10, max_theta=0.61)

Create a BOOSOP object.

This class implements the method described in [But24]. All point groups of finite order are supported.

Note

A max_l of at least 9 is needed to capture several higher order groups such as $C_{nh}$, $C_{nv}$ and some $D$ groups.

Parameters:

• dist (str) – The distribution to use. Either “fisher” for the von-Mises-Fisher distribution or “uniform” for a uniform distribution.

• symmetries (list[str]) – A list of point groups to test each particles’ neighborhood. Uses Schoenflies notation and is case sensitive. Options are $C_i$, $C_s$, $C_n$, $C_{nh}$, $C_{nv}$, $S_n$, $D_n$, $D_{nh}$, $D_{nd}$, $T$, $T_h$, $T_d$, $O$, $O_h$, $I$, $I_h$. Replace $n$ with an integer, and pass them as strings, e.g., ["C3", "D6h"].

• optimizer (spatula.optimize.Optimizer) – An optimizer to optimize the rotation of the particle’s local neighborhoods. When using spatula.optimize.NoOptimization, the provided fixed orientation is applied by rotating the Wigner-D symmetry operators once up front. The orientation comes from NoOptimization(orientation=...) in [w, x, y, z] convention and is normalized internally.

• max_l (int, optional) – The maximum spherical harmonic l to use for computations. This number should be larger than the l and refine_l used in compute. Defaults to 10.

• kappa (float) – The concentration parameter for the von-Mises-Fisher distribution. Only used when dist is “fisher”. This number should be roughly equal to average number of neighbors. If neighborhood is more dense (has more neighbors) higher values are recommended. Should be larger than l for good accuracy. Defaults to 11.5.

• max_theta (float) – The maximum angle (in radians) that the uniform distribution extends. Only used when dist is uniform. Defaults to 0.61 (roughly 35 degrees).

__weakref__

list of weak references to the object

compute(system, neighbors, query_points=None, l=10, m=10, refine=False, refine_l=20, refine_m=20)

Compute the point group symmetry for a given system and neighbor.

Note

Higher max_l requires higher m. A rough equality is usually good enough to ensure accurate results for the given fidelity, though setting m to 1 to 2 higher often still improves results.

Parameters:

• system (tuple[freud.box.Box, np.ndarray]) – A freud system-like object. Common examples include a tuple of a freud.box.Box and a numpy.ndarray of positions and a gsd.hoomd.Frame.

• neighbors (freud.locality.NeighborList | freud.locality.NeighborQuery) – A freud neighbor query object. Defines neighbors for the system. Weights provided by a neighbor list are currently unused.

• query_points (np.ndarray | None, optional) – The points to compute the BOOSOP for. Defaults to None which computes the BOOSOP for all points in the system. The shape should be (N_p, 3) where N_p is the number of points.

• l (int, optional) – The spherical harmonic l to use for the bond order functions calculation. Increasing l increases the accuracy of the bond order calculation at the cost of performance. The sweet spot number which is high enough for all point groups and gives reasonable accuracy for relatively high number of neighbors is 10. Point group O needs l of at least 9 and T needs at least 8. Lower values increase speed. Defaults to 10.

• m (int, optional) – The number of points to use in the longitudinal direction for spherical Gauss-Legrende quadrature. Defaults to 10. We recommend m to be equal or larger than l. More concentrated distributions require larger m to properly evaluate bond order functions. The number of points to evaluate scales as $4 m^2$.

• refine (bool, optional) – Whether to recompute the BOOSOP after optimizing. Defaults to False. This is used to enable a higher fidelity calculation after a lower fidelity optimization. If used the refine_l and refine_m should be set to a higher value than l and m. Make sure max_l is higher or equal to refine_l.

• refine_l (int, optional) – The maximum spherical harmonic l to use for refining. Defaults to 10.

• refine_m (int, optional) – The number of points to use in the longitudinal direction for spherical Gauss-Legrende quadrature in refining. Defaults to 10. More concentrated distributions require larger m to properly evaluate bond order functions. The number of points to evaluate scales as $4 m^2$.

property max_l

The maximum spherical harmonic l used in computations.

property order

The order parameter is [0,1].

The symmetry order is consistent with the order passed to BOOSOP.compute.

Type:

$(N_p, N_{sym})$ numpy.ndarray of float

property rotations

Optimal rotations.

The optimal rotations of local neighborhoods that maximize the value of PGOP for each query particle and each point group. Rotations are expressed as quaternions. Note that these use different convention to scipy! The convention used here is [w,x,y,z]. The scipy convention is [x,y,z,w].

Type:

$(N_p, N_{sym}, 4)$ numpy.ndarray of float

property symmetries

The point group symmetries tested.

class spatula.PGOP(symmetries, optimizer, mode='full', compute_per_operator_values_for_final_orientation=False, metric='BC')

Compute the point group symmetry order for a given point cloud.

This class implements the algorithm highlighted in [FRBG26]. It detects the point group symmetry of a point in space based on the surrounding points. Rather than treating the neighbor vectors as delta functions, this class treats these vectors as a Gaussian distribution. This enables continuous evaluation of the point group symmetry.

__init__(symmetries, optimizer, mode='full', compute_per_operator_values_for_final_orientation=False, metric='BC')

Create a PGOP object.

This class implements the algorithm highlighted in [FRBG26]. All point groups of finite order are supported.

Parameters:

• symmetries (list[str]) – A list of point groups to test each particles’ neighborhood. Uses Schoenflies notation and is case sensitive. Options are $C_i$, $C_s$, $C_n$, $C_{nh}$, $C_{nv}$, $S_n$, $D_n$, $D_{nh}$, $D_{nd}$, $T$, $T_h$, $T_d$, $O$, $O_h$, $I$, $I_h$, where $n$ where n should be replaced with group order (an integer) and passed as a list of strings.

• optimizer (spatula.optimize.Optimizer) – An optimizer to optimize the rotation of the particle’s local neighborhoods. When using spatula.optimize.NoOptimization, the provided fixed orientation is applied by rotating symmetry operators once up front. The orientation comes from NoOptimization(orientation=...) in [w, x, y, z] convention and is normalized internally.

• mode (str, optional) – The mode to use for the computation. Either “full” or “boo”. Defaults to “full”. “full” computes the full point group symmetry order parameter (PGOP) while “boo” computes the point group symmetry order of the bond orientational order diagram (PGOP-BOOD).

• compute_per_operator_values_for_final_orientation (bool, optional) – Whether to compute the PGOP values for all subgroups of point group symmetries of interest, at same orientation as the point group of interest PGOP value. Defaults to False. order values are in order point group symmetry, order for symmetry operators of this point group in order given by the representations.matrices, order for second point group symmetry, etc.

• metric (str, optional) –

  The metric to report. "BC" reports the Bhattacharyya coefficient and "HD" reports the Hellinger distance, $\sqrt{1 - \mathrm{BC}}$.

  "HD" obeys the triangle inequality while "BC" does not. This means HD values are true distances and can be compared on a linear distance scale (e.g., 0.2 is twice the distance of 0.1), making HD preferable for distance-based workflows such as clustering, nearest-neighbor search, and thresholding by geometric separation.

  Interpretation:

  • metric="BC": 1 means maximally ordered (perfect overlap), 0 means disordered/no overlap.

  • metric="HD": 0 means maximally ordered (zero distance), larger values mean less ordered. Defaults to "BC".

__weakref__

list of weak references to the object

compute(system, sigmas, neighbors, query_points=None)

Compute the point group symmetry for a given system and neighbor.

Parameters:

• system (tuple[freud.box.Box, np.ndarray]) – A freud system-like object. Common examples include a tuple of a freud.box.Box and a numpy.ndarray of positions and a gsd.hoomd.Frame.

• sigmas (np.ndarray | float) – The standard deviation of the Gaussian distribution for each particle for mode “full”. If mode is “boo”, the kappa parameter for the von-Mises-Fisher. Note that for gaussian distribution, smaller sigma values are more concentrated and larger sigma values are more spread out. For von-Mises- Fisher distribution, smaller kappa values are more spread out and larger kappa values are more concentrated. If a float is passed, the same value is used for all particles. If None is passed, sigma is determined as the value at which the gaussian function value evaluated at half of the smallest bond distance has 25% height of max gaussian height for the same sigma for the “full” mode. In the “boo” mode, the default value is 15.0.

• neighbors (freud.locality.NeighborList | freud.locality.NeighborQuery | dict) – Neighbors used for the computation. If a freud.locality.NeighborList is passed, the neighbors are used directly (in this case query_points should not be given as they are ignored). If a freud.locality.NeighborQuery is passed, the neighbors are computed using the query (working in conjunction with query points). If a dictionary is used it should be used as freud’s neighbor query dictionary (can also be used in conjunction with query_points).

• query_points (np.ndarray | None, optional) – The points to compute the PGOP for. Defaults to None which computes the PGOP for all points in the system. The shape should be (N_p, 3) where N_p is the number of points.

property metric

The metric used for the reported order values.

property mode

The mode used for the computation.

property order

Order parameter in [0,1].

The symmetry order is consistent with the order passed to PGOP.compute.

Value interpretation depends on self.metric: - metric="BC": 1 = ordered, 0 = disordered. - metric="HD": 0 = ordered, 1 = disordered.

Type:

$(N_p, N_{sym})$ numpy.ndarray of float

property rotations

Optimal rotations.

The optimal rotations of local neighborhoods that maximize the value of PGOP for each query particle and each point group. Rotations are expressed as quaternions. Note that these use different convention to scipy! The convention used here is [w,x,y,z]. The scipy convention is [x,y,z,w].

Type:

$(N_p, N_{sym}, 4)$ numpy.ndarray of float

property sigmas

The standard deviation of the Gaussian distribution for each particle.

property symmetries

The point group symmetries tested.

Modules

• spatula.optimize
• spatula.util