Algorithms (Prev) Command File (Next)

PSCF can perform partial saddle-point field theoretic simulation (PS-FTS) using either Brownian dynamics (BD) or Monte Carlo (MC) sampling methods. Parameter file formats for these two types of simulations share a common overall structure that is described in the remainder of this page, along with examples for both types of simulation and discussion of the differences.

Example: BD Simulation

Shown below is an example of a complete parameter file for a BD simulation of a symmetric diblock copolymer melt. The first three blocks within the main System block are Mixture, Interaction and Domain blocks that are very similar to the corresponding blocks of an SCFT parameter file. These three blocks specify all of the physical parameters and the computational domain for the problem of interest. The new element, relative to an analogous SCFT parameter file, is the existence of a large BdSimulator block after the Domain block. In a parameter file for BD simulation, the BdSimulator block contains all information that is required by algorithms used in a BD simulation, but that is not needed for an SCFT calculation. A parameter file an MC simulation would instead contain a block labelled "McSimulator" in this location, which would contain analogous information required by MC simulation algorithms.

System{
  Mixture{
    nMonomer  2
    monomers[
             1.0
             1.0
    ]
    nPolymer  1
    Polymer{
      type    linear
      nBlock  2
      blocks[
              0   0.5
              1   0.5
      ]
      phi     1.0
    }
    vMonomer  0.01
    ds   0.02
  }
  Interaction{
    chi(
        1   0   18.0
    )
  }
  Domain{
    mesh         40    40    40
    lattice      cubic
  }
  BdSimulator{
    seed           486893701
    BdStep{
      mobility  5.0E-2
    }
    Compressor{
      epsilon      1.0e-4
      maxHist      40
    }
    AnalyzerManager{
 
      StepLogger{
        interval        20
      }
 
      HamiltonianAnalyzer{
        interval        10
        outputFileName  out/hamiltonian
      }
 
    }
  }
}

The above parameter file could be used by either the pscf_pc or pscf_pg program, which provide identical capabilities and identical user interfaces for PS-FTS calculations.

Parameter File Structure (Overview)

A parameter file used to initialize a BD or MC PS-FTS calculation must begin with Mixture, Interaction and Domain blocks similar to those in a corresponding SCFT parameter file, as in the above example. To enable either type of stochastic simulations, the file must also contain a selectable "Simulator" block. This Simulator block may be either a "BdSimulator" block, for BD simulations, or an "McSimulator" block, for MC simulation. The BdSimulator and McSimulator blocks use analogous but slightly different formats, which must differ somewhat because they contain computational parameters for different types of sampling algorithms.

The format of the main System block of any pscf_pc or pscf_pg parameter file, including all allowed elements, is shown below in skeleton form:

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

Note that only the Mixture, Interaction, and Domain blocks are required. The optional Iterator and Sweep blocks are only used for SCFT calculations, and so would normally be omitted from a parameter file used to initialize a BD or MC simulation. The "Simulator" block is an optional, selectable block that is only used only for FTS, and is thus normally omitted from parameter files used for SCFT calculations.

The typical format of a parameter file for a Brownian dynamics simulation, is thus, in skeleton form:

System{
  Mixture{ ... }
  Interaction{ ... }
  Domain{ ... }
  BdSimulator{ ... }
}

This is a skeleton representation of the format used in the example shown above. The corresponding format of a typical parameter file for MC simulation is:

System{
  Mixture{ ... }
  Interaction{ ... }
  Domain{ ... }
  McSimulator{ ... }
}

Formats of the various blocks within these skeletons are discussed below.

Mixture, Interaction and Domain Blocks

The Mixture, Interaction, and Domain blocks of a parameter file for a PS-FTS calculation are nearly identical to the corresponding blocks of an SCFT parameter file. The required format for the Interaction block is identical to that used for an SCFT calculation. The only differences in the Mixture and Domain blocks are noted below:

vMonomer (presence) : The Mixture block used for a PS-FTS calculation must include a value for a parameter named vMonomer, which gives the monomer reference volume in an incompressible system, also denoted in mathematical formalus by \( v \) . This is an optional parameter that is not needed for most SCFT calculations, and so is usually omitted from SCFT parameter files. In a FTS, however, the value of \( v \) (or vMonomer) controls the magnitude of field fluctuations about a saddle-point configuration, which become small in the limit \( v \rightarrow 0 \). In a simulation of a melt of block polymers of length \( N \) in which all monomers have a common statistical segment length \( b \), the value of vMonomer determines the so-called invariant degree of polymerization
\[ \overline{N} = N (b^{3}/v)^{2} \quad, \]

which is a dimensionless parameter that controls the magnitude of deviations from SCFT. The vMonomer parameter appears immediately after the Polymer blocks and Solvent blocks (if any) that describe the chemical constituents of the system. If the vMonomer parameter is omitted, it is set to vMonomer = 1.0 by default, which is usually not what one wants.
Space group (absence) : For a FTS, one normally does not assume the existence of any space group symmetry for the fields, because the stochastic field fluctuations will never exactly preserve any of the space group symmetries characteristic of many SCFT solutions. The optional spaceGroup parameter of the Domain block must thus be omitted from an FTS parameter file.

The periodic unit cell used in a PS-FTS calculation is often larger than that used for SCFT calculations. In either context, the lattice type and unit cell parameters describe the overall periodic computational unit cell. In SCFT calculations, this computational unit cell is usually designed to contain a single crystallographic unit cell of a periodic structure, using lattice parameters that are adjusted to minimize the free energy density. In a FTS, however, the computational unit cell is often taken to be large enough to contain multiple unit cells of any expected ordered structure. In either type of calculation, the lattice type of the computational unit cell (cubic, orthorhombic, etc.) is specified in the parameter file by the "latice" string parameter, while values for unit cell parameters (i.e., lengths and angles) are normally given in the header of the file containing the initial w field configuration.

Brownian Dynamics: BdSimulator Block

The BdSimulator and McSimulator parameter blocks share a common internal structure, except for differences in the sub-block that specifies details of the actual BD or MC sampling algorithm.

Parameter formats for both types of Simulator block include optional Perturbation and Ramp blocks that are not needed for simple simulations but are included in the format descriptions given here for the sake of completeness.

The parameter file format for the BdSimulator block in a parameter file for a BD simulation is given in skeleton form below:

BdSimulator{
  seed* int
  BdStep#*{ ... }
  Compressor#*{..}
  Perturbation#*{..}
  Ramp#*{..}
  AnalyzerManager*{ .... }
}

Elements of this block are discussed below.

seed **: The optional seed parameter provides an integer seed for a random number generator. If it omitted, a seed will be generated automatically, using a clock time as an input. This parameter is often omitted.

The BdStep, Compressor, and AnalyzerManager blocks contain parameters for, respectively, the BD step algorithm, the compressor algorithm, and any associated data analysis operations. The AnalyzerManager block, if present, contains one or more nested subblocks that each specify a specific analysis operations, as discussed below.

The BdStep and Compressor blocks are marked as optional in the above format description, but must both be present in order to actually run a BD simulation. If the BdStep block is present, then the Compressor block is required. If both of these block are absent, the program will be able to successfully read the parameter file, but an error will occur if a SIMULATE command is encountered in the command file. These two blocks are treated as optional during processing of the parameter file because they are not needed for other possible types of calculation. Specifically, they are not needed during postprocessing of a field trajectory file.

The BdStep and Compressor blocks are both selectable. The actual block labels for these parameter file blocks may thus refer to the names of classes that implement particular choices of BD step algorithm and compressor algorithms, rather than the generic names BdStep and Compressor used in the above description.

Perturbation and Ramp blocks are selectable, optional blocks that are not needed for simple simulations of a standard model with fixed parameters. These blocks are omitted from examples discussed on this page.

For reference, here is the BdSsimulator block of the example BD parameter file given above :

BdSimulator{
  seed           486893701
  BdStep{
    mobility  5.0E-2
  }
  Compressor{
    epsilon      1.0e-4
    maxHist      40
  }
  AnalyzerManager{
 
    StepLogger{
      interval        20
    }
 
    HamiltonianAnalyzer{
      interval        10
      outputFileName  out/hamiltonian
    }
 
  }
}

This example uses the default BdStep algorithm, as indicated by the generic label BdStsep in the first line of the selectable BdStep block. The default algorithm is a Leimkuhler-Mathews (LM) Brownian dynamics step algorithm, which could also be selected using the specific class name LMBDStep as a label for this block. This example also uses the default compressor algorithm, as indicated by the use of the generic block label "Compressor". The default compressor algorithm is a linear-response Anderson mixing (LRAM) algorithm that was devised as part of the development of PSCF, which can also be selected using the specific class label LrAmCompressor. We recommend these two algorithm as the current methods of choice for almost all BD simulations.

BD Step Algorithms:

The BD step algorithms that are available for use with pscf_pc or pscf_pg are listed below, with each indicated by the name that would be used as the label of the BdStep parameter file block. Each such label is a clickable link to a file containing documentation of the algorithm and associated parameter file format.

Monte Carlo: McSimulator Block

The parameter file format for the McSimulator block of a parameter file used to initialize an MC simulation may be described schematically as follows:

McSimulator{
  seed*  int
  McMoveManager*{ ... }
  Compressor#*{..}
  Perturbation#*{..}
  Ramp#*{..}
  AnalyzerManager*{ .... }
}

The only difference between this format for McSimulator and the corresponding format for a BdSimulator is the existence of an McMoveManager block in the McSimulator block where a Bdsimulator block would have a selectable BdStep block.

The McMoveManager contains information about a set of MC moves that will be used during a simulation. An McMoveManager is a container for a set of MC move types, one of which is chosen at random at the beginning of each MC step. The McMoveManager parameter file block contains one or more subblocks that each begin with a line containing the name for a specific MC move type. The name of each MC move type is also the name of the C++ class that implements that type of move. The block associated with each MC move type contains any parameters required to define the move. The first parameter in the subblock associated with each MC move type is always a parameter named "probability" that gives the probability of choosing a move of that type at the beginning of each MC step.

Only two types of MC move that are currently implemented in PSCF, which are named RealMove and ForceBiasMove. RealMove is a simple MC move that generates an attempted move by adding independent random changes to the exchange field values at all grid points, The ForceBiasMove is "smart MC" or "force bias" that uses an explicit Euler BD step to generate a proposed MC move.

Below, we show an example of an McSimulator block for a MC simulation analogous to the BdSimulator block of the previous example:

  McSimulator{
    seed           486893701
    McMoveManager{
      ForceBiasMove{
        probability  0.75
        mobility     4.0E-3
      }
      RealMove{
        probability  0.25
        A            0.15
      }
    }
    Compressor{
      epsilon      1.0e-4
      maxHist      40
    }
    AnalyzerManager{
 
      HamiltonianAnalyzer{
        interval        10
        outputFileName  out/hamiltonian
      }
 
      StepLogger{
        interval        20
      }
 
    }
  }
}

The only difference between this McSimulator block and the BdSimulator block shown previously is the appearance of a McMmoveManager block in the location where a BdSimulator would instead contain a BdStep block. Like the BD example, this example uses the default LrAmCompressor algorithm, which is selected by using "Compressor" as a generic block label.

The McMoveManager block from the above example is show separately below:

McMoveManager{
 
   ForceBiasMove{
     probability  0.75
     mobility     4.0E-3
   }
 
   RealMove{
     probability  0.25
     A            0.15
   }
 
}

This block has subblocks labeled ForceBiasMove and RealMove, indicating that the simulation will use both of the currently available move types.

The first parameter in each subblock is the "probability" parameter, which is given a value of 0.75 for the ForceBiasMove and 0.25 for the RealMove. In this example, a ForceBiasMove is thus chosen with 75% probability at the beginning of each step, and a RealMove is chosen with 25% probability.

Other parameters of each MC move are required to specify the typical magnitude of random changes in field values. The "mobility" parameter of the ForceBiasMove gives the value of the Brownian dynamics mobility parameter for the explicit Euler BD step that is used by this algorithm to generate a proposed MC move. The parameter of a RealMove named "A" specifies the root-mean-squared change in the proposed value of the exchange field at each grid point.

MC Move Algorithms: The MC move algorithms that are available for use with pscf_pc or pscf_pg are listed below, labelled by the name that is used in the first line of a corresponding parameter file block. Further information about each MC move can be obtained by clicking on the associated link.

Compressor Block

In both BD and MC simulations, the block that describes the sampling algorithm (i.e., the BdStep or McMoveManager block) is followed by a selectable "Compressor" block. Users may choose from among several available compressor algorithms, the name of which is always given by the first line in the associated block.

The available compressor algorithms are listed below. Users may click on the link associated with each algorithm label to access more a detailed description of each the algorithm, and the format of the associated parameter file block.

The LrAmCompressor is the default choice, and is generally the most efficient of these three options. As the default, the LrAmCompressor may thus be chosen either by using the generic label "Compressor" or the more specific label "LrAmCompressor" in the first line of the relevant parameter file block.

AnalyzerManager

The AnalyzerManager block, if present, contains one or more subblocks that each enable use of an object that performs a data analysis and/or data output operation at regular intervals during a simulation. The underlying C++ objects are instances of subclasses of a base class named "Analyzer", and are generically referred to in the PSCF source code and documentation as analyzer classes or analyzers.

The AnalyzerManager block contains one or more subblocks, each of which enables a particular analyzer algorithm (or class). The first line of each subblock must contain the label of a known analyzer class, followed immediately by a opening bracket.

Each analyzer has a parameter named "interval" that determines determines how frequently the action performed by the analyzer is performed. The action defined by each analyzer is performed when the internal step counter that keeps track of the number of BD steps or attempted MC moves is an integer multipe of its interval parameter. The interval is an optional parameter that is set to 1 by default, but it is often present and set to a value greater than 1 for each analyzer within a parameter file for a BD or MC simulation.

The full format for an AnalyzerManager parameter file block is given here.

Below, we show the AnalyzerManager block for the BD simulation parameter file shown at the beginning of this page:

AnalyzerManager{
 
  StepLogger{
    interval      100
  }
 
  HamiltonianAnalyzer{
    interval        10
    outputFileName  out/hamiltonian
  }
 
}

In this example, the AnalyzerManager block contains subblocks for two analyzers named StepLogger and HamiltonianAnalyzer.

The StepLogger is a simple analyzer that periodically outputs the current value of the step counter (the number of completed BD or MC steps) to the standard output (i.e., to the screen, unless it is redirected). The purpose of this is simply to record the progress of the simulation.

The HamiltonianAnalyzer accumulates statistical information about the value of the field theoretic Hamiltonian, including the mean value, the variance, and a reasonably sophisticated estimate of the statistical error on the mean value. The outputFileName parameter gives the base name for a set of files to which the information accumulated by HamiltonianAnalyzer will be written.

The parameter file block for many analyzers contains a string, often named outputFileName, that specifies the name of a file or the base name of set of files to which results will be written. Different analyzers generally write results to different files.

A list of all of the available analyzers, including links to detailed documentation, was given in earlier the discussion of algorithms .