AgentSkillsCN

mxl-hpc-slurm

当用户需要在 SLURM/HPC 环境中运行 MaxwellLink，包括依赖作业模式，以及稳健的套接字主机/端口交接时，应使用此技能。

SKILL.md
--- frontmatter
name: mxl-hpc-slurm
description: This skill should be used when users need to run MaxwellLink in SLURM/HPC environments, including dependent job patterns and robust socket host/port handoff.

SLURM/HPC workflows

Choose socket transport

  • •Use UNIX sockets only when the EM solver and driver run on the same node.
  • •Use TCP sockets when the EM solver and drivers run on different nodes.

Use the two-step SLURM pattern (main job + driver job)

  • •Make the main job start the hub and write host and port to a shared text file (e.g. tcp_host_port_info.txt).
  • •Make the driver job wait until the file exists, read the file, then run mxl_driver --model ... --address "$HOST" --port "$PORT" ....
  • •Submit the driver job with --dependency=after:<main_job_id> so it starts only after the hub is scheduled and begins running.

Prefer robust host/port discovery

  • •Recommended (most robust on locked-down clusters): bind the hub to all interfaces (host="" / 0.0.0.0), pick a free port locally, and write a reachable hostname via MXL_HOST or hostname -f.
  • •Convenience helper: maxwelllink.sockets.get_available_host_port(localhost=False, save_to_file=...) can pick a port and write the file for you.
    • •If cluster outbound networking is blocked, this helper may fail to discover an external IP; fall back to the "most robust" pattern above.

Multi-molecule / multi-driver patterns

  • •For N molecules, launch N driver processes (hub assigns molecule IDs automatically as clients connect).
  • •Common HPC pattern: start N-1 drivers in the background and keep one in the foreground so the job keeps running.
  • •For heavy drivers (Psi4 RT-TDDFT / RT-Ehrenfest), prefer num_threads=1 per driver when launching many drivers in one job.

LAMMPS as the "driver job"

  • •When coupling to LAMMPS (fix mxl), treat the LAMMPS job as the client: read host/port, patch the LAMMPS input (or pass host/port directly), then srun lmp_mxl -in in.lmp.

Prefer templates

  • •Template: skills/mxl-project-scaffold/assets/templates/slurm-meep-tls-tcp

References

  • •Recipes: skills/mxl-hpc-slurm/references/slurm_recipes.md
  • •Docs: docs/source/usage.rst (distributed run sections)