Convert from/to

Author: mfkasim1

docs/api/toc.json

@@ -47,13 +47,13 @@
     "api": {
       "SpinParam": "",
       "ValGrad": "",
-      "length_to": "",
-      "time_to": "",
-      "freq_to": "",
-      "ir_ints_to": "",
-      "raman_ints_to": "",
-      "edipole_to": "",
-      "equadrupole_to": ""
+      "convert_length": "",
+      "convert_time": "",
+      "convert_freq": "",
+      "convert_ir_ints": "",
+      "convert_raman_ints": "",
+      "convert_edipole": "",
+      "convert_equadrupole": ""
     }
   }
 }

dqc/api/properties.py

@@ -8,8 +8,9 @@
 from dqc.qccalc.base_qccalc import BaseQCCalc
 from dqc.utils.misc import memoize_method
 from dqc.utils.datastruct import SpinParam
-from dqc.utils.units import length_to, freq_to, edipole_to, equadrupole_to, ir_ints_to, \
-                            raman_ints_to
+from dqc.utils.units import convert_length, convert_freq, convert_edipole, \
+                            convert_equadrupole, convert_ir_ints, \
+                            convert_raman_ints
 
 __all__ = ["hessian_pos", "vibration", "edipole", "equadrupole", "is_orb_min",
            "lowest_eival_orb_hessian", "ir_spectrum", "raman_spectrum"]
@@ -35,7 +36,7 @@ def hessian_pos(qc: BaseQCCalc, unit: Optional[str] = None) -> torch.Tensor:
         of the energy with respect to the atomic position
     """
     hess = _hessian_pos(qc)
-    hess = length_to(hess, unit)
+    hess = convert_freq(hess, to_unit=unit)
     return hess
 
 def vibration(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
@@ -64,8 +65,8 @@ def vibration(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
         to each axis sorted from the largest frequency to smallest frequency.
     """
     freq, mode = _vibration(qc)
-    freq = freq_to(freq, freq_unit)
-    mode = length_to(mode, length_unit)
+    freq = convert_freq(freq, to_unit=freq_unit)
+    mode = convert_length(mode, to_unit=length_unit)
     return freq, mode
 
 def ir_spectrum(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
@@ -93,8 +94,8 @@ def ir_spectrum(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
         tensor is the IR intensity with the same order as the frequency.
     """
     freq, ir_ints = _ir_spectrum(qc)
-    freq = freq_to(freq, freq_unit)
-    ir_ints = ir_ints_to(ir_ints, ints_unit)
+    freq = convert_freq(freq, to_unit=freq_unit)
+    ir_ints = convert_ir_ints(ir_ints, to_unit=ints_unit)
     return freq, ir_ints
 
 def raman_spectrum(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
@@ -121,8 +122,8 @@ def raman_spectrum(qc: BaseQCCalc, freq_unit: Optional[str] = "cm^-1",
         tensor is the IR intensity with the same order as the frequency.
     """
     freq, raman_ints = _raman_spectrum(qc)
-    freq = freq_to(freq, freq_unit)
-    raman_ints = raman_ints_to(raman_ints, ints_unit)
+    freq = convert_freq(freq, to_unit=freq_unit)
+    raman_ints = convert_raman_ints(raman_ints, to_unit=ints_unit)
     return freq, raman_ints
 
 def edipole(qc: BaseQCCalc, unit: Optional[str] = "Debye") -> torch.Tensor:
@@ -144,7 +145,7 @@ def edipole(qc: BaseQCCalc, unit: Optional[str] = "Debye") -> torch.Tensor:
         Tensor representing the dipole moment in atomic unit with shape ``(ndim,)``
     """
     edip = _edipole(qc)
-    edip = edipole_to(edip, unit)
+    edip = convert_edipole(edip, to_unit=unit)
     return edip
 
 def equadrupole(qc: BaseQCCalc, unit: Optional[str] = "Debye*Angst") -> torch.Tensor:
@@ -165,7 +166,7 @@ def equadrupole(qc: BaseQCCalc, unit: Optional[str] = "Debye*Angst") -> torch.Te
         Tensor representing the quadrupole moment in atomic unit in ``(ndim, ndim)``
     """
     equad = _equadrupole(qc)
-    equad = equadrupole_to(equad, unit)
+    equad = convert_equadrupole(equad, to_unit=unit)
     return equad
 
 @memoize_method

dqc/test/test_utils.py

@@ -1,5 +1,25 @@
+import torch
+import dqc.utils
 from dqc.utils.config import config
 from dqc.utils.misc import logger
+from dqc.test.utils import assert_fail
+
+def test_converter_length():
+    a = torch.tensor([1.0])
+
+    # convert to itself
+    assert torch.allclose(dqc.utils.convert_length(a), a)
+    # convert from atomic unit to angstrom
+    assert torch.allclose(dqc.utils.convert_length(a, to_unit="angst"), a * 5.29177210903e-1)
+    # convert from angstrom to atomic unit
+    assert torch.allclose(dqc.utils.convert_length(a, from_unit="angst"), a / 5.29177210903e-1)
+    # convert from angstrom to angstrom
+    assert torch.allclose(dqc.utils.convert_length(a, from_unit="angst", to_unit="angst"), a)
+    assert torch.allclose(dqc.utils.convert_length(a, from_unit="angst", to_unit="angstrom"), a)
+
+def test_converter_wrong_unit():
+    a = torch.tensor([1.0])
+    assert_fail(lambda: dqc.utils.convert_length(a, from_unit="adsfa"), ValueError, ["'angst'"])
 
 def test_logger(capsys):
     # test if logger behaves correctly

dqc/test/utils.py

@@ -1,8 +1,24 @@
 import gc
 import torch
-from typing import Callable
+from typing import Callable, Optional, List, Union
 
-__all__ = ["assert_no_memleak_tensor"]
+__all__ = ["assert_fail", "assert_no_memleak_tensor"]
+
+def assert_fail(fcn: Callable, err: Exception = Exception, contains: Optional[Union[str, List[str]]] = None):
+    try:
+        fcn()
+    except err as e:
+        if isinstance(contains, str):
+            assert contains in str(e), f"The error message must contain '{contains}'. Got {str(e)} instead."
+        elif isinstance(contains, list) or isinstance(contains, tuple):
+            for c in contains:
+                assert c in str(e), f"The error message must contain '{c}'. Got {str(e)} instead."
+        return
+    except Exception as e:
+        assert False, f"Expected {err} to be raised, got {type(e)} instead:\n{e}"
+        return
+
+    assert False, f"Expected {err} to be raised"
 
 # memory test functions
 def assert_no_memleak_tensor(fcn: Callable, strict: bool = True, gccollect: bool = False):

dqc/utils/units.py

@@ -4,8 +4,8 @@
 # This file contains various physical constants and functions to convert units
 # from the atomic units
 
-__all__ = ["length_to", "time_to", "freq_to", "ir_ints_to", "raman_ints_to",
-           "edipole_to", "equadrupole_to"]
+__all__ = ["convert_length", "convert_time", "convert_freq", "convert_ir_ints",
+           "convert_raman_ints", "convert_edipole", "convert_equadrupole"]
 
 # 1 atomic unit in SI
 LENGTH = 5.29177210903e-11  # m
@@ -81,61 +81,97 @@
 
 def _avail_keys(converter: Dict[str, float]) -> str:
     # returns the available keys in a string of list of string
-    return str(list(_length_converter.keys()))
+    return str(list(converter.keys()))
 
 def _add_docstr_to(phys: str, converter: Dict[str, float]) -> Callable:
     # automatically add docstring for converter functions
 
     def decorator(callable: Callable):
         callable.__doc__ = f"""
-            Convert the {phys} from atomic unit to the given unit.
-            Available units are (case-insensitive): {_avail_keys(converter)}
+            Convert the {phys} from a unit to another unit.
+            Available units are (case-insensitive): ``{_avail_keys(converter)}``
+
+            Arguments
+            ---------
+            a: torch.Tensor
+                The tensor to be converter.
+            from_unit: str or None
+                The unit of ``a``. If ``None``, it is assumed to be in atomic unit.
+            to_unit: str or None
+                The unit for ``a`` to be converted to. If ``None``, it is assumed
+                to be converted to the atomic unit.
+
+            Returns
+            -------
+            torch.Tensor
+                The tensor in the new unit.
         """
         return callable
     return decorator
 
 @_add_docstr_to("time", _time_converter)
-def time_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_time(a: PhysVarType, from_unit: UnitType = None,
+                 to_unit: UnitType = None) -> PhysVarType:
     # convert unit time from atomic unit to the given unit
-    return _converter_to(a, unit, _time_converter)
+    return _converter(a, from_unit, to_unit, _time_converter)
 
 @_add_docstr_to("frequency", _freq_converter)
-def freq_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_freq(a: PhysVarType, from_unit: UnitType = None,
+                 to_unit: UnitType = None) -> PhysVarType:
     # convert unit frequency from atomic unit to the given unit
-    return _converter_to(a, unit, _freq_converter)
+    return _converter(a, from_unit, to_unit, _freq_converter)
 
 @_add_docstr_to("IR intensity", _ir_ints_converter)
-def ir_ints_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_ir_ints(a: PhysVarType, from_unit: UnitType = None,
+                    to_unit: UnitType = None) -> PhysVarType:
     # convert unit IR intensity from atomic unit to the given unit
-    return _converter_to(a, unit, _ir_ints_converter)
+    return _converter(a, from_unit, to_unit, _ir_ints_converter)
 
 @_add_docstr_to("Raman intensity", _raman_ints_converter)
-def raman_ints_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_raman_ints(a: PhysVarType, from_unit: UnitType = None,
+                       to_unit: UnitType = None) -> PhysVarType:
     # convert unit IR intensity from atomic unit to the given unit
-    return _converter_to(a, unit, _raman_ints_converter)
+    return _converter(a, from_unit, to_unit, _raman_ints_converter)
 
 @_add_docstr_to("length", _length_converter)
-def length_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_length(a: PhysVarType, from_unit: UnitType = None,
+                   to_unit: UnitType = None) -> PhysVarType:
     # convert unit length from atomic unit to the given unit
-    return _converter_to(a, unit, _length_converter)
+    return _converter(a, from_unit, to_unit, _length_converter)
 
 @_add_docstr_to("electric dipole", _edipole_converter)
-def edipole_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_edipole(a: PhysVarType, from_unit: UnitType = None,
+                    to_unit: UnitType = None) -> PhysVarType:
     # convert unit electric dipole from atomic unit to the given unit
-    return _converter_to(a, unit, _edipole_converter)
+    return _converter(a, from_unit, to_unit, _edipole_converter)
 
 @_add_docstr_to("electric quadrupole", _equadrupole_converter)
-def equadrupole_to(a: PhysVarType, unit: UnitType) -> PhysVarType:
+def convert_equadrupole(a: PhysVarType, from_unit: UnitType = None,
+                        to_unit: UnitType = None) -> PhysVarType:
     # convert unit electric dipole from atomic unit to the given unit
-    return _converter_to(a, unit, _equadrupole_converter)
-
-def _converter_to(a: PhysVarType, unit: UnitType, converter: Dict[str, float]) -> PhysVarType:
-    # converter from the atomic unit
-    if unit is None:
+    return _converter(a, from_unit, to_unit, _equadrupole_converter)
+
+def _converter(a: PhysVarType, from_unit: UnitType, to_unit: UnitType,
+               converter: Dict[str, float]) -> PhysVarType:
+    # converter from a unit to another unit
+    from_unit = _preproc_unit(from_unit)
+    to_unit = _preproc_unit(to_unit)
+    if from_unit == to_unit:
         return a
-    u = unit.lower()
-    try:
-        return a * converter[u]
-    except KeyError:
+    if from_unit is not None:
+        a = a / _get_converter_value(converter, from_unit)
+    if to_unit is not None:
+        a = a * _get_converter_value(converter, to_unit)
+    return a
+
+def _get_converter_value(converter: Dict[str, float], unit: UnitType) -> float:
+    if unit not in converter:
         avail_units = _avail_keys(converter)
         raise ValueError(f"Unknown unit: {unit}. Available units are: {avail_units}")
+    return converter[unit]
+
+def _preproc_unit(unit: UnitType):
+    if unit is None:
+        return unit
+    else:
+        return ''.join(unit.lower().split())