update instructions for remote vis

sphinx_docs/source/workstations.rst

@@ -6,56 +6,72 @@ Linux Workstations
 In general GCC 10.x works well on Linux workstations.
 
 
-GPU offloading
-==============
 
-We use the GNU compilers to build with nvcc and CUDA.
+Remote vis with Jupyter
+=======================
 
-bender
-------
+You can connect to Jupyter on ahsoka via ssh to do remote visualization.
 
-Compile as::
+On ahsoka:
 
-  module load gcc/7.3
+* Install jupyter and yt (if you don't already have them)::
 
-  make CUDA_VERSION=cc60 COMPILE_CUDA_PATH=/usr/local/cuda-11.3 \
-    USE_CUDA=TRUE COMP=gnu -j 4
+    pip install jupyterlab
+    pip install yt
 
-To run the CUDA code path without GPU launching, add::
+* Start up jupyter on the remote (ahsoka) machine::
 
-  NO_DEVICE_LAUNCH=TRUE
+    jupyter lab --no-browser --ip=127.0.0.1
 
+  when you do this, it will output a lot to the screen, but
+  look for a line that starts like::
 
-groot
------
+    http://127.0.0.1:8888/lab?token=8469f3fb822e2a32c94...
 
-We need to work around a bug in the headers in the default GCC 10.2 on groot,
-so we load an older version for the GPU build.
+  The ``8888`` there is the port.  If that is being used, Jupyter
+  will pick a higher one.  Make note of the number it picked.
 
-Compile as::
+* On your local workstation do::
 
-  module load gcc/7.3
+    ssh -N -L 8888:127.0.0.1:8888 ahsoka.astro.sunysb.edu
 
-  make CUDA_VERSION=cc70 COMPILE_CUDA_PATH=/usr/local/cuda-11.3 \
-    USE_CUDA=TRUE COMP=gnu USE_MPI=FALSE -j 4
+  replacing the ``8888`` with the port it selected.
 
+  .. tip::
 
+     If your username on ``ahsoka`` is not the same as on your
+     local machine, then you need to prefix your username to
+     the remote, e.g., as::
 
-Remote vis with Jupyter
-=======================
+       ssh -N -L 8888:127.0.0.1:8888 username@ahsoka.astro.sunysb.edu
+
+     where you replace ``username`` with your ``ahsoka`` username.
+
+  Then enter your password.  There will be no output---that command
+  will just continue to run in the terminal window.
+
+  .. tip::
+
+     This says that port ``8888`` on your local machine will connect (via
+     SSH tunnel) to ``127.0.0.1:8888`` on the remote machine.  Here
+     ``127.0.0.1`` is the *loopback address* (the IP address on the
+     remote machine that resolves to itself)
 
-You can connect to Jupyter on groot to do remote visualization.
+  .. warning::
 
-On groot, do::
+     If you get an error like::
 
-   jupyter lab --no-browser --ip="groot"
+       bind [127.0.0.1]:8888: Address already in use
+       channel_setup_fwd_listener_tcpip: cannot listen to port: 8888
+       Could not request local forwarding.
 
-on your workstation do::
+     then that means that you are running Jupyter already on your local
+     machine, and it is already using port ``8888``, so kill the local
+     instance of Jupyter and try again.
 
-   ssh -N -L localhost:8888:groot:8888 groot.astro.sunysb.edu
+* Finally, on your local machine, point your web browser to the URL
+  output on ahsoka (we referenced this above as ``http://127.0.0.1:8888/lab?token=8469f3fb822e2a32c94...``)
 
-and enter your password.  There will be no output---that command will just continue
-to run in the terminal window.
+  This should open the Jupyter server on the remote machine in your
+  local browser.
 
-Point your web browser to http://localhost:8888 .
-You will be prompted to add the token that appears in the groot window.