---

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:

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:

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:

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.