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