|
PSCF v1.1
|
Command Files (Prev) Commands - pscf_pc (Next)
This page describes the commands accepted by the pscf_fd program. We begin by showing simple examples of complete command files.
Here is a example of a command file for a single SCFT calculation performed with pscf_fd. The example assumes the use of a convention for locations of input and output files in which the initial guess for the w field is located in a subdirectory of the current working directory named "in", and in which all outputs are written to files in a subdirectory named "out".
The effect of each command in this example is described below:
All pscf_fd that read or write field files use the same field file format, described here. The last line in every PSCF command script must be a FINISH command. Anything that appears after the FINISH command will be ignored.
Here is an example of a command file to perform a sweep. The SWEEP command can only be used if the parameter file that was read by pscf_fd before reading this command file contains an appropriate Sweep block.
The command "READ_W_BASIS in/w.bf" instructs the program to read an initial guess for the chemical potentials fields at the initial state of the sweep (the state s=0) from the file in/w.bf.
The SWEEP command actually executes the sweep operation.
Note that this example command file for a sweep does not contain any of the explicit output commands that are shown as part of the example for a single SCFT calculation. These output commands are unnecessary for a sweep because information about the solution at each step in the sweep is instead automatically output as part of the implementation of the sweep operation. Adding output commands that output data after the SWEEP command would in any case only output information that describes the solution for the final state point of the sweep, for which s=1.
The following table shows a list of available commands for pscf_fd, along with descriptions of any required parameters and the action initiated by each command:
| command | parameter(s) | action |
| Field Input | ||
| READ_W | filename [string] | Read w fields from specified file (filename) |
| Computation | ||
| COMPUTE | Solve the modified diffusion equation for current w fields, without iteration. | |
| ITERATE | Iteratively solve SCFT equations, using current w fields as an initial guess. | |
| SWEEP | Perform a sweep, as specified by the Sweep object in the param file. | |
| Data Output | ||
| WRITE_PARAM | filename [string] | Write param file associated with the current system. excluding any Sweep block |
| WRITE_THERMO | filename [string] | Write thermodynamic data (free energy, pressure, phi, and mu for each species) to file filename. If this file already exists, append thermodynamic data to the end of the file. |
| Field Output | ||
| WRITE_W | filename [string] | Write chemical potential (w) fields to file filename |
| WRITE_C | filename [string] | Write monomer volume fraction (c) fields to file filename |
| WRITE_BLOCK_C | filename [string] | Write volume fraction fields (c fields) for all individual polymer blocks and solvent species to file filename. |
| Propagator Output | ||
| WRITE_Q_SLICE | filename [string], ip[int], ib[int], id[int], is[int] | Write a single "slice" of a propagator at fixed contour step number is, for direction id (id=0 or 1), block number ib, and polymer number ip to a file named filename. |
| WRITE_Q_TAIL | filename [string], ip[int], ib[int], id[int] | Write the final slice (or "tail") of the propagator for direction id (id=0 or 1), block ib, and polymer ip to file filename. |
| WRITE_Q_VERTEX | polymerId [int], vertexId [int], filename [string] | Write product of incoming propagators fields for a specified vertex (vertexId) in a specified polymer (polymerId) to file filename. |
| WRITE_Q | filename [string], ip[int], ib[int], id[int] | Write an entire propagator (all slices) for direction id (0 or 1), block ib, and polymer ip to a file named filename. |
| WRITE_Q_ALL | basename [string] | Write all propagators for both directions of all blocks of all polymers to separate files with automatically generated filenames that begin with a common prefix given by the basename parameter. |
| Mesh Manipulation | ||
| REMESH_W | nx [int], outfile [string] | Write current w fields interpolated onto a new mesh with nx nodes to output file "filename" |
| EXTEND_W | m [int], filename | Write w fields extended to a mesh with m additional nodes with values that repeat values at the current last grid point, to output file "filename". |
| Compare to Homogenous Reference | ||
| COMPARE_HOMOGENEOUS | mode [int] | Compare solution to a homogeneous solution |
Individual commands and related groups of commands are discuss below in greater detail:
READ_W : The first command in a command file is usually a READ_W command, which takes the name of an input file as an argument. This command reads an initial guess for the chemical potential fields ("w fields") from the specified file and assigns the current values for these fields equal to the values read from this file.
The COMPUTE, ITERATE and SWEEP commands each perform a computation that requires an initial value for all w fields as an input. Each of these commands must thus be preceded by a READ_W command that initializes the w fields.
COMPUTE : The COMPUTE command performs a computation of the single molecule partition functions and monomer concentrations for a system of non-interacting molecules subjected to the current w-fields. This requires a solution of the modified diffusion equations for both directions for all blocks of each polymeric species and a simpler calculation of concentrations for each solvent species. The COMPUTE command does not modify the w fields, but does modify the volume fraction fields (c fields) associated with polymer blocks, solvent species and monomer types. The resulting c fields generally do not satisfy the self-consistenct field conditions.
ITERATE : The ITERATE command attempts to obtain a solution to the self-consistent field equations for a fixed set of parameters by iteratively adjusting the w fields. The choice of iteration algorithm is specified by the Iterator block of the parameter file. Each iteration usually requires at least one calculation similar to that performed once by the COMPUTE command.
SWEEP : THE SWEEP command attempts to solve the SCFT equations at a sequence of points along a path through the space of possible choices of input parameters. This command can only be invoked if the parameter file contains a SWEEP block, which defines the desired sequence of state points.
The WRITE_PARAM and WRITE_THERMO commands can be used to create a record of the input parameters and computed thermodynamic properties associated with a single SCFT calculation.
WRITE_PARAM : The WRITE_PARAM writes a slightly modified copy of the parameter file to a file whose name is given as a command parameter. The version of the parameter file written by this command outputs the current values for all parameters, and excludes any Sweep block.
WRITE_THERMO : The WRITE_THERMO command outputs a report of values for thermodynamic properties obtained after solution of a SCFT problem. The details of the output of this command can be found on the Thermodynamic Properties page.
If the file whose name is passed to the WRITE_THERMO command already exists, the report of thermodynamic properties will be appended to the end of this file, rather than overwriting the file. This is designed to allow users to output a parameter file block that contains the input parameters followed by a report of computed thermodynamic properties in a single file, if desired, by invoking WRITE_PARAM and WRITE_THERMO with the same file name parameter. The example command file shown above uses this pattern, by providing the same filename "out/data" as a parameter for both the WRITE_PARAM and WRITE_THERMO commands.
The following commands can be used to output information about chemical potential and concentration fields after solving a SCFT problem.
WRITE_W : Writes the current chemical potential fields (w fields) for all monomer types to an output file whose name is specified as a command parameter.
WRITE_C : Writes the current volume fraction / concentration fields for all monomer types to a specified output file.
WRITE_BLOCK_C : Writes the current volume fraction / concentration fields for all polymer blocks and monomer species to a single file, with the field associated with each block or solvent species written in a different column.
The information provided by the WRITE_BLOCK_C command is generally different than and more detailed than that provided by the WRITE_C command. The difference becomes relevant if and only if both commands are applied to a system in which any monomer type id is assigned to two or more blocks (on the same or different polymers) and/or solvent species. In this case, the WRITE_BLOCK_C list separate columns for concentrations arising from different blocks and/or solvent types of the same monomer type, while WRITE_C only ouputs the total concentration for all monomers of that type.
The format of the file created WRITE_BLOCK_C is similar to that of a field file created by WRITE_C. The file contains with a header section identical to that contained in any pscf_fd field file, followed by a data section. The format of the data section file is analogous to that of pscf_fd field file that contains one field per monomer type, except that each polymer block and solvent species is treated as a separate monomer type, and thus output in a separate column of the data section.
Columns associated with blocks and species are output by the WRITE_BLOCK_C command are listed from left to right in the same order that they appear in the parameter file: Columns associated with polymer blocks are listed first (i.e., to the left), followed by columns associated with solvent species. Columns associated with blocks of the same polymer appear sequentially in order of increasing block id, while groups of columns associated with different polymer species appear in order of increasing polymer id. Columns associated with solvent species appear after all polymer blocks, listed left to right in order of increasing solvent species id.
In the inner loop of a SCFT calculation, a modified diffusion equation (MDE) is solved within every block of every polymer to obtain a set of so-called propagator functions. Each polymer block has two associated propagator functions, each associated with one of the two directions in which the block can be traversed. Each propagator function \( q({\bf r}, s) \) is a function of position \( {\bf r} \) and a contour variable \( s \) measured within a block as a contour distance from the vertex at which the propagator originates. Each such propagator function is associated with a particular direction (identified by index id = 0 or 1), a particular block (block index ib), and a particular polymer (polymer index ip). We refer to the function of position alone that is obtained by evaluating a propagator at a fixed value of \( s \) as a "slice". Because the MDE for each such propagator is computed numerically at evenly spaced values of \( s \), a computationally accessible slice may be identified by a integer contour step index \( is \) that is equal to zero at the vertex at which the propagator originates, and increases with increasing distance \( s \) from that vertex.
The pscf_fd programs accept several commands that output propagators and propagator slices to one or more files. The names for these commands start with a string "WRITE_Q", followed by a suffix that describes what information is output by invoking the command. All of these commands take a filename string as a parameter, and all but one of them take values of several integer indices needed to identify a particular propagator or slice.
All of these commands use file formats that report values of slices on the nodes of the regular real-space grid that is used internally in computations, analogous to the r-grid file format for w and c fields. The file format always starts with a header section identical to that of an r-grid field file, followed by a data section in which the values of each slice are output in a format analogous to that of a r-grid field file for a system with only one monomer type, in which all values are output in a single column, with nodes listed in the same order as in an r-grid field file.
WRITE_Q_SLICE : The command WRITE_Q_SLICE write the values of a propagator slice at a specified contour variable index \( is \) to an output file. This command named must be followed by the name of the output file, and values for the polymer index \( ip \), the block index \( ib \) and the direction index \( id \), in that order. The data section for output by this function is the same as that of an r-grid field file for a system with one monomer type.
WRITE_Q_TAIL : The command WRITE_Q_TAIL write the values of a propagator slice at a value of \( s \) equal to the length of the block, corresponding to the slice evaluated at the vertex at which the propagator terminates. This command named must be followed by the name of the output file, and values for the polymer index \( ip \) and the block index \( ib \), in that order. The resulting output file has the same format as that used by WRITE_Q_SLICE.
Users may instead output the value of slice of a propagator corresponding to the vertex at which it originates (i.e., the propagator "head" rather than "tail"), by invoking WRITE_Q_SLICE with a contour variable index \( is = 0 \), corresponding to a contour variable \( s = 0 \),
WRITE_Q_VERTEX : The command WRITE_Q_VERTEX writes values of the point-wise product of all incoming propagators at a specific vertex of a specific polymer species. This command named must be followed by the name of the output file, and values for the polymer index \( ip \) and vertex index \( iv \). Vertex indices for a n-block linear block polymer are labelled from 0 from one end, with vertices 0 and n representing the chain ends. The resulting output file has the same format as that used by WRITE_Q_SLICE and WRITE_Q_TAIL commands. The resulting field is proportional to the probability density for the location of the specified vertex. The spatial average of this field should have the same value for any vertex, within numerical error, and is equal to the molecular partitition function \( Q \) for a molecule of type \( ip \).
WRITE_Q : The command WRITE_Q writes all slices of a specified propagator to a single file. This command name must be followed by the name of the output file and values for the polymer index \( ip \) and block index \( ib \), in that order.
The output file produced by this command contains a header section followed by a sequence of data sections, in which each data section contains the data for a single slice at an integer value of the countour variable index. Data sections are listed in order of increasing countour variable index. The header section is similar to that of an r-grid file, except for the addition of line at the end that contain the word "nslice" followed by the value of the number of slices. Each data section begins with a line containing the word "slice" followed by value of the contour variable index for the slice represented by that section. The value of the slice index ranges from 0 for the first slice (the "head") to nslice - 1 for the last (the "tail"). The format of the remainder of each data section is the same as that of the data section of an r-grid field file for a system containing one monomer type, which consists of a single column of numbers containing the values of the associated propagator slice on the nodes of the regular spatial mesh used throughout the computation.
Comment for readers who read the source code : This command calls the function Fd1d::System::writeQ, which defines the output format, and is defined in the C++ file src/fd1d/System.cpp.
WRITE_Q_ALL : The command WRITE_Q_ALL writes all slices of every propagator of every polymer to a set of files, with all the slices of each propagator written to a single file, but different propagators output in different files. This command name must be followed by the value of a string parameter "basename" that contains a common prefix for the names of the resulting file set of output files.
Each of files created by this command has the same format as that of a file created by the WRITE_Q command. The name of the file containing the propagator associated with polymer ip, block ib, and direction id is given by a string of the form (basename)_(ip)_(ib)_(id).rf, where (basename) denotes the value of the basename command parameter, and where (ip), (ib), and (id) denote string representations of the values of the non-negative integers ip, ib, and id. Thus, for example, if the command is passed a basename parameter out/q, then the file out/q_0_2_1.rf will contain all slices of the propagator associated with polymer 0, block 2 and direction 1.
The REMESH_W and EXTEND_W can be used to change the mesh used to define a problem, by changing resolution or extending the domain.
REMESH_W : The REMESH_W command allows a user to change the discretization of the existing domain by writing a file that contains the current w fields interpolated onto a mesh with a modified number of grid points. The command takes the number nx of grid points of the new mesh and the name of the output file as parameters.
EXTEND_W : The EXTEND_W command allows a user to extend the domain of the solution by adding new points with field values that are simply copies of the values of w fields at the last grid point. The command takes the number m of added grid points and the name of the output file as parameters.
COMPARE_HOMOGENEOUS : The COMPARE_HOMOGENEOUS command computes differences between properties of an inhomogeneous system of interest, as predicted by SCFT, and those of an homogeneous reference system. The command takes an integer mode parameter with allowed values 0, 1, and 2 that determines the nature of the homogeneous system used for this comparison. In mode 0 (i.e., when mode == 0), the inhomogeneous system is compared to a homogeneous system with a composition equal to the spatial average composition of the system of interest. In modes 1 and 2, the comparison is made to a homogeneous system in which chemical potentials for all species are equal to those of the system of interest.
Further details of the operation of this command are described in a separate page here. These details include a description of the difference between modes 1 and 2 and a discussion of the format of the resulting report.
Command Files (Up) Commands - pscf_pc (Next)
1.9.5