Giraffe
=======

[![build status](https://xgitlab.cels.anl.gov/nek5000/giraffe/badges/develop/build.svg)](https://xgitlab.cels.anl.gov/nek5000/giraffe/commits/develop)

Giraffe uses the [MOOSE](http://www.mooseframework.org/) framework to implement multiphysics coupling with [Nek5000](https://nek5000.mcs.anl.gov/) CFD simulations.  The project is a collaboration between [Idaho National Laboratory](https://www.inl.gov/) and [Argonne National Laboratory](https://www.inl.gov/) with contributions from [MIT](https://www.berkeley.edu/) and [UC-Berkeley](https://web.mit.edu/).

Requirements
------------

Giraffe requires the MOOSE environment (including PETSc, libmesh, and MOOSE).  This can be installed according to the [MOOSE installation instructions](http://mooseframework.com/getting-started/).  After installation you must define the following environment variables:
* `LIBMESH_DIR`: The top-level directory of your libmesh installation.  If you follow the MOOSE installation instructions, this should already be set in your environment.  A typical command is:

  ``` Shell
  export $LIBMESH_DIR="$HOME/projects/moose/libmesh/installed"
  ```

* `MOOSE_DIR`:  The top-level directory of your MOOSE installation.  For Giraffe, this must be additionally set in your environment. A typical command is:

  ``` Shell
  export $MOOSE_DIR="$HOME/projects/moose/"
  ```

Building Example Problems
-------------------------

### Basic compilation

Giraffe must be separately compiled for each specific problem, since Nek5000 uses static memory allocations that are specific to the problem setup. To build an example problem:
1. In the top-level Giraffe, directory use the `bootstrap` script to generate a `configure` script.
2. In the subdirectory for the example problem, run the `configure` script.
3. In the subdirctory for the example problem, run `make`. 

The complete steps for the `integration_example` problem are:

``` Shell
$ cd giraffe
$ ./bootstrap
$ cd examples/integration_example
$ ../../configure
$ make
```

A successful compilation will create libraries and executables in the top-level Giraffe directory (in this case, `giraffe/lib/lib-giraffe-opt.so` and `giraffe/giraffe-opt`).  **Note that, even though the libraries and executables are problem specific, they are not output to the problem's director.**

### Additional compilation options
To perform custom compilations, the `configure` script may be run with additional options.  Run `./configure --help` to see a complete list of the available options and variables.  Some of the most useful are:
* `CASENAME`: Specfies the basename of the Nek5000 `.usr` file.  For example, if you were compiling with `integration_example.usr`, then you would specify `CASENAME="integration_example"`.  The default value of `CASENAME` is the name of the example subdirectory.  
* `MOOSE_DIR`: Inherited from the environment.  If it is specified here, it will override the environment's value.
* `LIBMESH_DIR`: Inherited from the environment.  If it is specified here, it will override the environment's value.

For the majority of situations, it is not recommended to directly specify compilers and compiler/linker flags to configure script (`CC`, `CFLAGS`, `LDFLAGS`, etc).  This is because, by default, the compilers and flags are detected from the libmesh installation, which ensures a consistent compilation of Giraffe.  

### Running Example Problems

``` Shell
$ cd giraffe/examples/integration_example
$ ../../giraffe-opt -i coefficient_integration.i
```

The Giraffe executable is output to the top-level Giraffe directory (in this case, `giraffe/giraffe-opt`) but must be run in the example subdirectory.  To run the simulation, use:

``` Shell
$ cd examples/integration example/
$ ../../giraffe-opt -i coefficient_integration.i
```

Upon repeated runs, Nek5000 may raise an error if an output `.sch` file is present.  If so, delete the `.sch` file and rerun Giraffe.  

Developing Giraffe
------------------

Giraffe is ensured to be compatable with the current [MOOSE master branch](https://github.com/idaholab/moose/tree/master).  However, Giraffee is **not** necessarily compatable with a current or previous version [Nek5000 master branc](https://github.com/Nek5000/Nek5000/tree/master).  Hence, Giraffe includes Nek5000 as a Git **subtree** rather than a submodule.  

The use of a subtree means that developers may freely modify Nek5000 as if it were a normal part of the Giraffe repo.  For routine commits, pushes, and pulls to the Giraffe repository, no extra Git commands are necessary for changing `giraffe/Nek5000`.  With some additional Git commands, developers may also merge upstream changes from [https://github.com/Nek5000/Nek5000](https://github.com/Nek5000/Nek5000) into `giraffe/Nek5000`.  Finally, developers may also request to merge changes from `giraffe/Nek5000` to [https://github.com/Nek5000/Nek5000](https://github.com/Nek5000/Nek5000).   This [blog post](http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/) from Atlassian gives a brief rundown of these operations.