deepmd_gnn.mace_off
===================

.. py:module:: deepmd_gnn.mace_off

.. autoapi-nested-parse::

   Conservative helpers for loading selected MACE-OFF checkpoints.

   The helpers in this module intentionally support a narrower scope than the
   upstream discussion in PR #96: they load ordinary MACE-OFF checkpoints into a
   DeePMD-GNN ``MaceModel`` wrapper for standard MD use, but they do *not* infer
   DPRc/QM/MM atom-type semantics from the checkpoint.



Functions
---------

.. autoapisummary::

   deepmd_gnn.mace_off.download_mace_off_model
   deepmd_gnn.mace_off.load_mace_off_model
   deepmd_gnn.mace_off.convert_mace_off_to_deepmd


Module Contents
---------------

.. py:function:: download_mace_off_model(model_name: str, cache_dir: pathlib.Path | None = None) -> pathlib.Path

   Download a selected official MACE-OFF model file.

   Parameters
   ----------
   model_name
       Canonical model name (for example ``off23_small``) or one of the
       compatibility aliases ``small`` / ``medium`` / ``large``.
   cache_dir
       Cache directory. Defaults to :func:`get_mace_off_cache_dir`.


.. py:function:: load_mace_off_model(model_name: str | None = 'small', *, sel: int, model_path: pathlib.Path | None = None, cache_dir: pathlib.Path | None = None, device: str = 'cpu') -> deepmd_gnn.mace.MaceModel

   Load a supported MACE-OFF checkpoint as a DeePMD-GNN ``MaceModel``.

   Parameters
   ----------
   model_name
       Name of the official MACE-OFF checkpoint to download. Ignored when
       ``model_path`` is provided.
   sel
       Neighbor-list cap for the DeePMD-GNN wrapper. This value is *required*:
       MACE-OFF checkpoints do not store DeePMD's runtime neighbor-list limit,
       and guessing it can silently truncate neighbors.
   model_path
       Local checkpoint path. If omitted, download the selected official model.
   cache_dir
       Cache directory for downloaded checkpoints.
   device
       Device used when loading the original checkpoint.

   Notes
   -----
   This helper intentionally supports a narrower scope than DeePMD-GNN's full
   DPRc machinery. It only infers ordinary element ``type_map`` entries from
   ``atomic_numbers`` and does not infer ``mH`` / ``HW`` / ``OW`` or other
   QM/MM-specific type semantics.


.. py:function:: convert_mace_off_to_deepmd(output_file: str, *, sel: int, model_name: str | None = 'small', model_path: pathlib.Path | None = None, cache_dir: pathlib.Path | None = None, device: str = 'cpu') -> pathlib.Path

   Serialize a loaded MACE-OFF wrapper as a TorchScript DeePMD-GNN model.

   This helper scripts the DeePMD-GNN wrapper and writes it to ``output_file``.
   It does not, by itself, prove end-to-end downstream deployment in external
   engines such as LAMMPS or AMBER; callers should still validate the final
   deployment path they care about.