Merge branch 'master' into temp

README.md

@@ -1,6 +1,6 @@
 # PSCF - Polymer Self-Consistent Field Theory
 
-Copyright (2002-2016) Regents of the University of Minnesota
+Copyright (2002-2017) Regents of the University of Minnesota
 
 PSCF is a Fortran 90 program for numerically solving the polymer
 self-consistent field theory (SCFT) for spatially periodic structures 
@@ -12,15 +12,6 @@ it under the terms of the GNU General Public License as published by
 the Free Software Foundation. A copy of this license is included in
 the LICENSE file in the top-level PSCF directory.
 
-# Contributors
-
-- David Morse
-- Chris Tyler
-- Jian Qin
-- Amit Ranjan
-- Raghuram Thiagarajan
-- Akash Arora
-
 # Dependencies
 
 PSCF depends upon the FFTW fast Fourier transform library and the
@@ -56,7 +47,7 @@ If you use PSCF in published work, we request that you cite the paper:
 "Broadly Accessible Self-Consistent Field Theory for Block Copolymer
 Materials Discovery", A. Arora, J. Qin, D.C. Morse, K.T. Delaney,
 G.H. Fredrickson, F.S. Bates and K.D. Dorfman, 
-Macromolecules 49, 4675 (2016)
+*Macromolecules* **49**, 4675 (2016)
 
 available electronically at http:https://pubs.acs.org/doi/10.1021/acs.macromol.6b00107
 
@@ -91,3 +82,12 @@ An annotated list of source files is given in the file src/SRC_FILES.
 Before modifying any fortran files, see the note at the end of that
 file regarding the use of preprocessor to generate some files.
 
+# Contributors
+
+- David Morse
+- Chris Tyler
+- Jian Qin
+- Amit Ranjan
+- Raghuram Thiagarajan
+- Akash Arora
+

doc/user-man/binary.rst

@@ -70,11 +70,13 @@ files. To install from binary on Ubuntu:
 
  - libfftw3-3
  - liblapack3
+ - libatlas-base-dev
 
  To install these packages using apt-get, enter::
 
- sudo apt-get libfftw3-3
- sudo apt-get liblapack3
+ sudo apt-get install libfftw3-3
+ sudo apt-get install liblapack3
+ sudo 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>

doc/user-man/compile-make.rst

@@ -5,32 +5,32 @@ 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/ directory of the git 
+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 
-difference among different unix environments is the locations of the 
-required libraries. 
+differences among different unix environments are the locations of the 
+required libraries.
 
 To compile the code in this way, proceed as follows:
 
  * Follow the directions given in the discussion of 
- :ref:`install-compile-cmake-dependencies-sub` on the previoius 
+ :ref:`install-compile-cmake-dependencies-sub` on the previous 
  page. You will need to install all dependencies listed there
  except cmake.
 
  * Follow the directions given in the discussion of
  :ref:`install-compile-cmake-getsource-sub` on the previous page
  to create an appropriate directory structure and obtain the 
  source code. After this step, you should have a directory named
- pscf/ with a directory named git/ that contains the contents of
- the git repository. You do not need to create a subdirectory
- of pscf/ named cmake/ if you are not using cmake.
+ pscf/ 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 the working directory (cd) to the directory pscf/git/make .
+ * Change working directory (cd) to the directory pscf/git/make .
  Note that this is an existing subdirectory of the pscf/git 
  directory, and is different from the initially empty directory
- pscf/cmake from which we recommended that invoke cmake when using 
- cmake to compile.
+ pscf/cmake from which we recommended cmake 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 config.mk_r, by entering::
@@ -49,8 +49,8 @@ To compile the code in this way, proceed as follows:
  > make -j4 all
 
  from within pscf/git/make. The "-j4" option is not necessary, and
- simply installs make to try to use up to 4 CPU cores during
- compilation, if available.
+ simply instructs the make utility to try to use up 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::
@@ -66,9 +66,9 @@ Several of these steps are discussed in more detail below.
 **Editing the config.mk configfuration file**
 
 In the config.mk file in the src/make directory (which you should have
-created by copying config.mk_r), you will need to set values for several
-macro variables to values appropriate to your system. Makefile variables 
-you may need to reset are:
+created by making a copy of config.mk_r), you will need to set values for 
+several macro variables to values appropriate to your system. Makefile 
+variables you may need to reset are:
 
  ========= ========================================================
  F90 path to executable for Fortran 90 compiler

doc/user-man/field.rst

@@ -52,11 +52,11 @@ the field :math:`\omega_{\alpha}` as an expansion of the form
 .. math::
 
  \omega_{\alpha}(\textbf{r}) = 
- \sum_{i=1}^{\textrm{N\_star}} \omega_{i\alpha} f_{i}(\textbf{r})
+ \sum_{i=1}^{N_{star}} \omega_{i\alpha} f_{i}(\textbf{r})
 
 in which each function :math:`f_{i}(\textbf{r})` is a real basis 
 function, :math:`\omega_{i\alpha}` is an associated real coefficient, 
-and :math:`\textrm{N\_star}` is the number of basis functions used to
+and :math:`N_{star}` is the number of basis functions used to
 approximate the field. In a symmetry-adapted Fourier expansion of a 
 field with a specified space group symmetry, each basis function 
 :math:`f_{i}(\textbf{r})` is a real function that is invariant under 

doc/user-man/index.rst

@@ -3,8 +3,8 @@
  You can adapt this file completely to your liking, but it should at least
  contain the root `toctree` directive.
 
-Welcome to PSCF's documentation!
-================================
+PSCF User Manual
+================
 
 Contents:
 

doc/user-man/param.rst

@@ -5,16 +5,19 @@
 Parameter File
 **************
 
-The main program reads an parameter file containing the parameters and
-instructions for a calculation. This file is divided 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 block may contain values of a sequence of variables. The
-name of each variable appears on a line by itself, followed by the
-value or (for arrays) values on one more subsequent lines. The
-order in which variables must appear within a section is fixed. The
-program stops when it encounters the block title 'FINISH'.
+The main program reads a parameter file containing the parameters and
+instructions for a calculation. This file is divided 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 
+variables within each section must appear in a predetermined (i.e., hard-coded) 
+order. The name of each variable appears on a line by itself, followed by 
+either the variable value or, for array-valued variables, by a sequence of 
+values of the elements of the array on one more subsequent lines. 
+
+The program stops when it encounters the section title 'FINISH'.
 
 .. _example-sec:
 
@@ -28,16 +31,15 @@ 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 is divided into
-sections, each of which begins with a line containing a capitalized label,
-such as MONOMERS, CHAINS, ec. Each section begins with a capitalized 
-section identtifier (MONOMER, CHAINS, etc.) on a line by itself. A single
-line must is left blank between sections. The sections are processed in 
-the order in which the appear in the parameter file. The first few sections 
-in this example simply provide values for physical and computational 
-parameters. An ITERATE section instructs the program to actually perform 
-a SCF calculation, by iteratively solving the SCF equations. A SWEEP 
-section performs a sequence of such calculations along a line in parameter 
-space. Execution of the program stops when a FINISH line is encountered.
+sections. Each section begins with a capitalized section identtifier 
+(MONOMER, CHAINS, etc.) on a line by itself. A single blank line appears 
+between sections. The sections are processed in the order in which they 
+appear in the parameter file. The first few sections in this example 
+simply provide values for physical and computational parameters. An 
+ITERATE section instructs the program to actually perform a single SCF 
+calculation, by iteratively solving the SCF equations. A SWEEP section 
+performs a sequence of such calculations along a line in parameter space. 
+Execution of the program stops when a FINISH line is encountered.
 
 ::
 
@@ -155,22 +157,28 @@ parameter file section is given below in a discussion of :ref:`param-sections-se
  :ref:`param-finish-sub` Stop program
  =============================== ====================================================
 
+**Common Workflows**
+
 Several standard types of computation are possible using the blocks listed above:
 
- - Iterate: To solve solve SCF equations for a single state point, include
- all of the listed below sections except the SWEEP and RESPONSE sections.
+ - Iterate: To solve solve the SCF equations for a single state point, include
+ all of the sections above, in the order listed, except SWEEP and RESPONSE 
+ sections, which should not appear. Also exclude the SOLVENTS section if 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 both an ITERATE and SWEEP function, but not a RESPONSE
- section. The ITERATE section must precede the SWEEP section, and is used
- to obtain a solution for the initial choice of parameters.
+ space, include all of the sections listed above, in the order listed, except
+ the RESPONSE section. The ITERATE section must precede the SWEEP section, 
+ and is used to obtain a solution for the initial choice of parameters, which
+ is then used as a starting solution for the rest of the sweep.
 
- - Response: To compute the self-consistent-field or RPA linear susceptibility of a
- periodic microstructure, include ITERATE and RESPONSE sections, but do not include
- a SWEEP section.
+ - Response: To compute the self-consistent-field or RPA linear susceptibility 
+ of a periodic microstructure, include ITERATE and RESPONSE sections, but do 
+ not include a SWEEP section.
 
-The SOLVENTS section may be omitted for calculations on polymer melts, with no small 
-molecule solvent.
+The SOLVENTS section may always be omitted for calculations on systems that do 
+not contain any small molecule solvent.
 
 **Miscellaneous Utilities**
 
@@ -181,13 +189,14 @@ transformations on fields or parameters, or to output additional information.
  Section Description
  ============================== ===============================================
  :ref:`param-fieldtorgrid-sub` Read field file in symmetry-adapated format
- and output file in coordinate grid format
+ and output in coordinate grid format
  :ref:`param-rgridtofield-sub` Read field in coordinate grid file format
  and output in symmetry-adapated format
- :ref:`param-kgridtorgrid-sub` Read field in k-space and output in r-space
+ :ref:`param-kgridtorgrid-sub` Read field in k-space grid format and output 
+ in r-space coordinate grid format
  :ref:`param-rhotoomega-sub` Read rho field, compute and output omega field
  :ref:`param-rescale-sub` Redefine monomer reference volume 
- :ref:`param-waves-sub` Output map of waves to basis functions
+ :ref:`param-waves-sub` Output relationship of waves to basis functions
  :ref:`param-group-sub` Output all elements of space group
  ============================== ===============================================
 
@@ -212,20 +221,23 @@ or more of the statistical segment lengths is set to unity.
 SCFT also leaves the user some freedom to redefine what he or she means 
 by a "monomer", which need not correspond to a chemical repeat unit. The 
 choice of values of the parameters block_length, solvent_size, kuhn, and
- chi to represent a particular experimental system all depend on the choice 
-of a value for a monomer reference volume, which in turn defines an effective 
-monomer repeat unit. A monomer of a polymeric species defined to be a length 
-or molar mass of chain that occupies one monomer reference volume in the melt. 
-Each element of the variable block_length represents the number of "monomers" 
-in a block of a block copolymer, defined to be the ratio of the block volume 
-to the monomer reference volume. Similarly, the variable solvent_size is given 
-by ratio of the solvent volume to the reference volume. The values of the chi 
-parameters are proportional to the reference volume, while kuhn lengths are 
-proportional to the square root of the reference volume. 
+chi to represent a particular experimental system all depend on an implicit
+choice of a value for a monomer reference volume, which defines the mononmer 
+repeat unit that is being used for bookkeeping purposes. One "monomer" of a 
+polymeric species is defined to correspond to length or molar mass of chain 
+that occupies a volume in the melt equal to one reference volume, which may
+or may not correspond to a chemical repeat unit. Each element of the variable 
+block_length represents the number of "monomers" in a block of a block 
+copolymer, which is given by the ratio of the block volume to the monomer 
+reference volume. Similarly, the variable solvent_size is given by ratio 
+of the solvent volume to the reference volume. 
 
 Note that PSCF does not require the user to input a value for the monomer 
-reference volume - the choice is implicit in the values given for other
-quantities.
+reference volume - the choice of reference volume is implicit in the values 
+given for other quantities. Changes in one's choice of reference volume lead 
+to corresponding changes in the values for the chi parameters, which are
+proportional to the reference volume, and in the kuhn lengths, which are 
+proportional to the square root of the reference volume. 
 
 **Character Strings**
 
@@ -584,7 +596,7 @@ If "itr_algo" is "NR", PSCF uses a quasi-Newton-Raphson iteration
 algorithm that is unique to this program. This algorithm constructs 
 a physically motivated initial approximation for the Jacobian matrix
 in which elements associated with long wavelength components of the
-:\math:`\omega` field are computed numerically and shorter wavelength 
+:math:`\omega` field are computed numerically and shorter wavelength 
 components are estimated. After construction and inversion of this 
 initial estimate, Broyden updates of the inverse Jacobian are used to 
 refine the estimate of the inverse Jacobian. This method requires a 
@@ -769,7 +781,7 @@ the input variable "vref_scale".
  Variable Type Description
  ================ ============= ============================
  input_filename character(60) input omega file name
- vref_scale real scale factor
+ vref_scale real scale factor :math:`\lambda'
  ================ ============= ============================
 
 This command applies the following set of transformations to each
@@ -804,19 +816,20 @@ rescaled choice of parameter values. Using the RESCALE command to
 read in a file containing such a converged solution should thus 
 cause the subsequent ITERATE command to terminate immediately,
 since the error should be less than the numerical threshhold on 
-and output the new parameters to an output summary file and the 
-rescaled omega field to an output omega file. 
+input. This would cause the program to immediately output the 
+rescaled parameters to an output summary file and the rescaled 
+omega field to an output omega file. 
 
 .. _param-waves-sub:
 
 OUTPUT_WAVES
 ------------
 
-Output the relationship between plane waves and symmetry-adapted
-basis functions, by outputting a file containing showing which
-star each wavevector belongs to and the coefficients of the 
-plane-wave within a symmetry adapted basis function assocated 
-with that star.
+This command outputs a file that describes the relationship between
+complex exponential plane wave basis functions and symmetry-adapted
+basis functions. The resulting file lists which star each wavevector
+belongs to and the coefficient of the plane-wave within a symmetry 
+adapted basis function assocated with that star.
 
  ================ ============= ============================
  Variable Type Description

src/io_mod.f

@@ -356,15 +356,15 @@ module io_mod
  character(1) :: default_mat_sym = 'N' ! normal (full matrix)
 
  ! Integer field widths for output of comments and data:
- integer :: com_width = 20 ! comment field width
+ integer :: com_width = 40 ! comment field width
  integer :: data_width = 20 ! data field width (total)
  integer :: frac_width = 12 ! # digits after decimal
 
  ! Choice of format descriptor (E or F) for real numbers
  character(2) :: fmt_ef = 'ES' ! must = F, E, or ES
 
  ! Output format strings for scalar variables:
- character(3) :: fmt_c = 'A20' ! comment format
+ character(3) :: fmt_c = 'A40' ! comment format
  character(3) :: fmt_i = 'I20' ! integer format
  character(7) :: fmt_r = 'ES20.10' ! real format
  character(3) :: fmt_l = 'L20' ! logical format