Parameter File - 1D 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 structured into blocks, in which each block contains a sequence of parameters and nested subblocks. Each block has a fixed format, in which each element within a block can only appear at a specific location. Some flexibility is introduced, however, by allowing some elements to be optional and/or selectable, as discussed in greater detail below. The format for each element of a block (e.g., each parameter or nested subblock) 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 a syntax error is detected.
Blocks
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:
- Nested Subblocks : Each nested subblock is delimited by a label and matched opening and closing curly brackets, as described above.
- Individual Parameters : Each individual parameter entry appears on a single line that contains a parameter label followed by a text representation of the parameter value. The first example in the example parameter file shown on the previous page is the integer parameter nMonomer in the Mixture block.
- Array-valued Parameters : The entry for each one-dimensional array parameter is given in a multiline format that begins with a line containing an array label followed immediately by an opening square bracket ("[") and ends with line containing only a matching closing square bracket ("]"). Between these delimiting lines are lines containing values of array elements, with one value per line, listed in the order of increasing array element index. The "monomers" array in the Mixture block of the example file is an example of such an array, in which the value of each element is a floating point number.
- Matrix-valued Parameters : Two-dimensional arrays or matrices may be represented using a format that begins with a line containing a label and an opening parentheses and that ends with a closing parenthesis on a line by itself. Between these delimiting lines are lines that each contain the value of a single matrix element. Each nonzero element of the matrix is given on a line that contains a column index, a row index, and the value of the corresponding element, separated by whitesepace. The only matrix-valued parameter in the example parameter file is the chi matrix given in the Interaction block.
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 block of a parameter file.
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 allocated 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 each block of a parameter field checks the syntax of the input file while it is being read by checking that the label that begins each subblock or parameter matches an expected value or list of possible values. If the label does not match any allowed value, the program will halts execution after writing an error message explaining what label it expected and what it found instead. The usefulness of such error messages may be enhanced by echoing of the parameter file, by using "-e" command line option. The combination of detailed error messages and echoing provides enough information for most users to understand and quickly correct most parameter file syntax errors.
Individual Parameters
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, which gives 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 parameter 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., of 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, and may not contain any internal 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 allowed 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.
Array-Valued Parameters
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 C++ 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.
Matrix-Valued Parameters
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. Lines containing 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.
Optional Elements
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 0 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.
Selectable Blocks
Some blocks within a PSCF parameter file are "selectable". A selectable block is one that may start with the block label for any of a limited number of algorithms that serve analogous purposes, but that are implemented by instances of different C++ classes. (See technical note below for a discussion of the relationship between selectable block labels and C++ subclass names).
As already noted, the block that selects an SCFT iterator algorithm 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.
A user's choice of one options for a selectable block from a set of one or more possible options is specified by the label used in the opening line of the block, in the line that 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 input parameters, and so require different formats for the contents of the body of the block. 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 of algorithm is defined for every selectable block. The default choice may be selected either by using the generic name for the type of element (e.g., "Iterator") or the label for the 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 is done in the example. The same algorithm could also have been 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 required C++ class interface for objects of the relevant type, thus allowing them to be used interchangeably. 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 that base class, which normally points to an instance of the subclass declared in the block label.
For example, different iteration algorithms for a particular PSCF program are implemented by subclasses of a base class named "Iterator". The Iterator base class defines a common interface for SCFT iteration algorithms. The parent System object has a private member variable that is a pointer of type Iterator* that can point to an instance of any subclass of class Iterator.
If the block label 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. If the block label matches the name of the base class (e.g., "Iterator") then an instance of the default subsclass is constructed. The address of that new object is then 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 the format appropriate to the chosen subclass.
Parameter File - 1D SCFT Example (Prev) Parameter Files (Up) Parameter File - Format Descriptions (Next)
Generated on Mon Apr 14 2025 16:29:26 for PSCF by
1.12.0