Skip to content
Back to top
View this page

# mcal Documentation

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

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

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

- mcal
  - mcal package

## Indices and Tables

- Index

- Module Index

- Search Page

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