RDKit
Open-source cheminformatics and machine learning.
MolPickler.h
Go to the documentation of this file.
1 ///
2 // Copyright (C) 2001-2021 Greg Landrum and Rational Discovery LLC
3 //
4 // @@ All Rights Reserved @@
5 // This file is part of the RDKit.
6 // The contents are covered by the terms of the BSD license
7 // which is included in the file license.txt, found at the root
8 // of the RDKit source tree.
9 //
10 #include <RDGeneral/export.h>
11 #ifndef RD_MOLPICKLE_H
12 #define RD_MOLPICKLE_H
13 
14 #include <Geometry/point.h>
15 #include <GraphMol/Atom.h>
16 #include <GraphMol/QueryAtom.h>
17 #include <GraphMol/Bond.h>
18 #include <GraphMol/QueryBond.h>
19 #include <RDGeneral/StreamOps.h>
20 #include <boost/utility/binary.hpp>
21 #include <boost/variant.hpp>
22 #include <Query/QueryObjects.h>
23 
24 // Std stuff
25 #include <iostream>
26 #include <string>
27 #include <sstream>
28 #include <exception>
29 #ifdef WIN32
30 #include <ios>
31 #endif
32 #include <cstdint>
33 
34 namespace RDKit {
35 class ROMol;
36 class RingInfo;
37 
38 //! used to indicate exceptions whilst pickling (serializing) molecules
39 class RDKIT_GRAPHMOL_EXPORT MolPicklerException : public std::exception {
40  public:
41  MolPicklerException(const char *msg) : _msg(msg) {}
42  MolPicklerException(const std::string msg) : _msg(msg) {}
43  const char *what() const noexcept override { return _msg.c_str(); }
44  ~MolPicklerException() noexcept override = default;
45 
46  private:
47  std::string _msg;
48 };
49 
50 namespace PicklerOps {
51 typedef enum {
52  NoProps = 0, // no data pickled (default pickling, single-precision coords)
53  MolProps = 0x1, // only public non computed properties
54  AtomProps = 0x2,
55  BondProps = 0x4,
57  0x2, // n.b. DEPRECATED and set to AtomProps (does the same work)
58  PrivateProps = 0x10,
59  ComputedProps = 0x20,
60  AllProps = 0x0000FFFF, // all data pickled
61  CoordsAsDouble = 0x0001FFFF, // save coordinates in double precision
62  NoConformers =
63  0x00020000 // do not include conformers or associated properties
65 } // namespace PicklerOps
66 
67 //! handles pickling (serializing) molecules
69  public:
70  static const std::int32_t versionMajor; //!< mark the pickle major version
71  static const std::int32_t versionMinor; //!< mark the pickle minor version
72  static const std::int32_t versionPatch; //!< mark the pickle patch version
73  static const std::int32_t endianId; //! mark the endian-ness of the pickle
74 
75  //! the pickle format is tagged using these tags:
76  //! NOTE: if you add to this list, be sure to put new entries AT THE BOTTOM,
77  /// otherwise
78  //! you will break old pickles.
79  typedef enum {
80  VERSION = 0,
146  // add new entries above here
147  INVALID_TAG = 255
148  } Tags;
149 
150  static unsigned int getDefaultPickleProperties();
151  static void setDefaultPickleProperties(unsigned int);
152 
154  static void addCustomPropHandler(const CustomPropHandler &handler);
155 
156  //! pickles a molecule and sends the results to stream \c ss
157  static void pickleMol(const ROMol *mol, std::ostream &ss);
158  static void pickleMol(const ROMol *mol, std::ostream &ss,
159  unsigned int propertyFlags);
160 
161  static void pickleMol(const ROMol &mol, std::ostream &ss);
162 
163  static void pickleMol(const ROMol &mol, std::ostream &ss,
164  unsigned int propertyFlags) {
165  MolPickler::pickleMol(&mol, ss, propertyFlags);
166  }
167 
168  //! pickles a molecule and adds the results to string \c res
169  static void pickleMol(const ROMol *mol, std::string &res);
170  static void pickleMol(const ROMol *mol, std::string &res,
171  unsigned int propertyFlags);
172  static void pickleMol(const ROMol &mol, std::string &res);
173  static void pickleMol(const ROMol &mol, std::string &res,
174  unsigned int propertyFlags) {
175  MolPickler::pickleMol(&mol, res, propertyFlags);
176  }
177 
178  //! constructs a molecule from a pickle stored in a string
179  static void molFromPickle(const std::string &pickle, ROMol *mol,
180  unsigned int propertyFlags);
181  static void molFromPickle(const std::string &pickle, ROMol &mol,
182  unsigned int propertyFlags) {
183  MolPickler::molFromPickle(pickle, &mol, propertyFlags);
184  }
185  static void molFromPickle(const std::string &pickle, ROMol *mol) {
187  }
188  static void molFromPickle(const std::string &pickle, ROMol &mol) {
190  }
191 
192  //! constructs a molecule from a pickle stored in a stream
193  static void molFromPickle(std::istream &ss, ROMol *mol,
194  unsigned int propertyFlags);
195  static void molFromPickle(std::istream &ss, ROMol &mol,
196  unsigned int propertyFlags) {
197  MolPickler::molFromPickle(ss, &mol, propertyFlags);
198  }
199  static void molFromPickle(std::istream &ss, ROMol *mol) {
201  }
202  static void molFromPickle(std::istream &ss, ROMol &mol) {
204  }
205 
206  private:
207  //! Pickle nonquery atom data
208  static std::int32_t _pickleAtomData(std::ostream &tss, const Atom *atom);
209  //! depickle nonquery atom data
210  static void _unpickleAtomData(std::istream &tss, Atom *atom, int version);
211 
212  static void _pickleQueryAtomData(std::ostream &tss, const Atom *atom);
213 
214  //! do the actual work of pickling a molecule
215  template <typename T>
216  static void _pickle(const ROMol *mol, std::ostream &ss,
217  unsigned int propertyFlags);
218 
219  //! do the actual work of pickling an Atom
220  template <typename T>
221  static void _pickleAtom(std::ostream &ss, const Atom *atom);
222 
223  //! do the actual work of pickling a Bond
224  template <typename T>
225  static void _pickleBond(std::ostream &ss, const Bond *bond,
226  std::map<int, int> &atomIdxMap);
227 
228  //! do the actual work of pickling an SSSR structure
229  template <typename T>
230  static void _pickleSSSR(std::ostream &ss, const RingInfo *ringInfo,
231  std::map<int, int> &atomIdxMap);
232 
233  //! do the actual work of pickling a SubstanceGroup
234  template <typename T>
235  static void _pickleSubstanceGroup(std::ostream &ss,
236  const SubstanceGroup &sgroup,
237  std::map<int, int> &atomIdxMap,
238  std::map<int, int> &bondIdxMap);
239 
240  //! do the actual work of pickling Stereo Group data
241  template <typename T>
242  static void _pickleStereo(std::ostream &ss,
243  const std::vector<StereoGroup> &groups,
244  std::map<int, int> &atomIdxMap);
245 
246  //! do the actual work of pickling a Conformer
247  template <typename T, typename C>
248  static void _pickleConformer(std::ostream &ss, const Conformer *conf);
249 
250  //! do the actual work of de-pickling a molecule
251  template <typename T>
252  static void _depickle(std::istream &ss, ROMol *mol, int version, int numAtoms,
253  unsigned int propertyFlags);
254 
255  //! extract atomic data from a pickle and add the resulting Atom to the
256  /// molecule
257  template <typename T>
258  static Atom *_addAtomFromPickle(std::istream &ss, ROMol *mol,
259  RDGeom::Point3D &pos, int version,
260  bool directMap = false);
261 
262  //! extract bond data from a pickle and add the resulting Bond to the molecule
263  template <typename T>
264  static Bond *_addBondFromPickle(std::istream &ss, ROMol *mol, int version,
265  bool directMap = false);
266 
267  //! extract ring info from a pickle and add the resulting RingInfo to the
268  /// molecule
269  template <typename T>
270  static void _addRingInfoFromPickle(std::istream &ss, ROMol *mol, int version,
271  bool directMap = false);
272 
273  //! extract a SubstanceGroup from a pickle
274  template <typename T>
275  static SubstanceGroup _getSubstanceGroupFromPickle(std::istream &ss,
276  ROMol *mol, int version);
277 
278  template <typename T>
279  static void _depickleStereo(std::istream &ss, ROMol *mol, int version);
280 
281  //! extract a conformation from a pickle
282  template <typename T, typename C>
283  static Conformer *_conformerFromPickle(std::istream &ss, int version);
284 
285  //! pickle standard properties
286  static void _pickleProperties(std::ostream &ss, const RDProps &props,
287  unsigned int pickleFlags);
288  //! unpickle standard properties
289  static void _unpickleProperties(std::istream &ss, RDProps &props);
290 
291  //! backwards compatibility
292  static void _pickleV1(const ROMol *mol, std::ostream &ss);
293  //! backwards compatibility
294  static void _depickleV1(std::istream &ss, ROMol *mol);
295  //! backwards compatibility
296  static void _addAtomFromPickleV1(std::istream &ss, ROMol *mol);
297  //! backwards compatibility
298  static void _addBondFromPickleV1(std::istream &ss, ROMol *mol);
299 };
300 
301 namespace PicklerOps {
302 using QueryDetails = boost::variant<
303  MolPickler::Tags, std::tuple<MolPickler::Tags, int32_t>,
304  std::tuple<MolPickler::Tags, int32_t, int32_t>,
305  std::tuple<MolPickler::Tags, int32_t, int32_t, int32_t, char>,
306  std::tuple<MolPickler::Tags, std::set<int32_t>>>;
307 template <class T>
309 
310 } // namespace PicklerOps
311 
312 }; // namespace RDKit
313 
314 #endif
Defines the Atom class and associated typedefs.
Pulls in all the query types.
Base class for all queries.
Definition: Query.h:45
The class for representing atoms.
Definition: Atom.h:68
class for representing a bond
Definition: Bond.h:46
The class for representing 2D or 3D conformation of a molecule.
Definition: Conformer.h:45
used to indicate exceptions whilst pickling (serializing) molecules
Definition: MolPickler.h:39
~MolPicklerException() noexcept override=default
const char * what() const noexcept override
Definition: MolPickler.h:43
MolPicklerException(const std::string msg)
Definition: MolPickler.h:42
MolPicklerException(const char *msg)
Definition: MolPickler.h:41
handles pickling (serializing) molecules
Definition: MolPickler.h:68
static const std::int32_t endianId
Definition: MolPickler.h:73
static void molFromPickle(std::istream &ss, ROMol *mol)
Definition: MolPickler.h:199
static void molFromPickle(const std::string &pickle, ROMol &mol, unsigned int propertyFlags)
Definition: MolPickler.h:181
static void molFromPickle(std::istream &ss, ROMol &mol, unsigned int propertyFlags)
Definition: MolPickler.h:195
static void pickleMol(const ROMol *mol, std::string &res, unsigned int propertyFlags)
static void molFromPickle(std::istream &ss, ROMol *mol, unsigned int propertyFlags)
constructs a molecule from a pickle stored in a stream
static void molFromPickle(const std::string &pickle, ROMol *mol)
Definition: MolPickler.h:185
Tags
mark the endian-ness of the pickle
Definition: MolPickler.h:79
@ ATOM_PDB_RESIDUE_SERIALNUMBER
Definition: MolPickler.h:126
@ ATOM_PDB_RESIDUE_INSERTIONCODE
Definition: MolPickler.h:130
@ ATOM_PDB_RESIDUE_RESIDUENUMBER
Definition: MolPickler.h:135
@ ATOM_PDB_RESIDUE_SECONDARYSTRUCTURE
Definition: MolPickler.h:134
@ ATOM_PDB_RESIDUE_SEGMENTNUMBER
Definition: MolPickler.h:136
@ ATOM_PDB_RESIDUE_RESIDUENAME
Definition: MolPickler.h:128
@ ATOM_PDB_RESIDUE_ISHETEROATOM
Definition: MolPickler.h:133
static void pickleMol(const ROMol &mol, std::ostream &ss)
static void pickleMol(const ROMol &mol, std::string &res, unsigned int propertyFlags)
Definition: MolPickler.h:173
static void pickleMol(const ROMol *mol, std::ostream &ss, unsigned int propertyFlags)
static void molFromPickle(const std::string &pickle, ROMol *mol, unsigned int propertyFlags)
constructs a molecule from a pickle stored in a string
static void molFromPickle(const std::string &pickle, ROMol &mol)
Definition: MolPickler.h:188
static const CustomPropHandlerVec & getCustomPropHandlers()
static void setDefaultPickleProperties(unsigned int)
static const std::int32_t versionMajor
mark the pickle major version
Definition: MolPickler.h:70
static const std::int32_t versionMinor
mark the pickle minor version
Definition: MolPickler.h:71
static void molFromPickle(std::istream &ss, ROMol &mol)
Definition: MolPickler.h:202
static void pickleMol(const ROMol &mol, std::ostream &ss, unsigned int propertyFlags)
Definition: MolPickler.h:163
static void pickleMol(const ROMol *mol, std::ostream &ss)
pickles a molecule and sends the results to stream ss
static void pickleMol(const ROMol *mol, std::string &res)
pickles a molecule and adds the results to string res
static unsigned int getDefaultPickleProperties()
static void addCustomPropHandler(const CustomPropHandler &handler)
static const std::int32_t versionPatch
mark the pickle patch version
Definition: MolPickler.h:72
static void pickleMol(const ROMol &mol, std::string &res)
A class to store information about a molecule's rings.
Definition: RingInfo.h:28
The class for representing SubstanceGroups.
#define RDKIT_GRAPHMOL_EXPORT
Definition: export.h:209
RDKIT_CHEMREACTIONS_EXPORT void pickle(const boost::shared_ptr< EnumerationStrategyBase > &enumerator, std::ostream &ss)
pickles a EnumerationStrategy and adds the results to a stream ss
QueryDetails getQueryDetails(const Queries::Query< int, T const *, true > *query)
boost::variant< MolPickler::Tags, std::tuple< MolPickler::Tags, int32_t >, std::tuple< MolPickler::Tags, int32_t, int32_t >, std::tuple< MolPickler::Tags, int32_t, int32_t, int32_t, char >, std::tuple< MolPickler::Tags, std::set< int32_t > >> QueryDetails
Definition: MolPickler.h:306
Std stuff.
Definition: Abbreviations.h:18
std::vector< std::shared_ptr< const CustomPropHandler > > CustomPropHandlerVec
Definition: StreamOps.h:369