================================== mcal |version| documentation ================================== .. image:: https://img.shields.io/badge/python-3.11%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 .. image:: https://img.shields.io/pypi/v/yu-mcal :target: https://pypi.org/project/yu-mcal/ :alt: PyPI Overview ======== ``mcal`` is a tool for calculating mobility tensors of organic semiconductors. It calculates transfer integrals and reorganization energy from crystal structures (CIF files), and determines mobility tensors considering anisotropy and path continuity. Features -------- * Read crystal structures from CIF files * Quantum chemical calculations using Gaussian 09/16, PySCF, or ORCA * Calculation of transfer integrals * Calculation of reorganization energy * Computation of mobility tensors and eigenvalues Requirements ============ * Python 3.11 or newer * NumPy * Pandas * Matplotlib * yu-tcal>=5.0.2 Quantum Chemistry Calculation Tools ------------------------------------ At least one of the following is required: * Gaussian 09 or 16 * PySCF (macOS / Linux / WSL2(Windows Subsystem for Linux)) * GPU4PySCF (macOS / Linux / WSL2(Windows Subsystem for Linux)) * ORCA 6.1.0 or newer .. important:: When using Gaussian, the path to Gaussian must be set in your environment. PySCF is supported on macOS / Linux. Windows users must use WSL2. Installation ============ Using Gaussian 09 or 16 (without PySCF) ---------------------------------------- .. code-block:: bash pip install yu-mcal Using PySCF (CPU only, macOS / Linux / WSL2) --------------------------------------------- .. code-block:: bash pip install "yu-mcal[pyscf]" Using GPU acceleration with PySCF (macOS / Linux / WSL2) --------------------------------------------------------- 1. Check your installed CUDA Toolkit version: .. code-block:: bash nvcc --version 2. Install mcal with GPU acceleration: If your CUDA Toolkit version is 13.x: .. code-block:: bash pip install "yu-mcal[gpu4pyscf-cuda13]" If your CUDA Toolkit version is 12.x: .. code-block:: bash pip install "yu-mcal[gpu4pyscf-cuda12]" If your CUDA Toolkit version is 11.x: .. code-block:: bash pip install "yu-mcal[gpu4pyscf-cuda11]" Using ORCA 6.1.0 or newer -------------------------- .. code-block:: bash pip install "yu-mcal[orca]" Verify Installation ------------------- After installation, you can verify by running: .. code-block:: bash mcal --help mcal Usage Manual ================= Basic Usage ----------- .. code-block:: bash mcal [options] Required Arguments ~~~~~~~~~~~~~~~~~~ * ``cif_filename``: Path to the CIF file * ``pkl_filename``: Path to the pickle file * ``osc_type``: Organic semiconductor type * ``p``: p-type semiconductor (uses HOMO level) * ``n``: n-type semiconductor (uses LUMO level) Basic Examples ~~~~~~~~~~~~~~ .. code-block:: bash # Calculate as p-type semiconductor mcal xxx.cif p # Calculate as n-type semiconductor mcal xxx.cif n Options ------- The table below lists all available options. See the sections that follow for details. .. list-table:: :header-rows: 1 :widths: 8 26 66 * - Short - Long - Explanation * - ``-c`` - ``--cpu N`` - Set the number of CPUs. (default: 4) * - ``-g`` - ``--g09`` - Use Gaussian 09. (default is Gaussian 16) * - ``-h`` - ``--help`` - Show options description. * - ``-j`` - ``--json`` - Save calculation results to a JSON file. * - ``-m`` - ``--mem N`` - Set the memory size in GB. (default: 10) * - ``-p`` - ``--pickle`` - Save calculation results to a pickle file. * - ``-r`` - ``--read`` - Read results from existing files (Gaussian log / PySCF ``.chk`` / ORCA ``.out``) without executing calculations. * - ``-rp`` - ``--read_pickle`` - Read results from an existing pickle file without executing calculations. * - ``-M`` - ``--method METHOD/BASIS`` - Calculation method and basis set in "METHOD/BASIS" format. (default: ``B3LYP/6-31G(d,p)``) * - - ``--pyscf`` - Use PySCF instead of Gaussian. * - - ``--gpu4pyscf`` - Use GPU acceleration via gpu4pyscf. Automatically enables PySCF mode. * - - ``--cart`` - Use Cartesian basis functions instead of spherical harmonics. (PySCF only) * - - ``--bse`` - Use Basis Set Exchange to obtain basis sets. (PySCF only) * - - ``--orca`` - Use ORCA instead of Gaussian. * - - ``--mpi PATH`` - Path to OpenMPI installation directory for ORCA parallel execution (sets the ``OPI_MPI`` environment variable). (ORCA only) * - - ``--resume`` - Resume calculation using existing results. * - - ``--fullcal`` - Disable pair screening and monomer caching, and calculate all pairs and monomers from scratch. * - - ``--no-monomer-cache`` - Disable monomer caching only. Pair screening remains active. * - - ``--cellsize N`` - Number of unit cells to expand in each direction around the central unit cell. (default: 2, i.e. a 5×5×5 supercell) * - - ``--2d PLANE`` - Restrict the supercell expansion to the specified crystallographic plane (``ab``, ``ac``, ``ba``, ``bc``, ``ca``, ``cb``) and skip out-of-plane transfer integrals. * - - ``--plot-plane PLANE`` - Plot the mobility tensor as a 2D polar plot on the specified crystallographic plane (``ab``, ``ac``, ``ba``, ``bc``, ``ca``, ``cb``). Calculation Settings ~~~~~~~~~~~~~~~~~~~~ ``-M, --method `` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Specify the calculation method (used in both Gaussian and PySCF calculations). * **Default**: ``B3LYP/6-31G(d,p)`` * **Example**: ``mcal xxx.cif p -M "B3LYP/6-31G(d)"`` ``-c, --cpu `` ^^^^^^^^^^^^^^^^^^^^^^ Specify the number of CPUs to use. * **Default**: ``4`` * **Example**: ``mcal xxx.cif p -c 8`` ``-m, --mem `` ^^^^^^^^^^^^^^^^^^^^^^ Specify the amount of memory in GB. * **Default**: ``10`` * **Example**: ``mcal xxx.cif p -m 16`` ``-g, --g09`` ^^^^^^^^^^^^^ Use Gaussian 09 (default is Gaussian 16). * **Example**: ``mcal xxx.cif p -g`` PySCF Settings ~~~~~~~~~~~~~~ ``--pyscf`` ^^^^^^^^^^^^ Use PySCF instead of Gaussian for all calculations. Requires ``yu-mcal[pyscf]``. * **Example**: ``mcal xxx.cif p --pyscf`` ``--gpu4pyscf`` ^^^^^^^^^^^^^^^^ Use GPU acceleration via gpu4pyscf. Automatically enables PySCF mode (no need to specify ``--pyscf``). Requires ``yu-mcal[gpu4pyscf-cuda11]`` or ``yu-mcal[gpu4pyscf-cuda12]``. * **Example**: ``mcal xxx.cif p --gpu4pyscf`` ``--cart`` ^^^^^^^^^^^ Use Cartesian basis functions instead of spherical harmonics (PySCF only). * **Example**: ``mcal xxx.cif p --pyscf --cart`` ``--bse`` ^^^^^^^^^ Use Basis Set Exchange for basis-set definitions (PySCF only). * **Example**: ``mcal xxx.cif p --pyscf --bse -M "B3LYP/def2-SVP"`` ORCA Settings ~~~~~~~~~~~~~ ``--orca`` ^^^^^^^^^^ Use ORCA instead of Gaussian for all calculations. Requires ``yu-mcal[orca]``. * **Example**: ``mcal xxx.cif p --orca`` ``--mpi `` ^^^^^^^^^^^^^^^^ Specify the path to the OpenMPI installation directory for ORCA parallel execution. This sets the ``OPI_MPI`` environment variable used by the ORCA Python Interface (OPI). Only valid with ``--orca``. * **Example**: ``mcal xxx.cif p --orca --mpi /usr/lib/x86_64-linux-gnu/openmpi`` Parallel Execution ^^^^^^^^^^^^^^^^^^ To use multiple CPU cores (``--cpu N``), OpenMPI must be installed. First, confirm that ``mpirun`` is available: .. code-block:: 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 `_. When ``mpirun`` is installed under a dedicated directory (e.g., built from source or via a module system): .. code-block:: 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: .. code-block:: 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) """""""""""""""" .. code-block:: 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: .. code-block:: bash mcal xxx.cif p --orca -c 8 --mpi /path/to/openmpi Calculation Control ~~~~~~~~~~~~~~~~~~~ ``-r, --read`` ^^^^^^^^^^^^^^ Read results from existing files without executing calculations. With Gaussian, reads from log files; with PySCF, reads from checkpoint (``.chk``) files; with ORCA, reads from output (``.out``) files. * **Example**: ``mcal xxx.cif p -r`` ``-rp, --read_pickle`` ^^^^^^^^^^^^^^^^^^^^^^ Read results from existing pickle file without executing calculations. * **Example**: ``mcal xxx_result.pkl p -rp`` ``--resume`` ^^^^^^^^^^^^ Resume calculation using existing results. With Gaussian, checks log file termination; with PySCF, checks for existing checkpoint (``.chk``) files; with ORCA, checks ``.out`` file termination. * **Example**: ``mcal xxx.cif p --resume`` ``--fullcal`` ^^^^^^^^^^^^^ Disable all speedup processing and calculate transfer integrals for all pairs from scratch. The following two optimizations are disabled: 1. **Pair screening**: pairs are normally skipped based on moment of inertia and center-of-mass distance; ``--fullcal`` disables this screening. 2. **Monomer caching**: monomer SCF calculations for the same molecule type are normally skipped by reusing a previously computed result file; ``--fullcal`` forces all monomer calculations to be performed from scratch. * **Example**: ``mcal xxx.cif p --fullcal`` ``--no-monomer-cache`` ^^^^^^^^^^^^^^^^^^^^^^ Disable only monomer caching. Pair screening remains active. All monomer SCF calculations are performed from scratch instead of reusing previously computed result files. When performing detailed transfer integral analysis using `tcal `_, it is recommended to use this option. * **Example**: ``mcal xxx.cif p --no-monomer-cache`` ``--cellsize `` ^^^^^^^^^^^^^^^^^^^^^^^ Specify the number of unit cells to expand in each direction around the central unit cell for transfer integral calculations. * **Default**: ``2`` (creates 5x5x5 supercell) * **Examples**: * ``mcal xxx.cif p --cellsize 1`` (creates 3x3x3 supercell) * ``mcal xxx.cif p --cellsize 3`` (creates 7x7x7 supercell) ``--2d `` ^^^^^^^^^^^^^^^^ Restrict the supercell expansion to a crystallographic plane so that out-of-plane transfer integrals are skipped. This speeds up calculations for layered crystals. The supercell shape follows from combining ``--cellsize`` with ``--2d``: with the default ``--cellsize 2``, ``--2d ab`` produces a 5x5x1 supercell instead of 5x5x5. Mobility perpendicular to the selected plane is zero by construction. This option is distinct from ``--plot-plane``, which only controls the polar plot and does not change which transfer integrals are calculated. * **Available planes**: ``ab``, ``ac``, ``ba``, ``bc``, ``ca``, ``cb`` * **Default**: None (isotropic 3D expansion) * **Example**: ``mcal xxx.cif p --2d ab`` Output Settings ~~~~~~~~~~~~~~~ ``-p, --pickle`` ^^^^^^^^^^^^^^^^ Save calculation results to a pickle file. * **Example**: ``mcal xxx.cif p -p`` ``-j, --json`` ^^^^^^^^^^^^^^ Save calculation results to a JSON file (``_result.json``). Contains reorganization energy (with intermediate energies), transfer integrals, diffusion coefficient tensor, mobility tensor, eigenvalues, and eigenvectors, along with metadata (mcal version, method, backend). Can be combined with ``-p``. * **Example**: ``mcal xxx.cif p -j`` ``--plot-plane `` ^^^^^^^^^^^^^^^^^^^^^^^^^ Plot mobility tensor as a 2D polar plot on specified crystallographic plane. * **Available planes**: ``ab``, ``ac``, ``ba``, ``bc``, ``ca``, ``cb`` * **Default**: None (no plot generated) * **Examples**: * ``mcal xxx.cif p --plot-plane ab`` (plot on ab-plane) * ``mcal xxx.cif p --plot-plane bc`` (plot on bc-plane) Practical Usage Examples ------------------------- Basic Calculations ~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Calculate mobility of p-type xxx mcal xxx.cif p # Use 8 CPUs and 16GB memory mcal xxx.cif p -c 8 -m 16 High-Precision Calculations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Calculate transfer integrals for all pairs (high precision, time-consuming) mcal xxx.cif p --fullcal # Use larger supercell to widen transfer integral calculation range mcal xxx.cif p --cellsize 3 # Use different basis set mcal xxx.cif p -M "B3LYP/6-311G(d,p)" PySCF Calculations ~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Calculate using PySCF (CPU) mcal xxx.cif p --pyscf # Calculate using PySCF with GPU acceleration (no --pyscf needed) mcal xxx.cif p --gpu4pyscf # Use 8 CPUs and 16GB memory with PySCF mcal xxx.cif p --pyscf -c 8 -m 16 # Use Basis Set Exchange with --method in PySCF mode mcal xxx.cif p --pyscf --bse -M "B3LYP/def2-SVP" # Resume interrupted PySCF calculation mcal xxx.cif p --pyscf --resume # Read from existing PySCF checkpoint files mcal xxx.cif p --pyscf -r ORCA Calculations ~~~~~~~~~~~~~~~~~ .. code-block:: bash # Calculate using ORCA mcal xxx.cif p --orca # Use 8 CPUs and 16GB memory with ORCA mcal xxx.cif p --orca -c 8 -m 16 # Specify OpenMPI path for ORCA parallel execution mcal xxx.cif p --orca --mpi /usr/lib/x86_64-linux-gnu/openmpi # Resume interrupted ORCA calculation mcal xxx.cif p --orca --resume # Read from existing ORCA output files mcal xxx.cif p --orca -r Reusing Results ~~~~~~~~~~~~~~~ .. code-block:: bash # Read from existing calculation results mcal xxx.cif p -r # Read from existing pickle file mcal xxx_result.pkl p -rp # Resume interrupted calculation mcal xxx.cif p --resume # Save results to pickle file mcal xxx.cif p -p Output ------ Standard Output ~~~~~~~~~~~~~~~ * Reorganization energy * Transfer integrals for each pair * Diffusion coefficient tensor * Mobility tensor * Eigenvalues and eigenvectors of mobility Generated Files ~~~~~~~~~~~~~~~ Reorganization Energy Files ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following files are generated during reorganization energy calculation (``c`` = cation for p-type, ``a`` = anion for n-type): **Gaussian:** * ``xxx_opt_n.gjf`` / ``xxx_opt_n.log`` — geometry optimization of neutral molecule * ``xxx_c.gjf`` / ``xxx_c.log`` (or ``xxx_a``) — SP energy of ion at neutral geometry * ``xxx_opt_c.gjf`` / ``xxx_opt_c.log`` (or ``xxx_opt_a``) — geometry optimization of ion * ``xxx_n.gjf`` / ``xxx_n.log`` — SP energy of neutral at ion geometry **PySCF:** * ``xxx_opt_n.xyz`` / ``xxx_opt_n.chk`` — geometry optimization of neutral molecule * ``xxx_c.chk`` (or ``xxx_a.chk``) — SP energy of ion at neutral geometry * ``xxx_opt_c.xyz`` / ``xxx_opt_c.chk`` (or ``xxx_opt_a``) — geometry optimization of ion * ``xxx_n.chk`` — SP energy of neutral at ion geometry **ORCA:** * ``xxx_opt_n_input.xyz`` / ``xxx_opt_n.out`` / ``xxx_opt_n.xyz`` — geometry optimization of neutral molecule * ``xxx_c_input.xyz`` / ``xxx_c.out`` (or ``xxx_a``) — SP energy of ion at neutral geometry * ``xxx_opt_c_input.xyz`` / ``xxx_opt_c.out`` / ``xxx_opt_c.xyz`` (or ``xxx_opt_a``) — geometry optimization of ion * ``xxx_n_input.xyz`` / ``xxx_n.out`` — SP energy of neutral at ion geometry Transfer Integral Files ^^^^^^^^^^^^^^^^^^^^^^^ mcal generates calculation files named using the ``(s_t_i_j_k)`` notation (Gaussian and PySCF). For ORCA, the ``@s_t_i_j_k`` notation is used instead because ORCA cannot handle parentheses in filenames. .. list-table:: :header-rows: 1 * - Symbol - Meaning * - ``s`` - Molecule index in the reference unit cell (0,0,0) * - ``t`` - Molecule index in the neighboring unit cell * - ``i`` - Translation index along the **a**-axis * - ``j`` - Translation index along the **b**-axis * - ``k`` - Translation index along the **c**-axis **Example (Gaussian / PySCF):** ``xxx-(0_0_1_0_0)`` represents the transfer integral between the 0th molecule in the (0,0,0) cell and the 0th molecule in the (1,0,0) cell. **Example (ORCA):** ``xxx@0_0_1_0_0`` represents the same pair as above. **Gaussian:** * ``xxx-(s_t_i_j_k).gjf`` / ``xxx-(s_t_i_j_k).log`` — dimer * ``xxx-(s_t_i_j_k)_m1.gjf`` / ``xxx-(s_t_i_j_k)_m1.log`` — monomer 1 * ``xxx-(s_t_i_j_k)_m2.gjf`` / ``xxx-(s_t_i_j_k)_m2.log`` — monomer 2 **PySCF:** * ``xxx-(s_t_i_j_k).xyz`` / ``xxx-(s_t_i_j_k).chk`` — dimer * ``xxx-(s_t_i_j_k)_m1.chk`` — monomer 1 * ``xxx-(s_t_i_j_k)_m2.chk`` — monomer 2 **ORCA:** * ``xxx@s_t_i_j_k.xyz`` / ``xxx@s_t_i_j_k.out`` — dimer * ``xxx@s_t_i_j_k_m1.out`` — monomer 1 * ``xxx@s_t_i_j_k_m2.out`` — monomer 2 Notes ----- .. note:: 1. **Calculation Time**: Calculation time varies significantly depending on the number of molecules and cell size. By default, two speedup mechanisms are enabled: pair pre-screening (skipping pairs unlikely to have significant transfer integrals) and monomer caching (reusing the isolated-molecule SCF result for molecule types already computed). Use ``--fullcal`` to disable both. 2. **Memory Usage**: Ensure sufficient memory for large systems 3. **Gaussian Installation**: Gaussian 09 or Gaussian 16 is required 4. **Dependencies**: Make sure all required Python libraries are installed Troubleshooting --------------- If calculation stops midway ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Resume with --resume option mcal xxx.cif p --resume Memory shortage error ~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Increase memory amount mcal xxx.cif p -m 32 To reduce calculation time ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # Enable speedup processing (default) mcal xxx.cif p # Use smaller supercell for faster calculation mcal xxx.cif p --cellsize 1 # Increase number of CPUs mcal xxx.cif p -c 16 If a CIF file cannot be read ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CIF files come in various formats, and some may not be readable by mcal. Please try the following: 1. **Convert the CIF format using another software**: Use software such as `Mercury `_ to open the CIF file and re-export it, which may resolve the issue. 2. **Contact us**: If you send the unreadable CIF file to us by email, we will work on adding support for it. Please contact us at the email address listed in the Authors section below. Authors ======= `Matsui Laboratory, Research Center for Organic Electronics (ROEL), Yamagata University `_ * Koki Ozawa * Hiroyuki Matsui Email: h-matsui[at]yz.yamagata-u.ac.jp (Please replace ``[at]`` with ``@``) License ======= This project is released under the MIT License. For more details, see the `LICENSE file on GitHub `_. Acknowledgements ================ This work was supported by JSPS Grant-in-Aid for JSPS Fellows Grant Number JP25KJ0647. References ========== * [1] Qiming Sun et al., Recent developments in the PySCF program package, *J. Chem. Phys.* **2020**, *153*, 024109. * [2] Lee-Ping Wang, Chenchen Song, Geometry optimization made simple with translation and rotation coordinates, *J. Chem. Phys.* **2016**, *144*, 214108. * [3] 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. * [4] Frank Neese, The ORCA program system, *Wiley Interdiscip. Rev. Comput. Mol. Sci.*, **2012**, *2*, 73-78. API Reference ============= .. toctree:: :maxdepth: 2 :caption: API Reference modules Indices and Tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`