vibeqc.basis_crystal¶

CRYSTAL-format basis-set parser and NWChem/.g94 emitter.

Targets the per-element CRYSTAL basis-set files distributed by the Bredow group (Peintinger–Vilela Oliveira–Bredow, pob-*): one file per element, named ZZ_Sym (e.g. 06_C), plain-text CRYSTAL input.

Supported today¶

All-electron shells (S, SP, P, D, F, G). These cover the light-element Bredow sets (pob-TZVP and pob-DZVP-rev2 for H-Br). The emitter produces NWChem/.g94 files that libint loads without modification.

Not yet supported¶

ECP blocks (INPUT header on Rb-I and Cs-Po pob-* archives). Parsing them is trivial; applying them in vibe-qc needs libecpint integration, which is a separate follow-on. Such files raise NotImplementedError for now.

CRYSTAL per-element format summary¶

Line 1::: Z NSHELL
or for ECP-using atoms::: (200 + Z) NSHELL
Each shell starts with::: ITYPE LAT NG CHE SCAL

where

ITYPE – 0 = user-defined (the only case the Bredow files use).
LAT – shell angular-momentum code:
0=S, 1=SP, 2=P, 3=D, 4=F, 5=G.
NG – number of primitive Gaussians.
CHE – formal occupancy (electrons) assigned to this shell.
SCAL – scale factor applied to the exponents (1.0 = as-written).

Followed by NG lines of exponent coefficient (or exponent s_coef p_coef for SP shells).

Functions

`build_periodic_ecp_data`(system, atoms)	Build ECP data for a PeriodicSystem from parsed CRYSTAL atom bases.
`crystal_ecp_to_libecpint_arrays`(ecp)	Flatten a `CrystalECP` into libecpint primitive arrays.
`emit_crystal`(atoms)	Convert per-element basis specs into CRYSTAL inline-basis format.
`emit_g94`(atoms[, header_comment])	Convert a list of per-element basis specs into a single .g94 (Gaussian / NWChem format) string that libint can load.
`fetch_bredow_basis_sets`([dest_dir, names, ...])	Download the Bredow group all-electron basis sets and convert them to .g94 files loadable by libint.
`parse_crystal_atom_basis`(text[, source])	Parse a single CRYSTAL per-element basis file.
`parse_crystal_atom_basis_file`(path)	Convenience wrapper: parse a CRYSTAL per-element file from disk.
`parse_crystal_inline_basis`(text[, source])	Split a multi-element CRYSTAL inline basis block into per-element specs.

Classes

`CrystalAtomBasis`(Z, has_ecp[, shells, ecp])	Parsed per-atom basis set (one Bredow file).
`CrystalECP`(znuc, m_local[, m_per_ell, terms])	Parsed CRYSTAL effective-core-potential block.
`CrystalECPTerm`(ell, alpha, coefficient, n_pow)	One Gaussian term inside a CRYSTAL ECP angular-momentum block.
`CrystalShell`(shell_type, occupancy, scale_factor)	One contracted Gaussian shell in CRYSTAL format.
`LibecpintInlineArrays`(exponents, ...)	Flat primitive arrays in the exact shape `libecpint::ECPIntegrator:: set_ecp_basis(...)` expects for one ECP center.

class vibeqc.basis_crystal.CrystalShell(shell_type, occupancy, scale_factor, exponents=<factory>, coefficients=<factory>, coefficients_p=<factory>)[source]¶

Bases: object

One contracted Gaussian shell in CRYSTAL format.

Parameters:

shell_type (str)
occupancy (float)
scale_factor (float)
exponents (list[float])
coefficients (list[float])
coefficients_p (list[float])

shell_type: str¶

occupancy: float¶

scale_factor: float¶

exponents: list[float]¶

coefficients: list[float]¶

coefficients_p: list[float]¶

property n_primitives: int¶

class vibeqc.basis_crystal.CrystalECPTerm(ell, alpha, coefficient, n_pow)[source]¶

Bases: object

One Gaussian term inside a CRYSTAL ECP angular-momentum block.

Encodes the contribution

V_ℓ_term(r) = C . r^n . exp(-a . r^2)

in the standard Stuttgart-Köln / Hay-Wadt convention. ell is the angular momentum (0=s, 1=p, …, 4=g) – or the special label "local" for the M-counted local-potential terms in CRYSTAL’s eq. 3.18.

Parameters:

ell (object)
alpha (float)
coefficient (float)
n_pow (int)

ell: object¶

alpha: float¶

coefficient: float¶

n_pow: int¶

class vibeqc.basis_crystal.CrystalECP(znuc, m_local, m_per_ell=(), terms=<factory>)[source]¶

Bases: object

Parsed CRYSTAL effective-core-potential block.

Built from the INPUT-keyword block that follows a 200+Z atom header in CRYSTAL-format basis files. Carries everything libecpint needs to build the V_ECP operator: the effective nuclear charge (Z_eff = Z - ncore), and the per-ℓ Gaussian expansion of the local + ℓ-projected potentials.

The CRYSTAL ECP convention has up to five ℓ-projected components (ℓ = 0..4) plus a “local” group counted by M in the header. terms collects them all in source order; group them by term.ell to match a specific potential expansion.

Parameters:

znuc (float)
m_local (int)
m_per_ell (tuple[int, ...])
terms (list[CrystalECPTerm])

znuc: float¶

m_local: int¶

m_per_ell: tuple[int, ...] = ()¶

terms: list[CrystalECPTerm]¶

property total_terms: int¶

class vibeqc.basis_crystal.CrystalAtomBasis(Z, has_ecp, shells=<factory>, ecp=None)[source]¶

Bases: object

Parsed per-atom basis set (one Bredow file).

Parameters:

Z (int)
has_ecp (bool)
shells (list[CrystalShell])
ecp (CrystalECP | None)

Z: int¶

has_ecp: bool¶

shells: list[CrystalShell]¶

ecp: CrystalECP | None = None¶

property element_symbol: str¶

vibeqc.basis_crystal.parse_crystal_atom_basis(text, source='<string>')[source]¶

Parse a single CRYSTAL per-element basis file.

source is used only in error messages.

Parameters:

text (str)
source (str)

Return type:

CrystalAtomBasis

vibeqc.basis_crystal.parse_crystal_atom_basis_file(path)[source]¶

Convenience wrapper: parse a CRYSTAL per-element file from disk.

Parameters:: path (str | Path)
Return type:: CrystalAtomBasis

vibeqc.basis_crystal.parse_crystal_inline_basis(text, source='<string>')[source]¶

Split a multi-element CRYSTAL inline basis block into per-element specs.

The inverse of emit_crystal(). Where parse_crystal_atom_basis() reads one element’s file, this reads the concatenated block that goes into a .d12 deck after ENDGEOM:

5                 <- Mg
0 8  2.0 0.0
  ...
4                  <- O
0 8  2.0 0.0
  ...
0                <- terminator

Why it exists: the basis-optimization engines exchange candidate bases as exactly this text (EnergyEngine.crystal_energy’s basis_text). An engine that computes a crystal needs every element’s block, and an engine computing an isolated atom needs the right one. Reading only the first block and relabelling it with the requested Z – which is what the vibe-qc engine used to do – silently gives O the Mg basis, which converges and is wrong.

Splitting is line-structural (the CRYSTAL inline format is one record per line), then each per-element slice is handed to parse_crystal_atom_basis() so all the token-level quirks it handles – the SCAL typo, the exponent-scale convention, the positive-exponent guard – apply identically here.

ECP INPUT blocks are rejected rather than skipped: their record count is not derivable from the shell headers, so a splitter that guessed would mis-frame every following element. emit_crystal() does not emit them (it writes 200+Z with no ECP block), so this only fires on hand-written text.

Parameters:

text (str) – The inline basis block. A trailing 99 0 terminator and/or END are optional and are not returned.
source (str) – Used only in error messages.

Returns:

One entry per element, in source order.

Return type:

list[CrystalAtomBasis]

Raises:

ValueError – On a malformed block, a CRYSTAL built-in shell (ITYPE != 0), an inline ECP, or a duplicated element.

class vibeqc.basis_crystal.LibecpintInlineArrays(exponents, coefficients, ams, ns, local_ell, max_proj_ell)[source]¶

Bases: object

Flat primitive arrays in the exact shape libecpint::ECPIntegrator:: set_ecp_basis(...) expects for one ECP center.

Mapping convention (per CRYSTAL23 Sec.”Effective core pseudo-potentials” p. 84, eqs. 3.18 + 3.19, against libecpint’s XML convention where the local channel sits at lval = max_proj_ell + 1):

CRYSTAL M (ell="local" term group)
-> libecpint ams[i] = local_ell = max_proj_ell + 1. This is the U_L channel that acts on all angular momenta (no projector applied), matching the local-potential semantics in CRYSTAL eq. 3.18.
CRYSTAL M_ℓ (ell in {0..4} term groups, with non-zero count)
-> libecpint ams[i] = ℓ. Projected channels; libecpint applies P_ℓ during integration.

Both conventions yield the same V_ECP matrix elements when summed against the basis. Verified against ecp10mdf.xml (K, Z=19) shell layout: local at lval=4 with placeholder zero, projectors at lval= 0..3 for s/p/d/f, max projector ell = 3.

Parameters:

exponents (tuple[float, ...])
coefficients (tuple[float, ...])
ams (tuple[int, ...])
ns (tuple[int, ...])
local_ell (int)
max_proj_ell (int)

exponents: tuple[float, ...]¶

coefficients: tuple[float, ...]¶

ams: tuple[int, ...]¶

ns: tuple[int, ...]¶

local_ell: int¶

max_proj_ell: int¶

property n_primitives: int¶

vibeqc.basis_crystal.crystal_ecp_to_libecpint_arrays(ecp)[source]¶

Flatten a CrystalECP into libecpint primitive arrays.

The conversion is bookkeeping – no algebraic rewrite of the ECP. Each CrystalECPTerm becomes one primitive with its (alpha, coefficient, n_pow) carried over verbatim; only the ell label is re-keyed onto libecpint’s per-primitive am convention (see LibecpintInlineArrays for the mapping).

Phase 14g pairs this with a C++ compute_ecp_matrix_inline that calls libecpint’s set_ecp_basis(...) (the inline- primitive form) instead of set_ecp_basis_from_library(...) (the XML form used today). That unblocks the 5th-period pob basis sets (Rb-I, Cs-Po) and any future inline-ECP archives (vDZP, mixed-row dhf-*).

Parameters:: ecp (CrystalECP) – Parsed CRYSTAL ECP block from parse_crystal_atom_basis().
Returns:: Bundle ready to feed libecpint’s inline-primitive API.
Return type:: LibecpintInlineArrays
Raises:: ValueError – If a term carries an unrecognised ell label (not "local" and not in 0..4).

vibeqc.basis_crystal.build_periodic_ecp_data(system, atoms)[source]¶

Build ECP data for a PeriodicSystem from parsed CRYSTAL atom bases.

Parameters:

system (PeriodicSystem)
atoms (list[CrystalAtomBasis])

Return type:

tuple

vibeqc.basis_crystal.emit_g94(atoms, header_comment='')[source]¶

Convert a list of per-element basis specs into a single .g94 (Gaussian / NWChem format) string that libint can load.

Parameters:

atoms (Sequence[CrystalAtomBasis])
header_comment (str)

Return type:

str

vibeqc.basis_crystal.emit_crystal(atoms)[source]¶

Convert per-element basis specs into CRYSTAL inline-basis format.

Produces text suitable for pasting into a CRYSTAL .d12 input deck after the geometry block (ENDGEOM). The format is:

Z NSHELL
0 LAT NPG OCC SCALE
  exp1  coeff1
  exp2  coeff2
...
 99 0
END

where LAT = 0(S), 1(SP), 2(P), 3(D), 4(F), 5(G). For SP shells each primitive line carries both s and p coefficients.

ECP-bearing atoms (has_ecp=True) are emitted with 200+Z as the header number; the ECP block itself is not emitted (ECP inline emission needs a separate function – libecpint integration pending). All-electron atoms emit the raw Z.

Parameters:: atoms (Sequence[CrystalAtomBasis]) – Sequence of CrystalAtomBasis objects, typically parsed from the Bredow-group per-element CRYSTAL files via parse_crystal_atom_basis() or parse_crystal_atom_basis_file().
Returns:: Multi-line CRYSTAL basis-set block ready for insertion into a .d12 deck.
Return type:: str

vibeqc.basis_crystal.fetch_bredow_basis_sets(dest_dir=None, names=None, *, verbose=True, return_atoms=False)[source]¶

Download the Bredow group all-electron basis sets and convert them to .g94 files loadable by libint.

Parameters:

dest_dir (str | Path | None) – Target directory for the .g94 output files. Defaults to basis_library/basis/ inside the vibe-qc source tree (the path already on LIBINT_DATA_PATH in editable installs).
names (Iterable[str] | None) – Subset of basis-set keys to fetch (from _BREDOW_ARCHIVES). None fetches all supported light-element archives.
verbose (bool) – Print progress + citation info.
return_atoms (bool)

Return type:

dict mapping basis name -> path of the generated .g94 file.