feat: add built-in help system with fuzzy search for INPUT parameters (Useful Information for adding new input parameters and explanations)

docs/CONTRIBUTING.md

@@ -10,6 +10,7 @@ For more non-technical aspects, please refer to the [ABACUS Contribution Guide](
 - [Structure of the package](#structure-of-the-package)
 - [Submitting an Issue](#submitting-an-issue)
 - [Comment style for documentation](#comment-style-for-documentation)
+- [Documenting INPUT parameters](#documenting-input-parameters)
 - [Code formatting style](#code-formatting-style)
 - [Generating code coverage report](#generating-code-coverage-report)
 - [Adding a unit test](#adding-a-unit-test)
@@ -156,6 +157,97 @@ An practical example is class [LCAO_Deepks](https://github.com/deepmodeling/abac
     \f}
     ```
 
+## Documenting INPUT Parameters
+
+ABACUS includes a built-in help system that allows users to query INPUT parameters directly from the command line (e.g., `abacus -h ecutwfc`). This help system is automatically generated from the parameter documentation in `docs/advanced/input_files/input-main.md` using the script `tools/generate_help_data.py`.
+
+### Parameter Documentation Format
+
+When adding or modifying INPUT parameters, follow this markdown format in `docs/advanced/input_files/input-main.md`:
+
+#### 1. Category Headers (Optional)
+
+Group related parameters under category headers:
+
+```markdown
+## Category Name
+```
+
+Example: `## System Variables`, `## Electronic Structure`
+
+#### 2. Parameter Headers (Required)
+
+Each parameter must have a level-3 header:
+
+```markdown
+### parameter_name
+```
+
+For multiple related parameters that share the same documentation:
+
+```markdown
+### param1, param2, param3
+```
+
+Example: `### nx, ny, nz` (will create three separate parameter entries)
+
+**Note:** Parameter names should be valid identifiers (alphanumeric characters and underscores only).
+
+#### 3. Parameter Fields
+
+Each parameter must include these fields using the bullet point format:
+
+- **Type**: (Required) One of: `Integer`, `Real`, `String`, `Boolean`
+- **Description**: (Required) Detailed description of what the parameter does
+  - Descriptions can span multiple lines
+  - Can include sub-bullets for additional details
+  - Markdown formatting (bold, italic, links, code) is supported and will be stripped in help output
+- **Default**: (Optional but recommended) The default value
+- **Unit**: (Optional) Physical unit if applicable (e.g., "Ry", "Angstrom", "fs")
+- **Availability**: (Optional) Conditions when this parameter is available (e.g., "Only used for LCAO basis")
+- **Note**: (Optional) Additional notes (these are ignored by the help system parser)
+
+#### 4. Example
+
+```markdown
+## Plane Wave Related Variables
+
+### ecutwfc
+
+- **Type**: Real
+- **Description**: Energy cutoff for plane wave functions. Higher values increase accuracy but also computational cost.
+- **Default**: 50 for PW basis, 100 for LCAO basis
+- **Unit**: Ry
+
+### nx, ny, nz
+
+- **Type**: Integer
+- **Description**: FFT grid dimensions in x, y, z directions. If set to 0, values are calculated automatically from ecutrho.
+- **Default**: 0
+```
+
+### Regenerating Help Data
+
+After modifying the parameter documentation, regenerate the C++ help data file:
+
+```bash
+python3 tools/generate_help_data.py \
+    docs/advanced/input_files/input-main.md \
+    source/source_io/input_help_data.h
+```
+
+This will parse the markdown and generate a C++ header file with static parameter data used by the help system.
+
+### Format Validation
+
+The generation script will:
+- Warn about parameters missing required fields (Type, Description)
+- Detect suspicious multi-parameter names (containing spaces or parentheses)
+- Check for duplicate parameter names
+- Report the number of parameters parsed by category
+
+If you see warnings during generation, please fix them before submitting your PR.
+
 ## Code formatting style
 
 We use `clang-format` as our code formatter. The `.clang-format` file in root directory describes the rules to conform with.

docs/quick_start/input.md

@@ -46,7 +46,56 @@ In the above example, the meanings of the parameters are:
 
 For a complete list of input parameters, please consult this [instruction](../advanced/input_files/input-main.md).
 
-> **Note:** Users cannot change the filename “INPUT” to other names. Boolean paramerters such as `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is also available, which means turn off the checkpoint of charge density in binary (always dumped in `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the output also support a second option to control the output precision, e.g., `out_chg 1 8` will output the charge density on realspace grid with 8 digits after the decimal point.
+> **Note:** Users cannot change the filename "INPUT" to other names. Boolean paramerters such as `out_chg` can be set by using `True` and `False`, `1` and `0`, or `T` and `F`. It is case insensitive so that other preferences such as `true` and `false`, `TRUE` and `FALSE`, and `t` and `f` for setting boolean values are also supported. Specifically for the `out_chg`, `-1` option is also available, which means turn off the checkpoint of charge density in binary (always dumped in `OUT.{suffix}`, whose name ends with `CHARGE-DENSITY.restart`). Some parameters controlling the output also support a second option to control the output precision, e.g., `out_chg 1 8` will output the charge density on realspace grid with 8 digits after the decimal point.
+
+## Getting Help with Parameters
+
+ABACUS includes a built-in help system to look up INPUT parameters directly from the command line.
+
+### Basic Commands
+
+```bash
+# Show general help and common parameters
+abacus -h
+
+# Search for parameters by keyword
+abacus -s ecut
+# Finds: ecutwfc, ecutrho, lcao_ecut, etc.
+
+# Get detailed help for a specific parameter
+abacus -h ecutwfc
+```
+
+### Example Output
+
+```
+$ abacus -h ecutwfc
+
+Parameter: ecutwfc
+Type:      Real
+Default:   50 for PW basis, 100 for LCAO basis
+Category:  Plane wave related variables
+Unit:      Ry
+
+Description:
+  Energy cutoff for plane wave functions...
+```
+
+### Fuzzy Matching
+
+If you mistype a parameter name, ABACUS suggests similar parameters:
+
+```bash
+$ abacus -h exx_hybrid_steps
+Error: Unknown parameter 'exx_hybrid_steps'
+
+Did you mean one of these?
+  - exx_hybrid_step
+
+Use 'abacus -s <keyword>' to search for parameters.
+```
+
+Parameter lookups are case-insensitive, so `ECUTWFC`, `Ecutwfc`, and `ecutwfc` all work.
 
 ## *STRU*
 

source/source_io/CMakeLists.txt

@@ -1,3 +1,23 @@
+# Find Python3 for generating help data
+find_package(Python3 COMPONENTS Interpreter REQUIRED)
+
+# Generate input parameter help data from documentation
+set(GENERATED_HELP_HEADER "${CMAKE_CURRENT_BINARY_DIR}/input_help_data.h")
+add_custom_command(
+    OUTPUT ${GENERATED_HELP_HEADER}
+    COMMAND ${Python3_EXECUTABLE}
+            ${CMAKE_SOURCE_DIR}/tools/generate_help_data.py
+            ${CMAKE_SOURCE_DIR}/docs/advanced/input_files/input-main.md
+            ${GENERATED_HELP_HEADER}
+    DEPENDS ${CMAKE_SOURCE_DIR}/docs/advanced/input_files/input-main.md
+            ${CMAKE_SOURCE_DIR}/tools/generate_help_data.py
+    COMMENT "Generating INPUT parameter help data from documentation..."
+    VERBATIM
+)
+
+# Create custom target for help data generation
+add_custom_target(generate_help_data DEPENDS ${GENERATED_HELP_HEADER})
+
 list(APPEND objects
     module_parameter/input_conv.cpp
     module_ctrl/ctrl_output_fp.cpp
@@ -39,6 +59,7 @@ list(APPEND objects
     module_output/output_log.cpp
     para_json.cpp
     parse_args.cpp
+    input_help.cpp
     orb_io.cpp
     module_output/filename.cpp
 )
@@ -117,6 +138,9 @@ add_library(
     ${objects}
 )
 
+# Make sure help data is generated before compiling io_basic
+add_dependencies(io_basic generate_help_data)
+
 target_include_directories(
     io_basic
     PUBLIC