Merge branch 'devel' of https://github.com/dmorse/pscf into devel

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+edit.py

.travis.yml

@@ -2,6 +2,11 @@ sudo: required
 dist: trusty
 language: fortran
 
+branches:
+ only:
+ - master
+ - devel
+
 matrix:
  include:
  - os: linux

CMakeLists.txt

@@ -136,18 +136,18 @@ set(CPACK_BINARY_DRAGNDROP ON)
 # This gives us a nice prompt to accept the license on OSX.
 set(CPACK_RESOURCE_FILE_LICENSE ${CMAKE_SOURCE_DIR}/LICENSE)
 
-#DONE: havent quite figured out how to include the README in the .app
-set(CPACK_RESOURCE_FILE_README ${CMAKE_SOURCE_DIR}/README)
-set(CPACK_RESOURCE_FILE_WELCOME ${CMAKE_SOURCE_DIR}/README)
-set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_SOURCE_DIR}/README)
+#DONE: havent quite figured out how to include the README.md in the .app
+set(CPACK_RESOURCE_FILE_README ${CMAKE_SOURCE_DIR}/README.md)
+set(CPACK_RESOURCE_FILE_WELCOME ${CMAKE_SOURCE_DIR}/README.md)
+set(CPACK_PACKAGE_DESCRIPTION_FILE ${CMAKE_SOURCE_DIR}/README.md)
 
 if (APPLE AND BUILD_DMG)
 # Force the README up to the DMG root
-INSTALL(FILES ${CMAKE_SOURCE_DIR}/README DESTINATION ../../../Extra RENAME README.txt)
+INSTALL(FILES ${CMAKE_SOURCE_DIR}/README.md DESTINATION ../../../Extra RENAME README.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION ../../../Extra RENAME LICENSE.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/tools/bundle/HOWTO_INSTALL_OSX.txt DESTINATION ../../../. RENAME HOWTO_INSTALL_OSX.txt)
 else (APPLE AND BUILD_DMG)
-INSTALL(FILES ${CMAKE_SOURCE_DIR}/README DESTINATION share/pscf RENAME README.txt)
+INSTALL(FILES ${CMAKE_SOURCE_DIR}/README.md DESTINATION share/pscf RENAME README.txt)
 INSTALL(FILES ${CMAKE_SOURCE_DIR}/LICENSE DESTINATION share/pscf RENAME LICENSE.txt)
 endif (APPLE AND BUILD_DMG)
 

README.md

@@ -1,54 +1,74 @@
 # PSCF - Polymer Self-Consistent Field Theory
 
-[![Travis][buildstatus_image_travis]][travisci]
-
-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 for periodic microstructures formed
-by incompressible melts or mixtures of linear block copolymers,
-linear homopolymers, and small molecule solvents.
+self-consistent field theory (SCFT) for spatially periodic structures 
+formed by block copolymer melts and mixtures of block copolymers with
+linear homopolymers and/or small molecule solvents.
 
 This program is free software; you can redistribute it and/or modify
 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
- LAPACK linear algebra library. These packages must be installed
- before attempting to compile the program from source.
+PSCF depends upon the FFTW fast Fourier transform library and the
+LAPACK linear algebra library. These packages must be installed
+before attempting to compile the program from source.
 
 # User Documentation
 
-A web user manual is avalaible at:
-
- https://pscf.readthedocs.io
+A web user manual is available at https://pscf.readthedocs.io
 
 Instructions for compiling the program from source, as well as various
 ways to install precompiled executables, are given in the user manual.
 
 The source files for the user manual are text files that are stored in
 the doc/user-man directory. The relevant files have file extension .rst.
 
+We also recommend that users refer to the 2016 reference article from the 
+journal Macromolecules, cited below. This article provides a brief introduction 
+to SCFT, discusses some of the algorithms and file formats used in the PSCF 
+program, and discusses some issues and questions faced by first time users.
+
 # Developer Documentation
 
 A local copy of the developer API documentation, which includes
 documentation for all modules, subroutines and public variables, may
 be regenerated by following instructions given in the file doc/README.
-The resulting .html page are installed in doc/devel-man.
+The resulting html pages are installed in the doc/devel-man directory.
+
+# Reference Article 
+
+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)
+
+available electronically at https://pubs.acs.org/doi/10.1021/acs.macromol.6b00107
+
+# Examples
 
-# Directory Structure
+A library of examples is provided in a separate github repository,
+located at https://github.com/dmorse/pscf-examples
+
+# Links
+
+ - Home Page: https://morse.cems.umn.edu/morse/code/pscf/home.php.html
+ - Source Code: https://github.com/dmorse/pscf
+ - CI Server: https://travis-ci.org/dmorse/pscf
+ - Manual: https://pscf.readthedocs.io
+
+[buildstatus_image_travis]: https://travis-ci.org/dmorse/pscf.svg?branch=master
+[travisci]: https://travis-ci.org/dmorse/pscf
+
+[![Travis][buildstatus_image_travis]][travisci]
+
+# Repository Directory Structure
 
  src/ - Fortran 90 source files
  doc/ - documentation files
@@ -62,11 +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.
 
-# Examples
-
-A library of examples is provided in a separate github repository,
-located at https://github.com/dmorse/pscf-examples
+# Contributors
 
+- David Morse
+- Chris Tyler
+- Jian Qin
+- Amit Ranjan
+- Raghuram Thiagarajan
+- Akash Arora
 
-[buildstatus_image_travis]: https://travis-ci.org/Gjacquenot/pscf.svg?branch=master
-[travisci]: https://travis-ci.org/Gjacquenot/pscf

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: