Editing .rst docs. Adding discussion of symmetry and OUTPUT_GROUP.

doc/user-man/compile-cmake.rst

@@ -397,6 +397,8 @@ operating system to find the pscf program when it is invoked from the
 command line by name, and to allow the python interpreter to find some
 associated python modules that are useful for data analysis. 
 
+**Changing Paths**
+
 The simplest way to make the required changes to your user environment
 is to cd to bin/ subdirectory of the root install directory and, from
 there, enter::
@@ -415,18 +417,22 @@ enter the commands::
 where "install" denotes an absolute path to your chosen installation
 directory.
 
+**Making it Permanent**
+
 The above procedures (running pscf-env script or manually setting the
 relevant environment variables) only modifies the $PATH and $PYTHONPATH
-variables temporarily, until you log out (on Linux) or until you close
-the terminal window (on a Mac). To have the appropriate directories
-added to these variables automatically whenever you log in or open a
-terminal, simply add the command::
+variables temporarily, until you close the terminal window or log out.
+To have the appropriate directories added to these environment variables 
+automatically whenever you log in or open a terminal, simply add the 
+command::
 
  source install/bin/pscf-env 
 
-to the .bashrc configuration file in your home directory. Here, the
-string "install/" is a placeholder for the absolute path to the pscf 
-install directory.
+to the .bashrc file or (on Mac OS X) .profile configurtion file
+in your home directory. Here, the string "install/" is a placeholder 
+for the absolute path to the pscf install directory.
+
+**Configuration files: Linux vs. Mac OS X**
 
 On linux, after a user logs in, the operating system looks for a file 
 in the user directory named .profile or .bash_profile (in that order)
@@ -444,11 +450,14 @@ by the .profile or .bash_profile file, by a command such as::
 
 This part of the .profile or .bash_profile file checks if there is 
 a .bashrc file in the users home directory and, if one is found, 
-executes that file. 
+executes that file. With this configuration, commands that set up
+environment variables should be added to the .bashrc file.
 
-On Mac OS X, the Mac Terminal program actually executes the .profile
+On Mac OS X, the Mac Terminal program instead executes the .profile
 script whenever you open a terminal, rather than using different 
-files for login and non-login terminals, and thus does not ever 
-directly execute the .bashrc file. On a Mac, one can thus either use 
-the procedure described above, or simply place all commands that
-customize the user environment into the .profile. script.
+files for login and non-login terminals. The Mac Terminal program 
+thus thus does not ever directly execute the .bashrc file. A Mac 
+user that always uses the Mac Terminal program could thus either 
+use the procedure described above (which would still work correctly), 
+or simply place all commands that customize the user environment 
+into the .profile script.

doc/user-man/compile-make.rst

@@ -12,25 +12,30 @@ unix environments is the locations of the required libraries.
 
 To compile the code in this way, proceed as follows:
 
- * Change the working directory (cd) to the pscf/git/make directory
- (i.e., to make/ subdirectory of the directory tree containing the
- pscf git repository).
+ * Change the working directory (cd) to the pscf/git/make directory.
+ Note that this is a subdirectory of the pscf/git directory that
+ contains the git repository, and is different from the initially
+ empty pscf/cmake directory used to compile using cmake/.
 
- * Make a copy named config.mk of the file config.mk_r, by entering::
+ * This directory should contain files named config.mk_r and Makefile.
+ Make a copy named config.mk of the file config.mk_r, by entering::
 
  cd config.mk_r config.mk
 
- * Examine and edit the config.mk file to reflect your environment, 
- and to choose an installation directory (see below).
+ * Examine and edit the new config.mk file to reflect your environment, 
+ and to choose an installation directory. The need to manually edit 
+ this configuration file is the main difference between using cmake 
+ to and using make alone. See below for further instructions about
+ this step.
 
  * To compile, enter::
 
  > make -j4 all
 
  from within pscf/git/make.
 
- * To install in the location specified by the $(INSTALL) makefile 
- variable (defined in config.mk), enter::
+ * To install in the directory specified by the $(INSTALL) makefile 
+ variable (as defined in config.mk), enter::
 
  > make install
 
@@ -42,8 +47,8 @@ Some 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 must create by 
-copying config.mk_r), you will need to set values for a set of macro 
+In the config.mk file in the src/make directory (which you must create 
+by copying config.mk_r), you will need to set values for a set of macro 
 variables to values appropriate to your system. Makefile variables you 
 may need to reset are:
 
@@ -61,12 +66,16 @@ The INSTALL makefile variable in this makefile is equivalent to the
 MAKE_INSTALL_PREFIX variable that can be passed to cmake when compiling
 using cmake.
 
-The default config.mk file contains values appropriate for a number of 
-different common environments, most of which are commented out. It also
-contains some comments about appropriate choices for common environments. 
-Modify your copy of config.mk as needed, but make sure you give exactly 
-one uncommented definition for each variable, and comment out any unused 
-definitions.
+The file config.mk_r is a default makefile that is stored in the 
+repository. We require you to make an operational copy of this, named 
+config.mk, so that you can modify your config.mk file as needed without 
+changing the default copy. The config.mk_r file contains values for
+Makefile variables appropriate for a several different common operating
+system environments, most of which are commented out. It also contains 
+some comments about appropriate choices for specific environments. 
+Modify your copy of config.mk as needed, but avoid modifying config.mk_r,
+and make sure you give exactly one uncommented definition for each 
+variable in the config.mk file, and comment out any unused definitions.
 
 **Compile and Link**
 

doc/user-man/examples.rst

@@ -28,19 +28,27 @@ To download a zip file:
 
  * Point your browser at the pscf-examples github repository.
 
- * Click the "Download ZIP" button near the upper right corner 
- of that web page. 
+ * Click the "Download ZIP" button near the upper right corner of 
+ that web page. This will download the zip file, usually into
+ your "Downloads" directory and (in some environments), may
+ unzip the file to create a directory. 
 
- * Move the pscf-examples-master/ directory into your pscf/ directory,
- which should also contain a subdirectory that holds the repository 
- containing the source code.
+ * If you installed using a binary package, rather than installing
+ from source, create a directory named pscf/ somewhere in your
+ user directory. If you installed from source, this directory
+ should already exist.
+
+ * Move the pscf-examples-master/ directory into your pscf/ directory.
 
  * Rename the resulting directory pscf/pscf-examples-master/ to 
  pscf/examples.
 
 To clone the repository of examples, if git is installed on your machine:
 
- * Change directory to the parent pscf/ directory.
+ * If you installed using a binary package, create a directory 
+ named pscf/, as discussed above. 
+
+ * Change directory (cd) to your pscf/ directory.
 
  * Clone the pscf-examples repository, by entering::
 
@@ -49,14 +57,20 @@ To clone the repository of examples, if git is installed on your machine:
  * Change the name (i.e., mv) the pscf/pscf-examples directory to 
  pscf/examples/
 
-Either method should give you a pscf/ directory with the structure::
+Either method should give you a pscf/ directory with a subdirectory
+named examples. If you installed from source, you should have a pscf
+directory with the structure::
 
  pscf/
  git/
  examples/
 
 in which the pscf/git/ subdirectory contains the source code and the 
-pscf/examples/ directory contains the examples.
+pscf/examples/ directory contains input files for examples. If you 
+followed the instructions to compile using cmake, the pscf/ directory 
+will also contain subdirectory named cmake/. If you compiled from 
+source and also installed the code in your pscf/ directory, pscf/ will 
+also contain subdirectories named bin/, lib/ and share/.
 
 The structure and contents of the examples directory is explained in 
 the README file within that directory.

doc/user-man/field.rst

@@ -392,7 +392,7 @@ input_field_grid as a fortran loop of the form::
  do n3 = 0, ngrid(3) - 1
  do n2 = 0, ngrid(2) - 1
  do n1 = 0, ngrid(1) - 1
- [Read or write data at grid point (n1, n2, n3)]
+ [Read or write data at grid point r(n1, n2, n3)]
  enddo
  enddo
  enddo

doc/user-man/groups.rst

@@ -9,10 +9,17 @@ The symbol for a space group may be entered as the value of "space_group" in
 the BASIS section of the parameter file. The tables below list the allowed 
 space group symbols. 
 
-===============
 1D Space Groups
 ===============
 
+The only possible nontrivial symmetry for a one-dimensional lamellar 
+phase is inversion symmetry. There are thus only two possible groups: 
+The centrosymmetric group (group -1) and the non-centrosymmetric group
+(group 1). Fields for a centrosymmetric lamellar phase are expanded
+using a basis of cosine waves, while fields for a non-centrosymmetric 
+phase are expanded using a basis that contains both cosines and 
+sine waves.
+
 ======== ====== =================
 Number Symbol Comments
 ======== ====== =================
@@ -21,14 +28,14 @@ Number Symbol Comments
 ======== ====== =================
 
 
-===============
 2D Space Groups
 ===============
 
-The names of all 17 possible 2D plane groups are given below in the text format expected
-by PSCF. The format used in PSCF for both 2D and 3D space group names is based on the 
-names used in the international tables of crystallography, but allows space group names 
-to be written as simple ascii text strings.
+The names of all 17 possible 2D plane groups are given below in the text format 
+expected by PSCF. The format used in PSCF for both 2D and 3D space group names 
+is based on the names used in the international tables of crystallography, but 
+allows space group names to be written as simple ascii text strings, which
+contain spaces between elements of the space group name.
 
  ====== ======== ==============
  Number Symbol Lattice System
@@ -52,17 +59,43 @@ to be written as simple ascii text strings.
  17 p 6 m m hexagonal
  ====== ======== ==============
 
-===============
 3D Space Groups
 ===============
 
-The names of all possible 3D space groups are given below in the text format expected
-by PSCF. This format is based on the naming conventions used in the international 
-tables of crystallography, but allows space group names to be written as simple
-ascii text strings, with no special symbols or subscripts. In this format, a space is 
-ntroduced between different elements of the space group name, and overbars are indicated 
-by a "-" sign before the overbarred symbol. Thus for example, the space group of the
-gyroid phase (space group 230) is written in this format as "I a -3 d"
+The names of all possible 3D space groups are given below in the text format 
+expected by PSCF. These names are based on the names given in Hermann-Mauguin
+or "international" notation used the international tables of crystallography, 
+but are given in a format that allows space group names to be written as simple 
+ascii text strings, with no special symbols or subscripts. In this format, for
+example, the space group :math:`Ia\overline{3}d: of the gyroid phase (space 
+group 230) is written as "I a -3 d". 
+
+The following rules are applied to convert Hermann-Mauguin symbols into text 
+strings:
+
+ * A single space is introduced between different elements of the space 
+ group name, with a few exceptions described below. 
+
+ * Integers with overbars in the Hermann-Mauguin symbol, which indicate
+ inversion (:math:`\overline{1}`) or a 3-, 4- or 6-fold rotoinversion 
+ axis (:math:`\overline{3}`, :math:`\overline{4}`, or :math:`\overline{6}`), 
+ are indicated in the PSCF text string by placing a "-" sign before 
+ the overbarred integer. Thus for, example, "-3" represents the symbol
+ :math:`\overline{3}` in the text space group name "I a -3 d"
+
+ * Integers with subscripts, such as :math:`4_2`, which indicate screw 
+ axes, are indicated in the text representation by placing the two 
+ integers directly adjacent, with no intervening white space. Thus, 
+ for example, :math:`4_2` is replaced by "42".
+
+ * Symbols that are separated by a slash appear with no space on either 
+ side of the slash. 
+
+ * Different "settings" of the same space group, which correspond to 
+ different definitions of the origin of space in the definition of
+ the symmetry elements, are indicated by a colon followed by an 
+ integer label at the end of the space group. 
+
 
  ======== =================
  Number Symbol 
@@ -89,7 +122,7 @@ gyroid phase (space group 230) is written in this format as "I a -3 d"
  20 C 2 2 21 
  21 C 2 2 2 
  22 F 2 2 2 
- 23 I 2 2 2 
+ 23 I 2 2 2
  24 I 21 21 21 
  25 P m m 2 
  26 P m c 21 
@@ -330,3 +363,80 @@ gyroid phase (space group 230) is written in this format as "I a -3 d"
  230 I a -3 d 
  ======== =================
 
+Symmetry Elements
+=================
+
+A list of all of the symmetry elements of any space group can be output to file by placing a "OUTPUT_GROUP" command in the parameter file at any point after the "BASIS" section.
+
+Every space group symmetry can be expressed mathematically as an operation
+
+.. math::
+
+ \textbf{r} \rightarrow \textbf{A}\textbf{r} 
+ + \textbf{t}
+
+Here, :math:`\textbf{r} = [r_{1}, \ldots, r_{D}]^{T}` is a dimensionless 
+D-element column vector containing the components of a position within 
+the unit cell in a basis of Bravais lattice vectors, :math:`\textbf{A}` 
+is a :math:`D \times D` matrix that represents a point group symmetry 
+operation (e.g., identity, inversion, rotation about an axis, or 
+reflection through a plane), and :math:`\textbf{t}` is a dimenionless
+D-element colummn vector that (if not zero) represents a translation 
+by a fraction of a unit cell. Every group contains an identity element in 
+which :math:`\textbf{A}` is the identity matrix and :math:`\textbf{t}=0`. 
+
+The elements of the column vectors :math:`\textbf{r}` and :math:`\textbf{t}` 
+in the above are dimensionless components defined using a basis of Bravais 
+basis vectors. The position :math:`\textbf{r} = [1/2, 1/2, 1/2]^{T}` thus
+always represents the center of a 3D unit cell. The Cartesian representation 
+of a position vector is instead given by a sum
+
+.. math::
+
+ \sum_{i=1}^{D} r_{i}\textbf{a}_{i}
+
+
+in which :math:`\textbf{a}_{i}` is the Cartesian representation of 
+Bravais lattice vector number i. The elements of the dimensionless 
+translation vector :math:`\textbf{t}` are always either zero or 
+simple fractions such as 1/2, 1/4, or 1/3. For example, a symmetry 
+element in a 3D BCC lattice in which :math:`\textbf{a}` is the identity 
+matrix and :math:`\textbf{t} = [1/2, 1/2, 1/2]^{T}` represents the 
+body-centering translational symmetry that relates the two equivalent 
+positions per cubic unit cell in a BCC lattice. Similarly, a glide plane 
+in a 3D crystal represented by a diagonal matrix that represents inversion 
+through a plane and a translation vector that represents translation 
+by half a unit cell within that plane.
+
+The OUTPUT_GROUPS command outputs a list of symmetry elements in 
+which each element is displayed by showing the elements of the 
+matrix :math:`\textbf{A}` followed by elements of the associated 
+column vector :math:`\textbf{t}`.
+
+The Bravais lattice vectors used internally by PSCF for cubic, tetragonal, 
+and orthorhombic 3D systems are orthogonal basis vectors for the simple 
+cubic, tetragonal, or orthorhombic unit cells, which are aligned along 
+the x, y, and z axes of a Cartesian coordinate system. Similarly, the 
+basis vectors used for the 2D square and rectangular space groups are 
+orthogonal vectors which form a basis for a cubic or rectangular
+unit cell. The grid used to solve the modified diffusion equation is
+based on the same choice of unit cell and, thus for example, uses a
+regular grid within a cubic unit cell to represent fields in a BCC or 
+FCC lattice. For body-centered and space-centered lattice systems, 
+it is worth nothing that this unit cell not a primitive (minimum 
+size) unit cell of the crystal: For example, a cubic unit cell actually 
+contains 2 equivalent primitive unit cells of a BCC lattice or 4 
+primitive cells of an FCC lattice. 
+
+One consequence of the fact that PSCF does not always use a primitive 
+unit cell is that, in the Fourier expansion of the omega and rho fields,
+the Fourier coefficients associated with some sets of symmetry-related 
+wavevectors (some "stars") are required to vanish in order to satisfy 
+the requirement that the field be invariant under all elements of the 
+specified space group. The rules regarding which stars must have 
+vanishing Fourier coefficients are the same as the rules for systematic 
+cancellations of Bragg reflections in X-ray or neutron scattering from 
+a crystal of the specified space group. The procedure used by PSCF to 
+construct symmetry adapted basis functions automatially identifies and 
+accounts for these systematic cancellations.
+

doc/user-man/package.rst

@@ -71,7 +71,7 @@ information (Metadata, Dependencies, and File Contents), enter::
 
  > rpm --info -qpR -qlvp pscf-1.0.0-Linux.rpm 
 
-On a system that uses .deb file, to check the .deb file for 
+On a system that uses .deb package files, to check the .deb file for 
 semi-detailed information, enter::
 
  # This extracts multiple files