SocketNWChemPot Class Reference

A potential that gets forces and energy from an NWChem server via a socket. More...

#include <SocketNWChemPot.h>

Inheritance diagram for SocketNWChemPot:

Public Member Functions
	SocketNWChemPot (const Parameters &p)
	~SocketNWChemPot () override
void	write_nwchem_template (const std::string &filename, long N, const std::vector< std::string > &atom_symbols)
	Generates an NWChem input file (.nwi) configured to connect to this server.
void	force (long N, const double *R, const int *atomicNrs, double *F, double *U, double *variance, const double *box) override
	The method called to compute forces and energy.
bool	requiresIsolatedMoleculeLayout () const noexcept override
	NWChem socket SCF does not support PBC (#188).
bool	isThreadSafe () const noexcept override
	Whether this potential's force() can be called from multiple threads on the SAME instance.
Public Member Functions inherited from eonc::Potential
	Potential (PotType a_ptype)
	Potential (PotType a_ptype, const Parameters &)
	Potential (const Parameters &a_params)
virtual	~Potential ()
std::tuple< double, AtomMatrix >	get_ef (const AtomMatrix &pos, const VectorXi &atmnrs, const Matrix3d &box)
PotType	getType () const
virtual bool	isSurrogate () const noexcept
	Whether this is a surrogate (GP) potential.
virtual bool	isSharedInstanceThreadSafe () const noexcept
	Conservative gate for sharing one Potential instance across threads.
virtual bool	needsPerImageInstance () const noexcept
	Whether NEB should create separate Potential instances per image for true parallel force evaluation.
virtual bool	supportsBatchEvaluation () const noexcept
	Whether this potential supports batched evaluation of N systems in a single call.
virtual void	forceBatch (long nSystems, long nAtoms, const double *const *positions, const int *const *atomicNrs, double *const *forces, double *energies, double *variances, const double *const *boxes)
	Evaluate forces for N systems in a single call.

Private Member Functions
void	setup_server ()
void	accept_connection ()
void	send_header (const char *msg)
void	recv_header (char *buffer)
void	send_exact (const void *buffer, size_t n_bytes)
void	recv_exact (void *buffer, size_t n_bytes)

Private Attributes
bool	unix_socket_mode
std::string	server_address
std::string	unix_socket_basename
std::string	nwchem_settings
int	port
int	mem_in_gb
bool	make_template_input
int	listen_fd
int	conn_fd
bool	is_connected

Static Private Attributes
static constexpr int	MSG_LEN = 12
static constexpr double	BOHR_IN_ANGSTROM = 0.529177210903
static constexpr double	HARTREE_IN_EV = 27.211386245988

Additional Inherited Members
Public Attributes inherited from eonc::Potential
std::atomic< size_t >	forceCallCounter
Protected Attributes inherited from eonc::Potential
PotType	ptype

Detailed Description

A potential that gets forces and energy from an NWChem server via a socket.

Implements the i-PI socket protocol to communicate with an NWChem executable that has been launched in server mode (e.g., using task scf optimize and the driver socket directive). This class manages a persistent connection to NWChem. Supports both TCP/IP and UNIX domain sockets.

Definition at line 27 of file SocketNWChemPot.h.

Constructor & Destructor Documentation

SocketNWChemPot()

SocketNWChemPot::SocketNWChemPot ( const Parameters & p )

explicit

Definition at line 32 of file SocketNWChemPot.cpp.

    : Potential(PotType::SocketNWChem, p),
      listen_fd(-1),
      conn_fd(-1),
      is_connected(false) {
 
  unix_socket_mode = p.socket_nwchem_options.unix_socket_mode;
  nwchem_settings = p.socket_nwchem_options.nwchem_settings;
  mem_in_gb = p.socket_nwchem_options.mem_in_gb;
  make_template_input = p.socket_nwchem_options.make_template_input;
 
  if (unix_socket_mode) {
    unix_socket_basename = p.socket_nwchem_options.unix_socket_path;
    // NWChem's Fortran i-PI driver truncates the socket name to ~30 chars.
    // The full path is /tmp/ipi_<basename>, so basename must be short.
    server_address = "/tmp/ipi_" + unix_socket_basename;
    if (server_address.size() > 30) {
      std::cerr << "ERROR: UNIX socket path '" << server_address << "' is "
                << server_address.size()
                << " characters, which exceeds NWChem's ~30 character limit.\n"
                << "NWChem will silently truncate it, causing a connection "
                   "failure.\n"
                << "Shorten unix_socket_path (currently '"
                << unix_socket_basename << "') to at most " << (30 - 9)
                << " characters.\n";
      throw std::runtime_error(
          "unix_socket_path too long for NWChem (max ~21 chars, got " +
          std::to_string(unix_socket_basename.size()) + ")");
    }
    port = -1;
    std::cout << "SocketNWChemPot: Initializing in UNIX mode." << std::endl;
    std::cout << "Listening on socket file: " << server_address << std::endl;
  } else {
    server_address = p.socket_nwchem_options.host;
    port = p.socket_nwchem_options.port;
    std::cout << "SocketNWChemPot: Initializing in TCP mode." << std::endl;
    std::cout << "Listening on: " << server_address << ":" << port << std::endl;
  }
 
  setup_server();
}

~SocketNWChemPot()

SocketNWChemPot::~SocketNWChemPot ( )

override

Definition at line 74 of file SocketNWChemPot.cpp.

                                  {
  if (is_connected) {
    std::cout << "Closing connection to NWChem client..." << std::endl;
    try {
      send_header("EXIT");
    } catch (...) {
      // Ignore errors during shutdown
    }
  }
  if (conn_fd >= 0)
    ::close(conn_fd);
  if (listen_fd >= 0)
    ::close(listen_fd);
  if (unix_socket_mode) {
    ::unlink(server_address.c_str());
  }
}

Member Function Documentation

accept_connection()

void SocketNWChemPot::accept_connection ( )

private

Definition at line 295 of file SocketNWChemPot.cpp.

                                        {
  conn_fd = accept(listen_fd, nullptr, nullptr);
  if (conn_fd < 0) {
    perror("accept() failed");
    throw std::runtime_error("Failed to accept client connection.");
  }
  is_connected = true;
}

force()

void SocketNWChemPot::force ( long N, const double * R, const int * atomicNrs, double * F, double * U, double * variance, const double * box )

overridevirtual

The method called to compute forces and energy.

This method implements the full i-PI handshake for a single geometry:

1. Checks the client status, handling the NEEDINIT state if necessary.
2. Sends the new atomic positions and cell (POSDATA).
3. Polls until the calculation is complete (HAVEDATA).
4. Retrieves the results (GETFORCE).

Parameters

N	The number of atoms.
R	Pointer to the beginning of the position array [x1, y1, z1, ...].
atomicNrs	Pointer to the array of atomic numbers.
F	Pointer to the beginning of the force array to be populated.
U	Pointer to the potential energy value to be set.
variance	Not used by this potential.
box	Pointer to the 3x3 simulation box matrix.

Implements eonc::Potential.

Definition at line 131 of file SocketNWChemPot.cpp.

                                               {
  if (!is_connected) {
    std::vector<std::string> symbols;
    symbols.reserve(N);
    for (long i = 0; i < N; ++i) {
      symbols.emplace_back(atomicNumber2symbol(atomicNrs[i]));
    }
    if (make_template_input) {
      write_nwchem_template("nwchem_socket.nwi", N, symbols);
    }
 
    std::cout << "Waiting for NWChem client connection..." << std::endl;
    accept_connection();
    std::cout << "NWChem client connected." << std::endl;
 
    // 1. eOn acts as the server: after accepting the NWChem client connection,
    // eOn sends "STATUS" to the client to query its status.
    char status_buffer[MSG_LEN + 1] = {0};
    send_header("STATUS");
 
    // 2. eOn (acting as server) then waits for NWChem (the client) to respond
    // with "READY".
    recv_header(status_buffer);
    if (std::string(status_buffer) != "READY") {
      throw std::runtime_error(
          "Handshake failed: NWChem client not READY. It sent: " +
          std::string(status_buffer));
    }
    std::cout << "NWChem server is connected and READY." << std::endl;
  }
 
  // Check status for this specific force call
  char status_buffer[MSG_LEN + 1] = {0};
  send_header("STATUS");
  recv_header(status_buffer);
 
  if (std::string(status_buffer) == "NEEDINIT") {
    send_header("INIT");
    // Send dummy INIT payload (bead index, number of bytes in extra string)
    int32_t init_payload[] = {0, 1}; // bead_index=0, nbytes=1
    char dummy_byte = 0;
    send_exact(&init_payload, sizeof(init_payload));
    send_exact(&dummy_byte,
               sizeof(dummy_byte)); // No extra string (just a null terminator)
    send_header("STATUS");
    recv_header(status_buffer);
  }
 
  if (std::string(status_buffer) != "READY") {
    throw std::runtime_error("NWChem server not ready for new positions!");
  }
 
  // Convert positions to Bohr
  std::vector<double> pos_bohr(N * 3);
  for (size_t i = 0; i < pos_bohr.size(); ++i) {
    pos_bohr[i] = R[i] / BOHR_IN_ANGSTROM;
  }
 
  // Per i-PI spec, cell and inverse cell must be sent. NWChem does not use
  // this information for non-periodic calculations, so we send an identity
  // matrix as a safe, non-transforming placeholder to conform to the protocol.
  double invcell_T[9] = {1, 0, 0, 0, 1, 0, 0, 0, 1};
  double cell_T[9] = {1, 0, 0, 0, 1, 0, 0, 0, 1};
 
  send_header("POSDATA");
  int32_t nat = N;
  send_exact(cell_T, sizeof(cell_T));
  send_exact(invcell_T, sizeof(invcell_T));
  send_exact(&nat, sizeof(nat));
  send_exact(pos_bohr.data(), pos_bohr.size() * sizeof(double));
 
  // Poll for results
  while (true) {
    send_header("STATUS");
    recv_header(status_buffer);
    if (std::string(status_buffer) == "HAVEDATA") {
      break;
    }
    // A small sleep to prevent busy-waiting that consumes 100% CPU.
    sleep_for(10ms);
  }
 
  // Request and receive results ---
  send_header("GETFORCE");
  recv_header(status_buffer);
  if (std::string(status_buffer) != "FORCEREADY") {
    throw std::runtime_error("Expected FORCEREADY, got " +
                             std::string(status_buffer));
  }
 
  // Unpack the results payload.
  double energy_ha;
  int32_t nat_back;
  std::vector<double> forces_ha_bohr(N * 3);
  double virial_ha[9];
  int32_t extra_len;
 
  recv_exact(&energy_ha, sizeof(energy_ha));
  recv_exact(&nat_back, sizeof(nat_back));
  if (nat_back != N)
    throw std::runtime_error("Atom count mismatch from NWChem");
  recv_exact(forces_ha_bohr.data(), forces_ha_bohr.size() * sizeof(double));
  recv_exact(&virial_ha, sizeof(virial_ha));
  recv_exact(&extra_len, sizeof(extra_len));
  if (extra_len > 0) {
    std::vector<char> extra_buf(extra_len);
    recv_exact(extra_buf.data(), extra_len);
  }
 
  // Convert results back to eOn units (eV and Angstrom)
  *U = energy_ha * HARTREE_IN_EV;
  for (int i = 0; i < N * 3; ++i) {
    F[i] = forces_ha_bohr[i] * (HARTREE_IN_EV / BOHR_IN_ANGSTROM);
  }
  *variance = 0.0;
}

isThreadSafe()

bool SocketNWChemPot::isThreadSafe ( ) const

inlinenodiscardoverridevirtualnoexcept

Whether this potential's force() can be called from multiple threads on the SAME instance.

Python-based potentials return false. Potentials with internal mutex (MetatomicPotential) return true but serialize internally – use needsPerImageInstance() to check if separate instances would enable true parallelism.

Reimplemented from eonc::Potential.

Definition at line 66 of file SocketNWChemPot.h.

{ return false; }

recv_exact()

void SocketNWChemPot::recv_exact ( void * buffer, size_t n_bytes )

private

Definition at line 331 of file SocketNWChemPot.cpp.

                                                             {
  size_t recvd = 0;
  while (recvd < n_bytes) {
    ssize_t n = ::recv(conn_fd, (char *)buffer + recvd, n_bytes - recvd, 0);
    if (n <= 0) {
      throw std::runtime_error(
          "recv_exact failed: connection closed or error.");
    }
    recvd += n;
  }
}

recv_header()

void SocketNWChemPot::recv_header ( char * buffer )

private

Definition at line 310 of file SocketNWChemPot.cpp.

                                              {
  recv_exact(buffer, MSG_LEN);
  buffer[MSG_LEN] = '\0'; // Null-terminate
  // Trim trailing whitespace
  for (int i = MSG_LEN - 1; i >= 0 && isspace((unsigned char)buffer[i]); --i) {
    buffer[i] = '\0';
  }
}

requiresIsolatedMoleculeLayout()

bool SocketNWChemPot::requiresIsolatedMoleculeLayout ( ) const

inlinenodiscardoverridevirtualnoexcept

NWChem socket SCF does not support PBC (#188).

Reimplemented from eonc::Potential.

Definition at line 63 of file SocketNWChemPot.h.

                                                                              {
    return true;
  }

send_exact()

void SocketNWChemPot::send_exact ( const void * buffer, size_t n_bytes )

private

Definition at line 319 of file SocketNWChemPot.cpp.

                                                                   {
  size_t sent = 0;
  while (sent < n_bytes) {
    ssize_t n = ::send(conn_fd, (const char *)buffer + sent, n_bytes - sent, 0);
    if (n <= 0) {
      throw std::runtime_error(
          "send_exact failed: connection closed or error.");
    }
    sent += n;
  }
}

send_header()

void SocketNWChemPot::send_header ( const char * msg )

private

Definition at line 304 of file SocketNWChemPot.cpp.

                                                 {
  char buffer[MSG_LEN] = {0};
  strncpy(buffer, msg, MSG_LEN);
  send_exact(buffer, MSG_LEN);
}

setup_server()

void SocketNWChemPot::setup_server ( )

private

Definition at line 254 of file SocketNWChemPot.cpp.

                                   {
  int domain = unix_socket_mode ? AF_UNIX : AF_INET;
  listen_fd = socket(domain, SOCK_STREAM, 0);
  if (listen_fd < 0) {
    throw std::runtime_error("Failed to create socket.");
  }
 
  if (unix_socket_mode) {
    ::unlink(server_address.c_str()); // Remove stale socket file if it exists
    sockaddr_un sock_addr{};
    sock_addr.sun_family = AF_UNIX;
    strncpy(sock_addr.sun_path, server_address.c_str(),
            sizeof(sock_addr.sun_path) - 1);
 
    socklen_t addr_len =
        sizeof(sock_addr.sun_family) + strlen(sock_addr.sun_path);
    if (::bind(listen_fd, (struct sockaddr *)&sock_addr, addr_len) < 0) {
      perror("UNIX bind failed");
      throw std::runtime_error("Failed to bind UNIX socket.");
    }
  } else { // TCP Mode
    int opt = 1;
    setsockopt(listen_fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
    sockaddr_in sock_addr{};
    sock_addr.sin_family = AF_INET;
    sock_addr.sin_addr.s_addr = inet_addr(server_address.c_str());
    sock_addr.sin_port = htons(port);
 
    if (::bind(listen_fd, (struct sockaddr *)&sock_addr, sizeof(sock_addr)) <
        0) {
      perror("TCP bind failed");
      throw std::runtime_error("Failed to bind TCP socket.");
    }
  }
 
  if (::listen(listen_fd, 1) < 0) {
    perror("listen() failed");
    throw std::runtime_error("Socket listen() failed.");
  }
}

write_nwchem_template()

void SocketNWChemPot::write_nwchem_template	(	const std::string &	filename,
		long	N,
		const std::vector< std::string > &	atom_symbols )

Generates an NWChem input file (.nwi) configured to connect to this server.

Parameters

filename	The path to the output file (e.g., "nwchem_socket.nwi").
N	The number of atoms.
atom_symbols	A vector of atom symbols (e.g., {"O", "H", "H"}).

Definition at line 96 of file SocketNWChemPot.cpp.

                                              {
  std::ofstream outfile(filename);
  if (!outfile.is_open()) {
    throw std::runtime_error("Could not open file to write NWChem template: " +
                             filename);
  }
 
  outfile << "start nwchem_socket_job\n";
  outfile << "title \"NWChem Server for eOn\"\n\n";
  outfile << "memory " << mem_in_gb << " gb\n\n";
  outfile << "geometry units bohr noautosym nocenter noautoz\n";
  // This geometry block is only a template for memory allocation.
  // The atom types and count are what matter.
  for (long i = 0; i < N; ++i) {
    outfile << "  " << atom_symbols[i] << "  0.0 0.0 " << static_cast<double>(i)
            << "\n";
  }
  outfile << "end\n\n";
  outfile << "include " << nwchem_settings << "\n\n";
  outfile << "driver\n";
  if (unix_socket_mode) {
    // For the NWChem input, we provide only the basename. NWChem adds the
    // prefix.
    outfile << "  socket unix " << unix_socket_basename << "\n";
  } else {
    outfile << "  socket ipi_client " << server_address << ":" << port << "\n";
  }
  outfile << "end\n\n";
  outfile << "task scf optimize\n";
 
  outfile.close();
}

Member Data Documentation

BOHR_IN_ANGSTROM

double SocketNWChemPot::BOHR_IN_ANGSTROM = 0.529177210903

staticconstexprprivate

Definition at line 98 of file SocketNWChemPot.h.

conn_fd

int SocketNWChemPot::conn_fd

private

Definition at line 92 of file SocketNWChemPot.h.

HARTREE_IN_EV

double SocketNWChemPot::HARTREE_IN_EV = 27.211386245988

staticconstexprprivate

Definition at line 99 of file SocketNWChemPot.h.

is_connected

bool SocketNWChemPot::is_connected

private

Definition at line 93 of file SocketNWChemPot.h.

listen_fd

int SocketNWChemPot::listen_fd

private

Definition at line 91 of file SocketNWChemPot.h.

make_template_input

bool SocketNWChemPot::make_template_input

private

Definition at line 88 of file SocketNWChemPot.h.

mem_in_gb

int SocketNWChemPot::mem_in_gb

private

Definition at line 86 of file SocketNWChemPot.h.

MSG_LEN

int SocketNWChemPot::MSG_LEN = 12

staticconstexprprivate

Definition at line 96 of file SocketNWChemPot.h.

nwchem_settings

std::string SocketNWChemPot::nwchem_settings

private

Definition at line 85 of file SocketNWChemPot.h.

port

int SocketNWChemPot::port

private

Definition at line 86 of file SocketNWChemPot.h.

server_address

std::string SocketNWChemPot::server_address

private

Definition at line 81 of file SocketNWChemPot.h.

unix_socket_basename

std::string SocketNWChemPot::unix_socket_basename

private

Definition at line 83 of file SocketNWChemPot.h.

unix_socket_mode

bool SocketNWChemPot::unix_socket_mode

private

Definition at line 79 of file SocketNWChemPot.h.

---

The documentation for this class was generated from the following files:

• /home/runner/work/eOn/eOn/include/eon/potentials/SocketNWChem/SocketNWChemPot.h
• /home/runner/work/eOn/eOn/client/potentials/SocketNWChem/SocketNWChemPot.cpp