src/gromacs/selection/selparam.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2013,2014 by the GROMACS development team.
   5  * Copyright (c) 2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \internal \file
  37  * \brief API for handling parameters used in selections.
  38  *
  39  * There should be no need to use the data structures or call the
  40  * functions in this file directly unless implementing a custom selection
  41  * method.
  42  *
  43  * More details can be found on the page discussing
  44  * \ref page_module_selection_custom "custom selection methods".
  45  *
  46  * \author Teemu Murtola <teemu.murtola@gmail.com>
  47  * \ingroup module_selection
  48  */
  49 #ifndef GMX_SELECTION_SELPARAM_H
  50 #define GMX_SELECTION_SELPARAM_H
  51
  52 #include "gromacs/selection/indexutil.h"
  53
  54 #include "selvalue.h"
  55
  56 /*! \name Parameter flags
  57  * \anchor selparam_flags
  58  */
  59 /*@{*/
  60 /*! \brief
  61  * This flag is set if the user has provided the parameter.
  62  *
  63  * This flag is set automatically, and should not be set by the user.
  64  */
  65 #define SPAR_SET 1
  66 /*! \brief
  67  * If not set, an error is reported if the parameter is not specified by the
  68  * user.
  69  */
  70 #define SPAR_OPTIONAL 2
  71 /*! \brief
  72  * If set, the parameter value can be dynamic, i.e., be different for
  73  * different frames.
  74  *
  75  * If set, the parameter value should only be accessed in the update function
  76  * of \c gmx_ana_selmethod_t.
  77  * The flag is cleared before sel_initfunc() if the value provided is actually
  78  * static.
  79  */
  80 #define SPAR_DYNAMIC 4
  81 /*! \brief
  82  * If set, the parameter value is parsed into sorted ranges.
  83  *
  84  * Can only be specified for integer parameters.
  85  * If specified, the value of the parameter (\c gmx_ana_selparam_t::val)
  86  * consists of sets of two integers, each specifying a range.
  87  * The values give the endpoints of the ranges (inclusive).
  88  * The ranges are sorted and overlapping/continuous ranges are merged into
  89  * a single range to minimize the number of ranges.
  90  *
  91  * If this flag is specified, \c gmx_ana_selparam_t::nval gives the number of
  92  * ranges. \p gmx_ana_selparam_t::nval should be 1 or \ref SPAR_VARNUM should be
  93  * specified; other values would lead to unpredictable behavior.
  94  */
  95 #define SPAR_RANGES 8
  96 /*! \brief
  97  * If set, the parameter can have any number of values.
  98  *
  99  * If specified, the data pointer in \c gmx_ana_selparam_t::val should be NULL;
 100  * the memory is allocated by the parameter parser.
 101  * The implementation of the method should ensure that the pointer to the
 102  * allocated memory is stored somewhere in sel_initfunc();
 103  * otherwise, the memory is lost.
 104  *
 105  * The initial value of \c gmx_ana_selparam_t::nval is not used with this flag.
 106  * Instead, it will give the number of actual values provided by the user
 107  * after the parameters have been parsed.
 108  * For consistency, it should be initialized to -1.
 109  *
 110  * Cannot be combined with \ref GROUP_VALUE parameters.
 111  */
 112 #define SPAR_VARNUM 16
 113 /*! \brief
 114  * If set, the parameter can have a separate value for each atom.
 115  *
 116  * The flag is cleared before sel_initfunc() if the value provided is actually
 117  * a single value.
 118  *
 119  * Cannot be combined with \ref POS_VALUE or \ref GROUP_VALUE parameters.
 120  */
 121 #define SPAR_ATOMVAL 32
 122 /*! \brief
 123  * If set, the parameter takes one of a set of predefined strings.
 124  *
 125  * Can only be specified for a \ref STR_VALUE parameter that takes a single
 126  * string.
 127  * The data pointer in \c gmx_ana_selparam_t::val should be initialized into an
 128  * array of strings such that the first and last elements are NULL, and the
 129  * rest give the possible values. For optional values, the second element in
 130  * the array should give the default value. The string given by the user is
 131  * matched against the beginnings of the given strings, and if a unique match
 132  * is found, the first pointer in the array will be initialized to point to
 133  * the matching string.
 134  * The data pointer can be initialized as a static array; duplication of the
 135  * array for multiple instances of the same method is automatically taken care
 136  * of.
 137  */
 138 #define SPAR_ENUMVAL 128
 139 /*@}*/
 140
 141 /*! \internal \brief
 142  * Describes a single parameter for a selection method.
 143  */
 144 typedef struct gmx_ana_selparam_t
 145 {
 146     /** Name of the parameter. */
 147     const char* name;
 148     /*! \brief
 149      * The parameter value.
 150      *
 151      * Type \ref NO_VALUE can be used to define a boolean parameter.
 152      * The number of values should be 0 for boolean parameters.
 153      *
 154      * The value pointer be initialized to NULL in the definition of a
 155      * \c gmx_ana_selmethod_t and initialized in the
 156      * \c gmx_ana_selmethod_t::init_data call
 157      * (see sel_datafunc()).
 158      * However, if \ref SPAR_VARNUM is provided and the parameter is not
 159      * \ref POS_VALUE, this field should not be initialized. Instead,
 160      * sufficient memory is allocated automatically and the pointer should be
 161      * stored in \c gmx_ana_selmethod_t::init
 162      * (see sel_initfunc()).
 163      *
 164      * The values cannot be accessed outside these two functions: the compiler
 165      * makes a copy of the parameter structure for each instance of the
 166      * method, and the original parameter array is not changed.
 167      */
 168     gmx_ana_selvalue_t val;
 169     /*! \brief
 170      * Pointer to store the number of values.
 171      *
 172      * If not NULL, the number of values for the parameter is stored in the
 173      * pointed value.
 174      * Should be specified if \ref SPAR_VARNUM and \ref SPAR_DYNAMIC are both
 175      * set.
 176      *
 177      * Should be initialized to NULL in the definition a \c gmx_ana_selmethod_t
 178      * and initialized in sel_datafunc().
 179      */
 180     int* nvalptr;
 181     /*! \brief
 182      * Flags that alter the way the parameter is parsed/handled.
 183      *
 184      * See \ref selparam_flags for allowed values.
 185      */
 186     int flags;
 187 } gmx_ana_selparam_t;
 188
 189 /** Finds a parameter from an array by name. */
 190 gmx_ana_selparam_t* gmx_ana_selparam_find(const char* name, int nparam, gmx_ana_selparam_t* param);
 191
 192 #endif