You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/advanced/e3tb/advanced_input.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -86,6 +86,9 @@ In [7]: idp.get_irreps_ess()
86
86
Out[7]: 7x0e+6x1o+6x2e+2x3o+1x4e
87
87
```
88
88
89
+
Rules for the irreps setting:
90
+
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.
91
+
89
92
`n_layers`: indicates the number of layers of the networks.
90
93
91
94
`env_embed_multiplicity`: decide the irreps number when initializing the edge and node features.
Copy file name to clipboardExpand all lines: docs/quick_start/hands_on/e3tb_hands_on.md
+20-13Lines changed: 20 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
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.
4
4
5
-
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:
5
+
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:
6
6
7
7
```
8
8
deeptb/examples/e3/
@@ -19,16 +19,13 @@ deeptb/examples/e3/
19
19
| `-- info.json
20
20
`-- input.json
21
21
```
22
-
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:
22
+
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:
23
23
24
-
```json
24
+
```JSON
25
25
{
26
26
"nframes": 1,
27
27
"pos_type": "cart",
28
-
"AtomicData_options": {
29
-
"r_max": 7.4,
30
-
"pbc": true
31
-
}
28
+
"pbc": true, # same as [true, true, true]
32
29
}
33
30
```
34
31
@@ -42,7 +39,7 @@ The `input_short.json` file contains the least number of parameters that are req
42
39
"overlap": true
43
40
}
44
41
```
45
-
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.
42
+
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.
46
43
47
44
Here comes the `model_options`:
48
45
```json
@@ -67,16 +64,26 @@ The `model_options` contains `embedding` and `prediction` parts, denoting the co
67
64
68
65
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`.
69
66
70
-
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.
67
+
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.
68
+
69
+
```IPYTHON
70
+
In [1]: from dptb.data import OrbitalMapper
71
+
72
+
In [2]: idp = OrbitalMapper(basis={"Si": "1s1p"})
73
+
74
+
In [3]: idp.get_irreps_ess()
75
+
Out[3]: 2x0e+1x1o+1x2e
76
+
```
71
77
72
-
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.
78
+
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!
73
79
80
+
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.
74
81
75
82
Now everything is prepared! We can using the following command and we can train the first model:
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
87
94
```
88
95
or just using the command line
89
96
```bash
90
-
dptb run ./run/band.json -i ./e3_silicon/checkpoint/nnenv.best.pth -o ./band_plot
97
+
dptb run ./band.json -i ./e3_silicon/checkpoint/nnenv.best.pth -o ./band_plot
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.
102
+
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.
Copy file name to clipboardExpand all lines: docs/quick_start/input.md
+35-30Lines changed: 35 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,52 +4,56 @@ The following files are the central input files for DeePTB. Before executing the
4
4
5
5
## Inputs
6
6
### Data
7
-
The dataset files contrains both the **atomic structure** and the **training label** information.
7
+
The dataset files contrains both the **atomic structure** and the **training label** information.
8
8
9
-
The atomic structure should be prepared as a ASE trajectory binary file, where each structure is stored using an **Atom** class defined in ASE package. The provided trajectory file must have suffix `.traj` and the length of the trajectory is `nframes`. For labels, we currently support `eigenvalues`, `Hamiltonian`, `density matrix` and `overlap matrix`.
9
+
The **atomic structure** contains the atoms' position, unit-cell vector and atomic number vector. They **must** be included in your datafile in all task.
10
+
The **training labels** are prepared dependent on each task. If you are working on `DeePTB-SK` mode, the eigenvalues and kpoints are needed. If you are working with `DeePTB-E3` mode the Hamiltonian/Density Matrix under LCAO basis must be provided, while overlap matrix are optionally provided (But we suggest to do so for convenience).
10
11
12
+
The atomic structure should be prepared in either ASE trajectory binary file format, or the plain text format. We highly suggest to use the tool `dftio` to deal with the data preparation. It can transform the data from DFT output to the target format automatically. Herefore completion, we will introduce the format of each type.
11
13
12
-
For training a **DeePTB-SK**model, we need to prepare the `eigenvalues` label, which contrains the `eigenvalues.npy` and `kpoints.npy`. A typical dataset of **DeePTB-SK** task looks like:
14
+
-For ASE trajectory binary file, each structure is stored using an **Atom**class defined in ASE package. The provided trajectory file must have suffix `.traj` and the length of the trajectory is `nframes`
-- -- xdat.traj # ase trajectory file with nframes
20
-
-- -- info.json # defining the parameters used in building AtomicData graph data
21
-
```
16
+
- For the plain text format, three seperate textfiles for **atomic structures** need to be provided: `atomic_numbers.dat`, `cell.dat` and `positions.dat`. The length unit used in `cell.dat` and `positions.dat` (if cartesian coordinates) is Angstrom.
22
17
23
-
> We also support another format to provide structure information, instead of loading structures from a single binary `.traj` file. In this way, three seperate textfiles for **atomic structures** need to be provided: `atomic_numbers.dat`, `pbc.dat`, `cell.dat` and `positions.dat`. The length unit used in `cell.dat` and `positions.dat` (if cartesian coordinates) is Angstrom.
24
18
25
-
The **band structures**data includes the kpoints list and eigenvalues in the binary format of `.npy`. The shape of kpoints data is fixed as **[nkpoints,3]**and eigenvalues is fixed as **[nframes,nkpoints,nbands]**. The `nframes` here must be the same as in **atomic structures**files.
19
+
- For training a **DeePTB-SK**model, we need to prepare the `eigenvalues` label, which contrains the `eigenvalues.npy`and `kpoints.npy`. A typical dataset of **DeePTB-SK**task looks like:
26
20
27
-
> **Important:** The eigenvalues.npy should not contain bands that contributed by the core electrons, which is not setted as the TB orbitals in model setting.
-- -- xdat.traj # ase trajectory file with nframes
27
+
-- -- info.json # defining the parameters used in building AtomicData graph data
28
+
```
28
29
29
-
For typical **DeePTB-E3**task, we need to prepare the Hamiltonian/density matrix along with overlap matrix as labels. They are arranged as hdf5 binary format, and named as `hamiltonians.h5`/`density_matrices.h5` and `overlaps.h5` respectively. A typical dataset of **DeePTB-E3**looks like:
30
+
The **band structures** data includes the kpoints list and eigenvalues in the binary format of `.npy`. The shape of kpoints data is fixed as **[nkpoints,3]** and eigenvalues is fixed as **[nframes,nkpoints,nbands]**. The `nframes` here must be the same as in **atomic structures** files.
30
31
31
-
```
32
-
data/
33
-
-- set.x
34
-
-- -- positions.dat # a text file with nframe x natom row and 3 col
35
-
-- -- pbc.dat # a text file of three bool variables
36
-
-- -- cell.dat # a text file with nframe x 3 row and 3 col, or 3 rol and 3 col.
37
-
-- -- atomic_numbers.dat # a text file with nframe x natom row and 1 col
38
-
-- -- hamiltonian.h5 # a hdf5 dataset file with group named "0", "1", ..., "nframe". Each group contains a dict of {"i_j_Rx_Ry_Rz": numpy.ndarray}
39
-
-- -- overlaps.h5 # a hdf5 dataset file with group named "0", "1", ..., "nframe". Each group contains a dict of {"i_j_Rx_Ry_Rz": numpy.ndarray}
40
-
-- -- info.json
41
-
```
32
+
> **Important:** The eigenvalues.npy should not contain bands that contributed by the core electrons, which is not setted as the TB orbitals in model setting.
33
+
34
+
- For typical **DeePTB-E3** task, we need to prepare the Hamiltonian/density matrix along with overlap matrix as labels. They are arranged as hdf5 binary format, and named as `hamiltonians.h5`/`density_matrices.h5` and `overlaps.h5` respectively. A typical dataset of **DeePTB-E3** looks like:
35
+
```
36
+
data/
37
+
-- set.x
38
+
-- -- positions.dat # a text file with nframe x natom row and 3 col
39
+
-- -- cell.dat # a text file with nframe x 3 row and 3 col, or 3 rol and 3 col.
40
+
-- -- atomic_numbers.dat # a text file with nframe x natom row and 1 col
41
+
-- -- hamiltonian.h5 # a hdf5 dataset file with group named "0", "1", ..., "nframe". Each group contains a dict of {"i_j_Rx_Ry_Rz": numpy.ndarray}
42
+
-- -- overlaps.h5 # a hdf5 dataset file with group named "0", "1", ..., "nframe". Each group contains a dict of {"i_j_Rx_Ry_Rz": numpy.ndarray}
43
+
-- -- info.json
44
+
```
42
45
43
46
### Data settings: info.json
44
47
45
48
In **DeePTB**, the **atomic structures** and **band structures** data are stored in AtomicData graph structure. `info.json` defines the key parameters used in building AtomicData graph dataset, which looks like:
46
-
```bash
49
+
```JSON
47
50
{
48
51
"nframes": 1,
49
-
"pos_type": "ase/cart/frac"
52
+
"pos_type": "ase/cart/frac",
53
+
"pbc": [true, true, true]
50
54
}
51
55
```
52
-
`nframes` is the length of the trajectory, as we defined in the previous section. `pos_type` defines the input format of the **atomic structures**, which is set to `ase` if ASE `.traj` file is provided, and `cart` or `frac` if cartesian / fractional coordinate in `positions.dat` file provided.
56
+
`nframes` is the length of the trajectory, as we defined in the previous section. `pos_type` defines the input format of the **atomic structures**, which is set to `ase` if ASE `.traj` file is provided, and `cart` or `frac` if cartesian / fractional coordinate in `positions.dat` file provided. The `pbc` specifies the periodic boundray condition of the system. The three value coresponding to the three boundary vector set in the unit cell information of the atomic data file.
53
57
54
58
<!--In the `AtomicData_options` section, the key arguments in defining graph structure is provided. `r_max` is the maximum cutoff in building neighbour list for each atom. `er_max` and `oer_max` are optional value for additional environmental dependence TB parameterization in **DeePTB-SK** mode, such as strain correction and `nnenv`. All cutoff variables have the unit of Angstrom.
55
59
For **DeePTB-SK**, We can get the recommended `r_max` value by `DeePTB`'s bond analysis function, using:
0 commit comments