yu-mcal 0.1.0__tar.gz

yu_mcal-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+__pycache__/
+.venv/
+
+test*
+*.egg-info/
+/build/
+.buildinfo
+.doctrees/
+.pypirc
+/dist/

yu_mcal-0.1.0/.python-version

@@ -0,0 +1 @@
+3.9

yu_mcal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

yu_mcal-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: yu-mcal
+Version: 0.1.0
+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: numpy>=2.0.2
+Requires-Dist: pandas>=2.3.3
+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)
+
+# 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
+* 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`
+
+### 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 @  

yu_mcal-0.1.0/README.md

@@ -0,0 +1,211 @@
+# 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)
+
+# 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
+* 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`
+
+### 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 @  

yu_mcal-0.1.0/README_ja.md

@@ -0,0 +1,211 @@
+# mcal: 有機半導体結晶の移動度テンソル計算プログラム
+[![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)
+
+# 概要
+`mcal.py`は有機半導体の移動度テンソルを計算するツールです。結晶構造から移動積分と再配列エネルギーを計算し、異方性と経路の連続性を考慮して移動度テンソルを算出します。
+
+# 必要環境
+* Python 3.9以降
+* NumPy
+* Pandas
+* Gaussian 09または16
+
+# 注意事項
+* Gaussianのパスが設定されている必要があります。
+
+# インストール
+```bash
+pip install yu-mcal
+```
+
+
+## インストールの確認
+
+インストール後、以下のコマンドで確認できます：
+
+```bash
+mcal --help
+```
+
+# mcal 使用マニュアル
+
+## 基本的な使用方法
+
+```bash
+mcal <cif_filename or pkl_filename> <osc_type> [オプション]
+```
+
+### 必須引数
+
+- `cif_filename`: CIFファイルのパス
+- `pkl_filename`: pickleファイルのパス
+- `osc_type`: 何型の有機半導体として計算するか
+  - `p`: p型半導体 (移動積分にHOMOを使用)
+  - `n`: n型半導体 (移動積分にLUMOを使用)
+
+### 基本例
+
+```bash
+# p型半導体として計算
+mcal xxx.cif p
+
+# n型半導体として計算
+mcal xxx.cif n
+```
+
+## オプション
+
+### 計算設定
+
+#### `-M, --method <method>`
+Gaussianで使用する計算手法を指定します。
+- **デフォルト**: `B3LYP/6-31G(d,p)`
+- **例**: `mcal xxx.cif p -M "B3LYP/6-31G(d)"`
+
+#### `-c, --cpu <number>`
+使用するCPU数を指定します。
+- **デフォルト**: `4`
+- **例**: `mcal xxx.cif p -c 8`
+
+#### `-m, --mem <memory>`
+メモリ量をGB単位で指定します。
+- **デフォルト**: `10`
+- **例**: `mcal xxx.cif p -m 16`
+
+#### `-g, --g09`
+Gaussian 09を使用します（デフォルトはGaussian 16）。
+- **例**: `mcal xxx.cif p -g`
+
+### 計算制御
+
+#### `-r, --read`
+Gaussianを実行せずに既存のlogファイルから結果を読み取ります。
+- **例**: `mcal xxx.cif p -r`
+
+#### `-rp, --read_pickle`
+計算を実行せずに既存のpickleファイルから結果を読み取ります。
+- **例**: `mcal xxx_result.pkl p -rp`
+
+#### `--resume`
+ログファイルが正常に終了している場合、既存の結果を使用して計算を再開します。
+- **例**: `mcal xxx.cif p --resume`
+
+#### `--fullcal`
+慣性モーメントと重心間距離を使用した高速化処理を無効にし、すべてのペアに対して移動積分を計算します。
+- **例**: `mcal xxx.cif p --fullcal`
+
+#### `--cellsize <number>`
+移動積分計算のために中央単位格子の周りに各方向に拡張する単位格子数を指定します。
+- **デフォルト**: `2`（5×5×5のスーパーセルを作成）
+- **例**: 
+  - `mcal xxx.cif p --cellsize 1`（3×3×3のスーパーセルを作成）
+  - `mcal xxx.cif p --cellsize 3`（7×7×7のスーパーセルを作成）
+
+### 出力設定
+
+#### `-p, --pickle`
+計算結果をpickleファイルに保存します。
+- **例**: `mcal xxx.cif p -p`
+
+### 拡散係数計算手法
+
+#### `--mc`
+モンテカルロ法を使用して拡散係数テンソルを計算します。(テスト用)
+- **例**: `mcal xxx.cif p --mc`
+
+#### `--ode`
+常微分方程式法を使用して拡散係数テンソルを計算します。(テスト用)
+- **例**: `mcal xxx.cif p --ode`
+
+## 使用例
+
+### 基本的な計算
+```bash
+# p型xxxの移動度を計算
+mcal xxx.cif p
+
+# 8CPUと16GBメモリを使用
+mcal xxx.cif p -c 8 -m 16
+```
+
+### 高精度計算
+```bash
+# すべてのペアに対して移動積分を計算（高精度、時間がかかる）
+mcal xxx.cif p --fullcal
+
+# より大きなスーパーセルを使用して移動積分計算範囲を拡大
+mcal xxx.cif p --cellsize 3
+
+# 異なる基底関数セットを使用
+mcal xxx.cif p -M "B3LYP/6-311G(d,p)"
+```
+
+### 結果の再利用
+```bash
+# 既存の計算結果から読み取り
+mcal xxx.cif p -r
+
+# 既存のpickleファイルから読み取り
+mcal xxx_result.pkl p -rp
+
+# 中断された計算を再開
+mcal xxx.cif p --resume
+
+# 結果をpickleファイルに保存
+mcal xxx.cif p -p
+```
+
+### 拡散係数の比較
+```bash
+# 通常計算 + モンテカルロ法 + ODEで比較
+mcal xxx.cif p --mc --ode
+```
+
+## 出力
+
+### 標準出力
+- 再配列エネルギー
+- 各ペアの移動積分
+- 拡散係数テンソル
+- 移動度テンソル
+- 移動度の固有値と固有ベクトル
+
+## 注意事項
+
+1. **計算時間**: 分子数とセルサイズによって計算時間は大きく変わります
+2. **メモリ使用量**: 大きなシステムでは十分なメモリを確保してください
+3. **Gaussianのインストール**: Gaussian 09またはGaussian 16が必要です
+4. **依存関係**: 必要なPythonライブラリがすべてインストールされていることを確認してください
+
+## トラブルシューティング
+
+### 計算が途中で停止した場合
+```bash
+# --resumeオプションで再開
+mcal xxx.cif p --resume
+```
+
+### メモリ不足エラーの場合
+```bash
+# メモリ量を増やす
+mcal xxx.cif p -m 32
+```
+
+### 計算時間を短縮するには
+```bash
+# 高速化処理を有効にする（デフォルト）
+mcal xxx.cif p
+
+# より小さなスーパーセルを使用して高速計算
+mcal xxx.cif p --cellsize 1
+
+# CPU数を増やす
+mcal xxx.cif p -c 16
+```
+
+# 著者
+[山形大学 有機エレクトロニクス研究センター (ROEL) 松井研究室](https://matsui-lab.yz.yamagata-u.ac.jp/index.html)  
+松井 弘之、尾沢 昂輝  
+Email: h-matsui[at]yz.yamagata-u.ac.jp  
+[at]を@に置き換えてください