The program currently runs on HP workstations. The graphics can be displayed on X-Windows terminals.

This version V1.0 is not stabilised yet, this distribution is still a beta version. This version is distributed under a licence. There is no fees for academic laboratories, however the licence requires that you refer to Crowd in any published work which depend in some manner on the Crowd program.

This program can be downloaded by anonymous FTP on Internet, the home site is the following address : ftp://tome.cbs.univ-montp1.fr/pub/crowd_v1.

*Availability of several motion models: isotropic-rigid, Lipari-Szabo, local correlation time models.

*Aptitude to read free-format coordinate files.

*Interactive commands for beginners as well as fast entry mode for advanced users

*Complete on-line HELP.

*Comprehensive manual.

*Versatile command parser which permits to build macro commands with alias, tests, local and global variables, loops, graphic interaction and display capabilities, support for data-bases and associative arrays.

*graphical interface completely modifiable and definable by the user.

*Possibility to run in interactive mode as well as Batch mode (display less).

*The operating system is fully available from Crowd.

Entering the program

You enter the program by typing crowd on your favourite system (don't panic, just type EXIT to get out of it!) . The program should give you a short greeting, the size of the static buffers, and then respond in the text window with the prompt :

Crowd>

The other method consists in hitting a button in the graphic interface. The graphic interface consists in sets of related commands, arranged in vertical button boxes, each such boxes being called by clicking the associated button in the menu bar. Each button box can be opened and closed at will.

The two methods are strictly equivalent, graphic buttons are internally associated to commands (or list of commands). One day, you will eventually learn how to do your own buttons.

Entering

Crowd> HELP

at the prompt level will give you the same message. The command HELP is here in uppercase, it can actually be entered also in lowercase, or even in a mixture of upper and lower case letters. In the whole manual, we will use the rule that every built-in Crowd command is given in uppercase. Macros, however have to be typed exactly as defined (this is due to the UNIX file-system), they will always appear in the manual as lower case.

Typing

Crowd> HULP

will give you an error message, since there is no command nor macro named hulp (at least on the distribution kit)!

The HELP command can also be used with a parameter :

Crowd> HELP timer

Some command may require one or several parameters, you will be prompted for such parameters, either in graphic dialogue boxes if the command was entered from a menu, or at the text terminal if the command was typed from it. When entering the prompt level, it is also possible to put the parameter directly after the command on the same line.

For instance, let us try the TAUC command which permits to define the molecule global correlation time.

Typing

Crowd> TAUC

will prompt you for the global correlation time value currently defined, just typing return will leave the value unchanged.

Typing

Crowd> TAUC 5.0

Will set the current global correlation time value to 5.0 nsec.

Menu Set-up

However it is completely optional, and Crowd can work without any menu bar (even without any graphic window !), or with a completely different graphic environment.

This user interface is actually quite easy to modify (see below in the manuel) so if you are really lacking a function in the user interface, just add it !

The environment macros are found in the /usr/local/crowd/macro directory.

If the graphic is missing, try typing the following command basic_menu.g, which executes the macro which loads the default menu-bar, from which you can add all the specific menus.

Entries followed by 3 dots (...) indicates that some input will be asked to the user by the command.

About CROWD

Config

Quit CROWD

Define...

... XPLOR nucleotides

... Unix

Define res...

Motion model...

Tauc...

Internal motion parameters...

Hyd. reson. freq...

Nb of mixing times...

Define mixing time...

List mixing times...

...Exp.int.

Output menu

Theo intensities...

Build-up curve file...

DG file...

Current iteration report

Pente...

Calculation menu

CORMA...

ROE Intensities...

Off-ROESY Intensities...

NOE Build-up curves...

R factor...

MARDIGRAS...

IRMA...

A good example of the distinction between a context and a regular command is given by the context OMEGA which defines the default value used for hydrogen resonance frequency, as compared to the related CREL_NOESY command which calculates the NOESY relaxation rates from the inter-atomic distances, using the hydrogen resonance frequency defined by the command OMEGA.

Most of the behaviour of the program depends on these internal parameters (contexts). Another example of a context is MOTION_MODEL which describes the kind of motion model used for spectral density function calculations. The effect of the command CREL_NOESY depends also on the state of the context MOTION_MODEL.

Most contexts have associated Crowd variables which permits to evaluate its value during macro execution. See the chapter on variables for details.

Commands can be issued alone, in which case, the command will prompt you for all the values it needs, proposing default ones. Default values may be kept by hitting the <enter> key, or may be changed by typing new ones. You can also type the parameters on the same line than the command; the effect is then immediate. When using in-line entry, the different items will be separated by blanks.

Several commands can even be typed on a single line, separated with a blank. For instance, you could either type :

Crowd> TAUC 3.0

Crowd> CREL_NOESY

or, on a single line :

Crowd> TAUC 3.0 CREL_NOESY

The effect would be the same.

molecule residus (RES): res(szres)

atom coordinates (CRD) : crd(szat)

inter-atomic distances (DST): dst(szmat)

relaxation rates (RATE): rateh(szmat)

theoretical intensities (INT): inttheo(szmat)

mixing times (TMIX): tm(sztm)

experimental intensities (INTE): intexp(szmat)

internal correlation times (TAU): tau(szmat)

order parameters (S2): s2(szmat)

where szres is the maximum number of molecule residus, szat is the maximum number of atoms and szmat = szat*(szat+1)/2. The current szat, szres and sztm values are given by the command CONFIG.

PRINT, ALERT, MESSAGE

MESSAGE is used in macro, it is equivalent to PRINT, except that the string will be output to the user only if no parameters are available on the call line. It is thus nearly equivalent to

if (!$arg) PRINT text

However, it is different in the sense that the string will be presented in the graphic dialogue box when the macro is called from a menu button.

HELP

Crowd> sh "ls -l /usr/data"

You can also type SH alone, this has the effect of creating a sub process at the operating system level (csh is used ), you then get back to Crowd by loging out ( ^D on UNIX).

Using SH, several macros have been created that mimic UNIX : more, rm, ls, vi, pwd, etc... There are also two special editing command : vip will edit in your $HOME/macro directory, and vim in /usr/local/crowda/macro

sh 'cd dir'

*literal are as typed:

tauc

*literal string are enclosed within single (') or double(") quotes:

'a string' or "another string" or "yet an'other valid string"

*The special character % (to be used only as a parameter for a command) takes the place of the default value of the command:

OMEGA %

*The special string %% takes the place of the whole series of all the default values of the remaining parameters of the command :

ADDCRD HA % % % % and ADDCRD HA %% are equivalent

*variables are substituted before use (more about this later):

$variable1

*expressions, enclosed within parentheses, are evaluated before use (more about this later) :

( 2*(cos(3) + 1))

*any of the preceding syntaxes may be preceded with a < symbol. In which case the input is interpreted as a file name, and the parameters takes the value of the next line read in the file (if already OPENed). A complete line is read at each time.

Each of these syntax can be used in any places; however, a single word cannot match a series of words :

These are valid syntax :

tauc $x ; define the global correlation

; time as the variable $x value.

tauc (%+3) ; add 3.0 to the global tauc value

omega (2*$y +1) ; define the hydrogen freq as the ; (2*$y+1) value

set cmd = 'tauc' $cmd 0.5 ; perform tauc 0.5

wr_int ("/usr" // $user // $exp) 0.1 Title ; write an ; intensity file

("add" // "CRD") ; execute the command ADDCRD

set f = test open $f tauc <$f ; set the global coorelation to the value ; found in file called test

These are invalid syntax :

set corr = 'tauc 3.0' $tauc

a single word (here 'tauc 0.5') cannot be used to match several words

TAUC 1+2

the parenthesis are needed for expression to be evaluated

etc...

A line cannot be longer than 256 characters, otherwise the end the line will be lost. If a longer line is needed, a continuation sign is available : \

e.g.

Crowd> print 'A line cannot be very long' print \

\Crowd> 'But can be continued' print 'as many time as you wish'

Crowd> set d := 'hello mom' ; other syntax, see below

Variables are then just used by prefixing the name with a $ :

Crowd> tauc $c print $b

Variables can be used anywhere a regular entry is needed. Variables are not typed, but contain always a string. The maximum string is currently of 256 characters. The string is interpreted as a number when needed. Variable names are not case sensitive, the name is a maximum of 31 characters long; and must be built from purely alpha-numeric characters only (including the underscore : _ ). The number of available variables is limited at compile time (and reported by the command CONFIG, and variable $VAR_MAX (see below)), but a larger table can easily be built by recompilation if needed.

Associative arrays can be built using the construction [index] :

Crowd> set d[$k] = (cos($k/10))

Associative arrays means that each entry is created when needed, entries do not have to be sequential, and the index does not even have to be integer :

$d[1] ; $d[3] ; $d[$z] ; $d['foo bar']

is a valid array. Associative arrays are coming from the standard UNIX program awk, search for a manual of this program if you some help with associative arrays. The function nextlm() permits to go through all the entries of a given array (see below).

Variables are allocated the first time they are set; referencing a variable not yet allocated generate an error. Variable are automatically deallocated when exiting the macro; they cannot be accessed by any other macros that would be executed during the life of the variable. In other words, variables have local scope, and are volatile (dynamically allocated and removed).

Variables created at interactive level (not within a macro) have a special treatment : their life will be as long as the program (unless an UNSET command is explicitly used), and they can be accessed by any other macro : they are static and have global scope.

If you which to create such a static variable from a macro (useful to remember parameters from one call to the other), you can use the following syntax :

set d := 'this variable is static'

If d was already declared as volatile previously in the macro, the preceding command has the effect of creating a new variable, called d, but in the static storage, independent of the volatile d.

; variables

The format of the DUMP is : name of the variable ; context of the variable : (20 is static, 21 to 29 are macro call levels) ; content of the variable.

Using DUMP you will find that there might be entries in the variable table that do not correspond to user variables. This is due to the fact that the parser uses this table for particular use (dbm arrays, positions of label, location of WHILE, FOR controls). This entries have different formats from the user variables, thus cannot be mistaken with them. Some of these entries holds binary data that might disturb the terminal when using the DUMP command.

dbopen array_name file_name

will associate a pseudo associative array with the dbm files of base name : file_name. The file is created if it does not exist yet. No actual variable array_name is created, but each operation on it is performed on the dbm file.

DBCLOSE closes the file and forget about the array array_name .

( 2*(5-1)) (cos($i)) are examples of expressions. Expressions can be used whenever a Crowd input is needed (command as well as parameters). Expressions must fit on one line (i.e. 256 characters long), continuation mark cannot be used within expressions.

* the regular 4 operations : + - / * e.g. : (2*3 - 1)

* the modulo function : % (12 % 5)

* the power ^ operator (3^2.1)

* the regular mathematical functions : sqrt(x) cos(x) sin (x) atan(x) log(x) exp(x) abs(x) int(x) max(x,y) min(x,y)

Introduction to the control language

Crowd> @file_name

or simply

Crowd> file_name

In UNIX the macro name is the file name, sometime names with a .g extension are chosen. Any characters (but the blank) can be used in macro name, so ../test/my_macro or /usr/local/gifa/macro/startup.g is a valid name.

A macro consists of a series of regular Crowd commands used as in the interactive mode. Up to 9 recursive calls may be nested (i.e. you can call a macro from within a macro, down to 9 nested levels). The macro execution can always be stopped with the ^C command.

When calling a macro, the file is first searched in the current working directory. If the file is not found, it is then searched in the macro sub-directory of the home directory of the user ($HOME/macro in UNIX). If it is still not found, it is searched in the standard directory :

/usr/local/crowd/macro in UNIX.

This is reminiscent with the notion of path in UNIX. This permits to build a library of macros, available for every Crowd user, as well as a set of commands personal to each user and to each project.

When the Crowd program is first entered, it tries to execute the macro file called : startup.g, the file is searched in the directory as any regular macro. Thus you can easily set-up you own environment. For instance your startup.g file (in your home directory, or in your working directory) may look like :

...any personal set-up

/usr/local/crowd/macro/startup.g ; to be sure to have general set-up

You will find a comprehensive library of such macros in the /usr/local/crowd/macro sub-directory of the distribution kit.

FOR var_name = initial TO final { STEP step}

.. some Crowd code

ENDFOR

This construction permits to write loops. The variable called var_name, will be created local to the macro if it does not yet exist, set to the value initial, and incremented by 1 for each loop. The increment can be different from 1 (but always numeric) with the optional field STEP step. step can even be negative, in which case the variable will be decremented. In any case, the test performed to determine whether the loop is finished or not is (var_name > final) if step is positive or (var_name < final) if step is negative.

WHILE some_value_to_be_evaluated

.. some Crowd code

ENDWHILE

The Crowd code will executed as long as some_value_to_be_evaluated is true (is non zero). The value to be evaluated can be a variable or a complex evaluated expression into parentheses.

The IF command has two distinctive syntaxes : a one-line IF without possible nesting nor else; and a complete IF .. THEN construct with ELSIF and ELSE possibilities.

The multi-line IF is as follow :

IF test THEN

..commands on several lines

{ ELSIF test2 THEN

..commands } (eventually many exclusive tests )

{ ELSE (default case)

..commands }

ENDIF

The different commands will executed conditionally on the value of the tests. Any non-zero value is considered as true. If may be nested, with no limit on the number of nesting.

The one-line IF is as follow :

IF logical_value ...remaining of the line ...

All the commands on the remaining of the command line are executed only if logical_value holds true (is non-zero).

examples :

IF ($X =< 0) GOTO SKIP

print 'Hello' IF ($TAUC == 1) set x = ($x+1)

IF (!eof(input)) print 'Still reading the file' \

set line = (%+1) \

IF ($line<$linemax) goto continue

tests to be used are described in the "evaluated expression" paragraph.

GOTO label

will redirect the execution of the macro to the symbol =label appearing somewhere else in the file.

Example

=loop

...any kind of processing...

goto loop

GOTO should not be used to jump into FOR or WHILE loops, nor into IF .. THEN structures, Unpredictable execution will occur.

All these commands may freely nested. However, except for GOTO and the one-line IF, these commands (FOR, ENDFOR, WHILE, ENDWHILE, =label) should appear alone on one line, with no code preceding nor following the command (or the label), but eventually followed by a comment.

In Progress : 0%....25%....50%....75%....100%

* if a command misses a parameter, the user will be prompt for it, even if the macro is called deep in a nested loop. The user will be prompted with the current value. e.g.

print 'Enter new size' chsize

(actually the message is not really needed, since the command CHSIZE will issue one)

If the macro is called from the graphic interface (with BUTTONBOX), either directly or indirectly called, a dialogue box will be used to prompt the user for the value, the message from the command (here chsize) will be in the dialogue box.

* by the same token, it is possible to assign the input into a variable :

set b = 10 print 'Enter new value' set b =

The user here will be prompted with the value 10 as default for b.

The command MESSAGE permits to put the message in the dialogue box if the macro is called from a menu button, and on the terminal if called from the prompt. Thus this is a better construct :

set b = 10 message 'Enter new value' set b =

For instance, if the file test_arg is as follow :

; to test argument passing

print $_

set b = $_ print (2*$b)

set c = $_

the following call

test_arg hello 3

will produce the following output

hello

6

and will prompt for the value to be applied to c. Thus $_ can be used to both the command line or the user, much in the same way as regular Crowd commands do. It is even possible to have an optional message, depending whether there is a parameter available or not, with the variable $arg :

if (!$arg) print 'Enter new value'

set b = $_

The MESSAGE command, has similar built-in mechanism, the string is sent to the user only if no parameters are available on the calling line. But it is better to use the MESSAGE command, since the message will then go to a dialogue box if the macro is called from the graphic interface.

message 'Enter new value'

set b = $_

sh 'more text_file' ; UNIX

A more useful example: write a PDB file using the current atom coordinates.

if (!$arg) print "PDB Output Filename ?"

set outfile = $_

sh ('rm tmp')

connect tmp

for $i = 1 to $nb_res

lstcrd $i

endfor

disconnect

sh ('awk -f mkpdb.awk tmp > '//$outfil)

sh ('rm tmp')

quit

Here is a small (silly) interactive example :

; to compute the square root of a given number

sh 'more intro.txt' ; some greeting message'

set i = 1 ;i should be set here for the following test to work!

while ($i <> 0)

print 'Enter your number (0 to end)'

set i = 0 ; pre-set the value and ask for it

set i =

if ($i>0) then

print ('Square root of';$i;'is';sqrt($i))

elsif ($i<0) then

print 'No real square root !'

endif

endwhile

exit

BUTTONBOX, CLOSEBOX

Any legal command can be used to be associated with a given button, a built-in command as well as a macro, and will be executed as if entered form the terminal. So the WHILE, FOR, IF .. THEN, GOTO commands are not available but the IF .. any_command syntax is valid. The action of the command in independent from the way it is called, except for the user prompting for values, which is performed with dialogue boxes in the case of a command called from a button.

Example given :

BUTTONBOX "my first menu" \

Hello "print 'Hello World'" \

separator \

Omega omega \

"Test Omega" "if ($omega == 600) print 'We are at 600 MHz'" \

*

Note :

* How the command should on a single line, but how the continuation sign (\) can be used

* How the quotes are needed only to isolate field with blanks in it, for button names as well as commands (Hello Omega)

* How single and double quotes can be mixed to build composite commands (Hello)

* How the on-line IF can be used (Test Omega)

The command CLOSEBOX closes the menu bar and all the associated menus. It is equivalent to closing the menu bar from the close box.

message "Enter new correlation time" set newtauc := $_

will react as follow :

nothing will appear if called with a parameter :

example 3

the user will be prompted if called without parameters :

example

the user will be prompted in a dialogue box if the macro is called without parameters from a menu button.

DIALOGBOX permits to build sophisticated dialogue boxes, several fields can be built into the dialogue box, that the user has to fill-up. Each filed is internally associated to a Crowd variable, that the remain of the macro processes. The command appears as follow :

DIALOGBOX [series of entry] *

Each entry consists of a name, that appears as such in the dialogue box, and of a type for the field. Types can be : message, string, int, real, file, enum.

message type consists of a string that is displayed on the form and permits to put text in it.

The others type of field have two other entries which give the name of the associated variable and its default value. These types correspond to editable fields that the user has to fill-up. string, int, real correspond to string, real values or integer values respectively; file corresponds to a file-name entry, and presents a small additional button in the dialogue box, which permits to pop-up a standard Motif file selection box.

The last type : enum realises a pop-up menu, for an enumerated choice. It needs an additional entry which described the list of choice. Example given :

Dialogbox "my first dialogue" \

"Enter below the file name to work on" message \

"Enter file name" file var_file $name \

separator \

"Action to apply" enum "rd_pdb,wr_pdb" var_act % \

*

$var_act $var_file

This macro will build a dialogue box with 2 editable entries : (filename and action) and will apply the action to the selected file if the user clicks on Ok.

Note :

* How the command should on a single line, but how the continuation sign (\) can be used

* The separator special field which builds a thin line in the dialogue box

* How the enumerated list is comma separated

* How the default value can be anything, here a Crowd internal variable ($name), and the default prompted value (%). In this last case, the default prompted value will be the value of the variable itself if the variable exists before the dialogue is built. If this is not the case, it will be the first entry for enum, 0 or real and int and the empty string for string and file.

* How the returned values are usual variables, and can be used for anything (here even as Crowd commands)

FORMBOX is the static version of DIALOGBOX. It builds a form that will remain after the completion of the command (as BUTTONBOX does) and will survive as long as the user does not explicitly closes it. FORMBOX needs an additional field (the callback) which describe the Crowd command to be executed when the user clicks on the Ok or Apply buttons. Apart from this, the definition of FORMBOX is strictly equivalent to that of DIALOGBOX. If not global, a variable associated to a field in a FORMBOX is local to the FORMBOX, and cannot be accessed in any other macros but the callback line. Example given :

Formbox "my first Form" \

"print ('Hello';$y_name) print ('today it is';$the_wet) " \

"Enter informations below" message \

"Your name : " string y_name "unknown" \

"The weather today :" \

enum "Sunny,Rainy,Cold,Stormy,Terrible" the_wet % \

*

Note :

* How the form variables can be used in the callback, in expression, as parameters for other commands

* Check other points in DIALOGBOX and BUTTONBOX

Typical error conditions are :

* unknown command *wrong parameter for a command (e.g. TAUC -1; MOTION_MODEL 4 etc.. ). * A impossible read or write command is tried (e.g. rd_pdb DATA.001 and DATA.001 does not exist). * mistyping a parameter (e.g. OMEGA 600,0 instead of 600.0 ), * a ^C was typed by the user, * an ERROR command was issued.

If the error occurs when the command was executed from a menu button, a alert box will be displayed.

On UNIX machines, type a file containing the command as you would type them and just start Crowd by "piping" the file as standard input, and the output on another file. The & sign run the process in background :

% gifa < name_of_the_COM_file > process.out &

Again, DO NOT forget the final EXIT. Also you may experience problems if you use interactive shell commands such as 'vi' or even 'more'.

The input in the batch file is entered to the program as a user would do, so it is different from macro (of course not for macros called during the batch) in at least to points : *control structures are not allowed *error conditions will not stop the execution, but the program will continue, So be careful when deleting important files within batch files!

When running in batch mode it is usually useless (though not forbidden) to activate the display. However if you want to have Crowd running while you are not logged on, you should choose a graphic-less mode. This mode is entered if there is no X_window DISPLAY available. For instance with

unsetenv DISPLAY

Do not forget to adapt a special startup.g macro (for instance in the current disrectory) in order not to launch the standard graphic environment (which would give an error anyway).

It is perfectly possible to print results while in batch mode.

I hope that you will have fun, and enjoy working with the Crowd program. In any case don't hesitate to contact me (bug reports and propositions are specially welcomed).

Therese MALLIAVIN.

terez@cbs.univ-montp1.fr