Troubleshooting

Common issues grouped by stage.

Installation

:code:`torch-scatter` import error

Install the wheel matching your PyTorch, CUDA, Python, and platform from https://data.pyg.org/whl/

Optional model fails to import

Install NequIP, XequiNet, py-plumed, etc. per Installation.

Data

:code:`ModuleNotFoundError: numpy._core`

Pickle created with NumPy 2.x loaded under NumPy 1.x. Re-export dataset or align versions.

Missing field / shape mismatch

Check Datahub features/targets mapping against actual pickle keys and shapes (N, Ra, Za).

Stale preprocessing cache

Delete processed_dataset_<hash>/ or change a hash-affecting option intentionally, then rerun with preload: false once.

Training

NaN loss

Lower learning rate; check negative_gradient; verify energy/force units and atomic_energy references.

CUDA OOM

Reduce batch_size; use float32; disable data_in_memory; shrink model or cutoff.

Poor force accuracy, good energy

Revisit force loss weight and unit conversion (Units and Standard Fields).

Early stopping too aggressive

Increase patience; align Metric weights with loss.

Simulation

PLUMED instability

Fix UNITS line; verify Hartree_in_E, time_step, fs_in_t.

Wrong atom in constraint/scan

Check idx_start_from (0 vs 1).

NEB fails to interpolate

Verify frame count vs num_images; relax endpoints if needed.

QM annotation

TeraChem not found

Module load / PATH / license.

Unfinished jobs in batch

Run enerzymette terachem_timing; inspect scratch and keep_output.

Active learning

No uncertainty in extract

Enable shallow ensemble or committee; set non_target_features in predict path.

Confusing internal vs Enerzymette AL

Internal AL never creates new structures; Enerzymette AL requires template configs and iteration directories (Active Learning Workflows).

Documentation build

Sphinx autosummary warnings for moved classes (e.g. ASECalculator in calculator not simulator) do not affect runtime CLI behavior.