horton_part.glisa module

Module for Global Linear Iterative Stockholder Analysis (GL-ISA) partitioning scheme.

Optimization Problem Schemes

Convex optimization (name = “glisa_cvxopt”)
Trust-region methods with constraints
- Implicit constraints (name = “glisa_trust_constr”)
Fixed-point methods
- Alternating method (name = “glisa_sc”)
- DIIS (name = “glisa_diis”)

class GlobalLinearISAWPart(coordinates, numbers, pseudo_numbers, grid, moldens, spindens=None, lmax=3, logger=None, threshold=1e-06, maxiter=500, solver='cvxopt', solver_options=None, basis_func='gauss', grid_type=1, basis_type='analytic', **kwargs)

Bases: AbstractStockholderWPart

__init__(coordinates, numbers, pseudo_numbers, grid, moldens, spindens=None, lmax=3, logger=None, threshold=1e-06, maxiter=500, solver='cvxopt', solver_options=None, basis_func='gauss', grid_type=1, basis_type='analytic', **kwargs)

Construct LISA for given arguments.

Optional arguments: (that are not defined in WPart)

Parameters:

threshold (float) – The procedure is considered to be converged when the maximum change of the charges between two iterations drops below this threshold.
maxiter (int) – The maximum number of iterations. If no convergence is reached in the end, no warning is given. Reduce the CPU cost at the expense of more memory consumption.

property bs_helper: A basis function helper.

property cache: Cache.

calc_promol_dens(propars): Compute pro-molecule density based on pro-atom parameters.

calc_radial_distances(): Calculate radial distance w.r.t coordinates.

clear(): Discard all cached results, e.g. because wfn changed

compute_change(propars1, propars2): Compute the difference between an old and a new proatoms

compute_pseudo_population(index): Compute pseudo population

property coordinates

Center/Atomic coordinates.

Type:: ndarray(M, 3)

property density_cutoff

Get the density cutoff value.

Density values below this cutoff are considered to be invalid.

Returns:: The cutoff value for density.
Return type:: float

do_all(): Computes all properties and return a list of their keys.

do_charges(): Compute atomic charges.

do_density_decomposition(): Compute density decomposition.

do_moments()

Compute atomic multiple moments.

Calculates various types of multipoles, including Cartesian, Spherical, and Radial moments. The order of the moments is determined by the lmax parameter.

do_partitioning(): Do global partitioning scheme.

do_populations(): Compute atomic populations.

do_prosplines(): Do pro-atom splines

do_spin_charges(): Compute atomic spin charges.

eval_pro_shells(): Evaluate pro-shell functions on molecular grids.

eval_proatom(index, output, grid)

Evaluate function on a local grid.

The size of the local grid is specified by the radius of the sphere where the local grid is considered. For example, when the radius is np.inf, the grid corresponds to the whole molecular grid.

Parameters:

index (int) – The index of an atom in the molecule.
output (np.array) – The size of output should be the same as the size of the local grid.
grid (np.array) – The local grid.

eval_spline(index, spline, output, grid, label='noname')

Evaluate a given spline at radial distances from a specified atom center and store the results in the output array.

This method calculates the radial distances from the specified atom center to each point in the provided grid. It then evaluates the provided spline function at these distances, storing the results in the given output array.

Parameters:

index (int) – The index of the atom whose center is used for calculating radial distances.
spline (callable) – The spline function to be evaluated. This should be a function that takes an array of radial distances and returns the corresponding spline values.
output (1D ndarray) – The array where the evaluated spline values will be stored. This array is modified in-place.
grid (Grid) – An object representing the grid points. It should have an attribute points which is an array of grid point coordinates.
label (str, optional) – A label for identification purposes, defaults to “noname”.

Notes

The method computes the Euclidean norm (radial distance) from the atom center, specified by index, to each point in the grid. The spline function is then evaluated at these distances. The results are stored directly in the output array, overwriting any existing data.

fix_proatom_rho(index, rho, deriv)

Check if the radial density for the proatom is correct and fix as needed.

Parameters:

index (int) – The atom for which this proatom rho is created.
rho (1D np.ndarray) – The radial density
deriv (int) – the derivative of the radial density or None.

function_g(x): The fixed-point equation \(g(x)=x\).

get_grid(index=None)

Return an integration grid

Optional arguments:

index: The index of the atom. If not given, a grid for the entire system is returned. If self.local is False, a full system grid is always returned.

get_moldens(index=None, output=None)

Retrieves the molecular electron density (moldens) on the atomic grid.

This method converts the molecular electron density to the atomic grid specified by the index. If an output array is provided, the result is stored in that array.

Parameters:

index (int or None, optional) – The index of the atom for which the electron density is required. If None, electron density for all atoms is considered. Default is None.
output (np.ndarray or None, optional) – An optional array to store the resulting electron density. If provided, the result is saved in this array. Default is None.

Returns:

The molecular electron density on the atomic grid.

Return type:

np.ndarray

get_proatom_rho(iatom, propars=None, **kwargs)

Get pro-atom density for atom iatom.

If propars is None, the cache values are used; otherwise, the propars are used.

Parameters:

iatom (int) – The index of atom iatom.
propars (1D np.array) – The pro-atom parameters.

get_proatom_spline(index, *args, **kwargs)

Create and return a spline representation of the radial density for a given atomic index.

This method first retrieves the radial density and its derivatives for the specified atomic index. It then ensures the correctness of these values and constructs a spline representation based on the radial grid points.

Parameters:

index (int) – The index of the atom for which the radial density spline is to be calculated.
*args – Variable length argument list, used for passing non-keyworded arguments.
**kwargs – Arbitrary keyword arguments, used for passing additional data.

Returns:

A spline representation of the radial density. If derivatives are available, a CubicHermiteSpline is returned. Otherwise, a CubicSpline is used.

Return type:

CubicSpline or CubicHermiteSpline

Notes

The method internally calls get_proatom_rho to obtain the radial density (rho) and its derivatives (deriv), and fix_proatom_rho to validate and potentially correct these values. It also uses get_rgrid to acquire the radial grid points (rgrid.points). The spline is constructed with these grid points and density values, with the type of spline depending on the availability of derivative information.

get_rgrid(index): Load radial grid.

get_spindens(index=None, output=None)

Retrieves the spin density (spindens) on the atomic grid.

This method converts the spin density to the atomic grid specified by the index. If an output array is provided, the result is stored in that array.

Parameters:

index (int or None, optional) – The index of the atom for which the spin density is required. If None, spin density for all atoms is considered. Default is None.
output (np.ndarray or None, optional) – An optional array to store the resulting spin density. If provided, the result is saved in this array. Default is None.

Returns:

The spin density on the atomic grid.

Return type:

np.ndarray

get_wcor(index): Load correction of weights.

property grid: Molecular grid.

property grid_type

Get the type of grids used for partitioning density.

Returns:: The type of grids used in the partitioning process.
Return type:: str

is_proatom_valid(iatom, propars, check_mono): Check if the proatom density is valid.

is_promol_valid(propars, check_mono): Check if the promol density is valid.

property lmax: The maximum angular momentum index for moment calculations.

load_pro_shell(iatom, ishell)

Load one set of basis function values on a local grid.

Parameters:

iatom (int) – The index of the atom in the molecule.
ishell (int) – The index of the basis function for atom iatom.

Returns:

The basis function values on the local grid with a shape of (N, ), where N is the number of points in the local grid.

Return type:

np.array

property local: Whether local grids are included.

property maxiter: The maximum iterations.

property mol_pop: Molecular population.

name = 'glisa'

property natom: The number of atoms in the molecule.

property negative_cutoff

Get the negative cutoff value.

Values less than this threshold are treated as negative in computations.

Returns:: The negative cutoff value.
Return type:: float

property nelec: The number of electrons in the molecule.

property numbers: Atomic numbers

property on_molgrid

Check whether quantities are computed on molecular grids.

These grids are used for evaluating various properties, including:

AIM (Atoms-in-Molecule) weight functions: \(w_a(\mathbf{r})\).

Pro-atom density: :math:`

ho_a^0(mathbf{r})`.

Pro-molecule density: :math:`

ho^0(mathbf{r})`.

Mean-square deviation during computations.

bool: True if quantities are computed on molecular grids, False otherwise.

property only_use_molgrid

Check whether intermediate values are computed exclusively using molecular grids.

When set to True, all quantities are computed solely on the molecular grid.

Returns:: True if intermediate values are computed only using the molecular grid, False otherwise.
Return type:: bool

property population_cutoff

Get the population cutoff criterion.

This represents the allowed difference between the sum of proatom parameters and the reference population for determining accuracy of methods.

Returns:: The cutoff value for population differences.
Return type:: float

property pro_shells

All basis function values on the molecular grid.

It has a shape of (M, N) where M is the total number of basis functions and N is the number of grid points.

property propars

Load all pro-atom parameters.

It has a shape of (M, ) where M is the total nuber of basis functions.

property pseudo_numbers: Atomic charges.

property radial_distances

Get the radial distances of points from the atomic coordinates.

The radial distances are calculated as the L2 norm (Euclidean distance) of the points relative to the atomic coordinates.

Notes

Accessing this property triggers the calculation of radial distances via the calc_radial_distances method.

Returns:: A list containing the radial distances of points for each atom.
Return type:: list

residual(x): The definition of residual.

property rho_x_pro_shells

\(\rho(r) \times g_{ak}\).

It has a shape of (M, N) where M is the total number of basis functions and N is the number of grid points.

Type:: The intermediate quantity

setup_grids()

Setup grids used in partitioning.

# 1. atom_grids + mol_grid, use atoms for everything and mol_grid is only used for weights calculation # 2. atom_grids + mol_grid, use mol_grid for everything but atom_grids are used applied contratins. # 3. mol_grid, use mol_grid for everything, like in gLISA+.

solver_cdiis(**cdiis_options): CDIIS solver.

solver_cvxopt(allow_neg_pars=False, verbose=False, **cvxopt_options)

Convex optimization solver.

Parameters:

allow_neg_pars (bool, optional) – Whether negative parameters are allowed.
verbose (bool, optional) – Whether print more info.
cvxopt_options (dict) – Settings for ``cvxopt` solver.

Returns:

Optimized parameters, 1D array.

Return type:

np.array

solver_diis(use_dmrs=False, **diis_options): DIIS solver

solver_m_newton(maxiter=100, linspace_size=40, tau=1.0, linesearch_mode='valid-promol', **kwargs): Default Modified Newton method

solver_newton(maxiter=100): Default, Exact Newton method.

solver_quasi_newton(mode='bfgs', maxiter=1000, niter_exact_newton=0, linesearch_mode='valid-promol', tau=1.0, linspace_size=40, **kwargs): Default Quasi-Newton method.

solver_sc(niter_print=1)

Self-Consistent solver.

Parameters:: niter_print (int, optional) – Print info every niter_print iterations.
Returns:: Optimized parameters, 1D array.
Return type:: np.array

solver_trust_region(allow_neg_pars=False): Optimize the promodel using the trust-constr minimizer from SciPy.

property threshold: The convergence threshold.

to_atomic_grid(index, data): Load atomic contribution of molecular properties.

update_at_weights(force_on_molgrid=False): See Part.update_at_weights.

update_pro(index, proatdens, promoldens, force_on_molgrid=False)

Update propars.

Parameters:

index (int) – The index of the atom for which the pro-atom and pro-molecule densities are to be updated.
proatdens (1D np.ndarray) – The array representing the pro-atom density. This array is updated with the new density values for the specified atom.
promoldens (1D np.ndarray) – The array representing the pro-molecule density. This array accumulates the density contributions from each atom, including the one specified by index.

variables_stored_in_cache(): The properties stored in cache obj.