File Name Conventions:

  Files named <name>.f  are Fortran 90 files
  Files named <name>.fp.f are Fortran 90 preprocessor input files.

  Preprocessor input files are simply Fortran 90 files that contain 
  blocks of code that is conditionally included and compiled only if 
  particular environment variables are defined.  These files are 
  converted by the build system into corresponding Fortran 90 files
  by applying a python preprocessor script that is distributed with the
  pscf source code.  There are only a few files that are treated in
  this manner, but the main program is among them. See the comment 
  at the end of this file for further discussion of the use of a 
  preprocessor.


Main Program:

pscf.fp.f
	Main program preprocessor input file. Used to generate the 
	compilable fortran file pscf.f, which is installed in the 
        build directory.

Utility Modules:

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

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

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

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

version_mod
        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.f
        Fortran 90 wrappers for FFTW Fourier transform functions, 
	for FFTW version 3 (Either this or fft2_mod.f is linked)

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

grid_mod.f
        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.f
	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.f
        Defines derived types and operations for space group 
	symmetries and space groups

space_groups_mod.f
	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.f
        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.f
	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.f
	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.f
	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.f
        Routines to integrate one time step of modified diffusion
	equation, using the Rasmussen-Kaloskas pseudo-spectral
	algorithm and extrapolation with respect to contour 
	length step size.

scf_mod.fp.f
	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.f is a preprocessor input file, which
	is used to generate file scf_mod.f in the build directory.

Iteration Modules:

iterate_mod.fp.f
	Iterates scf equations to convergence. Currently contains
	Newton-Raphson (NR) algorithm for both fixed and variable 
	unit cells. Note: File iterate_mod.fp.f is a preprocessor
	input file, which is used to generate file iterate_mod.f
        in the build directory.

sweep_mod
        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.f
        Calculate response of periodic structures in form needed to
        construct approximate Jacobian for quasi-Newton method in
        iterate_mod.f

Linear Response Modules:

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

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

extrapolate_mod.f
	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.f 
     src/iterate/iterate_mod.fp.f 
     src/scf/scf_mod.fp.f 

  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.f 
     build/iterate_mod.f 
     build/scf_mod.f 
  
  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 these files are installed in the 
  pscf/make directory. 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.f preprocessor files are modified, and the program 
  is then recompiled using either cmake or the make file in the 
  pscf/make directory, then the *.f fortran files will be regenerated
  regenerated as part of the build process. When compiled with make
  in the src/make directory, the src/make/*.f fortran files are also
  removed by the 'make clean' command.