
File Name Conventions:

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

  The un-preprocessed version of the main program is src/pscf.fp.f. 
  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.

---------------------------------------------------------------------
! Directories and Files                                             !
---------------------------------------------------------------------

src/
----

pscf.fp.f
	Main program (preprocessor input file). Used to generate the 
	compilable fortran file pscf.f in the build directory.

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

src/io/
-------

io/io_mod
        Defines generic interfaces for parameter input and output.

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

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

io/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.

src/grid/
---------

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

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

grid/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.

src/crystal/
------------

crystal/unit_cell_mod
	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. 

crystal/group_mod
        Defines derived types and operations for space group 
	symmetries and space groups

crystal/space_groups_mod
	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. 

crystal/basis_mod
        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. 

crystal/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. 

src/scf/
--------

scf/chemistry_mod
	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. 

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

scf/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/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. 

src/iterate
------------

iterate/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.

iterate/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.

iterate/respond_pd_mod.f
        Calculate response of periodic structures in form needed to
        construct approximate Jacobian for iterate_mod.f

src/response/
-------------

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

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

response/extrapolate_mod.f
	Implements extrapolation with respect to contour length step 
	size ds. 

src/attic/
----------

        Random programs, tests and utilities that are not fit for
        public consumption. Please ignore.

---------------------------------------------------------------------
! 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.

