You're using a specific software on the UL HPC platform not listed in the above list? Then most probably you
- developed a set of script to effectively run that software
- used to face issues such that you're aware (eventually unconsciously) of tricks and tips for that specific usage.
Then your inputs are valuable for the other users and we would appreciate your help to complete this repository with new topics/entries.
To do that, the general approach is similar to the one proposed by Github via the Forking procedure. Since we use git-flow, your workflow for contributing to this repository should typically involve the following steps:
- Fork it
- Initialize your local copy of the repository (including git submodules etc.):
make setup - Create your feature branch:
git flow feature start <feature_name> - Commit your changes:
git commit -am 'Added some feature' - Publish your feature branch:
git flow feature publish <feature_name> - Create new Pull Request
More details are provided below.
The Git branching model for this repository follows the guidelines of gitflow.
In particular, the central repo (on github.com) holds two main branches with an infinite lifetime:
production: the production-ready tutorialsdevel: the main branch where the latest developments interviene. This is the default branch you get when you clone the repo.
So assuming you have forked this repository to work freely on your own copy of it, you can now feed a new tutorial, assuming you follow the below guidelines.
<topic>/<name> # Select the appropriate root directory
├── README.md # Main tutorial file, in Markdown
├── index.md -> README.md # Symlink (for mkdocs)
├── slides.pdf # Slides proposing an overview of the tutorial
├── cover_slides.png # Picture of the cover of the slide
├── Makefile # GNU Makefile offering the targets 'fetch', 'compile', 'run' and 'plot'
├── plots # Directory hosting the Gnuplots / R plots data
├── runs/ # Directory hosting the data/logs of the runs
├── scripts/ # Eventually, a directory hosting some specific scripts
└── launcher-<name>.{slurm|oar}.sh # launcher script to be used in the tutorial
# Prepare the appropriate link for ReadtheDocs -- if needed
docs/<topic> -> ../<topic>
# such that 'docs/<topic>/<name>' points to '../<topic>/<name>'
You SHOULD stick to a single README.md file, (using the markdown format) if possible.
Kindly follow the following format for this file (adapt path/to accordingly):
[](https://hpc.uni.lu) [](http://www.gnu.org/licenses/gpl-3.0.html) [](https://github.com/ULHPC/tutorials/issues/) [](https://github.com/ULHPC/tutorials/raw/devel/path/to/slides.pdf) [](https://github.com/ULHPC/tutorials/tree/devel/path/to/) [](http://ulhpc-tutorials.readthedocs.io/en/latest/path/to/) [](https://github.com/ULHPC/tutorials)
# <the title>
Copyright (c) 2013-2018 [You name,] UL HPC Team <[email protected]>
[](https://github.com/ULHPC/tutorials/raw/devel/path/to/slides.pdf)
The objective of this tutorial is to cover XXX, in particular:
* objective 1
* objective 2
--------------------
## Pre-requisites ##
Ensure you are able to [connect to the UL HPC clusters](https://hpc-docs.uni.lu/connect/access/)
In particular, recall that the `module` command **is not** available on the access frontends.
Now you'll need to pull the latest changes in your working copy of the [ULHPC/tutorials](https://github.com/ULHPC/tutorials) you should have cloned in `~/git/github.com/ULHPC/tutorials` (see ["preliminaries" tutorial](../../preliminaries/))
``` bash
(access)$> cd ~/git/github.com/ULHPC/tutorials
(access)$> git pull
Now configure a dedicated directory ~/tutorials/<topic> for this session
# return to your home
(access)$> mkdir -p ~/tutorials/<topic>
(access)$> cd ~/tutorials/<topic>
# create a symbolic link to the reference material
(access)$> ln -s ~/git/github.com/ULHPC/tutorials/<path> ref.dAdvanced users (eventually yet strongly recommended), create a Tmux session (see Tmux cheat sheet and tutorial) or GNU Screen session you can recover later. See also "Getting Started" tutorial .
# /!\ Advanced (but recommended) best-practice:
# Always work within a TMux or GNU Screen session named '<topic>' (Adapt accordingly)
(access-aion)$> tmux new -s HPC-school # Tmux
(access-iris)$> screen -S HPC-school # GNU Screen
# TMux | GNU Screen | Action
# ----------|------------|----------------------------------------------
# CTRL b c | CTRL a c | (create) creates a new Screen window. The default Screen number is zero.
# CTRL b n | CTRL a n | (next) switches to the next window.
# CTRL b p | CTRL a p | (prev) switches to the previous window.
# CTRL b , | CTRL a A | (title) rename the current window
# CTRL b d | CTRL a d | (detach) detaches from a Screen -
# Once detached:
# tmux ls | screen -ls : list available screen
# tmux att | screen -x : reattach to a past screenLet's get an interactive jobs:
### Access to ULHPC cluster (if not yet done)
(laptop)$> ssh aion-cluster # or iris-cluster
### Have an interactive job
# ... either directly
(access)$> si [...]
# ... or using the HPC School reservation 'hpcschool'if needed - use 'sinfo -T' to check if active and its name
# (access)$> si --reservation=hpcschool [...]
(node)$>instructions
instructions
Remember that they shall be understandable for users having no or very few knowledge on your topic!
One _proposal_ to organize the workflow of your tutorial:
* Select a typical sample example that will be used throughout all the tutorial, that is easy to fetch from the official page of the software. Adapt the `make fetch` directive in your root `Makefile` to perform the corresponding actions.
* (eventually) detail how to build the sources (using [EasyBuild](advanced/Easybuild). Adapt the `make build` accordingly.
* dedicate a section to the running of this example in an _interactive_ job such that the reader has a better understanding of:
- the involved modules to load
- the classical way to execute the software
- etc.
Adapt also the `make run_interactive` accordingly
* dedicate a second section to the running of the example in a _passive_ job, typically providing a generic launcher script adapted to your software. You might adapt / extend the [UL HPC launcher scripts](https://github.com/ULHPC/launcher-scripts) the same way to extend these tutorials. Adapt also the `make run` accordingly.
* a last section would typically involves hints / elements to benchmark the execution, add tips/tricks to improve the performances (and see the effects of those improvements) and have a way to plot the results. Adapt the `make plot` accordingly
### Semantic Versionning
The operation consisting of releasing a new version of this repository is automated by a set of tasks within the `Makefile` at the root of this repository.
In this context, a version number have the following format:
<major>.<minor>.<patch>
where:
* `< major >` corresponds to the major version number
* `< minor >` corresponds to the minor version number
* `< patch >` corresponds to the patching version number
Example: `1.2.0`
The current version number is stored in the file `VERSION`. **DO NOT EDIT THIS FILE**, use the below primitives to affect the number it contains.
For more information on the version, run:
$> make versioninfo
If a new version number such be bumped, you simply have to run:
$> make start_bump_{major,minor,patch}
This will start the release process for you using `git-flow`.
Then, to make the release effective, just run:
$> make release
This will finalize the release using `git-flow`, create the appropriate tag and merge all things the way they should be.