2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2014,2015,2016,2017,2018, 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"
58 template <typename T> class ArrayRef;
60 class AnalysisDataPlotSettings;
61 class ICommandLineOptionsModuleSettings;
63 class TrajectoryAnalysisRunnerCommon;
66 * Trajectory analysis module configuration object.
68 * This class is used by trajectory analysis modules to inform the caller
69 * about the requirements they have on the input (e.g., whether a topology is
70 * required, or whether PBC removal makes sense). It is also used to pass
71 * similar information back to the analysis module after parsing user input.
73 * Having this functionality as a separate class makes the
74 * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
75 * change existing code when new options are added.
77 * Methods in this class do not throw, except for the constructor, which may
78 * throw an std::bad_alloc.
81 * Remove plain flags from the public interface.
84 * \ingroup module_trajectoryanalysis
86 class TrajectoryAnalysisSettings
93 * Forces loading of a topology file.
95 * If this flag is not specified, the topology file is loaded only
96 * if it is provided on the command line explicitly.
100 * Requests topology coordinates.
102 * If this flag is specified, the coordinates loaded from the
103 * topology can be accessed, otherwise they are not loaded.
105 * \see TopologyInformation
109 * Disallows the user from changing PBC handling.
111 * If this option is not specified, the analysis module (see
112 * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
113 * PBC structure, and it should be able to handle such a situation.
119 * Disallows the user from changing PBC removal.
123 efNoUserRmPBC = 1<<5,
126 //! Initializes default settings.
127 TrajectoryAnalysisSettings();
128 ~TrajectoryAnalysisSettings();
130 //! Injects command line options module settings for some methods to use.
131 void setOptionsModuleSettings(ICommandLineOptionsModuleSettings *settings);
133 //! Returns the time unit the user has requested.
134 TimeUnit timeUnit() const;
135 //! Returns common settings for analysis data plot modules.
136 const AnalysisDataPlotSettings &plotSettings() const;
138 //! Returns the currently set flags.
139 unsigned long flags() const;
140 //! Tests whether a flag has been set.
141 bool hasFlag(unsigned long flag) const;
143 * Returns whether PBC should be used.
145 * Returns the value set with setPBC() and/or overridden by the user.
146 * The user-provided value can be accessed in
147 * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
148 * with a call to setPBC().
152 * Returns whether molecules should be made whole.
154 * See hasPBC() for information on accessing or overriding the
155 * user-provided value.
157 bool hasRmPBC() const;
158 //! Returns the currently set frame flags.
164 * Overrides any earlier set flags.
165 * By default, no flags are set.
167 void setFlags(unsigned long flags);
168 //! Sets or clears an individual flag.
169 void setFlag(unsigned long flag, bool bSet = true);
171 * Sets whether PBC are used.
173 * \param[in] bPBC true if PBC should be used.
175 * If called in TrajectoryAnalysisModule::initOptions(), this function
176 * sets the default for whether PBC are used in the analysis.
177 * If \ref efNoUserPBC is not set, a command-line option is provided
178 * for the user to override the default value.
179 * If called later, it overrides the setting provided by the user or an
182 * If this function is not called, the default is to use PBC.
184 * If PBC are not used, the \p pbc pointer passed to
185 * TrajectoryAnalysisModule::analyzeFrame() is NULL.
186 * The value of the flag can also be accessed with hasPBC().
190 void setPBC(bool bPBC);
192 * Sets whether molecules are made whole.
194 * \param[in] bRmPBC true if molecules should be made whole.
196 * If called in TrajectoryAnalysisModule::initOptions(), this function
197 * sets the default for whether molecules are made whole.
198 * If \ref efNoUserRmPBC is not set, a command-line option is provided
199 * for the user to override the default value.
200 * If called later, it overrides the setting provided by the user or an
203 * If this function is not called, the default is to make molecules
206 * The main use of this function is to call it with \c false if your
207 * analysis program does not require whole molecules as this can
208 * increase the performance.
209 * In such a case, you can also specify \ref efNoUserRmPBC to not to
210 * confuse the user with an option that would only slow the program
215 void setRmPBC(bool bRmPBC);
217 * Sets flags that determine what to read from the trajectory.
219 * \param[in] frflags Flags for what to read from the trajectory file.
221 * If this function is not called, the flags default to TRX_NEED_X.
222 * If the analysis module needs some other information (velocities,
223 * forces), it can call this function to load additional information
224 * from the trajectory.
226 void setFrameFlags(int frflags);
228 //! \copydoc ICommandLineOptionsModuleSettings::setHelpText()
229 void setHelpText(const ArrayRef<const char *const> &help);
234 PrivateImplPointer<Impl> impl_;
236 friend class TrajectoryAnalysisRunnerCommon;
240 * Topology information passed to a trajectory analysis module.
242 * This class is used to pass topology information to trajectory analysis
243 * modules and to manage memory for them. Having a single wrapper object
244 * instead of passing each item separately makes TrajectoryAnalysisModule
245 * interface simpler, and also reduces the need to change existing code if
246 * additional information is added.
248 * Methods in this class do not throw if not explicitly stated.
251 * \ingroup module_trajectoryanalysis
253 class TopologyInformation
256 //! Returns true if a topology file was loaded.
257 bool hasTopology() const { return mtop_ != nullptr; }
258 //! Returns true if a full topology file was loaded.
259 bool hasFullTopology() const { return bTop_; }
260 //! Returns the loaded topology, or NULL if not loaded.
261 const gmx_mtop_t *mtop() const { return mtop_.get(); }
262 //! Returns the loaded topology, or NULL if not loaded.
263 t_topology *topology() const;
264 //! Returns the ePBC field from the topology.
265 int ePBC() const { return ePBC_; }
267 * Gets the configuration from the topology.
269 * \param[out] x Topology coordinate pointer to initialize.
270 * (can be NULL, in which case it is not used).
271 * \param[out] box Box size from the topology file
272 * (can be NULL, in which case it is not used).
273 * \throws APIError if topology coordinates are not available and
276 * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
277 * \p x should be NULL.
279 * The pointer returned in \p *x should not be freed.
281 void getTopologyConf(rvec **x, matrix box) const;
284 TopologyInformation();
285 ~TopologyInformation();
287 std::unique_ptr<gmx_mtop_t> mtop_;
288 //! The topology structure, or NULL if no topology loaded.
289 // TODO: Replace fully with mtop.
290 mutable t_topology *top_;
291 //! true if full tpx file was loaded, false otherwise.
293 //! Coordinates from the topology (can be NULL).
295 //! The box loaded from the topology file.
297 //! The ePBC field loaded from the topology file.
300 GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
303 * Needed to initialize the data.
305 friend class TrajectoryAnalysisRunnerCommon;