deploy: c9d128f

Author: QG-phy

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 3a88eb33a9143260534ed02dfb7830fc
+tags: 645f666f9bcd5a90fca523b33c5a78b7

.nojekyll

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Yinzhanghao Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

_downloads/3b423627fe21976c3c06e60f78e14ae1/LICENSE

@@ -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)
+```

_sources/api/data.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.

_sources/api/index.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.

_sources/api/io.md

@@ -0,0 +1,72 @@
+# 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
+    ```
+
+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:**
+    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 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
+
+-   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 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.
+
+## Implementing a New Parser
+
+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.

_sources/contributing.md

@@ -0,0 +1,63 @@
+# Developer Guide
+
+This guide is for developers who want to contribute to `dftio` by adding support for a new Density Functional Theory (DFT) software package.
+
+## Project Structure
+
+The core logic of `dftio` is organized into several key modules:
+
+- **`dftio.data`**: Contains the fundamental data structures, such as `AtomicData` and `AtomicDataDict`, which are used to store and manage atomic information in a standardized format compatible with machine learning workflows.
+
+- **`dftio.datastruct`**: Defines data structures for physical quantities like Hamiltonian matrices, overlap matrices, and fields.
+
+- **`dftio.io`**: This is the I/O module, containing the interfaces to all supported DFT packages. Each package has its own submodule (e.g., `dftio.io.abacus`).
+
+## How to Add a New Parser
+
+Adding support for a new DFT code involves creating a new parser class and registering it with `dftio`. Here is a step-by-step guide:
+
+### 1. Create a New Parser Module
+
+Create a new directory under `dftio/io/` for your DFT package. For example, if you are adding a parser for a package named "NEWCODE," you would create the directory `dftio/io/newcode/`.
+
+Inside this directory, create a Python file for your parser, e.g., `dftio/io/newcode/newcode_parser.py`.
+
+### 2. Implement the Parser Class
+
+In your new parser file, you will need to create a parser class that inherits from a base class (if one is available) or implements the necessary parsing methods. The key methods your parser will need to provide are:
+
+- **`get_structure(idx)`**: This method should read the atomic structure information (atomic numbers, positions, cell, etc.) for a given calculation index (`idx`). It should return a dictionary of this data.
+
+- **`get_eigenvalue(idx)`**: This method should parse the eigenvalues and k-points from the DFT output files.
+
+- **`get_basis(idx)`**: This method should return information about the basis set used in the calculation.
+
+- **`get_blocks(idx, hamiltonian, overlap, density_matrix)`**: This method is responsible for parsing the Hamiltonian, overlap, and/or density matrices.
+
+### 3. Register Your Parser
+
+To make your new parser available through the CLI and the `ParserRegister`, you need to add it to the registry in `dftio/io/parse.py`. Import your new parser class and add it to the `ParserRegister`.
+
+```python
+# In dftio/io/parse.py
+from dftio.io.newcode.newcode_parser import NewCodeParser
+
+# ...
+
+ParserRegister.register("newcode", NewCodeParser)
+```
+
+### 4. Add a Test Case
+
+To ensure your parser works correctly and to prevent future regressions, you should add a new test file in the `test/` directory. You will need to include example output files from your DFT code in the `test/data/` directory.
+
+## Supported DFT Software
+
+`dftio` currently has parsers for the following DFT packages:
+
+- ABACUS
+- Gaussian
+- PYATB
+- RESCU
+- SIESTA
+- VASP

_sources/developer-guide.md

@@ -0,0 +1,20 @@
+# Welcome to 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 a Python library designed to assist the machine learning community by transcribing and manipulating output from Density Functional Theory (DFT) calculations into formats that are easy to read and use with machine learning models.
+
+It leverages multiprocessing to parallelize data processing and provides a standardized dataset class for direct use.
+
+**Key Features:**
+
+- **Broad Compatibility:** Parses output from a wide range of DFT software, including ABACUS, VASP, SIESTA, Gaussian, and more.
+- **Efficient I/O:** Uses multiprocessing to accelerate parsing of large datasets.
+- **Standardized Data:** Converts varied DFT outputs into consistent data structures.
+- **Flexible Output:** Saves processed data in multiple formats like `.dat`, `ase`, or `lmdb`.
+- **Command-Line Interface:** Provides a powerful CLI for easy automation and scripting.
+
+This documentation will guide you through installing `dftio`, using its features, and contributing to its development.

_sources/index.md

@@ -0,0 +1,48 @@
+# Installation
+
+There are several ways to install `dftio`. The recommended method is to use the provided install script, which handles all dependencies automatically.
+
+## Using the Install Script (Recommended)
+
+The easiest way to install `dftio` is by running the `install.sh` script in the root of the repository.
+
+```bash
+# For a standard CPU-only installation
+./install.sh
+
+# If you have a CUDA-compatible GPU (e.g., CUDA 12.1)
+./install.sh cu121
+```
+
+This script ensures that all dependencies, including specific versions of PyTorch and `torch-scatter`, are installed correctly.
+
+## Manual Installation with UV
+
+If you prefer to manage the installation yourself, you can use `uv`.
+
+1.  **Install uv:**
+    If you don't have `uv`, install it via pip:
+    ```bash
+    pip install uv
+    ```
+
+2.  **Sync Dependencies:**
+    Use `uv sync` to install the required packages from `pyproject.toml`.
+
+    ```bash
+    # For a CPU-only installation
+    uv sync --group dev
+
+    # For a GPU installation (e.g., CUDA 12.1), specify the PyTorch find-links URL
+    uv sync --group dev --find-links https://data.pyg.org/whl/torch-2.5.0+cu121.html
+    ```
+    Including the `--group dev` flag will also install the packages required for testing and building documentation.
+
+## Using pip (from PyPI)
+
+*Coming soon. Once `dftio` is published to the Python Package Index (PyPI), you will be able to install it directly with `pip`.*
+
+```bash
+# This will be enabled in a future release
+# pip install dftio
+```