1 Example of
using the library {#library_example}
2 ============================
4 A complete modeling script, <tt>simple.py</tt>, written in Python,
9 In the first part of the script, the %IMP kernel and the
10 [algebra](@ref IMP::algebra) and [core](@ref IMP::core) modules are loaded,
12 modules. We then proceed to set up the representation of the system,
using
13 the Model and Particle classes defined in the
14 kernel. Here we give the two particles (`p1` and `p2`) point-like attributes
17 In the second part, we set up the scoring of the system. We add two restraints
18 to the Model, one of which harmonically restrains `p1` to the origin and the
19 other of which restrains `p1` and `p2` to be distance 5.0 apart. (%IMP does not
20 enforce any units of distance; however, some physical optimizers, such
21 as molecular dynamics, [expect distances to be in angstroms](@ref units).)
24 the core module provides suitable building block restraints
for this purpose.
26 a restraint on a single particle (`p1`). It delegates the task of actually
27 scoring the particle, however, to another class called
28 IMP::SingletonScore that is simply given the
29 Particle and asked for its score. In this example, we use a type of
32 that calculates the Cartesian distance between the point-like Particle and
33 a fixed point (in this case the origin), and again delegates the task of
34 scoring the distance to another class, an
37 with a mean of zero. Thus, the Particle `p1` is harmonically restrained
38 to be at the origin. The second restraint is set up similarly; however,
39 in this case the restraints and scores act on a pair of particles.
40 This building block functionality makes it easy to add a new type of
41 restraint; for example, to implement a van der Waals potential it is
42 only necessary to provide a suitable PairScore that scores a single pair
43 of particles; the functionality for efficiently enumerating all pairs
44 of such particles is already provided in %IMP.
46 Finally, in the third part of the script, we tell %IMP that it can move
47 the two point-like particles, and to build a system configuration that
48 is consistent with all the restraints. In this example, a simple conjugate
49 gradients optimization is used.
51 The script is a regular Python script. Thus, provided that both %IMP and
52 Python are installed, it can be run on any machine, by typing on a command
53 line, in the same directory as the script:
55 <tt>python simple.py</tt>
57 The script will run the optimization, printing %IMP [log messages](@ref logging)
58 as it goes, and finally print the coordinates of the optimized particles.
60 %IMP is designed such that the C++ and Python interfaces are similar to use.
61 Thus, %IMP applications or protocols can be constructed either in C++ or in
62 Python, and new %IMP functionality (for example, new types of Restraint)
63 can be implemented in either language. For a comparison, please inspect the
64 <tt>simple.cpp</tt> file below. This file implements the same protocol as
65 the first part of <tt>simple.py</tt> but uses the %IMP C++ classes rather
66 than their Python equivalents. The two programs are very similar; the only
67 differences are in the language syntax (eg, the Python
68 '<tt>import IMP.algebra</tt>' translates to
69 '<tt>\#include \<IMP/algebra.h\></tt>'
70 in C++) and in memory handling (Python handles memory automatically;
71 in C++, memory handling must be done explicitly by using the
72 IMP::Pointer class or the [IMP_NEW](@ref IMP::IMP_NEW) macro,
73 which adds reference counting to automatically clean up after %IMP objects
74 when they are no longer in use).