2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2014,2015, 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 * Declares gmx::TrajectoryAnalysisSettings and gmx::TopologyInformation.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_trajectoryanalysis
43 #ifndef GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
44 #define GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
48 #include "gromacs/math/vectypes.h"
49 #include "gromacs/options/timeunitmanager.h"
50 #include "gromacs/utility/classhelpers.h"
57 template <typename T
> class ConstArrayRef
;
59 class AnalysisDataPlotSettings
;
60 class ICommandLineOptionsModuleSettings
;
62 class TrajectoryAnalysisRunnerCommon
;
65 * Trajectory analysis module configuration object.
67 * This class is used by trajectory analysis modules to inform the caller
68 * about the requirements they have on the input (e.g., whether a topology is
69 * required, or whether PBC removal makes sense). It is also used to pass
70 * similar information back to the analysis module after parsing user input.
72 * Having this functionality as a separate class makes the
73 * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
74 * change existing code when new options are added.
76 * Methods in this class do not throw, except for the constructor, which may
77 * throw an std::bad_alloc.
80 * Remove plain flags from the public interface.
83 * \ingroup module_trajectoryanalysis
85 class TrajectoryAnalysisSettings
92 * Forces loading of a topology file.
94 * If this flag is not specified, the topology file is loaded only
95 * if it is provided on the command line explicitly.
99 * Requests topology coordinates.
101 * If this flag is specified, the coordinates loaded from the
102 * topology can be accessed, otherwise they are not loaded.
104 * \see TopologyInformation
108 * Disallows the user from changing PBC handling.
110 * If this option is not specified, the analysis module (see
111 * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
112 * PBC structure, and it should be able to handle such a situation.
118 * Disallows the user from changing PBC removal.
122 efNoUserRmPBC
= 1<<5,
125 //! Initializes default settings.
126 TrajectoryAnalysisSettings();
127 ~TrajectoryAnalysisSettings();
129 //! Injects command line options module settings for some methods to use.
130 void setOptionsModuleSettings(ICommandLineOptionsModuleSettings
*settings
);
132 //! Returns the time unit the user has requested.
133 TimeUnit
timeUnit() const;
134 //! Returns common settings for analysis data plot modules.
135 const AnalysisDataPlotSettings
&plotSettings() const;
137 //! Returns the currently set flags.
138 unsigned long flags() const;
139 //! Tests whether a flag has been set.
140 bool hasFlag(unsigned long flag
) const;
142 * Returns whether PBC should be used.
144 * Returns the value set with setPBC() and/or overridden by the user.
145 * The user-provided value can be accessed in
146 * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
147 * with a call to setPBC().
151 * Returns whether molecules should be made whole.
153 * See hasPBC() for information on accessing or overriding the
154 * user-provided value.
156 bool hasRmPBC() const;
157 //! Returns the currently set frame flags.
163 * Overrides any earlier set flags.
164 * By default, no flags are set.
166 void setFlags(unsigned long flags
);
167 //! Sets or clears an individual flag.
168 void setFlag(unsigned long flag
, bool bSet
= true);
170 * Sets whether PBC are used.
172 * \param[in] bPBC true if PBC should be used.
174 * If called in TrajectoryAnalysisModule::initOptions(), this function
175 * sets the default for whether PBC are used in the analysis.
176 * If \ref efNoUserPBC is not set, a command-line option is provided
177 * for the user to override the default value.
178 * If called later, it overrides the setting provided by the user or an
181 * If this function is not called, the default is to use PBC.
183 * If PBC are not used, the \p pbc pointer passed to
184 * TrajectoryAnalysisModule::analyzeFrame() is NULL.
185 * The value of the flag can also be accessed with hasPBC().
189 void setPBC(bool bPBC
);
191 * Sets whether molecules are made whole.
193 * \param[in] bRmPBC true if molecules should be made whole.
195 * If called in TrajectoryAnalysisModule::initOptions(), this function
196 * sets the default for whether molecules are made whole.
197 * If \ref efNoUserRmPBC is not set, a command-line option is provided
198 * for the user to override the default value.
199 * If called later, it overrides the setting provided by the user or an
202 * If this function is not called, the default is to make molecules
205 * The main use of this function is to call it with \c false if your
206 * analysis program does not require whole molecules as this can
207 * increase the performance.
208 * In such a case, you can also specify \ref efNoUserRmPBC to not to
209 * confuse the user with an option that would only slow the program
214 void setRmPBC(bool bRmPBC
);
216 * Sets flags that determine what to read from the trajectory.
218 * \param[in] frflags Flags for what to read from the trajectory file.
220 * If this function is not called, the flags default to TRX_NEED_X.
221 * If the analysis module needs some other information (velocities,
222 * forces), it can call this function to load additional information
223 * from the trajectory.
225 void setFrameFlags(int frflags
);
227 //! \copydoc ICommandLineOptionsModuleSettings::setHelpText()
228 void setHelpText(const ConstArrayRef
<const char *> &help
);
233 PrivateImplPointer
<Impl
> impl_
;
235 friend class TrajectoryAnalysisRunnerCommon
;
239 * Topology information passed to a trajectory analysis module.
241 * This class is used to pass topology information to trajectory analysis
242 * modules and to manage memory for them. Having a single wrapper object
243 * instead of passing each item separately makes TrajectoryAnalysisModule
244 * interface simpler, and also reduces the need to change existing code if
245 * additional information is added.
247 * Methods in this class do not throw if not explicitly stated.
250 * \ingroup module_trajectoryanalysis
252 class TopologyInformation
255 //! Returns true if a topology file was loaded.
256 bool hasTopology() const { return top_
!= NULL
; }
257 //! Returns true if a full topology file was loaded.
258 bool hasFullTopology() const { return bTop_
; }
259 //! Returns the loaded topology, or NULL if not loaded.
260 t_topology
*topology() const { return top_
; }
261 //! Returns the ePBC field from the topology.
262 int ePBC() const { return ePBC_
; }
264 * Gets the configuration from the topology.
266 * \param[out] x Topology coordinate pointer to initialize.
267 * (can be NULL, in which case it is not used).
268 * \param[out] box Box size from the topology file
269 * (can be NULL, in which case it is not used).
270 * \throws APIError if topology coordinates are not available and
273 * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
274 * \p x should be NULL.
276 * The pointer returned in \p *x should not be freed.
278 void getTopologyConf(rvec
**x
, matrix box
) const;
281 TopologyInformation();
282 ~TopologyInformation();
284 //! The topology structure, or NULL if no topology loaded.
286 //! true if full tpx file was loaded, false otherwise.
288 //! Coordinates from the topology (can be NULL).
290 //! The box loaded from the topology file.
292 //! The ePBC field loaded from the topology file.
295 GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation
);
298 * Needed to initialize the data.
300 friend class TrajectoryAnalysisRunnerCommon
;