The Command-line Calculator:

        Spock also has a built in calculator capable of evaluating complicated expressions. The calculator is invoked by having ``#'' as the first character on a line. The simplest use of the calculator is simply by entering an expression. The command #1+1 will print--you guessed it--Result: 2. Users can also define variables in the calculator. For example # i=1 defines i to be 1. Subsequently, i may be used in calculations, e.g. # i*3 + i will evaluate that expression using the current value of i, and print the result (which is left as an exercise to the reader). The calculator also knows about lots of mathematical functions: sin, cos, tan, asin, acos, atan, sinh, cosh, abs, sgn, sqrt, exp, log10, log, and even--God save us--the Bessel functions besj0, besj1, besy0 and besy1, so commands like #sin(1) are permitted. Users can also define their own functions, e.g. #f(x)=sin(x)+cos(x)/3. This function may later be called e.g. #f(2.3) will evaluate sin(2.3)+cos(2.3)/3.

Most importantly, the function calculator has access to spock's atom and vertex property variables: q (charge), sa (surface area), d (distance), p (potential), ap1, ap2 (atom properties 1 and 2), dpartner (distance partner), vp (vertex potential), vd (vertex distance), vp1 and vp2 (vertex properties 1 and 2). The vertex properties are indexed by atom or vertex number, so the simple command #q(1) will print the charge property for the first atom. Similarly, the command #q(1)=ap1(1) + d(1) will assign the appropriate value to the charge for the first atom. This provides an additional (more powerful) way to alter atom and vertex properties, distinct from the set-style commands, like set charge=1, described in §5.2.4. If no atoms or vertices are defined, attempting to use their associated properties will generate an error.   It is also possible to operate on the entire array of atom or vertex properties. For instance, to set all atom distance properties to 0, one could use the command #d()=0.0. The ``()'' pair with no index indicates that this command is to operate on the entire array, rather than just a specified element of it. More complicated assignments of this type are possible, for instance: ap1()=exp(sin(ap2()) + cos(d()) + besj0(q())). If there is an invalid calculation (e.g. #log(0)), spock will print an error message, and the atom/vertex number of the offending command. Atom or vertex properties prior to the one on specified in the error message have been altered.

Users may define new functions in terms of the atom properties for later use. For instance #f(x)=ap1(x) + ap2(x) defines the new function f. Later, a command such as: q()=f() will use the previous definition of f(x). Finally, a parenthesis pair by itself stands for the index number. For instance q()=() will assign q=1 for the first atom, q=2 for the second atom, and so on.   Much of the functionality of the Calculate Properties math menu (§6.6.2) is accessible via the command line calculator, specifically the ability to add, subtract, multiply and divide properties, or add a constant, etc. One important difference between the command line-calculator and the Properties math menu is that operations entered via the command line calculator apply to all atoms or vertices, while in the Properties math menu operations only apply to the atoms/vertices specified via the ``Enter new selection string'' menu option. Look on the Properties math as a complement to, not a replacement of, the command line calculator. In the Properties math menu, there is an entry ``Apply a function''. This entry prompts for a command which is passed to the command-line calculator (no leading ``#'' is necessary). Unlike calculations entered directly from the command line, the selection string is applied, so calculations are performed only on the selected atoms/vertices.   The ``Use DP's property two'' option of the Properties math menu may be duplicated on the command via a command of the type: ap1()=ap2(dpartner()), which, in this example would set ap1 for each atom to the ap2 of that atom's distance partner. When the dpartner property is included in a calculation, entries for which the dpartner is undefined (0) are skipped.   The command-line calculator also has access to the electrostatic potential maps (phimap1 and phimap2) and the electron density maps (emap1 through emap8). The maps are treated as single dimensional arrays, so if you want to access a particular element you'll have to calculate the offset to it. However, spock can easily operate on the entire map via the ``()'' operator. For instance, to scale a map, you could use the command #emap1()=emap1()/5.0. You can also add and subtract maps in this manner. One caveat is that the map must already be defined before it can be used in the command line calculator. If only one density map is read in, the command #emap2()=emap1() will not work. Of course, to operate on more than one map, they must be of equal size. The calculator also understands any environment variables specified, so you could scale a map via the command #emap1()=emap1()/$SP_SD. (Recall that the ``Simple statistics'' option of the ``Calculate properties math'' menu sets several environment variables when it's used to calculate statistics on a property or map. See § 6.6.2).

There are a few commands that may be passed to the calculator besides arithmetic expressions:

 
• #show functions: Lists current user-defined functions, as well as the available atom and vertex properties, (referred to as program arrays) in the list.      
• #show variables: Lists current user-defined variables, and their current values.    
• #show angles: indicates if the arguments to and results of trig functions (sin, cos, etc.) are interpreted as radians or degrees.      
• #set angles <degrees|radians>: tells trig functions to use radians or degrees.

 

Calculator Variables:

    Finally, it's possible to access variables used by the command line calculator in other contexts. For example, if you've defined the variable i with a command like #i=32, you may use this variable in other commands, by preceding it with a hash mark ``#''. For example, the command bc=d,rn=#i would work exactly the same as the command bc=d,rn=32. Other, more complicated uses of calculator variables are, of course, possible. Note that there is a difference between calculator variables (e.g. #i) and environment variables (e.g. $i). Each each of these may exist and even have separate values! Environment variables (§5.2.5) are exported to sub-processes, but calculator variables are not. Environment variables are translated before commands are passed to the calculator. For example, if you have defined the environment variable $function with set $function=sin(x)+2, and then you issue the calculator command #f(x)=$function, the calculator will define the function f(x)=sin(x)+2. If you have an environment variable whose definition is a single number, it will be treated as such as well by the calculator; #5+$constant will print the sum of 5 and the value of $constant if it's defined. All this may seem confusing at first, but once you get the hang of it, it can be quite powerful. The important points to remember are:

• Environment variables are defined by a set command, or are imported from the parent shell. They are also exported to child processes. These variables are always preceded with a dollar sign $. These variables may be passed to the calculator, (e.g. #f=$total).    
• Calculator variables are defined only by a calculator command (e.g. #i=12). These variables are not exported to child processes, but they may be accessed from within spock by preceding them with a hash mark #, (e.g. rn=#i).
• The name space of environment variables and calculator variables does not overlap, which means that you may define two variables with the same name, one a calculator variable, and one an environment variable. They may have the same or different values.

Some useful examples of the use of math environment variables are:  

• #i=i+1; look,rn=#i This command will advance the view by a single amino acid. The command may be used repeatedly by pressing the up arrow and return in the command entry area. It may be useful to define a macro with this command, and call it ``pop''. To use this command, you must have first assigned a value to i with a command like i=5.
• #i=i-1; look,rn=#i This command will ``rewind'' the view by a single amino acid like above. It may be useful to define a macro with this command, and call it ``push''.