Example Parameter File

The text shown below is a complete parameter file for a simple 1D SCFT calculation performed using the pscf_1d program:

System{
  Mixture{
     nMonomer   2
     monomers[
                1.0
                1.0
     ]
     nPolymer   2
     Polymer{
        nBlock  2
        blocks[
                0   0.5
                1   0.5
        ]
        phi     0.6
     }
     Polymer{
        nBlock  1
        blocks[
                0   1.0
        ]
        phi     0.4
     }
     ds   0.01
  }
  Interaction{
     chi(
           0    1    10.0
     )
  }
  Domain{
     mode     planar
     xMin     0.0
     xMax     8.0
     nx       401
  }
  Iterator{
     epsilon   0.00000001
  }
}

This particular example gives parameters for a calculation of a binary mixture of a symmetric AB diblock copolymer with a homopolymer of type A in a one-dimensional planar geometry.

File Structure

Before delving into details, note the overall structure of this example: The above parameter file consists of a set of nested blocks that each begin and end with matching curly brackets, much like the syntax of a C program. Each block begins with a line that contains a capitalized label for the block (e.g., System, Mixture, etc.), followed without any intervening white space by an opening curly bracket, "{". Each such block ends with a matching closing curly bracket on a line by itself.

The structure of the main blocks in this example is shown in skeleton form below:

System{
  Mixture{
     ...
  }
  Interaction{
     ...
  }
  Domain{
     ...
  }
  Iterator{
     ...
  }
}

The main block of a PSCF parameter file, which encloses all the data in the file, is always labelled "System". The purpose of each primary subblock of the main "System" block is described below.

Mixture: The Mixture block contains a description of the chemical composition of a system that may contain one or more polymer species and zero or more solvent species. This includes a description of the structure and composition of each molecular species and a specification of either the volume fraction phi or chemical mu of each such species.
In this example, the Mixture block contains nested two Polymer{ ... } subblocks, each of which contains information about one of the two polymer species in a binary copolymer/homopolymer mixture.
Interaction: This Interaction block contains values for Flory-Huggins chi parameters that specify the strength of binary thermodynamic interactions between monomers of different types.
Domain: The domain block contains information about the spatial domain over which the SCFT equations should be solved and a description of the spatial discretization grid used by pscf_1d to numerically solve the field equations.
Iterator: The Iterator block contains parameters required by an iteration algorithm that is used to iteratively solve the nonlinear SCFT equations.

The parameter files required to initialize a simple SCFT calculations performed using a pscf_pc or pscf_pg program have a similar structure, with analogous top level blocks appearing in the same order. Parameter files for the three different PSCF programs use a common format for the Mixture and Interaction blocks, but generally use different formats for the Domain and Iterator block. The pscf_pc and pscf_pg programs for periodic systems use the same parameter file format for the Domain block, which differs from the format used by pscf_1d. The format of the body of the Iterator block is different for different iteration algorithms, and the choice of available iteration algorithms is different for all three programs.

Parameter files that are designed to initialize a single SCFT calculation performed with any PSCF program will generally exhibit a sequence of top level blocks analogous to that shown in this example. A different sequence of top-level subblocks may be required for other types of calculation. For example, a parameter file used to setup an SCFT parameter sweep would require an additional block "Sweep" block to described the desired sequence of states, as discussed elsewhere.

Parameters

We now consider general aspects of the syntax of any block in a PSCF parameter file. Each parameter file block may contain a sequence of parameter entries and nested subblocks. Nested subblocks are delimited by opening and closing curly brackets. Each parameter entry starts with a label that indicates the name of the parameter followed by a representation of the parameter value. Several types of parameters may be present:

Single Parameters : Each entry for a single parameter is a single line containing a label (the name of the parameter) followed by the parameter value. The value is often a single number or some other compact string representation. For examples of individual parameters, look for the nMonomer and nPolymer parameters within the Mixture block.

Array- and Matrix-Valued Parameters : Labels for some other parameters refer to names of 1D arrays or 2D matrices of values. In these cases, lists of elements of the array or matrix are delimited by either matched square brackets (for one-dimensional arrays) or by parentheses (for matrices or two-dimensional arrays). Names of array-valued parameters are often given as plural nouns.

As an example of a one-dimensional array-valued parameter, see the "monomers" parameter in the Mixture block, which begins with a line containing the string "monomers[" that ends with an opening square bracket, and which ends with a closing square bracket ("]") on a line by itself. The value of each element in this particular array is a real (i.e., floating point) number that is given on a line by itself. Each element in the monomers array gives the statistical segment length of a particular type of monomer.

The value of the parameter "chi" within the Interaction block is given by a symmetric matrix. The distinct nonzero elements of the chi matrix are given using a syntax in which each such element is given on a line containing a row index and a column index (defined using a zero-based convention), followed by the real value of the matrix element. The resulting list of nonzero matrix elements is enclosed by opening and closing parentheses.

Overview of Example

Mixture :

The Mixture block of the above example is reproduced below for reference:

Mixture{
   nMonomer   2
   monomers[
              1.0
              1.0
   ]
   nPolymer   2
   Polymer{
      nBlock  2
      blocks[
              0   0.5
              1   0.5
      ]
      phi     0.6
   }
   Polymer{
      nBlock  1
      blocks[
              0   1.0
      ]
      phi     0.4
   }
   ds   0.01
}

The parameter value nMonomer = 2 in the first line of this block indicates that the molecular species in this system are constructed from two types of monomer. Different types of monomer are labelled by integer indices in the range 0,...,nMonomer-1.

The "monomers" parameter is an array-valued parameter shown above as

monomers[
           1.0
           1.0
]

The value of each element in the "monomers" array gives the monomer statistical segment length for a monomer type, listed in order of increasing monomer type index. The number of elements in this array (corresponding to the number of lines between the lines containing the opening an closing square brackets) must be equal to nMonomer.

The value of the parameter nPolymer that appears next gives the number of polymer species in system. In this example, nPolymer = 2, indicating the presence of two species of polymer. This parameter is followed by two "Polymer" blocks, each of which describe one of these two species. In this example, each Polymer block contains an integer parameter named "nBlock", an array named "blocks", and a floating point parameter named "phi"

PSCF treats each polymer species as a block polymer, which can be either linear or branched. Homopolymers are treated as a special case of a block polymer with only one block. Each polymer species is assumed to be a linear block polymer by default, which is the case for both species in this example. A polymer can instead be declared to be a branched polymer by adding an optional "type" variable at the begining of the Polymer block (which is not present for either species in this example), as discussed here.

The value of the parameter "nBlock" within each Polymer block gives the number of blocks in the polymer. Each line with the array-valued "blocks" parameter (or each element of the associated array) contains information associated with one block of the polymer. In the default case of a linear polymer that is used for both species in this example, each such block description contains an integer monomer type index (the type of monomers in the block) followed by a floating point block length. For linear polymers, blocks are listed in the order in which they are connected along the chain. A more complicated format is needed to describe each block within a branched block polymer, in order to described connectivity as well as monomer type and length, as described here.

In this example, the value of the "phi" parameter in each Polymer block specifies the volume fraction of the associated species. It is also possible to specify a value for chemical potential (denoted by "mu") rather than a volume fraction for some or all of the species in a mixtue, but we have specified volume fraction values for both species in this example.

In this example, the first polymer species is a diblock copolymer (nBlock=2) containing blocks of equal length 0.5 with monomers of types 0 and 1. The second polymer species is a homopolymer (nBlock=1) of length 1.0 with monomers of type 0. The system is binary mixture containing 60% of diblock copolymer by volume (phi = 0.6 in the first Polymer block) and 40% homopolymer by volume (phi= 0.4 in the second block).

The last line in the mixture block in this example contains a value for the computational parameter ds, which is the approximate value of the contour length step used to discretize the length of each polymer within the numerical solution of the modified diffusion equation. In this example, the contour of the homopolymer of length 1.0 would thus be discretized into 100 steps within this numerical solver, while each block of length 0.5 within the symmetric diblock copolymer species would be discretized into 50 steps.

Interaction :

The Interaction block of the parameter file contains a single matrix-valued parameter named chi. The Interaction block from the above example is reproduced below for reference:

Interaction{
   chi(
         0    1    10.0
   )
}

Each line in within the "chi" matrix valued parameter contains a pair of monomer type indices (or row and column indices) followed by the a value for the corresponding matrix element. The chi matrix used in this example thus has a nonzero value of 10.0 for the element chi(0,1) that represents interactions between monomers of types 0 and 1. The chi matrix is represented internally as an nMonomer \( \times \) nMonomer symmetric matrix, so it is not necessary to specify a value for chi(1,0) in addition to chi(0,1). Elements that are not listed explicitly in the parameter file are assumed to be zero, so the diagonal elements chi(0,0) and chi(1,1) are implictly set to zero in this example.

Values of diagonal elements of the chi matrix are commonly set equal to zero by convention, though PSCF does not require this. In a system with two types of monomer and vanishing diagonal elements, only one nonzero chi parameter value thus needs to be specified in the parameter file.

Domain :

This example uses the pscf_1d program to simulate a 1D planar geometry, in which variation occurs only along one axis of a Cartesian coordinate system. The block labelled Domain contains information about the spatial domain and discreteization. The parameter xmin and xmax give the minimum and maximum values of the spatial coordinate that define the ends of the 1D domain over which the problem is solved. The value of parameter nx indicates the number of nodes or grid points of an evenly spaced 1D mesh, including nodes at both end points. In this example, the domain is thus discretized using a mesh with 401 notes or 400 spatial steps.

A parameter file for an SCFT calculation performed using the pscf_pc or pscf_pg program to simulate a periodic structure would also contain a "Domain" block in an analogous location in the parameter file. The Domain block such a calculation would normally contain information about the crystallographic lattice system type, the unit cell parameters and the space group as well as well information about the computational mesh.

Iterator :

In this example, the block labelled Iterator contains a single parameter labelled "epsilon". This is a error tolerance that is used to decide when an approximate solution is adequately converged - iteration continues while the total scalar error remains greater than the value of epsilon given in the parameter file.

The Iterator block is a "selectable" block that allows a user to specify a choice of an iteration algorithm from among a list of available alternatives. The name of the desired algorithm is specified by the label that appears in the opening line of the iterator block, on the same line as the opening curly bracket. The label used in this first line of an Iterator block can either be the generic label "Iterator", as in this example, which is used to indicate that the user would like to use the default choice for the iterator algorithm, or it can be the name of the class that implements a specific algorithm. The default iterator algorithm for the pscf_1d program is an Anderson-mixing algorithm that is implemented by a class named AmIterator. This default iterator algorithm can thus be invoked either using the generic label "Iterator", as in the above example, or, more explicitly, by using the class name "AmIterator" as the block label in the first line of the block.

Users of pscf_1d program can also choose either of two other iteration algorithms. A Newton-Raphson algorithm is implemented by a class named NrIterator, while a simple relaxation algorithm for systems with only two monomer types is implemented by a class named BinaryRelaxIterator. The Newton-Raphson iterator often converges in very few steps but the required computational time per step grows quadratically with the number of grid points, and becomes inefficient for very large grids. To choose the Newton-Raphson iterator, the Iterator block in the above example could be replaced by a block such as the following:

NrIterator{
   epsilon 0.00000001
   maxItr  200
}

Here, the use of NrIterator as a block label indicates the choice of a Newton-Raphson algorithm. In this example, the body of the block contain parameters named epsilon and maxItr.

By convention, the first parameter for each iterator algorithm is a required parameter named epsilon that represents an error tolerance.
This is actually the only required parameter for either the AmIterator or NrIterator algorithms. In the above example, we have also included an optional second parameter named maxItr for the NrIterator algorithm that specifies the maximum number of iterations that should be attempted before exiting the iteration loop and giving up.

In general, each iteration algorithm may accept a different list of required and optional parameters, and thus require a different format for the body of the iterator block. The documentation of the parameter file format for each PSCF program lists of all of the available iteration algorithms, and provides links to pages that fuly describe the parameter file format for each algorithm, including all required and optional parameters for each algorithm.

For simplicity, almost all of the examples shown in this user manual use the default iterator algorithm. The default iterator classes for all 3 PSCF programs are currently based on an Anderson-mixing algorithm.
Most examples in this manual thus contain an iterator block that starts with the string "Iterator{" on a line by itself, indicating the use of the default iterator.

Parameter Files (Up) Parameter File - Syntax (Next)