Require DFT k-spacing and license-gated VASP image discovery.

Enforce KSPACING/kspacing validation, Bohrium-safe VASP run commands, and private list_images resolution before setting vasp_image_name.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Zikkying

apex/skills/apex-flow/SKILL.md

@@ -59,7 +59,7 @@ Options to offer via AskQuestion:
   - LAMMPS + MLIP (DeePMD / DPA / MACE / NEP): fast, GPU-friendly
   - LAMMPS + classical (EAM / MEAM / SNAP): fast, CPU
   - ABACUS (DFT)
-  - VASP (DFT; license + image required)
+  - VASP (DFT; license-gated — resolve image via Bohrium `list_images` keyword=`vasp` or a user-known authorized address; otherwise stop)
    **Step B — only if Step A is LAMMPS + DeePMD/DPA: use the model bundled with this skill.**
   - Copy `models/DPA-3.2-5M/DPA-3.2-5M-OMat24.pth` into the job directory.
   - This is the frozen, single-task `OMat24` branch of DPA-3.2-5M. It is
@@ -179,6 +179,57 @@ Options to offer via AskQuestion:
    If the library is missing/incomplete: **STOP**, tell the user the path is
    unusable, and ask for the correct POTCAR location. Never submit with an
    absolute host POTCAR path hoping the container can see it.
+13. **MUST set DFT k-spacing; never rely on a hand-written KPOINTS/KPT file.**
+   APEX auto-generates the k-mesh from spacing; omitting it fails at make time.
+   - **VASP**: `INCAR` (or `cal_setting`) **must** contain `KSPACING`. Prefer also
+     setting `KGAMMA` (`True` = Gamma-centered, `False` = Monkhorst-Pack).
+     Do not hand-author per-task `KPOINTS`; APEX writes it from POSCAR + spacing.
+   - **ABACUS**: `INPUT` **must** contain `kspacing` (1/Bohr), **or** set
+     `cal_setting.K_POINTS` like `[nx, ny, nz, 0, 0, 0]`. APEX writes `KPT`.
+   - **Screening defaults** (APEX is screening-oriented, not publication-grade):
+     VASP `KSPACING=0.1–0.2` Å⁻¹; ABACUS `kspacing=0.20` (relax) / `0.15` (phonon SCF).
+     Smaller spacing → denser mesh and much higher cost (~8× from 0.20→0.10 on ABACUS).
+   - Confirm the spacing with the user before submit when they care about accuracy.
+     Details: `reference/calculators.md` → k-spacing sections.
+14. **STOP: Resolve VASP image via Bohrium `list_images` or a user-known authorized address — never invent a default.**
+   VASP is commercial. There is **no** default `vasp_image_name`. Before any
+   VASP `create` / submit, resolve an image by **exactly one** of these paths:
+   1. **Private image discovery (preferred):** query the user's own private
+      Bohrium Docker images filtered by keyword `vasp`:
+      - If the MatMaster / Bohrium tool is available:
+        `Bohrium(action="list_images", keyword="vasp")`
+        (tool description: *list the user's own private Docker images
+        (filtered by keyword)*).
+      - Otherwise run the skill helper (same OpenAPI):
+        ```bash
+        python <skill-root>/scripts/list_bohrium_images.py \
+          --keyword vasp --require
+        ```
+      Present matching image URL(s) to the user and get approval before use.
+   2. **User-known authorized address:** the user explicitly provides a
+      licensed/authorized VASP image path they are allowed to use.
+   **If neither path yields an image → TERMINATE the VASP workflow.** Do not
+   guess public tags (including `vasp:5.4.4-dflow`), do not submit, and tell
+   the user that a private VASP image or an authorized image address is
+   required. Only after a confirmed image exists, pass
+   `--vasp-image <url>` to `generate_config.py create` (writes
+   `vasp_image_name`).
+15. **MUST use a Bohrium-safe VASP `vasp_run_command` — never bare `vasp_std`.**
+   After a licensed VASP image is resolved (Rule 14), `global.json` should use a
+   command that sources Intel oneAPI, raises stack limit, and calls an absolute
+   binary. Typical Bohrium layout:
+   ```text
+   bash -c "source /opt/intel/oneapi/setvars.sh && ulimit -s unlimited && mpirun -n <N> /opt/vasp.5.4.4/bin/vasp_std"
+   ```
+   Constraints:
+   - Always `source /opt/intel/oneapi/setvars.sh` (Intel MPI / MKL env).
+   - Always `ulimit -s unlimited` (avoids stack overflow on large cells).
+   - Prefer absolute binary path (PATH `vasp_std` is unreliable); adjust path if
+     the user-approved image differs.
+   - Align `<N>` with `scass_type` CPU count (`c32_*` → `-n 32`, `c16_*` → `-n 16`).
+   - Do **not** use bare `mpirun -n 16 vasp_std`.
+   `generate_config.py` writes the run_command template for `--backend vasp`
+   and sets `vasp_image_name` only from `--vasp-image`.
 
 
 
@@ -306,13 +357,14 @@ Successfully validated workflow (ID: `cu-fcc-elastic-v3-joint-sdfml`):
 ## Scripts
 
 
-| Script                   | Purpose                                                                           |
-| ------------------------ | --------------------------------------------------------------------------------- |
-| `generate_config.py`     | `create` a complete job or `refresh-global` credentials without changing param.json |
-| `validate_apex_combo.py` | List / check / recommend safe image × scass_type combos                           |
-| `fetch_models.py`        | Optional: download the DPA-3.2-5M multi-head source `.pt` for freezing another head |
-| `parse_results.py`       | Parse APEX output into summary                                                    |
-| `validate_inputs.py`     | Validate configuration before submission                                          |
+| Script                     | Purpose                                                                           |
+| -------------------------- | --------------------------------------------------------------------------------- |
+| `generate_config.py`       | `create` a complete job or `refresh-global` credentials without changing param.json |
+| `list_bohrium_images.py`   | List private Bohrium images by keyword (MatMaster `list_images` equivalent)       |
+| `validate_apex_combo.py`   | List / check / recommend safe image × scass_type combos                           |
+| `fetch_models.py`          | Optional: download the DPA-3.2-5M multi-head source `.pt` for freezing another head |
+| `parse_results.py`         | Parse APEX output into summary                                                    |
+| `validate_inputs.py`       | Validate configuration before submission                                          |
 
 
 

apex/skills/apex-flow/data/default_templates.json

@@ -18,9 +18,9 @@
         },
         "vasp": {
             "image": null,
-            "machine": null,
-            "run_command": "mpirun -n 16 vasp_std",
-            "note": "User must provide image. VASP is commercial software."
+            "machine": "c32_m128_cpu",
+            "run_command": "bash -c \"source /opt/intel/oneapi/setvars.sh && ulimit -s unlimited && mpirun -n 32 /opt/vasp.5.4.4/bin/vasp_std\"",
+            "note": "Commercial software. Resolve image via Bohrium list_images(keyword=vasp) or a user-known authorized address; if neither exists, stop. Never invent a default image. Never use bare mpirun ... vasp_std."
         }
     },
     "properties": {

apex/skills/apex-flow/reference/calculators.md

@@ -370,10 +370,24 @@ kspacing        0.15
 | `smearing_method` | **mp** | gauss | Smearing type |
 | `force_thr_ev` | 0.03 | 0.02 | Force convergence (eV/Å) |
 | `stress_thr` | 1.0 | 0.5 | Stress convergence (GPa) |
-| `kspacing` | 0.20 | 0.20 | K-point spacing (1/Bohr) |
+| `kspacing` | **0.20 (required)** | **0.20 (required)** | K-point spacing (1/Bohr); APEX writes `KPT` from it |
 | `scf_nmax` | **200** | 100 | Max SCF iterations |
 | `relax_nmax` | **100** | 50 | Max relaxation steps |
 
+### ABACUS k-spacing constraints (REQUIRED)
+
+APEX does **not** accept a hand-written `KPT` as the primary control. At make time it requires either:
+1. `kspacing` in `INPUT` (float, unit **1/Bohr**), or
+2. `cal_setting.K_POINTS` as a 6-int list, e.g. `[6, 6, 6, 0, 0, 0]`.
+
+Missing both → `RuntimeError: K point information is not defined`.
+
+| Use case | Recommended `kspacing` | Notes |
+|----------|------------------------|-------|
+| Relaxation / screening | **0.20** | Default in skill templates |
+| Phonon / force SCF | **0.15** | Slightly denser |
+| Higher accuracy (user request) | 0.10 | ~8× cost vs 0.20 |
+
 > **kspacing 对比**: 0.20 → ~6×6×6 k-mesh (216 pts), 0.10 → ~12×12×12 (1728 pts). 计算量差 **8 倍**。
 
 ### ABACUS global.json Settings (Bohrium/dflow)
@@ -445,9 +459,25 @@ When `interaction.type` is `abacus` or `vasp`, the skill auto-applies smaller su
 
 | File | Description | User Responsibility |
 |------|-------------|-------------------|
-| INCAR | VASP input parameters | Provided or generated |
+| INCAR | VASP input parameters | Provided or generated; **must include `KSPACING`** |
 | POTCAR | Pseudopotentials | **User must provide** (license-restricted) |
-| KPOINTS | K-mesh | Auto-generated by APEX or provided |
+| KPOINTS | K-mesh | **Auto-generated by APEX** from `KSPACING` (+ `KGAMMA`); do not hand-author |
+
+### VASP k-spacing constraints (REQUIRED)
+
+APEX **requires** `KSPACING` in `INCAR` (or `cal_setting.kspacing`). At make time it:
+1. Reads `KSPACING` / `KGAMMA` from INCAR
+2. Builds a Monkhorst/Gamma mesh from the POSCAR reciprocal lattice
+3. Writes per-task `KPOINTS`
+
+Missing `KSPACING` → `RuntimeError: KSPACING must be given in INCAR`.
+
+| Tag | Required? | Default / recommendation | Notes |
+|-----|-----------|--------------------------|-------|
+| `KSPACING` | **Yes** | `0.1`–`0.2` (Å⁻¹) for screening | Smaller → denser mesh, higher cost |
+| `KGAMMA` | Strongly recommended | `True` (Gamma) or `False` (MP) | Controls mesh centering |
+
+Do **not** ship a static `KPOINTS` file expecting APEX to use it as the primary control — spacing drives generation. For `elastic`, APEX regenerates one shared `KPOINTS` from the undeformed cell and symlinks it into every deformation task.
 
 ### INCAR Example (Relaxation)
 
@@ -463,26 +493,54 @@ ISIF = 3
 ISMEAR = 1
 SIGMA = 0.1
 LREAL = Auto
+KSPACING = 0.15
+KGAMMA = True
 ```
 
-### VASP global.json Settings
+### VASP global.json Settings (Bohrium / dflow)
+
+> ⚠️ **Never** use bare `mpirun -n 16 vasp_std`. The Bohrium VASP image needs Intel oneAPI env + absolute binary path.
 
 ```json
 {
-    "machine": {
-        "batch_type": "Shell",
-        "context_type": "LazyLocalContext",
-        "local_root": "."
-    },
-    "resources": {
-        "number_node": 1,
-        "cpu_per_node": 16,
-        "group_size": 1
-    },
-    "run_command": "mpirun -n 16 vasp_std"
+    "dflow_host": "https://workflows.deepmodeling.com",
+    "k8s_api_server": "https://workflows.deepmodeling.com",
+    "batch_type": "Bohrium",
+    "context_type": "Bohrium",
+    "vasp_image_name": "<USER-PROVIDED licensed VASP image — never invent a default>",
+    "vasp_run_command": "bash -c \"source /opt/intel/oneapi/setvars.sh && ulimit -s unlimited && mpirun -n 32 /opt/vasp.5.4.4/bin/vasp_std\"",
+    "scass_type": "c32_m128_cpu",
+    "group_size": 1,
+    "pool_size": 1
 }
 ```
 
+> ⚠️ **Do not auto-fill `vasp_image_name`.** VASP is commercial. Resolve the image
+> first via Bohrium private-image listing or a user-known authorized address:
+>
+> ```text
+> # Preferred when MatMaster Bohrium tool is available:
+> Bohrium(action="list_images", keyword="vasp")
+>
+> # Skill helper (same OpenAPI /openapi/v2/image/private):
+> python scripts/list_bohrium_images.py --keyword vasp --require
+> ```
+>
+> Then pass the approved URL to `generate_config.py create --vasp-image <url>`.
+> If `list_images` returns nothing **and** the user does not know an authorized
+> image address → **terminate** the VASP workflow (do not invent a public tag).
+
+`vasp_run_command` constraints (typical Bohrium VASP layout; adjust binary path if the user image differs):
+
+| Piece | Why |
+|-------|-----|
+| `source /opt/intel/oneapi/setvars.sh` | Loads Intel MPI / MKL |
+| `ulimit -s unlimited` | Avoids stack overflow on large cells |
+| Absolute `vasp_std` path | PATH `vasp_std` is unreliable |
+| `mpirun -n <N>` | `<N>` must match `scass_type` CPUs (`c32_*`→32, `c16_*`→16) |
+
+Local/debug Shell jobs may use a simpler command only when the host already has VASP + MPI on PATH; for Bohrium use the template above. `generate_config.py` emits the run_command template for `--backend vasp` but leaves `vasp_image_name` unset.
+
 ### VASP POTCAR Handling
 
 APEX concatenates files at:

apex/skills/apex-flow/reference/examples.md

@@ -321,9 +321,10 @@ apex rss rss.json
 
 **Scenario**: Phonon band structure for Si using VASP.
 
-> ⚠️ Requires user to provide VASP image. Stage POTCARs into the job root
+> ⚠️ Confirm VASP license/image with the user. Stage POTCARs into the job root
 > (`POTCAR_Si` + `"potcar_prefix": "."`); do not leave absolute host paths
-> like `/share/PAW_PBE`.
+> like `/share/PAW_PBE`. INCAR **must** include `KSPACING`. Use the Bohrium
+> `vasp_run_command` template (never bare `mpirun ... vasp_std`).
 
 ### param.json
 ```json
@@ -363,6 +364,25 @@ NSW = 0
 ISMEAR = 0
 SIGMA = 0.05
 LREAL = .FALSE.
+KSPACING = 0.15
+KGAMMA = True
+```
+
+### Resolve VASP image first
+```bash
+# MatMaster: Bohrium(action="list_images", keyword="vasp")
+python <skill-root>/scripts/list_bohrium_images.py --keyword vasp --require
+# If empty and user has no authorized address → stop.
+# Else create with --vasp-image <approved-url>
+```
+
+### global.json (VASP keys)
+```json
+{
+    "vasp_image_name": "<from list_images or user-known authorized address>",
+    "vasp_run_command": "bash -c \"source /opt/intel/oneapi/setvars.sh && ulimit -s unlimited && mpirun -n 32 /opt/vasp.5.4.4/bin/vasp_std\"",
+    "scass_type": "c32_m128_cpu"
+}
 ```
 
 ---

apex/skills/apex-flow/reference/submission.md

@@ -120,7 +120,7 @@ dflow validates workflow names against RFC 1123 subdomain regex. Names like `"Cu
 | **Outer job (submission client)** | `registry.dp.tech/dptech/dp/native/prod-397637/apex-flow:1.3.0.post` | Lightweight; just runs `apex submit` |
 | **LAMMPS calculator** | `registry.dp.tech/dptech/dp/native/prod-397637/deepmd-kit-phonolammps:3.1.3` | Default; includes phonoLAMMPS |
 | **ABACUS calculator** | (same APEX image has ABACUS) | Or user-specified |
-| **VASP calculator** | User must provide | Commercial; confirm with user |
+| **VASP calculator** | User must provide after confirming license | Commercial; **never invent a default image** |
 
 > ⚠️ **Do NOT combine `deepmd-kit:3.1.1` with any NVIDIA T4 machine**. It also has a known segfault bug when handling triclinic cells (non-orthogonal boxes), including on CPU. Use `3.1.3` or later.
 
@@ -131,7 +131,36 @@ dflow validates workflow names against RFC 1123 subdomain regex. Names like `"Cu
 | LAMMPS (DeePMD/MACE/NEP) | `c8_m31_1 * NVIDIA T4` | GPU beneficial |
 | LAMMPS (EAM/MEAM/SNAP) | `c16_m32_cpu` | CPU sufficient |
 | ABACUS | `c16_m32_cpu` | CPU |
-| VASP | User specifies | User's license |
+| VASP | `c32_m128_cpu` (default) | Align `mpirun -n <N>` with CPU count |
+
+### VASP image resolution + `vasp_run_command` (license-gated)
+
+**Image resolution (mandatory before VASP submit):**
+
+1. Query the user's **private** Bohrium images with keyword `vasp`:
+   - MatMaster tool: `Bohrium(action="list_images", keyword="vasp")`
+     (*list the user's own private Docker images (filtered by keyword)*)
+   - Or skill helper: `python scripts/list_bohrium_images.py --keyword vasp --require`
+2. Else use a **user-known authorized** VASP image address.
+3. If neither exists → **stop**. Do not invent `vasp:5.4.4-dflow` or any default.
+4. Pass the approved image as `--vasp-image` to `generate_config.py create`.
+
+**Run command:** do **not** use bare `mpirun -n 16 vasp_std`. Typical
+Bohrium-safe command (adjust binary path to the user-approved image):
+
+```text
+bash -c "source /opt/intel/oneapi/setvars.sh && ulimit -s unlimited && mpirun -n 32 /opt/vasp.5.4.4/bin/vasp_std"
+```
+
+Must include: Intel `setvars.sh`, `ulimit -s unlimited`, absolute `vasp_std`,
+and `-n` matching `scass_type`. See `reference/calculators.md` and Critical
+Rules in `SKILL.md`.
+
+### DFT k-spacing (REQUIRED)
+
+- VASP: `INCAR` must set `KSPACING` (APEX auto-writes `KPOINTS`).
+- ABACUS: `INPUT` must set `kspacing`, or `cal_setting.K_POINTS`.
+- `validate_inputs.py` rejects missing spacing / bare VASP run commands.
 
 > **IMPORTANT**: Use the minimal `c1_m2_cpu` machine for the outer Bohrium job since it only submits to dflow and waits. The heavy compute is in the inner containers specified by `scass_type` in `global.json`.