Sb intro1

Starting up CHARMM
While you can run CHARMM interactively, one usually tells the program what to do by means of a script. Under Unix (at least for non-parallel versions of the program), this means that in order to execute a (short) CHARMM run, one runs from the command line (Unix Shell prompt)

charmm_executable < charmm_input_script.inp

exploiting input redirection available under all Unix shells. (TODO: what about other OS (Windows, OSX ?), explain non-parallel remark. Possibly should state somewhere that tutorial assumes Unix/Linux??). Since as we shall see shortly CHARMM output tends to be verbose, one normally also redirects the output, thus ending up with

charmm_executable < charmm_input_script.inp > charmm_output_file.out

Of course, instead of charmm_executable use the filename starting up CHARMM at your location and replace charmm_input_script.inp and charmm_output_file.out by the names of the actual script/output file which you want to try out / to which you want to save your output.

Titles
First, let's do something really silly and start up charmm reading from an empty file; which can be easily accomplished by executing

charmm_executable < /dev/null

CHARMM prints a header telling you copyright info, version and some more stuff, followed by a warning

RDTITL> No title read. ***** LEVEL 1 WARNING FROM  ***** ***** Title expected. ******************************************     BOMLEV (  0) IS NOT REACHED. WRNLEV IS 5

The job finishes by printing some status info. The interesting part is the warning from which we learn that CHARMM expected a "title". Indeed, each CHARMM script should start with a title, and if the main script tells CHARMM to read from another file, the program also expects to find a title at the beginning of that file.

A title should not be confused with comments. E.g., it can only occur at the beginning of a file (and we'll explain the apparent exceptions when we encounter them). Title lines start with a star * (up to 32); to indicate the end of the title give a line containing only a star. Thus,

* This would be a short title *

If you start CHARMM with a short file containing the above snippet (=title), you get the title echoed in uppercase letters

RDTITL> * THIS WOULD BE A SHORT TITLE RDTITL> *

instead of the warning when using the empty file.

Comments
Having blabbered so much about titles, what are comments: A comment in a CHARMM script is everything following an exclamation mark ! I.e.,

! this is a comment on a line by itself

and this would be a line containing a CHARMM command, followed by a comment

ENERgy ! as you might expect, this command calculates an energy

Ending a CHARMM script
So far, CHARMM finished when it reached the end of the script file (as the line

NORMAL TERMINATION BY END OF FILE

in the output informs you. It's OK to end a CHARMM script in this manner, but the preferred way of stopping CHARMM is by issuing the

stop

command. We, thus, can create a first, completely useless CHARMM script, looking like

* A CHARMM script doing nothing * ! we really should be doing something, but in the meantime all we know is stop

In addition to the title, the comment is echoed as well. Note that CHARMM now prints upon finishing

NORMAL TERMINATION BY NORMAL STOP

Command line parameters, @variables
As we shall see, the CHARMM language to write scripts contains all the elements of a( imperative) programming language (even though it is not an extremely comfortable one). One key element of a programming language is the ability to set and manipulate variables. In the context of running CHARMM, it is extremely useful to pass certain variables into the program from the outside. Run the following miniscript (we name it title2.inp) * Example of passing a variable from the command line * The variable myvalue was initialized to @myvalue * stop by executing

charmm_executable myvalue=500 < title2.inp

and study the output (you could also state myvalue:500): Before the title is echoed, you see that an argument was passed

Processing passed argument "myvalue:500" Parameter: MYVALUE <- "500"

and in the echoing of the title, @myvalue is replaced by the value assigned to the variable myvalue, i.e., 500 in our case. The little example highlights something to keep in mind. The first thing that is done when a line in a script (containing a title or a command) is parsed, is to scan for @variables, which are then replaced by their value (no variable replacement is done in comments!). The following line is an excerpt from the command to run molecular dynamics (MD)

DYNAmics STEP @nstep ! etc.

By executing the script containing this line (we assume its name to be run_dyna.inp) as

charmm_executable nstep:10 < run_dyna.inp > run_dyna.out we would carry out 10 steps of MD. If we specified nstep:1000000, we would carry out a million MD steps.

Obviously, one can also set variables in a script itself and manipulate them as well as calculate with them ; however, before we show some simple examples, we need a way to see the result of the calculations/manipulations. Unfortunately, there is no generic I/O facility in CHARMM, so the simple task of printing/"echoing" the value of parameters to the output is a bit awkward. The trick consists in creating a title on the fly and writing this to standard output. In Unix, standard output is associated with fileunit 6, and so we are going to write our title to unit 6. Please accept the following for the moment; more on input / output is to come shortly. Look at the following code snippet

writ title unit 6
 * some title on the fly
 * which may contain @variable values which will be substituded

The writ title command expects that a title follows, on which normal command line substitution is carried out. This title will be written to the specified unit, in the above example standard output, i.e., it gets merged into the normal CHARMM output. Consider the following example (which we name title3.inp)

* Example of passing a variable from the command line * The variable myvalue was initialized to @myvalue * ! we now set a second variable ourselves set 2value 100 ! and check that we can use it write title unit 6 * checking values of variables * myvalue : @myvalue * 2value : @2value stop

Run it as

charmm_executable myvalue:500 < title3.inp

and observe the output. You see that the title lines following the write title appear twice; once, as in the beginning of the script following the RDTITL> * string, and a second time all by themselves, without leading *. (BTW: try replacing unit 6 by, e.g., unit 51</tt>. You should notice that the lines

CHECKING VALUES OF VARIABLES MYVALUE : 500 2VALUE : 100

are now missing from the output, but you will find a new file named fort.51</tt> (or something similar), which contains exactly these three lines. Again, we'll return the question of how to give this file a more memorizable name shortly.)

Manipulating variables
Based on the framework of title3.inp we can now illustrate how variables can be manipulated. Please try the following examples and make sure that you understand what's going on:

varmanip1.inp:

* First example of manipulating variables * ! set a variable set value 100 ! and check its value write title unit 6 *checking values of variables *value : @value ! now increment it by one incr value by 1 ! and check its value write title unit 6 *checking values of variables *value : @value stop

A note on ?variables
For completeness sake, a preliminary comment on a second type of variable. Many CHARMM commands, aside from producing more or less direct output, place some key values in "internal" variables. E.g., the energy of a system calculated with the most recent ENER</tt> command is put into a variable named ener</tt>. To avoid name clashes with variables set by users, these value of these variables can be accessed by preceding the variable name by a question mark ?. I.e., if CHARMM encounters (in a title or in a command) the string ?ener</tt>, it will attept to replace it with the energy value from the most recent ENERgy</tt> command. This is quite handy, and we'll see many examples later on, once we reached the stage where we can use CHARMM to work with biomolecular systems.