Usage guide

Local usage

Within a local environment, for short-time usage or testing, the MDsrv can be started from a directory providing access to files within this and underlying directories by the following command:

> mdsrv

positional options: [structure] [trajectory]
additional options: [--script SCRIPT] [--configure CONFIGURE]
                    [--deltaTime DELTATIME] [--timeOffset TIMEOFFSET]
                    [--host HOST] [--port PORT]

The command "mdsrv" itself starts the MDsrv including the NGL viewer with access to files within the starting directory and underneath, exclusively. By executing the MDsrv with a structure (e.g. a .gro or .pdb file) and trajectory (e.g. a .gro, .xtc or .dcd file) including their path which must be within the current working directory or a sub directory, both will be loaded into the MD viewer.

> mdsrv 3DQB.gro sims/3DQB.xtc       <-- working
> mdsrv 3DQB.gro ../../3DQB.xtc      <-- not working (parent directory not accessible)

A structure file is mandatory for loading a trajectory. Trajectories and structures within the current working directory can still be loaded afterwards via the GUI.

MDsrv uses .ngl/.js script files to load structures and trajectories with specific settings (e.g representations, colors, selections or background scheme), orientations or self-coded functions. The file is further explained below and example code can be found in the scripting section and downloaded here.

mdsrv --script session.ngl
mdsrv --script session.js

The .ngl file is written in JavaScript and contains commands to execute predefined settings and functions. A sample .ngl file shows additional options like functions and basic loading commands. This is recommended if simulation sessions should be shared. The location of this file should be within an accessible directory and can then be loaded via the URL (e.g. http://localhost/mdsrv.html?load=file://MDsrv/example.ngl, where MDsrv is the directory defined within the .cfg file). Further information and example code can be found in the scripting section and all used examples within this documentation can be found here.

To include other directories and security settings, the configuration file (.cfg, explained in the configuration section) can be loaded accordingly:

mdsrv --cfg my.cfg
mdsrv --configure my.cfg

System wide/web-server usage

To maintain MDsrv as a system wide web-server, follow the deployment instructions. Besides apache, any web server with wsgi support can be used (not tested).

We provide examples of the usage of the MDsrv as a web-server in combination with the NGL viewer. An embedded example is used in this documentation. By utilizing a web-server, collaborators, reviewers or students can easily inspect simulations visually on-the-fly.

GUI usage

To get a detailed guide, how to use and change the GUI, go here.

Loading simulations

Simulations can be loaded in several different ways into the NGL GUI. The main focus of the MDsrv is to make deposited (remote) simulations available to others. Still, we provide an option for viewers (meaning those who have received a MDsrv session) to load their local trajectories, e.g. for comparison with the deposited simulations data into the session. Go here to find more about how to load a trajectory.