Commit d3a3a921 authored by Ron Rahaman's avatar Ron Rahaman
Browse files

Updates to README

parent 51299065
Pipeline #1052 passed with stages
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/).
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/).
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/"
```
Downloading the Repo
--------------------
Cloning the Giraffe repository requires the `--recursive` flag, since MOOSE and libmesh are included as [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). For example:
```
git clone --recursive https://xgitlab.cels.anl.gov/nek5000/giraffe.git
```
This will download and populate the src/moose and src/moose/libmesh.
Building Example Problems
-------------------------
Building PETSc
--------------
Giraffe requires PETSc, as described in the [MOOSE installation instructions](http://mooseframework.com/getting-started/). PETSc is not distributed with Giraffe. PETSc must either be compiled from source or installed as part of the MOOSE Environment package. After installing PETSc, you must define the `$PETSC_DIR` variable in your environment.
### 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`.
Building libmesh
----------------
Giraffe also requires libmesh, as described in the [MOOSE installation instructions](http://mooseframework.com/getting-started/). The libmesh source code is distributed with MOOSE. It should be compiled using the following scripts:
```
$ cd moose/
$ scripts/update\_and\_rebuild\_libmesh.sh.
```
After installing libmesh, you must define the `$LIBMESH_DIR` in your environment.
The Example Problems
--------------------
Currently, the only working example problem is "integration_example" in `giraffe/examples/integration_example`.
### Building Example Problems
To configure and build each example problem, first generate the `configure` script in the top-level Giraffe directory:
```
The complete steps for the `integration_example` problem are:
``` Shell
$ cd giraffe
$ ./bootstrap
```
Then cd into the example subdirectory and simply run `configure` && `make`. This will build the MOOSE and Nek5000 libraries, then link them to the executable driver.
```
$ cd giraffe/examples/integration_example`
$ cd examples/integration_example
$ ../../configure
$ make
```
The `configure` script may be run with additional options (for example, to point to a custom libmesh or MOOSE installation). Run `./configure --help` to see a list of the available options.
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
To run an example problem, it is recommended to use the convenience script `giraffe/examples/build_coupled_nek`. This script will automatically setup some input files needed by Nek5000 (such as SESSION.NAME). The script takes one command-line argument for the MOOSE configuration file, `-i <config_file>.i`.
```
``` Shell
$ cd giraffe/examples/integration_example
$ ../../giraffe-opt -i coefficient_integration.i
```
Linking to libgiraffe
------------------
The Giraffe libraries are output to the top-level lib/ directory.
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
```
Developing Nek5000 in Giraffe
--------------------------
Developers may freely modify src/Nek5000 as if it were a normal part of the Giraffe repo. This is because Nek5000 is included as a Git subtree (rather than a submodule). For routine commits, pushes, and pulls to the Giraffe repository, no extra Git commands are necessary.
Upon repeated runs, Nek5000 may raise an error if an output `.sch` file is present. If so, delete the `.sch` file and rerun Giraffe.
With some additional Git commands, developers may easily merge upstream changes from [https://github.com/Nek5000/Nek5000](https://github.com/Nek5000/Nek5000) into src/Nek5000. Finally, developers may also request to merge changes from src/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 the procedures.
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.
Developing MOOSE and libmesh in Giraffe
------------------------------------
Modifying src/moose and src/moose/libmesh require additional Git commands, since they are included as Git submodules (rather than subtrees). Modifying either of these libraries for Giraffe is intended to be unnecessary. Should the situation arise, this [chapter](https://git-scm.com/book/en/v2/Git-Tools-Submodules) from _Pro Git_ describes the procedure for making modifications to submodules.
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment