mcal.utils package

Submodules

mcal.utils.cif_reader module

CifReader beta (2026/03/29)

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  ...    weight  vdw_radius  covalent_radius 0        0      X         Dummy  ...    0.0000        0.00             0.00 1        1      H      Hydrogen  ...    1.0080        1.20             0.31 2        1      D     Deuterium  ...    2.0140        1.20             0.31 3        2     He        Helium  ...    4.0026        1.43             0.28 4        3     Li       Lithium  ...    6.9400        2.12             1.28 ..     ...    ...           ...  ...       ...         ...              ... 83      82     Pb          Lead  ...  207.2000        2.60             1.46 84      83     Bi       Bismuth  ...  208.9800        2.54             1.48 91      90     Th       Thorium  ...  232.0400        2.93             2.06 92      91     Pa  Protactinium  ...  231.0400        2.88             2.00 93      92      U       Uranium  ...  238.0300        2.71             1.96  [85 rows x 8 columns]

calc_cen_of_weight(coordinates: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[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[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[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[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[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 | Tuple[int, int, int] = 1) → Dict[Tuple[int, int, int], Dict[int, List[Tuple[str, ndarray[tuple[Any, ...], dtype[float64]]]]]]

Generate molecules around unique molecules.

Parameters:

expand_range (int or Tuple[int, int, int]) – The number of unit cells to expand along each lattice axis, by default 1. An int applies the same range to all three axes. A 3-tuple (na, nb, nc) sets a per-axis range: each axis runs from -n to +n. For example, (2, 2, 0) produces a 5x5x1 slab.

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

Raises:

ValueError – If any element of expand_range is negative, or if a sequence of length other than 3 is passed.

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/runner/work/mcal/mcal/src/mcal')

remove_duplicates(symbol: List[str], coordinate: ndarray[tuple[Any, ...], dtype[float64]], tol: float = 0.0001) → Tuple[List[str], ndarray[tuple[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[tuple[Any, ...], dtype[bool]]) → None

add adjacency matrix

Parameters:

adjacency_mat (NDArray[bool]) – Adjacency matrix.

add_coordinates(coordinates: ndarray[tuple[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  ...  weight  vdw_radius  covalent_radius 0         0      X        Dummy  ...  0.0000        0.00             0.00 1         1      H     Hydrogen  ...  1.0080        1.20             0.31 2         1      D    Deuterium  ...  2.0140        1.20             0.31 3         2     He       Helium  ...  4.0026        1.43             0.28 4         3     Li      Lithium  ...  6.9400        2.12             1.28 ..      ...    ...          ...  ...     ...         ...              ... 115     114     Fl    Flerovium  ...     NaN         NaN              NaN 116     115     Mc    Moscovium  ...     NaN         NaN              NaN 117     116     Lv  Livermorium  ...     NaN         NaN              NaN 118     117     Ts   Tennessine  ...     NaN         NaN              NaN 119     118     Og    Oganesson  ...     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/runner/work/mcal/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.log module

Logging helpers for the mcal package.

Warnings and other diagnostics are emitted through the standard logging module to stderr so that they stay separate from the program results printed to stdout. Colour is applied only when stderr is an interactive terminal.

mcal.utils.log.configure_logging(level: int = 30) → None

Attach a stderr handler to the mcal package logger.

Idempotent: calling it more than once leaves the existing handler in place and only updates the level. Intended to be called once from the CLI entry point. When never called (e.g. library use), logging falls back to its last-resort handler, which still emits WARNING and above to stderr.

Parameters:

level (int, optional) – Minimum level the package logger emits, by default logging.WARNING.

Return type:

None

mcal.utils.log.get_logger(name: str) → Logger

Return a logger for the given name.

Parameters:

name (str) – Logger name, conventionally the module __name__ so the logger becomes a child of the mcal package logger.

Returns:

The requested logger.

Return type:

logging.Logger

Module contents