Parameter File - Syntax (Prev) Parameter File - Mixture Block (Next)

Users of PSCF require precise and complete documentation of the required format for each block that can appear with a parameter file of a PSCF program. This page describes a representation that is used in the PSCF documentation to indicate the format of each parameter file block. This format representation is similar to that of the actual block, supplemented by notation to indicate data types of parameter values, and by the use of special symbols to indicate syntactical elements such as array-valued parameters, optional elements and selectable subblocks.

Example 1: pscf_1d

As a simple first example of this sort of description, the overall syntax for a pscf_1d parameter file is shown in skeleton form below:

System{
   Mixture{ ... }
   Interaction{ .... }
   Domain{ ... }
   Iterator#{ ... }
   Sweep#*{ ... }
}

This description should look familiar, except for the inclusion of a Sweep{...} block, which is an optional element that was omitted from our example file. In such a description, the syntax Label{...} is used to indicate a nested subblock, for which the format of the subblock must be described separately somewhere else. The appearance of an asterisk (*) after any block or parameter label is used to indicate that the element is optional (i.e., omittable). Parameters and subblock labels that are not followed by an asterisk thus indicate required elements. The appearance of a "#" symbol after a block label indicate that the block is selectable. The above description thus indicates that the Iterator block is selectable but required, and that the Sweep block is both selectable and optional.

Example 2: Mixture Block

As a second example, the format for a Mixture block in any PSCF parameter file can be given compactly as follows:

Mixture{
  nMonomer   int
  monomers   Array [ real ]
  nPolymer   int
  Polymer{ ... }
    ...
  nSolvent*  int (0 by default)
  Solvent*{ ... }
    ...
  vMonomer*  real (1.0 by default)
  ds         float
}

In this example, we see that the locations at which values of individual parameters would appear in an actual parameter file have been replaced by labels that specify the type of parameter value, such as int or real. The word Array followed by opening a closing square brackets enclosing a type descriptor is describe an array-value parameter. Note that default values for some optional elements (nSolvent and vMonomer) are given as comments enclosed in parentheses.

This sort of compact format description must be generally supplemented by a table and/or text that contains an explanation of the the meaning of each parameter, comments about allowed values for particular parameters, values for dimensions of arrays or matrices, relationships among choices of parameter values, and any other required supplementary information.

Conventions

The following conventions, most of which are illustrated in the above examples, are used in this type of parameter file format summary:

Parameters : Individual parameters are indicated using the syntax
label type

where "label" denotes the name (or label string) of the parameter and "type" is a string that identifies the data type of the parameter value (e.g., int, real, string, etc.).

The main labels used to indicate elementary data types are "int" for integer, "real" for a real (i.e., floating point) number, "bool" for a boolean value, a "string" for a string. Values of boolean variables are given as 0 for false and 1 for true. String parameters may not contain any whitespace.
Arrays : Parameters that represent one-dimensional arrays are indicated using the syntax
label Array[ type ]

where "label" is the name of the array, and "type" is a string that identifies the data type of a single element. For example, "monomers Array[real]" indicates that monomers is a one-dimensional array in which each element is a real floating point number.
Matrices : Parameters that represent two-dimensional arrays or matrices that must be input in element format are indicated using the syntax
label Matrix ( type )

where "type" is the data type for a single element.
Subblocks : The presence of a nested subblock is indicated using the syntax
Label{ ... }

where "Label" denote the label string for the subblock. The ... is used to indicate the body of the block, the format of which must be described somewhere else in the documentation.
Optional elements : Optional parameters and subblocks (i.e., elements that may be omitted from the file) are indicated by an asterisk after the subblock or parameter label. The label for an optional simple parameter is thus
label* type

where "label" denotes the actual label string.
Default values : Default values for optional parameters may be indicated by a comment enclosed in parentheses after the label and data type. The comment is often of the form "( ... by default)", where ... denotes the actual default value. The default value is the value assigned to the associated variable if the parameter is omitted from the parameter file.
Selectable subblocks : Selectable subblocks are indicated by adding a "#" symbol after the subblock label and before the opening curly bracket, using the syntax
Label#{ ... }

for a required but selectable subblock. The label for a selectable subblock in a format description should be the generic name for the subblock (e.g., the generic name "Iterator", rather than the name of a class that implements a specific iterator algorithm). This generic name can also be used as a block label to select the default choice for this block.
Selectable optional subblocks : The label for a selectable block that is also optional should contain an asterisk after the # symbol, giving a format description of the form
Label#*{ ... }

where Label denotes the generic name of the block. For example, the Sweep block of a pscf_1d parameter file is both selectable and optional, and so is described in the first of the above examples by a line of the form "Sweep#*{ ... }.

Parameter File - Syntax (Prev) Parameter Files (Up) Parameter File - Mixture Block (Next)