View source for Jupyter OOD

=Launching a JupyterLab server via Open on Demand=

{{Note|Open on Demand is only accessible from the UF network. Use the [https://vpn.ufl.edu VPN] if off campus.|warn}}

[[Open OnDemand|Open on Demand]] is a service that provides web-based access to HiPerGator, including Jupyter Lab and Jupyter Notebooks.

==Connect to https://ood.rc.ufl.edu ==
* Using your web browser navigate to https://ood.rc.ufl.edu/ and login with your GatorLink credentials.
* See the [[Open OnDemand|Open on Demand]] for information on file management, shell access and other features available from Open on Demand.

==Select Jupyter Notebook from the interactive Apps Menu and fill out form ==
* From the Interactive Apps menu, select '''Jupyter Notebook''' from the Servers section of the menu near the bottom. [[File:OOD JupyterServer.png|150px]]
* The next page presents a form with many options for scheduling your job.
[[File:OOD SLURM options 01.png|300px|frameless|right]]
* Settings of particular importance:
**'''Number of CPU cores requested per MPI task (--cpus-per-task, -p)''': How many CPU cores do you want? Most Python Notebooks will only use a single CPU core, so requesting more is generally not needed. If you are using multiple cores, set the number here.
**'''Maximum memory requested for this job in Gigabytes (--mem, -m)''': How much memory should be allocated to your job. This should be a reasonable estimate of the amount of memory (RAM) that you will use during your session in GB. If you experience Jupyter Kernels dying while running your notebooks, this may be an indication of not having enough memory. Restarting a session with more RAM may help.
**'''SLURM Account (--account, -A)''' and '''QoS (Required if custom Account is set, --qos, -q)''': Account and QOS can be set to use a secondary group (such as a course allocation). Most users will not need to change these settings. [[File:OOD.account_qos.screenshot.png|300px|frameless|right]]
**'''Time Requested for this job in hours (--time, -t)''': How long your Jupyter server should run for. {{Note|Remember that leaving idle Jupyter servers running wastes resources and prevents you and others from using those resources. This time should be set to the amount of time you will be actively working and running analyses.|reminder}}
**'''Cluster partition (--partition, -p)''': Leave as <code>default</code> unless are requesting a GPU or have a specific reason to select a partition.
**'''Generic Resource Request (--gres)''': If you are requesting a GPU, add the information here using the [[GPU Access|GPU Access page]] as a guide.

Once you have used Open On Demand once, your settings will typically be saved for future sessions. If you run similar sessions, you can scroll to the bottom and click Launch.

==Wait for job to start and then connect==

* After clicking Launch, your job will be submitted to the SLURM scheduler requesting the resources you have selected. At first the job will be listed with the image below. Remember that resources are allocated to groups based on investment, other jobs using the group's resource may delay the start of your job.
[[File:OOD Queued.png|400px|center]]
* Once your job starts the Connect button will appear. Click that to connect to your Jupyter session.
[[File:OOD Running.png|400px|center]]

=Accessing Blue and Orange Directories=
At first, Jupyter only has access to your home directory (<code>/home/<i>gatorlink</i></code>). In order to access directories outside of your home, it is necessary to add links to those directories using the command line. These links are similar to aliases or shortcuts on your computer. Common directories to add are your groups' <code>/blue</code> and <code>/orange</code> directories.

==Open a Terminal==
[[File:Jupyter Launcher Terminal.png|300px|frameless|right]]
We will need a terminal to run the commands below. You can use an ssh client, the OOD Shell Access or launch a Terminal within you Jupyter Server. The image on the right shows the Terminal Launcher button at the bottom of the Launcher panel in JupyterLab. If needed, you can open the Launcher with the '+' icon in the top left or from the File menu, select New Launcher.

==Create the Link==
The specific type of link we want to create is referred to as a ''symbolic link'' or ''symlink''.  The format of the command used to create this link is <code>ln -s <i>path_to_link_to name_of_link</i></code>. 
* In general, we recommend making a link to your group's directory. This allows you to use the group's ''share'' folder and more easily collaborate with others in the group than if you made the link to your own folder within the group directory.
* Since people are often in multiple groups, we recommend naming the link with the convention <code>blue_<i>group</i></code>. This allows for multiple links to each group directory.
* The <code>id</code> command will show you the groups you are a member of:
 [agator@login4 ~]$ id
 uid=12345(agator) gid=12345(gator-group) groups=12345(gator-group),12346(orange-group),12347(blue-group)
 [agator@login4 ~]$ 
* The commands below show the commands needed to change directories to your home directory (<code>cd</code>) and create links to the fictional gator-group <code>/blue</code> and <code>/orange</code> directories.
 [agator@login4 ~]$cd
 [agator@login4 ~]$ln -s /blue/gator-group blue_gator-group
 [agator@login4 ~]$ln -s /orange/gator-group orange_gator-group

Then, you'll see 'blue_gator-group' or 'orange_gator-group' as a folders in your home directory in JupyterLab and will be able to double-click on those to browse the directories.

=Reconnecting to Running Sessions=
You can close your browser window and reconnect to existing sessions using the My Interactive Sessions menu (sometimes shown with just the icon on smaller screens).
[[File:OOD MyInteractiveSessions.png|center]]

=Deleting Running Sessions=
Your Jupyter session will run for the time you selected, consuming the allocated resources. If you are finished with your analyses, you can release those resources by deleting the job. Using the My Interactive Sessions menu shown above, find the session and click the Delete button. The Delete button stops the SLURM job. The Notebooks/files/etc. created in your job are not deleted.
[[File:OOD Running.png|400px|center]]

=Using the Older Jupyter Notebook Interface=
[[File:OOD Jupyter SimpleNotebooks.png|frameless|right]]By default, the checkbox show at the right is selected, starting your server with the more modern JupyterLab interface. If you want to use the older, simpler Jupyter Notebook interface uncheck the box.