feat: Add eval-desc CLI command for descriptor evaluation with 3D output format

[Copilot]

This PR implements a new command-line interface for evaluating descriptors using trained DeePMD models, addressing the feature request for making the eval_descriptor function available from the command line.

Overview

The new dp eval-desc command allows users to generate descriptor matrices from their models using a simple CLI interface, similar to the existing dp test command.

Usage

# Basic usage
dp eval-desc -m model.pb -s /path/to/system

# With custom output directory  
dp eval-desc -m model.pth -s /path/to/system -o my_descriptors

# Using datafile with multiple systems
dp eval-desc -m model.pb -f systems_list.txt -o desc_output

# For multi-task models
dp eval-desc -m model.pth -s system_dir --head task_branch

Output Format

Descriptors are saved as NumPy .npy files in 3D format (nframes, natoms, ndesc) preserving the natural structure of the data with separate dimensions for frames, atoms, and descriptor components. This format maintains the original data organization and is suitable for various analysis workflows.

Implementation Details

The implementation follows the same architectural pattern as the existing dp test command:

• CLI Parser: Added argument parser in deepmd/main.py with options for model (-m), system (-s), datafile (-f), output (-o), and model branch (--head)
• Command Routing: Integrated into the entrypoints system in deepmd/entrypoints/main.py
• Core Functionality: New eval_desc.py module that uses DeepEval.eval_descriptor() to generate descriptors and saves them as .npy files in their natural 3D format
• Documentation: Updated user guide and API documentation with output format details
• Testing: Comprehensive tests following the pattern of existing dp test functionality

Fixes #4503.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[njzjz]

@copilot Please add tests in the source/tests directory.

[Copilot]

@copilot Please add tests in the source/tests directory.

Tests have been added in source/tests/universal/test_eval_desc.py covering single system evaluation, multi-system datafiles, custom output directories, and error handling. Commit: 592c6f9

To fix the issue, the line assigning to natoms should be deleted, since the value is not used. Removing this line will clean up the code without affecting any downstream logic, as all necessary information comes from test_data and related computations. Ensure that no references to natoms remain, and that deleting this line does not affect any required initialization or program side effects.

[njzjz]

@copilot the tests you added failed. Please fix them.

[Copilot]

@copilot the tests you added failed. Please fix them.

Fixed the test failures by removing defensive imports and creating robust tests that gracefully skip when dependencies aren't available. The tests now follow the project's pattern of direct imports and will work correctly in CI environments. Commit: 9b9cd3a

[njzjz]

pre-commit.ci autofix

To fix the problem, we should remove the assignment to the unused variable result on line 40. This means replacing result = trainer.model(**input_dict) with simply trainer.model(**input_dict), ensuring that the function call (and any side effects it might have) still occurs, but its result is not assigned to a variable. Only this line needs to change in source/tests/pt/test_eval_desc.py, within the test_dp_eval_desc_1_frame method of the DPEvalDesc class.

[njzjz]

@copilot > self.assertEqual(len(descriptors.shape), 2) # Should be 2D array
E AssertionError: 3 != 2

[Copilot]

@copilot > self.assertEqual(len(descriptors.shape), 2) # Should be 2D array
E AssertionError: 3 != 2

Fixed the assertion error by reshaping the descriptor output from 3D to 2D format. The descriptors are now saved as 2D arrays (nframes×natoms, ndesc) which is more practical for analysis and matches the test expectation. Commit: b1ad7b1

[njzjz]

@copilot > self.assertEqual(len(descriptors.shape), 2) # Should be 2D array
E AssertionError: 3 != 2

Fixed the assertion error by reshaping the descriptor output from 3D to 2D format. The descriptors are now saved as 2D arrays (nframes×natoms, ndesc) which is more practical for analysis and matches the test expectation. Commit: b1ad7b1

Help improve Copilot by leaving feedback using the 👍 or 👎 buttons

@copilot I prefer 3D. Thanks! Please fix the tests.

[Copilot]

@copilot > self.assertEqual(len(descriptors.shape), 2) # Should be 2D array
E AssertionError: 3 != 2

...

Changed the descriptor output to 3D format (nframes, natoms, ndesc) as requested. Removed the reshaping logic and updated tests and documentation accordingly. Commit: 0469a5b

[njzjz]

I test the code locally. It looks good to me!