pscf documentation

PSCF DocumentationRelease 1.0

David Morse

Jul 08, 2019

Contents

1 Introduction 31.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Installation 52.1 Binary Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Compiling from source, using cmake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Compiling from source, using make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.4 Installing the examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3 Usage 193.1 Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2 Command Line Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.3 Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 Parameter File 214.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.2 Overview of Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.3 Parameter Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244.4 Individual Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5 Output Summary File 33

6 Field Files 376.1 Symmetry-Adapted Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.2 Coordinate Grid Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416.3 Wavevector Grid Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7 Unit Cell 43

8 Space Groups 458.1 1D Space Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458.2 2D Space Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458.3 3D Space Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468.4 Symmetry Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

i

9 Python Tools 559.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559.2 Python Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569.3 ParamFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569.4 OutFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579.5 FieldFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589.6 Sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

10 Matlab Visualization Tool 61

11 Appendix: Self-Consistent Field Theory 63

12 Appendix: Memory Usage 67

13 Appendix: Creating Binary Packages 69

14 Indices and tables 71

ii

PSCF Documentation, Release 1.0

Contents:

Contents 1


2 Contents

CHAPTER 1

Introduction

PSCF is a numerical implementation of the Edwards-Helfand self-consistent field theory (SCFT) for periodic phasesformed by liquids containing block copolymers. It is designed to describe spatially periodic structures of incompessibleliquids that may contain a mixture of block copolymers, homopolymers, and small molecule solvents. It can describestructures with 1, 2, 3 or dimensional periodicity with any type of unit cell and any specified space group symmetry.The modified diffusion equation (MDE) is solved with an efficient pseudo-spectral method. The code was designedprimarily for calculating phase diagrams of block copolymer melts by comparing free energies of competing orderedphases, and contains several features that facilitate such calculations.

1.1 Features

• Arbitrary mixtures of block copolymers, homopolymers, and solvents

• Ordered phases with 1, 2, or 3 dimensional periodicity

• Canonical and grand-canonical ensembles

• Arbitrary 2 or 3D unit cell, with non-orthogonal axes

• Imposition of any specified space-group symmetry

• Hard-coded “database” of all 230 3D space groups and 17 2D plane groups

• Variable unit cell algorithm, in which unit cell parameters adjust to minimize free energy

• Continuation of solutions along lines in parameter space

• Linear response calculations for periodic structures

1.2 Documentation

• User manual (this file)

• Developer/API manual, generated from comments in the source code

3


• A library of examples, in a separate git repository located at

http://github.com/dmorse/pscf-examples.git

The developer manual is available online via a link from the program home page, and can also can be regeneratedfrom the source code (see the file doc/README for instructions).

1.3 Dependencies

The program is written in Fortran 90. It depends the open source FFTW Fast Fourier Transform library and theLAPACK linear algebra library. To compile the code from source, you will thus need a Fortran 90 compiler and thesetwo libraries.

1.4 Contributors

• David Morse

• Chris Tyler

• Jian Qin

• Amit Ranjan

• Raghuram Thiagarajan

• Akash Arora

4 Chapter 1. Introduction

http://github.com/dmorse/pscf-examples.git

CHAPTER 2

Installation

PSCF was designed to be used from the command line in a unix-like environment. It can be installed on either thelinux operating system or on Mac OS X system. A working version of PSCF may be installed either by installing aprecompiled binary executable or by compiling from source. Compiling from source can be also be carried out usingeither of two build systems, cmake or make.

Details for different methods of installation are given separately in the following pages, each of which includes in-structions that are specific to specific operating systems and specific distributions of linux.

2.1 Binary Installation

The steps to install a precompiled binary are different for different operating systems, and somewhat different fordifferent distributions of linux. The installer for Mac OS X installs a completely self-contained package that includescopies of all required external libraries. Instructions for installing binary .rpm and .deb packages for Redhat andDebian linux systems instead require the user to install packages containing the FFTW fast Fourier transform andLapack linear algebra libraries before installing PSCF.

2.1.1 Mac OSX

The procedure for installing PSCF on a Mac using a binary installer is similar to that for installing any application ona Mac:

• Download the Mac .dmg installer from the PSCF home page. This is a file with a name of the form pscf-<version>-Darwin.dmg.

• Open the .dmg file, and drag and drop the pscf_terminal icon file into the Applications folder.

To run the program, then simply double click the pscf_terminal application. The pscf_terminal application opens ayellow terminal window from which you can enter standard unix commands to navigate within the directory structureof your Mac, and from which you can invoke the pscf command using the same command interface as you would ona linux machine.

5


The first time you attempt to run pscf_terminal, Mac OSX security settings will prevent the application from startingbecause it is from an “Unknown Developer”. You will need to add an exception for this software. The followinginstructions for how to do this are copied from those provided by Apple at https://support.apple.com/kb/PH18657?locale=en_US:

1. In the Finder, locate the app you want to open. Don’t use Launchpad to do this. Launchpad doesn’t allow youto access the shortcut menu.

2. Press the Control key, then click the app icon, then choose Open from the shortcut menu.

3. Click Open.

This procedures saves the pscf_terminal app as an exception to your security settings, and will allow you to open it inthe future by double-clicking on the icon, as for any other registered app.

When the pscf_terminal application opens a yellow terminal window, it also modifies the unix executable search pathused in that window so as to allow the pscf command to be found when invoked from that window. This does not,however, allow pscf to be invoked from another terminal. If you install pscf using the .dmg installer file but would alsolike to be able to run it from the command line of a unix terminal that you open by other means (e.g., using the MacTerminal app), follow the instructions given in the discussion of Modifying Search Paths.

2.1.2 Ubuntu or Debian Linux

Ubuntu and Debian distributions of the linux operating system both use variants of the debian package managementsystem, which uses .deb package files. To install from binary on Ubuntu:

• First use the Ubuntu software center graphical installer or the apt-get command line utility to install the followingpackages:

– libfftw3-3

– liblapack3

– libatlas-base-dev

To install these packages using apt-get, enter:

sudo apt-get install libfftw3-3sudo apt-get install liblapack3sudo apt-get install libatlas-base-dev

• Download the .deb package from the PSCF home page. This is a file with a name of the form pscf-<version>-Linux.deb, where <version> denotes a version number string.

• Install the pscf package by running:

> sudo dpkg -i pscf-<version>-Linux.deb

• If the above command fails because of a missing dependence, try running:

> sudo apt-get install pscf-<version>-Linux.deb

This sometimes allows apt-get to attempt to fetch missing dependencies.

• Confirm that the pscf executable has been installed in /usr/local/bin/ by typing:

> which pscf

from any directory. The string /usr/local/bin/pscf should be printed to the terminal screen.

6 Chapter 2. Installation

https://support.apple.com/kb/PH18657?locale=en_US

https://support.apple.com/kb/PH18657?locale=en_US


2.1.3 Fedora / Redhat Linux

Redhat distributions of the linux operating system, including Fedora and CentOS, use package management systemsthat use .rpm package files. Instructions are similar to those for Ubuntu/Debian, except for the use of a differentpackage file format and package manager. In this case:

• Use the yum command line utility or the Fedora graphical package manager to install the following packagesfrom the appropriate Fedora repository:

– fftw

– lapack

To install these packages using yum from the command line, enter:

> sudo yum install lapack> sudo yum install fftw

For Fedora 22 and later, you may use the command “dnf” rather than “yum” to use an updated version of theyum package management system. The command line syntax is identical except for the replacement of the word“yum” by “dnf”.

• Download the pscf-<version>-Linux.rpm package from the PSCF home page.

• To install, enter:

> sudo rpm -Uvh pscf-<version>-Linux.rpm

• Confirm that the executable has been installed in /usr/local/bin, following the instructions given above for a .debpackage.

2.2 Compiling from source, using cmake

2.2.1 Overview

In this page, we discuss instructions for how to compile PSCF from source using the cmake build system, on eitherMac OS X or linux operating systems. It is also possible to compile the code using the unix make utility alone, usinga makefile that is provided with the source code. Compilation using make alone is described on a separate page onCompiling from source, using make. The advantage of using cmake is that cmake can generally find the paths to theLapack and FFTW libraries upon which PSCF depends, whereas you are more likely to need to figure out the locationsof these libraries yourself if you use make.

Compiling with cmake involves the following steps:

• Installing Dependencies

• Obtaining the Source Code

• Compiling and Installing

• Modifying Search Paths

Each of these steps is explained in greater detail below.

Only the first step, installing external dependencies, is substantially different for different operating systems. We thusgive separate instructions for Mac OS and different Linux distributions for this part of the process.

To obtain a copy of the source code from the github repository in which it is stored, one can either:

• Download a zip file

2.2. Compiling from source, using cmake 7


• Use the git version control software to clone the repository

We recommend using git to clone the repository, since this makes it simple to update the code later, but both proceduresare described below.

2.2.2 Installing Dependencies

The following software packages must be installed before using cmake to compile PSCF, if you plan on using git toobtain the source code:

• git (in order to clone the source code)

• cmake (to build a makefile)

• a Fortran 90 compiler (to compile the source code)

• Python (used by the build system)

• LAPACK linear algebra library

• FFTW version 3.x fast fourier transform library

You do not need to install git if you plan to simply download a copy of the source code rather than using git. On aMac, some of the above packages come bundled with the XCode development environment, which must in any casebe installed before you try to compile software from source on Mac OS X. Python is included with all common linuxdistributions, and is also bundled with recent versions of Mac OS X.

In what follows, we will assume that you plan to use free gfortran Fortran compiler, which is part of the Gnu CompilerCollection (gcc) suite of compilers, and give instructions for installing this fortran compiler. This fortran compilerdoes not come bundled with any of the operating systems discussed here.

Mac OS X

Installing XCode

To create an environment in which you can compile from source on OSX, you will generally first need to install theapple XCode development environment. XCode is available gratis from the Apple app store. It is a large package thatcan take a long time to install, so do this with a good internet connection. The XCode package contains git, so it isnot necessary to install git separately on a Mac. The Mac OS X operating system also appears to come with a versionof LAPACK, and the BLAS library upon which it depends. Neither the operating system nor XCode provide cmake,gfortran, or FFTW.

Checking for Python

A Python interpreter is included in recent versions of Mac OS X. To check if Python is already installed, enter thecommand:

> which python

or:

> which python2.7

from a unix terminal window. If the system responds to either of these commands by writing a location for a pythonexecutable file to the terminal, then Python is already installed. If nothing is written to the terminal in response, theneither Python is not installed or the operating system doesn’t know where to find it. Instructions for installing python,if necessary, are given below.

Package Managers: HomeBrew vs. MacPorts



The remaining dependencies (cmake, gfortran and FFTW) can be most easily installed using either the MacPorts orHomebrew package manager systems. These are both systems for managing open-source unix software on the unixsubsystem of the Mac OSX. The choice between these package managers is up to you, but you should avoid using bothon the same machine. If either Homebrew or MacPorts is already installed and in use on your Mac, use the existingsystem, and do not install the other, because they do not play well together. If neither Homebrew or MacPorts isinstalled, we have a slight preference for Homebrew, which we find makes it slightly easier to install the dependenciesrequired by PSCF. We have succeeded in building PSCF using both of these package managers on machines that arerunning the latest version of Mac OS X (El Capitan, X 10.11), using different package managers on different machines.Instructions for both package managers are given separately below.

Installing dependencies via Homebrew

To install from a command line terminal using homebrew:

> brew install cmake> brew install gcc --with-fortran> brew install fftw --with-fortran

If you need to install python (which is unlikely), enter:

> brew install python

Installing dependencies via Macports

After MacPorts is installed, to install the required dependencies using the most recent version of the gnu compilercollection (gcc), which is gcc 5.X at the time of writing, enter:

> sudo port install cmake> sudo port install gcc5> sudo port install fftw-3 +gfortran

If python is required, enter:

> sudo port install python27

Note that MacPorts (unlike homebrew) requires you to use “sudo” to execute installation with superuser/administratorprivileges, and so will ask for a password after each of the above commands.

The gcc5 MacPorts package installs the gfortran Fortran 90 compiler executable at /opt/local/bin/gfortran-mp-5 .Versions compiled with earlier versions of gcc (e.g., 4.9) seem to be placed in the same directory with a differentnumerical suffix, e.g., gfortran-mp-49. CMake appears to be unable to find this compiler executable without help. Toremedy this, you should set the FC environment variable (which indicates the path to a Fortran compiler) to point tothe absolute path to the gfortran executable before attempting to compile, by entering, for example:

> FC=/opt/local/bin/gfortran-mp-5> export FC

If expect to compile this and other fortran programs repeatedly, you may want to put this in your .profile or .bashrcbash configuration file.

Ubuntu Linux

Use the Ubuntu software manager or the command line apt-get utility to install the following packages:

• git

• cmake

• gfortran



• libfftw3-dev

• liblapack3

To use apt-get from the command line, enter:

> sudo apt-get update> sudo apt-get install git> sudo apt-get install cmake> sudo apt-get install gfortran> sudo apt-get install libfftw3-dev> sudo apt-get install liblapack3

Fedora Linux

Instructions for Fedora are similar to those for Ubuntu, except that one should use the native yum command linepackage manager or the Fedora graphical software manager to install dependencies. The required Fedora packagesare:

• git

• cmake

• gcc-gfortran

• lapack-devel

• fftw-devel

To install these packages from the command line, enter:

> sudo yum install git-all> sudo yum install cmake> sudo yum install gcc-gfortran> sudo yum install lapack-devel> sudo yum install fftw-devel

For Fedora 22 and later, you may use the command “dnf” rather than “yum” to use the an updated version of the yumpackage manager. To do so, simply replace “yum” by “dnf” in each of the above commands.

Using Linux Modules

Many large multi-user computer clusters use linux modules to allow users to load software packages that they require,chosen from among a list of available modules. The following instructions describe how to load the required modulesto build PSCF in a user directory on the Minnesota Supercomputer Institute (MSI) Mesabi computer, using linuxmodules and the Intel compiler. Similar instructions should apply to other large clusters that use linux modules.

To load the required modules on Mesabi at MSI, and also choose the Intel compiler, enter:

> module load cmake> module load intel mkl> module load fftw

The remaining instruction for how to obtain and compile the source code are generally similar to thos given for OSXor Linux. The only difference is that, to use the Intel compiler, one must tell cmake to use the Intel compiler by addingthe option “-DUSE_INTEL=1” to the cmake command. The required command is thus:



> cmake -DUSE_INTEL=1 -DCMAKE_INSTALL_PREFIX=/path/to/install ../pscf

More generally, to use the Intel fortran compiler on any operating system (when available), use the “-D” option todefine USE_INTEL=1 to instruct cmake search for an Intel compiler rather than using gnu fortran.

2.2.3 Obtaining the Source Code

We assume in what follows that you will use cmake to perform an “out-of-source” build, in which all of the filesgenerated during compilation are placed in a directory tree outside the source code tree. To begin, we recommendthat you create a directory named pscf/ somewhere in your user directory tree, and then create a subdirectory of pscf/named named cmake/. To do this, enter:

mkdir pscfcd pscfmkdir cmake

The directory named pscf/cmake/ will be used as the build directory. The source code will be placed in anothersubdirectory of pscf/, which we will call git/ to indicate that it contains the contents of the git repository that containsthe source code.

The source code for pscf is stored in a repository on the github.com server, at:

https://github.com/dmorse/pscf

A copy of the source code may be obtained either, by:

• Downloading a zip file, or

• Using git to clone the source code.

To download a zip file:

• Point your browser at the pscf github repository.

• Click the “Download ZIP” button near the upper right corner of that web page. On Mac OS X and most linuxsystems, this will create a subdirectory named pscf-master within your Downloads folder or directory.

• Move the pscf-master/ directory into the pscf/ directory that you just created.

• Rename the pscf/pscf-master/ directory as git/, by changing directory to pscf and then entering:

mv pscf-master git

To use git to clone the repository, after git is installed on your machine:

• Change directory to the pscf directory.

• Clone the repository, by entering:

git clone https://github.com/dmorse/pscf.git

• This should create a subdirectory of pscf/ that is also named pscf/. To avoid confusion, we recommend that youchange the subdirectory name to pscf/git/, exactly as described above for the case of a directory created from azip file.

At this point, by either method, you should have pscf/ directory structure:

pscf/cmake/git/


https://github.com/dmorse/pscf


in which the cmake/ subdirectory is empty and the git/ subdirectory contains the contents of github repository, includ-ing the source code.

2.2.4 Compiling and Installing

Choose an Install Directory

After installing all dependencies and obtaining the source code, you are ready to compile PSCF. Before compilingthe code, you need to decide where you would like to install the pscf executable, along with several other executablescripts and python files. The build system created by cmake will install these files in subdirectories of a directorythat we will refer to as the install directory. You can specify the location of the install directory by an option on thecommand line of the “cmake” command, as discussed in more detail below.

After installation, the install directory (denoted by install/ below) will contain the following three subdirectories:

install/bin/lib/share/

After installation, the bin/ subdirectory will contain the pscf executable and other executable files, the lib/ subdirec-tory will contain python modules and matlab files and the share/ directory will contain several text files containinginformation about the program.

We recommend that you choose one of the three following three possible locations for the install directory for pscf:

• The pscf/ directory that contains the cmake/ and git/ subdirectories.

• A standard location for installing software within your user directory.

• The system-wide /usr/local directory.

If you choose to install software within a standard location within your user directory, one common choice for this isa hidden directory of your home directory named “.local” .

One advantage of the first two options listed above is that both install all executable files within your user directory,and thus do not require adminstrative privileges. This also makes it somewhat easier for you to see what files youhave installed (since these files are not placed in directories containing many files associated with other applications),and remove them if you ever desire. The further administrative advantage of the first option, of installing executableswithin the pscf/ directory that also contains the source code, is that it keeps all of the files associated with PSCF in asingle directory tree within the user directory.

The main disadvantage of both the first and second options is that, because both install files within your user directory,they will both require you to modify some operating system environment variables in order to allow the operatingsystem to find the PSCF executable and to allow the python intepreter to find python modules that are provided tofaciliitate data analysis. Instructions for modifying the relevant environment variables, if necessary, are given below.

The advantage of installing in /usr/local is that, because this puts executables in a standard location, the operatingsystem should be able to automatically find the pscf executable. If you are not an experienced unix programmer, werecommend that you install in a user directory (either the pscf/ tree or the user .local directory) rather than in /usr/local.

Invoke cmake

The first step of compiling with cmake is to invoke the cmake command in order to construct a set of makefiles thatcontain instructions for building the system. To begin, change directory (cd) to the pscf/cmake/ directory. Then makesure the cmake/ directory is empty, and remove any contents if necessary. From there, enter:

> cmake -DCMAKE_INSTALL_PREFIX=/path/to/install ../git



In this command, the string “/path/to/install” denotes the path to the root of the install directory. The last argument,“../git”, is the relative path to your copy of the source code repository, in pscf/git, from the pscf/cmake directory.

To install within in the pscf/ directory tree, you would enter cd to pscf/cmake and then:

> cmake -DCMAKE_INSTALL_PREFIX=.. ../git

Here, “..” represents the pscf/ directory, which is the parent of the pscf/cmake directory from which the command isissued. This will cause the later creation of bin/, lib/ and share/ subdirectories of the pscf/ directory alongside thecmake/ and git/ repository. This method thus creates a directory structure:

pscf/git/cmake/bin/lib/share/

in which all of the files associated with pscf (including source and executable files) are placed in a single directory treewith the users home directory tree.

To install in the .local subdirectory of your home directory, instead enter:

> cmake -DCMAKE_INSTALL_PREFIX=~/.local ../git

in which the tilde (~) is linux shortand for the users home directory.

Finally, to install in the /usr/local directory, you need adminstrator privileges on your machine, and would enter:

> cmake ../git

No “-DCMAKE_INSTALL_PREFIX=” option is required in this case because /usr/local is the default installationused by cmake if no alternative is specified.

Invoke make

The cmake command described above should create several subdirectories of the pscf/cmake/ directory, which containmakefiles with instructions for building pscf. To actually compile and install the program, simply enter:

> make -j4> make install

from the pscf/cmake directory. The “-j4” option simply instructs the make utility to use up to 4 processor cores tocompile, if available, to speed up compilation. It is not required. The first “make” command compiles the code andplaces all the files generated by compilation in the pscf/cmake directory. The “make install” command then installsthe executable and other files files in the bin/, lib/ and share/ subdirectories of the chosen installation directory.

After the “make install” finishes execution, check that your chosen install directory contains subdirectories named bin/,lib/ and share/, and that the the bin/ subdirectory contains an executable file named pscf, along with several executablescripts whose names begin with the suffix “pscf-. . . ”. One of these should be a bash script named “pscf-env”.

If you install in the /usr/local directory, you will need to have administrator privileges on the your computer, and willneed to use the “sudo” command to run “make install” as the “super-user”, by entering:

> sudo make install

In this case, you will be prompted for your password.



2.2.5 Modifying Search Paths

If you install pscf in a directory within your home directory tree, you may need to modify a few environment variablesto allow the operating system to find the pscf program when it is invoked from the command line by name, and toallow the python interpreter to find some associated python modules that are useful for data analysis.

Changing Paths

The simplest way to make the required changes to your user environment is to cd to bin/ subdirectory of the root installdirectory and, from there, enter:

source ./pscf-env

This will run a script that is installed by PSCF, which adds the appropriate paths to your PATH and PYTHONPATHenvironment variables.

Alternatively, to make the required changes manually, you could simply enter the commands:

PATH=$PATH:install/binPYTHONPATH=$PYTHONPATH:install/lib/python2.7/site-packages

where “install” denotes an absolute path to the root installation directory that you chose when compiling.

If you installed pscf on Mac OS X using the .dmg installer, the root install directory (the directory that contains therelevant bin/ and lib/ subdirectories) is the directory:

/Applications/pscf_terminal.app/Contents/Resources

In this case, to run the pscf-env script, you must either cd to the bin subirectory of that directory, or use the followingcommand using the absolute path:

source /Applications/pscf_terminal.app/Contents/Resources/bin/pscf-env

If you installed pscf using a .deb or .rpm binary installer on linux, the root install directory is /usr/local and the path tothe pscf-env script is /usr/local/bin/pscf-env.

Making Changes Permanent

The above procedures (running pscf-env script or manually setting the relevant environment variables) only modifiesthe $PATH and $PYTHONPATH variables temporarily, until you close the terminal window or log out. To have theappropriate directories added to these environment variables automatically whenever you log in or open a terminal,simply add the command:

source install/bin/pscf-env

to the .bashrc file or (on Mac OS X) .profile configuration file in your home directory. Here, the string “install/” is aplaceholder for the absolute path to the pscf install directory.

Configuration files: Linux vs. Mac OS X

On linux, after a user logs in, the operating system looks for a file in the user directory named .profile or .bash_profile(in that order) and executes the first of these files that finds, if any. When you open a new interactive shell that is not alogin shell, e.g., by opening a new termiinal, it instead looks for and (if it exists) executes a file named .bashrc in theusers home directory. To make sure that the modifications of the environment are applied to both login and non-loginterminals, the .bashrc file is normally executed by the .profile or .bash_profile file, by a command such as:

if [ -f "${HOME}/.bashrc" ]; thensource "${HOME}/.bashrc"

fi



This part of the .profile or .bash_profile file checks if there is a .bashrc file in the users home directory and, if one isfound, executes that file. With this configuration, commands that set up environment variables should be added to the.bashrc file.

On Mac OS X, the Mac Terminal program instead executes the .profile script whenever you open a terminal, ratherthan using different files for login and non-login terminals. The Mac Terminal program thus thus does not ever directlyexecute the .bashrc file. A Mac user that always uses the Mac Terminal program could thus either use the proceduredescribed above (which would still work correctly), or simply place all commands that customize the user environmentinto the .profile script.

2.3 Compiling from source, using make

It is also possible to compile using the unix make utility alone, using a simple Makefile that is provided in the make/subdirectory of the git repository. The instructions for using make to compile from source are the same on any unix-like operating system, including Max OS X. The main differences among different unix environments are the locationsof the required libraries.

To compile the code in this way, proceed as follows:

• Follow the directions given in the discussion of Installing Dependencies on the previous page. You will need toinstall all dependencies listed there except cmake.

• Follow the directions given in the discussion of Obtaining the Source Code on the previous page to create anappropriate directory structure and obtain the source code. After this step, you should have a directory namedpscf/ with a subdirectory named git/ that contains the contents of the git repository. If you are not using cmake,then you do not need to create a subdirectory of pscf/ named cmake/.

• Change working directory (cd) to the directory pscf/git/make . Note that this is an existing subdirectory of thepscf/git directory, and is different from the initially empty directory pscf/cmake from which we recommendedcmake be invoked when using cmake to compile.

• The pscf/git/make directory will contain files named config.mk_r and Makefile. Make a copy of the file con-fig.mk_r, by entering:

cp config.mk_r config.mk

• Examine and edit the new config.mk file to reflect your environment, and to specify an installation directory.See below for further instructions about this step. The need to manually edit this configuration file is the maindifference between using cmake to generate makefiles and using the simple makefile distributed with the sourcecode.

• To compile, enter:

> make -j4 all

from within pscf/git/make. The “-j4” option is not necessary, and simply instructs the make utility to try to useup to 4 CPU cores during compilation, if multiple cores are available.

• To install in the directory specified by the $(INSTALL) makefile variable (as defined in config.mk), enter:

> make install

• Follow the directions given in the subsection of the previous page entitled Modifying Search Paths in order tomodify environment variables that define search paths.

Several of these steps are discussed in more detail below.

Editing the config.mk configfuration file

2.3. Compiling from source, using make 15


In the config.mk file in the src/make directory (which you should have created by making a copy of config.mk_r), youwill need to set values for several macro variables to values appropriate to your system. Makefile variables you mayneed to reset are:

F90 path to executable for Fortran 90 compilerFAST compiler options for high optimizationNOPT compiler options for no optimizationLIBDIR option setting any nonstandard directories for librariesLAPACKLIB option setting name of lapack library (e.g., “-l liblapack”)FFTWLIB option setting name of the FFTW library (e.g., “-l fftw3”)INSTALL root installation directory

The INSTALL makefile variable in this makefile is equivalent to the MAKE_INSTALL_PREFIX variable that can bepassed to cmake when using cmake to create a makefile.

The file config.mk_r is a default makefile that is stored in the repository. We require you to make an operationalcopy of this, named config.mk, so that you can modify your config.mk file as needed without changing the defaultcopy. The config.mk_r file contains values for Makefile variables appropriate for a several different common operatingsystem environments, most of which are commented out. It also contains some comments about appropriate choicesfor specific environments. Modify your copy of config.mk as needed, but avoid modifying config.mk_r, and make sureyou give exactly one uncommented definition for each variable in the config.mk file, and comment out any unuseddefinitions.

Compile and Link

To compile and link, from the git/make directory, simply enter:

> make -j4

This should create several .o object files and .mod module files in the git/make directory, and then create an executablefile named pscf in the same directory.

Install

To install a copy of the executable file in your chosen location, after compiling, simply enter:

> make install

This will install:

• pscf and other executable files in directory $(INSTALL)/bin/

• python modules in $(INSTALL)/lib/python2.7/site-packages/pscf/

• matlab scripts in $(INSTALL)/lib/matlab

• text files in $(INSTALL)/share

where $(INSTALL) denotes the value of the makefile variable defined in the config.mk file.

Cleaning Up

To remove all generated files from the git/make directory, if desired, enter:

> make clean

To remove all files installed in the INSTALL directory by the “make install” command, enter:

> make uninstall



2.4 Installing the examples

A library of examples of input files for pscf simulations is provided as a separate git repository. The best way tobecome familiar with the format of the pscf input and output files is to look at and run some of these examples.The following instructions assume that you will install the directory containing these examples as a directory namedpscf/examples, alongside a pscf/git directory that contains the source code repository.

Obtaining examples

The repository containing the examples is located on the github.com server at:

https://github.com/dmorse/pscf-examples

A copy of this repository may be obtained (as for the source code repository) either by downloading a zip file fromthe repository web page or using git to clone the repository. The instruction given below for both methods are verysimilar to those given for obtaining the source code:

To download a zip file:

• Point your browser at the pscf-examples github repository.

• Click the “Download ZIP” button near the upper right corner of that web page. This will download the zip file,usually into your “Downloads” directory and (in some environments), may unzip the file to create a directory.

• If you installed using a binary package, rather than installing from source, create a directory named pscf/ some-where in your user directory. If you installed from source, this directory should already exist.

• Move the pscf-examples-master/ directory into your pscf/ directory.

• Rename the resulting directory pscf/pscf-examples-master/ to pscf/examples.

To clone the repository of examples, if git is installed on your machine:

• If you installed using a binary package, create a directory named pscf/, as discussed above.

• Change directory (cd) to your pscf/ directory.

• Clone the pscf-examples repository, by entering:

git clone https://github.com/dmorse/pscf-examples.git

• Change the name (i.e., mv) the pscf/pscf-examples directory to pscf/examples/

Either method should give you a pscf/ directory with a subdirectory named examples. If you installed from source,you should have a pscf directory with the structure:

pscf/git/examples/

in which the pscf/git/ subdirectory contains the source code and the pscf/examples/ directory contains input files forexamples. If you followed the instructions to compile using cmake, the pscf/ directory will also contain subdirectorynamed cmake/. If you compiled from source and also installed the code in your pscf/ directory, pscf/ will also containsubdirectories named bin/, lib/ and share/.

The structure and contents of the examples directory is explained in the README file within that directory.

2.4. Installing the examples 17

https://github.com/dmorse/pscf-examples

CHAPTER 3

Usage

3.1 Input Files

A standard SCFT calculation requires two input files:

• A parameter file

• An input “omega” file

The parameter file contains both parameters required to define a physical system and instructions to execute a sequenceof computations. The input omega file contains an initial guess for the monomer chemical potential fields. Theparameter file is read by the main program from standard input. The path for the omega file is normally specified inthe parameter file. The format of the Parameter File is described in the next page of this manual.

3.2 Command Line Usage

The syntax for executing the pscf program is thus:

pscf < param

Here, “param” is the name of the parameter file. This method of executing the program will cause log messagesthat describe the progress of the calculation to written to the users screen. To run in the background and save thesemessages to a file, you would instead enter:

pscf < param > log &

where “log” is a file to which we have redirected messages emitted by the program during operation. The “&” at theend of this line indicates that the program should be run in the background, as is appropriate for a long computation,so that the user can continue on to other tasks in the same terminal.

19


3.3 Output Files

When PSCF is used to solve SCFT equations, it creates several type of output files. Paths to these files are generatedby appending standard suffixes to the value of a string variable ‘output_prefix’ that is specified in the parameter file.

Running a solution of the SCF equations for a single set of parameters creates the following types of output files:

Suffix Descriptionrho Monomer concentration fieldsomega Monomer chemical potential fieldsout Output summary

These output files may be placed in a common directory by setting output_prefix to the name of the desired direc-tory, with a trailing directory separator. For example, if output_prefix = ‘out/’, then PSCF will generate output files‘out/rho’, ‘out/omega’, and ‘out/out’ in subdirectory ‘out/’ of the directory from which PSCF was invoked.

The rho and omega output files both describe fields, and use the same file format, which is also the required format foran input omega file. Each of these field file contains a lists of coefficients of a symmetry -adapted Fourier expansionof the field. This file format, and the underlying expansion, are described in more detail in the page: Field Files .

20 Chapter 3. Usage

CHAPTER 4

Parameter File

The main program reads a parameter file containing the parameters and instructions for a calculation. This file isdivided into sections, each of which contains a different type of information.

Each section is preceded by a blank line and starts with a line containing a section title in all capital letters (i.e.,‘CHEMISTRY’, ‘UNIT_CELL’, etc.) Each section may contain values of a sequence of variables. The variableswithin each section must appear in a predetermined (i.e., hard-coded) order. The name of each variable appears ona line by itself, followed by either the variable value or, for array-valued variables, by a sequence of values of theelements of the array on one more subsequent lines.

The program stops when it encounters the section title ‘FINISH’.

4.1 Example

An example of a complete parameter file is shown below. This example is for a system containing a triblock copolymercontaining three chemically distinct blocks in a solvent that is chemically identical to one of the blocks.

The first line of the file identifies the version of the file format (in this case, version 1.0). The remainder of the file isdivided into sections. Each section begins with a capitalized section identtifier (MONOMER, CHAINS, etc.) on a lineby itself. A single blank line appears between sections. The sections are processed in the order in which they appearin the parameter file. The first few sections in this example simply provide values for physical and computationalparameters. An ITERATE section instructs the program to actually perform a single SCF calculation, by iterativelysolving the SCF equations. A SWEEP section performs a sequence of such calculations along a line in parameterspace. Execution of the program stops when a FINISH line is encountered.

format 1 0

MONOMERSN_monomer

2kuhn

0.4000000E+00 0.6000000E+00

(continues on next page)

21


(continued from previous page)

CHAINSN_chain

1N_block

3block_monomer

1 2 3block_length

1.2000000E+02 0.7000000E+02 0.6000000E+02

SOLVENTSN_solvent

1solvent_monomer

2solvent_size

1.0

COMPOSITIONensemble

0phi_chain

0.8000000E+00phi_solvent

0.2000000E+00

INTERACTIONSinteraction_type

'chi'chi

1.2000000E-02

UNIT_CELLdim

1crystal_system

'lamellar'N_cell_param

1cell_param

1.3200000E+01

DISCRETIZATIONngrid

32ds

1.00

BASISgroup_name

'-1'

ITERATEinput_filename

'in.omega'output_prefix

'out/'(continues on next page)

22 Chapter 4. Parameter File



max_itr20

error_max1.0000000E-08

domainT

itr_algo'NR'

N_cut100

SWEEPs_max

10.00000E+00d_chi

1.0000000E+00end_increments

FINISH

4.2 Overview of Sections

Primary Sections

The following list shows the titles of the most common parameter sections, in the order in which they normally appear.A detailed descriptions of the contents of each parameter file section is given below in a discussion of IndividualSections.

Section DescriptionMONOMERS # of monomer types, and their kuhn lengthsCHAINS Chain species, block sequences and lengths, etc.SOLVENTS Solvent species, chemical identities, volumesCOMPOSITION Statistical ensemble and mixture compositionINTERACTION Interaction parameters (excess free energy)UNIT_CELL Unit cell dimension, lattice type, and parametersDISCRETIZATION Spatial grid dimensions and ‘time’ step ds.BASIS Construct symmetry adapted basisITERATE Solve SCFT for one set of parametersSWEEP Solve SCFT for multiple sets of parametersRESPONSE Compute linear susceptibility of ordered phaseFINISH Stop program

Common Workflows

Several standard types of computation are possible using the blocks listed above:

• Iterate: To solve solve the SCF equations for a single state point, include all of the sections above, in the orderlisted, except SWEEP and RESPONSE sections, which should not appear. Also exclude the SOLVENTS sectionif the system of interest is a polymer melt or a mixture of polymers with no small molecule solvent component.

• Sweep: To compute a sequence of different states along a line in parameter space, include all of the sectionslisted above, in the order listed, except the RESPONSE section. The ITERATE section must precede the SWEEP

4.2. Overview of Sections 23


section, and is used to obtain a solution for the initial choice of parameters, which is then used as a startingsolution for the rest of the sweep.

• Response: To compute the self-consistent-field or RPA linear susceptibility of a periodic microstructure, includeITERATE and RESPONSE sections, but do not include a SWEEP section.

The SOLVENTS section may always be omitted for calculations on systems that do not contain any small moleculesolvent.

Miscellaneous Utilities

The following sections are used to invoke a variety of data processing operations or transformations on fields orparameters, or to output additional information.

Section DescriptionFIELD_TO_RGRID Read field file in symmetry-adapated format and output in coordinate grid for-

matRGRID_TO_FIELD Read field in coordinate grid file format and output in symmetry-adapated for-

matKGRID_TO_RGRID Read field in k-space grid format and output in r-space coordinate grid formatRHO_TO_OMEGA Read rho field, compute and output omega fieldRESCALE Redefine monomer reference volumeOUTPUT_WAVES Output relationship of waves to basis functionsOUTPUT_GROUP Output all elements of space group

Further details about the contents and purpose of each section are given below.

4.3 Parameter Conventions

Units

PSCF does not impose the use of a particular system of units for lengths. Any system of units can be used for enteringvalues of the monomer statistical segment lengths and the unit cell dimensions, as long as the same unit of length areused for all relevant quantities. One can use either a physical unit, such as nanometers or Angstroms, or dimensionlessunits in which one or more of the statistical segment lengths is set to unity.

Definition of a “Monomer”

SCFT also leaves the user some freedom to redefine what he or she means by a “monomer”, which need not correspondto a chemical repeat unit. The choice of values of the parameters block_length, solvent_size, kuhn, and chi to representa particular experimental system all depend on an implicit choice of a value for a monomer reference volume, whichdefines the mononmer repeat unit that is being used for bookkeeping purposes. One “monomer” of a polymeric speciesis defined to correspond to length or molar mass of chain that occupies a volume in the melt equal to one referencevolume, which may or may not correspond to a chemical repeat unit. Each element of the variable block_lengthrepresents the number of “monomers” in a block of a block copolymer, which is given by the ratio of the block volumeto the monomer reference volume. Similarly, the variable solvent_size is given by ratio of the solvent volume to thereference volume.

Note that PSCF does not require the user to input a value for the monomer reference volume - the choice of referencevolume is implicit in the values given for other quantities. Changes in one’s choice of reference volume lead tocorresponding changes in the values for the chi parameters, which are proportional to the reference volume, and in thekuhn lengths, which are proportional to the square root of the reference volume.

Character Strings



All parameters that are represented internally as characters or character strings must appear in the parameter file withsingle quotes, e.g., as ‘chi’ or ‘out.’.

Array-valued parameters

Many input parameters are represented one or two-dimensional array, in which different elements may be associatedwith, e.g., different monomer types or different molecular species. Here, we discuss how the dimension and format ofthese parameters is indicated in subsequent sections that use to tables to describe the parameters required in differentsections of the input script.

The discussion of each section of a parameter file contains a table listing the required parameters and the meaningof each. Parameters that are represented by one- or two-dimensional parameters arrays are indicated in these tablesby displaying the name of each array parameter with an an appropriate number of indices shown in induces. Onedimensional array parameters are thus indicated by writing the name of the parameter with one index: For example, inthe description of the MONOMERS section, kuhn(im) denotes a one dimensional array of statistical segment lengthsfor different monomer types. Two dimensional arrays are shown with two indices.

The meaning and range of each such array index is indicated by using a set of standard variable names to indicatedifferent types of indices, with different ranges of allowed values. For example, in the remainder of this page, thesymbol ‘im’ is always used to indicates an index for a monomer type. The meaning and range of every index symbolis summarized in the following table:

Meaning of Array Indices:

Indices Meaning Rangeim, in monomer types 1,. . . ,N_monomeric chain/polymer species 1,. . . ,N_chainib blocks within a chain 1,. . . ,N_block(ic)is solvent species 1,. . . ,N_solventid Cartesian direction 1,. . . ,dim

For each array parameter, the elements of the array are expected to appear in the parameter file in a specific format.Generally, arrays are formatted so that information about different molecular species appears on separate lines, butthat values that are associated with different monomer blocks or different blocks within a block copolymer appear ona single line separated by spaces.

The expected format for each array parameter in specified in the table of parameters for each section by a code givenin a table column labelled “Format”. The meaning of each array format code is specified below:

Code MeaningR 1D array, row format (all values in a single line)C 1D array, column format (one value per line)MR 2D array, multiple rows of different lengthLT 2D array, lower triangular

Within each line, values may be separated by any amount of whitespace. In the row (R) format for 1D arrays, allvalues appear on a single line separated by whitespace. In the column format (C), each value appears on a separateline. In the multiple row (MR) format, which is used for the arrays block_monomer(ib,ic) and block_length(ib,ic),each line of data contains the values for all of the blocks of one chain molecule, with N_block(ic) values in the linefor molecule number ic.

The lower triangular (LT) format for square 2D arrays is used for the array chi(im,in) of Flory-Huggin interactionparameters. In this format, a symmetric array with zero diagonal elements is input in the form:

4.3. Parameter Conventions 25


chi(2,1)chi(3,1) chi(3,2).....

in which line i contains elements chi(i+1,j) for j< i. For a system with only two monomer types (e.g., a diblockcopolymer melt or a binary homopolymer blend), only the single value chi(2,1) on a single line is required.

4.4 Individual Sections

Each of the following subsections describes the format of one possible section of the parameter file. Array-valuedparameters are indicated using the conventions described above. Some variables may be present or absent dependingon the value of a previous variable. These conditions, if any, are given in a column entitled ‘Required if’ or ‘Absentif’.

4.4.1 MONOMERS

Chemistry Parameters

Variable Type Description FormatN_monomer integer Number of monomer typeskuhn(im) real statistical segment length of monomer type im R

Despite the choice of name, the elements of the kuhn array are actually effective statistical segment lengths, ratherthan true Kuhn lnegths. The statistical segment length 𝑏 of a random-walk hompolymer depends upon the choice of adefinition of an effective monomer, and is defined by setting 𝑏2 = 𝑅2

𝑒/𝑁 , where 𝑅2𝑒 is the mean-squared end-to-end

length of the polymer and 𝑁 is the number of effective monomers (i.e., the number of monomer reference volumes)in the chain.

4.4.2 CHAINS

Chain Parameters

Variable Type Description FormatN_chain integer Number of chain speciesN_block(ic) integer Number of blocks in species ic Cblock_monomer(ib,ic) integer Monomer type for block ib of species ic MRblock_length(ib,ic) real Number of monomers in block ib of species ic MR

The block_monomer and block_length arrays are entered in a format in which each line contains the data for onepolymer species, and different entries within each line refer to different blocks. The number of entries in line ic mustequal to the value of N_block(ic), i.e., to the number of blocks in chain species ic. The length of each block in anincompressible mixture is equal to the volume occupied by that block (computed using the density of the correspondinghompolymer) divided by the monomer reference volume.

4.4.3 SOLVENTS

Solvent Parameters



Variable Type Description FormatN_solvent integer Number of solvent speciessolvent_monomer(is) integer Monomer type for solvent is Csolvent_size(is) real Volume of solvent is C

The parameter solvent_size is given by the ratio of the actual volume occupied by a particular solvent to the monomerreference volume.

4.4.4 COMPOSITION

Composition Parameters:

Variable Type Description Formatensemble integer 0 if canonical, 1 if grandphi_chain(ic) real volume fraction of chain species ic Cphi_solvent(is) real volume fraction of solvent species is Cmu_chain(ic) real chemical potential of chain species is Cmu_solvent(ic) real chemical potential of solvent species ic C

The integer parameter “ensemble” determines the choice of statistical ensemble. This should be set to 0 for canonical(NVT) ensemble and to 1 for grand-canonical ensemble. The remainder of the section then contains only the inputparameters required as inputs in the specified ensemble:

If canonical ensemble is specified (ensemble=0), then the rest of the section must contain values for the parametersphi_chain and (if N_solvent > 0) phi_solvent that specify the volume fractions of all species. The example parameterfile shows this for a canonical ensemble simulations of a single-component polymer melt.

If grand canonical ensemble is specified (ensemble=1), then the rest of the section must contain values for the pa-rameters mu_chain and (if N_solvent > 0) mu_solvent that specify values for the chemical potentials of all species.Chemical potentials are specified as free energies per molecule in units with 𝑘𝐵𝑇 = 1.

Values of phi_solvent (in canonical ensemble) or mu_solvent (in grand-canonical ensemble) should be given if andonly if there are solvent species present, i.e., if a solvent block is present and N_solvent > 0.

4.4.5 INTERACTION

Interaction Parameters

Variable Type Description Formatchi_flag char(1) ‘B’ => bare chi, ‘T’ => chi=chi_A/T + chi_Bchi(im,in) real Flory-Huggins parameter (‘bare’) LTchi_A(im,in) real Enthalpic coefficient for chi(T) LTchi_B(im,in) real Entropic contribution to chi(T) LTTemperature real Absolute temperature

The parameter “chi_flag” determines whether the Flory-Huggins interation parameters should be input by specifyingvalues, if chi_flag = ‘B’, or by specifying a temperature dependence of the form A/T + B, if chi_flag = ‘T’. The arraychi should be present if and only if chi_flag = ‘B’, while the parameters chi_A and chi_B should be present if and onlyif chi_flag = ‘T’.

4.4. Individual Sections 27


4.4.6 UNIT_CELL

The variables in the UNIT_CELL section contain the information necessary to define the crystal unit cell type, and theunit cell size and shape (i.e., to define the Bravais lattice).

Variable Type Description Formatdim integer dimensionality =1, 2, or 3crystal_system character(60) unit cell type (cubic, tetragonal, etc.)N_cell_param integer # unit cell parameterscell_param(i) real N_cell_param unit cell parameters R

The unit cell parameters are unit cell length and angles between Bravais basis vectors. The number of parametersrequired to describe a unit cell is different for different types of cell (different values of crystal_system), and is givenby N_cell_param. The array cell_param contains N_cell_param unit cell parameters, which are input in row format,with all elements in a single line.

Further information about the allowed values of the crystal_system string and the number and type of unit cell param-eters required by each type of unit cell is given in the Unit Cell page.

4.4.7 DISCRETIZATION

The discretization section defines the grid used to spatially discretize the modified diffusion equation and the size dsof the computational “step” ds in the time-like contour length variable.

Parameters:

Variable Type Description Formatngrid(id) integer # grid points in direction id=1,..,dim Rds real contour length step size

The integer array ngrid(id) is input in row format, with dim (i.e., 1,2 or 3) values on a line, where dim is the dimen-sionality of space. The value of the contour length step ds is an optimum value. The length of each block is dividedinto an integer number of steps, with the number of steps chosen to obtain an actual step size for each block that is asclose as possible to this input parameter.

4.4.8 BASIS

The BASIS block instructs the code to construct symmetrized basis functions that are invariant under the operationsof a specified space group. The file format for this block contains only one variable, a string named “group”, which isan identifier for the space group. The value of the “group” string can be either a standard name of one of the possiblespace groups or the path to a file that contains the elements of the group. Names of all possible space groups, in theform expected by PSCF, are given in the page on Space Groups.

Variable Type Descriptiongroup character(60) group name, or file name

4.4.9 ITERATE

The ITERATE command causes the program to read in an input omega file and then attempt to iteratively solve theSCFT equations for one set of input parameters. This is the workhorse of a SCFT computation. An ITERATE sectionmust immediately precede any SWEEP or RESPONSE section.



If an ITERATE section is immediately preceded by a RESCALE section, it will use the rescaled version of theomega field that was read by the RESCALE command. In that case, the ITERATE section should not contain aninput_filename parameter.

Parameters:

Variable Type Descriptionin-put_filename

charac-ter(60)

input omega file name

output_prefix charac-ter(60)

prefix to all output files

max_itr integer maximum allowed number of iterationsmax_error real tolerance - max. norm of residualdomain logical unit cell is variable if true, rigid if falseitr_algo charac-

ter(10)code for iteration algorithm

N_cut integer dimension of cutoff Jacobian in NR algorithm (required iff itr_algo =‘NR’)

N_hist integer Number of histories used in AM algorithm (required iff itr_algo =‘AM’)

Discussion:

The string “output_prefix” is concatenated with the suffixes ‘out’, ‘rho’, and ‘omega’ to create paths (file names) forthe output summary, output monomer concentration (rho) field, and output chemical potential (omega) field files. Theoutput prefix string should usually be either the name of a subdirectory followed by a “/” directory separator string,such as ‘out/’, in order to place these files in a separate directory, or a string that ends with a period, such as ‘out.’,to obtain files with file extensions ‘.out’, ‘.rho’ and ‘.omega’. In all of the examples, we set output_prefix = ‘out/’ toplace all output files in a subdirectory.

The value of the “domain” logical parameter determines whether PSCF attempts to solve the self-consistent fieldequations in a fixed unit cell (if domain == F) or whether it adjusts the parameters of the unit cell so as to find a stateof vanishing stress, and thus minimum free energy (if domain == “T”).

The value of the string “itr_algo” determines the choice of iteration algorithm. The only valid values (thus var) are“NR” or “AM”.

If “itr_algo” is “NR”, PSCF uses a quasi-Newton-Raphson iteration algorithm that is unique to this program. Thisalgorithm constructs a physically motivated initial approximation for the Jacobian matrix in which elements associatedwith long wavelength components of the 𝜔 field are computed numerically and shorter wavelength components areestimated. After construction and inversion of this initial estimate, Broyden updates of the inverse Jacobian are usedto refine the estimate of the inverse Jacobian. This method requires a parameter “N_cut”, which determines how manyrows and columns of the Jacobian matrix are to be computed numerically. The time required to construct the initialestimate of the Jacobian, which can become quite long for 3D problems that require many basis functions, increaseslinearly with “N_cut” . For problems involving relatively simple 3D unit cells of block copolymer melts, values ofN_cut of order 100 often provide a reasonable balance between accuracy and cost. One important disadvantage of the“NR” algorithm is that it requires storage of the full Jacobian matrix, which can become impossible for problems withmore than about 10,000 basis functions.

If “iter_algo” is set to “AM”, PSCF using an Anderson mixing algorithm that uses much less memory. This algorithmrequires an integer parameter “N_history” that determines how many previous iterations are stored and used to estimateeach update. We often set N_history = 30.



4.4.10 SWEEP

The presence of a SWEEP section instructs the program to solve the SCFT for a sequence of nearby values of param-eters along a line through parameter space (a ‘sweep’). We define a sweep contour variable s that varies from 0 upto a maximum value s_max, in increments of 1. For each integer step in the sweep parameter, the user may specifya fixed increment per step for any of the real parameters that are relevant to the problem. The parameters that canbe incremented include all of the real parameters in the MONOMERS, CHAINS, SOLVENTS, COMPOSITION, andINTERACTION section (i.e., all parameter in these sections for which a floating point value or an array of floatingpoint values is given in the parameter file). For simulations with a fixed unit cell (domain=1), the elements of theunit_cell_param array may also be incremented.

The desired increment per step for any variable <name> is specified by the value or (for an array) array of values ofa corresponding increment variable named d_<name>. Any number of increments may be specified. Variables thatare not incremented do not need to be referred to explicitly - increments of zero are assigned default. When an array-valued variable is incremented, however, increment values must be specified for all of the elements of the array. Thereading of increment variables ends when the program encounters the line containing the string “end_increments”.

Variable Type Descriptions_max real maximum value of sweep contour variables_<name> type of <name> increment in variable <name>end_increments none indicates end of the list of increments

4.4.11 RESPONSE

The presence of a RESPONSE section instructs the program to calculate the linear response matrix for a convergedordered structure at one or more k-vectors in the first Brillouin zone. If the linear response is calculated for more thanone k-vector, they must lie along a line in k-space, separated by a user defined vector increment.

Variable Type Descriptionpertbasis char If ‘PW’ => plane wave basis. If ‘SYM’ => symmetrized basis functionsk_group character Group used to construct symmetrized basis functionskdim int # dimensions in k-vector (kdim >= dim)kvec0(i) real initial k-vector, i=1,. . . ,kdimdkvec(i) real increment in k-vectornkstep integer # of k-vectors

4.4.12 FIELD_TO_RGRID

This command reads a file containing a field in the symmetry-adapted Fourier expansion format and outputs a rep-resentation containing values of the field on a coordinate space grid. This and the other commands to transformrepresentation can be applied to either a rho or omega field.

Variable Type Descriptioninput_filename character(60) input file name (symmetry-adapted format)output_filename character(60) output file name (coordinate grid format)

4.4.13 RGRID_TO_FIELD

This command performs the inverse of the transformation performed by FIELD_TO_RGRID: It reads a file containingvalues of a field on the nodes of a coordinate grid and outputs a file containing a representationo as an symmetry-



adapted Fourier expansion.

Variable Type Descriptioninput_filename character(60) input file name (coordinate grid)output_filename character(60) output file name (symmetry-adapted)

4.4.14 KGRID_TO_RGRID

This command inverts the operation applied by RGRID_TO_KGRID: It reads a file containing values Fourier compo-nents of a field on wavevectors on a k-space FFT grid, performs an inverse Fourier transform, and outputs values ofthe field on a coordinate r-space grid.

Variable Type Descriptioninput_filename character(60) input file name (wavevector grid)output_filename character(60) output file name (coordinate grid)

4.4.15 RHO_TO_OMEGA

This command reads a file containing a monomer concetnration field and outputs a corresponding initial guess forthe omega field. Both input and ouput files use the symmetry-adapted Fourier expansion format. The omega fieldis computed by simply setting the Lagrange multiplier pressure field to zero, giving a field that only contains thecontributions that arise from the excess interaction free energy, e.g., terms that explicitly involve the Flory-Hugginschi parameter. This command is intended to be used to generate an initial guess for $omega$ from an approximatestructural model for the volume fraction fields in a particular structure.

Variable Type Descriptioninput_filename character(60) input rho file name (symmetry-adapted)output_filename character(60) output omega file name (symmetry-adapted)

4.4.16 RESCALE

This command reads in an omega file, then applies a change in the convention for the monomer reference volume tothe omega field and to all parameters whose value depend upon an implicit choice of monomer reference volume. Thiscommand may only be called (if at all) immediately prior to an ITERATE commands, in order to read in an omegafield and then change the convention for the monomer reference volume prior to solving the SCFT equations.

This command applies a change in the omega field and various properties that corresponds to a change of the monomerreference volume 𝑣 by a factor 𝑣 → 𝑣/𝜆. The scale factor 𝜆 is given in the parameter file by the input variable“vref_scale”.

Variable Type Descriptioninput_filename character(60) input omega file namevref_scale real scale factor :math:‘lambda’

This command applies the following set of transformations to each block length 𝑁 , solvent size 𝑆, statistical segmentlength 𝑏, Flory-Huggins interaction parameter 𝜒, and monomer chemical potential field 𝜔:



Variable type Symbol New valueblock length 𝑁 𝑁𝜆solvent size 𝑆 𝑆𝜆

monomer length 𝑏 𝑏/√𝜆

interaction 𝜒 𝜒/𝜆field 𝜔 𝜔/𝜆

The SCFT equations can be shown to be invariant under such a change in convention for the definition of a “monomer”.Also note that this transformation leaves invariant any product 𝜒𝑁 of a interaction parameter and a block or a chainlength or any product 𝜔𝑁 of a chemical potential field per monomer and the number of monomers in a block, both ofwhich correspond to measures of the free energy of interaction of a block with its surroundings. The transformationalso leaves invariant any product

√𝑁𝑏 that corresponds to a random-walk coil size.

Applying this rescaling to an omega field that already solves the SCFT equations for the choice of parameters given inthe parameter file simply generates an equivalent solution corresping to a rescaled choice of parameter values. Usingthe RESCALE command to read in a file containing such a converged solution should thus cause the subsequentITERATE command to terminate immediately, since the error should be less than the numerical threshhold on input.This would cause the program to immediately output the rescaled parameters to an output summary file and therescaled omega field to an output omega file.

4.4.17 OUTPUT_WAVES

This command outputs a file that describes the relationship between complex exponential plane wave basis functionsand symmetry-adapted basis functions. The resulting file lists which star each wavevector belongs to and the coefficientof the plane-wave within a symmetry adapted basis function assocated with that star.

Variable Type Descriptionoutput_filename character(60) output file name

4.4.18 OUTPUT_GROUP

Output all symmetry elements of the current space group to a file. See the discussion of space group SymmetryElements for a discussion of the internal representation of space groups and the output file format.

Parameters:

Variable Type Descriptionoutput_filename character(60) output file name

4.4.19 FINISH

The FINISH string is the last section of any parameter file, and causes program execution to terminate.


CHAPTER 5

Output Summary File

When the self-consistent field problem is solved for a specific set of parameters, in response to an ITERATE commandin the parameter file, PSCF outputs an output summary file named “out”, in addition to files containing the final omegaand rho fields. The format of this summary file is similar to that of the parameter file, except that it contains someadditional information about thermodynamic properties and computational details near the end of the file.

Example

Here is an example of an output summary file produced by a simulation of the BCC of a diblock copolymer melt. Themajority of the file, up until the FINISH line, has the same format as a parameter file, so that this part of the file canbe used as the basis of a parameter file for a new simulation. The THERMO and STATISTICS sections appear afterthe FINISH line, and contain additional information about, respectively, thermodynamic properties of the convergedsolution and about computational aspeces of the simulation.

format 1 0

MONOMERSN_monomer

2kuhn

1.0000000000E+00 1.0000000000E+00

CHAINSN_chain

1N_block

2block_monomer

1 2block_length

2.0000000000E-01 8.0000000000E-01

COMPOSITIONensemble

0


33



phi_chain1.0000000000E+00

INTERACTIONinteraction_type

'chi'chi

2.4000000000E+01

UNIT_CELLdim

3crystal_system

'cubic'N_cell_param

1cell_param

1.8447588337E+00

DISCRETIZATIONngrid

24 24 24chain_step

1.0000000000E-02

BASISgroup_name

'I m -3 m'

ITERATEinput_filename

'in.omega'output_prefix

'out/'max_itr

20error_max

1.0000000000E-08domain

Titr_algo

'NR'N_cut

95

FINISH

THERMOf_Helmholtz

2.7451703490E+00f_homo

2.8400000000E+00pressure

3.7365224085E+00mu_chain

6.4816927575E+00stress


34 Chapter 5. Output Summary File



-6.0758291562E-11

STATISTICSN_star

231final_error

6.0758291562E-09iterations

10basis_time

5.6800000000E+00scf_time

1.3674400000E+02

THERMO Section

The thermodynamics section contains final values for the following thermodynamic properties of the converged solu-tion. All quantities that involve energy (i.e., f_Helmholtz and mu) are output in units in which thermal energy is set tokT=1. The pressure is output in units in which kT=1 and in which the monomer reference volume is =1.

Variable Descriptionf_Helmholtz Helmholtz free energy per monomer / kTf_homo f_Helhmoltz of a hypothetical homogeneous mixturepressure Macroscopic pressure x monomer volume / kTmu_chain chemical potential / kT, for each polymer speciesmu_solvent chemical potential / kT, for each solvent speciesphi_chain total volume fraction for each polymer speciesphi_solvent total volume fraction for each solvent speciesstress derivatives of free energy per monomer / kT

Values of mu_chain and mu_solvent appear in this section if and only if the calculation was carried out in canonicalensemble (ensemble == 0), in which case the corresponding species volume fractions are given as input parametersin the COMPOSITION section. Conversely, values of phi_chain and phi_solvent vectors appear in this output sectiononly if the calculation was carried out in grand-canonical ensemble (ensemble == 1), in which case the correspondingchemical potential values are given as inputs in the COMPOSITION section.

Units: The Helmholtz free energy f_Helmholtz is given in this section is a dimensionless free energy per monomer,normalized by kT. In the simple case of a single component block copolymer melt, the free energy per chain is thengiven by the product of f_Helmholtz and the overall chain length (sum of the block lengths given in the parameterfile). Similarly, the reported pressure is a dimensionless value obtained by multiplying the pressure by the monomerreference volume and then dividing by kT. Values of mu_chain and (if present) mu_solvent are instead free energiesper molecule, normalized by kT.

In a system with more than one chain and/or solvent component, a value would be given for the chemical potentialof each species, with one value per line. The mu_solvent (in canonical ensemble) or phi_solvent (in grand-canonicalensemble) array appears only if the parameter file has a SOLVENTS input section with one or more solvent species.

Each element of the array of values of “stress” is the derivative of the dimensionless free energy per monomerf_Helmholtz with respect to one of the unit cell parameters. The number of elements is thus equal to N_cell_param,the number of parameters required to describe the unit cell. All components of this array should be very close to zeroat the end of a computation with a flexible unit cell (domain == T).

Please refer to the Appendix: Self-Consistent Field Theory for documentaiton of the mathematical expressions used tocompute free energies and other physical properties.

STATISTICS Section

35


The statistics section contains information about the size N_star of the basis used to approximate the rho and omegafields, the number of iterations required, the final error, and the amount of time taken for different parts of the compu-tation. Times are given in seconds.

36 Chapter 5. Output Summary File

CHAPTER 6

Field Files

PSCF uses several file formats to describe fields, and uses the same set of formats for both “omega” and “rho” fields.In each of the available file formats, for a system with with N_monomer monomer types, a single file contains adescription of N_monomer “omega” or “rho” fields, each of which is associated with a specific monomer type. Werefer to such a set of N_monomer fields in what follows as a multi-component field.

PSCF can read, write and intercovert three different file formats for multi-component fields, which are based ondifferent mathematical representations of a field. These are:

• Symmetry-Adapted Format

• Coordinate Grid Format

• Wavevector Grid Format

Each of these three format is discussed in a separate section below. The symmetry-adaped format is based on gen-eralized Fourier expansion using a basis of symmetry-adapted basis functions. This is the default file format that isused by the ITERATE command for the input omega field and the output omega and rho fields. The coordinate spacegrid format contains the values of all fields on regular grid of points within one unit cell, and is useful as an input toexternal programs that can visualize a structure.

6.1 Symmetry-Adapted Format

This default file format used by the ITERATE command is based on an expansion of each field as an expansion interms of basis functions that exhibit the space group symmetry of the crystal. In what follows, we first discuss theunderlying mathematical expansion, and then the file format

Mathematical Basis

Consider a system with N_monomer monomer types indexed by an integer 𝛼 = 1, . . . , N_monomer. Let 𝜔𝛼(r) denotea field (e.g., a monomer chemical potential field) associated with monomer type 𝛼 . We approximate the field 𝜔𝛼 asan expansion of the form

𝜔𝛼(r) =

𝑁𝑠𝑡𝑎𝑟∑︁𝑖=1

𝜔𝑖𝛼𝑓𝑖(r)

37


in which each function 𝑓𝑖(r) is a real basis function, 𝜔𝑖𝛼 is an associated real coefficient, and 𝑁𝑠𝑡𝑎𝑟 is the numberof basis functions used to approximate the field. In a symmetry-adapted Fourier expansion of a field with a specifiedspace group symmetry, each basis function 𝑓𝑖(r) is a real function that is invariant under all symmetry elements of thechosen space group, and is also an eigenfunction of the Laplacian, such that

−∇2𝑓𝑖(r) = 𝜆𝑖𝑓𝑖(r)

for some 𝜆𝑖 ≥ 0. The basis functions form an orthogonal basis, which are normalized such that

1

𝑉

∫︁𝑑𝐷𝑟 𝑓𝑖(r)𝑓𝑗(r) = 𝛿𝑖𝑗

where the integral is taken over one unit cell of a periodic structure in D-dimensional space and 𝑉 is the generalizedvolume (length, area or volume) of the unit cell. Here 𝛿𝑖𝑗 denotes the Kronecker delta function, which is defined to be𝛿𝑖𝑗 = 1 for 𝑖 = 𝑗 and 0 otherwise

Each symmetry-adapted basis function can be expressed as a superposition of plane waves with wavevectorsk1, . . . ,k𝑀 that are reciprocal lattice vectors of equal equal magnitude, as a sum of the form

𝑓𝑖(r) =

𝑀∑︁𝑖=1

𝑎𝑖𝑒𝑖k𝑖·r

where 𝑀 is the number of associated plane waves, and where the the coefficients 𝑎1, . . . , 𝑎𝑀 are complex numbersthat all have equal magnitude |𝑎1| = |𝑎2| = · · · |𝑎𝑀 | = 1/

√𝑀 .

For any space group with inversion symmetry (i.e., a centrosymmetric group), the set of wavevectors associated with abasis function is a set of vectors that are related to one another by the point group symmetries of the crystal. For non-centrosymmetric groups, the wavevectors associated with a real basis function are related by point group symmetriesor by inversion (i.e., by the relation k → −k). A group of reciprocal lattice wavevectors that are related by symmetriesof the crystal is referred to here and in the PSCF source code as a “star”. The number of stars, denoted by N_star inthe corresponding file format, is equal to the number of basis functions. In a cubic crystal, for example, each star ofwavevectors (and thus each basis functions) correspond to a family of wavevectors with integer indices {ijk} that arerelated to one another by permutations and/or sign changes. For example, the basis function associated with the {321}star has 48 associated wavevectors that include wavevectors with integer indices (1,2,3), (3,2,1), (-3,2,1), etc, whereasthe {200} star in a cubic crystal has only six wavevectors (±2, 0, 0), (0,±2, 0), (0, 0,±2).

Each basis function for d-dimensional crystal is uniquely identified in the symmetry-adapted file format by a labelconsisting of d integer indices. These indices correspond to the Miller indices for one of the wavevectors associ-ated with the basis function. Thus for example, we identity the basis function associated with the {321} family ofwavevectors in a cubic crystal by a label “3 2 1”. The conventions for choosing which plane wave to use to identifythe basis function is discussed in the comments provided in the source code of crystal_mod (See the html developersmanual for browseable version of this. The set of Miller indices output to file corresponds to the value of the variablewave_of_star.)

Example: 3D Gyroid Phase

Below is an example of a “rho” file output from a simulation of a gyroid phase for a diblock copolymer melt. A sectionof the middle of this file has been removed, as indicated by the vertical dots.

format 1 0dim

3crystal_system

'cubic'N_cell_param

1cell_param


38 Chapter 6. Field Files



3.6735414146E+00group_name

'I a -3 d'N_monomer

2N_star

2353.000000000000E-01 7.000000000000E-01 0 0 0 1

-2.942897932802E-01 2.942897932848E-01 2 1 1 24-9.425546329793E-02 9.425546327223E-02 2 2 0 12-3.864399409689E-03 3.864399436086E-03 3 2 1 48-1.483047814338E-02 1.483047815806E-02 4 0 0 6-3.546446264855E-02 3.546446265383E-02 4 2 0 243.138519869858E-02 -3.138519870524E-02 3 3 2 242.003121375277E-02 -2.003121374994E-02 4 2 2 241.572048423239E-02 -1.572048424396E-02 4 3 1 48

-1.376822797257E-02 1.376822798292E-02 5 2 1 48-1.063353913450E-02 1.063353913935E-02 4 4 0 12

. . . . . .

. . . . . .

. . . . . .-7.575067702553E-05 7.575067344206E-05 13 13 10 24-2.570604494615E-05 2.570604263390E-05 14 12 10 24-5.627606758688E-05 5.627606408758E-05 14 14 8 65.879116047898E-05 -5.879115755266E-05 14 14 12 6

Example: 1D Lamellar Phase

Below is an example the “rho” file output for a small simulation of a lamellar phase of a diblock copolymer melt:

format 1 0dim

1crystal_system

'lamellar'N_cell_param

1cell_param

1.3835952906E+00group_name

'-1'N_monomer

2N_star

215.600000000000E-01 4.400000000000E-01 0 12.179734275940E-01 -2.179734275841E-01 1 2

-1.523969262415E-02 1.523969262143E-02 2 2-5.575240954520E-03 5.575240954490E-03 3 21.108470498335E-03 -1.108470498556E-03 4 21.455449531056E-04 -1.455449530934E-04 5 2

-6.218980135235E-05 6.218980146350E-05 6 2-8.059872486808E-07 8.059872753625E-07 7 22.826732709838E-06 -2.826732713547E-06 8 2

-2.194238294935E-07 2.194238338772E-07 9 2-1.060764766149E-07 1.060764782164E-07 10 21.946388906884E-08 -1.946388995126E-08 11 2


6.1. Symmetry-Adapted Format 39



3.010764186682E-09 -3.010764203812E-09 12 2-1.161872573075E-09 1.161872692383E-09 13 2-3.137859071779E-11 3.137865228352E-11 14 25.685537948359E-11 -5.685537190418E-11 15 2

-3.817653721188E-12 3.817577312625E-12 16 2-2.332684668702E-12 2.332625641218E-12 17 24.053664853576E-13 -4.051318636739E-13 18 23.071545504276E-14 -3.077687877704E-14 19 2

-1.475930488937E-13 -4.916067553040E-14 20 1

Description of Format

This first part of such a field file is a header that ends with the parameter N_star, which is the number of basis functions.This is followed by a data section that that is N_star rows long. Each row in the data section contains the coefficientsassociated with one basis function in the symmetry-adapted Fourier expansion described above, along with someadditional information that identifies the basis function.

The structure of the header is similar to that of the parameter file. The first line specifies a file format version number(file format v1.0). The rest of the header contains information that is required to interpret the field file, including thedimensionality of the structure (1,2, or 3) , the crystal system, the unit cell parameters, the space group, the numberof monomer types, and the number of basis functions, denoted here by N_star. The second example above is for alamellar structure with inversion symmetry, for which the space group symbol is -1.

The data section contains N_star rows, each of which contains the coefficients associated with one basis function, alongwith an identifier for the basis function. The first N_monomer columns of row i (e.g., the first two columns, in both ofthe above examples) contain the coefficients associated with different monomer types. Specifically, a coefficient 𝜔𝑖𝛼

associated with basis function 𝑖 and monomer type 𝛼 is given in column 𝛼 of row i of this data section.

In the file format for a crystal with dimension d (e.g., d=1 for a lamellar phase or d=3 for a gyroid phase) the next dcolumns, after the columns containing the expansion coefficients, contain a set of d integers that identify each basisfunction. As discussed above, these are integer indices for one of the wavevectors in the basis function. The lastcolumn is the number of wavevectors in an associated star of wavevectors, which we will refer to as the multiplicity.

The first basis function in the symmetry adapted Fourier expansion, which is given in the first row of the data section, isalways the spatially homogeneous function 𝑓1(r) = 1. This constant function is associated with the single wavevectork = 0, and identified in a 3D crystal by a label “0 0 0”, with multiplicity 1.

The second row in the gyroid example contains the coefficients for the basis function associated with the {211} familyof wavevectors, which is identified in columns 3-5 by the label “2 1 1”. Because this family contains 24 wavevectors,the last column lists a multiplicity of 24. The {211} family is the first star of non-zero wavevectors from which itpossible to construct a nonzero basis function that is invariant under all of the symmetries of space group 𝐼𝑎3̄𝑑 of thegyroid structure. The stars that can be used to construct a basis function are precisely those that satisfy the reflectionrules for allowed reflections in scattering from a particular space group symmetry, for which the {211} family givesthe first allowed family of reflections in scattering from a gyroid crystal.

Consider the second example, which is 1D lamellar phase with inversion symmetry. The first basis function is theconstant 𝑓1(𝑟) = 1, with a label “0” and a multiplicity 1. All subsequent basis functions are cosine functions of theform 𝑓𝑛+1(𝑟) =

√2 cos(𝑘𝑛𝑟) with 𝑘𝑛 = 2𝜋𝑛/𝐿 for a crystal with period 𝐿, for which we see an integer label n.

The multiplicity of each cosine basis function is 2, as indicated in the last column, since each such function can beexpressed as a superposition of two plane waves of wavenumbers ±𝑘𝑛.

The rules for constructing real basis functions for non-centrosymmetric space groups is somewhat more complicatedthan for centrosymmetric groups. When the group has no inversion symmetry, a basis function that is constructed bysuperposing plane waves that are related by symmetry elements of the space group will generally not be proportionalto a real function. The simplest example of this is a one dimensional crystal with no inversion symmetry (group 1), andthus no symmetry elements other than the identity. In this case, no plane wave is related to any other by symmetry. Thenatural basis functions, from the point of view of symmetry alone, are single complex exponential plane waves, but



these are complex functions of position. In order to construct basis functions that are real, in this example, one mustconstruct two real superpositions of each pair of plane waves that are related by inversion (which is not a symmetry ofthe crystal). The required basis functions in this case are both cosine and sine functions. More generally, to form realbasis functions in crystals with no inversion symmetry, we use generalizations of the cosine and sign functions thatare construction by constructing two different superpositions of “stars” that are related to one another by inversion.Conventions used for doing this are described best in the comments in the source code for the basis_mod module.

6.2 Coordinate Grid Format

PSCF can also output the values of set of fields (one per monomer type) evaluated on all of the grid points of the FFTgrid that is used to solve the modified diffusion equation.

Example: 2D Hex Phase of Diblock Copolymer Melt

Here is example of a converged omega field for a hex phase:

format 1 0dim

2crystal_system

'hexagonal'N_cell_param

1cell_param

1.7703537313E+00group_name

'P 6 m m'N_monomer

2ngrid

24 240.340581085 19.5188398830.570887775 19.6580200871.199229419 19.9846095172.070864605 20.2330127352.929754416 19.853514300

. .

. .

. .0.999219800 19.8902580660.570887775 19.658020087

Description of Format

Like the others, this file format contains a header section with crystallographic information followed by a data section.The header section is similar that for the symmetry adapted format, except that the last variable is an array “ngrid” ofintegers giving the number of grid points in each direction. In this example, because it is a two-dimensional crystal(dim = 2), this array contains two numbers, both 24, indicating a grid in which there are 24 grid points along each axis.To describe a hexagonal phase, we use a non-orthogonal coordinate system in which each axis is parallel to one of theBravais lattice vectors, which in a hexagonal phase have an angle of 60 degrees between.

The data section contains the values of fields associated with N_monomer monomer types at grid points given by

r(𝑛1, . . . , 𝑛𝐷) =

D∑︁𝑖=1

𝑛𝑖

𝑁𝑖a1

6.2. Coordinate Grid Format 41


where 𝐷 is the dimensionality of the crystal (denoted by “dim” in the header and the parameter file), a𝑖 is a Bravaislattice vector, 𝑁𝑖 is the number of grid points along direction 𝑖, and 𝑛𝑖 is an integer index in the range 0 ≤ 𝑛𝑖 < 𝑁𝑖.The number of rows in the data section is equal to the total number of grid points. Each row in this section containsvalues of all field components at a single grid point. The number of columns is equal to the number of monomer types,so that data in column 𝛼 contains the values of the field associated with monomer type 𝛼.

Grid points are listed in order using index 𝑛1 as the most rapidly varying (innermost) loop index. This is implementedin the field_io_mod module, in subroutines output_field_grid and input_field_grid as a fortran loop of the form:

do n3 = 0, ngrid(3) - 1do n2 = 0, ngrid(2) - 1do n1 = 0, ngrid(1) - 1

[Read or write data at grid point r(n1, n2, n3)]enddo

enddoenddo

6.3 Wavevector Grid Format

Finally, PSCF can read and write the unsymmetrized discrete Fourier transform of a multi-component field, which isrelated to the values on a grid a by discrete Fourier transform. The required file format is very similar to that used forthe coordinate space grid. The file consists of a header and a data section. The format of the header is identical to thatused for the coordinate grid format, and includes a list of the number of grid points used in each direction, denoted byngrid.

The data section contains the Fourier coefficients obtained by a discrete Fourier transform of each field at wavevectorsgiven by

k(𝑛1, . . . , 𝑛𝐷) =

D∑︁𝑖=1

𝑛𝑖b𝑖

where 𝐷 is the dimensionality of the crystal (i.e., dim in the header file), b𝑖 is a reciprocal lattice basis vector, 𝑁𝑖

is the number of grid points along direction 𝑖, and 𝑛𝑖 is an integer in the range 0 ≤ 𝑛1 ≤ 𝑁1/2 for the first indexand 0 ≤ 𝑛𝑖 ≤ 𝑁𝑖 − 1 for indices 𝑖 > 1. The number of rows in the data section is equal to the total numberof such wavevectors, and each row contains values of Fourier coefficients associated with a single wavevector, withcoefficients for fields associated with different monomer types in different columnns.

Coefficients for different wavevectors are output in sequential order, using the last index (e.g., 𝑛3 for a 3D crystal) asthe most rapidly varying (inner-most) loop index. This is implemented by a fortran loop of the form:

do n1 = 0, ngrid(1)/2do n2 = 0, ngrid(2) - 1do n3 = 0, ngrid(3) - 1

[Read or write coefficients for wavevector k(n1, n2, n3)]enddo

enddoenddo


CHAPTER 7

Unit Cell

The variables in the UNIT_CELL section of the parameter file specify the Bravais lattice of the crystal. The variablesrequired in this section, in the required order, are:

Variable Meaningdim number of periodic directions (1,2, or 3)crystal_system lattice system string identifierN_cell_param the number of required unit cell parameterscell_param an array of unit cell parameter values

The “crystal_system” for a three dimensional crystal string could, for example, be “cubic”, “tetragonal”, “orthorhom-bic” or several other possibilities. All allowed values of the “crystal_system” string are given below 1, 2 and 3dimensionally periodic systems. The number N_cell_param of parameters required to specify the unit cell is alsolisted for each crystal_system, along with the meaning and order of appearance of different parameters. The valueof N_cell_param, is, for example, 1 for a 1D lamellar phase, a 2D hexagonal phase or a 3D cubic phase, 3 for anorthorhombic 3D phase or 6 for a triclinic 3D phase.

Below, we discuss all possible crystal systems of 1, 2, and 3 dimensional crystals separately. Lists of the names of allpossible space groups for each crystal system are given on the following page.

1D Crystal Systems

The only allowed crystal system name for a one-dimensional crystal is s “lamellar”. Only one unit cell parameteris required to specify a lamellar unit cell (i.e., N_cell_param = 1). The value of that parameter is equal to the layerspacing.

2D Crystal Systems

For two dimensional crystals (dim=2), let the parameters a and b denote the lengths of two independent Bravais latticebasis vectors. For oblique crystals, gamma denotes the angle between these two basis vectors, in radians.

43


systems N_cell_param cell_paramsquare 1 ahexagonal 1 arectangular 2 a, boblique 3 a, b, gamma

3D Crystal Systems

For three dimensional crystals (dim=3), the parameters a, b, and c are the lengths of the three Bravais lattice vectors,alpha is the angle between b and c, beta is the angle between c and a, and gamma is the angle between a and b.

3D systems N_cell_param cell_paramcubic 1 atetragonal 2 a, corthorhombic 3 a, b, cmonoclinic 4 a, b, c, betahexagonal 2 a, ctrigonal 2 a, alphatriclinic 6 a, b, c alpha, beta, gamma

44 Chapter 7. Unit Cell

CHAPTER 8

Space Groups

The symbol for a space group may be entered as the value of “space_group” in the BASIS section of the parameterfile. The tables below list the allowed space group symbols.

8.1 1D Space Groups

The only possible nontrivial symmetry for a one-dimensional lamellar phase is inversion symmetry. There are thus onlytwo possible groups: The centrosymmetric group (group -1) and the non-centrosymmetric group (group 1). Fields fora centrosymmetric lamellar phase are expanded using a basis of cosine waves, while fields for a non-centrosymmetricphase are expanded using a basis that contains both cosines and sine waves.

Number Symbol Comments1 -1 Inversion symmetry2 1 No symmetry

8.2 2D Space Groups

The names of all 17 possible 2D plane groups are given below in the text format expected by PSCF. The format used inPSCF for both 2D and 3D space group names is based on the names used in the international tables of crystallography,but allows space group names to be written as simple ascii text strings, which contain spaces between elements of thespace group name.

45


Number Symbol Lattice System1 p 1 oblique2 p 2 oblique3 p m rectangular4 p g rectangular5 c m rectangular6 p 2 m m rectangular7 p 2 m g rectangular8 p 2 g g rectangular9 c 2 m m rectangular10 p 4 square11 p 4 m m square12 p 4 g m square13 p 3 hexagonal14 p 3 m 1 hexagonal15 p 3 1 m hexagonal16 p 6 hexagonal17 p 6 m m hexagonal

8.3 3D Space Groups

The names of all possible 3D space groups are given below in the text format expected by PSCF. These names are basedon the names given in Hermann-Mauguin or “international” notation used the international tables of crystallography,but are given in a format that allows space group names to be written as simple ascii text strings, with no specialsymbols or subscripts. In this format, for example, the space group 𝐼𝑎3𝑑 of the gyroid phase (space group 230) iswritten as “I a -3 d”.

Name conventions

The following conventions are used to convert standard Hermann-Mauguin space group symbols into text strings:

• A single space is introduced between different elements of the space group name, with a few exceptions de-scribed below.

• Integers with overbars in the Hermann-Mauguin symbol, which indicate inversion (1) or a 3-, 4- or 6-foldrotoinversion axis (3, 4, or 6), are indicated in the PSCF text string by placing a “-” sign before the integer. Thusfor, example, 3 is replaced by “-3” in the ascii identifier “I a -3 d”.

• Integers with subscripts, such as 42, which represent screw axes, are indicated in the text representation byplacing the two integers directly adjacent, with no intervening white space. Thus, for example, 42 is replacedby “42”.

• Symbols that are separated by a slash appear with no space on either side of the slash.

• Different “settings” of the same space group, which correspond to different definitions of the origin of space inthe definition of the symmetry elements, are indicated by a colon followed by an integer label at the end of thespace group.

Space Groups

Number Symbol1 P 12 P -1Continued on next page

46 Chapter 8. Space Groups


Table 1 – continued from previous pageNumber Symbol3 P 1 2 14 P 1 21 15 C 1 2 16 P 1 m 17 P 1 c 18 C 1 m 19 C 1 c 110 P 1 2/m 111 P 1 21/m 112 C 1 2/m 113 P 1 2/c 114 P 1 21/c 115 C 1 2/c 116 P 2 2 217 P 2 2 2118 P 21 21 219 P 21 21 2120 C 2 2 2121 C 2 2 222 F 2 2 223 I 2 2 224 I 21 21 2125 P m m 226 P m c 2127 P c c 228 P m a 229 P c a 2130 P n c 231 P m n 2132 P b a 233 P n a 2134 P n n 235 C m m 236 C m c 2137 C c c 238 A m m 239 A b m 240 A m a 241 A b a 242 F m m 243 F d d 244 I m m 245 I b a 246 I m a 247 P m m m48 P n n n : 248 P n n n : 149 P c c m50 P b a n : 2Continued on next page

8.3. 3D Space Groups 47


Table 1 – continued from previous pageNumber Symbol50 P b a n : 151 P m m a52 P n n a53 P m n a54 P c c a55 P b a m56 P c c n57 P b c m58 P n n m59 P m m n : 259 P m m n : 160 P b c n61 P b c a62 P n m a63 C m c m64 C m c a65 C m m m66 C c c m67 C m m a68 C c c a : 268 C c c a : 169 F m m m70 F d d d : 270 F d d d : 171 I m m m72 I b a m73 I b c a74 I m m a75 P 476 P 4177 P 4278 P 4379 I 480 I 4181 P -482 I -483 P 4/m84 P 42/m85 P 4/n : 285 P 4/n : 186 P 42/n : 286 P 42/n : 187 I 4/m88 I 41/a : 288 I 41/a : 189 P 4 2 290 P 4 21 291 P 41 2 292 P 41 21 2Continued on next page



Table 1 – continued from previous pageNumber Symbol93 P 42 2 294 P 42 21 295 P 43 2 296 P 43 21 297 I 4 2 298 I 41 2 299 P 4 m m100 P 4 b m101 P 42 c m102 P 42 n m103 P 4 c c104 P 4 n c105 P 42 m c106 P 42 b c107 I 4 m m108 I 4 c m109 I 41 m d110 I 41 c d111 P -4 2 m112 P -4 2 c113 P -4 21 m114 P -4 21 c115 P -4 m 2116 P -4 c 2117 P -4 b 2118 P -4 n 2119 I -4 m 2120 I -4 c 2121 I -4 2 m122 I -4 2 d123 P 4/m m m124 P 4/m c c125 P 4/n b m : 2125 P 4/n b m : 1126 P 4/n n c : 2126 P 4/n n c : 1127 P 4/m b m128 P 4/m n c129 P 4/n m m : 2129 P 4/n m m : 1130 P 4/n c c : 2130 P 4/n c c : 1131 P 42/m m c132 P 42/m c m133 P 42/n b c : 2133 P 42/n b c : 1134 P 42/n n m : 2134 P 42/n n m : 1135 P 42/m b cContinued on next page



Table 1 – continued from previous pageNumber Symbol136 P 42/m n m137 P 42/n m c : 2137 P 42/n m c : 1138 P 42/n c m : 2138 P 42/n c m : 1139 I 4/m m m140 I 4/m c m141 I 41/a m d : 2141 I 41/a m d : 1142 I 41/a c d : 2142 I 41/a c d : 1143 P 3144 P 31145 P 32146 R 3 : H146 R 3 : R147 P -3148 R -3 : H148 R -3 : R149 P 3 1 2150 P 3 2 1151 P 31 1 2152 P 31 2 1153 P 32 1 2154 P 32 2 1155 R 3 2 : H155 R 3 2 : R156 P 3 m 1157 P 3 1 m158 P 3 c 1159 P 3 1 c160 R 3 m : H160 R 3 m : R161 R 3 c : H161 R 3 c : R162 P -3 1 m163 P -3 1 c164 P -3 m 1165 P -3 c 1166 R -3 m : H166 R -3 m : R167 R -3 c : H167 R -3 c : R168 P 6169 P 61170 P 65171 P 62172 P 64173 P 63Continued on next page



Table 1 – continued from previous pageNumber Symbol174 P -6175 P 6/m176 P 63/m177 P 6 2 2178 P 61 2 2179 P 65 2 2180 P 62 2 2181 P 64 2 2182 P 63 2 2183 P 6 m m184 P 6 c c185 P 63 c m186 P 63 m c187 P -6 m 2188 P -6 c 2189 P -6 2 m190 P -6 2 c191 P 6/m m m192 P 6/m c c193 P 63/m c m194 P 63/m m c195 P 2 3196 F 2 3197 I 2 3198 P 21 3199 I 21 3200 P m -3201 P n -3 : 2201 P n -3 : 1202 F m -3203 F d -3 : 2203 F d -3 : 1204 I m -3205 P a -3206 I a -3207 P 4 3 2208 P 42 3 2209 F 4 3 2210 F 41 3 2211 I 4 3 2212 P 43 3 2213 P 41 3 2214 I 41 3 2215 P -4 3 m216 F -4 3 m217 I -4 3 m218 P -4 3 n219 F -4 3 c220 I -4 3 dContinued on next page



Table 1 – continued from previous pageNumber Symbol221 P m -3 m222 P n -3 n : 2222 P n -3 n : 1223 P m -3 n224 P n -3 m : 2224 P n -3 m : 1225 F m -3 m226 F m -3 c227 F d -3 m : 2227 F d -3 m : 1228 F d -3 c : 2228 F d -3 c : 1229 I m -3 m230 I a -3 d

8.4 Symmetry Elements

A list of all of the symmetry elements of any space group can be output to file by placing a “OUTPUT_GROUP”command in the parameter file at any point after the “BASIS” section.

Every space group symmetry can be expressed mathematically as an operation

r → Ar + t

Here, r = [𝑟1, . . . , 𝑟𝐷]𝑇 is a dimensionless D-element column vector containing the components of a position withinthe unit cell in a basis of Bravais lattice vectors, A is a 𝐷×𝐷 matrix that represents a point group symmetry operation(e.g., identity, inversion, rotation about an axis, or reflection through a plane), and t is a dimenionless D-elementcolummn vector that (if not zero) represents a translation by a fraction of a unit cell. Every group contains an identityelement in which A is the identity matrix and t = 0.

The elements of the column vectors r and t in the above are dimensionless components defined using a basis of Bravaisbasis vectors. The position r = [1/2, 1/2, 1/2]𝑇 thus always represents the center of a 3D unit cell. The Cartesianrepresentation of a position vector is instead given by a sum

𝐷∑︁𝑖=1

𝑟𝑖a𝑖

in which a𝑖 is the Cartesian representation of Bravais lattice vector number i. The elements of the dimensionlesstranslation vector t are always either zero or simple fractions such as 1/2, 1/4, or 1/3. For example, a symmetry elementin a 3D BCC lattice in which A is the identity matrix and t = [1/2, 1/2, 1/2]𝑇 represents the purely translationalsymmetry that relates the two equivalent positions per cubic unit cell in a BCC lattice. Similarly, a glide plane in a3D crystal is represented by a diagonal A matrix with values of ±1 on the diagonal that represents inversion througha plane and a translation vector that represents a translation by half a unit cell within that plane.

The OUTPUT_GROUP command outputs a list of symmetry elements in which each element is displayed by showingthe elements of the matrix A followed by elements of the associated column vector t.

The Bravais lattice vectors used internally by PSCF for cubic, tetragonal, and orthorhombic 3D systems are orthogonalbasis vectors for the simple cubic, tetragonal, or orthorhombic unit cells, which are aligned along the x, y, and z axesof a Cartesian coordinate system. Similarly, the basis vectors used for the 2D square and rectangular space groups



are orthogonal vectors which form a basis for a cubic or rectangular unit cell. The grid used to solve the modifieddiffusion equation is based on the same choice of unit cell and, thus for example, uses a regular grid within a cubicunit cell to represent fields in a BCC or FCC lattice. For body-centered and space-centered lattice systems, it is worthnothing that this unit cell not a primitive (minimum size) unit cell of the crystal: For example, a cubic unit cell actuallycontains 2 equivalent primitive unit cells of a BCC lattice or 4 primitive cells of an FCC lattice.

One consequence of the fact that PSCF does not always use a primitive unit cell is that, in the Fourier expansion ofthe omega and rho fields, the Fourier coefficients associated with some sets of symmetry-related wavevectors (some“stars”) are required to vanish in order to satisfy the requirement that the field be invariant under all elements of thespecified space group. The rules regarding which stars must have vanishing Fourier coefficients are the same as therules for systematic cancellations of Bragg reflections in X-ray or neutron scattering from a crystal of the specifiedspace group. The procedure used by PSCF to construct symmetry adapted basis functions automatially identifies andaccounts for these systematic cancellations.

8.4. Symmetry Elements 53

CHAPTER 9

Python Tools

PSCF is distributed with a set of Python modules that can be used to simplify common data analysis and job preparationtasks. All of these modules are part of a Python package named pscf. These Python modules are located within thesource code repository in a subdirectory named tools/python/pscf of the git repository directory (e.g., of pscf/git).

9.1 Overview

The most important of these python modules are a set of modules that can read and write several of the file formatsused by PSCF. Each of these modules is a file that contains the definition of a single class, in which the name of theclass is a a capitalized version of the name of the file or module. The names of these main modules and the classesthey contain are as follows:

Module Class Descriptionparamfile ParamFile Reads and stores contents of a parameter filefieldfile FieldFile Reads and stores a symmetry-adapted field fileoutfile OutFile Reads and stores a output summary filesweep Sweep Reads and stores summary files produced by a sweep

The constructor for each of these classes takes the path to a file or (for the Sweep class) of a directory as an argument.The constructor for each class immediately reads a specified file or (for the Sweep class) a set of files, and thenconstructs a a Python object that then contains all of the data contain in the that file or set of files. The values of eachnamed variable or (for field files) array of values that are read from file is stored in a corresponding attribute (memberdata variable) of the associated Python object. If the name of a parameter or variable is identified by a label in the fileformat, then the name of the attribute that holds the value of that variable is always the same as the label used in thefile format.

The the constructors of the ParamFile, OutFile and FieldFile each parse a particular file format. Each of these threeclasses also has a method (member function) named “write”. The write function writes the current contents of theobject to an output file using the same file format as that read by the constructor, thus creating a file that can be readby PSCF.

55


The constructor and write function for each of these classes thus provide a basis for modifying files of the associatedtype. To modify an existing file, one must use the constructor to read that file and create an associated object, modifythe ojbect by using Python commands to assign new values to the attributes that hold the values of one or morevariables, and then write the modified object to a file. The write operation could either write to a new file, in order tocreate a modified version, or could overwrite the original file.

The FieldFile class provides some specialized functions to carry out common manipulations on entire lists of Fouriercoefficients. These include operations that add a new column to an array of coefficients, corresponding to a newmonomer, and to switch the values of coefficients associated with two monomers. These sorts of operations aresometimes needed when manipulating existing omega files in order to provide input files suitable for a related system,such as modifying a solution obtained previously for a AB diblock copolymer in order to provide a starting point fora series of simulations of an ABC triblock copolymer.

The Sweep class is somewhat different than the ParamFile, OutFile, and FieldFile classes, in that a Sweep reads andstores the contents of a sequence of output files, rather than a single file. The constructor for the Sweep class reads inall of the numbered output summary files that are produced by a PSCF “SWEEP” command and stores the contentsof these files as a Python list of OutFile objects. This provides a convenient basis for analyzing the results of a sweep,by looping over output files produced by different simulations and outputting values of selected variables (e.g., freeenergies) in a compact form suitable for plotting and/or further analysis.

To use any of these modules, one must first open a python interpreter, import the relevant class, and then constructan object of the desired type by passing the constructor the name of the file or directory of interest. This pattern isdemonstrated in each of the examples given below.

9.2 Python Environment

To use the pscf python package, Python obviously must be installed on your computer. Because Python is alsorequired to install PSCF from source, instructions for how to check whether Python is installed (it usually is) or installit if necessary are given in the documentation regarding Compiling from source, using cmake.

After PSCF is installed, whether it is installed using a binary installer or after compiling from source, copies of allassociated python modules are placed in a directory:

$(INSTALL_DIR)/lib/python2.7/site-packages/pscf

where $(INSTALL_DIR) is a place holder for the actual absolute path to the root of the installation directory tree. Thispscf/ subdirectory must be included in the PYTHONPATH environment variable in order for the Python interpreter tofind and use these modules. This can be accomplished by running script $(INSTALL)/bin/pscf-env, as discussed inmore detail in the discussion of Modifying Search Paths.

After running the pscf-env script, to confirm that the $PYTHONPATH is set up correctly, type:

> echo $PYTHONPATH

This will cause a string to be printed to the terminal that should include the absolute path of the relevant directory,either by itself or as part of a colon separated list of directories.

9.3 ParamFile

In the following example, we use class ParamFile to construct an object that contains the contents of a single parameterinput file named ‘param’ in the current directory, and print values of the parameter N_monomer (the number ofmonomer types) and the volume fraction of the first chain species. To do this, one could type the following:

56 Chapter 9. Python Tools


> pythonpython> from pscf.outfile import ParamFilepython> param = ParamFile('param')python> print out.N_monomerpython> print out.phi_chain[0]python> quit()

It is safe to try running this example on any of the examples input files that are provided for PSCF - these commandsdo not not modify any input files. If import statement produce an error indicating that python interpreter cannot findmodule pscf.outfile, this indicates indicates that the PYTHONPATH environment is not yet set correctly.

The first line in the above example opens an interactive python interpreter, which is closed by the last line. Thesecond line imports the class OutFile from module (or file) outfile of package pscf. The third line constructs an objectnamed “out” of class OutFile. This object then contains the contents of the file whose name (“param”) is passed as anargument to OutFile constructor function. In python, like in C++ or Java, a constructor function is invoked by usingthe name of the class as a function. The constructor for an OutFile takes a single file name as an argument.

After the constructor is called, object “out” contains the values of all of the variables stored in the file “param”. This isdemonstrated by the 4th and 5th line of the above example, which simply print the values of two variables, N_monomerand phi_chain[0], to the terminal. The value of any labelled parameter in the original file is stored in an attribute (ormember variable) whose name is the same as the name of the label associated with the parameter in the associated file.

Some parameters, such as phi_chain, are stored in PSCF in one-dimensional arrays in which different elements refer toe.g., different molecular species. All such array-valued parameters are stored in the associated python object as pythonlists. Individual elements of a python list can be accessed using a subscript notation identical to that used to accesselements of an arrays in C, using indices that are numbered consecutively from 0. This is demonstated by the 5th lineof the above example, in which we use the symbol ‘out.phi_chain[0]’ to access the value of the volume fraction of thefirst (index 0) polymer species.

Note: All pscf python modules use the C/Python convention in which C array and python list indices are numberedconsecutively from zero. Because PSCF itself is written in Fortran, it instead uses the Fortran convention in whichindices start from 1. One consequence of this is that, for example, data associated with the second of two or moremonomer types is associated with a list index of 1 in all python objects, but is labelled by an integer “2” throughout thesource code of PSCF. This means, for example, that values of the block_monomer array in the PSCF input parameterfile, which uses the Fortran convention to assign monomer type label values, uses index values defined using the fortranconvention, in which an index “2” refers to the second monomer type. Users need to be aware of this difference andcorrect for it as necessary when using the python modules.

9.4 OutFile

Output summary files can be parsed, modified and output using a syntax essentially identical to that used for parameterfiles. In the following simple example, we read an output summary file in the working directory named ‘out’, and thenprint out the values of f_Helmholtz, the free energy per monomer, and mu_chain[0], the chemical potential of the firstchain species:

> pythonpython> from pscf.outfile import ParamFilepython> out = ParamFile('out')python> print out.f_Helmholtzpython> print out.mu_chain[0]python> quit()

Because the first part of an output summary file has the same syntax as an input parameter file, an output summary filefrom one simulation can be used as a starting point for creating a parameter file for a related system. This can be done

9.4. OutFile 57


either by manually editing and copying the output file, or by using python to read the file, modify the values of a fewparameters and write the contents of the modified object to a new file.

One advantage of using an output from one simulation to create an input for another is that the parameter file sectionof an output file is not exact copy of the parameter file used to run the simulation, and may contain final convergedvalues of parameters for which initial guesses are provided in the input file but then modified by the iteration algorithm.Specifically, the output file for a simulation that is performed with a deformable unit cell will contain the final valuesof the unit cell parameters.

9.5 FieldFile

A FieldFile object holds all of the information stored in the symmetry-adapated field file format. This includes thevalues of the coefficients of all basis functions in the symmetry-adapted Fourier expansion of the field associated witheach monomer type. The Field file can be used to read and manipulate either rho (volume fraction) or omega (chemicalpotential) files, which use the same file format.

A Field object is constructed using a syntax similiar to that for a ParamFile or OutFile object. To create an objectnamed “omega” that contains the contents of a field file named “omega”, one would enter:

> pythonpython> from pscf.fieldfile import FieldFilepython> omega = FieldFile('omega')

Attributes

A symmetry-adapted field file contains a header with labelled parameters followed by a data section. The value ofeach of the parameters that appears in the header is stored in an attribute with a name given by the parameter label inthe corresponding file, as for parameters in a parameter file or an output summary file.

The data section of a field file contains columns of numbers that represent coefficients of different basis functions ina symmetry adapted Fourier expansion. The contents of the data section are stored in three attributes named “fields”,“waves” and “counts”, as discussed below.

The “fields” attribute is a list of lists of Fourier coefficients. Each element of list fields is a list that contains of theFourier coefficients for one monomer type. Thus, for example, if omega is a Field object, omega.fields[0] is a listthat contains the coefficients given in the first column of the data section of the associated file, which defines the fieldassociated with the first monomer type. The item fields[1][13] is a real number that is equal to the coefficient of basisfunction 13 (the 14th basis function, with indices numbered from 0) of the field associated with monomer type number1 (i.e., the 2nd monomer type).

The “waves” attribute of a Field object is a list in which each element contains a list of 1, 2, or 3 integer Miller indicesfor a wavevector characteristic of the associated basis function. The number of indices is equal to the dimension ofspace (i.e., the number of directions in which the structure is periodic). These indices identify one of the wavevectorsthat is used to construct the the basis function, and acts as an identifier for the basis function. Thus, for example, forthe gyroid phase, the second basis function, with index 1, is associated with the {211} family of plane waves. In thiscase, the value of waves[1] is a list of 3 integers, waves[1] == [2, 1, 1], that identifies the basis function constructedfrom this family (or “star”) of wavevectors.

The attribute “counts” contains the integers given in the last column of the data section of a field file. Each of theseintegers gives the number of wavevectors in a “star” of symmetry related wavevectors that is associated with thecorresponding basis function. Thus for example, in a file for a gyroid phase, with space group “I a -3 d”, for whichwaves[1] = [2, 1, 1], count[1] == 24, because there are 24 wavevectors in the {211} family of wavevectors of a cubiccrystal.

In the following example, we open and read a chemical potential field file named ‘omega’ in the current directory,print the list of Miller indices that identifies basis function number 1 (the second basis function), and print the valueof the coefficient of this basis function in the expansion of the chemical potential field for monomer type number 0:



> pythonpython> from pscf.fieldfile import FieldFilepython> omega = FieldFile('omega')python> print omega.waves[1]python> print omega.fields[0][1]

9.6 Sweep

The Sweep class is a container that holds all of the data given in the set of number output summary files produced bya PSCF SWEEP command.

The SWEEP command performs a sequence of SCFT calculations along a line in parameter space. This commandproduces a set of output files for each of the resulting points in parameter space, with file names that begin with aninteger index. The resulting output summary files have names of the form <output_prefix>i.out, where <output_prefix>denotes the output_prefix string parameter given in the input parameter file, and where i is an integer index. The indexi has values in the range [0, s_max], where s_max is the maximum value given in the parameter file. Typically, thestring output_prefix is taken to be the name of a directory including a trailing backslash (/) directory separator, such as“out/”. In this case, the SWEEP produces a series of output summary files in the specified directory with names 0.out,1.out, 2.out, etc.

The constructor for a Sweep object assumes that the SWEEP command was run using a directory name with a trailingslash as an output_prefix, and that the output directory thus contains a sequence of files with names 0.out, 1.out etc.The constructor takes the name of the directory (with no trailing slash) as an argument, and reads any such sequence ofsuch numbered output summary files that it finds in that directory. If it finds such a sequence of files, it creates a pythonlist of OutFile objects, each of which contains the contents of a single corresponding output summary file. Each ofthe resulting Outfile objects can be accessed by applying the subscript [] operator directly to the Sweep object, thusemulating the syntax of a Python list. Thus, if x is a Sweep object, x[8] is an OutFile object containing the contentsof the file named 8.out in the directory that was named in the Sweep constructor. The number of OutFile objects inSweep object named x is returned by the operator len(x), as for a list.

The following example illustrates the syntax for creating a Sweep object and printing the value of a particular variablein a particular simulation:

> pythonpython> from pscf.sweep import Sweeppython> x = Sweep('.')python> print len(x)python> print x[8].f_Helmholtz

In this example, we assume that the python interpreter was run from the directory containing a set of output summaryfiles named 0.out, 1.out etc. The third line of this example thus reads all of the output files in the working directory.This is indicated here by the unix shorthand ‘.’ for the current directory, which is passed as an argument to the Sweepconstructor. The fourth line prints the number of output summary files found in that directory. The fifth line prints thevalue of the variable f_Helmholtz read from the file 8.out.

Users can aalso iterate over the list of OutFile objects contained in a Sweep object in order to output or manipulate listsshowing how selected variables change within the sequence of calculations. This is shown in the following example:

> pythonpython> from pscf.sweep import Sweeppython> x = Sweep('.')python> print len(x)python> file = open('free_energy','w')python> for outfile in x:


9.6. Sweep 59



*** line = str(outfile.block_length[0][1]) + ' '

*** line += str(outfile.f_Helmholtz)

*** print line

*** file.write(line + "\n")python>python> file.close()

The fifth line of this example uses the Python open() function to open a new file named ‘free_energy’ for writing (mode= ‘w’). The for loop produces a sequence of text lines containing two columns of numbers, in which the first columncontains values of the length block_length[0][1] of the second (index 1) block of the first (index 0) chain species, whilethe second column contains the value of f_Helmholtz, which is the Helmholtz free energy per monomer normalizedby kT, and each line contains values from a different output summary file. In this example, each line of this output isboth printed to the screen and written to a file named free_energy. The penultimate line closes the file before closingthe python interpreter.

The type of operation given above, which produces a string of containing two columns of numbers, is commonlyneeded to summarize information about a sweep. The Sweep class thus provides a method named write() that isdesigned to simplify this operation. The write function takes two arguments, named expr1 and expr2, each of which isliteral string containing a mathematical expression written using the names of attributes as variable names. It returns astring containing two columns of numbers, in which each value in the first column is obtaining by evaluating expressionexpr1 and each value is obtained by evaluating expr2, and in which each row represents a pair of values obtained froma different simulation. The above example could also be expressed using the write method as:

> pythonpython> from pscf.sweep import Sweeppython> sweep = Sweep('.')python> text = sweep.write('block_length[0][1]','f_Helmholtz')python> print textpython> file = open('free_energy','w')python> file.write(text)python> file.close()python> quit()

Each of the arguments of the write functions are text strings that are interpreted as mathematical expressions in whichthe names of parameters or elements within array-valued parameters are used as variable names. In the simple examplegiven above, these strings were simply the names of individual variables or array elements. One can, however, insteadpass this function string representations of less trivial mathematical expressions. For example, the satement

text = sweep.write(‘2.0*block_length[0][1]’, ‘f_Helmholtz - f_homo’)

would produce a string containing the contents of a two-column data file in which each value in the first column istwice the length of the 2nd block of the first chain species, and in which each value in the second column is thedifference between the free energy per monomer in the converged structure and that of a hypothetical homogeneousmixture of the same set of molecules with the same overall composition.


CHAPTER 10

Matlab Visualization Tool

PSCF is distributed with a matlab script that makes it easy to visualize the mononmer concentration profiles producedby solving the self-consistent field equations. This script was written and contributed to the project by Naveen Pillaiwhile he was an undergraduate at the University of Minnesota. Documentation for the visualization script, withcomplete usage instructions, is given in the file:

doc/tools/PSCF_Visualization.pdf

within the git repository directory (e.g., within pscf/git). The matlab file itself is located at:

tools/matlab/polymer_visual.m

within the git repository tree.

61


62 Chapter 10. Matlab Visualization Tool

CHAPTER 11

Appendix: Self-Consistent Field Theory

PSCF solves self-consistent field theory (SCFT) equations for an incompressible mixture of any number of linearblock copolymer species and point-like solvent molecular species.

SCFT for a liquid of flexible polymers is based on a mean-field approximation that allows us to predict properties ofan interacting liquid by considering considering the behavior of a corresponding gas of noninteracting molecules in aspatially inhomogeneous chemical potential landscape. In what follows, let 𝑘𝐵𝑇𝜔𝛼(r) denote the chemical potentialfield for monomers of type 𝛼, which gives the free energy cost of placing such a monomer at location r. Let 𝜌𝛼(r)denote the corresponding average volume fraction of monomers of type 𝛼 at position r.

PSCF implements a version of SCFT for incompressible liquids in which each species of molecule occupies a well-defined volume, independent of composition and (modest) changes in pressure. In what follows, 𝑁𝑖 is dimensionlessmeasure of the volume per molecule (or size) of species 𝑖, which is defined for both polymeric and point-like moleculesas the ratio of the volume occupied by one molecule of that species to an monomer reference volume. The length ofeach block within a block copolymer is specified similarly, as a ratio of the block volume to a monomer referencevolume.

In what follows, let 𝐶 be the number of distinct monomer or solvent types in the system. Let 𝑃 denote the numberof polymer species and 𝑆 be the number of solvent species. Here, we use a convention in which integer indices𝛼, 𝛽 = 1, . . . , 𝐶 indicate monomer types, and indices 𝑖, 𝑗 denote molecular species. Species indices are ordered withall polymeric species listed first, so that species index values in the range 𝑖, 𝑗 = 1, . . . , 𝑃 denote polymeric species,and values in the range 𝑃 + 1, . . . , 𝑃 + 𝑆 denote solvent species.

Polymer Species

Each polymeric species with species index 𝑖 and overall chain length 𝑁𝑖 is treated as a random walk characterizedby a contour R(𝑠), where 𝑠 is a contour variable with a range 0 ≤ 𝑠 ≤ 𝑁𝑖. For each such species, we define apair of functions 𝑞𝑖(r, 𝑠) and 𝑞†𝑖 (r, 𝑠). The functions 𝑞𝑖 and 𝑞† are normalized partition functions for chain segmentscorresponding to contour variable domains [0, 𝑠] and [𝑠,𝑁𝑖], respectively, when the monomer at contour position 𝑠 isconstrained to position R(𝑠) = r. These functions obey a pair of modified diffusion equations

𝜕𝑞𝑖𝜕𝑠

= −𝐻𝛼(𝑠)𝑞𝑖

𝜕𝑞†𝑖𝜕𝑠

= +𝐻𝛼(𝑠)𝑞†𝑖

63


in which 𝛼(𝑠) is the monomer type of the block containing monomer 𝑠 of polymer species 𝑖, and in which 𝐻𝛼 is alinear diferential operator

𝐻𝛼 = −𝑏2𝛼6∇2 + 𝜔𝛼(r)

in which 𝑏𝛼 is the statistical segment length for monomers of type 𝛼, and 𝜔𝛼 is the corresponding chemical potentialfield. These equations must be solved for 0 < 𝑠 < 𝑁𝑖 subject to an initial condition

𝑞𝑖(r, 𝑠 = 0) = 𝑞†𝑖 (r, 𝑠 = 𝑁) = 1

for all r, and boundary condition requiring that 𝑞 and 𝑞† be periodic functions of r with the periodicity of somespecified Bravais lattice.

The quantity 𝑄𝑖 is a normalized overall partition function for chains of species 𝑖, given by an integral

𝑄𝑖 =1

𝑉

∫︁𝑑r 𝑞(r, 𝑠 = 𝑁)

in which the integral is taken over one unit cell of a periodic structure, and 𝑉 denotes the generalized volume per unitcell of a structure that periodic in 𝐷 dimensions (i.e., the volume per unit cell for a 3D crystal, area per 2D unit cellfor a 2D structure such as the hexagonal cylinder phase, and the length per unit cell in a 1D lamellar phase).

The probability of finding a specific monomer 𝑠 of species 𝑖 at position r is proportional to the product 𝑞𝑖(r, 𝑠)𝑞†𝑖 (r, 𝑠)of the constrained partition functions for the two chain segments that meet at monomer s. Let 𝜌(𝑖)𝛼 denote the contri-bution to the local volume fraction of 𝛼 monomers from monomers of a polymer species 𝑖 that contains at least oneblock of monomer type 𝛼. This quantity is given by a product

𝜌(𝑖)𝛼 (r) =𝜑𝑖

𝑁𝑖𝑄𝑖

∫︁𝛼(𝑠)=𝛼

𝑑𝑠 𝑞(r, 𝑠)𝑞†(r, 𝑠)

in which 𝜑𝑖 is the average overall volume fraction of molecule species 𝑖 within the mixture, and the integral withrespect to 𝑠 is taken only over blocks of monomer type 𝛼.

Solvent Species

Each solvent species 𝑖 is associated with a specific monomer type 𝛼 and a volume 𝑖. A “monomer” type that is assignedto a solvent species may or may not also be contained within one or more of the polymeric species.

In the single molecule problem for solvent species, the free energy penalty for a solvent molecule of monomer type 𝛼to be located at position r is given by 𝑘𝐵𝑇𝑁𝑖𝜔𝛼(r). This yields a solvent concentration 𝜌𝑖(r) ∝ exp(−𝑁𝑖𝜔𝛼(r)).

The normalized overall partition for such a point-like species is given by an integral

𝑄𝑖 =1

𝑉

∫︁𝑑r exp(−𝑁𝑖𝜔𝛼(r))

The contribution of solvent species 𝑖 of type 𝛼 to the local volume fraction of 𝛼 is given by a ratio

𝜌(𝑖)𝛼 (r) =𝜑𝑖

𝑄𝑖exp(−𝑁𝑖𝜔𝛼(r))

in which 𝜑𝑖 is the overall volume fraction of species 𝑖 within the mixture.

The total volume fraction 𝜌𝛼(r) for each monomer type 𝛼 is simply given by the sum of contributions from allpolymeric species that contain a block or blocks of type 𝛼 plus the contribution of any solvent of type 𝛼.

Self-Consistent Field Equations

64 Chapter 11. Appendix: Self-Consistent Field Theory


The monomer chemical potential fields are given, within the standard approximation for excess free energies in termsof binary Flory-Huggins interaction parameters, as functions

𝜔𝛼(r) =

𝐶∑︁𝛽=1

𝜒𝛼𝛽𝜌𝛽(r) + 𝜉(r)

in which 𝜒𝛼𝛽 is a binary interaction parameter for interactions between monomers of types 𝛼 and 𝛽, and 𝜉(r) is aLagrange multiplier pressure field. The interaction parameters in PSCF satisfy 𝜒𝛼𝛼 = 0 and (obviously) 𝜒𝛼𝛽 = 𝜒𝛽𝛼.

The field 𝜉(r) must be chosen such that the monomer concentrations satisfy the incompressibility constraint

1 =

𝐶∑︁𝛼=1

𝜌𝛼(r)

Thermodynamic Properties

The Helmholtz free energy 𝑓 per monomer reference volume, as given in the output file, is given by a sum

𝑓

𝑘𝐵𝑇=

𝑃+𝑆∑︁𝑖=1

𝜑𝑖

𝑁𝑖

[︀ln(𝜑𝑖/𝑄𝑖) − 1

]︀− 1

𝑉

𝐶∑︁𝛼=1

∫︁𝑑r 𝜔𝛼(r)𝜌𝛼(r)

+1

2𝑉

𝐶∑︁𝛼,𝛽=1

𝜒𝛼𝛽

∫︁𝑑r 𝜌𝛼(r)𝜌𝛽(r)

Note that the sum over species in the first line is a sum over all species, including polymeric and solvent species, withdifferent ways of defining 𝑄𝑖 for different types of molecule.

The corresponding chemical potential 𝜇𝑖 for species 𝑖 is given by

𝜇𝑖

𝑘𝐵𝑇= ln(𝜑𝑖/𝑄𝑖)

The value given in the output file is 𝜇𝑖/𝑘𝐵𝑇 .

The macroscopic physical pressure 𝑃 is computed from the identity

𝑃 = −𝑓

𝑣+∑︁𝑖=1

𝜇𝑖𝜑𝑖

𝑁𝑖𝑣

in which 𝑣 is the monomer reference volume and 𝑓 is the Helmholtz free energy per reference volume. Note that𝑓/𝑣 is the Helmholtz free energy per volume and 𝜑𝑖/(𝑁𝑖𝑣) is the average number of molecules of species 𝑖 per unitvolume. The value given in the output file is the dimensionless value 𝑃𝑣/𝑘𝐵𝑇 .

Ensembles

PSCF can be carry out calculations using either canonical ensemble or grand-canonical ensemble.

In canonical ensemble a value of the overall volume fraction 𝜑𝑖 must be given for each species in the input parameterfile, and values of chemical potential are computed from the solution.

In grand canonical ensemble, a value of the normalized chemical potential 𝜇𝑖/𝑘𝐵𝑇 must be given for each species inthe input parameter file, and average volume fractions for each species are computed.

In grand-canonical ensemble, values for the Lagrange multplier field 𝜉(r) and the macroscopic pressure 𝑃 are uniquelydetermined by the values for the chemical potentials.

65


In canonical ensemble, the value of the Lagrange multplier field 𝜉(r) is defined only to within a arbitrary spatiallyhomogeneous constant. As a result, the chemical potentials and the macroscopic pressure 𝑃 are also undefined inthis ensemble, unless an additional constraint is imposed. PSCF resolves this ambiguity by requiring, as a matterof convention, that the spatial average of 𝜉(r) vanish. In this ensemble, PSCF also outputs values for the pressure,chemical potentials, and 𝜔 fields that are all consistent with this convention for the average value of 𝜉. Values for theHemholtz free energy density of an incompressible liquid can, however, be shown to be independent of changes in thevalue of 𝜉 by a homogeneous constant, and are thus independent of this choice of convention.

66 Chapter 11. Appendix: Self-Consistent Field Theory

CHAPTER 12

Appendix: Memory Usage

The majority of memory in a typical SCF calculation is consumed by the storage of mono-constrained partition func-tions (forward and backward) and, if solved using the quasi Newton-Raphson, by the storage of the inverse Jacobianmatrix needed in Broyden’s method.

Chain Partition Functions

The memory (in bytes) needed to store the two mono-constrained partition function is determined by the followingfactors:

Factor Valuenumber of grid points ngrid(1)*ngrid(2)*ngrid(3)number of contour segments 2*chain_length/chain_stepbytes per real (double) number 8

The product of these numbers yield:

mem(Q) = (ngrid(1)*ngrid(2)*ngrid(3)) * (chain_length/chain_step) * 16

Jacobian Matrix

The dimension of Jacobian is “N_monomer * N_basis” as long as the N_cell_param (<= 6) is ignored, thus the memoryrequirement, in bytes, is:

mem(J) = (N_monomer*N_basis)^2 * 8

The number of basis function (N_basis) may be roughfully estimated, if needed, to be the number of the grid pointsdivided by the number of space group symmetry elements.

Numerical Example

Imagine simulating a gyroid phase for an ABC triblock copolymer (N_monomer=3) using normalized chain_length=1,chain_step=0.01, a grid with dimensions ngrid(1)=ngrid(2)=ngrid(3)=56 The I a -3 d space group of the gyroid phasehas 96 symmetry elements, so our simple estimate suggests N_basis = 56*56*56/96=1829.3. In fact, we obtain aslightly higher value of N_basis=1856. mem(Q) and mem(J) are found to be 0.28GB and 0.25GB, respectively.

67


68 Chapter 12. Appendix: Memory Usage

CHAPTER 13

Appendix: Creating Binary Packages

This page gives instructions for how to use cmake to create a binary .dmg installer file for Mac OS X and a .deb or.rpm binary package for different distributions of linux. This information is not relevant to most users, and is providedonly as reference for core developers.

The first step in creating a package, for any operating system, is to follow the instruction given on the page about Com-piling from source, using cmake for installing dependencies and obtaining the source code. The remaining instructionsgiven here assume that all dependencies are already installed, and that a copy of the source code has been installedwithin the directory structure described in the instructions for compiling from source.

Mac OS X

On Mac OS X, after installing all dependencies and installing a copy of the source code in a repository named git/,one must:

• Change directory to the pscf/cmake directory.

• From the directory, enter:

> cmake -DBUILD_DMG=1 -DCMAKE_INSTALL_PREFIX=. ../git

• Then enter:

> make -j4> make package> make package

The instruction to run “make package” twice is not a typo: This appears to be necessary to get the packaging utility toinstall all of the shared libraries correctly. The absence of an “make install” command is also intentional - the installtarget is not supported when BUILD_DMG is defined. This procedure creates a standard Mac .dmg installer file witha name of the form pscf<version>-Darwin.dmg in the pscf/cmake directory.

Linux (Fedora or Ubuntu)

On a linux system, one must:

• Change directory to the pscf/cmake directory.

69


• From the directory, enter:

> cmake -DCMAKE_INSTALL_PREFIX=.. ../git

• Then enter:

> make -j4> make install> make package

The “make install” command will install the software in the users pscf/ directory, in subdirectories named bin/, lib/and share/. The “make package” command should then create either a file named pscf<version>-linux.rpm, if theprocedure is performed on a system such as Fedora that uses redhat package manager (rpm) files, or a file namedpscf<version>-linux.deb if built on a system such as Ubuntu that uses .deb files. RPM packages can only be built on asystem that use .rpm packages and .deb packages can only be built on a system that use .deb files.

On a system that uses .rpm files, to check the RPM for detailed information (Metadata, Dependencies, and FileContents), enter:

> rpm --info -qpR -qlvp pscf-1.0.0-Linux.rpm

On a system that uses .deb package files, to check the .deb file for semi-detailed information, enter:

# This extracts multiple filesar -vx pscf-1.0.0-Linux.deb# See the files that would be installedtar tvfz data.tar.gz

70 Chapter 13. Appendix: Creating Binary Packages

CHAPTER 14

Indices and tables

• genindex

• modindex

• search

71

pscf documentation

Documents