Add constant-potential electron control to the i-PI socket driver

[zhangchenyu-USTC]

What's changed?

Extend the native i-PI socket driver to receive a total electron count before each structure evaluation. PW and LCAO update occupations and charge-dependent potentials, run SCF, and return energy, forces, the actual occupation sum, the Fermi level, and an optional work function. Each response represents one completed frame.

The work-function reference shares the electrostatic-potential construction used for cube output, including PCC, and averages the requested window in memory. Constant-potential evaluations check SCF convergence and the electron count with an absolute tolerance of 1e-8. The PW ACE path receives the current occupations before constructing exchange.

Use the existing socket_driver INPUT option; electron-control settings belong to i-PI. Socket calculations default to symmetry=0 unless explicitly set, and position updates use nearest-image displacements for charge extrapolation. Energy-only Makov–Payne correction is rejected at the electronic-control entry point; ordinary Makov–Payne SCF and socket calculations retain their native behavior.

The matching i-PI server, PW/LCAO examples, and real-client tests are published together. This PR contains five focused C++ test files for protocol parsing, socket sessions, occupation reduction, INPUT behavior, and electrostatic-potential averaging.

Linked Issue

This extends the existing i-PI socket interface; there is no separate tracking issue.

Unit Tests and/or Case Tests for my changes

Built the candidate and unmodified reference with the same GNU/OpenMPI/LibXC/LibRI configuration and JSON enabled. The merged source is based on f264b4022fd477734de0f3ace723f6da9e306943, including #8119 and #7976. The DFT+U check uses the upstream init_occ_mat field.

ctest --test-dir build --output-on-failure \
  -R '^(MODULE_AO_ORB_atomic_lm_test|MODULE_RELAX_socket_.*_test|MODULE_ESOLVER_electronic_occupations.*_test|MODULE_IO_read_item_serial|MODULE_ESTATE_electrostatic_potential.*_test|MODULE_ESTATE_elecstate_occupy)$'

# In the linked i-PI checkout:
export ABACUS_CP_EXECUTABLE=/path/to/candidate/abacus
export ABACUS_REFERENCE_EXECUTABLE=/path/to/reference/abacus
export ABACUS_PP_ORB=/path/to/abacus-source/tests/PP_ORB
export PYTHONPATH=/path/to/abacus-source/interfaces/ASE_interface
bash examples/clients/abacus/validation/tests/run_develop_core.sh /path/to/new-results

export ABACUS_TEST_RANKS=1
python -m pytest examples/clients/abacus/validation/tests/test_socket_session_failures.py -k makov

export ABACUS_TEST_RANKS=4
python -m pytest examples/clients/abacus/validation/tests/test_electronic_methods.py \
  -k 'dftu1 or pbe0 or exhausted'

• 11 CTest targets passed, including potential averaging and occupation reduction with 1 and 4 MPI ranks.
• 46 real-client core tests passed with 4 ranks. They cover electron-count and position changes, static references, cube potentials, ordinary SCF/MD/relax, ASE, trajectories, restart, and exits.
• 8 Makov–Payne tests passed with 1 rank: PW/LCAO rejection for all three input spellings and ordinary SCF/socket reference comparisons. These also pass in the 4-rank core suite.
• 6 DFT+U and hybrid-functional checks passed, including exhausted EXX iteration budgets.
• Four upstream PW/LCAO PCC cases passed their references; candidate/reference cubes, energies, and forces matched exactly.

Governance Notes

The check reports 0 errors and 8 warnings. Four concern existing output, driver wiring, and EXX logging; the net number of global references decreases by one. Four concern header dependencies required by the stored window and completed-frame types and their string/vector members. Electronic control is passed explicitly to ESolver; electrostatic-potential construction remains in ElecState.

No documentation update required for generated files: following #7976, INPUT help is maintained in Input_Item metadata and rendered by CI. The PR does not restore parameters.yaml or input-main.md.

Reminder

• I have read AGENTS.md and docs/developers_guide/agent_governance.md.
• I have linked an issue or explained why this PR does not need one.
• I have added adequate unit tests and/or case tests, or explained why not.
• I have listed the exact verification commands run and their results.
• I have described user-visible behavior changes, including INPUT parameter changes.
• I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
• I have explained the governance warnings above.

[mohanchen]

@ABACUS-PR-BOT please review this PR

[ABACUS-PR-BOT]

Static review independently cross-checked at 8bfcec692120952fdfa27fd6dec7d2f8518b73ec. Trusted governance and whitespace checks passed (0 governance errors, 8 warnings reviewed). No builds or runtime tests were run; CI diagnostics were unavailable.

[ABACUS-PR-BOT]

[P2] Reject energy-only Makov–Payne correction for electron control

With a charged cubic cell and assume_isolated=makov-payne, this gate accepts the session, but cal_energies() adds the charge-dependent correction to the returned energy while electronic_observables() returns the uncorrected band Fermi level. Even the leading alpha*e2*Q^2/(2L) term contributes -alpha*e2*Q/L to the electron-number derivative, so those outputs describe different energy functionals. Please reject this combination here unless consistent potential/derivative support is provided, and add a focused rejection test.

[zhangchenyu-USTC]

Added the Makov–Payne check at the start of ESolver_FP::apply_electronic_control(), before any electronic state is changed. Real PW/LCAO tests cover makov-payne, mp, and m-p with 1 and 4 MPI ranks, and ordinary Makov–Payne SCF/socket comparisons still pass. Tests.

[ABACUS-PR-BOT]

Non-blocking: The linked triclinic cube comparisons cover all three axes, but a small in-tree test of this helper would make its window and partition rules easier to preserve. A hand-computed grid can check points exactly on the half-open window edges, an empty window, and an MPI rank with no local planes against the serial average. This can be a follow-up.

[zhangchenyu-USTC]

Added test_electrostatic_potential.cpp, calling the production planar_potential_average() with hand-calculated expectations. It covers x/y/z, half-open window boundaries, empty windows, empty MPI slabs, unequal partitions, and triclinic cells. Both MPI 1/4 CTest targets pass. The averaging implementation is unchanged.