Docs: NERSC ipympl Work-Around (#2815)

Document a work-around to get `ipympl` widgets to work on NERSC's Jupyter service. Also x-ref the upstream issue: matplotlib/ipympl#416
ECP-WarpX · Feb 2, 2022 · 605ddb3 · 605ddb3
1 parent 39b82f0
commit 605ddb3
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 2 deletions.
diff --git a/Docs/source/install/hpc/cori.rst b/Docs/source/install/hpc/cori.rst
@@ -320,11 +320,17 @@ In this manual, we often use this ``conda create`` line over the officially docu
 
 .. code-block:: bash
 
-   conda create -n myenv -c conda-forge python mamba ipykernel ipympl matplotlib numpy pandas yt openpmd-viewer openpmd-api h5py fast-histogram
+   conda create -n myenv -c conda-forge python mamba ipykernel ipympl==0.8.1 matplotlib numpy pandas yt openpmd-viewer openpmd-api h5py fast-histogram
 
 We then follow the `Customizing Kernels with a Helper Shell Script <https://docs.nersc.gov/services/jupyter/#customizing-kernels-with-a-helper-shell-script>`__ section to finalize the setup of using this conda-environment as a custom Jupyter kernel.
 
 When opening a Jupyter notebook, just select the name you picked for your custom kernel on the top right of the notebook.
 
 Additional software can be installed later on, e.g., in a Jupyter cell using ``!mamba install -c conda-forge ...``.
 Software that is not available via conda can be installed via ``!python -m pip install ...``.
+
+.. warning::
+
+   Jan 6th, 2022 (NERSC-INC0179165 and `ipympl #416 <https://github.com/matplotlib/ipympl/issues/416>`__):
+   Above, we fixated the ``ipympl`` version to *not* take the latest release of `Matplotlib Jupyter Widgets <https://github.com/matplotlib/ipympl>`__.
+   This is an intentional work-around; the ``ipympl`` version needs to exactly fit the version pre-installed on the Jupyter base system.
diff --git a/Docs/source/install/hpc/perlmutter.rst b/Docs/source/install/hpc/perlmutter.rst
@@ -107,7 +107,8 @@ Post-Processing
 
 For post-processing, most users use Python via NERSC's `Jupyter service <https://jupyter.nersc.gov>`__ (`Docs <https://docs.nersc.gov/services/jupyter/>`__).
 
-Please follow the same guidance as for :ref:`NERSC Cori post-processing <post-processing-cori>`.
+Please follow the same process as for :ref:`NERSC Cori post-processing <post-processing-cori>`.
+**Important:** The *environment + Jupyter kernel* must separate from the one you create for Cori.
 
 The Perlmutter ``$PSCRATCH`` filesystem is currently not yet available on Jupyter.
 Thus, store or copy your data to Cori's ``$SCRATCH`` or use the Community FileSystem (CFS) for now.