mcal.utils package¶

Submodules¶

mcal.utils.cif_reader module¶

CifReader beta (2025/10/30)

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('/Users/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('/Users/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.

mcal.utils package¶

Submodules¶

mcal.utils.cif_reader module¶

mcal.utils.gaus_log_reader module¶

mcal.utils.gjf_maker module¶

Module contents¶