#-----------------------------------------------------------------------
#       phdMesh : Parallel Heterogneous Dynamic unstructured Mesh
#                  Copyright (2007) Sandia Corporation
#
#  Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
#  license for use of this work by or on behalf of the U.S. Government.
#
#  This library is free software; you can redistribute it and/or modify
#  it under the terms of the GNU Lesser General Public License as
#  published by the Free Software Foundation; either version 2.1 of the
#  License, or (at your option) any later version.
#
#  This library is distributed in the hope that it will be useful, but
#  WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#  Lesser General Public License for more details.
#
#  You should have received a copy of the GNU Lesser General Public
#  License along with this library; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
#  USA
#-----------------------------------------------------------------------

Overall Description
------------------

Primary author:  H. Carter Edwards  <hcedwar@sandia.gov>

The phdMesh package is a work-in-progress / under construction.

This package currently consists of two research libraries:
(1) a full-featured parallel heterogeneous dynamic
    unstructured mesh library (phdmesh) and
(2) an experimental hybrid parallel (MPI + pthreads)
    sparse linear algebra library (txblas).


The primary 'phdmesh' library is a research code for evaluating the
performance of operations on parallel heterogeneous dynamic unstructured
meshes.  For example dynamic load balancing, geometric proximity search,
or parallel synchronizations for element-by-element operations.


The 'txblas' library is intended to implement simple experiments for
evaluating the performance of hybrid parallel sparse linear algebra
algorithms for the purpose of gaining insight into hybrid parallel
performance.  There is NO intention for it to be a production capability.


#-----------------------------------------------------------------------

Building the Code
------------------

This package currently uses a set of simplistic configuration scripts
and makefiles.  Integration into the Trilinos autoconf and automake
build strategy is to-be-done.

------------------

The package requires:
  a) C++ compiler that is compliant with the 1998 standard and
  b) C   compiler that is compliant with the 1999 standard.

1) Create a directory in which the build will be performed, e.g. BUILD_DIR.

2) Create a build script in the BUILD_DIR to invoke the primary makefile.
   Samples of configuration scripts for GNU, Intel, and SUN
   compilers are located in the 'build_examples' subdirectory.

   The build script had three responsibilities:
     a) Setting paths:
          ${PHDMESH_PATH}    - path to source installation.
          ${PHDMESH_INSTALL} - installation path for libraries.

     b) Setting the ${PATH} or loading modules for the compilers,
        if necessary.

     c) Choosing a compiler and options via one of the scripts:
          ${PHDMESH_PATH}/config/{gnu,intel,sun}
        Options include
          with/without MPI,
          with/without pthreads,
          debug/optimized,

     d) Choosing other configuration script options,
        such as to use ExodusII
          ${PHDMESH_PATH}/config/exodusII <path>

     e) Invoking make on the primary makefile.
          make -f ${PHDMESH_PATH}/Make.in $@
        or
          gmake -f ${PHDMESH_PATH}/Make.in $@

3) Make targets are identified in ${PHDMESH_PATH}/Make.in
   A typical build command is 'build_script all -j 4'
   which builds all executables using four parallel processes.

If a new compilers, or new compiler options, are introduced please
introduce created or updated ${PHDMESH_PATH}/config scripts into the
repository, or send to the author.

#-----------------------------------------------------------------------

Test Executables
------------------

Three test executables and example source code may be built.

1)  test_util.exe,   source directory ${PHDMESH_PATH}/tests/util
2)  test_mesh.exe,   source directory ${PHDMESH_PATH}/tests/gears
3)  test_txblas.exe, source directory ${PHDMESH_PATH}/tests/txblas

Tests have been run with gnu, intel, sun, and ibm compilers.

#-----------------------------------------------------------------------

Using the Libraries
------------------

The following include paths are required compile with installed libraries.
  "-I${PHDMESH_INSTALL} -I${PHDMESH_PATH}/include"

The following link path is required to link with the installed libraries.
  "-L${PHDMESH_INSTALL}"

Four libraries are installed.

  -lphdmesh_util     Utility library,
                     API in ${PHDMESH_PATH}/include/util

  -lphdmesh_mesh     Mesh library, requires -lphdmesh_util,
                     API in ${PHDMESH_PATH}/include/mesh

  -lphdmesh_meshio   Mesh io library, requires -lphdmesh_mesh,
                     API in ${PHDMESH_PATH}/include/mesh_io

  -lphdmesh_txblas   Hybrid MPI/pthread research blas library,
                     requires -lphdmesh_util,
                     API in ${PHDMESH}/include/txblas

#-----------------------------------------------------------------------

