IMP FAQ

This page contains the answers to frequently asked question and frequent problems encountered with IMP.

How do I make IMP run faster?

By default IMP performs a variety of run time checks, for example checking that an attribute exists before returning its value. These checks are there so that objects behave as expected in python (throwing exceptions rather than crashing). The checks can be disabled by calling

IMP.set_checks_level(IMP.NONE)

or, more permanently (and with extra speed benefits), by recompiling with the

build=fast

option. (At the very least make sure build is not debug.)

In addition, logging slows things down significantly. You can disable logging with

IMP.set_log_level(IMP.SILENT)

Next, one can optimize the representation and scoring to speed things up. Most importantly, don't use more particles then are needed to represent something. That is, if your final model is likely to be only accurate to 1nm, don't use any particles smaller than 5A or so. Secondly, replace generic scoring terms (eg SphereDistancePairScoring using a HarmonicLowerBound) by specialized ones (eg SoftSpherePairScore) as these can be several times faster.

If things are still too slow after trying these, please prepare a simple program that demonstrates what is too slow or profile your code and then complain on the imp-dev list, including your program or profile results.

Why can't I clone a Particle?

The short answer is: "because no one knows how to do it safely". The complication is that the attributes of various particles may have relationships to one another that would be violated by the cloning process. For example, a Particle attribute in a Particle could be part of a bond, in which case the bond particle must also be cloned and the attribute in the new particle must point to the new bond, or it could be a pointer to a particle which keeps track of all of the atoms in the system, in which case the attribute value should be copied unchanged. A clone function would have no way of knowing which should be done.

We suggest that you either

• call your initialization code more than once (to create two copies of the set of particles):

protein_0= create_protein("my_protein_name")
protein_1= create_protein("my_protein_name")

• or write a simple function which creates a new particle and copies the needed attributes.

Particle* copy_particle(Particle *o, unsigned int new_index) {
  Protein *p= new Protein(o->get_model());
  XYZDecorator::create(p, XYZDecorator(o).get_coordinates());
  MyDecorator d= MyDecorator::create(p);
  d.set_my_attribute(MyDecorator(o).get_my_attribute());
  d.set_my_index(new_index);
}

• use the clone_molecular_hierarchy function

How do I get Xcode to find my scons install?

You need to set the PATH used by GUI applications on mac os. To do this

• Create a director called "~/.MacOSX" in your home directory
• Create a file called "environment.plist" in that directory
• The file should contain the following lines to add "/opt/local/bin" to your path

{
    PATH = "/opt/local/bin:/usr/bin:/bin";
}

• Log out and log back in

How do I change the version of svn that Xcode uses?

Xcode uses svn through two plugins located in "/Developer/Library/Xcode/Plug-ins/". You can change which svn libraries that those plugins are linked against using a command called otool. A script to automate this, called update_xcode_svn is attached to this page. To switch to svn located in "/opt/local" do

update_xcode_svn /Developer/Library/Xcode/Plug-ins/XcodeSubversionIDEPlugin.xcplugin/Contents/MacOS/XcodeSubversionIDEPlugin /opt/local
update_xcode_svn /Developer/Library/Xcode/Plug-ins/XcodeSubversionPlugin.xcplugin/Contents/MacOS/XcodeSubversionPlugin /opt/local

What is this XXXEXPORT stuff?

In IMP we only export selected functions and classes from the dynamic linked libraries. As a result, each class/function that is used outside of the library needs to be marked with IMPMODULENAMEEXPORT. The rules for doing this are as follows:

• Any class which has any methods which are implemented in a .cpp file must be declared as

   class IMPMODULENAMEEXPORT ClassName: public BaseClass{};

• Any function whose implementation is in a .cpp file must be declared as

   IMPMODULENAMEEXPORT ReturnType function_name(ArgumentType arg_name);

• Non-template functions defined entirely in a header must be declared inline and NOT have an IMPMODULENAMEEXPORT

• Template functions or classes must NOT have IMPMODULENAMEEXPORT tags

Note that the pickiest compiler about this is the Visual Studio compiler, so the fact that your code works with gcc does not guarantee it is correct.

How do I profile IMP code?

The easiest way it to use Shark on a Mac. It is located at /Developer/Applications/Performance Tools/Shark.app if you have the developer tools installed. To use it, run your program and then tell Shark to sample it at an appropriate time. It will then tell you what functions were running during that sampling.

On linux it is a bit harder as the main tool, gprof, doesn't reliably support dynamic libraries. To use gprof, first do a profile build (with build='profile' passed to scons, making sure that CGAL is not used). gprof can only handle C++ programs, so the code you are profiling must be C++, and statically linked. The easiest way to do this is to write a benchmark and put it in benchmarks. Then run your program. Afterward do

gprof benchmarks/my_program > my_program.gprof
less my_program.gprof

to view the profiling output.

How do I debug IMP code?

First, build IMP in debug mode

scons build=debug

This will make sure that all checks are run and will provide information needed for more serious debugging. Run your code in debug mode and see if more useful error messages are produced. If you still can't figure out the problem then try to use gdb.

You should first copy the gdb init file in tools/gdbinit to .gdbinit in the IMP directory. This adds a few break points to gdb so it will stop when an error occurs. Then run gdb as follows

./bin/imppy.sh gdb (python | program_to_debug)

How do I undo a commit of a file?

SVN makes this operation a bit awkward. One way is to copy the following to a file and then run the shell script on each file you want to roll back the commit for.

 #!/bin/csh
 echo "Undoing commit of file " $1
 cp $1 build/tmp/$1:t
 svn merge -r COMMITTED:PREV $1
 svn commit -m "undo commit" $1
 cp build/tmp/$1:t $1