grid.robust_poisson module

grid.robust_poisson module#

Robust Poisson Solver — Double-Split Architecture.

Split 1 only (default)#

Total Density rho(r)
      |
[SPLIT 1]  Analytical core subtraction using pre-fitted Gaussian parameters
      |     (load_atomic_gaussian_params -> coulomb_potential)
      |
residual_1(r) = rho - rho_core   <- smooth, nuclear-cusp-free
      |
[SOLVE]  solve_poisson_bvp on residual_1  --> phi_numerical
      |
Total Potential = phi_core (analytical) + phi_numerical

Double-Split (split2=True)#

Total Density rho(r)
      |
[SPLIT 1]  Analytical core subtraction  --> residual_1
      |
[SPLIT 2]  Per-atom NNLS Gaussian fit of residual_1  --> residual_2
      |     (scipy.optimize.nnls, exponents from _DEFAULT_ALPHAS_BASIS)
      |
[SOLVE]  solve_poisson_bvp on residual_2  --> phi_numerical
      |
Total Potential = phi_core + phi_bonding (analytical) + phi_numerical

grid.robust_poisson.solve_poisson_robust(molgrid: MolGrid | AtomGrid, density_vals: ndarray, transform: BaseTransform, atnums: ndarray, atcoords: ndarray, split2: bool = False, alphas_basis: ndarray | None = None, **bvp_kwargs) → callable#

Solve the Poisson equation robustly using analytical core subtraction (Split 1).

If split2=True, an additional Non-Negative Least Squares (NNLS) fitting step is performed on the residual (Split 2) to analytically subtract bonding and polarization density features before the BVP solve.

For each atomic center, pre-fitted Gaussian parameters are loaded via load_atomic_gaussian_params() and the exact analytical core potential is computed with coulomb_potential(). The corresponding core density is subtracted from the input to form a smooth residual, which is then solved numerically with solve_poisson_bvp().

Parameters#

molgridMolGrid or AtomGrid: Molecular or atomic grid used for integration and ODE solving.
density_valsndarray(N,): Total electron density evaluated at all grid points.
transformBaseTransform: Radial coordinate transform passed to solve_poisson_bvp.
atnumsndarray(M,) of int: Atomic numbers for each of the M atomic centers.
atcoordsndarray(M, 3): Cartesian coordinates of the M atomic centers in atomic units (Bohr).
split2bool, default=False: If True, perform a second split (NNLS fitting of the residual) before solving.
alphas_basisndarray, optional: Array of s-type Gaussian exponents to use for the Split 2 fit. If None, a default geometric sequence of 20 exponents is used.
**bvp_kwargs: Additional keyword arguments forwarded to solve_poisson_bvp().

Returns#

callable: Function V(points) returning the total electrostatic potential at an array of Cartesian evaluation points, shape (N, 3) -> (N,).

Raises#

ValueError: If pre-fitted Gaussian parameters are not available for a given atomic number.
ValueError: If density_vals is not a 1-D array of length N matching the number of grid points in molgrid.

Notes#

Pre-fitted parameters are currently available for H (1), C (6), N (7), O (8), and Cl (17).