src/gmxlib/selection/selection.c

   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 /*! \internal \file
  32  * \brief
  33  * Implementation of functions in selection.h.
  34  */
  35 /*! \internal \dir src/gmxlib/selection
  36  * \brief
  37  * Source code for selection-related routines.
  38  */
  39 #ifdef HAVE_CONFIG_H
  40 #include <config.h>
  41 #endif
  42
  43 #include <smalloc.h>
  44 #include <statutil.h>
  45 #include <string2.h>
  46 #include <xvgr.h>
  47 #include <gmx_fatal.h>
  48
  49 #include <poscalc.h>
  50 #include <selection.h>
  51 #include <selmethod.h>
  52
  53 #include "mempool.h"
  54 #include "selcollection.h"
  55 #include "selelem.h"
  56 #include "symrec.h"
  57
  58 /*!
  59  * \param[out] scp Pointer to a newly allocated empty selection collection.
  60  * \param[in]  pcc Position calculation data structure to use for selection
  61  *   position evaluation.
  62  * \returns    0 on success.
  63  */
  64 int
  65 gmx_ana_selcollection_create(gmx_ana_selcollection_t **scp,
  66                              gmx_ana_poscalc_coll_t *pcc)
  67 {
  68     gmx_ana_selcollection_t *sc;
  69
  70     snew(sc, 1);
  71     sc->rpost     = NULL;
  72     sc->spost     = NULL;
  73     sc->bMaskOnly = FALSE;
  74     sc->bVelocities = FALSE;
  75     sc->bForces   = FALSE;
  76     sc->root      = NULL;
  77     sc->nr        = 0;
  78     sc->sel       = NULL;
  79     sc->nvars     = 0;
  80     sc->varstrs   = NULL;
  81     sc->top       = NULL;
  82     gmx_ana_index_clear(&sc->gall);
  83     sc->pcc       = pcc;
  84     sc->mempool   = NULL;
  85     _gmx_sel_symtab_create(&sc->symtab);
  86     *scp = sc;
  87     return 0;
  88 }
  89
  90 /*!
  91  * \param[in,out] sc Selection collection to free.
  92  *
  93  * The pointer \p sc is invalid after the call.
  94  */
  95 void
  96 gmx_ana_selcollection_free(gmx_ana_selcollection_t *sc)
  97 {
  98     int  i;
  99
 100     _gmx_selelem_free_chain(sc->root);
 101     if (sc->sel)
 102     {
 103         for (i = 0; i < sc->nr; ++i)
 104         {
 105             gmx_ana_selection_free(sc->sel[i]);
 106         }
 107     }
 108     sfree(sc->sel);
 109     for (i = 0; i < sc->nvars; ++i)
 110     {
 111         sfree(sc->varstrs[i]);
 112     }
 113     sfree(sc->varstrs);
 114     gmx_ana_index_deinit(&sc->gall);
 115     if (sc->mempool)
 116     {
 117         _gmx_sel_mempool_destroy(sc->mempool);
 118     }
 119     _gmx_selcollection_clear_symtab(sc);
 120     sfree(sc);
 121 }
 122
 123 /*!
 124  * \param[in,out] sc Selection collection.
 125  */
 126 void
 127 _gmx_selcollection_clear_symtab(gmx_ana_selcollection_t *sc)
 128 {
 129     if (sc->symtab)
 130     {
 131         _gmx_sel_symtab_free(sc->symtab);
 132         sc->symtab = NULL;
 133     }
 134 }
 135
 136 /*!
 137  * \param[in,out] sc        Selection collection to modify.
 138  * \param[in]     type      Default selection reference position type
 139  *   (one of the strings acceptable for gmx_ana_poscalc_type_from_enum()).
 140  *
 141  * Should be called before calling gmx_ana_selcollection_requires_top() or
 142  * gmx_ana_selcollection_parse_*().
 143  */
 144 void
 145 gmx_ana_selcollection_set_refpostype(gmx_ana_selcollection_t *sc,
 146                                      const char *type)
 147 {
 148     sc->rpost     = type;
 149 }
 150
 151 /*!
 152  * \param[in,out] sc        Selection collection to modify.
 153  * \param[in]     type      Default selection output position type
 154  *   (one of the strings acceptable for gmx_ana_poslcalc_type_from_enum()).
 155  * \param[in]     bMaskOnly If TRUE, the output positions are initialized
 156  *   using \ref POS_MASKONLY.
 157  *
 158  * If \p type is NULL, the default type is not modified.
 159  * Should be called before calling gmx_ana_selcollection_requires_top() or
 160  * gmx_ana_selcollection_parse_*().
 161  */
 162 void
 163 gmx_ana_selcollection_set_outpostype(gmx_ana_selcollection_t *sc,
 164                                      const char *type, bool bMaskOnly)
 165 {
 166     if (type)
 167     {
 168         sc->spost     = type;
 169     }
 170     sc->bMaskOnly = bMaskOnly;
 171 }
 172
 173 /*!
 174  * \param[in,out] sc        Selection collection to modify.
 175  * \param[in]     bVelOut   If TRUE, selections will also evaluate
 176  *      velocities.
 177  */
 178 void
 179 gmx_ana_selcollection_set_veloutput(gmx_ana_selcollection_t *sc,
 180                                     bool bVelOut)
 181 {
 182     sc->bVelocities = bVelOut;
 183 }
 184
 185 /*!
 186  * \param[in,out] sc        Selection collection to modify.
 187  * \param[in]     bForceOut If TRUE, selections will also evaluate
 188  *      forces.
 189  */
 190 void
 191 gmx_ana_selcollection_set_forceoutput(gmx_ana_selcollection_t *sc,
 192                                       bool bForceOut)
 193 {
 194     sc->bForces = bForceOut;
 195 }
 196
 197 /*!
 198  * \param[in,out] sc        Selection collection to set the topology for.
 199  * \param[in]     top       Topology data.
 200  * \param[in]     natoms    Number of atoms. If <=0, the number of atoms in the
 201  *   topology is used.
 202  * \returns       0 on success, EINVAL if \p top is NULL and \p natoms <= 0.
 203  *
 204  * The topology is also set for the position calculation collection
 205  * associated with \p sc.
 206  *
 207  * \p natoms determines the largest atom index that can be selected by the
 208  * selection: even if the topology contains more atoms, they will not be
 209  * selected.
 210  */
 211 int
 212 gmx_ana_selcollection_set_topology(gmx_ana_selcollection_t *sc, t_topology *top,
 213                                    int natoms)
 214 {
 215     gmx_ana_poscalc_coll_set_topology(sc->pcc, top);
 216     sc->top = top;
 217
 218     /* Get the number of atoms from the topology if it is not given */
 219     if (natoms <= 0)
 220     {
 221         if (!sc->top)
 222         {
 223             gmx_incons("selections need either the topology or the number of atoms");
 224             return EINVAL;
 225         }
 226         natoms = sc->top->atoms.nr;
 227     }
 228     gmx_ana_index_init_simple(&sc->gall, natoms, NULL);
 229     return 0;
 230 }
 231
 232 /*!
 233  * \param[in]  sc  Selection collection to query.
 234  * \returns    Number of selections in \p sc.
 235  *
 236  * If gmx_ana_selcollection_parse_*() has not been called, returns 0.
 237  *
 238  * \see gmx_ana_selcollection_get_selection()
 239  */
 240 int
 241 gmx_ana_selcollection_get_count(gmx_ana_selcollection_t *sc)
 242 {
 243     return sc->nr;
 244 }
 245
 246 /*!
 247  * \param[in]  sc  Selection collection to query.
 248  * \param[in]  i   Number of the selection.
 249  * \returns    Pointer to the \p i'th selection in \p sc,
 250  *   or NULL if there is no such selection.
 251  *
 252  * \p i should be between 0 and the value returned by
 253  * gmx_ana_selcollection_get_count().
 254  * The returned pointer should not be freed.
 255  * If gmx_ana_selcollection_compile() has not been called, the returned
 256  * selection is not completely initialized (but the returned pointer will be
 257  * valid even after compilation, and will point to the initialized selection).
 258  *
 259  * \see gmx_ana_selcollection_get_count()
 260  */
 261 gmx_ana_selection_t *
 262 gmx_ana_selcollection_get_selection(gmx_ana_selcollection_t *sc, int i)
 263 {
 264     if (i < 0 || i >= sc->nr || !sc->sel)
 265         return NULL;
 266     return sc->sel[i];
 267 }
 268
 269 /*!
 270  * \param[in]  sc  Selection collection to query.
 271  * \returns    TRUE if any selection in \p sc requires topology information,
 272  *   FALSE otherwise.
 273  *
 274  * Before gmx_ana_selcollection_parse_*(), the return value is based just on
 275  * the position types set.
 276  * After gmx_ana_selcollection_parse_*(), the return value also takes into account the
 277  * selection keywords used.
 278  */
 279 bool
 280 gmx_ana_selcollection_requires_top(gmx_ana_selcollection_t *sc)
 281 {
 282     t_selelem   *sel;
 283     e_poscalc_t  type;
 284     int          flags;
 285     int          rc;
 286
 287     if (sc->rpost)
 288     {
 289         flags = 0;
 290         rc = gmx_ana_poscalc_type_from_enum(sc->rpost, &type, &flags);
 291         if (rc == 0 && type != POS_ATOM)
 292         {
 293             return TRUE;
 294         }
 295     }
 296     if (sc->spost)
 297     {
 298         flags = 0;
 299         rc = gmx_ana_poscalc_type_from_enum(sc->spost, &type, &flags);
 300         if (rc == 0 && type != POS_ATOM)
 301         {
 302             return TRUE;
 303         }
 304     }
 305
 306     sel = sc->root;
 307     while (sel)
 308     {
 309         if (_gmx_selelem_requires_top(sel))
 310         {
 311             return TRUE;
 312         }
 313         sel = sel->next;
 314     }
 315     return FALSE;
 316 }
 317
 318 /*!
 319  * \param[in] fp      File handle to receive the output.
 320  * \param[in] sc      Selection collection to print.
 321  * \param[in] bValues If TRUE, the evaluated values of selection elements
 322  *   are printed as well.
 323  */
 324 void
 325 gmx_ana_selcollection_print_tree(FILE *fp, gmx_ana_selcollection_t *sc, bool bValues)
 326 {
 327     t_selelem *sel;
 328
 329     sel = sc->root;
 330     while (sel)
 331     {
 332         _gmx_selelem_print_tree(fp, sel, bValues, 0);
 333         sel = sel->next;
 334     }
 335 }
 336
 337 /*!
 338  * \param[in] sel  Selection to free.
 339  *
 340  * After the call, the pointer \p sel is invalid.
 341  */
 342 void
 343 gmx_ana_selection_free(gmx_ana_selection_t *sel)
 344 {
 345     sfree(sel->name);
 346     sfree(sel->selstr);
 347     gmx_ana_pos_deinit(&sel->p);
 348     if (sel->m != sel->orgm)
 349     {
 350         sfree(sel->m);
 351     }
 352     if (sel->q != sel->orgq)
 353     {
 354         sfree(sel->q);
 355     }
 356     sfree(sel->orgm);
 357     sfree(sel->orgq);
 358     sfree(sel);
 359 }
 360
 361 /*!
 362  * \param[in] sel  Selection whose name is needed.
 363  * \returns   Pointer to the name of the selection.
 364  *
 365  * The return value should not be freed by the caller.
 366  */
 367 char *
 368 gmx_ana_selection_name(gmx_ana_selection_t *sel)
 369 {
 370     return sel->name;
 371 }
 372
 373 /*!
 374  * \param[in] sel  Selection for which information should be printed.
 375  */
 376 void
 377 gmx_ana_selection_print_info(gmx_ana_selection_t *sel)
 378 {
 379     fprintf(stderr, "\"%s\" (%d position%s, %d atom%s%s)", sel->name,
 380             sel->p.nr,     sel->p.nr     == 1 ? "" : "s",
 381             sel->g->isize, sel->g->isize == 1 ? "" : "s",
 382             sel->bDynamic ? ", dynamic" : "");
 383     fprintf(stderr, "\n");
 384 }
 385
 386 /*!
 387  * \param[in] sel  Selection to initialize.
 388  * \param[in] type Type of covered fraction required.
 389  * \returns   TRUE if the covered fraction can be calculated for the selection,
 390  *   FALSE otherwise.
 391  */
 392 bool
 393 gmx_ana_selection_init_coverfrac(gmx_ana_selection_t *sel, e_coverfrac_t type)
 394 {
 395     sel->cfractype = type;
 396     if (type == CFRAC_NONE || !sel->selelem)
 397     {
 398         sel->bCFracDyn = FALSE;
 399     }
 400     else if (!_gmx_selelem_can_estimate_cover(sel->selelem))
 401     {
 402         sel->cfractype = CFRAC_NONE;
 403         sel->bCFracDyn = FALSE;
 404     }
 405     else
 406     {
 407         sel->bCFracDyn = TRUE;
 408     }
 409     sel->cfrac     = sel->bCFracDyn ? 0.0 : 1.0;
 410     sel->avecfrac  = sel->cfrac;
 411     return type == CFRAC_NONE || sel->cfractype != CFRAC_NONE;
 412 }
 413
 414 /*!
 415  * \param[in] out  Output file.
 416  * \param[in] sc   Selection collection which should be written.
 417  * \param[in] oenv Output options structure.
 418  */
 419 void xvgr_selcollection(FILE *out, gmx_ana_selcollection_t *sc,
 420                         const output_env_t oenv)
 421 {
 422     int  i;
 423
 424     if (output_env_get_xvg_format(oenv) != exvgNONE && sc)
 425     {
 426         fprintf(out, "# Selections:\n");
 427         for (i = 0; i < sc->nvars; ++i)
 428         {
 429             fprintf(out, "#   %s\n", sc->varstrs[i]);
 430         }
 431         for (i = 0; i < sc->nr; ++i)
 432         {
 433             fprintf(out, "#   %s\n", sc->sel[i]->selstr);
 434         }
 435         fprintf(out, "#\n");
 436     }
 437 }