Gromacs  2024.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions | Friends
gmx::TrajectoryAnalysisSettings Class Reference

#include <gromacs/trajectoryanalysis/analysissettings.h>

Description

Trajectory analysis module configuration object.

This class is used by trajectory analysis modules to inform the caller about the requirements they have on the input (e.g., whether a topology is required, or whether PBC removal makes sense). It is also used to pass similar information back to the analysis module after parsing user input.

Having this functionality as a separate class makes the TrajectoryAnalysisModule interface much cleaner, and also reduces the need to change existing code when new options are added.

Methods in this class do not throw, except for the constructor, which may throw an std::bad_alloc.

Todo:
Remove plain flags from the public interface.
Examples:
template.cpp.

Public Types

enum  {
  efRequireTop = 1 << 0, efUseTopX = 1 << 1, efUseTopV = 1 << 2, efNoUserPBC = 1 << 4,
  efNoUserRmPBC = 1 << 5
}
 Recognized flags. More...
 

Public Member Functions

 TrajectoryAnalysisSettings ()
 Initializes default settings.
 
void setOptionsModuleSettings (ICommandLineOptionsModuleSettings *settings)
 Injects command line options module settings for some methods to use.
 
TimeUnit timeUnit () const
 Returns the time unit the user has requested.
 
const AnalysisDataPlotSettingsplotSettings () const
 Returns common settings for analysis data plot modules.
 
unsigned long flags () const
 Returns the currently set flags.
 
bool hasFlag (unsigned long flag) const
 Tests whether a flag has been set.
 
bool hasPBC () const
 Returns whether PBC should be used. More...
 
bool hasRmPBC () const
 Returns whether molecules should be made whole. More...
 
int frflags () const
 Returns the currently set frame flags.
 
void setFlags (unsigned long flags)
 Sets flags. More...
 
void setFlag (unsigned long flag, bool bSet=true)
 Sets or clears an individual flag.
 
void setPBC (bool bPBC)
 Sets whether PBC are used. More...
 
void setRmPBC (bool bRmPBC)
 Sets whether molecules are made whole. More...
 
void setFrameFlags (int frflags)
 Sets flags that determine what to read from the trajectory. More...
 
void setHelpText (const ArrayRef< const char *const > &help)
 Sets the help text for the module from string array. More...
 

Friends

class TrajectoryAnalysisRunnerCommon
 

Member Enumeration Documentation

anonymous enum

Recognized flags.

Enumerator
efRequireTop 

Forces loading of a topology file.

If this flag is not specified, the topology file is loaded only if it is provided on the command line explicitly.

efUseTopX 

Requests topology coordinates.

If this flag is specified, the position coordinates loaded from the topology can be accessed, otherwise they are not loaded.

See Also
TopologyInformation
efUseTopV 

Requests topology coordinates.

If this flag is specified, the velocity coordinates loaded from the topology can be accessed, otherwise they are not loaded.

See Also
TopologyInformation
efNoUserPBC 

Disallows the user from changing PBC handling.

If this option is not specified, the analysis module (see TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL PBC structure, and it should be able to handle such a situation.

See Also
setPBC()
efNoUserRmPBC 

Disallows the user from changing PBC removal.

See Also
setRmPBC()

Member Function Documentation

bool gmx::TrajectoryAnalysisSettings::hasPBC ( ) const

Returns whether PBC should be used.

Returns the value set with setPBC() and/or overridden by the user. The user-provided value can be accessed in TrajectoryAnalysisModule::optionsFinished(), and can be overridden with a call to setPBC().

bool gmx::TrajectoryAnalysisSettings::hasRmPBC ( ) const

Returns whether molecules should be made whole.

See hasPBC() for information on accessing or overriding the user-provided value.

void gmx::TrajectoryAnalysisSettings::setFlags ( unsigned long  flags)

Sets flags.

Overrides any earlier set flags. By default, no flags are set.

void gmx::TrajectoryAnalysisSettings::setFrameFlags ( int  frflags)

Sets flags that determine what to read from the trajectory.

Parameters
[in]frflagsFlags for what to read from the trajectory file.

If this function is not called, the flags default to TRX_NEED_X. If the analysis module needs some other information (velocities, forces), it can call this function to load additional information from the trajectory.

void gmx::TrajectoryAnalysisSettings::setHelpText ( const ArrayRef< const char *const > &  help)

Sets the help text for the module from string array.

Parameters
[in]helpString array to set as the description.
Exceptions
std::bad_allocif out of memory.

Formatting for the help text is described on Help formatting.

Example usage:

const char *const desc[] = {
"This is the description",
"for the options"
};
settings->setHelpText(desc);
Examples:
template.cpp.
void gmx::TrajectoryAnalysisSettings::setPBC ( bool  bPBC)

Sets whether PBC are used.

Parameters
[in]bPBCtrue if PBC should be used.

If called in TrajectoryAnalysisModule::initOptions(), this function sets the default for whether PBC are used in the analysis. If efNoUserPBC is not set, a command-line option is provided for the user to override the default value. If called later, it overrides the setting provided by the user or an earlier call.

If this function is not called, the default is to use PBC.

If PBC are not used, the pbc pointer passed to TrajectoryAnalysisModule::analyzeFrame() is NULL. The value of the flag can also be accessed with hasPBC().

See Also
efNoUserPBC
void gmx::TrajectoryAnalysisSettings::setRmPBC ( bool  bRmPBC)

Sets whether molecules are made whole.

Parameters
[in]bRmPBCtrue if molecules should be made whole.

If called in TrajectoryAnalysisModule::initOptions(), this function sets the default for whether molecules are made whole. If efNoUserRmPBC is not set, a command-line option is provided for the user to override the default value. If called later, it overrides the setting provided by the user or an earlier call.

If this function is not called, the default is to make molecules whole.

The main use of this function is to call it with false if your analysis program does not require whole molecules as this can increase the performance. In such a case, you can also specify efNoUserRmPBC to not to confuse the user with an option that would only slow the program down.

See Also
efNoUserRmPBC

The documentation for this class was generated from the following files: