README

===========
Overview
===========
DynEarthSol3D is a finite element code that solves the momentum balance and 
the heat transfer in Lagrangian form using unstructured meshes. It can be
used to study the long-term deformation of Earth's lithosphere and problems
alike.

This version of DES3D contains libadaptivity from Fluidity
(https://github.com/FluidityProject/fluidity), 
a self-contained library for anisotropic adaptive mesh refinement, 
works well as a mesh optimizer for DES3D's remeshing.

===========
Build
===========

Requirement:
* You will need a recent C++ compiler that supports C++11 standard. (GNU g++
  4.4 or newer version will suffice.)
* You will need a recent version of Boost::Program_options library (1.42 or
  newer version). Instructions for building the library:
  -- Download the source code from www.boost.org
  -- In the untarred source directory, run "./bootstrap.sh"
  -- In the same directory, run "./b2 --with-program_options -q" to build
     the library.
* You will need Python 2.6+ or 3.2+ and the Numpy package.

For libadaptiviy, you further need
* VTK5 (v5.8 and v5.10 tested) or later versions built from source or development packages.
* MPI (openmpi v1.4~v1.6, and mpich2 v1.4 tested).

For importing a mesh in the ExodusII format, you need to install the exodus library
* exodus is available as a part of SEACAS project https://github.com/gsjaardema/seacas/

Procedures:
* Edit 'Makefile', 
  1) Modify BOOST_ROOT_DIR if you manually built or installed 
  boost library. If you followed the instructions above to build 
  Boost::Program_options library, set BOOST_ROOT_DIR to the untarred boost
  directory.
  2) If using libadaptivity:
    2.1) Set 'useadapt = 1' and 'ndims = 3'. libadaptivity works only for 3D.
    2.2) Set VTK_INCLUDE and VTK_LIBS paths if vtk is not in standard location.
    2.3) Set LIB_MPIFORTRAN for your mpi library
  3) If importing an exodus mesh:
    3.1) Set 'useexo = 1' and 'ndims = 3'. Only 3D exodus mesh can be imported.
    3.2) Set EXO_INCLUDE and EXO_LIB_DIR paths.
* Run "make" to build optimized executable.
* Or run "make opt=0" to build a debugging executable.
* Or run "make openmp=0" to build the executable without OpenMP. This is
  necessary to debug the code under valgrind.


===========
Run
===========

* Execute "dynearthsol2d inputfile".
* Pay attention to any warnings. For instance, if a warning about potential 
  race condition is printed on screen, do follow the given suggestions.
* Several example input files are provided under 'examples/' directory. The
  format of the input file is described in 'examples/defaults.cfg'.
* Benchmark cases with analytical solution can be found under 'benchmarks/'
  directory.
* Execute the executable with '-h' flag to see the available input parameters
  and their descriptions.


===========
Plot
===========

* Run "2vtk.py modelname" to convert the binary output to VTK files.
* Execute 2vtk.py with '-h' flag to see more usage information.
* Some of the simulation outputs might be disabled. Edit 2vtk.py and
  output.cxx to disable/enable them.
* Plot the VTK files with Paraview or LLNL's Visit program.


===========
Availability
===========

This software, as well as possible updates, is available from the
following URL:
  https://github.com/tan2/DynEarthSol

===========
Bug reports
===========
      
Bug reports, comments, and suggestions are always welcome. The best 
channel is to create an issue on the Issue Tracker here:
  https://github.com/tan2/DynEarthSol/issues

===========
License
===========

This program is free software: you can redistribute it and/or modify
it under the terms of the MIT / X Windows System license (see the
file LICENSE for the full text).

The files under the subdirectories 3x3-C/, ann/, libadaptivity/, tetgen/
and triangles/ are distributed by their own license(s).


by Eh Tan, Sept. 2014