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

Users of PSCF require complete documentation of the required format for each type of block that can appear within a parameter file. This manual page discusses a representation that is used throughout the PSCF documentation to describe the required format of parameter file blocks. This format representation looks similar to that of the actual block, except for thus use of notation to indicate data types of parameter values (rather than actual values), and by the use of special symbols to indicate syntactical elements such as array-valued parameters, optional elements and selectable subblocks.

Example 1: SCFT parameter file for a periodic structure

As a simple first example of this sort of format description, the overall format for a pscf_pc or pscf_pg parameter file used to initialize a SCFT calculation is shown below:

System{
   polymerModel*  enumeration ("thread" or "bead", "thread" by default)
   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 earlier example. 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 an element is optional (i.e., omittable). Parameters and block labels that are not followed by an asterisk are thus labels for 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 and Sweep blocks are both optional and selectable.

For simplicity, the above format description only shows allowed elements of the System block that are relevant to SCFT calculations for spatially periodic structure. A complete format description for the System block of the pscf_pc program, which includes additional optional elements, is given here.

Example 2: Mixture block

Every PSCF parameter file contains a Mixture block, which is always a required element of the System block. Different PSCF programs use a Mixture block with the same file format. This format can be described compactly as follows:

Mixture{
  nMonomer   int
  monomers   Array [ real ]
  nPolymer   int
  nSolvent*  int (0 by default)
  Polymer{ ... }
    ...
  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.

A Mixture block may contain multiple Polymer and Solvent blocks, as indicated by ellipses in the above format description. The number of Polymer and Solvent blocks must match the values of nPolymer and nSolvent, respectively.

The sort of compact format description shown above is usually supplemented by a table and/or text discussion that contains an explanation of the the meaning of each parameter, as well 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.

Element descriptors

The following conventions are used to describe different types of element that may appear in the description of a parameter block format:

Nested subblocks : The presence of a nested block is indicated using the syntax
Label{ ... }

where "Label" denote the label string for the nested block. The ellipses (...) within curly brackets is used to indicate the body of the sub-block, the format of which must be described somewhere else in the documentation.
Individual 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.

Values for parameters that are represented internally by a enumeration may be indicated by the data type "enumeration", followed by a list of the string representations of all allowed values.
Vectors : Vector-valued parameters are indicated using the syntax
label Vector[ 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, "mesh Vector[int]" indicates that the "mesh" parameter is a vector in which each element is an integer. Vectors are similar to arrays, but use a single-line parameter file format with no delimiters, rather than the mult-line format used for an array.
Arrays : Array-valued parameters 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. Arrays are formatted in the parameter file a format in which each element is on a separate line, delimited by square brackets.
Matrices : Parameters that represent two-dimensional arrays or matrices that must be input in element format (which uses parentheses as delimiters) are indicated using the syntax
label Matrix ( type )

where "type" is the data type for a single element.

Optional and Selectable Elements

Optional elements and selectable blocks are identified using the following conventions:

Optional elements : Optional parameters and blocks (i.e., elements that may be omitted from the file) are indicated by an asterisk after the subblock or parameter label. The description for an optional individual parameter is thus of the form
label* type

where "label" denotes the actual label string. Similarly, the description of an optional block would be of the form
Label*{

....

}

where "Label" denotes the block 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 Iterator and Sweep parameter file blocks are both selectable and optional.

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