bcal.utils package

Submodules

bcal.utils.input_maker module

InputMaker: generate monomer/dimer DFT inputs from a CIF structure.

This module reproduces the monomer/dimer input generation of the legacy make_files_for_bcal.py (CCDC-based) without the CCDC dependency, by reusing mcal.utils.cif_reader.CifReader and mcal.utils.gjf_maker.GjfMaker.

For each unique molecule in the unit cell a monomer input is written, and for each symmetry-unique neighboring pair (dimer) a dimer input is written. The crystal topology (lattice, sites, dimer types, pair table) is saved as a human-readable structure.json; the bulky per-calculation numerics are left to later pipeline stages.

bcal.utils.input_maker.cal_center_of_weight(cart_coos, weight_array=None)[source]

Calculate coordinates of center of weight.

Parameters:

  • cart_coos (np.ndarray, shape (n_atoms, 3)) – Cartesian coordinates in Angstroms.

  • weight_array (np.ndarray of shape (n_atoms,), optional) – Atomic weights. If None, the arithmetic mean is returned.

Returns:

Center-of-weight coordinates in Angstroms.

Return type:

np.ndarray, shape (3,)

bcal.utils.input_maker.cal_I(coo_array_ori, weight_array_ori=None)[source]

Calculate the inertia tensor and return its eigenvalues and eigenvectors.

Parameters:

  • coo_array_ori (np.ndarray, shape (n_atoms, 3)) – Cartesian coordinates in Angstroms.

  • weight_array_ori (np.ndarray of shape (n_atoms,), optional) – Atomic weights. If None, unit weights are assumed.

Returns:

  • moment (np.ndarray, shape (3,)) – Principal moments of inertia (eigenvalues of the inertia tensor).

  • axis (np.ndarray, shape (3, 3)) – Principal axes of inertia (eigenvectors, column-wise).

Return type:

Tuple[ndarray, ndarray]

bcal.utils.input_maker.check_vdw_contact(cart1, symbols1, cart2, symbols2, margin=0.7)[source]

Return True if any atom pair from two molecules is within VdW contact.

Parameters:

  • cart1 (np.ndarray, shape (n1, 3)) – Cartesian coordinates of molecule 1 in Angstroms.

  • symbols1 (list of str) – Element symbols for molecule 1.

  • cart2 (np.ndarray, shape (n2, 3)) – Cartesian coordinates of molecule 2 in Angstroms.

  • symbols2 (list of str) – Element symbols for molecule 2.

  • margin (float, optional) – Extra distance (Angstrom) added to the sum of VdW radii when deciding contact, by default 0.7.

Returns:

True if at least one atom pair is within the VdW contact threshold.

Return type:

bool

bcal.utils.input_maker.compare_coordinates(dimer_coo, ref_coo)[source]

Determine the symmetry relationship between a dimer and a reference dimer.

Parameters:

  • dimer_coo (np.ndarray, shape (2, n_atoms, 3)) – Cartesian coordinates of the dimer to compare.

  • ref_coo (np.ndarray, shape (2, n_atoms, 3)) – Cartesian coordinates of the reference dimer.

Returns:

  • bool_trans_array (np.ndarray or None) – [is_transposed, sign_x, sign_y, sign_z]. None only if no symmetry operation maps the dimer onto the reference (the two are not actually the same dimer type). When several operations match equally well – a benign ambiguity for dimers with their own point-group symmetry – the best one is returned; the resulting orbital-gauge difference is absorbed downstream by the self-overlap repair in Bcal._build_embedded_mo() and Bcal._enforce_hermiticity().

  • atoms_order (np.ndarray or None) – Per-atom mapping indices of length 2 * n_atoms. None if no atom reordering is needed.

Return type:

Tuple[ndarray | None, ndarray | None]

class bcal.utils.input_maker.InputMaker(reader, cpu, mem, method, engine='g16', expand_range=2, vdw_margin=0.7)[source]

Bases: object

Generate monomer/dimer inputs and structure.json from a parsed CIF.

Parameters:

  • reader (CifReader) – Parsed CIF data.

  • cpu (int) – Number of CPU cores to request in Gaussian inputs.

  • mem (int) – Memory in GB to request in Gaussian inputs.

  • method (str) – DFT method/basis string (e.g. "PBEPBE/6-31G(d,p)").

  • engine (str, optional) – Calculation engine. "g16"/"g09" produce .gjf inputs; any other value ("pyscf", "gpu4pyscf", "orca") produces .xyz geometry files, by default "g16".

  • expand_range (int, optional) – Supercell expansion range for the neighbor search; produces a (2 * expand_range + 1) ** 3 supercell, by default 2 (i.e. 5x5x5).

  • vdw_margin (float, optional) – Extra distance (Angstrom) added to the sum of VdW radii in the contact criterion, by default 0.7.

generate(save_dir)[source]

Generate all monomer/dimer inputs and write structure.json.

Parameters:

save_dir (str or pathlib.Path) – Directory of the structure. inputs/ is created beneath it and structure.json is written directly into it.

Returns:

The structure metadata that was serialized to structure.json.

Return type:

dict

bcal.utils.log module

Logging helpers for the bcal 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.

bcal.utils.log.configure_logging(level=30)[source]

Attach a stderr handler to the bcal 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

bcal.utils.log.get_logger(name)[source]

Return a logger for the given name.

Parameters:

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

Returns:

The requested logger.

Return type:

logging.Logger

Module contents

class bcal.utils.InputMaker(reader, cpu, mem, method, engine='g16', expand_range=2, vdw_margin=0.7)[source]

Bases: object

Generate monomer/dimer inputs and structure.json from a parsed CIF.

Parameters:

  • reader (CifReader) – Parsed CIF data.

  • cpu (int) – Number of CPU cores to request in Gaussian inputs.

  • mem (int) – Memory in GB to request in Gaussian inputs.

  • method (str) – DFT method/basis string (e.g. "PBEPBE/6-31G(d,p)").

  • engine (str, optional) – Calculation engine. "g16"/"g09" produce .gjf inputs; any other value ("pyscf", "gpu4pyscf", "orca") produces .xyz geometry files, by default "g16".

  • expand_range (int, optional) – Supercell expansion range for the neighbor search; produces a (2 * expand_range + 1) ** 3 supercell, by default 2 (i.e. 5x5x5).

  • vdw_margin (float, optional) – Extra distance (Angstrom) added to the sum of VdW radii in the contact criterion, by default 0.7.

generate(save_dir)[source]

Generate all monomer/dimer inputs and write structure.json.

Parameters:

save_dir (str or pathlib.Path) – Directory of the structure. inputs/ is created beneath it and structure.json is written directly into it.

Returns:

The structure metadata that was serialized to structure.json.

Return type:

dict