mlmm-toolkit 0.2.2.dev0__py3-none-any.whl

hessian_ff/tests/data/small/complex.pdb

@@ -0,0 +1,125 @@
+ATOM      1  N   GLY     1      47.321  49.145  36.060  1.00  0.00
+ATOM      2  H1  GLY     1      47.638  49.049  35.106  1.00  0.00
+ATOM      3  H2  GLY     1      47.907  49.820  36.530  1.00  0.00
+ATOM      4  H3  GLY     1      46.318  49.262  36.059  1.00  0.00
+ATOM      5  CA  GLY     1      47.561  47.880  36.747  1.00  0.00
+ATOM      6  HA2 GLY     1      48.201  48.046  37.613  1.00  0.00
+ATOM      7  HA3 GLY     1      46.613  47.477  37.104  1.00  0.00
+ATOM      8  C   GLY     1      48.201  46.829  35.834  1.00  0.00
+ATOM      9  O   GLY     1      47.731  46.579  34.722  1.00  0.00
+ATOM     10  N   ILE     2      49.244  46.171  36.323  1.00  0.00
+ATOM     11  H   ILE     2      49.629  46.469  37.215  1.00  0.00
+ATOM     12  CA  ILE     2      49.849  44.995  35.697  1.00  0.00
+ATOM     13  HA  ILE     2      49.397  44.851  34.717  1.00  0.00
+ATOM     14  CB  ILE     2      51.369  45.154  35.470  1.00  0.00
+ATOM     15  HB  ILE     2      51.884  45.038  36.423  1.00  0.00
+ATOM     16  CG2 ILE     2      51.816  44.023  34.525  1.00  0.00
+ATOM     17 HG21 ILE     2      51.340  44.130  33.551  1.00  0.00
+ATOM     18 HG22 ILE     2      52.888  44.063  34.368  1.00  0.00
+ATOM     19 HG23 ILE     2      51.583  43.044  34.945  1.00  0.00
+ATOM     20  CG1 ILE     2      51.735  46.545  34.899  1.00  0.00
+ATOM     21 HG12 ILE     2      51.202  46.705  33.963  1.00  0.00
+ATOM     22 HG13 ILE     2      51.423  47.317  35.603  1.00  0.00
+ATOM     23  CD1 ILE     2      53.234  46.748  34.658  1.00  0.00
+ATOM     24 HD11 ILE     2      53.592  46.071  33.887  1.00  0.00
+ATOM     25 HD12 ILE     2      53.408  47.765  34.313  1.00  0.00
+ATOM     26 HD13 ILE     2      53.789  46.579  35.582  1.00  0.00
+ATOM     27  C   ILE     2      49.518  43.780  36.563  1.00  0.00
+ATOM     28  O   ILE     2      49.997  43.653  37.693  1.00  0.00
+ATOM     29  N   ARG     3      48.662  42.897  36.045  1.00  0.00
+ATOM     30  H   ARG     3      48.280  43.089  35.129  1.00  0.00
+ATOM     31  CA  ARG     3      48.373  41.594  36.640  1.00  0.00
+ATOM     32  HA  ARG     3      48.334  41.705  37.723  1.00  0.00
+ATOM     33  CB  ARG     3      47.025  41.065  36.115  1.00  0.00
+ATOM     34  HB2 ARG     3      46.906  41.337  35.063  1.00  0.00
+ATOM     35  HB3 ARG     3      47.018  39.974  36.150  1.00  0.00
+ATOM     36  CG  ARG     3      45.813  41.582  36.909  1.00  0.00
+ATOM     37  HG2 ARG     3      45.758  42.665  36.811  1.00  0.00
+ATOM     38  HG3 ARG     3      44.912  41.169  36.454  1.00  0.00
+ATOM     39  CD  ARG     3      45.831  41.227  38.409  1.00  0.00
+ATOM     40  HD2 ARG     3      46.541  41.884  38.912  1.00  0.00
+ATOM     41  HD3 ARG     3      44.856  41.443  38.832  1.00  0.00
+ATOM     42  NE  ARG     3      46.201  39.822  38.678  1.00  0.00
+ATOM     43  HE  ARG     3      47.046  39.682  39.205  1.00  0.00
+ATOM     44  CZ  ARG     3      45.589  38.738  38.236  1.00  0.00
+ATOM     45  NH1 ARG     3      44.408  38.777  37.703  1.00  0.00
+ATOM     46 HH11 ARG     3      43.837  39.610  37.775  1.00  0.00
+ATOM     47 HH12 ARG     3      44.030  37.930  37.269  1.00  0.00
+ATOM     48  NH2 ARG     3      46.171  37.581  38.283  1.00  0.00
+ATOM     49 HH21 ARG     3      47.118  37.474  38.598  1.00  0.00
+ATOM     50 HH22 ARG     3      45.643  36.772  37.947  1.00  0.00
+ATOM     51  C   ARG     3      49.476  40.574  36.357  1.00  0.00
+ATOM     52  O   ARG     3      50.087  40.574  35.289  1.00  0.00
+ATOM     53  N   GLY     4      49.632  39.650  37.294  1.00  0.00
+ATOM     54  H   GLY     4      49.156  39.778  38.177  1.00  0.00
+ATOM     55  CA  GLY     4      50.286  38.368  37.061  1.00  0.00
+ATOM     56  HA2 GLY     4      50.148  38.100  36.018  1.00  0.00
+ATOM     57  HA3 GLY     4      51.351  38.445  37.264  1.00  0.00
+ATOM     58  C   GLY     4      49.720  37.249  37.928  1.00  0.00
+ATOM     59  O   GLY     4      48.981  37.517  38.886  1.00  0.00
+ATOM     60  N   ALA     5      50.088  36.011  37.600  1.00  0.00
+ATOM     61  H   ALA     5      50.634  35.883  36.749  1.00  0.00
+ATOM     62  CA  ALA     5      49.830  34.819  38.405  1.00  0.00
+ATOM     63  HA  ALA     5      49.857  35.104  39.454  1.00  0.00
+ATOM     64  CB  ALA     5      48.440  34.263  38.085  1.00  0.00
+ATOM     65  HB1 ALA     5      48.469  33.794  37.105  1.00  0.00
+ATOM     66  HB2 ALA     5      48.167  33.511  38.830  1.00  0.00
+ATOM     67  HB3 ALA     5      47.694  35.060  38.084  1.00  0.00
+ATOM     68  C   ALA     5      50.895  33.723  38.195  1.00  0.00
+ATOM     69  O   ALA     5      51.492  33.599  37.125  1.00  0.00
+ATOM     70  N   THR     6      51.097  32.899  39.220  1.00  0.00
+ATOM     71  H   THR     6      50.588  33.080  40.082  1.00  0.00
+ATOM     72  CA  THR     6      51.956  31.706  39.225  1.00  0.00
+ATOM     73  HA  THR     6      51.919  31.238  38.243  1.00  0.00
+ATOM     74  CB  THR     6      53.414  32.109  39.502  1.00  0.00
+ATOM     75  HB  THR     6      53.682  32.937  38.844  1.00  0.00
+ATOM     76  CG2 THR     6      53.701  32.518  40.948  1.00  0.00
+ATOM     77 HG21 THR     6      53.596  31.663  41.616  1.00  0.00
+ATOM     78 HG22 THR     6      54.724  32.889  41.007  1.00  0.00
+ATOM     79 HG23 THR     6      53.020  33.308  41.255  1.00  0.00
+ATOM     80  OG1 THR     6      54.272  31.029  39.215  1.00  0.00
+ATOM     81  HG1 THR     6      54.304  30.910  38.261  1.00  0.00
+ATOM     82  C   THR     6      51.437  30.679  40.241  1.00  0.00
+ATOM     83  O   THR     6      50.568  30.999  41.051  1.00  0.00
+ATOM     84  N   THR     7      51.958  29.455  40.232  1.00  0.00
+ATOM     85  H   THR     7      52.722  29.262  39.599  1.00  0.00
+ATOM     86  CA  THR     7      51.561  28.379  41.156  1.00  0.00
+ATOM     87  HA  THR     7      51.000  28.807  41.986  1.00  0.00
+ATOM     88  CB  THR     7      50.665  27.326  40.491  1.00  0.00
+ATOM     89  HB  THR     7      50.394  26.578  41.237  1.00  0.00
+ATOM     90  CG2 THR     7      49.383  27.918  39.913  1.00  0.00
+ATOM     91 HG21 THR     7      49.603  28.503  39.019  1.00  0.00
+ATOM     92 HG22 THR     7      48.696  27.110  39.667  1.00  0.00
+ATOM     93 HG23 THR     7      48.907  28.558  40.655  1.00  0.00
+ATOM     94  OG1 THR     7      51.377  26.686  39.454  1.00  0.00
+ATOM     95  HG1 THR     7      52.242  26.443  39.820  1.00  0.00
+ATOM     96  C   THR     7      52.780  27.674  41.733  1.00  0.00
+ATOM     97  O   THR     7      53.693  27.292  40.991  1.00  0.00
+ATOM     98  OXT THR     7      52.893  27.516  42.947  1.00  0.00
+TER   
+ATOM     99  C1  PRE     8      40.182  35.865  37.205  1.00  0.00
+ATOM    100  C2  PRE     8      39.825  35.162  38.553  1.00  0.00
+ATOM    101  C3  PRE     8      40.484  35.425  39.701  1.00  0.00
+ATOM    102  C4  PRE     8      41.619  36.450  39.807  1.00  0.00
+ATOM    103  O4  PRE     8      41.530  37.169  41.032  1.00  0.00
+ATOM    104  C5  PRE     8      41.522  37.451  38.670  1.00  0.00
+ATOM    105  C6  PRE     8      40.855  37.198  37.522  1.00  0.00
+ATOM    106  C7  PRE     8      38.873  36.029  36.278  1.00  0.00
+ATOM    107  O71 PRE     8      38.866  36.883  35.395  1.00  0.00
+ATOM    108  O72 PRE     8      37.973  35.185  36.370  1.00  0.00
+ATOM    109  C8  PRE     8      41.142  34.949  36.392  1.00  0.00
+ATOM    110  C1' PRE     8      42.419  34.555  37.122  1.00  0.00
+ATOM    111  O1' PRE     8      42.481  33.507  37.766  1.00  0.00
+ATOM    112  C2' PRE     8      43.706  35.545  37.013  1.00  0.00
+ATOM    113  O'L PRE     8      44.669  35.339  37.752  1.00  0.00
+ATOM    114  O'M PRE     8      43.648  36.538  36.300  1.00  0.00
+ATOM    115  HO4 PRE     8      41.806  36.579  41.746  1.00  0.00
+ATOM    116  H2  PRE     8      40.799  37.961  36.713  1.00  0.00
+ATOM    117  H3  PRE     8      42.012  38.385  38.823  1.00  0.00
+ATOM    118  H4  PRE     8      40.262  34.861  40.616  1.00  0.00
+ATOM    119  H5  PRE     8      39.058  34.428  38.495  1.00  0.00
+ATOM    120  H6  PRE     8      40.599  34.032  36.134  1.00  0.00
+ATOM    121  H7  PRE     8      41.405  35.528  35.501  1.00  0.00
+ATOM    122  H8  PRE     8      42.580  35.914  39.742  1.00  0.00
+TER   
+END   

hessian_ff/tests/data/small/complex.rst7

@@ -0,0 +1,63 @@
+default_name
+   122
+  47.3210000  49.1450000  36.0600000  47.6380000  49.0490000  35.1060000
+  47.9070000  49.8200000  36.5300000  46.3180000  49.2620000  36.0590000
+  47.5610000  47.8800000  36.7470000  48.2010000  48.0460000  37.6130000
+  46.6130000  47.4770000  37.1040000  48.2010000  46.8290000  35.8340000
+  47.7310000  46.5790000  34.7220000  49.2440000  46.1710000  36.3230000
+  49.6290000  46.4690000  37.2150000  49.8490000  44.9950000  35.6970000
+  49.3970000  44.8510000  34.7170000  51.3690000  45.1540000  35.4700000
+  51.8840000  45.0380000  36.4230000  51.8160000  44.0230000  34.5250000
+  51.3400000  44.1300000  33.5510000  52.8880000  44.0630000  34.3680000
+  51.5830000  43.0440000  34.9450000  51.7350000  46.5450000  34.8990000
+  51.2020000  46.7050000  33.9630000  51.4230000  47.3170000  35.6030000
+  53.2340000  46.7480000  34.6580000  53.5920000  46.0710000  33.8870000
+  53.4080000  47.7650000  34.3130000  53.7890000  46.5790000  35.5820000
+  49.5180000  43.7800000  36.5630000  49.9970000  43.6530000  37.6930000
+  48.6620000  42.8970000  36.0450000  48.2800000  43.0890000  35.1290000
+  48.3730000  41.5940000  36.6400000  48.3340000  41.7050000  37.7230000
+  47.0250000  41.0650000  36.1150000  46.9060000  41.3370000  35.0630000
+  47.0180000  39.9740000  36.1500000  45.8130000  41.5820000  36.9090000
+  45.7580000  42.6650000  36.8110000  44.9120000  41.1690000  36.4540000
+  45.8310000  41.2270000  38.4090000  46.5410000  41.8840000  38.9120000
+  44.8560000  41.4430000  38.8320000  46.2010000  39.8220000  38.6780000
+  47.0460000  39.6820000  39.2050000  45.5890000  38.7380000  38.2360000
+  44.4080000  38.7770000  37.7030000  43.8370000  39.6100000  37.7750000
+  44.0300000  37.9300000  37.2690000  46.1710000  37.5810000  38.2830000
+  47.1180000  37.4740000  38.5980000  45.6430000  36.7720000  37.9470000
+  49.4760000  40.5740000  36.3570000  50.0870000  40.5740000  35.2890000
+  49.6320000  39.6500000  37.2940000  49.1560000  39.7780000  38.1770000
+  50.2860000  38.3680000  37.0610000  50.1480000  38.1000000  36.0180000
+  51.3510000  38.4450000  37.2640000  49.7200000  37.2490000  37.9280000
+  48.9810000  37.5170000  38.8860000  50.0880000  36.0110000  37.6000000
+  50.6340000  35.8830000  36.7490000  49.8300000  34.8190000  38.4050000
+  49.8570000  35.1040000  39.4540000  48.4400000  34.2630000  38.0850000
+  48.4690000  33.7940000  37.1050000  48.1670000  33.5110000  38.8300000
+  47.6940000  35.0600000  38.0840000  50.8950000  33.7230000  38.1950000
+  51.4920000  33.5990000  37.1250000  51.0970000  32.8990000  39.2200000
+  50.5880000  33.0800000  40.0820000  51.9560000  31.7060000  39.2250000
+  51.9190000  31.2380000  38.2430000  53.4140000  32.1090000  39.5020000
+  53.6820000  32.9370000  38.8440000  53.7010000  32.5180000  40.9480000
+  53.5960000  31.6630000  41.6160000  54.7240000  32.8890000  41.0070000
+  53.0200000  33.3080000  41.2550000  54.2720000  31.0290000  39.2150000
+  54.3040000  30.9100000  38.2610000  51.4370000  30.6790000  40.2410000
+  50.5680000  30.9990000  41.0510000  51.9580000  29.4550000  40.2320000
+  52.7220000  29.2620000  39.5990000  51.5610000  28.3790000  41.1560000
+  51.0000000  28.8070000  41.9860000  50.6650000  27.3260000  40.4910000
+  50.3940000  26.5780000  41.2370000  49.3830000  27.9180000  39.9130000
+  49.6030000  28.5030000  39.0190000  48.6960000  27.1100000  39.6670000
+  48.9070000  28.5580000  40.6550000  51.3770000  26.6860000  39.4540000
+  52.2420000  26.4430000  39.8200000  52.7800000  27.6740000  41.7330000
+  53.6930000  27.2920000  40.9910000  52.8930000  27.5160000  42.9470000
+  40.1820000  35.8650000  37.2050000  39.8250000  35.1620000  38.5530000
+  40.4840000  35.4250000  39.7010000  41.6190000  36.4500000  39.8070000
+  41.5300000  37.1690000  41.0320000  41.5220000  37.4510000  38.6700000
+  40.8550000  37.1980000  37.5220000  38.8730000  36.0290000  36.2780000
+  38.8660000  36.8830000  35.3950000  37.9730000  35.1850000  36.3700000
+  41.1420000  34.9490000  36.3920000  42.4190000  34.5550000  37.1220000
+  42.4810000  33.5070000  37.7660000  43.7060000  35.5450000  37.0130000
+  44.6690000  35.3390000  37.7520000  43.6480000  36.5380000  36.3000000
+  41.8060000  36.5790000  41.7460000  40.7990000  37.9610000  36.7130000
+  42.0120000  38.3850000  38.8230000  40.2620000  34.8610000  40.6160000
+  39.0580000  34.4280000  38.4950000  40.5990000  34.0320000  36.1340000
+  41.4050000  35.5280000  35.5010000  42.5800000  35.9140000  39.7420000

hessian_ff/tests/test_coords_input.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import torch
+
+from hessian_ff.loaders import load_coords
+
+
+class _DummyASEAtoms:
+    def __init__(self, positions):
+        self._positions = positions
+
+    def get_positions(self):
+        return self._positions
+
+
+def test_load_coords_xyz(tmp_path) -> None:
+    xyz_path = tmp_path / "mini.xyz"
+    xyz_path.write_text(
+        "2\n"
+        "comment\n"
+        "H 0.0 1.0 2.0\n"
+        "O 3.0 4.0 5.0\n",
+        encoding="utf-8",
+    )
+    x = load_coords(xyz_path, natom=2, dtype=torch.float64, device="cpu")
+    assert tuple(x.shape) == (2, 3)
+    assert x.dtype == torch.float64
+    assert float(x[1, 2]) == 5.0
+
+
+def test_load_coords_ase_like() -> None:
+    atoms = _DummyASEAtoms([[0.0, 0.1, 0.2], [1.0, 1.1, 1.2]])
+    x = load_coords(atoms, natom=2, dtype=torch.float32, device="cpu")
+    assert tuple(x.shape) == (2, 3)
+    assert x.dtype == torch.float32
+    assert abs(float(x[0, 1]) - 0.1) < 1.0e-6
+
+
+def test_load_coords_tensor() -> None:
+    x0 = torch.tensor([[1.0, 2.0, 3.0]], dtype=torch.float64)
+    x = load_coords(x0, natom=1, dtype=torch.float32, device="cpu")
+    assert tuple(x.shape) == (1, 3)
+    assert x.dtype == torch.float32
+    assert float(x[0, 0]) == 1.0

hessian_ff/tests/test_energy_force.py

@@ -0,0 +1,49 @@
+"""Tests: energy and force correctness of hessian_ff vs OpenMM."""
+
+from __future__ import annotations
+
+import numpy as np
+import torch
+
+E_ABS_TOL = 1.0e-3  # kcal/mol
+F_RMS_TOL = 1.0e-3  # kcal/mol/A
+
+
+def _openmm_energy_force(context):
+    """Extract energy (kcal/mol) and forces (kcal/mol/A) from OpenMM context."""
+    from openmm import unit
+
+    state = context.getState(getEnergy=True, getForces=True)
+    e = float(state.getPotentialEnergy().value_in_unit(unit.kilocalories_per_mole))
+    f = state.getForces(asNumpy=True).value_in_unit(
+        unit.kilocalories_per_mole / unit.angstrom,
+    )
+    return e, torch.as_tensor(np.asarray(f), dtype=torch.float64)
+
+
+class TestEnergyForceVsOpenMM:
+    """Verify hessian_ff energy/force match OpenMM on the small system."""
+
+    def test_energy_matches_openmm(
+        self, small_ff, small_coords, openmm_context_and_pos,
+    ):
+        context, _ = openmm_context_and_pos
+        e_hff = float(small_ff(small_coords)["E_total"].detach().cpu())
+        e_omm, _ = _openmm_energy_force(context)
+        assert abs(e_hff - e_omm) <= E_ABS_TOL, (
+            f"Energy mismatch: hff={e_hff:.6f}, omm={e_omm:.6f}, "
+            f"diff={abs(e_hff - e_omm):.6e}"
+        )
+
+    def test_force_matches_openmm(
+        self, small_ff, small_coords, openmm_context_and_pos,
+    ):
+        context, _ = openmm_context_and_pos
+        _, f_hff = small_ff.energy_force(small_coords, force_calc_mode="Analytical")
+        f_hff = f_hff.detach().cpu().to(torch.float64)
+        _, f_omm = _openmm_energy_force(context)
+        diff = (f_hff - f_omm).numpy()
+        rms = float(np.sqrt(np.mean(diff ** 2)))
+        assert rms <= F_RMS_TOL, (
+            f"Force RMS mismatch: {rms:.6e} > tol={F_RMS_TOL}"
+        )

hessian_ff/tests/test_hessian.py

@@ -0,0 +1,137 @@
+"""Tests: Hessian correctness of hessian_ff (analytical vs autograd vs FD vs OpenMM FD)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+import torch
+
+from hessian_ff.analytical_hessian import build_analytical_hessian
+
+FD_DELTA = 1.0e-4  # Angstrom
+H_RELFRO_TOL = 1.0e-3  # relative Frobenius norm tolerance
+
+
+def _symmetrize(h: torch.Tensor) -> torch.Tensor:
+    h = h.detach().cpu().to(torch.float64)
+    return 0.5 * (h + h.T)
+
+
+def _relative_frobenius(a: torch.Tensor, b: torch.Tensor) -> float:
+    d = b - a
+    return float(torch.linalg.norm(d) / (torch.linalg.norm(a) + 1e-20))
+
+
+def _analytical_hessian(system, coords):
+    """Compute full analytical Hessian via build_analytical_hessian."""
+    all_atoms = list(range(system.natom))
+    h, _ = build_analytical_hessian(
+        system=system, coords=coords, active_atoms=all_atoms,
+        mpi_rank=0, mpi_size=1,
+    )
+    return _symmetrize(h)
+
+
+def _autograd_hessian(ff, coords):
+    """Compute full Hessian via torch.autograd.functional.hessian."""
+    x = coords.clone().detach().requires_grad_(True)
+    h4 = torch.autograd.functional.hessian(
+        lambda x_: ff(x_)["E_total"], x, vectorize=False,
+    )
+    return _symmetrize(h4.reshape(x.numel(), x.numel()))
+
+
+def _fd_hessian(ff, coords, delta=FD_DELTA, force_calc_mode="Analytical"):
+    """Compute full Hessian via finite-difference on forces."""
+    ndof = 3 * coords.shape[0]
+    h = torch.empty((ndof, ndof), dtype=torch.float64, device="cpu")
+    for col in range(ndof):
+        atom, comp = col // 3, col % 3
+        xp, xm = coords.clone(), coords.clone()
+        xp[atom, comp] += delta
+        xm[atom, comp] -= delta
+        _, fp = ff.energy_force(xp, force_calc_mode=force_calc_mode)
+        _, fm = ff.energy_force(xm, force_calc_mode=force_calc_mode)
+        fp_flat = fp.detach().cpu().to(torch.float64).reshape(-1)
+        fm_flat = fm.detach().cpu().to(torch.float64).reshape(-1)
+        h[:, col] = -(fp_flat - fm_flat) / (2.0 * delta)
+    return _symmetrize(h)
+
+
+def _openmm_fd_hessian(context, base_pos, delta=FD_DELTA):
+    """Compute full Hessian via finite-difference on OpenMM forces."""
+    from openmm import unit
+
+    natom = base_pos.shape[0]
+    ndof = 3 * natom
+    h = np.empty((ndof, ndof), dtype=np.float64)
+    force_unit = unit.kilocalories_per_mole / unit.angstrom
+
+    for col in range(ndof):
+        atom, comp = col // 3, col % 3
+        xp, xm = base_pos.copy(), base_pos.copy()
+        xp[atom, comp] += delta
+        xm[atom, comp] -= delta
+
+        context.setPositions(xp * unit.angstrom)
+        fp = np.asarray(
+            context.getState(getForces=True).getForces(asNumpy=True)
+            .value_in_unit(force_unit), dtype=np.float64,
+        ).reshape(-1)
+
+        context.setPositions(xm * unit.angstrom)
+        fm = np.asarray(
+            context.getState(getForces=True).getForces(asNumpy=True)
+            .value_in_unit(force_unit), dtype=np.float64,
+        ).reshape(-1)
+
+        h[:, col] = -(fp - fm) / (2.0 * delta)
+
+    # Restore original positions
+    context.setPositions(base_pos * unit.angstrom)
+    return _symmetrize(torch.from_numpy(h))
+
+
+class TestHessianConsistency:
+    """Verify Hessian methods produce consistent results on the small system."""
+
+    def test_analytical_vs_autograd(
+        self, small_system, small_ff_autograd, small_coords,
+    ):
+        h_ana = _analytical_hessian(small_system, small_coords)
+        h_auto = _autograd_hessian(small_ff_autograd, small_coords)
+        rel = _relative_frobenius(h_ana, h_auto)
+        assert rel <= H_RELFRO_TOL, (
+            f"analytical vs autograd: relative Frobenius = {rel:.6e} > {H_RELFRO_TOL}"
+        )
+
+    def test_analytical_vs_fd(
+        self, small_system, small_ff, small_coords,
+    ):
+        h_ana = _analytical_hessian(small_system, small_coords)
+        h_fd = _fd_hessian(small_ff, small_coords)
+        rel = _relative_frobenius(h_ana, h_fd)
+        assert rel <= H_RELFRO_TOL, (
+            f"analytical vs FD: relative Frobenius = {rel:.6e} > {H_RELFRO_TOL}"
+        )
+
+    def test_analytical_vs_openmm_fd(
+        self, small_system, small_coords, openmm_context_and_pos,
+    ):
+        context, base_pos = openmm_context_and_pos
+        h_ana = _analytical_hessian(small_system, small_coords)
+        h_omm = _openmm_fd_hessian(context, base_pos)
+        rel = _relative_frobenius(h_ana, h_omm)
+        assert rel <= H_RELFRO_TOL, (
+            f"analytical vs OpenMM FD: relative Frobenius = {rel:.6e} > {H_RELFRO_TOL}"
+        )
+
+    def test_analytical_hessian_shape(self, small_system, small_coords):
+        ndof = 3 * small_system.natom
+        h_ana = _analytical_hessian(small_system, small_coords)
+        assert h_ana.shape == (ndof, ndof)
+
+    def test_analytical_hessian_symmetric(self, small_system, small_coords):
+        h_ana = _analytical_hessian(small_system, small_coords)
+        diff = float(torch.max(torch.abs(h_ana - h_ana.T)))
+        assert diff < 1e-10, f"Hessian not symmetric: max asymmetry = {diff:.6e}"

hessian_ff/tests/test_smoke.py

@@ -0,0 +1,18 @@
+def test_public_api_symbols() -> None:
+    import hessian_ff
+
+    required = [
+        "clear_runtime_cache",
+        "load_system",
+        "load_coords",
+        "ForceFieldTorch",
+        "system_summary",
+        "torch_energy",
+        "torch_energy_batch",
+        "torch_force",
+        "torch_force_batch",
+        "torch_hessian",
+        "verify_openmm",
+    ]
+    for name in required:
+        assert hasattr(hessian_ff, name)

hessian_ff/tests/test_validation.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import torch
+
+from hessian_ff.forcefield import ForceFieldTorch
+from hessian_ff.loaders import load_coords, load_system
+
+
+_DATA_DIR = Path(__file__).resolve().parent / "data" / "small"
+_PRMTOP = _DATA_DIR / "complex.parm7"
+_COORDS = _DATA_DIR / "complex.rst7"
+
+pytestmark = pytest.mark.skipif(
+    (not _PRMTOP.exists()) or (not _COORDS.exists()),
+    reason="benchmark/data/small test fixtures are not available in this environment",
+)
+
+
+def _load_ff_and_coords():
+    system = load_system(_PRMTOP, device="cpu").to(dtype=torch.float64)
+    ff = ForceFieldTorch(system, nonbonded_cpu_fast=True)
+    return system, ff
+
+
+def test_forcefield_explicit_dtype_validation_single() -> None:
+    system, ff = _load_ff_and_coords()
+    coords = load_coords(_COORDS, natom=system.natom, device="cpu", dtype=torch.float32)
+    with pytest.raises(ValueError, match="coords dtype mismatch"):
+        ff.energy_force(coords, force_calc_mode="Analytical")
+
+
+def test_forcefield_explicit_dtype_validation_batch() -> None:
+    system, ff = _load_ff_and_coords()
+    coords = load_coords(_COORDS, natom=system.natom, device="cpu", dtype=torch.float32)
+    coords_batch = coords.unsqueeze(0).repeat(2, 1, 1)
+    with pytest.raises(ValueError, match="coords_batch dtype mismatch"):
+        ff.energy_force_batch(coords_batch, force_calc_mode="Analytical")