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 |
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
[
=\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 |
|
Gaussian elements and switching |
Lange and Herbert (2010), DOI 10.1063/1.3511297; pinned molecular port and notices |
|
CPCM scaling |
Cossi et al. (2003), DOI 10.1002/jcc.10189 |
|
COSMO scaling |
Klamt and Schuurmann (1993), DOI 10.1039/P29930000799 |
|
Density map and adjoint |
Full AO-pair density, spin-summed occupations, normalized k weights |
|
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.