vibe-qcDocumentation

Native continuum solvation of a slab

The initial native slab interface is run_periodic_job(..., solvation=SlabSolvationOptions(...)). No MOIST installation is required. It treats the substrate and adsorbates as one electronic system with two periodic directions and an open normal. This is a fixed-geometry model; energies and charges are per surface cell.

from vibeqc import ISwiGCavity, NativePCM, SlabSolvationOptions, SlabRKSNumerics

solvation = SlabSolvationOptions(
    cavity=ISwiGCavity(nleb=302),
    model=NativePCM(model="cpcm", epsilon=78.39),
    accessibility_spacing=0.0125,
    accessibility_mesh=(640, 640),
)
# Pass both controls to run_periodic_job with method="RKS", functional="pbe".
# Use the same slab_numerics for the dry calculation.
slab_numerics = SlabRKSNumerics()

Boundary conditions and capability

Both faces contact an electrically connected reservoir. The total induced charge is zero and the conductor potential is a common Lagrange multiplier. The isolated slab potential gauge retains a normal dipole step. The third lattice vector is bookkeeping only. The cavity is the periodic union of atomic iSwiG spheres. Lateral images screen the surface; each atomic node belongs to one cell. A periodic flood of the sphere complement removes sealed voids. This accessibility test has zero solvent probe radius and a finite voxel spacing which must be converged. Surface nodes are classified at a probe displaced outward by 1.5 voxel spacings. This numerical probe vanishes under refinement; it is not a solvent probe radius. The raster uses sphere bounding boxes and bounded coordinate panels, followed by a compiled six-neighbour flood with periodic seam propagation.

accessibility_mesh=(nx, ny) optionally fixes the in-plane raster counts for the actual surface cell; the normal grid still uses the requested spacing. For a 2x1 replication, double nx and retain ny. This repeats the raster exactly, whereas independently rounding a target spacing can change its phase. Converge the counts together with the normal spacing. The tutorial’s --accessibility-mesh NX NY takes counts for its original square example cell and multiplies them by the requested repeat factors.

Capability

Implementation

Qualification

Gaussian 2D single layer, analytic zero mode and self interactions

Native

Analytic plane, density-adjoint and identical-density water/MgO replication checks

Periodic iSwiG, both wet faces

Native

Wrapping, translation and sealed-void regression checks

CPCM and COSMO

Native, distinct dielectric factors

Converged two-face water/MgO demonstration and documented refinement budgets, #1168

Neutral singlet semilocal RKS, Gamma, all-electron basis

Public direct slab route

PBE/STO-3G water/MgO through vq, matched CRYSTAL dry references, #1168

Weighted complex AO potential-map transpose

Shared interface

Algebraic directional test; no multi-k host exposed

RHF/UHF/UKS, multi-k, hybrids, ECP, gradients, relaxation and periodic post-HF

Refused

Separate prerequisites

BIPOLE, AICCM, MSINDO CCM2D

No environment adapter

Dry host and density-map qualification required

Top-only wetting, charged electrodes, DROP, other PCM and pressure models

Refused

Separate boundary derivations required

Direct multi-k RKS has an unresolved dry-host discrepancy (#1123). Gamma supercell convergence and replication at fixed coverage remain necessary for a quantitative slab study. AICCM and MSINDO CCM2D remain experimental. The molecular solvation interfaces are unchanged.

Executable water/MgO tutorial

Run slab_solvation.py from an installed vibe-qc environment. It uses the existing MgO(100) bilayer geometry and adds mirrored waters on the two faces. PBE/STO-3G is a small method demonstration, not a basis-converged adsorption prediction.

python slab_solvation.py --output clean-dry
python slab_solvation.py --wet --output clean-wet
python slab_solvation.py --covered --output covered-dry
python slab_solvation.py --covered --wet --output covered-wet

Submit each command through vq submit HOST -- COMMAND for scientific validation. The usual output contains the environment energy, linear boundary residual and charge on each face. The .solvation.json record also contains the plane-averaged potential, in hartree per elementary positive charge, along the normal in bohr. Face labels split at the nuclear centroid; they do not impose a boundary in the surface solve.

For a returned periodic result, the complete AO response is available as e_env, v_reaction = result.solvent_environment.evaluate(result.density). The matrix uses the host AO order and enters its Fock operator directly; e_env is the environment functional in hartree per cell. The density is spin-summed on this RKS route. The reported total already includes the functional, so do not add it again when forming an adsorption cycle.

Converge --nleb, --accessibility-spacing, --normal-quadrature, --cutoff, --partition-radius, --radial-points and --lebedev-order. Use --energy-tolerance and --gradient-tolerance to set the electronic SCF criteria; the tutorial defaults are 1e-9 hartree and 1e-7. The partition radius includes neighbouring atoms in the periodic Becke weights; converge it independently of the AO lattice cutoff. Compare --height values without changing the physical geometry. --repeat 2 replicates both substrate and water at fixed coverage and changes Gamma sampling. Use --repeat-x 2 --repeat-y 1 for the rectangular 2x1 check. Divide total energies by the replication area before comparison. The tutorial defaults use 302-point atomic surfaces, a 640x640 accessibility mesh with 0.0125-bohr normal spacing, 99 radial points, 974 electronic angular points and an 18-bohr AO cutoff. Compare larger settings for the system of interest. The orthogonal slab vectors need no lattice reduction for nearest-neighbour reporting. The native image search handles the elongated replicated cells directly; the bookkeeping vector does not enter that search.

SlabRKSNumerics.ewald_alpha controls the electronic host’s Ewald split in inverse bohr. The tutorial exposes it as --host-ewald-alpha, together with --nuclear-cutoff. A smaller split reduces the reciprocal AO cache and requires longer real-space cutoffs. This parameter is independent of SlabSolvationOptions.ewald_split, which partitions the surface potential map. At the common TOL20 CRYSTAL clean density, changing host alpha from 0.4 to 0.15, AO cutoff from 18 to 40 bohr and nuclear cutoff from 25 to 45 bohr changes the total by 9.6e-10 hartree. The individual energy components change by at most 2.2e-9 hartree. The qualified larger-cell recipe below uses the separately checked 0.25/201 host split and normal quadrature.

SlabRKSNumerics.reciprocal_normal_points controls the host’s continuous normal Fourier integral for both Hartree and nuclear attraction. It defaults to 401 and must be an odd integer of at least 33. The tutorial exposes --host-normal-points; this is distinct from the surface potential map’s --normal-quadrature. Converge it together with the host Ewald split and cutoffs. Nondefault values currently require Gamma RKS. The evaluated Fock source record includes the actual quadrature count.

SlabRKSNumerics.reciprocal_cache_mib optionally sets a reciprocal workspace budget in MiB. The default uses the existing shared Hartree memory policy, including the job’s memory limit. Above that budget, the Gamma Hartree and nuclear-attraction builders contract the same analytic AO Fourier transforms in reciprocal panels. The zero-mode density transform is also panelled. This keeps every reciprocal mode, Gaussian normalization and potential gauge; it changes storage and recomputation cost. The retained real zero-mode profile, surface operators and other SCF arrays have separate storage requirements. A zero budget requests the minimum one-mode workspace. The evaluated Fock source records the cached or streamed mode, panel size and budget.

The tutorial exposes --reciprocal-cache-mib, --basis and --layers. The layer count must be even and at least two. The default bilayer geometry is unchanged; thicker neutral checkerboard slabs retain mirrored waters on the two outer faces. This exposes a thickness study, not a claim of thickness convergence. Use the same --basis in slab_water_reference.py for the adsorbate reference. These controls permit further convergence studies; their availability does not qualify a new basis or cell size automatically. Extended basis, thickness and two-direction sampling checks are tracked in #1271.

At the same TOL20 MgO density, alpha 0.25, 201 normal Fourier points and 30/35-bohr AO/nuclear cutoffs change the total by 3.54e-10 hartree relative to the 0.4/401, 18/25-bohr calculation. Each energy component changes by at most 3.52e-10 hartree. These controls reduce the host’s reciprocal storage while retaining an accurate real-space split. They do not change the cavity or dielectric model.

For two adsorbed waters per primitive cell, define the fixed-geometry solution adsorption energy as

[ E_{\rm ads}^{\rm wet} = (E_{\rm covered}^{\rm wet}-E_{\rm clean}^{\rm wet})/2

  • E_{\rm water}^{\rm solution}. ]

Run slab_water_reference.py with and without --wet, using the slab calculation’s --nleb, --model and --epsilon. It uses the same frozen water geometry, functional, basis, dielectric and molecular iSwiG recipe. The isolated-water calculation uses the existing molecular boundary at infinity; the periodic film separately imposes zero induced charge per cell to avoid an exterior sheet field. Subtract the corresponding dry expression with gas-phase water to obtain the solvent shift. Using gas-phase water in both expressions defines a different thermodynamic cycle and must be labelled accordingly. These are electronic energies, without entropy, standard-state or nuclear-motion corrections.

Collect the six converged records with slab_adsorption.py:

python slab_adsorption.py --clean-dry clean-dry.solvation.json \
  --clean-wet clean-wet.solvation.json \
  --covered-dry covered-dry.solvation.json \
  --covered-wet covered-wet.solvation.json \
  --water-gas water-gas.solvation.json \
  --water-solution water-solution.solvation.json

For a replicated cell, set --adsorbates-per-cell to the total number of waters on both faces. The collector rejects unconverged records. Check the input metadata for matching geometry, solvent recipe and numerical settings; the collector performs the energy arithmetic, not a qualification verdict.

The XC quadrature uses bounded native point batches. Its memory preflight also counts the resident grid and lattice matrices. Hartree and exchange caches require additional memory, especially for replicated cells.

Collected refined CPCM calculation

The tutorial recipe converged the clean and water-covered primitive cells through run_periodic_job with MOIST import blocked. Both use the same 99/974 electronic grid, 18-bohr AO cutoff and fixed geometry. Wet cells use 302-point atomic surfaces, a 640x640 accessibility mesh at 0.0125-bohr normal spacing, normal quadrature 160 and dielectric 78.39.

System

Dry total (hartree/cell)

Wet total (hartree/cell)

Wet environment functional (hartree/cell)

Clean bilayer

-1087.036681017346

-1087.046130382108

-0.009535058390

Bilayer with two waters

-1237.530198083838

-1237.562318903156

-0.037202197550

The frozen isolated-water references are -75.219551673961 hartree in the gas phase and -75.226209423140 hartree with the matched molecular CPCM recipe. The public adsorption collector gives -0.027206859285 hartree per water dry and -0.031884837384 hartree per water from solution, a solvent shift of -0.004677978100 hartree or -0.127294269 eV per water.

The covered wet boundary residual is 2.13e-14 and its induced charges on the upper and lower faces are +1.91e-12 and -1.91e-12 elementary charges. The clean face charges are approximately -2.42e-11 and +2.42e-11. These near-zero face totals follow the symmetric geometry; local surface charges remain nonzero. Both records contain the plane-averaged solute, reaction and total potentials in the same open-normal gauge.

At a common covered density, refining the accessibility mesh from 320x320 at 0.025 bohr to 640x640 at 0.0125 bohr changes the environment functional by 19.34 microhartree per cell, or 0.0002631 eV per water. The retained site count changes from 1032 to 1008. This checks the cavity refinement separately from electronic self-consistency.

The corresponding 302-point COSMO totals are -1087.046069952934 hartree for the clean cell and -1237.562083343015 hartree for the decorated cell. With the matched solution-water reference of -75.226165072563 hartree, the primitive-cell solvent shift is -0.126118331 eV per water.

Refining the atomic surface from 302 to 590 points changes the solution adsorption energy by +0.000652008 eV per water for CPCM and +0.000646738 eV for COSMO, within the 0.01 eV budget. Changing the bookkeeping height from 30 to 47 bohr changes the reconverged CPCM totals by at most 9.1e-13 hartree per cell. At a common density, normal quadratures 160 and 240 differ by at most 1.32e-11 hartree in the environment functional and 1.21e-11 hartree in an AO reaction-operator element. These are primitive-cell controls; the larger-cell sampling comparison below remains separate.

Qualified 3x1 CPCM and COSMO calculations

The native-only 3x1 Gamma calculations use six mirrored waters per decorated cell, a 1920x640 accessibility mesh at 0.0125-bohr normal spacing, 302-point atomic surfaces and the 99/974 electronic grid. The host uses alpha 0.25, 201 normal Fourier points and 30/35-bohr AO/nuclear cutoffs. Both the electronic and environment residuals are converged.

System

Dry total (hartree/cell)

CPCM total (hartree/cell)

COSMO total (hartree/cell)

Clean 3x1 bilayer

-3261.201161581244

-3261.225868572445

-3261.225710482511

Decorated 3x1 bilayer

-3712.677947510559

-3712.774223367619

-3712.773529911138

Environment

System

Functional (hartree/cell)

Upper / lower induced charge (e)

Electronic commutator

Boundary residual

CPCM

clean

-0.024944944179

-8.304e-11 / +8.304e-11

1.930e-09

1.832e-15

CPCM

covered

-0.109504705552

+3.986e-10 / -3.986e-10

5.372e-09

2.992e-14

COSMO

clean

-0.024783837455

-3.083e-10 / +3.083e-10

1.460e-08

2.179e-15

COSMO

covered

-0.108629593043

-3.586e-11 / +3.585e-11

1.591e-08

2.747e-14

Model

Dry adsorption (hartree/water)

Adsorption from solution (hartree/water)

Solvent shift (eV/water)

2x1 to 3x1 change (eV/water)

CPCM

-0.026579314258

-0.031849709389

-0.143414757597

0.000367452670

COSMO

-0.026579314258

-0.031804832209

-0.142193587300

0.000361179309

Both finer sampling changes satisfy the unchanged 0.01 eV per-water budget. This tested rectangular sampling increment qualifies the numerical demonstration; it does not establish convergence in both in-plane directions, slab thickness or basis size. The failed primitive-to-2x1 check remains recorded below.

Both models ran through the public periodic entry point with MOIST import blocked. The public adsorption collector also ran through vq, with six waters per cell and the matched frozen-water references above. Directional density-derivative errors of the actual covered-cell AO reaction operators are at most 3.15e-10 hartree for CPCM and 8.45e-11 for COSMO. Covered fixed-point closure residuals are 2.40e-9 for CPCM and 3.53e-9 for COSMO.

For these larger-cell settings, add the following to each slab tutorial command, keeping the same numerical controls for the dry and wet pair:

--repeat-x 3 --repeat-y 1 --host-ewald-alpha 0.25 \
  --host-normal-points 201 --cutoff 30 --nuclear-cutoff 35

The converged dry density can initialize a solvent calculation through run_periodic_job(..., initial_guess="READ", read_from=dry_result). Independent native SAD dry calculations agree with the selected occupied-space initializations within 1.72e-10 hartree for the clean cell and 5.19e-11 for the decorated cell. An arbitrarily repeated Gamma density array can have occupations above two; it is not a valid SCF occupation constraint. The artificial READ-guess convergence issue is tracked in #1214.

The reconverged 2x1 COSMO 302-to-590 surface comparison changes solution adsorption by +0.000328919 eV per water, also within budget. Increasing the covered-cell normal quadrature from 160 to 240 changes the complete AO-to-surface map by at most 5.96e-9, the environment functional by 4.31e-12 hartree and the reaction operator by 1.08e-11 hartree. The separate 3x1 CPCM surface check uses the actual converged densities, holding them fixed while increasing the atomic rule from 302 to 590. Clean and covered site counts change from 1080 to 2184 and from 3024 to 5724, respectively. The environment functionals change by +0.000131283946 and +0.000167174275 hartree per cell. Including the matched refined water reference, the solution-adsorption change is +0.000314056590 eV per water, within budget. The first changed quantity is the surface quadrature point set; the reaction operators change by at most 0.000238989 and 0.000308158 hartree. The fine covered boundary residual is 1.324e-13. This is a common-density 3x1 check, complementing the fully reconverged primitive CPCM/COSMO and 2x1 COSMO surface comparisons; no reconverged 3x1 590-point total is claimed. A passing rectangular sampling increment does not establish convergence in both in-plane directions, basis size or slab thickness.

Fixed-coverage sampling checks

The 2x1 Gamma calculations also converged at the fine 302-point recipe, using the exactly repeated 1280x640 accessibility mesh and four waters per decorated cell:

System

Dry total (hartree/cell)

Wet total (hartree/cell)

Wet environment functional (hartree/cell)

Clean 2x1 bilayer

-2174.128128874490

-2174.144746659846

-0.016777459905

Decorated 2x1 bilayer

-2475.113213111325

-2475.177597488422

-0.073296676286

The covered electronic commutator is 2.29e-8 and the boundary residual is 1.75e-14. The solution adsorption solvent shift is -0.143782210 eV per water. Its change of -0.016487941 eV from the primitive cell exceeds the 0.01 eV budget. Electronic SCF convergence does not qualify this fixed-coverage energy difference.

Gamma replication changes the electronic k sampling as well as the surface cell. At exactly repeated physical density, the actual covered water/MgO boundary and AO map pass the following independent replication checks:

Quantity

Maximum absolute difference

Surface points after wrapping

1.78e-15 bohr

Surface weights

3.58e-15 bohr squared

Gaussian widths

0

Surface potential

1.96e-11 hartree/e

Solved charges

2.91e-12 e

Environment energy per original cell

4.95e-14 hartree

Collapsed AO reaction operator

4.63e-13 hartree

Every AO density block repeats in this diagnostic, so the physical density and integrated charge repeat exactly (Tr(DS) = 200). Its supercell occupations can exceed two; this is a linear-map check, not an SCF occupation constraint. The AO operator comparison sums all four supercell blocks and divides by two, as required by the density variation per original cell. A compact AO regression independently protects this test.

At the different converged SCF densities, the first differing field quantity is the surface potential (maximum change 0.0081673 hartree/e), followed by the charges (0.00033774 e) and collapsed AO operator (0.0024527 hartree). The supercell density retains primitive translation symmetry to 1.88e-11 in its AO blocks. The boundary replication check therefore passes. The finer CPCM and COSMO electronic sampling comparisons above pass their budgets. The completed surface and reference checks are recorded in #1168. The primitive adsorption value remains a collected result, not a converged adsorption prediction.

Collected coarse calculation

The public periodic entry point converged all four PBE/STO-3G calculations below. These use a 26-point atomic iSwiG rule, dielectric 78.39, accessibility spacing 0.4 bohr, normal quadrature 160, AO lattice cutoff 15 bohr and the 75/302-point electronic grid. To reproduce them with the tutorial, add --cutoff 15 --radial-points 75 --lebedev-order 29 to all slab commands and --nleb 26 --accessibility-spacing 0.4 --accessibility-mesh 20 20 to the wet slab commands. Use --nleb 26 for the solution-water reference.

System

Dry total (hartree/cell)

Wet total (hartree/cell)

Wet environment functional (hartree/cell)

Clean bilayer

-1087.036936781613

-1087.044034764622

-0.007151230636

Bilayer with two waters

-1237.530567787574

-1237.559399793882

-0.033475458597

The covered wet electronic commutator norm is 1.15e-8, its boundary residual is 5.27e-16, and its upper/lower face charges are approximately +1.99e-12/-1.99e-12 elementary charges. The clean wet face charges are +2.68e-8/-2.68e-8; the total induced charge vanishes in both cases. The records include the normal plane-averaged potentials.

The matched frozen-water energies are -75.219551673961 hartree in the gas phase and -75.226142831247 hartree in solution with the same 26-point rule. They give dry and wet adsorption energies of -0.027263829019 and -0.031539683383 hartree per water, respectively. The provisional solvent shift is -0.004275854364 hartree, or -0.116351925 eV per water.

These are historical SCF convergence results, superseded by the finer recipe and larger-cell controls above. The dry Hartree difference was traced to the reference Coulomb approximation, as recorded below. The coarse adsorption shift is not a numerically qualified prediction. In particular, the covered-slab environment at a common density changes by 2.66 millihartree between 0.4- and 0.1-bohr accessibility masks, above the adsorption accuracy budget. The 0.4-bohr mask is not qualified for this system. The tutorial uses the finer recipe recorded in #1168; the generic SlabSolvationOptions defaults remain coarse starting controls which need system-specific refinement.

The isolated solution-water reference has also converged with 50-, 110- and 302-point iSwiG rules, giving -75.226154958382, -75.226201424645 and -75.226209423140 hartree. The 110-to-302 change is 8.0 microhartree. Slab surface refinement must be assessed independently.

Independent dry reference

The matched clean and covered CRYSTAL input decks, and their clean 2x1 and covered 2x1 replicas, use the true SLAB boundary, the same geometry, PBE/STO-3G and Gamma sampling. Their in-plane coordinates are fractional; normal coordinates are in angstrom. CRYSTAL23 version 1.0.1 with XXLGRID, BOHRANGS 0.529177210903, TOLINTEG 20 20 20 20 40, POLEORDR 6, NOBIPCOU and TOLDEE 9 gave the following independently converged dry energies through vq:

System

Energy (hartree per cell)

SCF cycles

Clean MgO bilayer

-1087.0366843957

2

Bilayer with two mirrored waters

-1237.5301949196

5

Clean 2x1 bilayer

-2174.1281358913

2

Decorated 2x1 bilayer

-2475.1132070455

2

Clean 3x1 bilayer

-3261.2011720959

12

Decorated 3x1 bilayer

-3712.6779384824

10

The standalone clean 3x1 and covered 3x1 decks extend this comparison to the next Gamma supercell at fixed coverage. Both completed with strict energy convergence and normal termination. The selected covered native total differs from CRYSTAL by -3.009 microhartree per original cell, within the unchanged 10-microhartree target. The covered reference used a provisional CRYSTAL-only XLGRID/TOL15 density as an initial guess, then fully reconverged the stated XXLGRID/TOL20/TOLDEE9 calculation. Its provisional energy is excluded. Exact inputs, source/runtime identities and measured errors are recorded with #1168.

The independent native SAD run of the clean 3x1 cell gives -3261.201161581073 hartree, with physical commutator 1.87e-8 and fixed-point closure 9.26e-9. It uses host alpha 0.15, 401 normal Fourier points and 40/45-bohr AO/nuclear cutoffs. Its difference from CRYSTAL is 3.50 microhartree per original cell, within the 10-microhartree target. This dry electronic-host check is independent of the solvent qualification.

The conversion factor matches the native input. Changing XLGRID to XXLGRID and matching the conversion, while retaining the initial Coulomb approximation, changed the clean and covered energies by 6.03 and 0.85 microhartree, respectively.

The initial TOLINTEG 10 10 10 10 20 references were -1087.0360057991 and -1237.5295622593 hartree. Tightening the Coulomb approximation lowers them by 674.18 and 629.87 microhartree. This was the first material source of the apparent dry-host disagreement. Native clean RKS with the 99/974 grid and 18-bohr cutoff gives -1087.036681017346 hartree, 3.38 microhartree above the TOL20 reference. The refined native covered energy is -1237.530198083838 hartree, 3.16 microhartree below its reference. Both are within the 1e-5-hartree target. At the same TOL20 CRYSTAL density, with Tr(DS) = 80 and an AO orthonormality error of 6.22e-12, the native minus reference component differences are:

Contribution

Difference (microhartree/cell)

Kinetic

0.000018

Electron-nuclear

-0.1302

Hartree

0.5488

Nuclear repulsion

0.000880

Exchange-correlation

2.9594

Total

3.3788

The first material common-density difference is the XC quadrature, rather than the periodic electrostatic terms. At TOL15, the largest component difference was 22.74 microhartree in the electron-nuclear contribution. Tightening TOL15 to TOL20 changes the clean and covered references by another 4.41 and 2.79 microhartree, respectively. Separate split-parameter, short-range screening and zero-mode checks constrain the native electrostatic error.

The primitive and 2x1 TOL20 references reused converged TOL15 CRYSTAL wavefunctions as initial guesses; the standalone decks start without that optional restart. These are dry electronic-host references; dry agreement does not certify the continuum model. The passing accessibility and angular refinements are recorded above and in #1168. The grounded-plane and normal dipole-sheet checks provide separate analytic electrostatic evidence. No matched independent periodic solvent calculation is currently available.

The numerical acceptance budget for this increment is 1e-5 hartree per primitive cell for the refined dry host against the matched independent reference, and 0.01 eV per water for the solvent adsorption shift under surface and electronic refinement at fixed coverage. Bookkeeping-height changes must stay below 1e-9 hartree per cell. Boundary residuals must stay below 1e-7 and electronic commutator norms below 1e-6. The analytic boundary and density-derivative checks remain separate evidence.

Numerical definition

A surface site is the unit-integral density (\xi^3\pi^{-3/2}\exp(-\xi^2r^2)). For two sites the effective width is (\alpha=(\xi_i^{-2}+\xi_j^{-2})^{-1/2}). The periodic Green function uses the Parry reciprocal modes, the analytic zero mode (-2\pi[g_0(z,\alpha)]/A), and an Ewald real-space correction, where (g_0=z,\mathrm{erf}(\alpha z)+\exp(-\alpha^2z^2)/(\alpha\sqrt\pi)). Its diagonal contains the Gaussian self interaction and every lateral image. The iSwiG self correction is (\sqrt{2/\pi}\xi_i(1/f_i-1)), with switching factor (f_i).

The augmented symmetric solve is

[

(1)\[\begin{pmatrix}S&1\\1^T&0\end{pmatrix}\]
(2)\[\begin{pmatrix}q\\\lambda\end{pmatrix}\]

=\begin{pmatrix}-s\phi\0\end{pmatrix},\qquad E_{\rm env}=\tfrac12\phi^Tq. ]

CPCM uses (s=(\epsilon-1)/\epsilon), COSMO uses (s=(\epsilon-1)/(\epsilon+1/2)), and both tend to one at the conductor limit. This is conductor-like dielectric scaling, not a general dielectric interface boundary-element solution.

The AO map combines native short-range three-centre integrals and analytic Bloch AO-pair Fourier transforms. A continuous normal quadrature and a subtracted zero-mode integral complete the open-normal map. Its exact transpose supplies the Fock term. The RKS builder retains the dry core Hamiltonian in its energy expression and adds E_env once. Thus it does not include an extra full density contraction of the reaction operator. Electronic convergence includes the applied field; each environment solve must also satisfy its specified residual tolerance.

Operation

Source and governing formulation

Native implementation

Open-normal electrostatics

Parry (1975), DOI 10.1016/0039-6028(75)90362-3; de Leeuw and Perram (1979), equations 8, 11-14 and image-energy equations 15-19, DOI 10.1080/00268977900100951

solvation/slab.py, periodic_v_ne_slab.py

Gaussian elements and switching

Lange and Herbert (2010), DOI 10.1063/1.3511297; pinned molecular port and notices

moist_native.py, solvation/slab.py

CPCM scaling

Cossi et al. (2003), DOI 10.1002/jcc.10189

SlabSurfaceOperator

COSMO scaling

Klamt and Schuurmann (1993), DOI 10.1039/P29930000799

SlabSurfaceOperator

Density map and adjoint

Full AO-pair density, spin-summed occupations, normalized k weights

SlabDensityMap, SlabGaussianHost, periodic_ks_fock.py

The surface construction reuses the native molecular port’s radius data, Lebedev weights, width constants and switching thresholds. The periodic Green function, reservoir constraint and accessibility filter are explicit extensions. No upstream MOIST periodic solver is called or assumed. See the design for later models and hosts.

The tutorial uses ISwiGCavity(radius_model="cpcm") for both dielectric models. Those tabulated radii already include their upstream scaling; no further radius multiplier is applied:

Element

Radius (angstrom)

Radius (bohr)

H

1.300

2.456643962007

O

1.720

3.250328934347

Mg

1.638

3.095371392128

The radius conversion preserves the upstream constant angstrom_per_bohr = 0.5291772109044922. The example geometry separately uses 0.529177210903, matching its independent CRYSTAL input. Custom ISwiGCavity.radii_bohr values are per atom in bohr. Changing the cavity radius model changes the physical boundary even if the dielectric scaling is held fixed.

Lebedev solid-angle weights sum to 4*pi. For radius R and solid-angle weight w, the raw area is R**2*w; its exposed weight is that area times the iSwiG switching factor f. The Gaussian width is formed from the raw area before switching, xi = zeta_n / sqrt(R**2*w). The upstream constants are zeta_302 = 4.90498088169 and zeta_590 = 4.90624071359. The default switching thresholds are cut_a=0 and cut_f=1e-10. Retained elements use the self correction above, so multiplying the width by an additional switching factor would change the discretization.

These data and conventions come from the molecular source-guided port at MOIST commit 922287f53b1cc2ac6b1f77ad6ca4c846d72df7b8; its source map and license notices also apply to the reused molecular cavity components.