| CDiscover |
Commands for calculation setup and analysis
Calculation setup is accomplished through the use of a number of auxiliary commands for input (begin, readFile, reset), output ( output, print, writeFile), and control (atomMovability, energyContribution, forcefield, restraint, pseudoAtom). Analysis commands (diffraction and vibrationalAnalysis) allow you to perform additional analysis of output results. The peek command can be used to monitor the progress of minimization and dynamics calculations.
Input commands
The BTCL commands begin, readFile, and reset all read information into the Discover program from external files. The begin command is generally placed at the start of a run_name.inp file to read in the molecular data files and a forcefield file. The readFile command is used to read in a data file created by a previous CDiscover, Cerius2, or Insight run (e.g., a coordinate snapshot from an archive file). It also allows you to work with multiple systems. The reset command is used to reread the molecular data files and forcefield. All information associated with the current molecular system (e.g., coordinates, energy expression) is lost with this command. However, the settings of command defaults (e.g., for dynamics) are unchanged.
Output commands
The output command specifies amount of output desired. The print command (which must be part of a minimize or dynamics command) generates output of system properties to various file types. The writeFile command is used to write a data file that can be read by subsequent CDiscover, Cerius2, or Insight runs.
Control commands
The atomMovability command allows you to fix the position of an atom or disregard its contribution to total energy throughout a calculation. The energyContribution command allows you to specify energy contributions of your own design. The forcefield command allows you to select a forcefield and tailor the contributions of built-in energy terms. The restraint command allows you to impose distance, torsion, or angle restraints of various forms on selected atoms. The pseudoAtom command allows you to create collections of atoms which are to be treated as individual atoms.
Exiting a BTCL session
If you want to end a BTCL session without starting a CDiscover run, enter exit, quit, or <Ctrl> d at the BTCL prompt.
Defining and using your own procedures
One of the most useful features of BTCL is that you can quickly define and use your own procedures (Btcl procedures). Procedures defined in files named filename and located in the current directory of the Discover run are automatically accessible. Procedures defined in any other files may be used by including:
source filenamein the run_name.inp file. Here, filename is the full path to the procedure-definition file.
If you would like to avoid dealing with geometric and mathematical details, a higher-level command (molGeom) allows you to work directly with models, monomers, atoms, and their relationships. molGeom employs some of the same performance enhancement techniques as geometry and vector. There is a bit more overhead involved in the use of molGeom, but its performance should be fine for most purposes. You will probably want to work first with molGeom, and employ the lower-level commands only as necessary. The molGeom command can be used to get and set geometric properties of models, such as the coordinates of atoms, bond lengths, bond angles, etc.
Databases
Information that is read into the Discover program is organized into databases for subsequent use. Each distinct molecular system resides in a separate database with the same name as the molecular system. You can make your own databases and perform various operations on them (or on the system databases) with the database command and database handle operations (see $dbHandle). The database command supports database creation, deletion, and other high-level operations. (Use of the database command to create or delete system databases is not recommended.) The database handle operations are an extension of the database command. They are used to access the data within a particular database.
Please see Databases and Tables for additional information on databases.
Objects
The object command is used to add information to or extract information from a BTCL object. A BTCL object is, in essence, a list of entries of arbitrary type. BTCL objects (of differing types) can be created with various commands, including object, vector, geometry, molGeom, database, database handle operations ($dbHandle), select, and subStructure. A BTCL object is deleted when the BTCL variable used to store its identity (or handle) is unset. As noted previously, objects are used to avoid processing burdensome amounts of data at the BTCL level. The object name is passed from BTCL to compiled code which deals with the underlying data.
Please see Databases and Tables for additional information on objects.
Given that these files exist, the Discover job can be started by several methods, depending on where you want its output to appear and the format of the command input file.
Initiating a run
Direct method
Enter the following at the UNIX prompt:
> discovery run_namewhere run_name is your name for the calculation.
The first line of the command input file run_name.inp must contain the line:
#BIOSYM dsl 3or (preferably):
#BIOSYM btcl 3which identifies it as a BTCL command input file for CDiscover.
The output from the calculations goes to the file run_name.out; and run_name.err contains messages from any serious errors that may have occurred.
> discoveryThe BTCL prompt appears, and you need to enter the following:
BTCL > set PROJECT run_name BTCL > source run_name.inpOutput from the calculations goes to standard output.
If you decide not to start a Discover run, you can end the BTCL session by entering exit, quit, or <Ctrl> d at the BTCL prompt.
> discovery < run_name.inpOutput from the calculations goes to standard output.
> discovery -mpi "-np N"where N is the number of processors.
To run CDiscover jobs submitted from the Insight program in parallel, set the environment variable MPI_ARGS to '-mpi "-np N"' before running CDiscover. This can be done with the Session/Env_var command in the Insight interface or via the UNIX shell before invoking the Insight program:
> setenv MPI_ARGS '-mpi "-np <N>"' > insightIIThe efficiency of parallel computation depends on the system size and the calculation method chosen. At present, moderate numbers of processors work best (e.g., 4 CPUs).
The script directory has been reorganized to include more example and gift scripts which demonstrate how to build scientific functionality with CDiscover.
A more complicated series of command statements is demonstrated in the file named $BIOSYM/gifts/discover/tcl/acenm.inp. (The file sets up a calculation that compares the results obtained with several different forcefields.) Since the filename in this example is acenm.inp, the molecular data are read from the files acenm.car and acenm.mdf, which must be present in the same directory as the acenm.inp file. These example input files can be also found in the directory $BIOSYM/gifts/discover/tcl. To test them, you need to first move to a directory in which you have write permission and copy the files by entering at the UNIX prompt:
> cp $BIOSYM/gifts/discover/tcl/acenm.* .A short example command input file
#BIOSYM btcl 3
begin
minimize \
iteration_limit = 20 \
newton method = newton_raphson \
execute \
frequency = 1 \
before = 1 \
after = 1 \
command = {
print output energy_summary = 1 \
internal_energy = 1 nonbond_energy = 1}
dynamics \
boltzmann = 1 \
time = 100.000000 \
timestep = 0.250000 \
ensemble = nvt \
execute \
frequency = {10 * 0.250000} \
command = {print output energy_summary = 1
state = 1}
dynamics \
time = 200.000000 \
timestep = 0.250000 \
ensemble = nve \
execute \
frequency = {10 * 0.250000} \
command = {print output energy_summary = 1
state = 1}
This file can be written entirely by hand, using any text editor, or a file from some previous run could be edited to produce this input file.Alternatively, the input file can be constructed using the Cerius2 or Insight interface to CDiscover.
These Cerius2·Discover control panels would be used to construct the above file:
The sample acenm.car and acenm.mdf files
The model in these files (in the $BIOSYM/gifts/discover/tcl directory) can also be constructed with the Cerius2 or Insight interface, by using the Builder facilities, followed by assigning forcefield atom types. Alternatively, model description files output by other software can be used, provided they have the appropriate formats, contents, and filename extensions.
Explanation of command input file
Setting up the computational
system
The first command to be executed is the begin command. This loads the molecular system having the specified name acenm (i.e., the files acenm.car and acenm.mdf). The begin command also opens and writes some initialization information to the default output file, acenm.out.
The minimize command assumes that minimization should be complete within 20 steps.
The dynamics command includes an execute subcommand to print energy information every 2.5 fs, as well as at the beginning and end of the dynamics run. This information is appended to the file acenm.out (which was opened earlier, by the begin command), although it is possible to specify some other filename.
Initiating the run
The commands contained in the acenm.inp file are executed by simply changing to the directory that contains the acenm.inp, acenm.car, and acenm.mdf files and entering, at the system prompt:
> discovery acenm
The readFile command may be used to read a particular frame of a history file into the CDiscover program. In this way a history file might be converted into an archive file, for instance, by using the writeFile archive command. The return value of the readFile command, when it is applied to a history or archive file, is the potential energy of that frame. This would allow you to, for instance, construct scripts that sort the frames in an archive or history file based on energy.
set esffOverrideParameters 1after the command:
beginin the input command file run_name.inp. With the edit option flag esffOverrideParameters now set to 1, only the parameters in the run_name.epa file are used. To use the default ESFF parameters to run the same molecular system once again, you need to reset the edit option flag esffOverrideParameters back to 0 by deleting the command line:
set esffOverrideParameters 1from the input command file run_name.inp.
This lesson assumes you are already familiar with using the Insight program.
| Copy the files helix.inp, helix.car, and helix.mdf from the directory $BIOSYM/tutorial/discover/ to a directory in which you have write permission |
2. Examining the command input file
| Read the command input file to understand it--the commands are associated with explanations in comment lines (starting with #). |
A few hints to understanding the script are:
Run CDiscover by entering at the UNIX prompt (indicated as >):
> discovery helixWait for the run to end. |
List the files in your working directory by entering:
> ls -lt |
Output files of the run should include helix.out, helix.cor, helix.arc, and helix.tbl
The lines for axis1 and axis2 show the centroid, (the first { } in each line) and the direction vector (the second { } in each line) of the axes. Note that axis1 and axis2 have the same direction, indicating that they are parallel after execution of the fixorientation procedure. The line distance is the distance between two lines, and the point distance is the distance between two centroids. These two distances are the same, indicating that the centroids are lined up perpendicular to both axes at the predefined distance apart.
The helix.cor file is the coordinate file written out after fixing the orientation. It should contain two helices parallel to each other and 10.0 Å apart.
Before doing this, you might also want to display the models in the helix.car file to show that the helices in the original file were randomly oriented.
8. Sorting the data to find the lowest-energy configurations
Use the Spreadsheet functionality to read in the helix.tbl file and then sort the energies in ascending order.
|
Select the Spreadsheet icon, then select the Open command from the list that appears. Set the following parameter values:
File Type = Graph File Name = helix.tbl Object Name = Sheet Select Execute. |
Grab a corner of the spreadsheet window with the cursor and enlarge it to have a clearer view.
9. Displaying the lowest-energy conformations
10. Applying what you have learned
| You could try writing your own script to reorient a three-helix system or a four-helix bundle. |
The BTCL language and its commands are documented in full in Btcl Language and Commands--Standalone Mode, where the commands are listed in alphabetical order. Below is a list of the BTCL commands according to their functions, followed by a brief description and the page on which the complete description starts.
Command Summary--Standalone Mode