docs: regenerate INPUT parameter docs in RTD build

.github/instructions/abacus-governance.instructions.md

@@ -23,8 +23,9 @@ Apply these instructions when reviewing or changing ABACUS code:
 - Require LF line endings for text files. `.bat` and `.cmd` files are the CRLF
   exceptions.
 - For INPUT parameter behavior changes, require synchronized updates to
-  `docs/parameters.yaml` and `docs/advanced/input_files/input-main.md`, or a
-  clear no-update explanation in the PR.
+  `docs/advanced/input_files/input-main.md`, or a clear no-update explanation
+  in the PR. The parameter YAML stream is generated transiently and is not stored
+  in the repository.
 - Check that new source files are linked through the relevant `CMakeLists.txt`
   unless the PR explains generated or indirect inclusion.
 - Keep default C++ changes compatible with the repository C++11 baseline.

.github/workflows/test.yml

@@ -89,24 +89,17 @@ jobs:
           ABACUS_BIN=$(find build -name "abacus_*" -type f -executable | head -1)
           echo "Using binary: ${ABACUS_BIN}"
 
-          # Check 1: parameters.yaml matches C++ Input_Item definitions
+          # Generate transient parameter metadata from C++ Input_Item definitions
           ${ABACUS_BIN} --generate-parameters-yaml > /tmp/parameters_generated.yaml
-          if ! diff -q docs/parameters.yaml /tmp/parameters_generated.yaml; then
-            echo "error: docs/parameters.yaml is out of sync with C++ source"
-            echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml > docs/parameters.yaml"
-            diff docs/parameters.yaml /tmp/parameters_generated.yaml || true
-            exit 1
-          fi
-          echo "  parameters.yaml: OK"
 
-          # Check 2: input-main.md matches regenerated markdown
+          # Check: input-main.md matches regenerated markdown
           pip install -q pyyaml
           python docs/generate_input_main.py \
             /tmp/parameters_generated.yaml \
             --output /tmp/input-main-generated.md
           if ! diff -q docs/advanced/input_files/input-main.md /tmp/input-main-generated.md; then
             echo "error: input-main.md is out of sync"
-            echo "Fix: python docs/generate_input_main.py docs/parameters.yaml"
+            echo "Fix: ${ABACUS_BIN} --generate-parameters-yaml | python docs/generate_input_main.py - --output docs/advanced/input_files/input-main.md"
             diff docs/advanced/input_files/input-main.md /tmp/input-main-generated.md || true
             exit 1
           fi

.readthedocs.yaml

@@ -9,6 +9,39 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - build-essential
+    - cmake
+    - gfortran
+    - git
+    - libfftw3-dev
+    - liblapack-dev
+    - libopenblas-dev
+    - ninja-build
+    - pkg-config
+  jobs:
+    pre_build:
+      - >
+        cmake -S . -B build-rtd-docs -G Ninja
+        -DCMAKE_BUILD_TYPE=Release
+        -DENABLE_MPI=OFF
+        -DENABLE_LCAO=OFF
+        -DUSE_OPENMP=OFF
+        -DUSE_ELPA=OFF
+        -DUSE_CUDA=OFF
+        -DUSE_ROCM=OFF
+        -DBUILD_TESTING=OFF
+        -DENABLE_LIBXC=OFF
+        -DENABLE_LIBRI=OFF
+        -DENABLE_DFTD4=OFF
+        -DENABLE_RAPIDJSON=OFF
+        -DENABLE_MLALGO=OFF
+        -DENABLE_FLOAT_FFTW=OFF
+        -DENABLE_CNPY=OFF
+        -DCOMMIT_INFO=OFF
+        -DGIT_SUBMODULE=OFF
+        -DMKLROOT=OFF
+      - cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

AGENTS.md

@@ -26,9 +26,10 @@ rules. Read the complete governance document before making or reviewing changes:
 - Use LF line endings for text files. Only `.bat` and `.cmd` files may use CRLF.
 - Keep source file additions deterministic: update the relevant `CMakeLists.txt`
   or explain why the file is generated or included indirectly.
-- INPUT parameter behavior changes must update `docs/parameters.yaml` and
+- INPUT parameter behavior changes must update
   `docs/advanced/input_files/input-main.md`, or the PR must state why no update
-  is required.
+  is required. The parameter YAML stream is generated transiently by the ABACUS
+  binary and is not stored in the repository.
 - Report the exact verification performed. Do not claim completion without
   fresh test or check output.
 
@@ -37,8 +38,7 @@ rules. Read the complete governance document before making or reviewing changes:
 - Core C++ implementation lives under `source/`; source additions must be wired
   through the relevant `CMakeLists.txt`.
 - INPUT parsing and help metadata live under `source/source_io/`; user-facing
-  INPUT docs live in `docs/parameters.yaml` and
-  `docs/advanced/input_files/input-main.md`.
+  INPUT docs live in `docs/advanced/input_files/input-main.md`.
 - Unit tests are colocated under module `test/` directories such as
   `source/source_md/test/`; integration and workflow tests are selected through
   CTest labels and patterns.

docs/CONTRIBUTING.md

@@ -174,37 +174,35 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac
 
 ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). Parameter metadata is defined inline in the C++ source files (`source/source_io/module_parameter/read_input_item_*.cpp`) using `Input_Item` registrations.
 
-A checked-in file `docs/parameters.yaml` contains a YAML dump of all parameter metadata, generated from the binary itself. This file is used by Sphinx to produce the online documentation page `input-main.md`.
+A checked-in file `docs/advanced/input_files/input-main.md` contains the generated INPUT parameter reference. Sphinx refreshes this file from an ABACUS executable when the executable is available.
 
-### When to Update `docs/parameters.yaml`
+### When to Update `input-main.md`
 
-You **must** regenerate `docs/parameters.yaml` whenever you:
+You **must** regenerate `docs/advanced/input_files/input-main.md` whenever you:
 
 - Add a new INPUT parameter
 - Remove an existing INPUT parameter
 - Change a parameter's description, type, default value, unit, category, or availability
 
 ### How to Regenerate
 
-After building and installing ABACUS, run:
+After building ABACUS, run:
 
 ```bash
-abacus --generate-parameters-yaml > docs/parameters.yaml
+abacus --generate-parameters-yaml \
+  | python3 docs/generate_input_main.py - \
+      --output docs/advanced/input_files/input-main.md
 ```
 
-Then verify the YAML is valid:
+You can also let Sphinx refresh the page during a documentation build:
 
 ```bash
-python3 -c "import yaml; d=yaml.safe_load(open('docs/parameters.yaml')); print(len(d['parameters']), 'parameters')"
+ABACUS_BINARY=/path/to/abacus sphinx-build -b html docs build-docs/html
 ```
 
-You can also regenerate the markdown documentation locally:
+If no ABACUS executable is available, Sphinx emits a warning and continues with the checked-in `input-main.md`, which may not be up to date.
 
-```bash
-python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md
-```
-
-**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes and the `input-main.md` is updated.
+**Important:** Include the updated `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the generated documentation matches the C++ source changes.
 
 ### Parameter Documentation Format
 

docs/README.md

@@ -0,0 +1,110 @@
+# ABACUS Documentation
+
+These files are the source for the ABACUS manual published on Read the Docs.
+
+Read the Docs builds a minimal serial ABACUS binary, regenerates
+`docs/advanced/input_files/input-main.md` from that binary during the
+documentation build, and fails the build if the INPUT reference cannot be
+refreshed.
+
+## Build the Manual Locally
+
+Run the following commands from the repository root.
+
+1. Create a Python virtual environment with `uv`:
+
+   ```bash
+   uv venv --python python3 .venv
+   ```
+
+1. Install the documentation requirements:
+
+   ```bash
+   uv pip install --python .venv/bin/python -r docs/requirements.txt sphinx ninja
+   ```
+
+1. Build the reduced ABACUS executable used for INPUT parameter metadata:
+
+   ```bash
+   cmake -S . -B build-rtd-docs -G Ninja \
+     -DCMAKE_BUILD_TYPE=Release \
+     -DENABLE_MPI=OFF \
+     -DENABLE_LCAO=OFF \
+     -DUSE_OPENMP=OFF \
+     -DUSE_ELPA=OFF \
+     -DUSE_CUDA=OFF \
+     -DUSE_ROCM=OFF \
+     -DBUILD_TESTING=OFF \
+     -DENABLE_LIBXC=OFF \
+     -DENABLE_LIBRI=OFF \
+     -DENABLE_DFTD4=OFF \
+     -DENABLE_RAPIDJSON=OFF \
+     -DENABLE_MLALGO=OFF \
+     -DENABLE_FLOAT_FFTW=OFF \
+     -DENABLE_CNPY=OFF \
+     -DCOMMIT_INFO=OFF \
+     -DGIT_SUBMODULE=OFF \
+     -DMKLROOT=OFF
+   cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2
+   ```
+
+1. Build the HTML manual:
+
+   ```bash
+   ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser \
+     .venv/bin/sphinx-build -b html docs build-docs/html
+   ```
+
+   If `ABACUS_BINARY` is not set, `docs/conf.py` looks for the Read the Docs
+   build binary and then for `abacus` or `abacus_pw_ser` on `PATH`.
+
+1. Open `build-docs/html/index.html` in a browser.
+
+For local builds, if no ABACUS executable is available, the Sphinx build still
+continues with the checked-in `docs/advanced/input_files/input-main.md` and
+prints a warning that the INPUT parameter reference may not be up to date.
+
+## Regenerate Only the INPUT Reference
+
+To refresh only the generated INPUT reference after building ABACUS:
+
+```bash
+./build-rtd-docs/source/abacus_pw_ser --generate-parameters-yaml \
+  | .venv/bin/python docs/generate_input_main.py - \
+      --output docs/advanced/input_files/input-main.md
+```
+
+## INPUT Parameter Reference
+
+The INPUT parameter reference is generated from metadata registered in
+`source/source_io/module_parameter/read_input_item_*.cpp`.
+
+- `abacus --generate-parameters-yaml` produces a transient YAML stream; it is
+  not stored in the repository.
+- `docs/advanced/input_files/input-main.md` is generated from that metadata.
+- `docs/conf.py` refreshes `input-main.md` automatically when it can find an
+  ABACUS executable.
+
+Keep `docs/advanced/input_files/input-main.md` in PRs that change INPUT
+metadata. The YAML dump is intentionally transient so there is only one
+generated reference file to maintain.
+
+## Optional Read the Docs Container Test
+
+To smoke-test the Read the Docs environment locally, use the same image as the
+hosted build:
+
+```bash
+docker run --rm -v "$PWD:/project" -w /project \
+  readthedocs/build:ubuntu-22.04-2024.01.29 \
+  /bin/bash -lc 'python -m pip install -r docs/requirements.txt sphinx ninja &&
+  cmake -S . -B build-rtd-docs -G Ninja -DCMAKE_BUILD_TYPE=Release \
+    -DENABLE_MPI=OFF -DENABLE_LCAO=OFF -DUSE_OPENMP=OFF -DUSE_ELPA=OFF \
+    -DUSE_CUDA=OFF -DUSE_ROCM=OFF -DBUILD_TESTING=OFF \
+    -DENABLE_LIBXC=OFF -DENABLE_LIBRI=OFF -DENABLE_DFTD4=OFF \
+    -DENABLE_RAPIDJSON=OFF -DENABLE_MLALGO=OFF -DENABLE_FLOAT_FFTW=OFF \
+    -DENABLE_CNPY=OFF -DCOMMIT_INFO=OFF -DGIT_SUBMODULE=OFF -DMKLROOT=OFF &&
+  cmake --build build-rtd-docs --target abacus_pw_ser --parallel 2 &&
+  export ABACUS_BINARY=./build-rtd-docs/source/abacus_pw_ser &&
+  sphinx-build -b html docs /tmp/abacus-docs-html'
+```

docs/advanced/input_files/input-main.md

@@ -1,6 +1,6 @@
 # Full List of INPUT Keywords
 
-<!-- This file is auto-generated from parameters.yaml -->
+<!-- This file is auto-generated from ABACUS INPUT parameter metadata -->
 <!-- Do not edit manually - changes will be overwritten -->
 
 <!-- Table of Contents -->
@@ -336,6 +336,12 @@
     - [rpa\_ccp\_rmesh\_times](#rpa_ccp_rmesh_times)
     - [exx\_symmetry\_realspace](#exx_symmetry_realspace)
     - [out\_ri\_cv](#out_ri_cv)
+    - [out\_unshrinked\_v](#out_unshrinked_v)
+    - [exx\_coul\_moment](#exx_coul_moment)
+    - [exx\_rotate\_abfs](#exx_rotate_abfs)
+    - [exx\_multip\_moments\_threshold](#exx_multip_moments_threshold)
+    - [shrink\_abfs\_pca\_thr](#shrink_abfs_pca_thr)
+    - [shrink\_lu\_inv\_thr](#shrink_lu_inv_thr)
   - [Exact Exchange (PW)](#exact-exchange-pw)
     - [exxace](#exxace)
     - [exx\_gamma\_extrapolation](#exx_gamma_extrapolation)
@@ -1170,7 +1176,7 @@
   ``text genelpa can not be used with plane wave basis. ``
 
   Then the user has to correct the input file and restart the calculation.
-- **Default**: 
+- **Default**:
     - PW basis: cg.
     - LCAO basis:
         - genelpa (if compiling option `USE_ELPA` has been set)
@@ -2247,23 +2253,23 @@
 
 - **Type**: Boolean
 - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)*
-- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. This feature does not work for gamma-only calculations.
+- **Description**: Whether to print Hamiltonian matrices H(R) in npz format. The output files are named output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY.
 - **Default**: False
 - **Unit**: Ry
 
 ### out_hsr_npz
 
 - **Type**: Boolean
 - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)*
-- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. This feature does not work for gamma-only calculations.
+- **Description**: Whether to print Hamiltonian matrices H(R) and overlap matrix S(R) in npz format. The output files are named output_SR.npz, output_HR0.npz, output_HR1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY.
 - **Default**: False
 - **Unit**: Ry
 
 ### out_dm_npz
 
 - **Type**: Boolean
 - **Availability**: *Numerical atomic orbital basis (not gamma-only algorithm)*
-- **Description**: Whether to print density matrices DM(R) in npz format. This feature does not work for gamma-only calculations.
+- **Description**: Whether to print density matrices DM(R) in npz format. The output files are named output_DM0.npz, output_DM1.npz, and so on according to spin channel. This feature requires ABACUS to be built with CNPY.
 - **Default**: False
 
 ### out_mul
@@ -3295,6 +3301,42 @@
 - **Description**: Whether to output the coefficient tensor C(R) and ABFs-representation Coulomb matrix V(R) for each atom pair and cell in real space.
 - **Default**: false
 
+### out_unshrinked_v
+
+- **Type**: Boolean
+- **Description**: Whether to output the large Vq matrix in the unshrinked auxiliary basis.
+- **Default**: false
+
+### exx_coul_moment
+
+- **Type**: Boolean
+- **Description**: Whether to use the moment method for Coulomb calculation.
+- **Default**: false
+
+### exx_rotate_abfs
+
+- **Type**: Boolean
+- **Description**: Whether to rotate the auxiliary basis for Coulomb calculation.
+- **Default**: false
+
+### exx_multip_moments_threshold
+
+- **Type**: Real
+- **Description**: Threshold to screen multipole moments in Coulomb calculation.
+- **Default**: 1e-10
+
+### shrink_abfs_pca_thr
+
+- **Type**: Real
+- **Description**: Threshold to shrink the auxiliary basis for GW/RPA calculations.
+- **Default**: -1
+
+### shrink_lu_inv_thr
+
+- **Type**: Real
+- **Description**: Threshold for obtaining the inverse of the overlap matrix by LU decomposition in the auxiliary-basis representation.
+- **Default**: 1e-6
+
 [back to top](#full-list-of-input-keywords)
 
 ## Exact Exchange (PW)
@@ -3377,6 +3419,7 @@
   - berendsen: Berendsen thermostat, see md_nraise in detail.
   - rescaling: velocity Rescaling method 1, see md_tolerance in detail.
   - rescale_v: velocity Rescaling method 2, see md_nraise in detail.
+  - csvr: Canonical Sampling through Velocity Rescaling, see md_csvr_tau in detail.
 - **Default**: nhc
 
 ### md_tfirst