BTCL Commands and Utilities

BTCL commands are used to set up and control Discover simulation runs. Their use is more complicated than the usual BTCL procedures in that their arguments may be specified by position or by name--the actual format depending on the particular command. Here is a full list of BTCL commands in the Discover 95.0 program.

Most BTCL commands have named-argument parameters and the syntax:

command parameter_path_name = value parameter_path_name = value...

Here parameter_path_name is usually just the name of particular parameter, for example:

analysis method = mean_square_displacement subset = "he"

Some command parameters require that a keyword path be included to access a particular parameter, for example:

minimize cg method = polak cg convergence = 5.0 sd convergence = 400.0

Notice that the parameter name convergence is used twice, but, because of the path tree mechanism, cg convergence and newton convergence are different parameters. A path may consist of more than one keyword, for example:

forcefield nonbond coulomb cutoff = 3.4

The full pathname is not always required for parameters in the same path tree. For example, the following two examples are equivalent:

minimize newton method = truncated newton convergence = 0.05 newton line_s = 0.1

minimize newton method = truncated convergence = 0.05 line_search_precision = 0.1

All keywords are treated as path specifiers until an assignment operator = or the end of the command line is encountered. If the next word is not a path branch from (or parameter of) the current path, then the path is traversed backwards until the parameter name or path keyword is found. For example, the command:

forcefield scale nonbond use_cutoffs = True

does not produce an error and assigns a value to nonbond use_cutoffs even though no assignment was made at the scale path level.

Once all parameter setting has been processed from the command line, with no anomalous parameter names or values, the command (e.g., forcefield) is executed. Any parameters that were not set directly on the command line (or indirectly as a consequence) assume their default values.

It is possible to change the default parameters using the BTCL utility command cdlConfig. For example, the previous command could have been set up and performed by entering:

BTCL >   cdlConfig minimize newton method = truncated \
         convergence = 0.05 line_search_precision = 0.1 
 0.1

BTCL >   minimize

Notice that the cdlConfig command returns a value--actually the value of the last parameter that was set. Whenever a minimize command is invoked subsequently, the default values are the same as those set by the cdlConfig utility. Here, newton method takes the value truncated unless it is respecified for a command, for example:

minimize ... newton method = bfgs ...

or unless another cdlConfig command is used.

Some BTCL commands take positional arguments which are then mapped onto named parameters. The following command:

BTCL >   readFile archive frame = 5

reads an archive file into the system for frame number 5. Here, the keyword archive is actually an enum value for the readFile parameter filetype, even though the filetype parameter is not specified here by name. However, if you want to set the default for the filetype, the filetype parameter must be referenced by name. Thus, the equivalent cdlConfig statement would be:

BTCL >   cdlConfig filetype = archive frame = 5

BTCL >   readFile

cdlGather is a utility command that is complementary to cdlConfig. This command collects all the parameter names and their current default values together in one string, for example:

BTCL >   cdlGather begin
 begin coord = {} topol = {} forcef = {}

Its main use is for preserving the current default values of a command. It is particularly useful in procedures and can also be used to store the current default parameters for a particular parameter path, for example:

BTCL >   set Newton [cdlGather minimize newton]

BTCL >   cdlConfig minimize newton method = bfgs ...

...

BTCL >   cdlConfig $Newton

To reset a command to its original default settings, you can use the BTCL utility cdlSetDefaults, for example:

cdlSetDefaults minimize

To view the current default setting for a particular BTCL command parameter, you can use the BTCL utility cdlFetch. Unlike cdlConfig and the BTCL commands themselves, cdlFetch operates only on a single parameter path and has the general syntax:

cdlFetch target parameter_path_name

Here, the target argument can be one of several keywords, the most useful of which is value, which retrieves the current default value, for example:

BTCL >   cdlFetch value minimize newton method
 truncated

Main access page

Advanced-Use access.

BTCL Language access Procedures Command Parameter Types