mcal Documentation

Python License: MIT

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

  • Calculation of transfer integrals

  • Calculation of reorganization energy

  • Computation of mobility tensors and eigenvalues

Requirements

  • Python 3.9 or newer

  • NumPy

  • Pandas

  • Matplotlib

  • yu-tcal==3.1.0

  • Gaussian 09 or 16

Important

The path to Gaussian must be set in your environment.

Installation

pip install yu-mcal

Verify Installation

After installation, you can verify by running:

mcal --help

mcal Usage Manual

Basic Usage

mcal <cif_filename or pkl_filename> <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

Calculation Control

-r, --read

Read results from existing log files without executing Gaussian.

  • 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 if log files terminated normally.

  • Example: mcal xxx.cif p --resume

--fullcal

Disable speedup processing using moment of inertia and distance between centers of weight, and calculate transfer integrals for all pairs.

  • Example: mcal xxx.cif p --fullcal

--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 5x5x5 supercell)

  • Examples:

    • mcal xxx.cif p --cellsize 1 (creates 3x3x3 supercell)

    • mcal xxx.cif p --cellsize 3 (creates 7x7x7 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)

Diffusion Coefficient Calculation Methods

--mc

Calculate diffusion coefficient tensor using kinetic Monte Carlo method.

  • Example: mcal xxx.cif p --mc

--ode

Calculate diffusion coefficient tensor using Ordinary Differential Equation method.

  • Example: mcal xxx.cif p --ode

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

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

Comparing Diffusion Coefficients

# Compare with normal calculation + kinetic Monte Carlo + ODE methods
mcal xxx.cif p --mc --ode

Output

Standard Output

  • Reorganization energy

  • Transfer integrals for each pair

  • Diffusion coefficient tensor

  • Mobility tensor

  • Eigenvalues and eigenvectors of mobility

Notes

Note

  1. Calculation Time: Calculation time varies significantly depending on the number of molecules and cell size

  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

API Reference

API Reference

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

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.