JupyterHub @ ELI-NP

1. Introduction and Overview

Your Python Platform for Physics Research

This JupyterHub service provides a ready-to-use environment for:

• 📊 Experimental data analysis (Pandas/Matplotlib)
• 🧮 Symbolic mathematics (SymPy)
• ⚛️ Numerical simulations (NumPy/SciPy)

Accessible from any browser, with:

• ✅ MATLAB-like syntax
• ✅ Mathematica-style interactive notebooks and symbolic workflow
• ✅ Pre-configured Python environments
• ✅ Secure on-premise hosting in LP50

📚 Start with tutorials: work/tutorials/processing_experimental_data.ipynb (experimental) or work/tutorials/sympy_intro (theoretical).

2. Getting Started

2.1 Accessing JupyterHub

To access the JupyterHub instance:

1. Navigate to jupyter.sequanium.de in your browser
2. You'll be presented with a login screen where you can authenticate using your GitHub account

Initial login page with GitHub authentication option

2.2 Authentication with GitHub

All users authenticate through GitHub accounts. If you already have a GitHub account, you can use it directly. If not, you'll need to create one.

For Existing GitHub Users:

1. Click the "Sign in with GitHub" button
2. Enter your GitHub username/email and password
3. Authorize JupyterHub to link to your GitHub account

GitHub login form

GitHub authorization screen

For New Users (Creating a GitHub Account):

1. Click "Create an account" link
2. Fill in the required information (email, password, username)
3. Complete the human verification step
4. Verify your email through the confirmation code sent by GitHub
5. Authorize JupyterHub to access your newly created GitHub account

GitHub signup form

GitHub human verification

Email verification process

3. JupyterLab Interface

After authentication, you'll be directed to the JupyterLab interface, which is a web-based interactive development environment for Jupyter notebooks, code, and data.

JupyterLab initial interface

3.1 File Browser and Terminal

The left sidebar contains the file browser showing your directories. You can navigate through your files and folders, and create new notebooks, text files, or other documents.

The terminal provides command-line access to your container environment, which is running a scaled-down Ubuntu Linux distribution:

Terminal access within JupyterLab

3.2 File Management

JupyterLab provides tools for uploading and downloading files from/to your computer:

File upload button

File download option (right-click menu)

4. Storage and Data Management

4.1 Work Directory

Each user has a personal work/ directory with the following characteristics:

• Quota: 50GB of storage
• Privacy: Files stored here are accessible only to you
• Persistence: Data remains available between sessions
• Purpose: Store personal datasets, scripts, notebooks, and other private work

A README.txt file in your work directory provides additional information about available tutorials and resource usage.

4.2 Shared Directory

The shared/ directory is designed for collaboration:

• Quota: 500GB of shared storage
• Access: Accessible to all JupyterHub users
• Purpose: Collaboration on datasets, code, and results

5. Computing Environment

The JupyterHub instance uses containerization to provide each user with their own isolated computing environment:

• Each user gets a personal Docker container based on the scipy-notebook image
• The container includes a full Ubuntu environment
• Pre-installed Python scientific stack includes:
  • NumPy, SciPy, Pandas
  • Matplotlib, Seaborn
  • scikit-learn, scikit-image
  • Jupyter extensions including ipywidgets and ipympl

5.1 Package Management

You can install additional Python packages using mamba or pip, but these installations are not persistent and will be lost when your container restarts.

5.2 Interactive Visualizations

The environment supports interactive visualizations through:

• ipympl for interactive Matplotlib figures
• ipywidgets for building interactive dashboards

6. Tutorials and Learning Resources

Several tutorials are available in the work/tutorials/ directory:

6.1 Available Tutorials

• Data Processing:
  • Processing Experimental Data: tutorials/processing_experimental_data.ipynb
• Python and NumPy Basics:
  • Python Introduction: tutorials/python_intro/python_intro.ipynb
  • NumPy Introduction: tutorials/numpy_intro/numpy_intro.ipynb

6.2 External Documentation

Additional learning resources:

• JupyterLab Documentation
• NumPy Documentation
• SciPy Documentation
• Matplotlib Documentation
• scikit-image Documentation

7. Technical Information

7.1 Server Architecture

The JupyterHub setup includes:

• Bare metal Ubuntu 24.04 LTS server with public IP located in LP50
• Nginx reverse proxy for secure HTTPS access
• JupyterHub using DockerSpawner to launch individual user containers
• scipy-notebook Docker image as the base environment

System architecture diagram showing the relationships between components

7.2 Local Container Usage

Advanced users can run the same container locally on their own computers:

docker pull jupyter/scipy-notebook
docker run -p 8888:8888 jupyter/scipy-notebook

This allows for development and testing in an identical environment to the JupyterHub server.

8. Limitations and Constraints

Please be aware of the following system limitations:

8.1 Resource Limitations

• Job Duration: Maximum 24-hour runtime for continuous jobs
• Inactivity Timeout: Automatic logout after 1 hour of inactivity
• Storage Quotas:
  • 50GB quota for personal work/ directory
  • 500GB quota for shared/ directory
• Computational Resources (per user):
  • Memory limit: 8GB
  • Memory guarantee: 4GB
  • CPU limit: 4 cores
  • CPU guarantee: 2 cores

8.2 System Constraints

• Sudo Access: Not permitted for security reasons
• Package Persistence: Custom-installed packages do not persist between container restarts
• Environment: The base container is immutable; changes to the system environment are not preserved

9. Frequently Asked Questions