bcal.calculations package

Submodules

bcal.calculations.bcal module

Band structure and effective mass from a generated structure directory.

This module consumes the per-crystal layout produced by bcal.utils.input_maker.InputMaker (structure.json + inputs/) and runs the calculation pipeline:

inputs/ –(DFT)–> logs/ –(extract)–> matrices/ –(TB)–> results/

The crystal-symmetry transfer-integral construction (one DFT per unique dimer type, reused for symmetry-equivalent pairs) is the core of bcal and is ported from the reference implementation. The external library yu-tcal is reused for SCF orchestration (TcalPySCF/TcalORCA driven with skip_monomer_num), Gaussian log/matrix parsing (Tcal.read_matrix etc.), and the transfer-integral formula/unit (Tcal.EV).

class bcal.calculations.bcal.Bcal(struct_dir, num_mo=15, engine='g16', cpu=4, mem=16, method='B3LYP/6-31G(d,p)', bse=False)[source]

Bases: object

Run the band-structure / effective-mass pipeline for one structure.

Parameters:

  • struct_dir (str or pathlib.Path) – Directory containing structure.json and inputs/ (as written by bcal.utils.input_maker.InputMaker). logs/, matrices/ and results/ are created beneath it.

  • num_mo (int, optional) – Number of MOs per molecule on each side of the frontier; the total window is n = 2 * num_mo orbitals (num_mo HOMO-side and num_mo LUMO-side). By default 15.

  • engine (str, optional) – Calculation engine and the single source of engine selection: "g16"/"g09" (Gaussian), "pyscf"/"gpu4pyscf" (PySCF), "orca" (ORCA). By default "g16".

  • cpu (int, optional) – Number of CPU cores / threads for the engine, by default 4.

  • mem (int, optional) – Memory in GB for the engine, by default 16.

  • method (str, optional) – DFT method/basis string, by default "B3LYP/6-31G(d,p)".

  • bse (bool, optional) – Use Basis Set Exchange to resolve the basis set (PySCF/gpu4pyscf only; ignored for other engines), by default False.

EV: float = 27211.38456571948
run_dft(read=False, resume=False)[source]

Execute (or read) DFT, extract matrices, and build transfer integrals.

Parameters:

  • read (bool, optional) – If True, do not run SCF. Reuse matrices/ if present, otherwise parse existing engine outputs (Gaussian logs/, PySCF chkfiles). By default False.

  • resume (bool, optional) – If True, skip inputs whose engine output already completed, by default False.

Return type:

None

cal_transfer_integrals_all()[source]

Build the transfer-integral tensor for all pairs using symmetry.

Returns:

Transfer integrals in eV for the n-orbital window of each pair.

Return type:

numpy.ndarray, shape (n_pairs, n, n)

cal_reciprocal_lattice()[source]

Calculate reciprocal lattice vectors from the direct lattice.

Return type:

ndarray

energies_at_ks(k)[source]

Calculate band energies at given k-points.

Parameters:

k (numpy.ndarray, shape (N, 3) or (3,)) – k-point vectors in reciprocal space.

Returns:

Band energies (eV) at each k-point.

Return type:

numpy.ndarray, shape (N, m*n)

cal_effective_mass(draw_band=True, band_path='XGYGZ')[source]

Calculate effective masses at the HOMO maximum and LUMO minimum.

Parameters:

  • draw_band (bool, optional) – If True, draw and save a band diagram, by default True.

  • band_path (str, optional) – High-symmetry k-path passed to draw_band_diagram() when draw_band is True, by default "XGYGZ".

Returns:

Principal effective masses (in units of electron mass): the first three at the HOMO maximum, the last three at the LUMO minimum.

Return type:

numpy.ndarray, shape (6,)

Notes

The band-edge k-points are also stored on the instance as homo_edge_frac/lumo_edge_frac (fractional reciprocal-lattice coordinates) and homo_edge_label/lumo_edge_label (the matching high-symmetry label from HIGH_SYMMETRY_POINTS, or None).

The principal effective masses (sorted by |m| ascending) and their unit principal-axis vectors (rows, Cartesian reciprocal-space) are stored as homo_em/lumo_em and homo_em_vectors/lumo_em_vectors; the returned (6,) array keeps the original unsorted layout for backward compatibility. Directions with nearly zero inverse mass are reported as inf.

refine_around_min_or_max(k_points, mo_index, window_size=0.01, max_or_min='max')[source]

Refine a band extremum k-point with Nelder-Mead optimization.

Parameters:
Return type:

ndarray

draw_band_diagram(path='XGYGZ')[source]

Draw and save a band diagram along a high-symmetry k-path.

The path string is read one character at a time; each character is a high-symmetry point label from HIGH_SYMMETRY_POINTS ("G" denotes Gamma). For "XGYGZ" the path is X -> Gamma -> Y -> Gamma -> Z. The horizontal axis is the cumulative k-distance along the path and the ticks are placed at the requested points. The figure is written to results/band.png and the raw data to results/band.npz.

Parameters:

path (str, optional) – Sequence of single-character high-symmetry point labels, by default "XGYGZ".

Raises:

ValueError – If path contains a label absent from HIGH_SYMMETRY_POINTS, or has fewer than two points.

Return type:

None

band_edges_on_path(path)[source]

Report whether the HOMO/LUMO band edges lie on the band-diagram path.

A band edge is “on the path” when its k-point lies on one of the straight segments connecting the high-symmetry nodes of path (the same geometry drawn by draw_band_diagram()), and is therefore visible in results/band.png. When an edge is off the path, the plotted HOMO/LUMO curve does not reach the true band extremum.

Parameters:

path (str) – High-symmetry k-path string, identical to the one passed to draw_band_diagram() / cal_effective_mass().

Returns:

Maps "HOMO" and "LUMO" to True if that band edge lies on the drawn path.

Return type:

dict[str, bool]

Raises:

RuntimeError – If the band edges have not been computed yet; call cal_effective_mass() first.

Module contents

class bcal.calculations.Bcal(struct_dir, num_mo=15, engine='g16', cpu=4, mem=16, method='B3LYP/6-31G(d,p)', bse=False)[source]

Bases: object

Run the band-structure / effective-mass pipeline for one structure.

Parameters:

  • struct_dir (str or pathlib.Path) – Directory containing structure.json and inputs/ (as written by bcal.utils.input_maker.InputMaker). logs/, matrices/ and results/ are created beneath it.

  • num_mo (int, optional) – Number of MOs per molecule on each side of the frontier; the total window is n = 2 * num_mo orbitals (num_mo HOMO-side and num_mo LUMO-side). By default 15.

  • engine (str, optional) – Calculation engine and the single source of engine selection: "g16"/"g09" (Gaussian), "pyscf"/"gpu4pyscf" (PySCF), "orca" (ORCA). By default "g16".

  • cpu (int, optional) – Number of CPU cores / threads for the engine, by default 4.

  • mem (int, optional) – Memory in GB for the engine, by default 16.

  • method (str, optional) – DFT method/basis string, by default "B3LYP/6-31G(d,p)".

  • bse (bool, optional) – Use Basis Set Exchange to resolve the basis set (PySCF/gpu4pyscf only; ignored for other engines), by default False.

EV: float = 27211.38456571948
name: str
MOs: ndarray | None
energies: ndarray | None
n_elect: int | None
n_basis: int | None
n_basis_d: int | None
ao_atom: ndarray | None
ao_xyz: ndarray | None
overlap_ori: ndarray | None
fock_ori: ndarray | None
levels: ndarray | None
trans: ndarray | None
band_energies: ndarray | None
homo_edge_frac: ndarray | None
lumo_edge_frac: ndarray | None
homo_edge_label: str | None
lumo_edge_label: str | None
homo_em: ndarray | None
lumo_em: ndarray | None
homo_em_vectors: ndarray | None
lumo_em_vectors: ndarray | None
run_dft(read=False, resume=False)[source]

Execute (or read) DFT, extract matrices, and build transfer integrals.

Parameters:

  • read (bool, optional) – If True, do not run SCF. Reuse matrices/ if present, otherwise parse existing engine outputs (Gaussian logs/, PySCF chkfiles). By default False.

  • resume (bool, optional) – If True, skip inputs whose engine output already completed, by default False.

Return type:

None

cal_transfer_integrals_all()[source]

Build the transfer-integral tensor for all pairs using symmetry.

Returns:

Transfer integrals in eV for the n-orbital window of each pair.

Return type:

numpy.ndarray, shape (n_pairs, n, n)

cal_reciprocal_lattice()[source]

Calculate reciprocal lattice vectors from the direct lattice.

Return type:

ndarray

energies_at_ks(k)[source]

Calculate band energies at given k-points.

Parameters:

k (numpy.ndarray, shape (N, 3) or (3,)) – k-point vectors in reciprocal space.

Returns:

Band energies (eV) at each k-point.

Return type:

numpy.ndarray, shape (N, m*n)

cal_effective_mass(draw_band=True, band_path='XGYGZ')[source]

Calculate effective masses at the HOMO maximum and LUMO minimum.

Parameters:

  • draw_band (bool, optional) – If True, draw and save a band diagram, by default True.

  • band_path (str, optional) – High-symmetry k-path passed to draw_band_diagram() when draw_band is True, by default "XGYGZ".

Returns:

Principal effective masses (in units of electron mass): the first three at the HOMO maximum, the last three at the LUMO minimum.

Return type:

numpy.ndarray, shape (6,)

Notes

The band-edge k-points are also stored on the instance as homo_edge_frac/lumo_edge_frac (fractional reciprocal-lattice coordinates) and homo_edge_label/lumo_edge_label (the matching high-symmetry label from HIGH_SYMMETRY_POINTS, or None).

The principal effective masses (sorted by |m| ascending) and their unit principal-axis vectors (rows, Cartesian reciprocal-space) are stored as homo_em/lumo_em and homo_em_vectors/lumo_em_vectors; the returned (6,) array keeps the original unsorted layout for backward compatibility. Directions with nearly zero inverse mass are reported as inf.

refine_around_min_or_max(k_points, mo_index, window_size=0.01, max_or_min='max')[source]

Refine a band extremum k-point with Nelder-Mead optimization.

Parameters:
Return type:

ndarray

draw_band_diagram(path='XGYGZ')[source]

Draw and save a band diagram along a high-symmetry k-path.

The path string is read one character at a time; each character is a high-symmetry point label from HIGH_SYMMETRY_POINTS ("G" denotes Gamma). For "XGYGZ" the path is X -> Gamma -> Y -> Gamma -> Z. The horizontal axis is the cumulative k-distance along the path and the ticks are placed at the requested points. The figure is written to results/band.png and the raw data to results/band.npz.

Parameters:

path (str, optional) – Sequence of single-character high-symmetry point labels, by default "XGYGZ".

Raises:

ValueError – If path contains a label absent from HIGH_SYMMETRY_POINTS, or has fewer than two points.

Return type:

None

band_edges_on_path(path)[source]

Report whether the HOMO/LUMO band edges lie on the band-diagram path.

A band edge is “on the path” when its k-point lies on one of the straight segments connecting the high-symmetry nodes of path (the same geometry drawn by draw_band_diagram()), and is therefore visible in results/band.png. When an edge is off the path, the plotted HOMO/LUMO curve does not reach the true band extremum.

Parameters:

path (str) – High-symmetry k-path string, identical to the one passed to draw_band_diagram() / cal_effective_mass().

Returns:

Maps "HOMO" and "LUMO" to True if that band edge lies on the drawn path.

Return type:

dict[str, bool]

Raises:

RuntimeError – If the band edges have not been computed yet; call cal_effective_mass() first.