Detailed Description

The IMP kernel provides base classes and key shared functionality.

The IMP kernel provides the base functionality and abstract base classes for representation, scoring and sampling. In addition it provides basic functionality such as I/O, logging and Error Reporting support as well as tools to help implement functionality.

Examples:

Author(s): Daniel Russel, Ben Webb

Version: SVN.r12662 with Boost.FileSystem

License: LGPL. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Publications:

Daniel Russel, Keren Lasker, Ben Webb, Dina Schneidman, Javier Velázquez-Muriel, Andrej Sali, “Putting the pieces together: integrative structure determination of macromolecular assemblies”, PLoS Biology, 2012. This paper provides an overview of the key concepts in IMP and how to apply them to biological problems.
Frank Alber, Friedrich Foerster, Dmitry Korkin, Maya Topf, Andrej Sali, “Integrating diverse data for structure determination of macromolecular assemblies”, Annual Review of Biochemistry, 2008. This paper provides a review of the integrative structure determination methodology and various data sources that can be used.

Namespaces
namespace	algebra
	This module contains general purpose algebraic and geometric methods.
namespace	atom
	This module contains functionality for dealing with atoms and proteins.
namespace	base
	This module provides low level functionality used by all of `IMP`.
namespace	benchmark
	This module provides benchmarks of a variety of aspects of `IMP`.
namespace	bullet
	This module provides a wrapper for the Bullet physics engine.
namespace	cgal
	This module provides `IMP` wrappers for various algorithms implemented in CGAL.
namespace	compatibility
	This module tries to smooth over the variations in platforms.
namespace	container
	This module provides containers in `IMP`.
namespace	core
	This module contains basic functionality that is expected to be used by a wide variety of `IMP` users.
namespace	display
	This module provides support for displaying and exporting `IMP` data in various ways.
namespace	domino
	This module provides a divide and conquer sampler. It provides a simpler interface and (hopefully) faster performance than the original IMP.domino module.
namespace	em
	This module allows density maps to be used to generate restraints.
namespace	em2d
	This module provides functionality to use two-dimensional EM images as restraints.
namespace	example
	This module provides example showing how to implement various types of objects and functionality in `IMP`.
namespace	gsl
	This module wraps optimizers from the GNU Scientific Library.
namespace	isd
	Inferential scoring.
namespace	misc
	This module contains miscellaneous and experimental functionality.
namespace	modeller
	This module contains functionality for integrating Modeller with IMP.
namespace	multifit
	This module contains a protocol for fitting proteins to EM maps.
namespace	parallel
	Support for parallel tasks that communicate infrequently.
namespace	pepdock
	Peptide docking method.
namespace	restrainer
	This module provides a higher level interface for using experimental proteomics data with `IMP`.
namespace	rmf
	This module provides RMF I/O for `IMP`.
namespace	saxs
	This module adds small angle X-ray scattering support to `IMP`.
namespace	scratch
	A place for testing classes and functions.
namespace	statistics
	This module provides methods for clustering, histograms and other statistical computations.
namespace	system
	This module provides helper functions for biological systems.
namespace	test
	Methods and classes for testing the IMP kernel and modules.
Classes
class	Configuration
	A class to store a configuration of a model. More...
class	ConfigurationSet
	A class to store a set of configurations of a model. More...
class	Constraint
	Implement a constraint on the Model. More...
class	Container
	Abstract class for containers of particles. More...
class	Decorator
class	DerivativeAccumulator
	Class for adding derivatives from restraints to the model. More...
class	GenericScopedRemoveRestraint
	Removes the Restraint until RAII object is destroyed. More...
class	GenericScopedRemoveScoreState
	Removes the ScoreState until RAII object is destroyed. More...
class	GenericScopedRestraint
	Removes the Restraint when the RAII object is destroyed. More...
class	GenericScopedScoreState
	Removes the ScoreState when the RAII object is destroyed. More...
class	Key
	A base class for Keys. More...
class	Model
	Class for storing model, its restraints, constraints, and particles. More...
class	Optimizer
	Base class for all optimizers. More...
class	OptimizerState
	Shared optimizer state. More...
class	PairContainer
	A shared container for Pairs. More...
class	PairDerivativeFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	PairDerivativeModifier
	A base class for modifiers of ParticlePairsTemp. More...
class	PairFilter
	A shared filter for Pairs. More...
class	PairFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	PairModifier
	A base class for modifiers of ParticlePairsTemp. More...
class	PairPredicate
	Abstract predicate function. More...
class	PairScore
	Abstract score function. More...
class	PairScoreRestraint
class	PairsScoreRestraint
class	Particle
	Class to handle individual model particles. More...
class	ParticleTuple
	A class to store a tuple of particles. More...
class	PivyWriter
class	PythonDirectedGraph
class	QuadContainer
	A shared container for Quads. More...
class	QuadDerivativeFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	QuadDerivativeModifier
	A base class for modifiers of ParticleQuadsTemp. More...
class	QuadFilter
	A shared filter for Quads. More...
class	QuadFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	QuadModifier
	A base class for modifiers of ParticleQuadsTemp. More...
class	QuadPredicate
	Abstract predicate function. More...
class	QuadScore
	Abstract score function. More...
class	QuadScoreRestraint
class	QuadsScoreRestraint
class	Refiner
	Abstract class to implement hierarchical methods. More...
class	Restraint
	Abstract class for representing restraints. More...
class	RestraintSet
	Container used to hold a set of restraints. More...
class	RestraintStatistics
class	Sampler
	Base class for all samplers. More...
class	ScopedAddCacheAttribute
class	ScopedFailureHandler
	Control a scope-dependent failure handler. More...
class	ScopedSetAttribute
class	ScoreState
	Shared score state. More...
class	SingletonContainer
	A shared container for Singletons. More...
class	SingletonDerivativeFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	SingletonDerivativeModifier
	A base class for modifiers of ParticlesTemp. More...
class	SingletonFilter
	A shared filter for Singletons. More...
class	SingletonFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	SingletonModifier
	A base class for modifiers of ParticlesTemp. More...
class	SingletonPredicate
	Abstract predicate function. More...
class	SingletonScore
	Abstract score function. More...
class	SingletonScoreRestraint
class	SingletonsScoreRestraint
class	TripletContainer
	A shared container for Triplets. More...
class	TripletDerivativeFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	TripletDerivativeModifier
	A base class for modifiers of ParticleTripletsTemp. More...
class	TripletFilter
	A shared filter for Triplets. More...
class	TripletFunctor
	Create a functor which can be used with build in C++ and python commands. More...
class	TripletModifier
	A base class for modifiers of ParticleTripletsTemp. More...
class	TripletPredicate
	Abstract predicate function. More...
class	TripletScore
	Abstract score function. More...
class	TripletScoreRestraint
class	TripletsScoreRestraint
class	UnaryFunction
	Abstract single variable functor class for score functions. More...
class	VectorOfRefCounted
	A vector-like container for reference counted objects. More...
Standard module methods
All `IMP` modules have a set of standard methods to help get information about the module and about file associated with the modules.
std::string	get_module_version ()
std::string	get_module_name ()
void	set_use_algebra (bool tf)
bool	get_use_algebra ()
void	set_use_cgal (bool tf)
bool	get_use_cgal ()
void	set_use_base (bool tf)
bool	get_use_base ()
void	set_use_compatibility (bool tf)
bool	get_use_compatibility ()
std::string	get_data_path (std::string file_name)
	Return the full path to installed data.
std::string	get_example_path (std::string file_name)
	Return the path to installed example data for this module.
Gathering restraints
It is sometimes useful to extract all the non-RestraintSet restraints from a hierarchy involving RestraintSets mixed with Restraints.
typedef std::pair < RestraintsTemp, Floats >	RestraintsAndWeights
RestraintsAndWeights	get_restraints_and_weights (const RestraintsTemp &rs, double initial_weight=1)
RestraintsTemp	get_restraints (const RestraintsTemp &rs)
template<class It >
RestraintsAndWeights	get_restraints_and_weights (It b, It e, double initial_weight=1)
template<class It >
RestraintsTemp	get_restraints (It b, It e)
template<class It >
RestraintSetsTemp	get_restraint_sets (It b, It e)
Attribute Keys
Each type of attribute has an associated type of key. The keys can be constructed from a string. Such construction can be expensive and so the resulting keys should be cached.
typedef Key< 0, true >	FloatKey
	The type used to identify float attributes in the Particles.
typedef Key< 1, true >	IntKey
	The type used to identify int attributes in the Particles.
typedef Key< 2, true >	StringKey
	The type used to identify string attributes in the Particles.
typedef Key< 3, true >	ParticleKey
	The type used to identify a particle attribute in the Particles.
typedef Key< 4, true >	ObjectKey
	The type used to identify a particle attribute in the Particles.
typedef Key< 5, true >	IntsKey
	The type used to identify int attributes in the Particles.
typedef Key< 6, true >	ParticlesKey
	The type used to identify a particle attribute in the Particles.
typedef Key< 7, true >	ObjectsKey
	The type used to identify a particle attribute in the Particles.
typedef Key< 8, true >	ModelKey
	The type used to identify data stored directly in the model.
Buffer I/O
Write/read the state of the particles to/from a buffer in memory. Note: Not all particles need to have all the attributes, missing attributes will be skipped. However, the set of attributes must match on the write and read particles. There is no handling of architectural issues. That is, this is only guaranteed to work if it is read and written on the same operating system and system bit length. We could probably fix this. both these methods should be considered unstable.
vector< char >	write_particles_to_buffer (const ParticlesTemp &particles, const FloatKeys &keys)
	return a binary buffer with the data
void	read_particles_from_buffer (const vector< char > &buffer, const ParticlesTemp &particles, const FloatKeys &keys)
	load found attributes into the particles
Pruned dependency graphs
The pruned dependency graph merges all particles which have the same dependencies to produce a simpler graph.
DependencyGraph	get_pruned_dependency_graph (Model *m)
DependencyGraph	get_pruned_dependency_graph (const RestraintsTemp &rs)
Python Only
The following functions are only available in python.
void	show_altgraph (Graph g)
networkx::DiGraph	get_networkx_graph (Graph g)
std::string	show_graphviz (Graph g)
Typedefs
typedef boost::graph	DependencyGraph
	A directed graph on the interactions between the various objects in the model.
typedef std::pair< double, double >	DerivativePair
	A pair representing a function value with its first derivative.
typedef double	Float
	Basic floating-point value (could be float, double...)
typedef std::pair< double, double >	FloatPair
	A generic pair of floats.
typedef std::pair< Float, Float >	FloatRange
	A pair representing the allowed range for a Float attribute.
typedef int	Int
	Basic integer value.
typedef std::pair< Int, Int >	IntPair
typedef std::pair< Int, Int >	IntRange
typedef IMP::VectorOfRefCounted < Particle * >	Particles
typedef vector< Particle * >	ParticlesTemp
typedef vector< vector < Particle * > >	ParticlesTemps
typedef GenericScopedRemoveRestraint < Restraint >	ScopedRemoveRestraint
	Remove a restraint until the object goes out of scope.
typedef GenericScopedRemoveScoreState < ScoreState >	ScopedRemoveScoreState
	Remove a score state until the object goes out of scope.
typedef GenericScopedRestraint < Restraint >	ScopedRestraint
	Remove a restraint when the object goes out of scope.
typedef GenericScopedScoreState < ScoreState >	ScopedScoreState
	Remove a score state when the object goes out of scope.
typedef ScopedSetAttribute < FloatKey, Float >	ScopedSetFloatAttribute
typedef std::string	String
	Basic string value.
Functions
template<class Before , class After >
Constraint *	create_constraint (Before b, After a, const typename Before::Argument &t, std::string name=std::string())
template<class Functor >
SingletonModifier *	create_particle_modifier (const Functor &f)
template<class Functor >
PairModifier *	create_particle_pair_modifier (const Functor &f)
template<class Functor >
QuadModifier *	create_particle_quad_modifier (const Functor &f)
template<class Functor >
TripletModifier *	create_particle_triplet_modifier (const Functor &f)
template<class Score >
Restraint *	create_restraint (Score *s, const typename Score::Argument &t, std::string name=std::string())
template<class Score >
Restraint *	create_restraint (const Score *s, const typename Score::Argument &t, std::string name=std::string())
const algebra::BoundingBoxD< 3 >	get_bounding_box_d_geometry (Particle *p)
DependencyGraph	get_dependency_graph (const RestraintsTemp &rs)
DependencyGraph	get_dependency_graph (const ScoreStatesTemp &ss, const RestraintsTemp &rs)
ParticlesTemp	get_dependent_particles (Particle *p, const ParticlesTemp &all)
ParticlesTemp	get_dependent_particles (Particle *p, const ParticlesTemp &all, const DependencyGraph &dg)
RestraintsTemp	get_dependent_restraints (Particle *p, const ParticlesTemp &all, const DependencyGraph &dg)
ScoreStatesTemp	get_ordered_score_states (const DependencyGraph &dg)
ScoreStatesTemp	get_required_score_states (const RestraintsTemp &rs)
const algebra::Sphere3D	get_sphere_d_geometry (Particle *p)
const algebra::Vector3D	get_vector_d_geometry (Particle *p)
void	set_print_deprecation_messages (bool tf)
	Toggle printing of warnings on using deprecated classes.
void	set_sphere_d_geometry (Particle *p, const algebra::Sphere3D &v)
void	set_vector_d_geometry (Particle *p, const algebra::Vector3D &v)
void	show_restraint_hierarchy (RestraintSet *rs, std::ostream &out=std::cout)
	Print the hierarchy of restraints.
template<class A , class B >
void	swap (Decorators< A, B > &a, Decorators< A, B > &b)
Variables
const std::nullptr_t	nullptr
static const double	PI = algebra::PI

Typedef Documentation

typedef boost::graph IMP::DependencyGraph

A directed graph on the interactions between the various objects in the model.

The vertices are named by the associated Object*. There is an edge from a to b, if a is an input to b. For example, there is an edge from a particle to a restraint if the restraint directly reads the particle.

See Graphs in IMP for more information.

typedef std::pair<double, double> IMP::DerivativePair

A pair representing a function value with its first derivative.

typedef double IMP::Float

Basic floating-point value (could be float, double...)

typedef Key<0, true> IMP::FloatKey

The type used to identify float attributes in the Particles.

typedef std::pair<double, double> IMP::FloatPair

A generic pair of floats.

typedef std::pair<Float, Float> IMP::FloatRange

A pair representing the allowed range for a Float attribute.

typedef int IMP::Int

Basic integer value.

typedef Key<1, true> IMP::IntKey

The type used to identify int attributes in the Particles.

typedef Key<5, true> IMP::IntsKey

The type used to identify int attributes in the Particles.

typedef Key<8, true> IMP::ModelKey

The type used to identify data stored directly in the model.

typedef Key<4, true> IMP::ObjectKey

The type used to identify a particle attribute in the Particles.

typedef Key<7, true> IMP::ObjectsKey

The type used to identify a particle attribute in the Particles.

typedef Key<3, true> IMP::ParticleKey

The type used to identify a particle attribute in the Particles.

typedef Key<6, true> IMP::ParticlesKey

The type used to identify a particle attribute in the Particles.

typedef GenericScopedRemoveRestraint<Restraint> IMP::ScopedRemoveRestraint

Remove a restraint until the object goes out of scope.

typedef GenericScopedRemoveScoreState<ScoreState> IMP::ScopedRemoveScoreState

Remove a score state until the object goes out of scope.

typedef GenericScopedRestraint<Restraint> IMP::ScopedRestraint

Remove a restraint when the object goes out of scope.

typedef GenericScopedScoreState<ScoreState> IMP::ScopedScoreState

Remove a score state when the object goes out of scope.

typedef std::string IMP::String

Basic string value.

typedef Key<2, true> IMP::StringKey

The type used to identify string attributes in the Particles.

Function Documentation

template<class Before , class After >

Constraint* IMP::create_constraint	(	Before *	b,
		After *	a,
		const typename Before::Argument &	t,
		std::string	name = `std::string()`
	)

When programming in C++, you can use generic constraint instead of a SingletonConstraint, PairConstraint, etc. The result is somewhat faster (20% or so). See specializing for speed for more information.

template<class Functor >

SingletonModifier* IMP::create_particle_modifier ( const Functor & f )

Create a modifier from a functor. C++ only. The function should take a Singleton as an argument. This is intended to be used as a temporary object and not stored. A reference to the functor is saved.

template<class Functor >

PairModifier* IMP::create_particle_pair_modifier ( const Functor & f )

Create a modifier from a functor. C++ only. The function should take a Pair as an argument. This is intended to be used as a temporary object and not stored. A reference to the functor is saved.

template<class Functor >

QuadModifier* IMP::create_particle_quad_modifier ( const Functor & f )

Create a modifier from a functor. C++ only. The function should take a Quad as an argument. This is intended to be used as a temporary object and not stored. A reference to the functor is saved.

template<class Functor >

TripletModifier* IMP::create_particle_triplet_modifier ( const Functor & f )

Create a modifier from a functor. C++ only. The function should take a Triplet as an argument. This is intended to be used as a temporary object and not stored. A reference to the functor is saved.

template<class Score >

Restraint* IMP::create_restraint	(	Score *	s,
		const typename Score::Argument &	t,
		std::string	name = `std::string()`
	)

When programming in C++, you can use generic restraint instead of a SingletonRestraint, PairRestraint, etc. The result is somewhat faster (20% or so). See specializing for speed for more information.

const algebra::BoundingBoxD<3> IMP::get_bounding_box_d_geometry ( Particle * p )

std::string IMP::get_data_path ( std::string file_name )

Return the full path to installed data.

Each module has its own data directory, so be sure to use the version of this function in the correct module. To read the data file "data_library" that was placed in the data directory of module "mymodule", do something like

    std::ifstream in(IMP::mymodule::get_data_path("data_library"));

This will ensure that the code works when IMP is installed or used via the tools/imppy.sh script.

IMP::get_dependency_graph ( const RestraintsTemp & rs )

The dependency graph captures the interactions between Restraint, ScoreState and Particle objects. The graph has an edge if the source of the edge is an input for the target of the edge. eg, there is an edge connecting a Container to the Restraint which gets its particles from the Container. In order for a given Restraint to be evaluated properly, all of the Particles connected by a path to the Restraint must be up to date.

See also:: get_pruned_dependency_graph()

Examples: dependency graph

DependencyGraph IMP::get_dependency_graph	(	const ScoreStatesTemp &	ss,
		const RestraintsTemp &	rs
	)

The dependency graph captures the interactions between Restraint, ScoreState and Particle objects. The graph has an edge if the source of the edge is an input for the target of the edge. eg, there is an edge connecting a Container to the Restraint which gets its particles from the Container. In order for a given Restraint to be evaluated properly, all of the Particles connected by a path to the Restraint must be up to date.

See also:: get_pruned_dependency_graph()

Examples: dependency graph

ParticlesTemp IMP::get_dependent_particles	(	Particle *	p,
		const ParticlesTemp &	all
	)

Returns the subset of particles that depend on p as input. This will include p. The variable all is the set of all other particles of interest, they will block dependency propagation.

Note:: This function is here to aid in debugging of optimization protocols that use Domino. As a result, its signature and functionality may change without notice.

ParticlesTemp IMP::get_dependent_particles	(	Particle *	p,
		const ParticlesTemp &	all,
		const DependencyGraph &	dg
	)

Returns the subset of particles that depend on p as input. This will include p. The variable all is the set of all other particles of interest, they will block dependency propagation.

Note:: This function is here to aid in debugging of optimization protocols that use Domino. As a result, its signature and functionality may change without notice.

RestraintsTemp IMP::get_dependent_restraints	(	Particle *	p,
		const ParticlesTemp &	all,
		const DependencyGraph &	dg
	)

Return all the restraints that depend on p as an input, even indirectly.

std::string IMP::get_example_path ( std::string file_name )

Return the path to installed example data for this module.

Each module has its own example directory, so be sure to use the version of this function in the correct module. For example to read the file example_protein.pdb located in the examples directory of the IMP::atom module, do

    IMP::atom::read_pdb(IMP::atom::get_example_path("example_protein.pdb", model));

This will ensure that the code works when IMP is installed or used via the tools/imppy.sh script.

networkx::DiGraph IMP::get_networkx_graph ( Graph g )

Export an IMP graph to a networkx graph. The resulting graph can be analyzed and displaye, although the graph layout algorithms in networkx seem to be quite poor compared to graphviz.

One a mac, such graphs can be displayed by

import matplotlib
matplotlib.use("macosx")
import matplotlib.pyplot as plt

import networkx
networkx.draw_spring(xg)
plt.show()

ScoreStatesTemp IMP::get_ordered_score_states ( const DependencyGraph & dg )

Return an ordering for the score states that is consistent with the dependencies show in the dependency graph.

IMP::get_pruned_dependency_graph ( const RestraintsTemp & rs )

Examples: dependency graph

ScoreStatesTemp IMP::get_required_score_states ( const RestraintsTemp & rs )

Get the score states required by the passed restraints.

const algebra::Sphere3D IMP::get_sphere_d_geometry ( Particle * p )

const algebra::Vector3D IMP::get_vector_d_geometry ( Particle * p )

void IMP::read_particles_from_buffer	(	const vector< char > &	buffer,
		const ParticlesTemp &	particles,
		const FloatKeys &	keys
	)

load found attributes into the particles

void IMP::set_print_deprecation_messages ( bool tf )

Toggle printing of warnings on using deprecated classes.

If set to true (the default) a warning is printed every time a class marked as deprecated is used.

See also:: IMP_DEPRECATED

void IMP::set_sphere_d_geometry	(	Particle *	p,
		const algebra::Sphere3D &	v
	)

void IMP::set_vector_d_geometry	(	Particle *	p,
		const algebra::Vector3D &	v
	)

void IMP::show_altgraph ( Graph g )

Use the python altgraph package to graphically display a graph. Note that is requires X11 to be running (you can find it in your Utilities folder in MacOS) and the window produced is shockingly retro.

An alterntative is to write the graph to a dot file

    g.show_graphviz(open("graph.dot", "w"));

then turn it to pdf with dot

 dot -Tpdf graph.dot > graph.pdf

and finally view the pdf.

std::string IMP::show_graphviz ( Graph g )

Generate a nice pdf of the graph and attempt to open the pdf. The name of the pdf will be returned in case the attempt to open it fails.

void IMP::show_restraint_hierarchy	(	RestraintSet *	rs,
		std::ostream &	out = `std::cout`
	)

Print the hierarchy of restraints.

vector<char> IMP::write_particles_to_buffer	(	const ParticlesTemp &	particles,
		const FloatKeys &	keys
	)

return a binary buffer with the data

Variable Documentation

const std::nullptr_t IMP::nullptr

The C++0x standard adds the nullptr keyword to get around a variety of problems with NULL. We provide an emulation within the IMP namespace when it is not available.

Use "nullptr" in code; the compiler will use our IMP::nullptr emulation automatically on systems that don't provide a native nullptr implementation.

If you are not in the IMP namespace, use the IMP_NULLPTR macro rather than asking for "IMP::nullptr". The latter does not work with some compilers (e.g. MSVC, which gets confused because nullptr is a keyword).

Detailed Description

Namespaces

Classes

Standard module methods

Gathering restraints

Attribute Keys

Buffer I/O

Pruned dependency graphs

Python Only

Typedefs

Functions

Variables

Typedef Documentation

Function Documentation

Variable Documentation