[Feature Request] DPA-4 / PyTorch backend import path requires `e3nn`, but `e3nn` is only declared as an optional `dpa-adapt` dependency

[qchempku2017]

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 <module>
    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 <module>
    from deepmd.pt.entrypoints.compress import (
  File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/entrypoints/compress.py", line 13, in <module>
    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 <module>
    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 <module>
    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 <module>
    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 <module>
    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 <module>
    from .sezm import (
  File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm.py", line 74, in <module>
    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 <module>
    from .block import (
  File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/block.py", line 43, in <module>
    from .ffn import (
  File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/ffn.py", line 37, in <module>
    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 <module>
    from .projection import (
  File "/opt/deepmd-kit/.venv/lib/python3.12/site-packages/deepmd/pt/model/descriptor/sezm_nn/projection.py", line 22, in <module>
    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:

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:

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

[qchempku2017]

I encountered another missing runtime dependency in the same DPA-4 / SeZM PyTorch path.

After installing e3nn, the model proceeds in inference, but fails during training:

RuntimeError: SeZM neighbor-list construction requires either 'nvalchemiops' or 'vesin', but neither is importable.

The traceback reaches:

deepmd.pt.model.model.sezm_model.build_neighbor_list
→ _select_neighbor_builder(nf, coord.device)
→ requires either 'nvalchemiops' or 'vesin'

This suggests that the SeZM / DPA-4 runtime path requires not only e3nn, but also at least one neighbor-list backend such as vesin or nvalchemiops.

If DPA-4 / SeZM is expected to be a mainstream PyTorch workflow, these dependencies should be declared as a coherent optional extra, for example:

dpa4 = [
    "e3nn",
    "vesin",
]

or:

sezm = [
    "e3nn",
    "vesin",
]

Alternatively, the installation documentation should explicitly state that DPA-4 / SeZM users need to install e3nn and either vesin or nvalchemiops.

Currently, the installation can succeed and the PyTorch backend can start, but the actual model fails only at runtime inside forward() due to missing optional dependencies. This makes the DPA-4 / SeZM installation path difficult to reproduce.

[qchempku2017]

I encountered another missing runtime dependency in the same DPA-4 / SeZM PyTorch path.

After installing e3nn, the model proceeds in inference, but fails during training:

RuntimeError: SeZM neighbor-list construction requires either 'nvalchemiops' or 'vesin', but neither is importable.

The traceback reaches:

deepmd.pt.model.model.sezm_model.build_neighbor_list
→ _select_neighbor_builder(nf, coord.device)
→ requires either 'nvalchemiops' or 'vesin'

This suggests that the SeZM / DPA-4 runtime path requires not only e3nn, but also at least one neighbor-list backend such as vesin or nvalchemiops.

If DPA-4 / SeZM is expected to be a mainstream PyTorch workflow, these dependencies should be declared as a coherent optional extra, for example:

dpa4 = [
"e3nn",
"vesin",
]
or:

sezm = [
"e3nn",
"vesin",
]
Alternatively, the installation documentation should explicitly state that DPA-4 / SeZM users need to install e3nn and either vesin or nvalchemiops.

Currently, the installation can succeed and the PyTorch backend can start, but the actual model fails only at runtime inside forward() due to missing optional dependencies. This makes the DPA-4 / SeZM installation path difficult to reproduce.

Actually we need vesin-torch here to work, not just vesin.

[njzjz-bot]

I think the dependency analysis here is missing the dynamic optional-dependencies generated by the custom build backend.

e3nn is not only declared under the static dpa-adapt extra. The project marks optional-dependencies as dynamic in pyproject.toml and provides them through:

[tool.scikit-build.metadata.optional-dependencies]
provider = "backend.dynamic_metadata"

backend.dynamic_metadata merges the static optional dependencies with backend.find_pytorch.get_pt_requirement(). The generated torch extra currently includes:

"e3nn>=0.5.9",
"vesin[torch]",
"nvalchemi-toolkit-ops>=0.3.1; python_version >= '3.11' and platform_system == 'Linux'",

So the statement that e3nn is only declared as a dpa-adapt dependency does not match the current source tree. The same applies to the neighbor-list dependencies: the PyTorch extra already asks for vesin[torch] rather than plain vesin, and also includes nvalchemi-toolkit-ops on supported Linux/Python versions.

If the package was installed with plain:

pip install .

then the optional torch extra was not requested, so these optional runtime dependencies are not expected to be installed. For the PyTorch runtime path, the intended install command should be closer to:

pip install '.[torch]'

or otherwise explicitly installing the generated torch extra dependencies.

There may still be a separate usability issue if dp --backend pytorch eagerly imports SeZM/DPA4 modules and fails before the user actually selects a SeZM/DPA4 model. That would be an import-laziness / error-message issue. But it is different from saying that the dependencies are undeclared: they are declared in the dynamically generated torch extra.

Authored by OpenClaw (model: custom-chat-jinzhezeng-group/gpt-5.5)

[qchempku2017]

Thanks for the clarification. I agree that my original dependency analysis missed the dynamically generated optional dependencies from backend.dynamic_metadata.

If the generated torch extra already includes:

e3nn>=0.5.9
vesin[torch]
nvalchemi-toolkit-ops>=0.3.1; python_version >= '3.11' and platform_system == 'Linux'

then the issue should not be phrased as “these dependencies are undeclared”.

However, I still think there is a usability and documentation problem.

The confusing part is that DP_ENABLE_PYTORCH=1 and DP_VARIANT=cuda can produce a PyTorch-enabled build, but pip install . does not install the generated torch runtime extra. As a result, the installation can appear successful, and the failure only appears later when dp --pt or a DPA4/SeZM path is executed.

For users, it is not obvious that the correct source installation command for the PyTorch runtime path should be (at least according to the current documentation):

pip install '.[torch]'

rather than:

pip install .

especially when the PyTorch backend was explicitly enabled at build time through environment variables.

So I would like to revise the request as follows:

1. Please make the source installation documentation explicitly state that PyTorch runtime users should install with pip install '.[torch]', not plain pip install ..
2. Please clarify the distinction between DP_ENABLE_PYTORCH=1 as a build-time option and .[torch] as a runtime dependency extra.
3. If dp --pt is executed without the required torch extra dependencies, please provide an actionable error message such as:

The PyTorch backend requires optional runtime dependencies.
Please install DeepMD-kit with: pip install '.[torch]'

4. If DPA4/SeZM modules are imported eagerly, please consider lazy imports or a preflight dependency check so that users do not encounter raw ModuleNotFoundError or neighbor-list backend errors deep inside the runtime stack.

The main issue is therefore not that the dependencies are absent from the project metadata, but that the intended installation path for PyTorch/DPA4 runtime dependencies is not sufficiently discoverable from the user-facing installation workflow.

[qchempku2017]

Further, I am willing to accept that the current source tree may be internally consistent: the build-system dependencies are declared, the backend path is present, and the PyTorch extra is dynamically generated.

However, the user-facing documentation in the website, particularly in section 2.2 Install from source code still does not provide a reproducible installation path for PyTorch + CUDA + DPA4/SeZM + C++ interface + LAMMPS.

The problem is not that every dependency is absent from the source tree. The problem is that the documentation does not explain the relationship between:

1. pip install .
2. pip install '.[torch]'
3. DP_ENABLE_PYTORCH=1
4. DP_VARIANT=cuda
5. CUDAToolkit_ROOT
6. CUDA_HOME
7. PyTorch wheel CUDA variants such as cu126/cu128
8. DPA4/SeZM runtime dependencies such as e3nn, vesin[torch], and nvalchemi-toolkit-ops
9. C++ interface installation
10. LAMMPS plugin / MPI compilation

These are not minor details. Missing any one of them can lead to a successful-looking installation that fails only later at runtime, during model import, neighbor-list construction, PyTorch Inductor compilation, or LAMMPS coupling.

So I am not claiming that the current metadata is necessarily wrong. I am saying that the documented installation workflow is not sufficient for an external user to reproduce a working DPA4/PyTorch/CUDA environment without reverse-engineering the build system or relying on internal images.