search

glotzerlab / hoomd-blue

Molecular dynamics and Monte Carlo soft matter simulation on GPUs.
http://glotzerlab.engin.umich.edu/hoomd-blue
BSD 3-Clause "New" or "Revised" License
336 stars 133 forks source link

Reformat units in the documentation #801

Closed joaander closed 3 years ago

joaander commented 4 years ago

Description

As I update the docs, I'm finding the units documentation for each parameter cumbersome. For example:

sigma (in energy units)
gamma (in units of force/velocity)

We could instead use the square bracket notation used by wolfram alpha for basic units:

sigma [energy]
gamma [force/velocity]

Motivation and context

I'm open to other suggestions.

mphoward commented 4 years ago

I like the square brackets, it is easier to read. What do you think about also replacing the words by math symbols consistent with the documented fundamental units? A shorthand could also be added for common derived units, as is done for time (tau).

https://hoomd-blue.readthedocs.io/en/stable/units.html

joaander commented 4 years ago

The page you link to has been rewritten for v3. The new tutorial uses the bracket notation when it introduces units: https://github.com/glotzerlab/hoomd-examples/blob/01-Introducing-Molecular-Dynamics/01-Introducing-Molecular-Dynamics/02-Initializing-a-Random-System.ipynb

Many of the symbols used in the v2 docs aren't in common use and I think that while they are compact, they add an additional and unnecessary fluid representation.

mphoward commented 4 years ago

Sure, the notation in the tutorial is very human-readable too. Having it directly in square brackets is the main plus!

vyasr commented 3 years ago

It might be helpful to look at unyt, pint, or astropy.units, which are the three packages that I'm aware of for actually working with and validating units. They might have examples of how they recommend documenting units (or their dependents might).