Skip to content

Commit 02c4a92

Browse files
authored
Update Omega documentation (#1016)
* Update Omega documentation and expose on fuse.help * Single install page with GA cluster header
1 parent efa523c commit 02c4a92

File tree

2 files changed

+37
-40
lines changed

2 files changed

+37
-40
lines changed

docs/src/install.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,14 @@ For installation start your Julia interpreter by typing `julia` at the terminal,
5050

5151
## Install Jupyter-Lab with Julia support
5252

53-
1. You will need to [install `jupyter-lab`](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) if that's not already available on your system
53+
1. You will need to [install `jupyter-lab`](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) if that's not already available on your system
5454

5555
!!! note
5656
The WebIO jupyter-lab extension is needed for the [`Interact.jl`](https://github.com/JuliaGizmos/Interact.jl?tab=readme-ov-file#usage) package to work.
5757

5858
Make sure WebIO is working with `jupyter labextension list`. If it is working properly, you should see something like: webio-jupyterlab-provider v0.1.0 enabled OK (python, webio_jupyter_extension). This can also be checked with `jupyter nbextension list`, which should show something like: webio-jupyter-nbextension/nbextension enabled.
5959

60-
If the extension has compatibility issues, install an older verision of Jupyter (eg. `conda install jupyterlab=3.6.7`). Also ensure that the WebIO and Interact packages are fully up-to-date, and restart the notebook session before testing that it works. Finally, it may be necessary to downgrade your system's version of Python - the recommended version for compatibility with Interact is 3.11.11.
60+
If the extension has compatibility issues, install an older verision of Jupyter (eg. `conda install jupyterlab=3.6.7`). Also ensure that the WebIO and Interact packages are fully up-to-date, and restart the notebook session before testing that it works. Finally, it may be necessary to downgrade your system's version of Python - the recommended version for compatibility with Interact is 3.11.11.
6161

6262
1. Install the `IJulia` package by running:
6363

@@ -106,7 +106,7 @@ For installation start your Julia interpreter by typing `julia` at the terminal,
106106

107107
1. Run `fusebot install_IJulia` to install the Kernel for the latest version of Julia in Jupyter-Lab
108108

109-
## Install on specific platforms
109+
## Working on GA clusters
110110

111111
```@contents
112112
Pages = ["install_omega.md", "install_saga.md"]

docs/src/install_omega.md

Lines changed: 34 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# On OMEGA cluster
1+
# On GA's OMEGA cluster
22

33
## FUSE module
44

@@ -9,7 +9,38 @@ To load the latest version, do:
99
module load fuse
1010
```
1111

12-
Once the module is loaded, you can start Julia at the terminal and import the FUSE module.
12+
The FUSE module does several things:
13+
14+
1. It exposes the `fuse` executable, which runs Julia in a read-only environment with the FUSE
15+
codebase precompiled into a
16+
[sysimage](https://julialang.github.io/PackageCompiler.jl/dev/sysimages.html).
17+
This greatly reduces the time-to-first-execution (TTFX) for many functions in the FUSE code suite,
18+
at the expense of "locking" those packages and functions to the versions with which they
19+
were compiled.
20+
21+
1. The Julia module is also loaded, so development work can be done by running the `julia` command.
22+
This gives you access to a public Julia installation with your own private "depot" in which each
23+
user can add or develop their own packages. The location of this private depot is given by the
24+
environment variable `JULIA_USER_DEPOT`.
25+
26+
1. FUSE is already available when you launch `julia` or `fuse`, so there's no need to do
27+
`Pkg.add("FUSE")`. You can simply do `using FUSE` and begin working.
28+
29+
1. A custom conda installation is made available to you that has Jupyterlab with
30+
precompiled Julia kernels that include the FUSE sysimage. You can just do `jupyter lab` to
31+
start a Jupyter session and select the desired kernels. There is a kernel with 1 thread meant
32+
for the login nodes and 10 & 16 threads for the worker nodes.
33+
!!! warning
34+
**Problem**: There's a bug that may occur when a new user first launches one of these
35+
Julia + FUSE Jupyter kernels.
36+
In your terminal, you will see output about precompiling IJulia, which is expected.
37+
Once the precompilation is done, it will report `Starting kernel event loops` but then the
38+
kernel may hang and your notebook may not work. It is unclear why this happens, but it is
39+
only the first time for each user.
40+
41+
**Solution**: Restart the kernel. Occasionally this needs to be done twice, perhaps if you
42+
restart too quickly and the precompilation was not finished. In any case, if the problem
43+
does not resolve after restarting the kernel twice, reach out to the FUSE developers.
1344

1445
## Running Julia/FUSE via VScode
1546

@@ -31,7 +62,7 @@ To do this:
3162

3263
Now Julia scripts and notebooks can be run directly from this remote VScode session.
3364

34-
## Connecting to a Jupyter-lab server running on OMEGA
65+
## Connecting to a Jupyter-lab server running on OMEGA from your laptop
3566

3667
1. Connect to `omega` and launch `screen`
3768

@@ -126,37 +157,3 @@ module load atom
126157
module unload gcc
127158
module unload env
128159
```
129-
130-
### How the public installation of FUSE works
131-
132-
The FUSE unix module `module load fuse` does several things:
133-
134-
1. The `julia` unix module is loaded, which gives you access to a public Julia installation with your
135-
own private "depot" in which each user can add or develop their own packages. The location
136-
of this private depot is given by the environment variable `JULIA_USER_DEPOT`.
137-
138-
1. The FUSE codebase has been precompiled and made available to Julia via a
139-
[sysimage](https://julialang.github.io/PackageCompiler.jl/dev/sysimages.html).
140-
This greatly reduces the time-to-first-execution (TTFX) for many functions in the FUSE code suite,
141-
at the expense of "locking" those packages and functions to the versions with which they
142-
were compiled.
143-
144-
1. FUSE is already available when you launch Julia, so there's no need to do `Pkg.add("FUSE")`.
145-
You can simply do `using FUSE` and being working.
146-
147-
1. A custom conda installation is made available to you that has Jupyter notebooks with
148-
precompiled Julia kernels that include the FUSE sysimage. You can just do `jupyter lab` to
149-
start a Jupyter session and select the desired kernels. There is a kernel with 10 threads meant
150-
for the login nodes and one with 40 threads meant for the worker nodes.
151-
!!! warning
152-
**Problem**: There's a bug that occurs when a new user first launches one of these
153-
Julia + FUSE Jupyter kernels.
154-
In your terminal, you will see output about precompiling IJulia, which is expected.
155-
Once the precompilation is done, it will report `Starting kernel event loops` but then the
156-
kernel may hang and your notebook may not work. It is unclear why this happens, but it is
157-
only the first time for each user.
158-
159-
**Solution**: Restart the kernel. Occasionally this needs to be done twice, perhaps if you
160-
restart too quickly and the precompilation was not finished. In any case, if the problem
161-
does not resolve after restarting the kernel twice, reach out to the FUSE developers.
162-

0 commit comments

Comments
 (0)