README.md 4.96 KB
Newer Older
1
Giraffe
Ron Rahaman's avatar
Ron Rahaman committed
2
=======
Derek Gaston's avatar
Derek Gaston committed
3

4
[![build status](https://xgitlab.cels.anl.gov/nek5000/giraffe/badges/develop/build.svg)](https://xgitlab.cels.anl.gov/nek5000/giraffe/commits/develop)
Ron Rahaman's avatar
Ron Rahaman committed
5

Ron Rahaman's avatar
Ron Rahaman committed
6
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/).
Ron Rahaman's avatar
Ron Rahaman committed
7

Ron Rahaman's avatar
Ron Rahaman committed
8 9
Requirements
------------
Derek Gaston's avatar
Derek Gaston committed
10

Ron Rahaman's avatar
Ron Rahaman committed
11 12 13 14 15 16 17 18 19
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/"
  ```
Ron Rahaman's avatar
Ron Rahaman committed
20

Ron Rahaman's avatar
Ron Rahaman committed
21 22
Building Example Problems
-------------------------
Ron Rahaman's avatar
Ron Rahaman committed
23

Ron Rahaman's avatar
Ron Rahaman committed
24
### Basic compilation
Ron Rahaman's avatar
Ron Rahaman committed
25

Ron Rahaman's avatar
Ron Rahaman committed
26 27 28 29
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`. 
Ron Rahaman's avatar
Ron Rahaman committed
30

Ron Rahaman's avatar
Ron Rahaman committed
31 32
The complete steps for the `integration_example` problem are:
``` Shell
33
$ cd giraffe
Ron Rahaman's avatar
Ron Rahaman committed
34
$ ./bootstrap
Ron Rahaman's avatar
Ron Rahaman committed
35
$ cd examples/integration_example
Ron Rahaman's avatar
Ron Rahaman committed
36 37 38
$ ../../configure
$ make
```
Ron Rahaman's avatar
Ron Rahaman committed
39 40 41 42 43 44 45 46 47 48

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.  
Ron Rahaman's avatar
Ron Rahaman committed
49 50

### Running Example Problems
Ron Rahaman's avatar
Ron Rahaman committed
51

Ron Rahaman's avatar
Ron Rahaman committed
52
``` Shell
53 54
$ cd giraffe/examples/integration_example
$ ../../giraffe-opt -i coefficient_integration.i
Ron Rahaman's avatar
Ron Rahaman committed
55
```
Ron Rahaman's avatar
Ron Rahaman committed
56

Ron Rahaman's avatar
Ron Rahaman committed
57 58 59 60 61
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
```
Ron Rahaman's avatar
Ron Rahaman committed
62

Ron Rahaman's avatar
Ron Rahaman committed
63
Upon repeated runs, Nek5000 may raise an error if an output `.sch` file is present.  If so, delete the `.sch` file and rerun Giraffe.  
Ron Rahaman's avatar
Ron Rahaman committed
64

Ron Rahaman's avatar
Ron Rahaman committed
65 66
Developing Giraffe
------------------
Ron Rahaman's avatar
Ron Rahaman committed
67

Ron Rahaman's avatar
Ron Rahaman committed
68
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.  
Ron Rahaman's avatar
Ron Rahaman committed
69

Ron Rahaman's avatar
Ron Rahaman committed
70
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.