Inference Model Ops

---
name: inference-model-ops
description: "Load DeePMD-kit models, run Python or CLI inference, extract
  descriptors and embeddings, compute model deviation, and operate on
  frozen/checkpoint/pretrained model artifacts."
disable-model-invocation: true
metadata:
  disco-role: operating
license: LGPL 3.0
---

# DeePMD-kit Inference and Model Operations

Use this sub-skill when the user already has a DeePMD-kit model artifact or built-in pretrained model selector and needs to evaluate, inspect, compare, convert, compress, or bias-adjust it.

## Route First

- Use this sub-skill for `DeepPot`, `DeepPotential`, `dp test`, `dp eval-desc`, `dp embed`, `dp model-devi`, `dp show`, `dp compress`, `dp convert-from`, `dp convert-backend`, `dp pretrained`, and `dp change-bias`.
- Route training input design, model architecture selection, checkpoints produced during training, and freeze workflow decisions to `../training-models/SKILL.md` when available.
- Route LAMMPS pair style, i-PI, ASE calculator, C/C++ API, and plugin integration questions to `../integrations-development/SKILL.md` when available.
- Route raw DeePMD data-system creation, type-map repair, `type.raw`/`set.*` layout fixes, and data conversion to `../data-config/SKILL.md` when available.

## Model Source Triage

1. Identify the model source before choosing an API or command:
   - TensorFlow frozen graph: commonly `.pb`; use default backend or `dp --tf ...`.
   - PyTorch frozen model: commonly `.pth`; use `dp --pt ...`.
   - PyTorch checkpoint: commonly `.pt`; usable for some commands such as `dp embed`, `dp show`, and `dp change-bias`; freeze before standard frozen-model inference workflows when needed.
   - Paddle frozen model: JSON plus `.pdiparams`; use `dp --pd ...` for supported operations.
   - Built-in pretrained selector: names such as `DPA-3.2-5M`; pass directly to `DeepPot` or download with `dp pretrained download`.
2. Prefer explicit backend flags (`--tf`, `--pt`, `--jax`, `--pd`, `--pt-expt`) when suffixes are ambiguous, generated by another tool, or being converted.
3. Use `dp show MODEL type-map descriptor fitting-net size observed-type` before inference when atom type order, branch selection, or descriptor support is uncertain.
4. For multi-task PyTorch models, pass `--head` or `--model-branch` to CLI commands that support it, and pass the corresponding `head=` keyword to Python evaluator construction when available.

## Python Inference Pattern

Use `deepmd.infer.DeepPot` for energy models:

```python
from deepmd.infer import DeepPot
import numpy as np

pot = DeepPot("model.pth", auto_batch_size=True)
coord = np.asarray(coords, dtype=float).reshape(nframes, natoms * 3)
cell = np.asarray(cells, dtype=float).reshape(nframes, 9)  # or None for non-PBC
atype = np.asarray(type_indices, dtype=np.int32)           # (natoms,) unless mixed_type=True
energy, force, virial = pot.eval(coord, cell, atype)
```

Important shape rules are in `references/python-api.md`. If the user only needs a safe scaffold for shapes, run:

```bash
python sub-skills/inference-model-ops/scripts/deeppot_input_shapes.py --natoms 3 --nframes 2
```

Use `cell=None` for non-periodic inference; do not pass zero cells as a substitute unless the model/data workflow explicitly expects PBC with zero vectors.

## DeepPot API Decision Table

| Task | API | Main outputs | Notes |
| --- | --- | --- | --- |
| Energy/force/virial | `DeepPot.eval(...)` | energy `(nframes, 1)`, force `(nframes, natoms, 3)`, virial `(nframes, 9)` | Add `atomic=True` for atomic energy and atomic virial. |
| Descriptors | `DeepPot.eval_descriptor(...)` | descriptor `(nframes, natoms, ndesc)` | `dtype="native"` by default; accepts `fp32`, `fp64`, `native`. |
| Embeddings | `DeepPot.eval_embedding(...)` | descriptor, atomic feature, structural feature | PyTorch-focused; `dtype="fp32"` by default. |
| Model deviation | `calc_model_devi(...)` | deviation table `(nframes, 8+)` | Load models once, then reuse model objects. |
| Metadata | `get_type_map()`, `get_rcut()`, `get_dim_fparam()`, `get_dim_aparam()` | scalars/lists | Inspect before shaping optional parameters. |

## CLI Decision Table

| Task | Command | Primary output |
| --- | --- | --- |
| Test labeled data | `dp test -m MODEL -s SYSTEM -n NUM` | RMSE summary; optional detail files. |
| Save descriptors | `dp eval-desc -m MODEL -s SYSTEM -o desc --dtype native` | `desc/<system>.npy` arrays. |
| Save embeddings | `dp embed -m MODEL -s SYSTEM -o embedding.hdf5 --dtype fp32` | HDF5 datasets: descriptor, atomic_feature, structural_feature. |
| Compare models | `dp model-devi -m M0 M1 M2 M3 -s SYSTEM -o model_devi.out` | Deviation text table. |
| Inspect model | `dp show MODEL type-map descriptor fitting-net size` | Logged model metadata. |
| Download pretrained | `dp pretrained download MODEL --cache-dir CACHE` | Local model path. |
| Compress frozen model | `dp compress -i MODEL -o MODEL_COMPRESSED` | Compressed frozen model. |
| Convert old TF model | `dp convert-from auto -i old.pb -o new.pb` | Compatibility-updated graph. |
| Convert backend | `dp convert-backend INPUT OUTPUT` | Model in backend inferred from `OUTPUT`. |
| Change output bias | `dp change-bias INPUT -s SYSTEM -o OUTPUT` | Bias-adjusted model/checkpoint. |

Full command recipes and pitfalls are in `references/cli-model-ops.md`.

## Model Deviation Without Repeated Loading

When comparing an ensemble in Python, instantiate each model once outside loops:

```python
from deepmd.infer import DeepPot, calc_model_devi

models = [DeepPot(path, auto_batch_size=True) for path in model_paths]
deviation = calc_model_devi(
    coord,
    cell,
    atype,
    models,
    atomic=True,
    relative=0.05,
    relative_v=0.05,
)
```

Do not create `DeepPot(path)` repeatedly inside frame, trajectory, or active-learning loops; TensorFlow and PyTorch runtimes may not release all memory, which can lead to OOM.

## Compatibility Checklist

Before running inference, verify:

- The backend flag matches the artifact suffix and installed backend support.
- `atype` indices follow the model `type_map`, not alphabetical element order unless that is the model order.
- `coord` is reshapeable to `(nframes, natoms, 3)` or flattened `(nframes, natoms * 3)`.
- `cell` is `None` for non-PBC or reshapeable to `(nframes, 9)` / `(nframes, 3, 3)` for PBC.
- `fparam` and `aparam` are present only when the model reports nonzero parameter dimensions.
- Old TensorFlow frozen models are converted with `dp convert-from` before use if the installed version rejects them.
- Pretrained downloads are allowed in the environment and cache location; otherwise ask the user for an existing model path.

## Troubleshooting Index

- Wrong backend or suffix: `references/troubleshooting.md#wrong-backend-or-model-suffix`
- Repeated model loading or OOM: `references/troubleshooting.md#repeated-model-loading-memory-growth`
- Atom type order mismatch: `references/troubleshooting.md#atom-type-order-mismatch`
- Bad coordinate/cell shapes: `references/troubleshooting.md#bad-coordinate-cell-or-atype-shapes`
- Non-periodic cells: `references/troubleshooting.md#non-periodic-cell-handling`
- Descriptor dtype/output confusion: `references/troubleshooting.md#descriptor-embedding-and-dtype-confusion`
- Unsupported old frozen model: `references/troubleshooting.md#unsupported-old-frozen-model`
- Pretrained network/cache constraints: `references/troubleshooting.md#pretrained-network-or-cache-constraints`

## Safe Defaults

- Use `auto_batch_size=True` for Python inference unless the user has a reason to set an integer initial batch size.
- Use `--dtype native` for descriptor reproducibility; use `fp32` for compact embedding files unless the user needs higher precision.
- Use `--relative` and `--relative_v` only with an explicit level parameter, not as booleans.
- Use `--atomic` in `dp test` or `dp model-devi` only when per-atom output is needed, because it increases output size.
- Keep all generated helper scripts and reusable snippets inside this skill subtree; do not depend on original repository example paths at runtime.