deepmodeling / deepmodeling/deepmd-kit
[Feature Request] DPA-4 / PyTorch backend import path requires `e3nn`, but `e3nn` is only declared as an optional `dpa-adapt` dependency
- Dominant language
- Python
- Stars
- 2k
- Forks
- 649
- Avg merge
- 6d 18h
- Merged PRs (30d)
- 15
Description
### Summary
When using the PyTorch backend, dp fails at import time with:
```
ModuleNotFoundError: No module named 'e3nn'
```
This happens even before a specific model or descriptor is explicitly selected by the user. The import chain goes through the regular PyTorch backend entry point and eventually imports the SEZM-related descriptor modules, which unconditionally import e3nn.
However, in pyproject.toml, e3nn appears to be declared only under the optional dpa-adapt extra, not as a regular PyTorch backend dependency.
This creates a dependency mismatch: the PyTorch backend can import code paths that require `e3nn`, but a normal PyTorch/DeepMD-kit installation does not necessarily install `e3nn`.
This is especially concerning because future mainstream users are likely to move toward DPA-4 / PyTorch-based workflows. If DPA-4-related or SEZM-related modules require `e3nn`, the installation path should make that dependency explicit, or at least clearly state it in the documentation.
### Detailed Description
**Environment**
DeepMD-kit source build
-Python: 3.12.3
-PyTorch: 2.11.0+cu128
-torch.version.cuda: 12.8
-CUDA Toolkit: 12.8.93
-GPU backend: PyTorch
-DP_ENABLE_PYTORCH=1
-DP_ENABLE_TENSORFLOW=0
-DP_VARIANT=cuda
PyTorch and CUDA are available:
-torch: 2.11.0+cu128
-torch cuda: 12.8
-cuda available: True
**Error**
Running the PyTorch backend through dp fails with:
```
Traceback (most recent call last):
File "/opt/deepmd-kit/.venv/bin/dp", line 6, in
sys.exit(main())
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/main.py", line 1135, in main
deepmd_main = BACKENDS[args.backend]().entry_point_hook
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/backend/pytorch.py", line 66, in entry_point_hook
from deepmd.pt.entrypoints.main import main as deepmd_main
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/entrypoints/main.py", line 41, in
from deepmd.pt.entrypoints.compress import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/entrypoints/compress.py", line 13, in
from deepmd.pt.model.model import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/model/__init__.py", line 22, in
from deepmd.pt.model.atomic_model import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/atomic_model/__init__.py", line 20, in
from .dipole_atomic_model import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/atomic_model/dipole_atomic_model.py", line 12, in
from .dp_atomic_model import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/atomic_model/dp_atomic_model.py", line 16, in
from deepmd.pt.model.descriptor.base_descriptor import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/__init__.py", line 45, in
from .sezm import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm.py", line 74, in
from .sezm_nn import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/__init__.py", line 19, in
from .block import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/block.py", line 43, in
from .ffn import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/ffn.py", line 37, in
from .grid_net import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/grid_net.py", line 48, in
from .projection import (
File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/projection.py", line 22, in
from e3nn.o3 import (
ModuleNotFoundError: No module named 'e3nn'
```
**Relevant pyproject.toml section**
In the current `pyproject.toml`, `e3nn` appears under the optional `dpa-adapt` extra:
```python
dpa-adapt = [
"scikit-learn",
"dpdata",
"torch",
"ase",
"rdkit",
"e3nn",
]
```
But it does not appear in the main dependencies list.
As a result, a normal source installation with the PyTorch backend can produce an environment where `deepmd.pt ` imports code requiring `e3nn`, but `e3nn` is not installed.
**Why this is a problem**
This is not a user-side model configuration issue. The failure occurs during import of the PyTorch backend entry point, before the user has explicitly requested a specific SEZM/DPA-4/DPA-ADAPT model.
If `e3nn` is required for normal PyTorch backend import, then it should be declared as a PyTorch backend dependency.
If e3nn is only required for specific models or descriptors, then the import should be lazy and only triggered when those models/descriptors are actually used. In that case, the error message should explicitly say which optional dependency group is required.
For example:
```
The SEZM/DPA-4 descriptor requires e3nn. Please install deepmd-kit[dpa-adapt] or install e3nn manually.
```
At present, the user only receives a generic Python import error.
**Expected behavior**
One of the following should happen:
- e3nn is included in the dependency set required for the PyTorch backend, if it is required for normal deepmd.pt import.
- SEZM/DPA-4/DPA-ADAPT-related imports are made lazy, so that users who do not use those descriptors do not need e3nn.
- The documentation explicitly states that PyTorch backend users who want to use DPA-4 / SEZM / DPA-ADAPT functionality must install the corresponding extra, and the runtime error should point to that extra.
Actual behavior
A normal PyTorch backend invocation fails with:
```
ModuleNotFoundError: No module named 'e3nn'
```
even though the missing dependency is only declared under an optional extra.
**Suggested fixes**
Possible fixes include:
Add `e3nn` to the PyTorch backend dependency group if it is now required by the default PyTorch backend import path.
Move e3nn-dependent imports to lazy import locations, so that e3nn is imported only when SEZM/DPA-4/DPA-ADAPT functionality is actually used.
Add an optional dependency group specifically for DPA-4 or SEZM, for example:
```python
dpa4 = [
"e3nn",
]
```
or include `e3nn` in the relevant PyTorch extra if DPA-4 is expected to become a mainstream PyTorch workflow.
Improve the error message so users are told exactly which extra to install.
**Request**
Please clarify whether `e3nn` is now a required dependency for the PyTorch backend, DPA-4, SEZM, or only DPA-ADAPT.
Given that DPA-4 / PyTorch workflows are likely to become mainstream for many users, this dependency path should be explicit and robust. The current behavior makes the PyTorch backend fail at import time with an undeclared runtime dependency. Also, please do a thorough update to the documentation according to these changes.
### Further Information, Files, and Links
_No response_
Contributor guide
Assessment
This issue has not been assessed yet.