Add fixed-cell i-PI socket driver

[Phorbol]

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 requested any needed governance exception below.

Linked Issue

No linked issue. This PR adds a new optional driver mode and does not change the default execution path.

Unit Tests and/or Case Tests for my changes

• Added a focused INPUT reset-value unit test for chg_extrap default with calculation socket, expecting first-order.
• Ran fixed-cell socket smoke tests with an ASE SocketIOCalculator driver:
  • sequential energy/force requests through a persistent ABACUS socket process;
  • fixed-cell ASE NVT MD for a short trajectory;
  • fixed-cell ASE LBFGS relaxation for a short trajectory.
• Explicitly tested chg_extrap atomic, first-order, and second-order in socket mode. The result is trajectory dependent, so this PR documents the default behavior but does not claim one extrapolation mode is universally fastest.

Exact Verification Performed

Commands run:

# Rebase state
git fetch origin develop
git rebase origin/develop

# Build, using the same CMake build tree after loading the ABACUS CUDA/MPI/ELPA environment
cmake --build <build-dir> -j 32

# CLI/help checks
<build-dir>/source/abacus_basic_gpu -h calculation
<build-dir>/source/abacus_basic_gpu -h chg_extrap

# Governance check against the current upstream base
python3 tools/03_code_analysis/agent_governance_check.py \
  --base origin/develop --head HEAD --format text

Result summary:

• The branch rebases cleanly on the current upstream develop.
• The build completed successfully and produced abacus_basic_gpu.
• abacus_basic_gpu -h calculation lists socket.
• abacus_basic_gpu -h chg_extrap documents that default chooses first-order for relax/cell-relax/socket, second-order for md, and atomic for other calculations.
• The governance checker reports the global dependency exception described below and header-include warnings for the new socket helper header. No CMake linkage, INPUT documentation, line-ending, or default-argument blocker was reported.

Checks not run, with reason:

• The newly added serial INPUT unit test was not run locally because the available validation build was configured without the relevant test target. The test source is included for CI/reviewer runs.
• Full CI/toolchain matrix was not run locally. The new code is wired into the normal CMake source list and should be covered by CI builds.
• Variable-cell, stress, ASE NPT, and ASE FrechetCellFilter workflows were not run because this PR intentionally supports fixed-cell energy/force requests only.

What's changed?

This PR adds a fixed-cell i-PI-compatible socket driver mode for ABACUS.

Motivation:

• External atomistic drivers such as ASE optimizers and MD engines often need repeated energy/force evaluations for a sequence of closely related structures.
• Without a socket driver, each evaluation is typically handled as a separate ABACUS run, which repeats process startup, INPUT/STRU/KPT parsing, setup, and file handoff work.
• A socket driver lets an external program keep one ABACUS process alive, send updated atomic positions, and receive energy/forces through a standard i-PI-style protocol.
• This provides a cleaner integration path for ASE SocketIOCalculator and similar drivers while keeping the default ABACUS calculation modes unchanged.SocketIOCalculator, to keep one ABACUS process alive and request energy/forces for updated atomic positions.

User-visible INPUT change:

calculation socket

Socket endpoint selection:

export ABACUS_IPI_ADDRESS=/tmp/ipi_abacus_test:UNIX

The value is an address string, not an installed dependency:

• /tmp/ipi_abacus_test is the UNIX-domain socket path created by the external driver.
• :UNIX tells ABACUS to connect through a UNIX-domain socket instead of TCP.
• For TCP, ABACUS_IPI_ADDRESS=localhost:31415 is also supported.
• In batch jobs, use a unique socket path, for example /tmp/ipi_abacus_${SLURM_JOB_ID}:UNIX, to avoid collisions.

No i-PI library is linked or required by ABACUS. The implementation speaks the subset of the i-PI socket protocol needed by ASE-style drivers using POSIX sockets. Users need an external socket server/driver, for example ASE, to create the socket and launch ABACUS as the client.

Implementation details:

• driver_run() dispatches calculation socket to Driver::driver_ipi_run() before the ordinary calculation-mode dispatch.
• driver_ipi_run() initializes hardware and an ESolver once, then enters an i-PI message loop.
• The socket driver handles STATUS, INIT, POSDATA, and GETFORCE messages.
• On POSDATA, ABACUS updates atomic positions in the existing fixed cell, runs the SCF runner, computes energy and forces, and stores them for the following GETFORCE response.
• Energies are returned in Hartree and forces in Hartree/Bohr, matching i-PI protocol conventions.
• Incoming POSDATA cell vectors are compared to the ABACUS cell using the ASE/i-PI transpose convention. Non-matching cells are rejected because variable-cell updates are not implemented in this PR.
• The implementation returns a zero virial placeholder and must not be used as stress support.
• Root-rank socket I/O errors are broadcast to MPI ranks to avoid rank divergence.
• Cleanup is guarded so after_all_runners() is called only after at least one successful runner call.

Example external-driver shape with ASE:

import os
import subprocess
from ase.calculators.socketio import SocketIOCalculator

abacus_cmd = "mpirun -np 1 -mca coll_hcoll_enable 0 /path/to/abacus_basic_gpu"
workdir = "/path/to/case-with-INPUT-STRU-KPT"

def launch_client(atoms, properties, port=None, unixsocket=None):
    env = os.environ.copy()
    env["ABACUS_IPI_ADDRESS"] = f"/tmp/ipi_{unixsocket}:UNIX"
    return subprocess.Popen(abacus_cmd, shell=True, cwd=workdir, env=env)

with SocketIOCalculator(unixsocket="abacus_socket", timeout=1200, launch_client=launch_client) as calc:
    atoms.calc = calc
    energy = atoms.get_potential_energy()
    forces = atoms.get_forces()

Example minimal INPUT fragment:

INPUT_PARAMETERS
calculation socket
esolver_type ksdft
basis_type lcao
cal_force 1
cal_stress 0
chg_extrap default

Compile/use notes:

• No new third-party C++ library is introduced.
• The new source files are added to the existing CMake driver object list.
• A normal ABACUS CMake build should pick up the implementation through source/CMakeLists.txt.
• Runtime users still need an external socket server, such as ASE SocketIOCalculator, to create the socket and launch/connect ABACUS.

Governance Checklist

• Global dependencies: exception requested below. This new top-level driver currently follows existing Driver integration patterns and uses PARAM/GlobalV for input, rank, logging, ESolver setup, JSON output, and hardware lifecycle.
• Default parameters: no new default arguments added.
• Headers: ipi_socket.h includes standard library declarations needed for its public value types (std::string, std::vector, std::size_t).
• Line endings: changed text files use LF.
• Build linkage: new source files are listed in source/CMakeLists.txt.
• Documentation: INPUT behavior changes update both docs/parameters.yaml and docs/advanced/input_files/input-main.md.
• CodeRabbit: if automatic review does not start, please request @coderabbitai review.

INPUT Parameter Changes

• Parameters added/removed/changed:
  • calculation: adds the new accepted value socket.
  • cal_force: defaults to enabled for calculation socket, consistent with socket energy/force use.
  • chg_extrap: documents calculation-dependent default routing and routes socket mode to first-order.
• docs/parameters.yaml updated: yes.
• docs/advanced/input_files/input-main.md updated: yes.
• If not updated, explain why no INPUT documentation update is required: not applicable.

Core Module Impact

• Affected core modules:
  • Driver: adds a new socket driver dispatch path.
  • ESolver: reused through the existing SCF runner path; no ESolver API change.
  • UnitCell: positions are updated from incoming POSDATA under a fixed cell; variable-cell updates are rejected.
  • source_io/module_parameter: adds INPUT metadata/default behavior for socket mode.
• Risk summary:
  • The default behavior for existing calculation modes is unchanged.
  • The new mode is opt-in via calculation socket.
  • Stress/virial and variable-cell support are intentionally out of scope.
  • The largest maintenance concern is the new driver-level use of PARAM/GlobalV, covered by the governance exception below.
• Compatibility or performance impact:
  • Existing scf, relax, md, cell-relax, and post-processing modes should continue through the existing dispatch path.
  • Socket mode can avoid repeated process startup for external fixed-cell optimizers/MD drivers, but actual performance depends on the driver trajectory, SCF setup cost, charge extrapolation choice, and build/runtime environment.

Governance Exception

• Rule: Global dependency budget; avoid increasing GlobalV, GlobalC, or PARAM references.
• Reason: This PR adds a top-level driver mode. Existing ABACUS driver setup currently obtains input, MPI rank/logging, hardware lifecycle, ESolver initialization, and JSON output through PARAM/GlobalV patterns. The socket driver follows that integration style to keep the change localized and avoid broad core-interface churn.
• Scope: New references are confined to the new socket driver and the small dispatch point in driver_run.cpp.
• User or maintenance risk: The new mode is opt-in, but the implementation adds another driver path that depends on global runtime state. This may make future refactoring harder if socket support is expanded to stress or variable-cell workflows.
• Why the normal rule cannot be followed now: Passing all required driver context explicitly would require a broader redesign of Driver, ESolver setup, logging, hardware lifecycle, and JSON output interfaces, which is larger than this feature PR.
• Follow-up cleanup plan: If maintainers prefer, a follow-up PR can introduce a narrow driver context object or helper interface and migrate this socket driver, and potentially other driver modes, away from direct global access.
• Requested approver: ABACUS core driver / architecture maintainers.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[mohanchen]

it is not a good idea to add new function here,

[mohanchen]

we have 'bcast_int' function that can be used without writing a new one

[mohanchen]

we use WARNING_QUIT

[mohanchen]

I would suggest not using PARAM (global variable)

[mohanchen]

Thanks for the PR, but here it seems not appropriate to set the calculation as 'socket' first and then change it to 'scf', it may better to design another variable other than calculation

[mohanchen]

seems better to name the file name as socket_ipi.cpp, consistent with the socket_driver.cpp

[mohanchen]

could you provide some examples in the 'interface' directory to demonstrate that the function can run successfully?

[mohanchen]

do you have an example to demonstrate how to use this feature?