IMP  2.3.0
The Integrative Modeling Platform
IMP::base Namespace Reference

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:

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

A list of objects.

Store a set of objects.

Definition at line 61 of file types.h.

Pass a set of objects.

See Also
Object

Definition at line 63 of file types.h.

Pass or store a set of SetCheckState .

Definition at line 54 of file SetCheckState.h.

Pass or store a set of SetLogState .

Definition at line 50 of file SetLogState.h.

Pass or store a set of TextInput .

Definition at line 150 of file file.h.

Pass or store a set of TextOutput .

Definition at line 151 of file file.h.

Pass or store a set of VersionInfo .

Definition at line 48 of file VersionInfo.h.

Enumeration Type Documentation

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.

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.

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

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]argcargc
[in]argvargv
[in]descriptionA 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]argcargc
[in]argvargv
[in]descriptionA message describing what the program does.
[in]positional_descriptionA message describing the the positional arguments
[in]num_positionalA 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]argvsys.argv
[in]descriptionA 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]argvsys.argv
[in]descriptionA message describing what the program does.
[in]positional_descriptionA message describing the positional arguments, eg "input.pdb output.pdb"
[in]num_positionalA 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]argcargc
[in]argvargv
[in]descriptionA 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.