Enhance documentation for dftio

- Updated contributing guide with clearer instructions on development setup, code style, and testing requirements.
- Revised developer guide to provide detailed steps for adding new DFT software support, including parser implementation and registration.
- Improved index and installation documentation for better clarity on installation methods and prerequisites.
- Added a new tutorial for plotting band structures from VASP calculations, including step-by-step commands.
- Expanded CLI reference with detailed command usage for parsing and band plotting.
- Documented output data formats, including `dat`, `ase`, and `lmdb`, with examples of their structure.
- Provided a comprehensive guide on parsing outputs from various DFT packages, including ABACUS, VASP, SIESTA, Gaussian, and RESCU.
- Created a new section summarizing supported DFT packages and the specific data types each parser can handle.

Author: QG-phy

GEMINI.md

@@ -0,0 +1,79 @@
+# GEMINI.md: AI-Assisted Development Guide for `dftio`
+
+This document provides context and instructions for an AI assistant to effectively contribute to the `dftio` project.
+
+## Project Overview
+
+`dftio` is a Python library designed to parse and process output files from various Density Functional Theory (DFT) software packages. Its primary goal is to convert complex DFT outputs into standardized, machine-learning-ready formats. The library supports packages such as ABACUS, VASP, SIESTA, Gaussian, RESCU, and PYATB.
+
+The project provides a command-line interface (CLI) for parsing operations and for plotting derived data like electronic band structures.
+
+**Key Technologies:**
+- **Language:** Python 3.9+
+- **Core Libraries:** NumPy, SciPy, PyTorch, ASE (Atomic Simulation Environment), sisl
+- **Package Management:** `uv`
+- **Testing:** `pytest`
+
+## Building and Running
+
+### Installation
+
+The project uses `uv` for dependency management. To set up a development environment, including testing dependencies, run:
+
+```bash
+# Install all dependencies, including development tools
+uv sync --group dev
+```
+This command installs packages defined in `pyproject.toml`.
+
+### Running the CLI
+
+The main entry point is the `dftio` command. It has several subcommands, with `parse` being the most central one.
+
+**Example for parsing ABACUS output:**
+```bash
+dftio parse --mode abacus --root /path/to/abacus/output --hamiltonian --overlap -o /path/to/save
+```
+
+For a full list of commands and options, use the help flag:
+```bash
+dftio --help
+dftio parse --help
+```
+
+### Running Tests
+
+The project uses `pytest` for testing. The standard test suite can be run with the following command, which excludes slower "integration" tests:
+
+```bash
+uv run pytest -v -m "not integration"
+```
+
+To run the full suite including code coverage analysis (as done in CI):
+```bash
+uv run pytest -v -m "not integration" --cov=dftio
+```
+
+## Development Conventions
+
+### Project Structure
+
+- **`dftio/`**: Main source code for the library.
+    - **`io/`**: Contains the parsing logic for different DFT packages. Each package (e.g., `abacus`, `siesta`) has its own submodule.
+    - **`data/`**: Data structures for handling atomic configurations and computational results.
+    - **`__main__.py`**: Defines the CLI entry point and its arguments.
+- **`test/`**: Contains all `pytest` tests. The structure mirrors the main `dftio/` directory.
+- **`docs/`**: Project documentation, built with Jupyter Book.
+- **`pyproject.toml`**: Defines project metadata, dependencies, and tool configurations (including `pytest`).
+
+### Coding Style
+
+Follow the existing coding style in the file you are editing. While no specific linter is enforced in the project configuration, adhere to standard PEP 8 conventions.
+
+### Adding a New Parser
+
+To add support for a new DFT package, you would typically:
+1. Create a new module under `dftio/io/`, e.g., `dftio/io/new_package/`.
+2. Implement a parser class within that module.
+3. Register the new parser in `dftio/io/parse.py`'s `ParserRegister` to make it available via the CLI.
+4. Add corresponding tests in the `test/` directory to validate the parser's correctness.

docs/_toc.yml

@@ -10,7 +10,13 @@ chapters:
       - file: user-guide/parsing
       - file: user-guide/data-formats
       - file: user-guide/cli-reference
+      - file: user-guide/supported_packages
   - file: tutorials/index
+    sections:
+      - file: tutorials/plot_bands
   - file: api/index
+    sections:
+      - file: api/io
+      - file: api/data
   - file: developer-guide
   - file: contributing

docs/api/data.md

@@ -0,0 +1,53 @@
+# Data Structures (`dftio.data`)
+
+The `dftio.data` module provides the fundamental data structures for storing and managing atomic information and computational results. These structures are designed to be flexible, efficient, and compatible with machine learning workflows.
+
+## `AtomicData`
+
+The `dftio.data.AtomicData` class is the primary container for data associated with a single atomic structure. It is a dictionary-like object that stores properties of the system, such as atomic numbers, positions, and cell parameters, as PyTorch tensors.
+
+### Key Features
+
+- **Tensor-Based:** All data is stored as `torch.Tensor` objects, enabling seamless integration with PyTorch and other machine learning libraries.
+- **Extensible:** You can add any custom data to an `AtomicData` object, allowing for flexible and detailed representations of your system.
+- **Property-Based Access:** Accessing a key on an `AtomicData` object (e.g., `data['positions']`) returns the corresponding tensor.
+
+### Core Properties
+
+The following are some of the standard keys defined in `dftio.data._keys`:
+
+- `cell`: The lattice vectors of the simulation cell.
+- `positions`: The coordinates of each atom.
+- `atomic_numbers`: The atomic number of each atom.
+- `pbc` (Periodic Boundary Conditions): A boolean tensor indicating which directions are periodic.
+- `eigs`: The eigenvalues of the electronic structure.
+- `kpoints`: The coordinates of the k-points.
+
+## `AtomicDataDict`
+
+The `dftio.data.AtomicDataDict` class is a specialized dictionary designed to hold multiple `AtomicData` objects. It is the primary data structure returned by the parsers when processing multiple frames or structures.
+
+### Key Features
+
+- **Batching:** Provides methods for collating multiple `AtomicData` objects into a single batch for efficient processing.
+- **Transformation Support:** Can be used with the `dftio.data.transforms` module to apply transformations to all `AtomicData` objects in the dictionary.
+- **Serialization:** Can be saved to and loaded from disk, typically in `.dat` files (PyTorch's serialization format).
+
+## Example Usage
+
+```python
+import torch
+from dftio.data import AtomicData
+
+# Create an AtomicData object for a simple system
+data = AtomicData(
+    positions=torch.tensor([[0.0, 0.0, 0.0], [0.5, 0.5, 0.5]]),
+    atomic_numbers=torch.tensor([14, 14]),  # Silicon
+    cell=torch.eye(3) * 5.43,
+    pbc=torch.tensor([True, True, True]),
+)
+
+# Access properties
+print(data.positions)
+print(data.cell)
+```

docs/api/index.md

@@ -1,12 +1,11 @@
 # API Reference
 
-API documentation for dftio modules.
+This section provides detailed, auto-generated documentation for the `dftio` Python API. Use this reference to understand the internal components, data structures, and parser implementations.
 
-(To be auto-generated from docstrings using Sphinx autodoc)
+The API is organized into several key modules:
 
-## Main Modules
+- **[I/O and Parsers (`dftio.io`)](./io.md):** The core parsing engine, including the abstract base parser and specific implementations for each supported DFT code.
 
-- `dftio.io` - DFT parsers
-- `dftio.data` - Dataset classes
-- `dftio.datastruct` - Data structures
-- `dftio.op` - Operations and utilities
+- **[Data Structures (`dftio.data`)](./data.md):** The internal data containers used to store and manage atomic structures and calculation results.
+
+For details on how to use these components, please refer to the pages linked above.

docs/api/io.md

@@ -0,0 +1,57 @@
+# I/O and Parsers (`dftio.io`)
+
+The `dftio.io` module is the core of the library's parsing capabilities. It contains the `ParserRegister` class, which manages the registration and selection of parsers for different DFT codes, as well as the implementations of the parsers themselves.
+
+## `ParserRegister`
+
+The `ParserRegister` class is a singleton that holds a registry of all available parsers. When you run `dftio parse` from the command line, this class is responsible for selecting the appropriate parser based on the `--mode` argument.
+
+### Key Methods
+
+- **`register(name, parser_cls)`:** Adds a new parser to the registry.
+- **`get_parser(name)`:** Retrieves a parser class from the registry by name.
+
+## Available Parsers
+
+`dftio` supports the following DFT codes. Each parser is implemented in its own submodule within `dftio.io`.
+
+- **ABACUS (`abacus`):** Parses output from the ABACUS DFT code. See `dftio.io.abacus.abacus_parser`.
+- **Gaussian (`gaussian`):** Parses output from the Gaussian quantum chemistry software. See `dftio.io.gaussian.gaussian_parser`.
+- **PYATB (`pyatb`):** Parses output from the PYATB library. See `dftio.io.pyatb.pyatb_parser`.
+- **RESCU (`rescu`):** Parses output from the RESCU DFT code. See `dftio.io.rescu.rescu_parser`.
+- **SIESTA (`siesta`):** Parses output from the SIESTA DFT code. See `dftio.io.siesta.siesta_parser`.
+- **VASP (`vasp`):** Parses output from the Vienna Ab initio Simulation Package (VASP). See `dftio.io.vasp.vasp_parser`.
+
+Below is a more detailed breakdown of each parser's functionality.
+
+### ABACUS Parser
+
+The ABACUS parser (`dftio.io.abacus.AbacusParser`) is designed to handle the output files generated by the ABACUS software.
+
+**Key Responsibilities:**
+
+- Parses atomic structures (`STRU` files).
+- Extracts Hamiltonian and overlap matrices from sparse matrix files (`data-HR-sparse_SPIN0.csr`, `data-SR-sparse_SPIN0.csr`).
+- Reads band structure data from `BANDS_1.dat`.
+- Extracts other information from the main log file (`running_scf.log`).
+
+### Gaussian Parser
+
+The Gaussian parser (`dftio.io.gaussian.GaussianParser`) processes `.log` files from Gaussian calculations.
+
+**Key Responsibilities:**
+
+- Extracts atomic structures and coordinates.
+- Parses basis set information.
+- Reads molecular orbital energies (eigenvalues).
+
+### VASP Parser
+
+The VASP parser (`dftio.io.vasp.VaspParser`) is responsible for parsing the various output files from VASP.
+
+**Key Responsibilities:**
+
+- Reads atomic positions from `POSCAR` or `CONTCAR`.
+- Parses eigenvalues from `EIGENVAL`.
+- Extracts k-points and weights from `KPOINTS`.
+- Gathers additional information from `OUTCAR`, such as lattice parameters and forces.

docs/contributing.md

@@ -1,46 +1,72 @@
 # Contributing to dftio
 
-Thank you for your interest in contributing to dftio!
+Thank you for your interest in contributing to dftio! We welcome contributions of all kinds, from bug fixes to new features.
 
 ## Development Setup
 
-1. Clone the repository:
-```bash
-git clone https://github.com/deepmodeling/dftio.git
-cd dftio
-```
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/deepmodeling/dftio.git
+    cd dftio
+    ```
 
-2. Install with development dependencies:
-```bash
-./install.sh  # or specify GPU version
-uv sync --group dev
-```
+2.  **Install dependencies:**
+    This project uses `uv` for package management. To install all required dependencies, including those for development and testing, run:
+    ```bash
+    uv sync --group dev
+    ```
 
-3. Run tests:
-```bash
-uv run pytest
-```
+3.  **Run tests:**
+    To make sure everything is set up correctly, run the test suite:
+    ```bash
+    uv run pytest -m "not integration"
+    ```
 
 ## Code Style
 
-- Follow PEP 8 guidelines
-- Use meaningful variable and function names
-- Add docstrings to all public functions and classes
+-   Follow PEP 8 guidelines for Python code.
+-   Use clear and meaningful names for variables, functions, and classes.
+-   Add docstrings to all public functions and classes, explaining their purpose, arguments, and return values.
 
 ## Testing
 
-- Write tests for new features
-- Ensure all tests pass before submitting PR
-- Use pytest markers for integration tests
+-   All new features and bug fixes should be accompanied by tests.
+-   Ensure that the full test suite passes before submitting a pull request.
+-   Use `pytest` markers (e.g., `@pytest.mark.integration`) for tests that are slow or require external resources.
 
 ## Pull Request Process
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run tests
-5. Submit a pull request
+1.  Fork the repository on GitHub.
+2.  Create a new feature branch from the `main` branch.
+3.  Make your changes in the new branch.
+4.  Add or update tests as needed.
+5.  Run the tests to ensure everything passes.
+6.  Submit a pull request to the `main` branch of the original repository.
 
-## Adding Support for New DFT Software
+## Implementing a New Parser
 
-See the [Developer Guide](developer-guide.md) for details on implementing parsers for new DFT packages.
+If you are adding support for a new DFT package, please see the [Developer Guide](developer-guide.md) for a general overview. When implementing the parser class, you will need to provide several key methods. Below are the details of what each method should return.
+
+### `get_structure(idx)`
+
+This method should return a dictionary containing the atomic structure for the `idx`-th calculation. The dictionary should have the following keys (defined in `dftio.data._keys`):
+
+-   `_keys.ATOMIC_NUMBERS_KEY`: Atomic numbers as a 1D tensor (`[natom]`).
+-   `_keys.PBC_KEY`: Periodic boundary conditions as a boolean tensor (`[3]`).
+-   `_keys.POSITIONS_KEY`: Atomic positions in Ångströms (`[nframe, natom, 3]`).
+-   `_keys.CELL_KEY`: Lattice vectors in Ångströms (`[nframe, 3, 3]`).
+
+### `get_eigenvalues(idx)`
+
+This method should return a dictionary containing the eigenvalues and k-points:
+
+-   `_keys.KPOINT_KEY`: K-point coordinates (`[nk, 3]`).
+-   `_keys.ENERGY_EIGENVALUE_KEY`: Eigenvalues (`[nframe, nk, nband]`).
+
+### `get_basis(idx)`
+
+This method should return a dictionary describing the basis set, for example: `{"Si": "2s2p1d"}`.
+
+### `get_blocks(idx, ...)`
+
+This method should parse the real-space Hamiltonian, overlap, and/or density matrices. It should return a tuple of three lists: `(hamiltonians, overlaps, density_matrices)`. Each list should contain one dictionary per frame, where each dictionary's keys are strings like `"i_j_Rx_Ry_Rz"` (representing the matrix element between orbital `i` and orbital `j` in a neighboring cell at `(Rx, Ry, Rz)`) and the values are the corresponding matrix blocks as NumPy arrays.