IMP logo
IMP Reference Guide  2.20.2
The Integrative Modeling Platform
npctransport/Statistics.h
Go to the documentation of this file.
1 /**
2  * \file npctransport/Statistics.h
3  * \brief statistics and order parameters about the simulations
4  * that is associated with a SimulationData object
5  *
6  * \author Barak Raveh, Daniel Russell
7  * Copyright 2007-2022 IMP Inventors. All rights reserved.
8  */
9 
10 #ifndef IMPNPCTRANSPORT_STATISTICS_H
11 #define IMPNPCTRANSPORT_STATISTICS_H
12 
13 
14 #include "npctransport_config.h"
15 #include <IMP/Model.h>
16 #include <IMP/PairContainer.h>
18 #include <IMP/atom/Hierarchy.h>
25 #include <IMP/core/Typed.h>
28 #include <IMP/Pointer.h>
29 #include <IMP/set_map_macros.h>
30 #include <RMF/HDF5/File.h>
31 #include "io.h"
37 #include "Parameter.h"
38 #include "Scoring.h"
39 #include "typedefs.h"
40 
41 #include <IMP/internal/SimpleTimer.h>
42 #include "boost/tuple/tuple.hpp"
43 #include <boost/utility/value_init.hpp>
44 #include <boost/unordered_map.hpp>
45 #include <boost/unordered_set.hpp>
46 #include <stdint.h>
47 #include <string>
48 
49 #ifdef SWIG
50 namespace IMP {
51 namespace internal {
52 struct SimpleTimer {};
53 }
54 }
55 #endif
56 
57 
58 IMPNPCTRANSPORT_BEGIN_NAMESPACE
59 
60 class SimulationData; // fwd incomplete declaration
61 
62 //! Statistics and order parameters about the simulations
63 class IMPNPCTRANSPORTEXPORT Statistics : public Object {
64  private:
66 
67  // Whether statistics gathering has been activated (= optimizer states added to optimizer)
68  bool is_activated_;
69 
70  // interval of simulation frames for gathering stats
71  Parameter<int> statistics_interval_frames_;
72 
73  // the file to which simulation statistics are dumped:
74  std::string output_file_name_;
75 
77 
78  // statistics about all fgs, per particle, per chain, per particle type
79  typedef std::vector< BodyStatisticsOptimizerStates >
80  FGsBodyStatisticsOSs;
81  typedef IMP_KERNEL_LARGE_UNORDERED_MAP<core::ParticleType, FGsBodyStatisticsOSs>
82  FGsBodyStatisticsOSsMap;
83  FGsBodyStatisticsOSsMap fgs_bodies_stats_map_;
84 
85  // statistics about all floaters (kaps etc.), per particle type
86  typedef IMP_KERNEL_LARGE_UNORDERED_MAP<core::ParticleType, BodyStatisticsOptimizerStates>
87  BodyStatisticsOSsMap;
88  BodyStatisticsOSsMap floaters_stats_map_;
89 
90  // transport statistics about all floaters (kaps etc.) per particle type
93  ParticleTransportStatisticsOSsMap;
94  ParticleTransportStatisticsOSsMap floaters_transport_stats_map_;
95 
96  int update_calls_ = 0;
97 
98 #ifndef SWIG
99  // distributions
101  std::vector< std::vector<int> > >
102  ParticleTypeZRDistributionMap;
103  ParticleTypeZRDistributionMap particle_type_zr_distribution_map_;
104  typedef IMP_KERNEL_LARGE_UNORDERED_MAP< uint_fast8_t,
105  IMP_KERNEL_LARGE_UNORDERED_MAP< uint_fast8_t,
106  IMP_KERNEL_LARGE_UNORDERED_MAP< uint_fast8_t,
107  boost::value_initialized<unsigned int> > > >
108  t_sparse_3d_matrix;
110  t_sparse_3d_matrix >
111  ParticleTypeXYZDistributionMap;
112  ParticleTypeXYZDistributionMap particle_type_xyz_distribution_map_;
113  struct t_size_3d_matrix{
114  uint_fast8_t d0;
115  uint_fast8_t d1;
116  uint_fast8_t d2;
117  };
118  t_size_3d_matrix xyz_distribution_sizes_;
119 #endif
120 
121  // statistics about entire FG chains, for each FG type
122  typedef IMP_KERNEL_LARGE_UNORDERED_MAP<core::ParticleType, ChainStatisticsOptimizerStates>
123  ChainStatisticsOSsMap;
124  ChainStatisticsOSsMap chains_stats_map_;
125 
126  // statistics of pairs of interactions for each interaction type
129  BipartitePairsStatisticsOSMap;
130  BipartitePairsStatisticsOSMap interaction_stats_map_;
131 
132  // true if statistics were recently reset, so that update()
133  // should restart averaging from 0 frames
134  mutable bool is_stats_reset_;
135 
136 
137  public:
138 
139  //! Remove all statistics related to particle type pt
140  /**
141  Removes statistics of particle type pt from all internal maps
142  and from the optimizer states of get_sd()->get_bd()
143 
144  @param pt the particle type to be removed
145  */
146  void remove_particle_type(core::ParticleType pt);
147 
148  /**
149  @param sd the sd that owns and uses this statistics object
150  @param statistics_interval_frames the interval of simulation frames for gathering
151  statistics
152  @param output_file_name name of output file to which to dump statistics (or update
153  if it already exists) when calling update()
154  */
156  unsigned int statistics_interval_frames,
157  std::string output_file_name);
158 
159  //! add statistics about an FG chain
160  /** add statistics about an FG chains
161 
162  @param fg_chain the chain
163  */
164  void add_fg_chain_stats(FGChain* fg_chain);
165 
166  //! add statistics about a floater particle
167  /** add statistics about a floater particle
168 
169  @param p the particle
170  */
171  void add_floater_stats(IMP::Particle* p);
172 
173  //! add statistics about interactions between particles of type 0 and 1
174  /** add statistics about interactions between particles of type 0 and 1
175  (order does not matter)
176 
177  @param type0 type of first interacting particles
178  @param type1 type of other interacting particles
179  */
180  void add_interaction_stats
181  ( core::ParticleType type0, core::ParticleType type1);
182 
183  //! add all statistics-related optimizer states to o
184  /**
185  @param o optimizer to which optimizer states are added,
186  use get_sd()->get_bd() if nullptr
187  @return the list of optimizer states that were added
188 
189  @note If called for more than one optimizer, only the last
190  optimizer will be guaranteed to work well.
191  */
192  OptimizerStates add_optimizer_states(Optimizer* o = nullptr);
193 
194  /**
195  updates the map of z-r distributions of particle coordinates
196  with p's binned position counts (if z-symmetry flag is on,
197  z is absolute vertical location; r is distance from pore axis)
198 
199  Comment: assume a pore geometry, no checks made that it is so
200  */
201  void update_particle_type_zr_distribution_map(Particle* p);
202 
203  /**
204  updates the map of x-y-z distributions of particle coordinates
205  with p's binned position counts (if z-symmetry flag is on,
206  z is absolute vertical location)
207 
208  Comment: assume a pore geometry, no checks made that it is so
209  */
210  void update_particle_type_xyz_distribution_map(Particle* p);
211 
212 
213  /**
214  opens / creates statistics protobuf file, and update it
215  with appropriate statistics, using statistics file
216  originally specified in the constructor, and based on statistics
217  gathered from the optimizer that was specified by
218  add_optimizer_states().
219 
220  @throw UsageException If add_optimizer_states() was not called yet
221  (= get_is_activated() is false)
222 
223  @param timer the timer that was used to measure the time
224  that has elapsed for statistics
225  @param nf_new the number of frames by which the statistics file
226  should be advanced. This is used to weight the
227  contribution of average statistics over time.
228  @param force_full_output if true, then full statistics are dumped
229  to the output file, even if the number
230  of calls to update does not divide by the
231  value of full_output_statistics_interval_factor
232 
233  @note this method is not const cause it may invoke e.g., energy evaluation
234  though it does not substantially change anything in the state of the object
235  @note if configuration file full_output_statistics_interval_factor
236  is larger than 1, then full statistics are dumped every N calls
237  to update(), where N is the value of full_output_statistics_interval_factor,
238  and only the HDF5 file is updated at each call.
239  */
240  void update(const IMP::internal::SimpleTimer &timer,
241  unsigned int nf_new = 1,
242  bool force_full_output = false);
243 
244  /** resets all the counters of any statistics counters,
245  and the simulation time to zero */
246  void reset_statistics_optimizer_states();
247 
248  //! Loads the stats file and set the interrupted flag to true
249  void set_interrupted(bool tf);
250 
251  /************************************************************/
252  /************* various simple getters and setters *******************/
253  /************************************************************/
254 
255  /** returns the model associated with the owned SimulationData */
256  Model* get_model();
257 
258 #ifndef SWIG
259  /** returns the model associated with the owned SimulationData */
260  Model* get_model() const;
261 #endif
262 
263  /** return the SimulationData object that owns this ScoringFunction */
265  return owner_sd_;
266  }
267 
268  //! if true, statistics have been activated, so add_optimizer_states()
269  //! was called such that statistics are being tracked
271  return is_activated_;
272  }
273 
274 #ifndef SWIG
275  /** return the SimulationData object that owns this ScoringFunction */
276  SimulationData const* get_sd() const{
277  return owner_sd_;
278  }
279 #endif
280 
281  std::string get_output_file_name() const{
282  return output_file_name_;
283  }
284 
285  private:
286 
287  //! update the xyz distribution of type p_type to a dataset in
288  //! hdf5_group, with name p_type.get_string()
289  bool update_xyz_distribution_to_hdf5
290  (RMF::HDF5::Group hdf5_group,
291  core::ParticleType p_type);
292 
293 
294  //! updates pStats with all statistics related to fgs, averaged over
295  //! nf_new additional frames
296  //! @param zr_hist a grid on z / (x,y)-radial axis relevant only if not outputting xyz stats to hdf5
297  void update_fg_stats( ::npctransport_proto::Statistics* pStats,
298  unsigned int nf_new,
299  unsigned int zr_hist[4][3]);
300 
301  //! updates pStats with all statistics related to floaters, averaged over
302  //! nf_new additional frames
303  //!
304  //! @return for historical reasons, returns a map of diffusion coefficients for each particle type
305  //! to be used in order params later on
306  std::map<IMP::core::ParticleType, double> update_floater_stats( ::npctransport_proto::Statistics* pStats,
307  unsigned int nf_new);
308 
309 
310 
311 
312  // TODO: move to util.h, possibly internal
313  // @param floaters a list of floater particles
314  // @param fg_roots a list of hierarchy particles that are the root of an
315  // fg chain (= all their children are fg typed particles)
316  // @return a 4-tuple (1,2,3,4) with:
317  // 1 - total # of individual site-site interactions between the specified
318  // floaters and chains
319  // 2 - total # of floaters that site-interact with any specified chain
320  // 3 - total # of fg bead-floater pairs that site-interact
321  // 4 - sum of # of chain-floater that site-intercat
322  boost::tuple<double, double, double, double> get_interactions_and_interacting
323  ( const ParticlesTemp &floaters, const atom::Hierarchies &chain_roots) const;
324 
325  //! @return the top of a z-axis bin for various stats
326  double get_z_distribution_top() const;
327 
328  //! @return the radius of a outermost radial (x,y) bin for various stats
329  double get_r_distribution_max() const;
330 
331  /**
332  for particles ps, returns the distribution along the z axis, in regions
333  z0 = [top...) ; z1 = [0..top) ; z2 = [-top..top) ; z3 = (...top)
334  with top being the return value of get_z_distribution_top()
335 
336  @param ps the particles
337 
338  @return a tuple <z0,z1,z2,z3> with counts of particles from ps
339  in z0, z1, z2 and z3 regions
340  */
341  boost::tuple<int, int, int, int>
342  get_z_distribution(const ParticlesTemp& ps) const;
343 
344  /** add the z-axis / (x,y)-radial distribution of particles ps
345  to zr_hist, a grid with z-axis bins on the first dimension and
346  radial bins on the second dimension.
347 
348  @param zr_hist a grid on z / (x,y)-radial axis
349  @param ps the particles
350 
351  */
352  void fill_in_zr_hist(unsigned int zr_hist[4][3],
353  ParticlesTemp ps) const;
354 
355  void update_hdf5_statistics(); // output HDF5 statistics
356 
357 
358  public:
360 
361 
362 };
363 
364 inline IMPNPCTRANSPORTEXPORT IMP::internal::SimpleTimer create_boost_timer() {
365  return IMP::internal::SimpleTimer();
366 }
367 
368 IMPNPCTRANSPORT_END_NAMESPACE
369 
370 #endif /* IMPNPCTRANSPORT_STATISTICS_H */
Apply a PairScore to each Pair in a list.
std::pair< IMP::core::ParticleType, IMP::core::ParticleType > InteractionType
an interaction that involves particles of two types
Definition: typedefs.h:21
Simple Brownian dynamics optimizer.
scoring associated with a SimulationData object
Store a list of ParticleIndexes.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
Store a set of PairContainers.
Storage of a model, its restraints, constraints and particles.
Track the rotational correlation time of a rigid body particle.
Score particles based on a bounding box.
Dump the state of all associated objects into the RMF file.
Key< 34897493 > ParticleType
An IMP::Key object for identifying types of particles by strings.
Definition: Typed.h:28
Statistics and order parameters about the simulations.
A weak pointer to an Object or RefCountedObject.
Definition: WeakPointer.h:33
description
A more IMP-like version of the std::vector.
Definition: Vector.h:42
Implement geometry for the basic shapes from IMP.algebra.
A particle with a user-defined type.
Macros to choose the best set or map for different purposes.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Decorator for helping deal with a hierarchy of molecules.
A container for Pairs.
Common base class for heavy weight IMP objects.
Definition: Object.h:111
Return all pairs from a SingletonContainer.
Base class for all optimizers.
Definition: Optimizer.h:48
A smart pointer to a ref-counted Object that is a class member.
Definition: Pointer.h:143
SimulationData const * get_sd() const
Store all parameters for a simulation.
A nullptr-initialized pointer to an IMP Object.
Define some predicates.
description
Class to handle individual particles of a Model object.
Definition: Particle.h:43
description
#define IMP_KERNEL_LARGE_UNORDERED_MAP
Macro to support platform independent declaration of a large unordered map.