Merge pull request #37 from flindersuni/feature/conda-slurm-jupyterhub

Jupyter Conda & Linting Pass

docs/source/software/ansys.rst

@@ -1,23 +1,23 @@
 -------------------------
 ANSYS Engineering Suite 
 -------------------------
-=======
-Status
-=======
+=============
+ANSYS Status
+=============
 ANSYS 2021R2 is the current version of the ANSYS Suite installed on the HPC. Both Single-Node (-smp) and Multi-Node (-dis) execution is supported as well as GPU acceleration.
 
 
 .. _ANSYS: https://www.ansys.com/
 
-==========
-Overview 
-========== 
+===============
+ANSYS Overview 
+=============== 
 The ANSYS Engineering Suite is a comprehensive software suite for engineering simulation. More information on can be found on the `ANSYS`_ website.
 
 
-================================
-Quickstart Command Line Guide
-================================
+====================================
+ANSYS Quickstart Command Line Guide
+====================================
 
 To run a job with ANSYS on the HPC you will need the following: 
     - An ANSYS Script file 

docs/source/software/delft3d.rst

@@ -7,9 +7,11 @@ Status
 Delft3D 4, Revision 65936 is installed and available for use on the HPC.
 
 .. Delft3D: 
-==========
-Overview 
-========== 
+
+==================
+Delft3D Overview 
+==================
+
 From `Delft3D`_: 
 
 Delft3D is Open Source Software and facilitates the hydrodynamic (Delft3D-FLOW module), morphodynamic (Delft3D-MOR module), waves (Delft3D-WAVE module), water quality (Delft3D-WAQ module including the DELWAQ kernel) and particle (Delft3D-PART module) modelling
@@ -19,12 +21,12 @@ Delft3D is Open Source Software and facilitates the hydrodynamic (Delft3D-FLOW m
 Known Issues
 ================================
 
-Delft3D does **not** currently support Multi-Node Execution.  The binary swan_mpi.exe will _not work and immediately crash with errors_.
+Delft3D does **not** currently support Multi-Node Execution.  The binary swan_mpi.exe will *not work and immediately crash with errors*.
 
 
-+++++++++++++++++++++++++
++++++++++++++++++++++++++++++
 Delft3D Program Quick List
-+++++++++++++++++++++++++
++++++++++++++++++++++++++++++
 
 Below are two main binaries that are used as part of the Delft3D Suite
 

docs/source/software/gromacs.rst

@@ -1,15 +1,18 @@
 --------
 GROMACS 
 --------
-=======
-Status
-=======
+===============
+GROMACS Status
+===============
+
 GROMACS version 2021.5 is installed and available for use on the HPC.  
 
 .. _GROMACS: https://www.gromacs.org/
-==========
-Overview 
-========== 
+
+=================
+GROMACS Overview 
+=================
+
 From `GROMACS`_: 
 
 GROMACS is a versatile package to perform molecular dynamics, i.e. simulate the Newtonian equations of motion for systems with hundreds to millions of particles.
@@ -19,19 +22,19 @@ It is primarily designed for biochemical molecules like proteins, lipids and nuc
 GROMACS supports all the usual algorithms you expect from a modern molecular dynamics implementation.
 
 
-================================
-Quickstart Command Line Guide
-================================
+======================================
+GROMACS Quickstart Command Line Guide
+=======================================
 
 GROMACS uses UCX and will require a custom mpirun invocation. The module system will warn you of this when you load the module. The following is a known good starting point:
 
 
 ``mpirun -mca pml ucx --mca btl ^vader,tcp,uct -x UCX_NET_DEVICES=bond0 <program> <options>``
 
 
-+++++++++++++++++++++++++
++++++++++++++++++++++++++++
 GROMACS Program Quick List
-+++++++++++++++++++++++++
++++++++++++++++++++++++++++
 
 Below is a quick reference list of the different programs that make up the GROMACS suite.
 

docs/source/software/jupyter.rst

@@ -1,17 +1,18 @@
 ------------
 Jupyter Hub
 ------------
-=======
-Status
-=======
+==============
+Jupyter Status
+==============
 Released and accessible to all HPC USers at the correct URLs. 
 
 .. _Jupyter Enterprise Gateway: https://jupyter.org/hub
 .. _Jupyter URL: https://deepweb.flinders.edu.au/jupyter
 
-=========
-Overview
-=========
+====================
+Jupyter Hub Overview
+====================
+
 The `Jupyter Enterprise Gateway`_ is a multi-user environment for Jupyter Notebooks. DeepThought has integrated 
 the Jupyter Gateway to allow users to run jobs on the cluster via the native Web Interface.  
 
@@ -22,15 +23,41 @@ the same as the HPC, your FAN and password.
 If you are a student with access to the HPC, the above URLs may work - the URL http://deepteachweb.flinders.edu.au/jupyter is guaranteed to work correctly. 
 
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+========================================
 Using Conda Environments in Jupyter Hub
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can use your own custom environment in a Jupyter Kernel. To do so on the HPC via SLURM requires a few simple, extra steps. 
-
-
-1. Ensure you have a named conda environment that is loadable by ``conda activate <ENVIRONMENT_NAME>`` 
-2. Execute ``pip install cm-jupyter-eg-kernel-wlm``. You must use pip, as the package is not available via conda.
-3. Log into the HPC Jupyter instace at the `Jupyter URL`_.  
-4. Create a new Kernel, using the 'Conda via SLURM' Template. Ensure you change the environemnt from 'base' to the environment you wish to use. 
-5. Use this Kernel with your Jupyter Notebook
+========================================
+
+You can use your own custom environment in a Jupyter Kernel. There are some restrictions on python versions that must be adhered to for this integration to work 
+correctly. You will also need to install some specific packages. This process of enabling a conda environment to work with the HPC, SLURM and Jupyter Hub is detailed below. 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Python Version Restrictions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * Python Version <= 3.9.  
+
+Python 3.10 *will* **not** *work*, due to dependency incompatibility. 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Conda Environment Preparation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Ensure you have a named conda environment that is loadable by ``conda activate <ENVIRONMENT_NAME>``
+2. Ensure that the python version used by the environment is Python 3.9 or less.'
+3. Log ont the HPC via SSH and activate your Conda environment ``conda activate <ENVIRONMENT_NAME>`` 
+4. Execute the following commands: 
+    a. ``python3 -m pip install cm-jupyter-eg-kernel-wlm`` 
+    b. ``conda install ipython ipython_genutils``
+5. Log into Jupyter Hub with your FAN and password at the `Jupyter URL`_
+6. Using the bar on the Left-hand side, select small green symbol
+7. Create a new Kernel based on the 'CONDA via SLURM' template. 
+    a. Ensure you select any additional modules you need, like GDAL 
+    b. Ensure that you select the correct Conda environment to initialise 
+8. Use the Kernel in your Jupyter Notebooks
+
+For Reference, the below image shows the Kernel Template Screen. 
+
+.. figure:: ../_static/jupyter-kernel-template.png
+    :align: left
+    :alt: Jupyter Hub Kernel Template Screen
+

docs/source/software/lammps.rst

@@ -1,9 +1,10 @@
 ------------------
 LAMMPS
 ------------------
-=======
-Status
-=======
+==============
+LAMMPS Status
+==============
+
 LAMMPS was installed from the Development Branch on 7th Jan, 2022. 
 
 There are two versions of LAMMPS installed on DeepThought, each with their own modules:
@@ -17,7 +18,7 @@ There are two versions of LAMMPS installed on DeepThought, each with their own m
 
 
 =================
-Overview 
+LAMMPS Overview 
 =================
 From LAMMPS_:
 

docs/source/software/matlab.rst

@@ -1,9 +1,10 @@
 ------------------
 Mathworks MATLAB 
 ------------------
-=======
-Status
-=======
+===============
+MATLAB Status
+===============
+
 Matlab 2020b is the currently installed version on the HPC. 
 
 investigation is under way to enable tighter GUI integration and better workload management. 
@@ -13,7 +14,7 @@ investigation is under way to enable tighter GUI integration and better workload
 
 
 =================
-Overview 
+MATLAB Overview 
 =================
 `Mathworks MATLAB`_ is a leading mathematical analysis suite.  Coupled with their 
 Parallel Server, the new MATLAB Integration will enable the full power of DeepThought 

docs/source/software/singularity.rst

@@ -1,14 +1,16 @@
 ========================
 Singularity Containers
 ========================
---------
-Status
---------
+-------------------
+Singularity Status
+-------------------
+
 The Singularity Container Engine is available for use on the HPC. 
 
----------
-Overview
----------
+---------------------
+Singularity Overview
+----------------------
+
 .. _here: https://singularity.hpcng.org/user-docs/master/
 
 Singularity is the most common container engine used for HPC.  With the capability to run most container formats, including Docker, 

docs/source/software/vasp.rst

@@ -1,26 +1,28 @@
 -------------------------
 VASP
 -------------------------
-=======
-Status
-=======
+============
+VAPS Status
+============
+
 VASP: The Vienna Ab initio Simulation Package version 6.2.0 is operational with OpenACC GPU support on the HPC for the Standard, Gamma Ponit and Non-Collinear versions of the program. 
 
 .. _VASP: https://www.vasp.at/
 
-==========
-Overview 
-========== 
+===============
+VASP Overview 
+===============
+
 From `VASP`_:
 
 The Vienna Ab initio Simulation Package (VASP) is a computer program for atomic scale materials modelling, e.g. electronic structure calculations and quantum-mechanical molecular dynamics, from first principles.
 
 VASP computes an approximate solution to the many-body Schrödinger equation, either within density functional theory (DFT), solving the Kohn-Sham equations, or within the Hartree-Fock (HF) approximation, solving the Roothaan equations. Hybrid functionals that mix the Hartree-Fock approach with density functional theory are implemented as well. Furthermore, Green’s functions methods (GW quasiparticles, and ACFDT-RPA) and many-body perturbation theory (2nd-order Møller-Plesset) are available in VASP.
 
+====================================
+VAPS Quickstart Command Line Guide
+=====================================
 
-================================
-Quickstart Command Line Guide
-================================
 VASP must be started via the MPI wrapper script. If your SLURM Script has requested a GPU, VASP will autodetect and use the GPU for all supported operations. Substitute the VASP binary of your requirements.
 
 ``mpirun <MPI OPTIONS> vasp_std <OPTIONS>``