Editing user guide.

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/param.rst

@@ -5,16 +5,17 @@
 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. 
+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
-name of each variable appears on a line by itself, followed by the value 
-or (for arrays) values on one more subsequent lines. The variables within
-each section must appear in a predetermined (i.e., hard-coded) order. 
+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'.
 
@@ -156,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**
 
@@ -182,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
  ============================== ===============================================
 
@@ -226,7 +234,7 @@ 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 of reference volume is implicit in the values 
-given for other quantities. Changes in ones choice of reference volume lead 
+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. 
@@ -588,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 
@@ -773,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
@@ -808,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