2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012, 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
46 #include "../legacyheaders/typedefs.h"
48 #include "../options/timeunitmanager.h"
49 #include "../utility/common.h"
54 class AnalysisDataPlotSettings;
56 class TrajectoryAnalysisRunnerCommon;
59 * Trajectory analysis module configuration object.
61 * This class is used by trajectory analysis modules to inform the caller
62 * about the requirements they have on the input (e.g., whether a topology is
63 * required, or whether PBC removal makes sense). It is also used to pass
64 * similar information back to the analysis module after parsing user input.
66 * Having this functionality as a separate class makes the
67 * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
68 * change existing code when new options are added.
70 * Methods in this class do not throw, except for the constructor, which may
71 * throw an std::bad_alloc.
74 * Remove plain flags from the public interface.
77 * \ingroup module_trajectoryanalysis
79 class TrajectoryAnalysisSettings
86 * Forces loading of a topology file.
88 * If this flag is not specified, the topology file is loaded only
89 * if it is provided on the command line explicitly.
93 * Requests topology coordinates.
95 * If this flag is specified, the coordinates loaded from the
96 * topology can be accessed, otherwise they are not loaded.
98 * \see TopologyInformation
102 * Disallows the user from changing PBC handling.
104 * If this option is not specified, the analysis module (see
105 * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
106 * PBC structure, and it should be able to handle such a situation.
112 * Disallows the user from changing PBC removal.
116 efNoUserRmPBC = 1<<5,
119 //! Initializes default settings.
120 TrajectoryAnalysisSettings();
121 ~TrajectoryAnalysisSettings();
123 //! Returns the time unit manager with time unit timeUnit().
124 const TimeUnitManager &timeUnitManager() const;
125 //! Returns the time unit the user has requested.
126 TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
127 //! Returns common settings for analysis data plot modules.
128 const AnalysisDataPlotSettings &plotSettings() const;
130 //! Returns the currently set flags.
131 unsigned long flags() const;
132 //! Tests whether a flag has been set.
133 bool hasFlag(unsigned long flag) const;
135 * Returns whether PBC should be used.
137 * Returns the value set with setPBC() and/or overridden by the user.
138 * The user-provided value can be accessed in
139 * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
140 * with a call to setPBC().
144 * Returns whether molecules should be made whole.
146 * See hasPBC() for information on accessing or overriding the
147 * user-provided value.
149 bool hasRmPBC() const;
150 //! Returns the currently set frame flags.
156 * Overrides any earlier set flags.
157 * By default, no flags are set.
159 void setFlags(unsigned long flags);
160 //! Sets or clears an individual flag.
161 void setFlag(unsigned long flag, bool bSet = true);
163 * Sets whether PBC are used.
165 * \param[in] bPBC true if PBC should be used.
167 * If called in TrajectoryAnalysisModule::initOptions(), this function
168 * sets the default for whether PBC are used in the analysis.
169 * If \ref efNoUserPBC is not set, a command-line option is provided
170 * for the user to override the default value.
171 * If called later, it overrides the setting provided by the user or an
174 * If this function is not called, the default is to use PBC.
176 * If PBC are not used, the \p pbc pointer passed to
177 * TrajectoryAnalysisModule::analyzeFrame() is NULL.
178 * The value of the flag can also be accessed with hasPBC().
182 void setPBC(bool bPBC);
184 * Sets whether molecules are made whole.
186 * \param[in] bRmPBC true if molecules should be made whole.
188 * If called in TrajectoryAnalysisModule::initOptions(), this function
189 * sets the default for whether molecules are made whole.
190 * If \ref efNoUserRmPBC is not set, a command-line option is provided
191 * for the user to override the default value.
192 * If called later, it overrides the setting provided by the user or an
195 * If this function is not called, the default is to make molecules
198 * The main use of this function is to call it with \c false if your
199 * analysis program does not require whole molecules as this can
200 * increase the performance.
201 * In such a case, you can also specify \ref efNoUserRmPBC to not to
202 * confuse the user with an option that would only slow the program
207 void setRmPBC(bool bRmPBC);
209 * Sets flags that determine what to read from the trajectory.
211 * \param[in] frflags Flags for what to read from the trajectory file.
213 * If this function is not called, the flags default to TRX_NEED_X.
214 * If the analysis module needs some other information (velocities,
215 * forces), it can call this function to load additional information
216 * from the trajectory.
218 void setFrameFlags(int frflags);
223 PrivateImplPointer<Impl> impl_;
225 friend class TrajectoryAnalysisRunnerCommon;
229 * Topology information passed to a trajectory analysis module.
231 * This class is used to pass topology information to trajectory analysis
232 * modules and to manage memory for them. Having a single wrapper object
233 * instead of passing each item separately makes TrajectoryAnalysisModule
234 * interface simpler, and also reduces the need to change existing code if
235 * additional information is added.
237 * Methods in this class do not throw if not explicitly stated.
240 * \ingroup module_trajectoryanalysis
242 class TopologyInformation
245 //! Returns true if a topology file was loaded.
246 bool hasTopology() const { return top_ != NULL; }
247 //! Returns true if a full topology file was loaded.
248 bool hasFullTopology() const { return bTop_; }
249 //! Returns the loaded topology, or NULL if not loaded.
250 t_topology *topology() const { return top_; }
251 //! Returns the ePBC field from the topology.
252 int ePBC() const { return ePBC_; }
254 * Gets the configuration from the topology.
256 * \param[out] x Topology coordinate pointer to initialize.
257 * (can be NULL, in which case it is not used).
258 * \param[out] box Box size from the topology file
259 * (can be NULL, in which case it is not used).
260 * \throws APIError if topology coordinates are not available and
263 * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
264 * \p x should be NULL.
266 * The pointer returned in \p *x should not be freed.
268 void getTopologyConf(rvec **x, matrix box) const;
271 TopologyInformation();
272 ~TopologyInformation();
274 //! The topology structure, or NULL if no topology loaded.
276 //! true if full tpx file was loaded, false otherwise.
278 //! Coordinates from the topology (can be NULL).
280 //! The box loaded from the topology file.
282 //! The ePBC field loaded from the topology file.
285 GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
288 * Needed to initialize the data.
290 friend class TrajectoryAnalysisRunnerCommon;