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 8931 with Boost.FileSystem, NetCDFCPP

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, “Integrative assembly modeling using IMP”, submitted, 2010. 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	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	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	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	hdf5
	This module provides rich file I/O for `IMP`.
namespace	misc
	This module contains miscellaneous and experimental functionality.
namespace	multifit
	This module contains a protocol for fitting proteins to EM maps.
namespace	openmm
	This module provides example showing how to implement various types of objects and functionality in `IMP`.
namespace	restrainer
	This module provides a higher level interface for using experimental proteomics data with `IMP`.
namespace	saxs
	This module adds small angle X-ray scattering support to `IMP`.
namespace	statistics
	This module provides methods for clustering, histograms and other statistical computations.
namespace	system
	This module provides helper functions for biological systems.
Data Structures
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...
struct	CreateLogContext
	Execute the code block if a certain level of logging is on. More...
class	Decorator
class	DerivativeAccumulator
	Class for adding derivatives from restraints to the model. More...
class	Exception
	The general base class for `IMP` exceptions. More...
class	FailureHandler
class	FailureHandlerBase
	A base class for setting up failure handlers. More...
class	GenericScopedRemoveRestraint
	Removes the Restraint 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	IndexException
	An exception for a request for an invalid member of a container. More...
struct	InternalException
	Execute the code block if a certain level checks are on. More...
class	IOException
	An input/output exception. More...
class	Key
	A base class for Keys. More...
class	Model
	Class for storing model, its restraints, constraints, and particles. More...
class	ModelException
	An exception which is thrown when the Model has attributes with invalid values. More...
class	Object
	Common base class for heavy weight `IMP` objects. More...
class	Optimizer
	Base class for all optimizers. More...
class	OptimizerState
	Shared optimizer state. More...
class	PairContainer
	A shared container for Pairs. 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	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	Pointer
	A reference counted pointer to an object. More...
class	QuadContainer
	A shared container for Quads. 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	QuadScore
	Abstract score function. More...
class	QuadScoreRestraint
class	QuadsScoreRestraint
class	RefCounted
	Common base class for ref counted objects. More...
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	Sampler
	Base class for all samplers. More...
class	SaveOptimizeds
	Save and restore the set of optimized attributes for a set of particles. More...
class	ScopedFailureHandler
	Control a scope-dependent failure handler. More...
class	ScoreState
	Shared score state. More...
class	SetLogState
	A class to change and restore log state. More...
class	SetLogTarget
class	SingletonContainer
	A shared container for Singletons. 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	SingletonScore
	Abstract score function. More...
class	SingletonScoreRestraint
class	SingletonsScoreRestraint
class	TextInput
class	TextOutput
class	TripletContainer
	A shared container for Triplets. 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	TripletScore
	Abstract score function. More...
class	TripletScoreRestraint
class	TripletsScoreRestraint
class	UnaryFunction
	Abstract single variable functor class for score functions. More...
class	UsageException
	An exception for an invalid usage of `IMP`. More...
class	ValueException
	An exception for an invalid value being passed to `IMP`. More...
class	VectorOfRefCounted
	A vector-like container for reference counted objects. More...
class	VersionInfo
	Version and module information for Objects. More...
class	WeakPointer
	A weak pointer to an IMP::Object or IMP::RefCountedObject. More...
class	WriteParticlesBinaryFailureHandler
class	WriteParticlesBinaryOptimizerState
class	WriteParticlesFailureHandler
class	WriteParticlesOptimizerState
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)
RestraintsAndWeights	get_restraints_and_weights (const RestraintSet *rs)
RestraintsTemp	get_restraints (const RestraintsTemp &rs)
RestraintsTemp	get_restraints (const RestraintSet *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)
Error checking and reporting
By default `IMP` performs a variety of runtime error checks. These can be controlled using the IMP::set_check_level function. Call IMP::set_check_level with IMP::NONE to disable all checks when you are performing your optimization as opposed to testing your code. Make sure you run your code with the level set to at least USAGE before running your final optimization to make sure that `IMP` is used correctly.Error handling is provided by IMP/exception.h,Use the `gdbinit` file provided in `tools` to automatically have `gdb` break when `IMP` errors are detected.
enum	CheckLevel { NONE = 0, USAGE = 1, USAGE_AND_INTERNAL = 2 }
	Determine the level of runtime checks performed. More...
CheckLevel	get_maximum_check_level ()
	Determine the maximum check level that can be used for this build.
void	set_check_level (CheckLevel tf)
	Control runtime checks in the code.
CheckLevel	get_check_level ()
	Get the current audit mode.
void	set_print_exceptions (bool tf)
	Set whether exception messages are printed or not.
Logging
`IMP` provides tools for controlling the amount of log output produced and directing it to the terminal or a file. Only log messages tagged with a lower level than the current LogLevel are emitted. In addition to a global log level (get_log_level(), set_log_level()), each IMP::Object has an internal log level (IMP::Object::get_log_level(), IMP::Object::set_log_level()) which is used when executing code on that object.Logging is provided by IMP/log.h.People implementing IMP::Object classes should also see IMP_OBJECT_LOG() and IMP::SetLogState.All logging is disabled when `IMP` is built using `build='fast'`.
enum	LogLevel { DEFAULT = -1, SILENT = 0, WARNING = 1, PROGRESS = 2, TERSE = 3, VERBOSE = 4, MEMORY = 5 }
	The log levels supported by `IMP`. More...
void	push_log_context (std::string name)
	Push a new log context onto the stack.
void	pop_log_context ()
	pop the top log context
void	add_to_log (std::string to_write)
	Write a string to the log.
void	set_log_level (LogLevel l)
	Set the current global log level.
LogLevel	get_log_level ()
	Get the currently active log level.
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 std::vector < DerivativePair >	DerivativePairs
typedef double	Float
	Basic floating-point value (could be float, double...)
typedef std::pair< double, double >	FloatPair
	A generic pair of floats.
typedef std::vector< FloatPair >	FloatPairs
typedef std::pair< Float, Float >	FloatRange
	A pair representing the allowed range for a Float attribute.
typedef std::vector< Float >	Floats
	Standard way to pass a bunch of Float values.
typedef int	Int
	Basic integer value.
typedef std::pair< Int, Int >	IntPair
typedef std::vector< IntPair >	IntPairs
typedef std::pair< Int, Int >	IntRange
typedef std::vector< IntRange >	IntRanges
typedef std::vector< Int >	Ints
	Standard way to pass a bunch of Int values.
typedef VectorOfRefCounted < Object * >	Objects
	A class which is used for representing collections of Object objects.
typedef std::vector< Object * >	ObjectsTemp
	A type to use when returning sets of objects so as to avoid refcounting.
typedef std::pair < PairContainer , PairContainer >	PairContainerPair
typedef std::pair < QuadContainer , QuadContainer >	QuadContainerPair
typedef ::boost::rand48	RandomNumberGenerator
typedef VectorOfRefCounted < Refiner * >	Refiners
	a collection of Refiner objects
typedef GenericScopedRemoveRestraint < Restraint >	ScopedRemoveRestraint
	Remove a restraint 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 std::pair < SingletonContainer , SingletonContainer >	SingletonContainerPair
typedef std::string	String
	Basic string value.
typedef std::vector< String >	Strings
	Standard way to pass a bunch of String values.
typedef std::pair < TripletContainer , TripletContainer >	TripletContainerPair
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.
Functions
void	add_failure_handler (FailureHandler *f)
	Add a custom function to be called on an error.
TextOutput	create_temporary_file (std::string prefix="imp_temp", std::string suffix="")
const algebra::BoundingBoxD< 3 >	get_bounding_box_d_geometry (Particle *p)
std::string	get_data_path (std::string file_name)
	Return the path to installed data for this module.
DependencyGraph	get_dependency_graph (const RestraintsTemp &rs)
std::string	get_example_path (std::string file_name)
	Return the path to installed example data for this module.
TextOutput	get_log_target ()
std::string	get_module_name ()
const VersionInfo &	get_module_version_info ()
DependencyGraph	get_pruned_dependency_graph (const RestraintsTemp &rs)
std::string	get_relative_path (std::string base, std::string relative)
ScoreStatesTemp	get_required_score_states (const RestraintsTemp &rs)
const algebra::SphereD< 3 >	get_sphere_d_geometry (Particle *p)
const algebra::VectorD< 3 >	get_vector_d_geometry (Particle *p)
template<class O , class I >
O *	object_cast (I *o)
ConfigurationSet *	read_configuration_set (std::string fname, const Particles &ps, const FloatKeys &keys)
void	read_configuration_set (std::string fname, const Particles &ps, const FloatKeys &keys, ConfigurationSet *out)
void	remove_failure_handler (FailureHandler *f)
	Remove a failure handler from the list.
void	set_data_path (std::string dp)
void	set_example_path (std::string dp)
void	set_log_target (TextOutput l)
	Set the target for the log.
void	set_print_deprecation_messages (bool tf)
	Toggle printing of warnings on using deprecated classes.
void	set_sphere_d_geometry (Particle *p, const algebra::SphereD< 3 > &v)
void	set_vector_d_geometry (Particle *p, const algebra::VectorD< 3 > &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)
void	write_configuration_set (ConfigurationSet *cs, const Particles &ps, const FloatKeys &keys, std::string fname)
Model IO
Models can be written to files in an easy-to-read file format based on “name: value” pairs on separate lines with indentation used to indicated nesting (as in Python). The functions take a list of the particles to write/read. The particles need to be provided in the same order for reading and writing. This is not checked. The files should have the suffix ".imp". If a passed particle has a particle attribute which is a particle not in the list, an IOException is thrown. This can change to silently ignoring such attributes if desired. If a list of attributes is passed to read or write, only those attributes are read. Note: If you are just interested in saving the state of a model during runtime, use an IMP::ConfigurationSet instead. It should be substantially faster.
void	write_particles (const ParticlesTemp &particles, TextOutput out)
void	read_particles (TextInput in, const ParticlesTemp &particles)
void	write_particles (const ParticlesTemp &particles, const FloatKeys &keys, TextOutput out)
void	read_particles (TextInput in, const ParticlesTemp &particles, const FloatKeys &keys)
Binary I/O
When lots of data is being written, it can be useful to write the data as binary instead of text. Binary writing requires NetCDF. The files should have the suffix ".impb". For writing if the append is true is a positive integer, then the data is added to the file if it already exists. For reading, and IOException will be thrown if an invalid frame is requested. Frames are always sequential. 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. These methods should be considered unstable. Use the text IO if you want stable long term storage. The binary I/O functions requires NetCDF in order to function.
void	write_particles_binary (const ParticlesTemp &particles, const FloatKeys &keys, std::string filename, bool append=false)
	if append, don't overwrite an existing file
void	read_particles_binary (std::string filename, const ParticlesTemp &particles, const FloatKeys &keys, int frame=-1)
	load the ith frame if frame is non-negative
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.
std::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 std::vector< char > &buffer, const ParticlesTemp &particles, const FloatKeys &keys)
	load found attributes into the particles
Variables
static const double	PI = 3.1415926535897931
	the constant pi
RandomNumberGenerator	random_number_generator
	A shared random number generator.

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::vector<Object*> IMP::ObjectsTemp

A type to use when returning sets of objects so as to avoid refcounting.

Always store using Objects instead, but return ObjectsTemp. Objects can be constructed from a ObjectsTemp and vice versa.

Enumeration Type Documentation

enum IMP::CheckLevel

Determine the level of runtime checks performed.

NONE means that minimial checks are used.
- USAGE means that checks of input values to functions and classes are verified.
- USAGE_AND_INTERNAL adds checks that IMP itself is correct. Turn these on if you suspect an IMP bug or are developing Restraints or other IMP classes.

enum IMP::LogLevel

The log levels supported by IMP.

DEFAULT is only local logging (like in IMP::Object); it means to use the global log level.

VERBOSE prints very large amounts of information. It should be enough to allow the computational flow to be understood.

TERSE prints a few lines per restraint or per state each time the score is evaluated.

PROGRESS show how large calculations are progressing (eg samplers) but otherwise just show warnings

WARNING prints only warnings.

MEMORY prints information about allocations and deallocations to debug memory issues.

Function Documentation

IMP::add_failure_handler ( FailureHandler * f )

Add a custom function to be called on an error.

Examples: dump on error

TextOutput IMP::create_temporary_file	(	std::string	prefix = `"imp_temp"`,
		std::string	suffix = `""`
	)

Create a temporary file. The path can be extracted from the TextOutput.

If suffix is non-empty, there is some small chance of a collision on non-BSD systems as a unique temporary file is first created, and then a file with that suffix appended is created.

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

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

Return the path to installed data for this module.

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.

DependencyGraph 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()

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.

LogLevel IMP::get_log_level ( )

Get the currently active log level.

This may not always match the value passed to set_log_level() as objects can temporarily override the global level while they are evaluating.

CheckLevel IMP::get_maximum_check_level ( )

Determine the maximum check level that can be used for this build.

For example, 'fast' builds can't use any checks.

DependencyGraph IMP::get_pruned_dependency_graph ( const RestraintsTemp & rs )

The pruned dependency graph merges all particles which have the same dependencies to produce a simpler graph.

std::string IMP::get_relative_path	(	std::string	base,
		std::string	relative
	)

Return a path to a file relative to another file. For example if base is path/to/config.file and relative is data/image0.jpg then the return value would be path/to/data/image0.jpg. This function should be used when processing configuration files so that the meaning of the configuration file does not change if current working directory changes.

ScoreStatesTemp IMP::get_required_score_states ( const RestraintsTemp & rs )

Get the score states required by the passed restraints.

const algebra::SphereD<3> IMP::get_sphere_d_geometry ( Particle * p )

const algebra::VectorD<3> IMP::get_vector_d_geometry ( Particle * p )

template<class O , class I >

O* IMP::object_cast ( I * o )

Up (or down) cast an IMP Object-derived class. If the cast does not succeed a ValueException will be thrown. Use a dynamic_cast if you prefer to have a NULL returned.

void IMP::push_log_context ( std::string name )

Push a new log context onto the stack.

A log context is, eg, a function name.

ConfigurationSet * read_configuration_set	(	std::string	fname,
		const Particles &	ps,
		const FloatKeys &	keys
	)

Read a set of configurations from a file created by write_binary_model(). The function read_configuration_set() requires NetCDF in order to function.

void read_configuration_set	(	std::string	fname,
		const Particles &	ps,
		const FloatKeys &	keys,
		ConfigurationSet *	out
	)

Read a set of configurations from a file created by write_binary_model() into an existing configuration set. The function read_configuration_set() requires NetCDF in order to function.

IMP::set_check_level ( CheckLevel tf )

Control runtime checks in the code.

The default level of checks is USAGE for release builds and USAGE_AND_INTERNAL for debug builds.

Examples: score protein with ligand, local fitting

void IMP::set_data_path ( std::string dp )

Set the directory where IMP data is to be found. The directory should have a subdirectory for each module containing that module's data.

void IMP::set_example_path ( std::string dp )

Set the directory where IMP examples are to be found. The directory should have a subdirectory for each module containing that module's examples.

IMP::set_log_level ( LogLevel l )

Set the current global log level.

Note that this should not, currently, be used directly during Model::evaluate() calls.

Examples: write a restraint, chain, custom filter, restrain diameter, nup84 complex in bead representation, six particles optimization, rigid body excluded volume, sample 0, six particles loopy optimization, filter close pairs, write an optimizer state, displaying ensembles, local fitting, fit restraint

void IMP::set_log_target ( TextOutput l )

Set the target for the log.

See TextOutput for options. Python users should use SetLogTarget instead.

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_print_exceptions ( bool tf )

Set whether exception messages are printed or not.

By default the error message associated with thrown exceptions are printed when using from C++, but not from Python (since the error messages of an unhandled exception are printed by the Python runtime).

void IMP::set_sphere_d_geometry	(	Particle *	p,
		const algebra::SphereD< 3 > &	v
	)

void IMP::set_vector_d_geometry	(	Particle *	p,
		const algebra::VectorD< 3 > &	v
	)

void write_configuration_set	(	ConfigurationSet *	cs,
		const Particles &	ps,
		const FloatKeys &	keys,
		std::string	fname
	)

Write a configuration set to a file. The function write_configuration_set() requires NetCDF in order to function.

Variable Documentation

RandomNumberGenerator IMP::random_number_generator

A shared random number generator.

The random number generator is seeded based of of the current time. To provide a better seed or use a constant seed call random_number_generator.seed(x) with a 32 bit int or a 64 bit unsigned int.

This generator can be used by the Boost.Random distributions.

IMP Namespace Reference

Detailed Description

Author(s)

Version

License:

Publications:

Namespaces

Data Structures

Gathering restraints

Error checking and reporting

Logging

Typedefs

Functions

Variables

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation