3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares gmx::TrajectoryAnalysisSettings and gmx::TopologyInformation.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_trajectoryanalysis
39 #ifndef GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
40 #define GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
42 #include "../legacyheaders/typedefs.h"
44 #include "../options/timeunitmanager.h"
45 #include "../utility/common.h"
50 class AnalysisDataPlotSettings;
52 class TrajectoryAnalysisRunnerCommon;
55 * Trajectory analysis module configuration object.
57 * This class is used by trajectory analysis modules to inform the caller
58 * about the requirements they have on the input (e.g., whether a topology is
59 * required, or whether PBC removal makes sense). It is also used to pass
60 * similar information back to the analysis module after parsing user input.
62 * Having this functionality as a separate class makes the
63 * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
64 * change existing code when new options are added.
66 * Methods in this class do not throw, except for the constructor, which may
67 * throw an std::bad_alloc.
70 * Remove plain flags from the public interface.
73 * \ingroup module_trajectoryanalysis
75 class TrajectoryAnalysisSettings
82 * Forces loading of a topology file.
84 * If this flag is not specified, the topology file is loaded only
85 * if it is provided on the command line explicitly.
89 * Requests topology coordinates.
91 * If this flag is specified, the coordinates loaded from the
92 * topology can be accessed, otherwise they are not loaded.
94 * \see TopologyInformation
98 * Disallows the user from changing PBC handling.
100 * If this option is not specified, the analysis module (see
101 * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
102 * PBC structure, and it should be able to handle such a situation.
108 * Disallows the user from changing PBC removal.
112 efNoUserRmPBC = 1<<5,
115 //! Initializes default settings.
116 TrajectoryAnalysisSettings();
117 ~TrajectoryAnalysisSettings();
119 //! Returns the time unit manager with time unit timeUnit().
120 const TimeUnitManager &timeUnitManager() const;
121 //! Returns the time unit the user has requested.
122 TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
123 //! Returns common settings for analysis data plot modules.
124 const AnalysisDataPlotSettings &plotSettings() const;
126 //! Returns the currently set flags.
127 unsigned long flags() const;
128 //! Tests whether a flag has been set.
129 bool hasFlag(unsigned long flag) const;
131 * Returns whether PBC should be used.
133 * Returns the value set with setPBC() and/or overridden by the user.
134 * The user-provided value can be accessed in
135 * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
136 * with a call to setPBC().
140 * Returns whether molecules should be made whole.
142 * See hasPBC() for information on accessing or overriding the
143 * user-provided value.
145 bool hasRmPBC() const;
146 //! Returns the currently set frame flags.
152 * Overrides any earlier set flags.
153 * By default, no flags are set.
155 void setFlags(unsigned long flags);
156 //! Sets or clears an individual flag.
157 void setFlag(unsigned long flag, bool bSet = true);
159 * Sets whether PBC are used.
161 * \param[in] bPBC true if PBC should be used.
163 * If called in TrajectoryAnalysisModule::initOptions(), this function
164 * sets the default for whether PBC are used in the analysis.
165 * If \ref efNoUserPBC is not set, a command-line option is provided
166 * for the user to override the default value.
167 * If called later, it overrides the setting provided by the user or an
170 * If this function is not called, the default is to use PBC.
172 * If PBC are not used, the \p pbc pointer passed to
173 * TrajectoryAnalysisModule::analyzeFrame() is NULL.
174 * The value of the flag can also be accessed with hasPBC().
178 void setPBC(bool bPBC);
180 * Sets whether molecules are made whole.
182 * \param[in] bRmPBC true if molecules should be made whole.
184 * If called in TrajectoryAnalysisModule::initOptions(), this function
185 * sets the default for whether molecules are made whole.
186 * If \ref efNoUserRmPBC is not set, a command-line option is provided
187 * for the user to override the default value.
188 * If called later, it overrides the setting provided by the user or an
191 * If this function is not called, the default is to make molecules
194 * The main use of this function is to call it with \c false if your
195 * analysis program does not require whole molecules as this can
196 * increase the performance.
197 * In such a case, you can also specify \ref efNoUserRmPBC to not to
198 * confuse the user with an option that would only slow the program
203 void setRmPBC(bool bRmPBC);
205 * Sets flags that determine what to read from the trajectory.
207 * \param[in] frflags Flags for what to read from the trajectory file.
209 * If this function is not called, the flags default to TRX_NEED_X.
210 * If the analysis module needs some other information (velocities,
211 * forces), it can call this function to load additional information
212 * from the trajectory.
214 void setFrameFlags(int frflags);
219 PrivateImplPointer<Impl> impl_;
221 friend class TrajectoryAnalysisRunnerCommon;
225 * Topology information passed to a trajectory analysis module.
227 * This class is used to pass topology information to trajectory analysis
228 * modules and to manage memory for them. Having a single wrapper object
229 * instead of passing each item separately makes TrajectoryAnalysisModule
230 * interface simpler, and also reduces the need to change existing code if
231 * additional information is added.
233 * Methods in this class do not throw if not explicitly stated.
236 * \ingroup module_trajectoryanalysis
238 class TopologyInformation
241 //! Returns true if a topology file was loaded.
242 bool hasTopology() const { return top_ != NULL; }
243 //! Returns true if a full topology file was loaded.
244 bool hasFullTopology() const { return bTop_; }
245 //! Returns the loaded topology, or NULL if not loaded.
246 t_topology *topology() const { return top_; }
247 //! Returns the ePBC field from the topology.
248 int ePBC() const { return ePBC_; }
250 * Gets the configuration from the topology.
252 * \param[out] x Topology coordinate pointer to initialize.
253 * (can be NULL, in which case it is not used).
254 * \param[out] box Box size from the topology file
255 * (can be NULL, in which case it is not used).
256 * \throws APIError if topology coordinates are not available and
259 * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
260 * \p x should be NULL.
262 * The pointer returned in \p *x should not be freed.
264 void getTopologyConf(rvec **x, matrix box) const;
267 TopologyInformation();
268 ~TopologyInformation();
270 //! The topology structure, or NULL if no topology loaded.
272 //! true if full tpx file was loaded, false otherwise.
274 //! Coordinates from the topology (can be NULL).
276 //! The box loaded from the topology file.
278 //! The ePBC field loaded from the topology file.
281 GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
284 * Needed to initialize the data.
286 friend class TrajectoryAnalysisRunnerCommon;