refactor(quantity): use [[deprecated]] attr, TORCH_WARN_DEPRECATION, and remove quantity-based unit conversion

- Add [[deprecated]] attribute to quantity() getter and set_quantity()
  in model.hpp for compile-time warnings
- Switch from TORCH_WARN to TORCH_WARN_DEPRECATION with std::once_flag
  in set_quantity() for proper runtime deprecation signaling
- Remove quantity-based unit conversion logic from model.py; unit
  conversion now uses declared/requested unit fields directly
- Revert conftest.py files to strict stderr checking; catch deprecation
  warnings explicitly at emission sites using capfd in affected tests
  and fixtures
- Add filterwarnings for ModelOutput.quantity DeprecationWarning in ASE
  and torchsim pyproject.toml

Author: HaoZeke

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

@@ -55,15 +55,17 @@ class METATOMIC_TORCH_EXPORT ModelOutputHolder: public torch::CustomClassHolder
     /// description of this output, defaults to empty string of not set by the user
     std::string description;
 
-    /// quantity of the output (e.g. energy, dipole, …).  If this is an empty
+    /// quantity of the output (e.g. energy, dipole, ...).  If this is an empty
     /// string, no unit conversion will be performed.
     /// @deprecated This field is no longer required for unit conversion.
     ///             The unit parser determines dimensions from the expression itself.
+    [[deprecated("quantity is no longer required for unit conversion, use unit directly")]]
     const std::string& quantity() const {
         return quantity_;
     }
 
     /// set the quantity of the output
+    [[deprecated("quantity is no longer required for unit conversion, use unit directly")]]
     void set_quantity(std::string quantity);
 
     /// unit of the output. If this is an empty string, no unit conversion will

metatomic-torch/src/model.cpp

@@ -1,4 +1,5 @@
 #include <cstring>
+#include <mutex>
 
 #include <sstream>
 #include <filesystem>
@@ -55,11 +56,14 @@ static void read_vector_int_json(
 
 void ModelOutputHolder::set_quantity(std::string quantity) {
     if (!quantity.empty()) {
-        TORCH_WARN(
-            "ModelOutput.quantity is deprecated and will be removed in a future version. "
-            "The quantity field is no longer required for unit conversion since the "
-            "unit parser determines dimensions from the expression itself."
-        );
+        static std::once_flag warn_flag;
+        std::call_once(warn_flag, []() {
+            TORCH_WARN_DEPRECATION(
+                "ModelOutput.quantity is deprecated and will be removed in a future version. "
+                "The quantity field is no longer required for unit conversion since the "
+                "unit parser determines dimensions from the expression itself."
+            );
+        });
     }
     if (valid_quantity(quantity)) {
         validate_unit(quantity, unit_);

python/metatomic_ase/pyproject.toml

@@ -44,6 +44,8 @@ python_files = ["*.py"]
 testpaths = ["tests"]
 filterwarnings = [
     "error",
+    # ModelOutput.quantity deprecation (C++ TORCH_WARN_DEPRECATION)
+    "ignore:ModelOutput.quantity is deprecated:DeprecationWarning",
     # TorchScript deprecation warnings
     "ignore:`torch.jit.script` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",
     "ignore:`torch.jit.script_method` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",

python/metatomic_ase/tests/calculator.py

@@ -37,8 +37,8 @@
 
 
 @pytest.fixture
-def model():
-    return metatomic_lj_test.lennard_jones_model(
+def model(capfd):
+    m = metatomic_lj_test.lennard_jones_model(
         atomic_type=28,
         cutoff=CUTOFF,
         sigma=SIGMA,
@@ -47,11 +47,16 @@ def model():
         energy_unit="eV",
         with_extension=False,
     )
+    # consume the once-per-process quantity deprecation warning from C++
+    captured = capfd.readouterr()
+    if captured.err:
+        assert "ModelOutput.quantity is deprecated" in captured.err
+    return m
 
 
 @pytest.fixture
-def model_different_units():
-    return metatomic_lj_test.lennard_jones_model(
+def model_different_units(capfd):
+    m = metatomic_lj_test.lennard_jones_model(
         atomic_type=28,
         cutoff=CUTOFF / ase.units.Bohr,
         sigma=SIGMA / ase.units.Bohr,
@@ -60,6 +65,10 @@ def model_different_units():
         energy_unit="kJ/mol",
         with_extension=False,
     )
+    captured = capfd.readouterr()
+    if captured.err:
+        assert "ModelOutput.quantity is deprecated" in captured.err
+    return m
 
 
 @pytest.fixture
@@ -793,7 +802,7 @@ def forward(
         }
 
 
-def test_additional_input(atoms):
+def test_additional_input(atoms, capfd):
     inputs = {
         "masses": ModelOutput(quantity="mass", unit="u", per_atom=True),
         "velocities": ModelOutput(quantity="velocity", unit="A/fs", per_atom=True),
@@ -833,6 +842,11 @@ def test_additional_input(atoms):
 
         assert np.allclose(values, expected)
 
+    # consume the once-per-process quantity deprecation warning from C++
+    captured = capfd.readouterr()
+    if captured.err:
+        assert "ModelOutput.quantity is deprecated" in captured.err
+
 
 @pytest.mark.parametrize("device,dtype", ALL_DEVICE_DTYPE)
 def test_mixed_pbc(model, device, dtype):

python/metatomic_ase/tests/conftest.py

@@ -1,5 +1,3 @@
-import re
-
 import pytest
 
 
@@ -8,17 +6,5 @@ def fail_test_with_output(capfd):
     yield
     captured = capfd.readouterr()
     # the code should not print anything to stdout or stderr
-    # except for expected deprecation warnings
     assert captured.out == ""
-    # Filter out expected deprecation warnings
-    stderr_lines = captured.err.splitlines()
-    unexpected_errors = [
-        line
-        for line in stderr_lines
-        if not re.search(
-            r"(ModelOutput\.quantity is deprecated|"
-            r"compute_requested_neighbors_from_options.*is deprecated)",
-            line,
-        )
-    ]
-    assert "".join(unexpected_errors) == "", f"Unexpected stderr output: {captured.err}"
+    assert captured.err == ""

python/metatomic_torch/metatomic/torch/model.py

@@ -265,7 +265,6 @@ class AtomisticModel(torch.nn.Module):
     >>> capabilities = ModelCapabilities(
     ...     outputs={
     ...         "energy": ModelOutput(
-    ...             quantity="energy",
     ...             unit="eV",
     ...             per_atom=False,
     ...             explicit_gradients=[],
@@ -507,21 +506,9 @@ def forward(
             for name, output in outputs.items():
                 declared = self._capabilities.outputs[name]
                 requested = options.outputs.get(name, ModelOutput())
-                if declared.quantity == "" or requested.quantity == "":
+                if declared.unit == "" or requested.unit == "":
                     continue
 
-                # Note: Deprecation warning for quantity is emitted from C++ when
-                # ModelOutput is constructed with non-empty quantity.
-                # We don't warn here because TorchScript can't handle
-                # DeprecationWarning.
-
-                if declared.quantity != requested.quantity:
-                    raise ValueError(
-                        f"model produces values as '{declared.quantity}' for the "
-                        f"'{name}' output, but the engine requested "
-                        f"'{requested.quantity}'"
-                    )
-
                 conversion = unit_conversion_factor(
                     declared.unit,
                     requested.unit,

python/metatomic_torch/tests/conftest.py

@@ -1,5 +1,3 @@
-import re
-
 import pytest
 
 
@@ -8,17 +6,5 @@ def fail_test_with_output(capfd):
     yield
     captured = capfd.readouterr()
     # the code should not print anything to stdout or stderr
-    # except for expected deprecation warnings
     assert captured.out == ""
-    # Filter out expected deprecation warnings
-    stderr_lines = captured.err.splitlines()
-    unexpected_errors = [
-        line
-        for line in stderr_lines
-        if not re.search(
-            r"(ModelOutput\.quantity is deprecated|"
-            r"compute_requested_neighbors_from_options.*is deprecated)",
-            line,
-        )
-    ]
-    assert "".join(unexpected_errors) == "", f"Unexpected stderr output: {captured.err}"
+    assert captured.err == ""

python/metatomic_torch/tests/units.py

@@ -317,10 +317,9 @@ def test_micro_sign_microsecond():
 # ---- Quantity-unit mismatch ----
 
 
-def test_quantity_unit_mismatch():
+def test_quantity_unit_mismatch(capfd):
     # energy quantity with force unit
     # quantity parameter is deprecated, but we still test unit validation
-    # Warning is emitted via C++ TORCH_WARN, not Python warnings
     with pytest.raises((ValueError, RuntimeError), match="incompatible with quantity"):
         ModelOutput(quantity="energy", unit="eV/A")
 
@@ -332,6 +331,12 @@ def test_quantity_unit_mismatch():
     with pytest.raises((ValueError, RuntimeError), match="incompatible with quantity"):
         ModelOutput(quantity="length", unit="eV/A^3")
 
+    # consume the once-per-process quantity deprecation warning from C++
+    captured = capfd.readouterr()
+    assert captured.out == ""
+    if captured.err:
+        assert "ModelOutput.quantity is deprecated" in captured.err
+
 
 # ---- Deprecation warning for 3-arg C++ op ----
 

python/metatomic_torchsim/pyproject.toml

@@ -45,6 +45,8 @@ python_files = ["*.py"]
 testpaths = ["tests"]
 filterwarnings = [
     "error",
+    # ModelOutput.quantity deprecation (C++ TORCH_WARN_DEPRECATION)
+    "ignore:ModelOutput.quantity is deprecated:DeprecationWarning",
     # TorchScript deprecation warnings
     "ignore:`torch.jit.script` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",
     "ignore:`torch.jit.script_method` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",

python/metatomic_torchsim/tests/conftest.py

@@ -1,5 +1,3 @@
-import re
-
 import pytest
 
 
@@ -8,17 +6,5 @@ def fail_test_with_output(capfd):
     yield
     captured = capfd.readouterr()
     # the code should not print anything to stdout or stderr
-    # except for expected deprecation warnings
     assert captured.out == ""
-    # Filter out expected deprecation warnings
-    stderr_lines = captured.err.splitlines()
-    unexpected_errors = [
-        line
-        for line in stderr_lines
-        if not re.search(
-            r"(ModelOutput\.quantity is deprecated|"
-            r"compute_requested_neighbors_from_options.*is deprecated)",
-            line,
-        )
-    ]
-    assert "".join(unexpected_errors) == "", f"Unexpected stderr output: {captured.err}"
+    assert captured.err == ""