yu-mcal 0.6.0

Program for the calculation of mobility tensor for organic semiconductor crystals

mcal: Program for the calculation of mobility tensor for organic semiconductor crystals

Overview

mcal is a tool for calculating mobility tensors of organic semiconductors. It calculates transfer integrals and reorganization energy from crystal structures, and determines mobility tensors considering anisotropy and path continuity.

Requirements

• Python 3.11 or newer
• NumPy
• Pandas
• Matplotlib
• yu-tcal==5.0.1

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 notice

• When using Gaussian, the path of the Gaussian must be set.
• PySCF is supported on macOS / Linux. Windows users must use WSL2.

Installation

Using Gaussian 09 or 16 (without PySCF)

pip install yu-mcal

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

pip install "yu-mcal[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-mcal[gpu4pyscf-cuda13]"

If your CUDA Toolkit version is 12.x, install tcal with GPU acceleration:

pip install "yu-mcal[gpu4pyscf-cuda12]"

If your CUDA Toolkit version is 11.x, install tcal with GPU acceleration:

pip install "yu-mcal[gpu4pyscf-cuda11]"

Using ORCA 6.1.0 or newer

pip install "yu-mcal[orca]"

Verify Installation

After installation, you can verify by running:

mcal --help

mcal Usage Manual

Basic Usage

mcal <cif_filename or pkl_filenname> <osc_type> [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

# Calculate as p-type semiconductor
mcal xxx.cif p

# Calculate as n-type semiconductor
mcal xxx.cif n

Options

Calculation Settings

-M, --method <method>

Specify the calculation method used in Gaussian calculations.

• Default: B3LYP/6-31G(d,p)
• Example: mcal xxx.cif p -M "B3LYP/6-31G(d)"

-c, --cpu <number>

Specify the number of CPUs to use.

• Default: 4
• Example: mcal xxx.cif p -c 8

-m, --mem <memory>

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 <path>

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:

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):

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:

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)

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:

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 <number>

Specify the number of unit cells to expand in each direction around the central unit cell for transfer integral calculations.

• Default: 2 (creates 5×5×5 supercell)
• Examples:
  • mcal xxx.cif p --cellsize 1 (creates 3×3×3 supercell)
  • mcal xxx.cif p --cellsize 3 (creates 7×7×7 supercell)

Output Settings

-p, --pickle

Save calculation results to a pickle file.

• Example: mcal xxx.cif p -p

--plot-plane <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

# 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

# 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

# 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

# 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

# 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 (where 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:

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

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

# Resume with --resume option
mcal xxx.cif p --resume

Memory shortage error

# Increase memory amount
mcal xxx.cif p -m 32

To reduce calculation time

# 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 below.

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 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.