make available sending control packets

[orbeckst]

Expected behavior

I can use control packets in the IMD protocol through IMDClient methods.

client = IMDClient(host, port, n_atoms=1000)
...

PAUSE

PAUSE to temporarily halt the simulation

# directly pause simulation
# v2: sending PAUSE (not sure how we could ascertain that it actually pauses,
#     given that in v2 PAUSE toggles)
# v3: sending PAUSE
success = client.pause()
if success:
   print("paused simulation")

If it makes sense for the client to report success through a return value then we could implement it although in some cases the only sensible response may be to raise an exception.

RESUME

RESUME to continue running a paused simulation:

# directly resume simulation
# v2: sending PAUSE again (toggle)
# v3: sending RESUME
success = client.resume()

WAIT

WAIT to modify the wait behavior.

# set to blocking: Pause simulation execution and wait until a receiver is 
# connected to resume execution
success = client.wait(blocking=True)

# set to non-blocking: Continue execution, continuously checking on the 
# listening socket for a receiver attempting to connect
success = client.wait(blocking=False)

DISCONNECT

DISCONNECT to indicate that the simulation engine should close the connected socket.

I am not 100% sure if this signal should be exposed and users should instead always use IMDClient.stop() because it may leave IMDClient in an incomplete state. However, if we want to give full control to the power user then

success = client.disconnect()

may do the job.

KILL

KILL to terminate the simulation.

success = client.kill()

Like DISCONNECT, there's a risk of leaving imdclient in a poor state.

TRANSMISSION RATE (TRATE)

TRANSMISSION_RATE to change the frame interval for sending data. 1 means "every integrator step", <1 means "reset to default of the MD engine", ">1" meanse every that many steps.

success = client.transmission_rate(5)    # set to every 5 steps
success = client.transmission_rate(0)    # set to default (or -1, -2, ...)
success = client.transmission_rate(None) # allow None for 0, -1, ...

Raise TypeError if value exceeds signed int32 max.

Actual behavior

• The IMDClient docs only document IMDClient.stop()
• DISCONNECT is wrapped by stop()
• other packets such PAUSE, RESUME, WAIT are only available in the actual _producer as underscore methods and not in the IMDClient.
• KILL does not exist
• TRANSMISSION_RATE does not exist

Suggested Changes

[orbeckst]

Note that some of the logger messages such as

imdclient/imdclient/IMDClient.py

Lines 656 to 659 in 73d54b7

	def _pause(self):
	logger.debug(
	"IMDProducer: Pausing simulation because buffer is almost full"
	)

would need to be changed because at the moment they describe the situation when the control command is issued inside imdclient during frame processing. When a user explicitly issues the command then these messages are confusing.

Some commands such as DISCONNECT and KILL may need to be wrapped so that sufficient clean up in IMDClient itself can be done.

[orbeckst]

IMDClient will have different commands depending on it being v2 or v3 under the hood. For commands like resume() that only exist in v3 we can raise a RuntimeError or just not expose them as attributes.

Perhaps it would keep the namespace clean to collect all commands under a pseudo-attribute such as "send" or "command" to get nice syntax such as

client.send.pause()
client.send.transmission_rate(10)

[orbeckst]

See also issues #122 (IMD_WAIT) and #121 (KILL, IOERROR).