Wiki
Clone wikitios / Getting Started
Overview
Getting started with tios involves three steps:
- Install the software
- Register for an account on a tios hub
- 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:
-
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.
-
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.
-
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> %
tios-ls -a
and you should see a list of all simulations currently in the tios database.
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
tios-submit
only submits an MD simulation to tios, but the job does not actually start. To get the job running, you then need to run tios-restart
(for more details about tios commands, please see the User Guide):
#!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
my_sim.pdb
and my_sim.xtc
into VMD or similar to check your data.
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...
tios-ls
to see the job is now running again. Start a second trajectory data collection using tios-collect
, and leave this running as you go to the next step:
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.
Updated