[File: Application_Include_File.txt] 9/19/99

             Application Dependent Source Include Files
             (Except for Existing Example Applications)

Each application must have some source files that define its specific
tasks.  They are usually brought into the code by an INCLUDE statement
which gives the name of the file with the lines of source code.
Any un-needed source file option would simply include a comment line.
Default dummy versions of these typical files are in the directory
Dummy_inc with the name *_inc.dum.  The  actual INCLUDE statements
all occur  in the file application_lib.f.  At least one (my_el_sq_inc)
must be supplied since every application must, as a minmum, must define
an element square matrix.  Usually the error estimator is used and it
requires two other include files (my_b_matrix_inc & my_e_matrix_inc) 
which are usually also used in defining the square matrix.

   Definining the element square matrix is always required and this
is done in subroutine ELEM_SQ_MATRIX by means of the include file
'my_el_sq_inc'.  The typical definition of the square matrix usually
involves the triple matrix product: transpose (B) * E * B, so we
often need source code for the "b matrix" and "e matrix".  They are
also often used in post processing, and in the error estimator.  Thus,
their user supplied definitions can be accessed by calls to the
optional function GET_APPLICATION_B_MATRIX that has include 
'my_b_matrix_inc', and/or function GET_APPLICATION_E_MATRIX that has 
include 'my_e_matrix_inc'.  Related optional utilities include the
function COPY_DGH_INTO_B_MATRIX, that simply copies the physical
gradient for Poisson problems.  In other words the "b matrix" is often
just the gradient of the soluition interpolation functions, and the 
"e matrix" is often an identity matrix.

  Those common source lines to be placed in the include files are
often in available libraries. For example elasticity_lib.f contains 
subroutines for: B_MATRIX_AXISYM_ELASTIC, B_MATRIX_BAR_ELASTIC,
B_MATRIX_ELASTIC, B_MATRIX_PLANE_ELASTIC, and B_MATRIX_3D_ELASTIC
which could be called in the 'my_b_matrix_inc' file, and subroutines
PLANE_STRESS_E_MATRIX, and PLANE_STRAIN_E_MATRIX that could be called 
in file 'my_e_matrix_inc'.  Likewise, the file math_lib.f contains
the function GET_REAL_IDENTITY which can be used for Laplace problems
in file 'my_e_matrix_inc'.

Include file:			Appears in:
'my_el_sq_inc'			SUBROUTINE ELEM_SQ_MATRIX
'my_el_col_inc'			SUBROUTINE ELEM_COL_MATRIX
'my_el_post_inc'		SUBROUTINE ELEM_POST_DATA
'my_post_el_inc'		SUBROUTINE POST_PROCESS_ELEM
'my_flux_inc'			SUBROUTINE BOUNDARY_FLUX
'my_iter_start_inc'		FUNCTION   START_DOF_VALUE
'my_b_matrix_inc'		FUNCTION   GET_APPLICATION_B_MATRIX
				SUBROUTINE APPLICATION_B_MATRIX
'my_e_matrix_inc'		FUNCTION   GET_APPLICATION_E_MATRIX
				SUBROUTINE APPLICATION_E_MATRIX

If one also envokes the superconvergent patch average flux for error
estimation, which is now the default, then file 'my_b_matrix_inc' is 
always used (by GET_APPLICATION_B_MATRIX in SCP_ERROR_ESTIMATES), along
with the E_matrix (by GET_APPLICATION_E_MATRIX in SCP_ERROR_ESTIMATES),
unless spatially varying properties exist, then the rarely used file
'my_variable_e_matrix_inc' is probably used (by GET_E_AT_QP within
SCP_ERROR_ESTIMATES).

[End File: Application_Include_File.txt] 9/19/99, 1/9/01