src/gromacs/selection/sm_position.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2012,2013,2014,2015,2016,2017, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \internal \file
  36  * \brief
  37  * Implements position evaluation selection methods.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \ingroup module_selection
  41  */
  42 #include "gmxpre.h"
  43
  44 #include "gromacs/selection/indexutil.h"
  45 #include "gromacs/selection/position.h"
  46 #include "gromacs/utility/arraysize.h"
  47 #include "gromacs/utility/cstringutil.h"
  48 #include "gromacs/utility/smalloc.h"
  49
  50 #include "keywords.h"
  51 #include "poscalc.h"
  52 #include "selelem.h"
  53 #include "selmethod.h"
  54
  55 /*! \internal \brief
  56  * Data structure for position keyword evaluation.
  57  */
  58 typedef struct
  59 {
  60     /** Position calculation collection to use. */
  61     gmx::PositionCalculationCollection *pcc;
  62     /** Index group for which the center should be evaluated. */
  63     gmx_ana_index_t                     g;
  64     /** Position evaluation data structure. */
  65     gmx_ana_poscalc_t                  *pc;
  66     /** true if periodic boundary conditions should be used. */
  67     bool                                bPBC;
  68     /** Type of positions to calculate. */
  69     char                               *type;
  70     /** Flags for the position calculation. */
  71     int                                 flags;
  72 } t_methoddata_pos;
  73
  74 /** Allocates data for position evaluation selection methods. */
  75 static void *
  76 init_data_pos(int npar, gmx_ana_selparam_t *param);
  77 /** Sets the position calculation collection for position evaluation selection methods. */
  78 static void
  79 set_poscoll_pos(gmx::PositionCalculationCollection *pcc, void *data);
  80 /*! \brief
  81  * Initializes position evaluation keywords.
  82  *
  83  * \param[in] top   Not used.
  84  * \param[in] npar  Not used.
  85  * \param[in] param Not used.
  86  * \param[in,out] data  Should point to \c t_methoddata_pos.
  87  * \returns       0 on success, a non-zero error code on error.
  88  *
  89  * The \c t_methoddata_pos::type field should have been initialized
  90  * externally using _gmx_selelem_set_kwpos_type().
  91  */
  92 static void
  93 init_kwpos(const gmx_mtop_t *top, int npar, gmx_ana_selparam_t *param, void *data);
  94 /*! \brief
  95  * Initializes the \p cog selection method.
  96  *
  97  * \param[in]     top   Topology data structure.
  98  * \param[in]     npar  Not used.
  99  * \param[in]     param Not used.
 100  * \param[in,out] data  Should point to \c t_methoddata_pos.
 101  * \returns       0 on success, a non-zero error code on error.
 102  */
 103 static void
 104 init_cog(const gmx_mtop_t *top, int npar, gmx_ana_selparam_t *param, void *data);
 105 /*! \brief
 106  * Initializes the \p cog selection method.
 107  *
 108  * \param[in]     top   Topology data structure.
 109  * \param[in]     npar  Not used.
 110  * \param[in]     param Not used.
 111  * \param[in,out] data  Should point to \c t_methoddata_pos.
 112  * \returns       0 on success, a non-zero error code on error.
 113  */
 114 static void
 115 init_com(const gmx_mtop_t *top, int npar, gmx_ana_selparam_t *param, void *data);
 116 /*! \brief
 117  * Initializes output for position evaluation selection methods.
 118  *
 119  * \param[in]     top   Topology data structure.
 120  * \param[in,out] out   Pointer to output data structure.
 121  * \param[in,out] data  Should point to \c t_methoddata_pos.
 122  * \returns       0 for success.
 123  */
 124 static void
 125 init_output_pos(const gmx_mtop_t *top, gmx_ana_selvalue_t *out, void *data);
 126 /** Frees the data allocated for position evaluation selection methods. */
 127 static void
 128 free_data_pos(void *data);
 129 /** Evaluates position evaluation selection methods. */
 130 static void
 131 evaluate_pos(const gmx::SelMethodEvalContext &context,
 132              gmx_ana_index_t * /* g */, gmx_ana_selvalue_t *out, void *data);
 133
 134 /** Parameters for position keyword evaluation. */
 135 static gmx_ana_selparam_t smparams_keyword_pos[] = {
 136     {nullptr,   {GROUP_VALUE, 1, {nullptr}}, nullptr, SPAR_DYNAMIC},
 137 };
 138
 139 /** Parameters for the \p cog and \p com selection methods. */
 140 static gmx_ana_selparam_t smparams_com[] = {
 141     {"of",   {GROUP_VALUE, 1, {nullptr}}, nullptr, SPAR_DYNAMIC},
 142     {"pbc",  {NO_VALUE,    0, {nullptr}}, nullptr, 0},
 143 };
 144
 145 /** Selection method data for position keyword evaluation. */
 146 gmx_ana_selmethod_t sm_keyword_pos = {
 147     "kw_pos", POS_VALUE, SMETH_DYNAMIC | SMETH_VARNUMVAL | SMETH_ALLOW_UNSORTED,
 148     asize(smparams_keyword_pos), smparams_keyword_pos,
 149     &init_data_pos,
 150     &set_poscoll_pos,
 151     &init_kwpos,
 152     &init_output_pos,
 153     &free_data_pos,
 154     nullptr,
 155     &evaluate_pos,
 156     nullptr,
 157     {nullptr, nullptr, 0, nullptr},
 158 };
 159
 160 /** Selection method data for the \p cog method. */
 161 gmx_ana_selmethod_t sm_cog = {
 162     "cog", POS_VALUE, SMETH_DYNAMIC | SMETH_SINGLEVAL,
 163     asize(smparams_com), smparams_com,
 164     &init_data_pos,
 165     &set_poscoll_pos,
 166     &init_cog,
 167     &init_output_pos,
 168     &free_data_pos,
 169     nullptr,
 170     &evaluate_pos,
 171     nullptr,
 172     {"cog of ATOM_EXPR [pbc]", nullptr, 0, nullptr},
 173 };
 174
 175 /** Selection method data for the \p com method. */
 176 gmx_ana_selmethod_t sm_com = {
 177     "com", POS_VALUE, SMETH_REQMASS | SMETH_DYNAMIC | SMETH_SINGLEVAL,
 178     asize(smparams_com), smparams_com,
 179     &init_data_pos,
 180     &set_poscoll_pos,
 181     &init_com,
 182     &init_output_pos,
 183     &free_data_pos,
 184     nullptr,
 185     &evaluate_pos,
 186     nullptr,
 187     {"com of ATOM_EXPR [pbc]", nullptr, 0, nullptr},
 188 };
 189
 190 /*!
 191  * \param[in]     npar  Should be 1 or 2.
 192  * \param[in,out] param Method parameters (should point to
 193  *   \ref smparams_keyword_pos or \ref smparams_com).
 194  * \returns       Pointer to the allocated data (\c t_methoddata_pos).
 195  *
 196  * Allocates memory for a \c t_methoddata_pos structure and initializes
 197  * the first parameter to define the value for \c t_methoddata_pos::g.
 198  * If a second parameter is present, it is used for setting the
 199  * \c t_methoddata_pos::bPBC flag.
 200  */
 201 static void *
 202 init_data_pos(int npar, gmx_ana_selparam_t *param)
 203 {
 204     t_methoddata_pos *data;
 205
 206     snew(data, 1);
 207     param[0].val.u.g = &data->g;
 208     if (npar > 1)
 209     {
 210         param[1].val.u.b = &data->bPBC;
 211     }
 212     data->pc       = nullptr;
 213     data->bPBC     = false;
 214     data->type     = nullptr;
 215     data->flags    = -1;
 216     return data;
 217 }
 218
 219 /*!
 220  * \param[in]     pcc   Position calculation collection to use.
 221  * \param[in,out] data  Should point to \c t_methoddata_pos.
 222  */
 223 static void
 224 set_poscoll_pos(gmx::PositionCalculationCollection *pcc, void *data)
 225 {
 226     ((t_methoddata_pos *)data)->pcc = pcc;
 227 }
 228
 229 bool
 230 _gmx_selelem_is_default_kwpos(const gmx::SelectionTreeElement &sel)
 231 {
 232     if (sel.type != SEL_EXPRESSION || !sel.u.expr.method
 233         || sel.u.expr.method->name != sm_keyword_pos.name)
 234     {
 235         return false;
 236     }
 237
 238     t_methoddata_pos *d = static_cast<t_methoddata_pos *>(sel.u.expr.mdata);
 239     return d->type == nullptr;
 240 }
 241
 242 /*! \brief
 243  * Updates selection method flags about required topology information.
 244  *
 245  * Sets the flags to require topology and/or masses if the position calculation
 246  * requires them.
 247  */
 248 static void set_pos_method_flags(gmx_ana_selmethod_t *method,
 249                                  t_methoddata_pos    *d)
 250 {
 251     const bool forces = (d->flags != -1 && (d->flags & POS_FORCES));
 252     switch (gmx::PositionCalculationCollection::requiredTopologyInfoForType(d->type, forces))
 253     {
 254         case gmx::PositionCalculationCollection::RequiredTopologyInfo::TopologyAndMasses:
 255             method->flags |= SMETH_REQMASS;
 256         // fallthrough
 257         case gmx::PositionCalculationCollection::RequiredTopologyInfo::Topology:
 258             method->flags |= SMETH_REQTOP;
 259             break;
 260         case gmx::PositionCalculationCollection::RequiredTopologyInfo::None:
 261             break;
 262     }
 263 }
 264
 265 /*!
 266  * \param[in,out] sel   Selection element to initialize.
 267  * \param[in]     type  One of the enum values acceptable for
 268  *     PositionCalculationCollection::typeFromEnum().
 269  *
 270  * Initializes the reference position type for position evaluation.
 271  * If called multiple times, the first setting takes effect, and later calls
 272  * are neglected.
 273  */
 274 void
 275 _gmx_selelem_set_kwpos_type(gmx::SelectionTreeElement *sel, const char *type)
 276 {
 277     t_methoddata_pos *d = (t_methoddata_pos *)sel->u.expr.mdata;
 278
 279     if (sel->type != SEL_EXPRESSION || !sel->u.expr.method
 280         || sel->u.expr.method->name != sm_keyword_pos.name)
 281     {
 282         return;
 283     }
 284     if (!d->type && type)
 285     {
 286         d->type = gmx_strdup(type);
 287         set_pos_method_flags(sel->u.expr.method, d);
 288     }
 289 }
 290
 291 /*!
 292  * \param[in,out] sel   Selection element to initialize.
 293  * \param[in]     flags Default completion flags
 294  *     (see PositionCalculationCollection::typeFromEnum()).
 295  *
 296  * Initializes the flags for position evaluation.
 297  * If called multiple times, the first setting takes effect, and later calls
 298  * are neglected.
 299  */
 300 void
 301 _gmx_selelem_set_kwpos_flags(gmx::SelectionTreeElement *sel, int flags)
 302 {
 303     t_methoddata_pos *d = (t_methoddata_pos *)sel->u.expr.mdata;
 304
 305     if (sel->type != SEL_EXPRESSION || !sel->u.expr.method
 306         || sel->u.expr.method->name != sm_keyword_pos.name)
 307     {
 308         return;
 309     }
 310     if (d->flags == -1)
 311     {
 312         GMX_RELEASE_ASSERT(d->type != nullptr,
 313                            "Position type should be set before flags");
 314         d->flags = flags;
 315         set_pos_method_flags(sel->u.expr.method, d);
 316     }
 317 }
 318
 319 static void
 320 init_kwpos(const gmx_mtop_t * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
 321 {
 322     t_methoddata_pos *d = (t_methoddata_pos *)data;
 323
 324     if (!(param[0].flags & SPAR_DYNAMIC))
 325     {
 326         d->flags &= ~(POS_DYNAMIC | POS_MASKONLY);
 327     }
 328     else if (!(d->flags & POS_MASKONLY))
 329     {
 330         d->flags |= POS_DYNAMIC;
 331     }
 332     d->pc = d->pcc->createCalculationFromEnum(d->type, d->flags);
 333     gmx_ana_poscalc_set_maxindex(d->pc, &d->g);
 334 }
 335
 336 static void
 337 init_cog(const gmx_mtop_t * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
 338 {
 339     t_methoddata_pos *d = (t_methoddata_pos *)data;
 340
 341     d->flags = (param[0].flags & SPAR_DYNAMIC) ? POS_DYNAMIC : 0;
 342     d->pc    = d->pcc->createCalculation(d->bPBC ? POS_ALL_PBC : POS_ALL, d->flags);
 343     gmx_ana_poscalc_set_maxindex(d->pc, &d->g);
 344 }
 345
 346 static void
 347 init_com(const gmx_mtop_t * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
 348 {
 349     t_methoddata_pos *d = (t_methoddata_pos *)data;
 350
 351     d->flags  = (param[0].flags & SPAR_DYNAMIC) ? POS_DYNAMIC : 0;
 352     d->flags |= POS_MASS;
 353     d->pc     = d->pcc->createCalculation(d->bPBC ? POS_ALL_PBC : POS_ALL, d->flags);
 354     gmx_ana_poscalc_set_maxindex(d->pc, &d->g);
 355 }
 356
 357 static void
 358 init_output_pos(const gmx_mtop_t * /* top */, gmx_ana_selvalue_t *out, void *data)
 359 {
 360     t_methoddata_pos *d = (t_methoddata_pos *)data;
 361
 362     gmx_ana_poscalc_init_pos(d->pc, out->u.p);
 363 }
 364
 365 /*!
 366  * \param data Data to free (should point to a \c t_methoddata_pos).
 367  *
 368  * Frees the memory allocated for \c t_methoddata_pos::g and
 369  * \c t_methoddata_pos::pc.
 370  */
 371 static void
 372 free_data_pos(void *data)
 373 {
 374     t_methoddata_pos *d = (t_methoddata_pos *)data;
 375
 376     sfree(d->type);
 377     gmx_ana_poscalc_free(d->pc);
 378     sfree(d);
 379 }
 380
 381 /*!
 382  * See sel_updatefunc() for description of the parameters.
 383  * \p data should point to a \c t_methoddata_pos.
 384  *
 385  * Calculates the positions using \c t_methoddata_pos::pc for the index group
 386  * in \c t_methoddata_pos::g and stores the results in \p out->u.p.
 387  */
 388 static void
 389 evaluate_pos(const gmx::SelMethodEvalContext &context,
 390              gmx_ana_index_t * /* g */, gmx_ana_selvalue_t *out, void *data)
 391 {
 392     t_methoddata_pos *d = (t_methoddata_pos *)data;
 393
 394     gmx_ana_poscalc_update(d->pc, out->u.p, &d->g, context.fr, context.pbc);
 395 }