 __________________________________________________________________
|                                                                  |
|                           README FILE                            |
|                           -----------                            |
|                                                                  |
|             Natural Element Method for 2D Elastostatics          |
|             ===========================================          |
|                          [Fortran Code]                          |
|                                                                  |
|                            N. Sukumar                            |
|       	   Theoretical & Applied Mechanics                 |
|                      Northwestern University                     |
|                         Evanston, IL 60208                       |
|                          Dated: May 1998                         |
|__________________________________________________________________|

I. Installation
---------------

Unpack the gzipped tar archive for the NEM program using the UNIX command:

  tar -xvzf nem2d.tar.gz ["z" flag is for "gunzip before untarring"]

The archive consists of:

o Fortran files (suffix .F) in directory nem_code

o Library files (suffix .a) in directory nem_code/lib

o Header files (suffix .h) in directory nem_code/include

o Source code for input C functions in directory nem_code/input_src

o Sample input files (suffix .dat) in directory nem_code/inputs

o Sample data file for plotting (suffix .dat) in directory nem_code/plot

o Script file (script_nem) in directory nem_code

o UNIX Makefile (Makefile) in directory nem_code

o README.nem (this file) in directory nem_code


II. Overview
------------

o Fortran Files: Fortran files are created with the suffix .F. 
  Standard HP-UX Fortran77 language is used with the notable 
  inclusion of macro definition statements (#define). The Fortran77
  linker fort77 is used so that the Fortran files are 
  processed by the C pre-processor which recognizes the macro 
  definitions.  See the online man pages for fort77 and f77 for 
  further details. 

o Library Files: Standard library files for BLAS (blas.a) and 
  LAPACK (lapack.a) for HP9000/s700 (HPUX-9.05) are included.
  Appropriate library files for other UNIX systems would have 
  to be used when compiling/linking. The input functions for the
  NEM code are written in ANSI C. The object files for
  the same are included in the library file libneminput2d.a.
  See the call to the input subroutine input_data() in nem.F.

o Source Code for Input C functions: The C source code for the
  input functions are in the directory nem_code/input_src for
  reference purposes. 

o Header Files: Header files for parameter declaration and 
  settings, declaration of variables and common blocks.

o Input Files: Sample input files for two boundary-value problems
  in elastostatics are included: displacement patch test and
  the plate with a hole problem. The input files for the patch
  test are in the directory nem_code/inputs/patch while those
  for the plate with a hole problem are in the directory
  nem_code/inputs/hole. The input file is assumed to be ``input.dat''.
  Please copy the appropriate input file to a file named ``input.dat''
  before running the NEM executable. The nodal discretizations for the
  above two problems are indicated and discussed in the NEM paper
  (see the NEM web page indicated in section IV of this file).
  The package TRIANGLE (http://www.cs.cmu.edu/~quake/triangle.html)
  was used to create the nodal discretizations.

o Plot file: Sample data file to plot the stresses between two
  points (x1,y1) and (x2,y2) for the plate with a hole problem
  ---see subroutine output2d.F. Note that the shape function
  algorithm fails if any data point is located on the edge of a
  Delaunay triangle. Hence, appropriate choice of starting point,
  end point, and number of sub-divisions must be made. See the
  NEM paper indicated in section IV of this file for details
  on the shape function algorithm and its implementation.

o UNIX Makefile: Makefile to compile and link the Fortran routines

o Script File: The Bourne shell script file ``script_nem'' consists 
  of the Fortran linker (with options) to compile and link 
  the NEM code. This would suffice in order to test and execute 
  the sample input files. If a two-dimensional NEM application is 
  undertaken, for ease of code development and maintenance, a
  Makefile (such as the sample one provided) should be used.

III. Compiling and Execution
----------------------------

1. Make changes in the Makefile as per the configuration of your
   machine and then run `make' to create the executable.

2. If you'd like to use the script file, do `chmod +x script_nem' if the
   script file ``script_nem'' does not have executable permission. On
   the command line, the Bourne shell script file ``script_nem'' is run
   to create the Fortran-executable ``nem2d'' for the NEM program.
   The command syntax with options in the script file is:

fort77 -o nem2d {-DPLATE_HOLE || -DPATCH} [-DFE] [-DQUAD=25]
*.F lib/libneminput2d.a lib/lapack.a lib/blas.a +U77

where the options in the square brackets [ ] are optional,
the options within the curly braces { } MUST be defined, || 
denotes the logical .OR. operation, and valid values for
the macro QUAD are 1, 3, 6, 13, and 25. The macro definition
QUAD is used to indicate the number of quadrature points to be 
used in the post-processing (error norm computations). The
option +U77 in the above statement is used to invoke the BSD 3F
library [dtime() timing function is used in nem.F].  For example,
for the patch test with NEM using 13 point quadrature in each triangle
for the error norm computations, one would modify the above command
to read:

fort77 -o nem2d -DPATCH -DQUAD=13 *.F lib/libneminput2d.a lib/lapack.a 
lib/blas.a +U77

while for the plate with a hole problem using finite elements (FEM)
with the default quadrature (indicated in ``input.dat'') for the
post-processing, the command would read:

fort77 -o fe2d -DPLATE_HOLE *.F lib/libneminput2d.a lib/lapack.a 
lib/blas.a +U77

In order to run the program, execute ``nem2d'' or ``fe2d'' on
the command line to run the NEM (patch test) or the FE (plate 
with a hole) problems, respectively.

IV. NEM Web Page and More Information
=====================================

The NEM web page at http://dilbert.engr.ucdavis.edu/~suku/nem, created
and maintained by the author, contains links to papers on NEM, other
related computational geometric links, as well as a short overview
of the Natural Element Method. The NEM paper that accompanies this code
can be found at:
http://dilbert.engr.ucdavis.edu/~suku/nem/papers/nem_statics.ps.gz
---this paper would be a useful aid to understand and closely follow the
Fortran routines as well as many of the subtleties of NEM. 

V. Contact
==========

The NEM code, which is in the public-domain, can be downloaded off the
web site http://dilbert.engr.ucdavis.edu/~suku/nem/thesis/nem2d.tar.gz. 
Any and all feedback to me via e-mail (nsukumar@ucdavis.edu) on bugs, 
fixes, questions and/or improvements to this sample version of the NEM code
are most welcome. If you use parts of this code in order to accomplish
real work, an acknowledgement/e-mail would be greatly appreciated.
