installation.md

Installation

It's recommended to install the offline calibration (pycalibration) package on maxwell, using the anaconda/3 environment.

The following instructions clone from the EuXFEL GitLab instance using SSH remote URLs, this assumes that you have set up SSH keys for use with GitLab already. If you have not then read the appendix section on SSH Key Setup for GitLab for instructions on how to do this.

Installation using python virtual environment - recommended

pycalibration uses Python 3.11. Currently the default python installation on Maxwell is still Python 3.9, so Python 3.11 needs to be loaded from a different location.

We use pyenv to manage different Python versions. A pyenv installation is provided at /gpfs/exfel/sw/calsoft/.pyenv.

To install pycalibration, follow these steps:

# Activate pyenv
source /gpfs/exfel/sw/calsoft/.pyenv/bin/activate

# Clone the repository
git clone ssh://git@git.xfel.eu:10022/detectors/pycalibration.git
cd pycalibration

# Set up Python environment
pyenv shell 3.11.9
python3 -m venv .venv
source .venv/bin/activate

# Install pycalibration
python3 -m pip install --upgrade pip
# Use 'pip install -e .' for editable install
python3 -m pip install .

Working with Jupyter Notebooks

If you plan to work with Jupyter notebooks interactively, you have two main options:

Option 1: Install Jupyter Notebook locally

if you prefer to run Jupyter notebooks on your local machine or on Maxwell, you can install the notebook package in your virtual environment:

python3 -m pip install notebook==6.2.0

After installation, you can start a Jupyter notebook server by running:

jupyter notebook

Option 2: Use max-jhub (Recommended)

Alternatively, we recommend using max-jhub, a JupyterHub instance available at DESY. This option provides a convenient web-based environment for running Jupyter notebooks without needing to set up everything locally.

For detailed instructions on how to use max-jhub, please refer to these documentations:

• Max-jhub DESY Documentation
• Max-jhub EuXFEL User Documentation

To use max-jhub effectively with pycalibration, make sure you've created an ipython kernel as described in the Creating an ipython kernel for virtual environments section below.

Creating an ipython kernel for virtual environments

To create an ipython kernel with pycalibration available you should (if using a venv) activate the virtual environment first, and then run:

# If not using a venv add `--user` flag
python3 -m pip install ipykernel
# If not using a venv pick different name
python3 -m ipykernel install --user --name pycalibration --display-name "pycalibration"

This can be useful for Jupyter notebook tools as max-jhub documentation(max-jhub)

SSH Key Setup for GitLab

It is highly recommended to setup SSH keys for access to GitLab as this simplifies the setup process for all of our internal software present on GitLab.

To set up the keys:

1. Connect to Maxwell
2. Generate a new keypair with ssh-keygen -o -a 100 -t ed25519, you can either leave this in the default location (~/.ssh/id_ed25519) or place it into a separate directory to make management of keys easier if you already have multiple ones. If you are using a password for your keys please check this page to learn how to manage them: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent
3. Add the public key (id_ed25519.pub) to your account on GitLab: https://git.xfel.eu/gitlab/profile/keys
4. Add the following to your ~/.ssh/config file

# Special flags for gitlab over SSH
Host git.xfel.eu
    User git
    Port 10022
    ForwardX11 no
    IdentityFile ~/.ssh/id_ed25519

Once this is done you can clone repositories you have access to from GitLab without having to enter your password each time. As pycalibration requirements are installed from SSH remote URLs having SSH keys set up is a requirement for installing pycalibration.