README.md 4.97 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
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:
13

Ron Rahaman's avatar
Ron Rahaman committed
14 15 16
  ``` Shell
  export $LIBMESH_DIR="$HOME/projects/moose/libmesh/installed"
  ```
17

Ron Rahaman's avatar
Ron Rahaman committed
18
* `MOOSE_DIR`:  The top-level directory of your MOOSE installation.  For Giraffe, this must be additionally set in your environment. A typical command is:
19

Ron Rahaman's avatar
Ron Rahaman committed
20 21 22
  ``` Shell
  export $MOOSE_DIR="$HOME/projects/moose/"
  ```
Ron Rahaman's avatar
Ron Rahaman committed
23

Ron Rahaman's avatar
Ron Rahaman committed
24 25
Building Example Problems
-------------------------
Ron Rahaman's avatar
Ron Rahaman committed
26

Ron Rahaman's avatar
Ron Rahaman committed
27
### Basic compilation
Ron Rahaman's avatar
Ron Rahaman committed
28

Ron Rahaman's avatar
Ron Rahaman committed
29 30 31 32
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
33

Ron Rahaman's avatar
Ron Rahaman committed
34
The complete steps for the `integration_example` problem are:
35

Ron Rahaman's avatar
Ron Rahaman committed
36
``` Shell
37
$ cd giraffe
Ron Rahaman's avatar
Ron Rahaman committed
38
$ ./bootstrap
Ron Rahaman's avatar
Ron Rahaman committed
39
$ cd examples/integration_example
Ron Rahaman's avatar
Ron Rahaman committed
40 41 42
$ ../../configure
$ make
```
Ron Rahaman's avatar
Ron Rahaman committed
43 44 45 46 47 48 49 50 51 52

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
53 54

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

Ron Rahaman's avatar
Ron Rahaman committed
56
``` Shell
57 58
$ cd giraffe/examples/integration_example
$ ../../giraffe-opt -i coefficient_integration.i
Ron Rahaman's avatar
Ron Rahaman committed
59
```
Ron Rahaman's avatar
Ron Rahaman committed
60

Ron Rahaman's avatar
Ron Rahaman committed
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:
62

Ron Rahaman's avatar
Ron Rahaman committed
63 64 65 66
``` Shell
$ cd examples/integration example/
$ ../../giraffe-opt -i coefficient_integration.i
```
Ron Rahaman's avatar
Ron Rahaman committed
67

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

Ron Rahaman's avatar
Ron Rahaman committed
70 71
Developing Giraffe
------------------
Ron Rahaman's avatar
Ron Rahaman committed
72

Ron Rahaman's avatar
Ron Rahaman committed
73
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
74

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