Analyzing simulations with LOOS

Other documents will cover issues specific to particular packages (e.g. NAMD, gromacs). The purpose of this document is to give you an idea how LOOS expects you to think about your data, and to clarify our notation and terminology.

To figure out what tools are available, go to the main tool documentation. To learn more about how a particular tool works, run the command toolname --fullhelp; this will give you a discussion of the options, details about the algorithms, suggested workflows, and possible pitfalls, as well as references to the literature where appropriate. To just get a list of available options, you can just run the tool with no command line options.

Getting started

This document assumes you've already built LOOS. If not, look at INSTALL.md in the top-level directory for instructions, including the commands you'll need to install dependencies from your package manager. Before running, you'll need to get your environment set up, by sourcing either setup.sh or setup.csh, depending on which shell you're using. The file will be in the top-level directory of LOOS if your working from a source tree, or in the top of the install directory (not the bin/ directory) if you're working from an installation.

Key Terms

• system file: This is the file that specifies the system's contents. This could be a PSF (CHARMM or NAMD), parmtop (Amber), gro (gromacs), xyz (Tinker), or a PDB file. LOOS is totally agnostic to which kind of file you use, except for the fact that the file formats have different information. So, if the tool you're using requires partial charges, you need to use a file format that contains that information (e.g. PSF). GRO is one of the less informative file formats, so we provide a tool (gmxdump2pdb.pl) to generate a PSF for your gromacs system. Since PSFs contain connectivity information, this PSF is also useful for correctly rendering bonds of coarse-grained models in VMD. However, this PSF cannot be used for running a simulation, since it only contains the information LOOS needs. LOOS tools deduce the file types based on the file extensions, but this autodetection can be overridden by the --modeltype option if your naming scheme is something we didn't anticipate.

• trajectory file: This is the trajectory. Currently, we support DCD, XTC, Amber mdcrd, Amber netcdf, Tinker ARC, and concatenated PDB files. The trajectory format does not have to "match" the system file, so you can easily mix and match at your convenience (e.g. use a PSF with XTC trajectories). As long as the systems match (same number of atoms in the same order), LOOS doesn't care. As with the system file, the autodetection can be overridden, this time with the --trajtype flag. Note: if scons doesn't find the netcdf libraries at build time, netcdf format will not be supported.

• selection string: a string (usually specified on the command line) that lets you pick out atoms for analysis based on metadata (e.g. atom name). Note: geometric selection (e.g. position or distance) is not supported. Details of the selection syntax and working examples are available in the main documentation. Depending on what shell you're using, you may have to do some additional quoting to make it work. We suggest embedding selection strings in single quotes -- ' -- to protect subsequent double quotes from the shell, but you may also need to put in some additional backslash characters -- \ -- in order to get everything to work. This is particularly an issue with RNA, where many of the atom names have single quotes in them.

Getting help

Almost every tool has some amount of help built in. If you run the command with either the -h or --help flag (or with no arguments at all), it will list the command line arguments available to it. For more detail, run the command with the argument --fullhelp. This will give you a more detailed description of the tool's intended use, the meaning of the various arguments, details about the algorithms employed (when this is not obvious), example command lines. It may also contain suggested workflows, alternative tools, and often-made mistakes.