Low level functionality (logging, error handling, profiling, command line flags etc) that is used by all of IMP. More...

Detailed Description

Low level functionality (logging, error handling, profiling, command line flags etc) that is used by all of IMP.

Graphs

Graphs in IMP are represented in C++ using the Boost.Graph. All graphs used in IMP are VertexAndEdgeListGraphs, have vertex_name properties, are BidirectionalGraphs if they are directed.

The Boost.Graph interface cannot be easily exported to Python so we instead provide a simple wrapper IMP::PythonDirectedGraph. There are methods to translate the graphs into various common python and other formats (eg graphviz).

Values and Objects (C++ only)

As is conventional in C++, IMP classes are divided into broad, exclusive types

Object classes: They inherit from IMP::base::Object and are always passed by pointer. They are reference counted and so should only be stored using IMP::base::Pointer (in C++, in Python everything is reference counted). Never allocate these on the stack as very bad things can happen. Objects cannot be duplicated. Equality on objects is defined as identity (eg two different objects are different even if the data they contain is identical).
Value classes which are normal data types. They are passed by value (or const&), never by pointer. Equality is defined based on the data stored in the value. Most value types in IMP are always valid, but a few, mostly geometric types (IMP::algebra::Vector3D) are designed for fast, low-level use and are left in an uninitialized state by their default constructor
RAII classes control some particular resource. They grab control of a resource when created and then free it when they are destroyed. As a result, they cannot be copied. Non-IMP examples include things like files in python, which are automatically closed when the file object is deleted.

All types in IMP, with a few documented exceptions, can be

compared to other objects of the same type
output to a C++ stream or printed in python
meaningfully put into python dictionaries or C++ hash maps

Google Perf Tools

The google perf tools can be used for cpu and memory profiling of IMP. They can be controlled from the command line in many IMP executables.

Info

Author(s): Daniel Russel

Maintainer: benmwebb

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:

See main IMP papers list.

Classes
struct	AddBoolFlag

struct	AddFloatFlag

struct	AddIntFlag

struct	AddStringFlag

class	AdvancedFlag
	Use this to add an advanced flag to the program. More...

class	Array
	A class to store an fixed array of same-typed values. More...

class	ConstVector
	Store an array of values of the same type. More...

class	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	Flag

class	Index

class	IndexException
	An exception for a request for an invalid member of a container. More...

class	IndexVector

class	InputAdaptor

struct	InternalException
	A general exception for an internal error in IMP. More...

class	IOException
	An input/output exception. More...

class	LRUCache

class	map

class	Memoizer

class	ModelException
	An exception which is thrown when the kernel::Model has attributes with invalid values. More...

class	NonCopyable

class	Object
	Common base class for heavy weight `IMP` objects. More...

class	piecewise_linear_distribution

struct	Pointer
	A smart pointer to a reference counted object. More...

struct	PointerMember
	A smart pointer to a ref-counted Object that is a class member. More...

class	RAII

class	set

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	SetNumberOfThreads

class	Showable

class	SparseSymmetricPairMemoizer

class	TextInput

class	TextOutput

class	Timer

struct	UncheckedWeakPointer
	A weak pointer to an Object or RefCountedObject. More...

class	UsageException
	An exception for an invalid usage of `IMP`. More...

class	Value
	Base for a simple primitive-like type. 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	WarningContext

struct	WeakPointer

Typedefs
typedef IMP::base::Vector < IMP::base::Pointer< Object > >	Objects
	A list of objects. More...

typedef IMP::base::Vector < IMP::base::WeakPointer < Object > >	ObjectsTemp

typedef ::boost::mt19937	RandomNumberGenerator

typedef IMP::base::Vector < SetCheckState >	SetCheckStates

typedef IMP::base::Vector < SetLogState >	SetLogStates

typedef IMP::base::Vector < TextInput >	TextInputs

typedef IMP::base::Vector < TextOutput >	TextOutputs

typedef IMP::base::Vector < VersionInfo >	VersionInfos

Enumerations
enum	CheckLevel { DEFAULT_CHECK = -1, NONE = 0, USAGE = 1, USAGE_AND_INTERNAL = 2 }
	Specify the level of runtime checks performed. More...

enum	LogLevel { DEFAULT = -1, SILENT = 0, WARNING = 0 + 1, PROGRESS = 2, TERSE = 3, VERBOSE = 4, MEMORY = 5 }
	The log levels supported by `IMP`. More...

enum	StatisticsLevel { NO_STATISTICS = 0, ALL_STATISTICS = 1 }
	Specify the level of statistics to record. More...

Functions
void	clear_statistics ()

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="")
	Create a temporary file. More...

template<class Tag >
unsigned int	get_as_unsigned_int (Index< Tag > i)

template<class Tag >
Index< Tag >	get_invalid_index ()

bool	get_is_quick_test ()

Strings	get_live_object_names ()
	Return the names of all live objects. More...

Objects	get_live_objects ()
	Return pointers to all live objects. More...

TextOutput	get_log_target ()

boost::uint64_t	get_random_seed ()
	Return the initial random seed. More...

std::string	get_relative_path (std::string base, std::string relative)
	Return a path to a file relative to another file. More...

std::string	get_unique_name (std::string templ)
	Return a unique name produced from the string. More...

const algebra::Vector3D	get_vector_geometry (base::WeakPointer< kernel::Particle > d)

const algebra::Vector3D	get_vector_geometry (base::Pointer< kernel::Particle > d)

void	handle_use_deprecated (std::string message)

template<class T >
std::size_t	hash_value (const T &t)

std::size_t	hash_value (double d)

std::size_t	hash_value (int d)

std::size_t	hash_value (bool d)

std::size_t	hash_value (const std::string &d)

template<class T >
std::size_t	hash_value (const std::vector< T > &t)

template<class T >
std::size_t	hash_value (const __gnu_debug::vector< T > &t)

template<class T >
bool	isinf (const T &a)
	Return true if a number is infinite. More...

template<class T >
bool	isnan (const T &a)
	Return true if a number is NaN. More...

template<class O >
O *	object_cast (Object *o)

std::ostream &	operator<< (std::ostream &out, const Showable &s)

template<class Tag , class Container , class T >
void	resize_to_fit (Container &v, Index< Tag > i, const T &default_value=T())

void	set_deprecation_exceptions (bool tf)

void	set_deprecation_warnings (bool tf)
	Toggle printing of warnings on using deprecated classes. More...

void	set_log_target (TextOutput l)
	Set the target for the log. More...

void	set_show_leaked_objects (bool tf)
	Set whether to complain about objects not being properly cleaned up. More...

void	set_statistics_level (StatisticsLevel l)

void	set_vector_geometry (base::WeakPointer< kernel::Particle > d, const algebra::Vector3D &v)

void	set_vector_geometry (base::Pointer< kernel::Particle > d, const algebra::Vector3D &v)

void	show_timings (TextOutput out)

template<class A >
void	swap (ConstVector< A > &a, ConstVector< A > &b)

void	write_help (std::ostream &out=std::cerr)

Variables
RandomNumberGenerator	random_number_generator
	A shared random number generator. More...

Standard module functions
All `IMP` modules have a set of standard functions to help get information about the module and about files associated with the module.
std::string	get_module_version ()

std::string	get_module_name ()

std::string	get_data_path (std::string file_name)
	Return the full path to installed data. More...

std::string	get_example_path (std::string file_name)
	Return the path to installed example data for this module. More...

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/base/exception.h, Use the `gdbinit` file provided in `tools` to automatically have `gdb` break when `IMP` errors are detected.
void	set_check_level (CheckLevel tf)
	Control runtime checks in the code. More...

CheckLevel	get_check_level ()
	Get the current audit mode. More...

void	handle_error (const char *msg)

Flags
These methods add support for shared command line flags to `IMP`. Programs that use this have access to flags declared in modules which allow users to do things like control log level and turn on and off profiling to see what is going on. These functions are Python accessible. In C++, you can also use the AddFloatFlag, AddStringFlag, AddBoolFlag and AddIntFlag classes to add flags statically.
std::string	get_executable_name ()
	Return the name of the current executable. More...

void	setup_from_argv (int argc, char **argv, std::string description)
	Parse the command line flags and return the positional arguments. More...

Strings	setup_from_argv_allowing_unknown (int argc, char **argv, std::string description)

Strings	setup_from_argv (int argc, char **argv, std::string description, std::string positional_description, int num_positional)

void	setup_from_argv (const Strings &argv, std::string description)

Strings	setup_from_argv (const Strings &argv, std::string description, std::string positional_description, int num_positional)

void	add_string_flag (std::string name, std::string default_value, std::string description)

std::string	get_string_flag (std::string name)

void	add_int_flag (std::string name, size_t default_value, std::string description)

size_t	get_int_flag (std::string name)

void	add_bool_flag (std::string name, std::string description)

bool	get_bool_flag (std::string name)

void	add_float_flag (std::string name, double default_value, std::string description)

double	get_float_flag (std::string name)

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/base/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	add_to_log (LogLevel level, std::string to_write)
	Write a string to the log, for Python. More...

void	set_log_level (LogLevel l)
	Set the current global log level. More...

void	set_log_timer (bool tb)
	Set whether log messages are tagged with the current log time. More...

void	reset_log_timer ()
	Reset the log timer. More...

LogLevel	get_log_level ()
	Get the currently active global log level. More...

Create a progress bar in the terminal
void	set_progress_display (std::string description, unsigned int steps)
	Set up the progress bar with the passed description. More...

void	add_to_progress_display (unsigned int step=1)
	Set the current progress. More...

Number of threads
Get and set the default number of threads to use in `IMP`.
unsigned int	get_number_of_threads ()

void	set_number_of_threads (unsigned int n)

Typedef Documentation

typedef IMP::base::Vector<IMP::base::Pointer< Object > > IMP::base::Objects

A list of objects.

Store a set of objects.

Definition at line 61 of file types.h.

typedef IMP::base::Vector<IMP::base::WeakPointer< Object > > IMP::base::ObjectsTemp

Pass a set of objects.

See Also: Object

Definition at line 63 of file types.h.

typedef IMP::base::Vector< SetCheckState > IMP::base::SetCheckStates

Pass or store a set of SetCheckState .

Definition at line 54 of file SetCheckState.h.

typedef IMP::base::Vector< SetLogState > IMP::base::SetLogStates

Pass or store a set of SetLogState .

Definition at line 50 of file SetLogState.h.

typedef IMP::base::Vector< TextInput > IMP::base::TextInputs

Pass or store a set of TextInput .

Definition at line 150 of file file.h.

typedef IMP::base::Vector< TextOutput > IMP::base::TextOutputs

Pass or store a set of TextOutput .

Definition at line 151 of file file.h.

typedef IMP::base::Vector< VersionInfo > IMP::base::VersionInfos

Pass or store a set of VersionInfo .

Definition at line 48 of file VersionInfo.h.

Enumeration Type Documentation

enum IMP::base::CheckLevel

Specify the level of runtime checks performed.

Enumerator
DEFAULT_CHECK	Use the default check level (eg IMP::base::Object::set_check_level()).
NONE	Perform no runtime checks.
USAGE	Perform checks that `IMP` is being called correctly.
USAGE_AND_INTERNAL	Check internal `IMP` invariants. This is to be used for debugging `IMP`.

Definition at line 54 of file enums.h.

enum IMP::base::LogLevel

The log levels supported by IMP.

Enumerator
DEFAULT	Use to specify that the global log level should be used (eg in IMP::base::Object::set_log_level())
SILENT	Do not output any text.
WARNING	Output only warnings.
PROGRESS	Output only progress meter style displays and occasional printouts when switching phases of work.
TERSE	Output a line or two per evaluation call.
VERBOSE	Produce copious output to allow someone to trace through the computation.
MEMORY	Log memory allocations and frees.

Definition at line 20 of file enums.h.

enum IMP::base::StatisticsLevel

Specify the level of statistics to record.

See Also: show_timings().

Definition at line 73 of file enums.h.

Function Documentation

void IMP::base::add_bool_flag	(	std::string	name,
		std::string	description
	)

For Python use. Default is always false.

void IMP::base::add_float_flag	(	std::string	name,
		double	default_value,
		std::string	description
	)

For Python use.

void IMP::base::add_int_flag	(	std::string	name,
		size_t	default_value,
		std::string	description
	)

For Python use.

void IMP::base::add_string_flag	(	std::string	name,
		std::string	default_value,
		std::string	description
	)

For Python use.

void IMP::base::add_to_log	(	LogLevel	level,
		std::string	to_write
	)

Write a string to the log, for Python.

void IMP::base::add_to_progress_display ( unsigned int step = 1 )

Set the current progress.

When it equals the number of steps, the bar is done.

void IMP::base::clear_statistics ( )

Reset all the statistics for IMP.

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.

bool IMP::base::get_bool_flag ( std::string name )

For Python use.

CheckLevel IMP::base::get_check_level ( )

Get the current audit mode.

Definition at line 81 of file exception.h.

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 setup_environment.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 setup_environment.sh script.

std::string IMP::base::get_executable_name ( )

Return the name of the current executable.

double IMP::base::get_float_flag ( std::string name )

For Python use.

size_t IMP::base::get_int_flag ( std::string name )

For Python use.

bool IMP::base::get_is_quick_test ( )

Executables can inspect this flag and when it is true, run a shorter, simpler version of their code to just make sure things work.

Definition at line 178 of file flags.h.

Strings IMP::base::get_live_object_names ( )

Return the names of all live objects.

Use this to check for memory leaks.

Objects IMP::base::get_live_objects ( )

Return pointers to all live objects.

Use this to check for memory leaks.

LogLevel IMP::base::get_log_level ( )

Get the currently active global log level.

Get the currently active global log level

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

See Also: set_log_level(); IMP::base::Object::set_log_level()

Definition at line 94 of file log.h.

unsigned int IMP::base::get_number_of_threads ( )

Get the current number of threads requested. The default is the number of cores/hardware threads in the machine if there is OpenMP support, or 1 otherwise.

boost::uint64_t IMP::base::get_random_seed ( )

Return the initial random seed.

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.

std::string IMP::base::get_string_flag ( std::string name )

For Python use.

std::string IMP::base::get_unique_name ( std::string templ )

Return a unique name produced from the string.

This is done by replacing %1% with a sequential number.

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.

void IMP::base::handle_use_deprecated ( std::string message )

Break in this method in gdb to find deprecated uses at runtime.

template<class T >

bool IMP::base::isinf ( const T & a )

Return true if a number is infinite.

Definition at line 35 of file math.h.

template<class T >

bool IMP::base::isnan ( const T & a )

Return true if a number is NaN.

With certain compiler settings the compiler can optimize out a!=a (and certain Intel chips had issues with it too).

Definition at line 24 of file math.h.

template<class O >

O* IMP::base::object_cast ( Object * 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.

Definition at line 24 of file object_cast.h.

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.

Definition at line 73 of file exception.h.

void IMP::base::set_deprecation_exceptions ( bool tf )

Toggle whether an exception is thrown when a deprecated method is used.

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

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

Set the current global log level.

Note: may be overridden by set_log_level of specific objects that inherit from IMP::base::Object; this global method should not, currently, be used directly during kernel::Model::evaluate() calls.

See Also: get_log_level(); IMP::base::Object::set_log_level()

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_number_of_threads ( unsigned int n )

Set the current number of threads to a number greater or equal to 1. Setting it to 1 disables multithreaded evaluation.

void IMP::base::set_progress_display	(	std::string	description,
		unsigned int	steps
	)

Set up the progress bar with the passed description.

See Also: IMP_PROGRESS_DISPLAY().

void IMP::base::set_show_leaked_objects ( bool tf )

Set whether to complain about objects not being properly cleaned up.

void IMP::base::set_statistics_level ( StatisticsLevel l )

Set the level of statistics to be gathered.

void IMP::base::set_vector_geometry	(	base::WeakPointer< kernel::Particle >	d,
		const algebra::Vector3D &	v
	)

See generic geometry for more information.

Definition at line 168 of file XYZ.h.

Here is the call graph for this function:

void IMP::base::set_vector_geometry	(	base::Pointer< kernel::Particle >	d,
		const algebra::Vector3D &	v
	)

See generic geometry for more information.

Definition at line 177 of file XYZ.h.

Here is the call graph for this function:

void IMP::base::setup_from_argv	(	int	argc,
		char **	argv,
		std::string	description
	)

Parse the command line flags and return the positional arguments.

Parameters

[in]	argc	argc
[in]	argv	argv
[in]	description	A message describing what the program does.

Examples:: atom/dope_and_excluded_volume.cpp, and base/flags.cpp.

Strings IMP::base::setup_from_argv	(	int	argc,
		char **	argv,
		std::string	description,
		std::string	positional_description,
		int	num_positional
	)

Parse the command line flags and return the positional arguments.

Parameters

[in]	argc	argc
[in]	argv	argv
[in]	description	A message describing what the program does.
[in]	positional_description	A message describing the the positional arguments
[in]	num_positional	A positive integer to require that many positional arguments, or a negative integer to require at least that many.

void IMP::base::setup_from_argv	(	const Strings &	argv,
		std::string	description
	)

Parse the command line flags and return the positional arguments. For Python.

Parameters

[in]	argv	sys.argv
[in]	description	A message describing what the program does.

Strings IMP::base::setup_from_argv	(	const Strings &	argv,
		std::string	description,
		std::string	positional_description,
		int	num_positional
	)

Parse the command line flags and return the positional arguments. For Python.

Parameters

[in]	argv	sys.argv
[in]	description	A message describing what the program does.
[in]	positional_description	A message describing the positional arguments, eg "input.pdb output.pdb"
[in]	num_positional	A positive integer to require that many positional arguments, or a negative integer to require at least that many.

Strings IMP::base::setup_from_argv_allowing_unknown	(	int	argc,
		char **	argv,
		std::string	description
	)

Parse the command line flags and return the positional arguments returning unknown flags in a list. Use this version if some arguments are to be parsed by a different system.

Parameters

[in]	argc	argc
[in]	argv	argv
[in]	description	A message describing what the program does.

void IMP::base::show_timings ( TextOutput out )

Show all captured timings.

void IMP::base::write_help ( std::ostream & out = std::cerr )

Prints out the help message, useful if you have extra error checking and the flags don't pass it.

Variable Documentation

RandomNumberGenerator IMP::base::random_number_generator

A shared random number generator.

The random number generator is seeded based using the boost::random_device if it is available or /dev/urandom if it is not.

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

Detailed Description

Graphs

Values and Objects (C++ only)

Google Perf Tools

Info

Classes

Typedefs

Enumerations

Functions

Variables

Standard module functions

Error checking and reporting

Flags

Logging

Create a progress bar in the terminal

Number of threads

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation