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