Interprocess Communication for Discover

Click to jump down this page to a topic:

discoverIO
discoverIPC

discoverIO

Purpose

The discoverIO command is used by the ipc command primarily to read/write coordinates, energies, gradients, stresses and Hessians from/to a Tcl file handle into/out of the System database and internal energy structures. When the -autoEnergy option is used with the ipc init operation, a BTCL restraint procedure that uses the discoverIO command is automatically created. This is used to exchange energy calculation results between an external program and the Discover program's energy evaluation code.

However, the discoverIO command may also be used directly by BTCL experts to implement specialized data exchanges between Discover and other programs running on the network during Discover energy evaluations.

Syntax

discoverIO -read tclFileHandle ?-options args?
discoverIO -write tclFileHandle ?-options args?

Any number of -read tclFileHandle ?-options args? groups may be used on the same discoverIO command to specify several data exchanges in succession.

tclFileHandle: A Tcl file handle referring to a file/pipe/socket. This argument must immediately follow the -read or -write option. The target file must be readable (for -read) or writable (for -write).

Subsequent options and arguments further specify the data to be exchanged as follows:

-atom spec: spec is a string or the name of an object containing references to atoms of interest.

The -atom option allows specification of a collection of atoms to be operated on for -data elements (see below) for which this applies (Coord and Gradient). The -atom option affects the previous -read or -write option prior to the appearance of the -atom option (call this previous operation ``P''). Additionally, the -atom option affects the operation before ``P'' (call this ``NP'') if:

operation NP exists, and
an -atom option was not specified already for operation NP, and
operation NP is the opposite of operation P in a -read/-write sense

For example, suppose the variables outFH and inFH are Tcl file handles to open channels for writing and reading, respectively. Then, the command:

discoverIO -write $outFH -read $inFH -atom "*:*:Atom;*"

writes data (Coord) for all atoms and then reads data (e.g., Gradient) for all atoms. That is, the -atom option refers to the previous -read and also to the -write before that.

-data list

Allows specification of the logical collections of items to be transferred. Currently recognized list elements are:

Coord
Cartesian2Fractional
Fractional2Cartesian
CellParameters
Energy
Gradient
Stress
Hessian

If no -data option is specified and the operation is -write, the default -data corresponds to -data Coord if the system is nonperiodic and to -data {Cartesian2Fractional Fractional2Cartesian Coord} if the system is periodic.

If Coord is requested and no atom specification is given, then the following coordinates are exchanged:

  Nonperiodic:     all coordinates
  Periodic: write: all P1 atoms
  Periodic:  read: all assymetric atoms

If Gradient is requested and no atom specification is given, then the following gradients are exchanged:

  Nonperiodic:     all gradients
  Periodic: write: all asymmetric atom gradients
  Periodic:  read: all P1 atom gradients

CellParameters sends a,b,c,alpha,beta,gamma

Cartesian2Fractional and Fractional2Cartesian send over transformation matrices as 9 real*8 values ordered as: 1,1 1,2 1,3 2,1 2,2, etc.

-expect ?tag?

The -expect option applies only to the immediately previous -read or -write.

If -expect option is used, then discoverIO either sends a string-type IPC frame (if the -expect applies to a -write) containing the list of items the client should expect next; or, if the -expect applies to a -read, discoverIO expects a string IPC frame containing the names of the data items that the Discover program should expect in forthcoming IPC frames.

The optional tag argument specifies a message entry for the IPC frame containing the expected data. This tag is used on -write and expected on -read. If no tag is provided, the tag Expect is sent or expected. If the tag must have a leading hyphen, use two hyphens (--).

Outgoing Expect frames always generate a flush.

-request ?tag?

The -request option applies only to the immediately prior -read. However, it sends its information out via the previous -write Tcl file handle.

The -request option is similar to the -expect option in that it helps the Discover program and clients negotiate what information is to be exchanged. If -request is specified, then before waiting for the data specified in the -read, Discover sends a Request message with strings indicating what information is desired from the client. If no -expect option applies to the -read in question, then Discover waits for the information requested. If an -expect does apply to this read, then before waiting for the data, Discover waits for an Expect message from the client. The contents of the Expect message from the client may modify what data Discover attempts to read next.

The optional tag argument specifies a message entry for the IPC frame containing the request data. If no tag is provided, the tag Request is sent. If the tag must have a leading hyphen, use two hyphens (--).

Request frames always generate a flush.

-energyName name

Specifies that a new child of the Energy database ``External'' energy row be created (in the table Values, column Name). The incoming energy components are made children of this new name, instead of direct children of the ``External'' row.

If -energyName is absent, then a new child of the ``External'' row is created using the name of the tclFileHandle specified on the associated -read action.

For example, if -energyName MOPAC appears, then the Energy database will look like:

External         ...
  MOPAC          ...

All IPC frames with the message ``Energy'' will be summed into the MOPAC row. Furthermore, if ``Energy'' IPC frames are returned from the remote application with a second word in the message, then these distinguished energies are made children of the energy row specified by -energyName. For example, suppose -energyName MOPAC appears (as before) and that the application sends back two energy IPC frames with messages:

"Energy firstPart"
"Energy secondPart"

Now, the Energy database is set up as follows:

External         ...
  MOPAC          ...
    firstPart    ...
    secondPart   ...

When the energies are printed, ``firstPart'' and ``secondPart'' are summed into ``MOPAC'', which will in turn be summed with any other rows at that level of the hierarchy, into ``External''. Note that, because the ``MOPAC'' row now has children, no energy IPC frames should arrive with only an ``Energy'' message; if this happens, the energies stored into ``MOPAC'' are overwritten when the children (``firstPart'' and ``secondPart'') are summed into ``MOPAC''.

-energyName applies to the previous read action.

Tcl Results

If the -read option is specified, the Tcl result is a list of the message records from each input IPC frame.

If the -write option is specified, the Tcl result is a list of the message records sent for each output IPC frame.

discoverIpc

Purpose

Used primarily by the ipc command to perform low-level interprocess communication operations. This command may be used directly by BTCL experts to implement specialized communications between the Discover program and other programs running on the network.

Syntax

discoverIpc operation ?args?

The possible operations are as follows:

eval

Purpose

Reads BTCL commands from tclFileHandle and evaluates them in the global scope.

Syntax

discoverIpc eval ?-nowait? tclFileHandle

?-nowait?: Option to not wait if no input is available. The default is to block until input is available.
tclFileHandle: A Tcl file handle referring to a file/pipe. The target file must be readable.

poll

Purpose

Determine if the file descriptor associated with the Tcl file handle has readable data after an optional timeout.

Syntax

discoverIpc poll tclFileHandle ?timeoutMilliseconds?

tclFileHandle: A Tcl file handle referring to a file/pipe. The target file must be readable.
timeoutMilliseconds: Optional amount of time to wait for input to become available. If absent, or 0, do not wait.

connect

Purpose

Connect to a remote host/process and return a Tcl file handle opened for reading and writing on the connection.

Syntax

discoverIpc connect hostName portName

hostName: Host where remote process is listening for a connection. An empty hostName means to use ``localhost''.
portName: Port number or service name of remote process.

The result is an ordered list of two Tcl file handles. The first handle is to be used for reading on the connection; the second handle is to be used for writing on the connection.

listen

Purpose

Establish a listening socket on a specified or system-chosen port.

Syntax

discoverIpc listen ?portNumber?

portNumber: Port to which listen socket should be bound.

The result is a list of length 2. The first element is a Tcl file handle connected to the listen socket. This can be used with the poll command to see if a connection on that socket is being requested. The second element is a copy of the port number assigned for listening. This will be the same as the specified port if the bind was successful.

accept

Purpose

Accept a connection request on a listening socket specified by the Tcl file handle. If the connection is successfully accepted and created, a new Tcl file handle is created. The Tcl file handle for the read/write connection is returned.

Syntax

discoverIpc accept tclFileHandle ?hostname?

tclFileHandle: File handle on which to try the accept.
hostname: Optional remote host description. If present, this argument requires that the peer have the host description/name specified.

The result is an ordered list of two Tcl file handles. The first handle is to be used for reading on the connection; the second handle is to be used for writing on the connection.

Main access page

Advanced-Use access.

IPC Main Page