feat(units): add an expression parser

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
 

docs/src/torch/reference/misc.rst

@@ -7,36 +7,62 @@ Miscellaneous
 
 .. autofunction:: metatomic.torch.unit_conversion_factor
 
-.. _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``)                                                                                                                           |
-+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
+The set of recognized base units is documented in the
+:cpp:func:`C++ API reference <metatomic_torch::unit_conversion_factor>`.
+
+The :py:func:`unit_conversion_factor` function accepts any valid unit expression
+built from base units combined with operators. There is no need to specify a
+physical quantity --- the parser automatically verifies dimensional compatibility
+between the source and target units.
+
+.. _known-base-units:
+
+Supported base units
+~~~~~~~~~~~~~~~~~~~~
+
+Unit expressions are built from the following base units. Matching is
+case-insensitive, and whitespace is ignored.
+
+**Length**:
+  ``angstrom`` (``A``), ``Bohr``, ``meter`` (``m``), ``centimeter`` (``cm``),
+  ``millimeter`` (``mm``), ``micrometer`` (``um``, ``µm``), ``nanometer`` (``nm``)
+
+**Energy**:
+  ``eV``, ``meV``, ``Hartree``, ``kcal``, ``kJ``, ``Joule`` (``J``), ``Rydberg`` (``Ry``)
+
+**Time**:
+  ``second`` (``s``), ``millisecond`` (``ms``), ``microsecond`` (``us``, ``µs``),
+  ``nanosecond`` (``ns``), ``picosecond`` (``ps``), ``femtosecond`` (``fs``)
+
+**Mass**:
+  ``u`` (``Dalton``), ``kilogram`` (``kg``), ``gram`` (``g``), ``electron_mass`` (``m_e``)
+
+**Charge**:
+  ``e``, ``Coulomb`` (``C``)
+
+**Dimensionless**:
+  ``mol``
+
+**Derived constants**:
+  ``hbar``
+
+Expression syntax
+~~~~~~~~~~~~~~~~~~~
+
+Base units can be combined using the following operators:
+
+- Multiplication: ``*`` or whitespace (``kJ mol``, ``kJ*mol``)
+- Division: ``/`` (``kJ/mol``)
+- Exponentiation: ``^`` (``A^3``, ``m^2``)
+- Parentheses: ``()`` for grouping (``(eV*u)^(1/2)``)
+
+Examples of valid compound expressions:
+
+- ``kJ/mol`` --- energy per mole
+- ``eV/Angstrom^3`` or ``eV/A^3`` --- pressure
+- ``(eV*u)^(1/2)`` --- momentum (fractional powers)
+- ``Hartree/Bohr`` --- force in atomic units
+- ``nm/fs`` --- velocity
+
+The parser automatically checks that both unit expressions have matching
+physical dimensions before computing the conversion factor.

metatomic-torch/CHANGELOG.md

@@ -17,6 +17,18 @@ 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
+
+- 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

metatomic-torch/CMakeLists.txt

@@ -96,6 +96,7 @@ find_package(Torch 2.3 REQUIRED)
 set(METATOMIC_TORCH_HEADERS
     "include/metatomic/torch/system.hpp"
     "include/metatomic/torch/model.hpp"
+    "include/metatomic/torch/units.hpp"
     "include/metatomic/torch.hpp"
     "include/metatomic/torch/outputs.hpp"
 )
@@ -104,6 +105,7 @@ set(METATOMIC_TORCH_SOURCE
     "src/misc.cpp"
     "src/system.cpp"
     "src/model.cpp"
+    "src/units.cpp"
     "src/outputs.cpp"
     "src/register.cpp"
     "src/internal/shared_libraries.cpp"

metatomic-torch/include/metatomic/torch.hpp

@@ -4,4 +4,5 @@
 #include "metatomic/torch/misc.hpp"    // IWYU pragma: export
 #include "metatomic/torch/system.hpp"  // IWYU pragma: export
 #include "metatomic/torch/model.hpp"   // IWYU pragma: export
+#include "metatomic/torch/units.hpp"   // IWYU pragma: export
 #include "metatomic/torch/outputs.hpp"  // IWYU pragma: export

metatomic-torch/include/metatomic/torch/model.hpp

@@ -28,16 +28,6 @@ class ModelMetadataHolder;
 /// TorchScript will always manipulate `ModelMetadataHolder` through a `torch::intrusive_ptr`
 using ModelMetadata = torch::intrusive_ptr<ModelMetadataHolder>;
 
-/// Check that a given physical quantity is valid and known. This is
-/// intentionally not exported with `METATOMIC_TORCH_EXPORT`, and is only
-/// intended for internal use.
-bool valid_quantity(const std::string& quantity);
-
-/// Check that a given unit is valid and known for some physical quantity. This
-/// is intentionally not exported with `METATOMIC_TORCH_EXPORT`, and is only
-/// intended for internal use.
-void validate_unit(const std::string& quantity, const std::string& unit);
-
 
 /// Information about one of the quantity a model can compute
 class METATOMIC_TORCH_EXPORT ModelOutputHolder: public torch::CustomClassHolder {
@@ -326,14 +316,6 @@ 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`.
-METATOMIC_TORCH_EXPORT double unit_conversion_factor(
-    const std::string& quantity,
-    const std::string& from_unit,
-    const std::string& to_unit
-);
-
 }
 
 #endif

metatomic-torch/include/metatomic/torch/units.hpp

@@ -0,0 +1,77 @@
+#ifndef METATOMIC_TORCH_UNITS_HPP
+#define METATOMIC_TORCH_UNITS_HPP
+
+#include <string>
+
+#include "metatomic/torch/exports.h"
+
+namespace metatomic_torch {
+
+/// Check that a given physical quantity is valid and known. This is
+/// intentionally not exported with `METATOMIC_TORCH_EXPORT`, and is only
+/// intended for internal use.
+///
+/// Known quantities are: "length", "energy", "force", "pressure", "momentum",
+/// "mass", "velocity", and "charge".
+bool valid_quantity(const std::string& quantity);
+
+/// Check that a given unit is valid and known for some physical quantity. This
+/// is intentionally not exported with `METATOMIC_TORCH_EXPORT`, and is only
+/// intended for internal use.
+///
+/// This function parses the unit expression and verifies that its physical
+/// dimensions match the expected dimensions for the given quantity. For example,
+/// `validate_unit("energy", "eV")` succeeds, but `validate_unit("energy", "eV/A")`
+/// throws an error because eV/A has dimensions of force, not energy.
+void validate_unit(const std::string& quantity, const std::string& unit);
+
+/// 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.
+///
+/// Unit expressions are built from base units combined with `*`, `/`, `^`,
+/// and parentheses. Unit lookup is case-insensitive, and whitespace is
+/// ignored. For example:
+///
+/// - `"kJ/mol"` -- energy per mole
+/// - `"eV/Angstrom^3"` -- pressure
+/// - `"(eV*u)^(1/2)"` -- momentum (fractional powers)
+/// - `"Hartree/Bohr"` -- force in atomic units
+///
+/// Supported base units:
+///
+/// - **Length**: angstrom (A), bohr, nanometer (nm), meter (m),
+///   centimeter (cm), millimeter (mm), micrometer (um, µm)
+/// - **Energy**: eV, meV, Hartree, Ry (rydberg), Joule (J), kcal, kJ
+///   (note: kcal and kJ are bare; write kcal/mol for per-mole)
+/// - **Time**: second (s), millisecond (ms), microsecond (us, µs),
+///   nanosecond (ns), picosecond (ps), femtosecond (fs)
+/// - **Mass**: dalton (u), kilogram (kg), gram (g), electron_mass (m_e)
+/// - **Charge**: e, coulomb (c)
+/// - **Dimensionless**: mol
+/// - **Derived**: hbar
+///
+/// Note on quantity validation:
+/// The 2-argument form `unit_conversion_factor(from_unit, to_unit)` does not
+/// take a quantity parameter. Dimensional compatibility is checked automatically
+/// by comparing the parsed dimensions of both unit expressions. The deprecated
+/// 3-argument form accepts a `quantity` parameter, but it is ignored for the
+/// conversion calculation - it only emits a deprecation warning.
+METATOMIC_TORCH_EXPORT double unit_conversion_factor(
+    const std::string& from_unit,
+    const std::string& to_unit
+);
+
+/// @deprecated Use the 2-argument overload instead. The `quantity` parameter
+/// is ignored; dimensional compatibility is checked by the parser. Emits a
+/// one-time runtime deprecation warning.
+[[deprecated("use the 2-argument unit_conversion_factor(from_unit, to_unit) instead")]]
+METATOMIC_TORCH_EXPORT double unit_conversion_factor(
+    const std::string& quantity,
+    const std::string& from_unit,
+    const std::string& to_unit
+);
+
+}
+
+#endif