PAMoC's execution is controlled by user-prepared data. Input data are provided through:
The user input-file may be prepended by a default procedure or configuration file. PAMoC looks for the following configuration files
at first in the current working directory and then in the home directory. Configuration files are searched in the specified order, but only the first one which is found is read.
An auxiliary input file can be specified by the keyword inp (e.g., on the command line: -inp <aux-input-file>). Data provided on the configuration, standard input and auxiliary input files obey the same syntax rules, so that the three files are interchangeable. However, a hierarchy exists, so that data on the auxiliary input file override those on the configuration file, and data on the standard input file override those on the auxiliary input file.
Input data can be rather complex, like wavefunctions or the results of least-squares multipole refinement of experimental structure factors, so that they are usually stored on disk files, either in binary or ascii text format. However a lot of data are in the form of keywords with optional arguments and options, and can be provided also through the command line or as environment variables. A full list of the available keywords can be found in a separate section of this manual.
The C-shell UNIX command line to run a PAMoC job in background mode has the following syntax:
Syntax rules agree with the following notations. The “Lucida Sans Typewriter” monospaced font family denotes both UNIX commands (including the executable program name, pamoc.exe) and keywords recognized by PAMoC. UNIX commands are given in bold and are case sensitive. PAMoC keywords must be typed as shown, but they can be in upper, lower or mixed case. In addition, keywords are prepended by the minus sign, "-". Keywords which have the same meaning and produce the same action are enclosed in parentheses "( )" with a vertical bar "|" as the delimiter. A double vertical bar "||" is used to delimite two mutually exclusive options. Parentheses "( )" can be omitted if no ambiguity occurs. Keywords may require one or more options. <italic> embedded in angle brackets "< >" is used for variables and options which should be replaced with actual values. Angle brackets "< >" can be omitted if no ambiguity occurs. Square brackets "[ ]" denote optional values.
Every UNIX process runs in a specific environment. An environment consists of a table of environment variables, each with an assigned value. C-shell environment variables are set by the setenv command, and displayed by the printenv or env commands, while the echo command is used to display a specified variabe, individually. The syntax of the command is:
where option is interpreted as a character string. If the string includes blanks (i.e. if it encompasses multiple values), enclose the string in double quotes (" "), e.g.:
At variance from the command line, here keyword must not be prepended with the minus sign "-".
Since input data can be rather complex, they are usually stored on disk files. Three types of data input files are mentioned above, namely the standard input file, the auxiliary input file and the configuration file. Other files can provide additional data input to specific sections of PAMoC and are addressed by specific keywords. Interface data files (IDF's) provide an interface between PAMoC and other computer packages, which are able to produce a representation of the electron density distribution of an isolated molecule or molecular crystal. Currently PAMoC is interfaced to ab initio electronic structure packages and to packages based on multipole refinement of experimental electron densities. Eventually, PAMoC accepts other types of IDF (e.g. CIF, CRYSTAL-XX print-output files, etc.). Of course, the actions that PAMoC will take, depend on the type and content of the IDF, and additional input data may be required.
Print output data are sent to the terminal (standard output) unless they are redirected to a disk file by the user. A print output file can also be specified by the keyword out (e.g., on the command line: -out <print-output-file>). In this case, most print output data are sent to the specified disk file and only a small piece of information may still be sent to the standard output (mainly for debugging purposes). In addition, PAMoC can generate output files either by itself or upon user request through specific keywords.
PAMoC can be launched either in background or in foreground mode. Remember that a foreground process is any command or task you run directly and wait for it to complete. For example, you can launch PAMoC in forground mode by entering the command
from the shell prompt. You cannot do almost anything else from the shell prompt while PAMoC completes its task. Only then do you regain access to the shell prompt. However, if the foreground process is taking too much time, you can stop it by pressing Ctrl+Z. A stopped job still exists, but its execution is suspended. To resume the job, but in the background, type bg to send the stopped job to background execution. To resume a suspended process in the foreground, type fg and that process will take over the active session. To see a list of all suspended processes, use the jobs command, or use the top command to show a list of the most CPU-intensive tasks so that you can suspend or stop them to free up system resources. To change the execution priority of a process, use nice and renice.
Unlike with a foreground process, the shell does not have to wait for a background process to end before it can run more processes. Within the limit of the amount of memory available, you can enter many background commands one after another. To run a command as a background process, type the command and add a space and an ampersand to the end of the command. For example:
When you issue a command with the concluding ampersand, the shell executes the work, but instead of making you wait for the command to finish, you'll immediately be returned to the shell. At this point, you can enter another command for either foreground or background process. Background jobs are run at a lower priority to the foreground jobs. You will see a message on the screen when a background process finishes.
Since its early development, a foreground PAMoC process showed some type of user interface that supported ongoing user interaction. Such an interactive procedure was designed primarily for debugging and testing purposes. Based on a cascade of menus, it was rather self explaining and easy to use. To activate an interactive session, it was sufficient to launch PAMoC without redirecting the standard input and the standard output, e.g.
The two parts of the program, the one for background execution and the one planned for interactive sessions, shared many routines. Changing one of these subroutines made it necessary to update both sections of the program. Unfortunately, in most cases only the part related to background execution was updated. Thus the number of bugs in the interactive part started to grow, making the user unhappy.
Starting from the summer of 2012, a profound revision of the PAMoC code was undertaken by the author (who called it RV, i.e. Retirement Version, due to the coincidence with the beginning of his retirement). Since then, all the interactive pieces of code have been extracted from PAMoC and developed independently in the form of interactive user interfaces.