========================================================================
Source File Name Conventions:

  Files named <base>_mod.f90  are Fortran 90 module source files
  Files named <name>.fp.f90   are preprocessor input files.

  The un-preprocessed version of the main program is src/pscf.fp.f90.
  A corresponding compilable fortran program is generated by applying
  a preprocessor script, which installs the resulting program in the
  build directory. See the end of this file for a discussion of the
  use of a preprocessor.

========================================================================
Source Files:

pscf.fp.f90
	Main program (preprocessor input file). Used to create a
	compilable fortran file pscf.f90 in the build directory.

Utility Modules:
----------------

const_mod.f90
	Defines global variable dim (= # dimensions of space) and
	parameter long (=real kind for double precision). Used by
	all other modules.

io_mod.f90
        Defines generic interfaces for parameter input and output.

field_io_mod.f90
        Routines to input and output fields, as lists of coefficients
	of symmetry-adapted basis functions.

string_mod.f90
	Utilities to convert integers to strings. Used in io formats.

version_mod.f90
        Defines a version_type derived type, with major and minor
	integer version numbers, and routines to read and write this.
	Version numbers are used to specify file format versions.

FFT grid Modules:
----------------

fft3_mod.f90
        Fortran 90 wrappers for FFTW Fourier transform functions,
	for FFTW version 3 (Either this or fft2_mod.f90 is linked)

fft2_mod.f90
        Fortran 90 wrappers for FFTW Fourier transform functions,
	for FFTW version 2 (Either this or fft3_mod.f90 is linked)

grid_mod.f90
        Defines scf data structures on an FFT grid, and routines
	to allocate, deallocate, and manipulate these structures.
	Defines ngrid, rho_grid, omega_grid, and ksq_grid. Also
	contains several functions for manipulating single FFT
	wavevectors, including norm, G_to_fft and G_to_bz.

Crystallography Modules:
------------------------

unit_cell_mod.f90
	Creates Bravais and reciprocal basis vectors, using user
	supplied name of crystal system and cell parameters.  Defines
	data structures specifying cell parameters, Bravais and
	reciprocal lattice basis vectors, and some related quantities.

group_mod.f90
        Defines derived types and operations for space group
	symmetries and space groups

space_groups_mod.f90
	Routine space_groups creates space group specified by user
	by name or number, using look-up table of all 230 3D space
	groups, 17 2D plane groups, and 2 1D groups.

basis_mod.f90
        Module to construct basis functions for periodic crystal.
        Defines data structures describing reciprocal wavevectors and
	stars. Contains routines to generate reciprocal wavevectors,
	to group them into stars of wavevectors related by symmetry,
	and to calculate coefficients of plane waves in symmetry
	adapted basis functions.  A discussion of the data structures
	and conventions used in basis_mod is given within a long
	comment within basis_mod, which is reproduced in the
        developer/api documentation for the module.

grid_basis_mod.f90
	Contains routines to convert between representations of a
	field as a 1D array of coefficients of symmetry-adpated
	basis functions and as a set of values defined at points
	on a regular grid.

Self-consistent field modules:
------------------------------

chemistry_mod.f90
	Defines data structures required to specify chemistry of an
	incompressible polymer blend (chi, Kuhn lengths, block lengths,
	molecular volume fractions etc.), and routines to input and
	output this data.

chain_mod.f90
	Defines a derived type chain_type that contains the
	q(r,s) =qf and q^{+}(r,s) =qr functions for a chain, and
	information about discretization in r and s. Also defines
	arrays of chain_types and subroutines to allocate and
	destroy these arrays.

step_mod.f90
	Contains routines to solve diffusion equation by the
	pseudo-spectral method, and to calculate monomer
        concentration fields, the free and energy, and stress.
	Note: scf/scf_mod.fp.f90 is a preprocessor input file, which
	is used to generate file scf_mod.f90 in the build directory.

scf_mod.fp.f90
	Contains routines to solve diffusion equation by the
	pseudo-spectral method, and to calculate monomer
        concentration fields, the free and energy, and stress.
	Note: scf_mod.fp.f90 is a preprocessor input file, which
	is used to generate file scf_mod.f90 in the build directory.

chain_mod.f90
	Defines a derived type chain_type that contains the
	q(r,s) =qf and q^{+}(r,s) =qr functions for a chain, and
	information about discretization in r and s. Also defines
	arrays of chain_types and subroutines to allocate and
	destroy these arrays.

Iteration Modules:
------------------

iterate_mod.fp.f90
	Iterates scf equations to convergence.
        Note: iterate_mod.fp.f90 is a preprocessor input file, which
        is used to generate file iterate_mod.f90 in the build directory.

sweep_mod.f90
        Used to conduct a "sweep" along a path through the space
        of SCF input parameters (i.e., chi, block_lengths, etc).
        Implements 1st and 2nd order continuation of solutions
        along such a path.

respond_pd_mod.f90
        Calculate response of periodic structures in form needed to
        construct approximate Jacobian for quasi-Newton method in
        iterate_mod.f90

Linear Response Modules:
------------------------

response_mod.f90
	Module for calculating SCF linear response of period structure

response_step_mod.f90
	Routines to integrate inhomogeneous PDE required in the ideal
	gas perturbation theory

extrapolate_mod.f90
	Implements extrapolation with respect to contour length step
	size ds.

========================================================================
Preprocessor Usage

  Several fortran files are generated by applying a python
  preprocessor script named FORPEDO to corresponding preprocessor
  input files.  This script is included as part of the pscf package
  in a subdirectory of the tools/python directory.

  The relevant preprocesor input files are:

     src/pscf.fp.f90
     src/iterate_mod.fp.f90
     src/scf_mod.fp.f90

  These are fortran files that contain preprocessor directives that
  control conditional compilation of some sections of code. The
  FORPEDO preprocessor is used here in manner similar to the use
  of the standard C preprocessor to control conditional compilation
  in C and C++ programs. Preprocessing each of these files generates
  a Fortran file with the same name as the preprocessor input file
  without the ".fp." string. The resulting fortran files are thus 
  named:

     build/scf.f90
     build/iterate_mod.f90
     build/scf_mod.f90

  These preprocessed fortran files installed in the build directory
  from which make is invoked, rather than in the src/ directory. If
  pscf is built using the simple makefile that is provided in the
  pscf/make directory, then the build directory is the directory 
  pscf/make.  If pscf is built out-of-source using cmake, by invoking 
  cmake and make from a build directory outside the pscf/ directory 
  tree, then these fortran files will be installed in that build 
  directory tree.

  An external script is used for preprocessing because Fortran
  (unlike C) does not provide a standard preprocessor.  The use of
  a preprocessor makes it easier for developers to maintain code
  that contains experimental features that are not yet ready to be
  released as part of a stable version, without maintaining separate
  development and release version. Sections of code containing
  features that are not ready for prime time are surrounded by
  conditional compilation directives and are excluded from release
  versions of the corresponding fortran files.

  If the *.fp.f90 preprocessor files are modified, and the program
  is then recompiled using either cmake or the make file in the
  pscf/make directory, then the *.f90 fortran files will be automatically
  regenerated as part of the build process. When compiled with make in
  the make directory, the generated make/*.f90 fortran files are also
  removed by the 'make clean' command.