update docstrings and examples for units clarity

[dallasfoster]

ALCHEMI Toolkit Pull Request

Description

Tries to add clarity to the usage of units throughout the package.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• [ x ] Documentation update
• Refactoring (no functional changes)
• CI/CD or infrastructure change

Related Issues

Changes Made

Testing

• Unit tests pass locally (make pytest)
• Linting passes (make lint)
• New tests added for new functionality meets coverage expectations?

Checklist

• I have read and understand the Contributing Guidelines
• I have updated the CHANGELOG.md
• I have performed a self-review of my code
• I have added docstrings to new functions/classes
• I have updated the documentation (if applicable)

Additional Notes

Tip

This repository uses Greptile, an AI code review service, to help conduct
pull request reviews. We encourage contributors to read and consider suggestions
made by Greptile, but note that human maintainers will provide the necessary
reviews for merging: Greptile's comments are not a qualitative judgement
of your code, nor is it an indication that the PR will be accepted/rejected.
We encourage the use of emoji reactions to Greptile comments, depending on
their usefulness and accuracy.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR improves unit clarity across the codebase by updating docstrings, examples, and comments to consistently describe the unit system implied by each parameter. It also includes several functional bug fixes: renaming batch.stress → batch.stresses throughout the dynamics stack (base.py, npt.py, nph.py, fire2.py, tests) to match the actual named AtomicData field, and updating the MACEWrapper to prefer the "virials" output (correct raw virial in eV) over "stress" (Cauchy stress in eV/ų) for NPT/NPH correctness.

Key changes:

• New "Units and physical conventions" section in docs/userguide/data.md covering natural time unit derivation, auto-populated amu masses, temperature convention (Kelvin), and positive-raw-virial stress sign convention.
• Functional fix: batch.stress → batch.stresses in BaseDynamics._apply_outputs, NPT._compute_pressure, NPH._compute_pressure, and FIRE2VariableCell._compute_cell_forces.
• MACEWrapper.adapt_output: now routes raw_output["virials"] to "stresses" first, with a UserWarning fallback to "stress" (Cauchy) for old checkpoints.
• lj.py module docstring: corrects pre-allocation example from the wrong batch["stress"] to stresses=torch.zeros(1, 3, 3) in AtomicData.
• NPT user-guide snippet (docs/userguide/dynamics_simulations.md): missing required barostat_time and thermostat_time arguments (see inline comment).

Important Files Changed

Filename	Overview
docs/userguide/dynamics_simulations.md	Updated unit comments throughout; NPT code snippet is missing required barostat_time and thermostat_time arguments (P1 issue).
nvalchemi/dynamics/base.py	Corrects batch.stress → batch.stresses in _apply_outputs; matches the named AtomicData field and fixes a silent AttributeError for NPT/NPH users.
nvalchemi/dynamics/integrators/npt.py	Fixes batch.stress → batch.stresses in compute_pressure_tensor call; updates parameter docstrings with explicit unit information.
nvalchemi/models/mace.py	Adds logic to prefer "virials" over "stress" from MACE output; emits a UserWarning when falling back to the Cauchy stress (wrong units for NPT/NPH).
nvalchemi/data/atomic_data.py	Comprehensive docstring additions: unit-agnostic framework explanation, stress/virial sign convention, per-field unit annotations for all major fields.

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into dallasf/units" | Re-trigger Greptile}

[WardLT]

Are you planning to update the sphinx documentation in this PR as well? A brief reference to the text you added to the atomic data class could be helpful

[dallasfoster]

/ok to test 05e7154

[laserkelvin]

LGTM

@WardLT I think the docs were updated; see if that satisfies you and if so I'll merge

[WardLT]

Docs look good to me too

[dallasfoster]

/ok to test 68b9f51

[dallasfoster]

/ok to test 8a4b004