nanover.app.client module

Module containing a basic interactive molecular dynamics client that receives frames and can publish interactions.

class nanover.app.client.NanoverImdClient(*, trajectory_address: Tuple[str, int] | None = None, imd_address: Tuple[str, int] | None = None, multiplayer_address: Tuple[str, int] | None = None, max_frames=50, all_frames: bool | None = None)

Bases: object

Interactive molecular dynamics client that receives frames, create selections, and join the multiplayer shared state.

Parameters:

trajectory_address – Address and port of the trajectory service.
imd_address – Address and port of the iMD service.
multiplayer_address – Address and port of the multiplayer service.
max_frames – Maximum number of frames to store in a buffer, if not storing all frames.

All addresses are optional, so one can, for example, just connect to a trajectory service to passively receive frames.

The NanoverImdClient.autoconnect() and NanoverImdClient.connect_to_single_server() methods provide shorthands for common server setups.

Inspecting a Frame

The NanoVer Imd client can be used to inspect frames received from a nanover.trajectory.FrameServer, which can be useful for analysis.

Creating Selections for Rendering

One of the main uses of the client is to create selections that control how a group of particles will be visualised and interacted with in other clients (e.g., the VR client):

# Connect to the multiplayer
client.subscribe_multiplayer()
# Create a selection called 'Selection' which selects particles with indices 0-4
selection = client.create_selection("Selection", [0, 1, 2, 3, 4])

Selections are created and updated based on lists of particle indices. Tools such as MDAnalysis or MDTraj <http://mdtraj.org/>_ are very good at extracting indices of particles based on a human readable command.

With a selection in hand, the way in which it is rendered and interacted with can be changed and transmitted to other clients (i.e. VR) using the modify context:

# Change how the selection is rendered and interacted with.
with selection.modify():
    selection.renderer = {
            'color': 'IndianRed',
            'scale': 0.1,
            'render': 'liquorice'
        }
    selection.velocity_reset = True  # Reset the velocities after interacting.
    selection.interaction_method = 'group'  # Interact with the selection as a group.

property all_frames

property are_frames_subscribed: Returns True if the client is subscribed to frames with either subscribe_to_all_frames() or subscribe_to_frames().

attempt_update_multiplayer_locks(update: Dict[str, float | None]) → bool

Attempt to acquire and/or free a number of locks on the shared state.

Parameters:: update – A dictionary of keys to either a duration in seconds to attempt to acquire or renew a lock, or None to indicate the lock should be released if held.
Returns:: True if the desired locks were acquired, and False otherwise.

attempt_update_multiplayer_state(update: DictionaryChange) → bool

Attempt to make a single atomic change to the shared state, blocking until a response is received.

Parameters:: update – A single change to make to the shared state that will either be made in full, or ignored if some of the keys are locked by another user.
Returns:: True if the server accepted our change, and False otherwise.

classmethod autoconnect(search_time=2.0, discovery_address: str | None = None, discovery_port: int | None = None, name: str | None = None)

Autoconnect to the first available server discovered that at least produces frames.

Parameters:

search_time – Time, in seconds, to search for.
discovery_address – IP address to search on.
discovery_port – Port upon which to listen for discovery messages.
name – If supplied, only servers with this name will be used.

Returns:

Instantiation of an iMD client connected to whatever is available at the first

clear_selections(): Remove all selections in the system

close(clear_frames=True)

Closes the connection with the server.

Parameters:: clear_frames – Whether to clear the frames received by the client, or keep them.

connect(*, trajectory_address: Tuple[str, int] | None = None, imd_address: Tuple[str, int] | None = None, multiplayer_address: Tuple[str, int] | None = None): Connects the client to all services for which addresses are provided.

connect_imd(address: Tuple[str, int])

Connects the client to the given interactive molecular dynamics server, allowing it to start publishing interactions.

Parameters:

address – The address and port of the IMD server.
port – The port of the IMD server.

connect_multiplayer(address: Tuple[str, int])

Connects the client to the given multiplayer server.

Parameters:: address – The address and port of the multiplayer server.

classmethod connect_to_single_server(address: str | None = None, port: int | None = None)

Connect to a single NanoVer server running all services on the same port.

Parameters:

address – Address of the server.
port – Server port

Returns:

Instantiation of a client connected to all available services on the server at the given destination.

classmethod connect_to_single_server_multiple_ports(address: str, trajectory_port: int, imd_port: int, multiplayer_port: int)

Connect to a collection of NanoVer servers running at the same address but potentially different ports.

Parameters:

address – Address of the server.
multiplayer_port – The port at which multiplayer is running.
trajectory_port – The port at which the trajectory service is running.
imd_port – The port at which the iMD service is running.

Returns:

Instantiation of a client connected to all available services on the server at the given destination.

connect_trajectory(address: Tuple[str, int])

Connects the client to the given trajectory server, and begin receiving frames.

Parameters:: address – The address and port of the trajectory server.

create_selection(name: str, particle_ids: Iterable[int] | None = None) → RenderingSelection

Create a particle selection with the given name.

Parameters:

name – The user-friendly name of the selection.
particle_ids – The indices of the particles to include in the selection.

Returns:

The selection that was created.

property current_frame: FrameData

A copy of the current state of the trajectory, formed by collating all received frames.

Returns:: FrameData, which is empty if none have been received.

property first_frame: FrameData | None

The first received trajectory frame, if any.

Returns:: The first frame received by this trajectory, or None.

property frames: Sequence[FrameData]

The most recently received frames up to the storage limit specified by max_frames.

Returns:: Sequence of frames.

get_selection(selection_id: str) → RenderingSelection

Get the selection with the given selection id, throwing a KeyError if it is not present. For the root selection, use the root_selection property.

Parameters:: selection_id – The id of the selection
Returns:: The selection if it is present

get_shared_value(key)

Attempts to retrieve the value for the given key in the multiplayer shared value store.

Parameters:: key – The key that identifies the value
Returns:: The value stored in the dictionary
Raises:: grpc._channel._Rendezvous – When not connected to a multiplayer service

property interactions: Dict[str, ParticleInteraction]: The dictionary of current interactions received by this client. :return: Dictionary of active interactions, keyed by interaction ID identifying who is performing the interactions.

property latest_frame: FrameData | None

The trajectory frame most recently received, if any.

Returns:: FrameData, or None if none has been received.

property latest_multiplayer_values: Dict[str, object]

The latest state of the multiplayer shared key/value store.

Returns:: Dictionary of the current state of multiplayer shared key/value store.

remove_selection(selection: RenderingSelection): Delete the given selection

remove_shared_value(key: str) → bool

Attempts to remove the given key on the multiplayer shared value store.

Raises:: grpc._channel._Rendezvous – When not connected to a multiplayer service

property root_selection: RenderingSelection

Get the root selection, creating it if it does not exist yet.

Returns:: The selection representing the root selection of the system

run_command(name, **args)

Runs a command on the trajectory service, multiplayer service or imd service as appropriate.

Parameters:

name – Name of the command to run
args – Dictionary of arguments to run with the command.

Returns:

Results of the command, if any.

run_imd_command(name: str, **args) → Dict[str, object]

Runs a command on the iMD service.

Parameters:

name – Name of the command to run
args – Dictionary of arguments to run with the command.

Returns:

Results of the command, if any.

run_list() → List[str]: Retrieves an ordered list of the available simulations for the load command.

run_load(index: int): Sends a request for the trajectory service to switch to a particular simulation.

run_multiplayer_command(name: str, **args)

Runs a command on the multiplayer service.

Parameters:

name – Name of the command to run.
args – Dictionary of arguments to run with the command.

Returns:

Results of the command, if any.

run_next(): Sends a request for the trajectory service to switch to the next simulation.

run_pause(): Sends a request to pause the simulation to the trajectory service.

run_play(): Sends a request to start playing the trajectory to the trajectory service.

run_reset(): Sends a request to reset the simulation to the trajectory service.

run_step(): Sends a request to take one step to the trajectory service.

run_trajectory_command(name: str, **args) → Dict[str, object]

Runs a command on the trajectory service.

Parameters:

name – Name of the command to run
args – Dictionary of arguments to run with the command.

Returns:

Results of the command, if any.

property selections: Iterable[RenderingSelection]

Get all selections which are stored in the shared key store.

Returns:: An iterable of all the selections stored in the shared key store.

set_shared_value(key, value) → bool

Attempts to set the given key/value pair on the multiplayer shared value store.

Parameters:

key – The key that identifies the value to be stored.
value – The new value to store.

Returns:

True if successful, False otherwise.

Raises:

grpc._channel._Rendezvous – When not connected to a multiplayer service

start_interaction(interaction: ParticleInteraction | None = None) → str

Start an interaction with the IMD server.

Parameters:: interaction – An optional :class: ParticleInteraction with which to begin.
Returns:: The unique interaction ID of this interaction, which can be used to update the interaction with update_interaction().
Raises:: ValueError, if the there is no IMD connection available.

stop_interaction(interaction_id) → bool

Stops the interaction identified with the given interaction_id on the server. This method blocks until the server returns a reply indicating that the interaction has stopped.

Parameters:

interaction_id – The unique interaction ID, created with start_interaction(), that identifies the interaction to stop.

Returns:

An InteractionEndReply, which is an empty message indicating successful termination of the interaction.

Raises:

ValueError – if the there is no IMD connection available, or if invalid parameters are passed to the server.
KeyError – if the given interaction ID does not exist.

subscribe_multiplayer(interval=0.03333333333333333)

Subscribe to all multiplayer state updates.

Parameters:: interval – Subscription interval for state updates.
Raises:: grpc._channel._Rendezvous – When not connected to a multiplayer service

subscribe_to_all_frames()

Request all the frames from the server.

This makes the frames available with the frames, current_frame, latest_frames, and first_frame attributes.

All the frames produced by the frame server are sent from the time of the subscription get received by the client. Note that, depending on the server set up, this may not be all the frames generated by the MD engine. Subscribing to all frames is usefull for some applications such as saving a trajectory or analyses, however it may get behind the server if the frames are not received and treated as fast as they are sent.

Warning

A client can subscribe to frames only ones and cannot change how it subscribes.