Data Input.

Data Entry and Data Input are all encompassing terms for any task that requires information to be entered into a computer. This manual page describes data input which is provided mainly through configuration files (.pamocrc, pamoc.rc, pamoc.cf), auxiliary input files (keyword inp) and files redirected to the standard input. PAMoC data input consists of a series of lines in an ASCII text file. The basic structure of a PAMoC input file may include several different sections, in any order:

  1. Input syntax
  2. Atom coordinates
  3. Cell parameters
  4. Lattice specification
  5. Symmetry operations
  6. Space group
  7. Nuclear centered/distributed multipole moments
  8. Rotation matrix
  9. Keywords and options
  10. Comments

An input section may consist of either a single line or a block of lines.

1. - Input Syntax

In general, PAMoC input is free-format and case-insensitive.  The contents of an external file can be included within a PAMoC input file using the following syntax:

@filename   file-name[/N]

This causes the entire file to be placed at the current location in the input stream. Appending /N to such commands will prevent the included-file´s contents from being echoed at the start of the output file.

Comments begin with an exclamation point (!), which may appear anywhere on a line, or with the number sign (#), which must be the first character of the line. Separate comment lines may appear anywhere within the input file.

A single-line input section has the following form:

keyword   <option1 option2 … >

At variance from the command line, here the keyword does not need to be prepended by the minus sign (-).

A block-input section starts with a line that specifies the section-name and possibly a number of options and terminates with an end-of-section line according to the general form:

[begin] section-name   <option1 option2 … >
....................
....................
....................
end [ection-name]

The lines that are embedded between the begin-of-section and the end-of-section lines are subject to syntax rules that depend on the specific section.

Most of data-input sections override proviously entered data, when they are repeated (e.g. atom coordinates, lattice specification, space group, dma). On the other hand, a few data-input sections can be repeated as many times as needed to add required data (e.g. symmetry operations, rotation matrix, comments).

2. - Atom coordinates

The input of atom coordinates consists of a series of lines of the form:

[begin] coord   [<units>]
.................... .................... .................... .................... ....................
element-label atomic-number   x-coordinate   y-coordinate   z-coordinate
atomic number   element-label x-coordinate y-coordinate z-coordinate
.................... .................... .................... .................... ....................
element-label x-coordinate y-coordinate z-coordinate 
atomic number   x-coordinate y-coordinate z-coordinate 
.................... .................... .................... .................... ....................
end [coord]

Any coordinate line must have either 4 or 5 fields, as indicated above. Both the element-label and the atomic number can be specified on the same line, though only one of them is usually given. The remaining items on the line are Cartesian or Fractional coordinates specifying the position of that nucleus.

The keyword coord, which specifies the section name, may be followed by the option units, which specifies the units of the atomic coordinates. The allowed values are angstrom, bohr and au for cartesian coordinates, and fract[ional] otherwise. The latter is the default.

Element-label is a character string consisting of the chemical symbol for the atom. The elemental symbol may be optionally followed by other alphanumeric characters to create an identifying label for that atom. A common practice is to follow the element name with a secondary identifying integer: C1, C2, C3, and so on; this technique is useful in following conventional chemical numbering. The maximum length of the element label is 4 characters.

3. - Cell parameters

Cell parameters are entered on a single-line input section, which has the following form:

cell   <a b c   alpha beta gamma>

The arguments are cell parameters (a, b, c), with lengths in angstrom or 1/angstrom, and angles (alpha, beta, gamma) in degrees or cosines of angles.

4. - Lattice specifications

Lattice specifications are entered on a single-line input section, which has the following form:

latt   <centric-specification    lattice-type>

The argument centric-specification is either A or C (for acentric or centrosymmetric crystal, respectively), and lattice-type is P, I, R, F, A, B, or C.

5. - Symmetry operations

Symmetry operations are entered on a single-line input section, which has the following form:

sym|symm|symtry   <symmetry-operation-elements>

where the symmetry operation elements are given exactly as in the International Tables, the three general position coordinates being separated either by commas or spaces. If desired, more positions can be entered on a single sym line, by placing a semicolon between each of them. Alternatively, the symmetry operation is written in a purely numerical way by giving a translation vector and a 3 by 3 rotation matrix, i.e.:

sym|symm|symtry   tx  r11  r12  r13   ty  r21  r22  r23   tz  r31  r32  r33

Single-line symmetry sections are repeated until the full number of symmetry operations is covered. Alternatively, symmetry operations can be entered as a block-of-lines input section:

[begin] sym|symm|symtry
symmetry-operation-elements
[end] sym|symm|symtry

6. - Space group

The space group can be specified either by its International Tables number (1 through 230) or by its symbol. Explicit definition of the space group is an alternative to specify lattice type and symmetry operations separately. It is entered by a single-line input section of the form:

spac[e group]   <number|symbol>

7. - Nuclear centered/distributed multipole moments

The first line of a DMA (Distributed Multipole Analysis) section contains the keyword DMA followed by the specification of the DMA-type:

[BEGIN] DMA   <DMA-type>
....................
END [DMA]

The DMA section is terminated by either an end-of-file or an END line.

Types of DMA accepted by PAMoC are listed in a separate page, which describes the structure of the External DMA Data Input File's. These files, which usually have suffix .ext, are addressed by the keyword ext in a single-line input section:

ext   <filename.ext>

or included in a block input section:

[BEGIN] DMA   <DMA-type>
@<filename.ext>
END [DMA]

8. - Rotation Matrix

A rotation matrix can be provided to rotate, for example, the external multipole moments to the same orientation of the IDF moments:

[begin] rotate [invert]
R11 R12 R13
R21 R22 R23
R31 R32 R33
end [rotate]

or, equivalently

[begin] rotate [invert]
R11 R12 R13 R21 R22 R23 R31 R32 R33
end [rotate]

Matrix elements can be distributed on 1 to 9 lines, provided that they are in row order. The option invert requires that the inverse of the input matrix (instead of the input matrix itself) is used to rotated the moments. If a second rotation matrix is given (in a separate section), the two rotations are applied in sequence.

9. - Keywords and Options

Control of a PAMoC run is realized through keywords and options which are entered in the form of single-line data-input sections:

keyword   <option1 option2 … >

Keywords and options can be entered also as environment variables or on the command line. In the latter case the keyword must be prepended by the minus sign (-). A complete list of keywords is given in a specific page of the manual.

10. - Comments

Comments are entered as a block of lines that contains strings of ascii characters:

[begin] comment[s]
....................
....................
....................
end [comment[s]]

Comment lines are printed on the standard output as they are read. Comment sections differ from the comments identified by an exclamation point (!) or by a number sign (#), which usually are not echoed on the standard output.