Parameter File - Format Descriptions (Prev) Parameter File - Domain Block (Next)
The first subblock of the main System block in every PSCF parameter file is required block that 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 :
Format
All three PSCF programs use very similar format for the Mixture block. The pscf_r1d and pscf_rpc programs use identical formats for this block, which was discussed on the previous page . The format used by the pscf_rpg program accepts one additional optional parameter named useBatchedFFT the end of the block. The format of the Mixture block used by pscf_rpg is shown below
The asterisks after nSolvent, Solvent, vMonomer and useFFTBatched labels indicates that these are optional parameters or subblocks. The ellipses after the Polymer and Solvent blocks are used here to indicate that the Mixture block may contain several subblocks of each type. 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, no Solvent subblocks may be present 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{ ... } block describes one polymer species. The number of Polymer blocks must equal nPolymer. |
| Solvent{ ... } | Each Solvent{ ... } block describes one point-like solvent species. The number of Solvent subblocks must equal nSolvent. |
| vMonomer* | monomer reference volume (optional, real, 1.0 by default) |
| ds | Target value for the block length step size used to integrate the modified diffusion equation within each block. The ds parameter is required for the thread model and prohibited for the bead model. |
| useBatchedFFT* | For pscf_rpg, this boolean flag controls a purely computational option that is discussed on a separate page. This parameter may only appear in pscf_rpg parameter files (optional, 1 or true by default) |
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 nPolymer (the number of polymer species) must be a positive integer. Every mixture must contain at least one polymer species.
- The parameter nSolvent (the number of solvent species) may be zero, and is set to zero by default if the nSolvent parameter is absent.
- 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. A value for vMonomer is, however, normally needed as an input parameter for stochastic PF-FTS calculations. A value of vMonomer is also needed as an input in the calculation of some optional outputs of the pscf_r1d program, such as the total excess free energy of a spherical micelle.
- The parameter ds is required when the thread model is being used, but may not appear when the bead model is being used. The pscf_r1d program can only use the thread model, and so always requires a "ds" parameter. For the pscf_rpc and pscf_rpg programs, the choice of bead or thread model is determined by the value of the polymerModel parameter, which is the first (optional) element of the main System block, which appears before the Mixture block.
- In the numerical solution of the modified diffusion equation (MDE) for the thread model, the contour length of each block is divided into an even number of steps of equal length. The number of such steps is chosen for each block so as to give an actual contour length step length that is as close as possible to the value of ds given in the parameter file. The input parameter ds is thus a target value for the step size, which is not necessarily equal to the actual contour length step size used for any particular block.
- The format for the Mixture block used by pscf_rpg has one additional optional algorithm parameter named usedBatchedFFT, which appears at the end of the Mixture block format used for this program. This is a purely computational parameter whose meaning is discussed on a separate page. Use of the default value of 1 (or true) saves a bit of computational time at the cost of additional memory usage. The default value is appropriate on modern GPUs for all but the largest problems, so this parameter may usually be safely omitted.
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 namespaces named Prdc, R1d, Rpc, and Rpg. Namespace Pscf::Prdc contains code relevant to problems involving periodic boundary conditions, which is used to construct both pscf_rpc and pscf_rpg. The enclosed namespaces named R1d, Rpc, and each contain code that is only used by one executable program (e.g., pscf_r1d, pscf_rpc or pscf_rpg, respectively).
We refer to the enclosed namespaces R1d, Rpc, and Rpg throughout this documentation as program-level namespaces, because each contains files that are only used within a single executable program. By convention, code defined in a program-level namespace may not use names defined in another program-level namespace. The segregation of code associated with different executable programs into separate namespaces allows identical names to be used for several analogous classes in different program-level namespaces without causing name clashes or ambiguity.
Each program-level namespace contains a class or class template named Mixture. The R1d namespace contains a class named Mixture. The Rpc and Rpg namespaces each contain a class template Mixture<int D>, for which the integer dimensionality of space D is a template parameter. The Mixture object used by the pscf_rpc program to treat a 2D periodic structure is thus a instance of class Pscf::Rpc::Mixture<2>, for which the dimensionality of space is specified by the template parameter D=2. All of the Mixture classes and class templates defined in program-level namespaces are derived from instantions of a base class template named Pscf::MixtureTmpl. All of these Mixture classes use very similar parameter file formats, as described above. Most elements of this format are 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 must contain one or more Polymer blocks, each of which contains information about a specific polymeric molecular species. The format for a Polymer block is
The meaning of different parameters is summarized in the table below:
| Label | Description |
| type* | enumeration with allowed text representations "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 of a block polymer |
| phi* | volume fraction of this species (optional). |
| mu* | chemical potential of this species (required if and only if phi is absent). |
Comments:
- The "type" parameter is an optional enumeration value that can be assigned a text 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 Polymer block must contain either a phi parameter or a mu parameter in this location, and 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 program-level namespace of the top-level Pscf namespace (i.e., in the R1d, Rpc and Rpg sub-namespaces of Pscf). These Polymer classes all use the same parameter file format, which is described above. Each of these Polymer classes is indirectly derived from a common base class named Pscf::PolymerSpecies. The inherited member function Pscf::PolymerSpecies::readParameters defines this shared parameter file format.
Block
Each line in the "blocks" array of a Polymer parameter file block contains information about a single block with a block polymer. The required format for each block depends on whether the polymer type is "linear" (the default) or "branched".
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 takes a slightly different form when using a thread model or a bead model.
Thread model: For the thread model, each line of the blocks array for a linear polymer must have the form
where monomerId is the monomer type index for monomers in the block, and length is a real number giving the contour length of the block.
Bead model : For the bead model, each line of the blocks array for a linear polymer has the form
where monomerId is the monomer type index for all beads (or monomers) in the block, and nBead is the integer number of beads in the block.
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 | contour length of this block (thread model) |
| nBead | int | number of bead in the block (bead model) |
The only difference between formats used for thread and bead models is the use of a floating point number "length" or an integer "nBead" to specify the block length.
Branched polymers
If the polymer type is branched, then the information in the "blocks" array of a Polymer block must contain a description of the connectivity of blocks within the polymer, as well as the monomer type and length of each block. As discussed previously, a branched polymer is described in PSCF as an acyclic graph consisting of a set of vertices with integer labels connected by "edges", in which each edge corresponds to a block, and each vertex is a junction or chain end. An acyclic connected polymer with nBlock blocks always contains exactly nBlock + 1 vertices. To describe a branched polymer with nBlock blocks, the user must associate each vertex with unique index in the range 0, ..., nBlock. Each block connects a specific pair of vertices that may be identified by their integer vertex indices. The parameter file format for a block in a branched polymer differs from that used for a linear polymer in that the data for each block must include the indices of the two attached vertices.
Thread model: : In the thread model, the line associated with each block in the "blocks" array for a branched polymer must be of the form
where monomerId and length are the integer monomer type index and floating point length of the block, while vertexId0 and vertexId1 are integer indices of the two vertices to which the block is attached.
Bead model: : In the bead model, each line in the "blocks" array for a branched polymer is of the form
where nBead is the integer number of beads in the block, and the meaning of monomerId, vertexId0 and vertexId1 are the same as for the thread model.
For either the thread or bead model, the only difference between the formats used for branched and linear polymers is that the format for a branched polymer contains the indices of the two attached vertices at the end.
Example: As a simple example of a branched polymer, consider a one-component melt containing an ABC star terpolymer that contains three chemically distinct blocks connected at a central junction. For simplicity, let 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 monomers of types 0, 1, and 2, respectively. Let vertex 3 be the central three-fold junction. As an example, we use the thread model and set the length of each block to 1.0.
The Polymer block for such a star polymer would look like this:
Note that the type parameter must be explicitly set to "branched" for this species, 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.
In the bead model, a corresponding description of an ABC star terpolymer would differ from that given above only in that the length of each block would have to be given as an integer number of beads. For example, for an ABC star polymer in which each block has 50 beads, the floating point length of 1.0 given in each line of the blocks array would be replaced by an integer value of 50.
Technical comment (for users who examine the source code): A class or class template named Block is defined in each of the program-level namespaces, Pscf::R1d, Pscf::Rpc and Pscf::Rpg. Each such Block class is derived from a common base class named Pscf::Edge. The data for each line of the "blocks" array is read in using an overloaded insertion (>>) operator for an Edge, which is a function with an interface std::istream& Pscf::operator>>(std::istream&,Pscf::Edge&) . The implementation of this insertion operator thus defines the text representation of the data required in a single line of the "blocks" array in any PSCF program. The required text representation depends both on whether the block is part of a linear or branched polymer, and on whether the program is using the thread or bead model.
Solvent
A Mixture block of a parameter file may contain zero or more Solvent blocks, each of which describes a small-molecule solvent species. Solvent species are treated in PSCF as point-like particles that each occupy a specified volume (or "size"). Interactions of solvents with polymers and other solvents is 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, this parameter 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
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 either specify values for both phi and mu or to omit both parameters.
Technical comment (for users who examine the source code): A class or class template named Solvent is defined in each of the program-level namespaces, Pscf::R1d, Pscf::Rpc and Pscf::Rpg. Each such class or class template is derived from a common base class named Pscf::SolventSpecies. The parameter file format that is described above, which is used by all PSCF programs, is defined by the inherited member function Pscf::SolventSpecies::readParameters .
Parameter File - Format Descriptions (Prev) Parameter Files (Up) Parameter File - Domain Block (Next)
Generated on for PSCF by
1.14.0