Commit e09958e9 authored by Max Hutchinson's avatar Max Hutchinson
Browse files

Adding readme and contributing guide

parent d7ece752
# Contributing to Nek5000
Nek5000 on Github follows a forking workflow.
If you are unfamiliar with forking, take a look at [this great guide](
For a more detailed description of forking workflow, here's a [slightly longer read](
Please branch off of and open pull requests to the `develop` branch.
The `master` branch is reserved for releases.
## Where did the sources go?
As part of the move to git, the contents of the svn repo have been reorganized to match the modularlity of the codebase. Here's a brief description of each top-level directory:
### `core`
`core` contains the majority of the Nek5000 application sources.
### `jl`
`jl` contains gather/scatter communication, interpolation, and preconditioners written in highly general C code.
`jl` used to live in `nek5_svn/trunk/nek`, but is being promoted to the top level to emphasize its library-like relationship to the rest of the source.
In fact, `jl` has been extended externally in [gslib](, which is used in other projects.
### `scripts`
`scripts` contains bash scripts for running nek5000 and manipulating its output on a variety of platforms, e.g. `nekmpi`.
### `tools`
`tools` contains the sources for the pre- and post-processing tools, e.g. `genmap`, which are stand-alone fortran programs.
### `tests`
`tests` contains a light-weight subset of the validation tests found in nek5000-examples and, in the future, unit-like tests to validate specific features.
Validation tests that require binary inputs, e.g. `re2` or `map` files, belong in the separate nek5000-examples repo.
### `lib`
`lib` contains original nek5000 sources that are general enough to be used by 3rd party plugin/toolbox developers or are shared with the tools.
`lib` is starting nearly empty, with sources slowly migrating into them from `core`.
### `3rd_party`
`3rd_party` contains nothing, and should remain empty save git-related meta-data files.
Its purpose it to provide a consistent place for 3rd part plugin/toolbox developers to place their code.
## Porting to the new layout
If you had previously forked the Nek5000/Nek5000 repository and made changes, you need to match the new layout before pulling.
Fortunately, this is easy!
cd <PATH_TO_NEK5000>
git filter-branch --force --index-filter \
'git ls-files -s | sed "s-\t-&core/-" |
git update-index --index-info &&
git filter-branch --force --tree-filter \
'test -d core/jl && mv core/jl . || echo "Nothing"' HEAD
Now you should be able to pull in the rest of the new layout via pull request or the command line.
# Nek5000
## Wait, where did everything go?
With the move to git, we have decided to reorganize the sources to improve modularity.
Most of what used to be in `trunk/nek` now lives in `core`, including the all-important `makenek`.
We hope the rest of the directories are self describing: you can find things like `nekmpi` and `nekb` in `scripts` or `genbox` and `genmap` in `tools`.
The examples have been moved into a seperate repository, [nek5000_examples](, to keep this one light-weight.
## Get Nek5000
You can download the latest release of nek5000 as [a zip]( or [a tarball](
You can also clone the repository with git:
git clone --single-branch
or even check it out with svn!
svn co nek5000
## Use Nek5000
nek5000 works the same way it used to: build cases with `core/makenek` and run them with a script, e.g. `scripts/nekmpi`.
For more information, see the [user guide](
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