diff --git a/README.md b/README.md index 493b963ec3..c7497b7860 100644 --- a/README.md +++ b/README.md @@ -212,9 +212,26 @@ plugins. Applications can therefore open the backend required by a model without directly linking every framework. > [!NOTE] -> Working with an AI coding or scientific agent? DeePMD-kit ships +> Working with an AI coding or scientific agent? Start with +> [Install with an AI agent][agent-install], or browse the > [official Agent Skills][agent-skills] for model selection, training, > fine-tuning, Python inference, and LAMMPS workflows. +> +> ```bash +> npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \ +> --skill deepmd-install -y +> ``` +> +> If direct GitHub access fails, clone the official Gitee mirror and install +> from the local checkout: +> +> ```bash +> git clone --depth 1 \ +> https://gitee.com/deepmodeling/deepmd-kit.git \ +> deepmd-kit-skill-source +> npx -y skills add ./deepmd-kit-skill-source/skills \ +> --skill deepmd-install -y +> ``` ## 📚 Documentation and community @@ -251,6 +268,7 @@ that matches the version used and the method-specific papers listed in DeePMD-kit is licensed under the [GNU Lesser General Public License v3.0 or later](./LICENSE). +[agent-install]: https://docs.deepmodeling.com/projects/deepmd/en/latest/install/install-with-agent.html [agent-skills]: https://docs.deepmodeling.com/projects/deepmd/en/latest/agent-skills.html [ase]: https://docs.deepmodeling.com/projects/deepmd/en/latest/third-party/ase.html [backends]: https://docs.deepmodeling.com/projects/deepmd/en/latest/backend.html diff --git a/doc/agent-skills.md b/doc/agent-skills.md index 54abd87d2e..6e488a32de 100644 --- a/doc/agent-skills.md +++ b/doc/agent-skills.md @@ -2,7 +2,7 @@ DeePMD-kit provides official [Agent Skills](https://agentskills.io/what-are-skills) that help AI agents run DeePMD-kit workflows in a reproducible way. These skills capture -project-specific operating knowledge—such as training inputs, model +project-specific operating knowledge—such as installation, training inputs, model selection, deployment, LAMMPS integration, and Python inference patterns—so an agent can turn a high-level request into concrete files, commands, and validation steps. @@ -14,6 +14,11 @@ in the DeePMD-kit repository under `skills/`. ## List of skills +- `deepmd-install`: Select a pip, conda, `dp1s`, offline, Docker, or source + installation path, load the official documentation matching the requested + version, and verify the requested Python, C/C++, or LAMMPS interface. A + compact failure-mode reference covers issues not resolved by the install + pages. - `deepmd-train`: Choose a DeePMD-kit model family, then train from scratch. The skill uses progressive disclosure: the top-level workflow handles common training steps and model selection, while model-specific configuration lives @@ -40,6 +45,10 @@ paper: ## Install skills +To have an agent install DeePMD-kit itself, send +[Install with an AI agent](install/install-with-agent.md) and ask it to load +`deepmd-install`. + ### If you are a user The easiest way is to send this page to your agent and ask it to install the @@ -51,7 +60,7 @@ If you already have a DeePMD-kit checkout, run this command from the repository root: ```bash -npx -y skills add ./skills -a openclaw -y +npx -y skills add ./skills --skill '*' -y ``` If you do not have a checkout, the same skills can also be installed directly @@ -59,15 +68,25 @@ from GitHub: ```bash npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \ - -a openclaw -y + --skill '*' -y +``` + +If direct GitHub access fails, clone the official Gitee mirror and install from +that checkout: + +```bash +git clone --depth 1 \ + https://gitee.com/deepmodeling/deepmd-kit.git \ + deepmd-kit-skill-source +npx -y skills add ./deepmd-kit-skill-source/skills --skill '*' -y ``` -The examples above require Node.js/npm so that `npx` is available, and they -install the skills for OpenClaw. Replace `openclaw` with the target agent name -when installing for another agent. The GitHub command lets the skill CLI fetch -the repository for you. For large repositories or slow networks, this can take -longer than installing from an existing local checkout. Refresh or restart the -session afterward so the installed skills are reloaded. +The examples require Node.js/npm so that `npx` is available. The Skills CLI +installs every official skill for the detected agent. To target one product, +add its agent name, for example `--agent cursor` or `--agent claude-code`. The +GitHub command lets the CLI fetch the repository; installing from an existing +checkout avoids that download. Refresh or restart the session afterward so the +installed skills are reloaded. ## Minimal verification @@ -80,3 +99,6 @@ without launching an expensive calculation. For example: water dataset and draft a training input, but do not start training.” - “Use the `lammps-deepmd` skill to prepare an NVT LAMMPS input file for a DeePMD-kit model, and explain each command.” +- “Use the `deepmd-install` skill to install the current stable release with + PyTorch and CUDA. Read the matching official documentation before choosing + packages, then verify a tensor operation on the GPU.” diff --git a/doc/index.rst b/doc/index.rst index 11d2c2e3dc..9de8ef30e5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -276,8 +276,8 @@ New and noteworthy :link-type: doc :shadow: sm - Give AI agents reproducible guidance for training, fine-tuning, - inference, and LAMMPS workflows. + Give AI agents reproducible guidance for installation, training, + fine-tuning, inference, and LAMMPS workflows. Documentation map ================= diff --git a/doc/install/easy-install.md b/doc/install/easy-install.md index 1eef898316..23d4e82327 100644 --- a/doc/install/easy-install.md +++ b/doc/install/easy-install.md @@ -2,6 +2,8 @@ There are various easy methods to install DeePMD-kit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections. +An AI agent can perform the same installation. See [Install with an AI agent](install-with-agent.md). + After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to train models or run LAMMPS in parallel. > [!NOTE] diff --git a/doc/install/index.rst b/doc/install/index.rst index 6491e6b787..32691b7e29 100644 --- a/doc/install/index.rst +++ b/doc/install/index.rst @@ -5,6 +5,7 @@ Installation :maxdepth: 1 easy-install + install-with-agent install-from-source install-from-c-library install-lammps diff --git a/doc/install/install-from-source.md b/doc/install/install-from-source.md index 8f4b933440..3d7aa75606 100644 --- a/doc/install/install-from-source.md +++ b/doc/install/install-from-source.md @@ -1,5 +1,8 @@ # Install from source code +An AI agent can walk through this source build, including the C++ interface +and LAMMPS with Kokkos. See [Install with an AI agent](install-with-agent.md). + Please follow our [GitHub](https://github.com/deepmodeling/deepmd-kit) webpage to download the source code of a specific version or the [development version](https://github.com/deepmodeling/deepmd-kit/tree/master). Or get the DeePMD-kit source code by `git clone` diff --git a/doc/install/install-lammps.md b/doc/install/install-lammps.md index d9fcbc4e7c..30828e614e 100644 --- a/doc/install/install-lammps.md +++ b/doc/install/install-lammps.md @@ -1,5 +1,9 @@ # Install LAMMPS +An AI agent can build LAMMPS with the DeePMD-kit module and Kokkos. DPA4/SeZM +uses `pair_style deepmd/kk`; DPA4C uses `pair_style dpa4spin/kk`. See +[Install with an AI agent](install-with-agent.md). + There are two ways to install LAMMPS: the built-in mode and the plugin mode. The built-in mode builds LAMMPS along with the DeePMD-kit and DeePMD-kit will be loaded automatically when running LAMMPS. The plugin mode builds LAMMPS and a plugin separately, so one needs to use `plugin load` command to load the DeePMD-kit's LAMMPS plugin library. ## Install LAMMPS's DeePMD-kit module (built-in mode) diff --git a/doc/install/install-with-agent.md b/doc/install/install-with-agent.md new file mode 100644 index 0000000000..f73fb6b49b --- /dev/null +++ b/doc/install/install-with-agent.md @@ -0,0 +1,62 @@ +# Install with an AI agent + +DeePMD-kit ships an official Agent Skill, `deepmd-install`, that walks an AI +agent through installing the package. The skill covers easy methods (conda, +pip, Docker, offline installers, `dp1s`) and source builds of the Python +package, the C++ interface, and LAMMPS. + +The skill inspects the target machine, asks only for decisions required by the +selected installation path, reads the official documentation matching the +requested version, and verifies the requested interface. Version-specific +package and build commands remain in the installation documentation instead +of being duplicated in the skill. + +The full skill catalog is in [Agent Skills](../agent-skills.md). For a +manual install, use [Easy install](easy-install.md) or +[Install from source](install-from-source.md). + +## If you are a user + +Send this page to your agent and ask it to install the official +`deepmd-install` skill, then install DeePMD-kit. You do not need to run the +commands below yourself. + +## If you are an agent + +Install `deepmd-install` first, then load it and install DeePMD-kit with the +required backend, accelerator, and optional native interfaces. + +If this machine already has a DeePMD-kit checkout, run from the repository +root: + +```bash +npx -y skills add ./skills --skill deepmd-install -y +``` + +If there is no checkout, install the same skill from GitHub: + +```bash +npx -y skills add https://github.com/deepmodeling/deepmd-kit/tree/master/skills \ + --skill deepmd-install -y +``` + +If direct GitHub access fails, clone the official Gitee mirror and install from +the local checkout: + +```bash +git clone --depth 1 \ + https://gitee.com/deepmodeling/deepmd-kit.git \ + deepmd-kit-skill-source +npx -y skills add ./deepmd-kit-skill-source/skills \ + --skill deepmd-install -y +``` + +The examples require Node.js/npm so that `npx` is available. The Skills CLI +uses the detected agent. To target one product, add `--agent cursor`, +`--agent claude-code`, or another supported agent name. Refresh or restart the +session afterward so the skill is reloaded. + +Then use the `deepmd-install` skill. The agent selects one installation method, +loads the version-matched official documentation, executes its commands in the +chosen environment, and verifies the requested Python, C/C++, or LAMMPS +interface. diff --git a/skills/deepmd-install/SKILL.md b/skills/deepmd-install/SKILL.md new file mode 100644 index 0000000000..89245bf0bc --- /dev/null +++ b/skills/deepmd-install/SKILL.md @@ -0,0 +1,243 @@ +--- +name: deepmd-install +description: Install DeePMD-kit with pip, conda, dp1s, an offline package, Docker, or source code. Use for PyTorch, TensorFlow, JAX, or Paddle on CPU, CUDA, or ROCm, and for backend-enabled or backend-neutral C/C++ interfaces and DeePMD-enabled LAMMPS. +--- + +# Install DeePMD-kit + +Use the official documentation as the source of version-specific commands. +This skill selects the shortest suitable installation path, applies a small +set of safety rules, and verifies the requested runtime. It does not duplicate +the full installation manual. + +## 1. Establish the target + +Determine only the choices that affect installation: + +- DeePMD-kit release or Git ref; +- PyTorch, TensorFlow, JAX, or Paddle backend, or a backend-neutral C/C++ + library; +- CPU, NVIDIA CUDA, or ROCm runtime; +- Python only, packaged LAMMPS, C/C++, or source-built LAMMPS; +- existing environment or a new user-approved environment. + +If the user does not request a development version, prefer the current stable +release. When no method is specified, recommend a source install if the +machine has the required compiler and the user accepts the build time; +otherwise choose the shortest supported package path. Do not create a new +environment when the user requires an existing one. Ask only for a missing +choice that changes the installation path. + +The backend-neutral choice applies only to the C/C++ interface and requires a +compatible backend plugin at runtime. It is not a Python installation target. + +Inspect the OS, architecture, Python version and prefix, package manager, and +requested accelerator before changing the machine. Resolve the selected +Python executable to an absolute path and use `"" -m pip`; +do not rely on a bare `pip` or shell activation persisting between commands. + +## 2. Read the matching documentation + +Assume no local DeePMD-kit checkout exists. Fetch the documentation before +rendering an install command: + +1. Use the agent's browser or web-fetch tool to open the direct official page, + not a search-result summary. + +1. For a release, open the Releases page, record its tag, and use the matching + versioned documentation. + +1. If the page is missing or no web-fetch tool is available, fetch the needed + Markdown file from that exact tag or commit: + + ```bash + curl -fsSL --retry 2 \ + "https://raw.githubusercontent.com/deepmodeling/deepmd-kit//doc/install/.md" + ``` + +1. If direct GitHub access fails, fetch the same path and exact ref from the + official Gitee mirror. Reject an HTTP failure, empty response, HTML error + page, or missing ref. + +Read [`references/official-docs.md`](references/official-docs.md) for the URL +map, version-selection rules, exact repository paths, and network fallback. +Use the docs matching the selected version, not `latest` for an older release. + +The commands below describe executable and argument boundaries; they are not +text-substitution templates. Pass dynamic values through an argument array +with shell evaluation disabled, such as a process API's `shell=False`, and +pass environment variables through a process environment map. If only a shell +string is available, escape each complete value with the target shell's +canonical quoting (`shlex.quote` for POSIX). Reject NUL, newline, and other +control characters; double quotes alone are not a safety boundary. Keep +option-looking inputs behind the documented option boundary. Apply any changed +requirements from the matching official page before execution. + +## 3. Choose one installation path + +### pip + +Use pip for a released Python package and optional packaged LAMMPS. Start from +the backend tab in the official easy-install page: + +| Backend | Minimal package shape | +| ---------- | ------------------------------------------------------------------------------------------ | +| PyTorch | Install the selected PyTorch build, then `deepmd-kit` or `deepmd-kit[torch]` as documented | +| TensorFlow | `deepmd-kit[cpu]` for CPU or the documented GPU/CUDA extras | +| JAX | `deepmd-kit[jax]`, plus the documented JAX accelerator package | +| Paddle | Install the documented Paddle package first, then `deepmd-kit` | + +Add `lmp` or `ipi` to the extras only when requested and supported by the +selected backend and platform. Normalize the selected release tag to its +package version, for example `v3.1.3` to `3.1.3`, and append an exact `==` +constraint to the DeePMD-kit requirement after any extras. Install through the +absolute target Python: + +```bash +"" -m pip install \ + "==" +``` + +### conda + +Use conda-forge for a released package when the user prefers conda: + +```bash +"" create -n "" \ + -c conda-forge "deepmd-kit==" +``` + +Normalize the selected release tag as for pip and use Conda's exact `==` +MatchSpec. Add `lammps` or distributed-training packages only when requested. +Follow the linked conda-forge CUDA guidance rather than inventing a toolkit +pin. After creation, resolve the environment's absolute Python before +verification. + +### dp1s + +Use the official one-second installer when the user selects it. Show the +remote script command and obtain confirmation before piping it to a shell: + +```bash +curl -fsSL https://dp1s.deepmodeling.com | bash +``` + +Read the dp1s repository for `DP1S_HOME`, version selection, release-candidate, +and PATH-update options. Resolve the installed `dp` entry point and its Python +prefix instead of assuming that `DP1S_HOME` is the Python environment. + +### Offline package + +Use the exact asset for the selected release, OS, architecture, and runtime +from the official GitHub Releases page. Follow the release instructions to +assemble split files, verify the published checksum when available, and run +the completed installer. Never execute a partial download, an HTML response, +or an asset selected only by a similar filename. + +### Docker + +Pull the exact official image tag selected from the package page. For current +official images, the DeePMD environment is under `/opt/deepmd-kit`; confirm the +selected image's absolute `sys.executable` and `sys.prefix` before using it. +The minimal CPU check is: + +```bash +docker pull "" +docker run --rm --entrypoint /opt/deepmd-kit/bin/python \ + "" -c \ + "import sys, deepmd; print(sys.executable, sys.prefix, deepmd.__version__)" +``` + +Use a different absolute interpreter only when the selected image definition +documents it. For packaged LAMMPS, run the binary inside the same container: + +```bash +docker run --rm --entrypoint /opt/deepmd-kit/bin/lmp \ + "" -h +``` + +A host-side `lmp` does not verify the image. Mount inputs read-only, and add +explicit GPU device selection for CUDA. + +### Source Python (recommended) + +Use source installation for a reproducible build from a selected stable tag, +an unreleased feature, a custom build, or ROCm. Reject a remote or ref beginning +with `-`, then clone and resolve the selected ref safely: + +```bash +git clone --no-checkout -- \ + https://github.com/deepmodeling/deepmd-kit.git "" +git -C "" fetch --tags -- origin "" +git -C "" checkout --detach FETCH_HEAD +git -C "" rev-parse HEAD +``` + +If GitHub is unavailable, use the official mirror at +`https://gitee.com/deepmodeling/deepmd-kit.git` and resolve the same validated +ref. Do not obtain installation instructions or source through an +unauthenticated proxy. + +Read `doc/install/install-from-source.md` at that exact commit, install the +selected backend first, and apply only the documented build variables. Render +the target-defining variables in the same invocation so build defaults cannot +select another runtime or backend: + +```bash +DP_VARIANT="" \ + DP_ENABLE_TENSORFLOW="<0|1>" \ + DP_ENABLE_PYTORCH="<0|1>" \ + "" -m pip install "" +``` + +Enable only the TensorFlow or PyTorch compiled support requested by the user. +For a Python-only JAX or Paddle installation, set both backend variables to +`0` unless the matching documentation requires compiled support. Add the +documented `CUDAToolkit_ROOT` or `ROCM_ROOT` to the same invocation when the +selected runtime requires an explicit toolkit root. + +Keep source, build, and install locations distinct. + +### Pre-compiled C library + +Use this route only when the official page provides an artifact for the +selected version, platform, and backend. Download and unpack it into a +dedicated prefix, then follow the same page for CMake discovery and optional +LAMMPS plugin use. Do not substitute a Python wheel or a C library from another +release. + +### C/C++ interface and LAMMPS + +For C/C++, choose the backend-enabled or backend-neutral section of the +matching source-install page; do not guess CMake options or backend library +roots. A backend-neutral build must set `ALLOW_NO_BACKEND=ON`, build only the +C/C++ libraries, and provide a compatible backend plugin at runtime. For +LAMMPS, use a packaged `lmp` when it satisfies the request. Otherwise follow +the matching built-in or plugin instructions after the C/C++ interface +succeeds. Enable Kokkos only when the requested LAMMPS runtime requires it, +and select the architecture supported by that exact LAMMPS/Kokkos source tree. + +## 4. Verify the requested interface + +An installation is complete only after the requested public interface runs: + +1. Print `sys.executable`, `sys.prefix`, `deepmd.__version__`, and + `deepmd.__file__` with the selected absolute Python. +1. For pip or conda, normalize the selected release tag and + `deepmd.__version__` with `packaging.version.Version(...).public`; fail if + they differ. For source, verify the resolved Git commit and installation + origin separately. +1. Import the selected backend (`deepmd.pt`, `deepmd.tf`, `deepmd.jax`, or + `deepmd.pd`) and run one minimal tensor operation on the requested device. +1. Run the installed `dp --version` and backend-specific help. +1. For C/C++, confirm the installed headers/libraries, then load a built + library or run a linked client so the platform loader resolves its dynamic + dependencies. +1. For LAMMPS, run the selected binary with `-h`, require the exact DeePMD pair + style needed by the model, and run a short documented example. +1. For Docker, perform all applicable checks inside the selected image. + +On failure, stop at the first failing check and read +[`references/failure-modes.md`](references/failure-modes.md). Report the +selected method, version or commit, environment identity, commands executed, +observed verification results, and anything that remains unverified. diff --git a/skills/deepmd-install/references/failure-modes.md b/skills/deepmd-install/references/failure-modes.md new file mode 100644 index 0000000000..bd081df8b2 --- /dev/null +++ b/skills/deepmd-install/references/failure-modes.md @@ -0,0 +1,153 @@ +# Installation failure modes + +Diagnose the first failing step. Keep its complete output, change one input at +a time, and rerun the smallest command that distinguishes the cause. Do not +restart the whole installation, erase caches, reset a source tree, or remove a +working environment without the user's approval. + +## Documentation or asset is unavailable + +Confirm the requested version or ref and the exact URL. Try the versioned docs, +then the same file at the exact GitHub ref as described in +[`official-docs.md`](official-docs.md). If GitHub is blocked, use the exact ref +and path on the official Gitee mirror. Do not silently substitute a newer +release, different CUDA build, or similarly named asset. + +For downloads, retain the HTTP status, file size, and content type. An HTML +error page is not an installer or archive. Reassemble split offline assets in +the documented order and verify a published checksum when one exists. + +## A rendered value changes the command + +Stop if a dynamic value is interpolated directly into shell source. Prefer an +argument array with shell evaluation disabled. To check a shell-string +renderer, print its resulting argument vector instead of executing the target +and test literal values such as `path with spaces`, `$(printf injected)`, +`` `printf injected` ``, `x;printf injected`, and `-n`. Each value must remain +one unchanged argument, and no nested command may execute. Reject NUL, newline, +and other control characters rather than trying to quote them. + +## Python, pip, and dp identify different environments + +Run these checks with the selected absolute interpreter: + +```bash +"" -c \ + "import sys; print(sys.executable); print(sys.prefix)" +"" -m pip --version +command -v dp +``` + +The Python prefix, pip location, `dp` entry point, and `deepmd.__file__` must +identify the intended environment. If an import resolves into a source tree, +repeat it from a neutral directory and check `PYTHONPATH`. Do not repair an +identity mismatch by installing the package again with a different `pip`. + +## Dependency resolution or backend import fails + +Read the first resolver conflict or import error. Compare the selected Python, +OS, architecture, DeePMD-kit version, backend package, and package index with +the matching documentation. Install only the requested backend; adding every +extra often creates conflicts and does not diagnose the missing dependency. + +For PyTorch, TensorFlow, JAX, and Paddle, verify the framework itself before +testing DeePMD-kit. A successful `import deepmd` does not prove that the +selected backend is installed. + +## CPU, CUDA, or ROCm is not available + +Separate three facts: the accelerator is visible to the host, the framework +was built for the requested runtime, and a tensor operation executes on that +device. Check device visibility variables and compare the framework runtime +with the driver/toolkit reported by the system. Do not replace packages until +the failing layer is identified. + +A source compiler toolkit and a framework wheel runtime are related but not +identical. Treat a major-version incompatibility as a hard failure; use the +official compatibility guidance for minor-version combinations. + +## Source ref or build identity is wrong + +Inspect without modifying the checkout: + +```bash +git -C "" status --short +git -C "" remote -v +git -C "" rev-parse HEAD +``` + +Use a separate clone when the remote, commit, or local changes do not match the +request. Never use `git reset --hard` or `git clean` on a user tree. Reject a +remote or ref beginning with `-`; option-like input must not reach `git fetch` +or `git checkout`. + +## A source build fails + +Preserve the first compiler or CMake error. Verify the absolute compiler, +Python, backend installation, toolkit root, and free disk/RAM. Re-read the +source-install page and build options at the exact commit. If CMake cached a +different compiler, source path, backend, or install prefix, create a new build +directory instead of layering more flags onto the stale cache. + +For PyTorch custom operations, confirm that the intended PyTorch is visible to +the build and that build isolation behavior matches the selected version's +documentation. For TensorFlow, JAX, or Paddle C/C++, use the documented library +interface and ABI for that backend; do not substitute a Python package root +unless the docs explicitly support it. + +## A native library cannot be loaded + +Use `ldd` on Linux or `otool -L` on macOS to identify dependencies of the +failing library or executable. These listings are diagnostic; `otool -L` does +not prove that dyld can resolve its install names. Require the platform loader +to load the built library or execute a linked client. A minimal dylib probe is: + +```bash +"" -c \ + 'import ctypes; ctypes.CDLL(".dylib")' +``` + +Treat any loader error or Linux `not found` entry as a failed gate. Locate the +named dependency in the selected environment before changing `RPATH`, +`LD_LIBRARY_PATH`, or linker flags. Framework import success does not prove +that a separately built C++ client or LAMMPS binary uses the same ABI and +libraries. + +## LAMMPS lacks the required DeePMD pair style + +Run the exact selected binary with `-h`. Distinguish packaged, built-in, and +plugin installations; for plugin mode, confirm that the plugin was loaded. +Require the pair style used by the target model rather than any occurrence of +the word `deepmd`. Kokkos styles require a Kokkos-enabled LAMMPS build and an +architecture supported by that LAMMPS source tree. + +If the style exists but rejects a model, diagnose model/runtime compatibility +separately from installation. Rebuild only after confirming that the binary, +DeePMD C/C++ libraries, backend, and model family are the intended combination. + +## Docker verification disagrees with the host + +Host executables do not verify a container. Run all checks inside the exact +image tag, record the container's absolute `sys.executable` and `sys.prefix`, +and invoke that interpreter directly. For packaged LAMMPS, run the in-container +binary. Mount verification inputs read-only and pass an explicit device with +Docker's GPU option when CUDA is requested. + +If the image contains multiple Python installations, do not fall back to a +bare `python`; inspect the image definition or documented environment prefix +and verify `deepmd.__file__` against it. + +## Permission, disk, or memory failure + +Do not switch silently to `sudo`, a shared system prefix, or a different disk. +Report the required permission or resource and use a user-approved dedicated +prefix. For compilation memory pressure, reduce parallel jobs and rerun the +same build so that compiler, backend, toolkit, and source commit remain fixed. + +## Reporting a blocked installation + +Report the selected method and version, the exact failing command, its first +actionable error, environment identity, and checks that passed. State what +additional user choice or external change is required. Do not report an +installation as successful when only package resolution or file creation +completed. diff --git a/skills/deepmd-install/references/official-docs.md b/skills/deepmd-install/references/official-docs.md new file mode 100644 index 0000000000..474a36d58a --- /dev/null +++ b/skills/deepmd-install/references/official-docs.md @@ -0,0 +1,117 @@ +# Official documentation routing + +Fetch documentation before choosing version-sensitive packages, image tags, +build variables, or LAMMPS options. This reference assumes there is no local +DeePMD-kit checkout. + +## Fetch procedure + +1. Use the agent's browser, URL reader, or web-fetch tool to open a direct URL + from this file. Read the page body and relevant tabs; a search snippet is + not documentation. + +1. Determine the target release tag or Git ref before selecting commands. For + a stable release, obtain the tag from the official Releases page. + +1. Open the versioned documentation. If it is missing or incomplete, retrieve + the corresponding raw Markdown from the exact tag or commit. + +1. If the agent has no web-fetch tool, use `curl` and keep the response in the + tool output: + + ```bash + curl -fsSL --retry 2 \ + "https://raw.githubusercontent.com/deepmodeling/deepmd-kit//doc/install/.md" + ``` + +1. If GitHub is unavailable, fetch the same exact ref and path from the + official Gitee mirror: + + ```bash + curl -fsSL --retry 2 \ + "https://gitee.com/deepmodeling/deepmd-kit/raw//doc/install/.md" + ``` + +1. Stop on a nonzero curl exit, empty response, HTML error page, or missing + ref. Do not generate commands from partial or unverified content. + +## Primary pages + +- Easy install: +- Source Python and C/C++: +- Pre-compiled C library: +- LAMMPS: +- Development packages: +- Releases: +- Container images: +- Official Gitee mirror: +- dp1s options: + +Use official backend installers when the DeePMD-kit page links to them: + +- PyTorch: +- TensorFlow: +- JAX: +- Paddle: + +## Match the target version + +The `latest` documentation follows the development branch and may not describe +an older release. For a release, first try the versioned documentation root: + +```text +https://docs.deepmodeling.com/projects/deepmd/en/v/ +``` + +If that build is unavailable or incomplete, fetch the relevant Markdown file +from the exact tag or commit in the official repository. Typical paths are: + +```text +doc/install/easy-install.md +doc/install/easy-install-dev.md +doc/install/install-from-source.md +doc/install/install-from-c-library.md +doc/install/install-lammps.md +pyproject.toml +``` + +For example, replace `` with a validated tag or commit in either form: + +```text +https://github.com/deepmodeling/deepmd-kit/blob//doc/install/install-from-source.md +https://raw.githubusercontent.com/deepmodeling/deepmd-kit//doc/install/install-from-source.md +https://gitee.com/deepmodeling/deepmd-kit/raw//doc/install/install-from-source.md +``` + +Resolve a branch or tag to a commit SHA before building. Treat a Git ref as +data: reject values beginning with `-`, quote it, and use Git's `--` option +boundary where supported. + +## When a page lacks the required detail + +Inspect authoritative files at the same ref instead of borrowing commands from +another version: + +1. `pyproject.toml` for Python requirements and extras; +1. `source/CMakeLists.txt` and included CMake modules for current build options; +1. `.github/workflows/` and `source/install/docker/Dockerfile` for maintained + package and image build examples; +1. the selected LAMMPS tree for available Kokkos architecture names. + +State clearly when a conclusion is inferred from maintained build +configuration rather than stated in the user documentation. Do not invent a +version, wheel index, image tag, CMake option, or Kokkos architecture. + +## Network fallback + +If GitHub is unreachable, use the official Gitee mirror for both source and +raw documentation: + +```text +https://gitee.com/deepmodeling/deepmd-kit.git +https://gitee.com/deepmodeling/deepmd-kit/raw//doc/install/install-from-source.md +``` + +Require the requested tag or commit to exist on the mirror. After cloning, +record the configured remote and resolved commit SHA before building; do not +silently substitute the mirror's default branch for a missing ref.