Intro to HPC
This lesson is focused on teaching the basics of high-performance computing (HPC).
Topic breakdown and todo list
The lesson outline and rough breakdown of topics by lesson writer is in lesson-outline.md. The topics there will be initially generated by the lesson writer, and then reviewed by the rest of the group once complete.
Using this material
- Follow the instructions found in the Software Carpentry example lesson source to create a repository for your lesson.
- Edit _config.yml to modify the configuration options for the HPC system you
will be using in the section titled
Workshop specific values
. These options set such things as the address of the host to login to, definitions of the command prompt, scheduler names. The default is the setup for the Graham Compute Canada cluster hosted at the University of Waterloo which uses the SLURM scheduler. Other examples can be found in the _extras/snippets_library/ directory. - Create the required host-specific code snippets in subdirectories in
_includes/snippets. These snippets provide inputs and outputs that
are host-specific and that are included automatically when the lesson website is built.
- Code snippets are in files named
snippet_name.snip
and are included automatically when the lesson is built. For example, if thesnippet_name
waslogin_output
, then the snippet file would be calledlogin_output.snip
. - Code snippets are placed in subdirectories that are named according to the episode they
appear in. For example, if the snippet is for episode 12, then it will be in a
subdirectory called
12
. - In the episodes source, snippets are included using Liquid
scripting
include
statements. For example, the first snippet in episode 12 is included using{% include /snippets/12/info.snip %}
.
- Code snippets are in files named
Please contribute any configurations you create for your local systems back into the HPC Carpentry snippets library.
Lesson writing instructions
This is a fast overview of the Software Carpentry lesson template. This won't cover lesson style or formatting.
For a full guide to the lesson template, see the Software Carpentry example lesson.
Lesson structure
Software Carpentry lessons are generally episodic, with one clear concept for each episode (example).
An episode is just a markdown file that lives under the _episodes
folder. Here is a link to a
markdown cheatsheet with most
markdown syntax. Additionally, the Software Carpentry lesson template uses several extra bits of
formatting- see here for a full guide.
The most significant change is the addition of a YAML header that adds metadata (key questions,
lesson teaching times, etc.) and special syntax for code blocks, exercises, and the like.
Episode names should be prefixed with a number of their section plus the number of their episode within that section. This is important because the Software Carpentry lesson template will auto-post our lessons in the order that they would sort in. As long as your lesson sorts into the correct order, it will appear in the correct order on the website.
Publishing changes to Github + the Github pages website
The lesson website is viewable at https://hpc-carpentry.github.io/hpc-intro/
The lesson website itself is auto-generated from the gh-pages
branch of this repository. Github
pages will rebuild the website as soon as you push to the Github gh-pages
branch. Because of this
gh-pages
is considered the "master" branch.
Previewing changes locally
Obviously having to push to Github every time you want to view your changes to the website isn't
very convenient. To preview the lesson locally, run make serve
. You can then view the website at
localhost:4000
in your browser. Pages will be automatically regenerated every time you write to
them.
Note that the autogenerated website lives under the _site
directory (and doesn't get pushed to
Github).
This process requires Ruby, Make, and Jekyll. You can find setup instructions here.
Example lessons
A couple links to example SWC workshop lessons for reference:
- Example Bash lesson
- Example Python lesson
- Example R lesson (uses R markdown files instead of markdown)