2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,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 * 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 "../options/timeunitmanager.h"
47 #include "../math/vectypes.h"
48 #include "../utility/common.h"
55 class AnalysisDataPlotSettings;
57 class TrajectoryAnalysisRunnerCommon;
60 * Trajectory analysis module configuration object.
62 * This class is used by trajectory analysis modules to inform the caller
63 * about the requirements they have on the input (e.g., whether a topology is
64 * required, or whether PBC removal makes sense). It is also used to pass
65 * similar information back to the analysis module after parsing user input.
67 * Having this functionality as a separate class makes the
68 * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
69 * change existing code when new options are added.
71 * Methods in this class do not throw, except for the constructor, which may
72 * throw an std::bad_alloc.
75 * Remove plain flags from the public interface.
78 * \ingroup module_trajectoryanalysis
80 class TrajectoryAnalysisSettings
87 * Forces loading of a topology file.
89 * If this flag is not specified, the topology file is loaded only
90 * if it is provided on the command line explicitly.
94 * Requests topology coordinates.
96 * If this flag is specified, the coordinates loaded from the
97 * topology can be accessed, otherwise they are not loaded.
99 * \see TopologyInformation
103 * Disallows the user from changing PBC handling.
105 * If this option is not specified, the analysis module (see
106 * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
107 * PBC structure, and it should be able to handle such a situation.
113 * Disallows the user from changing PBC removal.
117 efNoUserRmPBC = 1<<5,
120 //! Initializes default settings.
121 TrajectoryAnalysisSettings();
122 ~TrajectoryAnalysisSettings();
124 //! Returns the time unit manager with time unit timeUnit().
125 const TimeUnitManager &timeUnitManager() const;
126 //! Returns the time unit the user has requested.
127 TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
128 //! Returns common settings for analysis data plot modules.
129 const AnalysisDataPlotSettings &plotSettings() const;
131 //! Returns the currently set flags.
132 unsigned long flags() const;
133 //! Tests whether a flag has been set.
134 bool hasFlag(unsigned long flag) const;
136 * Returns whether PBC should be used.
138 * Returns the value set with setPBC() and/or overridden by the user.
139 * The user-provided value can be accessed in
140 * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
141 * with a call to setPBC().
145 * Returns whether molecules should be made whole.
147 * See hasPBC() for information on accessing or overriding the
148 * user-provided value.
150 bool hasRmPBC() const;
151 //! Returns the currently set frame flags.
157 * Overrides any earlier set flags.
158 * By default, no flags are set.
160 void setFlags(unsigned long flags);
161 //! Sets or clears an individual flag.
162 void setFlag(unsigned long flag, bool bSet = true);
164 * Sets whether PBC are used.
166 * \param[in] bPBC true if PBC should be used.
168 * If called in TrajectoryAnalysisModule::initOptions(), this function
169 * sets the default for whether PBC are used in the analysis.
170 * If \ref efNoUserPBC is not set, a command-line option is provided
171 * for the user to override the default value.
172 * If called later, it overrides the setting provided by the user or an
175 * If this function is not called, the default is to use PBC.
177 * If PBC are not used, the \p pbc pointer passed to
178 * TrajectoryAnalysisModule::analyzeFrame() is NULL.
179 * The value of the flag can also be accessed with hasPBC().
183 void setPBC(bool bPBC);
185 * Sets whether molecules are made whole.
187 * \param[in] bRmPBC true if molecules should be made whole.
189 * If called in TrajectoryAnalysisModule::initOptions(), this function
190 * sets the default for whether molecules are made whole.
191 * If \ref efNoUserRmPBC is not set, a command-line option is provided
192 * for the user to override the default value.
193 * If called later, it overrides the setting provided by the user or an
196 * If this function is not called, the default is to make molecules
199 * The main use of this function is to call it with \c false if your
200 * analysis program does not require whole molecules as this can
201 * increase the performance.
202 * In such a case, you can also specify \ref efNoUserRmPBC to not to
203 * confuse the user with an option that would only slow the program
208 void setRmPBC(bool bRmPBC);
210 * Sets flags that determine what to read from the trajectory.
212 * \param[in] frflags Flags for what to read from the trajectory file.
214 * If this function is not called, the flags default to TRX_NEED_X.
215 * If the analysis module needs some other information (velocities,
216 * forces), it can call this function to load additional information
217 * from the trajectory.
219 void setFrameFlags(int frflags);
224 PrivateImplPointer<Impl> impl_;
226 friend class TrajectoryAnalysisRunnerCommon;
230 * Topology information passed to a trajectory analysis module.
232 * This class is used to pass topology information to trajectory analysis
233 * modules and to manage memory for them. Having a single wrapper object
234 * instead of passing each item separately makes TrajectoryAnalysisModule
235 * interface simpler, and also reduces the need to change existing code if
236 * additional information is added.
238 * Methods in this class do not throw if not explicitly stated.
241 * \ingroup module_trajectoryanalysis
243 class TopologyInformation
246 //! Returns true if a topology file was loaded.
247 bool hasTopology() const { return top_ != NULL; }
248 //! Returns true if a full topology file was loaded.
249 bool hasFullTopology() const { return bTop_; }
250 //! Returns the loaded topology, or NULL if not loaded.
251 t_topology *topology() const { return top_; }
252 //! Returns the ePBC field from the topology.
253 int ePBC() const { return ePBC_; }
255 * Gets the configuration from the topology.
257 * \param[out] x Topology coordinate pointer to initialize.
258 * (can be NULL, in which case it is not used).
259 * \param[out] box Box size from the topology file
260 * (can be NULL, in which case it is not used).
261 * \throws APIError if topology coordinates are not available and
264 * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
265 * \p x should be NULL.
267 * The pointer returned in \p *x should not be freed.
269 void getTopologyConf(rvec **x, matrix box) const;
272 TopologyInformation();
273 ~TopologyInformation();
275 //! The topology structure, or NULL if no topology loaded.
277 //! true if full tpx file was loaded, false otherwise.
279 //! Coordinates from the topology (can be NULL).
281 //! The box loaded from the topology file.
283 //! The ePBC field loaded from the topology file.
286 GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
289 * Needed to initialize the data.
291 friend class TrajectoryAnalysisRunnerCommon;