==================================
mcal Documentation
==================================

.. image:: https://img.shields.io/badge/python-3.9%20or%20newer-blue
   :target: https://www.python.org
   :alt: Python

.. image:: https://img.shields.io/badge/License-MIT-blue.svg
   :target: https://opensource.org/licenses/MIT
   :alt: 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
============

.. code-block:: bash

   pip install yu-mcal


Verify Installation
-------------------

After installation, you can verify by running:

.. code-block:: bash

   mcal --help

mcal Usage Manual
=================

Basic Usage
-----------

.. code-block:: bash

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

.. code-block:: 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 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
~~~~~~~~~~~~~~~~~~

.. code-block:: 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: 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
~~~~~~~~~~~~~~~

.. code-block:: 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: 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
-----

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

.. code-block:: bash

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

Memory shortage error
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

To reduce calculation time
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: 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

API Reference
=============

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   modules

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

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

License
=======

This project is released under the MIT License.

For more details, see the `LICENSE file on GitHub <https://github.com/matsui-lab-yamagata/mcal/blob/main/LICENSE>`_.

Acknowledgements
================

This work was supported by JSPS Grant-in-Aid for JSPS Fellows Grant Number JP25KJ0647.
