qstack.spahm.rho.utils

Utility functions for SPAHM(a,b) computation and default settings.

Provides:

defaults: Default parameters for SPAHM(a,b) computation. omod_fns_dict: Dictionary of density matrix modification functions for open-shell systems.

qstack.spahm.rho.utils.check_data_struct(fin, local=False)[source]

Check the structure of a representation file.

Parameters:

  • fin (str) – Input file path.

  • local (bool) – If True, checks for local representations.

Returns:

(is_single (bool), is_labeled (bool))

is_single: True if the file contains a single representation. is_labeled: True if the representations are labeled.

Return type:

tuple

qstack.spahm.rho.utils.dm_open_mod(dm, omod)[source]

Treats density matrix according to the open-shell mode..

Parameters:

  • dm (numpy ndarray) – Density matrix (2D for closed-shell, 3D for open-shell).

  • omod (str or None) – Open-shell mode. Options in omod_fns_dict.

Returns:

Modified density matrix.

Return type:

numpy ndarray

Raises:

  • NotImplementedError – If omod is not a valid modification type.

  • RuntimeError – If dm is 2D but omod is None, or if dm is 3D but omod is not None.

qstack.spahm.rho.utils.get_chsp(fname, n)[source]

Load charge and spin information from file.

Reads a file containing charge/spin values, converting ‘None’ strings to None objects.

Parameters:

  • fname (str or None) – Path to charge/spin file. If None, returns array of Nones.

  • n (int) – Expected number of entries in the file.

Returns:

Array of charge/spin values (int or None) of length n.

Return type:

numpy ndarray

Raises:

RuntimeError – If file is not found or has wrong length.

qstack.spahm.rho.utils.get_xyzlist(xyzlistfile)[source]

Load list of paths to files.

Parameters:

xyzlistfile (str) – Path to the file containing list of XYZ filenames.

Returns:

Array of XYZ filenames as strings.

Return type:

numpy ndarray

qstack.spahm.rho.utils.load_mols(xyzlist, charge, spin, basis, printlevel=0, units='ANG', ecp=None, progress=False, srcdir=None)[source]

Load molecules from XYZ files and creates pyscf Mole objects.

Parameters:

  • xyzlist (list) – List of XYZ filenames.

  • charge (list or None) – List of molecular charges (or None for neutral).

  • spin (list or None) – List of spin multiplicities (or None for default).

  • basis (str or dict) – Basis set.

  • printlevel (int) – Verbosity level (0=silent). Defaults to 0.

  • units (str) – Coordinate units (‘ANG’ or ‘BOHR’). Defaults to ‘ANG’.

  • ecp (str or dict, optional) – Effective core potential. Defaults to None.

  • progress (bool) – If True, shows progress bar. Defaults to False.

  • srcdir (str, optional) – Source directory prepended to XYZ filenames. Defaults to None.

Returns:

List of pyscf Mole objects.

Return type:

list

qstack.spahm.rho.utils.load_reps(f_in, from_list=True, srcdir=None, with_labels=False, local=True, sum_local=False, printlevel=0, progress=False, file_format=None)[source]

Load representations from disk.

Parameters:

  • f_in (str) – Path to the input file.

  • from_list (bool) – If the input file is a text file containing a list of paths to the representations.

  • srcdir (str) – The path prefix to be at the begining of each file in f_in. Defaults to current working directory.

  • with_labels (bool) – If return atom type labes along with the representations.

  • local (bool) – If the representations are local (per-atom) or global (per-molecule).

  • sum_local (bool) – Sums the local components into a global representation, only if local=True.

  • printlevel (int) – Verbosity level.

  • progress (bool) – If shows a progress bar.

  • file_format (dict) – Structure of the input data, with keys=(‘is_labeled;, ‘is_single’). Defaults to structure auto determination (for “experienced users” only).

Returns:

np.array with shape (N_representations, N_features), or a tuple containing a list of atomic labels and said np.array.

Raises:

RuntimeError – In case of shape mismatch.

qstack.spahm.rho.utils.mols_guess(mols, xyzlist, guess, xc='hf', spin=None, readdm=None, printlevel=0)[source]

Compute or loads guess density matrices for a list of molecules.

Parameters:

  • mols (list) – List of pyscf Mole objects.

  • xyzlist (list) – List of XYZ filenames (for naming/loading).

  • guess (str or callable) – Guess method name or function.

  • xc (str) – Exchange-correlation functional for guess. Defaults to defaults.xc.

  • spin (list or None) – List of spin multiplicities. Defaults to None.

  • readdm (str, optional) – Directory path to load pre-computed density matrices. Defaults to None.

  • printlevel (int) – Verbosity level. Defaults to 0.

Returns:

List of density matrices (2D or 3D numpy arrays).

Return type:

list

qstack.spahm.rho.utils.regroup_symbols(file_list, print_level=0, trim_reps=False)[source]

Regroups representations by atom type.

Parameters:

  • file_list (list) – List of representation files.

  • print_level (int) – Verbosity level. Defaults to 0.

  • trim_reps (bool) – If True, trims zeros from representations. Defaults to False.

Returns:

Dictionary with atom types as keys and lists of representations as values.

Return type:

dict