Parameter File - pscf_1d (Prev) Parameter File - pscf_pg (Next)

The pscf_pc and pscf_pg programs for periodic systems use nearly identical parameter file formats, and so are discussed together here. The description given here only covers required and optional elements relevant to SCFT calculations. A complete description of the parameter file format for either of these programs, including optional elements that not relevant to SCFT, is given here.

Example

The example show below is a typical parameter file for using pscf_pc to perform a SCFT calculation for a 3D perodic structure of known space group symmetry of a diblock copolymer melt. This example would also be accepted by the pscf_pg program, which would perform the same calculation while offloading some parts of the calculation to a GPU.

System{
  polymerModel thread
  Mixture{
    nMonomer  2
    monomers[
              1.0
              1.0
    ]
    nPolymer  1
    Polymer{
      type    linear
      nBlock  2
      blocks[
              0  0.15
              1  0.85
      ]
      phi     1.0
    }
    ds   0.01
  }
  Interaction{
    chi(
          1   0   25.0
    )
  }
  Domain{
    mesh             32  32  32
    lattice          cubic
    groupName        I_m_-3_m
  }
  Iterator{
    epsilon      1e-10
    maxItr       100
    maxHist      50
    isFlexible   1
  }
}

This parameter file is designed to initialize a single SCFT calculation for a BCC phase of a single-component diblock copolymer melt. A parameter file for SCFT calculation of a mixture could contain more than one "Polymer" blocks and/or one or more "Solvent" blocks. A parameter file to initialize a parameter Sweep would contain an additional "Sweep" block.

File format

The format of a parameter file used by pscf_pc or pscf_pg to perform a an SCFT calculation is shown in skeleton from below:

System{
  polymerModel*   enumeration  ("thread" or "bead", "thread" by default)
  Mixture{ ...  }
  Interaction{ ...  }
  Domain{ ...  }
  Environment#*{ ...  }
  Iterator#*{ ... }
  Sweep#*{ ... }
}

The above skeleton includes only blocks that are relevant for SCFT calculations, and excludes optional elements that are only relevant to PS-FTS calculations. A complete description of the format for the main System block is given here.

polymerModel : The polymerModel entry is an optional enumeration parameter with allowed values of "Thread" and "Bead" that specify global use of either the continuous thread or discrete bead model. If this parameter is omitted, the thread model is used by default.

Iterator and Sweep : The Iterator and Sweep blocks are both optional and selectable, but an Iterator block must be present in order to perform an SCFT calculation. The Sweep block is only needed if one intends to peform an SCFT parameter sweep.

Formats of the Mixture and Interaction blocks are the same for all PSCF programs, and have thus been discussed previously. Below, we discuss the contents of the Domain, Iterator, and Sweep blocks.

Domain block

The Domain block contains information required to describe the unit cell of a periodic structure, the regular mesh that is used to discretize fields within each unit cell, and (optionally) an identifier for the space group of the desired solution. The parameter file format is discussed below, as well as in separate page here.

An example of the format of this block is shown below:

Domain{
  mesh        32  32  32
  lattice     cubic
  groupName   I_m_-3_m
}

The format for this block is

Domain{
   mesh        [int(D)] (D integer elements)
   lattice     string
   groupName*  string
}

The groupName parameter is optional, but must be included to enable SCFT calculations that seek a solution of specified space group symmetry. The mesh and groupName parameter lines are discussed separately below.

mesh

The value of the variable "mesh" is a vector of integers on a single line that specify the number of grid points along each direction of the uniform spatial mesh used to discretize fields within each unit cell of the crystal. The number of integers is equal to the dimensionality D of the periodic unit cell. The format is

mesh N[0] .... N[D-1]

where N[i] is the number of grid points along axis number i, for i = 0 ,..., D-1.

The dimensions N[0], ... , N[D-1] of the spatial mesh are initialized to in the parameter file and are immutable thereafter. The only way to run simulations with different mesh sizes is to run pscf_pc and pscf_pg multiple times using different parameters files with different values for the mesh parameter.

lattice

The value of the parameter "lattice" is given by string that specifies the desired crystal system type. The set of allowed values for this string depends on the dimensionality of space. There are 7 allowed values of the lattice string for a 3D structure, corresponding to the 7 types of 3D crystal system, with names given by the strings "cubic", "tetragonal", "orthorhombic", "hexagonal", "rhombohedral", "monoclinic", and "triclinic". The allowed values for a 2D system include "square", "rectangular", "hexagonal" "rhombic" and "oblique". There is only one allowed lattice system for a 1D crystal, which is referred to as "lamellar". A more detailed discussion of each of the possible lattice systems is given in a separate page that documents conventions for unit cells.

The lattice system parameter is initialized by the parameter file and is immutable thereafter.

groupName

The "spaceGroup" is an optional string parameter that, if present, identifies the crystallographic space group for the structure of interest. Each allowed value of the groupName string corresponds to a modified version of the name of a space group, as listed in the international tables of crystallography. In the above example, the groupName string I_m_-3_m is a modified form of the name \(Im\overline{3}m\) for the space group for a BCC lattice. PSCF uses a set of conventions for converting an international table symbol for a space group into a text string that involve insertion of underbars between logical elements and the use of - sign to represent an overbar, among other conventions. Allowed identifiers for crystallographic space groups are listed and discussed in more detail here.

If groupName identifer is present, it is used construct a space group (i.e., a set of symmetry operations) and a symmetry-adapted Fourier basis. A symmetry-adapted Fourier basis is a set of functions of position that are all eigenfunctions of the Laplacian and are all invariant under all symmetry operations in the specified space group, which can be used as a basis for expanding functions with the specified symmetry. The algorithm used to construct such a basis requires knowledge of a set of initial values for the unit cell parameters. This symmetry-adapted basis is thus normally constructed immediately after the first time unit cell parameters are initialized, e.g., by reading the values given in a file that contains a description of a field.

If a groupName parameter is present in the parameter file, it is immutable after the parameter file is processed. Simulations of structures with different space groups must be performed separately, by running pscf_pc or pscf_pg multiple times with different parameter files.

Unit cell parameters (absence from parameter file)

To completely describe the Bravais lattice for a crystal with a known crystal system, one must assign values to a list of unit cell parameters that give the lengths of the edges of the unit cell and, for some lattice systems, angles between some of these edges. The number of unit cell parameters required to describe a unit cell is different for different lattice system. For example, a 3D cubic crystal can be described using a single parameter that gives the length of any edge of a simple cubic unit cell. Three parameters are required to describe an orthorhombic unit cell, to specify lengths of three orthogonal Bravais basis vectors, while 6 parameters are required for a triclinic unit cell, to specify 3 independent unit cell lengths and 3 angles. The unit cell parameters for each unit cell type are stored internally in an array that lists the required parameters in some pre-specified order. Conventions for the meaning of the required parameters and the order in which they are listed are described for each crystal system in a separate page of documentation about unit cells.

Values for unit cell parameters are specified within the header section of files that describe periodic chemical potential fields (w-fields) or monomer concentration fields (c-cields). Values for these parameters are not, however, provided in the parameter file. Unit cell parameters are thus normally first assigned values during execution of the first command in the command file that causes the program to set the chemical potential fields for the program, by reading these fields from a file. Unit cell parameters can also be set explicitly using a command named SET_UNIT_CELL users may invoke to manually set or reset the unit cell parameter values at any point during processing of a command file.

If the Domain block of the parameter file contains a space group name, a symmetry-adapted Fourier basis for that space group is constructed immediately after the first time that unit cell parameters are assigned initial values by either mechanism, e.g., either the first time that the w-fields are set by reading these fields from a file or the SET_UNIT_CELL command is invoked).

Unit cell parameters for a crystal are changed many times during SCFT calculations for systems with flexible unit cells, in which the unit cell parameters are adjusted so as to minimize the free energy density. At the end of such a calculation, converged values for the optimal unit cell parameters are normally output within the header of a file that contains the converged w-fields.

Environment

The Environment block is an optional selectable block that can be used to define a mask and/or external potential fields in order to define an inhomogeneous externally imposed environment, as described in detail here. An environment can be used to describe a confined environment such as that experienced by a thin film. This block is not needed for standard SCFT calculations involving bulk periodic phases.

Iterators

The default Iterator for the pscf_pc and pscf_pg programs is based on an algorithm that uses an Anderson-Mixing (AM) iterator algorithm, and that imposes a specified space group symmetry. This default iterator can be invoked in pscf_pc using either the generic label "Iterator" or the specific label "AmIteratorBasis". This is currently the only iterator available in pscf_pc. A description of the parameter file format for this iterator is given here.

The AmIteratorBasis is designed to search for a solution with a specified space group symmetry, and can only be used with a parameter file that contains a valid groupName parameter. The pscf_pg program, however, also provides an Anderson-Mixing algorithm named AmIteratorGrid that does not impose any space-group symmetry, and that can be used with a parameter file that does not contain a groupName string.

The Iterator block of the parameter file is formally optional (i.e., the program will finish reading the parameter file if it is omitted), but is required to enable SCFT calculations. An Iterator block is not needed to peform a field theoretic simulation.

Sweep

The Sweep block is another a block that (like the Iterator block for pscf_pc) has been programmed as a selectable block, but for which there is currently only one available algorithm. The only sweep algorithm that is currently available for use with either pscf_pc or pscf_pg is a general linear sweep algorithm, which is also the default algorithm. Such a linear sweep can thus be enabled by including a block that starts either with the generic label "Sweep" (as done in any examples shown here that include a sweep block) or the specific label "LinearSweep". The format of the associated parameter file block is described here.

Example

File format

Domain block

Environment

Iterators

Sweep

See Also: