mcal.utils package - mcal documentation

Skip to content
Back to top
View this page

# mcal.utils package

## Submodules

## mcal.utils.cif_reader module

CifReader beta (2026/02/05)

class mcal.utils.cif_reader.CifReader(cif_path: str)

  Bases: `object`

  CifReader class.

  This class is used to read cif file and extract crystal information.

  Raises:

    - ElementPropertiesIsNotDefinedError – Raised when element properties is not defined.

    - SymmetryIsNotDefinedError – Raised when symmetry is not defined.

    - ZValueIsNotMatchError – Raised when z value is not match. The atomic bond detection may not be functioning correctly.

  ATOMIC_WEIGHTS = {'Ag': 107.87, 'Al': 26.982, 'Ar': 39.95, 'As': 74.922, 'Au': 196.97, 'B': 10.81, 'Ba': 137.33, 'Be': 9.0122, 'Bi': 208.98, 'Br': 79.904, 'C': 12.011, 'Ca': 40.078, 'Cd': 112.41, 'Ce': 140.12, 'Cl': 35.45, 'Co': 58.933, 'Cr': 51.996, 'Cs': 132.91, 'Cu': 63.546, 'D': 2.014, 'Dy': 162.5, 'Er': 167.26, 'Eu': 151.96, 'F': 18.998, 'Fe': 55.845, 'Ga': 69.723, 'Gd': 157.25, 'Ge': 72.63, 'H': 1.008, 'He': 4.0026, 'Hf': 178.49, 'Hg': 200.59, 'Ho': 164.93, 'I': 126.9, 'In': 114.82, 'Ir': 192.22, 'K': 39.098, 'Kr': 83.798, 'La': 138.91, 'Li': 6.94, 'Lu': 174.97, 'Mg': 24.305, 'Mn': 54.938, 'Mo': 95.95, 'N': 14.007, 'Na': 22.99, 'Nb': 92.906, 'Nd': 144.24, 'Ne': 20.18, 'Ni': 58.693, 'O': 15.999, 'Os': 190.23, 'P': 30.974, 'Pa': 231.04, 'Pb': 207.2, 'Pd': 106.42, 'Pt': 195.08, 'Rb': 85.468, 'Re': 186.21, 'Rh': 102.91, 'Ru': 101.07, 'S': 32.06, 'Sb': 121.76, 'Sc': 44.956, 'Se': 78.971, 'Si': 28.085, 'Sm': 150.36, 'Sn': 118.71, 'Sr': 87.62, 'Ta': 180.95, 'Tb': 158.93, 'Te': 127.6, 'Th': 232.04, 'Ti': 47.867, 'Tl': 204.38, 'Tm': 168.93, 'U': 238.03, 'V': 50.942, 'W': 183.84, 'X': 0.0, 'Xe': 131.29, 'Y': 88.906, 'Yb': 173.05, 'Zn': 65.38, 'Zr': 91.224}
  COVALENT_RADII = {'Ag': 1.45, 'Al': 1.21, 'Ar': 1.06, 'As': 1.19, 'Au': 1.36, 'B': 0.84, 'Ba': 2.15, 'Be': 0.96, 'Bi': 1.48, 'Br': 1.2, 'C': 0.76, 'Ca': 1.76, 'Cd': 1.44, 'Ce': 2.04, 'Cl': 1.02, 'Co': 1.5, 'Cr': 1.39, 'Cs': 2.44, 'Cu': 1.32, 'D': 0.31, 'Dy': 1.92, 'Er': 1.89, 'Eu': 1.98, 'F': 0.57, 'Fe': 1.52, 'Ga': 1.22, 'Gd': 1.96, 'Ge': 1.2, 'H': 0.31, 'He': 0.28, 'Hf': 1.75, 'Hg': 1.32, 'Ho': 1.92, 'I': 1.39, 'In': 1.42, 'Ir': 1.41, 'K': 2.03, 'Kr': 1.16, 'La': 2.07, 'Li': 1.28, 'Lu': 1.87, 'Mg': 1.41, 'Mn': 1.61, 'Mo': 1.54, 'N': 0.71, 'Na': 1.66, 'Nb': 1.64, 'Nd': 2.01, 'Ne': 0.58, 'Ni': 1.24, 'O': 0.66, 'Os': 1.44, 'P': 1.07, 'Pa': 2.0, 'Pb': 1.46, 'Pd': 1.39, 'Pt': 1.36, 'Rb': 2.2, 'Re': 1.51, 'Rh': 1.42, 'Ru': 1.46, 'S': 1.05, 'Sb': 1.39, 'Sc': 1.7, 'Se': 1.2, 'Si': 1.11, 'Sm': 1.98, 'Sn': 1.39, 'Sr': 1.95, 'Ta': 1.7, 'Tb': 1.94, 'Te': 1.38, 'Th': 2.06, 'Ti': 1.6, 'Tl': 1.45, 'Tm': 1.9, 'U': 1.96, 'V': 1.53, 'W': 1.62, 'X': 0.0, 'Xe': 1.4, 'Y': 1.9, 'Yb': 1.87, 'Zn': 1.22, 'Zr': 1.75}
  ELEMENT_PROP = number symbol name period group weight vdw_radius covalent_radius 0 0 X Dummy 0 0 0.0000 0.00 0.00 1 1 H Hydrogen 1 1 1.0080 1.20 0.31 2 1 D Deuterium 1 1 2.0140 1.20 0.31 3 2 He Helium 1 18 4.0026 1.43 0.28 4 3 Li Lithium 2 1 6.9400 2.12 1.28 .. ... ... ... ... ... ... ... ... 83 82 Pb Lead 6 14 207.2000 2.60 1.46 84 83 Bi Bismuth 6 15 208.9800 2.54 1.48 91 90 Th Thorium 7 3 232.0400 2.93 2.06 92 91 Pa Protactinium 7 3 231.0400 2.88 2.00 93 92 U Uranium 7 3 238.0300 2.71 1.96 [85 rows x 8 columns]
  calc_cen_of_weight(coordinates: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]]

    Calculate center of weight.

    Parameters:

      coordinates (NDArray[np.float64]) – Coordinates of monomolecular.

    Returns:

      Center of weight.

    Return type:

      NDArray[np.float64]

  convert_cart_to_frac(cart_coord: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]]

    Convert Cartesian coordinates to fractional coordinates.

    Parameters:

      cart_coord (NDArray[np.float64]) – Cartesian coordinates.

    Returns:

      Fractional coordinates.

    Return type:

      NDArray[np.float64]

  convert_frac_to_cart(frac_coord: ndarray[Any, dtype[float64]]) → ndarray[Any, dtype[float64]]

    Convert fractional coordinates to Cartesian coordinates.

    Parameters:

      frac_coord (NDArray[np.float64]) – Fractional coordinates.

    Returns:

      Cartesian coordinates.

    Return type:

      NDArray[np.float64]

  expand_mols(expand_range: int = 1) → Dict[Tuple[int, int, int], Dict[int, List[Tuple[str, ndarray[Any, dtype[float64]]]]]]

    Generate molecules around unique molecules.

    Parameters:

      expand_range (int) – The number of molecular cycles produced., by default 1

    Returns:

      A nested dictionary containing the expanded molecular structure:

      - Outer key: Tuple[int, int, int]

          Represents the unit cell offset (i, j, k) relative to the origin unit cell. For example, (0, 0, 0) is the origin unit cell, (1, 0, 0) is one unit cell away in the a-direction, etc.

      - Inner key: int

          The index of the unique molecule within that unit cell.

      - Value: Tuple[List[str], NDArray[np.float64]]

          A list containing molecular information: - List[str]: Element symbols of the molecule - NDArray[np.float64]: Cartesian coordinates of the molecule (shape: (3, n))

    Return type:

      Dict[Tuple[int, int, int], Dict[int, List[Tuple[str, NDArray[np.float64]]]]]

  export_unit_cell_file(file_path: str, format: Literal['mol', 'xyz'] = 'mol') → None

    export unit cell file

    Parameters:

      - file_path (str) – Path of the file to be saved.

      - format (Literal['mol', 'xyz']) – Format of the file to be saved.

  parent_dir = PosixPath('/home/subaru/Documents/manage-with-git/mcal/src/mcal')
  remove_duplicates(symbol: List[str], coordinate: ndarray[Any, dtype[float64]], tol: float = 0.0001) → Tuple[List[str], ndarray[Any, dtype[float64]]]

    Remove duplicates from symbol and coordinate arrays based on coordinate with a given tolerance.

    Parameters:

      - symbol (List[str]) – Symbols of molecules.

      - coordinate (NDArray[np.float64]) – Coordinates of molecules.

      - tol (float) – Tolerance for duplicate detection.

    Returns:

      Symbols and coordinates of unique molecules.

    Return type:

      Tuple[List[str], NDArray[np.float64]]

exception mcal.utils.cif_reader.ElementPropertiesIsNotDefinedError

  Bases: `Exception`

  Exception raised when element properties is not defined.

class mcal.utils.cif_reader.FileIO

  Bases: `object`

  add_adjacency_mat(adjacency_mat: ndarray[Any, dtype[bool]]) → None

    add adjacency matrix

    Parameters:

      adjacency_mat (NDArray[bool]) – Adjacency matrix.

  add_coordinates(coordinates: ndarray[Any, dtype[float64]]) → None

    add coordinates

    Parameters:

      coordinates (NDArray[np.float64]) – Coordinates.

  add_symbols(symbols: List[str]) → None

    add symbols

    Parameters:

      symbols (List[str]) – Symbols.

  export_mol_file(file_path: str, header1: str, header2: str) → None

    export mol file

    Parameters:

      - file_path (str) – Path of the file to be saved.

      - header1 (str) – Header line 1.

      - header2 (str) – Header line 2.

  export_xyz_file(file_path: str, comment: str) → None

    export xyz file

    Parameters:

      - file_path (str) – Path of the file to be saved.

      - comment (str) – Comment.

exception mcal.utils.cif_reader.SymmetryIsNotDefinedError

  Bases: `Exception`

  Exception raised when symmetry is not defined.

exception mcal.utils.cif_reader.ZValueIsNotMatchError

  Bases: `Exception`

  Exception raised when z value is not match.

## mcal.utils.gaus_log_reader module

Gaussian log file reader (2025/06/21)

class mcal.utils.gaus_log_reader.FileReader(file_path, buffer_size=8192)

  Bases: `object`

  File reader that reads line by line from the end.

  Examples

      >>> with FileReader('sample.txt') as f:
      ...     while True:
      ...         line = f.reversed_readline()
      ...         if not line:
      ...             break
      ...         print(line)

  close()
  reversed_readline()

mcal.utils.gaus_log_reader.check_normal_termination(log_file: str) → bool

  Check if the calculation terminated normally.

  Parameters:

    log_file (str) – Path to the log file

  Returns:

    True if the calculation terminated normally, False otherwise

  Return type:

    bool

## mcal.utils.gjf_maker module

GjfMaker beta (2025/08/18)

class mcal.utils.gjf_maker.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}
  ELEMENT_PROP = number symbol name period group weight vdw_radius covalent_radius 0 0 X Dummy 0 0 0.0000 0.00 0.00 1 1 H Hydrogen 1 1 1.0080 1.20 0.31 2 1 D Deuterium 1 1 2.0140 1.20 0.31 3 2 He Helium 1 18 4.0026 1.43 0.28 4 3 Li Lithium 2 1 6.9400 2.12 1.28 .. ... ... ... ... ... ... ... ... 115 114 Fl Flerovium 7 14 NaN NaN NaN 116 115 Mc Moscovium 7 15 NaN NaN NaN 117 116 Lv Livermorium 7 16 NaN NaN NaN 118 117 Ts Tennessine 7 17 NaN NaN NaN 119 118 Og Oganesson 7 18 NaN NaN NaN [120 rows x 8 columns]
  add_link() → None

    Add the link of the gjf file.

  add_root(root: str) → None

    Add the root of the gjf file.

  create_chk_file() → None

    Create the chk file.

  create_rwf_file() → None

    Create the rwf file.

  export_gjf(file_name: str, save_dir: str = '.', chk_rwf_name: str | None = None) → None

    Export the gjf file.

    Parameters:

      - file_name (str) – Name of the gjf file.

      - save_dir (str) – Directory to save the gjf file.

      - chk_rwf_name (Optional[str]) – Name of the chk or rwf file.

  opt(tight: bool = True) → None

    Set the optimization option of the gjf file.

    Parameters:

      tight (bool) – If True, the optimization is tight, by default True.

  output_detail() → None

    Output the detail to log file.

  parent_dir = PosixPath('/home/subaru/Documents/manage-with-git/mcal/src/mcal')
  reset_variable() → None

    Reset the variables of the gjf file.

  set_charge_spin(charge: int, spin: int) → None

    Set the charge and spin of the molecule.

    Parameters:

      - charge (int) – Charge of the molecule.

      - spin (int) – Spin of the molecule.

  set_coordinates(coordinates: List[Tuple[float, float, float]]) → None

    Set the coordinates of the molecule.

    Parameters:

      coordinates (List[Tuple[float, float, float]]) – Coordinates of the molecule.

  set_function(function: str) → None

    Set the function of the gjf file.

    Parameters:

      function (str) – Function of the gjf file.

  set_resource(cpu_num: int, mem_num: int, mem_unit: str = 'GB') → None

    Set the number of cpu and memory.

    Parameters:

      - cpu_num (int) – Number of cpu.

      - mem_num (int) – Number of memory.

      - mem_unit (str) – Unit of memory, by default ‘GB’.

  set_symbols(symbols: List[str]) → None

    Set the symbols of the molecule.

    Parameters:

      symbols (List[str]) – Symbols of the molecule.

  set_title(title: str) → None

    Set the title of the gjf file.

    Parameters:

      title (str) – Title of the gjf file.

## Module contents