src/gromacs/selection/selection.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares gmx::Selection and supporting classes.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_selection
  38  */
  39 #ifndef GMX_SELECTION_SELECTION_H
  40 #define GMX_SELECTION_SELECTION_H
  41
  42 #include <string>
  43 #include <vector>
  44
  45 #include "../legacyheaders/typedefs.h"
  46
  47 #include "../utility/arrayref.h"
  48 #include "../utility/common.h"
  49 #include "../utility/gmxassert.h"
  50
  51 #include "position.h"
  52 #include "indexutil.h"
  53 #include "selectionenums.h"
  54
  55 namespace gmx
  56 {
  57
  58 class SelectionOptionStorage;
  59 class SelectionTreeElement;
  60
  61 class Selection;
  62 class SelectionPosition;
  63
  64 //! Container of selections used in public selection interfaces.
  65 typedef std::vector<Selection> SelectionList;
  66
  67 namespace internal
  68 {
  69
  70 /*! \internal \brief
  71  * Internal data for a single selection.
  72  *
  73  * This class is internal to the selection module, but resides in a public
  74  * header because of efficiency reasons: it allows frequently used access
  75  * methods in \ref Selection to be inlined.
  76  *
  77  * Methods in this class do not throw unless otherwise specified.
  78  *
  79  * \ingroup module_selection
  80  */
  81 class SelectionData
  82 {
  83     public:
  84         /*! \brief
  85          * Creates a new selection object.
  86          *
  87          * \param[in] elem   Root of the evaluation tree for this selection.
  88          * \param[in] selstr String that was parsed to produce this selection.
  89          * \throws    std::bad_alloc if out of memory.
  90          */
  91         SelectionData(SelectionTreeElement *elem, const char *selstr);
  92         ~SelectionData();
  93
  94         //! Returns the string that was parsed to produce this selection.
  95         const char *selectionText() const { return selectionText_.c_str(); }
  96         //! Returns true if the size of the selection (posCount()) is dynamic.
  97         bool isDynamic() const { return bDynamic_; }
  98         //! Number of positions in the selection.
  99         int posCount() const { return rawPositions_.nr; }
 100         //! Returns the root of the evaluation tree for this selection.
 101         SelectionTreeElement &rootElement() { return rootElement_; }
 102
 103         //! Returns whether the covered fraction can change between frames.
 104         bool isCoveredFractionDynamic() const { return bDynamicCoveredFraction_; }
 105
 106         //! Returns true if the given flag is set.
 107         bool hasFlag(SelectionFlag flag) const { return flags_.test(flag); }
 108         //! Sets the flags for this selection.
 109         void setFlags(SelectionFlags flags) { flags_ = flags; }
 110
 111         //! \copydoc Selection::initCoveredFraction()
 112         bool initCoveredFraction(e_coverfrac_t type);
 113
 114         /*! \brief
 115          * Computes total masses and charges for all selection positions.
 116          *
 117          * \param[in] top   Topology information.
 118          * \throws    std::bad_alloc if out of memory.
 119          *
 120          * For dynamic selections, the values need to be updated after each
 121          * evaluation with refreshMassesAndCharges().
 122          * This is done by SelectionEvaluator.
 123          *
 124          * This function is called by SelectionCompiler.
 125          *
 126          * Strong exception safety guarantee.
 127          */
 128         void initializeMassesAndCharges(const t_topology *top);
 129         /*! \brief
 130          * Updates masses and charges after dynamic selection has been
 131          * evaluated.
 132          *
 133          * \param[in] top   Topology information.
 134          *
 135          * Called by SelectionEvaluator.
 136          */
 137         void refreshMassesAndCharges(const t_topology *top);
 138         /*! \brief
 139          * Updates the covered fraction after a selection has been evaluated.
 140          *
 141          * Called by SelectionEvaluator.
 142          */
 143         void updateCoveredFractionForFrame();
 144         /*! \brief
 145          * Computes average covered fraction after all frames have been evaluated.
 146          *
 147          * \param[in] nframes  Number of frames that have been evaluated.
 148          *
 149          * \p nframes should be equal to the number of calls to
 150          * updateCoveredFractionForFrame().
 151          * Called by SelectionEvaluator::evaluateFinal().
 152          */
 153         void computeAverageCoveredFraction(int nframes);
 154         /*! \brief
 155          * Restores position information to state it was in after compilation.
 156          *
 157          * \param[in] top   Topology information.
 158          *
 159          * Depends on SelectionCompiler storing the original atoms in the
 160          * \a rootElement_ object.
 161          * Called by SelectionEvaluator::evaluateFinal().
 162          */
 163         void restoreOriginalPositions(const t_topology *top);
 164
 165     private:
 166         //! Name of the selection.
 167         std::string               name_;
 168         //! The actual selection string.
 169         std::string               selectionText_;
 170         //! Low-level representation of selected positions.
 171         gmx_ana_pos_t             rawPositions_;
 172         //! Total masses for the current positions.
 173         std::vector<real>         posMass_;
 174         //! Total charges for the current positions.
 175         std::vector<real>         posCharge_;
 176         SelectionFlags            flags_;
 177         //! Root of the selection evaluation tree.
 178         SelectionTreeElement     &rootElement_;
 179         //! Type of the covered fraction.
 180         e_coverfrac_t             coveredFractionType_;
 181         //! Covered fraction of the selection for the current frame.
 182         real                      coveredFraction_;
 183         //! The average covered fraction (over the trajectory).
 184         real                      averageCoveredFraction_;
 185         //! true if the value can change as a function of time.
 186         bool                      bDynamic_;
 187         //! true if the covered fraction depends on the frame.
 188         bool                      bDynamicCoveredFraction_;
 189
 190         /*! \brief
 191          * Needed to wrap access to information.
 192          */
 193         friend class gmx::Selection;
 194         /*! \brief
 195          * Needed for proper access to position information.
 196          */
 197         friend class gmx::SelectionPosition;
 198
 199         GMX_DISALLOW_COPY_AND_ASSIGN(SelectionData);
 200 };
 201
 202 }   // namespace internal
 203
 204 /*! \brief
 205  * Provides access to a single selection.
 206  *
 207  * This class provides a public interface for accessing selection information.
 208  * General information about the selection can be accessed with methods name(),
 209  * selectionText(), isDynamic(), and type().  The first three can be accessed
 210  * any time after the selection has been parsed, and type() can be accessed
 211  * after the selection has been compiled.
 212  *
 213  * Each selection is made of a set of positions.  Each position has associated
 214  * coordinates, and possibly velocities and forces if they have been requested
 215  * and are available.  It also has a set of atoms associated with it; typically
 216  * the coordinates are the center-of-mass or center-of-geometry coordinates for
 217  * that set of atoms.  To access the number of positions in the selection, use
 218  * posCount().  To access individual positions, use position().
 219  * See SelectionPosition for details of how to use individual positions.
 220  * setOriginalId() can be used to adjust the return value of
 221  * SelectionPosition::mappedId(); see that method for details.
 222  *
 223  * It is also possible to access the list of atoms that make up all the
 224  * positions directly: atomCount() returns the total number of atoms in the
 225  * selection and atomIndices() an array of their indices.
 226  *
 227  * Both positions and atoms can be accessed after the selection has been
 228  * compiled.  For dynamic selections, the return values of these methods change
 229  * after each evaluation to reflect the situation for the current frame.
 230  * Before any frame has been evaluated, these methods return the maximal set
 231  * to which the selection can evaluate.
 232  *
 233  * There are two possible modes for how positions for dynamic selections are
 234  * handled.  In the default mode, posCount() can change, and for each frame,
 235  * only the positions that are selected in that frame can be accessed.  In a
 236  * masked mode, posCount() remains constant, i.e., the positions are always
 237  * evaluated for the maximal set, and SelectionPosition::selected() is used to
 238  * determine whether a position is selected for a frame.  The masked mode can
 239  * be requested with SelectionOption::dynamicMask().
 240  *
 241  * The class also provides methods for printing out information: printInfo()
 242  * and printDebugInfo().  These are mainly for internal use by Gromacs.
 243  *
 244  * This class works like a pointer type: copying and assignment is lightweight,
 245  * and all copies work interchangeably, accessing the same internal data.
 246  *
 247  * Methods in this class do not throw.
 248  *
 249  * \see SelectionPosition
 250  *
 251  * \inpublicapi
 252  * \ingroup module_selection
 253  */
 254 class Selection
 255 {
 256     public:
 257         /*! \brief
 258          * Creates a selection wrapper that has no associated selection.
 259          *
 260          * Any attempt to call methods in the object before a selection is
 261          * assigned results in undefined behavior.
 262          */
 263         Selection() : sel_(NULL) {}
 264         /*! \brief
 265          * Creates a new selection object.
 266          *
 267          * \param  sel  Selection data to wrap.
 268          *
 269          * Only for internal use by the selection module.
 270          */
 271         explicit Selection(internal::SelectionData *sel) : sel_(sel) {}
 272
 273         //! Returns the name of the selection.
 274         const char *name() const  { return data().name_.c_str(); }
 275         //! Returns the string that was parsed to produce this selection.
 276         const char *selectionText() const { return data().selectionText(); }
 277         //! Returns true if the size of the selection (posCount()) is dynamic.
 278         bool isDynamic() const { return data().isDynamic(); }
 279         //! Returns the type of positions in the selection.
 280         e_index_t type() const { return data().rawPositions_.m.type; }
 281
 282         //! Total number of atoms in the selection.
 283         int atomCount() const
 284         {
 285             return data().rawPositions_.g != NULL ? data().rawPositions_.g->isize : 0;
 286         }
 287         //! Returns atom indices of all atoms in the selection.
 288         ConstArrayRef<int> atomIndices() const
 289         {
 290             if (data().rawPositions_.g == NULL)
 291             {
 292                 return ConstArrayRef<int>();
 293             }
 294             return ConstArrayRef<int>(data().rawPositions_.g->isize,
 295                                       data().rawPositions_.g->index);
 296         }
 297         //! Number of positions in the selection.
 298         int posCount() const { return data().posCount(); }
 299         //! Access a single position.
 300         SelectionPosition position(int i) const;
 301         /*! \brief
 302          * Sets the ID for the \p i'th position for use with
 303          * SelectionPosition::mappedId().
 304          *
 305          * \param[in] i  Zero-based index
 306          * \param[in] id Identifier to set.
 307          *
 308          * This method is not part of SelectionPosition because that interface
 309          * only provides access to const data by design.
 310          *
 311          * This method can only be called after compilation, before the
 312          * selection has been evaluated for any frame.
 313          *
 314          * \see SelectionPosition::mappedId()
 315          */
 316         void setOriginalId(int i, int id) { data().rawPositions_.m.orgid[i] = id; }
 317
 318         //! Deprecated method for direct access to position data.
 319         const gmx_ana_pos_t *positions() const { return &data().rawPositions_; }
 320
 321         //! Returns whether the covered fraction can change between frames.
 322         bool isCoveredFractionDynamic() const { return data().isCoveredFractionDynamic(); }
 323         //! Returns the covered fraction for the current frame.
 324         real coveredFraction() const { return data().coveredFraction_; }
 325         /*! \brief
 326          * Initializes information about covered fractions.
 327          *
 328          * \param[in] type Type of covered fraction required.
 329          * \returns   true if the covered fraction can be calculated for the
 330          *      selection.
 331          */
 332         bool initCoveredFraction(e_coverfrac_t type)
 333         {
 334             return data().initCoveredFraction(type);
 335         }
 336
 337         /*! \brief
 338          * Prints out one-line description of the selection.
 339          *
 340          * \param[in] fp      Where to print the information.
 341          *
 342          * The output contains the name of the selection, the number of atoms
 343          * and the number of positions, and indication of whether the selection
 344          * is dynamic.
 345          */
 346         void printInfo(FILE *fp) const;
 347         /*! \brief
 348          * Prints out extended information about the selection for debugging.
 349          *
 350          * \param[in] fp      Where to print the information.
 351          * \param[in] nmaxind Maximum number of values to print in lists
 352          *      (-1 = print all).
 353          */
 354         void printDebugInfo(FILE *fp, int nmaxind) const;
 355
 356     private:
 357         internal::SelectionData &data()
 358         {
 359             GMX_ASSERT(sel_ != NULL,
 360                        "Attempted to access uninitialized selection");
 361             return *sel_;
 362         }
 363         const internal::SelectionData &data() const
 364         {
 365             GMX_ASSERT(sel_ != NULL,
 366                        "Attempted to access uninitialized selection");
 367             return *sel_;
 368         }
 369
 370         /*! \brief
 371          * Pointer to internal data for the selection.
 372          *
 373          * The memory for this object is managed by a SelectionCollection
 374          * object, and the \ref Selection class simply provides a public
 375          * interface for accessing the data.
 376          */
 377         internal::SelectionData *sel_;
 378
 379         /*! \brief
 380          * Needed to access the data to adjust flags.
 381          */
 382         friend class SelectionOptionStorage;
 383 };
 384
 385 /*! \brief
 386  * Provides access to information about a single selected position.
 387  *
 388  * Each position has associated coordinates, and possibly velocities and forces
 389  * if they have been requested and are available.  It also has a set of atoms
 390  * associated with it; typically the coordinates are the center-of-mass or
 391  * center-of-geometry coordinates for that set of atoms.  It is possible that
 392  * there are not atoms associated if the selection has been provided as a fixed
 393  * position.
 394  *
 395  * After the selection has been compiled, but not yet evaluated, the contents
 396  * of the coordinate, velocity and force vectors are undefined.
 397  *
 398  * Default copy constructor and assignment operators are used, and work as
 399  * intended: the copy references the same position and works identically.
 400  *
 401  * Methods in this class do not throw.
 402  *
 403  * \see Selection
 404  *
 405  * \inpublicapi
 406  * \ingroup module_selection
 407  */
 408 class SelectionPosition
 409 {
 410     public:
 411         /*! \brief
 412          * Constructs a wrapper object for given selection position.
 413          *
 414          * \param[in] sel    Selection from which the position is wrapped.
 415          * \param[in] index  Zero-based index of the position to wrap.
 416          *
 417          * Asserts if \p index is out of range.
 418          *
 419          * Only for internal use of the library.  To obtain a SelectionPosition
 420          * object in other code, use Selection::position().
 421          */
 422         SelectionPosition(const internal::SelectionData &sel, int index)
 423             : sel_(&sel), i_(index)
 424         {
 425             GMX_ASSERT(index >= 0 && index < sel.posCount(),
 426                        "Invalid selection position index");
 427         }
 428
 429         /*! \brief
 430          * Returns type of this position.
 431          *
 432          * Currently always returns the same as Selection::type().
 433          */
 434         e_index_t type() const { return sel_->rawPositions_.m.type; }
 435         //! Returns coordinates for this position.
 436         const rvec &x() const
 437         {
 438             return sel_->rawPositions_.x[i_];
 439         }
 440         //! Returns whether velocity is available for this position.
 441         bool hasVelocity() const { return sel_->rawPositions_.v != NULL; }
 442         /*! \brief
 443          * Returns velocity for this position.
 444          *
 445          * Must not be called if hasVelocity() returns false.
 446          */
 447         const rvec &v() const
 448         {
 449             GMX_ASSERT(hasVelocity(), "Velocities accessed, but unavailable");
 450             return sel_->rawPositions_.v[i_];
 451         }
 452         //! Returns whether force is available for this position.
 453         bool hasForce() const { return sel_->rawPositions_.f != NULL; }
 454         /*! \brief
 455          * Returns force for this position.
 456          *
 457          * Must not be called if hasForce() returns false.
 458          */
 459         const rvec &f() const
 460         {
 461             GMX_ASSERT(hasForce(), "Forces accessed, but unavailable");
 462             return sel_->rawPositions_.f[i_];
 463         }
 464         /*! \brief
 465          * Returns total mass for this position.
 466          *
 467          * Returns the total mass of atoms that make up this position.
 468          * If there are no atoms associated or masses are not available,
 469          * returns unity.
 470          */
 471         real mass() const
 472         {
 473             return sel_->posMass_[i_];
 474         }
 475         /*! \brief
 476          * Returns total charge for this position.
 477          *
 478          * Returns the sum of charges of atoms that make up this position.
 479          * If there are no atoms associated or charges are not available,
 480          * returns zero.
 481          */
 482         real charge() const
 483         {
 484             return sel_->posCharge_[i_];
 485         }
 486         //! Returns the number of atoms that make up this position.
 487         int atomCount() const
 488         {
 489             return sel_->rawPositions_.m.mapb.index[i_ + 1]
 490                    - sel_->rawPositions_.m.mapb.index[i_];
 491         }
 492         //! Return atom indices that make up this position.
 493         ConstArrayRef<int> atomIndices() const
 494         {
 495             if (sel_->rawPositions_.g == NULL)
 496             {
 497                 return ConstArrayRef<int>();
 498             }
 499             int first = sel_->rawPositions_.m.mapb.index[i_];
 500             return ConstArrayRef<int>(atomCount(),
 501                                       &sel_->rawPositions_.g->index[first]);
 502         }
 503         /*! \brief
 504          * Returns whether this position is selected in the current frame.
 505          *
 506          * The return value is equivalent to \c refid() == -1.  Returns always
 507          * true if SelectionOption::dynamicMask() has not been set.
 508          *
 509          * \see refId()
 510          */
 511         bool selected() const
 512         {
 513             return refId() >= 0;
 514         }
 515         /*! \brief
 516          * Returns reference ID for this position.
 517          *
 518          * For dynamic selections, this provides means to associate positions
 519          * across frames.  After compilation, these IDs are consequently
 520          * numbered starting from zero.  For each frame, the ID then reflects
 521          * the location of the position in the original array of positions.
 522          * If SelectionOption::dynamicMask() has been set for the parent
 523          * selection, the IDs for positions not present in the current
 524          * selection are set to -1, otherwise they are removed completely.
 525          *
 526          * Example:
 527          * If a dynamic selection consists of at most three positions, after
 528          * compilation refId() will return 0, 1, 2 for them, respectively.
 529          * If for a particular frame, only the first and the third are present,
 530          * refId() will return 0, 2.
 531          * If SelectionOption::dynamicMask() has been set, all three positions
 532          * can be accessed also for that frame and refId() will return 0, -1,
 533          * 2.
 534          */
 535         int refId() const
 536         {
 537             return sel_->rawPositions_.m.refid[i_];
 538         }
 539         /*! \brief
 540          * Returns mapped ID for this position.
 541          *
 542          * Returns ID of the position that corresponds to that set with
 543          * Selection::setOriginalId().
 544          *
 545          * If for an array \c id, \c setOriginalId(i, id[i]) has been called
 546          * for each \c i, then it always holds that
 547          * \c mappedId()==id[refId()].
 548          *
 549          * Selection::setOriginalId() has not been called, the default values
 550          * are dependent on type():
 551          *  - ::INDEX_ATOM: atom indices
 552          *  - ::INDEX_RES:  residue numbers
 553          *  - ::INDEX_MOL:  molecule numbers
 554          *  .
 555          * All the default values are zero-based
 556          */
 557         int mappedId() const
 558         {
 559             return sel_->rawPositions_.m.mapid[i_];
 560         }
 561
 562     private:
 563         const internal::SelectionData  *sel_;
 564         int                             i_;
 565 };
 566
 567
 568 inline SelectionPosition
 569 Selection::position(int i) const
 570 {
 571     return SelectionPosition(data(), i);
 572 }
 573
 574 } // namespace gmx
 575
 576 #endif