Gromacs
2026.0-dev-20241212-74b8831
|
Provides functionality for managing command line programs.
This module provides utility classes and functions for implementing command line programs. They are mainly used within GROMACS, but can also be used from external programs if they want to get a similar user experience to GROMACS tools.
The classes exposed from this module can be roughly divided into two groups:
Helper classes/functions for implementing the main() function. See Using GROMACS as a library for an overview of those available for user programs. These are declared in cmdlineinit.h (gmx::ICommandLineModule is declared in cmdlinemodule.h and gmx::ICommandLineOptions in cmdlineoptionsmodule.h).
Additionally, for internal GROMACS use, gmx::CommandLineModuleManager provides the functionality to implement the gmx
wrapper binary, as well as command line options common to all GROMACS programs (such as -version
). This is described in more detail at Wrapper binary implementation.
Namespaces | |
gmx | |
Generic GROMACS namespace. | |
Classes | |
class | gmx::CommandLineHelpContext |
Context information for writing out command-line help. More... | |
class | gmx::CommandLineHelpWriter |
Writes help information for Options. More... | |
class | gmx::CommandLineModuleSettings |
Settings to pass information between a module and the general runner. More... | |
class | gmx::ICommandLineModule |
Module that can be run from command line using CommandLineModuleManager. More... | |
class | gmx::CommandLineModuleManager |
Implements a wrapper command-line interface for multiple modules. More... | |
class | gmx::CommandLineModuleGroup |
Handle to add content to a group added with CommandLineModuleManager::addModuleGroup(). More... | |
class | gmx::ICommandLineOptionsModuleSettings |
Settings to pass information between a CommandLineOptionsModule and generic code that runs it. More... | |
class | gmx::ICommandLineOptionsModule |
Module that can be run from a command line and uses gmx::Options for argument processing. More... | |
class | gmx::CommandLineParser |
Implements command-line parsing for Options objects. More... | |
class | gmx::IExecutableEnvironment |
Allows customization of the way various directories are found by CommandLineProgramContext. More... | |
class | gmx::CommandLineProgramContext |
Program context implementation for command line programs. More... | |
struct | t_filenm |
File name option definition for C code. More... | |
struct | t_pargs |
Command-line argument definition for C code. More... | |
Macros | |
#define | ffSET 1 << 0 |
Whether a file name option is set. | |
#define | ffREAD 1 << 1 |
Whether a file name option specifies an input file. | |
#define | ffWRITE 1 << 2 |
Whether a file name option specifies an output file. | |
#define | ffOPT 1 << 3 |
Whether a file name option specifies an optional file. | |
#define | ffLIB 1 << 4 |
Whether a file name option specifies a library file. | |
#define | ffMULT 1 << 5 |
Whether a file name option accepts multiple file names. | |
#define | ffALLOW_MISSING 1 << 6 |
Whether an input file name option accepts non-existent files. | |
#define | ffRW (ffREAD | ffWRITE) |
Convenience flag for an input/output file. | |
#define | ffOPTRD (ffREAD | ffOPT) |
Convenience flag for an optional input file. | |
#define | ffOPTWR (ffWRITE | ffOPT) |
Convenience flag for an optional output file. | |
#define | ffOPTRW (ffRW | ffOPT) |
Convenience flag for an optional input/output file. | |
#define | ffLIBRD (ffREAD | ffLIB) |
Convenience flag for a library input file. | |
#define | ffLIBOPTRD (ffOPTRD | ffLIB) |
Convenience flag for an optional library input file. | |
#define | ffRDMULT (ffREAD | ffMULT) |
Convenience flag for an input file that accepts multiple files. | |
#define | ffOPTRDMULT (ffRDMULT | ffOPT) |
Convenience flag for an optional input file that accepts multiple files. | |
#define | ffWRMULT (ffWRITE | ffMULT) |
Convenience flag for an output file that accepts multiple files. | |
#define | ffOPTWRMULT (ffWRMULT | ffOPT) |
Convenience flag for an optional output file that accepts multiple files. | |
#define | opt2FILE(opt, nfile, fnm, mode) gmx_ffopen(opt2fn(opt, nfile, fnm), mode) |
Returns a file pointer from the filename. | |
#define | ftp2FILE(ftp, nfile, fnm, mode) gmx_ffopen(ftp2fn(ftp, nfile, fnm), mode) |
Returns a file pointer from the file type. | |
#define | PCA_CAN_VIEW (1 << 5) |
Add option -w to view output files (must be implemented in program). More... | |
#define | PCA_CAN_BEGIN (1 << 6) |
Add option to set begin time for trajectory reading. More... | |
#define | PCA_CAN_END (1 << 7) |
Add option to set end time for trajectory reading. More... | |
#define | PCA_CAN_DT (1 << 14) |
Add option to set time step for trajectory reading. More... | |
#define | PCA_CAN_TIME (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT) |
Add all options for trajectory time control. More... | |
#define | PCA_TIME_UNIT (1 << 15) |
Add option -tu to set time unit for output. More... | |
#define | PCA_CAN_SET_DEFFNM (1 << 10) |
Add option -deffnm to set default for all file options. More... | |
#define | PCA_NOEXIT_ON_ARGS (1 << 11) |
Do not raise a fatal error when invalid options are encountered. More... | |
#define | PCA_DISABLE_INPUT_FILE_CHECKING (1 << 17) |
Don't do any special processing for ffREAD files. | |
Typedefs | |
typedef std::unique_ptr < ICommandLineModule > | gmx::CommandLineModulePointer |
Smart pointer type for managing a ICommandLineModule. | |
typedef std::map< std::string, CommandLineModulePointer > | gmx::CommandLineModuleMap |
Container type for mapping module names to module objects. | |
typedef std::unique_ptr < CommandLineModuleGroupData > | gmx::CommandLineModuleGroupDataPointer |
Smart pointer type for managing a CommandLineModuleGroup. | |
typedef std::vector < CommandLineModuleGroupDataPointer > | gmx::CommandLineModuleGroupList |
Container type for keeping a list of module groups. | |
typedef std::unique_ptr < IExecutableEnvironment > | gmx::ExecutableEnvironmentPointer |
Shorthand for a smart pointer to IExecutableEnvironment. | |
Enumerations | |
enum | { etINT, etINT64, etREAL, etTIME, etSTR, etBOOL, etRVEC, etENUM, etNR } |
Command line argument type. More... | |
Functions | |
CommandLineProgramContext & | gmx::initForCommandLine (int *argc, char ***argv) |
Initializes the GROMACS library for command-line use. More... | |
void | gmx::finalizeForCommandLine () |
Deinitializes the GROMACS library after initForCommandLine(). More... | |
void | gmx::writeCommandLineHelpCMain (const CommandLineHelpContext &context, const char *name, int(*mainFunction)(int argc, char *argv[])) |
Helper to implement ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args(). More... | |
virtual std::filesystem::path | gmx::IExecutableEnvironment::getWorkingDirectory () const =0 |
Returns the working directory when the program was launched. | |
virtual std::vector < std::filesystem::path > | gmx::IExecutableEnvironment::getExecutablePaths () const =0 |
Returns list of paths where executables are searched for. More... | |
gmx::CommandLineProgramContext::CommandLineProgramContext () | |
Constructs an empty context object. More... | |
gmx::CommandLineProgramContext::CommandLineProgramContext (const char *binaryName) | |
Initializes a program context object with binary name only. More... | |
gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[]) | |
Initializes a program context object based on command line. More... | |
gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[], ExecutableEnvironmentPointer env) | |
Initializes a program context object based on command line. More... | |
void | gmx::CommandLineProgramContext::setDisplayName (const std::string &name) |
Sets a display name for the binary. More... | |
const char * | gmx::CommandLineProgramContext::programName () const override |
Returns the name of the binary as it was invoked without any path. More... | |
const char * | gmx::CommandLineProgramContext::displayName () const override |
Returns a display name of the current module. More... | |
std::filesystem::path | gmx::CommandLineProgramContext::fullBinaryPath () const override |
Returns the full path of the running binary. More... | |
InstallationPrefixInfo | gmx::CommandLineProgramContext::installationPrefix () const override |
Returns the installation prefix (for finding GROMACS data files). More... | |
const char * | gmx::CommandLineProgramContext::commandLine () const override |
Returns the full command line used to invoke the binary. More... | |
const char * | opt2fn (const char *opt, int nfile, const t_filenm fnm[]) |
Returns the filename belonging to cmd-line option opt, or NULL when no such option. | |
gmx::ArrayRef< const std::string > | opt2fns (const char *opt, int nfile, const t_filenm fnm[]) |
Returns the filenames belonging to cmd-line option opt. More... | |
gmx::ArrayRef< const std::string > | opt2fnsIfOptionSet (const char *opt, int nfile, const t_filenm fnm[]) |
Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set. More... | |
const char * | ftp2fn (int ftp, int nfile, const t_filenm fnm[]) |
Returns the first file name with type ftp, or NULL when none found. | |
gmx::ArrayRef< const std::string > | ftp2fns (int ftp, int nfile, const t_filenm fnm[]) |
Returns the filenames for the first option with type ftp. More... | |
bool | ftp2bSet (int ftp, int nfile, const t_filenm fnm[]) |
Returns TRUE when this file type has been found on the cmd-line. | |
bool | opt2bSet (const char *opt, int nfile, const t_filenm fnm[]) |
Returns TRUE when this option has been found on the cmd-line. | |
const char * | opt2fn_null (const char *opt, int nfile, const t_filenm fnm[]) |
DEPRECATED Returns the file name belonging top cmd-line option opt, or NULL when no such option. More... | |
std::optional < std::filesystem::path > | opt2path_optional (const char *opt, int nfile, const t_filenm fnm[]) |
Returns the file name belonging top cmd-line option opt, or std::nullopt when no such option. More... | |
const char * | ftp2fn_null (int ftp, int nfile, const t_filenm fnm[]) |
DEPRECATED Returns the first file name with type ftp, or NULL when none found. More... | |
std::optional < std::filesystem::path > | ftp2path_optional (int ftp, int nfile, const t_filenm fnm[]) |
Returns the first file name with type ftp, or std::nullopt when none found. More... | |
bool | is_optional (const t_filenm *fnm) |
Returns whether or not this filenm is optional. | |
bool | is_output (const t_filenm *fnm) |
Returns whether or not this filenm is output. | |
bool | is_set (const t_filenm *fnm) |
Returns whether or not this filenm is set. | |
bool | hasSuffixFromNoAppend (std::string_view filename) |
Return whether filename might have been produced by mdrun -noappend. More... | |
int | add_suffix_to_output_names (t_filenm *fnm, int nfile, const char *suffix) |
When we do checkpointing, this routine is called to check for previous output files and append a '.partNNNN' suffix before the (output) file extensions. If there was already a '.partNNNN' suffix before the file extension, that is removed before the new suffix is added. | |
int | nenum (const char *const enumc[]) |
Returns ordinal number for an etENUM argument. More... | |
int | opt2parg_int (const char *option, int nparg, t_pargs pa[]) |
Returns value of an etINT option. More... | |
bool | opt2parg_bool (const char *option, int nparg, t_pargs pa[]) |
Returns value of an etBOOL option. More... | |
real | opt2parg_real (const char *option, int nparg, t_pargs pa[]) |
Returns value of an etREAL/etTIME option. More... | |
const char * | opt2parg_str (const char *option, int nparg, t_pargs pa[]) |
Returns value of an etSTR option. More... | |
const char * | opt2parg_enum (const char *option, int nparg, t_pargs pa[]) |
Returns value of an etENUM option. More... | |
bool | opt2parg_bSet (const char *option, int nparg, const t_pargs *pa) |
Returns whether an argument has been set. More... | |
bool | parse_common_args (int *argc, char *argv[], unsigned long Flags, int nfile, t_filenm fnm[], int npargs, t_pargs *pa, int ndesc, const char **desc, int nbugs, const char **bugs, gmx_output_env_t **oenv) |
Parse command-line arguments. More... | |
Directories | |
directory | commandline |
Command Line Program Management (commandline) | |
directory | tests |
Unit tests for Command Line Program Management (commandline). | |
Files | |
file | cmdlinehelpcontext.h |
Declares gmx::CommandLineHelpContext. | |
file | cmdlinehelpwriter.h |
Declares gmx::CommandLineHelpWriter. | |
file | cmdlineinit.h |
Declares functions for initializing the GROMACS library for command line use. | |
file | cmdlinemodule.h |
Declares gmx::ICommandLineModule and supporting classes. | |
file | cmdlinemodulemanager.h |
Declares gmx::CommandLineModuleManager. | |
file | cmdlineoptionsmodule.h |
Declares gmx::ICommandLineOptionsModule and supporting routines. | |
file | cmdlineparser.h |
Declares gmx::CommandLineParser. | |
file | cmdlineprogramcontext.h |
Declares gmx::CommandLineProgramContext. | |
file | filenm.h |
Declares t_filenm for old-style command-line parsing of file name options. | |
file | pargs.h |
Declares t_pargs , parse_common_args() and related methods. | |
file | viewit.h |
Provides function to open output files automatically (with some X11 programs). | |
#define PCA_CAN_BEGIN (1 << 6) |
Add option to set begin time for trajectory reading.
#define PCA_CAN_DT (1 << 14) |
Add option to set time step for trajectory reading.
#define PCA_CAN_END (1 << 7) |
Add option to set end time for trajectory reading.
#define PCA_CAN_SET_DEFFNM (1 << 10) |
Add option -deffnm to set default for all file options.
#define PCA_CAN_TIME (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT) |
Add all options for trajectory time control.
#define PCA_CAN_VIEW (1 << 5) |
Add option -w to view output files (must be implemented in program).
#define PCA_NOEXIT_ON_ARGS (1 << 11) |
Do not raise a fatal error when invalid options are encountered.
#define PCA_TIME_UNIT (1 << 15) |
Add option -tu to set time unit for output.
anonymous enum |
Command line argument type.
|
overridevirtual |
Returns the full command line used to invoke the binary.
Does not throw.
Implements gmx::IProgramContext.
gmx::CommandLineProgramContext::CommandLineProgramContext | ( | ) |
Constructs an empty context object.
All methods in the constructed object return dummy values.
|
explicit |
Initializes a program context object with binary name only.
[in] | binaryName | Name of the binary. |
This is needed for unit testing purposes. The constructed object works as if the command line consisted of only of the binary name.
gmx::CommandLineProgramContext::CommandLineProgramContext | ( | int | argc, |
const char *const | argv[] | ||
) |
gmx::CommandLineProgramContext::CommandLineProgramContext | ( | int | argc, |
const char *const | argv[], | ||
ExecutableEnvironmentPointer | env | ||
) |
Initializes a program context object based on command line.
[in] | argc | argc value passed to main(). |
[in] | argv | argv array passed to main(). |
[in] | env | Customizes the way the binary name is handled. |
This overload allows one to customize the way the binary is located by providing a custom IExecutableEnvironment implementation. This is mainly useful for testing purposes to make it possible to test different paths without setting environment variables, changing the working directory or doing other process-wide operations. It may also be useful for making Gromacs behave better when linked into a non-Gromacs executable (with possible extensions in IExecutableEnvironment).
|
overridevirtual |
Returns a display name of the current module.
The returned value equals programName(), unless a separate display name has been set with setDisplayName().
Does not throw.
Implements gmx::IProgramContext.
void gmx::finalizeForCommandLine | ( | ) |
Deinitializes the GROMACS library after initForCommandLine().
Calls gmx::finalize() and additionally undoes the work done by initForCommandLine().
const char* ftp2fn_null | ( | int | ftp, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
DEPRECATED Returns the first file name with type ftp, or NULL when none found.
Also return NULL when ftp is optional and option is not set.
gmx::ArrayRef<const std::string> ftp2fns | ( | int | ftp, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
Returns the filenames for the first option with type ftp.
An assertion will fail when when none found.
std::optional<std::filesystem::path> ftp2path_optional | ( | int | ftp, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
Returns the first file name with type ftp, or std::nullopt when none found.
Also return std::nullopt when ftp is optional and option is not set.
|
overridevirtual |
Returns the full path of the running binary.
std::bad_alloc | if out of memory. |
Returns argv[0] if there was an error in finding the absolute path.
Implements gmx::IProgramContext.
|
pure virtual |
Returns list of paths where executables are searched for.
The returned list should be in priority order. An empty string in the returned list corresponds to getWorkindDirectory().
bool hasSuffixFromNoAppend | ( | std::string_view | filename | ) |
Return whether filename
might have been produced by mdrun -noappend.
If so, it must match "prefix.partNNNN.extension", for four decimal digits N and non-empty prefix and extension.
CommandLineProgramContext & gmx::initForCommandLine | ( | int * | argc, |
char *** | argv | ||
) |
Initializes the GROMACS library for command-line use.
This function is tailored for use in command line applications. For other usage, combination of gmx::init() and gmx::setProgramContext() provides more flexible initialization alternatives. Unlike gmx::init(), calls to this method cannot be nested.
The command line arguments are communicated so that they can be parsed on each processor. argc
and argv
are passed to gmx::init(); see there for additional discussion. This method does not place any additional limitations, but generally there should be no need to pass NULL values.
Does not throw. Terminates the program on out-of-memory error.
This method is not thread-safe, since it is intended to be the first method called. See setProgramContext() for additional discussion.
|
overridevirtual |
Returns the installation prefix (for finding GROMACS data files).
std::bad_alloc | if out of memory. |
Returns a hardcoded path set during configuration time if there is an error in finding the library data files.
Implements gmx::IProgramContext.
int nenum | ( | const char *const | enumc[] | ) |
Returns ordinal number for an etENUM argument.
[in] | enumc | Array passed to t_pargs for an etENUM argument. |
See t_pargs::u::c for the expected format of the array, including how the first element should be initialized. Note that the return value starts at one instead of zero: if the first enum value is selected, this returns 1.
const char* opt2fn_null | ( | const char * | opt, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
DEPRECATED Returns the file name belonging top cmd-line option opt, or NULL when no such option.
Also return NULL when opt is optional and option is not set.
gmx::ArrayRef<const std::string> opt2fns | ( | const char * | opt, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
Returns the filenames belonging to cmd-line option opt.
An assertion will fail when the option does not exist.
gmx::ArrayRef<const std::string> opt2fnsIfOptionSet | ( | const char * | opt, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set.
An assertion will fail when the option does not exist.
bool opt2parg_bool | ( | const char * | option, |
int | nparg, | ||
t_pargs | pa[] | ||
) |
Returns value of an etBOOL option.
[in] | option | Name of etBOOL argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
bool opt2parg_bSet | ( | const char * | option, |
int | nparg, | ||
const t_pargs * | pa | ||
) |
Returns whether an argument has been set.
[in] | option | Name of argument to check. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
true
if option
has been set.option
must specify a valid argument in pa
.
const char* opt2parg_enum | ( | const char * | option, |
int | nparg, | ||
t_pargs | pa[] | ||
) |
Returns value of an etENUM option.
[in] | option | Name of etENUM argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
int opt2parg_int | ( | const char * | option, |
int | nparg, | ||
t_pargs | pa[] | ||
) |
Returns value of an etINT option.
[in] | option | Name of etINT argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
Returns value of an etREAL/etTIME option.
[in] | option | Name of etREAL/etTIME argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
const char* opt2parg_str | ( | const char * | option, |
int | nparg, | ||
t_pargs | pa[] | ||
) |
Returns value of an etSTR option.
[in] | option | Name of etSTR argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
std::optional<std::filesystem::path> opt2path_optional | ( | const char * | opt, |
int | nfile, | ||
const t_filenm | fnm[] | ||
) |
Returns the file name belonging top cmd-line option opt, or std::nullopt when no such option.
Also return std::nullopt when opt is optional and option is not set.
bool parse_common_args | ( | int * | argc, |
char * | argv[], | ||
unsigned long | Flags, | ||
int | nfile, | ||
t_filenm | fnm[], | ||
int | npargs, | ||
t_pargs * | pa, | ||
int | ndesc, | ||
const char ** | desc, | ||
int | nbugs, | ||
const char ** | bugs, | ||
gmx_output_env_t ** | oenv | ||
) |
Parse command-line arguments.
Some common default arguments are also recognized in addition to those provided through pa
. The set of recognized default arguments is affected by Flags
.
Recognized arguments are removed from the list.
For full functionality, this function needs to be used within a function that is passed to gmx_run_cmain(). It should be called as the first thing in that function. Initialization code can be executed before it, but you need to be aware that if the program is executed with -h and MPI, the code before parse_common_args() only executes on the main node.
If the return value is FALSE
, the program should return immediately (this is necessary for -h and a few other cases).
|
overridevirtual |
Returns the name of the binary as it was invoked without any path.
Does not throw.
Implements gmx::IProgramContext.
void gmx::CommandLineProgramContext::setDisplayName | ( | const std::string & | name | ) |
Sets a display name for the binary.
std::bad_alloc | if out of memory. |
This is used with the wrapper binary to add the name of the invoked module to the name of the binary shown.
It is not threadsafe if there are concurrent calls to displayName() before this method has returned. Thread safety is not required for the normal initialization sequence of command line programs; it is called in the wrapper binary before the control passes to the actual module which may create threads.
void gmx::writeCommandLineHelpCMain | ( | const CommandLineHelpContext & | context, |
const char * | name, | ||
int(*)(int argc, char *argv[]) | mainFunction | ||
) |
Helper to implement ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args().
[in] | context | Context object for writing the help. |
[in] | name | Name of the module. |
[in] | mainFunction | C-like main() function that calls parse_common_args(). |