metatensor · HaoZeke · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/docs/src/torch/reference/cxx/misc.rst b/docs/src/torch/reference/cxx/misc.rst
@@ -1,7 +1,9 @@
 Miscellaneous
 =============
 
-.. doxygenfunction:: metatomic_torch::unit_conversion_factor
+.. doxygenfunction:: metatomic_torch::unit_conversion_factor(const std::string &from_unit, const std::string &to_unit)
+
+.. doxygenfunction:: metatomic_torch::unit_conversion_factor(const std::string &quantity, const std::string &from_unit, const std::string &to_unit)
 
 .. doxygenfunction:: metatomic_torch::pick_device
 

diff --git a/docs/src/torch/reference/misc.rst b/docs/src/torch/reference/misc.rst
@@ -9,34 +9,82 @@ Miscellaneous
 
 .. _known-quantities-units:
 
-Known quantities and units
---------------------------
-
-The following quantities and units can be used with metatomic models. Adding new
-units and quantities is very easy, please contact us if you need something else!
-In the mean time, you can create :py:class:`metatomic.torch.ModelOutput` with
-quantities that are not in this table. A warning will be issued and no unit
-conversion will be performed.
-
-When working with one of the quantities in this table, the unit you use must be
-one of the registered unit.
-
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   quantity     | units                                                                                                                                                |
-+================+======================================================================================================================================================+
-|   **length**   | ``angstrom`` (``A``), ``Bohr``, ``meter``, ``centimeter`` (``cm``), ``millimeter`` (``mm``), ``micrometer`` (``um``, ``µm``), ``nanometer`` (``nm``) |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **energy**   | ``eV``, ``meV``, ``Hartree``, ``kcal/mol``, ``kJ/mol``, ``Joule`` (``J``), ``Rydberg`` (``Ry``)                                                      |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **force**    | ``eV/Angstrom`` (``eV/A``), ``Hartree/Bohr``                                                                                                         |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **pressure** | ``eV/Angstrom^3`` (``eV/A^3``)                                                                                                                       |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **momentum** | ``u*A/fs``, ``u*A/ps``, ``(eV*u)^(1/2)``, ``kg*m/s``, ``hbar/Bohr``                                                                                  |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|    **mass**    | ``u`` (``Dalton``), ``kg`` (``kilogram``), ``g`` (``gram``), ``electron_mass`` (``m_e``)                                                             |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **velocity** | ``nm/fs``, ``A/fs``, ``m/s``, ``nm/ps``, ``Bohr*Hartree/hbar``                                                                                       |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-|   **charge**   | ``e``, ``Coulomb`` (``C``)                                                                                                                           |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+Unit expression parser
+----------------------
+
+``unit_conversion_factor`` accepts arbitrary unit expressions built from base
+tokens combined with ``*``, ``/``, ``^``, and parentheses. For example:
+
+- ``"kJ/mol"``
+- ``"eV/Angstrom^3"``
+- ``"(eV*u)^(1/2)"``
+- ``"Hartree/Bohr"``
+
+Dimensional compatibility is verified automatically; no ``quantity`` parameter
+is needed. Token lookup is case-insensitive, and whitespace is ignored.
+
+Base unit tokens
+^^^^^^^^^^^^^^^^
+
+.. list-table:: Supported Unit Tokens
+   :header-rows: 1
+
+   * - Dimension
+     - Tokens
+     - Notes
+   * - **Length**
+     - ``angstrom`` (``a``), ``bohr``, ``nm`` (``nanometer``), ``meter`` (``m``), ``cm`` (``centimeter``), ``mm`` (``millimeter``), ``um`` (``micrometer``)
+     -
+   * - **Energy**
+     - ``ev``, ``mev``, ``hartree``, ``ry`` (``rydberg``), ``joule`` (``j``), ``kcal``, ``kj``
+     - ``kcal`` and ``kj`` are bare (not per-mol); write ``kcal/mol`` for the per-mole unit
+   * - **Time**
+     - ``s`` (``second``), ``ms`` (``millisecond``), ``us`` (``microsecond``), ``ns`` (``nanosecond``), ``ps`` (``picosecond``), ``fs`` (``femtosecond``)
+     -
+   * - **Mass**
+     - ``u`` (``dalton``), ``kg`` (``kilogram``), ``g`` (``gram``), ``electron_mass`` (``m_e``)
+     -
+   * - **Charge**
+     - ``e``, ``coulomb`` (``c``)
+     -
+   * - **Dimensionless**
+     - ``mol``
+     - Avogadro scaling factor
+   * - **Derived**
+     - ``hbar``
+     - :math:`\hbar` in SI (:math:`M L^2 T^{-1}`)
+
+Known quantities
+^^^^^^^^^^^^^^^^
+
+When setting ``quantity`` on a :py:class:`~metatomic.torch.ModelOutput`, the
+following names are recognized. The parser will check that the unit expression
+has dimensions matching the expected quantity.
+
+.. list-table:: Physical Dimensions
+   :header-rows: 1
+
+   * - quantity
+     - expected dimension
+   * - **length**
+     - :math:`L`
+   * - **energy**
+     - :math:`M L^2 T^{-2}`
+   * - **force**
+     - :math:`M L T^{-2}`
+   * - **pressure**
+     - :math:`M L^{-1} T^{-2}`
+   * - **momentum**
+     - :math:`M L T^{-1}`
+   * - **mass**
+     - :math:`M`
+   * - **velocity**
+     - :math:`L T^{-1}`
+   * - **charge**
+     - :math:`Q`
+
+.. note::
+
+   The 3-argument form ``unit_conversion_factor(quantity, from_unit, to_unit)``
+   is deprecated. Use the 2-argument form instead. The ``quantity`` parameter is
+   ignored by the parser; dimensional compatibility is checked automatically.
diff --git a/metatomic-torch/CHANGELOG.md b/metatomic-torch/CHANGELOG.md
@@ -17,6 +17,20 @@ a changelog](https://keepachangelog.com/en/1.1.0/) format. This project follows
 
 ## [Unreleased](https://github.com/metatensor/metatomic/)
 
+### Added
+
+- Unit expression parser supporting compound expressions (`kJ/mol/A^2`,
+  `(eV*u)^(1/2)`, etc.) with automatic dimensional validation
+- 2-argument `unit_conversion_factor(from_unit, to_unit)` that parses
+  arbitrary unit expressions and checks dimensional compatibility
+
+### Changed
+
+- `validate_unit` now accepts arbitrary parseable expressions and validates
+  their dimensions against the expected quantity
+- 3-argument `unit_conversion_factor(quantity, from_unit, to_unit)` is
+  deprecated; the `quantity` parameter is ignored
+
 ## [Version 0.1.11](https://github.com/metatensor/metatomic/releases/tag/metatomic-torch-v0.1.11) - 2026-02-27
 
 ### Added

diff --git a/metatomic-torch/include/metatomic/torch/model.hpp b/metatomic-torch/include/metatomic/torch/model.hpp
@@ -326,8 +326,22 @@ METATOMIC_TORCH_EXPORT metatensor_torch::Module load_atomistic_model(
     c10::optional<std::string> extensions_directory = c10::nullopt
 );
 
-/// Get the multiplicative conversion factor to use to convert from unit `from`
-/// to unit `to`. Both should be units for the given physical `quantity`.
+/// Get the multiplicative conversion factor to use to convert from
+/// `from_unit` to `to_unit`. Both units are parsed as expressions (e.g.
+/// "kJ/mol/A^2", "(eV*u)^(1/2)") and their dimensions must match.
+///
+/// Supported tokens include length (angstrom, bohr, nm, m, cm, mm, um),
+/// energy (eV, meV, hartree, ry, joule, kcal, kJ), time (s, ms, us, ns, ps,
+/// fs), mass (u, dalton, kg, g, electron_mass), charge (e, coulomb),
+/// dimensionless (mol), and derived (hbar). Case-insensitive.
+METATOMIC_TORCH_EXPORT double unit_conversion_factor(
+    const std::string& from_unit,
+    const std::string& to_unit
+);
+
+/// Deprecated 3-argument overload. The `quantity` parameter is ignored;
+/// dimensional compatibility is checked by the parser. Emits a one-time
+/// deprecation warning.
 METATOMIC_TORCH_EXPORT double unit_conversion_factor(
     const std::string& quantity,
     const std::string& from_unit,