Feature: periodic self-consistent continuum solvation (SCCS) Step4: delayed start, relax, diagnostics and out_sol by LKFEIYI · Pull Request #8222 · deepmodeling/abacus-develop

LKFEIYI · 2026-10-27T13:14:52Z

Linked Issue

Fifth part of #8052. It follows #8075 (PCC), #8162 (SCCS Step 1: periodic SCCS), #8194 (SCCS Step 2: SCCS with PCC 0D/2D) and #8219 (SCCS Step 3: derivative lowpass filter and full cavity).

This PR is stacked on #8219: until #8219 is merged, please review only the last commit. The remaining follow-up PR adds the solvent-aware cavity.

Summary

Steps 1–3 run SCCS only in a single SCF, with the solvent active from the first iteration and with no diagnostics. This PR adds what is needed to use SCCS in real calculations:

Delayed start (sccs_start_drho, sccs_start_nmax). The SCF first runs without the solvent until reaching a desired drho, then SCCS starts, which is also applied in Environ and cp2k.
Fixed-cell relax (calculation relax). The SCCS potential is rebuilt every ionic step. The start state and the last sqrt-CG solution carry over as a warm start.
Diagnostics (sccs_debug 1/2). Solver iterations, residuals, cavity volume and surface, Gauss-law and multipole checks are written to the running log (only for debug).
Solvent fields (out_sol 1). The dielectric function and the cavity are written as cube files, for both imp_sol 1 and imp_sol 2.

All four are off by default, and nothing changes for existing inputs: no existing integration reference changes.

What's changed?

1. Delayed start and fixed-cell relax

PotSccs gains a start state. Until it starts, it contributes no potential, energy or force. It starts once DRHO ≤ sccs_start_drho, or at iteration sccs_start_nmax at the latest. Once started, it stays on.
Relax. pot_register reads the SCCS state (SccsResume: start flag and warm start) from the old components before deleting them. It passes the state explicitly to get_pot_type, which gains a const SccsResume& parameter, so no new member variable holds it. Registration keeps its original order: old components are deleted first.
SccsFixedSources caches the Gaussian ion and core densities and the grid coordinates within one ionic step. They are rebuilt only when the atoms change.

2. Diagnostics (sccs_debug)

Level 1: one line per SCF iteration, with the sqrt-CG iteration count and the solvation and PCC energies.
Level 2 adds, in every SCF iteration:
- residuals and warm start;
- cavity volume and surface;
- FFT counts;
- with PCC, the Gauss-law check (far-field polarization charge against its expected value), the origin and the smooth, point, polarization and screened multipole moments, and the energy components.

3. out_sol

out_sol 1 [precision] writes sol_eps.cube and sol_cavity.cube through ModuleIO::write_vdata_palgrid, at the same point as out_pot.
For imp_sol 1, surchem keeps the dielectric function of its last cal_vel, and the cavity is computed from it as 1 − S.
Nothing is written while SCCS waits for its delayed start.

Governance Notes

Core module impact.
- ESolver (esolver_ks.cpp only). Following source/source_esolver/AGENTS.md, it only calls named steps of module_charge and adds no function of its own:
  - iter_finish calls update_pot_model before mixing and print_corr_iter after print_etot;
  - iter_finish reads PARAM.globalv.two_fermi once into a local.
- Charge (chg_routine): update_pot_model and print_corr_iter select the first rank of the first pool, the screen for the start notice and the running log for sccs_debug.
- ElecState:
  - Potential gains model_pending, update_model, write_corr_iter and sol_out_fields.
  - get_pot_type gains a SccsResume parameter, and its only call site is updated.
  - Charge mixing: the changes in item 4.
- Output: ctrl_output_fp writes out_sol.
- No changes to HSolver, Operator or Psi.
Global dependencies. The PR adds 2 references (GlobalV::ofs_running for the running log, in chg_routine.cpp, and the two_fermi local) and removes 3, for a net change of −1. The checker reports these as warnings only.
Exceptions requested: none. The governance check reports 0 errors and 17 warnings:
- 2 global-dependency warnings: see above.
- 14 header-dependency warnings. Each header declares a member or parameter of that type:
  - <iosfwd> in pot_sccs.h, potential_new.h and sccs_output.h: std::ostream parameters.
  - sccs_output.h and sccs_fixed_src.h in pot_sccs.h: value members of PotSccs.
  - charge_moments.h and sccs_coulomb.h in sccs_output.h: value members of PccOutput and SccsOutput.
  - <memory> and <vector> in sccs_fixed_src.h, <string> and <vector> in sol_grid_field.h, <vector> in sccs_diag.h, sccs_output.h and surchem.h.
Code quality score. esolver_ks.cpp is 65, as on develop

Every line is a row of 16-character, left-aligned cells: the tag, then KEY/unit and value cells, so every cell starts on a column edge and the columns line up across lines and iterations. Values are in scientific notation (9 significant digits for energies, 8 otherwise). The PCC moments form a table whose headers start at the column edges. PCC_USED/Ry is dropped (it repeats E_PCC/Ry), and SCCS_DEFERRED is formatted in sccs_output.cpp with the other lines.

ABACUS-PR-BOT

The new solvent-output regression can pass when an expected cube is missing; please make that absence fail the check.

Non-blocking: please record the exact commands, configurations and observed results for the added unit/integration tests and relevant INPUT checks, identifying anything not run.

Static review of the complete feature delta at 434ee60e3e5005782a8f73970722c41fd32555cb; builds, tests and numerical runs were not executed, and CI diagnostics were unavailable.

ABACUS-PR-BOT · 2026-10-28T12:43:31Z

+                para.input.out_sol[0] = std::stoi(item.str_values[0]);
+                if (count >= 2)
+                {
+                    para.input.out_sol[1] = std::stoi(item.str_values[1]);


Non-blocking: out_sol 1.5 6junk is parsed as 1 6, and tokens after the second are ignored. The vector-domain binding does not validate these original tokens; please require exactly one or two complete integer tokens and cover malformed prefixes and extra arguments in the INPUT tests.

out_sol takes exactly one or two tokens, and each must be a whole integer: std::stoi with the position argument, and the token must be fully consumed.

- props_basic.sh: out_sol 1 fails the case when sol_eps.cube or sol_cavity.cube is missing, instead of silently skipping the sol_cavity_integralref check. - out_sol: accept exactly one or two whole integer tokens; "6junk", "8x" and a third token are rejected. INPUT tests cover these. - sccs_debug: the help text and a comment state that the FFT counts are the Coulomb-operator FFTs of the sqrt-CG solve. - sccs_output: name the computed precision and padding; a cell as wide as the column (a three-digit exponent) keeps one blank instead of running into the next cell. A test covers it.

mohanchen · 2026-10-29T12:19:09Z

there are some conflicts need to be resolved, thx. @LKFEIYI

Resolve the conflicts with deepmodeling#8223.

ABACUS-PR-BOT

Delayed SCCS activation can feed a stale PW DFT+U occupation matrix into the next potential update. Please reset its mixing history alongside the charge history.

Static review at f14898e0ac1c7d4a4d5cc9bd7581fa907aa89c6e against 5a7e6a61c90cf7a96bc02ca0c0f98bff9109be54; builds, tests, numerical runs and CI diagnostics were not executed.

ABACUS-PR-BOT · 2026-10-29T19:55:00Z

+void Charge_Mixing::restart_for_new_model(const int iter)
+{
+    this->mix_reset();
+    this->mixing_restart_last = iter;


With PW DFT+U, mixing_dftu 1 and mixing_type pulay, activating SCCS after the occupation history is populated resets rho_mdata but leaves uom_mdata at its old ring position. When charge mixing runs in that iteration, the next mix_uom can apply its new coefficients to stale occupation columns and feed a stale matrix into the +U potential. Please reset UOM on this transition and test the first occupation update after activation.

mix_reset now restarts the DFT+U occupation history together with the density and density-matrix histories, so after SCCS starts the first mix_uom is a single simple mixing step on the new occupations.

mix_uom reuses the rho Pulay coefficients, so mix_reset now restarts uom_mdata together with the rho and DMR histories.

ABACUS-PR-BOT

The new UOM reset addresses the occupation-history mismatch raised in the previous review, and the added test targets the first mix after restart. I found no new functional issue in this update; one non-blocking call-site suggestion is inline.

Static source review only; builds and runtime tests were not run.

LKFEIYI added 2 commits October 28, 2026 15:38

Feature: SCCS delayed start, fixed-cell relax, diagnostics and out_sol

52abb85

LKFEIYI force-pushed the codex/sccs-pcc-3-scf branch from 47b8635 to 434ee60 Compare October 28, 2026 08:04

LKFEIYI marked this pull request as ready for review October 28, 2026 08:06

Critsium-xy mentioned this pull request Oct 28, 2026

Move the dV/dR sparse conversion out of module_gint and narrow three header includes #8230

Merged

6 of 7 tasks

ABACUS-PR-BOT reviewed Oct 28, 2026

View reviewed changes

This was referenced Oct 29, 2026

[Dependency] module_gint includes source_lcao for the dH sparse output; two headers include more than they use #8232

Closed

[Dependency] Structure_Factor and Soc live in source_pw, but source_psi, source_estate and source_hamilt depend on them #8233

Closed

mohanchen added Feature Discussed The features will be discussed first but will not be implemented soon Refactor Refactor ABACUS codes labels Oct 29, 2026

LKFEIYI and others added 2 commits October 29, 2026 21:19

Merge branch 'develop' into codex/sccs-pcc-3-scf

6d64c28

Resolve the conflicts with deepmodeling#8223.

Merge branch 'develop' into codex/sccs-pcc-3-scf

f14898e

ABACUS-PR-BOT reviewed Oct 29, 2026

View reviewed changes

LKFEIYI and others added 2 commits October 30, 2026 08:21

Reset the DFT+U occupation mixing history when SCCS starts

3225b65

mix_uom reuses the rho Pulay coefficients, so mix_reset now restarts uom_mdata together with the rho and DMR histories.

Merge branch 'develop' into codex/sccs-pcc-3-scf

c6de778

ABACUS-PR-BOT reviewed Oct 30, 2026

View reviewed changes

Comment thread source/source_estate/module_charge/unittests/test_chg_mix.cpp Resolved

Name the occupation values in ModelChangeRestartsUomHistory

70a45d0

Navigation Menu

Repository navigation

Feature: periodic self-consistent continuum solvation (SCCS) Step4: delayed start, relax, diagnostics and out_sol - #8222

Feature: periodic self-consistent continuum solvation (SCCS) Step4: delayed start, relax, diagnostics and out_sol#8222
LKFEIYI wants to merge 8 commits into
deepmodeling:developfrom
LKFEIYI:codex/sccs-pcc-3-scf

LKFEIYI commented Oct 27, 2026

Uh oh!

ABACUS-PR-BOT left a comment

Uh oh!

Uh oh!

ABACUS-PR-BOT Oct 28, 2026

Uh oh!

LKFEIYI Oct 28, 2026

Uh oh!

Uh oh!

Uh oh!

mohanchen commented Oct 29, 2026

Uh oh!

ABACUS-PR-BOT left a comment

Uh oh!

ABACUS-PR-BOT Oct 29, 2026

Uh oh!

LKFEIYI Oct 30, 2026

Uh oh!

ABACUS-PR-BOT left a comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

LKFEIYI commented Oct 27, 2026

Linked Issue

Summary

What's changed?

Governance Notes

Uh oh!

ABACUS-PR-BOT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ABACUS-PR-BOT Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

LKFEIYI Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mohanchen commented Oct 29, 2026

Uh oh!

ABACUS-PR-BOT left a comment

Choose a reason for hiding this comment

Uh oh!

ABACUS-PR-BOT Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

LKFEIYI Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

ABACUS-PR-BOT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants