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