ocal.utils package

Submodules

ocal.utils.cif_reader module

CifReader beta (2026/03/29)

class ocal.utils.cif_reader.CifReader(cif_path)

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.

Parameters:

cif_path (str)

parent_dir = PosixPath('/home/runner/work/ocal/ocal/src/ocal')

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  [86 rows x 8 columns]

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, 'Pr': 140.91, '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, 'Pr': 2.03, '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}

calc_cen_of_weight(coordinates)

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)

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)

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=1)

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, format='mol')

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.

Return type:

None

remove_duplicates(symbol, coordinate, tol=0.0001)

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 ocal.utils.cif_reader.ElementPropertiesIsNotDefinedError

Bases: Exception

Exception raised when element properties is not defined.

exception ocal.utils.cif_reader.SymmetryIsNotDefinedError

Bases: Exception

Exception raised when symmetry is not defined.

exception ocal.utils.cif_reader.ZValueIsNotMatchError

Bases: Exception

Exception raised when z value is not match.

class ocal.utils.cif_reader.FileIO

Bases: object

add_adjacency_mat(adjacency_mat)

add adjacency matrix

Parameters:

adjacency_mat (NDArray[bool]) – Adjacency matrix.

Return type:

None

add_coordinates(coordinates)

add coordinates

Parameters:

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

Return type:

None

add_symbols(symbols)

add symbols

Parameters:

symbols (List[str]) – Symbols.

Return type:

None

export_mol_file(file_path, header1, header2)

export mol file

Parameters:

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

• header1 (str) – Header line 1.

• header2 (str) – Header line 2.

Return type:

None

export_xyz_file(file_path, comment)

export xyz file

Parameters:

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

• comment (str) – Comment.

Return type:

None

ocal.utils.cube_reader module

Cube file reader and orbital tail fraction (OTF) calculator.

ocal.utils.cube_reader.load_element_tables(path=PosixPath('/home/runner/work/ocal/ocal/src/ocal/constants/element_properties.csv'))

Load vdW radii and atomic-number tables from element_properties.csv.

Reads with utf-8-sig so a leading BOM does not corrupt the first column name. Rows with number == 0 (Dummy X) are omitted from the atomic-number maps. Empty, non-finite, or non-positive vdw_radius values are omitted from the radius map (lookups then fail explicitly). For number → symbol, the first CSV row wins (so 1 → "H", not "D").

Parameters:

path (Path) – Path to element_properties.csv.

Returns:

(van_der_waals_radius, elements_num, rev_elements_num).

Return type:

tuple[dict[str, float], dict[str, int], dict[int, str]]

ocal.utils.cube_reader.read_cubefile(filepath, plus_one=True)

Read and process a cube file.

Parameters:

• filepath (Path) – The path of the cube file to be processed.

• plus_one (bool) – A flag to adjust the starting line for volume data.

Returns:

A tuple containing voxel coordinates, normalized voxel values, atomic symbols, atomic coordinates, and van der Waals radii.

Return type:

tuple

ocal.utils.cube_reader.calc_distance_matrix(voxel_coords, single_coords, single_VDWrad)

Calculate the distance matrix.

Parameters:

• voxel_coords (np.ndarray) – The voxel coordinates.

• single_coords (np.ndarray) – The coordinates of single atoms.

• single_VDWrad (np.ndarray) – The van der Waals radii of single atoms.

Returns:

The calculated distance matrix.

Return type:

np.ndarray

ocal.utils.cube_reader.calc_otf(cube_path)

Compute the orbital tail fraction and density sum for a cube file.

The fraction is the sum of normalized probability density over voxels outside the van der Waals surface (signed distance >= 0). density_sum is the total of all normalized voxel values and is used as a sanity check that the cube is properly normalized.

Parameters:

cube_path (Path) – Path to a Gaussian MO cube file.

Returns:

(otf, density_sum) where otf is the orbital tail fraction and density_sum is norm_voxel_val.sum().

Return type:

tuple[float, float]

ocal.utils.gaus_log_reader module

Gaussian log file reader (2025/06/21)

ocal.utils.gaus_log_reader.check_normal_termination(log_file)

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

class ocal.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()

ocal.utils.gjf_maker module

GjfMaker beta (2025/08/18)

class ocal.utils.gjf_maker.GjfMaker(remove_radical_flag=False)

Bases: object

Parameters:

remove_radical_flag (bool)

parent_dir = PosixPath('/home/runner/work/ocal/ocal/src/ocal')

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]

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}

add_link()

Add the link of the gjf file.

Return type:

None

add_root(root)

Add the root of the gjf file.

Parameters:

root (str)

Return type:

None

create_chk_file()

Create the chk file.

Return type:

None

create_rwf_file()

Create the rwf file.

Return type:

None

export_gjf(file_name, save_dir='.', chk_rwf_name=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.

Return type:

None

opt(tight=True)

Set the optimization option of the gjf file.

Parameters:

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

Return type:

None

output_detail()

Output the detail to log file.

Return type:

None

reset_variable()

Reset the variables of the gjf file.

Return type:

None

set_charge_spin(charge, spin)

Set the charge and spin of the molecule.

Parameters:

• charge (int) – Charge of the molecule.

• spin (int) – Spin of the molecule.

Return type:

None

set_coordinates(coordinates)

Set the coordinates of the molecule.

Parameters:

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

Return type:

None

set_function(function)

Set the function of the gjf file.

Parameters:

function (str) – Function of the gjf file.

Return type:

None

set_resource(cpu_num, mem_num, mem_unit='GB')

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’.

Return type:

None

set_symbols(symbols)

Set the symbols of the molecule.

Parameters:

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

Return type:

None

set_title(title)

Set the title of the gjf file.

Parameters:

title (str) – Title of the gjf file.

Return type:

None

ocal.utils.structure_reader module

Structure file readers returning Cartesian coordinates in Angstrom.

ocal.utils.structure_reader.read_gjf(path)

Read atomic symbols and Cartesian coordinates from a Gaussian gjf/com file.

Only the symbol x y z Cartesian format is supported. Charge and spin on the charge-spin line are ignored (always treated as 0 1 downstream).

Parameters:

path (Path) – Path to a .gjf or .com file.

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

Raises:

ValueError – If no charge-spin line is found, no atoms are present, or a line uses an unsupported format (atomic number, freeze flag, Z-matrix, ONIOM).

ocal.utils.structure_reader.read_xyz(path)

Read atomic symbols and Cartesian coordinates from an XYZ file.

Lines from the 3rd onward are parsed as token x y z. If token is an atomic number, it is converted to an element symbol via rev_elements_num.

Parameters:

path (Path) – Path to a .xyz file.

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

Raises:

ValueError – If no atoms are found or an unknown atomic number appears.

ocal.utils.structure_reader.read_mol(path)

Read atomic symbols and Cartesian coordinates from an MDL mol (V2000) file.

Parameters:

path (Path) – Path to a .mol file.

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

Raises:

ValueError – If the file is V3000 or the atom block cannot be parsed.

ocal.utils.structure_reader.read_mol2(path)

Read atomic symbols and Cartesian coordinates from a Tripos mol2 file.

Element symbols are taken from the atom_type field before the first . (e.g. C.ar → C).

Parameters:

path (Path) – Path to a .mol2 file.

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

Raises:

ValueError – If the @<TRIPOS>ATOM section is missing or empty.

ocal.utils.structure_reader.read_cif(path)

Extract the first unique molecule from a CIF file as Cartesian coordinates.

Uses CifReader and molecule index 0. When z_value > 1, a message is printed that the first molecule is used.

Parameters:

path (Path) – Path to a .cif file.

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

ocal.utils.structure_reader.read_structure(path)

Dispatch structure reading by file suffix (case-insensitive).

Parameters:

path (Path) – Path to a structure file (.gjf, .com, .xyz, .mol, .mol2, or .cif).

Returns:

(symbols, coordinates) in Angstrom.

Return type:

tuple[list[str], list[tuple[float, float, float]]]

Raises:

ValueError – If the suffix is not supported.

Module contents