/**
\page introduction Introduction

\imp is a library for solving a a wide variety of molecular structures and
dynamics using many different data sources. As a result, it provides a
great deal of flexibility. In order to best make the required decisions
about how to use \imp to solve a particular problem, it is useful to
understand the overall structure of \imp.

 -# \ref im1 "Theory"
 -# \ref i55 "Concepts"
 -# \ref i6 "Examples"
 -# \ref i125 "Modules"
 -# \ref i13 "C++ and Python"
 -# \ref conventions "Conventions"
 -# \ref incremental "Incremental scoring"
 -# \ref fixbug "Reporting bugs"
 -# \ref next "Where to go next"

\section im1 1. Theory

Structure and dynamics modeling in \imp proceeds in a five stage iterative process
\dotgraph{ \dot
 digraph intergrative_modeling {
    node [shape=record\, fontname= Helvetica\, fontsize=10]
      a [label="1. Gathering of experimental data"\, URL="\ref dataacq"];
      b [label="2. Choice of the representation\nscheme for the model"\, URL="\ref dataacq"];
      c [label="3. Encoding of the data as a\nscoring function on the\nrepresentation scheme"\, URL="\ref dataenc"];
      d [label="4. Sampling of the possible models\nin the representation scheme\nto try to find good models"\, URL="\ref sampling"];
      e [label="5. Analysis of the found models\nto determine if more work\nis needed"\, URL="\ref analysis"];
      a -> b [arrowhead="open"];
      b -> c [arrowhead="open"]
      c -> d [arrowhead="open"];
      d -> e [arrowhead="open"];
      e -> a [arrowhead="open"];
    }
\enddot
}
 
\imp provides a large number of functionality to facilitate this process. Links to representative classes are given for future reference.
-# \anchor dataacq <em> Data acquisition: </em> 
   we can't be much help here as we are computer people and don't know what to do with test tubes.
-# \anchor repsel <em> Representation selection: </em> representation in \imp is via a collection of
  entities called particles (IMP::Particle objects). Each particle can contain one or
  more of the following sets of data
   - \inlineimage{xyz.png, 50} Cartesian coordinates (IMP::core::XYZ)
   - \inlineimage{sphere.png, 50} sphere (IMP::core::XYZR)
   - \inlineimage{atom.png, 50} atom information such as type, element, mass (IMP::atom::Atom)
   - \inlineimage{residue.png, 50} residue type information (IMP::atom::Residue)
   - \inlineimage{chain.png, 50} chain IDs (IMP::atom::Chain)
   - \inlineimage{domain.png, 50} domain extents (IMP::atom::Domain)
   - \inlineimage{mass.png, 50} mass, in daltons (IMP::atom::Mass)
   - \inlineimage{charged.png, 50} charge (IMP::atom::Charged)
   - \inlineimage{hierarchy.png, 50} relationships between parts of molecules (IMP::atom::Hierarchy)
   - \inlineimage{bond.png, 50} bonds (IMP::atom::Bond and IMP::atom::Bonded)
   - \inlineimage{rigid.png, 50} rigid body coordinate frames (IMP::core::RigidBody)
   - \inlineimage{angle.png, 50} bond angle (IMP::atom::Angle)
   - \inlineimage{torsion.png, 50} bond angle (IMP::atom::TorsionAngle)
   - etc.
   .
  In addition, \imp can enforce relationships between particles:
   - \inlineimage{rigid.png, 50} all of the members of a rigid body move along with the rigid body (IMP::core::RigidBody, IMP::core::RigidMember)
   - \inlineimage{centroid.png, 50} a centroid particle has Cartesian coordinates computed from the centroid of another set (IMP::core::Centroid)
   - \inlineimage{spherecover.png, 50} a cover particle has a sphere containing another set of particles (IMP::core::Cover)
   .
  New types of representation can be easily added via a decorator mechanism, which is explained
  more below and on the IMP::Decorator page.\n\n
  Representations can loaded from a number of standard file types, for %example see
  IMP::atom::read_pdb() and IMP::atom::read_mol2().
-# \anchor dataenc <em>Encoding the data as a scoring function: </em>
  Proposed models are scored based on how well they match the
  data, with a low score meaning a closer fit than a high score. In
  \imp the scoring function is the sum terms, each of which is
  computed by an IMP::Restraint object. The scoring function terms can be
  based on things like
    - \inlineimage{distance.png, 50} how close a distance is to the measured value (IMP::core::DistanceRestraint, IMP::core::DistancePairScore, IMP::core::RigidBodyDistancePairScore, IMP::core::SphereDistancePairScore)
    - \inlineimage{em.png, 50} how well the model fits a density map (IMP::em::FitRestraint)
    - \inlineimage{volume.png, 50} how close the volume of a molecule is to the expected value (IMP::core::VolumeRestraint)
    - \inlineimage{ev.png, 50}  excluded volume (steric clash) (IMP::core::ExcludedVolumeRestraint)
    - \inlineimage{connectivity.png, 50} connectivity of a subcomplex (IMP::core::ConnectivityRestraint)
    - \inlineimage{saxs.png, 50} the fit of the SAXS cure of a complex to a measured one (IMP::saxs::Restraint)
    - \inlineimage{protlig.png, 50} statistical potentials (IMP::atom::ProteinLigandRestraint)
    - \inlineimage{angle.png, 50} torsion angles or bond angles (IMP::core::TorsionAngleRestraint, IMP::core::AngleRestraint)
    - \inlineimage{symmetry.png, 50} symmetry: (IMP::core::TransformedDistancePairScore)
    - etc.
    .
  Other terms can be formed by using IMP::SingletonScore, IMP::PairScore, IMP::TripletScore, IMP::QuadScore objects in conjuction with general purpose restraint creators. These allow large number of parts to be scored in similar ways more efficiently than creating many restraints. Examples using this include
    - symmetry by using IMP::core::TransformedDistancePairScore coupled with IMP::container::PairsRestraint
    - bond lengths using an IMP::atom::BondSingletonScore coupled with a IMP::container::SingletonsRestraint
    - etc.
    .
-# \anchor sampling <em> Sampling good conformations: </em> Once the scoring function has been designed you need to search for conformations of the model that
  have low scores (and therefore fit the data well). Sampling produces a set of
  conformations of the model, organized into an IMP::ConformationSet. Currently
  \imp provides two sampling protocols, IMP::core::MCCGSampler which uses a
  combination of IMP::core::MonteCarlo and IMP::core::ConjugateGradients with
  randomized starting conformations and IMP::domino::DominoOptimizer which uses
  a graph based inference algorithm. Sampling is an iterative process that tends to
  be structured as follows:
\dotgraph{ \dot
 digraph sampling {
    node [shape=record\, fontname= Helvetica\, fontsize=10]
      a [label="Sampler sets model to\ninitial\, random\nconfiguration"];
      b [label="Model gives constraints\nchance to update\nconfiguration"];
      c [label="Model asks restraints\nto compute score\n(and derivatives\, if desired)"];
      d [label="Model gives constraints\nchance to update derivatives\n(if desired)"];
      e [label="Sampler uses score\nand derivatives to\nmodify the configuration"];
      a -> b [arrowhead="open"];
      b -> c [arrowhead="open"]
      c -> d [arrowhead="open"];
      d -> e [arrowhead="open"];
      e -> b [arrowhead="open"];
    }
\enddot
}
-# \anchor analysis <em> Analysis of good conformations: </em> 
  Finally, one needs to analyze the set of conformations produced by
  sampling. \imp provides a variety of tools to help display the conformations,
  in IMP::display, and to cluster them, in IMP::statistics. Display capabilities
  include
  - export to Chimera via the IMP::display::ChimeraWriter
  - export to Pymol via the IMP::display::PymolWriter
  Clustering methods are currently based around k-means clustering
  (IMP::statistics::get_lloyds_kmeans()) and supports
  clustering of
  - configurations of the model using IMP::statistics::ConfigurationSetXYZEmbedding
  - arbitrary points using IMP::statistics::VectorDEmbedding
  - density maps using IMP::statistics::HighDensityEmbedding
  

Knowledge about the system being modeled enters the process at all
stages, but a few need extra note:

- The choice of representation must allow the final structure to be represented to
  the desired accuracy.

- A certain amount of knowledge is encoded as "constraints". These are
  choices made in choosing the representation scheme that force
  relationships between parts to always hold. For %example,
  representing part of the system as a rigid body, means that none of
  the distances or angles within the rigid body ever change.

- Other knowledge is encoded as restraints via scoring functions that
  penalize conformations which don't fit that bit of information.

- Knowledge can also be used to tune the sampling scheme by choosing
  starting configurations, how to perform the sampling etc.

Coming up with the right choices for representation, scoring and sampling for
a given system typically takes a few iterations and trial and error. \imp
provides tools to help monitor how things are performing.

- <em> Logging: </em> most actions in \imp can produce logged information to help understand
  what is going on. The amount of logging information produced can be controlled
  globally using the IMP.set_log_level() function and passing it one of the IMP::LogLevel
  values. In addition, restraints, samplers, constraints (and all objects which inherit
  from IMP::Object) have an internal log level that overrides the global one. To set
  that call the IMP::Object::set_log_level() function on that object. Setting the log
  level to IMP::VERBOSE will produce a huge amount of information during a typical
  sampling run. IMP::TERSE is generally better. Make sure to set it to at least
  IMP::WARNING to make sure that you don't miss any important warnings.

- <em> Usage checking: </em> \imp can perform a lot of checks that it is being used correctly
  as well as that it is behaving correctly. The checks being performed are controlled
  by the IMP::set_check_level() function call. Set the check level to IMP::USAGE to
  make sure that all parameters passed are correct. Set it to IMP::USAGE_AND_INTERNAL
  if you are developing new restraints or sampling protocols or are worried that
  \imp is malfunctioning.

- <em> IO: </em> \imp supports I/O to and from a variety of formats. To preserve the maximum amount
  of information, one can use the IMP::read_model() and IMP::write_model() methods to
  save and load a whole model to a human (and machine) readable file. See also the
  IMP::display module for geometry output and IMP::atom for biological formats.

\section i55 2. Concepts
As has already been hinted at, \imp is organized around a number of core concepts.
Representation is handled via a collection of IMP::Particle objects. Each has a
set of arbitrary attributes (such as an x coordinate or a mass). In order to make
particles more friendly, we provide IMP::Decorator classes which, guess what, decorate, an existing
particle to provide a higher level interface to manipulate the attributes of a particle.
See the IMP::Decorator page for more details.

\imp provides containers in order to aid managing sets of particles. These inherit from
IMP::Container (notice that IMP::Particle objects are containers and can contain lists
of particles). A container could
be as simple as an IMP::container::ListSingletonContainer which simply stores a list
of particles. However, it could also be more involved, such as the IMP::container::ClosePairContainer which keeps track of all pairs of particles which are close to one another in space. It can
be used to implemented non-bonded operations for example.

Scoring is handled by a collection of IMP::Restraint objects. Each of these keeps a list
of particles and scores those particles based on how well they fit some sort of data. Some restraints are designed to see if a set of particles fit a particular experimental measurement (eg IMP::em::FitRestraint). Some other restraints are more general, allowing
a particular sort of score function to an
arbitrary container. For example, one can use an IMP::container::PairsRestraint,
coupled with an IMP::container::ClosePairContainer and an IMP::core::SoftSpherePairScore,
to make sure that a collection of balls don't overlap.

The IMP::Model ties together the representation and score. In addition to storing all the
particles and restraints, it allows one to enforce invariant between particles (eg allows \imp to implement rigid bodies using IMP::core::RigidBody), allows one to specify maximum
allowable scores for restraints and ranges for attributes. Invariants are enforced using  IMP::Constraint objects stored in the IMP::Model. They maintain
some hard invariant of the representation. Examples include, keeping a rigid body
rigid, or ensuring that the IMP::container::ClosePairContainer really contains all
close pairs. Constraints are updated as part of the IMP::Model::evaluate().
<em> This means that the constraint does not necessarily hold except during
score evaluation.</em> In order to ensure that all constraints hold, call
IMP::Model::evaluate() before inspecting the particles.

Once the representation and scoring are set up, one needs to find good
conformations of the model. This is done via IMP::Optimizer and
IMP::Sampler-derived classes. The former takes the current state of
the model and tries to change the optimized attributes it so that the
score improves (an optimized attribute is a float attribute where
IMP::Particle::get_is_optimized() returns true). The latter, run more
involved sampling algorithms and return an IMP::ConfigurationSet which
allows one to inspect the found conformations. The process of
optimization or sampling can be observed and influenced via
IMP::OptimizerState objects. The most generally useful of these write
the optimization steps to files so that the process can be observed
(eg IMP::atom::WritePDBOptimizerState). The set of attributes which
are manipulated by the optimizers are controlled by setting the
optimized flag using IMP::Particle::set_is_optimized() or a decorator
method such as IMP::core::XZYR::set_coordinates_are_optimized(). Certain
attributes which are computed as functions of other attributes should
never be set as optimized. Examples include the x,y,z coordinates of
members of a rigid body.

Finally, the found conformations should be analyzed. These conformations would typically be stored in an IMP::ConformationSet. The conformations can be clustered via the
IMP::statistics::get_lloyds_kmeans() function coupled with an IMP::statistics::ConfigurationSetXYZEmbedding. Alternatively, they can be exported
as PDB files (IMP::atom::write_pdb()), Pymol files (IMP::display::PymolWriter) or Chimera
files (IMP::display::ChimeraWriter).


\section i6 3. Examples
The following examples give some idea of the basics of using \imp. They are all are in Python,
but the C++ code is nearly the same.

Each module has an examples page linked from its main page.

\subsection i7 Creating some particles
The function creates a bunch of particles and uses the IMP::core::XYZR decorator to
given them random coordinates and a radius of 1.
\htmlinclude setup.py.html

\subsection i7 Restrain some distances

Once the particles are created, we have to add some restraints. To do this, you must choose
which particles to restraint and then how to restrain them. Given that you create a restraint,
initializing it with the chosen particles and then add it to the model.

\htmlinclude pair_restraint.py.html


\subsection i8 Preventing collisions
The IMP::container::ClosePairsContainer maintains a list of all pairs of particles that are closer than a certain distance. The IMP::core::HarmonicLowerBound forces the spheres apart.
\htmlinclude excluded_volume.py.html


\subsection i9 Restraining bonds

Load a protein and restrain all the bonds to have the correct length. Bond angles is a bit trickier at the moment.

\htmlinclude load_protein_restrain_bonds.py.html






\subsection i10 Sampling and analysis
Once we have set up our restraints, we can run a sampler to compute some good
conformations. Our basic sampler is the IMP::core::MCCGSampler which uses
a combination of Monte Carlo and conjugate gradients to find conformations.
It then returns an object which allows one to load the saved conformations
for analysis.
\htmlinclude basic_optimization.py.html

\subsection i11 Writing a simple restraint
See IMP::example::ExampleRestraint.

\section i125 4. Modules

Functionality in \imp is grouped into modules, each with its own
namespace (in C++) or package (in Python). For %example, the functionality
for IMP::core can be found like
\code
IMP::core::XYZ(p)\endcode
in C++ and
\verbatim
IMP.core.XYZ(p)\endverbatim
in Python.

A module contains classes,
methods and data which are related and controlled by a set of authors. The names
of the authors, the license for the module, its version and an overview of the
module can be found on the module main page (eg IMP::example).
See the "Modules" tab above for a complete list of modules in this version of \imp.

Modules are either grouped based on types of experimental data (eg IMP::em) or based
on shared functionality (IMP::core or IMP::container).


\section i13 5. C++ vs Python
\anchor cpppythondifferences
\imp can be used from both C++ and Python. We recommend that you:
- use Python to put \imp classes together to handle your data and resulting structures
- write new \imp classes in C++

If you are new to programming you should check out a general python 
introduction such as
\external{docs.python.org/tutorial/introduction.html, the official introduction to Python} and
\external{www.rexx.com/~dkuhlman/python_101/python_101.html, Python
101}. Users who have
programmed but are not familiar with Python should take a look at
\external{diveintopython.org/toc/index.html, Dive into Python},
especially chapters 1-6, and 15-18.

While effort has been made to ensure that the interfaces are the same
between the two languages, a number of differences remain due to
differences in the languages and limitations of the program used to
generate the connection between the two languages. Key differences are

- Python does not support templates and so template classes (eg
  IMP::algebra::BoundingBoxD, IMP::VectorOfRefCounted) cannot be
  directly exposed in python. Instead, specific versions of the
  classes are exported (IMP::algebra::BoundingBoxD<3> and
  IMP::Particles, respectively). New versions can be easily added, so
  feel free to request them when desired.
- Iterators on C++ containers do not translate easily into Python. As a
  result, for every iterator generating pair \c foos_begin(),
  \c foos_end(), we provide a method \c get_foos() which can be used
  with python \c foreach loops.
- Macros such as IMP_RESTRAINT(), IMP_LOG(), IMP_USAGE_CHECK() are not
  available in Python. While we could, conceivably, provide python
  function equivalents, we do not.
- Oddly, the Python side is much stricter about converting between
  different types. In C++ you can call a function that takes a \c
  Particle* with a \c Decorator and the decorator will automatically
  be converted. It will not on the python side. Similarly for
  converting between \c ParticlesTemp and \c Particles.
- All \imp exceptions are exposed as identical Python exception
  classes. The class hierarchy is similar (e.g. all exceptions derive
  from IMP::Exception, so "except IMP.Exception" will catch all IMP
  exceptions), except for convenience some generic \imp exceptions also
  derive from their standard Python equivalents
  (e.g. IMP.IndexException derives from the standard Python IndexError
  as well as IMP::Exception). Thus, an IMP::IndexException could be
  caught in Python most specifically with "except IMP.IndexException"
  but also with "except IMP.Exception" or "except IndexError".
- All objects in python are reference counted so that they are cleaned
  up when they are no longer in use. \imp also uses reference counting
  on the C++ side so that memory managment works naturally across the
  language barrier. See IMP::RefCounted for a detailed description of
  how to do \imp reference counting in C++.


\section conventions 6. Conventions

    To ensure consistency and ease of use, certain conventions should be
    adhered to when writing code using or in \imp.

    \subsection physical Measurements
    Unless there is a good reason, the following units are to be used
    - angstrom for all distances
    - \f$ \frac{\operatorname{kcal}}{\operatorname{mol} \AA}\f$ for forces/derivatives
    - \f$\frac{\operatorname{kcal}}{\operatorname{mol}}\f$ for energies
    - radians for angles. All angles are counterclockwise.
    - all charges are in units of the elementary charge

    Anything that breaks from these conventions must be labeled
    clearly and accompanied by an explaination of why the normal units
    could not be used.

    \subsection storage Passing and storing data

    - 3D points and vectors are stored and passed using
      IMP::algebra::VectorD objects.

    - 3D rotations are stored and passed using
      IMP::algebra::Rotation3D objects.

    - Likewise for spheres (IMP::algebra::SphereD), segments
      (IMP::algebra::Segment3D) etc.

    - Collections of object \c Name are passed using the type \c Names. For
    %example, a bunch of IMP::algebra::Vector3D objects are passed using
    a IMP::algebra::Vector3Ds type, and a bunch of IMP::Restraint
    objects is passed using IMP::Restraints (or, equivalently
    IMP::RestraintsTemp).

    - Classes and methods use \imp exceptions to report errors. See
    IMP::Exception for a list of existing exceptions. These C++
    exceptions are mapped onto the normal python exception types.

    \anchor values
    \subsection objects Values and Objects
    As is conventional in C++, \imp classes are divided into two types
    - \e value \e classes which are be passed, stored, and returned by value
      (or, for speed, \c const&). Examples include IMP::algebra::VectorD,
      collections such as IMP::RestraintsTemp, or
      decorators, such as IMP::core::XYZ. In fact, in \imp, anything
      that does not inherit from IMP::RefCounted is a value class.

    - \e object \e classes which are passed and returned via pointers and
      stored using reference counted pointers (eg IMP::Pointer). In
      \imp, these classes all inherit from IMP::Object. For %example always
      do things like this in C++:
      \code
      IMP::Pointer<IMP::Model> m= new IMP::Model();
      IMP_NEW(Model, m, ()); // a macro which expands to the above
      \endcode
      \anchor tempornot Since reference counting can be expensive,
      it can be useful to pass, return or store a non-reference
      counted list of objects (or decorators). This should only
      be done when it is known to be safe. If you can't figure out
      that it is, don't do it. If it is safe, pass a \c NamesTemp
      instead of a \c Names.

    Python does not have this distinction.

    A few classes in \imp are designed for fast, low level use. Their default
    constructor leaves them in an unspecified state. This is similar to
    the built in types in C++ (\c int, \c double). For %example
      \code
      IMP::algebra::VectorD<3> v; // the vector has unknown coordinates
      std::cout << v << std::endl; // illegal
      v= IMP::algebra::VectorD<3>(0,1,2); // now we can use v
      \endcode

    Unless the documentation says otherwise, all \e value
    \e class object in \imp can be compared with other equivalent objects
    based on their contents. \e Object \e class objects allow checking of
    equality to see if they are the same object (not whether two have the
    same state). In C++, this is done by comparing the pointers.
   \subsection standardmethods Standard Methods
    All objects should have a \c const method \c show(std::ostream&), which
    writes some basic information about the object to the supplied stream.
    In addition, on the C++ side, all objects support standard output
    to stream via \c <<. In addition, all objects support \c __str__ in
    python so that they can be printed and displayed.

   \subsection names Names in IMP
    - Class names are in \c CamelCase, for %example \c class \c SpecialVector'
    - For each type of object in \imp, \c Name, there is a type \c Names
      which is used to pass a list of objects of type \c Name. \c Names
      look like an \c std::vector in C++ or a \c list in Python. Sometimes,
      for efficiency, a \c NamesTemp is passed instead
      (see \ref tempornot "when to use Temp values" for the reason). \c Names
      will be converted into \c NamesTemp without cost, so the distinction
      should not matter for the caller.
    - method names and variables are \c separated_by_underscores, for
      %example \c void \c SpecialVector::add_constant(int the_constant)'
    - member methods that change a value begin with \c set_
    - member methods or function which create or return a \c value object or which
      return an existing \c object \c class object begin with \c get_. No arguments
      of such functions are modified.
    - methods or functions which create a new IMP::Object \c class object start
      with \c create_.
    - functions with names starting with other verbs have more complicated effects. For
      %example IMP::core::transform() changes the first argument based on the second.
      IMP::Restraint::evaluate() computes a score as well as (optionally) adding to
      Particle derivatives.
    - all preprocessor symbols (things created by \c \#define) begin with \c %IMP_
    - Abbreviations are not used in names except when the abbreviation is more
      common than the unabreviated name.

  \subsection raii RAII
    RAII-style objects are a convenient way of controlling a resource. They
    assume "ownership" of the resource on creation and then "free" it on
    destruction. Examples include, using a reference counted pointer to
    make sure an object is destroyed when it is no longer needed
    \code
    {
      Pointer<PymolWriter> pw= new PymolWriter("afile.pym");
      // write to pw
    } // pw is deleted here
    \endcode
    Or temporarily removing a restraint from the model
    \code
    {
      ScopedRemoveRestraint srr(new MyRestraint(), m->get_root_restraint_set());
      // optimize the "relaxed" model without the restraint
    } // restraint is automatically added back
    \endcode
    RAII objects also help with exception safety since they guarantee that
    the cleanup code occurs when an exception occurs. Compare
    \code
    void transform_map(std::string in) {
      DensityMap *map= read_map(in);
      // transform the map
      write_map(map, "/unwriteable/directory/map.mrc");
      delete map;
    }
    \endcode
    When write_map() throws an exception due to being unable to open the file
    for writing, the (large) block of memory allocated in map is lost. Instead,
    one should do:
    \code
    void transform_map(std::string in) {
      Pointer<DensityMap> map= read_map(in);
      // transform the map
      write_map(map, "/unwriteable/directory/map.mrc");
    }
    \endcode
    So that map is always destroyed.

    As pretty much any operation can throw an exception any time, one can never
    count on general cleanup code to excute.

\section incremental 7. Incremental Scoring
    Scoring in \imp can be performed in two different ways, 
    - whole model, where each restraint is evaluated each time the model is changed
    - or incremental, where restraints are given the opportunity to update their scores after only a few of the particles change.

    Whole model scoring is faster when more than approximately half of the particles change each time the Model::evaluate() is called. Either one will produce the correct (and same) answer in all instances.

    To set up incremental scoring call IMP::Model::set_is_incremental() with the value \c true. See \ref scoring "Scoring" for implementation information.

\section graphs 8. Graphs

Graphs in \imp are represented using the \external{www.boost.org/doc/libs/release/libs/graph, Boost Graph Library}. All graphs used in \imp are \external{www.boost.org/doc/libs/1_43_0/libs/graph/doc/VertexAndEdgeListGraph.html, VertexAndEdgeListGraphs}, have vertex_name properties,
are either \external{www.boost.org/doc/libs/1_43_0/libs/graph/doc/BidirectionalGraph.html, and are BidirectionalGraphs}.

The Boost.Graph interface cannot be easily exported to Python so we instead provide a simple wrapper which looks as follows
\code
class Graph {
public:
  class VertexDescriptor;
  class VertexDescriptors;
  class VertexName;
  Vertices get_vertices();
  VertexDescriptors get_in_neighbors(VertexDescriptor);
  VertexDescriptors get_out_neighbors(VertexDescriptor);
  void add_edge(VertexDescriptor, VertexDescriptor);
  VertexDescriptor add_vertex(VertexName);
};
\endcode
Each vertex has a descriptor which provides a unique identifier for the vertex as well as a name, which need not be unique.

The python wrapper should be considered unstable. If there is a python graph library which users would like to use, we will adapt the python interface for that library.

\section fasterfaster 9. Making IMP run faster

Sampling can often be very computationally expensive. If you computation is taking longer than you would like, the first thing you should do is to profile it. We find \external{developer.apple.com/tools/sharkoptimize.html,Shark} and \external{developer.apple.com/library/mac/#documentation/Performance/Conceptual/PerformanceOverview/InitialEvaluation/InitialEvaluation.html#//apple_ref/doc/uid/TP40001410-CH206-SW7, Instruments} which are part of the Macintosh developer tools to be the best free Mac/Linux options. \external{www.cs.utah.edu/dept/old/texinfo/as/gprof.html, gprof} is a free alternative on linux, but it requires a static build (and hence can't work with python) and is not so friendly to use.

Once you know where your application is spending its time, we provide a number of facilities to speed up \imp computations. These include:

\subsection parametertuning Parameter tuning

Certain classes, such as IMP::container::ClosePairContainer, have parameters which influence how fast they perform. IMP::container::ClosePairContainer has a helper method, IMP::container::get_slack_estimate() which tries to figure out a good value for that slack.

\subsection specializing Specializing for speed

The usual pattern in \imp is to plug various classes together via what is known as virtual function calls. Composing this way is very flexible, but is not necessarily very fast as the C++ compiler is not able to take advantage simplifications across function calls. To get around this, we provide some specialized classes which act as composits of other classes. For example:
- IMP::core::SoftSpherePairScore which is equivalent to IMP::core::SphereDistancePairScore with a IMP::core::HarmonicLowerBound
- IMP::core::HarmonicDistancePairScore which is equivalent to IMP::core::DistancePairScore with a IMP::core::Harmonic
These can be twice or more faster than the classes they replace.

\anchor cppspecialization
C++ users can also take compose classes via templates at compile time. This is done using IMP::core::TupleRestraint, IMP::core::TupleConstraint, IMP::container::ContainerRestraint, IMP::container::ContainerConstraint. When using these, make sure you provide the actual types of the scores, modifiers and containers used (not the base classes). For example do
\code
m->add_restraint(IMP::core::create_restraint(new IMP::core::HarmonicDistancePairScore(3, 1),
                                            IMP::ParticlePair(p0, p1)))
\endcode
which is equivalent to
 \code
m->add_restraint(new IMP::core::TupleRestraint<HarmonicDistancePairScore>(new IMP::core::HarmonicDistancePairScore(3, 1),
                                                                          IMP::ParticlePair(p0, p1)))
\endcode
which, in turn, is equivalent to, but faster than
\code
m->add_restraint(new IMP::core::PairRestraint(new IMP::core::HarmonicDistancePairScore(3,1),
                                              IMP::ParticlePair(p0, p1)));
\endcode

\section fixbug 10. Reporting bugs

While we strive for perfection, we, lamentably, slip up from time to
time. If you find a bug in \imp, please report it on the
\salilabssl{imp/bugs/,IMP bug tracker}. This will ensure it does not get
lost.  The best way to report a bug is to provide a short script file
that demonstrates the problem.



\section next 11. Where to go next
Instructions on how to build and install \imp can be found in
the \ref installation "installation instructions".

There are a few areas of core functionality that have already been mentioned.
- IMP::Decorator
- \ref log "Logging Support"
- \ref assert "Error Reporting Facilities"

Then look through the examples which can be found linked from the page of each module.
 
There are a variety of useful base classes which are used to provide
most functionality. They are:
    - IMP::Model
    - IMP::Particle
    - IMP::Decorator
    - IMP::Restraint
    - IMP::Constraint
    - IMP::Sampler
    - IMP::Optimizer
    - IMP::SingletonContainer, IMP::PairContainer
    - IMP::SingletonScore, IMP::PairScore, IMP::TripletScore
    - IMP::SingletonModifier, IMP::PairModifier

There are a few blocks of functionality that cut across modules. They
include
- \ref hierarchy "Code to create and manipulate hierarchies"
- \ref bond "Code to create and manipulate bonds"

When programming with \imp, one of the more useful pages is the
\internal{namespaces.html, modules list}.

For general help, you can use the \impusers mailing list.

*/