IMP logo
IMP Manual  for IMP version 2.20.2
serialization.md
1 Serialization {#serialization}
2 =============
3 
4 Most %IMP types can be serialized - that is, the internal state of an object,
5 such as the values of its member variables, can be written to or read in from
6 a file, string or stream. This allows for individual objects or an entire %IMP
7 run to be saved and later restored, or to be sent from one machine to another.
8 In Python, the objects can be loaded or saved using the `pickle` module.
9 
10 Serialization uses a compact binary format. However, it is not heavily
11 optimized for size. If a smaller file size is desired, the Python `pickle`
12 file can be compressed with a general-purpose compression tool such as `gzip`.
13 
14 Note that IMP::Model is handled specially due to its large size. Objects that
15 refer to the model (such as restraints or particles) will only include the ID
16 of the model in the serialization stream, not the model itself.
17 On deserialization these objects will be reassociated with the model by matching
18 the ID. This requires that the model be deserialized before any of these other
19 objects. To ensure this, `pickle` a tuple, list, or other ordered Python
20 container containing the model before any other object.
21 
22 Serialization relies on the excellent
23 [cereal](https://uscilab.github.io/cereal/) library, which is required to
24 build %IMP.
25 
26 To add serialization to a new class, simply add a suitable serialization
27 function, as per the
28 [cereal docs](https://uscilab.github.io/cereal/serialization_functions.html).
29 Most %IMP classes define a `serialize` private method. The class will also
30 need a default constructor (i.e. one that takes no arguments) if it does not
31 already have one. If the class is visible to Python, make sure pickle support
32 is enabled by using the `IMP_SWIG_OBJECT_SERIALIZE` or
33 `IMP_SWIG_VALUE_SERIALIZE` macros in the SWIG interface.
34 
35 If a class is polymorphic - i.e. it is a subclass that is referenced somewhere
36 by a base class pointer, such as a `Restraint` subclass - then the
37 serialization subsystem will need to store the name of the subclass in the
38 serialized output and will need to know how to access derived class
39 information. This is done by adding the `IMP_OBJECT_SERIALIZE_DECL` and
40 `IMP_OBJECT_SERIALIZE_IMPL` macros to the `.h` file and `.cpp` file
41 respectively. (These macros are used instead of cereal's `CEREAL_REGISTER_TYPE`
42 macro.)
43 
44 The serialization format is subject to change. It should not be considered
45 portable between different machines (e.g. 32-bit and 64-bit, or Linux and
46 Windows) or between different %IMP versions, although this could be addressed
47 in future if necessary.
#define IMP_OBJECT_SERIALIZE_IMPL(Name)
#define IMP_OBJECT_SERIALIZE_DECL(Name)