Updates to mkdocs version

.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install \
+              mkdocs-material \
+              pymdown-extensions
+      - run: git fetch -u origin gh-pages:gh-pages
+      - run: mkdocs gh-deploy --force

LICENSE.txt

@@ -0,0 +1,34 @@
+CC BY 4.0
+
+Attribution 4.0 International (CC BY 4.0)
+
+This is a human-readable summary of (and not a substitute for) the license
+(https://creativecommons.org/licenses/by/4.0/legalcode).
+
+You are free to:
+
+   - Share — copy and redistribute the material in any medium or format
+   - Adapt — remix, transform, and build upon the material
+
+for any purpose, even commercially.
+
+This license is acceptable for Free Cultural Works.
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+Under the following terms:
+
+   - Attribution — You must give appropriate credit, provide a link to the license, and
+   indicate if changes were made. You may do so in any reasonable manner, but not in any
+   way that suggests the licensor endorses you or your use.
+
+   - No additional restrictions — You may not apply legal terms or technological measures
+   that legally restrict others from doing anything the license permits.
+
+Notices:
+
+You do not have to comply with the license for elements of the material in the public domain
+or where your use is permitted by an applicable exception or limitation. No warranties are
+given. The license may not give you all of the permissions necessary for your intended use.
+For example, other rights such as publicity, privacy, or moral rights may limit how you use 
+the material.

README.md

@@ -0,0 +1,64 @@
+# Cirrus Documentation
+
+Cirrus is EPCC's Tier-2 High Performance Computing (HPC) cluster.
+
+This repository contains the documentation for the service and is linked
+to a rendered version on  Github pages.
+
+This documentation is drawn from the [Sheffield Iceberg
+documentation](https://github.com/rcgsheffield/sheffield_hpc) and the
+[ARCHER](http://www.archer.ac.uk) documentation.
+
+## Rendered Documentation
+
+  - [Cirrus Documentation (HTML)](https://docs.cirrus.ac.uk)
+
+## How to Contribute
+
+
+We welcome contributions from the Cirrus community and beyond. Contributions can take many different
+forms, some examples are:
+
+- Raising Issues if you spot a mistake or something that could be improved
+- Adding/updating material via a Pull Request
+- Adding your thoughts and ideas to any open issues
+
+All people who contribute and interact via this Github repository undertake to abide by the
+[ARCHER2 Code of Conduct](https://www.archer2.ac.uk/about/policies/code-of-conduct.html) so that
+we, as a community, provide a welcoming and supportive environment for
+all people, regardless of background or identity.
+
+To contribute content to this documentation, first you have to fork it
+on GitHub and clone it to your machine, see [Fork a
+Repo](https://help.github.com/articles/fork-a-repo/) for the GitHub
+documentation on this process.
+
+Once you have the git repository locally on your computer, you will need
+to [install Material for mkdocs](https://squidfunk.github.io/mkdocs-material/getting-started/)
+to be able to build the documentation. This can be done using a local installation
+or using a Docker container.
+
+Once you have made your changes and updated your Fork on GitHub you will
+need to [Open a Pull
+Request](https://help.github.com/articles/using-pull-requests/).
+
+### Building the documentation on a local machine
+
+Once Material for mkdocs is installed, you can preview the site locally using the
+[instructions in the Material for mkdocs documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write).
+
+
+## Making changes and style guide
+
+The documentation consists of a series of Markdown files which have the `.md`
+extension. These files are then automatically converted to HTMl and
+combined into the web version of the documentation by mkdocs. It is
+important that when editing the files the syntax of the Markdown files is
+followed. If there are any errors in your changes the build will fail
+and the documentation will not update, you can test your build locally
+by running `mkdocs serve`. The easiest way to learn what files should look
+like is to read the Markdown files already in the repository.
+
+A short list of style guidance:
+
+  - Headings should be in sentence case

STYLE_GUIDE.md

@@ -0,0 +1,16 @@
+Web site style guide
+=================
+
+All images much have an Alt Text included.  If the image is purely decorative then use a blank tag i.e. `alt=""`
+
+All hyperlinks should be descriptive text, or an image with a descriptive Alt Text, indicating where the link will take the reader.
+Hyperlinks should not be "Click here", nor should they be the raw html link.
+
+All pages should have a H1 heading - this is generally part of each page's template.  
+Subsequent headings should be incremental without gaps i.e. the next level heading should be H2 not a jump to H3.
+
+Headings should generally be written in 'Sentence case.'
+
+[Princeton's guide to accessible web content](https://accessibility.princeton.edu/guidelines/web#accessible-content) is a very good, brief guide to Authoring accessible content.
+
+The [WAVE web accessibility evaluation tool](https://wave.webaim.org/) is very useful - Browser extensions are available for Chrome, Firefox and Edge to check pages instantly for issues.

docs/CNAME

@@ -0,0 +1 @@
+docs.cirrus.ac.uk

docs/index.md

@@ -0,0 +1,39 @@
+<img src="images/epcc_uoe_epsrc.png" class="align-right" alt="image" align="right" />
+
+# Cirrus
+
+Cirrus is a HPC and data science service hosted and run by
+[EPCC](http://www.epcc.ed.ac.uk) at [The University of
+Edinburgh](http://www.ed.ac.uk). It is one of the
+[EPSRC](http://www.epsrc.ac.uk) Tier-2 National HPC Services.
+
+Cirrus is available to industry and academic researchers. For
+information on how to get access to the system please see the [Cirrus
+website](http://www.cirrus.ac.uk).
+
+The Cirrus facility is based around an SGI ICE XA system. There are 280
+standard compute nodes and 38 GPU compute nodes. Each standard compute
+node has 256 GiB of memory and contains two 2.1 GHz, 18-core Intel Xeon
+(Broadwell) processors. Each GPU compute node has 384 GiB of memory,
+contains two 2.4 GHz, 20-core Intel Xeon (Cascade Lake) processors and
+four NVIDIA Tesla V100-SXM2-16GB (Volta) GPU accelerators connected to
+the host processors and each other via PCIe. All nodes are connected
+using a single Infiniband fabric. This documentation covers:
+
+- Cirrus User Guide: general information on how to use Cirrus
+- Software Applications: notes on using specific software applications
+  on Cirrus
+- Software Libraries: notes on compiling against specific libraries on
+  Cirrus. Most libraries work *as expected* so no additional notes are
+  required however a small number require specific documentation
+- Software Tools: Information on using tools such as debuggers and
+  profilers on Cirrus
+
+Information on using the SAFE web interface for managing and reporting
+on your usage on Cirrus can be found on the [Tier-2 SAFE
+Documentation](http://tier2-safe.readthedocs.io/en/latest/)
+
+This documentation draws on the
+documentation for the [ARCHER2 National Supercomputing
+Service](http://docs.archer2.ac.uk).
+

docs/software-libraries/hdf5.md

@@ -0,0 +1,16 @@
+# HDF5
+
+Serial and parallel versions of HDF5 are available on Cirrus.
+
+| Module name                        | Library version | Compiler  | MPI library  |
+|------------------------------------|-----------------|-----------|--------------|
+| hdf5parallel/1.10.4-intel18-impi18 | 1.10.4          | Intel 18  | Intel MPI 18 |
+| hdf5parallel/1.10.6-intel18-mpt222 | 1.10.6          | Intel 18  | HPE MPT 2.22 |
+| hdf5parallel/1.10.6-intel19-mpt222 | 1.10.6          | Intel 19  | HPE MPT 2.22 |
+| hdf5parallel/1.10.6-gcc6-mpt222    | 1.10.6          | GCC 6.3.0 | HPE MPT 2.22 |
+
+
+
+Instructions to install a local version of HDF5 can be found on this
+repository:
+<https://github.com/hpc-uk/build-instructions/tree/main/utils/HDF5>

docs/software-libraries/intel_mkl.md

@@ -0,0 +1,112 @@
+# Intel MKL: BLAS, LAPACK, ScaLAPACK
+
+The Intel Maths Kernel Libraries (MKL) contain a variety of optimised
+numerical libraries including BLAS, LAPACK, and ScaLAPACK. In general,
+the exact commands required to build against MKL depend on the details
+of compiler, environment, requirements for parallelism, and so on. The
+Intel MKL link line advisor should be consulted.
+
+See
+<https://software.intel.com/content/www/us/en/develop/articles/intel-mkl-link-line-advisor.html>
+
+Some examples are given below. Note that loading the appropriate intel
+tools module will provide the environment variable
+<span class="title-ref">MKLROOT</span> which holds the location of the
+various MKL components.
+
+## Intel Compilers
+
+### BLAS and LAPACK
+
+To use MKL libraries with the Intel compilers you just need to load the
+relevant Intel compiler module, and the Intel `cmkl` module, e.g.:
+
+    module load intel-20.4/fc
+    module load intel-20.4/cmkl
+
+To include MKL you specify the `-mkl` option on your compile and link
+lines. For example, to compile a simple Fortran program with MKL you
+could use:
+
+    ifort -c -mkl -o lapack_prb.o lapack_prb.f90
+    ifort -mkl -o lapack_prb.x lapack_prb.o
+
+The `-mkl` flag without any options builds against the threaded version
+of MKL. If you wish to build against the serial version of MKL, you
+would use `-mkl=sequential`.
+
+### ScaLAPACK
+
+The distributed memory linear algebra routines in ScaLAPACK require MPI
+in addition to the compiler and MKL libraries. Here we use Intel MPI
+via:
+
+    module load intel-20.4/fc
+    module load intel-20.4/mpi
+    module load intel-20.4/cmkl
+
+ScaLAPACK requires the Intel versions of BLACS at link time in addition
+to ScaLAPACK libraries; remember also to use the MPI versions of the
+compilers:
+
+    mpiifort -c -o linsolve.o linsolve.f90
+    mpiifort -o linsolve.x linsolve.o -L${MKLROOT}/lib/intel64 \
+    -lmkl_scalapack_lp64 -lmkl_intel_lp64 -lmkl_sequential -lmkl_core \
+    -lmkl_blacs_intelmpi_lp64 -lpthread -lm -ldl
+
+## GNU Compiler
+
+### BLAS and LAPACK
+
+To use MKL libraries with the GNU compiler you first need to load the
+GNU compiler module and Intel MKL module, e.g.,:
+
+    module load gcc
+    module load intel-20.4/cmkl
+
+To include MKL you need to link explicitly against the MKL libraries.
+For example, to compile a single source file Fortran program with MKL
+you could use:
+
+    gfortran -c -o lapack_prb.o lapack_prb.f90
+    gfortran -o lapack_prb.x lapack_prb.o -L$MKLROOT/lib/intel64 \
+    -lmkl_gf_lp64 -lmkl_core -lmkl_sequential
+
+This will build against the serial version of MKL; to build against the
+threaded version use:
+
+    gfortran -c -o lapack_prb.o lapack_prb.f90
+    gfortran -fopenmp -o lapack_prb.x lapack_prb.o -L$MKLROOT/lib/intel64 \
+    -lmkl_gf_lp64 -lmkl_core -lmkl_gnu_thread
+
+### ScaLAPACK
+
+The distributed memory linear algebra routines in ScaLAPACK require MPI
+in addition to the MKL libraries. On Cirrus, this is usually provided by
+SGI MPT.
+
+    module load gcc
+    module load mpt
+    module load intel-20.4/cmkl
+
+Once you have the modules loaded you need to link against two additional
+libraries to include ScaLAPACK. Note we use here the relevant
+`mkl_blacs_sgimpt_lp64` version of the BLACS library. Remember to use
+the MPI versions of the compilers:
+
+    mpif90 -f90=gfortran -c -o linsolve.o linsolve.f90
+    mpif90 -f90=gfortran -o linsolve.x linsolve.o -L${MKLROOT}/lib/intel64 \
+    -lmkl_scalapack_lp64 -lmkl_intel_lp64 -lmkl_sequential -lmkl_core \
+    -lmkl_blacs_sgimpt_lp64 -lpthread -lm -ldl
+
+### ILP vs LP interface layer
+
+Many applications will use 32-bit (4-byte) integers. This means the MKL
+32-bit integer interface should be selected (which gives the `_lp64`
+extensions seen in the examples above).
+
+For applications which require, e.g., very large array indices (greater
+than 2^31-1 elements), the 64-bit integer interface is required. This
+gives rise to `_ilp64` appended to library names. This may also require
+`-DMKL_ILP64` at the compilation stage. Check the Intel link line
+advisor for specific cases.