From 67e4044793bc6a1a4fa1d48008392a8800b17ada Mon Sep 17 00:00:00 2001
From: Ionizing <PeterSmith_9@outlook.com>
Date: Wed, 8 May 2024 21:06:48 +0800
Subject: [PATCH] [docs] update `wav3d` docs

---
 docs/src/Wavefunction3D.md | 151 +++++++++++++++++++++----------------
 1 file changed, 85 insertions(+), 66 deletions(-)

diff --git a/docs/src/Wavefunction3D.md b/docs/src/Wavefunction3D.md
index ae2c8a7..a6aa79b 100644
--- a/docs/src/Wavefunction3D.md
+++ b/docs/src/Wavefunction3D.md
@@ -8,74 +8,93 @@ Main functions of `rsgrad wav3d`
 
 ```shell
 $ rsgrad wav3d --help
-rsgrad-wav3d
 Plot wavefunction in realspace, and save it as '.vasp' file
 
-USAGE:
-    rsgrad wav3d [OPTIONS]
-
-OPTIONS:
-    -b, --ibands <IBANDS>...
-            Select band index, starting from 1
-
-    -d, --detail
-            Show the eigen values and band occupations of current WAVECAR.
-
-            This flag should be used with `--list`
-
-    -e, --show-eigs-suffix
-            Add eigen value suffix to the filename
-
-        --gamma-half <GAMMA_HALF>
-            Gamma Half direction of WAVECAR. You need to set this to 'x' or 'z' when processing
-            WAVECAR produced by `vasp_gam`
-
-            [possible values: x, z]
-
-    -h, --help
-            Print help information
-
-    -k, --ikpoints <IKPOINTS>...
-            Select kpoint index, starting from 1
-
-            [default: 1]
-
-    -l, --list
-            List the brief info of current WAVECAR
-
-    -o, --output-parts <OUTPUT_PARTS>...
-            Specify output part of the wavefunction.
-
-            Detailed message:
-             - normsquared/ns: Perform `ρ(r) = |ѱ(r)|^2` action to get the spatial distribution of
-            selected band.
-             - real/re: Real part of the wavefunction, suffix '_re.vasp' is added to the output
-            filename.
-             - imag/im: Imaginary part of the wavefunction, suffix '_im.vasp' is added to the output
-            filename.
-             - reim: Output both real part and imaginary parts of the wavefunction.
-
-            [possible values: normsquared, ns, real, re, imag, im, reim]
-
-    -p, --poscar <POSCAR>
-            POSCAR filename, POSCAR is needed to get the real-space wavefunction
-
-            [default: ./POSCAR]
-
-        --prefix <PREFIX>
-            Prefix of output filename
-
-            [default: wav]
-
-    -s, --ispins <ISPINS>...
-            Select spin index, starting from 1
-
-            [default: 1]
-
-    -w, --wavecar <WAVECAR>
-            WAVECAR file name
-
-            [default: ./WAVECAR]
+Usage: rsgrad wav3d [OPTIONS]
+
+Options:
+  -w, --wavecar <WAVECAR>
+          WAVECAR file name
+          
+          [default: ./WAVECAR]
+
+  -p, --poscar <POSCAR>
+          POSCAR filename, POSCAR is needed to get the real-space wavefunction
+          
+          [default: ./POSCAR]
+
+  -s, --ispins [<ISPINS>...]
+          Select spin index, starting from 1
+          
+          [default: 1]
+
+  -k, --ikpoints [<IKPOINTS>...]
+          Select kpoint index, starting from 1.
+          
+          You can input ranges directly: `-k 1..4 5..10`
+          
+          [default: 1]
+
+  -b, --ibands [<IBANDS>...]
+          Select band index, starting from 1.
+          
+          You can input ranges directly: `-b 1..4 5..10`
+
+  -l, --list
+          List the brief info of current WAVECAR
+
+  -d, --detail
+          Show the eigen values and band occupations of current WAVECAR.
+          
+          This flag should be used with `--list`
+
+      --gamma-half <GAMMA_HALF>
+          Gamma Half direction of WAVECAR. You need to set this to 'x' or 'z' when processing WAVECAR produced by `vasp_gam`
+          
+          [possible values: x, z]
+
+      --ngrid <NGRID> <NGRID> <NGRID>
+          Grid size for realspace wavefunction, 3 numbers are required, i.e. NGXF NGYF and NGZF.
+          
+          If this argument is left empty, NG_F will be set as NG_F=2*NG_.
+          
+          Be aware that NG_F must be greater than or at least equal to corresponding NG_.
+
+  -o, --output-parts [<OUTPUT_PARTS>...]
+          Specify output part of the wavefunction.
+          
+          Detailed message:
+           - normsquared/ns: Perform `ρ(r) = |ѱ(r)|^2` action to get the spatial distribution of selected band.
+           - real/re: Real part of the wavefunction, suffix '_re.vasp' is added to the output filename.
+           - imag/im: Imaginary part of the wavefunction, suffix '_im.vasp' is added to the output filename.
+           - reim: Output both real part and imaginary parts of the wavefunction.
+           - uns/dns: Perform `ρ(r) = |ѱ(r)|^2` for spinor up/down only. **Note: this option works for `ncl` WAVECAR only.**
+          
+          [possible values: normsquared, ns, uns, dns, real, re, imag, im, reim]
+
+      --prefix <PREFIX>
+          Prefix of output filename
+          
+          [default: wav]
+
+  -e, --show-eigs-suffix
+          Add eigen value suffix to the filename
+
+      --sum-chgs
+          Perform sum-up of the charge densities for selected bands.
+          
+          With this flag open, only `normsquared` or `ns` or `uns` or `dns` are allowed for the `-o`/`--output-parts` option.
+           IMPORTANT NOTES:
+           - The prefix for output filename `sum-prefix` is also required and has no default prefix.
+           - The individual charge densities will not be saved to corresponding '.vasp' files if this flag is on.
+
+      --sum-prefix <SUM_PREFIX>
+          Specify the output file for the summed charge densities.
+          
+          This argument is required if `sum_chgs` is on.
+
+  -h, --help
+          Print help (see a summary with '-h')
 ```
 
 ## Example