Metadata-Version: 2.4
Name: yu-tcal
Version: 5.0.1
Summary: Program for the calculation of transfer integral
Author: Koki Ozawa
Author-email: Hiroyuki Matsui <h-matsui@yz.yamagata-u.ac.jp>
License: MIT License
        
        Copyright (c) 2023 Matsui Lab. in Yamagata University
        
        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.
License-File: LICENSE
Keywords: interatomic transfer integral,organic semiconductor,transfer integral
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: numpy>=2.0.2
Provides-Extra: gpu4pyscf-cuda11
Requires-Dist: basis-set-exchange>=0.12; extra == 'gpu4pyscf-cuda11'
Requires-Dist: cutensor-cu11>=2.2.0; extra == 'gpu4pyscf-cuda11'
Requires-Dist: gpu4pyscf-cuda11x>=1.5.2; extra == 'gpu4pyscf-cuda11'
Requires-Dist: pyscf>=2.12.1; extra == 'gpu4pyscf-cuda11'
Provides-Extra: gpu4pyscf-cuda12
Requires-Dist: basis-set-exchange>=0.12; extra == 'gpu4pyscf-cuda12'
Requires-Dist: cutensor-cu12>=2.5.0; extra == 'gpu4pyscf-cuda12'
Requires-Dist: gpu4pyscf-cuda12x>=1.5.2; extra == 'gpu4pyscf-cuda12'
Requires-Dist: pyscf>=2.12.1; extra == 'gpu4pyscf-cuda12'
Provides-Extra: gpu4pyscf-cuda13
Requires-Dist: basis-set-exchange>=0.12; extra == 'gpu4pyscf-cuda13'
Requires-Dist: cutensor-cu13>=2.6.0; extra == 'gpu4pyscf-cuda13'
Requires-Dist: gpu4pyscf-cuda13x>=1.7.0; extra == 'gpu4pyscf-cuda13'
Requires-Dist: pyscf>=2.12.1; extra == 'gpu4pyscf-cuda13'
Provides-Extra: orca
Requires-Dist: orca-pi; extra == 'orca'
Provides-Extra: pyscf
Requires-Dist: basis-set-exchange>=0.12; extra == 'pyscf'
Requires-Dist: pyscf>=2.12.1; extra == 'pyscf'
Description-Content-Type: text/markdown

# tcal: Program for the calculation of transfer integral
[![Python](https://img.shields.io/badge/python-3.11%20or%20newer-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![docs](https://img.shields.io/badge/docs-here-11419572)](https://matsui-lab-yamagata.github.io/tcal/)

# Requirements
* Python 3.11 or newer
* NumPy
* Gaussian 09 or 16 (optional)
* PySCF (optional, macOS / Linux / WSL2(Windows Subsystem for Linux))
* ORCA 6.1.0 or newer (optional)

# Important notice
* When using Gaussian, the path of the Gaussian must be set.
* PySCF is supported on macOS and Linux. Windows users must use WSL2.
* When using ORCA, ORCA must be installed. To perform parallel calculations with ORCA, OpenMPI must be configured.

# 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)
### 1. Check your installed CUDA Toolkit version
```
nvcc --version
```

### 2. Install tcal with GPU acceleration
If your CUDA Toolkit version is 13.x, install tcal with GPU acceleration:  
```
pip install "yu-tcal[gpu4pyscf-cuda13]"
```
If your CUDA Toolkit version is 12.x, install tcal with GPU acceleration:  
```
pip install "yu-tcal[gpu4pyscf-cuda12]"
```
If your CUDA Toolkit version is 11.x, install tcal with GPU acceleration:  
```
pip install "yu-tcal[gpu4pyscf-cuda11]"
```

## Using ORCA
```
pip install "yu-tcal[orca]"
```

## 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)|
||--bse|Use Basis Set Exchange to obtain basis sets. Allows use of basis sets not included in PySCF. (PySCF only)|
||--mpi PATH|Path to OpenMPI installation directory for ORCA parallel execution (sets `OPI_MPI` environment variable). (ORCA only)|

# How to use
## Using Gaussian
### 1. Create gjf file
First of all, create a gaussian input file as follows:  
ex: xxx.gjf  
![gjf_file_example](img/gjf_file_example.png)  
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
1. Open cif file in Mercury.  
2. Display the dimer you want to calculate.  
![Anthracene_dimer](img/Anthracene_dimer.png)  
3. Save in mol file or mol2 file.  
4. 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
```
1. Open a terminal.
2. Go to the directory where the files is located.
```
cd yyy
```
3. Execute the following command.
```
tcal -a xxx.gjf
```

### 3. Visualization of molecular orbitals
1. Execute the following command.
```
tcal -cr xxx.gjf
```
2. Open xxx.fchk in GaussView.
3. [Results] &rarr; [Surfaces/Contours...]
![visualize1](img/visualize1.png)  
4. [Cube Actions] &rarr; [Load Cube]
5. Open xxx_m1_HOMO.cube and xxx_m2_HOMO.cube.
![visualize2](img/visualize2.png)  
6. Visualize by operating [Surface Actions] &rarr; [New Surface].
![visualize3](img/visualize3.png)  
![visualize4](img/visualize4.png)  

## 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 use basis sets from Basis Set Exchange (e.g., def2-TZVP, cc-pVDZ):
```
tcal --pyscf --bse -M "B3LYP/def2-TZVP" -a xxx.xyz
```
To read from existing checkpoint files without re-running calculations:
```
tcal --pyscf -ar xxx.xyz
```

## Using ORCA
### 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 --orca -a xxx.xyz
```
To specify a calculation method and basis set:
```
tcal --orca -M "B3LYP/6-31G(d,p)" -a xxx.xyz
```
To read from existing output files without re-running calculations:
```
tcal --orca -ar xxx.xyz
```

### Parallel execution
To use multiple CPU cores (`--cpu N`), OpenMPI must be installed.
First, confirm that `mpirun` is available:
```bash
which mpirun
```
If OpenMPI is already in `$PATH` and `$LD_LIBRARY_PATH` (common on Linux/WSL after `apt install`), no further configuration is needed.

If parallel execution does not work, find the OpenMPI base directory (the directory that contains `bin/` and `lib/`) and pass it via `OPI_MPI` or `--mpi`.

#### Linux / WSL
> **Note:** ORCA requires a specific version of OpenMPI. The version available via `apt` may not match. If parallel execution fails, it is recommended to build OpenMPI from source using the version specified in the [ORCA documentation](https://www.faccts.de/docs/orca/6.0/manual/).

When `mpirun` is installed under a dedicated directory (e.g., built from source or via a module system):
```bash
which mpirun
# e.g., /opt/openmpi/bin/mpirun  →  base: /opt/openmpi
export OPI_MPI=$(dirname $(dirname $(which mpirun)))
```
When installed system-wide via `apt` (Ubuntu/Debian), `mpirun` is typically at `/usr/bin/mpirun` but the OpenMPI libraries live under `/usr/lib/`. Check with:
```bash
which mpirun
# /usr/bin/mpirun  →  base is usually /usr/lib/x86_64-linux-gnu/openmpi
export OPI_MPI=/usr/lib/x86_64-linux-gnu/openmpi
```

#### macOS (Homebrew)
```bash
which mpirun
# e.g., /opt/homebrew/bin/mpirun
export OPI_MPI=$(brew --prefix open-mpi)
```

#### Passing the path with `--mpi`
Instead of setting the environment variable, you can pass the path directly:
```bash
tcal --orca --cpu 8 --mpi /path/to/openmpi -a 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.  
[4] Benjamin P. Pritchard et al., New Basis Set Exchange: An Open, Up-to-Date Resource for the Molecular Sciences Community, *J. Chem. Inf. Model.* **2019**, *59*, 4814-4820.  
[5] Frank Neese, The ORCA program system, *Wiley Interdiscip. Rev. Comput. Mol. Sci.*, **2012**, *2*, 73-78.  

# 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](https://doi.org/10.1080/14686996.2024.2354652)  

# Example of using tcal
1. [Satoru Inoue et al., Regioisomeric control of layered crystallinity in solution-processable organic semiconductors, *Chem. Sci.* **2020**, *11*, 12493-12505.](https://pubs.rsc.org/en/content/articlelanding/2020/SC/D0SC04461J)  
2. [Toshiki Higashino et al., Architecting Layered Crystalline Organic Semiconductors Based on Unsymmetric π-Extended Thienoacenes, *Chem. Mater.* **2021**, *33*, 18, 7379–7385.](https://pubs.acs.org/doi/10.1021/acs.chemmater.1c01972)  
3. [Koki Ozawa et al., Statistical analysis of interatomic transfer integrals for exploring high-mobility organic semiconductors, *Sci. Technol. Adv. Mater.* **2024**, *25*, 2354652.](https://doi.org/10.1080/14686996.2024.2354652)  

# Authors
[Matsui Laboratory, Research Center for Organic Electronics (ROEL), Yamagata University](https://matsui-lab.yz.yamagata-u.ac.jp/index-e.html)  
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.  
