In general, a statement in CNS can be a control statement or an application statement. A control statement allows structured control of the sequence of application statements, such as loops, and conditional tests. It also allows switching the input stream to another file, opening and closing files, and various other operations. Control statements form the basis of the CNS scripting language and are as follows:

A condition takes the form:

( word = | # | > | < | GE | LE word )

A condition is true if the first word is equal to, not equal to, greater than, less than, greater than or equal to, or less than or equal to the second word, respectively.

A basic loop takes the form:

LOOP label { [EXIT label] } END LOOP label

The label is a string with up to four characters. The EXIT statement allows jumping out of the specified loop (and should be part of a conditional statement). Loops may be nested.

Example: A Conditional Test

This example either divides or multiplies the symbol $1 by a factor of two, depending on the value of the NOE energy ($NOE). In the first case, 40 steps of minimization are carried out, whereas in the latter case, 100 steps of minimization are carried out. Note that the indentation is arbitrary but can make the input file more readable.

if ($NOE > 10.0) then 
   evaluate ($1=$1/2.0) 
   minimize powell 
     nstep=40 
   end 
else 
   evaluate ($1=$1*2.0) 
   minimize powell 
     nstep=100 
   end 
end if
Example: A Simple Loop

The following example writes the characters a, b, c, d, and e to the file called testing.dat (the case is preserved).

set display=testing.dat end 
for $1 in ( a b c d e ) loop main 
   display  $1 
end loop main
Example: A Double Loop with Exit Condition

The conditional statement forces exit from both loops if the condition is satisfied.

for $1 in ( a b c d e ) loop m1 
  while ($2 > 10.0 ) loop m2 
     if ($3>1000.0) then  exit  m1  end if 
     evaluate ($2=$2-1.0) 
  end loop m2 
end loop m1
Example: Switch Control to Another File

Suppose the file called "mini.str" contains the following statements:

minimize powell 
   nstep=40.0 
end

One can then include the contents of this file in another file by specifying the "@" statement; e.g.,

@mini.str

is equivalent to

minimize powell 
   nstep=40.0 
end
Example: Switch Control to Another File within Loops

When CNS executes loops, it stores all input information in internal buffers. This may not be desirable if one wants to loop through several files. To do this, one should use the "@@" statement. In the following example, four coordinate files are rms-compared to a set of reference coordinates:

coordinate disposition=comp @reference.pdb 

for $1 in ( "coor1.pdb" "coor2.pdb" "coor3.pdb" "coor4.pdb" ) loop main 
   coordinate @@$1 
   coordinate rms end 
end loop main
Symbols

A symbol is a word with a "$" as the first character. It is replaced by another word that has been assigned by the user or by CNS during program execution. Symbols can be assigned an arbitrary value and manipulated by the evaluate statement and several control statements. The data type can be real, string, logical or complex and is assigned automatically by the program. The name of the symbol is a string that qualifies as a word with fewer than 20 characters. Symbols can also be compound, that is sublevels are delimited by a point (eg. $number.1 $number.2 $number.total). CNS internally declares particular symbols when certain statements are executed. Here are a few examples:

Example

In the following example, a symbol $weight is declared. Note that CNS automatically determines the type of the symbol. This symbol is used in the subsequent statements. The third statement declares a symbol $root_weight.

  evaluate ($weight=3.40+433^2) 

  xray wa=$weight end 

  evaluate ($root_weight=sqrt($weight))

In the next line, the symbol $root_weight is redeclared as a character string.

  evaluate ($root_weight="testing 1 2 3")

As a consequence of this statement, $EXIST_root_weight is set to logical true.

Here, the compound symbols $total.number, $total.1 and $total.2 are declared as real.

  evaluate ($total.number=10)
  evaluate ($total.1=230)
  evaluate ($total.2=178)
Parameters

Parameters are assigned with the define statement. The named parameter is assigned the string verbatim after symbol substitution. The string can extend over many lines (these linebreaks will be inserted into the parameter). A parameter can be referenced using an ampersand (eg. ¶meter). Parameters cannot be modified, they however can be overwritten by a new define statement. Parameter names can be a maximum of 80 characters.

Examples

A parameter named weight is assigned the value 10:

  define ( weight=10; )

A parameter named comment is assigned a string value:

  define ( comment="this is a text comment
                    that goes over more than one line"; )

Two parameters are assigned in the same define statement:

  define ( weight=10; 
           comment="this is a text comment
                    that goes over more than one line"; )

The parameter weight is used in:

  define ( weight=10; )
  evaluate ( $new_weight= &weight * 30.0 )
  xray
    wa = &weight
  end
Modules and procedures

Modules and procedures are mechanisms to isolate common tasks in a well defined way such they can be readily used by several task files. They are analogous to subroutines or functions in lower-level programming languages such as FORTRAN or C (although the syntax and specifics differ).

Modules: reside in separate text files and are called using the stream redirection facility in CNS.

  @getweight ( selected=(residue 10:60);
               fixed=(residue 45);
               wa=wa_new; )

The module file itself begins with the declaration of the expected parameters. The declaration may define defaults for the parameters (in the case that they are not passed when the module is called). The module is called with the appropriate parameters (see above):

module {getweight}
(
  &selected=(all);
  &fixed=(none);
  &wa=$wa_temp;
)

In the body of the module an reference to a passed parameter (eg. &selected) will be substituted with the value of the parameter from the module invocation. In this case any instance of &selected would be substituted with (residue 10:60). Modules have scope, that is, when a module is called any symbols created in the module have a new scope.

Procedures: are defined within the body of a CNS task file (or can be kept in a separate library file which is read by the task file upon start up). Procedures are very similar to modules expect that they are defined and invoked from the level of the task file. The procedure declaration again defines the expected parameters:

procedure set_target (target_label)
  if     (&target_label="f2f2") then
    display set_target: target defined to be f2f2
  else
    display set_target: fatal error: unsupported target_label.
    abort
  end if
endprocedure

The procedure is then called using the call statement:

  call set_target (target_label=&pc_target;)

As with modules the parameters in the body of the procedure definition are substituted by the passed parameter values. A new scope level is used for the procedure.

Wildcards

Another special case of a word is a wildcard which can take the following forms:

* | % | # | +

where

Example

The following atom selection selects all atoms that contain a "C" in their names at any position:

 ( name *C* )
Filenames

A filename is any sequence of nonblank characters enclosed by spaces. In particular, the filename may contain one-character words, and it is case sensitive.

Example

The following statements assign the specified files to the DISPlay unit:

 set display=display.list end 

 set display=/home/sub/testing.test end

On all UNIX and Windows systems, CNS provides the feature of environmental variables. Suppose the user has defined a UNIX variable MYDIR in his/her ".cshrc" file.

  setenv MYDIR  /home/paul/project

Then it is possible to access a file "coordinates.pdb" in the directory "/home/paul/project" in CNS by specifying the filename "MYDIR:coordinates.pdb", e.g., if the user wants to set the DISPLay file,

  set display= MYDIR:coordinates.pdb

The same feature can be used on Windows systems:

  set MYDIR=C:\Paul\Project
Set Statement

The set statement allows one to change certain parameters that control CNS program execution and output. The following is a list of the available statements:

Evaluate Statement

The evaluate statement allows one to carry out manipulations of symbols together with literal or numerical constants:

  evaluate ( symbol = operation )

Where operation is:

  function|symbol|real|integer|string [ op operation ]

and op is:

The data types of the operations and operands have to match; otherwise an error message is issued. The available functions, such as SIN, COS, and TAN, are the same as those for atomic manipulations (see other documentation pages).

Example

The statement

evaluate ($1=1.0)

sets the symbol $1 to 1.0, whereas

evaluate ($1=$1+2.2)

increases it by 2.2,

evaluate ($1=$1*cos(2.*$pi$1))

sets it to 3.00498, and

evaluate ($2="a"+"b"+encode($1))

sets the symbol $2 to the string "ab3.00498".

Back to tutorials   Next section