Client¶

class narupatools.app.client.Client(**kwargs: Any)¶

An extension of NarupaImdClient with more features.

These features include:

Callback for when a frame is received.
Exposing the shared state through the narupatools shared state API.
Fixing a bug where the client connects to frames before it has defined the needed variables to store them.

Inheritance

Methods

`__init__`	Create a client.
`attempt_update_multiplayer_locks`	Attempt to acquire and/or free a number of locks on the shared state. :param 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. :return: True if the desired locks were acquired, and False otherwise.
`attempt_update_multiplayer_state`	Attempt to make a single atomic change to the shared state, blocking until a response is received. :param 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. :return: True if the server accepted our change, and False otherwise.
`autoconnect`	Autoconnect to the first available server discovered that at least produces frames.
`clear_selections`	Remove all selections in the system
`close`	Closes the connection with the server.
`connect`	Connects the client to all services for which addresses are provided.
`connect_imd`	Connects the client to the given interactive molecular dynamics server, allowing it to start publishing interactions.
`connect_multiplayer`	Connects the client to the given multiplayer server.
`connect_to_server`	Connect to a server.
`connect_to_session`	Connect to a session.
`connect_to_single_server`	Connect to a single Narupa server running all services on the same port.
`connect_to_single_server_multiple_ports`	Connect to a collection of Narupa servers running at the same address but potentially different ports.
`connect_trajectory`	Connects the client to the given trajectory server, and begin receiving frames.
`create_selection`	Create a particle selection with the given name.
`get_selection`	Get the selection with the given selection id, throwing a KeyError if it is not present.
`get_shared_value`	Attempts to retrieve the value for the given key in the multiplayer shared value store.
`remove_selection`	Delete the given selection
`remove_shared_value`	Attempts to remove the given key on the multiplayer shared value store.
`run_command`	Runs a command on the trajectory service, multiplayer service or imd service as appropriate.
`run_imd_command`	Runs a command on the iMD service.
`run_multiplayer_command`	Runs a command on the multiplayer service.
`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`	Runs a command on the trajectory service.
`set_shared_value`	Attempts to set the given key/value pair on the multiplayer shared value store.
`start_interaction`	Start an interaction with the IMD server.
`stop_interaction`	Stops the interaction identified with the given interaction_id on the server.
`subscribe_multiplayer`	Subscribe to all multiplayer state updates.
`subscribe_to_all_frames`	Request all the frames from the server.
`subscribe_to_frames`	Request the latest frames at a given time interval.
`update_available_commands`	Fetches an updated set of available commands from the services this client is connected to.
`update_interaction`	Updates the interaction identified with the given interaction_id on the server with parameters from the given interaction.
`update_selection`	Applies changes to the given selection to the shared key store.
`wait_until_first_frame`	Wait until the first frame is received from the server.

__init__(**kwargs: Any) → None ¶

Create a client.

Parameters: kwargs – Keyword arguments to pass to NarupaImdClient.

attempt_update_multiplayer_locks(update: Dict[str, Optional[float]]) → bool ¶

Attempt to acquire and/or free a number of locks on the shared state. :param 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: narupa.utilities.change_buffers.DictionaryChange) → bool ¶

Attempt to make a single atomic change to the shared state, blocking until a response is received. :param 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: Optional[str] = None, discovery_port: Optional[int] = None, name: Optional[str] = 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: Optional[Tuple[str, int]] = None, imd_address: Optional[Tuple[str, int]] = None, multiplayer_address: Optional[Tuple[str, int]] = 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_server(*, address: Optional[str] = None, port: Optional[int] = None) → Generator[narupatools.app.client.Client, None, None]¶

Connect to a server.

Parameters

address – Address to connect to, or None to use the default.
port – Port to connect to, or None to use the default.

Yield

Client connected to all available services on the server at the given destination.

classmethod connect_to_session(session: narupatools.app.session.Session, /) → Generator[narupatools.app.client.Client, None, None]¶

Connect to a session.

Parameters: session – Session that is running.
Yields: Client connected to the given session.

classmethod connect_to_single_server(address: Optional[str] = None, port: Optional[int] = None)¶

Connect to a single Narupa 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 Narupa 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: Optional[Iterable[int]] = None) → narupa.app.selection.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.

get_selection(selection_id: str) → narupa.app.selection.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

remove_selection(selection: narupa.app.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

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_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_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.

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: Optional[narupa.imd.particle_interaction.ParticleInteraction] = 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.

subscribe_to_frames(interval: float = 0.03333333333333333)¶

Request the latest frames at a given time interval.

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

This requests for the server to send the latest available frame at a given framerate expressed with the interval of time between two consecutive frames. This requested interval is the a minimum interval: if the frames are produced slower, then they will be sent as fast as possible.

This is usefull for applications that do not need all the frames but only the latest available ones.

Warning

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

Parameters: interval – Minimum time, in seconds, between two consecutive frames.

update_available_commands() → MutableMapping[str, narupa.command.command_info.CommandInfo]¶

Fetches an updated set of available commands from the services this client is connected to.

Returns: A collection of CommandInfo, detailing the commands available.

If the same command name is available on multiple services, the nested nature of the returned ChainMap will enable the user to determine the correct one to call.

update_interaction(interaction_id, interaction: narupa.imd.particle_interaction.ParticleInteraction)¶

Updates the interaction identified with the given interaction_id on the server with parameters from the given interaction.

Parameters

interaction_id – The unique id of the interaction to be updated.
interaction – The :class: ParticleInteraction providing new parameters for the interaction.

Raises

ValueError, if the there is no IMD connection available, or if invalid parameters are passed to the server.

Raises

KeyError – if the given interaction ID does not exist.

update_selection(selection: narupa.app.selection.RenderingSelection)¶

Applies changes to the given selection to the shared key store.

Parameters: selection – The selection to update.

wait_until_first_frame(check_interval=0.01, timeout=1)¶

Wait until the first frame is received from the server.

Parameters

check_interval – Interval at which to check if a frame has been received.
timeout – Timeout after which to stop waiting for a frame.

Returns

The first FrameData received.

Raises

Exception – if no frame is received.

Attributes

`all_frames`
`are_frames_subscribed`	Returns True if the client is subscribed to frames with either `subscribe_to_all_frames()` or `subscribe_to_frames()`.
`current_frame`	A copy of the current state of the trajectory, formed by collating all received frames.
`first_frame`	The first received trajectory frame, if any.
`frames`	The most recently received frames up to the storage limit specified by max_frames.
`interactions`	The dictionary of current interactions received by this client.
`latest_frame`	The trajectory frame most recently received, if any.
`latest_multiplayer_values`	The latest state of the multiplayer shared key/value store.
`on_frame_received`	Event triggered when a frame is received by the client.
`root_selection`	Get the root selection, creating it if it does not exist yet.
`selections`	Get all selections which are stored in the shared key store.
`shared_state`	Shared state of the client.

all_frames¶

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

current_frame¶

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.

first_frame¶

The first received trajectory frame, if any.

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

frames¶

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

Returns: Sequence of frames.

interactions¶: The dictionary of current interactions received by this client. :return: Dictionary of active interactions, keyed by interaction ID identifying who is performing the interactions.

latest_frame¶

The trajectory frame most recently received, if any.

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

latest_multiplayer_values¶

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

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

on_frame_received¶: Event triggered when a frame is received by the client.

root_selection¶

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

Returns: The selection representing the root selection of the system

selections¶

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

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

shared_state¶: Shared state of the client.

narupatools

Navigation

Related Topics

Client¶