clarify language on units for custom MD algorithms, remove default units

CHANGELOG.rst

@@ -12,6 +12,8 @@ Breaking changes:
   avoid confusions. Use ``make_trainvalidtest_split(test_size=a, valid_size=b)``
   instead of ``make_trainvalidtest_split(a, b)``.
 - Invalid custom kernel specifications are now errors rather than warnings.
+- Default values for ``units_force`` and ``units_acc`` in the custom MD classes
+  ``VelocityVerlet`` and ``LangevinDynamics`` have been removed. 
 
 
 New Features:

hippynn/molecular_dynamics/__init__.py

@@ -7,7 +7,7 @@
 
 """
 
-from .md import MolecularDynamics, Variable, NullUpdater, VelocityVerlet, LangevinDynamics
+from .md import MolecularDynamics, Variable, NullUpdater, VelocityVerlet, LangevinDynamics, VariableUpdater
 
 
-__all__ = ["MolecularDynamics", "Variable", "NullUpdater", "VelocityVerlet", "LangevinDynamics"]
+__all__ = ["MolecularDynamics", "Variable", "NullUpdater", "VelocityVerlet", "LangevinDynamics", "VariableUpdater"]

hippynn/molecular_dynamics/md.py

@@ -5,7 +5,6 @@
 
 import numpy as np
 import torch
-import ase
 
 from ..tools import progress_bar
 from ..graphs import Predictor
@@ -196,23 +195,17 @@ class VelocityVerlet(VariableUpdater):
     def __init__(
         self,
         force_db_name: str,
-        units_force: float = None,
-        units_acc: float = None,
+        units_force: float,
+        units_acc: float,
     ):
         """
         :param force_db_name: key which will correspond to the force on the corresponding Variable
             in the HIPNN model output dictionary
-        :param units_force: amount of eV equal to one in the units used for force output
-            of HIPNN model (eg. if force output in kcal/mol/A, units_force =
-            ase.units.kcal/ase.units.mol/ase.units.Ang ~=.0434 since .0434 kcal ~= 1 eV),
-            by default ase.units.eV = 1, defaults to ase.units.eV / ase.units.Ang
-        :param units_acc: amount of Ang/fs^2 equal to one in the units used for acceleration
-            in the corresponding Variable, by default units.Ang/(1.0 ** 2) = 1, defaults to ase.units.Ang/(1.0**2)
+        :param units_force: force units via ase.units (eg. ase.units.kcal/ase.units.mol/ase.units.Ang),
+        :param units_acc: acceleration units via ase.units (eg. ase.units.Ang/(ase.units.ps**2)),
+
+        mass of attached Variable must be in amu
         """
-        if units_force is None:
-            units_force = ase.units.eV / ase.units.Ang
-        if units_acc is None:
-            units_acc = ase.units.Ang / (1.0**2)
         self.force_key = force_db_name
         self.force_factor = units_force / units_acc
 
@@ -256,28 +249,21 @@ def __init__(
         force_db_name: str,
         temperature: float,
         frix: float,
-        units_force: float = None,
-        units_acc: float = None,
+        units_force: float,
+        units_acc: float,
         seed: Optional[int] = None,
     ):
         """
         :param force_db_name: key which will correspond to the force on the corresponding Variable
             in the HIPNN model output dictionary
         :param temperature: temperature for Langevin algorithm
         :param frix: friction coefficient for Langevin algorithm
-        :param units_force: amount of eV equal to one in the units used for force output
-            of HIPNN model (eg. if force output in kcal/mol/A, units_force =
-            ase.units.kcal/ase.units.mol/ase.units.Ang ~=.0434 since .0434 kcal ~= 1 eV),
-            by default ase.units.eV = 1, defaults to ase.units.eV / ase.units.Ang
-        :param units_acc: amount of Ang/fs^2 equal to one in the units used for acceleration
-            in the corresponding Variable, by default units.Ang/(1.0 ** 2) = 1, defaults to ase.units.Ang/(1.0**2)
+        :param units_force: force units via ase.units (eg. ase.units.kcal/ase.units.mol/ase.units.Ang),
+        :param units_acc: acceleration units via ase.units (eg. ase.units.Ang/(ase.units.ps**2)),
         :param seed: used to set seed for reproducibility, defaults to None
-        """
-        if units_force is None:
-            units_force = ase.units.eV / ase.units.Ang
-        if units_acc is None:
-            units_acc = ase.units.Ang / (1.0**2)
 
+        mass of attached Variable must be in amu
+        """
         self.force_key = force_db_name
         self.force_factor = units_force / units_acc
         self.temperature = temperature
@@ -301,6 +287,7 @@ def pre_step(self, dt:float):
                 self.variable.data["unwrapped_position"] = self.variable.data["unwrapped_position"] + self.variable.data["velocity"] * dt
             except KeyError:
                 self.variable.data["unwrapped_position"] = copy(self.variable.data["position"])
+
     def post_step(self, dt: float, model_outputs: dict):
         """
         Updates to variables performed during each step of MD simulation after HIPNN model evaluation