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 setting up an SCFT calculation for a perodic structure of known space group symmetry of a diblock copolymer melt using either pscf_pc or pscf_pg.

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

File format

The main System block of a parameter file for an SCFT calculation peformed using pscf_pc or pscf_pg has the same overall structure as that used for pscf_1d. The required elements for an SCFT calculation can be described by the format skeleton:

System{
  Mixture{ ...  }
  Interaction{ ...  }
  Domain{ ...  }
  Iterator#*{ ... }
  Sweep#*{ ... }
}

As for pscf_1d, the Sweep block is optional, and Iterator and Sweep blocks (if present) are both selectable blocks. The above skeleton includes only blocks that are relevant for SCFT calculations, and excludes some optional elements that are used for FTS calculations. A complete description of the format for the main System block of pscf_pc parameter file is given here.

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        Array[int] (D 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 unitCell, mesh and groupName parameter lines are discussed separately below.

mesh

The value of the variable "mesh" is a vector of integers that specifies 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 the values given in the parameter file and cannot be changed during the lifetime of a program, except by rerunning the program with a modified parameter file.

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.

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.

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 parameters that give the lengths of the edges of the unit cell and, for some crystal 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 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 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 not specified in the parameter files for pscf_pc or pscf_pg. These parameters values are instead specified within the header section of files that describe periodic chemical potential fields (w-fields) or monomer concentration fields (c-cields). The unit cell parameters are thus normally first assigned values during execution of the first command in the command file that causes the program to read such a field from file. There also exists a command named SET_UNIT_CELL that a user can 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., the first time a field is read 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.

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

Iterators

Sweep

See Also: