tcal Documentation¶

Requirements¶

Python 3.9 or newer
NumPy
Gaussian 09 or 16 (optional)
PySCF (optional, macOS / Linux / WSL2(Windows Subsystem for Linux))

Important

When using Gaussian, the path of the Gaussian must be set.

Important

PySCF is supported on macOS and Linux. Windows users must use WSL2.

Installation¶

Using Gaussian 09 or 16 (without PySCF)¶

pip install yu-tcal

Using PySCF (CPU only, macOS / Linux / WSL2)¶

pip install "yu-tcal[pyscf]"

Using GPU acceleration with PySCF (macOS / Linux / WSL2)¶

Check your installed CUDA Toolkit version:
```
nvcc --version
```
Install tcal with GPU acceleration:

If your CUDA Toolkit version is 12.x:
```
pip install "yu-tcal[gpu4pyscf-cuda12]"
```
If your CUDA Toolkit version is 11.x:
```
pip install "yu-tcal[gpu4pyscf-cuda11]"
```

Verify Installation¶

After installation, you can verify by running:

tcal --help

Options¶

Short	Long	Explanation
`-a`	`--apta`	Perform atomic pair transfer analysis.
`-c`	`--cube`	Generate cube files.
`-g`	`--g09`	Use Gaussian 09. (default is Gaussian 16)
`-h`	`--help`	Show options description.
`-l`	`--lumo`	Perform atomic pair transfer analysis of LUMO.
`-m`	`--matrix`	Print MO coefficients, overlap matrix and Fock matrix.
`-o`	`--output`	Output csv file on the result of apta.
`-r`	`--read`	Read log/checkpoint files without executing calculations.
`-x`	`--xyz`	Convert xyz file to gjf file. (Gaussian only)
`-M`	`--method METHOD/BASIS`	Calculation method and basis set in “METHOD/BASIS” format. (default: B3LYP/6-31G(d,p))
	`--cpu N`	Set the number of CPUs. (default: 4)
	`--mem N`	Set the memory size in GB. (default: 16)
	`--napta N1 N2`	Perform atomic pair transfer analysis between different levels. N1 is the number of level in the first monomer. N2 is the number of level in the second monomer.
	`--hetero N`	Calculate the transfer integral of heterodimer. N is the number of atoms in the first monomer.
	`--nlevel N`	Calculate transfer integrals between different levels. N is the number of levels from HOMO-LUMO. N=0 gives all levels.
	`--skip N...`	Skip specified calculation. If N is 1, skip 1st monomer calculation. If N is 2, skip 2nd monomer calculation. If N is 3, skip dimer calculation.
	`--pyscf`	Use PySCF instead of Gaussian. Input file must be an xyz file.
	`--gpu4pyscf`	Use GPU acceleration via gpu4pyscf. (PySCF only)

How to Use¶

Using Gaussian¶

1. Create gjf file¶

First of all, create a gaussian input file as follows:

Example: xxx.gjf

The xxx part is an arbitrary string.

Description of link commands¶

pop=full: Required to output coefficients of basis functions, overlap matrix, and Fock matrix.
iop(3/33=4,5/33=3): Required to output coefficients of basis functions, overlap matrix, and Fock matrix.

How to create a gjf using Mercury¶

Open cif file in Mercury.
Display the dimer you want to calculate.
Save in mol file or mol2 file.
Open a mol file or mol2 file in GaussView and save it in gjf format.

2. Execute tcal¶

Suppose the directory structure is as follows:

yyy
└── xxx.gjf

Open a terminal.
Go to the directory where the files is located.
```
cd yyy
```
Execute the following command.
```
tcal -a xxx.gjf
```

3. Visualization of molecular orbitals¶

Execute the following command.
```
tcal -cr xxx.gjf
```
Open xxx.fchk in GaussView.
[Results] → [Surfaces/Contours…]
[Cube Actions] → [Load Cube]
Open xxx_m1_HOMO.cube and xxx_m2_HOMO.cube.
Visualize by operating [Surface Actions] → [New Surface].

Using PySCF¶

1. Create xyz file¶

Prepare an xyz file of the dimer structure. The first half of the atoms are treated as monomer 1, and the second half as monomer 2. For heterodimers, use the --hetero N option to specify the number of atoms in the first monomer.

2. Execute tcal¶

tcal --pyscf -a xxx.xyz

To specify a calculation method and basis set:

tcal --pyscf -M "B3LYP/6-31G(d,p)" -a xxx.xyz

To use GPU acceleration:

tcal --gpu4pyscf -M "B3LYP/6-31G(d,p)" -a xxx.xyz

To read from existing checkpoint files without re-running calculations:

tcal --pyscf -ar xxx.xyz

Interatomic Transfer Integral¶

For calculating the transfer integral between molecule A and molecule B, DFT calculations were performed for monomer A, monomer B, and the dimer AB. The monomer molecular orbitals \(\ket{A}\) and \(\ket{B}\) were obtained from the monomer calculations. Fock matrix F was calculated in the dimer system. Finally the intermolecular transfer integral \(t^{[1]}\) was calculated by using the following equation:

\[t = \frac{\braket{A|F|B} - \frac{1}{2} (\epsilon_{A}+\epsilon_{B})\braket{A|B}}{1 - \braket{A|B}^2},\]

where \(\epsilon_A \equiv \braket{A|F|A}\) and \(\epsilon_B \equiv \braket{B|F|B}\).

In addition to the intermolecular transfer integral in general use, we developed an interatomic transfer integral for further analysis \(^{[2]}\). By grouping the basis functions \(\ket{i}\) and \(\ket{j}\) for each atom, the molecular orbitals can be expressed as

\[\ket{A} = \sum^A_{\alpha} \sum^{\alpha}_i a_i \ket{i},\]

\[\ket{B} = \sum^B_{\beta} \sum^{\beta}_j b_j \ket{j},\]

where \(\alpha\) and \(\beta\) are the indices of atoms, \(i\) and \(j\) are indices of basis functions, and \(a_i\) and \(b_j\) are the coefficients of basis functions. Substituting this formula into aforementioned equation gives

\[t = \sum^A_{\alpha} \sum^B_{\beta} \sum^{\alpha}_i \sum^{\beta}_j a^*_i b_j \frac{\braket{i|F|j} - \frac{1}{2} (\epsilon_A + \epsilon_B) \braket{i|j}}{1 - \braket{A|B}^2}\]

Here we define the interatomic transfer integral \(u_{\alpha\beta}\) as:

\[u_{\alpha \beta} \equiv \sum^{\alpha}_i \sum^{\beta}_j a^*_i b_j \frac{\braket{i|F|j} - \frac{1}{2} (\epsilon_A + \epsilon_B) \braket{i|j}}{1 - \braket{A|B}^2}\]

References¶

[1] Veaceslav Coropceanu et al., Charge Transport in Organic Semiconductors, Chem. Rev. 2007, 107, 926-952.

[2] Koki Ozawa et al., Statistical analysis of interatomic transfer integrals for exploring high-mobility organic semiconductors, Sci. Technol. Adv. Mater. 2024, 25, 2354652.

[3] Qiming Sun et al., Recent developments in the PySCF program package, J. Chem. Phys. 2020, 153, 024109.

Citation¶

When publishing works that benefited from tcal, please cite the following article:

Koki Ozawa, Tomoharu Okada, Hiroyuki Matsui, Statistical analysis of interatomic transfer integrals for exploring high-mobility organic semiconductors, Sci. Technol. Adv. Mater., 2024, 25, 2354652.

DOI: 10.1080/14686996.2024.2354652

Example of using tcal¶

API Reference¶

API Reference

src
- tcal package

Indices and Tables¶

Authors¶

Matsui Laboratory, Research Center for Organic Electronics (ROEL), Yamagata University

Hiroyuki Matsui
Koki Ozawa

Email: h-matsui[at]yz.yamagata-u.ac.jp (Please replace [at] with @)

Acknowledgements¶

This work was supported by JST, CREST, Grand Number JPMJCR18J2.

License¶

This project is released under the MIT License.

For more details, see the LICENSE file on GitHub.