mcal.calculations package - mcal 0.1.0 documentation

Skip to content
Back to top
View this page

# mcal.calculations package

## Submodules

## mcal.calculations.hopping_mobility_model module

hopping_mobility_model.py (2025/10/06)

mcal.calculations.hopping_mobility_model.cal_pinv(array: ndarray[Any, dtype[float64]], rcond: float = 1e-09) → ndarray[Any, dtype[float64]]

  Calculate pseudo-inverse matrix using eigenvalue decomposition

  Parameters:

    - array (NDArray[np.float64]) – Input matrix

    - rcond (float, optional) – Cutoff for small singular values, by default 1e-9

  Returns:

    Pseudo-inverse matrix

  Return type:

    NDArray[np.float64]

  Raises:

    - ValueError – The last eigenvalue is not zero.

    - ValueError – All eigenvalues except the last one should be negative.

mcal.calculations.hopping_mobility_model.demo()

mcal.calculations.hopping_mobility_model.diffusion_coefficient_tensor(lattice: ndarray[Any, dtype[float64]], hop: List[Tuple[int, int, int, int, int, float]]) → ndarray[Any, dtype[float64]]

  Calculate diffusion coefficient tensor from hopping rate

  Parameters:

    - lattice (3x3 numpy.array) – lattice[0,:] is a-axis vector, lattice[1,:] b-axis vector, lattice[2,:] c-axis vector

    - hop (list of (int, int, int, int, int, float) tuple.) – (s, t, i, j, k, p) means that the hopping rate from s-th molecule in (0, 0, 0) cell to t-th molecule in (i, j, k) cell is p.

  Returns:

    Diffusion coefficient tensor

  Return type:

    3x3 numpy.array

mcal.calculations.hopping_mobility_model.diffusion_coefficient_tensor_MC(lattice: ndarray[Any, dtype[float64]], hop: List[Tuple[int, int, int, int, int, float]], steps: int = 100, particles: int = 10000) → ndarray[Any, dtype[float64]]

  Calculate diffusion coefficient tensor from Monte Carlo simulation using Gillespie algorithm.

  Parameters:

    - lattice (3x3 numpy.array) – lattice[0,:] is a-axis vector, lattice[1,:] b-axis vector, lattice[2,:] c-axis vector

    - hop (list of (int, int, int, int, int, float) tuple.) – (s, t, i, j, k, p) means that the hopping rate from s-th molecule in (0, 0, 0) cell to t-th molecule in (i, j, k) cell is p.

    - steps (int) – Number of steps

    - particles (int) – Number of particles

  Returns:

    Diffusion coefficient tensor

  Return type:

    3x3 numpy.array

mcal.calculations.hopping_mobility_model.diffusion_coefficient_tensor_ODE(lattice: ndarray[Any, dtype[float64]], hop: List[Tuple[int, int, int, int, int, float]], max_steps: int = 200, size: int = 40, max_rate: float = 0.05) → ndarray[Any, dtype[float64]]

  Calculate diffusion coefficient tensor from numerical solution of Ordinary Differential Equation (ODE)

  Parameters:

    - lattice (3x3 numpy.array) – lattice[0,:] is a-axis vector, lattice[1,:] b-axis vector, lattice[2,:] c-axis vector

    - hop (list of (int, int, int, int, int, float) tuple.) – (s, t, i, j, k, p) means that the hopping rate from s-th molecule in (0, 0, 0) cell to t-th molecule in (i, j, k) cell is p.

    - max_steps (int) – Maximum number of steps

    - size (int) – Size of the simulation box

    - max_rate (float) – Maximum rate of hopping

  Returns:

    Diffusion coefficient tensor

  Return type:

    3x3 numpy.array

mcal.calculations.hopping_mobility_model.marcus_rate(transfer: float, reorganization: float, T: float = 300.0) → float

  Calculate hopping rate (1/s) from transfer integral (eV) and reorganization energy (eV)

  Parameters:

    - transfer (float) – Transfer integral [eV]

    - reorganization (float) – Reorganization energy [eV]

    - T (float) – Temperature [K], by default 300.0

  Returns:

    Hopping rate [1/s]

  Return type:

    float

mcal.calculations.hopping_mobility_model.mobility_tensor(D: ndarray[Any, dtype[float64]], T: float = 300.0) → ndarray[Any, dtype[float64]]

  Calculate mobility tensor from diffusion coefficient tensor

  Parameters:

    - D (3x3 numpy.array) – Diffusion coefficient tensor

    - T (float) – Temperature [K], by default 300.0

  Returns:

    Mobility tensor

  Return type:

    3x3 numpy.array

mcal.calculations.hopping_mobility_model.print_tensor(tensor: ndarray[Any, dtype[float64]], msg: str = 'Mobility tensor')

## mcal.calculations.rcal module

Rcal

exception mcal.calculations.rcal.GausTermError

  Bases: `Exception`

  Exception for Gaussian error termination.

exception mcal.calculations.rcal.OSCTypeError

  Bases: `Exception`

  Exception for organic semiconductor type.

class mcal.calculations.rcal.Rcal(gjf_file: str, osc_type: Literal['p', 'n'] = 'p')

  Bases: `object`

  Calculate organization energy.

  calc_reorganization(gau_com: str = 'g16', only_read: bool = False, is_output_detail: bool = False, skip_specified_cal: List[Literal['opt_neutral', 'opt_ion', 'neutral', 'ion']] = []) → float

    Calculate reorganization energy.

    Parameters:

      - gau_com (str) – Gaussian command, by default ‘g16’.

      - only_read (bool) – if True, the calculation is only read, by default False.

      - is_output_detail (bool) – if True, the calculation detail will be output, by default False.

      - skip_specified_cal (List[Literal['opt_neutral', 'opt_ion', 'neutral', 'ion']]) – if specified, the calculation of the specified type will be skipped, by default [].

    Returns:

      reorganization energy [eV].

    Return type:

      float

  static check_error_term(line: str) → None

    Check the error term of Gaussian.

    Parameters:

      line (str) – last line of the log file.

    Raises:

      GausTermError – if the calculation of Gaussian was error termination.

  check_extension_log(gjf: str) → None

    Check the extension of log file.

    Parameters:

      gjf (str) – gjf file name.

  extract_energy(gjf: str, only_read: bool = False, is_output_detail: bool = False, skip_cal: bool = False) → float

    Extract energy from log file.

    Parameters:

      - gjf (str) – gjf file name.

      - only_read (bool) – if True, the calculation is only read, by default False.

      - is_output_detail (bool) – if True, the calculation detail will be output, by default False.

    Returns:

      total energy.

    Return type:

      float

  static print_timestamp() → None

    Print timestamp.

mcal.calculations.rcal.main()

  This code is to execute rcal for command line.

## mcal.calculations.tcal module

Tcal

class mcal.calculations.tcal.PairAnalysis(apta)

  Bases: `object`

  Analyze atomic pair transfer integrals.

  print_element_pairs()

    Print element pairs.

  print_largest_pairs()

    Print largest pairs.

class mcal.calculations.tcal.Tcal(file, monomer1_atom_num=-1)

  Bases: `object`

  Calculate transfer integrals.

  EV = 27211.38456571948
  atomic_pair_transfer_analysis(analyze_orbital='HOMO', output_apta=False)

    Calculate atomic pair transfer integrals.

    Parameters:

      - analyze_orbital (str, optional) – Analyze orbital., default ‘HOMO’

      - output_apta (bool, optional) – If it is True, output csv file of atomic pair transfer integrals., default False

  static cal_transfer_integrals(bra, overlap, fock, ket)

    Calculate intermolecular transfer integrals.

    Parameters:

      - bra (numpy.array) – MO coefficients of one molecule.

      - overlap (numpy.array) – Overlap matrix of dimer.

      - fock (numpy.array) – Fock matrix of dimer.

      - ket (numpy.array) – MO coefficients of the other molecule.

    Returns:

      Intermolecular transfer integrals.

    Return type:

      double

  check_extension_log()

    Check the extension of log file.

  static check_normal_termination(reader)

    Whether the calculation of gaussian was successful or not.

    Parameters:

      reader (_io.TextIOWrapper) – Return value of open function.

    Returns:

      Return value of function.

    Return type:

      _io.TextIOWrapper

    Examples

        >>> with open('sample.log', 'r') as f:
        ...     f = Tcal.check_normal_termination(f)

  convert_xyz_to_gjf(function='B3LYP/6-31G(d,p)', nprocshared=4, mem=16, unit='GB')

    Convert xyz file to gjf file.

    Parameters:

      - function (str, optional) – _description_, default ‘b3lyp/6-31g(d,p)’

      - nprocshared (int, optional) – The number of nprocshared., default 4

      - mem (int, optional) – The number of memory., default 16

      - unit (str, optional) – The unit of memory., default ‘GB’

  create_cube_file()

    Create cube file.

  create_monomer_file()

    Create gjf files of monomer from gjf file of dimer.

  custom_atomic_pair_transfer_analysis(analyze_orb1, analyze_orb2, output_apta=False)

    Calculate atomic pair transfer integrals.

    Parameters:

      - analyze_orb1 (int, optional) – Analyze orbital., default -1

      - analyze_orb2 (int, optional) – Analyze orbital., default -1

      - output_apta (bool, optional) – If it is True, output csv file of atomic pair transfer integrals., default False

  static extract_coordinates(reader)

    Extract coordinates from gjf file of dimer.

    Parameters:

      reader (_io.TextIOWrapper) – Return value of open function.

    Returns:

      - _io.TextIOWrapper – Return value of open function.

      - list – The list of coordinates.

    Examples

        >>> import re
        >>> with open(f'sample.gjf', 'r') as f:
        ...     while True:
        ...         line = f.readline()
        ...         if not line:
        ...             break
        ...         if re.search('[-0-9]+ [0-3]', line):
        ...             f, coordinates = Tcal.extract_coordinates(f)

  static extract_num(pattern, line, idx=0)

    Extract integer in strings.

    Parameters:

      - pattern (str) – Strings using regular expression.

      - line (str) – String of target.

    Returns:

      If there is integer, return it.

    Return type:

      int or None

  static output_csv(file_name, array)

    Output csv file of array.

    Parameters:

      - file_name (str) – File name including extension.

      - array (array_like) – Array to create csv file.

  print_apta(a_transfer, message='Atomic Pair Transfer Analysis')

    Create list of apta and print it.

    Parameters:

      - a_transfer (numpy.array) – Result of atomic pair transfer analysis.

      - message (str, optional) – Message to print., default ‘Atomic Pair Transfer Analysis’

    Returns:

      The array of atomic pair transfer analysis.

    Return type:

      numpy.array

  static print_matrix(matrix)

    Print matrix.

    Parameters:

      matrix (array_like)

  static print_timestamp()

    Print timestamp.

  print_tranfer_integral_diff_levels(nlevel, output_ti_diff_levels=False)
  print_transfer_integrals()

    Print transfer integrals of NLUMO, LUMO, HOMO and NHOMO.

  read_dimer(is_matrix=False, output_matrix=False)

    Extract overlap and fock matrix from log file of dimer.

    Parameters:

      - is_matrix (bool, optional) – If it is True, print overlap and fock matrix., default False

      - output_matrix (bool, optional) – If it is True, Output overlap and fock matrix., default False

  static read_matrix(reader, n_basis, n_bsuse)

    Read matrix.

    Parameters:

      - reader (_io.TextIOWrapper) – Return value of open function.

      - n_basis (int) – The number of row.

      - n_bsuse (int) – The number of column.

    Returns:

      Read matrix like MO coefficients.

    Return type:

      numpy.array

  read_monomer1(is_matrix=False, output_matrix=False)

    Extract MO coefficients from log file of monomer.

    Parameters:

      - is_matrix (bool, optional) – If it is True, print MO coefficients., default False

      - output_matrix (bool, optional) – If it is True, Output MO coefficients., default False

  read_monomer2(is_matrix=False, output_matrix=False)

    Extract MO coefficients from log file of monomer.

    Parameters:

      - is_matrix (bool, optional) – If it is True, print MO coefficients., default False

      - output_matrix (bool, optional) – If it is True, Output MO coefficients., default False

  static read_symmetric_matrix(reader, n_basis)

    Read symmetric matrix.

    Parameters:

      - reader (_io.TextIOWrapper) – Return value of open function.

      - n_basis (int) – The number of column or row.

    Returns:

      Read symmetrix matrix like overlap or fock matrix.

    Return type:

      numpy.array

  run_gaussian(gaussian_command, skip_monomer_num=[0])

    Execute gjf files using gaussian.

    Parameters:

      - gaussian_command (str) – Command of gaussian.

      - skip_monomer_num (list[int], optional) – If it is 1, skip 1st monomer calculation. If it is 2, skip 2nd monomer calculation. If it is 3, skip dimer calculation.

    Returns:

      Returncode of subprocess.run.

    Return type:

      int

mcal.calculations.tcal.main()

  This code is to execute tcal for command line.

## Module contents