Add fixed-cell i-PI socket driver

docs/advanced/input_files/input-main.md

@@ -9,6 +9,7 @@
     - [suffix](#suffix)
     - [ntype](#ntype)
     - [calculation](#calculation)
+    - [socket\_driver](#socket_driver)
     - [esolver\_type](#esolver_type)
     - [symmetry](#symmetry)
     - [symmetry\_prec](#symmetry_prec)
@@ -592,6 +593,18 @@
   - test_neighbour: obtain information of neighboring atoms (for LCAO basis only), please specify a positive search_radius manually
 - **Default**: scf
 
+### socket_driver
+
+- **Type**: Boolean
+- **Description**: If set to True, ABACUS keeps the calculation type as scf and receives atomic positions from an external driver through the i-PI socket protocol.
+
+  > Note: Use calculation = scf with socket_driver = True. ABACUS connects to the external i-PI server selected by ABACUS_SOCKET_ADDRESS. If ABACUS_SOCKET_ADDRESS is unset, ABACUS uses localhost:31415. The value can use one of two forms:
+
+  - host:port, for example localhost:31415 or 127.0.0.1:31415, opens a TCP connection to that host and port. Use this when the i-PI server listens on a TCP port.
+  - path:UNIX, for example /tmp/ipi_abacus_si:UNIX, opens a Unix-domain socket at the given filesystem path. The :UNIX suffix tells ABACUS that the preceding value is a local socket path rather than a TCP host name. This form only works on the same machine.
+  When using the ASE AbacusSocketIO interface, this environment variable is set automatically from the port or unixsocket calculator argument.
+- **Default**: False
+
 ### esolver_type
 
 - **Type**: String
@@ -840,7 +853,12 @@
 ### chg_extrap
 
 - **Type**: String
-- **Description**: Charge extrapolation method for MD and relaxation calculations.
+- **Description**: Charge extrapolation method for MD, relaxation, and socket-driven calculations.
+
+  When set to default, ABACUS chooses second-order for md, first-order for
+  relax/cell-relax and socket_driver calculations, and atomic for other calculations. Socket-driven
+  molecular dynamics can explicitly set second-order if the external driver
+  updates structures smoothly enough for second-order extrapolation.
 - **Default**: default
 
 ### nb2d

docs/advanced/interface/ase.md

@@ -103,6 +103,77 @@ In the new implementation, we limit the range of functionalties supported to mai
 
 Please read the examples in `interfaces/ASE_interface/examples/` for more details.
 
+### Socket I/O with ASE
+
+For socket-driven ASE workflows, use the `AbacusSocketIO` calculator. ASE runs the i-PI socket server, while ABACUS keeps `calculation=scf` and is launched with `socket_driver=1` as the client. The protocol is simple: ASE sends atomic positions and cell data to ABACUS; ABACUS evaluates one SCF step for that structure and returns energy, forces, and virial. See the [ASE socket I/O documentation](https://ase-lib.org/ase/calculators/socketio/socketio.html) and the i-PI reference paper, [Ceriotti et al., Comput. Phys. Commun. 185, 1019-1026 (2014)](https://doi.org/10.1016/j.cpc.2013.10.027), for the protocol background.
+
+Build ABACUS as usual before using this interface. PW-only builds work with `basis_type=pw`; LCAO socket calculations require an LCAO-enabled executable. No extra socket library is required.
+
+With CMake, choose the executable according to the basis:
+
+```bash
+cmake -S . -B build-pw -DENABLE_MPI=ON -DENABLE_LCAO=OFF
+cmake --build build-pw --target abacus_pw_para -j
+
+cmake -S . -B build-lcao -DENABLE_MPI=ON -DENABLE_LCAO=ON
+cmake --build build-lcao --target abacus_basic_para -j
+```
+
+With the ABACUS toolchain workflow, build the normal ABACUS executable with LCAO support when `basis_type=lcao` is needed, then pass that executable to `AbacusProfile(command=...)`. The command can include an MPI launcher, for example `mpirun -np 4 /path/to/abacus`; ABACUS rank 0 opens the socket connection and broadcasts the i-PI data to the other ranks internally. On managed clusters, keep scheduler-specific launch options outside the calculator when possible and test the exact launcher command on a compute node.
+
+For PW calculations on CUDA/ROCm with multiple MPI ranks, use a k-point layout compatible with ABACUS' GPU parallelization. In practice, make sure each k-point pool contains one MPI rank; for example, a 4-rank PW GPU socket calculation should use at least four k-points so the default GPU `kpar` adjustment can assign one rank per pool. A one-k-point PW GPU job with several MPI ranks can fail in the PW GPU transform path; reduce the rank count or use a denser k-point mesh such as a smaller `kspacing`.
+
+The ASE interface can be installed from this repository with:
+
+```bash
+cd interfaces/ASE_interface
+pip install .
+```
+
+A minimal socket calculator setup is:
+
+```python
+from ase.optimize import BFGS
+from abacuslite import AbacusProfile, AbacusSocketIO
+
+aprof = AbacusProfile(
+    command="mpirun -np 4 /path/to/abacus",
+    pseudo_dir="/path/to/pseudopotentials",
+    orbital_dir="/path/to/orbitals",
+    omp_num_threads=1,
+)
+
+abacus = AbacusSocketIO(
+    profile=aprof,
+    directory="socketio",
+    unixsocket="abacus_si",
+    pseudopotentials={"Si": "Si_ONCV_PBE-1.0.upf"},
+    basissets={"Si": "Si_gga_8au_100Ry_2s2p1d.orb"},
+    inp={"calculation": "scf", "basis_type": "lcao", "kspacing": 0.1},
+)
+
+with abacus as calc:
+    atoms.calc = calc
+    BFGS(atoms).run(fmax=0.05)
+```
+
+`AbacusSocketIO` sets `socket_driver=1` and `cal_force=1` automatically. It also selects the socket endpoint and passes it to ABACUS through `ABACUS_SOCKET_ADDRESS`, so users normally do not set this environment variable by hand when using abacuslite.
+
+There are two endpoint styles:
+
+- `unixsocket="abacus_si"` uses a local Unix-domain socket. ASE creates and listens on `/tmp/ipi_abacus_si`; abacuslite launches ABACUS with `ABACUS_SOCKET_ADDRESS=/tmp/ipi_abacus_si:UNIX`. The `:UNIX` suffix is part of ABACUS' address syntax and means that `/tmp/ipi_abacus_si` is a filesystem socket path, not a TCP host. This is usually the best choice when ASE and ABACUS run on the same node because it avoids TCP port conflicts.
+- `port=31415` uses a TCP socket. abacuslite launches ABACUS with `ABACUS_SOCKET_ADDRESS=localhost:31415`, meaning host `localhost` and TCP port `31415`. Use this style when the socket server should listen on a TCP port. If ABACUS is launched manually instead of through `AbacusSocketIO`, set `ABACUS_SOCKET_ADDRESS` yourself to the same `host:port` or `path:UNIX` endpoint.
+
+Calling `atoms.get_potential_energy()` is supported, but the ABACUS client still computes forces because the i-PI `GETFORCE` exchange returns energy, forces, and virial as one response.
+
+A socket calculator owns one ABACUS process initialized from one fixed `INPUT`/`STRU` setup. Reuse the same `AbacusSocketIO` instance only for position updates under the same electronic-structure settings and the same cell. Do not change `kpts`, `kspacing`, `nspin`, `basis_type`, `basissets`, pseudopotentials, species, atom count, cell, or other core `INPUT`/`STRU` parameters through an existing socket calculator; create a new `AbacusSocketIO` instance and a new ABACUS client process for those changes. `AbacusSocketIO` rejects cell changes before sending them to ABACUS, and the ABACUS socket driver also checks incoming POSDATA cells against the initial `STRU` cell and exits if they differ.
+
+In socket mode, ABACUS keeps one client process alive. All SCF evaluations produced by the same `AbacusSocketIO` instance are appended to the same `OUT.ABACUS/running_scf.log`, because the ABACUS calculation type remains `scf`. The authoritative per-step energy and force results are returned through the i-PI socket to ASE. Use ASE trajectory and optimizer log files, such as `BFGS(atoms, trajectory="opt.traj", logfile="opt.log")`, when each optimizer or MD step should be saved separately. Treat `running_scf.log` mainly as the ABACUS diagnostic log for the socket client, not as one independent FileIO result per structure.
+
+The i-PI protocol does not transmit element symbols. `AbacusSocketIO` therefore sorts the internal socket atoms with the same first-occurrence species grouping used when writing `STRU`, and maps returned forces back to the original ASE `Atoms` order. This avoids silent force/atom mismatches when structures are read from CIF, extxyz, POSCAR, or other formats whose atom order is not already grouped for ABACUS. Users should not manually reorder atoms for socket I/O; pass the physical ASE `Atoms` object directly to the calculator.
+
+A complete fixed-cell validation and benchmark example is available in `interfaces/ASE_interface/examples/socketio.py`.
+
 ## SPAP Analysis
 
 [SPAP](https://github.com/chuanxun/StructurePrototypeAnalysisPackage) (Structure Prototype Analysis Package) is written by Dr. Chuanxun Su to analyze symmetry and compare similarity of large amount of atomic structures. The coordination characterization function (CCF) is used to 

docs/parameters.yaml

@@ -38,6 +38,19 @@ parameters:
     default_value: scf
     unit: ""
     availability: ""
+  - name: socket_driver
+    category: System variables
+    type: Boolean
+    description: |
+      If set to True, ABACUS keeps the calculation type as scf and receives atomic positions from an external driver through the i-PI socket protocol.
+
+      [NOTE] Use calculation = scf with socket_driver = True. ABACUS connects to the external i-PI server selected by ABACUS_SOCKET_ADDRESS. If ABACUS_SOCKET_ADDRESS is unset, ABACUS uses localhost:31415. The value can use one of two forms:
+      * host:port, for example localhost:31415 or 127.0.0.1:31415, opens a TCP connection to that host and port. Use this when the i-PI server listens on a TCP port.
+      * path:UNIX, for example /tmp/ipi_abacus_si:UNIX, opens a Unix-domain socket at the given filesystem path. The :UNIX suffix tells ABACUS that the preceding value is a local socket path rather than a TCP host name. This form only works on the same machine.
+      When using the ASE AbacusSocketIO interface, this environment variable is set automatically from the port or unixsocket calculator argument.
+    default_value: "False"
+    unit: ""
+    availability: ""
   - name: esolver_type
     category: System variables
     type: String
@@ -329,7 +342,12 @@ parameters:
     category: System variables
     type: String
     description: |
-      Charge extrapolation method for MD and relaxation calculations.
+      Charge extrapolation method for MD, relaxation, and socket-driven calculations.
+
+      When set to default, ABACUS chooses second-order for md, first-order for
+      relax/cell-relax and socket_driver calculations, and atomic for other calculations. Socket-driven
+      molecular dynamics can explicitly set second-order if the external driver
+      updates structures smoothly enough for second-order extrapolation.
     default_value: default
     unit: ""
     availability: ""

interfaces/ASE_interface/README.md

@@ -32,6 +32,7 @@ Please refer to the example scripts in the `examples` folder. Recommended learni
 7. **constraintmd.py** - Constrained molecular dynamics simulation
 8. **metadynamics.py** - Metadynamics simulation
 9. **neb.py** - Nudged Elastic Band (NEB) calculation
+10. **socketio.py** - ASE optimization with the AbacusSocketIO calculator running ABACUS as an i-PI socket client
 
 More usage examples will be provided in future versions.