Grace-Hopper non-pilot documentation

_static/css/custom.css

@@ -22,12 +22,14 @@
   --n8-dark-theme-text-color: #F0F6FC;
   --n8-dark-theme-text-color-muted: #9ca4af;
   --n8-dark-theme-inline-code-background-color: #1f2733;
+  --sphinx-tabs-tab-color: var(--pst-color-primary);
+  --sphinx-tabs-background-color: var(--pst-color-surface);
+  --sphinx-tabs-border-color: var(--pst-color-primary);
 }
 
 /* -----------------------------------------
   Non-theme specific / universal css changes
   ------------------------------------------*/
-
 html {
   --pst-sidebar-font-size: 1.0rem;
 }
@@ -90,6 +92,30 @@ body {
     max-width:1600px
   }
 }
+/* Sphinx tabs theming via variables for easier light/dark theming */
+html .sphinx-tabs-tab {
+  color: var(--sphinx-tabs-tab-color);
+  background-color: var(--sphinx-tabs-background-color);
+}
+html .sphinx-tabs-tab[aria-selected="true"] {
+  border-color: var(--sphinx-tabs-border-color);
+  border-bottom-color: var(--sphinx-tabs-background-color);
+  background: var(--sphinx-tabs-background-color);
+}
+html .sphinx-tabs-panel {
+  background: var(--sphinx-tabs-background-color);
+  border-color: var(--sphinx-tabs-border-color);
+}
+html [role="tablist"] {
+  border-bottom-color: var(--sphinx-tabs-border-color);
+}
+html .sphinx-tabs-panel pre {
+  background-color: var(--color-surface-tabs);
+}
+/* Fix right border of selected tab from being hidden */
+.sphinx-tabs-tab[aria-selected="true"] {
+  z-index: 2;
+}
 
 /* --------------------------------------
   Light theme specific formatting changes
@@ -100,11 +126,13 @@ html[data-theme="light"] {
   --pst-color-text-muted: var(--n8-light-theme-text-color-muted);
   --pst-color-primary: var(--n8-deep-blue-color);
   --pst-color-secondary: var(--n8-burnt-orange-color-high-contrast-light);
+  --pst-color-warning: var(--n8-burnt-orange-color-high-contrast-light);
   --pst-color-accent: var(--n8-burnt-orange-color-high-contrast-light);
   --pst-color-inline-code: var(--n8-burnt-orange-color-high-contrast-light);
   --pst-color-link: var(--n8-deep-blue-color);
   --pst-color-preformatted-background: var(--pygments-default-background-color);
   --sbt-color-announcement: var(--n8-deep-blue-color);
+  --color-surface-tabs: #fcfcfc;
 }
 /* Override the default sphinx book theme announcement colour */
 html[data-theme="light"] .bd-header-announcement a {
@@ -126,6 +154,20 @@ html[data-theme="light"] .bd-article-container h4
 html[data-theme="light"] .bd-article-container h5 {
   color: var(--n8-deep-blue-color);
 }
+/* Sphinx-tabs light/dark themed styling tweaks */ 
+/* html[data-theme="light"] .sphinx-tabs-tab {
+  color: var(--pst-color-primary);
+  background-color: #0f0;
+}
+html[data-theme="light"] .sphinx-tabs-tab[aria-selected="true"] {
+  border-color: #ff0;
+  border-bottom-color: #00F;
+  background: #00f;
+}
+html[data-theme="light"] .sphinx-tabs-panel {
+  background: #00cccc;
+} */
+
 
 /* -------------------------------------
   Dark theme specific formatting changes
@@ -136,13 +178,12 @@ html[data-theme="dark"] {
   --pst-color-text-muted: var(--n8-dark-theme-text-color-muted);
   --pst-color-primary: var(--n8-deep-blue-color-high-contrast-dark);
   --pst-color-secondary: var(--n8-burnt-orange-color);
+  --pst-color-warning: var(--n8-burnt-orange-color);
   --pst-color-accent: var(--n8-burnt-orange-color);
   --pst-color-surface: var(--n8-dark-theme-inline-code-background-color); /* inline code block background colour */
   --pst-color-inline-code: var(--n8-burnt-orange-color);
   --pst-color-link: var(--n8-deep-blue-color-high-contrast-dark);
-   /* var(--n8-deep-blue-color); */
-  /* --pst-color-preformatted-background: var(--pygments-default-background-color); */
-  --sbt-color-announcement: var(--n8-deep-blue-color);
+  --color-surface-tabs: #181e27;
 }
 /* Override the default sphinx book theme announcement colour */
 html[data-theme="dark"] .bd-header-announcement a {

_static/js/custom.js

@@ -4,10 +4,12 @@ so cannot use sphinx :ref: for output destination URIs relative to the current p
 Instead, find the appropriate link within the current page, to add the anchor to the announcement.
 This does not currently support linking outside of the documentation website.
 */
-/* window.onload = function () {
-    expectedAnnouncementContent = "";
-    expectedAnchorContent = "";
-    var elements = document.getElementsByClassName("announcement");
+ window.onload = function () {
+    expectedAnnouncementContent = "Using Bede";
+    expectedAnchorContent = "Using Bede";
+    optionalTargetID = "grace-hopper-pilot"; // null if linking to page
+    fullAnnouncementAnchor = false;
+    var elements = document.getElementsByClassName("bd-header-announcement");
     for (var i = 0; i < elements.length; i++) {
         var element = elements.item(i);
         originalContent = element.innerHTML;
@@ -28,10 +30,16 @@ This does not currently support linking outside of the documentation website.
                         // then append the optionalTargetID, which should no longer begin with a hash.
                         targetDestination += optionalTargetID;
                     }
-                    newAnnouncementContent = '<a href="' + targetDestination + '">' + originalContent + '</a>'
-                    element.innerHTML = newAnnouncementContent;
+                    // Either wrap the full announcement body in the anchor, or just the expected anchor content
+                    if (fullAnnouncementAnchor) {
+                        newAnnouncementContent = '<a href="' + targetDestination + '">' + originalContent + '</a>'
+                        element.innerHTML = newAnnouncementContent;
+                    } else {
+                        newAnnouncementContent = originalContent.replace(expectedAnchorContent, '<a href="' + targetDestination + '">' + expectedAnchorContent + '</a>')
+                        element.innerHTML = newAnnouncementContent;
+                    }
                 }
             }
         }
     }
-} */
+}

common/aarch64-only-sidebar.rst

@@ -0,0 +1,4 @@
+.. admonition:: aarch64 partitions only
+    :class: sidebar warning
+
+    |arch_availabilty_name| is only provided on ``aarch64`` partitions (``gh``, ``ghtest``, ``ghlogin``).

common/aarch64-only.rst

@@ -0,0 +1,4 @@
+.. admonition:: aarch64 partitions only
+    :class: warning
+
+    |arch_availabilty_name| is only provided on ``aarch64`` partitions (``gh``, ``ghtest``, ``ghlogin``).

common/ppc64le-only-sidebar.rst

@@ -0,0 +1,4 @@
+.. admonition:: ppc64le partitions only
+    :class: sidebar warning
+
+    |arch_availabilty_name| is only provided on ``ppc64le`` partitions/nodes (``gpu``, ``infer``, ``test``).

common/ppc64le-only.rst

@@ -0,0 +1,4 @@
+.. admonition:: ppc64le partitions only
+    :class: warning
+
+    |arch_availabilty_name| is only provided on ``ppc64le`` partitions/nodes (``gpu``, ``infer``, ``test``).

conf.py

@@ -11,7 +11,8 @@
 extensions = [
     "sphinxext.rediraffe",
     'sphinx.ext.mathjax',
-    'sphinx_copybutton'
+    'sphinx_copybutton',
+    'sphinx_tabs.tabs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,6 +53,9 @@
 ## Added by CA to get MathJax rendering loaded
 mathjax_path='https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'
 
+# Disable sphinx-tabs closing
+sphinx_tabs_disable_tab_closing = True
+
 # -- Options for HTML output ----------------------------------------------
 
 html_theme = 'sphinx_book_theme'
@@ -81,6 +85,7 @@
     "home_page_in_toc": False,
     "show_navbar_depth": 1,  # Sets the depth for expanded content
     # Control the right hand in-page toc
+    "navigation_with_keys": False,
     "toc_title": "Contents",
     "show_toc_level": 2,
     "show_prev_next": False,
@@ -89,7 +94,7 @@
     # Code highlighting theme for dark mode
     "pygment_dark_style": "github-dark-high-contrast",
     # Add an announcement bar, visible at the top of each page.
-    "announcement": "",
+    "announcement": "3 NVIDIA Grace-Hopper nodes (GH200 480) are now available. See Using Bede for more information.",
     # Add the traditional footer theme and sphinx acknowledgements
     "extra_footer": f"<p>&nbsp;Built with <a href=\"http://sphinx-doc.org/\">Sphinx</a> {sphinx.__version__} using a theme by the <a href=\"https://ebp.jupyterbook.org/\">Executable Book Project</a>.</p>"
 }

faq/index.rst

@@ -137,3 +137,26 @@ find the support email address for your institution `on the N8CIR website
 There is also a `slack workspace <https://n8cirbede.slack.com>`__ that you can join to get further support and
 contact the Bede user community. To request access, please e-mail: [email protected].
 
+.. _faq-architecture-specific-eng:
+
+How do I specialise my bash environment for Power 9 and Grace-Hopper systems?
+-----------------------------------------------------------------------------
+
+If you have modified your Bede user environment (``.bashrc``, or ``.bash_profile``) to make software available by default (i.e. conda),
+you may need to modify your environment to set environment variables or source scripts based on the CPU architecture.
+
+You can check the CPU architecture in bash using the ``uname`` command.
+
+This allows you to set different environment variables on the ``aarch64`` Grace-Hopper nodes than on the ``ppc64le`` Power 9 nodes:
+
+.. code-block:: bash
+
+   # Get the CPU architecture
+   arch=$(uname -i)
+   if [[ $arch == "aarch64" ]]; then
+      # Set variables and source scripts for aarch64
+       export MYVAR=FOO
+   elif [[ $arch == "ppc64le" ]]; then
+      # Set variables and source scripts for ppc64le
+       export MYVAR=BAR
+   fi

requirements.txt

@@ -3,3 +3,4 @@ sphinx-book-theme==1.1.2
 sphinx-autobuild
 sphinxext-rediraffe
 sphinx-copybutton
+sphinx-tabs==3.4.5

software/applications/amber.rst

@@ -1,7 +1,10 @@
 .. _software-applications-amber:
 
 AMBER
--------
+-----
+
+.. |arch_availabilty_name| replace:: AMBER
+.. include:: /common/ppc64le-only-sidebar.rst
 
 `AMBER <https://ambermd.org/>`__ is a suite of biomolecular simulation programs. It began in the late 1970's, and is maintained by an active development community.
 

software/applications/conda.rst

@@ -15,29 +15,61 @@ The simplest way to install Conda for use on Bede is through the `miniconda <htt
 
 .. note::
 
-    You may wish to install conda into the ``/nobackup/projects/<project>/$USER`` (where ``project`` is the project code for your project) directory rather than your ``home`` directory as it may consume considerable disk space
+    You may wish to install conda into the ``/nobackup/projects/<project>/$USER/<architecture>`` (where ``<project>`` is the project code for your project, and ``<architecture>>`` is CPU architecture) directory rather than your ``home`` directory as it may consume considerable disk space
 
-.. code-block:: bash
+.. tabs::
+
+   .. code-tab:: bash ppc64le
+
+      export CONDADIR=/nobackup/projects/<project>/$USER/ppc64le # Update this with your <project> code.
+      mkdir -p $CONDADIR
+      pushd $CONDADIR
 
-   export CONDADIR=/nobackup/projects/<project>/$USER # Update this with your <project> code.
-   mkdir -p $CONDADIR
-   pushd $CONDADIR
+      # Download the latest miniconda installer for ppc64le
+      wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-ppc64le.sh
+      # Validate the file checksum matches is listed on https://docs.conda.io/en/latest/miniconda_hashes.html.
+      sha256sum Miniconda3-latest-Linux-ppc64le.sh
+
+      sh Miniconda3-latest-Linux-ppc64le.sh -b -p ./miniconda
+      source miniconda/etc/profile.d/conda.sh
+      conda update conda -y
+
+   .. code-tab:: bash aarch64
 
-   # Download the latest miniconda installer for ppcle64
-   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-ppc64le.sh
-   # Validate the file checksum matches is listed on https://docs.conda.io/en/latest/miniconda_hashes.html.
-   sha256sum Miniconda3-latest-Linux-ppc64le.sh
+      export CONDADIR=/nobackup/projects/<project>/$USER/aarch64 # Update this with your <project> code.
+      mkdir -p $CONDADIR
+      pushd $CONDADIR
 
-   sh Miniconda3-latest-Linux-ppc64le.sh -b -p ./miniconda
-   source miniconda/etc/profile.d/conda.sh
-   conda update conda -y
+      # Download the latest miniconda installer for aarch64
+      wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
+      # Validate the file checksum matches is listed on https://docs.conda.io/en/latest/miniconda_hashes.html.
+      sha256sum Miniconda3-latest-Linux-aarch64.sh
+
+      sh Miniconda3-latest-Linux-aarch64.sh -b -p ./miniconda
+      source miniconda/etc/profile.d/conda.sh
+      conda update conda -y
 
 On subsequent sessions, or in job scripts you may need to re-source miniconda. Alternatively you could add this to your bash environment. I.e. 
 
-.. code-block:: bash
+.. tabs::
+
+   .. code-tab:: bash ppc64le
+
+      arch=$(uname -i) # Get the CPU architecture
+      if [[ $arch == "ppc64le" ]]; then
+         # Set variables and source scripts for ppc64le
+         export CONDADIR=/nobackup/projects/<project>/$USER/ppc64le # Update this with your <project> code.
+         source $CONDADIR/miniconda/etc/profile.d/conda.sh
+      fi
 
-    export CONDADIR=/nobackup/projects/<project>/$USER # Update this with your <project> code.
-    source $CONDADIR/miniconda/etc/profile.d/conda.sh
+   .. code-tab:: bash aarch64
+
+      arch=$(uname -i) # Get the CPU architecture
+      if [[ $arch == "aarch64" ]]; then
+         # Set variables and source scripts for aarch64
+         export CONDADIR=/nobackup/projects/<project>/$USER/aarch64 # Update this with your <project> code.
+         source $CONDADIR/miniconda/etc/profile.d/conda.sh
+      fi
 
 Creating a new Conda Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,17 +90,17 @@ Once created, the environment can be activated using ``conda activate``.
 
 Alternatively, Conda environments can be created outside of the conda/miniconda install, using the ``-p`` / ``--prefix`` option of ``conda create``. 
 
-I.e. if you have installed miniconda to your home directory, but wish to create a conda environment within the ``/project/<PROJECT>/$USER/`` directory named ``example`` you can use:
+I.e. if you have installed miniconda to your home directory, but wish to create a conda environment within the ``/project/<PROJECT>/$USER/<architecture>/`` directory named ``example`` you can use:
 
 .. code-block:: bash
 
-   conda create -y --prefix /project/<PROJECT>/$USER/example python=3.9
+   conda create -y --prefix /project/<PROJECT>/$USER/<architecture>/example python=3.9
 
 This can subsequently be loaded via:
 
 .. code-block:: bash
 
-   conda activate /project/<PROJECT>/$USER/example
+   conda activate /project/<PROJECT>/$USER/<architecture>/example
 
 Listing and Activating existing Conda Environments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

software/applications/eman2.rst

@@ -3,6 +3,9 @@
 EMAN2
 =====
 
+.. |arch_availabilty_name| replace:: EMAN2
+.. include:: /common/ppc64le-only-sidebar.rst
+
 `EMAN2 <https://blake.bcm.edu/emanwiki/EMAN2>`__ is a broadly based greyscale scientific image processing suite with a primary focus on processing data from transmission electron microscopes.
 
 On Bede, EMAN2 is provided by the :ref:`IBM Collaboration project <software-projects-ibm-collaboration>`.

software/applications/grace.rst

@@ -3,6 +3,9 @@
 Grace
 -----
 
+.. |arch_availabilty_name| replace:: Grace
+.. include:: /common/ppc64le-only-sidebar.rst
+
 `Grace <https://plasma-gate.weizmann.ac.il/Grace/>`__ Grace is a WYSIWYG 2D plotting tool for the X Window System.
 
 On Bede, the batch-printing component of Grace, ``gracebat`` is provided via an environment module:

software/applications/gromacs.rst

@@ -3,6 +3,9 @@
 GROMACS
 -------
 
+.. |arch_availabilty_name| replace:: GROMACS
+.. include:: /common/ppc64le-only-sidebar.rst
+
 `GROMACS <http://www.gromacs.org/About_Gromacs>`__ is a versatile package for molecular dynamics simulation.
 It is primarily designed for biochemical molecules like proteins, lipids and nucleic acids that have a lot of complicated bonded interactions, but since GROMACS is extremely fast at calculating the nonbonded interactions (that usually dominate simulations) many groups are also using it for research on non-biological systems, e.g. polymers.
 

software/applications/index.rst

@@ -9,6 +9,18 @@ If you notice any omissions, errors or have any suggested changes to the documen
 
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    *
+    amber.rst
+    conda.rst
+    eman2.rst
+    grace.rst
+    gromacs.rst
+    namd.rst
+    open-ce.rst
+    openmm.rst
+    python.rst
+    pytorch.rst
+    r.rst
+    rust.rst
+    tensorflow.rst
+

software/applications/namd.rst

@@ -3,6 +3,9 @@
 NAMD
 ----
 
+.. |arch_availabilty_name| replace:: NAMD
+.. include:: /common/ppc64le-only-sidebar.rst
+
 `NAMD <https://www.ks.uiuc.edu/Research/namd/>`__ is a parallel molecular dynamics code designed for high-performance simulation of large biomolecular systems.
 Based on Charm++ parallel objects, NAMD scales to hundreds of cores for typical simulations and beyond 500,000 cores for the largest simulations.