|
PSCF v1.1
|
Parameter File - SCFT Example (Prev) Parameter File - Format Descriptions (Next)
This page gives a more complete discussion of syntactical conventions used in all PSCF parameter files.
PSCF parameter files are fixed format files, in which each element can only appear at a specific location within the file. Some flexibility is introduced, however, by allowing some elements to be optional or selectable, as discussed greater detail below. The format for each element (e.g., each block or parameter) begins with a text label that identifies the element. When a parameter file is read, this label is compared to an expected label or a set of possible allowed values. This allows the code that reads a parameter file to confirm its syntactical validity while it is being read, and to provide informative error messages when an error is detected.
Every PSCF parameter file consists of a heirarchy of of nested parameter blocks, each of which is delimited by opening and closing curly braces.
Each block begins with a line containing a capitalized label for the block followed immediately by an opening curly bracket, and ends with a closing bracket on a line by itself, giving
Here, the string "Label" is used to denote a capitalized label string for the block, such as "System", "Mixture", "Polymer", or "Domain". There may not be any whitespace space between the block label (e.g., "System", or "Mixture") and the opening curly bracket.
Each such parameter block may contain a sequence of the following types of sub-elements:
Each block within a parameter file has a fixed file format: The order in which elements may appear within each block of a parameter file is predefined by the code that reads the block.
By convention, labels for blocks begin with a capital letter, while parameter labels begin with a lower case letter. Both types of label use upper- or lower-cased camel convention for labels that are constructed by concatenating two or more words, in which the first letter of each word after the first is capitalize.
Technical comments (for users familiar with C++):
The name of each block within a parameter file generally corresponds to the name of a class or class template in the underlying C++ code. The data contained within each such block is read by a member function of the specified class, and contains all of the information required to initialize the internal state of an instance of that class.
The code required to read the parameter file block associated with a particular class is almost always defined in a member function of that class named "readParameters". Users who are comfortable with C++ can thus use knowledge of this convention to easily find the source code that reads a particular parameter file block.
The nesting of parameter file blocks in PSCF parameter files directly reflects the structure of the underlying C++ code. Nesting of blocks within a parameter file generally reflects parent-child ownership relationships among objects in the corresponding source code. Each subblock corresponds to an object that the parent object "owns", i.e., an object that is either a member of the parent object or a dynamically created object that the parent object is responsible for creating and destroying. The top level object in any PSCF program is an instance of a class or class temnplate named "System", and so the outermost block in the parameter file is always labelled "System".
The code that reads a block of a parameter field checks the syntax of the file format by checking that the label that begins each subblock and parameter matches an expected value or list of possible values. If the label does not match an expected label for a required element, the program halts execution after writing an error message explaining what label it expected and what it actually found. When combined with echoing of the parameter file (by using "-e" command line option) these error messages make it relatively easy for users to understand and correct most parameter file syntax errors.
The simplest type of element within a parameter file block is an entry that represents a value for an individual parameter. Each such entry is given on single line that contains a label string that identifies the name of the parameter, followed by one or more spaces, and then a text representation of the parameter value.
As an example, consider the entry for the nMonomer integer parameter within the Mixture block. The value of nMonomer gives the number of distinct monomer types present within the system. The entry for a system with two distinct types of monomer would look like
The label for each such parameter generally corresponds to a slightly modified version of the name of the member variable of the relevant parent class, i.e., the name of the member variable that stores the parameter value.
The value of any parameter that is stored in a variable of a primitive C data types (e.g., an integer or floating point number) or a string may be given using any standard C text representation for that data type. String values are given without surrounding quotation marks, but must be separated from the label by one or more spaces. Values of string variables may not contain any spaces or other whitespace characters.
Technical comments (for users familiar with C++):
Parameter values are usually stored in private member variables of the enclosing class (i.e., the class whose name is given by the label for the innermost enclosing parameter block). By convention, private member variable are assigned variable names that end with an underscore, such as "nMonomer_". The corresponding parameter file label is almost always given by the variable name without the underscore, such as "nMonomer".
Values of individual parameters are read from an input stream using the C++ ">>" operator. This guarantees that a standard C text representation will work for any parameter that is stored in a variable of standard C type, such as int or double. It also means that std::string variables cannot contain internal whitespace characters, since the ">>" operator stops reading when it encounters a whitespace character.
Values of some parameters are stored as instances of non-primitive data types, such as classes or enumerations, that are defined within the PSCF source code. Values for such variables are also read from file using the ">>" operator. In these cases, the text representation of the "value" of each such non-primitive variable must be defined by an overloaded iostream extractor (>>) and insertor (<<) operators that are defined for that data type.
For example, in the example, the "type" parameter within each Polymer subblock of the Mixture block is stored as an enumeration with two possible values. The text representations of these values, as defined by overloaded ">>" and "<<" operators, are the strings "linear" or "branched". The value of the "type" parameter must thus be given in the parameter file by a string that must have one of these two allowed values.
Values of some parameters are stored as elements of a one-dimensional array. The parameter file entry for such array is given in a multi-line format in which the first row contains a label that contains the name of the array followed immediately by an opening square bracket (i.e., [), and the last line contains a matching closing square bracket (]) on a line by itself. Between these delimiters are lines that contain values of elements of the array, with one element per line. Elements appear in the parameter file in order of increasing array index, with an index value of 0 for the first element.
For example, the parameter file entry for the contents of an array named A with N elements would thus be of the form
Here, A[0], ... A[N-1] denote array element values, with zero-based indices. In the example given in the previous page, this syntax is used for the "monomers" array within the Mixture block, and the "blocks" arrays within each Polymer subblock of the Mixture block.
The number of expected elements of such an array must always be specified by the value of a parameter that appears before the array in the parameter file. The function that reads such an array thus always knows how many elements it should contain, which is passed to this function as a parameter. For example, the number of monomer types is specified by parameter nMonomer that appears just before the "monomers" array.
Variables that are stored internally in matrices or two-dimensional arrays can use one of two different multi-line parameter file formats. We will refer to these in what follows as "element format" and "row format". Only the "element format" is actually used in the current PSCF code. In either format, the dimensions of a 2D array must be calculable from parameters that appear in the parameter file before the array.
Element Format: In element format, the value of each nonzero element appears on separate line. This is the format used in above example for the chi matrix. The element format for an array starts with a line that contains a name label followed immediately by an opening parenthesis, and ends with a line containing a closing parenthesis on a line by itself. Between these delimiters are lines that each contain a row index, a column index and value of a single element of the array. In this format, elements that are not assigned values are set to zero by default. Distinct nonzero elements can appear in any order, but should not be repeated.
When used for a square symmetric matrix, such as the chi matrix, this format requires that the user enter either the (i,j) or (j,i) element for unequal i and j, but not both. The same value is then assigned to both of these equivalent elements when an entry for either is encountered in the parameter file.
As an example, consider the syntax for a symmetric chi matrix for a system with 3 monomer types (nMonomer = 3), vanishing diagonal elements, and nonzero values for all off-diagonal elements. A valid parameter file format for such a matrix might look something like this
In this example, zero values are assigned to all diagonal elements by default. If desired, nonzero values also could be assigned to diagonal elements by including them in the parameter file format. Entries for nonzero elements may appear in any order.
Row Format: In the row format for a matrix-valued parameter, elements values are entered using a format very similar to the standard representation of a matrix as an array of numbers, as used in matrix linear algebra. This format is currently not used in the parameter file format for any PSCF program, but is available for future use.
The row format for the elements of a 2D array begins with a line that contains a label string followed immediately by an opening square bracket, and ends with a line containing a closing square bracket on a line by itself, exactly as for a 1D array. Between these opening and closing lines are lines that each contain the values of all of the elements of one row of the corresponding matrix.
For example, the row format for elements of 2 x 3 matrix named "matrix" would use a format something like this:
In this example, the value of the matrix element in row 0 and column 1 is 23.0, while the value in row 1 and column 2 is 21.3.
Each labelled element in a parameter file (i.e, each block or parameter) may be either required or optional. Most elements required.
The label associated with a required element must appear at the expected position in a file format. If the label for a required element is not found at the expected location, the program will halt after writing a error message to standard output that explains what label it expected to find.
The entry for an optional block or parameter may be either be present in the parameter file or absent. If the label associated with an optional block or parameter is absent, the program will continue on and try to instead match the label that was found at that location with the label associated with the next expected element. Optional parameters that are omitted from a parameter file are usually assigned default values.
When echoing of the parameter file is enabled, by invoking a program with the -e command line option, the name of each omitted optional parameter is echoed to standard output followed by the string "[absent]" to indicate that it was omitted.
Some parameters or blocks in a parameter file may also be required or allowed only if other parameters that appear earlier in the file are present or have been assigned particular values. Generally, the PSCF parameter file format does not require or allow entry of parameters that are already known to be meaningless or irrelevent on the basis of the information given in earlier parts of the parameter file.
For example, the Mixture block of any PSCF program contains an optional parameter nSolvent that may appear immediately after the parameter nPolymer. The parameter nSolvent is assigned a default value of zero if it is absent. If nSolvent is present and is assigned a nonzero value, then the Mixture block must contain a corresponding number of Solvent blocks immediately after the Polymer blocks. Solvent blocks may not appear, however, if nSolvent is set to zero either explicitly or by default.
Some blocks in a PSCF parameter file are "selectable". A selectable block is one that may contain any of several blocks that are associated with C++ classes that serve analogous purposes but that rely on different algorithms. As already noted, the block that represents an iterator in a PSCF program is always a selectable block. The use of a selectable block for the iterator allows users to specify a choice from among several different available iterator algorithms.
The users choice of one of several valid options for a selectable block is specified by the label used in the opening line for the block, which ends with an opening curly bracket. That block label is compared to a list of label strings for available options. If the label for a selectable block in the parameter files matches one such string, the option corresponding to that label is selected. Different possible options for a selectable block generally require different parameters, and thus require different parameter file formats. The format of the body of a selectable block must match the format expected for the type of block declared in the block label.
A default choice is normally defined for each selectable block. The default choice may be selected either by using the generic name for the type of element (e.g., "Iterator") or the name for a specific algorithm. In the example shown on the previous page, the default choice of a iterator is an Anderson-Mixing iterator that is implemented by a class named AmIterator. Because it is the default choice, this algorithm may be selected by using a parameter file in which the block begins with the generic label "Iterator", as in the example. The same algorithm may also be selected, however, by using a block that starts with the specific label "AmIterator".
Technical comments (for users familiar with C++:
The implementation of selectable parameter file blocks in PSCF is based on C++ inheritance and polymorphism. The different options for a selectable block are always implemented by different subclasses of a common base class. The base class defines a shared C++ interface for objects of the relevant type. The generic name of the block in the parameter file (i.e., the name that can also be used as a label to select the default option) is always the name of the relevant base class. The parent object (e.g., the System) has a member variable which is a pointer to an instance of the base class.
For example, different iteration algorithms for a particular PSCF program are subclasses of a base class named "Iterator", which defines a common interface for SCFT iteration algorithms. The parent System object has a private member variable of type Iterator* that can point to an instance of any subclass of class Iterator.
If the block label input for a selectable block matches the name of an available subclass of the relevant base class (e.g., a subclass of Iterator), then an instance of the selected subclass is constructed after the opening line of the block is read and interpreted. The address of that new object is also assigned to the base class pointer owned by the parent class (i.e., the Iterator* pointer variable owned by the parent System). The "readParameters" member function of the new object is then invoked to read the body of the selectable block, using a block format appropriate to the chosen subclass.
Parameter File - SCFT Example (Prev) Parameter Files (Up) Parameter File - Format Descriptions (Next)
1.9.5