feat: add comprehensive type hints to core modules excluding backends and tests (#4936)

- [x] Add comprehensive type hints to core modules excluding backends
and tests
- [x] **Fixed type annotation issues from code review:**
  - Fixed `head` parameter type from `Any` to `str` in calculator.py
- Fixed `neighbor_list` parameter type to use proper ASE NeighborList
type annotation
  - Fixed `**kwargs` type from `object` to `Any` in deep_polar.py
- Fixed `write_model_devi_out` return type from `None` to `np.ndarray`
to match actual return value
- Fixed `get_natoms_vec` return type from `list[int]` to `np.ndarray` to
match actual return type
- Fixed `_get_natoms_2` return type from `list[int]` to `tuple[int,
np.ndarray]` to match actual return values
- Fixed `make_index` return type from `dict[str, int]` to `str` to match
actual return value
  - Added missing imports for type annotations (ASE NeighborList, Any)

**Current status:** All type annotation suggestions from code review
have been addressed. All ruff checks pass with zero violations.

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/deepmodeling/deepmd-kit/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: njzjz <[email protected]>

Author: Copilot

deepmd/__init__.py

@@ -8,6 +8,14 @@
 modules for performance.
 """
 
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+if TYPE_CHECKING:
+    from deepmd.infer import DeepPotential as DeepPotentialType
+
 try:
     from deepmd._version import version as __version__
 except ImportError:
@@ -16,7 +24,7 @@
     )
 
 
-def DeepPotential(*args, **kwargs):
+def DeepPotential(*args: Any, **kwargs: Any) -> "DeepPotentialType":
     """Factory function that forwards to DeepEval (for compatibility
     and performance).
 

deepmd/calculator.py

@@ -6,6 +6,7 @@
 )
 from typing import (
     TYPE_CHECKING,
+    Any,
     ClassVar,
     Optional,
     Union,
@@ -25,6 +26,9 @@
     from ase import (
         Atoms,
     )
+    from ase.neighborlist import (
+        NeighborList,
+    )
 
 __all__ = ["DP"]
 
@@ -85,9 +89,9 @@ def __init__(
         model: Union[str, "Path"],
         label: str = "DP",
         type_dict: Optional[dict[str, int]] = None,
-        neighbor_list=None,
-        head=None,
-        **kwargs,
+        neighbor_list: Optional["NeighborList"] = None,
+        head: Optional[str] = None,
+        **kwargs: Any,
     ) -> None:
         Calculator.__init__(self, label=label, **kwargs)
         self.dp = DeepPot(

deepmd/common.py

@@ -284,7 +284,7 @@ def symlink_prefix_files(old_prefix: str, new_prefix: str) -> None:
             shutil.copyfile(ori_ff, new_ff)
 
 
-def get_hash(obj) -> str:
+def get_hash(obj: Any) -> str:
     """Get hash of object.
 
     Parameters

deepmd/entrypoints/convert_backend.py

@@ -1,4 +1,8 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
+from typing import (
+    Any,
+)
+
 from deepmd.backend.backend import (
     Backend,
 )
@@ -8,7 +12,7 @@ def convert_backend(
     *,  # Enforce keyword-only arguments
     INPUT: str,
     OUTPUT: str,
-    **kwargs,
+    **kwargs: Any,
 ) -> None:
     """Convert a model file from one backend to another.
 

deepmd/entrypoints/doc.py

@@ -1,6 +1,10 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 """Module that prints train input arguments docstrings."""
 
+from typing import (
+    Any,
+)
+
 from deepmd.utils.argcheck import (
     gen_doc,
     gen_json,
@@ -11,7 +15,7 @@
 
 
 def doc_train_input(
-    *, out_type: str = "rst", multi_task: bool = False, **kwargs
+    *, out_type: str = "rst", multi_task: bool = False, **kwargs: Any
 ) -> None:
     """Print out trining input arguments to console."""
     if out_type == "rst":

deepmd/entrypoints/eval_desc.py

@@ -7,6 +7,7 @@
     Path,
 )
 from typing import (
+    Any,
     Optional,
 )
 
@@ -34,7 +35,7 @@ def eval_desc(
     datafile: str,
     output: str = "desc",
     head: Optional[str] = None,
-    **kwargs,
+    **kwargs: Any,
 ) -> None:
     """Evaluate descriptors for given systems.
 

deepmd/entrypoints/gui.py

@@ -1,8 +1,12 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 """DP-GUI entrypoint."""
 
+from typing import (
+    Any,
+)
 
-def start_dpgui(*, port: int, bind_all: bool, **kwargs) -> None:
+
+def start_dpgui(*, port: int, bind_all: bool, **kwargs: Any) -> None:
     """Host DP-GUI server.
 
     Parameters

deepmd/entrypoints/ipi.py

@@ -15,7 +15,7 @@
 ROOT_DIR = get_op_dir()
 
 
-def _program(name: str, args: list[str]):
+def _program(name: str, args: list[str]) -> None:
     """Execute a program.
 
     Parameters

deepmd/entrypoints/neighbor_stat.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 import logging
 from typing import (
+    Any,
     Optional,
 )
 
@@ -24,8 +25,8 @@ def neighbor_stat(
     type_map: Optional[list[str]],
     mixed_type: bool = False,
     backend: str = "tensorflow",
-    **kwargs,
-):
+    **kwargs: Any,
+) -> None:
     """Calculate neighbor statistics.
 
     Parameters

deepmd/entrypoints/show.py

@@ -1,5 +1,8 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 import logging
+from typing import (
+    Any,
+)
 
 from deepmd.infer.deep_eval import (
     DeepEval,
@@ -19,7 +22,7 @@ def show(
     *,
     INPUT: str,
     ATTRIBUTES: list[str],
-    **kwargs,
+    **kwargs: Any,
 ) -> None:
     model = DeepEval(INPUT, head=0)
     model_params = model.get_model_def_script()