Fix socket docs generation and launcher parsing

Author: jianrui geng

docs/advanced/input_files/input-main.md

@@ -596,14 +596,12 @@
 ### socket_driver
 
 - **Type**: Boolean
-- **Availability**: *calculation==scf*
 - **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
 

docs/advanced/interface/ase.md

@@ -119,7 +119,11 @@ 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. The ASE interface can be installed from this repository with:
+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

interfaces/ASE_interface/abacuslite/core.py

@@ -125,11 +125,14 @@ def __init__(self,
 
     @staticmethod
     def parse_version(stdout) -> str:
-        # up to the ABACUS version v3.9.0.17, the run of command
-        # `abacus --version` would returns the information organized
-        # in the following way:
-        # ABACUS version v3.9.0.17
-        return re.match(r'ABACUS version (\S+)', stdout).group(1)
+        # MPI launchers may add informational lines before ABACUS output.
+        match = re.search(r'ABACUS version (\S+)', stdout or '')
+        if match is None:
+            raise RuntimeError(
+                'Could not parse ABACUS version from command output. '
+                'Expected a line like "ABACUS version vX.Y.Z".'
+            )
+        return match.group(1)
 
     def get_calculator_command(self, inputfile) -> List[str]:
         # because ABACUS run in the folder where there are INPUT files, so the
@@ -778,6 +781,14 @@ def test_socketio_rejects_cell_changes(self):
         with self.assertRaisesRegex(PropertyNotImplementedError, 'fixed-cell'):
             calc._check_fixed_cell(changed)
 
+    def test_parse_version_allows_launcher_noise(self):
+        stdout = 'launcher info\nABACUS version v3.11.0-beta6\n'
+        self.assertEqual(AbacusProfile.parse_version(stdout), 'v3.11.0-beta6')
+
+    def test_parse_version_rejects_missing_version(self):
+        with self.assertRaisesRegex(RuntimeError, 'ABACUS version'):
+            AbacusProfile.parse_version('launcher failed before abacus started')
+
     def test_calculator_results(self):
         from ase.build.bulk import bulk
         silicon = bulk('Si', crystalstructure='diamond', a=5.43)