hpcleuven / vscdocumentation

VSC (Vlaams Supercomputing Center) user documentation.

VscDocumentation

Repository of the VSC documentation website.

How to contribute?

Improving the documentation is quite simple, all documents can be edited with a simple text editor. You standard workflow to contribute changes is:

1. Clone this repository
2. Make corrections/improvements to any document
3. Push you changed to a new branch
4. Open a pull request to the master branch of this repo

⚠️ Follow our style guide to edit the VSC documentation.

What is the status of improvements/fixes?

Feel free to open issues to get fixes or improvements on the agenda. To get an overview of work that is planned or in progress, check out the project overview.

Workflow

Prerequisites

You will need to clone the repository, i.e.,

$ git clone [email protected]:hpcleuven/VscDocumentation.git

Your life will be substantially easier if you can preview your changes locally. For this you'll need to install the required packages in a self-contained environment such as a Python virtual environment (venv) or Conda. The packages are listed in the requirements.txt file in this repo.

Such environments should preferably use the same Python version as the one specified in the .readthedocs.yaml file. Note that older Python versions (<= v3.7 at the time of writing) may not be able to install the requirements.

Python venv

This is an example setup for a Python virtual environment:

$ python -m venv /path/to/new/venv
$ source /path/to/new/venv/bin/activate
$ cd VscDocumentation
$ python -m pip install -r requirements.txt

Conda

This is an example setup for a Conda environment:

$ conda create -n vscdocs python=3.11
$ source activate vscdocs
$ pip install -r requirements.txt

Downloads and installation instructions for Miniconda can be found on conda's website.

Creating a feature branch

Do not make changes in the master or development branches directly. Create your own feature/bugfix branch as needed.

$ cd VscDocumentation
$ git checkout master
$ git checkout -b feature/new_stuff

Running a local sphinx server

The repository contains a make file that has a target to run the sphinx server. The latter will monitor the source directory for changes, and serve the documentation to a web browser that is opened automatically.

$ make web

Edit content

You can now edit the content to your heart's content, making commits to your feature branch as you go. You can push your feature branch to the Github repository whenever you like.

$ git add source/some_documentation_file.rst
$ git commit -m "some new stuff added to VSC docs"
$ git push origin feature/new_stuff

Pull request

When you are done, create a pull request to the master branch of this repository on GitHub.

Changes to the documentation require the positive review from the documentation maintainers of your pull request. Pay attention to the review in case there would be remarks to address.

Once the pull request has been merged, the branch will be deleted from GitHub. At this point, all that is left to do is delete your local feature branch.

$ git fetch origin
$ git checkout master
$ git pull origin master
$ git branch -d feature/new_stuff

vscdocumentation's Issues

Add documentation on job arrays

Some documentation on submitting and managing job arrays would be useful.

FAQ page

At the moment, there is an unofficial FAQ page on the documentation site. Whenever I come across a page that answers a FAQ, I add a link on that page.

https://vlaams-supercomputing-centrum-vscdocumentation.readthedocs-hosted.com/en/latest/faq.html?highlight=faq#frequently-asked-questions-faqs

It is "unofficial" in the sense that there is no link to it from other pages.

Since I know that opinions on FAQ pages are divided, opinions as to its fate are invited.

Add remark that having a conda function definition in your .bashrc will give problems for NX login

When installing miniconda3, the installer offer to modify the user's .bashrc. In the past, it simply added a modification of PATH, now it defines a conda function.

Somehow, this causes issues when users try to log in on NX nodes, so a cautionary note should be added to the documentation.

Add references to MFA page

The MFA page explains how to use NoMachine with MFA, but on the NoMachine page itself (https://docs.vscentrum.be/en/latest/access/nx_start_guide.html#nx-start-guide) there is no mention of MFA. Could you revise that page (and probably all other pages explaining how to connect to the cluster) so that there are references to the main MFA page?

Retiring the Development branch and revisiting the workflow

Hey all

I would like to bring the fact into your attention that the development branch has fallen quite behind the master branch, which to my knowledge opposes the original idea. A simple git diff master..development shows quite sensitive differences between the two which calls for some work to bring them back in sync.

So, one possibility is to retire the existing development branch, and then

• either create one from the existing master, and keep our current workflow (and really practice it)
• or we follow the normal practice of branching off from master and merging to the master.
  However, the master branch can be protected from direct merges, by enforcing reviews.

What do you guys think?
Ehsan

Add documentation about beeond option

Add documentation about how to use beeond on Tier-1 and KU Leuven Tier-2 systems

Title bar/header

The bar at the top of the page contains a number of useful (or not so much) icons:

• Does the one to Github add value? We don't have much material there that is public/interesting
• Can we replace the Twitter icon with the X icon?
• Can we add a LinkedIn icon since that is our main social media channel?
• Can we add an icon for the VSC website?

Add documentation on singularity

SVN documentation

We have quite a number of pages on SVN, do we keep them or retire them? I suspect that those who use know how to, and that we hardly encourage new users to use subversion.

Broken link?

Dear GJB

The link pointing to the request form for introduction credits for KU Leuven user is either broken, or is not properly set up, because it leads to a blank page: https://vlaams-supercomputing-centrum-vscdocumentation.readthedocs-hosted.com/en/latest/leuven/credits.html#id1

Br
Ehsan

ThinKing hardware nodemap errors

There are some things that look off in the thinking_centos7.png figure of the hardware on ThinKing (shown at the bottom of this VsCdocs page):

• I think the legend on the right is mostly fine, except that those two Quadro K5200 nodes are not there anymore?

• The map colors don't seem to agree with the legend. According to pbsnodes info,

  • the r10 racks should be red
  • the r11 and r12 racks should be salmon (that intermediate color I mean)
  • the r04i00, r04i01, r05i00 and r05i01 don't exist (anymore?)
  • the r04i02, r05i02 and r08i00 racks should be yellow (except for those debug nodes in brown)

• Probably also good to double-check the FDR/QDR infiniband network rectangle.

Link to cloud docs

There seems to be no link to the cloud documentation from the general documentation.

Can that be added? @boegel ? @alvarosimon ? https://hpcugent.github.io/vsc_user_docs/cloud/

Change wording of FileZilla and WinSCP documentation on the hostname to use (cfr. PuTTY docs).

Currently, a generic, non-existant host name is used in both the screenshot and the text of the FileZilla documentation page.

Since this confuses users, it should be reworded similarly to what was done for PuTTY.

Additionally, the WinSCP documentation should be checked to see whether it has similar issues.

Add remark on screenshots to the information on how to request help.

Users tend to send screenshot of terminals, rather than simply copy/paste the text.

This makes the support staff's life harder, since, e.g., path names must be retyped, rather than simply copy/pasted from the helpdesk ticket.

Suggestion to use `cpus-per-gpu` instead of `ntasks` in slurm docs

In the documentation all examples use ntasks or n to specify the number of CPUs needed per GPU. This generally works fine, but external tools (such as submitit ) have a specific interpretation of ntasks, which can lead to issues. It might be better to explicitly use the cpus-per-gpu slurm option in the examples to avoid such issues. The options both work identically in my tests requesting GPUs on the debug node and on wice.

Separation of site-specific Slurm info (especially UAntwerpen)

Hi @backelj @RVerschoren (and others from UA):

I would like to clean up / improve the Slurm-related pages. One thing that catches the eye is that (probably for historic reasons) there is quite a bit of UAntwerpen-specific info on the following pages:

https://docs.vscentrum.be/jobs/job_submission.html
https://docs.vscentrum.be/jobs/job_types.html
https://docs.vscentrum.be/jobs/job_advanced.html

I think it would be better to move such info to somewhere in UAntwerp Tier-2 Infrastructure, possibly as part of 2.1.5. UAntwerp-specific software instructions :: Slurm workload manager. What do you think? If you're in favor but in lack of time, I can open a PR for this.

Revise superdome documentation

The first and second example may confuse the user, some clarification is required.

gquote

The documentation on the credits system mentions gquote, the utility to estimate the credits required to run a job.

gquote has not been updated in quite a while, and can not deal with jobs that use parts of nodes (nor regular, nor GPU).

Either gquote has to be updated, or we remove it from the documentation.

Opinions?

explicitely forbid users to use nx node as terminal

Add documentation on job dependencies

Job dependencies can be useful for certain workflows.

A mini how-to and a reference to the official documentation could be useful.

Update intel toolchain page for new compilers

Some of the information on https://docs.vscentrum.be/software/intel_toolchain.html only applies to the classic compilers like icc. It should be updated for the modern compilers like icx.

TurboVNC

At KU Leuven, TurboVNC is no longer used. I've removed all references to KU Leuven from pages on which it was mentioned.

I note that UAntwerp has its own page on its visualization nodes.

Do we still need to keep the following page?
./access/turbovnc_start_guide.rst

Add note on the anatomy of a job script

Although suggested by the documentation, it is nowhere stated explicitly that the order in a job script matters.

Verify Anaconda installation procedure for NX nodes

The procedure for installing Anaconda on the NX nodes explicitly refers to thinking. Is it still up-to-date?

Revise worker documentation, vis a vis job arrays

The worker documentation page has a remark on job arrays that is no longer accurate. This needs reformulation.

The page should also prominently refer to the official worker documentation.

The content should be reviewed with respect to current worker features.

Update OS versions on "Basic Linux Usage" page

Since we mention this page in the VSC user-day presentation, the first paragraph of https://docs.vscentrum.be/jobs/basic_linux_usage.html should be updated

Proxy configuration page

Do we need the following page?
https://vlaams-supercomputing-centrum-vscdocumentation.readthedocs-hosted.com/en/latest/access/setting_up_a_ssh_proxy_with_putty.html#ssh-proxy-with-putty

It was written back in the old days when muk was behind a firewall. Do we still have systems for which you need to set up a proxy using a login node?

The problem is that this page leads to no end of confusion from users who think they need to do this (and obviously don't), so I would be very happy if we could delete it.

Add a note on using screen/tmux

It would be useful to have a pointer to screen/tmux with an emphasis on session persistence to mitigate poor-quality network issues.

Since there are many good tutorials, there is no need for full-blown documentation, simply to point out these tools exist.

Tier-1 quickstart

A link to a PDF document that served as a quickstart to Tier-1 was sent to new Tier-1 users.

This document is out of date, too extensive, and should be available on the documentation site, rather than as a static document.

Add some info on MPT for superdome

Since Cerebro is decommissioned, there is no information available on MPT, SGI's (now HPE) MPI implementation.

It would be useful to add some notes on MPT to the page on superdome.

add need to request memory for superdome with the -L flag

In superdome if the user wants to use a ratio of mem/core higher than the default it is needed to specify the memory feature in the -L command. If this is not done when the job tries to use more than the default memory it will start swapping. In the manual of pbs in the numa section it is explicitily mention this behaviour:

http://docs.adaptivecomputing.com/torque/6-1-3/adminGuide/torque.htm#topics/NUMA/-Lresource.htm#options

So, for example to submit of a job using 7 cores and 100GB per core the jobs should be submitted as follows:

qsub -l partition=superdome -q qsuperdome - L tasks=1:lprocs=7:place=numanode=1:memory=700gb

generate proper sitemap.xml

current sitemap.xml only has a reference to the main page

Revise KU Leuven archive storage documentation

Do we need to add documentation for archive storage?