### Quick start: submit a job with dpdispatcher

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/README.md

This example creates a Submission with a Shell machine using LazyLocalContext, specifies resources (1 node, 1 CPU, 0 GPU), and defines a single task that echoes 'hello'. It then runs the submission. This is the quick start from examples/submit_example.json.

```python
from dpdispatcher import Machine, Resources, Submission, Task

submission = Submission(
    work_base="0_md/",
    machine=Machine.load_from_dict(
        {"batch_type": "Shell", "local_root": "./", "context_type": "LazyLocalContext"}
    ),
    resources=Resources(
        number_node=1, cpu_per_node=1, gpu_per_node=0, queue_name="", group_size=1
    ),
    task_list=[
        Task(
            command="echo hello",
            task_work_path="task1/",
            forward_files=[],
            backward_files=[],
            outlog="log",
            errlog="err",
        )
    ],
)
submission.run_submission()
```

--------------------------------

### Example Python script with PEP 723 metadata

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/run.md

A complete example script that includes PEP 723 inline metadata for DPDispatcher configuration. The script prints 'hello world!'.

```py
# /// script
# # dpdispatcher doesn't use `requires-python` and `dependencies`
# requires-python = ">=3"
# dependencies = [
# ]
# [tool.dpdispatcher]
# work_base = "./"
# forward_common_files=[]
# backward_common_files=[]
# [tool.dpdispatcher.machine]
# batch_type = "Shell"
# local_root = "./"
# context_type = "LazyLocalContext"
# [tool.dpdispatcher.resources]
# number_node = 1
# cpu_per_node = 1
# gpu_per_node = 0
# group_size = 0
# [[tool.dpdispatcher.task_list]]
# # no need to contain the script filename
# # `uv run` supports dependencies declared in the PEP-723 format
# # See: https://docs.astral.sh/uv/guides/scripts/
# command = "uv run"
# # can be a glob pattern
# task_work_path = "./"
# forward_files = []
# backward_files = ["log"]
# ///

print("hello world!")
```

--------------------------------

### Project directory structure overview

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Directory layout of the project, showing the main package modules, example configurations, tests, documentation, and CI setup. Useful for understanding where to place or find machine, resource, and task files.

```text
.
├── README.md
├── pyproject.toml           # Project configuration and dependencies
├── dpdispatcher/            # Main package
│   ├── __init__.py
│   ├── submission.py        # Core submission/job/task classes
│   ├── machine.py          # Machine configuration
│   ├── contexts/           # Execution contexts (SSH, local, etc.)
│   ├── machines/           # HPC scheduler implementations
│   └── utils/              # Utility functions
├── examples/               # Example configurations and scripts
│   ├── machine/           # Example machine configs
│   ├── resources/         # Example resource specs
│   ├── task/             # Example task definitions
│   └── dpdisp_run.py     # Complete working example
├── tests/                # Comprehensive test suite
├── doc/                  # Sphinx documentation
└── ci/                   # CI/CD Docker configurations
```

--------------------------------

### dpdisp CLI usage examples

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/cli.md

Command-line usage examples for the dpdisp CLI, including submit, run, gui, and submission commands. The JSON submission mirrors `examples/submit_example.json`.

```bash
dpdisp submit submit_example.json
dpdisp submit submit_example.json --dry-run --no-clean
dpdisp run dpdisp_run.py --allow-ref
dpdisp gui --port 8080
dpdisp submission abcd1234ef567890... --download-terminated-log
```

--------------------------------

### Install DPDispatcher with Bohrium support

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/README.md

Installs DPDispatcher with optional Bohrium support. Use this command to enable Bohrium integration.

```bash
pip install dpdispatcher[bohrium]
```

--------------------------------

### PEP 723 script example for dpdisp run

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/cli.md

PEP 723 script example copied from `examples/dpdisp_run.py`. Run with `dpdisp run dpdisp_run.py`.

```python
# /// script
# requires-python = ">=3"
# [tool.dpdispatcher]
# work_base = "./"
# [tool.dpdispatcher.machine]
# batch_type = "Shell"
# local_root = "./"
# context_type = "LazyLocalContext"
# [tool.dpdispatcher.resources]
# number_node = 1
# cpu_per_node = 1
# gpu_per_node = 0
# group_size = 0
# [[tool.dpdispatcher.task_list]]
# command = "uv run"
# task_work_path = "./"
# backward_files = ["log"]
# ///

print("hello world!")
```

--------------------------------

### LazyLocalContext recommended local dev setup

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/contexts-local.md

Use this snippet for the recommended local development setup with LazyLocalContext, which avoids SSH and staging copies. It matches the examples/lazy_local.json configuration and runs a submission with a single task.

```python
from dpdispatcher import Machine, Resources, Submission, Task

submission = Submission(
    work_base="./",
    machine=Machine(
        batch_type="Shell",
        context_type="LazyLocalContext",  # no SSH, no staging copy
        local_root="./",
    ),
    resources=Resources(1, 1, 0, "", 1),
    task_list=[Task(command="python solve.py", task_work_path=".")],
)
submission.run_submission()
```

--------------------------------

### Run example with lazy local execution via dpdisp run

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Run the provided example locally using the `dpdisp run` command with the `LazyLocalContext` and `Shell` batch type. This does not require HPC; it creates a log file containing "hello world!" and various job tracking files that are automatically cleaned up.

```bash
# Example with lazy local execution (no HPC needed)
dpdisp run examples/dpdisp_run.py

# Example output files created:
# - log: contains "hello world!" output
# - Various job tracking files (automatically cleaned up)
```

--------------------------------

### Install dpdisp-submit skill with npx skills add

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/agent-skills.md

Downloads and installs the dpdisp-submit skill from the dpdispatcher repository into the agent's workspace skills directory. Placeholder <your-agent-name> must be replaced with your agent name. After running it, restart the session so the skill is reloaded.

```sh
npx -y skills add deepmodeling/dpdispatcher -a <your-agent-name> -y
```

--------------------------------

### Build Documentation

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Build the documentation. Install the docs extra dependencies, change to the 'doc' directory, and run 'make html'. Takes about 14 seconds.

```bash
uv pip install .[docs]
cd doc
make html
```

--------------------------------

### Install DPDispatcher with pip

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/README.md

Installs the DPDispatcher package via pip. This is the standard installation method.

```bash
pip install dpdispatcher
```

--------------------------------

### Example submission JSON file

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/submit.md

Example JSON file for a submission. It includes work_base, machine, resources, forward/backward common files, and a task list. The machine uses batch_type Shell and context_type LazyLocalContext.

```json
{
    "work_base": "0_md/",
    "machine": {
        "batch_type": "Shell",
        "local_root": "./",
        "context_type": "LazyLocalContext"
    },
    "resources": {
        "number_node": 1,
        "cpu_per_node": 1,
        "gpu_per_node": 0,
        "queue_name": "",
        "group_size": 1
    },
    "forward_common_files": [],
    "backward_common_files": [],
    "task_list": [
        {
            "command": "echo hello",
            "task_work_path": "task1/",
            "forward_files": [],
            "backward_files": [],
            "outlog": "log",
            "errlog": "err"
        }
    ]
}
```

--------------------------------

### Staging-plan usage example

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/file-manager.md

Shows how to use FileTransfer and SubmissionStagingPlan to upload and download files, mirroring LocalContext.upload/download. Raises FileNotFoundError if an upload file is missing.

```python
from dpdispatcher.file_manager import (
    FileTransfer,
    SubmissionStagingPlan,
)

plan = SubmissionStagingPlan("./", submission)
upload_manifest = plan.upload_manifest()
if upload_manifest.missing:
    missing = upload_manifest.missing[0]
    raise FileNotFoundError(f"cannot find upload file {missing.pattern}")
FileTransfer("./remote", symlink=True, link_sources=True).apply(upload_manifest)

download_manifest = plan.download_manifest("./remote", fallback_root="./")
FileTransfer("./", move=True).apply(download_manifest)  # move remote → local
```

--------------------------------

### DP-GUI entrypoint function signature

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/cli.md

Function signature for the DP-GUI entrypoint. Delegates to `from dpgui import start_dpgui` and raises `ModuleNotFoundError("To use DP-GUI, please install the dpgui package:\npip install dpgui")` when the optional dependency is missing.

```python
def start_dpgui(*, port: int, bind_all: bool, **kwargs: Any) -> None:  # noqa: ANN401
    """Host DP-GUI server."""
```

--------------------------------

### Usage example for HDFS operations

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/archive-hdfs.md

Shows how to use the HDFS class: create a directory, copy a local file, attempt to copy a remote file while handling the missing path error, and check existence.

```python
from dpdispatcher.utils.hdfs_cli import HDFS, HDFSMissingPathError

HDFS.mkdir("hdfs:///user/dpgen/job1")
HDFS.copy_from_local("inputs.tgz", "hdfs:///user/dpgen/job1")
try:
    HDFS.copy_to_local("hdfs:///user/dpgen/job1/results.tar.gz", "./out/")
except HDFSMissingPathError:
    print("no result archive yet")
print(HDFS.exists("hdfs:///user/dpgen/job1"))
```

--------------------------------

### Using JobStatus enum

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/utils.md

Shows how to import and use JobStatus. The example asserts that `JobStatus.running` equals the integer 3 and has the name "running".

```python
from dpdispatcher.utils.job_status import JobStatus

state = JobStatus.running
assert state == 3 and state.name == "running"

```

--------------------------------

### Job API methods (job_create, get_job_detail, get_log, get_tasks_list, get_job_result_url, kill)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/dpcloudserver.md

Defines methods for creating and managing jobs. job_create maps snake_case keys to camelCase and posts to /brm/v2/job/add, returning (jobId, jobGroupId). get_job_detail GETs /brm/v1/job/{job_id} and returns None for HTTP 200 responses with errors. get_log fetches byte ranges from the latest log URL and tracks offsets. get_tasks_list pages through job lists. get_job_result_url and kill accept composite IDs.

```python
def job_create(
    self,
    job_type: str,
    oss_path: str,
    input_data: dict[str, Any],  # noqa: ANN401
    program_id: int | None = None,
    group_id: int | None = None,
) -> tuple[int, int | None]:
    ...

def get_job_detail(self, job_id: str | int) -> dict[str, Any] | None: ...
def get_log(self, job_id: str | int) -> str: ...
def get_tasks_list(self, group_id: int, per_page: int = 30) -> list[dict[str, Any]]: ...
def get_job_result_url(self, job_id: str | int) -> str | None: ...
def kill(self, job_id: str | int) -> dict[str, Any] | None: ...
```

--------------------------------

### machine.json configuration for DistributedShell and HDFSContext

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/dpdispatcher_on_yarn.md

Example machine.json configuration with batch_type DistributedShell and context_type HDFSContext. Includes command, local_root, remote_root, resources settings (number_node, cpu_per_node, gpu_per_node, queue_name, group_size, source_list, prepend_script, kwargs, envs).

```json
  "fp": [
    {
      "command": "mpirun -n 32 vasp_std",
      "machine": {
        "batch_type": "DistributedShell",
        "context_type": "HDFSContext",
        "local_root": "./",
        "remote_root": "hdfs://path/to/remote/root"
      },
      "resources": {
        "number_node": 1,
        "cpu_per_node": 32,
        "gpu_per_node": 0,
        "queue_name": "queue_name",
        "group_size": 1,
        "source_list": ["/opt/intel/oneapi/setvars.sh"],
        "prepend_script": [
          "export HADOOP_HOME=\"${HADOOP_HOME:-/path/to/hadoop}\"",
          "export CLASSPATH=\"$(\"${HADOOP_HOME}/bin/hadoop\" classpath --glob)\"",
          "export PATH=\"${HADOOP_HOME}/bin${PATH:+:${PATH}}\""
        ],
        "kwargs": {
          "img_name": "",
          "mem_limit": 32,
          "yarn_path": "/path/to/yarn/jars"
        },
        "envs": {}
      }
    }
  ]
```

--------------------------------

### Object storage methods (_get_oss_bucket, download, download_from_url, upload)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/dpcloudserver.md

Defines methods for interacting with object storage. _get_oss_bucket obtains STS credentials from GET /data/get_sts_token and builds an oss2.Bucket. download_from_url streams a URL to save_file with 3 retries, raising RequestInfoException on failure. upload performs a multipart upload with 1 MB preferred parts.

```python
def _get_oss_bucket(self, endpoint: str, bucket_name: str) -> Any: ...
def download(self, oss_file: str, save_file: str, endpoint: str, bucket_name: str) -> str: ...
def download_from_url(self, url: str, save_file: str | os.PathLike) -> None: ...
def upload(self, oss_task_zip: str, zip_task_file: str, endpoint: str, bucket_name: str) -> Any: ...
```

--------------------------------

### Initialize: Fetch DPDispatcher Schema Protocol

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/skills/dpdisp-submit/SKILL.md

Run this command before gathering information and building the configuration to read and learn the latest Schema protocol specifications and requirements.

```bash
uvx --with dpdispatcher dargs doc dpdispatcher.entrypoints.submit.submission_args
```

--------------------------------

### Run pre-commit, pyright, tests, and documentation build

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/CONTRIBUTING.md

Run this command sequence after documentation or Python changes to enforce style, type-check, run tests with coverage, and build the documentation.

```bash
pre-commit run --all-files
pyright
python -m coverage run -p --source=./dpdispatcher -m unittest -v
python -m coverage combine
python -m coverage report
make -C doc html
```

--------------------------------

### normalize_relative usage examples

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/file-manager.md

Interactive examples showing output for normalize_relative with and without glob. Backslashes are normalized, empty components removed, glob characters allowed when allow_glob is True.

```python
>>> PathPolicy.normalize_relative("./a//b/")          # → "a/b"
>>> PathPolicy.normalize_relative("a/*.dat", allow_glob=True)  # → "a/*.dat"

```

--------------------------------

### start_dpgui(port: int, bind_all: bool, **kwargs: Any) -> None

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.entrypoints.md

Hosts the DP-GUI server on a specified port, optionally binding to all public interfaces.

```APIDOC
## start_dpgui(port: int, bind_all: bool, **kwargs: Any) -> None

### Description
Host DP-GUI server.

### Parameters
- **port** (int) - Required - The port to serve DP-GUI on.
- **bind_all** (bool) - Required - Serve on all public interfaces. This will expose your DP-GUI instance to the network on both IPv4 and IPv6 (where available).
- **kwargs** (Any) - Optional - additional arguments

### Raises
- **ModuleNotFoundError** - The dpgui package is not installed
```

--------------------------------

### Machine.get_exit_code(job)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Gets the exit code of the job.

```APIDOC
## Machine.get_exit_code(job)

### Description
Gets the exit code of the job.

### Method
instance method

### Signature
get_exit_code(job: Job) → int

### Parameters
- **job** (Job) - Required - The job.

### Returns
- **int** - The exit code of the job.

```

--------------------------------

### Basic Task creation and serialization

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/task.md

Creates a Task with command, work path, forward/backward files, and log settings, then prints its hash and serialized form.

```python
from dpdispatcher import Task

task = Task(
    command="lmp -in in.lammps",
    task_work_path="md/run1",
    forward_files=["in.lammps", "data.*"],
    backward_files=["log.lammps", "dump/*.lammpstrj"],
    outlog="log",
    errlog="err",
    task_name="lammps-run1",
)
print(task.task_hash)
print(task.serialize())
```

--------------------------------

### OpenAPI.get_exit_code(job)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.machines.md

Gets the exit code of the job.

```APIDOC
## get_exit_code(job: SubmissionJob) → int

### Description
Get exit code of the job.

### Parameters
- **job** (SubmissionJob) - Required - The job.

### Returns
- **int** - The exit code.

```

--------------------------------

### Bohrium.get_exit_code(job)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.machines.md

Gets the exit code of the job.

```APIDOC
## get_exit_code(job)

### Description
Get exit code of the job.

### Parameters
- **job** (Job) - Required - The job to get the exit code for.

### Returns
- **int** - The exit code of the job.
```

--------------------------------

### SSHContext.__init__

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/contexts-ssh.md

Initializes an SSHContext instance with local and remote roots and SSH settings. Opens the SSH session and creates the remote root if requested.

```APIDOC
## SSHContext.__init__

### Description
Initializes an SSHContext instance with local and remote roots and SSH settings. Opens the SSH session and creates the remote root if requested.

### Method
Constructor

### Signature
```python
SSHContext(
    local_root: str,
    remote_root: str,
    remote_profile: dict[str, Any],
    clean_asynchronously: bool = False,
    create_remote_root: bool = False,
    *args: Any,
    **kwargs: Any
) -> None
```

### Parameters
- **local_root** (str) - Required - Local working root.
- **remote_root** (str) - Required - Must be an absolute remote path (AssertionError otherwise).
- **remote_profile** (dict) - Required - SSH settings passed to SSHSession(**remote_profile).
- **clean_asynchronously** (bool) - Optional - Default: False - Run remote cleanup with nohup.
- **create_remote_root** (bool) - Optional - Default: False - Recursively create remote_root when parents are missing.

### Notes
- `archive_chunk_size == 0` is popped from the profile before use (keeps pre-feature submission hashes stable).
- Construction opens the session and creates the remote root.
```

--------------------------------

### Load configuration with allow_ref=True

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/python-api.md

Pass allow_ref=True to enable external $ref resolution, which reads additional local files. Only use for trusted configuration.

```python
task = Task.load_from_json("task.json", allow_ref=True)
machine = Machine.load_from_dict(machine_config, allow_ref=True)
resources = Resources.load_from_dict(resources_config, allow_ref=True)
```

--------------------------------

### dpdispatcher.Job.get_last_error_message

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Get last error message when the job is terminated.

```APIDOC
## Job.get_last_error_message

### Description
Get last error message when the job is terminated.

### Method
method

### Signature
`get_last_error_message() -> str | None`

### Returns
- **str | None** - Last error message when the job is terminated.
```

--------------------------------

### get_last_error_message()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/job.md

Get last error message when the job is terminated.

```APIDOC
## get_last_error_message

### Description
Get last error message when the job is terminated.

### Method
get_last_error_message

### Signature
```python
def get_last_error_message(self) -> str | None:
```

### Returns
- **str | None** - The colorized error message in red ANSI.
```

--------------------------------

### LazyLocalContext.call

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/contexts-local.md

Starts a subprocess to run a command in the local context.

```APIDOC
## LazyLocalContext.call

### Description
Starts a subprocess to run a command in the local context.

### Method
Instance Method

### Signature
```python
def call(self, cmd: str) -> sp.Popen:
```

### Parameters
- **cmd** (str) - Required - The command to run.

### Returns
sp.Popen - The subprocess object.
```

--------------------------------

### DistributedShell.gen_script_env

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/machines-shell-cloud.md

Generates the environment setup portion of the script for a DistributedShell backend.

```APIDOC
## DistributedShell.gen_script_env

### Description
Generates the environment setup portion of the script for a DistributedShell backend. Pulls the submission archive (`hadoop fs -get {remote_root}/*.tgz .`) and extracts every `*.tgz`.

### Method
DistributedShell.gen_script_env

### Parameters
- **job** (Job) - Required - The job object.

### Returns
- **str** - The environment setup script.
```

--------------------------------

### Load Machine from dict with error handling and $ref disabled

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/machine.md

Demonstrates loading a Machine from a dict with Slurm batch type and SSHContext. Includes try/except blocks for unknown batch_type (raises KeyError) and for load_from_dict with allow_ref=False to reject external references.

```python
from dpdispatcher import Machine

machine = Machine.load_from_dict(
    {
        "batch_type": "Slurm",
        "local_root": "./",
        "remote_root": "/scratch/work",
        "context_type": "SSHContext",
        "remote_profile": {"hostname": "login.hpc.example.org", "username": "alice"},
    }
)

try:
    Machine.load_from_dict({"batch_type": "NoSuchScheduler", "local_root": "./", "context_type": "LazyLocalContext"})
except KeyError as e:
    print("unknown batch_type", e)

try:
    Machine.load_from_dict(
        {"$ref": "machine.yaml"}, allow_ref=False  # external references rejected
    )
except Exception:
    print("$ref disabled — rejected")

```

--------------------------------

### Machine.arginfo()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Builds the dargs schema for machine and context configuration.

```APIDOC
## Machine.arginfo()

### Description
Builds the dargs schema for machine and context configuration.

### Method
classmethod

### Signature
arginfo() → Argument

### Returns
- **Argument** - The dargs schema for machine and context configuration.

```

--------------------------------

### Task.get_task_state(context)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Gets the task state by checking the tag file.

```APIDOC
## Task.get_task_state(context: BaseContext) → None

### Description
Gets the task state by checking the tag file.

### Parameters
- **context** (BaseContext) - Required - The context of the task.
```

--------------------------------

### LazyLocalContext.get_return

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/contexts-local.md

Gets the return code and output from a subprocess, catching SubprocessError.

```APIDOC
## LazyLocalContext.get_return

### Description
Gets the return code and output from a subprocess. Catches sp.SubprocessError.

### Method
Instance Method

### Signature
```python
def get_return(
    self, proc: sp.Popen
) -> tuple[int | None, SPRetObj | None, SPRetObj | None]:
```

### Parameters
- **proc** (sp.Popen) - Required - The subprocess object.

### Returns
tuple[int | None, SPRetObj | None, SPRetObj | None] - A tuple containing the return code, stdout, and stderr.
```

--------------------------------

### Machine.arginfo()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/api.md

Returns argument information for the machine's constructor.

```APIDOC
## Machine.arginfo()

### Description
Returns argument information for the machine's constructor, likely used for introspection or validation.

### Method
`arginfo()`

### Returns
- **dict** - Argument information.
```

--------------------------------

### Test Basic CLI

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Test the basic CLI functionality by displaying help and running a sample job dispatch script.

```bash
dpdisp --help
dpdisp run examples/dpdisp_run.py
```

--------------------------------

### Machine.gen_script_env(job)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Generates environment setup shared by every task in a job.

```APIDOC
## Machine.gen_script_env(job)

### Description
Generates environment setup shared by every task in a job.

### Method
instance method

### Signature
gen_script_env(job: Job) → str

### Parameters
- **job** (Job) - Required - The job for which to generate the environment setup.

### Returns
- **str** - The environment setup script.

```

--------------------------------

### Run Sample Job Dispatch Script

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Run the sample job dispatch script directly.

```bash
python examples/dpdisp_run.py
```

--------------------------------

### Submission.run_submission()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/api.md

Submits the submission to the scheduler. This method uploads jobs and starts the submission process.

```APIDOC
## Submission.run_submission()

### Description
Runs the submission, submitting all jobs to the cluster.

### Method
Submit

### Parameters
No parameters documented.

### Response
No response documented.

```

--------------------------------

### Task.get_task_state()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/api.md

Gets the current state of the task. This method queries the cluster for the task's status.

```APIDOC
## Task.get_task_state()

### Description
Gets the current state of the task from the scheduler.

### Method
Query

### Parameters
No parameters documented.

### Response
Returns a TaskState enum.

```

--------------------------------

### Create Resources with custom flags and strategy

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/resources.md

Constructs a Resources object with node, queue, and strategy settings, then prints its serialized form. Useful for basic request and strategy tuning.

```python
from dpdispatcher import Resources

res = Resources(
    number_node=2,
    cpu_per_node=24,
    gpu_per_node=0,
    queue_name="shared",
    group_size=4,
    custom_flags=["#SBATCH --time=24:00:00", "#SBATCH --mem=16G"],
    strategy={"if_cuda_multi_devices": True, "ratio_unfinished": 0.1},
    para_deg=2,
    module_list=["intel/2020"],
    source_list=["activate /home/user/deepmd-kit"],
    envs={"OMP_NUM_THREADS": 4},
    wait_time=5,
)
print(res.serialize())
```

--------------------------------

### Task.get_task_state()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/task.md

Gets the task state by checking the tag file, flipping to finished when the tag exists.

```APIDOC
## Task.get_task_state()

### Description
Gets the task state by checking the tag file, flipping to finished when the tag exists.

### Method
`get_task_state(self, context: "BaseContext") -> None`

### Parameters
- **context** (BaseContext) - Required - The context in which to check for the tag file.

### Returns
None
```

--------------------------------

### GET {base_url}/brm/v1/job/{job_id}

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/endpoints.md

Retrieves details of a specific job by its ID. Used by get_job_detail and get_job_result_url.

```APIDOC
## GET {base_url}/brm/v1/job/{job_id}

### Description
Retrieves details of a specific job by its ID. Used by get_job_detail and get_job_result_url.

### Method
GET

### Endpoint
{base_url}/brm/v1/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (integer) - Required - Job ID. Composite form "{id}:job_group_id:{gid}" must be split by callers.

### Response
#### Success Response (200)
- **data.status** (integer) - Job status.
- **data.exitCode** (integer) - Exit code.
- **data.resultUrl** (string) - URL to download result files.
- **data.id** (integer) - Job ID.
- **data.logFiles** (array) - List of log files.

#### Response Example
{
  "code": "0000",
  "data": {
    "status": 3,
    "exitCode": 0,
    "resultUrl": "https://example.com/result.zip",
    "id": 12345,
    "logFiles": ["stdout.log"]
  }
}
```

--------------------------------

### Task.get_task_state()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.md

Gets the task state by checking the tag file. This method updates the task state based on the context.

```APIDOC
## Task.get_task_state(context)

### Description
Get the task state by checking the tag file.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
#### Parameters
- **context** (BaseContext) - Required - The context of the task.

### Request Example
N/A

### Response
#### Success Response (None)
- **None** - No return value.

#### Response Example
N/A

### Error Handling
No explicit error handling documented.
```

--------------------------------

### Submission.__init__ constructor

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/submission.md

Constructor for the Submission class. Note that machine, resources, forward_common_files, and backward_common_files are positional; task_list, previous_submission_hash, and continue_on_failure are keyword-only. Relative work_base and common file paths are normalized via PathPolicy.normalize_relative; absolute paths are accepted as-is. previous_submission_hash must match [0-9a-f]{40} or raise ValueError; continue_on_failure default is False (fail-fast).

```python
def __init__(
    self,
    work_base: str,
    machine: Optional["Machine"] = None,
    resources: Optional["Resources"] = None,
    forward_common_files: list[str] | None = None,
    backward_common_files: list[str] | None = None,
    *,
    task_list: list["Task"] | None = None,
    previous_submission_hash: str | None = None,
    continue_on_failure: bool = False,
) -> None:
```

--------------------------------

### Usage of safe_extract_tar and safe_extract_zip

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/api-reference/archive-hdfs.md

Example of extracting a tar and zip archive with error handling, as used by dpdispatcher/utils/dpcloudserver/zip_file.py and the SSH context.

```python
import tarfile
from dpdispatcher.utils.archive import UnsafeArchiveError, safe_extract_tar, safe_extract_zip

with tarfile.open("results.tar.gz") as tar:
    try:
        safe_extract_tar(tar, "./out")
    except UnsafeArchiveError as e:
        print("archive rejected:", e)

from zipfile import ZipFile
with ZipFile("back.zip") as zf:
    extracted = safe_extract_zip(zf, "./out")
    print(extracted)
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Run linting and formatting checks. Takes less than 5 seconds. If it fails due to network issues, fall back to 'ruff check . && ruff format --check .'.

```bash
pre-commit run --all-files
```

--------------------------------

### GET {base_url}/brm/v1/job/list?groupId={group_id}&page={page}&pageSize={per_page}

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/endpoints.md

Lists jobs in a group with pagination. Used by get_tasks_list.

```APIDOC
## GET {base_url}/brm/v1/job/list?groupId={group_id}&page={page}&pageSize={per_page}

### Description
Lists jobs in a group with pagination. Used by get_tasks_list.

### Method
GET

### Endpoint
{base_url}/brm/v1/job/list?groupId={group_id}&page={page}&pageSize={per_page}

### Parameters
#### Query Parameters
- **groupId** (integer) - Required - Group ID to filter jobs.
- **page** (integer) - Required - Page number.
- **pageSize** (integer) - Required - Number of items per page.

### Response
#### Success Response (200)
- **data.items** (array) - List of job detail dictionaries.

#### Response Example
{
  "code": "0000",
  "data": {
    "items": [
      {
        "id": 12345,
        "status": 3
      }
    ]
  }
}
```

--------------------------------

### Resources.arginfo()

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/api.md

Returns argument information for Resources constructor.

```APIDOC
## Resources.arginfo()

### Description
Returns argument information for the Resources constructor.

### Method
`arginfo()`

### Returns
- **dict** - Argument information.
```

--------------------------------

### Client.get(url, header, params, retry)

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/doc/api/dpdispatcher.utils.dpcloudserver.md

Performs an HTTP GET request to the legacy Bohrium API and returns the parsed JSON response.

```APIDOC
## Client.get(url, header, params, retry)

### Description
Sends an HTTP GET request to the specified URL with optional headers and query parameters. Returns the response as a dictionary.

### Method
SDK method

### Signature
`get(url: str, header: dict[str, str] | None = None, params: dict[str, Any] | None = None, retry: int = 5) -> dict[str, Any]`

### Parameters
- **url** (str) - Required - The URL to send the GET request to.
- **header** (dict[str, str] | None) - Optional - HTTP headers to include.
- **params** (dict[str, Any] | None) - Optional - Query parameters to append.
- **retry** (int) - Optional - Number of retry attempts (default: 5).

### Returns
- **dict[str, Any]** - The JSON response body.

```

--------------------------------

### GET {base_url}/data/get_sts_token

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/_autodocs/endpoints.md

Retrieves temporary STS credentials for Aliyun OSS access. Used to build an OSS bucket for multipart downloads/uploads.

```APIDOC
## GET {base_url}/data/get_sts_token

### Description
Retrieves temporary STS credentials for Aliyun OSS access. Used to build an OSS bucket for multipart downloads/uploads.

### Method
GET

### Endpoint
{base_url}/data/get_sts_token

### Response
#### Success Response (200)
- **data.AccessKeyId** (string) - STS access key ID.
- **data.AccessKeySecret** (string) - STS access key secret.
- **data.SecurityToken** (string) - STS security token.

#### Response Example
{
  "code": "0000",
  "data": {
    "AccessKeyId": "LTAI...",
    "AccessKeySecret": "secret",
    "SecurityToken": "token"
  }
}
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/deepmodeling/dpdispatcher/blob/master/AGENTS.md

Activate the Python virtual environment that is automatically set up by the Copilot environment.

```bash
source .venv/bin/activate
```