Servers and Sessions¶
Running a server allows users to connect, view and interact with simulations. In narupatools, a server is called a Session.
How do I…¶
… start a new session?¶
To start a new session, simply create it:
from narupatools.app import Session
session = Session()
This is an empty session - it is not currently showing anything.
… show dynamics through a session?¶
Given some dynamics object, we can instruct the session to broadcast it using show()
session.show(dynamics)
If we already have the dynamics and want to start the server showing it automatically, we can pass it as an argument to Session:
session = Session(dynamics)
If the dynamics is not playing,
… show a frame through a session?¶
Showing Narupa FrameData’s and any object that can be converted to one (such as an MDAnalysis Universe, OpenMM Simulation or ASE Atoms object) is achieved in the same way as showing dynamics, either by calling show() or by passing it to the constructor of the Session.
session.show(frame)
… change what a session is showing?¶
By calling show() with a different object, you can change what a server is showing.
… play, pause or restart what the session is showing?¶
If the current target (the object the session is showing) supports playing and restarting (such as dynamics), this can be called either directly or through the session:
session = Session(dynamics)
# These two do the same action
session.play()
dynamics.play()
# Likewise
session.pause()
dynamics.pause()
session.restart()
dynamics.restart()
… close a session?¶
To ensure cleanup, when finished with a Session you should always call close() when finished:
session.close()
If running in a script and not a notebook, then using the session as a context manager will call close:
with Session(...):
# ...
pass
# When the with block is left, close() is automatically called
… find out the address and port of the session?¶
Especially if you’ve use automatic port selection, you may want to find out what port the server is running on.
# Get the name of the Session, as it will be displayed to clients
session.name
# Get the port of the Session
session.port
# Get the address of the Session
session.address
… choose what port to run on?¶
To choose a port, pass the port argument to the session constructor:
session = Session(port=44222)
By default, the port 38801 is used.
… use a random port?¶
If you don’t care what port is used, you can choose to have a random free port chosen by using port = 0.
… check why my session is broken?¶
When running in notebooks, one of the background threads may crash. Due to how Python works, it won’t automatically print it to the screen.
To check that the session is currently working, you can call health_check(). If everything is fine, nothing will happen. If something broke in the background, it will throw this error so you can see what went wrong.