Skip to content

Single Point Engine Mode (MPI Interface)

When launched with the command-line option --UseMPI=3, TeraChem enters single point engine mode, in which it acts as a long-running server for single-point energy and gradient calculations. This is useful for embedding TeraChem inside an external driver that repeatedly requests energies/gradients for evolving geometries.

Server/client communication uses MPI named ports through paired MPI_Comm_accept / MPI_Comm_connect calls. The client calls MPI_Comm_connect() after the server has started, looking up the service name given by the --MPIPort option to connect to the correct port.

Initial settings

Once connected, TeraChem expects an initial settings buffer: a text buffer in the format of a TeraChem input file. For consistency with the other MPI interfaces:

  • each keyword and value must be padded to a length of 128 characters, and
  • the buffer must be terminated with the line end — all lowercase, no indentation.

After processing the settings, TeraChem enters standby mode and responds to requests. Every request begins with an array of 8 C integers, whose first element is a tag identifying the request type.

Request: single point calculation (tag = 1)

The 8 integers carry:

# Meaning
1 Number of atoms
2 Molecular charge
3 Spin multiplicity
4 Closed-shell wavefunction if non-zero
5 Restricted wavefunction if non-zero
6 Compute and report the gradient if non-zero; otherwise energy only
7 Compute and report the Mayer bond-order matrix if non-zero
8 Initial-guess control: 0 = reuse MO coefficients from the last run; 1 = regenerate the guess with the specified method; 2 = MO coefficients will be transmitted over MPI. If the previous/received coefficients are inconsistent with the current molecule (e.g. different molecule or basis set), TeraChem falls back to a fresh GenerateGuess().

Then the client sends, over MPI:

  1. a character buffer of size 2*natoms containing the atom symbols, each padded to width 2; followed by
  2. a double-precision array of size 3*natoms with the Cartesian coordinates.

TeraChem performs the calculation and replies with a single double-precision number, the energy. If the SCF did not converge, this message carries a non-zero tag and nothing further is sent. On success the tag is zero and TeraChem then sends, in order:

  • atomic charges — double * natoms
  • spin densities — double * natoms
  • dipole moment — double * 4 (first 3 components are the vector, the 4th is its norm)
  • if requested, the gradient — double * 3*natoms
  • if requested, the Mayer bond-order matrix — double * natoms*natoms

Request: change settings (tag = 2)

TeraChem expects a character buffer containing a new input file, in the same format as the initial settings buffer. No memory of previous settings is retained — any keyword not present in the new buffer reverts to its default, exactly as if running a standalone calculation with that buffer as the input. TeraChem sends no response to this request.

Request: disconnect (tag = 0)

The MPI connection is terminated and the server shuts down.

Warning

After sending the termination signal, the client must also call MPI_Comm_disconnect() so the server can finalize MPI and shut down cleanly.