loos.dox

/*!

\mainpage Lightweight Object-Oriented Structure library (LOOS)


Copyright © 2008-2019, Tod D. Romo, Alan Grossfield\n
Department of Biochemistry and Biophysics\n
School of Medicine & Dentistry, University of Rochester\n


\image html gplv3.png

<hr>
<h2>Important News for LOOS 3.0</h2>

LOOS 3.0 and higher require python 3.x.  The install instructions in INSTALL.md have been updated accordingly.  If your OS does not support python 3.x, you can try installing LOOS inside a Conda environment.

For questions or problems using LOOS, the best approach is to open an issue on our <a href="https://github.com/GrossfieldLab/loos">GitHub page</a>.  Alternatively, you can email us at loos.maintainer@gmail.com.

We are phasing out the mailing lists as support mechanisms; if you were previously a member, we suggest following LOOS on GitHub as a better strategy to keep up to date with us.

<hr>

<h2>Quick Links</h2>
      - <a href="https://github.com/GrossfieldLab/loos">Clone LOOS from GitHub</a>
      - <a href="https://github.com/GrossfieldLab/loos/wiki">Online tutorials and documentation</a>
      -  <a href="http://membrane.urmc.rochester.edu/sites/default/files/loos.pdf">Download a tutorial (pdf) on using LOOS</a>
      -  Ask the developers a question at loos.maintainer@gmail.com or by opening an issue on GitHub.
      - \subpage building "Building LOOS"
      - \subpage tools "Tools included with LOOS"
      - \subpage selections "Selection Language"
      - \subpage common_options "Common Options for Tools"
      - \subpage formats "Supported File Formats"
      - \subpage citing "Citing LOOS in published work"
      - \subpage new_pyloos "What's new in PyLOOS"
      - \subpage exceptions "Exceptions in LOOS and PyLOOS"
      - \subpage changes "Changes"
      - \subpage faq "FAQ"
          - \ref faq_pyloos "FAQ for PyLOOS"
      - Posters and presentations on LOOS
          - <a href="http://membrane.urmc.rochester.edu/sites/default/files/posters_bps_2019/loos-2019.pdf">2019 Biophysical Society Poster</a>
          - <a href="http://membrane.urmc.rochester.edu/sites/default/files/posters_bps_2016/bps2016_tromo.pdf">2016 Biophysical Society Poster</a>

\section intro Introduction

Welcome to LOOS, a product of the Grossfield Lab at the University of
Rochester Medical School and the Department of Biochemistry and Biophysics.
Our goal in developing LOOS is to make it easier to analyze molecular
dynamics simulations.  LOOS is a code library for developing new analysis
applications, designed to simplify the common tasks (reading structure and
trajectory files, selecting atoms, computing geometric quantities) found in
almost every application.  Moreover, it is distributed with a
number of useful standalone tools, ranging from simple things like radial
distribution functions and radii of gyration to principal component
analysis to sophisticated methods for analyzing statistical errors.

LOOS has several major features:
    - It transparently reads the native file formats for most major
      biomolecular simulation pacakges, including CHARMM, NAMD, gromacs,
      AMBER, and Tinker.
    - It uses an expressive syntax to allow selection of atoms using
      all available metadata (e.g. atom number, residue name, etc).
      For more information see \subpage selections "Selection Language".
    - It allows novel analysis applications to be developed rapidly, with
      minimal programming skill required.  For example, atoms are referred
      to using reference-counted shared pointers, which retain the benefits
      of using pointers (e.g. rapid, lightweight copying) without requiring
      the developer to do manual memory management.
    - It should run on any unix-like environment, and is tested under
      multiple linux versions, Mac OSX, and cygwin.

For assistance using LOOS, to suggest a patch, to request a feature, or simply
to offer positive feedback, email loos.maintainer [AT] gmail.com.  The
latest version of LOOS can be found at our <a href="https://github.com/GrossfieldLab/loos">GitHub page</a>.

We strongly suggest that you also follow LOOS on Github.

\section Applications

Although we primarily view LOOS as a development platform -- a tool for
making tools -- it is distributed with a number of prebuilt applications.
The included tools were developed in the course of research in the
Grossfield lab, but we believe them to be generally useful enough to merit
their inclusion.  Some of the code for these programs is found in the Tools/
directories, while other related programs are grouped together as Packages
(e.g. Packages/Convergence/).

For more information, see the
    \subpage tools "Tools page"

In addition to providing valuable functionality (principal component
analysis, structure alignment, etc), these applications can also be useful
as templates for developing new applications using LOOS.  We have taken a
general design approach of developing relatively simple, single-purpose
tools, as we believe that makes it easier to quickly add functionality and
experiment with analysis methods, without the overhead of integrating with
a larger package.  Many (if not most) analysis involve the same sequence of
steps: read a description of the system (e.g. a PDB, PSF, parmtop, or gro
file), select which atoms will be examined, and then, for each frame in a
trajectory, compute some geometric quantity using the coodinates (e.g.
their centroid or moments of inertia).




\section Bugs
There are none...only features.  So don't worry about them!
Either mail us directly (loos.maintainer [AT] gmail.com) or raise an issue on GitHub.

\section future Future Plans

<ul>
    <li> More extensive manual, including developer's tutorial
    <li> More applications
</ul>

<hr>

\section license License


<I>LOOS (Lightweight Object-Oriented Structure library)</I>\n
Copyright &copy; 2008-2019, Tod D. Romo, Alan Grossfield\n
Department of Biochemistry and Biophysics\n
School of Medicine & Dentistry, University of Rochester\n

This package (LOOS) is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation under version 3 of the License.

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

\image html grossfield_logo.jpg


*/


/*! \page citing Citing LOOS in published work
If you use LOOS in your work, please reference the following
publications:

Romo, T.D., Grossfield, A. "LOOS: An extensible platform for the
structural analysis of simulations."  31st Annual International
Conference of the IEEE EMBS (2009): 2332-2335

Romo, T. D., Leioatts, N. and Grossfield, A., "Lightweight Object Oriented Structure Analysis: Tools for building tools to analyze molecular dynamics simulations", J. Comput. Chem. (2014): 2305-2318

*/

/*! \page formats Supported File Formats

LOOS reads the native file formats for most major biomolecular simulation packages.

<H3> Structure Files </H3>
<table align="center" border="1" style="width:80%">
<tr align="center"><th>Package</th> <th>File Suffix</th>   <th>Notes</th></tr>
<tr align="center">  <td> Amber </td>  <td> prmtop </td> <td> </td> </tr>
<tr align="center"> <td>  CHARMM/NAMD </td> <td> pdb </td>    <td> </td> </tr>
<tr align="center">  <td> CHARMM/NAMD </td>  <td> psf </td>  <td> </td>  </tr>
<tr align="center">  <td> CHARMM </td>  <td> crd </td> <td> </td> </tr>
<tr align="center">  <td> Gromacs </td>  <td> gro </td> <td> </td> </tr>
<tr align="center">  <td> Tinker </td>  <td> xyz </td> <td> </td> </tr>
</table>

<H3> Trajectory Files </H3>
<table align="center" border="1" style="width:80%">
<tr align="center"><th>Package</th> <th>File Suffix</th>   <th>Notes</th></tr>
<tr align="center">  <td> Amber </td>  <td> nc, netcdf </td> <td> velocities </td> </tr>
<tr align="center">  <td> Amber</td>  <td> crd, mdcrd </td> <td> velocities (if NetCDF)</td> </tr>
<tr align="center">  <td> Amber</td>  <td> inpcrd, rst, rst7 </td> <td> </td> </tr>
<tr align="center">  <td> CHARMM/NAMD </td>  <td> dcd </td> <td> </td> </tr>
<tr align="center">  <td> CHARMM/NAMD </td>  <td> pdb </td> <td> concatenated PDBs or sets of PDBs</td> </tr>
<tr align="center">  <td> Gromacs </td>  <td> xtc </td> <td> </td> </tr>
<tr align="center">  <td> Gromacs </td>  <td> trr </td> <td> velocities, pressure, virial, forces <br> (Only velocities available with Trajectory Class)</td> </tr>
<tr align="center">  <td> Tinker </td>  <td> arc </td> <td> </td> </tr>
</table>

LOOS can write structures out in PDB format or a native pseudo-xml format, and can write
trajectories in either DCD or XTC format.

*/


/*! \page selections Selection Language

\section Language Description

The selection string parser is a relatively simpled parser patterned
after C/PERL expressions and includes support for PERL-style regular
expressions via Boost.  There are two kinds of literals supported:
strings and numbers.  Numbers are any valid integer.  Strings are
delimited by either single quotes or double quotes, so both of the
following are valid strings:
\verbatim
"a string"
'another string'
\endverbatim

An important caveat to integer numbers is that LOOS assumes that none
will be negative.  In other words, no atomid nor resid nor number
extracted from a segid (see \ref magops_explained magical ops
below) will evaluate to a
negative number.  The relational operators &lt; and &lt;= will behave
differently if either operand is a negative number.  In this case,
they will evaluate to false, for reasons that will become obvious when
you read about the magical operators below...

The parser also recognizes a small set of keywords that evaluate to
Atom properties.  These keywords fall into two types as well: those
that evaluate to a number (id, resid) and those that evaluate to a
string (name, resname, chainid, and segname or segid).  Keep in mind that keywords
are not substitutions, but are more like a pre-defined function that
returns that atom property.  So you cannot put a keyword in a string
and expect it to be substituted with the appropriate value, for example.

\subsection relops Relational Operators
<table align="center" border="1" style="width:80%">
<tr align="left"><th>Operator</th><th>Operation</th> <th>Strings</th><th>Numbers</th><th>Example</th></tr>
<tr align="left"><td>&gt;</td><td>Greater than</td><td>yes</td><td>yes</td><td>resid &gt; 10</td></td>
<tr align="left"><td>&gt;=</td><td>Greater than or equals</td><td>yes</td><td>yes</td><td>resid &gt;= 10</td></td>
<tr align="left"><td>&lt;=</td><td>Less than or equals</td><td>yes</td><td>yes</td><td>resid &lt;= 50</td></td>
<tr align="left"><td>&lt;</td><td>Less than</td><td>yes</td><td>yes</td><td>resid &lt; 50</td></td>
<tr align="left"><td>==</td><td>Exactly equals</td><td>yes</td><td>yes</td><td>name == "CA"</td></td>
<tr align="left"><td>!=</td><td>Doesn't equals exactly</td><td>yes</td><td>yes</td><td>segname != "SOLV"</td></td>
<tr align="left"><td>=~</td><td>Regular expression match</td><td>yes</td><td>no</td><td>name =~ "^(C[A]?|N|O)$"</td></td>
</table>

\subsection logops Logical Operators
<table align="center" border="1" style="width:80%">
<tr align="left"><th>Operator</th><th>Operation</th><th>Example</th></tr>
<tr align="left"><td>&&</td><td>Logical And</td><td>name == "CA" && segid == "PROT"</td></tr>
<tr align="left"><td>||</td><td>Logical Or</td><td>segid == "SOLV" || segid == "BULK"</td></tr>
<tr align="left"><td>!</td><td>Not (Negate)</td><td>!(segid == "SOLV")</td></tr>
</table>


\subsection magops Magical Operators
<table align="center" border="1" style="width:80%">
<tr align="left"><th>Operator</th><th>Operation</th><th>Example</th></tr>
<tr align="left"><td>-></td><td>Extracts a number from a string</td><td>segid -> "L(\d+)"</td></tr>
</table>


\subsection keywords Keywords
<table align="center" border="1" style="width:80%">
<tr align="left" valign="top"><th>Keyword</th><th>Atom Property</th><th>Evaluates to...</th><th>Operators</th></tr>
<tr align="left" valign="top"><td>name</td><td>Atom name</td><td>string</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=, =~</td></tr>
<tr align="left" valign="top"><td>id</td><td>Atom ID</td><td>number</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=</td></tr>
<tr align="left" valign="top"><td>index</td><td>Atom index in model file (0=based)</td><td>number</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=</td></tr>
<tr align="left" valign="top"><td>resname</td><td>Residue name</td><td>string</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=, =~</td></tr>
<tr align="left" valign="top"><td>resid</td><td>Residue ID</td><td>number</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=</td></tr>
<tr align="left" valign="top"><td>segid</td><td>Atom segid</td><td>string</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=, =~</td></tr>
<tr align="left" valign="top"><td>segname</td><td>Synonym for segid</td><td>string</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=, =~</td></tr>
<tr align="left" valign="top"><td>chainid</td><td>Chain ID</td><td>string</td><td>&gt;, &gt;=, &lt;=, &lt;, ==, !=, =~</td></tr>
<tr align="left" valign="top"><td>all</td><td>Evaluates to true</td><td>number</td><td></td></tr>
<tr align="left" valign="top"><td>hydrogen</td><td>Evaluates to true if atom is a hydrogen</td><td>number</td><td></td></tr>
<tr align="left" valign="top"><td>backbone</td><td>Evaluates to true if atom is a backbone atom (nucleic acids and proteins, and includes hydrogens)</td><td>number</td><td></td></tr>
</table>

Notes:\n
The \c all keyword is used to force a selection string to match all
atoms in instances where a selection is required.  For example, a
program to align frames of a trajectory DCD to a reference structure
might require a selection to pick which atoms to use when computing
the rotations and then another selection to pick which atoms are
actually rotated.  If you wanted to apply the rotation to all atoms,
you just use the \c all keyword, i.e.
\verbatim
aligner --selection='name='CA' && segid =~ "BAR[12]"' --transform='all' foo.pdb foo.dcd newfoo
\endverbatim


\subsection regexps Regular Expression Matching
The regular expression matching operator "=~" deserves special
attention.  It's use is more restrictive than the other operators in
that it can only take a keyword that evaluates to a string on the
left-hand side and a string on the right-hand side.  So, the following
expressions are valid:
\verbatim
name =~ "CA"
name =~ "^(C|O|N)$"
segid =~ "PROT|HEME"
\endverbatim
While the following are not valid:
\verbatim
resid =~ "10[0-9][0-9]"
segid =~ 0010
name =~ resname
\endverbatim

The regular expression syntax supported is the PERL syntax as
implemented by the Boost libraries.  While you can write regular
expressions that look a lot like globbing (a la VMD selections), keep
in mind that it isn't globbing.  It's a regular expression, which is
more powerful anyway...  You do need to be careful though that your
shell does not munge any of the regex operators.  It's a good idea to
use single quotes when you're writing regex's in a shell.

The string equality operators ("==" and "!=") both consider the
<I>entire</I> string.
\verbatim
"CA" == "C"  --> false
 "C" == "C"  --> true
\endverbatim
You can use the "=~" operator to perform a substring match.
\verbatim
"CA" == "C"  --> false
 "C" == "C"  --> true
"CA" =~ "C"  --> true
\endverbatim
This brings up an important point about using regular expressions: be
careful of unexpected substring matches.  For example, let's say you
are wanting to pick out all backbone atoms and you write this
selection string:
\verbatim
name =~ "C|CA|O|N"
\endverbatim
Now look what happens when the following atom names are matched:
\verbatim
 "CG" --> true
"CD1" --> true
 "NE" --> true
"OH2" --> true
\endverbatim
The problem is that the regular expression is not constrained, so even
though you explicitly put "CA" and "CB" in there, you also have a "C"
which says <I>any</I> atom name with a "C" in it is a match.  If
you want to match a string <I>exactly</I> with a regular expression,
you must anchor it:
\verbatim
name =~ "^(C|CA|CB|O|N)$"
\endverbatim

\subsection magops_explained Magical Operations
There is currently only one "magical operator" defined: "->".  This
operator takes a string keyword on the left-hand side (i.e. name,
resname, or segid/segname) and a string on the right-hand side
representing a regular expression pattern.  It will then try to
extract a numeric value (integer) from the subexpression matches.  For
example, suppose you have a range of segments that all follow a
pattern such as "PG1", "PG2", "PG3", ..., "PG120".  The regular
expression "PG(\d+)" matches these and the pattern within the
parenthesis is a subexpression.  So,
\verbatim
(segid->"L(\d+)") >= 10 && (segid->"L(\d+)") <= 50
\endverbatim
will match segid's "L10" through "L50".  Since each matched
subexpression will be examined for a valid integer conversion, the
following will work as expected:
\verbatim
segid->"(L|PG)(\d+)"
\endverbatim

There is a small hitch with the magical operator.  If there is no
match, it evaluates to -1.  But this is a valid int, so you cannot do
the following:
\verbatim
segid->"L(\d+)" <= 100
\endverbatim
since it will match all segids.  You can't, unless the &lt;= operator
is also a little bit special.  Fortunately, it is.  If either operand
is a negative number, both the &lt; and &lt;= operands assume that
this is a flag for a null-match, and will result in a false value
being returned.  It's a bit of a kludge, but it works...

<hr>
\section kahuna Putting It All Together...
When you perform a selection on an AtomicGroup using the selection
language, the expression is evaluated once for each atom in the
group.  If it evaluates to "true" (integer 1), then the atom is added
to the new selection.  Only one atom is considered at a time.

Here are some example selections:
\verbatim
Extract C-alphas:
  name == "CA"

Solvent:
  segid == "SOLV" || segid == "BULK"

Solvent heavy atoms (oxygens only)
  name =~ "O" && (segid == "SOLV" || segid == "BULK")

C-alphas from a range of residues:
  name == "CA" && resid >= 10 && resid <= 50
\endverbatim

\subsection Usage
Most tools based on LOOS will accept selection strings from the
command-line.  They must be enclosed in quotes though so they are all
one argument to the tool.  If you're using regular expressions, it's a
good idea to use single quotes to prevent your shell from
misinterpreting the regular expression operators and as mentioned
before, back-slash escapes may need doubling.

You can store your selection in a file if you want.  To use it then,
use the back-quote feature of your shell to "cat" your selection
file.  Since your selection must be one argument, you must enclose the
back-quote within double-quotes, i.e.
\verbatim
  a_tool_name "`cat myselection.txt`" arg arg arg
\endverbatim

If you store your selection in a file, then you can also use
comments.  A comment is anything after a "#" on a line.  Here's an
example of a selection in a file:
\verbatim
### Select water oxygens only...
# Pick out any atom that contains an oxygen
name =~ "O" &&
(segid == "SOLV" || # any segment named SOLV
segid == "BULK")    # or named BULK
\endverbatim


*/


namespace loos {
/*! \page common_options Common Command-Line Options for Tools

Many LOOS tools use a common set of command-line options (through
the \c OptionsFramework ).  These options are organized into
groups that tend to be used together.  Not all tools will support
all options.  Options may also appear in two forms: a "long" form
where the option is written out following two hyphens, or a "short"
form that is a single character following a single hyphen.  An option may
also have a value associated with it, and it can be assigned either
using an equals sign, e.g. \c --verbosity=3, or by just following
the option with a space (optional with the short forms), e.g. \c --verbosity 3.  Additionally, some
options are "boolean" in that they turn on or off specific behavior.
These options are turned on by assigning a 1 (true) to it, or a 0 (false),
for example, \c --brief=1 turns on brief output.

\subsection common_options_table Common Options

<table align="center" border="1" style="width:100%">
<tr align="left"><th>Long Name</th> <th>Short Name</th> <th>Description</th> <th>Example</th></tr>

<tr align="left" valign="top">
    <td>\-\-fullhelp</td>
    <td></td>
    <td>Give a lot more information about how the tool works and how to use it.</td>
    <td>\-\-fullhelp</td>
</tr>

<tr align="left" valign="top">
    <td>\-\-prefix</td>
    <td>\-p</td>
    <td>Sets the prefix for files written out by the tool.</td>
    <td> \-p sim1 </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-verbosity</td>
    <td>\-v</td>
    <td>Sets the output/logging level of a tool.  Higher numbers means more verbose output.</td>
    <td> \-v 3 </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-selection</td>
    <td>\-s</td>
    <td>Select atoms for the tool to operate on</td>
    <td> \-s backbone </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-modeltype</td>
    <td></td>
    <td> Specify the type of model file being used.  LOOS will automatically
         assign a file-type based on the suffix for a filename (e.g. pdb, psf, ...).
         If you use a different convention, you may need to manually tell
         the tool what kind of file you are using.  The tool's \c --fullhelp
         output will available types.</td>
    <td> \-\-modeltype pdb </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-trajtype</td>
    <td></td>
    <td> Specify the type of trajectory file being used.  LOOS will automatically
         assign a file-type based on the suffix for a filename (e.g. dcd, xtc, ...).
         If you use a different convention, you may need to manually tell
         the tool what kind of file you are using.  The tool's \c --fullhelp
         output will available types.</td>
    <td> \-\-trajtype dcd </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-outtrajtype</td>
    <td></td>
    <td> Specify the type of trajectory file being written.  LOOS will automatically
         assign a file-type based on the suffix for a filename (e.g. dcd, xtc, ...).
         If you use a different convention, you may need to manually tell
         the tool what kind of file you are using.  The tool's \c --fullhelp
         output will available types.</td>
    <td> \-\-trajtype xtc </td>
</tr>


<tr align="left" valign="top">
    <td>\-\-skip</td>
    <td>\-k</td>
    <td> Skip the first N frames of the trajectory (or trajectories)</td>
    <td> \-k 50 </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-stride</td>
    <td>\-i</td>
    <td> Read every ith frame from the trajectory (or trajectories)</td>
    <td> \-i 10 </td>
</tr>

<tr align="left" valign="top">
    <td>\-\-range</td>
    <td>\-r</td>
    <td> Specifies a range-list of frames to operate on from a trajectory.  See below
    for more details.</td>
    <td> -r 50:10: </td>
</tr>
</table>


\subsection ranges Specifying Ranges

The range option (through \c parseIndexRange() ) in LOOS tools is a versatile method of picking exactly what
frames from a trajectory (or \c MultiTrajectory) you want the tool to use.  A range-spec
can be a frame number, a range of frames, or a range of frames with a stride.
A range-spec can also be list of range-specs separated by commas.  So, you can pick a single
frame by giving the frame number.  For example,
\code{.sh}
foo -r 9 model.pdb sim.dcd
\endcode

\c foo will only use the 10th frame from \c sim.dcd.  <B>Remember, frame numbers are 0-based!</B>  Similarly,

\code{.sh}
foo -r 0,1,2,3,4 model.pdb sim.dcd
\endcode
\c foo will only use the first 5 frames.
Literal ranges of frames can be
specified using an octave/matlab-like syntax of start:stop (<B>inclusive</B>),

\code{.sh}
foo -r 0:99 model.pdb sim.dcd
\endcode
\c foo will use the first 100 frames, while

\code{.sh}
foo -r 100:199 model.pdb sim.dcd
\endcode
will skip the first 100 frames, and use the next 100 frames.

A stride can also be given with the syntax of start:stride:stop,
\code{.sh}
foo -r 10:2:99 model.pdb sim.dcd
\endcode
\c foo will now skip the first 10 frames, then take every other frame through the 100th frame.

You do not need to know how long a trajectory is in order to use the range notation to
specify a skip and a stride (this was not true in older versions of LOOS).  Simply
leave off the end,

\code{.sh}
foo -r 10: model.pdb sim.dcd
\endcode

Will use all but the first 10 frames of the trajectory.  Note that you must have a colon
after the number, otherwise you will be telling use to use <em>only</em> frame index 10 (i.e.
the 11th frame).

You can also set a stride without knowing how long a trajectory is,

\code{.sh}
foo -r 10:2: model.pdb sim.dcd
\endcode

Here, the first 10 frames a skipped and then every other frame is used for
the rest of the trajectory.

*/
}

/*! \page building Building LOOS

The best source of information on building LOOS is <A href="https://github.com/GrossfieldLab/loos/blob/master/INSTALL.md">INSTALL.md</A>, found in the top level directory of the LOOS distribution.  It includes detailed instructions for building LOOS on various Linux distributions and OSX, as well as using Conda.

\section basicbuild Building Basics
LOOS requires <A href="http://www.scons.org" target="_blank">SCons</A>
and the <A href="http://boost.org" target="_blank">Boost (1.36+)</A>
libraries.  For macs, it also requires <A
href="https://itunes.apple.com/us/app/xcode/id497799835?mt=12"
target="_blank">XCode</A> be installed (free download from the Mac App
Store).  On Linux, <A href="http://math-atlas.sourceforge.net"
target="_blank">Atlas</A> is <em>strongly</em> recommended, although
the standard LAPACK and BLAS should work.  If you plan to modify the
parser (and you probably shouldn't), then you'll need the GNU
utilities <A href="http://www.gnu.org/software/flex/">flex</A> and <A
href="http://www.gnu.org/software/bison/">bison</A>.  Although LOOS
comes bundled with pre-built documentation, you can regenerate it.
Doing so requires doxygen and graphviz be installed.

To build LOOS, go into the LOOS distribution directory and run scons.
If your libraries are installed in non-standard locations, you may
need to tell LOOS where its required components are.  There are two
ways you can tell SCons where to look for those libraries.  The first
is to specify it on the command-line.  The second, described later, is
to use a <TT>custom.py</TT> file.

Using the command line, if you have Boost
installed in <TT>/usr/local/boost_1_54_0</TT>, build LOOS using:
\verbatim
scons BOOST=/usr/local/boost_1_54_0
\endverbatim

This will tell SCons to look
in <TT>/usr/local/boost_1_54_0/include</TT> for header files
and <TT>/usr/local/boost_1_54_0/lib</TT> for libraries.  In some
cases, the directories may not follow this convention, so you will need
to specify the individual directories explicitly:
\verbatim
scons BOOST_INCLUDE=/usr/local/include/boost BOOST_LIBPATH=/usr/local/lib
\endverbatim

SCons will, by default, try to figure out the appropriate threaded
Boost libraries to use and, if it cannot find those, it will use the
non-threaded versions.  While the build system can handle most
variants of the Boost library names, it may not catch all.  To
explicitly set the libraries LOOS is linked with, set the BOOST_LIBS
variable to a space-separated list of libraries.  Note that
you <B>must</B> include all libraries required by LOOS.  For example:
\verbatim
scons BOOST_LIBS="boost_regex-gcc43-mt boost_program_options-gcc43-mt
boost_thread-gcc43-mt boost_system-gcc43-mt"
\endverbatim

Similar configuration options are available for NetCDF and
ATLAS/LAPACK.  If threaded versions of ATLAS are found, these will be used by
default.  If you intend to run multiple LOOS tools concurrently, then
you may get better performance by using the serial ATLAS libraries.
You can force LOOS to build with the serial ATLAS libraries by using
the threads option with scons,
\verbatim
scons threads=0
\endverbatim
SCons will also prefer to use ATLAS if it's available, but
will revert to LAPACK/BLAS if necessary.  For Macs, the Accelerate
FrameWork is used rather than ATLAS.  NetCDF support is only included
if the NetCDF library is found.

It is not necessary to always set these build options on the
command-line.  If a <TT>custom.py</TT> file exists, SCons will read it
and set the variables appropriately.  We provide an examples of how it
can be used in <TT>custom.py-proto</TT>.  Simply copy this file
to <TT>custom.py</TT> and then uncomment and edit the appropriate
lines.  Note that variables set on the command-line or environment
will have priority over what's in your <TT>custom.py</TT> file.


\subsection install Installing


To install LOOS, use the "install" target:

\verbatim
scons install
\endverbatim

This will cause SCons to copy the headers, tools, and library into
 /opt/loos.  You can change where LOOS is installed by setting the
 PREFIX variable in either your custom.py file or on the command
 line.  LOOS will create a /bin, /include, /lib, and /docs directory
 and copy the appropriate files.  The recommended installation
 methodology is to install LOOS into a version-specific directory, and
 then set up a symlink from \c loos-latest to the most recent
 installed version:
\verbatim
scons PREFIX=/opt/loos-2.1 install
ln -s /opt/loos-2.1 /opt/loos-latest
\endverbatim
Remember that any options you have previously provided to scons should
 be specified again when installing.

<H2>Important Note...</H2>


To use LOOS, your environment must be first setup:
\verbatim
  (bash)   source /path/to/loos/setup.sh
  (tcsh)   source /path/to/loos/setup.csh
\endverbatim

<hr>
\subsection building_pyloos Building PyLOOS, the Python Interface to LOOS
PyLOOS will be automatically built if you have a recent swig (2.0+)
installed.  PyLOOS now (as of LOOS 2.3.0) also requires NumPy.  See
the top of the INSTALL and \ref faq_pyloos "the FAQ for PyLOOS" for
more information about building and using PyLOOS.

In some cases, scons may try to build PyLOOS when it isn't appropriate
(i.e. supported).  To disable PyLOOS, use the pyloos flag,
\verbatim
scons pyloos=0
\endverbatim

<hr>

\subsection general General Notes

If you're using a compiler in a non-standard location (e.g. you have
your own build of the latest and greatest gcc), SCons may not be using
it even though your $PATH is set correctly.  You can force which
compiler is used to build LOOS by setting the CXX variable in your
"custom.py" file.

Note: Settings in the custom.py file can be overridden using the
command-line and the shell environment.

SCons supports building LOOS in parallel.  If you have 4 cores, for
example, use "scons -j4" to use all 4 cores.

Prebuilt documentation for LOOS is provided as part of the
distribution.  This is simply copied into the install directory as
part of installation.  Should you want to build a new version of the
documentation, Doxygen is required.  Moreover, due to an issue we ran
into with SCons, documentation building and installation are
decoupled.  What this means is that you must explicitly build the docs
(i.e. "scons docs") and -then- install, "scons install".  Running
"scons install" will -not- rebuild the documentation, even if it is out
of date (or nonexistent).


\subsection BYO Building Your Own Tools

You have two choices for building your own tools depending on LOOS.  The
simplest way is to work in the Packages/User directory.  In that case, all you
need to do to build against LOOS (other than write your application, of
course) is edit the SConscript file in that directory, adding your program
to the build list.  Specifically, you edit the line that creates a variable
"apps", appending your program's name to the end of the string.  Then, run
scons from the main LOOS directory, and your program will be built.
We have included a number of trivial programs in the User directory; they
don't actually do anything useful, but they provide basic templates for how
to use the command line options, and get the basic setup you'll need.
Note that tools in the User package will be installed if you choose to
install LOOS.

If you wish to work outside the LOOS directory structure, copy the
SConstruct and SConscript files from the Examples directory and edit
them as needed.  You can probably get by with just editing the
SConscript file.  To build, you will need to have sourced one of the
LOOS setup scripts (e.g. <TT>setup.sh</TT>).  This will set several
environment variables that will tell your SConstruct where LOOS is and
how it was built.  If all goes well, running <TT>scons</TT> in your
directory will build your tools.  If not, you can change your
environment variables or alternatively, <I>not</I> source the LOOS
setup script and use a <TT>custom.py</TT> file.

<h3>Important Note</h3>
The environment <i>always</i> overrides what's in the SConstruct and
in the <tt>custom.py</tt> file.  If you create a <tt>custom.py</tt>
file and change the <tt>LOOS_CCFLAGS</tt> variable, it will be ignored
in favor of what <tt>LOOS_CCFLAGS</tt> was set to when you sourced the
<tt>setup.sh</tt> script.

<hr>


\section Build Targets

There are several build targets available:

<table align="center">
<tr align="left"><th>Target</th><th>Description</th></tr>
<tr align="left"><td>all (default)</td><td>Build the library, tools, packages, and PyLOOS</td></tr>
<tr align="left"><td>core</td><td>Builds the library and PyLOOS only</td></tr>
<tr align="left"><td>docs</td><td>Rebuilds the documentation</td></tr>
<tr align="left"><td>install</td><td>Installs library, toosl, PyLOOS, and all packages (except user)</td></tr>
</table>

Each package in LOOS is also a build target.  The LOOS library and
only that package will be built.  The current set of packages are:

<table align="center">
<tr align="left"><td>ENM</td><td>Elastic Network Models</td></tr>
<tr align="left"><td>HBonds</td><td>Hydrogen bonds analysis</td></tr>
<tr align="left"><td>Conv</td><td>Simulation convergence analysis</td></tr>
<tr align="left"><td>Density</td><td>Density/3D histogram tools</td></tr>
<tr align="left"><td>User</td><td>User created tools</td></tr>
<tr align="left"><td>Python</td><td>PyLOOS-based scripts</td></tr>
</table>

There are several different build options that are available for
LOOS.  These are handled on the command-line by SCons as "foo=1" to
turn the option on or "foo=0" to turn it off.  Most options default to
off.  Finally, you can query the available options by passing the "-h"
flag to SCons.  The following table lists the principal build options:

<table align="center">
<tr align="left"><th>Option</th><th>Default</th><th>Description</th></tr>
<tr align="left"><td>debug</td><td>0</td><td>Adds "-DDEBUG" to build</td></tr>
<tr align="left"><td>release</td><td>1</td><td>Turns on aggressive optimization (-O3)</td></tr>
<tr align="left"><td>regenerate</td><td>0</td><td>Regenerates the test verification data</td></tr>
<tr align="left"><td>reparse</td><td>0</td><td>Runs bison/flex to create the C++ files for parsing selections</td></tr>
</table>


\subsection Reparsing
To remove the dependency on Bison/Flex, the output from these tools
for the grammar and scanner are included.  If you want to rebuild
them, you will need to use the 'reparse=1' option.  The catch is that
if you have a different version of flex installed, there is a good
chance there will be a conflict with the bundled FlexLexer.h include
file.  If you see odd compiler errors, try removing that file and
rebuilding.  Alternatively, forcibly remove all generated files by
doing "rm *.cc *.hh" (assuming you've added no files with those
suffixes), then rebuild.

*/

/*! \page tools Summary of Tools

Below is a summary of the tools currently distributed with LOOS.  To get a
detailed summary of the command line arguments, run the program without
arguments or using "-h".  Nearly all tools also support the
"--fullhelp" options, which will display more detailed help
information, including examples of how to use the tool.

In the documentation, the term "system" or "model" refers to a file that
describes the contents of a system, such as a PDB file or one of the inputs
from the various simulation packages (PSF, parmtop, gro, etc).  All of the
tools are now package agnostic, in the sense that they will take any of the
supported file formats as input.  However, not all files provide all of the
needed information; for example, the order_params tool requires connectivity
information to function properly, so the user must run it with a system file
type that has that information, such as a CHARMM/NAMD PSF file or a PDB with
CONECT records.

At present, LOOS assumes that all periodic boxes are rectangular, and
will produce incorrect answers if trajectories using different box shapes
(eg truncated octahedron) are used in programs which make use of
periodicity (eg rdf).  We have no immediate plans to generalize the
code to handle other periodicities, but are willing to reconsider if
there is significant demand from users.

LOOS uses angstroms as the output unit of distance, even when the input
coordinates are in other units (e.g. nanometers for GROMACS files).  All output
is in plain text format, and follows general unix/linux conventions.  Every
program's output starts with a series of comment lines, marked by beginning
with a "#", echoing the command line used to invoke the program, the user, the
date teh program was run, the working directory, and the version of LOOS used.
Any additional information, such as the meanings of various columns of output,
is also provide on lines marked with "#".

LOOS tools are designed to make it easy to plot the results generated.  As a
rule, files are formatted such that they can be cleanly plotted using the
gnuplot plotting program, standard with most modern linux distributions.   In
addition, if matrices or vectors are written out (e.g. from the svd tool or one
of the tools from the ENM package), the format is consistent with that used by
Matlab and Octave.

<HR>
<B><I> Categories of Tools </I> </B>
      - \subpage manipulation "Manipulating trajectory files"
      - \subpage convergence "Assessing statistical errors and convergence"
      - \subpage density "3D density distributions"
      - \subpage hbond "Hydrogen Bonding"
      - \subpage pca "Principal component analysis"
      - \subpage membranes "Membrane systems"
      - \subpage enm "Elastic network models"
      - \subpage other "General purpose tools"
      - \subpage voronoi "Voronoi decomposition"
      - \subpage user "User-created tools"

  \page convergence Convergence
  <h2>Convergence Analysis Tools</h2>
  A collection of tools for assessing statistical error and
  convergence, found in the Packages/Convergence/ directory:

    <DL>
      <DT> <B> assign_frames </B>
      <DD>  Given a trajectory and a set of fiducial structures (histogram
      centers), assign each frame in the trajectory to a histogram bin.
      Part of the workflow for computing the effective sample size.  (See
      effsize.pl)

      <DT> <B> avgconv </B>
      <DD> Computes the RMSD between the average structure for time i
      and i+1 for a trajectory.  The "locally optimal" flag determines
      whether the trajectory is globally aligned first or whether each
      block of frames used in the average is aligned prior to averaging.

      <DT> <B> bcom </B>
      <DD> Implements the block covariance overlap method.  Briefly,
      think of block-averaging where the trajectory is broken up into
      blocks of a given size, the PCA computed for the block, and then
      the covariance overlap is calculated between the block's PCA and
      the PCA for the entire trajectory.  Then this is repeated for
      increasing block sizes.  A Z-score for the bcom result can also
      be calculated (using the --zscore=1 flag and optionally setting
      the number of "tries" to use).

      <DT> <B>block_average</B>
      <DD> Reads a simple columnated text file, and computes the block-averaged
           standard error as a function of block size.  The plateau value
           is the best estimate for the true standard error.
           Reference: Flyvbjerg, H. & Petersen, H. G.
           J. Chem. Phys., 1989, 91, 461-466

      <DT> <B> block_avgconv </B>
      <DD> Block-averaging of RMSD between average structures for a
      trajectory.  "Range" in this case is the range of block sizes
      and not stricly which frames of the trajectory to use.

      <DT> <B> bootstrap_overlap.pl </B>
      <DD> PERL program to compute the bcom and bootstrapped bcom for
      a trajectory, generating a plot of their ratio and an
      exponential fit.  Also generates a plot of the residual error in
      the fit.  Use the "--help" option for more details.  Note that
      the number of block sizes used is somewhat conservative, so it's
      probably a good idea to use a low number of block sizes
      initially to get a quick idea of how good or bad the sampling
      is, and then use the higher number of blocks for a more detailed
      analysis.  Also note that plotting requires gnuplot.  If you do
      not have gnuplot installed (or do not like gnuplot), use the
      "--noplot" flag to disable this.

      <DT> <B> boot_bcom </B>
      <DD> Bootstrapped bcom is similar to bcom above, but rather than
      using contiguous blocks, it uses a bootstrap procedure by
      randomly selecting frames from the trajectory to build
      decorrelated blocks.  If no seed for the random number generator
      is given, LOOS will pick a default (based on the current system
      clock).  The --replicates option determines how many blocks are
      generated for a given size.

      <DT> <B> chist </B>
      <DD> Calculates either a cumulative histogram (where each output
      row is the histogram up to that point), or a windowed histogram.

      <DT> <B> coscon </B>
      <DD> Computes the cosine content for varying windows of a
      trajectory, based on Hess, B.  "Convergence of sampling in
      protein simulations." Phys Rev E (2002) 65(3):031910

      <DT> <B> decorr_time </B>
      <DD> Decorrelaton time as computed by structural histogram
      analysis.  The default values for the range of N-values,
      repetitions, and bin fraction are taken from the paper below and
      may need to be changed, particularly if you are using a
      trajectory you suspect is undersampled.
      Reference: Lyman & Zuckerman, J Phys Chem B (2007) 111:1287-82

      <DT> <B> effsize.pl </B>
      <DD> PERL front-end to the effective sample size tools (ufidpick,
      assign_frames, hierarchy, neff).  If you want to apply the
      Zuckerman-style effective sample size method (see the entry for neff,
      below), you probably should use this script instead of the individual
      tools, since this tool automates the process of picking fiducial
      structures (the frames that will be the centers of your histogram
      bins), assigning the frames from the trajectories to those bins,
      working out the mean first passage time between bins, and computing
      the effective sample size.  Reference: Lyman & Zuckerman, Biophys J
      (2006) 91:164-72

      <DT> <B> fidpick </B>
      <DD> Picks fiducial structures for structural histograms.
      Reference: Lyman & Zuckerman, Biophys J (2006) 91:164-72

      <DT> <B> hierarchy </B>
      <DD>Given a trajectory whose structures have been binned into
      states via reference structures, computes the mean first passage time
      between states and then constructs a hierarchy of states based on
      exchange rates.  Used to generate input for neff.
        Based on Zhang, Bhatt, and Zuckerman; JCTC, DOI: 10.1021/ct1002384
	and code provided by the Zuckerman Lab
	(http://www.ccbb.pitt.edu/Faculty/zuckerman/software.html)

      <DT> <B> neff </B>
      <DD> Computes effective sample size given an assignment and
      state file (from hierarchy).
      Based on Zhang, Bhatt, and Zuckerman; JCTC, DOI: 10.1021/ct1002384
      and code provided by the Zuckerman Lab
      (http://www.ccbb.pitt.edu/Faculty/zuckerman/software.html)

      <DT> <B> qcoscon </B>
      <DD> Computes a "quick" cosine content using the entire trajectory
      for the top few modes, based on Hess, B.  "Convergence of
      sampling in protein simulations." Phys Rev E (2002) 65(3):031910

      <DT> <B> sortfids </B>
      <DD>Sorts fiducials (from fidpick) based on a decreasing bin
      population.

      <DT> <B> ufidpick </B>
      <DD> Picks a set of fiducial structures from a trajectory using
      a uniform distribution.
      Reference: Lyman & Zuckerman, J Phys Chem B (2007) 111:12876-82

</DL>

  \page density
  <h2>Density Tools</h2>
  A collection of tools for working with 3D density distributions,
  found in Packages/DensityTools.  This includes new classes such as
  loos::DensityTools::DensityGrid and loos::DensityTools::SimpleMeta.
  Some of the grid tools read and write to stdout so they can be
  chained, for example:
<pre>
	water-hist foo.pdb foo.dcd | gridgauss 4 2 | grid2xplor >foo.map
</pre>
   Water-specific tools may allow you to specify "internal" waters to
  proteins.  This is done by one of 3 methods: axis, box, and grid.
  Axis picks waters that are within a given radius from the principal
  axis of the protein.  Box uses the bounding box of a protein.  Grid
  uses a grid mask to only consider waters within the non-zero portion
  of the mask.  Note that "water" and "protein" are just LOOS
  selections so there are no restrictions on what part of your system
  can be used for building the histogram (e.g. ligand density in a
  binding simulation).

<DL>
       <DT> <B> blobid </B>
       <DD> Identifies "blobs" in a grid using a flood-fill algorithm

       <DT> <B>  blob_stats </B>
       <DD> Takes a blobid'd grid and prints out statistics about each blob

       <DT> <B>  contained </B>
       <DD> Given a thresholded grid and a trajectory, counts the
       number of atoms that are contained within the grid segment at
       each time point.

       <DT> <B>  grid2ascii </B>
       <DD> Converts a grid into a serialized ASCII representation

       <DT> <B>  grid2xplor </B>
       <DD> Converts a grid into an XPLOR compatible ASCII electron
       density map.  Requires that the "type" of the grid be specified
       (i.e. float, double [default], etc)

       <DT> <B>  gridgauss </B>
       <DD> Convolves a grid with a Gaussian kernel for smoothing

       <DT> <B> gridinfo  </B>
       <DD> Prints out basic information about a grid

       <DT> <B>  gridmask </B>
       <DD> Applies a binary mask (a grid containing ints) to a density grid
       of doubles.  Any grid point where the mask is non-zero is
       copied into a new density grid.  All other voxels are zero.
       Use this to "clip" out unwanted blobs in a grid.

       <DT> <B> gridscale </B>
       <DD> Applies a constant scaling to a grid.  Assumes a density
       grid (i.e. grid of doubles)

       <DT> <B>  gridstat </B>
       <DD> Simple statistics about the data stored in a density grid
       (i.e. grid of doubles)

       <DT> <B>  peakify </B>
       <DD> Finds peaks in a density grid using a threshold cutoff.
       Blobs are found by flood-filling the grid and the centroid of
       the blob is used as the peak.

       <DT> <B>  pick_blob </B>
       <DD> Given a grid mask (i.e. grid of ints), create another grid
       mask containing only the blobs that are requested (near an
       atom or a gridpoint).

       <DT> <B> water-count </B>
       <DD> Counts the number of waters inside a protein at each
       time-point.  Requires an "internal water matrix" (see water-inside).

       <DT> <B>  water-extract </B>
       <DD> Extracts "internal" waters from a trajectory and
       concatenates them into a single PDB for visualizing water
       pockets/channels.

       <DT> <B> water-hist </B>
       <DD> Creates a density grid (histogram) that represents water
       locations throughout the trajectory.  Bulk water can be
       explicitly added into the histogram by using the --bulked option
       (this is useful for transmembrane proteins).

       Scaling the density by the bulk water density currently only
       works for membrane systems (or systems where the bulk water
       lies in a plane).  Use the --scale option along with the --bulk
       option to specify what z-range to use for the bulk density estimate.

       <DT> <B> water-inside </B>
       <DD> Classifies waters as being inside a protein (by various
       user-specified criteria) over the course of a trajectory.  The
       state of all waters is written as a large matrix where the rows
       represent time, columns represent different waters, and a 1
       means the water is inside at time t.

       <DT> <B> water-sides </B>
       <DD> Similar to water-inside, but classifies water based on
       which side of a membrane it lies (or whether it's internal).

</DL>

  \page enm
  <h2>Elastic Network Models</h2>
  A collection of tools for working with ENMs, found in the
  Packages/ElasticNetworks/ directory:
    <DL>
      <DT> <B>anm</B>
      <DD> Computes the anisotropic network model for a structure.
      Reference: Atilgan, et al., Biophys. J. 80, 505-515, (2001).

      <DT> <B>gnm</B>
      <DD> Computes the gaussian network model for a structure. Reference:
      Bahar, et al, Folding and Design 2, 173-181, 1997.

      <DT> <B>vsa</B>
      <DD> Computes the vibrational subsystem analysis model for a
      structure. Reference: Woodcock, et al, J. Chem. Phys., 129, 214109-9,
      2008

      <DT> <B>psf-masses</B>
      <DD> Copies atom masses from a PSF into the occupancy field of a PDB

      <DT> <B>heavy-ca</B>
      <DD> Places the total mass for a residue into its CA (for a PDB with masses)

      <DT> <B>enmovie</B>
      <DD> Creates a DCD depicting motion along the axes taken from an ENM result

      <DT> <B>flucc2b</B>
      <DD> Computes B-values based on ENM (<I>now deprecated</I>)

      <DT> <B>eigenflucc</B>
      <DD> Computes the fluctuations from either ENM or PCA output.
      These can be mapped to B-values in a structure.

   </DL>
   <H3>Important note</H3><p>
   The ENM tools return <i>all</i> eigenpairs, including the
   zero-modes.  The results are ordered such that the first 6 entries
   correspond to the zero modes in a typical case.  This means that
   when you specify a mode to subsequent analysis tools (such as
   porcupine or eigenflucc), you <i>must</i> account for this
   (i.e. add 6 to the mode requested).

    \page hbond
   <h2>Hydrogen Bonding Tools</h2>
   A set of tools for analyzing hydrogen bonding, found in
   Packages/HydrogenBonds/ directory:
      <DL>
        <DT><B>hbonds</B>
	    <DD> Finds putative h-bonds based on angle and distance

	    <DT><B>hmatrix</B>
	    <DD> Writes out a binary matrix indicating which atoms
	    have possible h-bonds at each time-point in a trajectory.

	    <DT><B>hcorrelation</B>
	    <DD> Computes the time-correlation function for h-bonds.
      </DL>

    \page manipulation Trajectory manipulation
   <h2> Trajectory manipulation tools </h2>
   A set of tools for manipulating structure and trajectory
   files, found in the Tools/ directory:
   <DL>
       <DT> <B>aligner</B>
       <DD> Align structures in a trajectory against the average using an
       iterative refinement scheme.  Can read any LOOS trajectory format, but
       will write the aligned trajectory as a DCD.

       <DT><B>center-molecule</B>
       <DD>A more flexible tool for centering molecules.  Can use
       different subsets for calculating the center, controlling what is
       translated, and what goes to the output.  It can also reimage the
       molecule and center only within the x,y plane.

       <DT><B>center-pdb</B>
       <DD>Read in a structure file, shift its centroid to the origin, and
       write a new pdb file to stdout.

       <DT><B>clipper</B>
       <DD>Manually clip a model using arbitrary sets of clipping planes.
       Outputs a PDB.

       <DT><B>concat-selection</B>
       <DD>Concatenates atoms from a trajectory into a single PDB.  Useful
       for seeing where something has been...

       <DT><B>convert2pdb</B>
       <DD>Read in a structure file in a LOOS-supported format, and write it
       out as a pdb file.

       <DT><B>dcdinfo</B>
       <DD>Extract the header information from a CHARMM/NAMD dcd file.  Will
       verify the number of frames present and report periodic box
       information.

       <DT><B>dumpmol</B>
       <DD>Outputs the low-level AtomicGroup representation for a model.
       Useful for double-checking LOOS' parsing of a file.

       <DT><B>frame2pdb</B>
       <DD>Extract a frame from a trajectory and write it as a pdb file.

       <DT><B>merge-traj</B>
       <DD> Merges a series of trajectory files into a single DCD file.  If you
       give it a pre-existing merged file to work from, it simply appends the
       new data to it by counting frames in the merged DCD and skipping that
       many frames in the input; this enormously reduces the time needed to
       merge large data sets.  It also has options to produce a second
       down-sampled trajectory, to translate and reimage each frame such that a
       particular set of atoms is centered at the origin, and to fix imaging
       such that molecules aren't broken across the periodic image.

       <DT><B>model-select</B>
       <DD>Takes a model (PDB, PSF, etc) and a selection string.  Parses the
       selection, then applies it to the PDB and writes the output to stdout.
       This tool is used mainly for checking your selection strings to make
       sure you're actually selecting what you intend to select.

       <DT><B>model2matlab</B>
       <DD>Takes a PDB and a selection and an optional selection and writes out
       the coordinates to stdout in matlab format.

       <DT><B>porcupine</B>
       <DD>Creates a faux-PDB containing atoms/bonds that represent a
       "porcupine" figure for a column vector from a matrix.  This can be used
       to visualize the direction of motion from SVD and ENM results.

       <DT><B>rebond</B>
       <DD>Distance-based search for bonds, that are explicitly added to
       the output PDB.  Use this tool to visualize your ENM networks, or
       to reconnect CA traces from SVD results...

       <DT><B>recenter-trj</B>
       <DD>Loop over a trajectory, translating the entire system such that
       the selected portion remains at the origin, and reimaging the rest
       on a molecule by molecule basis.  It can also just do translations
       in the z-dimension, or just in the xy-plane (these options are
       useful for membrane systems).  The model file must have connectivity
       information, and the trajectory must have periodic box information.
       This program writes a DCD file as output.

       <DT><B>reimage-by-molecule</B>
       <DD>Reads a trajectory, and writes a new DCD which has been reimaged
       on a molecule by molecule basis.  The model file must have
       connectivity information, and the trajectory must have periodic box
       information.

       <DT><B>renum-pdb</B>
       <DD>Used primarily to renumber atoms/residues in a PDB...but it can
       work with any LOOS-supported format.

       <DT><B>rmsfit</B>
       <DD>Superimpose two structures using Kabsch RMS alignment.

       <DT><B>serialize-selection</B>
       <DD>Takes a trajectory consisting of N copies of a selection
       and turns it into a trajectory that is N times as long, but with
       only one copy of the selection.

       <DT><B>smooth-traj</B>
       <DD>Smooths a trajectory by computing a windowed-average structure.
       Weighting within the window can either be uniform or cosine-weighted.

       <DT><B>subsetter</B>
       <DD>Subsets a trajectory (stripping out any atoms that don't match the
       given selection), and writes a new DCD file.  Can be used to
       concatenate trajectories, pull specific frames out, as well as
       adjusting periodic box information and centering the trajectory on a
       selection.  Since trajectories are often stored in files with an
       ascending numerical sequence name (i.e. frame_1.dcd, frame_2.dcd,
       etc), and since the shell globbing doesn't sort these in numerical
       order, a command such as
    <PRE>subsetter foo model.pdb frame_*.dcd</PRE>
       will not concatenate your frames in the order you want.  You can tell
       subsetter to sort the input trajectories so that they are in numerical
       order by using the "--sort" flag.  For more detailed information, use
       the "--fullhelp" option with subsetter.

       <DT><B>traj2dcd</B>
       <DD>Converts a LOOS-supported format to a DCD.

       <DT><B>trajinfo</B>
       <DD>Similar to dcdinfo, but works with generic trajectories.  Can report
       box information and the centroid of a selection.  Useful for verifying
       trajectory header information and extracting the number of frames and
	 atoms in a trajectory.
   </DL>


   \page membranes Membrane systems
   <h2> Tools for membrane systems</h2>
   Tools specifically intended for analyzing lipid bilayers and
   related systems, found in the Tools/
   directory:


   <DL>
       <DT><B>cross-dist</B>
       <DD> Compute the probability distribution of crossing angles and
       torsions for a set of chains.

       <DT><B>crossing-waters</B>
       <DD>Loop over a trajectory and compute the number waters crossing a
       membrane.

       <DT><B>cylindrical-density</B>
       <DD>Construct the density of some membrane component around a protein,
       as a function of lateral and vertical distance

       <DT><B>cylindrical-thickness</B>
       <DD>Calculate the membrane thickness as a function of lateral distance from
       a protein

       <DT><B>density-dist</B>
       <DD>Compute the charge/electron/mass density distribution for the system
       along the z-axis. Produces the distribution for the whole system and an
       arbitrary number of selections.  Requires a structure file format which
       supplies mass and/or charge.  The newest version also has an option to
       symmetrize the density distribution in z.  This assumes that the input
       trajectory has already been set up with the membrane center at z=0.  You
       can accomplish this using merge-traj, which can optionally recenter a
       selection at every frame.  The functionality from density-dist-windowed
       has also been folded in, using the --window option.  Note: this tool can
       be used in combination with potential_profile.py to compute electrostatic
       potentials along the membrane normal.

       <DT><B>density-dist-windowed</B>
       <DD>Compute the charge/electron/mass density distribution for the
       system along the z-axis for blocks of time within a trajectory,
       producing a density distribution time series.  This is deprecated,
       since the functionality has been merged into density-dist.

       <DT><B>dibmops</B>
       <DD>Calculates molecular order parameters, binned by lateral distance
       from a target.

       <DT><B>mops</B>
       <DD>Calculates a molecular order parameter (using the principal axes
       of a selection).  Used for comparing order between coarse grained and all
       atom MD.

       <DT><B>membrane_map</B>
       <DD>Compute the distribution of a variety of membrane properties
       about a membrane properties.  Properties currently implemented include
       height, density, molecular order parameter, and average vector
       orientation.

       <DT><B>order_params</B>
       <DD>Compute the deuterium quadrupolar splitting order parameters for
       lipid molecules.  The model file must have connectivity information.
       The current version supports both 3 residues/lipid and 1
       residue/lipid topology files, and can optionally compute order
       parameters relative to the x and y axes.  In addition, a more
       careful estimate of statistical uncertainties is available using
       block averaging.

       If you wish to use block averaging to estimate the errors, we suggest
       running the tool twice: the first time will give you the block standard
       error as a function of block size, and you can read out the true
       standard error as the plateau value at large block size.  Because the
       plateau region is often noisy (since the number of blocks is getting
       small), the code offers you the ability to estimate the plateau value by
       averaging over a range of numbers of blocks.  This defaults to using the
       estimates from 2 blocks through 5 blocks, but you should check the plots
       yourself to make sure this is appropriate for your data set.  For more
       on block averaging, see the review by Grossfield and Zuckerman,
       "Quantifying uncertainty and sampling quality in biomolecular
       simulations", Annual Reports in Computational Chemistry, 2009, 5, 23-48.

       <DT><B>potential_profile.py</B>

       <DD> Compute the electrostatic potential profile along the membrane
       normal.  This program takes the output of the density-dist tool run in
       "charge" mode and returns the electrostatic potential in Volts.  The
       algorithm used here is described by Sachs, et al, J Chem Phys, 2004,
       121, 10847, and includes a correction to ensure that the electrostatic
       potential is continuous at the periodic boundary.  A typical command
       line would look like:

       density-dist --type=charge -- path/to/model-file path/to/trajectory -38 38 76 > charge-density.dat
       potential_profile.py charge-density.dat > potential.dat

       See the --fullhelp message for more details about the meaning of
       specific columns in the output.

       Note: this tool requires the python numpy extension in order to run.

       <DT><B>verap</B>
       <DD> Computes an area profile along the Z-axis by binning the structure and
       calcuating the radius of gyration (or max radius) for each bin.

       <DT><B>xy_rdf</B>
       <DD>Compute a two dimension radial distribution function in the xy plane,
       splitting the system into upper and lower leaflets.  Primarily intended
       for analyzing lateral organization of lipid-water interfaces.  Note
       that as of version 1.6.0, the command line arguments have changed
       significantly. The new version allows you control how your selection
       is split up, by residue, segment ID, or molecule (if your system
       file has connectivity).

       <DT><B>xy_rdf_timeseries</B>
       <DD>Same as xy_rdf, except producing a series of block averages rather
       than averaging over the whole trajectory.  This program is
       deprecated, because its functionality has been merged into xy_rdf.

   </DL>

    \page pca
   <h2> Principal component analysis </h2>
   Tools for performing PCA, found in Tools/.  Note: some related
   tools are also found in the network models section (\subpage enm).

    <DL>
       <DT><B>coverlap</B>
       <DD>Compute the covariance and subspace overlaps between either ENM
       results or PCA results (or any combination).  The covariance overlap
       was defined in  Hess, Phys. Rev. E, 65, 031910, 2002

       <DT><B>big-svd</B>
       <DD>Computes the SVD/PCA for a trajectory.  This differs from the
       svd below in that it uses single precision math and it computes
       fewer right singular vectors (e.g. if your structure has N atoms
       and you have T timestemps in the trajectory, then the RSV matrix
       will be T x 3N as opposed to T x T in the svd tool).  See also svd.

       <DT><B>svd</B>
       <DD>Performs principal component analysis for a trajectory using
       singular value decomposition, writing out the eigenvalues, left
       singular vectors (eigenvectors) and the right singular vectors
       (projection timeseries) as OCTAVE-formatted text files.

       <DT><B>svdcolmap</B>
       <DD>Map the magnitude of a left singular vector onto a PDB file's B-value
       column.  Useful for visualizing which portions of a molecule are mobile
       for a given SVD mode.
    </DL>


    \page other

   <h2> General purpose tools</h2>

   <DL>
     <DT><B>averager</B>
       <DD>Compute the average structure for a set of molecules from a
       trajectory, using an iterative scheme.

       <DT> <B>atomic-rdf</B>
       <DD>Compute the radial distribution function for 2 selections of
       atoms taken from a trajectory, treating each selection as a set of
       individual atoms.  For contrast, see rdf.

       <DT><B>blurrogram.pl</B>
       <DD>A PERL tool for creating "blurrogram" style figures with Pymol.

       <DT><B>bounding</B>
       <DD>Write out the bounding box for a selection of atoms from a
       structure file.

       <DT><B>cluster-structures.py</B>
       <DD>Perform clustering analysis on a trajectory using the k-means
       algorithm on the basis of RMSD.  In Packages/PyLOOS.

       <DT><B>contact-time</B>
       <DD>This tool computes the number of contacts between a probe
       selection and a set of target selections.  The output is in the
       form of a matrix and can be normalized by either total number of
       contacts (across the row) or by the maximum # of contacts per
       target (down the column).  In addition, it can automatically split
       the probe into separate molecules, based on their segids, and
       compute the inter-probe contacts as well.

       <DT><B>contacts</B>
       <DD>Loop over a trajectory and count the number of contacts between two
       sets of atoms.

       <DT><B>cylindrical-density.py</B>
       <DD> Compute a 2D radial distribution function in cylindrical
       coordinates. In Packages/PyLOOS.

       <DT><B>domain.py</B>
       <DD> Describe the motion of two selections within a single macromolecule,
       including distance and the angle and torsion formed the their first
       principal moments.  In Packages/PyLOOS.

       <DT><B>drifter</B>
       <DD>Calculates movement centroids over a trajectory

       <DT><B>exposure</B>
       <DD>Computes the degree of exposure of a set of selections over
       time.  The exposure is defined as the average density of a probe
       selection within a spherical shell about each target atom.  This
       tool can be used to determine how exposed to solvent a selection
       is, or alternatively how buried a selection is.

       <DT><B>gmxdump2pdb.pl</B>
       <DD>Converts a Gromacs/MARTINI system into a PDB and minimal
       PSF with connectivity.  Constraints (and bonds to hydrogens)
       can be added, and the connectivity for water can be inferred.

       <DT><B>helix_kink</B>
       <DD>Given two selections and a trajectory, compute the time series
       of the angle between their principal components.  Also useful for
       measuring domain hinge motions.

       <DT><B>interdist</B>
       <DD>Calculates distances between a selection and an aribtrary set of
       other selections over a trajectory.  The distance computed can be the
       distance between the centroids, the minimum distance between any atom
       in any group, or the max distance between any atom in any group.

       <DT><B>octavex</B>
       <DD>Extract embedded OCTAVE data from a LOOS output/log.  This is
       used with aligner.

       <DT><B>paxes</B>
       <DD>Computes the magnitude of the principal axes of a set of selections
       over the trajectory.  This can be used to analyze shape changes over
       time.

       <DT><B>packing_score</B>
       <DD>Computes the packing score, a measure of the contact between two
       selections, over the course of a trajectory.  Originally defined in
       Grossfield et al, PNAS, 2006, 103, 4888-4893

       <DT><B>protein_tilt.py</B>
       <DD>Compute the overall tilt of a membrane protein relative to the
       membrane normal by averaging the tilts of the individual transmembrane
       helices.  In Packages/PyLOOS.

       <DT><B>ramachandran</B>
       <DD>Computes a ramachandran map for a given selection of a specified
       range of frames in a trajectory (or all frames).  Note that some
       torsions may be missing for the residues at the ends of the
       selection.  To avoid this, expand your selection by a residue in
       both directions, then use the "--skip" flag.

       <DT><B>rdf</B>
       <DD>Computes the radial distribution function for two selections
       averagd over a trajectory.  The selections are split up by molecule
       and the center of mass is used.  For example, selecting all water
       molecules will cause it to compute the radial distribution of the
       centers of mass of individual water molecules.  For contrast, see
       atomic-rdf.

       <DT><B>rgyr</B>
       <DD>Compute the radius of gyration for a selection of atoms.
       Optionally, it can break your selection into individual molecules,
       if for example you have multiple solutes in the system.

       <DT><B>rmsd2ref</B>
       <DD>Computes rmsds between a selection and either its average
       conformation or a reference model, optionally aligning the
       selection.

       <DT><B>rmsds</B>
       <DD>Loops over a trajectory and computes the pairwise RMSDs for a
       selection of atoms.

       <DT><B>rotamer</B>
       <DD>Computes the chi-1 and chi-2 angles for a given selection over an
       entire trajectory.

       <DT><B>torsion</B>
       <DD>Given 4 selections, compute the torsion angle for their centroids.
       This program loops over a trajectory and writes the torsion angle time
       series.

       <DT><B>transition_contacts</B>
       <DD>Calculate the normalized transition between two structures over
       a trajectory.
    </DL>

    \page voronoi
    <h2> Voronoi decomposition </h2>
    A collection of tools for 2D Voronoi decomposition of slabs, presumably from a
    membrane simulation.  This package is a wrapper around the scipy (www.scipy.org)
    Voronoi class, which is itself a wrapper around QHull (www.qhull.org).  As a result,
    this package is dependent having a working install of numpy and scipy (instructions
    for installing them can be found at www.scipy.org).

    All tools assume work with a slab-like geometry oriented along the z-axis.  Within a
    slab, the system is treated as 2-dimensional.

    All tools take at least 2 selections of atoms.  The first is the set of atoms used
    to compute the Voronoi decomposition, while any other selections are subsets of those
    atoms for which areas are desired.  In all cases, these selections are application
    <B> after </B> the original selection.

    Padding: all of the tools listed have a required option called "padding".  The
    purpose of this option is to ensure that periodic boundaries are handled correctly.
    Since the underlying engine (qhull) has no knowledge of periodicity, we do this by
    replicating dummy atoms in the 8 surrounding periodic images, such that no "true"
    atoms are at the "edge".  The padding option controls how far out these padding atoms
    are generated.  If your selection for the Voronoi decomposition is all-atom or all
    heavy-atom, 15 angstroms is a good choice for the padding value.  However, if you're
    using a sparser selection (e.g. just lipid phosphates), you will probably need to
    make the padding value significantly larger, e.g. 30 ang or more.  If your padding
    value is too small, you will occasionally see absurdly large areas for individual
    atom, or the program can fail outright.

    <DL>
        <DT> <B> run_areas.py </B>
        <DD> Compute areas for different sets of atoms within a particular slice along
        the membrane normal.  Typical slice widths are 2-4 ang.

        <DT> <B> area_profile.py </B>
        <DD> Compute the voronoi cross-sectional area for something (e.g. a protein)
        through the membrane.

        <DT> <B> area_per_molecule.py </B>
        <DD> Compute distribution of areas/molecule for a z-slice.  Note: this program
        requires a system file that contains connectivity information (e.g. a PSF file).
   </DL>


    \page user
     <h2> User-created tools</h2>
   Create your own tools in Packages/User/.  Currently contains
   a number of templates for different kinds of apps.

*/


namespace loos {

/*! \page new_pyloos What's new in PyLOOS

PyLOOS has undergone some substantial changes in LOOS 2.3.0.  The
top-level module/namespace remains "loos", and it includes everything
imported from the core of LOOS.  We have added a new "pyloos" module
under "loos" that now holds Python-specific code, such as the new
trajectories classes.

One of the biggest changes in PyLOOS is the introduction of three new
trajectory classes.  These classes ultimately wrap loos Trajectory
objects but provide more python-like interfaces.  The first class is
\ref loos::pyloos::trajectories::Trajectory "loos.pyloos.Trajectory".
You can specify a stride and the number of
frames to skip from the start of the trajectory.  The trajectory
object can then be used like a python iterator,
\code{.py}
model = loos.createSystem('foo.pdb')
traj = loos.pyloos.Trajectory('foo.dcd', model, skip=50)

for frame in traj:
    print frame.centroid()
\endcode

You can also use the trajectory like an array,
\code{.py}
first_frame = traj[0]
last_frame = traj[-1]
\endcode

There is often a need to know what frame number a frame corresponds
to.  If you are using the trajectory
as in iterator, then the
\ref loos::pyloos::trajectories::Trajectory::realIndex "realIndex()"
function will return the frame
number,
\code{.py}
for frame in traj:
    print traj.realIndex(), frame.centroid()
\endcode

Since you can specify a skip and a stride, an array index does not
necessarily give you the real frame number.  Instead, use the
frameNumber() member function.  For example,
\code{.py}
frame = traj[0]    # This is actually frame index 50 in the
                   # trajectory because of the skip

print traj.frameNumber(0)  # This prints out 50
\endcode

Another thing to be careful of is the linkage between groups through
the shared atoms.  By default, the frame returned will share atoms
with whatever group was used to instantiate the trajectory.  If you
need to decouple the trajectory from the model, pass a copy to the
constructor,
\code{.py}
traj = loos.pyloos.Trajectory('foo.dcd', model.copy())
\endcode

The other two trajectory classes,
\ref loos::pyloos::trajectories::VirtualTrajectory "VirtualTrajectory"
and
\ref loos::pyloos::trajectories::AlignedVirtualTrajectory "AlignedVirtualTrajectory"
let you combine multiple pyloos trajectory
objects to make one big "virtual" trajectory.  The latter supports the
LOOS iterative alignment method and will return the aligned frames.
Note that this does require reading in the alignment subset and
aligning it at the first access to a frame, so there may be memory and
performance penalties.  The cached frames are discarded after the
alignment however.  Also, the
\ref loos::pyloos::trajectories::AlignedVirtualTrajectory "AlignedVirtualTrajectory"
can be used
with a single
\ref loos::pyloos::trajectories::Trajectory "loos.pyloos.Trajectory"
to align it.

All of these classes have rich support for accessing the underlying
components and getting information about what frame is being used,
among others.  For more information, see the above links, use the
search bar, or see the documentation for pyloos under the Namespace
tab.

In addition to the new trajectories, pyloos now sports several utility
functions related to ensembles:
\ref loos::pyloos::ensembles::averageStructure "loos.pyloos.averageStructure()",
\ref loos::pyloos::ensembles::extractCoords "loos.pyloos.extractCoords()",
and
\ref loos::pyloos::ensembles::svd "loos.pyloos.svd()",
all of which use the new Trajectory classes.  We have also
added
\ref loos::pyloos::subspace::subspaceOverlap "loos.pyloos.subspaceOverlap()",
and
\ref loos::pyloos::subspace::covarianceOverlap "loos.pyloos.covarianceOverlap()".


The iterative alignment functions have also changed.  There is now a
\ref loos::pyloos::alignment::iterativeAlignment "loos.pyloos.iterativeAlignment()"
function that will take a
\ref loos::pyloos::trajectories::Trajectory "loos.pyloos.Trajectory"
and align it (or a list/vector of loos::AtomicGroup).  The
loos-style interface is now available through
\ref loos::pyloos::alignment::iterativeAlignTrajectory "loos.pyloos.iterativeAlignTrajectory()".
You can optionally pass a
list of frame indices to use.  Both functions now return a Python
tuple containing the results.

Finally, AtomicGroup now has support for NumPy with the
AtomicGroup::getCoords() and AtomicGroup::setCoords() functions, which
will return (or set) the coordinates of all atoms in the group.  For
example, calculating an average set of coordinates can be implemented this way:
\code{.py}
avg = numpy.zeros(len(traj.frame), 3)
for frame in traj:
    coords = frame.getCoords()
    avg += coords
avg /= len(traj)
\endcode

*/
};


namespace loos {

/*! \page exceptions Exceptions in LOOS and PyLOOS

As of LOOS 2.2.0, how LOOS uses exceptions has changed significantly.
This will probably not affect user code that relies on
uncaught exceptions to terminate with an error, with a few exceptions
(no pun intended).

In general, exceptions thrown by LOOS will derive from the LOOSError
class, which in turn derives from std::exception.  In cases where it
would be more appropriate to return a standard exception, such as
std::range_error from the operator[], LOOS will throw that instead.

The exceptions you are most likely to encounter are FileError and
derived classes.  These cover errors while reading and writing the
various model and trajectory formats.  The FileOpenError is associated
with a problem opening the file (e.g. missing file or incorrect
permissions).  The FileReadError covers any number of errors while
reading from a file.  Since some classes (such as trajectory classes
and most model classes) read from the file as part of instantiation,
this exception may occur during the "opening" process.  The
FileReadErrorWithLine exception comes from classes that track the
lines read and will report where in the file the error occured.
Finally, the FileWriteError covers any error while writing to a file.

Once an exception has been thrown, expecially for the model and
trajectory classes, the internal state of the object that threw is
undefined.  For example, suppose you are reading from a DCD and a
FileReadError occurs.  That DCD object should not be used again after
the exception occured.


Changes Compared to pre-2.2.0 LOOS
----------------------------------

The primary external change in LOOS-2.2 is that selectAtoms() will no
longer throw an exception if no atoms are selected.  Instead, it will
return an empty AtomicGroup.

There are two major internal changes to how exceptions are handled
compared to earlier versions of LOOS.  Previously, the standard
exceptions were more liberally used (e.g. std::runtime_error,
std::logic_error, etc).  Most exceptions that come from LOOS are now
derived from LOOSError.  Related to this, the exceptions that LOOS can
throw have been streamlined.

The second major change is that the set of exceptions in LOOS have
been flattened and placed in the loos namespace.  Some classes defined
exceptions that were specific to that class.  These have either been
flattened (e.g. are now in the loos namespace) or have been replaced
with more general LOOS exceptions.


Translating Exceptions to PyLOOS
--------------------------------

In most cases, Swig will convert the exceptions thrown by LOOS into
the Python equivalent, or into the wrapped version of the LOOS
exception.  You can call the LOOSError::what() function to get the
error string.  Alternatively, the __str__() method is defined for all
LOOS exceptions that are translated into Python.

The following illustrates catching PyLOOS exceptions...
\code{.py}
try:
     model = createSystem(filename)
except loos.LOOSError as e:
     print 'HELP!  There was a problem reading the model...'
     print e.what()
\endcode




While we have tried to ensure that exceptions that can be thrown by
LOOS will be caught and translated for Python, it's possible that a
few have been missed.  Any exception not properly caught before it
reaches Python will result in the Python interpreter exiting.  If you
find this happening, please file a bug report or email the developers
at loos.maintainer [at] gmail.com


*/
};


namespace loos {

/*! \page changes Change Log
\section release233 Version 2.3.3 (unreleased)
\subsection r233_bugs Bug Fixes
<ul>
  <li> Fixed bug in effsize.pl affecting some Linux distros
  <li> Fixed bug affecting PyLOOS aligning routines
  <li> Fixed bug in rmsd_to_average.py
  <li> Fixed bug in doxygen handling causing excessive docs rebuilding
  <li> Fixed bug in area_profile.py
</ul>

\subsection r233_add_changed Added, Changed, and Otherwise Notable
<ul>
  <li> Added periodicity support to native contacts
  <li> Added new lipid_survival tool
</ul>

\section release232 Version 2.3.2 (7-8-2016)
\subsection r232_bugs Bug Fixes
<ul>
  <li> Added HSD, HSE, and HSP as recognized residues for backbone selector
  <li> Fixed bug in center-molecule affecting --center_xy
  <li> Fixd bug in fullhelp for serialize-selection
  <li> Fixed bug in aligner where --xyonly was ignored if using a reference structure
  <li> Fixed bug in membrane_map when using a reference structure
  <li> Fixed bug in PyLOOS that made XTCWriter unavailable
  <li> Fixed bug in density-dist when using the number calculation
  <li> Fixed bug in Amber prmtop reader that affects Ubuntu 16
</ul>

\subsection r232_add_changed Added, Changed, and Otherwise Notable
<ul>
  <li> Changed the organization of LOOS source tree so that the core library
       resides in the src/ directory.
  <li> Changed how documentation is built (now automatic for GitHub users)
  <li> Added support for unpacking pre-built docs from tarball in top-level LOOS dir
  <li> Added inside_helices.py tool to PyLOOS
  <li> Added --positive and --negative flags to enmovie to control which direction motion is depicted
  <li> Added ability to write Gromacs .gro files
  <li> Added new cylindrical-thickness tool
  <li> Added verap tool for quick vertical area profiles (non-voronoi)
  <li> Added (officially) the functions in utils_structural.cpp to PyLOOS
  <li> Added support for manually specifying the mapping of molecule names to segid
             in gmxdump2pdb tool
</ul>



\section release231 Version 2.3.1 (1-11-2016)
\subsection r231_bugs Bug Fixes
<ul>
  <li> Fixed bug in membrane_map causing aligned coordinates to be squashed
       into the x-y plane.
  <li> Fixed bug affecting center-molecule with --center_xy
</ul>

\subsection r231_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Documentation improvements
</ul>

\section release230 Version 2.3.0 (11-20-2015)
\subsection r230_bugs Bug Fixes
<ul>
  <li> Fixed bug in periodicity handling where it could appear to be
       set but have default values.
  <li> Fixed bug affecting reading of Charmm CRD files
  <li> Fixed bug in xf_rdf where the sel1-spans, sel2-spans, and reselect flags
       were ignored
  <li> Fixed handling of DEBUG in setup scripts
</ul>
\subsection r230_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Changed: BOOST threads is now required for build
  <li> Changed: NumPy now required for PyLOOS build

  <li> Added 'index' keyword to selection language to use an atom's
       position in a model (different from atom id)

<li> (PyLOOS) Changed splitByMolecule(), splitByUniqueSegid(), and SplitByResidue()
       to return a python list of AtomicGroup rather than an AtomicGroupVector
  <li> (PyLOOS) Changed iterativeAlignment() function to now return a Python tuple
       and works with new loos.pyloos trajectories
  <li> (PyLOOS) Added iterativeAlignTrajectory() to align with plain LOOS trajectory
       objects (as well as loos.pyloos), and accepts an optional list of frames to use.
  <li> (PyLOOS) Added
  <li> (PyLOOS) Deprecated iterativeAlignmentPy()
  <li> (PyLOOS) Added k-means clustering tool (cluster-structures.py)
  <li> (PyLOOS) Added ensemble and SVD support
  <li> (PyLOOS) Reorganized PyLOOS (into loos and loos.pyloos)
  <li> (PyLOOS) Added support for NumPy
  <li> (PyLOOS) Added voronoi package
  <li> (PyLOOS) Added new cylindrical-density.py tool

  <li> Changed trajinfo so that it ALWAYS scans frames and can handle read errors (using
       only the first set of valid frames)
  <li> Changed order_params tool to support ranges for frames to use
  <li> Changed AtomicGroup::superposition() to use the faster dgesvj().
	Note: this is an iterative method that may not converge.  In
	practice, the residual will be small if it does not.  LOOS will
	print out a warning in such cases.  If you find many warnings
	being issued, contact the LOOS developers.
  <li>  Changed RMSD to use a much faster method (and removed option to disable caching).
        In addition, can now run in a multithreaded mode
  <li>  Moved alignment-related code to its own source module
  <li>  Added AtomicGroup::centrifyByMolecule() and AtomicGroup::centrifyByResidue()


</ul>

\section release225 Version 2.2.5 (4-22-2015)
\subsection r225_bugs Bug Fixes
<ul>
  <li> Fixed handling of non-netCDF Amber files when buildind LOOS with netCDF support
  <li> Fixed reading of Amber prmtop files with mixed case format specifiers
  <li> Fixed bug in merge-traj that required downsampled dcd filename
  <li> Fixed bug in fcontacts resulting in NaN's in output if there are no
       target atoms near the probe.
  <li> Fixed fullhelp in subsetter
  <li> (PyLOOS ONLY) Fixed bug in GCoord operator overloads
</ul>
\subsection r225_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added new --ref-structure option to membrane_map
  <li> Added support for sorting trajectory files numerically in merge-traj (as subsetter does)
  <li> Changed the default sort regex for merge-traj and subsetter to sort an the LAST number
       in the filename
  <li> Added ".netcdf" as a recognized suffix for Amber files
  <li> Changed default selection for SVD and ENM tools to alpha-carbons
  <li> Changed options and behavior of porcupine and enmovie.  See their fullhelp
       for more details
  <li> Added optional NAMD tag to PSF files generated by gmxdump2pdb

</ul>

\section release224 Version 2.2.4 (2-6-2015)
\subsection r224_bugs Bug Fixes
<ul>
  <li> Fixed reading of Amber prmtop files that use mixed case for format specs
  <li> Fixed handling of non-NetCDF Amber files when built with NetCDF support
</ul>


\section release223 Version 2.2.3 (1-26-2015)
\subsection r223_bugs Bug Fixes
<ul>
  <li> Fixed bug affecting functions in Atom, Coord, and Matrix44 that return
       references to contained data.  They now return const refs and should
       no longer be wrapped by swig, returning the contained value instead.
  <li> Improved error handling in the build system
</ul>


\section release222 Version 2.2.2 (1-17-2015)
\subsection r222_bugs Bug Fixes
<ul>
  <li> Fixed bug in Amber parmtop reader
  <li> Fixed problem building with MacOS
</ul>

\section release221 Version 2.2.1 (1-13-2015)
\subsection r221_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added --upper-only and --lower-only options to membrane_map
  <li> Changed how mops and dibmops split the selection to get molecules
       (and added an option to force splitting by residue)
  <li> Added support to mops for writing the average molecular order parameter
       as a time-series
  <li> Removed gridify() and dcd_utils.cpp
  <li> Changed the build system
</ul>

\section release220 Version 2.2.0 (12-24-2014)
\subsection r220_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added AtomicGroup::contactWith() that returns true or false if
       two AtomicGroups have any contacts between them.
  <li> Added support for retrieving time and step from frames of XTC files
  <li> Added support for estimating DCD-style timestep for XTC files
  <li> Added spliteFilename() utility
  <li> Added Trajectory::description(), returning a string describing the format
  <li> Added TrajectoryWriter base class to support writing multiple
  trajectory formats.  The interface is intentially simple.  For more
  control, explicitly use a supported format.
  <li> Added XTCWriter class for writing Gromacs XTC files (based on
  xdrfile-lib from Gromacs).
  <li> Added createOutputTrajectory() factory function
  <li> Added OutputTrajectoryOptions class
  <li> Added a static create() function to all trajectory and system
  classes (returns a boost shared pointer to a new instance of the
  appropriate class)
  <li> Changed DCDWriter to inherit from TrajectoryWriter
  <li> Changed how the system and trajectory factory functions work.
  They are now table driven and utilize the static create() function.
  <li> Changed how available file formats are listed (as a
  newline-delimited list for use in ProgramOptions, rather than a more
  compact comma-delimited list)
  <li> Changed subsetter and merge-traj to use new OutputTrajectory class.
  <li> Changed DCDWriter::framesWritten() to return an unsigned int
  instead of a signed int.
  <li> Added BackboneSelector for proteins and nucleic acids.  Note that
  this will only work for known residue and atom names (see Selector.cpp).
  Will also select hydrogens attached to backbone atoms.
  <li> Added "backbone" keyword to selection language
  <li> Changed PDB reader so that missing fields (to the right of coordinates)
  will issue a warning and then be ignored.
  <li> Added functions to PDB to report whether fields are missing or not
  <li> Added OMG (the Optimal Membrane Generator)
  <li> Changed/Added exception classes and handling, particularly for PyLOOS
  (see \ref exceptions) for more details.
  <li> Changed selectAtoms() to return an empty AtomicGroup when no atoms are
  selected, rather than throw an exception.
  <li> Changed AtomicGroup::groupFromID() so that missing atoms are ignored,
  rather than throw an exception.
  <li> Removed all char* based constructors in favor of string&
  <li> Changed how the Swig interface is generated (from the CPP header files directly)
  <li> Deprecated gridify() in dcd_utils.cpp
  <li> Added --clip flag to smooth-traj to control whether the ends of the trajectory
  are clipped or not
</ul>
\subsection r220_bugs Bugs Fixed
<ul>
  <li> Fixed bug in aligner causing incorrect output when using a skip, stride, or
some ranges of frames.
  <li> Fixed bug in smooth-traj that dropped frames at the end of the trajectory
</ul>



\section release213 Version 2.1.3 (7-18-2014)
\subsection r213_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added two new tool for molecular order parameters: mops and
       dibmops.  The former computes an average molecular order
       parameter for a set of trajectories, while the latter bins
       the order parameter based on lateral distance to the nearest
       target (e.g. lipopeptide)
  <li> Added chist tool for calculating cumulative or windowed histograms
  <li> Added support in merge-traj for separate selections to recenter in xy and z
  <li> Added number density option to density-dist
  <li> Added "core" water filter for density tools
  <li> Added --threshold option to interdist that will segment the output based
       on the given cutoff
  <li> XForm::rotate() will throw an exception now if the rotation
  axis has zero length
</ul>

\subsection r213_bugs Bugs Fixed
<ul>
  <li> Bad HTML code in docs fixed
  <li> Fixed crashing of phasepdb with default settings
  <li> Fixed bad execution time estimate when using rmsds to compare two different trajecties
  <li> Fixed bug in TRR/XDR support affecting double precision data (found by Pin-Kuang Lai)
  <li> Fixed build issue when ATLAS_LIBS is specified
  <li> Fixed help in dcdinfo
  <li> Fixed crash in phasepdb caused by using default chunk-size
  setting
  <li> Fixed bug in rebond where atoms would end up bound to themselves
</ul>




\section release212 Version 2.1.2 (2-14-2014)
\subsection r212_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added new feature to xy_rdf (--reselect) to handle case where
       molecules move back and forth between leaflets
</ul>

\subsection r212_bugs Bug Fixes
<ul>
  <li> Fixed bug where PyTraj.py was not installed
  <li> Fixed bug affecting AmberTraj::updateGroupCoords() [mdcrd files]
       resulting in a segfault.
</ul>

\section release211 Version 2.1.1 (1-31-2014)
\subsection r211_add_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added new packing_score tool to quantify the packing between
       two selections over the course of a trajectory
  <li> Added PyTraj and PyAlignedTraj for Python iteration through
       a Trajectory in PyLOOS
  <li> Added support for OpenSUSE 13 and Fedora 20
  <li> Changed GCoord, AtomicGroup, TimeSeries, and Matrix44 to
       be iterable in Python
</ul>
\subsection r211_bugs Bug Fixes
<ul>
  <li> Fixed bug in drifter preventing it from running
  <li> Fixed bug in parseStringAs<> that can affect shortened
       fields at the end of a line.
  <li> Fixed bug in protein_tilt.py where the average vector
       wasn't reset upon successive frames
  <li> Fixed bug in rmsds tool there the average RMSD reported
       was under-valued
  <li> Fixed build issue with MacOS 10.9
</ul>

\section release210 Version 2.1.0 (12-6-2013)
\subsection r210_add_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Substantial change to build system.  See INSTALL file or
  \subpage building
  <li> Test suite is now deprecated and has been removed
  <li> Changed how atomid's are handled in LOOS.  They are no longer
  indices into the trajectory frame for atom coordinates.  Atoms now
  have an "index" property for that purpose.  The index is
  automatically set when reading a model from a file.
  <li> Changed all Trajectory::updateGroupCoords() implementations to
  honor the atom index property.
  <li> Changed Trajectory::updateGroupCoords() to use the NVI idiom.
  Derived classes should override the updateGroupCoordsImpl()
  function.
  <li> Added Math::eigenDecomp() that calculates eigenpairs (using
  ssyev/dsyev)
  <li> Added gnm-traj and anm-traj tools in the ENM Package for
  analyzing trajectories using ENM's
  <li> Added BasicSplitBy option.  Use BasicSplitBy::split() to split
  an AtomicGroup based on a user-specified method
  <li> The rmsds tool will now cache the trajectory for improved
  performance.  Caching can be disabled for large systems
  <li> Added smooth-traj tool
  <li> Added new membrane_map tool to compute the 2D distribution of
  various physical properties around a membrane protein
  <li> The Matrix bracket operators '[]' will only check for out of
  bounds indices if debugging is turned on while compiling LOOS.
</ul>
\subsection r210_bugs Bug Fixes
<ul>
  <li> Fixed bug in SVD tool where some command line options would
  incorrectly fail with an options error.
</ul>

\section release206 Version 2.0.6 (9-13-2013)
\subsection r206_bugs Bug Fixes
<ul>
  <li> Fixed bugs in DCD reading code affecting trajectories that have
  a zero frame-count.
  <li> Fixed bug in setup.csh script affecting path to user package
  tools.
  <li> Fixed bugs in gmxdump2pdb.pl:
    <ul>
      <li> No longer users hybrid-36 encoding for PSF file
      <li> Correctly handles moltype in topology (systems where
	molecule segments were repeated in the topology would cause
	errors, e.g. bilayers where each leaflet is a separate
	segment).
    </ul>
  <li> Fixed fringe bug in coverlap tool where ENM-generated
  eigenpairs would not load in older RedHat Enterprise installs.
  <li> Fixed hierarchy so that it catches bad input and issues an
  error rather than segfaults.
  <li> Fixed several tools to catch errors when opening files.
  <li> Fixed bug in serialize-selection where the output molecules
  were interleaved rather than being in a contiguous block (see
  ChangeLog for more details)
  <li> Fixed bug affecting XTC trajectories with 9 or fewer atoms
  <li> Fixd bug in phase-pdb causing incorrect bonds when using
  --chunk and --row options
</ul>

\subsection r206_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added fixdcd tool to fix the DCD header (in-place) with the
  correct number of frames in the trajectory.
  <li> Added support for disambiguating sign of PCA vectors in
  cross-dist.
  <li> Added link to tutorial on LOOS
  <li> Added protein_tilt.py tool to PyLOOS.
  <li> Added .nc and .crd as Amber format for trajectory files
  <li> Changed installation to include python scripts if pyloos is
  being built
  <li> Changed transition_contacts to add a --smoothed-transition
  option, smoothing the contact matrix when a contact is near the
  cutoff.  This is now the default behavior.  See the associated
  --fullhelp for more details
  <li> Changed default exponential spring constant in ENMs to -0.5
</ul>

\section release205 Version 2.0.5 (6-19-2013)
\subsection r205_bugs Bug Fixes
<ul>
  <li> Fixed bug in gmxdump2pdb.pl affecting systems with >= 100k atoms
  <li> Fixed bug in native_contacts causing the last residue in
  selection to be handled incorrectly.
  <li> Fixed bug in pyloos.selectAtoms() so that it throws a LOOS
  exception on error.
</ul>

\subsection r205_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Changed StreamWrapper, Trajectory (and derived classes), and
  all structure classes to take an istream object in the constructor rather
  than an ifstream.
  <li> Added HBondDetector class as part of core LOOS
  <li> Added LOOS exceptions to PyLOOS
  <li> Added fcontacts tool that, in most cases, should replace
  contact-time.
  <li> Added/changed options to native_contacts
  <li> Changed renum-pdb so connectivity is preserved
  <li> Changed setup scripts to prepend paths rather than append
  <li> Changed averageStructure() and iterativeAlignment() functions
  that take a Trajectory object so that they do not cache frames
  <li> Changed aligner and rmsd2ref tools so that they do not cache frames
  <li> Added --xyonly option to aligner
  <li> Added serialize-selection tool
  <li> Added transition_contacts tool
</ul>


\section release204 Version 2.0.4 (4-3-2013)
\subsection r204_bugs Bug Fixes
<ul>
  <li> Fixed build issue with Boost 1.52+
  <li> Fixed issue associated with regenerating the parser
  <li> Fixed bug in area_per_lipid where it ignored the --skip option
  <li> Fixed error in documentation for subsetter
  <li> Fixed performance issue when writing PDB files with CONECT
       records that contain a lot of atoms
  <li> Changed PSF reader to NOT use hybrid-36 encoding (would break
       for large systems and is unnecessary for PSF files)
</ul>

\subsection r204_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Changed build protocol for PyLOOS.  To build PyLOOS along with
       the rest of LOOS, use "scons pyloos=1".  To install everything
       along with PyLOOS, use "scons pyloos=1 install"
  <li> Added support for building PyLOOS in MacOS (note: still in beta-release)
  <li> Added "chainid" keyword to selection language
  <li> Added --assign option to ramachandran for a rough secondary structure assignment
  <li> Added --brief option to area_per_lipid
</ul>


\section release203 Version 2.0.3 (2-1-2013)
\subsection r203_bugs Bug Fixes
<ul>
  <li> Fixed big in CHARMM CRD reader where the segid wasn't set
  <li> Fixed errors in help messages
  <li> Fixed bug in PSF reader when reading a file that came from windows
  <li> Fixed bug in AtomicGroup::AtomicGroup(const int n) constructor
       found by H. Elgabarty.
  <li> Fixed build for OpenSUSE and Ubuntu 8.04 LTS
</ul>

\subsection r203_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added support for AMOEBA Amber prmtop files
  <li> Added Amber::title()
  <li> Added support for handling basic fortran formats within Amber
       files (i.e. data format is no longer hard-coded)
  <li> Improved error messages when parsing Amber prmtop files
  <li> Added support for NetCDF formatted Amber trajectories
  <li> Changed AtomicGroup::splitByUniqueSegid() so that the
  AtomicGroup's returned are in the order the segids appear in the
  source group.

  <li> Added LineReader base class for reading lines from a file.
  Handles removal of comments and tracking of line numbers for
  errors.  Amber prmtop reader now uses this, as does readVector<T>().

  <li> Added AtomicGroup::atomOrderMapFrom() to map the order of atoms
  in one group into another.  This is for "edge" cases such as when
  psfgen reorders the atoms within a residue.  See the full changelog
  or source code for details.

  <li> Added AtomicGroup::copyMappedCoordinatesFrom() to find the
  mapping of atoms from one group into the current one and use this to
  correctly copy the coordinates.  See AtomicGroup::atomOrderMapFrom()
  for more information.

  <li> Changed water-hist to now include the water-filter bounds when
  calculating grid size.

  <li> Changed gridgauss options to permit more control over the
  smoothing kernel (note: old invocation will no longer work)

  <li> Added gridautoscale to normalize grid densities such that bulk
  water is 1.0 (only for membrane systems with Z along the membrane
  normal)

  <li> Ramachandran tool only uses spaces in output, not tabs and
  spaces

  <li> Added some support functions to Simplex
</ul>


\section release202 Version 2.0.2 (8-21-2012)
\subsection r202_bugs Bug Fixes
<ul>
  <li> Fixed bug in PDB reader where bonds were not made symmetrical
  unless they were explicitly so in the PDB file (i.e. a bond from X
  to Y did not imply Y bound to X).
  <li> Fixed a bug when using << to write a PDB file with bonds.  The
  underlying PDB would be sorted after it was written.  Now the PDB is
  const and will not change.
  <li> Fixed a bug when writing PDB files with bonds where every bond
  was explicitly written into the CONECT records.  Now, only the
  unique bonds are written (i.e. a bond from X to Y will appear in a
  CONECT record, but not Y to X).
</ul>

\subsection r202_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Changed model-select to now require the "--selection" option to
  specify a subset.  A "--splitby mode" option has been added where
  mode can be residue, segid, molecule, or name.  This will split the
  subset and each resulting AtomicGroup written out.
</ul>

\section release201 Version 2.0.1 (8-6-2012)
\subsection r201_bugs Bug Fixes
<ul>
  <li> AtomicGroup::superposition() will now throw an error if the
  superposition is indeterminate.
  <li> Fixed a bug in water-inside and water-hist that can cause the
  radius filter to segfault
  <li> Fixed normalization bug in the cumulative column of xy_rdf
  <li> Removed --center option in aligner since it is no longer
  necessary and it can lead to unintended translations in the output.
</ul>

\subsection r201_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added "hcontacts", a tool for tracking intra- and
  inter-molecular hydrogen bonds in a trajectory.
  <li> Added "hoccupancies.pl", a tool for computing occupancies from
  hcontacts and hmatrix output.
  <li> Atoms can now be compared in PyLOOS
  <li> Major change in how the Atom::bondsbit is handled.  If a file
  is read that supports connectivity (e.g. a PSF or a PDB with CONECT
  records), then the bondsbit will be set for all atoms, regardless of
  whether or there are bonds actually present for a given atom.
  Additionally, Atom::getBonds() will now return an empty vector in
  this case rather than throwing an error.
  <li> Added gmxdump2pdb.pl, a PERL program that takes the output from
  gmxdump and creates a PDB and a "fake" PSF file representing the
  structure and its connectivity.
</ul>

\section release200 Version 2.0.0 (5-2-2012)
\subsection r200_bugs Bug Fixes
<ul>
  <li> Fixed bug in subsetter when using a subset of a model that
  resulted in incorrect connectivity being written out.
  <li> Fixed bug in averager regarding the default selection to
  average over.
  <li> Fixed bug in blurrogram.pl where it would incorrectly call
  trajinfo.
  <li> Fixed bug in aligner when alignment and transformation subsets
  are not the same and auto-centering is turned on.
  <li> Fixed documentation for AtomicGroup::within() to say that
  A.within(x, B) returns atoms from A that are within x Angstroms of
  any atom in B.
  <li> Fixed bug in GROMACS TRR trajectories where natoms() could
  return erroneous sizes (only after instantiating the object and
  before any frames had been explicitly read).
  <li> Fixed bug in GROMACS TRR trajectories where
  TRR::updateGroupCoords() could possibly fail if updating a small
  subset.
  <li> Fixed bug in PDB output when the REMARKS lines contained
  embedded newlines.  These are now stripped.
  <li> Fixed bug in rmsd2ref where warnings would always be issued
  regardless of whether a target was specified or not.
  <li> rotamer now automatically splits the selections into residues.
  There is a potential bug in rotamer if a selection contains multiple
  residues and for some, a rotamer calculation is not possible.  The
  tool will select atoms by name from the set of residues and use the
  first one found to calculate the torsions.

</ul>
\subsection r200_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> <B><I>Beta-release of the Python interface to the core LOOS</I></B>
  <li> Changed eye() and submatrix() to be templated functions
  <li> Restored original behavior of density-dist tool (the first
  selection is always "all") and zero or more selections are permitted
  on the command-line
  <li> Added potential_profile.py tool that uses the output from
  density-dist, run in "charge" mode, to compute the electrostatic
  potential profile
  <li> Added flags to xy_rdf to handle the case where a selection
  should be treated as appearing in both leaflets (e.g. a
  transmembrane helix)
  <li> Changed parseRange<> implementation to reflect how
  Octave/Matlab handle negative step sizes for counting backwards.
  Improved validation of inputs.
  <li> Added cross-dist tool to compute distribution of crossing
  angles and torsions for chains.
  <li> Changed traj2pdb to use a printf-style output name template
  <li> Refactored utils.hpp into utils_random, utils_structural, and
  utils.  loos.hpp includes all utils headers, so no tools require
  changes
  <li> Improved AtomicGroup::within() performance and added support
  for periodicity
  <li> The following tools are deprecated: model2matlab, svdcolmap,
  dumpmol, center-model, density-dist-windowed, xy_rdf_timeseries
  <li> Added --fullhelp support in most tools and improved help output
  for the rest
</ul>

\section release175 Version 1.7.5 (2-24-2012)
\subsection r175_bugs Bug Fixes
<ul>
  <li> Fixed bug in porcupine
  <li> Fixed bug in merge-traj that sometimes caused it to not merge all frames
  <li> Fixed bug affecting all grid tools (stored metadata in grid output) when
       any tool option includes a newline.  This would typically occur in selection
       strings.
  <li> Fixed bug in molshape where some command line options were ignored
</ul>
\subsection r175_added_changed Added, Changed, or Otherwise Notable
<ul>
  <li> Added more help information for various density tools (see --fullhelp)
  <li> Changed the system and trajectory factory functions to allow
       an explicit file-type to be passed.  For many tools, you can now
       explicitly set the file-type from the command-line as well.  See
       the tool --help for more information.
  <li> The rmsds tool was largely rewritten.  It can now compare either a
       single trajectory with itself or another trajectory.  The iteratively-
       aligned mode has been removed.
</ul>
\section release174 Version 1.7.4 (12-23-2011)
\subsection r174_bugs Bug Fixes
<UL>
  <LI> Fixed bug in AtomicGroup::maxResid() that gave erroneous
  results (found by Ben Reynwar).
  <LI> Fixed AtomicGroup::splitByResidue() so that it preserves the
  periodic box information in the split residues.
</UL>
\subsection r174_added_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Changed AtomicGroup::splitByMolecule() to be a const function
  (internally, it makes a copy of the current group prior to
  splitting).
  <LI> Changed subsetter so that connectivity is preserved (as best it
  can be) when extracting a subset from a trajectory.
  <LI> Added a "radius" water-filter for the density tools.  This
  selects waters that are within a given radius of any specified
  protein atom.
  <LI> Added an optional bool argument to AtomicGroup::radius() that
  tells radius to use the coordinates of the first atom rather than
  the centroid of the group.
</UL>

\section release173 Version 1.7.3 (12-12-2011)
\subsection r173_bugs Bug Fixes
<UL>
  <LI> Fixed bug in decorr_time causing it to not generate output
  <LI> Fixed bug in order_params where not spcifying the ba_last
  option caused it to be improperly set.
  <LI> Fixed bug in effsize.pl where the random number seed value was
  not correctly used.
  <LI> Fixed bug in density-dist where the time-series was always
  written.
  <LI> Fixed bug in PDB reader affecting DOS-formatted PDB files with
  CONECT records.
  <LI> Fixed bug in subsetter where the --verbose flag was ignored
  <LI> Fixed bug in XTC::updateGroupCoords() when passed a group
  smaller than the trajectory frame (found by Ben Reynwar).
  <LI> Fixed bug where radial distribution tools would operate without
  periodic box information.  Now, either the model or the trajectory
  must have periodic box information to run.
</UL>
\subsection r173_added_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Added a new tool to compute a residue-contact "heat map".
  <LI> Added new option to merge-trj (selection-is-split) to more
  robustly handle the case where the centering selection is split
  across an image boundary.
  <LI> Added an "--any" mode to hcorrelations to compute the
  time-correlation for whether there is *any* hydrogen bound, rather
  than a specific hydrogen.
  <LI> Added Atom::atomType() to support tinkerXYZ atom type info
  <LI> Default spring constant for exponential springs was changed to
  -6
  <LI> xy_rdf will write out 0's rather than NaN's if there are not
  atoms in a leaflet.
  <LI> AtomicGroup::splitByMolecule() will now skip over missing bonds
  rather than throw an exception.
  <LI> All header CPP guards now have "LOOS_" as a prefix,
  i.e. "LOOS_ATOM_HPP" rather than "ATOM_HPP"
  <LI> Changed the PDB reader so that reading large PDBs with CONECT
  records is significantly faster.
</UL>


\section release172 Version 1.7.2 (8-5-2011)
\subsection r172_bugs Bug Fixes
<UL>
  <LI> Fixed bug in xy_rdf causing "by-molecule" split-mode to fail in
  some cases.
  <LI> Fixed bug caused by certain older versions of BOOST where
  similar command-line option names would cause an error
  (e.g. --center and --center_xy in the center-molecule tool)
  <LI> Fixed bug in density-dist-windowed and rgyr where the first
  frame of the trajectory would be skipped if no explicit skip was
  given on the command-line
  <LI> Fixed bug in water-hist that caused a corrupted grid to be
  written out
  <LI> Fixed bugs in command-line handling for contained, blobid, and
  pick_blob
  <LI> Fixed bug in avgconv that would fill up memory if the
  trajectory was too small
  <LI> Fixed bug in gridslice tool that either transposed the output
  matrix or crashed the tool
  <LI> Fixed bug in xy_rdf and rdf tool where there was no default
  split-mode (despite the help saying there was)
</UL>
\subsection r172_added_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Added a --brange option to water-hist to take the bulk water
  estimate from a Z-slice
  <LI> Performance optimization in rdf tool
  <LI> Changed how the build-date is handled.  It is now placed in a
  source file, so building LOOS on a new day will only involve
  recompiling that file and relinking all tools (as opposed to
  recompiling EVERYTHING).
</UL>


\section release171 Version 1.7.1 (7-26-2011)
\subsection r171_bugs Bug Fixes
<UL>
  <LI> Fixed bug in the rdf tool that incorrectly processed the
  command-line arguments, preventing it from running.
  <LI> Fixed an issue in rdf, atomic-rdf when using long
  trajectories.
</UL>

\section release170 Version 1.7.0 (7-18-2011)
\subsection r170_bugs Bug Fixes
<UL>
  <LI> Fixed bug in avgconv where the default block-sizes would cause
  a segfault.
  <LI> Fixed bug in ramachandran for structures with multiple chains
  where the terminii were not handled correctly.
  <LI> Fixed bug in Trajectory class where the following code would
  result in a duplicated first frame being read:
\code
traj->readFrame(0);  // Reads first frame and leaves iterator at second
traj->readFrame();   // Reads second frame and bumps iterator
\endcode
  Instead, the second readFrame() call would return the first frame.
  This is now fixed.
</UL>

\subsection r170_add_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Reorganized LOOS into the core LOOS library, core tools, and a
  set of packages.
  <LI> Added a "User" package with several tool templates that cover
  common tool cases (e.g. calculations based on a model, based on a
  trajectory, etc).  These are built using the LOOS top-level
  SConstruct.  However, they are <em>not</em> not part of the default
  build, so you must explicitly build them with "scons user".
  <LI> Added a "Density" package primarily for analyzing water density
  from MD simulations.
  <LI> Added a new options handling framework (OptionsFramework).
  Many tools (and some packages) now use this framework.  This will
  ensure more consistent options across tools.  The catch is that this
  means many tools now have slightly different command-line usage.
  This will break existing scripts that use the old LOOS tool
  command-line options.  See the documentation for OptionsFramework
  for more information.  <em>NOTE: User-written code does NOT have to
  use the OptionsFramework system.  You can still use whatever method
  you want to handle the command line.</em>
  <LI> Added general utility functions including
  loadStructureWithCoords(), assignTrajectoryFrames(), and
  vectorAsStringWithCommas<T>(const vector<T>& v)
  <LI> AtomicGroup::append() and AtomicGroup::remove() now return an
  AtomicGroup reference so they may be chained.
  <LI> Added a Math::transpose() function (this is <em>not</em> an
  in-place transpose)
  <LI> Changed the header/metadata from LOOS tools to include the
  current working directory (if available).
  <LI> Added support for using different selections for the trajectory
  and the reference structure in rmsd2ref
</UL>


\section release161 Version 1.6.1 (5-18-2011)
\subsection r161_bugs Bug Fixes
<UL>
  <LI> Fixed bug where charmm.hpp was not copied as part of an install
  <LI> Fixed bug in GRO files where the periodic box was not converted into Angstroms.
  <LI> Fixed bug in eigenflucc that included the rotation/translation
  modes when computing B-factors.
</UL>
\subsection r161_add_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Added support for hybrid-36 encoding in atomids and resids in
  PSF files.
</UL>

\section release160 Version 1.6.0 (3-4-2011)
\subsection r160_bugs Bug Fixes

<UL>
  <LI> Fixed bug affecting Trajectory::rewind() for Tinker ARC files
  <LI> Fixed bug when computing variance in TimeSeries
  <LI> Re-fixed bug in svd tool for MacOS (precision issue with
  vecLib)
  <LI> Fixed compiler issue in AtomicGroup for older versions of g++
  <LI> Fixed bug in AtomicGroup::renumberWithBonds()
  <LI> Fixed bug in big-svd where RSVs were not normalized

</UL>
\subsection r160_add_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Substantial change in ENM code to turn it into a library in its
  own right.  More information can be found within the Doxygen docs
  (in ENM namespace)
  <LI> AtomicGroup::findById() no longer implicitly sorts atoms.  If
  the AtomicGroup has been explicitly sorted, then the binary search
  will still be used to find the atom.  Otherwise, a linear search is
  used.
  <LI> Order parameters now uses boost program options (command
	line is similar, but not precisely backward compatible), has the option to
	use y or x as the direction of the magnetic field, and has the option to
	dump out the timeseries of the order parameters.  Specifically, the last
	quantity is computes the average instantaneous order parameter for each
	carbon position at each time point.  The "+/-" column in the output is the
	stdev of these timeseries, which is _not_ a good measure of the
	statistical uncertainty.  To get that, one should use block averaging on
	the time series.  This is also an option -- in principle, you read off the
	plateau value from the block averaging plot, but since this plateau is
	noisy, I make you specify a range of block sizes over which to average
	(the defaults are 2 blocks to 5 blocks, but you really should run the
	program twice, and the first time look at the block averaging plots to see
	where the block standard error converges.
  <LI> Added a simple Nelder-Meade Simplex optimizer
  <LI> Changed averager so that bonds are pruned (rather than cleared)
  when subsetting.
  <LI> Improved phase-pdb tool.  See "--help" for more details
  <LI> Added kurskew tool to compute moments for RSVs (useful for
  quick and dirty checks for modality)
  <LI> Added block averaging tool
  <LI> The aligner tool can now align to a reference structure and
    deprecated options removed
  <LI> Added a suite of convergence tools (see Doxygen docs for more
  details)
  <LI> covarianceOverlap() now uses BLAS and matrix operations so it
  is significantly faster.
  <LI> Added z-score for covariance overlap and support for this in
  the coverlap tool.
  <LI> Changed rdf tool to split by molecule, residue, or segment.
  <LI> AtomicGroup::splitByMolecule() has been improved and should be
  20-30x faster.
  <LI> density-dist can now make the density symmetric about the
  membrane center (assuming the system has been centered such that the
  membrane center is at z=0).
  <LI> Many more tools now use boost::program_options
  <LI> density-dist-windowed is now deprecated, having been folded
  into density-dist
  <LI> recenter-trj should be more robust (although slower)
  <LI> Added option to merge-traj to "fix by molecule" so that
  trajectories that have molecules broken across the periodic boundary
  (eg gromacs output) come out looking clean.
</UL>

\section release155 Version 1.5.5 (8-2-2010)
\subsection r155_add_changed Added, Changed, or Otherwise Notable
<UL>
  <LI> Added a tool to randomly perturb structures
  <LI> Added a tool for computing fluctuations from ENM/PCA (the old
  flucc2b tool is now deprecated)
  <LI> Added a tool for computing SVD's of large systems or when there
  are many time-steps
  <LI> Added a tool to compute the covariance and subspace overlaps
  from ENM and PCA results
  <LI> Added a new suite of tools for analyzing hydrogen-bonding
  <LI> Added support for accessing the SharedPeriodicBox in
  AtomicGroup
  <LI> Added support for some STL algorithms in TimeSeries class
  <LI> Changed the order_params tool to handle both 1- and 3-residue
  per lipid formats
  <LI> Changed the regular SVD tool to use double-precision
  <LI> The transpose flag in ASCII matrices is now deprecated
</UL>

\subsection r155_bugs Bug Fixes
<UL>
  <LI> Fixed bug in linux that affected library link order.  ATLAS is
  now correctly linked in first.
  <LI> Fixed bug in AtomicGroup::perturbCoords() where the directions
  picked were not actually uniformly distributed on the sphere.
  <LI> Fixed bug in writing internally transposed matrices.
  <LI> Fixed bug in Matrix code that affected large matrices (those
  with more than 2^32 elements).
  <LI> Fixed bug in svd tool only for MacOS.  This bug is one in the
  vecLib framework and may or may not effect the SVD output for single
  precision.  Symptoms include non-orthogonal LSVs and all non-zero
  singular values (there should be 6-zeros if using an aligned
  trajectory).  The double-precision svd does not have this problem
  nor does the implementation in big-svd.
  <LI> Fixed big in traj2matlab where the wrong subset of atoms was
  used to create the matrix.


\section release154 Version 1.5.4 (4-23-2010)
\subsection r154_added_changed Added, Changed, or otherwise Notable
<UL>
  <LI> Changed contact-time to use "fast" method that uses a
  distance-cutoff to restrict which target atoms are considered.  This
  can be disabled if necessary.  See "contact-time --help" for more
  details.
  <LI> Fixed bug in DescendingSort that caused it to sort ascending
  instead.
  <LI> Changed porcupine tool to make tagging of altered atoms
  optional and to have fixed length tips rather than proportional
  length ones.
  <LI> Changed AtomicGroup::rmsd() to take a const arg (this means
  that it no longer implicitly sorts the AtomicGroup objects).
  Implicit sorting is one "feature" that is going to gradually go away
  from AtomicGroup.
  <LI> Changed VSA/ANM tools so as to allow user-defined HCA
  parameters
  <LI> Fixed Hessian code (affecting ANM/VSA) to truncate negative
  spring constants to 0 (generally, this happens when using HCA with
  nodes that are too close together).
  <LI> Fixed bug in parser for Debian systems
  <LI> Changed Linux code to use blas rather than cblas
  <LI> Changes made to SConstruct for better Ubuntu/SUSE support
</UL>


\section release153 Version 1.5.3 (2-19-2010)
\subsection r153_added_changed Added, Changed, or otherwise Notable
<UL>
  <LI> PDB::fromAtomicGroup() now generates a UnitCell if the
       passed AtomicGroup has periodic boundary information.  This
       means that the output PDB will have a CRYST1 record.
  <LI> Added a more flexible centering tool called center-molecule
  <LI> Added a new tool for computing inter-selection contacts
       over time called contact-time
  <LI> Changed exposure tool to default to reimaging
  <LI> Added alignto tool for aligning a trajectory to a reference
  structure
  <LI> Added a set of generic sorting functions
  <LI> Added support for single and double precision matrix
  operations.  Note that these are for "quick-and-dirty" work and are
  not meant to give good performance...
  <LI> ENM tools sort their output from smallest to largest
  eigenvalue, and the zero eigenpairs always come first
  <LI> Added a VSA tool (along with psf-masses and heavy-ca tools for
  getting mass information into the VSA tool)
  <LI> Added covariance and subspace overlap functions
  <LI> Changed DCDWriter so that it can now append to an existing DCD
  <LI> Changed ENM tools use a Hessian constructor that's in a
  separate module, along with different methods for handling the
  spring constants via a polymorphic "superblock" object pointer...
  This will make more sense looking at the code itself...
</UL>

\subsection r153_bugs Bug Fixes
<UL>
  <LI> Fixed bugs in subsetter affecting reimaging only occuring if
  centering was turned on, and one causing bonds not to be cleared
  when subsetting.
  <LI> Fixed bug in extractCoords() causing it to always fail.
  <LI> Fixed bug in enmovie tool affecting connectivity not being
  cleared and atom number mismatches between the reference PDB and the
  DCD.
  <LI> Fixed bug in svd function that takes a vector<AtomicGroup>, but
  only when aligning was requested.  The alignment transform was
  doubly-applied to the passed vector.  No tools were affected by
  this.  No other invocations of svd() were affected either.
  <LI> Fixed bug in aligner where the target selection was not always
  correctly centered.  It would be aligned correctly, just not always
  centered...

\section release152 Version 1.5.2 (10-9-2009)
\subsection r152_added_changed Added, Changed, or otherwise Notable
<UL>
  <LI> Changed AtomicGroup::principalAxes() so that it scales the
  eigenvalues by the number of atoms.
</UL>

\subsection r152_bugs Bug Fixes
<UL>
  <LI> Fixed bug where segname was not correctly handled as a synonym
  for segid.
  <LI> Fixed bug affecting Amber restart files.  These are handled as
  a special trajectory with one frame, but the readFrame() iterator
  was not correctly set so the first call would return a false,
  indicating that all frames had been read.
  <LI> Fixed another issue with Amber restart files that may have
  slight variations in formatting.  This affected restart files that
  only have the number of atoms in the header rather than the number
  of atoms and the time.
</UL>

\section release151 Version 1.5.1 (9-21-2009)
\subsection r151_bugs Bug Fixes
<UL>
  <LI> Fixed bug in install target where trr.hpp was not copied to the
  installation directory.
</UL>

\section release150 Version 1.5.0 (9-17-2009)
Many of the changes in this version are internal (primarily as new
functions and features).  The big change is that LOOS now supports
Gromacs .gro, .trr, and .xtc file formats.  Since Gromacs stores
coordinates in nm, LOOS converts the coordinates into Angstroms upon reading.
LOOS only supports single precision .xtc files.

<em>Important note regarding Gromacs support:  While we have tested
the gromacs support with a limited set of sample files, the code has
not been as rigorously tested as support for previous formats have
been.  Gromacs support should therefore be considered experimental at
this stage.  Please report any problems or errors to as at
loos_maintainer [at] urmc.rochester.edu</em>

LOOS now also uses the hybrid-36 encoding method for PDB files with a
large number of atoms or residues.  See <A
href="http://cci.lbl.gov/hybrid_36">here</A> for more information.

\subsection r150_added_changed Added, Changed, or otherwise Notable
<UL>
  <LI> Added AtomicGroup::findBonds() to perform a simple
  distance-search for bonds.
  <LI> Added support for testing Atom equality.  See loos::AtomEquals,
  loos::AtomCoordsEquals for more information.
  <LI> Added loos::AtomicGroup::contains() and loos::AtomicGroup::intersect() for
  set operations.
  <LI> Added new bits to loos::Atom that can be used as flags (i.e. flagbit,
  usr1bit, ...)
  <LI> Added Gromacs classes: loos::Gromacs, loos::TRR, and loos::XTC.
  <LI> Changes to the Trajectory class and subclasses:
  <UL>
	<LI> Changed the underlying stream type to iostream.  This
	should not break anything unless you have subclassed
	Trajectory for your own purposes.
	<LI> Implementation functions are now private.
	<LI> Added some missing constructors in the subclasses.
  </UL>
  <LI> Added some utilities for parsing strings
  (loos::parseStringAs<>())
  <LI> Added new formatters for matrix output that make it easier to
  set the width and precision of the matrix elements, or write them
  out in scientific notation (i.e. loos::ScientificMatrixFormatter)
  <LI> Added Hybrid-36 support to PDB's (both reading and writing)
  <LI> rmsds can now work with a subset of frames from a trajectory
  <LI> subsetter can now reimage
  <LI> SVD now will only write out the non-zero terms of the SVD
  rather than the entire matrix.
  <LI> Added a "not" operator to the selection language so there's no
  more fighting with the shell over '!'.
  <LI> Some tools have been updated internally to be more
  consistent with the current LOOS idioms...  There may be minor
  changes in usage:
  <UL>
	<LI> SVD now requires a 1 or 0 for the -S option
  </UL>
  <LI> New tools:
  <DL>
	<DT> molshape
	<DD> Reports statistics about a selection (i.e. extents,
	radius of gyration, location of centroid, principal axes, etc)

	<DT> native_contacts
	<DD> Compute the fraction of native contacts in a trajectory
	based on an initial structure
  </DL>
</UL>

\subsection r150_bugs Bug Fixes
<UL>
  <LI> Fixed bug in loos::writeAsciiMatrix() when only writing a subset of a
  matrix.
  <LI> Fixed bug in bounding tool's box size
  <LI> Fixed problem with spurious rebuilds of all of LOOS with
  SCons.
  <LI> Fixed bug in loos::DCD::updateGroupCoords where the upper-bounds
  check on atomid's was incorrect.
</UL>


\section release140 Version 1.4.0 (6-26-2009)
There has been a change in philosophy of how LOOS handles system
descriptions vs models/trajectories/coordinates.  Previously, LOOS
would try to create an AtomicGroup that had complete information, such
as when given an Amber prmtop file.  In this case, LOOS would go
looking for a file with the same name ending in ".inpcrd" and load
this in with the prmtop file.  Now, LOOS will treat coordinate files
as a special trajectory that has only one frame.  This way, most tools
that can operate over a trajectory can also operate on a single model,
and vice versa.  For example, the following are all valid:
\verbatim
ramachandran --pseuo foo.prmtop foo.rst all
ramachandran --pseudo foo.prmtop foo.mdcrd all
ramachandran foo.psf foo.dcd all
ramachandran foo.psf foo.pdb all
ramachandran foo.pdb foo.pdb all
\endverbatim

This can lead to the somewhat awkward usage in the last example, but
think of it as the first PDB provides the system description and the
second provides the actual model, even though they're both the same.

\subsection r140_added_changed Added, Changed, or otherwise Notable
<UL>
  <LI> Added an AtomNameSelector() to match arbitraty atoms
  <LI> Added centerOfElectrons() to AtomicGroup class
  <LI> Added support for Tinker file formats in the factory functions
  <LI> Added a renum-pdb tool for renumbering models
  <LI> Added interdist tool for calculating distances between selections
  <LI> Added support for numerically sorting the input trajectory
  filenames in subsetter.  See the tool documentation above for more
  information.
  <LI> Added a porcupine tool for creating porcupine plots for SVD/ENM
  results
  <LI> Added paxes tool for computing the principal axes magnitudes
  (i.e. eigenvalues) of a set of selections over a trajectory.
  <LI> Added drifter tool for tracking centroid movement
  <LI> Added a ramachandran tool for calculating ramachandran maps
  <LI> Added a "rotamer" tool for calculating the chi-1, chi-2 torsion
angles for side-chains.
  <LI> Added "rmsfit" tool to superimpose one model upon another
  <LI> Added a suite of Elastic Network Modeling tools inside Tools:
  <UL>
     <LI> "anm" calculates an anistropic network model
     <LI> "gnm" calculaes a gaussian network model
     <LI> "flucc2b" maps anm/gnm fluctuations onto a PDB's B-values
     <LI> "enmovie" creates a DCD trajectory showing motion based on
anm/gnm results.
  </UL>
  <LI> Reduced the size of the test files
  <LI> Added an install target for SCons
  <LI> Added support for building a shared-library version of LOOS
  <LI> Added a special SCons check for ubuntu.  Some systems appear to
  have an issue where they require the gfortran lib to be explicitly
  linked.  If this causes an issue for you, simply comment out the
  ubuntu check in the SConstruct.
</UL>

\subsection r140_internal Internal Changes
<UL>
  <LI> Changed how Trajectory classes work slightly...
  Trajectory-derived classes must now read in and cache the first
  frame of the trajectory as part of their initialization.
  <LI> CAlphaSelector() is now deprecated; use AtomNameSelector("CA")
  instead.
  <LI> Added a set of classes for providing user-feedback when a tool
  may take some time to execute.  See loos::ProgressCounter for more
  information, and the rmsds tool for an example of how to use the new
  classes.
  <LI> Removed the use of BOOST_FOREACH.  This solves a compatability
  issue with older versions of BOOST and LOOS.
  <LI> Added a number of support utilities for reading in whole
  trajectories and reading in specific frames.
  <LI> The ensemble functions (i.e. align and average) can now operate
  over a user-specified set of frames from a trajectory.
  <LI> Added AtomicGroup::splitByResidue() that splits up a group by
  residue (based on changes in resid and/or segid), returning a
  vector<AtomicGroup>.
  <LI> The createSystem factory function now no longer tries to
  automatically find and import an Amber coord file when reading in a
  PRMTOP.  In addition, the Amber::readCoords() function has been
  removed.
  <LI> Added support for Amber restart and coord files as a special
  1-frame trajectory.  This is transparently handled by the
  createTrajectory factory function.
  <LI> The Trajectory class now uses NVI for the seek and rewind
  member functions so it can impose some pre-conditions.  This means
  the Trajectory base class handles the cached_first flag.  Unless
  you're writing your own trajectory class, this wont affect you.  If
  you are, it means the seek and rewind functions are now handled by
  rewindImpl(), seekImpl(), etc.

</UL>

\subsection r140_bugs Bug Fixes
<UL>
  <LI> Fixed bug in subsetter where verbose output was always on.
  <LI> Fixed bug in subsetter where out of range frame indices would
  cause a seg-fault.
  <LI> Fixed bug in rmsds that caused the average rmsd to be
  calculated incorrectly.
  <LI> Fixed some issues with the SConstruct file
  <LI> Fixed a problem with averager where it was caching all frames
  of the trajectory causing swapping for large trajectories
</UL>


\section release134 Version 1.3.4 (2-16-2009)
\subsection r134_bugs Bug Fixes
<UL>
  <LI> Fixed bug in aligner affecting centering the trajectory while
using different alignment and transformation subsets.  The output
trajectory was incorrectly transformed.  The error committed is
proportional to the difference in the centroids between the two
subsets...
</UL>



\section release133 Version 1.3.3 (2-9-2009)
\subsection r133_added_changed Added, Changed, or Notables
<UL>
  <LI> Added recenter-trj tool to center trajectories
  <LI> Added trajinfo tool to print out information about generic
  trajectories.  This tool will also verify the number of frames
  actually present in the trajectory.
  <LI> Added concat-selection tool to concatenate atoms from a
  trajectory into a single PDB.  This is useful for visualization atom
  distributions over the entire trajectory
  <LI> Added blurrogram.pl, a PERL script to aid in creating
  "blurrogram" figures using Pymol
  <LI> Added AtomicGroup::translate()
  <LI> The frame2pdb tool now accepts a selection (subset) to write
  out
  <LI> The svd tool always writes out an average structure now
  <LI> The subsetter tool can now accept a list of aribtrary ranges of
  frames to extract, or a stride option.  It can also take an
  arbitrary list of input trajectories to combine and extract from.
  In addition, it can override or add periodic box information.
  <LI> The DCD class will now handle reading of non-native endian DCD
  files
  <LI> The DCDWriter class will now flush the output streams after
  each frame is written to ensure all data is actually written to disk
</UL>

\subsection r133_bugs Bug Fixes
<UL>
  <LI> Fixed an issue with DCD's written by LOOS that have periodic
  boundary information.  The default unit cell angles were 1, rather
  than 90 degrees.  This prevents programs like VMD from correctly
  displaying the periodic images.
  <LI> Fixed a typo in the default alignment selection for the
  rmsd2ref tool
  <LI> Fixed a bug in several tools that affected using a PSF file for
  the model when writing out a PDB file that had been subset with a
  selection.
  <LI> The loos::averageStructure() function did not verify that the
  input vector<XForm> matches the numbef of frames in the passed
  trajectory.  This results in a segmentation fault when the
  trajectory has a bad header (i.e. the number of frames listed does
  not reflect the number of frames actually in the trajectory).  This
  case is now checked for and a slightly more sensible error is
  thrown.
  <LI> The error messages given when the LOOS could not decide what
  format a file is in were vague...this has been improved...
</UL>

\section release132 Version 1.3.2 (1-20-2009)
\subsection r132_bugs Bug Fixes
<UL>
 <LI> Fixed <B>severe</B> bug that results in bad connectivity
 information when reading from Amber prmtop files.
</UL>

\subsection r132_added_changed Added or Altered Functionality and Notables
<UL>
 <LI> Added Atom::isBoundTo()
</UL>

\section release131 Version 1.3.1 (1-14-2009)
\subsection r131_bugs Bug Fixes
<UL>
 <LI>Fixed bug affecting MacOS X 10.5 builds.
 <LI>Aligner wrote out its reference PDB uncentered even if given the
 "--center" flag.
 <LI>Aligner did not correctly compute average structure unless the
 "--rmsd" flag was given.
 <LI>The "--terms" flag for the svd tool was inadvertently removed.
</UL>


\section release130 Version 1.3.0 (12-22-2008)

\subsection r130_namespace Namespace Changes
This release represents some major changes to the internal structure
of LOOS.  First and foremost, virtually all of LOOS is now
encapsulated within the "loos" namespace whereas before much of loos
was in the global namespace.  This means that <tt>Atom a;</tt>
becomes <tt>loos::Atom a;</tt>.  Alternatively, you can place a using
directive at the top of your code,
\code
using namespace loos;

Atom a;
\endcode

LOOS also now respects your global namespace by not forcing the
importation of names that it uses, such as from the \c std namespace
or \c boost.  In fact, in versions prior to 1.3.0, LOOS would import
\c std into the global namespace.  If you were relying on this
behavior, you will now need to manually import in your code.  We
therefore recommend that you add the following to the start of all of
your code:
\code
using namespace std;
using namespace loos;
\endcode

Another \b major change in version 1.3.0 is the matrix handling code.
There is now a generic \c loos::Math::Matrix class that supports several different
ways of laying out the raw data (i.e. row major vs column major) and
can even support sparse storage.  This class in in the \c loos::Math
namespace.  It is important to note that the goal of this class is to
provide a controllable wrapper around a block of memory for
interfacing with ATLAS.  It is not meant to be a generic matrix in a
mathematical sense, despite being located in the \c loos::Math
namespace.  The polymorphic matrix I/O classes (i.e. \c MatrixReader and
\c MatrixWriter) are now gone, replaced by template functions \c
loos::writeAsciiMatrix() and \c loos::readAsciiMatrix().  The format used is just
a block of ASCII data that can be read in my Octave/MATLAB and
GnuPlot.  These reading and writing functions are in the \c loos
namespace, not the \c loos::Math namespace.  The reason for this is to
support the following pattern,
\code
using namespace std;
using namespace loos;

typedef Math::Matrix<double, Math::Triangular> Matrix;
...
Matrix M;
writeAsciiMatrix(filename, M, "My matrix");
\endcode

Additionally, math functions that were at a global scope, such as \c angle() and \c
torsion() are now in the \c loos::Math namespace.

\subsection r130_added_changed Added or Altered Functionality and Notables

<UL>
 <LI> There is an issue with tr1::unordered_set in gcc-4.0.1.  This
 the internal data structure used by the sparse matrix policy.  To
 work around this, LOOS will switch to using the GNU provided hash_map
 if you're using gcc-4.0.1.  This is most likely to affect MacOS users
 running 10.4 and XCode 2.5 and earlier.
 <LI> When \c loos::createSystem() sees an Amber prmtop file, it will
 automatically look for a corresponding .inpcrd file and load the
 coordinates from that.  Otherwise, it returns an AtomicGroup sans
 coordinates.
 <LI> The ensemble functions (such as \c loos::averageStructure()) now
 take a \c loos::pTraj instead of a reference to a \c
 loos::Trajectory&.
 <LI> Many of the tools now use the boost program_options library
 <LI> The alignment tool (<tt>aligner</tt>) now writes out the average
 structure as well, and has an option to center the aligned
 trajectory.
 <LI> Added <tt>subsetter</tt> tool that pulls a subset of a model out
 of a trajectory into a new, smaller trajectory.
 <LI> The \c PDB reader now only emits warnings for each unique
 unknown record read rather than a whole mess of 'em...
</UL>

\subsection r130_bugs Bug Fixes
<UL>
 <LI> Fixed a bug in the Amber trajectory reader that caused LOOS to
 incorrectly seek frames.  This affected using readFrame(i) but not
 readFrame().
 <LI> \c AtomicGroup::splitByMolecule() now handles groups without
 connectivity.
 <LI> Fixed a problem with the PDB reading code that mangled wide
 CONECT records.
</UL>



<hr>

\section release121 Version 1.2.1 (11-3-2008)
\subsection r121_bugs Bug Fixes
<UL>
 <LI> Fixed bug in crossing-waters tool
 <LI> Fixed bug in \c loos::Atom::clearPropertyBit() that caused it to
 not always toggle the correct bit.
</UL>


<hr>


\section release120 Version 1.2.0 (10-24-2008)
\subsection r120_changes Changes
<UL>
 <LI>Added <tt>helix_kink</tt> tool to determine bend-angles in
 helices.
 <LI> Added \c HeavySolventSelector
 <LI> Updated tools to use new convenience/factory functions, also
 making them a tad more universal in what inputs they can take.
 <LI> Added \c AtomicGroup::clearBonds() to remove connectivity in a
 group.
 <LI> \c PDB will out write out CONECT records when there are 10K
 atoms or greater, to prevent field overflow.
 <LI> \c Coord<T> can now extract itself from a stream.
 <LI> Added \c loos::selectAtoms() to parse a selection string and
 apply it to an \c AtomicGroup.
 <LI> Added support for writing out \c PDB CONECT records.

</UL>

\subsection r120_bugs Bug Fixes
<UL>
 <LI> Fixed problem with \c PDB output when there are more than 10K
 residues
 <LI> Fixed bug in \c DCDWriter that caused the output periodic
 box to be set to (1,1,1) regardless of what was passed in.
 <LI> Fixed problem when writing a \c PDB with bonds to missing
 atoms.  Bonds are now dereferenced prior to writing.  This means that
 the \c PDB is now no longer const when written and could be sorted.
 <LI> Fixed bug in width of CONECT record fields
 <LI> Fixed bug in \c DCD trajectories affecting seeking frames
 <LI> Fixed bug in \c DCD trajectories potentially affecting the
 number of frames sensed in a trajectory that comes from NAMD.
 <LI> Fixed bug in \c Atom::checkProperty() that caused
 erroneous results.
</UL>


<hr>

\section release110 Version 1.1.0 (9-12-2008)
\subsection r110_changes Changes
<UL>
 <LI> Major reorganization of the \c Trajectory class using a template
 pattern.
 <LI> Added \c CCPDB class for concatenated PDBs that you can treat as
 a \c Trajectory
 <LI> Added \c PDBTraj class for handling non-contiguous PDB
 trajectories
 <LI> Added \c TinkerArc class for TinkerArc (concatenated XYZ files)
 trajectories
 <LI> Changed \c Atom defaults to initialize atomid and resid to 1
 rather than -1
 <LI> Added tool to compute the RMSD between a selection and its
 average structure over the course of a trajectory
 <LI> Improved self-tests
 <LI> Added a new tool to reimage a trajectory by molecule
 <LI> Added \c AtomicGroup::apply() to call a functor or a function
 pointer on each \c Atom in an \c AtomicGroup.
 <LI> \c DCDWriter now long requires you to specify how many frames
 will be written--you can append and it will automatically update the
 header correctly.
</UL>


\subsection r110_bugs Bug Fixes
<UL>
 <LI> Fixed problem with typedefs in MacOS 10.5
 <LI> Fixed bug in \c ATom where setting coords using a \c GCoord ref
 not correctly setting the coords-bit.
 <LI> Fixed big in <tt>aligner</tt> where the first frame of the DCD
 was not transformed.
 <LI> Fixed bug in \c AtomicGroup::splitByMolecule() where the \c
 PeriodicBox was not propagated beyond the first group split.
 <LI> Fixed bug in <tt>svdcolmap</tt> tool that affected certain
 instances of using atomid maps.
 <LI> Fixed bug in \c loos::iterativeAlignment() where the returned \c
 XForms were incorrect.  The passed ensemble of \c AtomicGroup objects
 were correctly transformed, but anything that used the \c XForms were
 affected by varying degrees.
</UL>

*/

}

namespace loos {


/*! \page faq Frequently Asked Questions
\section faq_loos LOOS

\subsection faq_loos_building Building LOOS (and building with LOOS)
<DL>

<DT> I am having trouble building LOOS with Boost 1.52 (or later)
<DD> There was a change in Boost at version 1.52 that breaks the build
of LOOS.  We recommend upgrading to either LOOS 2.0.4 or downgrading
your version of Boost to 1.51

<DT> SCons is not finding the right compiler/swig/doxygen
<DD> For LOOS, SCons will use your shell's $PATH veriable to look
for tools.  You will need to make sure the missing tool is in your
path.  Some care may be necessary in the order directories appear
in your path to make sure you are finding the intended version of
the tool.  You can explicitly specify a C++ compiler to use
with the CXX variable (either in your environment or from a
custom.py file).  This will take precedence over your path.

<DT> SCons is not finding my installation of Boost.
<DD> If you need to point SCons to a non-standard location of Boost,
use the BOOST variable on the command-line or within your custom.py
file.  If you need to override either the include directory or the
library directory, use the BOOST_INCLUDE and BOOST_LIBPATH variables
respectively.

<DT> SCons cannot find a Boost library.
<DD> SCons will try to determine the correct naming variant for your
Boost install.  It will start by looking for "libboost_foo-mt.suff",
followed by "libboost_foo.suff" where suff is either "dylib"
(MacOS/Darwin), "so" (Linux), and "dll.a" (Cygwin).  Failing that, it
will look for any file matching "libboost_foo-*-mt.suff" followed by
the non-threaded version.  Of the list of filenames found, SCons will
take the shortest one.<p>
If necessary, override the libraries linked to for Boost by setting
the BOOST_LIBS variable to a space-separated list of libraries.  Note
that you will need to include all of the ones required by LOOS, at a
minimum,
\verbatim
BOOST_LIBS="boost_regex boost_program_options boost_system boost_thread"
\endverbatim
Note that the libraries will be linked in with the same order they
appear in the BOOST_LIBS variable.

<DT> I'm getting undefined reference or other link errors that appear
  to be related to Boost
<DD> This can happen if you have multiple versions of Boost
  installed.  SCons may use include files from one version, but link
  with the libraries from another.  Check the path to BOOST and the
  name of the libraries linked against.

<DT> I get a build error that says expected threaded libraries or
  non-threaded libraries, but some library is the opposite?
<DD> This is probably a failure of SCons to figure out the appropriate
  library name.  Use the BOOST_LIBS variable (described above) to
  manually set the libraries used.

<DT> I get an error that says I must have some kind of blas installed
<DD> This means that SCons could find neither the versions of blas
  included with Atlas nor the typical system blas.  You will need to
  make sure one or the other is installed.  Double check your
  ATLAS_LIBPATH.  In a worst case, you may need to explicitly list the
  libraries to use by setting the ATLAS_LIBS variable.

<DT> I get an error that says SCons could not figure out how to build
<DD> As part of the build, SCons will try to compile and link a test
  program to see whether ATLAS/LAPACK works and if there are any
  additional libraries needed.  For some reason, this step failed.
  Double-check your Atlas/lapack installation.  You may want to try
  building a small test program with Atlas, and use that to set
  ATLAS_LIBS or CCFLAGS appropriately.

<DT> How do I compile my own, separate tool with debugging?
<DD> If you copied the example SConstruct/SConscript, then change the
     LOOS_CCFLAGS environment variable before building your tool(s).

</DL>

\subsection faq_loos_using_tools Using LOOS Tools
<DL>

<DT> What units does LOOS use for coordinates?
<DD> LOOS uses Angstroms as the output unit of distance, even when the input
coordinates are in other units (e.g. nanometers for GROMACS files are
converted into Angstroms).

<DT> How does LOOS write out the connectivity information?
<DD> LOOS places the model's connectivity into the CONECT records of
the output PDB.  Connectivity is written out for all atoms for which
there is connectivity present.

<DT> Using LOOS tools with large systems
<DD> LOOS should have no problem with large systems, although some
care is required when using PDB files.  There are several different
approaches to reading and writing PDB files that contain more than
100,000 atoms or 10,000 residues.  LOOS uses the Hybrid-36 scheme for
encoding large numbers in the atom serial numbers (atomids) and
residue id's (resids).  While LOOS can read PDB's written in other
conventions, it is best to canonicalize them into LOOS's hybrid-36
scheme.  One way to do this is to use the renum-pdb tool,
\code
renum-pdb bigmodel.pdb all 1 1 >loos_bigmodel.pdb
\endcode

Alternatively, stick with a PSF.  If you need
coordinates in a model, you can extract the first frame of your
trajectory using frame2pdb,
\code
frame2pdb bigmodel.psf bigmodel.dcd 0 >loos_bigmodel.pdb
\endcode

Alternatively, since PSF files are space delimited, field overflow is
not an issue.  You can convert a PDB+PSF to a PDB without
renumbering by using the convert2pdb tool, i.e.
\code
convert2pdb --coords bigmodel.pdb bigmodel.psf >loos_bigmodel.pdb
\endcode

<DT> My DCD says it has 0 frames (or too many frames)
<DD> LOOS relies on the DCD header to know how may frames
are in a trajectory, but sometimes the header may be incorrect.
For example, a ptraj conversion my result in a 0 frame count in
the header, or if a write to a trajectory was interrupted, the
header may list more frames than were actually written.  Two tools can
be used to check the integrity of a trajectory: trajinfo and dcdinfo.
Both tools will scan the trajectory and count the number of frames
actually present.  The latter will also dump the inctrl block from the
DCD header.  If there is a problem with the frame count in the DCD
header, use the fixdcd tool to correct it.
\code
fixdcd simulation.dcd
\endcode


</DL>

\subsection faq_loos_library Using the LOOS Library
<DL>

<DT> How does LOOS handle connectivity/bonds?
<DD> Bonds are represented in LOOS by a list of atom id's that are
bound to a given atom.  This means that connectivity can be maintained
even when the bound atoms are no longer stored.  However, it also
means that atom id's are assumed to be unique.  If you are having
trouble with connectivity because of fragmenting groups of atoms, you
can use AtomicGroup::clearBonds() to remove all connectivity in a
group, or AtomicGroup::pruneBonds() to remove bonds to any atom not
contained in the given group.

<DT> How do I make a copy of an AtomicGroup?  Why do changes in one
group affect another?
<DD> Atoms are typically shared between AtomicGroup's in LOOS.  For
example, select just the alpha-carbons from a model,
\code
	AtomicGroup model = createSystem("protein.pdb");
	AtomicGroup ca = selectAtoms(model, "name == 'CA'");
\endcode
	The atoms in ca will be shared with the corresponding atoms in
model.  Changes to an atom in one group will result in changes to the
other group because the atoms are shared.
\code
	ca[0]->coords(ca[0]->coords() + translation_vector);
\endcode
Will translate the first alpha-carbon in both ca and model.
Making a copy of an AtomicGroup,
\code
	AtomicGroup duplicate = model;
	AtomicGroup duplicate(model);
\endcode
results in the copy sharing the same atoms.  Also of note here are the
two idioms for making a copy of a group.  Both result in what is
called a "shallow copy" of model.  The atoms are shared, but the lists
of atoms in the group are different.  For example,
\code
	duplicate.remove(ca);
\endcode
will remove all alpha-carbons from the list of atoms in duplicate, but
they will still be present in model.<p>

In order to make a copy of an AtomicGroup where the atoms are
<i>not</i> shared, a "deep copy" must be made.  Here, each atom is
copied into a new, separate atom, and then stored in the copy of the
group.  The AtomicGroup::copy() function does this,
\code
	AtomicGroup duplicate = ca.copy();
\endcode
Now, not only are the lists of atoms distinct, but so are the atoms...
\code
	duplicate[0]->coords(duplicate[0]->coords() + translation_vector);
\endcode
Here, the changes to the first alpha-carbon in duplicate does
<i>not</i> change the coordinates of the first alpha-carbon in ca
since they are no longer shared.

<DT> What's the difference between an atom index and an atom id?
<DD> When working with a
trajectory, the ordering of the atoms in the corresponding model is
important.  The ith coordinate in a frame of the trajectory belongs to
the ith atom in the model.  When a model is read in by LOOS, the
associated atoms are assigned an index based on their position within
the file/model.  In general, this approach should just work and you
will not need to worry about atom indices.<P>

In contrast, LOOS treats the atom id (atomid) as an atom identifier
(metadata) and assumes that atomid's are unique.  They are important
for connectivity since bonds are stored as a list of atomid's that are
connected to a given atom.  Also, atomid's can be non-contiguous to
indicate logical groupings, for example, nor are they required to
begin with 1.

<DT> How have atomid's changed in LOOS in release 2.1.0?
<DD> Previously, LOOS treated atomid's as special when reading a
trajectory.  The atomid was the index into the trajectory frame for
the corresponding atom.  This required models to have contiguous
atomid's that began with 1.  This is no longer the case.  Atomid's
should still be unique, otherwise features like searching for atoms
and following bonds may give erroneous results.<P>

Additionally, some trajectory format classes have special cases of
\code
Trajectory::updateGroupCoords(AtomicGroup& g)
\endcode
If the number of atoms in g is the
same as the trajectory frame, then the coordinates are copied <i>in
order</i> into g, irrespective of the atomid's.  This is no longer the
case.  Atom indices will always be honored.

<DT> What if I need to renumber the atom indices?
<DD> This should rarely happen.  If it does, you can set the indices
directly by using Atom::index(), or use AtomicGroup::resetAtomIndices()
which will make all indices in a given group sequential and beginning
with 0.

</DL>

<hr><hr>
\section faq_pyloos PyLOOS

<hr>
<B>
NOTE: This FAQ is specific to the Python interface to LOOS (PyLOOS).
Please report any bugs found to "loos.maintainer [at] gmail.com".
Similarly, please feel free to contact us regarding new functionality
or better implementations.
</B>
<hr>

\subsection faq_pyloos_building Building PyLOOS
<DL>
<DT>	What operating systems support PyLOOS?
<DD>	PyLOOS currently supports Linux and MacOS.  For specific
	versions and installation instructions, see the INSTALL file.

<DT>	How do I build PyLOOS?
<DD>	You will need to install a recent version of Swig.  For
	details specific to your OS, please see the INSTALL file.

<DT>	I'm getting errors from Swig (about missing files)
<DD>	On a few test systems, we found that there is an older
	version of swig present (e.g. /usr/bin) in addition
	to a newer version (e.g. in /sw/bin).  Make sure that your
	shell's path has the newever location first, i.e. /sw/bin
	appears to the left of /usr/bin

<DT>	I'm seeing a lot of warnings messages from the PyLOOS build
<DD>	We have seen this in some instances (MacOS 10.9, for example),
	and believe they can be safely ignored.

<DT>	SCons is trying to build PyLOOS even though it's unsupported,
	or the build is breaking with PyLOOS
<DD>	You can disable the auto-build of PyLOOS by using the pyloos
	command-line flag with scons:  <TT>scons pyloos=0</TT>

<DT>	How do I use PyLOOS?
<DD>	Your environment needs to be setup to allow Python to locate
	the PyLOOS libraries.  LOOS now provides two setup scripts,
	setup.sh for bash users, and setup.csh for tcsh users.  Source
	the appropriate script, then execute Python and import from
	loos.

<DT>	Can I install PyLOOS?
<DD>	Yes.  PyLOOS can be installed alongside the rest of LOOS,
\code
	scons install
\endcode
	or to install in a specific location,
\code
	scons PREFIX=/home/user/MyLOOS
\endcode
	Be sure to source the appropriate setup.sh or setup.csh file
	in the install directory prior to using LOOS/PyLOOS.

<DT>	I get an error about a missing init function when I try to import PyLOOS...
<DD>	If you built LOOS and <em>then</em> built PyLOOS, the old LOOS
  shared library may still be around and this can confuse Python.
  Look for <tt>loos.so</tt> and remove it, or try a clean rebuild,
\code
        scons -c
        scons
\endcode

</DL>

\subsection faq_pyloos_using Using PyLOOS
<DL>
<DT>	Setting parameters in LOOS objects
<DD>	In C++, it is possible to have two different methods for
	setting a parameter value,
\code
		  GCoord c;
		  c.x() = 42;
		  c.x(42);
\endcode
	In both cases, the X-coordinate is set to 42.  In Python,
	however, you must use the second form, c.x(42) .

<DT>	Making copies of LOOS objects
<DD>	Remember that in Python, saying "a = b" does not actually copy
	b.  Python has a "copy" package which supports a shallow copy
	using the copy() function and a deep copy using the deepcopy()
	function.  A shallow copy is similar to how a LOOS object would
	normally be copied in C++.  For example,
\code
		  AtomicGroup A;
		  AtomicGroup B = A;
\endcode

	In this case, B is a shallow copy of A.  That is, the atoms
	are shared between A and B.  However, B can contain a
	different set of atoms from A, e.g.
\code
		  B.append(another_atom);
\endcode
	Now B will have an extra atom that A will be lacking, but
	existing atoms will still be shared between A and B.  In
	contrast, in the PyLOOS equivalent,
\code{.py}
		  A = AtomicGroup()
		  B = A
		  B.append(another_atom)
\endcode
	A and B are the same and now both have the extra atom.  To
	make a copy of A that behaves like the C++ copy, use Python's
	copy package to make a shallow copy,
\code{.py}
	          import copy
		  A = AtomicGroup()
		  B = copy.copy(A)
		  B.append(another_atom)
\endcode
	Now, B has an extra atom and existing atoms are shared.  Note
	that the C++ idiom,
\code
		  A = AtomicGroup()
	 	  B = AtomicGroup(A)
\endcode
	will also work for creating a shallow copy.

	Since atoms are shared in a shallow copy of an AtomicGroup,
	modifying the atom in one group will modify the atom in all
	groups that contain that atom.
\code{.py}
	          import copy
		  an_atom = Atom(1, "CA", GCoord(1,2,3))
	          A = AtomicGroup()
		  A.append(an_atom)

		  B = copy.copy(A)
		  B[0].id(42)
\endcode
	Here, we've created an atom, appended it to AtomicGroup A,
	then made a shallow copy into AtomicGroup B.  However, atoms
	are shared between AtomicGroups that have been
	shallow-copied.  Therefore, when the atomid of the first atom
	in B is changed, since the atom is shared between A and B,
	both groups see the change.  Sometimes, it is necessary to
	have a separate copy of a group so that changes to the atom in
	group B will not affect group A.  This requires a deep copy,
\code{.py}
	          import copy
		  an_atom = Atom(1, "CA", GCoord(1,2,3))
		  A = AtomicGroup()
		  A.append(an_atom)

		  B = copy.deepcopy(A)
		  B[0].id(42)
\endcode
	Here, the atoms are no longer shared...each group has its own
	copy of the atom.  Therefore, changing the atomid of the first
	atom in group B does NOT change the first atom in group A.
	This is equivalent to using the AtomicGroup::copy() function
	in C++.

<DT>	Why are my GCoords changing on me?
<DD>	See above...  Remember that saying "a = b" in Python does
	NOT copy the GCoord so when you change a, you're also changing
	b.  Use "a = copy(b)" to get a new GCoord that's a copy of the
	existing one.

<DT>	What objects support copying?
<DD>	Currently, Atom, GCoord, and AtomicGroup support copying.  For
	Atom and GCoord, copy() and deepcopy() are functionally
	equivalent.

<DT>	Where did pAtoms go in PyLOOS?
<DD>	Swig maps the boost shared pointer (pAtom) into the name
	"Atom".  So, wherever you would use a pAtom in the C++ version
	of your code, simply use Atom in PyLOOS.

<DT>	Are there any examples of using PyLOOS?
<DD>	Yes.  Look in the Packages/PyLOOS directory.  We will be
	adding more examples in future releases.

<DT>	Where are the matrix operations?
<DD>	We currently assume that matrix operations are better handled
	by the appropriate Python package (e.g. numpy).  Some
	matrix-based routines are available, such covariance and
	subspace overlaps.

<DT>	Why is PyLOOS so slow?
<DD>	A frequent problem with PyLOOS performance is a result of
	looping using Python.  For example, to find an Atom in an
	AtomicGroup, the following will be slow,
\code{.py}
	found = 0
	for x in range(system.size()):
	    if (system[x] == an_atom):
	       found = 1
	       break

	if (found):
	   do_something()
\endcode

	Instead of using loops, try first to get Python to do the
	looping internally, i.e.
\code{.py}
	if (an_atom in system):
	   do_something()
\endcode

	Alternatively, look for LOOS functions that will perform the
	same operation, such as:
\code{.py}
	if (system.contains(an_atom)):
	   do_something()
\endcode

	Finally, consider rewriting the loop in C++ and adding it to
	AtomicGroup (remembering to update the SWIG interface file,
	AtomicGroup.i).
</DL>

*/

}