Parameter File - Format Descriptions (Prev) Parameter File - Parameter Sweeps (Next)

The first subblock of the main System block in every PSCF parameter file starts with a label "Mixture", and is referred to as the Mixture block. The Mixture block describes the chemical composition of the system that is being simulated, and includes a description of the chemical structure of each species in the mixture.

PSCF programs are designed to treat a mixture that may contain one or more polymer species and zero or more solvent point-particle species. Each polymer may be either a linear or acyclic branched block polymer. Polymers and solvents are both constructed from a palette of several types of monomer.

Each monomer type is assigned an integer index and a statistical segment length. Each copolymer block and each solvent species is assigned an integer parameter named monomerId that specifies the type of monomer from which it is constructed. The Mixture block contains information that specifies the structure of each polymer species within the mixture (including information about the length and connectivity of the blocks), the monomer type and volume of each solvent species, and the composition of the mixture.

Example

For reference, here is the Mixture block from the example parameter file shown previously :

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
}

Mixture Block Format

The format for the mixture block in any PSCF parameter file is described somewhat more generally below:

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

The asterisks after the nSolvent and vMonomer labels indicates that these are optional parameters. The number of Polymer subblocks must equal nPolymer, and the number of Solvent subblocks must equal nSolvent. Because the optional parameter nSolvent is set to 0 by default, there cannot be any Solvent subblocks if the nSolvent parameter is absent.

The meanings of parameters and subblocks are described in the following table:

Label	Description
nMonomer	Number of distinct monomer types in the mixture (positive int)
monomers	A 1D array of nMonomer elements in which the value of each element is the statistical segment length of the associated monomer type.
nPolymer	The number of polymer species (positive int).
nSolvent*	The number of solvent (point-particle) species (non-negative int, optional, 0 by default).
Polymer{ ... }	Each Polymer{ ... } subblock describes one Polymer species. The number of such subblocks must equal nPolymer.
Solvent{ ... }	Each Solvent{ ... } subblock contains data for one point-like Solvent species. The number of solvent subblocks must equal nSolvent.
vMonomer*	monomer reference volume (optional, real, 1.0 by default)
ds	Preferred value for the block length step size used to integrate the modified diffusion equation within each block.

Comments:

Monomer types are implicitly assigned integer type identifiers in the order in which they appear in the monomers array, with indices that start from 0. We thus assign an index 0 to the monomer type whose statistical segment length is given as the first element in this array, and index 1 to the second, and so on. These integer monomer type indices are used to elsewhere in the parameter file identify the monomer types associated with each block of each block polymer and with each solvent species type.
Polymer and solvent species are also assigned integer labels in the order in which Polymer and Solvent subblocks appear in the parameter file. The polymer species described by the first Polymer block in the parameter file is thus assigned an index 0, the polymer described by the second block is assigned an index 1, etc. Similarly, the solvent species described by the first Solvent subblock (if any) is assigned an index 0, etc.
The parameter nSolvent (the number of solvent species) may be zero, and is set to zero by default if the parameter does not appear in the parameter file, as noted above. The parameter nPolymer must, however, be greater than zero. Correspondingly, the Mixture block must always contains one or more Polymer subblocks and zero or more Solvent subblocks.
The parameter vMonomer is an optional parameter, and is usually absent from parameter files for standard SCFT calculations. The reasons that it may be neglected in such calculations have been briefly discussed elsewhere. Users are nonetheless given the option of providing a value for vMonomer because an input value for vMonomer is required as an input for some optional outputs of the pscf_fd program (e.g., the total excess free energy of a spherical micelle). It is also included as an optional parameter because the value of vMonomer will be a required input parameter for stochastic field-theoretic simulations that will be implemented in future versions of PSCF.

Technical comments (for users who examine the source code) :

The source code for PCSF is defined within a C++ namespace named Pscf. This top-level namespace contains several enclosed sub-namespaces named Fd1d, Pspc, and Pspg that each contain code specific to a specific implementation of SCFT (i.e., a specific program or family of programs). We refer to these as implementation-level namespaces. This segregation of code associated with different SCFT implementations into corresponding namespaces allows the same class name to be used for analogous classes in different implementations without causing name clashes or ambiguity. When possible, identical or similar parameter file formats are used for the parameter blocks associated with analogous classes used in different SCFT implementations.

Each implementation-level namespace contains a class or class template named Mixture. The Fd1d namespace contains a concrete class named Mixture. The Pspc and Pspg namespaces each contain a class template Mixture<int D>, in which the integer dimensionality of space D is a template parameter. The mixture object used in the pscf_pc2 program for 2D periodic structures is thus an instance of class Pscf::Mixture<2>, where the dimensionality of space is specified by the template parameter D=2. All of the Mixture classes and class templates defined in implementation level namespaces are derived from instances of a base class template named Pscf::MixtureTmpl. All of these Mixture classes use the same parameter file format, which is described above. Most of this format is defined in the member function Pscf::MixtureTmpl::readParameters of the shared base class template.

The array "monomers" is implemented internally as an array of instances of the class Pscf::Monomer, as discussed here.

Polymer

The Mixture block always contains one or more Polymer blocks, each of which contains information about a specific polymer molecule species. The format for a polymer block is

Polymer{
    type*  enumeration  ("linear" or "branched", linear by default)
    nBlock int
    blocks Array [ Block ] (nBlock elements)
    phi*   real  (in range [0,1])
    mu     real  (required if and only if phi is absent)
}

The meaning of different parameters is summarized in the table below:

Label	Description
type	enumeration with allowed values "linear" or "branched" (optional, "linear" by default).
nBlock	Number of blocks in a block polymer.
blocks	array in which each element contains a description of one block, represented internally by an object of type "Block".
phi*	volume fraction of this species (real, optional).
mu	chemical potential of this species (real, must be present if and only if phi is absent).

Comments:

The "type" parameter is an optional enumeration value that can be assigned a value "linear", to specify a linear block polymer, or "branched" to specify a general acyclic branched block polymer. If absent, this parameter is set to "linear" by default.
In the parameter file format for the array blocks, each line of data contains a description of one block of a block polymer, listed in the order of increasing block index. The description of each block is stored internally in an object of type "Block", as indicated by the notation "Array [ Block ]" in the above format description.
The required text representation for each Block in the "blocks" array is different depending on whether the value of the type parameter for the polymer is linear (the default) or branched, as discussed below .
The last parameter in a Polymer block must be either a value for phi, which is the volume fraction occupied by the polymer species, or a value for mu, which is the chemical potential for that species. The block must contain either a phi parameter or a mu parameter in this location, but may not contain both.
When the volume fraction parameter phi is present, its value must lie in the range [0,1].

Descriptions of parameter file formats for individual blocks of linear and branched polymers are discussed separately below.

Technical comment (for users who examine the source code): A Class or class template named Polymer is defined in each implementation-level namespace of the top-level Pscf namespace (i.e., in the Fd1d, Pspc and Pspg sub-namespaces of Pscf). These Polymer classes all use the same parameter file format, which is described above. Each of these Polymer classes is a subclass of an instances of a common class template named Pscf::PolymerTmpl. The readParameters function of this base class template defines the common file format.

Block

The text representation of a block within the "blocks" array in a Polymer parameter file block is different for linear and branched polymers.

Linear Polymers

If the polymer type is linear, then blocks must be listed in the "blocks" array in the order in which they appear along the polymer, starting from one end. In this case the data required in each line of the blocks array is of the form

monomerId length

where monomerId is an integer and length is a real number. The meanings of these variable values are described in the following table:

Variable	Type	Description
monomerId	int	monomer type index for all monomers in this block
length	real	length of this block

The "length" of a block is defined in PSCF to be proportional to the volume occupied by the block within an incompressible mixture. Monomer units must be defined PSCF such that monomers of different types occupy the same volume, which we refer to as the monomer reference volume. The length of a block is defined to be the ratio of the volume occupied by the block to the monomer reference volume. This block length is thus also equal to the number of monomers in the block.

Branched Polymers

If the polymer type id branched, then the information in the "blocks" array of a Polymer block must contain a description of the topology of the polymer, as well as the monomer type and length of each block. A branched block polymer is described in PSCF using the language of graph theory as an acyclic graph consisting of a set of vertices connected by edges. Each "edge" in this graph corresponds to a block of the polymer, and each vertex corresponds to either a free chain end or a junction at which two or more blocks are connected. A linear or branched block polymer with nBlock blocks is thus described by an acyclic graph containing nBlock edges in which each edge (or block) connects a specific pair of such vertices. For example, a linear block polymer with nBlock blocks contains two chain ends and nBlock - 1 junctions, giving nBlock + 1 vertices.

A standard theorem of graph theory states that any acyclic graph with N edges must have exactly N+1 vertices. As a result, we know that any acyclic block polymer with nBlock blocks has exactly nBlock + 1 vertices. In the description of polymer structure used by PSCF, each vertex is assigned a unique integer vertex index in the range [0, nBlock], and each block is assigned a unique index in the range [0, nBlock-1]. Each block connects a specific pair of vertices that may be identified by their integer vertex indices, each of which may be either a junction or chain end.

The data format for a block in a branched polymer is of the form

monomerId length vertexId0 vertexId1

Here, monomerId and length have the same meanings as for a linear polymer, while vertexId0 and vertexId1 are indices for the two vertices to which the block is attached.

In the special case of a linear polymer with nBlock blocks, the structure of the polymer is stored internally as a graph in which block number i connects vertices i and i+1, for all i from 0 to nBlock - 1. Because the topology is known, information about blocks in a linear polymer may use a simpler text representation.

Example: As a simple example of a branched polymer, consider a pure melt of pure ABC star terpolymer that contains three chemically distinct blocks connected at a central junction, for which nBlock = 3. For simplicity, assume that the three blocks in this polymer have monomer types indices 0, 1 and 2. Let vertices 0, 1, and 2 represent the free ends of the blocks with monomer types 0, 1, and 2, respectively, and let vertex 3 be the central junction. For simplicity, we set the lengths of each block to 1.0. The Polymer block for such a star polymer within the parameter file would look like this:

Polymer{
  type branched
  nBlock 3
  blocks[
           0   1.0    0   3
           1   1.0    1   3
           2   1.0    2   3
  ]
  phi  1.0
}

Note that the type parameter must be explicitly set to "branched", because the type is set to linear by default. We have set phi = 1.0 in this example on the assumption that this is a one-component terpolymer melt, for which the volume fraction of this species must equal unity.

Technical comment (for users who examine the source code): A class or class template named Block is also defined in every implementation-level namespace. All of the Block classes are subclasses of a base class named Pscf::BlockDescriptor. The data for each line of the "blocks" array is read in using an overloaded insertion (>>) operator for a BlockDescriptor, which defines the text representation of the data required in a single line of the "blocks" array.

Solvent

A mixture block may contain zero or more Solvent blocks, each of which contains data about a small-molecule solvent species. Solvent species are treated in PSCF as point-like particles that occupy a specified volume (or "size"), for which the interactions with other components can be described by assigning the solvent a monomer type index.

Solvent blocks should be present if and only if the optional parameter nSolvent is present and is assigned a positive value. When nSolvent is absent, it is set to 0 by default. If nSolvent > 0, then exactly nSolvent Solvent blocks must appear within the Mixture block immediately after the Polymer blocks.

The format for a single solvent block is

Solvent{
   monomerId   int
   size        real
   phi*        real
   mu          real (required iff phi is omitted)
}

The monomerId is a monomer type index that identifies the solvent as containing a specified monomer type. The size parameter gives the volume occupied a solvent molecule, in units in which the monomer reference volume is equal to unity. For each solvent, a value must be specified for either the volume fraction phi occupied by the species, or its chemical potential mu. It is an error to specify both phi and mu or to omit both variables.

Technical comment (for users who examine the source code): A Class or class template named Solvent is defined in each implementation-level namespace (i.e., in the Fd1d, Pspc and Pspg sub-namespaces of Pscf). These classes are all use the same parameter file format, which is described above, and are all subclasses of a common base class named Pscf::SolventDescriptor. The function Pscf::SolventDescriptor::readParameters defines most of this file format.

Parameter File - Format Descriptions (Prev) Parameter Files (Up) Parameter File - Parameter Sweeps (Next)