psim in depth - · pdf filepsim in depth release 1.0.0 the polyswift++ and composer teams...
TRANSCRIPT
PSim In DepthRelease 1.0.0
The PolySwift++ and Composer Teams
May 09, 2013
Contents
1 Basic Concepts 21.1 Basic Concepts for All Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Simulation Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Input File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Vectors of Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Input Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Input File Basics 42.1 Input Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Python Token Evaluator (txpp.py) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Scoping Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Expression Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Flow Control and Repetition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Using Macros in Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Setup for Pseudospectral Solver Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3 Tutorials 123.1 Linear Diblock Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Linear Diblock Simulation Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Lesson 1: Model/Simulation detail for a 2-component AB diblock . . . . . . . . . . . . . . . . . . . 13Lesson 2: Increase the resolution of the simulaton . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Lesson 3: Explore morphology phase diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.2 Interacting Surfaces Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Interaction Surfaces Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Lesson 1: Model/Simulation detail for interacting surfaces . . . . . . . . . . . . . . . . . . . . . . . 34Lesson 2: Specifying Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4 Advanced Concepts 454.1 Running the PolySwift++ engine from the Command Line . . . . . . . . . . . . . . . . . . . . . . . 45
The ps-run.py PolySwift++ run script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Running the PolySwift++ Executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Examples of Running PolySwift++ from the Command Line . . . . . . . . . . . . . . . . . . . . . . 46
Serial Computation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Parallel Computation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.2 HDF5 Format PSim Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47HDF5 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Change the Names of Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Display the Content of .h5 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5 Troubleshooting 485.1 Troubleshooting Numerical SCFT Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
The Simulation Does Not Start/Finish Properly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48The Simulation Becomes Unstable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6 References 496.1 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496.2 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
1 Basic Concepts
1.1 Basic Concepts for All Simulations
This section presents concepts about PSim that you should understand before creating and running simulations. Takingthe time to examine these concepts before reading about the simulation process, will make the simulation proceduressimple to understand and tutorial lessons straightforward to follow.
Simulation Grid
Every object in a PSim simulation interacts with a 3D grid, in Cartesian coordinates. Future development will enablesimulations on AMR grids. Length scales in the simulation are scaled by the radius of gyration of the first Polymerobject in the input file.
1.2 Input File Syntax
The most important part of the PSim simulation process, which we will examine in the-simulation-process, is creatingan input file. You define the simulation and its variables in the input file, which has a .pre suffix.
This section discusses the syntax used in pre files.
An input file consists of:
• Comments
• Variables
• Top-level simulation parameters
• Parameters and vectors of parameters organized into input blocks
2
Comments
You can enter comments in either of two ways:
• Following a pound sign (#) either on a new line or a continuation of a current line
• Between the opening and closing comment tags <Comment> </Comment>
Note: Tech-X recommends that you always update your comments when you make changes to an inputfile. The reasoning behind a change may become unclear if you do not provide comments that explainwhy you made the change. Input files with old, out-of-date comments are difficult to work with.
Variables
Each line defining a variable begins with a dollar sign ($).
Parameters
Parameters can be integers, floating-point numbers, or text strings.
The format of the parameter value determines the type of parameter. For example:
• x = 10 indicates an integer
• x = 10.0 indicates a floating-point number
• x = ten indicates a text string
Some parameters accept any text string (within reason). Other parameters accept only a choice of text strings.
If PSim can parse a value as an integer, it will do so. For example:
42
If PSim cannot parse the value as an integer, it will attempt to parse it as a floating-point number – for example, anyof the following:
42.3.141591.60217646e-19
If PSim cannot parse the value as either an integer or a floating-point number, it will parse the value as a string of text,for example, either of the following:
4o. (4 and lowercase O) or4O (4 and uppercase O).
Use a decimal point to specify a floating point number. You must write floating-point numbers with a decimal pointso that PSim will not interpret them as integers. If you want to assign an integer value to a floating-point parameter,make sure you write it as 3. (with a decimal point .) rather than only the numeral 3 (without a decimal point). Ifyou write the number as an integer (without the decimal point), PSim will interpret it as an integer. This will likelyproduce unexpected results.
Check that you have correctly defined parameter values. If you incorrectly define a parameter that has a default value,PSim will use the default value and give you unsatisfactory results. If you incorrectly define a parameter that does nothave a default value, the PolySwift++ engine may crash, fail to compute the physics of the simulation, or ignore theincorrectly defined parameter and give you unsatisfactory results.
3
Do not specify a parameter twice. If you do, PSim will use the second occurrence of the parameter in the processedinput file produced from the input file with the .pre extension. Although PSim allows you to specify parameters andinput blocks in many different sequences, if you follow the recommendations in this user guide, you should not havea problem with specifying parameters twice.
Vectors of Parameters
Vectors of parameters are enclosed by brackets [ ] with white space used as separators. For example:
• x = [10 10 10] indicates a vector of integers
• x = [10. 10. 10.] indicates a vector of floats
Input Blocks
Input blocks are used to create simulation objects. The block is enclosed by opening and closing tags such as:
<Grid globalGrid>...
</Grid>
The tag determines:
• object type: indicated by an initial capital letter, for example, Grid
• object name: indicated by an initial lowercase letter, for example, globalGrid
You use the object name to refer to the object in other input blocks. For example, in the input block for a copolymerBlock object, you may refer to the name of another Block object in the same Polymer block. These references areused in the ‘headjoined’ and ‘tailjoined’ parameters to specify the connectivity of the block copolymer.
Input blocks can be nested. For example, input blocks for Interaction and Updater objects are nested within the inputblock for an Hamiltonian model, EffHamil.
1.3 Output Files
All data produced by the PolySwift++ engine is output using the HDF5 .h5 data file format. These output files aredumped as defined by the user; they can be written at the end of a simulation, for example, or every n steps to createtime series that can be used to see how a system evolves over time. Additionally, these output files can be used torestart a run and continue from a given point; for example, if a user has run a simulation for 1000 time steps and wishesto see how the simulation progresses if run for another 1000.
For more information on the HDF5 format of PSim output files, please see HDF5 Format PSim Output Files
2 Input File Basics
2.1 Input Parser
Python Token Evaluator (txpp.py)
The Python preprocessor has the following features:
4
• It accepts a file, conventionally with suffix .pre, for processing.
• Lines in that file that start with the character $ are processed by the preprocessor.
• Those lines are sent through the python interpreter for evaluation
• The resulting values are replaced and written to a new file with suffix, .in
Note: Recent versions of Tech-X codes (including PSim) use the txpp.py code internally (i.e. the txpp.py pythoncode is called within simulation engines using the Python/C++ API) The txpp.py code can still be used externally, inorder to debug input file code.
For example, suppose one has a file, myfile.pre, containing,
################################################# A Boundary object################################################$ CYLRADIUS = float(NX/2 - int(0.05*NX))$ CYLCENTER_X = float(NX/2)$ CYLCENTER_Y = float(NY/2)$ CYLCENTER_Z = float(1)
# Sets the hyperbolic tangent profile$ WIDTHPARAM = 1.5
<Boundary softEthyWalls>kind = fixedWallboundaryfield = totWall
<STFunc walls>kind = pyfuncname = cylinderparamKeys = [ radius widthParam cylcenterX cylcenterY cylcenterZ ]paramValues = [ CYLRADIUS WIDTHPARAM CYLCENTER_X CYLCENTER_Y CYLCENTER_Z ]
</STFunc></Boundary>
Execution of:
<txpp.py directory>/txpp.py --prefile=myfile.pre
produces a file, myfile.in that contains:
################################################# A Boundary object#################################################$ CYLRADIUS = float(NX/2 - int(0.05*NX))# --> CYLRADIUS = 58.0#$ CYLCENTER_X = float(NX/2)# --> CYLCENTER_X = 64.0#$ CYLCENTER_Y = float(NY/2)# --> CYLCENTER_Y = 64.0#$ CYLCENTER_Z = float(1)# --> CYLCENTER_Z = 1.0# Sets the hyperbolic tangent profile#$ WIDTHPARAM = 1.5# --> WIDTHPARAM = 1.5
<Boundary softEthyWalls>
5
kind=fixedWallboundaryfield=totWall
<STFunc walls>kind=pyfuncname=cylinderparamKeys=[radius widthParam cylcenterX cylcenterY cylcenterZ]paramValues=[58.0 1.5 64.0 64.0 1.0]
</STFunc>
</Boundary>
This mechanism facilitates modifying files to change systems size, resolution, or other parameters while keepingrequisite mathematical relationships intact.
The preprocessor imports math, so one can include statements such as:
$ PI = math.pi
and then use the variable PI in the pre file. The replace occurs for commented lines as well. This is useful for printingout intermediate values for, e.g., debugging. In addition, the value of any variable named NDIM defined in the inputfile can be modified on the command line with the directive NDIM=2, for example, to have all occurrences of NDIMin the file replace by 2 instead of the value defined in the file. This enables writing only a single pre file for simulationsof multiple dimensionalities when the differences in the file follow from the value of NDIM alone.
Interpretation of Parameters and Values
The Python preprocessor simplifies setup of complex simulations by providing an abstraction mechanism. With thepre-processor’s macro features, you can write parameterized input files and encapsulate input file fragments intolibraries for later use. By using a macro (described in detail later) you can easily reuse the same code in more thanone place. Rather than repeating the code, you just call the single macro to be substituted for that code each place youwould like to use it.
The type of value expected by PSim for each parameter and variable is identified in parentheses next to the name of thatparameter or variable in the description of each feature or block. The PSim input parser distinguishes between typesfor integers, floating-point numbers, and strings based on input format. Expressions are parsed for values followingthe order:
• integer
• floating-point
• string (text)
• vector
Integer If a symbol can be parsed as an integer, PSim assumes that integer is the correct type.
Example of an integer:
42
Floating Point If the integer format comparison fails, the software tries to parse the symbol as a floating-point num-ber. Floating-point numbers must be written with a decimal point so they will not be interpreted as integerparameters.
Examples of floating-point numbers:
3.14159
1.60217646e-19
6
To assign an integer value to a floating-point variable, make sure it is written with a decimal point, otherwise,the variable will be interpreted as an integer, and this will likely produce unexpected results.
Example of correct integer value format for usage with a floating-point variable:
3.
Example of incorrect integer value format for usage with a floating-point variable:
3
String If the integer and subsequent floating-point comparisons both fail PSim interprets the variable as string of textcharacters rather than a number.
Vector When parsing a vector type of variable, PSim uses the same logic and order of analysis as for non-vector vari-ables. For example, PSim would interpret the following example as a vector having three integer components:
lowerBounds = [-1 -1 -1]
Scoping Rules
Symbols in txpp are scoped. This means that the effect of a symbol’s definition is confined to the macro or block inwhich that symbol is defined. Whenever txpp enters a macro or a new input file block, it enters a new scope.
In the case in which SYMBOL is defined in multiple scopes, txpp ignores the previously defined SYMBOL for theduration of the current scope. In the case in which SYMBOL is defined more than once in the current scope, the newvalue overrides the previous value defined in the current scope.
This scope is closed once txpp leaves the block or macro. That is, the symbol’s definition no longer has an effect oncetxpp has used the symbol’s value in the macro or block where it was defined and then proceeded to a different blockor macro. Scoping allows the next block or macro to be free to redefine the value of the symbol for its own purposes.
Expression Evaluation
Txpp evaluates expressions by interpreting them as Python expressions. Python expressions are composed of tokens.A token is a single element of an expression, such as a constant, identifier, or operation. The preprocessor breaks theexpression string into individual tokens then performs recursive substitution on each token. Once a token is no longerfound to be substitutable, the preprocessor tries to evaluate it as a Python expression. The result of this evaluation willthen be used as the value of this token. All the token values are then concatenated and again evaluated as a Pythonexpression. This result will then be assigned to the symbol.
Tokenizing, the act of breaking a string into tokens, is performed following the lexical rules of Python. This meansthat white spaces are used to delimit tokens, but are otherwise entirely ignored.
Note: A string within matched quotes is treated as a single token with the matching quotes removed.
The input files generated by txpp are sensitive to white spaces; as a result, txpp has to re-introduce white spaces in thetranslation process. By default, tokens are joined without any white spaces. However, if both tokens are of type string,then a white space is introduced. Also, tokens inside an array (delineated by [ and ]) are delimited by a white space.
See the Python documentation on the official Python website at http://www.python.org for more information aboutPython expressions.
Flow Control and Repetition
The PSim preprocessor includes both flow control and conditional statements, similar to other scripting languages.These features allow the user a great deal of flexibility when creating input files.
7
Conditionals
A conditional takes either the form:
$ if COND...
$ endif
or
$ if COND...
$ else...
$ endif
Conditionals can be arbitrarily nested. All the tokens following the if token are interpreted following the expressionevaluation procedure (see above) and if they evaluate to true, the text following the if statement is inserted into theoutput. If the conditional statement evaluates to false, the text after the else is inserted (if present). Note that trueand false in preprocessor macros are evaluated by Python – in addition to evaluating conditional statements suchas x == 1, other tokens can be evaluated. The most common use of this is using 0 for false and 1 for true. Emptystrings are also evaluated to false. For more detailed information, consult the Python documentation.
Repetition
For repeated execution, txpp provides while loops; these take the form:
$ while COND...
$ endwhile
which repeatedly inserts the loop body into the output. For example, to create 10 stacked circles using the circle macrofrom above, you could use:
$ n = 10$ while n > 0 circle(n)$ n = n - 1$ endwhile
2.2 Macros
Using Macros in Input Files
A macro is a mechanism to abstract complex input files sequences into (parameterized) tokens. In its simplest form, amacro provides a way to substitute a code snippet from an input file:
<macro snippet>line1line2line3
</macro>
In this example, every occurrence of the code named snippet in the input file will now be replaced by the three linesdefined between the <macro> and </macro> tags.
8
Macro Parameters
Macros can take parameters, allowing variables to be passed into and used by the macro. Parameters are listed inparentheses after the macro name in the macro declaration. Once a macro is defined, it can be used by calling it andproviding values or symbols for the parameters. The macro will substitute the parameter values into the body provided.
Note: The parameter substitution happens in the scope of the caller. Parameters do not have scope outside of themacro in which they are defined.
Macro Overloading
As with symbols, macros can be overloaded within a scope. The particular instance of a macro that is used is deter-mined by the number of parameters provided at the time of instantiation. This enables the user to write macros withdifferent levels of parameterization:
<macro circle(x0, y0, r)>r^2 - ((x-x0)^2 + (y-y0)^2)
</macro>
<macro circle(r)>circle(0, 0, r)
</macro>
Looking in the example above, whenever the macro circle is used with a single parameter, it creates a circle aroundthe origin; if you use the macro with 3 parameters, you can specify the center of the circle.
The macro substitution does not occur until the macro instantiation is actually made. This means that you do not haveto define the 3-parameter circle prior to defining the 1-parameter circle, even though the 1-parameter circle refers tothe 3-parameter circle. It is only necessary that the first time the 1-parameter circle is instantiated, that 3-parametercircle has already been defined, otherwise you will receive an error.
Defining Functions Using Macros
Macros can be particularly useful for defining complex mathematical expressions, such as defining functions inSTFunc blocks with kind = expression.
Consider a macro that should simplify the setup of a Gaussian. One could define the following macro:
<macro badGauss(A, x, sigma)>A * exp(-x^2/sigma)
</macro>
While this is a legitimate macro, an instantiation of the macro via:
badGauss(A0+5, x-3, 2*sigma)
will result in:
A0+5*exp(-x+3^3/2*sigma)
which is probably not the expected result. One alternative is to put parentheses around the parameters whenever theyare used in the macro.
9
<macro betterGauss(A, x, sigma)>((A) * exp(-(x)^2/(sigma)))
</macro>
This will ensure that the expressions in parameters will not cause any unexpected side effects. The downside of thisapproach, however, is that the macro text is hard to read due to all the parentheses. To overcome this issue, txppprovides a mechanism to automatically introduce the parentheses around arguments by using a function block
<function goodGauss(A, x, sigma)>A * exp(-x^2/sigma)
</function>
The previous example will produce the same output as the badGauss macro, but without requiring the additionalparentheses in the macro text.
Importing Files
Txpp allows input files to be split into individual files, thus enabling macros to be encapsulated into separate libraries.For example, physical constant definitions or commonly-used geometry setups can be stored in files that can then beused by many PSim simulations. Input files can be nested to arbitrary depth.
Files are imported via the import keyword:
$ import FILENAME
where FILENAME represents the name of the file to be included. txpp applies the standard rules for token substitutionto any tokens after the import token. Quotes around the filename are optional and, computed filenames are possible.
Recursion
Macros can be called recursively. E.g. the following computes the Fibonacci numbers:
<macro fib(a)>$ if a < 2
a$ else
fib(a-1)+fib(a-2)$ endif
</macro>fib(7)
Note: There is nothing preventing you from creating infinitely recursive macros; if terminal conditions are not givenfor the recursion, infinite loops can occur.
‘Requires’ Directive
When writing reusable macros, best practices compel macro authors to help ensure that the user can be prevented frommaking obvious mistakes. One such mechanism is the requires directive, which terminates translation if one or moresymbols are not defined at the time. This allows users to write macros that depend on symbols that are not passed asparameters. For example, the following code snippet will not be processed if the symbol NDIM has not been previouslydefined:
10
<macro circle(r)>$requires NDIM$if NDIM == 2 r^2 - x^2 - y^2$endif$if NDIM == 3 r^2 - x^2 - y^2 - z^2$endif
</macro>
String Concatenation
One task that is encountered often when creating PSim simulations is naming groups of similar blocks, e.g. similarspecies. Macros can allow us to concatenate strings to make this process more clean and simple. However, based onthe white-spacing rules, strings will always be concatenated with a space between them. For example,
$a = hello$b = worlda b
will result in
hello world
However, we can get around this rule to get the desired output with the following:
<macro concat(a, b)>$ tmp = ’a tmp b’
</macro>
Now when calling
concat(hello, world)
the result will be:
helloworld
The first line appends a single quote to a and stores the result in tmp. The next line then puts the token a together withthe token b. As they are now no longer two strings; they will be concatenated without a space. The final evaluation ofthe resulting string then removes the quotes around it, resulting in the desired output.
Setup for Pseudospectral Solver Macro
pseudoSpecSetup: The pseudo-spectral Setup macro is used with the flexPseudoSpec models for solving the flexibleGaussian chain models for block copolymers. The pseudoSpecSetup.mac macro is used with all currentPSim input files.
setupPS
setupPS (nx, ny, nz, dx, dy, dz, debug):
The FFTW implementation of the pseudo-spectral method requires a transposed grid to save communi-cation time. This macro sets up the unifrom Cartesian grids and the transposed grid with the appropriatedecompositions The communication block is the MPI required by FFTW and the FFTW objects assoicatedwith the correct grid and decomp objects are created as well.
• nx: number of cells in x-direction
11
• ny: number of cells in y-direction
• nz: number of cells in z-direction
• dx: size of each cell in x-direction [radius of gyration]
• dy: size of each cell in y-direction [radius of gyration]
• dz: size of each cell in z-direction [radius of gyration]
• debug: one of ‘on’ or ‘off’. Turn on or off debugging statements
3 Tutorials
3.1 Linear Diblock Tutorial
Linear Diblock Simulation Tutorial
Basic Linear Diblock Simulation Model
This tutorial covers how to simulate a dense melt of monodisperse AB diblock copolymers chains. A Hamiltonian forthis system can be written as:
H =1
4R2g0
n∑α=1
∫ 1
0
ds
(d~rα(s)ds
)2
+ ρ−10
∫d~r χ ρ̂A(~r)ρ̂B(~r).
where the first term expresses the free-energy of a “Gaussian thread” model. This term can be derived by taking thecontinuous limit of spherical monomers interacting through harmonic springs. The second term expresses a Flory-typeinteraction energy between chemically distinct monomers (eg A-B).
The monomer density operators for the A and B species are
ρ̂A(~r) = N
n∑α=1
∫ f
0
ds δ(~r − ~rα(s))
ρ̂B(~r) = N
n∑α=1
∫ 1
f
ds δ(~r − ~rα(s))
where f = 0.5 and corresponds to a symmetric AB diblock.
The SCF theory yields a partition function
Z =∫ n∏
α=1
D̃~rα exp{−ρ−1
0
∫d~r χ ρ̂A(~r)ρ̂B(~r)
}δ[ρ0 − ρ̂A − ρ̂B ]
with
12
D̃~rα = D~rα exp
{− 1
4R2g0
∫ 1
0
ds
(d~rα(s)ds
)2}
This tutorial examines the parameters and input blocks that comprise the linearDiblock.pre file distributed with PSim.The linearDiblock.pre file demonstrates the basics of numerical self-consistent field theory (SCFT) simulations ofbulk copolymers using the PolySwift++ engine. This section assumes you are familiar with the material in the section,Basic Concepts for All Simulations, from this manual.
About the Example Input File, linearDiblock.pre
The linearDiblock.pre file has been selected for use with the example simulation in this section because this file issimple enough to examine section by section, yet complicated enough to demonstrate a variety of physics features andPSim features.
PolySwift++ Features Demonstrated
The linearDiblock example demonstrates the following PSim features:
• setup for the pseudospectral solution algorithm
• basics for setting up bulk simulation of copolymer system
• visualizing morphology results and diagnostics
In Lesson 1 of this Linear Diblock Simulation Tutorial, you will define the conceptual model for the linearDiblockexample on the 2D Cartesian grid following the instructions in Lesson 1: Model/Simulation detail for a 2-componentAB diblock.
Lesson 1: Model/Simulation detail for a 2-component AB diblock
Definition of linearDiblock
Now that we have examined the conceptual model for linearDiblock, we are ready to define the linearDiblock simula-tion, which includes 3 three physical fields, a model definition block, and a copolymer definition block. The processinvolves:
• Variable definition
• Simulation parameter definition
• Grid definition
• Decomposition definition
• Physical field defintion
• Model definition (includes updaters and interactions)
• Diblock copolymer definition
• Diagnostics definition
As needed, refer back to the PSim In Depth section, Basic Concepts for All Simulations.
13
Variable Definition The input file imports any needed macros and defines variables. The linearDiblock exampleuses the macro pseudospectral.mac, which contains input block setup appropriate for the pseudospectral method ofsolving the modified diffusion equations in the theory.
• Variables for the Grid
• Variables for the Copolymer Block Sizes
• Variables for the Monomer Interaction Strength
• Variables for the Relaxation Algorithm
By changing the variables, we can quickly change aspects of the simulation.
Variables for the Grid The variables for the grid input block comprise:
• Number of cells in the simulation grid along the x axis (NX), y axis (NY), and z axis (NZ)
• Length of a grid cell in x-dir (dx), y-dir (dy), and z-dir (dz)
The dimensions, or lengths, of the grid in the example are:
• X = 6.4 Rg
• Y = 6.4 Rg
• Z = (For 2D simulations NZ=1)
where Rg sets the length scale. The radius of gyration of the unperturbed chain is given by
R2g =
b2N
6
where b is the statistical segment length and N is the number of statistically independent chain segments.
The figure, User-defined Cartesian grid for linearDiblock used by PolySwift++, displays the grid for the linearDiblocksimulation. The grid cells sizes are denoted by ‘dx, dy and dz’. The slab domain decomposition is needed for the FFTimplementation of the pseudospectral method of solving for the chain propagators in the numerical theory []. (Thedomain decomposition example shown is for four MPI processors on a grid of size NX = 12, NY = 12, NZ = 3).
Variables for the Copolymer Block Sizes The variables for the copolymer block sizes include:
• length fraction of the A block (fA)
• length fraction of the B block (fB)
The total for each copolymer must be one (fA+ fB = 1)
Variables for the Monomer Interaction Strength The variables for the monomer interactions parameterize thestrength of the Flory segregation strength.
• The Flory χ parameter (chiAB)
• The number of statistical segment lengths in the copolymer N (NLEN).
The product χN sets the over segregation strength. The parameter NLEN appears later in the <Polymer> object andis used to set the length scale for the theory. If other <Polymer> objects appear in the input file the NLEN in the first<Polymer> object is used to set the length scale for entire model.
14
Figure 1: User-defined Cartesian grid for linearDiblock used by PolySwift++
15
Variables for the Relaxation Algorithm The variables that control the steepest descent relaxation algorithm include
• The size of the first mixing factor λ (lambda1)
• The size of the second mixing factor λ′
(lambda2). For convenience, this is set to half of the first mixingparameter
• The strength of the gaussian noise added to the field updates (noise_stregnth). This is added in orderto aid relaxation and keep the simulation from reaching the homogeneous phase when starting from a randominitial state.
The λ relaxation paramters control updating the chemical potential fields ω (conjugate to the monomer densities)through the following expressions
ωn+1A − ωnA = λ
′ δF̃
δφnB+ λ
δF̃
δφnA
ωn+1A − ωnA = λ
′[φnA − φ̄A −
ωnB − pn
χN
]+ λ
[φnB − φ̄B −
ωnA − pn
χN
]
and
ωn+1B − ωnB = λ
δF̃
δφnB+ λ
′ δF̃
δφnA
ωn+1B − ωnB = λ
[φnA − φ̄A −
ωnB − pn
χN
]+ λ′
[φnB − φ̄B −
ωnA − pn
χN
]
Variable Definition Section in Pre File The variable definition section of the linearDiblock.pre file follows.
Each line defining a variable begins with a dollar sign $.
############ Primary variables (defined in terms of constants)###########
$ NX = 64$ NY = 64$ NZ = 1
$ dr = 0.10$ DX = dr$ DY = dr$ DZ = dr
$ DS = 0.05
$ fA = 0.5$ fB = 0.5
$ noise_strength = 0.025$ lambda1 = 0.30$ lambda2 = lambda1 * 0.50$ randomSeed = 123
16
$ chiNAB = 12.0$ NLEN = 100.0
Note: Comment lines to highlight the beginning of the variables section of the pre file explain the meaning of thevariables.
Note: Tech-X recommends that you always use comment lines both to make the various sections of the pre file easyto find and to clarify the purpose of parameters in each section.
Simulation Parameter Definition
Following the variable definition section, the input file defines the top-level simulation parameters.
Top-level simulation parameters specify the global data that is not specific to any object in the simulation. ThelinearDiblock.pre file defines two simulation parameters:
• nsteps
• dumpPeriodicity
The nsteps parameter specifies the number of update steps in the simulation. If PSim must be restarted, it usesnsteps to determine the number of additional steps to run. The linearDiblock example has 1000 update steps.
The dumpPeriodicity parameter specifies the number of update steps that must elapse before PSim dumps theoutput of the simulation into output files. The linearDiblock example dumps output to files after every 10 time steps.Because the linearDiblock example has 10 update steps, it dumps output once, at the end of the simulation. For moreinformation, see Basic Concepts for All Simulations.
You can override the values of the nsteps, and dumpPeriodicity parameters by adding options to the polyswift com-mand line. For more information, see Running the PolySwift++ engine from the Command Line.
For the complete list of top-level simulation parameters, see the PSim Reference Manual.
The top-level simulation parameter definition section of the linearDiblock.pre file follows.
########################################################### Domain parameters and defaults ###########################################################
nsteps = 500 # timesteps in relaxation algorithmdumpPeriodicity = 20 # dump period
Grid Definition
Following the section defining the top-level simulation parameters, the input file defines the Cartesian grid. Thepseudospec macro sets up the grid and domain decomposition blocks for this simulation. See Setup for PseudospectralSolver Macro for details of the pseudospec macro and see the PSim Reference Manual for details of the <Grid> and<Decomp> blocks. This macro is loaded in the following lines in the linearDiblock.pre file
$ import pseudoSpecSetupsetupPS(NX, NY, NZ, DX, DY, DZ, "’off’")
17
Input Blocks in the Input File
The following three blocks in the file linearDiblock.pre set up the physical fields. There are two fields for themonomer densities; one for the monomers on the ‘A’ block and one for the monomers on the ‘B’ block. The thirdfield is a constraint field needed to maintain the incompressibility constraint used in this simulation. For additionalmonomer types, an extra <PhysField> block need to be added along with additional blocks defining their interactions(see below).
######################################################## Physical observable fields#######################################################
<PhysField totStyrDens>kind = monomerDenstype = fieldD3R
</PhysField>
<PhysField totEthyDens>kind = monomerDenstype = fieldD3R
</PhysField>
<PhysField defaultPressure>kind = constrainttype = fieldD3R
</PhysField>
The next block is the <EffHamil> block and holds the updaters and interactions that define the energetics of the modeland relaxation methods.
########################################################## Effective Hamiltonian: defines energetic SCFT model#########################################################<EffHamil mainHamil>
kind = canonicalMFupdaterSequence = [wAwB]
<Updater wAwB>
kind = steepestDescenttype = incompressiblerelaxlambdas = [lambda1 lambda2]noise = noise_strengthupdatefields = [totStyrDens totEthyDens]interactions = [StyrEthy]
</Updater>
<Interaction StyrEthy>kind = florychi = chiABscfields = [totStyrDens totEthyDens]
</Interaction>
</EffHamil>
For some problems, additional updaters need to be specified. The order in which they are to be applied is set by
18
the parameter ‘updaterSequence’. Only one <Updater> block is needed for this example. The <Interaction> blockspecifies the Flory interaction model. The parameter ‘chi’ sets the Flory interaction strength χ. The ‘scfields’ param-eters specfies which monomer species that the χ parameter is setting the segregation strength between. For additionalmonomer species, additional <Interaction> blocks would be required. For example, if the model contains A,B and Cmonomers there would need to be three interaction blocks (AB, AC and BC).
The linear diblock architecture is specified in the next block.
<Polymer diblock1>
kind = blockCopolymervolfrac = 1.0length = NLEN
The ‘length’ parameter corresponds to N in the theory and ‘volfrac’ is the volume fraction of this diblock species.Since this is the only copolymer in the system the volume fraction is one. For multiple species the code checks that allpolymeric and solvent species sum to unity.
The <Polymer> block holds <Block> objects. For a diblock there are two blocks listed ‘blockA’ and ‘blockB’. The kindparameter specifies the model and solution method namely, a flexible Gaussian coil model solved with a pseudospectralmethod.
<Block blockA>kind = flexPseudoSpecscfield = totStyrDensds = DSlengthfrac = fAheadjoined = [freeEnd]tailjoined = [blockB]
</Block>
The flexible Gaussian model leads to the following modified diffusion equation for the restricted partition function ofthe polymer chains.
∂q
∂s=
R2
g0∇2q(~r, s)− iNwAq(~r, s), 0 < s < f
R2g0∇2q(~r, s)− iNwBq(~r, s), f < s < 1
This block implements the following algorithm for calculating the restricted partition function q(~r, s) needed forcalulating the coarse grained monomer density fields
q(~r, s+ ∆s) = exp[∆s(∇2 − w(~r))
]q(~r, s)
q(~r, s+ ∆s) ≈ e−w(~r)∆s/2e∆s∇2e−w(~r)∆s/2q(~r, s)
q(~r, s+ ∆s) ≈ e−w(~r)∆s/2F̂−1[e−∆s k2
F̂[e−w(~r)∆s/2q(~r, s)
]]The ‘scfield’ parameter lists the name of the physical field object corresponding to a particular monomer species. Sothe <Block> object ‘blockA’ contains the physical field ‘totStyrDens’ (ie ‘A’) and <Block> object ‘blockB’ containsthe physical field ‘totEthyDens’ (ie ‘B’). The sizes of each block (fA and fB) set the parameter ‘lengthfrac’ in eachblock.
<Block blockB>kind = flexPseudoSpecscfield = totEthyDens
19
ds = DSlengthfrac = fBheadjoined = [blockA]tailjoined = [freeEnd]
</Block>
The connectivity information specifying a linear diblock is set with the ‘headjoined’ and ‘tailjoined’ parameters. The‘blockA’ above has one free-end and the other end connected to only one block, namely ‘blockB’. The ‘blockB’ hasone free-end and the other end connected to only one block, namely ‘blockA’.
The next block specifies optional diagnostics. This block causes the free-energy of the system modeled by the<EffHamil> block ‘wAwB’ to be dumped to a dataset in a ‘History’ file.
<History freeE1>kind = freeEnergyupdaterName = wAwB
</History>
The expression for the free-energy calculated by this diagnostic is
F̃ = V −1
∫d~r[χN(φA − φ̄A)(φB − φ̄B)− ωAφA − ωBφB − p(1− φA − φB)
]− lnQ[ωA, ωB ]
where the free-energy has been scaled by N/ρ0V and shifted by the free-energy of the disordered phase.
Visualize linearDiblock Using PSimComposer
Please refer to documentation for running the input file associated with this tutorial at psimbase-linearDiblock
This section explains how to visualize the data generated for the linearDiblock.pre file by running PSimCom-poser.
Note: In addition to PSimComposer, other commonly used tools for visualizing PolySwift++ data are:
• Mathematica
• VisIt from Lawrence Livermore National Laboratory
1. From within PSimComposer, click on the Visualize icon in the icon panel on the far left.
2. Click on the Open button.
3. In the CONTROLS pane, in the Variables list of the Data Overview data view, click on the arrow next toScalar Data.
4. Select MonomerDensity (totEthyDens) (you may need to resize the CONTROLS pane so the complete titlesmay be seen.
The initial 2D contour rendering is not as clear as the ‘Pseudocolor’ plot capability. Click off the “Display Contours”box.
Move the ‘Dump’ slider to visualize the data files in time. In this way, one can follow the relaxation procedure.
Move the ‘Dump’ slider to the end of the run to view the fully equilibrated state.
This grid size for this tutorial is sufficiently small that the ordered lamellar phase should be seen regardless of randomseed or processor number. The orientation of the layers may be different than the figure above but the free-energyshould be close (small differences possible due to effect of box constraint).
20
Figure 2: PSimComposer initial view displaying 2D pseudocolor of monomer density for the ‘totEthyDens’ species
21
Figure 3: PSimComposer intermediate view displaying 2D pseudocolor of monomer density for the ‘totEthyDens’block
22
Figure 4: PSimComposer final view displaying 2D pseudocolor of monomer density for the ‘totEthyDens’ block
23
To view the free-energy values in the file linearDiblock*History.h5 go back to the CONTROLS pane andselect the Data Overview menu and go to the History selection
Figure 5: PSimComposer displaying single history dataset for the free-energy of the AB diblock bulk system
In Lesson 2 of this Linear Diblock Simulation Tutorial, you will adjust parameters that control the resolution of thesimulation and the run time, see Lesson 2: Increase the resolution of the simulaton.
Lesson 2: Increase the resolution of the simulaton
Starting with an example simulation in your area of interest and making changes to the example is a practical way tocreate a new simulation. If you visualize the output as you make changes, you can see whether you are getting theresults you expect or whether you need to review and modify your initial changes before making further changes.
Now that we have examined the sections of the linearDiblock.pre file in detail and visualized the output inPSimComposer, we are ready to make changes to the linearDiblock.pre file. In this lesson we will:
• Increase the grid resolution
• Increase the grid size (simulation size)
• Increase the number of update steps (restart capability)
Increase the grid resolution
The first change we are going to make in the linearDiblock.pre file is simple. We are going to increase the resolutionof the grid from dx = dy = 0.1Rg → 0.05Rg . For a fixed grid size, this effectively reduces the overall simulation
24
length in each direction.
Increase the grid size (simulation size)
The second change we are going to make in the linearDiblock.pre file is to increase the grid size from NX = NY =64 → 128 while keeping the new grid cell size of dx = dy = 0.05Rg . This restores the overall system length inLesson 1 but now at a higher spatial resolution
Increase the number of time steps
The PolySwift++ engine currently solves for the mean-field (fluctuation-free) solution of the copolymer SCFT equa-tions. Iterative methods are used to advance the current state of the simulation at step ni to a state closer to themean-field solution at step ni+1. Increasing the total number of time steps nT will tend to produce results closer tothe true, mean-field solution.
This is most clearly seen in a system sufficiently large for topological defects to form. Keeping the same overall gridsize, change the grid cell size to dx = dy = 0.2Rg . This effectively doubles the overall system (while reducing theresolution). In this way, one can more quickly illustrate the effect of changing the number of time steps in a systemthat does not rapidly reach a completely ordered state.
The overall order is lamellar, however topological defects such as edge dislocations can clearly be seen. To increasethe number of time steps one can restart the simulation from any dumped state. Restart this simulation by going tothe Run Pane and going to the Standard runtime options. Then enter ‘500’ into the ‘Restart At Dump Number’ box,this will restart the simulation from the last dumped state. If the other parameters are left unchanged, this will run thesimulation for another 500 time steps. defects to form.
25
After running for 1000 time steps the system is closer to an ordered state, however the relaxation is clearly becomingtrapped in a state with topological defects. These features are seen in experimental systems and a variety of methodscan be used to remove them to produce a completely ordered, equilibrium state. These experimental methods haveinspired numerical techniques that are demonstrated in the Spectral Filtering and Zone Annealing examples.
In Lesson 3 of this Linear Diblock Simulation Tutorial, you will adjust parameters that control the block sizes andinteraction strengths. Then, one can investigate the entire morphology phase diagram in Lesson 3: Explore morphologyphase diagram.
Lesson 3: Explore morphology phase diagram
This lesson will show how PSim can be used to explore the morphology phase diagram for the well known 2-component AB linear diblock model. The examples below will be simulations for small 2D systems as these runto completion quickly. Exploring the full phase diagram would require 3D simulations that will need a large, parallelcompute cluster. (Remote execution on clusters will be available in v 1.2.0).
The figure Schematic of phase diagram calculated from fully spectral SCFT method, that requires foreknowledge ofspace groups that copolymer domains will form. shows a schematic of the well known SCFT phase diagram for anAB diblock. The three points labeled in the phase diagram are three pairs of (f, χN ) values corresponding to differentmorphologies in the phase diagram. Using the ‘Linear Diblock’ example change the (f, χN ) values and run thesimulation through PSimComposer to generate the result.
Lamellar phase morphology (LAM)
The first example is for f = 0.5 and χN = 12.0. These are the default settings for this template example
26
Figure 6: PSimComposer view of Standard section of Runtime Options
27
Figure 7: Run Pane with restart parameter set and Log information after run is restart
28
Disordered, homogeneous phase (DIS)
The next example is for f = 0.5 and χN = 8.0
Hexgonally packed cylinders (HEX)
The next example is for f = 0.3 and χN = 18.0
A summary of the results you should see is below. The images of the monomer density fields are from larger PSimsimulations to more clearly illustrate the calculated morphologies.
3.2 Interacting Surfaces Tutorial
Interaction Surfaces Tutorial
Interacting Surfaces/Confinement Model
This tutorial covers how to simulate a dense melt of confined monodisperse AB diblock copolymer chains.
A Hamiltonian for this system can be written as
29
Figure 8: Schematic of phase diagram calculated from fully spectral SCFT method, that requires foreknowledge ofspace groups that copolymer domains will form.
30
31
H =1
4R2g0
n∑α=1
∫ 1
0
ds
(d~rα(s)ds
)2
+ ρ−10
∫d~r χAB ρ̂A(~r)ρ̂B(~r)
+ρ−10
∫d~r χWA %W (~r)ρ̂A(~r)
+ρ−10
∫d~r χWB %W (~r)ρ̂B(~r)
The first two terms are the same as the bulk model and are described in Lesson 1: Model/Simulation detail for inter-acting surfaces. The positions of each wall-monomer can in principle be described explicitly with a function %̂W (~r),as are the monomers within the diblock chains. However, this is unnecessary because these particles are forced to bestationary and therefore the entropy due to the wall-particles does not contribute to the total partition function. Theparticle density inside the wall is assumed to be sufficiently large, such that the continuous density field %W (~r) is anappropriate description of the interactions between particles in the wall and monomers along the polymer chains.
With χAB > 0, an overall repulsive force between dissimilar monomers is modelled, which drives phase separation.The wall interaction parameters χWA and χWB determine the tendency for the polymer chains to either wet or beexcluded from the confining surface. The relative sizes of the χ parameters determine the effective attraction orreplusion for a monomer species to a wall species. For example, if χWA < χWB then A monomers preferentially wetthe surface wall. If χWB < χWA then B monomers preferentially wet the surface wall, and if χWB = χWA then thewall is effectively neutral. The absolute sizes of χWA, χWB .... determine how strongly the monomers are excludedfrom the confinement walls.
The A/B monomer density operators and the wall density function are:
32
Figure 9: 2-component linear diblock phase diagram results from PolySwift++
33
ρ̂A(~r) = N
n∑α=1
∫ f
0
ds δ(~r − ~rα(s))
ρ̂B(~r) = N
n∑α=1
∫ 1
f
ds δ(~r − ~rα(s))
%W (~r) ∈ [0, ρ0].
where f is the fraction of the chain consisting of A monomers and %W (~r) can in general be an arbitrary function ofposition.
About the Example Input File, interactingSurfaces.pre
The interactingSurfaces.pre file has been selected for use with the example simulation in this section because it isrepresentative of the input blocks needed to define a simulation of this type. These blocks define geometries, setup theadditional fields needed to implement the confinement model and define the appropriate energetic model to describethe interactions of the confining surfaces and the monomers on the copolymer chains.
PolySwift++ Features Demonstrated
The interactingSurfaces example demonstrates the following PSim features:
• specifying geometry
• defining wall interaction model
• associating different surfaces with specific monomer interactions
In the next section Lesson 1: Model/Simulation detail for interacting surfaces, you will examine the differences in theinput file blocks for simulations with confinement.
Lesson 1: Model/Simulation detail for interacting surfaces
Definition of interactingSurfaces
Now that we have examined the conceptual model for interactingSurfaces, we are ready to define the interacting-Surfaces simulation, which includes five physical fields, a model definition block, boundaries and the other blocksnecessary for all copolymer simulations (see Linear Diblock Simulation Tutorial). In addition to the blocks necessaryfor bulk simulations, this input file involves:
• Physical field definitions for the surfaces
• Model definition (includes special updater parameters and wall-polymer interactions)
• Boundary object definitions (one for the top wall and one for the bottom wall)
As needed, refer back to the PSim User Guide section, Basic Concepts for All Simulations and Linear Diblock Simu-lation Tutorial for simulation/model details that apply to bulk simulations as well as simulations with confinement
34
Blocks in Input File
The following three blocks in the file interactingSurfaces.pre setup the physical fields. There are two fieldsfor the monomer densities, one for the monomers on the ‘A’ block and one for the monomers on the ‘B’ block. Thethird field is a constraint field needed to maintain the incompressibility constraint used in this simulation. These aresimilar to the blocks for the bulk case (see Lesson 1: Model/Simulation detail for a 2-component AB diblock)
For the Interacting Surfaces examples there are two extra physical fields, one for the density field that defines the topwall and one for the bottom wall. There are separate fields for the walls because different interactions will be definedbetween the copolymer monomers and the top/bottom surfaces.
<PhysField totTopWall>kind = monomerDenstype = fieldD3R
</PhysField>
<PhysField totBottomWall>kind = monomerDenstype = fieldD3R
</PhysField>
These physical fields contribute to the %W (~r) field. The boundary objects themselves are defined in the <Boundary>input blocks.
################################################# A Boundary object################################################
# Defines left(bottom) and right(top) edges# of flat walls... along Y for both 2D and 3D# domain decomp$ WALLEDGE_NEGY = float(10.0)$ WALLEDGE_POSY = float(NY - WALLEDGE_NEGY)
# Sets the hyperbolic tangent profile$ WIDTHPARAM = float(0.1/DX)
<Boundary bottomInteractWall>kind = fixedWallboundaryfield = totBottomWall
<STFunc walls>kind = pyfuncname = lowSineWallparamKeys = [ widthParam walledge amplitude freq ]paramValues = [ WIDTHPARAM WALLEDGE_NEGY SINE_AMPL SINE_FREQ ]
</STFunc>
</Boundary>
<Boundary topNeutralWall>kind = fixedWallboundaryfield = totTopWall
<STFunc walls>kind = pyfuncname = highFlatWallparamKeys = [ widthParam walledge ]
35
paramValues = [ WIDTHPARAM WALLEDGE_POSY ]</STFunc>
</Boundary>
The parameters ‘WALLEDGE_NEGY’, ‘WALLEDGE_POSY’ and ‘WIDTHPARAM’ are set up as a convenienceoutside of the <Boundary> objects. The <Boundary> blocks here are of ‘kind=fixedWall’. These are constraints thatdo not change as the simulation proceeds. These boundary blocks have two main functions: (1) specifying the spatiallocation of the walls and (2) the properties of the wall with respect to the monomeric species. The ‘boundaryfield’parameter takes the name of a physical field corresponding to a wall. This physical field appears in <Interaction>blocks elsewhere in the input file that defines the relative preferences for each monomer species to be attracted to orrepelled from the confining surface. The <Boundary> block can also be a container for an <STFunc> that defines thespatial extent of the confinement field. For this example, the <STFunc> is of ‘kind = pyfunc’ which uses the Python/CAPI to import an external python function in the file ‘interactingSurface.py’. For more details see Lesson 2: SpecifyingGeometry.
The next block is the <EffHamil> block and contains various updaters and interactions that define the energetics ofthe model and relaxation methods.
########################################################## Effective Hamiltonian: defines energetic SCFT model#########################################################<EffHamil mainHamil>
kind = canonicalMFupdaterSequence = [wAwB]
<Updater wAwB>
kind = steepestDescenttype = incompressiblerelaxlambdas = [0.20 0.10]noise = 0.02
updatefields = [totStyrDens totEthyDens]interactions = [StyrEthy EthyBottomWall StyrBottomWall EthyTopWall StyrTopWall]constraints = [EthyBottomWall StyrBottomWall EthyTopWall StyrTopWall]
</Updater>
<Interaction StyrEthy>kind = florychi = chiABscfields = [totStyrDens totEthyDens]
</Interaction>
The ‘interactions’ parameter must have each of the <Interaction> block names in which the ‘updatefields’ namesappear. For simulations with constraints, the <Interaction> block names that contribute to the boundary constraints,must be listed in the ‘constraints’ parameter. The wall-monomer interactions below, are defined within the same<EffHamil> block
#################################### Bottom wall interaction blocks###################################<Interaction EthyBottomWall>kind = floryWallchi = CHI_WALL_ETHYscfields = [totBottomWall totEthyDens]
36
wallField = totBottomWall</Interaction>
<Interaction StyrBottomWall>kind = floryWallchi = CHI_WALL_STYRscfields = [totBottomWall totStyrDens]wallField = totBottomWall
</Interaction>
#################################### Top wall interaction blocks# These are hardwired to be equal# and therefore effectively neutral###################################<Interaction EthyTopWall>kind = floryWallchi = 0.20scfields = [totTopWall totEthyDens]wallField = totTopWall
</Interaction>
<Interaction StyrTopWall>kind = floryWallchi = 0.20scfields = [totTopWall totStyrDens]wallField = totTopWall
</Interaction>
</EffHamil>
Note that since separate physical fields are associated with the <Boundary> blocks defining the top/bottom walls,different interactions with the monomeric species can be set for each surface.
Visualize interactingSurfaces Using PSimComposer
This section explains how to visualize the data generated for the interactingSurfaces.pre file by runningPSimComposer.
Note: In addition to PSimComposer, other commonly used tools for visualizing PolySwift++ data are:
• Mathematica
• VisIt from Lawrence Livermore National Laboratory
1. From within PSimComposer, click on the Visualize icon in the icon panel on the far left.
2. Click on the Open button.
3. In the CONTROLS pane, in the Variables list of the Data Overview data view, click on the arrow next toScalar Data.
4. Click on the Colors button and choose the limits to be [0-1] and select ‘Hot Desaturated’ from the palette.
Select the MonomerDensity (totTopWall) to see the field assocated with the top surface.
Deselect the ‘totTopWall’ and select the MonomerDensity (totBottomWall) to see the field assocated with the bottom,structured surface.
37
Figure 10: PSimComposer showing the physical field for the top wall confinement. (Note, the wall densities)
38
Figure 11: PSimComposer showing the physical field for the bottom (‘sine wall’) surface confinement
39
Note, the wall densities are fixed and do not enter the theoretical treatment in the same way. Therefore, the conjugatedensities associated with the wall fields are not used in the simulation. They are by default initialized to random valuesand not updated.
Deselect the ‘totBottomWall’ and select the MonomerDensity (defaultPressure) to see the field associated with allconstraints in simulation. This field is constructed automatically within the algorithm.
Figure 12: PSimComposer showing the physical field for all constraints.
Deselect ‘defaultPressure’ and select the MonomerDensity (totEthyDens) to see the field associated with minoritymonomeric species. The first density configuration for Dump:1 is
Move the Dump slider to the end to see the equilibrium configuration
Lesson 2: Specifying Geometry
Details of the Boundary Block
Now that we have examined the entire input file for interactingSurfaces, we are ready to examine how to specifyboundaries. This includes:
• Wall parameters
• Boundary input blocks
• Python geometry file ‘interactingSurfaces.py’
As needed, refer back to the PSim User Guide section, Basic Concepts for All Simulations.
40
Figure 13: PSimComposer showing the physical field for ‘totEthyDens’. Note, the regions of constraint can be seenwhere all polymer densities are ~0.0.
41
Wall Parameters
The variables defined above the <Boundary> blocks are
• The position/size of the bottom wall ‘WALLEDGE_NEGY’
• The position/size of the top wall ‘WALLEDGE_POSY’ (defined in terms of the bottom wall and size of thesystem)
• The width parameter of the edge of the fixed walls ‘WIDTHPARAM’ (scaled so that the width size stays constantas the grid size, DX is adjusted)
Setting these parameters is a convenience so the values set in the <Boundary> block below can be documented clearly.
Boundary Block
The Boundary block specifying the bottom wall is:
<Boundary bottomInteractWall>
kind = fixedWallboundaryfield = totBottomWall
<STFunc walls>kind = pyfuncname = lowSineWallparamKeys = [ widthParam walledge amplitude freq ]paramValues = [ WIDTHPARAM WALLEDGE_NEGY SINE_AMPL SINE_FREQ ]
42
</STFunc>
</Boundary>
As mentioned in the previous lesson, boundary blocks have two main functions: (1) specifying the spatial locationof the walls and (2) the properties of the wall with respect to the monomeric species. The ‘boundaryfield’ parametertakes the name of a physical field corresponding to a wall. This physical field appears in <Interaction> blocks thatdefine the relative preferences for each monomer species to be attracted to or repelled from the confining surface.This ‘Boundary’ block is also a container for an <STFunc> block that defines the spatial extent of the confinement.For this example, the <STFunc> is of kind = pyfunc which uses the Python/C API to import functions from anexternals file. The Python method that is used to define the spatial region of the wall is set in the parameter name =lowSineWall.
For an input file name of ‘simName.pre’, PSim automatically looks for a Python file with the name ‘simName.py’.This Python file is expected to contain methods that define functions needed by the blocks that refer to these methodsby name. For a simulation using the input file ‘interactingSurfaces.pre’, the Python methods are contained in the file‘interactingSurface.py’.
## Sine modulated flat wall on "low" side of system#def lowSineWall(x, y, z, t, params={’widthParam’:1.0,
’walledge’:10,’amplitude’:3.0,’freq’:4.0}):
global NXglobal NYglobal NZ
# Convert dictionary to variable assigmentswidthParam = params[’widthParam’]walledge = params[’walledge’]amplitude = params[’amplitude’]freq = params[’freq’]
if (NZ == 1):r = [x,y,1]negEdge = [x,0,1]
else:r = [x,y,z]negEdge = [x,0,z]
negRdis = rdistance(r,negEdge)negRdis = negRdis - (amplitude*math.sin(freq*2.0*math.pi*x/NX))
tanhval = math.tanh((walledge-negRdis)/widthParam)wallValue = (tanhval+1)/2.0return wallValue
This Python function generates a wall with the sine wave profile seen in the template example. The structure of the‘edge’ of the wall follows a hyperbolic tangent profile (as do most of the wall edge functions for the template examplesprovided). A schematic of the functional form of the wall edge is shown here
The function ‘lowSineWall’ sets the position of the bottom wall (walledge), the width of the wall edge (widthParam),the amplitude of the sine function (amplitude) and the frequency of the sine function (freq), such that ‘freq’ number ofperiods fits into the length of the simulation grid. The STFunc block takes this function and uses it to generate a scalaras a function of (x,y,z) position in the grid. This scalar is used to set the appropriate value of the constraint field thatdefines the surfaces.
43
Figure 14: Schematic of function form of wall ‘edge’
Keeping the specifics of the geometry external to the PolySwift++ engine allows the same algorithms to be used, asthe geometry construction changes. Note: future releases will implement interactive, constructive geometry softwareto specify confinement. The external Python file contains the methods
# Distance between point r and r0 (r is a python vector [x,y,z])def rdistance(r,r0):
# Sine modulated flat wall on "low" side of systemdef lowSineWall(x, y, z, t, params={’widthParam’:1.0,’walledge’:10,’amplitude’:3.0,’freq’:4.0}):
# Sine modulated flat wall on "high" side of systemdef highSineWall(x, y, z, t, params={’widthParam’:1.0,’walledge’:10,’amplitude’:3.0,’freq’:4.0}):
# Simple flat wall on "low" side of systemdef lowFlatWall(x, y, z, t, params={’widthParam’:1.0,’walledge’:10 }):
# Simple flat wall on "high" side of systemdef highFlatWall(x, y, z, t, params={’widthParam’:1.0, ’walledge’:10 }):
which can be used to set other kinds of surfaces. Keeping the Python geometry functions external, allows developersto more easily prototype new geometries. In principle, any arbitrary function can be used to define surfaces for PSimsimulations.
44
4 Advanced Concepts
4.1 Running the PolySwift++ engine from the Command Line
There are 2 main ways to run PolySwift++ from the command line.
• A python script ‘ps-run.py’ is included in the PSim distribution (as well as engine-only distributions). If installedproperly and the PATH environment variable is set correctly, ‘ps-run.py -h’ should provide help.
• Running the PolySwift++ executable directly. Both the serial and parallel PolySwift++ executables require youto specify the input file (.pre) as well as any optional arguments.
The ps-run.py PolySwift++ run script
ps-run.py:
A Python script that helps setup and run PolySwift++ in separate directories. ps-run.py -h gives theusage message for the script. Running the command:
ps-run.py -d new-ps-rundir-1 -i diblock.pre
will create a new directory ‘new-ps-rundir=1’, copy the input file ‘diblock.pre’ to this new directory andsetup the run. If the hostname is recognized and an entry exists for the local queueing system, ps-run.pywill create the correct PBS script and submit. If an entry does not exist ps-run.py will attempt to run thejob locally in the background of the compute machine from which you are submitting the run. If youwould like to have a PBS entry added contact Tech-X. The ps-run.py script will prompt the user for theinformation needed to setup the simulation.
Running the PolySwift++ Executable
Your PSim distribution package contains two executable programs for running the PolySwift++ engine, one for se-rial computations (polyswiftser) and another for parallel computations (polyswift). Both versions of thePolySwift++ executables are located in the POLYSWIFT_BIN_DIR directory.
Command Line Features
If PolySwift++ is run from the command line, input file and runtime options are specified as command line options.PSimComposer sets up your environment prior to running PolySwift++, and therefore you must set up your environ-ment when running PolySwift++ from the command line.
Symbol Definition on the Command Line
txpp allows symbols to be defined on the command line. These definitions override any symbol definitions in theouter-most (global) scope. This allows you to set a default value inside an input file that can then be overridden on thecommand line if needed.
For example, if the following is in the outermost scope of the input file (outside of any blocks or macros):
$ X = 3X
Then this will result in a line containing 3 in the output. However, if you were to invoke txpp via:
45
txpp.py DX=4
then this will result in a line 4.
However, if you were to define X inside a block (not in the global scope), such as:
<block foo>$ X = 3X
</block>
then X will always be 3, no matter what value for X is specified on the command line.
Order of Parameter Precedence
If a parameter is both set within the input file and specified on the command line, the command line parameter valuetakes precedence. The command line override enables you to configure an input file with default values while exploringalternative parameter settings from the command line. From the command line, you can quickly change simulationgrid sizes, dump periodicity, random seed, etc.
Examples of Running PolySwift++ from the Command Line
In these examples, it is assumed that you are either in the directory in which the polyswiftser is installed or you haveadded the appropriate directory to your PATH environment variable.
Command Line Options
To use multiple options, the command line syntax is:
./polyswiftser -i filename [-o prefix_name] [-r num] [-n num]
in which ./polyswiftser is used to run a serial computation.
Commonly used options that you can specify on the command line include:
-i filename Read input from file named filename.
For example:
./polyswiftser -i diblock.pre
-o prefix_name Base names of output files on the text string prefix_name.
For example, if you want output files named diblockTest1 rather than diblock, use:
./polyswiftser -i diblock.pre -o diblockTest1
-n num Run the simulation for num time steps. This option overrides the nsteps parameter.
For example, if you want to run diblock with 50 time steps rather than 10, use:
./polyswiftser -i simpleEs.in -n 50
-d num Dump data every num time steps. This option overrides the dumpPeriodicity parameter.
For example, to run diblock and dump output after every 5 time steps, use:
46
./polyswiftser -i diblock.pre -d 5
-r num Restart PolySwift++ from dump num.
For example, if you want to restart diblock using the output dumped at time step 50, use:
./polyswiftser -i diblock.pre -r 50
Serial Computation
The PolySwift++ executable for use in serial computation is named polyswiftser. Except as noted, the explanationsand tutorials within the PSim In Depth and PSim Quick Start manuals demonstrate PolySwift++ usage for serialcomputations. Here is an example of PolySwift++ command line invocation using an input file named myfile.inand specifying 1000 time steps, outputting the result data (dumping) every thousand steps. By default, the output filesfor this example would be named using the format myfile.out.
polyswiftser -i myfile.pre -n 1000 -d 1000
Note: The above invocation line assumes you have executable in your PATH.
Note: When running PolySwift++ via PSimComposer, command line options are not directly available, however -iand -o command line options described in this document are implicit; that is, these options are automatically invokedwhen running PSimComposer.
Parallel Computation
The PolySwift++ executable for use in parallel computation is named polyswift. This section explains use of thePolySwift++ executable program for parallel computations. PolySwift++ for parallel computations requires the Mes-sage Passing Interface (MPI).
Running PolySwift++ with Parallel Queuing Systems
Parallel queuing systems, such as LoadLeveler and PBS, require the submission of a shell script with embeddedcomments that the systems interpret. Here is an example of a basic shell script for a PBS-based system:
#PBS -N NDS_polyswift#PBS -l nodes=2:ppn=2cd /directory/containing/your/input/filempiexec -np 4 polyswift -i diblock.in -n 250 -d 50
The run script ps-run.py invokes another script (pspp-gen.py, that is also included) that will generate a PBS run scriptand submit to the queuing system. The specific PBS file settings can be included in the pspp-gen.py script by contactingTech-X.
4.2 HDF5 Format PSim Output Files
Hierarchical Data Format Version 5 (HDF5) is a library and file format for storing graphical and numerical data andfor transferring that data between computers. PSim outputs data in HDF5 format.
47
The Hierarchical Data Format was developed by the National Center for Supercomputing Applications at theUniversity of Illinois at Urbana-Champaign. For more information about HDF5, please see the web page at:http://hdfgroup.org/HDF5
HDF5 Files
PSim outputs data in HDF5 format files that have .h5 suffixes.
PSim produces one HDF5 file for each field or species at each dump time. For example, if the simulation parameternsteps = 100 and the simulation parameter dumpPeriodicity = 10, PSim dumps data 10 times during thesimulation and outputs a total of 10 HDF5 files for each field or species while running the simulation.
For more information about HDF5, see: http://hdfgroup.org/HDF5
Change the Names of Output Files
If you want to change the names of the output files, which include the .h5 files, you can specify the -o output optionwhen you run PSim.
For example, you want to replace linearDiblock with linearDiblockTest1 in the names of thelinearDiblock simulation’s output files. Run serial PSim from the command line using this command:
polyswiftser -i linearDiblock.in -o linearDiblockTest1
Display the Content of .h5 Files
The h5dump utility converts the binary data in .h5 files into human-readable ASCII data in .txt files.
The h5dump utility is available for all the platforms on which PSim runs. You can download the utilityfrom:http://hdfgroup.org/HDF5 The basic command is:
h5dump -o output_file_name.txt your_h5_file.h5
To convert the file ‘diblock_totStyrDens_1000100.h5’ to ASCII text format, use this command:
h5dump -o diblock_totStyrDens_1000100.txt diblock_totStyrDens_1000100.h5
For information about HDF5 and the h5dump utility, see the HDF5 User’s Guide and HDF5 Reference Manual, whichare available at: http://www.hdfgroup.org/HDF5/doc/index.html
5 Troubleshooting
5.1 Troubleshooting Numerical SCFT Simulations
This chapter discusses common problems that you may encounter as you modify examples and develop your ownSCFT polymer simulations.
The Simulation Does Not Start/Finish Properly
If submitted via PBS, check queue time limits
Check contour step size. If one copolymer block in simulation is too small the contour step size for this block mayhave to be decreased.
48
The Simulation Becomes Unstable
Check the resolution and update step size.
For hybrid SCFT, check simulation log for excessive overlap for incompressibility constriant
6 References
Further reading and terminology definitions:
6.1 Bibliography
[1] “Functional Integrals and Polymer Statistics”, K.F. Freed, Adv. Chem. Phys., 22, p1 (1972).
[2] “Theory of Inhomogeneous Multicomponent Polymer Systems”, K.M Hong, J. Noolandi, Macromolecules 14p727-736 (1981).
[3] “Stable and Unstable Phases of a Diblock Copolymer Melt”, M.W. Matsen, M. Schick, Phys. Rev. Lett., 72,p2660-2663, (1994).
[4] “Combinatorial Screening of Complex Block Copolymer Assembly with Self-Consistent Field Theory”, F. Drolet,G.H. Fredrickson, Phys. Rev. Lett., 83, 21, p4317-4320, (1999).
[5] “Parallel algorithm for numerical self-consistent field theory simulations of block copolymer structure”, S.W.Sides, G.H. Fredrickson, Polymer 44, p5859-5866, (2003).
[6] “Composite mesostructures by nano-confinement”, Y. Wu, G. Cheng, K. Katsov, S.W. Sides, J. Wang, J. Tang,G.H. Fredrickson, M. Moskovits, G.D. Stucky, Nature Materials, 3, p816, (2004).
[7] “Field-Theoretic Computer Simulation Methods for Polymers and Complex Fluids”, G.H. Fredrickson, V. Ganesan,F. Drolet, Macromolecules, 35, p16-39, (2002).
[8] “Ordering of Sphere Forming SISO Tetrablock Terpolymers on a Simple Hexagonal Lattice” J. Zhang, S. W. Sidesand F. S. Bates, Macromolecules, 2012, 45 (1), pp 256265.
[9] “Directed Assembly of Model Block Copolymer PCBM Blend System for Photovoltaic Applications” G. Singh,M. M. Kulkarni, D. Smilgies, S. Sides, B. Berry, D. Raghavan, D.G. Bucknall, B Sumpter and A. Karim. MRSProceedings (2012) 1390 : mrsf111390h1354.
[10] “Morphology diagrams for A2B copolymer melts: real-space self-consistent field theory” R. Kumar, Y. Li, S. W.Sides, J. W. Mays and B. G. Sumpter. Journal of Physics: Conference Series 402 (2012) 012042.
[11] “Morphologies of ABC tri-block terpolymer melts containing poly(cyclohexadiene) : effects of conformationalasymmetry”, Kumar, R.; Sides, S.; Goswami, M.; Sumpter, B.; Hong, K.; Wu, X.; Russell, T.; Gido, S.; Misichronis,K.; Rangou, S.; Avgeropoulos, A.; Tsoukatos, T.; Hadjichristidis, N.; Beyer, F.; Mays, J. Langmuir, 29(6), pp 1995-2006 (2013).
[12]“Effect of Macromolecular Architecture on the Morphology of Polystyrene/Polyisoprene Block Copolymers” C.Dyer, P. Driva, S. W. Sides, B. G. Sumpter, J. W. Mays, J. Chen, R. Kumar, M. Goswami, and M. D. DadmunMacromolecules, (2013), 46 (5), pp 20232031. DOI: 10.1021/ma202650a
6.2 Glossary
domain The rectangular Cartesian grid. The physical domain is the grid specified by a user.
FDTD Finite-difference time-domain. The FDTD method is a technique for solving problems in electromagnetics.
49
float A floating-point number.
HDF5 Hierarchical Data Format Version 5. A library and file format, developed by the National Center for Super-computing Applications at the University of Illinois at Urbana-Champaign, for storing graphical and numericaldata and for transferring that data between computers. PSim outputs data in HDF5 Format PSim Output Files.
input block An input block is an object consisting of simulation parameters in an input file. Input blocks can benested within other input blocks. For example, input blocks for copolymer blocks are nested within the inputblock for an polymer.
input file A PSim simulation file, which has a .pre suffix. Users define a simulation and its variables in an input file.PSimComposer with then automatically run the file through a preprocessor to produce a processed input file. Or,if running on the command line, you must first run the input file through the preprocessor to produce a processedinput file.
MPI Message Passing Interface. An application programming interface (API) for communicating between processesexecuting in parallel.
multi-grid pre-conditioner A pre-conditioner that enables a solver to use a hierarchy of grids to solve a partialdifferential equation problem. The multi-grid pre-conditioner applies the results from coarse grids to acceleratethe convergence on the finest grid.
parameter A parameter is a variable value (integer, floating-point number, or text string) that users define to create asimulation.
parse To divide input into parts and determine the meaning of each part.
physical domain See domain.
processed input file A PSim simulation file, which has a .in suffix. PSimComposer automatically does this for you.Users running on the command line must produce the processed input file by running an input file through apreprocessor prior to running.
Python An open-source, interpreted scripting language managed by the Python Software Foundation.
• |PolySwift++| © 2002-2013 University of Colorado and Tech-X Corporation. All rights reserved.
• |PolySwift++| © 1999-2002 University of Colorado. All rights reserved.
• |PolySwift++| © 2008-2013 Tech-X Corporation. All rights reserved.
• PSim™ © 2012-2013 Tech-X Corporation. All rights reserved.
For PSim™ licensing details please email [email protected]. All trademarks are the property of theirrespective owners. Redistribution of any PSim™ input files from the PSim™ installation or the PSim™document set, including the PSim Quick Start, PSim In Depth and PSim Reference, is allowed providedthat this copyright statement is also included with the redistribution.
50