Metadata-Version: 2.4
Name: yu-mcal
Version: 0.2.1
Summary: Program for the calculation of mobility tensor for organic semiconductor crystals
Author: Koki Ozawa
Author-email: Hiroyuki Matsui <h-matsui@yz.yamagata-u.ac.jp>
License: MIT License
        
        Copyright (c) 2025 Hiroyuki Matsui
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: mobility,mobility tensor,organic semiconductor,reorganization energy,transfer integral
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: numpy>=2.0.2
Requires-Dist: pandas>=2.3.3
Requires-Dist: yu-tcal==3.1.0
Description-Content-Type: text/markdown

# mcal: Program for the calculation of mobility tensor for organic semiconductor crystals
[![Python](https://img.shields.io/badge/python-3.9%20or%20newer-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![docs](https://img.shields.io/badge/docs-here-11419572)](https://matsui-lab-yamagata.github.io/mcal/)

# Overview
`mcal.py` 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.9 or newer
* NumPy
* Pandas
* Matplotlib
* yu-tcal==3.1.0
* Gaussian 09 or 16

# Important notice
* The path of the Gaussian must be set.

# Installation
```bash
pip install yu-mcal
```


## Verify Installation

After installation, you can verify by running:

```bash
mcal --help
```

# mcal Usage Manual

## Basic Usage

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

```bash
# 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 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)

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

### Reusing Results
```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
```

### Comparing Diffusion Coefficients
```bash
# 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

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
```bash
# Resume with --resume option
mcal xxx.cif p --resume
```

### Memory shortage error
```bash
# Increase memory amount
mcal xxx.cif p -m 32
```

### To reduce calculation time
```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
``` 

# Authors
[Matsui Laboratory, Research Center for Organic Electronics (ROEL), Yamagata University](https://matsui-lab.yz.yamagata-u.ac.jp/index-e.html)  
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.  
