Overview

Getting started with tios involves three steps:

1. Install the software
2. Register for an account on a tios hub
3. Configure the software

Then you are ready to go.

Installation.

Tios can be installed most easily by using pip:

#!irc
% pip install tios --user

Out of the box, tios provides you with guest (read-only) access to data via the tios evaluation hub. This means you can use commands like tios-ls and tios-collect to look at some example simulations, but you cannot launch your own new simulations. For this, you need to read on.

Registration.

Before you can use tios for your own simulations, you need to obtain an account on a tios hub. You have three options:

1. If you know of an existing tios hub you can use, contact the administrator and they will provide you with the necessary settings for the next step.

2. For testing purposes, for example if you want to run the example jobs (see this section), you can use the evaluation hub. You can apply for an account on this here.

3. While you can use the evaluation server to launch simulations, you will ultimately need your own server for your own group/institution if you intend to run large-scale jobs. For a guide as to how to build and activate your own hub (very easy if you have Docker!), see here.

Configuration.

Before you use tios for the first time on any resource, you must configure it on each using tios-config, and the configuration details (items in <...> below) you received when you registered.

#!irc
% tios-config
Database URL (): <mongobd_url>
Database Port (): <mongodb_port>
Username: (): <username>
Password (): <password>
%

Run your first tios simulation.

Once you have installed and configured tios, and have GROMACS or NAMD installed and/or loaded (for example with module load or similar, depending on your system), you can run your first example tios job. For this, you need to download and unzip the file examples.tgz that you can find in the "Downloads" section of the tios repository.

1. Launch a job.

Gromacs users cd into the examples/Gromacs folder you have downloaded and unpacked, and use tios-submit to submit the test simulation.

#!irc
% cd $HOME/tios-1.1.0/examples/Gromacs
% tios-submit -t 'My first TIOS simulation' gmx mdrun -deffnm bpti
Simulation <tios_id> registered

#!irc
% tios-restart <tios_id>

NAMD users cd into the examples/NAMD folder you have downloaded and unpacked, and use tios-submit to submit the test simulation.

#!irc
% cd $HOME/tios-1.1.0/examples/NAMD
% tios-submit -t 'My first TIOS simulation' namd2 ubq_wb.conf
Simulation <tios_id> registered

#!irc
% tios-restart <tios_id>

Note: the first time you use tios it might take 20-30 seconds to start up.

2 Check the job.

Now open a separate terminal window. Use tios-ls to see the status of your job:

#!irc
% tios-ls
<tios_id> My first TIOS simulation            4.00 <username>   Running   Apr 02 13:55

3 Collect trajectory data.

Let's collect some trajectory data using tios-collect. Once you have a few frames, hit ctrl-C.

#!irc
% tios-collect <tios_id> -o my_sim.xtc -p my_sim.pdb -v
Frames so far: 7 Time point (ps): 8.00 status: Running

4 Stop the tios job.

If you look back in your first terminal window, or do tios-ls again in the second, you will see that when you quit data collection, that did not terminate the simulation - it's still running.

You can connect again using tios-collect and download another chunk of trajectory data. But notice that any frames produced between the time you stopped the first collection and started the second are lost - that is because tios is streaming data, not storing it.

Let's stop the simulation:

#!irc
% tios-stop <tios_id>
% tios-ls
<tios_id> My first TIOS simulation          14.00 <username>   Stopped   Apr 02 13:55

5 Restart the tios job.

In the first terminal window, restart the tios job:

#!irc
% tios-restart <tios_id>
job starting...

6 Stop and restart the tios job while collecting data.

In the first terminal window, use crtl-C to stop the tios job. In the second window you should see that your tios-collect has hung, but not quit. In the first window use tios-restart to get the simulation going again, and then after a short while you should see that data collection starts again in the second window.

7 Next steps.

Install tios on a second machine you have access to, and see how the commands above work just as well when the two windows are on different machines.