2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2009,2010,2011,2012,2013,2014, 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.
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.
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.
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.
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.
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.
37 * Implements internal selection methods for numeric and string keyword
40 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_selection
50 #include <boost/shared_ptr.hpp>
52 #include "gromacs/legacyheaders/macros.h"
53 #include "gromacs/utility/cstringutil.h"
54 #include "gromacs/utility/exceptions.h"
55 #include "gromacs/utility/gmxregex.h"
56 #include "gromacs/utility/messagestringcollector.h"
57 #include "gromacs/utility/smalloc.h"
58 #include "gromacs/utility/stringutil.h"
61 #include "parsetree.h"
64 #include "selmethod.h"
67 * Allocates data for integer keyword evaluation.
69 * \param[in] npar Not used.
70 * \param param Not used.
71 * \returns Pointer to the allocated data (\ref t_methoddata_kwint).
73 * Allocates memory for a \ref t_methoddata_kwint structure.
76 init_data_kwint(int npar, gmx_ana_selparam_t * param);
78 * Allocates data for real keyword evaluation.
80 * \param[in] npar Not used.
81 * \param param Not used.
82 * \returns Pointer to the allocated data (\ref t_methoddata_kwreal).
84 * Allocates memory for a \ref t_methoddata_kwreal structure.
87 init_data_kwreal(int npar, gmx_ana_selparam_t * param);
89 * Allocates data for string keyword evaluation.
91 * \param[in] npar Not used.
92 * \param param Not used.
93 * \returns Pointer to the allocated data (t_methoddata_kwstr).
95 * Allocates memory for a t_methoddata_kwstr structure.
98 init_data_kwstr(int npar, gmx_ana_selparam_t * param);
99 /** /brief Initializes data for integer keyword evaluation.
101 * \param[in] top Not used.
102 * \param[in] npar Not used (should be 2).
103 * \param[in] param Method parameters (should point to \ref smparams_keyword_int).
104 * \param[in] data Should point to \ref t_methoddata_kwint.
107 init_kwint(t_topology *top, int npar, gmx_ana_selparam_t *param, void *data);
109 * Initializes data for real keyword evaluation.
111 * \param[in] top Not used.
112 * \param[in] npar Not used (should be 2).
113 * \param[in] param Method parameters (should point to \ref smparams_keyword_real).
114 * \param[in] data Should point to \ref t_methoddata_kwreal.
115 * \returns 0 (the initialization always succeeds).
118 init_kwreal(t_topology *top, int npar, gmx_ana_selparam_t *param, void *data);
120 * Initializes data for string keyword evaluation.
122 * \param[in] top Not used.
123 * \param[in] npar Not used (should be 2).
124 * \param[in] param Method parameters (should point to \ref smparams_keyword_str).
125 * \param[in] data Should point to t_methoddata_kwstr.
128 init_kwstr(t_topology *top, int npar, gmx_ana_selparam_t *param, void *data);
129 /** Frees the memory allocated for string keyword evaluation. */
131 free_data_kwstr(void *data);
132 /** Evaluates integer selection keywords. */
134 evaluate_keyword_int(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
135 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data);
136 /** Evaluates real selection keywords. */
138 evaluate_keyword_real(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
139 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data);
140 /** Evaluates string selection keywords. */
142 evaluate_keyword_str(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
143 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data);
146 * Data structure for integer keyword expression evaluation.
148 typedef struct t_methoddata_kwint
150 /** Array of values for the keyword. */
152 /** Number of ranges in the \p r array. */
155 * Array of sorted integer ranges to match against.
157 * Each range is made of two integers, giving the endpoints (inclusive).
158 * This field stores the pointer to the ranges allocated by the
159 * parameter parser; see \ref SPAR_RANGES for more information.
162 } t_methoddata_kwint;
165 * Data structure for real keyword expression evaluation.
167 typedef struct t_methoddata_kwreal
169 /** Array of values for the keyword. */
171 /** Number of ranges in the \p r array. */
174 * Array of sorted ranges to match against.
176 * Each range is made of two values, giving the endpoints (inclusive).
177 * This field stores the pointer to the ranges allocated by the
178 * parameter parser; see \ref SPAR_RANGES for more information.
181 } t_methoddata_kwreal;
187 * Single item in the list of strings/regular expressions to match.
189 * \ingroup module_selection
191 class StringKeywordMatchItem
195 * Constructs a matcher from a string.
197 * \param[in] matchType String matching type.
198 * \param[in] str String to use for matching.
200 StringKeywordMatchItem(gmx::SelectionStringMatchType matchType,
204 bool bRegExp = (matchType == gmx::eStringMatchType_RegularExpression);
205 if (matchType == gmx::eStringMatchType_Auto)
207 for (size_t j = 0; j < std::strlen(str); ++j)
209 if (std::ispunct(str[j]) && str[j] != '?' && str[j] != '*')
218 if (!gmx::Regex::isSupported())
220 GMX_THROW(gmx::InvalidInputError(gmx::formatString(
221 "No regular expression support, "
222 "cannot match \"%s\"", str)));
224 regex_.reset(new gmx::Regex(str));
229 * Checks whether this item matches a string.
231 * \param[in] matchType String matching type.
232 * \param[in] value String to match.
233 * \returns true if this item matches \p value.
235 bool match(gmx::SelectionStringMatchType matchType,
236 const char *value) const
238 if (matchType == gmx::eStringMatchType_Exact)
240 return str_ == value;
244 return gmx::regexMatch(value, *regex_);
248 return gmx_wcmatch(str_.c_str(), value) == 0;
253 //! The raw string passed for the matcher.
255 //! Regular expression compiled from \p str_, if applicable.
256 boost::shared_ptr<gmx::Regex> regex_;
260 * Data structure for string keyword expression evaluation.
262 struct t_methoddata_kwstr
264 /** Matching type for the strings. */
265 gmx::SelectionStringMatchType matchType;
266 /** Array of values for the keyword. */
268 /** Array of strings/regular expressions to match against.*/
269 std::vector<StringKeywordMatchItem> matches;
274 /** Parameters for integer keyword evaluation. */
275 static gmx_ana_selparam_t smparams_keyword_int[] = {
276 {NULL, {INT_VALUE, -1, {NULL}}, NULL, SPAR_ATOMVAL},
277 {NULL, {INT_VALUE, -1, {NULL}}, NULL, SPAR_RANGES | SPAR_VARNUM},
280 /** Parameters for real keyword evaluation. */
281 static gmx_ana_selparam_t smparams_keyword_real[] = {
282 {NULL, {REAL_VALUE, -1, {NULL}}, NULL, SPAR_ATOMVAL | SPAR_DYNAMIC},
283 {NULL, {REAL_VALUE, -1, {NULL}}, NULL, SPAR_RANGES | SPAR_VARNUM},
286 /** Parameters for string keyword evaluation. */
287 static gmx_ana_selparam_t smparams_keyword_str[] = {
288 {NULL, {STR_VALUE, -1, {NULL}}, NULL, SPAR_ATOMVAL},
289 {NULL, {STR_VALUE, -1, {NULL}}, NULL, SPAR_VARNUM},
292 /** Selection method data for integer keyword evaluation. */
293 gmx_ana_selmethod_t sm_keyword_int = {
294 "kw_int", GROUP_VALUE, SMETH_SINGLEVAL,
295 asize(smparams_keyword_int), smparams_keyword_int,
302 &evaluate_keyword_int,
307 /** Selection method data for real keyword evaluation. */
308 gmx_ana_selmethod_t sm_keyword_real = {
309 "kw_real", GROUP_VALUE, SMETH_SINGLEVAL,
310 asize(smparams_keyword_real), smparams_keyword_real,
317 &evaluate_keyword_real,
322 /** Selection method data for string keyword evaluation. */
323 gmx_ana_selmethod_t sm_keyword_str = {
324 "kw_str", GROUP_VALUE, SMETH_SINGLEVAL,
325 asize(smparams_keyword_str), smparams_keyword_str,
332 &evaluate_keyword_str,
338 * Initializes keyword evaluation for an arbitrary group.
340 * \param[in] top Not used.
341 * \param[in] npar Not used.
342 * \param[in] param Not used.
343 * \param[in] data Should point to \ref t_methoddata_kweval.
344 * \returns 0 on success, a non-zero error code on return.
346 * Calls the initialization method of the wrapped keyword.
349 init_kweval(t_topology *top, int npar, gmx_ana_selparam_t * param, void *data);
351 * Initializes output for keyword evaluation in an arbitrary group.
353 * \param[in] top Not used.
354 * \param[in,out] out Pointer to output data structure.
355 * \param[in,out] data Should point to \c t_methoddata_kweval.
356 * \returns 0 for success.
359 init_output_kweval(t_topology *top, gmx_ana_selvalue_t *out, void *data);
360 /** Frees the data allocated for keyword evaluation in an arbitrary group. */
362 free_data_kweval(void *data);
363 /** Initializes frame evaluation for keyword evaluation in an arbitrary group. */
365 init_frame_kweval(t_topology *top, t_trxframe *fr, t_pbc *pbc, void *data);
366 /** Evaluates keywords in an arbitrary group. */
368 evaluate_kweval(t_topology *top, t_trxframe *fr, t_pbc *pbc, gmx_ana_index_t * /* g */, gmx_ana_selvalue_t *out, void *data);
371 * Data structure for keyword evaluation in arbitrary groups.
375 /** Wrapped keyword method for evaluating the values. */
376 gmx_ana_selmethod_t *kwmethod;
377 /** Method data for \p kwmethod. */
379 /** Group in which \p kwmethod should be evaluated. */
381 } t_methoddata_kweval;
383 /** Parameters for keyword evaluation in an arbitrary group. */
384 static gmx_ana_selparam_t smparams_kweval[] = {
385 {NULL, {GROUP_VALUE, 1, {NULL}}, NULL, SPAR_DYNAMIC},
389 /********************************************************************
390 * INTEGER KEYWORD EVALUATION
391 ********************************************************************/
394 init_data_kwint(int /* npar */, gmx_ana_selparam_t * /* param */)
396 t_methoddata_kwint *data;
403 init_kwint(t_topology * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
405 t_methoddata_kwint *d = (t_methoddata_kwint *)data;
407 d->v = param[0].val.u.i;
408 d->n = param[1].val.nr;
409 d->r = param[1].val.u.i;
413 * See sel_updatefunc() for description of the parameters.
414 * \p data should point to a \c t_methoddata_kwint.
416 * Does a binary search to find which atoms match the ranges in the
417 * \c t_methoddata_kwint structure for this selection.
418 * Matching atoms are stored in \p out->u.g.
421 evaluate_keyword_int(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
422 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data)
424 t_methoddata_kwint *d = (t_methoddata_kwint *)data;
425 int n, i, j, jmin, jmax;
430 for (i = 0; i < g->isize; ++i)
433 if (d->r[0] > val || d->r[2*n-1] < val)
439 while (jmax - jmin > 1)
441 j = jmin + (jmax - jmin) / 2;
449 if (val <= d->r[2*j+1])
456 if (val <= d->r[2*jmin+1])
458 out->u.g->index[out->u.g->isize++] = g->index[i];
464 /********************************************************************
465 * REAL KEYWORD EVALUATION
466 ********************************************************************/
469 init_data_kwreal(int /* npar */, gmx_ana_selparam_t * /* param */)
471 t_methoddata_kwreal *data;
478 init_kwreal(t_topology * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
480 t_methoddata_kwreal *d = (t_methoddata_kwreal *)data;
482 d->v = param[0].val.u.r;
483 d->n = param[1].val.nr;
484 d->r = param[1].val.u.r;
488 * See sel_updatefunc() for description of the parameters.
489 * \p data should point to a \c t_methoddata_kwreal.
491 * Does a binary search to find which atoms match the ranges in the
492 * \c t_methoddata_kwreal structure for this selection.
493 * Matching atoms are stored in \p out->u.g.
496 evaluate_keyword_real(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
497 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data)
499 t_methoddata_kwreal *d = (t_methoddata_kwreal *)data;
500 int n, i, j, jmin, jmax;
505 for (i = 0; i < g->isize; ++i)
508 if (d->r[0] > val || d->r[2*n-1] < val)
514 while (jmax - jmin > 1)
516 j = jmin + (jmax - jmin) / 2;
524 if (val <= d->r[2*j+1])
531 if (val <= d->r[2*jmin+1])
533 out->u.g->index[out->u.g->isize++] = g->index[i];
539 /********************************************************************
540 * STRING KEYWORD EVALUATION
541 ********************************************************************/
544 init_data_kwstr(int /* npar */, gmx_ana_selparam_t * /* param */)
546 t_methoddata_kwstr *data = new t_methoddata_kwstr();
547 data->matchType = gmx::eStringMatchType_Auto;
552 * \param[in,out] sel Selection element to initialize.
553 * \param[in] matchType Method to use to match string values.
555 * Sets the string matching method for string keyword matching.
558 _gmx_selelem_set_kwstr_match_type(const gmx::SelectionTreeElementPointer &sel,
559 gmx::SelectionStringMatchType matchType)
561 t_methoddata_kwstr *d = static_cast<t_methoddata_kwstr *>(sel->u.expr.mdata);
563 if (sel->type != SEL_EXPRESSION || !sel->u.expr.method
564 || sel->u.expr.method->name != sm_keyword_str.name)
568 d->matchType = matchType;
572 init_kwstr(t_topology * /* top */, int /* npar */, gmx_ana_selparam_t *param, void *data)
574 t_methoddata_kwstr *d = static_cast<t_methoddata_kwstr *>(data);
576 d->v = param[0].val.u.s;
577 /* Return if this is not the first time */
578 if (!d->matches.empty())
582 int n = param[1].val.nr;
583 d->matches.reserve(n);
584 for (int i = 0; i < n; ++i)
586 const char *s = param[1].val.u.s[i];
587 d->matches.push_back(StringKeywordMatchItem(d->matchType, s));
592 * \param data Data to free (should point to a t_methoddata_kwstr).
595 free_data_kwstr(void *data)
597 t_methoddata_kwstr *d = static_cast<t_methoddata_kwstr *>(data);
602 * See sel_updatefunc() for description of the parameters.
603 * \p data should point to a \c t_methoddata_kwstr.
605 * Does a linear search to find which atoms match the strings in the
606 * \c t_methoddata_kwstr structure for this selection.
607 * Wildcards are allowed in the strings.
608 * Matching atoms are stored in \p out->u.g.
611 evaluate_keyword_str(t_topology * /* top */, t_trxframe * /* fr */, t_pbc * /* pbc */,
612 gmx_ana_index_t *g, gmx_ana_selvalue_t *out, void *data)
614 t_methoddata_kwstr *d = static_cast<t_methoddata_kwstr *>(data);
617 for (int i = 0; i < g->isize; ++i)
619 for (size_t j = 0; j < d->matches.size(); ++j)
621 if (d->matches[j].match(d->matchType, d->v[i]))
623 out->u.g->index[out->u.g->isize++] = g->index[i];
631 /********************************************************************
632 * KEYWORD EVALUATION FOR ARBITRARY GROUPS
633 ********************************************************************/
636 init_kweval(t_topology *top, int /* npar */, gmx_ana_selparam_t * /* param */, void *data)
638 t_methoddata_kweval *d = (t_methoddata_kweval *)data;
640 d->kwmethod->init(top, 0, NULL, d->kwmdata);
644 init_output_kweval(t_topology * /* top */, gmx_ana_selvalue_t *out, void *data)
646 t_methoddata_kweval *d = (t_methoddata_kweval *)data;
648 out->nr = d->g.isize;
649 _gmx_selvalue_reserve(out, out->nr);
653 * \param data Data to free (should point to a \c t_methoddata_kweval).
655 * Frees the memory allocated for all the members of \c t_methoddata_kweval.
658 free_data_kweval(void *data)
660 t_methoddata_kweval *d = (t_methoddata_kweval *)data;
662 _gmx_selelem_free_method(d->kwmethod, d->kwmdata);
667 * \param[in] top Topology.
668 * \param[in] fr Current frame.
669 * \param[in] pbc PBC structure.
670 * \param data Should point to a \ref t_methoddata_kweval.
671 * \returns 0 on success, a non-zero error code on error.
673 * Creates a lookup structure that enables fast queries of whether a point
674 * is within the solid angle or not.
677 init_frame_kweval(t_topology *top, t_trxframe *fr, t_pbc *pbc, void *data)
679 t_methoddata_kweval *d = (t_methoddata_kweval *)data;
681 d->kwmethod->init_frame(top, fr, pbc, d->kwmdata);
685 * See sel_updatefunc() for description of the parameters.
686 * \p data should point to a \c t_methoddata_kweval.
688 * Calls the evaluation function of the wrapped keyword with the given
689 * parameters, with the exception of using \c t_methoddata_kweval::g for the
693 evaluate_kweval(t_topology *top, t_trxframe *fr, t_pbc *pbc,
694 gmx_ana_index_t * /* g */, gmx_ana_selvalue_t *out, void *data)
696 t_methoddata_kweval *d = (t_methoddata_kweval *)data;
698 d->kwmethod->update(top, fr, pbc, &d->g, out, d->kwmdata);
702 * \param[in] method Keyword selection method to evaluate.
703 * \param[in] params Parameter that gives the group to evaluate \p method in.
704 * \param[in] scanner Scanner data structure.
705 * \returns Pointer to the created selection element (NULL on error).
707 * Creates a \ref SEL_EXPRESSION selection element that evaluates the keyword
708 * method given by \p method in the group given by \p param.
710 * The name of \p param should be empty.
712 gmx::SelectionTreeElementPointer
713 _gmx_sel_init_keyword_evaluator(gmx_ana_selmethod_t *method,
714 const gmx::SelectionParserParameterList ¶ms,
717 gmx::MessageStringCollector *errors = _gmx_sel_lexer_error_reporter(scanner);
719 sprintf(buf, "In evaluation of '%s'", method->name);
720 gmx::MessageStringContext context(errors, buf);
722 if ((method->flags & (SMETH_SINGLEVAL | SMETH_VARNUMVAL))
723 || method->outinit || method->pupdate)
725 GMX_THROW(gmx::InternalError(
726 "Unsupported keyword method for arbitrary group evaluation"));
729 gmx::SelectionTreeElementPointer sel(
730 new gmx::SelectionTreeElement(SEL_EXPRESSION));
731 _gmx_selelem_set_method(sel, method, scanner);
733 t_methoddata_kweval *data;
735 data->kwmethod = sel->u.expr.method;
736 data->kwmdata = sel->u.expr.mdata;
737 gmx_ana_index_clear(&data->g);
739 snew(sel->u.expr.method, 1);
740 memcpy(sel->u.expr.method, data->kwmethod, sizeof(gmx_ana_selmethod_t));
741 sel->u.expr.method->flags |= SMETH_VARNUMVAL;
742 sel->u.expr.method->init_data = NULL;
743 sel->u.expr.method->set_poscoll = NULL;
744 sel->u.expr.method->init = method->init ? &init_kweval : NULL;
745 sel->u.expr.method->outinit = &init_output_kweval;
746 sel->u.expr.method->free = &free_data_kweval;
747 sel->u.expr.method->init_frame = method->init_frame ? &init_frame_kweval : NULL;
748 sel->u.expr.method->update = &evaluate_kweval;
749 sel->u.expr.method->pupdate = NULL;
750 sel->u.expr.method->nparams = asize(smparams_kweval);
751 sel->u.expr.method->param = smparams_kweval;
752 _gmx_selelem_init_method_params(sel, scanner);
753 sel->u.expr.mdata = data;
755 sel->u.expr.method->param[0].val.u.g = &data->g;
757 if (!_gmx_sel_parse_params(params, sel->u.expr.method->nparams,
758 sel->u.expr.method->param, sel, scanner))
760 return gmx::SelectionTreeElementPointer();