Starting a visualisation session

1. Open up a browser and navigate to http://balena.bath.ac.uk and log in with your University username and password. 
2. You will be presented with the Bright Cluster Manager userportal, from here select the VISUALISATION tab.

3. The default settings should be sufficient. The table below describes the various options available. 

   Option	Default	Description
   Walltime	1 hour	Set the time of the Visualisation session. By default the visualisation service uses the free service, making the maximum session time 6 hours.
   Shared	no	Will allow selected users to access the VNC session shared = all selected users to have full access viewonly = selected users to only view your session
   Allowed users	none selected	Select the users you would like to share your VNC session with. You can select multiple users by holding down the Ctrl button.
   Nodes	1	Recommend leaving this set to 1. Unless needed for MPI based visualisation workloads.
   Cores	1	Recommend leaving this set to 1. The visualisation nodes are fully shared to allow multiple users and do not restrict the size of jobs being run on the node.
   CUDA offload devices	0	Will reserve a dedicated GPU card. This is only required if you are running an intensive visualisation.
   Resolution	current desktop window size	Set the size of the resolution. By default it will use your current window size.
   Bandwidth	auto	Auto default setting should be sufficient, but if you experience responsiveness issues then try adjusting the bandwidth setting. Lowering the bandwidth will reduce the quality of the pixel rendering to increase the responsiveness of the interactions.
   Only Java Applet	no	To only allow visualisation access via the Java Applet.
   Extra parameters		Additional parameters to pass to sbatch, see SBATCH options. To run a visualisation job under a premium project use "--account=project-code --time=8:00:00".

4. To launch a visualisation session click on the blue 'Submit Job' button.  This will submit a job to the scheduler to start a VNC server on the visualisation nodes.  
5. It takes a few seconds for the connection to be setup, and the browser will auto-refresh the page. Once ready you will see the job appear and green buttons underneath the VNC Session title. 
6. From here you will have two options to launch the VNC session, these are described in the next two sections. 

Launching a JavaApplet VNC session

Using the Java Applet VNC session will launch a Java version of the VNCclient from the Balena servers.  This is particularly useful if you do not have a VNC client on your desktop; however the performance of the visualisation will be slightly lower. 

To launch the Java Applet VNC session:

1. Click on the green 'Java Applet' button, this will open up a new browser window. 
2. You may get prompted by Java to run TightVNC Viewer, click on Run.
3. After a couple of seconds you will have a Linux Desktop displayed in the window. 

Launching a Local VNC Client session

This session opens up a direct connection to the VNC service on the Visualisation nodes.  You will need a VNC client/viewer installed on your desktop to be able to connect.  The recommended version is TurboVNC, but you can also use TigerVNC or TightVNC, which have similar 3D performance capabilities, although other VNC clients will also work.  If you do not have Administrator/root access on your local machine to install the VNC client, then you can use the VNC viewers available under the download section on the userportal home page.

To launch the Local VNC Client session:

1. Click on the green 'Local VNC Client' button. This will open up a new window with the session connection details for the VNC client.  The passwords are single use One Time Passwords (OTP) and will expire when an attempt has been made to login. 
2. These connection details can be copied directly to the VNC client or at the bottom of the window there is a 'Launch local VNC' button. 
3. In firefox, if this is the first time your browser tries to use VNC files you will be asked what you would like to do with it, see window image below.  Select 'Open With' and browse to and select your vncview executable and request Firefox to remember these settings.  
   .
4. After clicking 'OK' this will open the VNC client using your session connection details and you should see a Linux desktop.

Ending a visualisation session

To end a visualisation session:

1. Log out of the desktop session by clicking on 'Log Out' under the System drop-down menu at the top of the screen. 
2. Cancel the visualisation session in the userportal, by clicking on the red 'Delete' button under the Manage Job section. 

Visualisation 3D performance with VirtualGL

The below instructions use the VMD visualisation tools to load up example data, and will allow you to interact with the molecule.

1. Launch a terminal session, either by:
   1. Clicking on the Terminal Icon on the top menu bar
   2. Right-clicking on the desktop and select 'Open in Terminal'
2. `module list` should show that you have the esm module loaded; this is done be default on the visualisation nodes. 
3. Load the VMD software environment: `module load vmd`
4. The command `vglrun` is needed before any graphical command to capture the OpenGL instructions and process them on the local graphics card.
5. To run the VMD tools use the command: vglrun vmd /beegfs/scratch/group/training/vis/vmd-example.pdb
6. Screen shot of VMD
7. To take this a step further, the nvidia-smi tool will show the utilisation of the GPU card whilst using the visualisation tools.
   1. module load cuda/toolkit
   2. nvidia-smi

When I try to connect from a Linux OS using the Java Applet the window is all greyed out.

Some of the settings in your ~/.java directory will need resetting or cache cleared out. To clean out the cache use `javaws -viewer`, the cache settings can be found from the Settings button under the General tab.

Failing that, the next simplest method would be to remove the ~/.java directory.

'vglrun: No such file or directory'

The environment path of vglrun is setup when the esm module is loaded. If `module list` does not show esm in the list, then you will need to load it with `module load esm`. If could be that in your ~/.bashrc or ~/.bash_profile you might have purged the modules.