=========================================================== tcal Documentation =========================================================== .. image:: https://img.shields.io/badge/python-3.9%20or%20newer-blue :target: https://www.python.org :alt: Python .. image:: https://img.shields.io/badge/License-MIT-blue.svg :target: https://opensource.org/licenses/MIT :alt: License: MIT 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) ----------------------------------------- .. code-block:: bash pip install yu-tcal Using PySCF (CPU only, macOS / Linux / WSL2) ---------------------------------------------- .. code-block:: bash pip install "yu-tcal[pyscf]" Using GPU acceleration with PySCF (macOS / Linux / WSL2) ---------------------------------------------------------- 1. Check your installed CUDA Toolkit version: .. code-block:: bash nvcc --version 2. Install tcal with GPU acceleration: If your CUDA Toolkit version is 12.x: .. code-block:: bash pip install "yu-tcal[gpu4pyscf-cuda12]" If your CUDA Toolkit version is 11.x: .. code-block:: bash pip install "yu-tcal[gpu4pyscf-cuda11]" Verify Installation ------------------- After installation, you can verify by running: .. code-block:: bash tcal --help Options ======= .. list-table:: :header-rows: 1 :widths: 10 15 75 * - 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 .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/gjf_file_example.png :alt: gjf file example 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. .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/Anthracene_dimer.png :alt: Anthracene dimer 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: .. code-block:: text yyy └── xxx.gjf 1. Open a terminal. 2. Go to the directory where the files is located. .. code-block:: bash cd yyy 3. Execute the following command. .. code-block:: bash tcal -a xxx.gjf 3. Visualization of molecular orbitals ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Execute the following command. .. code-block:: bash tcal -cr xxx.gjf 2. Open xxx.fchk in GaussView. 3. [Results] → [Surfaces/Contours...] .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/visualize1.png :alt: Visualize 1 4. [Cube Actions] → [Load Cube] 5. Open xxx_m1_HOMO.cube and xxx_m2_HOMO.cube. .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/visualize2.png :alt: Visualize 2 6. Visualize by operating [Surface Actions] → [New Surface]. .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/visualize3.png :alt: Visualize 3 .. image:: https://raw.githubusercontent.com/matsui-lab-yamagata/tcal/main/img/visualize4.png :alt: Visualize 4 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 ~~~~~~~~~~~~~~~~ .. code-block:: bash tcal --pyscf -a xxx.xyz To specify a calculation method and basis set: .. code-block:: bash tcal --pyscf -M "B3LYP/6-31G(d,p)" -a xxx.xyz To use GPU acceleration: .. code-block:: bash tcal --gpu4pyscf -M "B3LYP/6-31G(d,p)" -a xxx.xyz To read from existing checkpoint files without re-running calculations: .. code-block:: bash 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 :math:`\ket{A}` and :math:`\ket{B}` were obtained from the monomer calculations. Fock matrix F was calculated in the dimer system. Finally the intermolecular transfer integral :math:`t^{[1]}` was calculated by using the following equation: .. math:: t = \frac{\braket{A|F|B} - \frac{1}{2} (\epsilon_{A}+\epsilon_{B})\braket{A|B}}{1 - \braket{A|B}^2}, where :math:`\epsilon_A \equiv \braket{A|F|A}` and :math:`\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 :math:`^{[2]}`. By grouping the basis functions :math:`\ket{i}` and :math:`\ket{j}` for each atom, the molecular orbitals can be expressed as .. math:: \ket{A} = \sum^A_{\alpha} \sum^{\alpha}_i a_i \ket{i}, .. math:: \ket{B} = \sum^B_{\beta} \sum^{\beta}_j b_j \ket{j}, where :math:`\alpha` and :math:`\beta` are the indices of atoms, :math:`i` and :math:`j` are indices of basis functions, and :math:`a_i` and :math:`b_j` are the coefficients of basis functions. Substituting this formula into aforementioned equation gives .. math:: 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 :math:`u_{\alpha\beta}` as: .. math:: 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 ====================== 1. `Satoru Inoue et al., Regioisomeric control of layered crystallinity in solution-processable organic semiconductors, Chem. Sci. 2020, 11, 12493-12505. `_ 2. `Toshiki Higashino et al., Architecting Layered Crystalline Organic Semiconductors Based on Unsymmetric π-Extended Thienoacenes, Chem. Mater. 2021, 33, 18, 7379-7385. `_ 3. `Koki Ozawa et al., Statistical analysis of interatomic transfer integrals for exploring high-mobility organic semiconductors, Sci. Technol. Adv. Mater. 2024, 25, 2354652. `_ API Reference ============= .. toctree:: :maxdepth: 2 :caption: API Reference modules Indices and Tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 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 `_.