Merge pull request #22 from QG-phy/refactor

Modernize repository: UV migration, Jupyter Book docs, CI/CD workflows

Author: floatingCatty

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install UV
+      run: pip install uv
+
+    - name: Install dependencies
+      run: |
+        uv sync --group dev
+
+    - name: Build documentation
+      run: |
+        cd docs
+        uv run jupyter book build .
+
+    - name: Deploy to GitHub Pages
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html
+        force_orphan: true

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # For setuptools-scm versioning
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install UV
+      run: pip install uv
+
+    - name: Install dependencies
+      run: |
+        uv sync --group dev
+
+    - name: Run tests
+      run: |
+        uv run pytest -v -m "not integration" --cov=dftio --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false

.gitignore

@@ -69,6 +69,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+_build/
 
 # PyBuilder
 .pybuilder/
@@ -100,6 +101,12 @@ ipython_config.py
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 #poetry.lock
 
+# uv
+.python-version
+
+# Version file auto-generated by setuptools-scm
+dftio/_version.py
+
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
 #pdm.lock

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.

README.md

@@ -1,15 +1,51 @@
 # dftio
+
+[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://deepmodeling.github.io/dftio/)
+[![Tests](https://github.com/deepmodeling/dftio/workflows/Tests/badge.svg)](https://github.com/deepmodeling/dftio/actions/workflows/test.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10-blue)](https://www.python.org/downloads/)
+
+
 dftio is to assist machine learning communities in transcribing and manipulating DFT output into a format that is easy to read or used by machine learning models. 
 
 dftio uses multiprocessing to paralleling the processing, and provide a standard dataset class that reads the processed dataset directly.
 
 ## Installation
-The user can install dftio once located in the root directory, and run:
+
+### Using the install script (Recommended)
+
+The easiest way to install dftio is using the provided installation script:
+
 ```bash
-pip install .
+# CPU version (default)
+./install.sh
+
+# Or for GPU with CUDA 12.1
+./install.sh cu121
 ```
-The dependent packages will be installed accordingly.
-However, the user can always manage the dependency themselves, here are the packages that dftio requires:
+
+### Manual installation with UV
+
+If you prefer manual installation:
+
+```bash
+# Install UV if you haven't already
+pip install uv
+
+# Install dftio (CPU version)
+uv sync
+
+# Or for GPU version
+uv sync --find-links https://data.pyg.org/whl/torch-2.5.0+cu121.html
+```
+
+### Using pip (from PyPI - coming soon)
+
+```bash
+pip install dftio
+```
+
+**Note**: dftio depends on `torch-scatter` which requires special handling. The install script automatically manages this for you.
 
 ## Supports
 

dftio/op/grid_int.py

@@ -34,7 +34,8 @@ def __init__(self, atomic_numbers, pbc, cell, coordinates, grids, atomic_basis,
     def integrate(self, weights=None):
 
         ngrid = len(self.grids)
-        results = torch.zeros(ngrid, dtype=weights.dtype)
+        dtype = weights.dtype if weights is not None else self.dtype
+        results = torch.zeros(ngrid, dtype=dtype)
         norbs = [self.atomic_basis[atomic_numbers_r[int(i)]].irreps.dim for i in self.atomic_numbers]
         cnorbs = torch.cumsum(torch.tensor([0]+norbs), dim=0)[:-1]
         for element in self.atomic_basis:

docs/_config.yml

@@ -0,0 +1,44 @@
+# Jupyter Book Configuration
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: dftio Documentation
+author: dftio Team
+copyright: "2025"
+logo: ""
+
+# Force re-execution of notebooks on each build
+execute:
+  execute_notebooks: auto
+  timeout: 600
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: dftio.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/deepmodeling/dftio
+  path_to_book: docs
+  branch: main
+
+# Add GitHub buttons to your book
+html:
+  use_issues_button: true
+  use_repository_button: true
+  use_edit_page_button: true
+
+# Sphinx configuration
+sphinx:
+  extra_extensions:
+    - sphinx.ext.autodoc
+    - sphinx.ext.napoleon
+    - sphinx.ext.viewcode
+    - sphinx_autodoc_typehints
+  config:
+    html_theme: sphinx_book_theme
+    autodoc_typehints: description

docs/_toc.yml

@@ -0,0 +1,22 @@
+# Table of Contents for dftio Documentation
+
+format: jb-book
+root: index
+chapters:
+  - file: installation
+  - file: user-guide/index
+    sections:
+      - file: user-guide/quickstart
+      - 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

@@ -0,0 +1,11 @@
+# API Reference
+
+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.
+
+The API is organized into several key 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.
+
+- **[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.