freud: Hexatic normalization in docs doesn't match implementation

@Plastikschuessel noted that the documentation for the Hexatic order parameter doesn’t match the implementation. The docs say that the formula normalizes by 1/n, but the implemented code normalizes by 1/k. In many systems (particularly hexagonal and square crystals), k=n, but in some cases (e.g. 2D quasicrystals), the order is 12-fold even though any given particle has fewer than 12 neighbors.

https://github.com/glotzerlab/freud/blob/3f44951a7eb8d6670664fc1dac22c451f17278a1/freud/order.pyx#L250-L251

https://github.com/glotzerlab/freud/blob/3f44951a7eb8d6670664fc1dac22c451f17278a1/cpp/order/HexaticTranslational.cc#L38-L45

A temporary workaround to achieve the desired behavior is to enabled weighted=True in the constructor. In ball queries and nearest neighbor queries (but not Voronoi queries), the weight for each bond defaults to 1. If weighted=True, the normalization will divide by the number of neighbor bonds (a sum with 1 for each bond).

To resolve this issue, we should verify the literature to see which convention is more common and consider changing to normalization by 1/n instead of 1/k.

About this issue

  • Original URL
  • State: closed
  • Created 4 years ago
  • Comments: 17 (11 by maintainers)

Most upvoted comments

Agree, we should probably add documentation indicating that the recommended usage is np.mean(np.abs(hex.particle_order)) or so for most standard use cases. I’ve never really seen much usage of the phase; it’s also worth noting that strictly speaking the value of the phase is dependent on the choice of reference vector.