/*

                   *****    *****   ******  ******  ***   ***
                 **   **  **   **  **      **      ** *** **
                **   **  **   **  ****    ****    **  *  **
               **   **  **   **  **      **      **     **
              **   **  **   **  **      **      **     **
              *****    *****   **      ******  **     **

               OOFEM : Object Oriented Finite Element Code

                 Copyright (C) 1993 - 2012   Borek Patzak

         Czech Technical University, Faculty of Civil Engineering,
          Department of Mechanics, 166 29 Prague, Czech Republic
                www.oofem.org    e-mail: [email protected]
     

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program 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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                                                                              
*/

CONTENTS:

[1]   What is here
[2]   Pre-requisites
[3]   Installation
[4]   Running oofem and oofeg
[5]   Related Links




[1] What is here
==============================================================================
The directory tree below holds source code to the OOFEM package.  

OOFEM_TOP_DIR
|
|-- doc - contains the "User's guide", sources to generate "Reference manual", 
|         documents describing the input file specifications, element and
|         material libraries, and other useful documents. 
|
|-- src - source files of all oofem modules
|   |
|   |-- oofemlib - sources of the core part of OOFEM, the OOFEMlib module.
|   |
|   |-- sm       - sources of structural analysis module.
|   |
|   |-- tm       - sources of transport problem module.
|   |
|   |-- fm       - sources of fluid mechanics module.
|   |
|   |-- dss      - includes the sources for Direct Sparse Solver (DSS),
|   |              contributed by R. Vondracek)
|   |
|   |-- main     - contains the sources of main() and implementation of some 
|                  global functions for oofem, oofeg, and poofem targets.
|
|-- tools   - sources for several utility programs.
|
|-- tests   - contains several tests, which are useful to verify
|             the program functionality.
|
|-- base    - contains templates for target makefiles.
|-- targets - will contain compiled targets after successful compilation


[2] Pre-requisites
==============================================================================
The oofem requires the GNU make tool and C++ compiler with STL support 
(Standard Template Library).

XML parser is supported through tinyXML library. The library is required
for tm module, particularly for CEMHYD3D model. Please download from
http://sourceforge.net/projects/tinyxml/
and place *.cpp and *.h files under tinyxml/ directory under OOFEM root.
Other location can be specified using --with-TINYXMLDIR=" " directive.

The oofem contains interface to IML++ library. It is the C++ templated 
library of modern iterative methods for solving both symmetric and 
non-symmetric linear systems of equations, written by 
Roldan Pozo. It can be downloaded from http://math.nist.gov/iml++/. 
It is recommended to install IML++ and compile OOFEM with IML++ support.
Please place *.h files under iml/ directory under OOFEM root.
Other location can be specified using --with-IMLDIR=" " directive.

The graphical post-processor (oofeg) requires the ELIXIR and Ckit libraries
by Petr Krysl (http://www.multires.caltech.edu/~pkrysl/), to be installed. 
They provide X-windows graphics support.  
The version of Elixir to be used with OOFEM is likely to be not compatible 
with the original version maintained by the Petr Krysl. The compatible
Elixir version is available at oofem home page 
(http://ksm.fsv.cvut.cz/oofem/oofem.html). The Ckit library can be obtained 
at the same location.

Parallel version (poofem) requires MPI library to be installed. 
If you do not have any, we recommend to use Open MPI. 
This is a freely available, high-performance, and portable 
implementation of MPI (http://www.open-mpi.org/).

If you want to use PETSc toolkit, the PETSc version 3.0.0 or higher is
required. The toolkit can be downloaded from PETSc project home page 
(http://www-unix.mcs.anl.gov/petsc/petsc-as/index.html). 

If you want to use SLEPc toolkit, the SLEPc version 3.0.0 or higher is
required. The toolkit can be downloaded from SLEPc project home page 
(http://www.grycap.upv.es/slepc). 

The reference manual can be generated automatically from the sources.
You can use it to generate documentation of your classes, too.
To do this, you have to install doxygen documentation system 
(http://sourceforge.net/projects/doxygen/)
or (http://www.stack.nl/~dimitri/doxygen/) 
and the Graph visualization toolkit 
(http://www.research.att.com/sw/tools/graphviz/)

To build the element library, material library, and oofem input manuals 
from the sources the latex and latex2html packages are required.

The compiled Reference Manual itself is not included in release 
due to its size. It can be accessed online from oofem home page.

To test oofem instalation, Python is required.


[3] Installation
==============================================================================

Quick instructions for UNIX:
----------------------------
0) unpack sources
1) ./configure
2) make
3) make tests


Detailed Installation instructions for UNIX:
--------------------------------------------

1) Unpack the distribution 
   (for example by running "gunzip -c oofem-x.y.tar.gz | tar xof - ")
1) Change the directory to the OOFEM source directory
2) Optionally download and unpack IML++ distribution 
   in the oofem directory under "iml" directory
3) Run the configure script as: ./configure
   o) The configure will set up the default target (named "default"). 
      By default, the solver (oofem) will be build with "-O" optimization
      and no debug options.
   o) To specify compiler flags, set CXXFLAGS environment variable accordingly.
      For example, to build optimized version, use 
      ./configure CXXFLAGS="-O2"
   o) To set up different target, set OOFEM_TARGET variable. For example,
      to build solver with debug information, named oofem-debug, use
      ./configure OOFEM_TARGET="oofem-debug" CXXFLAGS="-g"
   o) If you want to compile with IML++ support use "--enable-iml" parameter
   o) If you want to build graphical post-processor (oofeg)
      use "--enable-oofeg" parameter. 
      Requires Ckit and Elixir libs to be installed.
      Use --with-CKITDIR=dir and --with-ELIXIRDIR=dir configure options
      to specify the location of Ckit and Elixir installation directories. 
      Use absolute paths! 
   o) If you want to build parallel version (poofem) 
      use "--enable-poofem" parameter. Requires MPI library to be installed.
      Use "--with-MPIDIR=dir" to set up MPI installation directory (use absolute path!).
   o) If you want to use PETSc library use "--enable-petsc" together with
      "--with-PETSCDIR=dir" and "--with-PETSCARCH=arch" options to
      configure PETSC support (dir is the path to PETSC installation
      directory - use absolute path, arch is PETSC architecture. 
      See PETSC installation manual for details.)
   o) If you want to use SLEPc library use "--enable-slepc" together with
      "--with-SLEPCDIR=dir" option to configure SLEPc support (dir is the path
      to SLEPc installation directory - use absolute path.
      See SLEPc installation manual for details.)
   o) If you want to use ParMETIS, use "--enable-parmetis" with 
      "--with-PARMETISDIR=dir" to set up ParMETIS installation directory,
       again use absolute path.
   o) Add --enable-dss to compile with Direct Sparse Solver support (DSS)
   o) Use "./configure --help" to see all configure options.

Please, note that all configure parameters that describe location of
optional package installation directories should be specified using
absolute paths, since different makefiles in different directories
depend on these parameters.

The difference with the previous installation procedure 
is the introduction of targets. 
They represent specific settings to produce target executable.
In order to compile solver (oofem), its parallel version (poofem) and graphics
postprocessor (oofeg) you have to set up three different targets:
o) To set up solver target named "oofem-release", 
   with compiler optimization:
./configure OOFEM_TARGET="oofem-release" CXXFLAGS="-O2"
o) To set up parallel solver (poofem) named "poofem-release" 
./configure OOFEM_TARGET="poofem-release" CXXFLAGS="-O2" --enable-poofem ....
o) To set up graphical postprocessor (oofeg) with debugging information:
./configure OOFEM_TARGET="oofeg-debug" CXXFLAGS="-g" --enable-oofeg \
   --with-CKITDIR=dir --with-ELIXIRDIR=dir

4) Run make to compile the required targets as: 
      make OOFEM_TARGET="target_name"

      or
      cd targets/target_name; make 

      or
      export OOFEM_TARGET="target_name"
      make

      supply valid target name (as set up when running configure script)
      for target_name

   The target executable will be created in target_name/bin directory

5) Optionally to test the oofem package (requires Python):
   a) change to particular target directory:
      cd targets/target_name
   b) perform the tests:
      make tests
   c) examine file test_results:
      less test_result

6) Optionally to build reference manuals
   (requires doxygen, Graph visualization toolkit, latex and latex2html to be installed)

   o) OOFEM reference manual (including OOFEMlib):
      a) to build html version use:
         cd doc/refman; make html
      b) to build PostScript version use:
         cd doc/refman; make ps


Hints for Windows:
------------------

There is no direct support for installation under Windows. The are several 
options, that can be used to install oofem on your system:

o) Cygwin/X (http://x.cygwin.com) is a Linux-like environment for Windows
   including a port of X-Windows. Follow installation instructions for UNIX.
o) Dev-C++ is a full-featured IDE for C++. It uses port of GCC as a compiler.
   It creates native Win32 executable. The project has to be set up, follow 
   makefiles for a list of source files to include. Only solver can be build.
o) Other compilers will work as well, but some manual fine-tuning 
   should be expected.

Check out oofem wiki (www.oofem.org/wiki) and
oofem forum (www.oofem.org/forum) as well.


[4] Running oofem and oofeg
==============================================================================
The oofem program prints out the available options when run without
any option. To run a specific job, you can enter

oofem -f input_file_name
 

To run oofeg (graphic post-processor), you need job context file 
(created by oofem, for example using -context option). To run oofeg, enter

oofeg -f input_file_name

There are few useful oofeg key-bindings:
Fast viewing

B1            =  window
Ctrl B1       =  pan
Ctrl B2       =  zoom
Shift B2      =  fit all (only active drawing window will be affected)
Ctrl Shift B1 =  rotate
B3            =  done

Selection

B1            =  select
Ctrl B1       =  select window
Shift B1      =  select nearest point 
                 (confirm by B1 or select next one by Shift B1)
B2            =  accept
B3            =  reject



[5] Further documentation
==============================================================================
Please consult oofem home page (http://www.oofem.org) for 
more documentation, manuals and new versions.

Bugs
==============================================================================

Please mail all bug reports and suggestions to [[email protected]]. I will try to
give satisfaction, if the time is at least partially on my side. 


                                Enjoy
                                        Borek Patzak