glotzerlab
Document use of nematic order parameter from vector inputs
While freud implements a general solution for the nematic order parameter, new users are confused at how to specify the inputs. They want to give a list of vectors representing orientations.
Here is an example question on the mailing list: https://groups.google.com/g/freud-users/c/Fyklr5GxFvg/m/gdW5y0ovBAAJ
Areas that need improvement
- Add a code snippet to the API documentation that uses rowan to convert a list of vectors to the form freud needs. Perhaps something like this that Bradley wrote in the mailing list question linked above:
import freud
import rowan
# Generate input vectors
random_quaternions = rowan.random.rand(1000)
reference_vector = [1, 0, 0]
input_vectors = rowan.rotate(random_quaternions, reference_vector)
# Compute quaternions mapping from the reference vector to the input vectors
orientations = rowan.vector_vector_rotation(reference_vector, input_vectors)
# Determine the nematic order -- this should be small because the inputs
# point in random directions.
nop = freud.order.Nematic(reference_vector)
nop.compute(orientations)
print(f"Nematic order value: {nop.order}")
- Add a simpler example to the the example notebook
Tagging @DomFijan because he mentioned wanting to address this (and smectic order) in the developer's meeting today
Just to clarify for whoever chooses to write this up in the future: the random_quaternions above are just for demonstration. The usage example should just start on the line orientations = ... for how to extract the quaternions from the relationship between a reference vector and a set of input vectors.
Good idea. We should continue to use quaternions in freud's APIs, for alignment with HOOMD's representation of a body rotation, but improving the docs on how to use vector inputs would be helpful. I agree that this is a complicated feature to explain and our example notebooks can be improved.
In addition to explaining the use of quaternions and how to compute those from vectors, we could also try to improve the docs on what u represents. (See past freud-users thread.) Specifically, I would like to include something like "The u vector is sometimes called the molecular axis or molecular director" so that users can more readily cross-reference sources that have different names for the same thing.
Another possible improvement would be to link to an external source that we like. I've started down this path before but did not find a source I really liked. I think Wikipedia is somewhat weak in its descriptions of nematic phases, from the perspective of condensed matter physics terminology and formalism / math that is relevant for users of freud. While SklogWiki has some helpful formulas, it lacks much description. Citing a published paper or a textbook that explains the nematic tensor may be the best external resource.
Yeah I think the only places that I recall finding satisfactory explanations for the nematic tensor, the director, and the order parameter were published papers. All other sources were definitely sparser in information.
To expand on the example notebook task: We discussed at the meeting that the notebook presents the nematic director as if it is some kind of input to be optimized over. This confuses new users because the director of the molecule is fixed by the geometry of the molecule in research applications.
Last several Glotzer group dev meetings featured extended discussion on this topic caused by new batch of confused users re. use of quaternions for calculation of the nematic OP. Here is a quick summary:
Given that Freud v3 is on the horizon, this might be a perfect opportunity to change the API to accept 3D orientation vectors instead of quaternions. It seems that this is what most users expect anyways which should make using Freud's Nematic order compute straightforward for new users, especially those not directly tied to the use of HOOMD. To compensate for HOOMD user base, an example in the docs to convert HOOMD's quat representation to orientation vectors using rowan should be provided.
In addition, the long standing issue of updating the example will also have to be tackled since breaking the API will require a new example to be written from scratch.
