add doc and example for TBtrans interface

docs/advanced/interface/TBtrans.md

@@ -0,0 +1,82 @@
+# TBtrans
+
+Here is the instruction for an deeptb interface `tbtrans_negf`, which is convenient for users with needs to do NEGF calculation and are familiar with TBtrans. 
+
+This interface enpowers deeptb the ability to generate input files for TBtrans, containing sufficient information for TBtrans to calculate transport properties.
+
+## TBtrans info
+
+- TBtrans (Tight-Binding transport) is a generic computer program which calculates transport and other physical quantities using the Green function formalism. It is a stand-alone program which allows extreme scale tight-binding calculations. For details, see https://www.sciencedirect.com/science/article/pii/S001046551630306X?via%3Dihub.
+
+- We design an inferface for dptb to utilize TBtrans as a tool for transport calculation. The interface would prepare tbtrans input files (.nc) by extracting necessary information from deeptb-negf input files and predicting hamiltonian with deeptb model. 
+
+- Users only need to prepare their own RUN.fdf (TBtrans input setting files) to satisfy various functions in TBtrans, although we have provided an example input in DeePTB/examples/tbtrans_hBN/tbtrans_input/RUN_tbtrans.fdf.
+
+- To run the Interface, users need install **sisl** package(https://zerothi.github.io/sisl/index.html), which is a postprocess python code for siesta.
+
+- Attention: 
+  - TBtrans would not automatically run. This interface just prepares input files for you!
+    - If you are interested in Runing TBtrans, please install it firstly.
+  - Currently, `tbtrans_negf` only support 2-terminal transport.
+
+## Input files for `tbtrans_negf`
+
+To run `tbtrans_negf`, only 3 files user should prepare: structure, deeptb model and input setting. 
+
+### structure
+
+- `tbtrans_negf` support `extxyz` and `.vasp` format.
+- Following  the same convention as dptb-negf, the transport direction should be the z-direction. 
+
+### deeptb model
+- `tbtrans_negf` would use this model to generate the Hamiltonian and related info for later transport calculation.
+
+### input setting
+
+- `input setting` contains information of the region definition and periodic conditions. An example file is `DeePTB/examples/tbtrans_hBN/negf_tbt.json`, from which this interface would automatically extract necessary information for TBtrans calculation.
+- Users could directly reuse setting for dptb-negf  as an setting for dptb-tbtrans. The only thing users need to do is give `task` label a new string: rename `negf` as `tbtrans_negf`. 
+
+
+## RUN
+
+The interface `tbtrans_negf` has merged into DeePTB Shell Command and 
+
+Take `DeePTB/examples/tbtrans_hBN/negf_tbt.json` as an example. 
+
+```shell
+cd DeePTB/examples/tbtrans_hBN/tbtrans_input/
+dptb run -sk negf_tbt.json -i ./data/model/latest_nnsk_b3.600_c3.600_w0.300.pth -o tbtrans_input
+```
+ As `DeePTB/examples/tbtrans_hBN/data/model/latest_nnsk_b3.600_c3.600_w0.300.pth` is nnsk model, we need to add `-sk` here to the command line. Then  the input files for TBtrans would store in `tbtrans_input`.
+
+## Output
+
+- **structure files**
+  - lead_L_tbtrans.xyz, lead_R_tbtrans.xyz: lead region of the whole structre, being easy for users to check and visulize their definiton of leads.
+  - srtuctre_tbtrans.vasp, structure_tbtrans.xyz: the whole structure, being easy for visulization in vasp format.
+
+- **nc files**
+  - lead_L.nc, lead_R.nc: Hamiltonian and overlap matrix of lead_L and lead_R,  necessary for TBtrans to calculate lead self energy.
+  - structure.nc: Hamiltonian and overlap matrix of the whole structure
+
+- To run TBtrans successfully, users should know the basic principles in NEGF and prepare their own setting files (usually named `RUN_tbtrans.fdf`) for TBtrans. Here we provide an simple example `DeePTB/examples/tbtrans_hBN/tbtrans_input/RUN_tbtrans.fdf` . 
+
+## Example
+
+We design an example of `tbtrans_negf` for hBN in `DeePTB/examples/tbtrans_hBN`， and `DeePTB/examples/tbtrans_hBN/tbtrans_hBN_show.ipynb` shows the results of TBtrans transmission calculation. The detailed information and results are concluded in  `DeePTB/examples/tbtrans_hBN/tbtrans_hBN_show.ipynb`.
+
+Firstly we calculate the $\Gamma$ point transmission, which evidently shows the band gap in the middle.
+<div align=center>
+<img src="https://raw.githubusercontent.com/AsymmetryChou/DeePTB/tbtrans_doc/docs/img/hBN_gamma_trans.png" width = "60%" height = "50%" alt="hBN gamma transmission" align=center />
+</div>
+Sum up all the k points we get k-average transmission. 
+<div align=center>
+<img src="https://raw.githubusercontent.com/AsymmetryChou/DeePTB/tbtrans_doc/docs/img/hBN_kavg_trans.png" width = "60%" height = "50%" alt="hBN gamma transmission" align=center />
+</div>
+Finally we calculate directly I-V in non-self-consistent manner 
+<div align=center>
+<img src="https://raw.githubusercontent.com/AsymmetryChou/DeePTB/tbtrans_doc/docs/img/hBN_IV.png" width = "60%" height = "50%" alt="hBN gamma transmission" align=center />
+</div>
+
+
+Combining this example would be the most efficient way to master `tbtrans_negf` interface. 

examples/tbtrans_hBN/band.json

@@ -0,0 +1,18 @@
+{   
+    "structure":"./data/struct_unitcell.vasp",
+    "task_options": {
+        "task": "band",
+        "kline_type":"abacus",
+        "kpath":[
+            [0, 0, 0, 50],
+            [0.5, 0, 0, 50],
+            [0.3333333, 0.3333333, 0, 50],
+            [0, 0, 0, 1]
+        ],
+        "nkpoints":151,
+        "klabels":["G", "M", "K", "G"],
+        "E_fermi":-19.25515365600586,
+        "emin":-20,
+        "emax":20
+    }
+}

examples/tbtrans_hBN/data/dptb_TBT_results/lead_L_tbtrans.xyz

@@ -0,0 +1,18 @@
+   16
+Lattice="30.00000000 0.00000000 0.00000000 0.00000000 4.33705513 0.00000000 0.00000000 0.00000000 10.01599979 " nsc="1 1 1" pbc="T T T" boundary_condition="PERIODIC PERIODIC  PERIODIC PERIODIC  PERIODIC PERIODIC"
+B   15.00000000  2.52994883  0.62599999
+N   15.00000000  3.97563387  0.62599999
+B   15.00000000  0.36142126  1.87799996
+N   15.00000000  1.80710631  1.87799996
+B   15.00000000  2.52994883  3.12999994
+N   15.00000000  3.97563387  3.12999994
+B   15.00000000  0.36142126  4.38199991
+N   15.00000000  1.80710631  4.38199991
+B   15.00000000  2.52994883  5.63399988
+N   15.00000000  3.97563387  5.63399988
+B   15.00000000  0.36142126  6.88599986
+N   15.00000000  1.80710631  6.88599986
+B   15.00000000  2.52994883  8.13799983
+N   15.00000000  3.97563387  8.13799983
+B   15.00000000  0.36142126  9.38999981
+N   15.00000000  1.80710631  9.38999981

examples/tbtrans_hBN/data/struct.xyz

@@ -0,0 +1,62 @@
+60
+Lattice="30.0 0.0 0.0 0.0 4.337055133 0.0 0.0 0.0 37.5599992275" Properties=species:S:1:pos:R:3 pbc="T T T"
+B       15.00000000       2.52994883       5.63399988
+N       15.00000000       3.97563387       5.63399988
+B       15.00000000       0.36142126       6.88599986
+N       15.00000000       1.80710631       6.88599986
+B       15.00000000       2.52994883       8.13799983
+N       15.00000000       3.97563387       8.13799983
+B       15.00000000       0.36142126       9.38999981
+N       15.00000000       1.80710631       9.38999981
+B       15.00000000       2.52994883       0.62599999
+N       15.00000000       3.97563387       0.62599999
+B       15.00000000       0.36142126       1.87799996
+N       15.00000000       1.80710631       1.87799996
+B       15.00000000       2.52994883       3.12999994
+N       15.00000000       3.97563387       3.12999994
+B       15.00000000       0.36142126       4.38199991
+N       15.00000000       1.80710631       4.38199991
+B       15.00000000       2.52994883      10.64199978
+N       15.00000000       3.97563387      10.64199978
+B       15.00000000       0.36142126      11.89399976
+N       15.00000000       1.80710631      11.89399976
+B       15.00000000       2.52994883      13.14599973
+N       15.00000000       3.97563387      13.14599973
+B       15.00000000       0.36142126      14.39799970
+N       15.00000000       1.80710631      14.39799970
+B       15.00000000       2.52994883      15.64999968
+N       15.00000000       3.97563387      15.64999968
+B       15.00000000       0.36142126      16.90199965
+N       15.00000000       1.80710631      16.90199965
+B       15.00000000       2.52994883      18.15399962
+N       15.00000000       3.97563387      18.15399962
+B       15.00000000       0.36142126      19.40599960
+N       15.00000000       1.80710631      19.40599960
+B       15.00000000       2.52994883      20.65799957
+N       15.00000000       3.97563387      20.65799957
+B       15.00000000       0.36142126      21.90999955
+N       15.00000000       1.80710631      21.90999955
+B       15.00000000       2.52994883      23.16199952
+N       15.00000000       3.97563387      23.16199952
+B       15.00000000       0.36142126      24.41399950
+N       15.00000000       1.80710631      24.41399950
+B       15.00000000       2.52994883      25.66599948
+N       15.00000000       3.97563387      25.66599948
+B       15.00000000       0.36142126      26.91799945
+N       15.00000000       1.80710631      26.91799945
+B       15.00000000       2.52994883      28.16999943
+N       15.00000000       3.97563387      28.16999943
+B       15.00000000       0.36142126      29.42199940
+N       15.00000000       1.80710631      29.42199940
+B       15.00000000       2.52994883      30.67399937
+N       15.00000000       3.97563387      30.67399937
+B       15.00000000       0.36142126      31.92599935
+N       15.00000000       1.80710631      31.92599935
+B       15.00000000       2.52994883      33.17799932
+N       15.00000000       3.97563387      33.17799932
+B       15.00000000       0.36142126      34.42999930
+N       15.00000000       1.80710631      34.42999930
+B       15.00000000       2.52994883      35.68199927
+N       15.00000000       3.97563387      35.68199927
+B       15.00000000       0.36142126      36.93399925
+N       15.00000000       1.80710631      36.93399925

examples/tbtrans_hBN/negf_tbt.json

@@ -0,0 +1,55 @@
+{   "structure":"./data/struct.xyz",
+	"task_options":
+        {
+            "task": "tbtrans_negf",
+            "scf": true,
+            "block_tridiagonal": false,
+            "ele_T": 500,
+            "unit": "Hartree",
+            "scf_options":{
+                "mode": "PDIIS",
+                "mixing_period": 3,
+                "step_size": 0.05,
+                "n_history": 6,
+                "abs_err": 1e-6,
+                "rel_err": 1e-4,
+                "max_iter": 100
+            },
+            "stru_options":{
+                "pbc":[false, true, false],
+                "kmesh":[1,1,1],
+                "device":{
+                    "id":"16-44",
+                    "sort": true
+                },
+                "lead_L":{
+                    "id":"0-16",
+                    "voltage":0.0
+                },
+                "lead_R":{
+                    "id":"44-60",
+                    "voltage":0.0
+                }
+            },
+            "poisson_options": {
+                "solver": "fmm",
+                "err": 1e-5
+            },
+            "sgf_solver": "Sancho-Rubio",
+            "espacing": 0.04,
+            "emin": -20,
+            "emax": 15,
+            "e_fermi": -9.874357223510742,
+            "density_options":{
+                "method": "Ozaki"
+            },
+            "eta_lead":1e-5,
+            "eta_device":0.0,
+            "out_dos": true,
+            "out_tc": true,
+            "out_ldos": true,
+            "out_current_nscf": true,
+            "out_density": true,
+            "out_lcurrent": true
+    }
+}

examples/tbtrans_hBN/tbtrans_input/RUN_tbtrans.fdf

@@ -0,0 +1,30 @@
+TBT.HS structure.nc
+TBT.Directory ./T
+
+TBT.k [1 100 1] # set the k points along x/y/z axis
+
+%block TBT.Elec.Left
+  HS lead_L.nc
+  semi-inf-direction -A3
+  electrode-position 1
+%endblock TBT.Elec.Left
+%block TBT.Elec.Right
+  HS lead_R.nc
+  semi-inf-direction +A3
+  electrode-position end -1
+%endblock TBT.Elec.Right
+
+
+%block TBT.Contours
+  neq
+%endblock TBT.Contours
+
+%block TBT.Contour.neq
+  part line
+   from   -39.25000 eV to -4.25 eV
+    delta    0.02 eV
+     method mid-rule
+%endblock TBT.Contour.neq
+
+
+TBT.BTD.Pivot.Device orb+none

pyproject.toml

@@ -44,6 +44,14 @@ optional = true
 ifermi = "*"
 pymatgen = "*"
 
+[tool.poetry.group.tbtrans_init]
+optional = true
+
+[tool.poetry.group.tbtrans_init.dependencies]
+sisl = "*"
+
+
+
 [tool.poetry.scripts]
 dptb = 'dptb.__main__:main'