common ondemand docs (wip)

source/access/access_methods.rst

@@ -10,6 +10,7 @@
    windows_client
    macos_client
    linux_client
+   ondemand/index
 
 We provide multiple methods to access the VSC clusters and use their
 computational resources. Not all options may be equally supported across all
@@ -108,7 +109,7 @@ clusters. See below for guides on available solutions:
          :maxdepth: 1
 
          nx_start_guide
-         ../leuven/services/openondemand
+
 
 VPN
 ===

source/access/mfa_login.rst

@@ -8,7 +8,7 @@ As the name suggests, MFA requires additional steps with human intervention
 when authenticating.
 MFA is mandatory for accessing KU Leuven infrastructures.
 In this page, we explain how to login to the
-:ref:`KU Leuven Open OnDemand portal <ood_t2_leuven>`, and how to use SSH clients
+:ref:`KU Leuven Open OnDemand portal <ood_t2>`, and how to use SSH clients
 (such as PuTTY, terminal etc) with and without using an SSH agent.
 
 .. note::
@@ -20,7 +20,7 @@ Login to Open OnDemand
 ----------------------
 
 Users from all VSC sites can access the Open OnDemand portal at KU Leuven site.
-For that, proceed to the :ref:`Open OnDemand portal <ood_t2_leuven>`.
+For that, proceed to the :ref:`Open OnDemand portal <ood_t2>`.
 If you are affiliated with KU Leuven, click on the KU Leuven logo.
 Otherwise, click on the VSC logo to choose your institute.
 You will be then forwarded to the Identity Provider (IdP) of your institute to

source/access/ondemand/active-jobs.rst

@@ -0,0 +1,17 @@
+.. _ood_active_jobs:
+
+Active jobs
+-----------
+
+The 'Jobs - Active Jobs' menu item lists all your running, queued and completed jobs.
+Depending on the cluster, completed jobs will be removed from this view within a
+timeframe ranging from a few minutes to one day.  A handy overview of multiple job
+details is shown by clicking the large arrow at the left side of the job id,
+including the node list, the account you used, the status of the job, and more.
+It also gives you the option to open the job script directory in the file
+manager or in the terminal, and thus inspect the created output and error files.
+
+If your job is still running, you can also delete it by clicking the bin under
+'Actions'. Re-submitting a previous job can be done via the 'My Interactive
+Sessions' menu or in the :ref:`ood_job_composer`.
+

source/access/ondemand/desktop.rst

@@ -0,0 +1,39 @@
+Desktop
+-------
+
+The Desktop app will launch a light-weight (Xfce) desktop environment in an
+interactive job. Its main purpose is to run graphical software for which there
+isn’t (yet) an app available.
+
+VSC clusters that support the Desktop app:
+
+.. grid:: 3
+    :gutter: 4
+
+    .. grid-item-card:: |VUB|
+       :columns: 12 4 4 4
+
+       .. TODO use links
+
+       * Tier-2 Hydra
+       * Tier-2 Anansi
+
+
+For optimal performance, we recommend the following workflow:
+
+#. Launch the app in the ``Anansi`` cluster and request a GPU.
+#. In the desktop environment, open a terminal window and load the module of
+   your graphical software
+#. Launch the executable with ``vglrun`` to enable hardware acceleration:
+
+   .. code-block:: bash
+
+      vglrun <executable>
+
+.. tip::
+
+   Once the Desktop app is running, you can provide view-only access to other
+   VSC users. In the 'My Interactive Sessions' menu, right-click the 'View Only
+   (Share-able Link)' button to copy the link and share it with others. This
+   feature can be very useful for tasks like troubleshooting, pair programming,
+   and trainings.

source/access/ondemand/files.rst

@@ -0,0 +1,40 @@
+Files
+=====
+
+The 'Files' menu provides a file explorer that allows you to navigate through
+your files and folders. General file explorer options like moving, deleting,
+modifying and creating files or directories are available as well.
+
+.. tab-set::
+
+   .. tab-item:: KU Leuven/UHasselt
+
+      From the 'Files' menu, you can access your ``$VSC_HOME`` and ``$VSC_DATA``
+      folders.
+
+   .. tab-item:: VUB
+
+      From the 'Files' menu, you can access all ``$VSC_*`` folders available to
+      you.
+
+Download/upload
+---------------
+
+You can also use the Files interface to download and upload to and from
+your local machine. Be aware that this is not recommended for very large files.
+
+For large files we recommend the :ref:`globus platform`.  The ``Globus`` button
+takes you directly to the Globus login page, and upon a successful login to your
+Globus account (using your institution credentials), you will land on the same
+sub-directory from which you clicked on the Globus button.
+
+File editing
+------------
+
+You can edit a file via the button with 3 dots and a down arrow on the right
+side of the file.
+
+.. tip:: The standard ``ctrl+s`` keyboard shortcut does **not** save your edited
+   files on Open OnDemand, but will trigger a save on your local machine.
+   Luckily, there is a ``Save`` button in the upper left corner on the editor
+   page.

source/access/ondemand/index.rst

@@ -0,0 +1,74 @@
+.. _ood_t2:
+
+################################
+:fas:`circle-play` Open OnDemand
+################################
+
+Open OnDemand provides a user interface to HPC clusters from within a web browser.
+This tool supports a range of different apps and features that not only allow the
+user to easily submit jobs from within the browser, but also provide different
+coding GUIs, tools for plotting and more.
+
+Portals
+=======
+
+VSC clusters that support an Open OnDemand web portal:
+
+.. grid:: 3
+    :gutter: 4
+
+    .. grid-item-card:: |KUL|
+       :columns: 12 4 4 4
+
+       :fas:`circle-play` `KU Leuven OnDemand`_
+
+       * Tier-2 :ref:`Genius <Genius hardware>`
+       * Tier-2 :ref:`wICE <wICE hardware>`
+
+    .. grid-item-card:: |VUB|
+       :columns: 12 4 4 4
+
+       :fas:`circle-play` `VUB OnDemand`_
+
+       .. TODO fix links
+
+       * Tier-2 :ref:`Hydra <Hydra hardware>`
+       * Tier-2 Anansi
+
+.. _KU Leuven OnDemand: https://ondemand.hpc.kuleuven.be/
+.. _VUB OnDemand: https://portal.hpc.vub.be/
+
+You can log in using the credentials of your home institution or your VSC
+credentials.
+
+General features
+================
+
+The VSC Open OnDemand portals provide a range of functions:
+
+- Browsing, creating, transferring, viewing and/or editing files
+- Submitting and monitoring jobs, creating job templates
+- Opening a shell on one of the login nodes
+- Using interactive apps
+
+All of these functionalities can be accessed via the menu bar at the top of the
+page.  In the following sections, we will describe them in more detail.
+
+.. toctree::
+   :maxdepth: 1
+
+   files
+   login-shell
+   active-jobs
+   job-composer
+   interactive-apps
+   desktop
+   interactive-shell
+   jupyterlab
+   matlab
+   paraview
+   rstudio-server
+   tensorboard
+   vscode-server
+   vscode-tunnel
+

source/access/ondemand/interactive-apps.rst

@@ -0,0 +1,180 @@
+.. _ood_interactive_apps:
+
+Launching interactive apps
+==========================
+
+The 'Interactive Apps' menu shows a range of different apps that provide a GUI.
+When you launch an interactive app, Open Ondemand first submits an interactive
+job to the cluster in your account. Once the interactive job starts, the app is
+automatically launched inside the interactive session.
+
+To launch an interactive app, you need to fill out the resources form.
+Most of the options in the resources form are shared across all apps and are
+explained below. The app-specific options will be detailed in their respective
+sections.  See also the section on :ref:`choosing your resources
+<choosing_your_resources>` for resources recommendations.  Beware that by
+launching any app your interactive job will end up in a regular queue, so
+requesting a large amount of resources might result in a long queue time.
+
+Once you've specified all your resources, press the ``Launch`` button and your
+job will be queued.
+
+.. _shared_resources:
+
+.. list-table:: Shared resources (part 1)
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Resource
+     - Description
+   * - Cluster
+     - Select one of the supported clusters.
+   * - Partition
+     - Select a supported partition in the selected cluster.
+   * - Number of hours
+     - Select the time limit (in hours) for your interactive app session.
+   * - Number of nodes
+     - Select the amount of nodes. Only 1 node should be used in most cases,
+       unless you are sure the app *can and will* use more than 1 node
+       effectively.
+   * - Number of cores
+     - Select the amount of cores per node.
+   * - Number of GPUs
+     - Select the amount of GPUs per node. Check the :ref:`hardware` section for
+       the device type that corresponds to the selected cluster/partition. Only
+       request a GPU if you are sure the app *can and will* use the GPU
+       effectively.
+   * - Pre-run scriptlet
+     - Optionally add shell commands to your job before launching the app.
+       Examples: loading extra modules that you need within the app, sourcing a
+       specific script, or defining specific environment variable(s).
+
+.. warning::
+
+   Be careful when using the Pre-run scriptlet, because you will be modifying
+   the behavior of your session.
+
+.. tab-set::
+
+   .. tab-item:: KU Leuven/UHasselt
+
+      .. list-table:: Shared resources (part 2)
+         :header-rows: 1
+         :widths: 20 80
+
+         * - Resource
+           - Description
+         * - Account
+           - Select the credit account you want to deduct the credits from.  The
+             accounts associated with your VSC number will be displayed in a
+             dropdown menu.
+         * - Required memory per core in megabytes
+           - This defaults to 3400 MB.
+         * - Reservation
+           - If you are part of a reservation, you can also use these nodes with
+             Open Ondemand by specifying your reservation name here.
+         * - Screen resolution
+           - For apps which run inside a remote `noVNC`_ desktop (e.g. MATLAB,
+             ParaView, etc), one may choose a resolution between 'FullHD', '2K'
+             or '4K'.  After launching the app, one may still change the
+             compression level and the image quality of the transferred noVNC
+             frames.  E.g. opting for the lowest compression level and highest
+             image quality can give you a crisp noVNC desktop.
+         * - View Only (Share-able Link)
+           - For `noVNC`_ apps, you can provide a view-only access to other VSC
+             users.  For that, click on the 'View Only (Share-able Link)' button
+             to copy the URL into your clipboard, and be able to share it with
+             others.
+
+      .. note::
+
+         The acquired GPU will be the same as the type specified in the partition
+         (e.g. a NVidia H100 for ``gpu_h100`` on wICE).  For wICE, you can also
+         request a GPU from the ``interactive`` partition.
+         One GPU here is a virtual GPU slice of the available A100 GPUs.
+         One GPU slice is the same as 1/7th of CUDA cores and memory of an A100 GPU.
+         The interactive partition only allows you to request max 1 GPU (slice) though.
+
+      .. warning::
+
+         As the end-user, you are responsible for all consequences of sharing
+         your application with other VSC users.  So, think twice before
+         sharing your sensitive data, sources and information by all means.
+
+
+   .. tab-item:: VUB
+
+      .. list-table:: Shared resources (part 2)
+         :header-rows: 1
+         :widths: 20 80
+
+         * - Resource
+           - Description
+         * - Working Directory
+           - Specify the working directory for your app, or use the handy
+             ``Select Path`` button below the text field to select it from a
+             file browser.
+
+
+.. _choosing_your_resources:
+
+Choosing your resources
+-----------------------
+
+Choosing the correct resources for your interactive session is mostly the same
+as selecting them when launching regular batch jobs. For this reason, we
+strongly recommend consulting the documentation on how to effectively choose
+your job resources:
+
+.. tab-set::
+
+   .. tab-item:: KU Leuven/UHasselt
+
+      Documentation on resources is available for both :ref:`Genius
+      <running_jobs_on_genius>` and :ref:`wICE <running jobs on wice>`.
+
+      If requesting a GPU, it will be the same as the type specified in the
+      partition (e.g. a NVidia H100 for ``gpu_h100`` on wICE).  For wICE, you
+      can also request a GPU from the ``interactive`` partition.  One GPU here
+      is a virtual GPU slice of the available A100 GPUs.  One GPU slice is the
+      same as 1/7th of CUDA cores and memory of an A100 GPU.  The interactive
+      partition only allows you to request max 1 GPU (slice) though.
+
+      In most cases we recommend using the ``interactive`` partition on wICE for
+      the interactive apps.  This partition is meant for lighter work, like code
+      development, testing, debugging, visualisations, pre- and post-processing.
+      Using this partition is also free, mainly to encourage you to request
+      these resources for such work, instead of using any of the other
+      partitions. There are however some limitations on the amount of resources
+      you can request here:
+
+      - Max 1 node
+      - Max 8 cores
+      - Max 1 virtual GPU slice
+      - Max 16h of walltime
+
+      This is put in place to ensure that these resources are kept for their
+      original purpose, namely the interactive work.
+
+      If for some reason some of these limitations are too strict for you, or
+      you need resources that are not available on the interactive nodes (e.g. a
+      full GPU, big memory nodes), you can always request nodes from another
+      partition.  Remember however that these interactive apps are not meant for
+      running full jobs.  If you indeed need multiple nodes or full GPUs to test
+      your code/program, go ahead and request the resources for your interactive
+      app from a more suitable partition.
+
+   .. tab-item:: VUB
+
+      Documentation on resources is available in the section on `job submission
+      <https://hpc.vub.be/docs/job-submission/>`_.
+
+      For light-weight (testing) work, we recommend using the ``Anansi``
+      cluster, which also contains 4 shared GeForce GTX 1080 Ti GPUs for
+      improved rendering performance.
+
+Once you have passed the testing phase, and you want to start conducting
+experiments, we recommend that you make the switch to batch jobs instead, as
+they will not require your presence to start your code.
+
+.. _noVNC: https://novnc.com/