FEM Earthquake Simulation Toolchain Demo 

Developed by CMU Euclid/Quake Team. 

Contact:
Tiankai Tu 
Computer Science Department
Carnegie Mellon University
Pittsburgh, PA 15213
tutk@cs.cmu.edu

**********
0. Files
**********

README          This file
Makefile        Builds and runs the programs for FEM earthquake simulation.
bin/            Directory containing the programs.
data/           Directory containing the data of the simulation.


*************************************
1. What is contained in the package
*************************************

The package contains the programs and meta data for conducting finite
element earthquake simulation. The input to the simulation process is
an etree database recording the material properties of the domain. The
output is a 4D etree databae containing the simulation result. Five
steps are involved in the process:

 1. Mesh generation (bin/mesher/*):
      Generate an unstructured hexahedral mesh to resolve a specified 
      frequency by querying an etree database. 

 2. Mesh partitioning (bin/partitioner/*):
      Create a partition plan for a pre-determined number of subdomains 
      that corresponds to the number of processors to be used in solving
      step.

 3. Data packing (bin/packer/*):
      Pack/subdivide the mesh into smaller pieces (files) according 
      to the partition plan. 

 4. Problem solving (bin/solver/*): 
      Solve the mesh using the number of processors pre-determined.

 5. Output conversion (bin/converter/*):
      Collect the output produced by each processor and store the results
      in a 4D etree.

In addition to the simulation programs, we also provide a query tool to 
extract data from the 4D result etree. 

 6. Data extraction (bin/querier/*):
       Query the 4D etree database to retrieve the waveform in at a 
       particular point in the domain. 

Note that this demo only uses one processor. But all the simulation steps 
are executed in order to demonstrate he completeness. 

In the data/ directory, there are five subdirectories:

 1. data/cvm-etree/ (read only): 
      Contains the material database representing the Greater LA Basin.
      See data/cvm-etree/README for details. 

 2. data/mesh/ (read/write):
      Contains the meta data for a 0.1Hz mesh simulation. See 
      data/mesh/README for details. The meta data is specific to the 
      demo and needs to be provided by users. In addition to the meta data,
      intermediary results produced during the simulation are also stored 
      in this directory. 

 3. data/4d-etree/ (read/write):
      Contains the 4D etree database represeting the simulation results 
      when the demo is done.

 4. data/benchmark/ (read only):
      Contains a text file recording the benchmark waveforms at eight 
      observation points that can be used for comparison purpose. 

 5. data/plots/ (read/write):
      Contains the waveform plottings for the observation points and the
      benchmark waveform plottings.


*********************************
2. How to build and run the demo
*********************************

In order to build the toolchain programs, we require the following software
packages be installed:

  - GNU make (gmake) 
  - GNU compiler (gcc) 
  - MPI (mpich) 
  - GNU plot (gnuplot): optional for comparison with benchmark. 

Make sure that the PATH environment is set properly so that these software
packages are accessible from the command prompt. 

The demo is fully automated and has been tested on PIII/Linux 2.4. 

Type 'gmake all' to build the toolchain programs.
Type 'gmake clean" to remove the programs and object files. 
Type 'gmake run' to conduct the end-to-end demo for the 0.1Hz mesh.


*****************************
3. How to check the results
*****************************

In general, the 4D result etree database can be queried to produce
waveforms at arbitrary points in the domain. For this demo, we extract
the waveforms for eight observation points:

            x     y      z
Point 1:  74000 16000  -0.1 
Point 2:  68000 24000  -0.1        
Point 3:  62000 32000  -0.1       
Point 4:  56000 40000  -0.1
Point 5:  44000 56000  -0.1       
Point 6:  32000 72000  -0.1 
Point 7:  38000 64000  -0.1       
Point 8:  50000 50000  -0.1       

Type 'gmake plot' to extract the eight waveforms. 

In this process, we automatically invoke gnuplot to visually plot the
waveforms. Eight postscript files named obv_pt1.ps, obv_pt2.ps, ...,
obv_pt8.ps will be produced and stored under data/plots/.

To facilitate correctness check, we also convert the benchmark data
(text format) in data/benchmark/ into eight postscript files name
benchmark_pt1.ps, benchmark_pt2.ps, ..., and benchmark_pt8.ps under
data/plots/. Any postscript viewer can be used to compare the
results.