Please make sure that you sign up to the Nektar++ mailing list. This can be done at the following URL:
https://mailman.ic.ac.uk/mailman/listinfo/nektar-users
While the name suggests it is for users of Nektar++, this list is also used to ask questions about Nektar++ development.
The Nektar++ blog ( https://www.nektar.info/cat/community) provides a broad range of posts on topics such as compiling the code on specific machines, to discussions of Nektar++ in specific application areas, to recently published papers which have made use of the code.
Contributing to this resource is a valuable way to support the project, as well as promoting your own work.
In 2015, we held the first Nektar++ workshop, which was a great success and followed by a similar event in 2016. It is now an annual event and allows first-hand access to the core Nektar++ development team as well as a range of other Nektar++ users.
The Nektar++ code is managed in a distributed version control system called git. To obtain
the code directly from the repository and add new content to the repository requires the git
command-line tool (or a suitable GUI equivalent). This is available for Linux, Mac OSX and
Windows.
If you plan to work with the Nektar++ community, you will need to have a reasonable
understanding of the git software. While it is beyond the scope of this document to discuss
how to use git, it is important for someone new to git to spend time understanding how the
tool works. For this purpose, we highly recommend familiarizing yourself with it using any of
the many online resources (such as https://git-scm.com).
Nektar++ may be cloned anonymously using the following command:
git clone http://gitlab.nektar.info/clone/nektar/nektar.git nektar++
Your local copy of the code can be updated to include the latest changes in the repository using the command:
git pull
The Anonymous Access approach will provide you with a complete copy of the code, but you will be unable to push changes or new developments back to the repository. For this, you should use Collaborative Access.
Once you are familiar with git, have introduced yourself to the development community (see the mailing list information above), and are ready to become a contributing developer, you will need to register an account on the Nektar++ Gitlab website:
To use use authenticated access, using your new account, you must first upload the public
part of your SSH key to your Gitlab profile. Generating and managing SSH keys is beyond the
scope of this document. However, on Linux and OSX, one generally finds these keys in the
\$HOME/.ssh directory.
To upload the key, visit: https://gitlab.nektar.info/profile, select SSH keys from the menu on the left and follow the instructions.
Registering for an account and uploading your SSH key need only be done once.
To clone Nektar++, use the git command:
git clone git@gitlab.nektar.info:nektar/nektar.git nektar++
Note the different URL to use authenticated access, in comparison to the anonymous access.
Code contribution then follows three basic steps:
Create an issue to describe the code updates you are making;
Branch the Nektar++ master branch and make your changes on that branch; and
Submit a merge request on the Nektar++ Gitlab website that your updates are ready to be merged into the master branch.
More details regarding the concepts mentioned above is found below. The information is also
available in the CONTRIBUTING.md file in the root directory of the code, or online at:
https://gitlab.nektar.info/nektar/nektar/blob/master/CONTRIBUTING.md
Issues - The initial step for those who wish to add code to the master repository is to create an issue ticket that describes the defect, bug, proposed additions, changes, updates, etc. This is done on the Gitlab website at:
https://gitlab.nektar.info/nektar/nektar/issues
Please ensure you provide sufficient detail when creating the issue to cover all of the following (as required): Describe what is being requested, why it is important / necessary, an initial list of files that may be effected, any potential problems the change/addition may cause, and any other information that will help the development team understand the request and alert others to your work to avoid duplication of effort.
Branches - The second step is to create a git branch in which to do the actual code development. In your local copy of the Nektar++ repository, run the command:
git branch <branch-name>
replacing <branch-name> with a suitable name for your branch. The naming
convention used for branches reflects the nature of the change and is composed
of a prefix and descriptor, separated by a forward slash. Prefixes are one of:
feature: used for developments which constitute a new capability in the code;
fix: used for changes to fix a bug in the code;
tidy: used for changes which improve the quality or readability of the code
but do not change its function;
ticket: can be used to reference changes which address a specific issue.
Please choose concise descriptors in all-lowercase, using hyphens to separate words. An
example <branch-name> might therefore be: feature/low-energy-preconditioner
Now make your new branch active by running the command:
git checkout <branch-name>
Confirm you are on the correct branch by running:
git status
which should print something similar to
On branch <branch-name>
At this point you are all set to make the required modifications to the code in your branch. As you modify your branch, you can use git to save and track your changes.
The following examples show how you can add a file to the list of local files that are being tracked, display differences between the current file and the original file, and commit the file.
git add library/LibUtilities/BasicUtils/my_new_file.cpp git diff --cached
Note --cached is necessary because my_new_file.cpp was staged using the
git add command above. Note, before you add (stage) the file, you can just use
git diff.
To actually create the commit from the staged files, run:
git commit -m "Added␣X,␣Y,␣Z..."
This commits the file to your local repository. The first line of the log message should be
a concise summary of the changes. You can use subsequent lines to provide more
details if needed. Use git log to see the list of previous commits and their
messages.
These changes are still local to your computer. To push them up to the main Nektar++ repository, use the command
git push origin
Nektar++ uses the CMake tool to manage the build process for the three supported operating systems: Linux, Windows, and OSX. For detailed instructions on how to use CMake to build Nektar++, including a list of required software dependencies and CMake option flags, please refer to the Nektar++ User Guide section 1.3.
Before you are ready to have your code merged into the Nektar++ trunk, you should make sure that it passes the built-in test suite - in addition to any new tests that you have added for your updates. To run the test suite, on the command line type:
ctest [-j#]
The -j# optional argument will run # tests in parallel taking advantage of multiple cores on
your machine. It is highly recommended that your use all available cores to minimize the
amount of time spent waiting for the tests to complete. There are currently several hundred
built-in unit tests for Nektar++.
For more information on testing, see “Software Testing Approaches” below.
The final step in contributing your code to the Nektar master repository is to submit a merge request to the development team using the Nektar++ gitlab website:
https://gitlab.nektar.info/nektar/nektar/merge\_requests
Submitting a merge request will automatically trigger the continuous integration (CI) system, which will build and test your code on a range of platforms. You can monitor the progress of these tests from the merge request page. Selecting individual workers will take you to the buildbot website from which you can examine any failures which have occurred.