qstack.spahm.rho.compute_rho_spahm¶

Main computation routines for SPAHM(a,b) representations.

qstack.spahm.rho.compute_rho_spahm.get_repr(rep_type, mols, xyzlist, guess, xc='hf', spin=None, readdm=None, pairfile=None, dump_and_exit=False, same_basis=True, bpath='/home/runner/work/Q-stack/Q-stack/qstack/spahm/rho/basis_opt', cutoff=5.0, omods=['alpha', 'beta'], elements=None, only_m0=False, zeros=False, split=False, printlevel=0, auxbasis='ccpvdzjkfit', model='Lowdin-long-x', with_symbols=False, only_z=None, merge=True)[source]¶

Compute and reshapes SPAHM(a) or SPAHM(b) representations with flexible output formats.

High-level interface that handles density matrix computation, representation generation, and output formatting including splitting, symbol labeling, and merging options.

Parameters:

rep_type (str) – Representation type (‘atom’ or ‘bond’).
mols (list) – List of pyscf Mole objects.
xyzlist (list) – List of XYZ file paths corresponding to mols.
guess (str) – Guess Hamiltonian name.
xc (str) – Exchange-correlation functional. Defaults to defaults.xc.
spin (list, optional) – List of spin multiplicities per molecule. Defaults to None.
readdm (str, optional) – Directory path to load pre-computed density matrices. Defaults to None.
pairfile (str, optional) – Path to atom pair file for SPAHM(b). Defaults to None.
dump_and_exit (bool) – Save atom pair file for SPAHM(b) to pairfile and exit without computing. Defaults to False.
same_basis (bool) – Use generic CC.bas for all atom pairs for SPAHM(b). Defaults to False.
bpath (str) – Directory path containing bond-optimized basis files (.bas) for SPAHM(b). Defaults to defaults.bpath.
cutoff (float) – Bond cutoff distance in Å for SPAHM(b). Defaults to defaults.cutoff.
omods (list) – Open-shell modes (‘alpha’, ‘beta’, ‘sum’, ‘diff’). Defaults to defaults.omod.
elements (list, optional) – Element symbols in dataset. Auto-detected if None. Defaults to None.
only_m0 (bool) – Use only m=0 angular momentum component for SPAHM(b). Defaults to False.
zeros (bool) – Pad with zeros for non-existent bond pairs in SPAHM(b). Defaults to False.
split (bool) – Split output by molecule. Defaults to False.
printlevel (int) – Verbosity level. Defaults to 0.
auxbasis (str) – Auxiliary basis for SPAHM(a). Defaults to defaults.auxbasis.
model (str) – Atomic density fitting model for SPAHM(a). Defaults to defaults.model.
with_symbols (bool) – Include atomic symbols with representations. Defaults to False.
only_z (list, optional) – Restrict to specific atom types. Defaults to None.
merge (bool) – Merge alpha/beta into single vector. Defaults to True.

Returns:

Representation array with shape depending on options: - Base: (n_omods, n_mols, max_atoms, n_features) - If split=False: (n_omods, total_atoms, n_features) - all molecules concatenated - If merge=True: Features concatenated, omods dimension removed - If with_symbols=True: Object array with (symbol, vector) tuples per atom - If split=True and with_symbols=True: List format per molecule

Return type:

numpy ndarray

qstack.spahm.rho.compute_rho_spahm.main(args=None)[source]¶

Command-line interface for computing SPAHM representations (atom or bond centered).

Unified CLI that supports both SPAHM(a) and SPAHM(b) computations with extensive options for molecular datasets, splitting, and output formatting.

Parameters:: args (list, optional) – Command-line arguments. If None, uses sys.argv. Defaults to None.

Output:: Saves representations to numpy files based on –name argument and options.

qstack.spahm.rho.compute_rho_spahm.spahm_a_b(rep_type, mols, dms, bpath='/home/runner/work/Q-stack/Q-stack/qstack/spahm/rho/basis_opt', cutoff=5.0, omods=['alpha', 'beta'], elements=None, only_m0=False, zeros=False, printlevel=0, auxbasis='ccpvdzjkfit', model='Lowdin-long-x', pairfile=None, dump_and_exit=False, same_basis=False, only_z=None)[source]¶

Compute SPAHM(a) or SPAHM(b) representations for a set of molecules.

Reference:: K. R. Briling, Y. Calvino Alonso, A. Fabrizio, C. Corminboeuf, “SPAHM(a,b): Encoding the density information from guess Hamiltonian in quantum machine learning representations”, J. Chem. Theory Comput. 20 1108–1117 (2024), doi:10.1021/acs.jctc.3c01040

Parameters:

rep_type (str) – Representation type: ‘atom’ for SPAHM(a) or ‘bond’ for SPAHM(b).
mols (list) – List of pyscf Mole objects.
dms (list) – List of density matrices (2D or 3D numpy arrays) for each molecule.
bpath (str) – Directory path containing bond-optimized basis files (.bas) for SPAHM(b). Defaults to defaults.bpath.
cutoff (float) – Bond cutoff distance in Å for SPAHM(b). Defaults to defaults.cutoff.
omods (list) – Open-shell modes (‘alpha’, ‘beta’, ‘sum’, ‘diff’). Defaults to defaults.omod.
elements (list, optional) – Element symbols present in dataset. Auto-detected if None. Defaults to None.
only_m0 (bool) – Use only m=0 angular momentum component for SPAHM(b). Defaults to False.
zeros (bool) – Pad with zeros for non-existent bond pairs in SPAHM(b). Defaults to False.
printlevel (int) – Verbosity level (0=silent, >0=verbose). Defaults to 0.
auxbasis (str) – Auxiliary basis set for SPAHM(a). Defaults to defaults.auxbasis.
model (str) – Atomic density fitting model for SPAHM(a). Defaults to defaults.model.
pairfile (str, optional) – Path to atom pair file for SPAHM(b). Atom pairs are computed from mols if None. Defaults to None.
dump_and_exit (bool) – Save atom pair file for SPAHM(b) to pairfile and exit without computing. Defaults to False.
same_basis (bool) – Use generic CC.bas for all atom pairs for SPAHM(b). Defaults to False.
only_z (list, optional) – Restrict to specific atom types. Defaults to None.

Returns:

4D array (n_omods, n_mols, max_atoms, n_features) where: - n_omods: Number of open-shell components (1 for closed-shell, len(omods) for open-shell) - n_mols: Number of molecules in dataset - max_atoms: Maximum number of atoms/bonds across all molecules - n_features: Representation dimension

Return type:

numpy ndarray

Command-line use¶

This program computes the SPAHM(a,b) representations for a given molecular system or a list thereof

usage: python3 -m qstack.spahm.rho.compute_rho_spahm [-h] --mol FILENAME
                                                     [--charge CHARGE]
                                                     [--spin SPIN]
                                                     [--guess {core,sad,sap,gwh,lb,huckel,lb-hfs}]
                                                     [--basis BASIS] [--xc XC]
                                                     [--ecp ECP]
                                                     [--readdm READDM]
                                                     [--units {Angstrom,Bohr}]
                                                     [--elements ELEMENTS [ELEMENTS ...]]
                                                     [--only-z ONLY_Z [ONLY_Z ...]]
                                                     [--omod {sum,diff,alpha,beta} [{sum,diff,alpha,beta} ...]]
                                                     [--name NAME_OUT]
                                                     [--split] [--nomerge]
                                                     [--symbols]
                                                     [--print PRINT]
                                                     [--aux-basis AUXBASIS]
                                                     [--model {pure,sad-diff,occup,lowdin-short,lowdin-long,lowdin-short-x,lowdin-long-x,mr2021}]
                                                     [--cutoff CUTOFF]
                                                     [--bpath BPATH] [--zeros]
                                                     [--onlym0]
                                                     [--pairfile PAIRFILE]
                                                     [--dump_and_exit]
                                                     [--same_basis]
                                                     --rep {atom,bond}

Named Arguments¶

--mol

path to an xyz file / to a list of molecular structures in xyz format

--charge

charge / path to a file with a list of thereof

Default: 'None'

--spin

number of unpaired electrons / path to a file with a list of thereof

Default: 'None'

--guess

Possible choices: core, sad, sap, gwh, lb, huckel, lb-hfs

the initial guess Hamiltonian to be used

Default: 'LB'

--basis

basis set for computing density matrix

Default: 'minao'

--xc

DFT functional for the SAD guess

Default: 'hf'

--ecp

effective core potential to use

--readdm

directory to read density matrices from

--units

Possible choices: Angstrom, Bohr

the units of the input coordinates

Default: 'Angstrom'

--elements

the elements contained in the database

--only-z

restrict the representation to one or several atom types

--omod

Possible choices: sum, diff, alpha, beta

model(s) for open-shell systems (alpha, beta, sum, diff

Default: ['alpha', 'beta']

--name

name of the output representations file.

--split

split into molecules (use twice to also split the output in one file per molecule)

Default: 0

--nomerge

merge different omods

Default: True

--symbols

if save tuples with (symbol, vec) for all atoms

Default: False

--print

printing level

Default: 0

--aux-basis

auxiliary basis set for density fitting

Default: 'ccpvdzjkfit'

--model

Possible choices: pure, sad-diff, occup, lowdin-short, lowdin-long, lowdin-short-x, lowdin-long-x, mr2021

model for the atomic density fitting

Default: 'Lowdin-long-x'

--cutoff

bond length cutoff in Å

Default: 5.0

--bpath

directory with basis sets

Default: '/home/runner/work/Q-stack/Q-stack/qstack/spahm/rho/basis_opt'

--zeros

use a version with more padding zeros

Default: False

--onlym0

use only functions with m=0

Default: False

--pairfile

path to the atom pair file

--dump_and_exit

write the atom pair file and exit if –pairfile is set

Default: False

--same_basis

if to use generic CC.bas basis file for all atom pairs (Default: uses pair-specific basis, if exists)

Default: False

--rep

Possible choices: atom, bond

the type of representation

Note

If you built those docs yourself and the command-line section is empty, please make sure you have installed the right components of qstack.