Merge branch 'main' into hotfix_vasp_kpath

Author: QG-phy

.github/workflows/add_pages_doc.yml

@@ -0,0 +1,35 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches: [ main ]  # 或者您的默认分支名
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    if: github.repository == 'deepmodeling/DeePTB'
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx sphinx_book_theme linkify-it-py
+        pip install myst-nb jupyter
+        # 安装deepmodeling_sphinx
+        if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi
+    - name: Build docs
+      run: |
+        cd docs
+        sphinx-build -b html . _build/html
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v4
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html

README.md

@@ -66,42 +66,40 @@ Installing **DeePTB** is straightforward. We recommend using a virtual environme
 
     Highly recommended to install DeePTB from source to get the latest features and bug fixes.
   1. **Setup Python environment**:
-    
         Using conda (recommended, python >=3.9, <=3.12 ), e.g.,
         ```bash
         conda create -n dptb_venv python=3.10
         conda activate dptb_venv
         ```
         or using venv (make sure python >=3.9,<=3.12)
+    
         ```bash
         python -m venv dptb_venv
         source dptb_venv/bin/activate
+        ```
 
   2. **Clone DeePTB and  Navigate to the root directory**:
         ```bash
         git clone https://github.com/deepmodeling/DeePTB.git
         cd DeePTB
         ```
-  3. **Install `torch` and `torch-scatter`** (two ways):
-        - **Recommended**: Install torch and torch-scatter using the following commands:
 
+  3. **Install `torch`**:
+        ```bash
+        pip install "torch>=2.0.0,<=2.5.0"
+        ```
+  4. **Install `torch-scatter`** (two ways):
+        - **Recommended**: Install torch and torch-scatter using the following commands:
             ```bash
             python docs/auto_install_torch_scatter.py
             ```
-
         - **Manual**: Install torch and torch-scatter manually:
-          1. install torch:
-                ```bash
-                pip install "torch>=2.0.0,<=2.5.0"
-                ```
-
-          2. install torch-scatter:
-                ```bash
-                pip install torch-scatter -f https://data.pyg.org/whl/torch-${version}+${CUDA}.html
-                ```
-                where `${version}` is the version of torch, e.g., 2.5.0, and `${CUDA}` is the CUDA version, e.g., cpu, cu118, cu121, cu124. See [torch_scatter doc](https://github.com/rusty1s/pytorch_scatter) for more details.   
-
-  4. **Install DeePTB**:
+            ```bash
+            pip install torch-scatter -f https://data.pyg.org/whl/torch-${version}+${CUDA}.html
+            ```
+            where `${version}` is the version of torch, e.g., 2.5.0, and `${CUDA}` is the CUDA version, e.g., cpu, cu118, cu121, cu124. See [torch_scatter doc](https://github.com/rusty1s/pytorch_scatter) for more details.   
+
+  5. **Install DeePTB**:
         ```bash
         pip install .
         ```

docs/advanced/e3tb/advanced_input.md

@@ -86,6 +86,9 @@ In [7]: idp.get_irreps_ess()
 Out[7]: 7x0e+6x1o+6x2e+2x3o+1x4e
 ```
 
+Rules for the irreps setting:
+First, we should check the largest angular momentum defined in the DFT LCAO basis, and then double it as our highest order of irreps (since the addition rule of the angular momentum). For example, for `1s1p` basis, the irreps should contain features with angular momentum from 0 to 2, which is 2 times 1, the angular momentum of `p` orbital. If the basis contains `d` orbital, then the irreps should contain angular momentum up to 4. `f` and `g` or even higher orbitals are also supported.
+
 `n_layers`: indicates the number of layers of the networks.
 
 `env_embed_multiplicity`: decide the irreps number when initializing the edge and node features.

docs/conf.py

@@ -31,9 +31,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-        'myst_parser',
+        'myst_nb',
         'deepmodeling_sphinx',
 ]
+nb_execute_notebooks = "off"  # 不执行notebooks
+
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",

docs/quick_start/easy_install.md

@@ -29,32 +29,28 @@ Highly recommended to install DeePTB from source to get the latest features and
     ```bash
     python -m venv dptb_venv
     source dptb_venv/bin/activate
-
+    ```
 2. **Clone DeePTB and  Navigate to the root directory**:
     ```bash
     git clone https://github.com/deepmodeling/DeePTB.git
     cd DeePTB
     ```
-3. **Install `torch` and `torch-scatter`** (two ways):
-- **Recommended**: Install torch and torch-scatter using the following commands:
-
+3. **Install `torch`**:
     ```bash
-    python docs/auto_install_torch_scatter.py
+    pip install "torch>=2.0.0,<=2.5.0"
     ```
-
-- **Manual**: Install torch and torch-scatter manually:
-  1. install torch:
+4. **Install `torch-scatter`** (two ways):
+    - **Recommended**: Install torch and torch-scatter using the following commands:
         ```bash
-        pip install "torch>=2.0.0,<=2.5.0"
+         python docs/auto_install_torch_scatter.py
         ```
-
-  2. install torch-scatter:
+    - **Manual**: Install torch and torch-scatter manually:
         ```bash
         pip install torch-scatter -f https://data.pyg.org/whl/torch-${version}+${CUDA}.html
         ```
         where `${version}` is the version of torch, e.g., 2.5.0, and `${CUDA}` is the CUDA version, e.g., cpu, cu118, cu121, cu124. See [torch_scatter doc](https://github.com/rusty1s/pytorch_scatter) for more details.   
 
-4. **Install DeePTB**:   
+5. **Install DeePTB**:   
     ```bash
     pip install .
     ```

docs/quick_start/hands_on/e3tb_hands_on.md

@@ -2,7 +2,7 @@
 
 DeePTB supports training an E3-equalvariant model to predict DFT Hamiltonian, density and overlap matrix under LCAO basis. Here, cubic-phase bulk silicon has been chosen as a quick start example.
 
-Silicon is a chemical element; it has the symbol Si and atomic number 14. It is a hard, brittle crystalline solid with a blue-grey metallic lustre, and is a tetravalent metalloid and semiconductor. The prepared files are located in:
+Silicon is a chemical element; it has the symbol Si and atomic number 14. It is a hard, brittle crystalline solid with a blue-grey metallic lustre, and is a tetravalent metalloid and semiconductor (Shut up). The prepared files are located in:
 
 ```
 deeptb/examples/e3/
@@ -19,16 +19,13 @@ deeptb/examples/e3/
 |   `-- info.json
 `-- input.json
 ```
-We prepared one frame of silicon cubic bulk structure as an example. The data was computed using DFT software ABACUS, with an LCAO basis set containing 1 `s` and 1 `p` orbital. The cutoff radius for the orbital is 7au, which means the largest bond would be less than 14 au. Therefore, the r_max should be set as 7.4. So we have an info.json file like:
+We prepared one frame of silicon cubic bulk structure as an example. The data was computed using DFT software ABACUS, with an LCAO basis set containing 1 `s` and 1 `p` orbital. We now have an info.json file like:
 
-```json
+```JSON
 {
         "nframes": 1,
         "pos_type": "cart",
-        "AtomicData_options": {
-                "r_max": 7.4,
-                "pbc": true
-        }
+        "pbc": true, # same as [true, true, true]
 }
 ```
 
@@ -42,7 +39,7 @@ The `input_short.json` file contains the least number of parameters that are req
     "overlap": true
 }
 ```
-In `common_options`, here are the essential parameters. The `basis` should align with the DFT calculation, so 1 `s` and 1 `p` orbital would result in a `1s1p` basis. The `device` can either be `cpu` or `cuda`, but we highly recommend using `cuda` if GPU is available. The `overlap` tag controls whether to fit the overlap matrix together. Benefitting from our parameterization, the fitting overlap only brings negelectable costs, but would boost the convenience when using the model.
+In `common_options`, here are the essential parameters. The `basis` should align with the DFT calculation, so 1 `s` and 1 `p` orbital would result in a `1s1p` basis. The cutoff radius for the orbital is 7au, which means the largest bond would be less than 14 au. Therefore, the `r_max`, which equals to the maximum bond length, should be set as 7.4. The `device` can either be `cpu` or `cuda`, but we highly recommend using `cuda` if GPU is available. The `overlap` tag controls whether to fit the overlap matrix together. Benefitting from our parameterization, the fitting overlap only brings negligible costs, but is very convenient when using the model.
 
 Here comes the `model_options`:
 ```json
@@ -67,16 +64,26 @@ The `model_options` contains `embedding` and `prediction` parts, denoting the co
 
 In `embedding`, the `method` supports `slem` and `lem` for now, where `slem` has a strictly localized dependency, which has better transferability and data efficiency, while `lem` has an adjustable semi-local dependency, which has better representation capacity, but would require a little more data. `r_max` should align with the one defined in `info.json`.
 
-For `irreps_hidden`, this parameter defines the size of the hidden equivariant irreducible representation, which is highly related to the power of the model. There are certain rules to define this param. First, we should check the largest angular momentum defined in the DFT LCAO basis, the irreps's highest angular momentum should always be double. For example, for `1s1p` basis, the irreps should contain features with angular momentum from 0 to 2, which is 2 times 1, the angular momentum of `p` orbital. If the basis contains `d` orbital, then the irreps should contain angular momentum up to 4. `f` and `g` or even higher orbitals are also supported.
+For `irreps_hidden`, this parameter defines the size of the hidden equivariant irreducible representation, which decides most of the power of the model. There are certain rules to define this param. But for quick usage, we provide a tool to do basis analysis to extract essential irreps.
+
+```IPYTHON
+In [1]: from dptb.data import OrbitalMapper
+
+In [2]: idp = OrbitalMapper(basis={"Si": "1s1p"})
+
+In [3]: idp.get_irreps_ess()
+Out[3]: 2x0e+1x1o+1x2e
+```
 
-In `prediction`, we should use the `e3tb` method to let the model know the output features are arranged in **DeePTB-E3** format. The neurons are defined for a simple MLP to predict the slater-koster-like parameters for predicting the overlap matrix, for which [64,64] is usually fine.
+This is the number of independent irreps contains in the basis. Irreps configured should be multiple times of this essential irreps. The number can varies with a pretty large freedom, but the all the types, for example ("0e", "1o", "2e") here, should be included for all. We usually take a descending order starts from "32", "64", or "128" for the first "0e" and decay by half for latter high order irreps. For general rules of the irreps, user can read the advance topics in the doc, but for now, you are safe to ignore!
 
+In `prediction`, we should use the `e3tb` method to require the model output features using **DeePTB-E3** format. The neurons are defined for a simple MLP to predict the slater-koster-like parameters for predicting the overlap matrix, for which [64,64] is usually fine.
 
 Now everything is prepared! We can using the following command and we can train the first model:
 
 ```bash
 cd deeptb/examples/e3
-dptb train ./input/input_short.json -o ./e3_silicon
+dptb train ./input_short.json -o ./e3_silicon
 ```
 
 Here ``-o`` indicate the output directory. During the fitting procedure, we can see the loss curve of hBN is decrease consistently. When finished, we get the fitting results in folders ```e3_silicon```.
@@ -87,9 +94,9 @@ python plot_band.py
 ```
 or just using the command line 
 ```bash
-dptb run ./run/band.json -i ./e3_silicon/checkpoint/nnenv.best.pth -o ./band_plot
+dptb run ./band.json -i ./e3_silicon/checkpoint/nnenv.best.pth -o ./band_plot
 ```
 
 ![band_e3_Si](https://raw.githubusercontent.com/deepmodeling/DeePTB/main/docs/img/silicon_e3_band.png)
 
-Now you know how to train a **DeePTB-E3** model for Hamiltonian and overlap matrix. For better usage, we encourage the user to read the full input parameters for the **DeePTB-E3** model. Also, the **DeePTB** model supports several post-process tools, and the user can directly extract any predicted properties just using a few lines of code. Please see the basis_api for details.
+Now you know how to train a **DeePTB-E3** model for Hamiltonian and overlap matrix. For better usage, we encourage the user to read the full input parameters for the **DeePTB-E3** model. Also, the **DeePTB** model supports several post-process tools, and the user can directly extract any predicted properties just using a few lines of code. Please see the basis_api for details.

docs/quick_start/hands_on/index.rst

@@ -3,5 +3,7 @@ A quick Example
 =================================================
 
 .. toctree::
-   sktb_hands_on
-   e3tb_hands_on
+   tutorial1_base_sk
+   tutorial2_data
+   tutorial3_train_si
+   tutorial4_E3_si