### Example: Calculate n-type semiconductor

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example command to calculate mobility tensors for an n-type semiconductor using the file 'xxx.cif'.

```bash
mcal xxx.cif n
```

--------------------------------

### Practical Usage Examples

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Common command patterns for running basic mobility calculations and high-precision analysis.

```bash
# Basic calculation
mcal xxx.cif p

# Resource-constrained calculation
mcal xxx.cif p -c 8 -m 16

# High-precision calculation
mcal xxx.cif p --fullcal
mcal xxx.cif p --cellsize 3
mcal xxx.cif p -M "B3LYP/6-311G(d,p)"
```

--------------------------------

### Basic Calculation Example

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

This is a basic example of how to run a mobility calculation for a p-type material using the mcal tool. It specifies the input CIF file and the calculation type 'p'.

```bash
# Calculate mobility of p-type xxx
mcal xxx.cif p
```

--------------------------------

### Calculation with CPU and Memory Allocation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

This example demonstrates how to specify the number of CPUs and the amount of memory to be used during the calculation. This can help optimize performance for larger or more complex calculations.

```bash
# Use 8 CPUs and 16GB memory
mcal xxx.cif p -c 8 -m 16
```

--------------------------------

### Install mcal with Gaussian

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Installs the mcal package for use with Gaussian 09 or 16. This is the default installation if PySCF is not specified.

```bash
pip install yu-mcal
```

--------------------------------

### PySCF Calculation with CPU and Memory Allocation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

This example combines PySCF calculations with resource allocation, specifying the number of CPUs and memory to use. This is useful for managing computational resources effectively.

```bash
# Use 8 CPUs and 16GB memory with PySCF
mcal xxx.cif p --pyscf -c 8 -m 16
```

--------------------------------

### GjfMaker: Create Checkpoint File

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Generates a checkpoint file (.chk) as part of the Gaussian input file setup. This method does not require any parameters and returns no value.

```python
create_chk_file() -> None
```

--------------------------------

### Verify mcal Installation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Command to verify if the mcal tool has been installed correctly by checking its help message.

```bash
mcal --help
```

--------------------------------

### Install mcal with PySCF (CPU)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Installs the mcal package with PySCF support for CPU calculations. This option is suitable for macOS, Linux, and WSL2 environments.

```bash
pip install "yu-mcal[pyscf]"
```

--------------------------------

### High-Precision MCAL Calculation with Larger Supercell

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_sources/index.rst.txt

This example combines `--fullcal` for high-precision calculations with `--cellsize 3` to use a larger supercell (7x7x7), which widens the range for transfer integral calculations.

```bash
mcal xxx.cif p --fullcal
   mcal xxx.cif p --cellsize 3
```

--------------------------------

### Set Number of CPUs

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example of specifying the number of CPUs to use for calculations using the -c option.

```bash
mcal xxx.cif p -c 8
```

--------------------------------

### Calculation with Different Basis Set

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

This example shows how to specify a different basis set for the calculation using the -M option. This allows for fine-tuning the accuracy and computational cost of the electronic structure calculations.

```bash
# Use different basis set
mcal xxx.cif p -M "B3LYP/6-311G(d,p)"
```

--------------------------------

### Use Gaussian 09

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example command to explicitly use Gaussian 09 instead of the default Gaussian 16 with the -g flag.

```bash
mcal xxx.cif p -g
```

--------------------------------

### Set Memory Allocation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example of specifying the amount of memory (in GB) to allocate for calculations using the -m option.

```bash
mcal xxx.cif p -m 16
```

--------------------------------

### Set Calculation Method

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example of specifying a calculation method (e.g., B3LYP/6-31G(d)) for Gaussian or PySCF calculations using the -M option.

```bash
mcal xxx.cif p -M "B3LYP/6-31G(d)"
```

--------------------------------

### Configure Memory and Backend Settings

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Adjust computational resources and select the quantum chemistry backend. Options include setting memory limits and switching between Gaussian and PySCF engines.

```bash
mcal xxx.cif p -m 16
mcal xxx.cif p -g
mcal xxx.cif p --pyscf
mcal xxx.cif p --gpu4pyscf
mcal xxx.cif p --pyscf --cart
```

--------------------------------

### Output and Visualization Settings

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Configure result persistence and visualization options such as saving to pickle files or generating polar plots for mobility tensors.

```bash
mcal xxx.cif p -p
mcal xxx.cif p --plot-plane ab
```

--------------------------------

### Install mcal with PySCF (GPU CUDA 11.x)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Installs mcal with GPU acceleration using gpu4pyscf for CUDA Toolkit version 11.x. This automatically enables PySCF mode.

```bash
pip install "yu-mcal[gpu4pyscf-cuda11]"
```

--------------------------------

### Optimize mcal Calculation Performance via CLI

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Demonstrates how to reduce calculation time in mcal by enabling speedup processing, adjusting supercell size, and allocating additional CPU resources.

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

--------------------------------

### Install mcal with PySCF (GPU CUDA 12.x)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Installs mcal with GPU acceleration using gpu4pyscf for CUDA Toolkit version 12.x. This automatically enables PySCF mode.

```bash
pip install "yu-mcal[gpu4pyscf-cuda12]"
```

--------------------------------

### Initialize and Configure GjfMaker

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/gjf_maker.html

Demonstrates how to instantiate the GjfMaker class and configure basic Gaussian input parameters such as links, roots, and file output settings.

```python
from mcal.utils import GjfMaker

# Initialize the maker
maker = GjfMaker(remove_radical_flag=False)

# Configure links and roots
maker.add_root("Opt")
maker.add_link()

# Export to .gjf file
maker.export_gjf(file_name="calculation", save_dir="./output")
```

--------------------------------

### GjfMaker: Create Read/Write File

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Creates a read/write file (.rwf) for the Gaussian calculation. This method has no parameters and returns void.

```python
create_rwf_file() -> None
```

--------------------------------

### Read Gaussian Input File Directives

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/calculations/rcal.html

Reads link 0 commands (starting with '%') and route section directives (starting with '#') from a Gaussian input file (.gjf). It raises a ValueError if 'Link' commands are found, as they are not supported.

```python
def _input_gjf(self) -> None:
    """Input link 0 command and root options from gjf file."""
    with open(self.input_file, 'r') as f:
        for line in f:
            if line.startswith('%'):
                self._gjf_lines['%'].append(line)
            elif line.startswith('#'):
                self._gjf_lines['#'].append(line)
            elif 'link' in line.lower():
                raise ValueError("Please do not use Link.")
```

--------------------------------

### Create Reorganization Energy XYZ File (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Creates an XYZ file for reorganization energy calculations, storing atomic symbols and coordinates. The function takes atomic data, a base filename, and a save directory as input. It does not return any value.

```python
import numpy as np
import mcal

# Example data:
symbols = np.array(['O', 'H', 'H'])
coordinates = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.0], [0.0, 1.0, 0.0]])
basename = "reorg_xyz_output"
save_dir = "./xyz_files"

mcal.mcal.create_reorg_xyz(symbols, coordinates, basename, save_dir)
```

--------------------------------

### PySCF Calculation with Resource Allocation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_sources/index.rst.txt

This command demonstrates how to use PySCF for calculations while specifying the number of CPUs (`-c`) and memory (`-m`) to be allocated, similar to standard MCAL calculations.

```bash
mcal xxx.cif p --pyscf -c 8 -m 16
```

--------------------------------

### GET /check_transfer_integral_completion

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/mcal.html

Verifies if all transfer integral calculations (dimer, monomer1, monomer2) have completed successfully.

```APIDOC
## GET /check_transfer_integral_completion

### Description
Checks if the Gaussian log files for dimer and monomer calculations exist and indicate normal termination.

### Method
GET

### Endpoint
/check_transfer_integral_completion

### Parameters
#### Query Parameters
- **gjf_file** (str) - Required - Base path of the gjf file (without extension).
- **extension_log** (str) - Optional - Extension of the log file (default: '.log').

### Response
#### Success Response (200)
- **status** (bool) - True if all calculations terminated normally.

#### Response Example
{
  "status": true
}
```

--------------------------------

### Check Reorganization Energy Completion (General Log) (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Verifies if all reorganization energy calculations (optimized neutral, optimized ion, neutral, ion) have successfully completed by checking log files. It requires the base path of a CIF file and the semiconductor type (p-type or n-type). The function returns a list of calculations that are considered complete and can be skipped.

```python
from typing import List, Literal

def check_reorganization_energy_completion(cif_path_without_ext: str, osc_type: Literal['p', 'n'], extension_log: str = '.log') -> List[Literal['opt_neutral', 'opt_ion', 'neutral', 'ion']]:
    """Check if all reorganization energy calculations are completed normally."""
    # Implementation details would go here
    pass
```

--------------------------------

### Create Transfer Integral XYZ File (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Creates an XYZ file for transfer integral calculations, specifically for dimers. It takes dictionaries for the unique and neighbor molecules (symbols and coordinates), a base input filename, and a save directory. The function returns None.

```python
import numpy as np
import mcal

# Example molecular data:
unique_mol = {
    'symbols': np.array(['N', 'C']),
    'coordinates': np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.1]])
}
neighbor_mol = {
    'symbols': np.array(['N', 'C']),
    'coordinates': np.array([[3.0, 0.0, 0.0], [3.0, 0.0, 1.1]])
}

input_basename = "ti_dimer_xyz"
save_dir = "./ti_xyz"

mcal.mcal.create_ti_xyz(unique_mol, neighbor_mol, input_basename, save_dir)
```

--------------------------------

### Resource Allocation for Calculations

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/README.md

Specify the number of CPUs and the amount of memory to be used for calculations. This allows for optimizing performance based on available system resources.

```bash
mcal xxx.cif p -c 8 -m 16
mcal xxx.cif p --pyscf -c 8 -m 16
```

--------------------------------

### Use Cartesian Basis Functions (PySCF)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs-src/source/index.rst

Example command to use Cartesian basis functions instead of spherical harmonics in PySCF calculations, using the --cart flag.

```bash
mcal xxx.cif p --pyscf --cart
```

--------------------------------

### Create Reorganization Energy GJF File (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Generates a Gaussian input file (.gjf) for reorganization energy calculations. It requires atomic symbols, coordinates, a base filename, save directory, CPU count, memory allocation, and the calculation method. This function does not return any value.

```python
import numpy as np
import mcal

# Example data:
symbols = np.array(['C', 'H', 'H'])
coordinates = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.0], [0.0, 1.0, 0.0]])
basename = "reorg_calc"
save_dir = "./calculations"
cpu = 8
mem = 32
method = "B3LYP/def2-SVP"

mcal.mcal.create_reorg_gjf(symbols, coordinates, basename, save_dir, cpu, mem, method)
```

--------------------------------

### PySCF Calculation Options

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/README.md

Execute calculations using the PySCF library. Options include standard CPU-based calculations, GPU acceleration for PySCF, resuming interrupted calculations, and reading from existing checkpoint files.

```bash
mcal xxx.cif p --pyscf
mcal xxx.cif p --gpu4pyscf
mcal xxx.cif p --pyscf --resume
mcal xxx.cif p --pyscf -r
```

--------------------------------

### Run MCAL Calculation (Basic and with Resources)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Execute MCAL calculations on a CIF file. Options include specifying the number of CPUs and memory allocation for resource-intensive tasks.

```bash
$ mcal xxx.cif n

$ mcal xxx.cif p -c 8 -m 16
```

--------------------------------

### Generate Gaussian Input Files with GjfMaker

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

The GjfMaker class provides an interface to construct Gaussian input files (.gjf) by setting molecular coordinates, charge, spin, and calculation parameters. It supports exporting the configuration to a file after defining the system properties.

```python
from mcal.utils.gjf_maker import GjfMaker

maker = GjfMaker()
maker.set_title("Optimization Task")
maker.set_charge_spin(0, 1)
maker.set_coordinates([["C", 0.0, 0.0, 0.0]])
maker.export_gjf("output.gjf")
```

--------------------------------

### Implement reverse file reading with FileReader

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/gaus_log_reader.html

A utility class that allows reading a file line-by-line starting from the end. It uses a buffer to efficiently navigate the file pointer backwards.

```python
class FileReader:
    def __init__(self, file_path, buffer_size=8192):
        self.buffer_size = buffer_size
        self.file = open(file_path, 'rb')
        self.file.seek(0, os.SEEK_END)
        self.file_size = self.file.tell()
        self.reversed_block_end = self.file_size
        self.reversed_block_start = max(0, self.reversed_block_end - self.buffer_size)
        self.lines = []

    def reversed_readline(self):
        if not self.lines and self.reversed_block_end - self.reversed_block_start != 0:
            self.file.seek(self.reversed_block_start)
            block = self.file.read(self.reversed_block_end - self.reversed_block_start)
            lines = block.splitlines(keepends=True)
            if self.reversed_block_start == 0:
                self.reversed_block_end = self.reversed_block_start
            else:
                self.reversed_block_end = max(0, self.reversed_block_start + len(lines[0]))
            self.reversed_block_start = max(0, self.reversed_block_end - self.buffer_size)
            if self.reversed_block_end == 0:
                self.lines = lines
            else:
                self.lines = lines[1:]
            return self.lines.pop().decode('utf-8')
        elif self.lines:
            return self.lines.pop().decode('utf-8')
        else:
            return None
```

--------------------------------

### Perform Matrix and Log File Utilities

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Utility functions for numerical matrix operations like pseudo-inverse calculation and file system operations to verify Gaussian log file termination status.

```python
from mcal import cal_pinv, check_normal_termination

# Calculate pseudo-inverse matrix
pinv_matrix = cal_pinv(matrix, rcond=0.001)

# Verify Gaussian log file termination
is_normal = check_normal_termination("path/to/gaussian.log")
```

--------------------------------

### MCAL Calculation using PySCF (CPU)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_sources/index.rst.txt

The `--pyscf` option enables calculations using the PySCF quantum chemistry package on CPUs. This provides an alternative computational engine for MCAL.

```bash
mcal xxx.cif p --pyscf
```

--------------------------------

### Reset GJF File Variables

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.utils.html

This method resets all internal variables associated with the GJF file generation. It's useful for starting a new GJF file creation process or clearing previous settings.

```python
def reset_variable() -> None:
    """Reset the variables of the gjf file."""
    pass
```

--------------------------------

### Build Mean Field Object with GPU Support (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/calculations/rcal_pyscf.html

Sets up the mean-field (MF) object for SCF calculations, with an option to utilize GPU acceleration via the gpu4pyscf library. It handles different SCF methods (RHF/UHF) and functionals, including Hartree-Fock. Requires gpu4pyscf to be installed for GPU usage.

```python
    def \_build_mf(self, mol: gto.Mole, functional: str):
        """Build mean field.

        Parameters
        ----------
        mol : gto.Mole
            Molecule.
        functional : str
            Functional.

        Returns
        -------
        mf : scf.Mole
            Mean field.
        """
        if self._use_gpu:
            try:
                if functional.upper() == 'HF':
                    from gpu4pyscf.scf import hf as gpu_hf, uhf as gpu_uhf
                    mf = gpu_hf.RHF(mol) if mol.spin == 0 else gpu_uhf.UHF(mol)
                else:
                    from gpu4pyscf.dft import rks as gpu_rks, uks as gpu_uks
                    mf = gpu_rks.RKS(mol) if mol.spin == 0 else gpu_uks.UKS(mol)
                    mf.xc = functional
            except ImportError:
                print("Error: gpu4pyscf is not installed.")
                exit(1)
        else:
            if functional.upper() == 'HF':
                mf = scf.RHF(mol) if mol.spin == 0 else scf.UHF(mol)
            else:
                mf = dft.RKS(mol) if mol.spin == 0 else dft.UKS(mol)
                mf.xc = functional
        return mf
```

--------------------------------

### Depth-First Search for Bonded Atoms in Python

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/cif_reader.html

Implements a depth-first search (DFS) algorithm to find bonded atoms starting from a given node. It utilizes a list of atoms, a boolean array to track visited atoms, and the total number of atoms. This function is typically used in molecular structure analysis.

```python
def _search_connect_atoms(self, node: int, atoms: List[int], visited: NDArray[bool], num_atoms: int) -> None:
    """Find bonded atoms using depth-first search.

    Parameters
    ----------
    node : int
        Index of the atom.
    atoms : List[int]
        List of bonded atoms.
    visited : NDArray[bool]
        Array of visited atoms.
    num_atoms : int
        Number of atoms.
    """
    pass
```

--------------------------------

### GJF File Creation with GjfMaker (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

A class designed for creating Gaussian input files (.gjf). It includes a dictionary mapping element symbols to their atomic numbers, which is essential for constructing molecular input for computational chemistry software. It has an option to remove radical flags.

```python
class GjfMaker(_remove_radical_flag: bool = False):
    """Bases: object"""
    ELEMENTS_NUM = {
        'Ac': 89, 'Ag': 47, 'Al': 13, 'Am': 95, 'Ar': 18, 'As': 33, 'At': 85, 'Au': 79, 'B': 5, 'Ba': 56, 'Be': 4, 'Bh': 107, 'Bi': 83, 'Bk': 97, 'Br': 35, 'C': 6, 'Ca': 20, 'Cd': 48, 'Ce': 58, 'Cf': 98, 'Cl': 17, 'Cm': 96, 'Cn': 112, 'Co': 27, 'Cr': 24, 'Cs': 55, 'Cu': 29, 'D': 1, 'Db': 105, 'Ds': 110, 'Dy': 66, 'Er': 68, 'Es': 99, 'Eu': 63, 'F': 9, 'Fe': 26, 'Fl': 114, 'Fm': 100, 'Fr': 87, 'Ga': 31, 'Gd': 64, 'Ge': 32, 'H': 1, 'He': 2, 'Hf': 72, 'Hg': 80, 'Ho': 67, 'Hs': 108, 'I': 53, 'In': 49, 'Ir': 77, 'K': 19, 'Kr': 36, 'La': 57, 'Li': 3, 'Lr': 103, 'Lu': 71, 'Lv': 116, 'Mc': 115, 'Md': 101, 'Mg': 12, 'Mn': 25, 'Mo': 42, 'Mt': 109, 'N': 7, 'Na': 11, 'Nb': 41, 'Nd': 60, 'Ne': 10, 'Nh': 113, 'Ni': 28, 'No': 102, 'Np': 93, 'O': 8, 'Og': 118, 'Os': 76, 'P': 15, 'Pa': 91, 'Pb': 82, 'Pd': 46, 'Pm': 61, 'Po': 84, 'Pr': 59, 'Pt': 78, 'Pu': 94, 'Ra': 88, 'Rb': 37, 'Re': 75, 'Rf': 104, 'Rg': 111, 'Rh': 45, 'Rn': 86, 'Ru': 44, 'S': 16, 'Sb': 51, 'Sc': 21, 'Se': 34, 'Sg': 106, 'Si': 14, 'Sm': 62, 'Sn': 50, 'Sr': 38, 'Ta': 73, 'Tb': 65, 'Tc': 43, 'Te': 52, 'Th': 90, 'Ti': 22, 'Tl': 81, 'Tm': 69, 'Ts': 117, 'U': 92, 'V': 23, 'W': 74, 'X': 0, 'Xe': 54, 'Y': 39, 'Yb': 70, 'Zn': 30, 'Zr': 40}

```

--------------------------------

### Initialize CLI for Mobility Calculation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/mcal.html

The main function configures an argument parser to handle input files, semiconductor types, and Gaussian calculation parameters. It allows users to specify CPU/memory resources, toggle between Gaussian versions, and manage calculation resumption or result serialization.

```python
def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('file', help='cif file name or pickle file name', type=str)
    parser.add_argument('osc_type', help='organic semiconductor type', type=str)
    parser.add_argument('-M', '--method', help='calculation method', type=str, default='B3LYP/6-31G(d,p)')
    parser.add_argument('-c', '--cpu', help='number of cpu', type=int, default=4)
    parser.add_argument('-m', '--mem', help='memory in GB', type=int, default=10)
    parser.add_argument('-r', '--read', help='read log files without executing Gaussian', action='store_true')
    parser.add_argument('-p', '--pickle', help='save result to pickle', action='store_true')
    args = parser.parse_args()
```

--------------------------------

### Gaussian Input File Generation API

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/genindex.html

Utilities for generating and configuring Gaussian input files via the GjfMaker class.

```APIDOC
## POST /mcal/utils/gjf_maker/set_charge_spin

### Description
Configures the charge and spin multiplicity for a Gaussian input file generation process.

### Method
POST

### Endpoint
mcal.utils.gjf_maker.GjfMaker.set_charge_spin

### Request Body
- **charge** (int) - Required - Molecular charge
- **spin** (int) - Required - Spin multiplicity

### Response
#### Success Response (200)
- **status** (string) - Confirmation of configuration update

### Response Example
{
  "status": "success"
}
```

--------------------------------

### Perform PySCF Calculations via CLI

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Executes molecular calculations using the PySCF backend. Supports GPU acceleration, resource allocation (CPU/memory), and resuming interrupted tasks.

```bash
# Calculate using PySCF (CPU)
mcal xxx.cif p --pyscf

# Calculate using PySCF with GPU acceleration
mcal xxx.cif p --gpu4pyscf

# Use 8 CPUs and 16GB memory with PySCF
mcal xxx.cif p --pyscf -c 8 -m 16

# Resume interrupted PySCF calculation
mcal xxx.cif p --pyscf --resume

# Read from existing PySCF checkpoint files
mcal xxx.cif p --pyscf -r
```

--------------------------------

### Manage Calculation Results and Reusability

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Commands for reading existing calculation data, resuming interrupted processes, and exporting results to pickle files for later analysis.

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

--------------------------------

### Create Transfer Integral GJF File (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Generates a Gaussian input file (.gjf) for transfer integral calculations. It requires dictionaries for the unique and neighbor molecules (containing symbols and coordinates), a base filename, save directory, CPU count, memory, and calculation method. This function returns None.

```python
import numpy as np
import mcal

# Example molecular data:
unique_mol = {
    'symbols': np.array(['C', 'H']),
    'coordinates': np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 1.0]])
}
neighbor_mol = {
    'symbols': np.array(['C', 'H']),
    'coordinates': np.array([[2.0, 0.0, 0.0], [2.0, 0.0, 1.0]])
}

gjf_basename = "ti_calculation"
save_dir = "./ti_gjf"
cpu = 4
mem = 16
method = "B3LYP/6-31G*"

mcal.mcal.create_ti_gjf(unique_mol, neighbor_mol, gjf_basename, save_dir, cpu, mem, method)
```

--------------------------------

### Gaussian Input File Generation (GjfMaker)

Source: https://context7.com/matsui-lab-yamagata/mcal/llms.txt

Creates Gaussian input files (.gjf) programmatically using the GjfMaker class. Allows setting computational resources, DFT method, checkpoint files, optimization keywords, molecular structure, charge, and spin. Supports single-step and multi-step calculations with Link1.

```python
from mcal import GjfMaker
import numpy as np

# Initialize GjfMaker
gjf = GjfMaker()

# Set computational resources
gjf.set_resource(cpu_num=8, mem_num=16)  # 8 CPUs, 16 GB memory

# Set DFT method
gjf.set_function('B3LYP/6-31G(d,p)')

# Enable checkpoint file creation
gjf.create_chk_file()

# Enable detailed output
gjf.output_detail()

# Add optimization keyword
gjf.opt(tight=True)

# Set molecular structure
symbols = ['C', 'C', 'H', 'H', 'H', 'H']
coordinates = np.array([
    [0.0, 0.0, 0.0],
    [1.54, 0.0, 0.0],
    [-0.5, 0.9, 0.0],
    [-0.5, -0.9, 0.0],
    [2.04, 0.9, 0.0],
    [2.04, -0.9, 0.0],
])

gjf.set_symbols(symbols)
gjf.set_coordinates(coordinates)

# Set charge and spin (optional - auto-detected if not set)
gjf.set_charge_spin(charge=0, spin=1)

# Export gjf file
gjf.export_gjf(file_name='ethane_opt', save_dir='./calculations')

# Create a multi-step calculation with Link1
gjf.reset_variable()
gjf.set_function('B3LYP/6-31G(d,p)')
gjf.create_chk_file()
gjf.opt()
gjf.set_symbols(symbols)
gjf.set_coordinates(coordinates)

# Add Link1 for property calculation
gjf.add_link()
gjf.add_root('Pop=Full')
gjf.add_root('IOp(3/33=4)')

gjf.export_gjf(file_name='ethane_opt_prop', save_dir='./calculations')
```

--------------------------------

### Configure MCAL Calculation Method and Precision

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Customize MCAL calculations by selecting different quantum mechanical methods and enabling high-precision computation modes. This allows for more accurate results at the cost of increased computation time.

```bash
$ mcal xxx.cif p -M "B3LYP/6-311G(d,p)"

$ mcal xxx.cif p –fullcal

$ mcal xxx.cif p –cellsize 2
```

--------------------------------

### Troubleshoot Calculation Failures

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Common commands to address calculation interruptions or memory limitations during execution.

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

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

--------------------------------

### Configure CLI Arguments and Calculation Workflow in Python

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/mcal.html

This snippet demonstrates how to define command-line arguments using argparse and implement conditional logic to switch between PySCF and Gaussian calculation backends. It includes error handling for missing dependencies and initializes the reorganization energy calculation process.

```python
import argparse
from pathlib import Path
from time import time

parser = argparse.ArgumentParser()
parser.add_argument('--fullcal', help='calculate all pairs and monomers from scratch', action='store_true')
parser.add_argument('--pyscf', help='use PySCF instead of Gaussian', action='store_true')
parser.add_argument('--gpu4pyscf', help='use GPU acceleration via gpu4pyscf', action='store_true')
args = parser.parse_args()

pyscf_mode = args.pyscf or args.gpu4pyscf
if pyscf_mode:
    try:
        from tcal import TcalPySCF
        from mcal.calculations.rcal_pyscf import RcalPySCF
    except ImportError:
        print('Error: PySCF is not installed.')
        exit(1)

cif_file = Path(args.file)
# Logic for reorganization energy calculation follows...
```

--------------------------------

### Basic Mobility Calculation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/README.md

Perform a basic calculation of the mobility for a p-type material. This is the simplest form of calculation and can be further customized with resource allocation options.

```bash
mcal xxx.cif p
```

--------------------------------

### GjfMaker: Add Root Path

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Sets the root directory path for the Gaussian input file generation process. It takes a string representing the root path as input and returns nothing.

```python
add_root(_root: str_) -> None
```

--------------------------------

### GjfMaker: Set Charge and Spin

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Sets the molecular charge and spin multiplicity for the Gaussian calculation. It requires integer arguments for charge and spin.

```python
set_charge_spin(_charge: int, _spin: int) -> None
```

--------------------------------

### Check Reorganization Energy Completion (PySCF) (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Checks the completion status of reorganization energy calculations specifically performed using PySCF. It takes the base path of a CIF file and the semiconductor type (p-type or n-type) as input. The function returns a list indicating which calculations (opt_neutral, opt_ion, neutral, ion) are completed.

```python
from typing import List, Literal

def check_reorganization_energy_completion_pyscf(cif_path_without_ext: str, osc_type: Literal['p', 'n']) -> List[Literal['opt_neutral', 'opt_ion', 'neutral', 'ion']]:
    """Check if PySCF reorganization energy calculations are completed."""
    # Implementation details would go here
    pass
```

--------------------------------

### GjfMaker: Export GJF File

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Exports the generated Gaussian input file (.gjf) to a specified directory. It requires the file name and optionally accepts a save directory and a name for the checkpoint or read/write file.

```python
export_gjf(_file_name: str, _save_dir: str = '.', _chk_rwf_name: str | None = None_) -> None
```

--------------------------------

### MCAL Calculation with Resource Allocation

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_sources/index.rst.txt

This command allows you to specify the number of CPUs (`-c`) and the amount of memory (`-m` in GB) to be used for the calculation. This is useful for optimizing performance on multi-core systems.

```bash
mcal xxx.cif p -c 8 -m 16
```

--------------------------------

### Perform Coordinate Transformations

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Utility functions to convert between Cartesian and fractional coordinate systems and calculate the center of weight for molecular structures.

```python
import numpy as np

def calc_cen_of_weight(coordinates: np.ndarray) -> np.ndarray:
    """Calculate center of weight for monomolecular coordinates."""
    return np.mean(coordinates, axis=0)

def convert_cart_to_frac(cart_coord: np.ndarray) -> np.ndarray:
    """Convert Cartesian coordinates to fractional coordinates."""
    pass

def convert_frac_to_cart(frac_coord: np.ndarray) -> np.ndarray:
    """Convert fractional coordinates to Cartesian coordinates."""
    pass
```

--------------------------------

### GjfMaker: Output Detail Log

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

Writes detailed information to a log file during the Gaussian input file generation process. This method takes no arguments and returns nothing.

```python
output_detail() -> None
```

--------------------------------

### FileIO Class Initialization

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/cif_reader.html

Initializes the `FileIO` class, setting up attributes to store atom count, symbol lists, coordinate lists, and adjacency matrices. This class is used for managing and exporting molecular file data.

```python
class FileIO:
    def __init__(self) -> None:
        self.atom_num = 0
        self.symbols_list = []
        self.coordinates_list = []
        self.adjacency_mat_list = []
```

--------------------------------

### Main Function for Mobility Tensor Calculation (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.html

The main entry point for calculating the mobility tensor, considering anisotropy and path continuity. It can be invoked from the command line with crystal structure file and type (p-type or n-type) as arguments.

```python
# Command line usage examples:
# Calculate p-type mobility for xxx crystal
# $ mcal xxx.cif p

# Calculate n-type mobility for xxx crystal
# $ mcal xxx.cif n

# Note: The actual Python code for mcal.mcal.main() is not provided here,
# but it would be invoked as shown in the command line examples.
```

--------------------------------

### Read from Existing Pickle File

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_sources/index.rst.txt

The `-rp` option combines reading from existing results (`-r`) with specifying a pickle file (`-p`). This allows MCAL to load calculation data directly from a previously saved pickle file.

```bash
mcal xxx_result.pkl p -rp
```

--------------------------------

### Control Calculation Execution and Caching

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/index.html

Manage how calculations are performed, including reading existing results, resuming interrupted tasks, and toggling optimization features like monomer caching and pair screening.

```bash
mcal xxx.cif p -r
mcal xxx_result.pkl p -rp
mcal xxx.cif p --resume
mcal xxx.cif p --fullcal
mcal xxx.cif p --no-monomer-cache
mcal xxx.cif p --cellsize 3
```

--------------------------------

### Use Different Basis Set for Calculations

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/README.md

Specify a different basis set for the calculations. This can influence the accuracy and nature of the computed electronic properties.

```bash
mcal xxx.cif p -M "B3LYP/6-311G(d,p)"
```

--------------------------------

### Initialize CifReader for Crystal Data Extraction

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/mcal.utils.html

The CifReader class is used to initialize a parser for a given CIF file path. It provides the necessary infrastructure to extract crystal information and includes built-in atomic property references.

```python
from mcal.utils.cif_reader import CifReader

# Initialize the reader with a path to a .cif file
reader = CifReader(cif_path="path/to/structure.cif")

# Accessing atomic data constants
weight = reader.ATOMIC_WEIGHTS.get('C')
radius = reader.COVALENT_RADII.get('C')
```

--------------------------------

### Create Reorganization Energy GJF File (Python)

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/mcal.html

Generates a Gaussian input file (.gjf) for reorganization energy calculations. It utilizes the `GjfMaker` class to set up calculation parameters, including method, resources, and atomic information, before exporting the file.

```python
def create_reorg_gjf(
    symbols: NDArray[str],
    coordinates: NDArray[np.float64],
    basename: str,
    save_dir: str,
    cpu: int,
    mem: int,
    method: str,
) -> None:
    """Create gjf file for reorganization energy calculation.

    Parameters
    ----------
    symbols : NDArray[str]
        Symbols of atoms
    coordinates : NDArray[np.float64]
        Coordinates of atoms
    basename : str
        Base name of gjf file
    save_dir : str
        Directory to save gjf file
    cpu : int
        Number of cpu
    mem : int
        Number of memory [GB]
    method : str
        Calculation method used in Gaussian calculations
    """
    gjf_maker = GjfMaker()
    gjf_maker.set_function(method)
    gjf_maker.create_chk_file()
    gjf_maker.output_detail()
    gjf_maker.opt()

    gjf_maker.set_symbols(symbols)
    gjf_maker.set_coordinates(coordinates)
    gjf_maker.set_resource(cpu_num=cpu, mem_num=mem)

    gjf_maker.export_gjf(
        file_name=f'{basename}_opt_n',
        save_dir=save_dir,
        chk_rwf_name=f'{save_dir}/{basename}_opt_n'
    )
```

--------------------------------

### PySCF Backend Mobility Calculation (CLI)

Source: https://context7.com/matsui-lab-yamagata/mcal/llms.txt

Utilize the PySCF backend for quantum chemistry calculations within mcal. This supports CPU-only or GPU-accelerated calculations via gpu4pyscf, and allows for specifying Cartesian basis functions and custom computational resources.

```bash
# CPU-only PySCF calculation
mcal crystal.cif p --pyscf

# GPU-accelerated calculation via gpu4pyscf
mcal crystal.cif p --gpu4pyscf

# PySCF with Cartesian basis functions
mcal crystal.cif p --pyscf --cart

# PySCF with custom resources
mcal crystal.cif p --pyscf -c 8 -m 16
```

--------------------------------

### Initialize CifReader and Process Crystal Data

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/cif_reader.html

The CifReader class automates the extraction of crystal data from a CIF file. Upon initialization, it performs lattice calculation, symmetry operations, duplicate removal, and Z-value validation.

```python
from mcal.utils.cif_reader import CifReader

# Initialize the reader with a path to a .cif file
# This triggers internal processing including lattice calculation and symmetry operations
reader = CifReader("path/to/structure.cif")

# Access processed crystal properties
print(f"Lattice matrix:\n{reader.lattice}")
print(f"Calculated Z-value: {reader.z_value}")
```

--------------------------------

### GjfMaker Class API

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/utils/gjf_maker.html

Documentation for the GjfMaker class, including its constructor and methods for building Gaussian input files.

```APIDOC
## GjfMaker Class

### Description
Initializes the GjfMaker class for creating Gaussian input files (.gjf).

### Method
`__init__(self, remove_radical_flag: bool = False)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **remove_radical_flag** (bool) - Optional - If True, the radical is removed. Not recommended to use this flag.

### Request Example
```json
{
  "remove_radical_flag": false
}
```

### Response
#### Success Response (200)
Initializes the GjfMaker object.

#### Response Example
```json
{
  "message": "GjfMaker initialized successfully."
}
```

---

## add_link Method API

### Description
Adds a link section to the gjf file, preparing for subsequent geometry or calculation steps.

### Method
`add_link(self)`

### Endpoint
N/A (This is a class method)

### Parameters
None

### Request Example
```json
{
  "action": "add_link"
}
```

### Response
#### Success Response (200)
Adds a link section to the internal structure.

#### Response Example
```json
{
  "message": "Link added successfully."
}
```

---

## add_root Method API

### Description
Adds a root directive to the gjf file, specifying calculation keywords or options.

### Method
`add_root(self, root: str)`

### Endpoint
N/A (This is a class method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **root** (str) - Required - The root directive string (e.g., `# PBE0/def2-TZVP Opt Freq`).

### Request Example
```json
{
  "root": "# PBE0/def2-TZVP Opt Freq"
}
```

### Response
#### Success Response (200)
Adds the specified root directive.

#### Response Example
```json
{
  "message": "Root added successfully."
}
```

---

## create_chk_file Method API

### Description
Enables the creation of a checkpoint (.chk) file for the calculation.

### Method
`create_chk_file(self)`

### Endpoint
N/A (This is a class method)

### Parameters
None

### Request Example
```json
{
  "action": "create_chk_file"
}
```

### Response
#### Success Response (200)
Sets the internal flag to indicate checkpoint file creation.

#### Response Example
```json
{
  "message": "Checkpoint file creation enabled."
}
```

---

## create_rwf_file Method API

### Description
Enables the creation of a restart write file (.rwf) for the calculation.

### Method
`create_rwf_file(self)`

### Endpoint
N/A (This is a class method)

### Parameters
None

### Request Example
```json
{
  "action": "create_rwf_file"
}
```

### Response
#### Success Response (200)
Sets the internal flag to indicate restart write file creation.

#### Response Example
```json
{
  "message": "Restart write file creation enabled."
}
```

---

## export_gjf Method API

### Description
Exports the constructed Gaussian input file (.gjf) to a specified directory.

### Method
`export_gjf(self, file_name: str, save_dir: str = '.', chk_rwf_name: Optional[str] = None)`

### Endpoint
N/A (This is a class method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
*   **file_name** (str) - Required - The base name for the output .gjf file.
*   **save_dir** (str) - Optional - The directory where the .gjf file will be saved. Defaults to the current directory.
*   **chk_rwf_name** (Optional[str]) - Optional - The base name for the .chk or .rwf file if different from the file_name.

### Request Example
```json
{
  "file_name": "my_molecule",
  "save_dir": "./calculations",
  "chk_rwf_name": "checkpoint_data"
}
```

### Response
#### Success Response (200)
Creates and saves the .gjf file to the specified location.

#### Response Example
```json
{
  "message": "gjf file 'my_molecule.gjf' exported successfully to './calculations'."
}
```

#### Error Response (400)
Returns an error if the molecule is identified as a radical and `remove_radical_flag` is True.

#### Error Response Example
```json
{
  "error": "This molecule is radical and cannot be processed with the current settings."
}
```
```

--------------------------------

### Initialize RcalPySCF Calculator

Source: https://github.com/matsui-lab-yamagata/mcal/blob/main/docs/_modules/mcal/calculations/rcal_pyscf.html

The constructor initializes the calculator with an XYZ file and computational parameters. It sets up the method (functional/basis), hardware acceleration options, and memory limits.

```python
from mcal.calculations.rcal_pyscf import RcalPySCF

calculator = RcalPySCF(
    xyz_file="molecule.xyz",
    method="B3LYP/6-31G(d,p)",
    ncore=4,
    max_memory_gb=16
)
```