Detailed Description

Standard way to pass a bunch of Float values.

This module provides low level functionality used by all of IMP.

Standard way to pass a bunch of Int values Standard way to pass a bunch of String values Standard way to pass a bunch of Floats values Standard way to pass a bunch of Ints values Standard way to pass a bunch of Strings values

The module provides low level functionality (logging, error handling etc) that is used by all of IMP. For backward compatibility, its methods are imported into the IMP namespace and the IMP python module.

Author(s): Daniel Russel

Version: SVN.r14091 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.

Classes
class	ConstArray
	Store an array of values of the same type. More...
struct	CreateLogContext
	Create a new log context. More...
class	EventException
	An exception that signifies some event occurred. 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	Index
class	IndexException
	An exception for a request for an invalid member of a container. More...
class	IndexVector
struct	InternalException
	A general exception for an intenal error in IMP. More...
class	IOException
	An input/output exception. More...
class	LRUCache
class	Memoizer
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...
struct	OwnerPointer
	A reference counted pointer to an object. More...
struct	Pointer
	A reference counted pointer to an object. More...
class	RefCounted
	Common base class for ref counted objects. More...
class	SetCheckState
	A class to change and restore check state. More...
class	SetLogState
	A class to change and restore log state. More...
class	SetLogTarget
class	Showable
class	SILENT
class	SparseSymmetricPairMemoizer
class	TextInput
class	TextOutput
class	TrackedObject
class	Tracker
struct	UncheckedWeakPointer
	A weak pointer to an IMP::Object or IMP::RefCountedObject. 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	Vector
class	VersionInfo
	Version and module information for Objects. More...
struct	WeakPointer

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.
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.
void	handle_error (const char *msg)

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'`.
void	push_log_context (const char functionname, const void object)
	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.
void	set_log_timer (bool tb)
	Set whether log messages are tagged with the current log time.
void	reset_log_timer ()
	Reset the log timer.
LogLevel	get_log_level ()
	Get the currently active log level.

Typedefs
typedef ::boost::rand48	RandomNumberGenerator

Enumerations
enum	CheckLevel { DEFAULT_CHECK = -1, NONE = 0, USAGE = 1, USAGE_AND_INTERNAL = 2 }
	Determine the level of runtime checks performed. More...
enum	LogLevel { DEFAULT = -1, SILENT = 0, WARNING = 1, PROGRESS = 2, TERSE = 3, VERBOSE = 4, MEMORY = 5 }
	The log levels supported by `IMP`. More...

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="")
std::string	create_temporary_file_name (std::string prefix="imp_temp", std::string suffix="")
template<class Tag >
unsigned int	get_as_unsigned_int (Index< Tag > i)
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.
template<class Tag >
Index< Tag >	get_invalid_index ()
TextOutput	get_log_target ()
std::string	get_relative_path (std::string base, std::string relative)
template<class T >
std::size_t	hash_value (const T &t)
template<class T >
std::size_t	hash_value (const IMP::compatibility::vector< T > &t)
template<class O , class I >
O *	object_cast (I *o)
std::ostream &	operator<< (std::ostream &out, const Showable &s)
void	remove_failure_handler (FailureHandler *f)
	Remove a failure handler from the list.
template<class Tag , class Container , class T >
void	resize_to_fit (Container &v, Index< Tag > i, const T &default_value=T())
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.
template<class A >
void	swap (ConstArray< A > &a, ConstArray< A > &b)

Variables
RandomNumberGenerator	random_number_generator
	A shared random number generator.

Enumeration Type Documentation

enum IMP::base::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::base::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

void add_failure_handler ( FailureHandler * f )

Add a custom function to be called on an error.

void IMP::base::add_to_log ( std::string to_write )

Write a string to the log.

TextOutput IMP::base::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.

std::string IMP::base::create_temporary_file_name	(	std::string	prefix = `"imp_temp"`,
		std::string	suffix = `""`
	)

Create a temporary file.

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.

CheckLevel IMP::base::get_check_level ( )

Get the current audit mode.

std::string IMP::base::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.

std::string IMP::base::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::base::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::base::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.

std::string IMP::base::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.

void IMP::base::handle_error ( const char * msg )

This function is called whenever IMP detects an error. It can be useful to add a breakpoint in the function when using a debugger.

template<class O , class I >

O* IMP::base::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 nullptr returned.

void IMP::base::pop_log_context ( )

pop the top log context

void IMP::base::push_log_context	(	const char *	functionname,
		const void *	object
	)

Push a new log context onto the stack.

A log context is, eg, a function name.

void remove_failure_handler ( FailureHandler * f )

Remove a failure handler from the list.

void IMP::base::reset_log_timer ( )

Reset the log timer.

void IMP::base::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.

void IMP::base::set_log_level ( LogLevel l )

Set the current global log level.

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

void IMP::base::set_log_target ( TextOutput l )

Set the target for the log.

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

void IMP::base::set_log_timer ( bool tb )

Set whether log messages are tagged with the current log time.

void IMP::base::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).

Variable Documentation

RandomNumberGenerator IMP::base::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.

Detailed Description

Classes

Error checking and reporting

Logging

Typedefs

Enumerations

Functions

Variables

Enumeration Type Documentation

Function Documentation

Variable Documentation